进阶 opencode.ai 2026-11-11 16:13:22 · 15 阅读

第10章 OpenCode 终端界面主题配置指南

主题

在终端界面中按 Ctrl+P,选择 Open settings 并打开 Theme 即可选择主题。你也可以直接在全局 CLI 配置中设置:

~/.config/opencode/cli.json

{

"theme": {

"name": "tokyonight",

"mode": "system"

}

}

主题归属于终端客户端。将主题选择配置在 cli.json 中,而不是 opencode.json。配置位置及其他终端设置请参见 CLI settings。

使用 system 跟随终端外观,或将主题锁定为特定模式:

~/.config/opencode/cli.json

{

"theme": {

"name": "opencode",

"mode": "dark"

}

}

  • Value:Behaviorsystem(跟随终端的浅色或深色模式)。
  • dark:始终使用深色主题。
  • light:始终使用浅色主题。

如果自定义主题仅提供一种模式,请求另一种模式时 OpenCode 将使用其提供的模式。

通过名称选择内置主题:

~/.config/opencode/cli.json

{

"theme": {

"name": "catppuccin"

}

}

可用主题包括:aura、ayu、carbonfox、cobalt2、cursor、dracula、everforest、flexoki、catppuccin、catppuccin-frappe、catppuccin-macchiato、github、gruvbox、kanagawa、material、matrix、mercury、monokai、nightowl、nord、one-dark、opencode、orng、lucent-orng、osaka-jade、palenight、rosepine、solarized、synthwave84、tokyonight、vercel、vesper、zenburn。

当 OpenCode 能读取终端调色板时,系统主题可用。

要创建名为 ocean 的全局主题,请使用 theme 工具在全局主题目录中生成完整文件。其相关结构如下:

~/.config/opencode/themes/ocean.json (excerpt)

{

"base": {

"text": {

"base": "#d8f3ff"

}

},

"dark": {

"hue": {

"accent": "$hue.cyan"

}

}

}

然后在设置中选择 ocean,或在 cli.json 中将 theme.name 设为 ocean。去掉 .json 扩展名的文件名即为主题名称。

  • Scope:Global → ~/.config/opencode/themes/
  • Project → 项目树中的 .opencode/themes/

OpenCode 仅读取 .json 文件。更接近当前目录的同名主题会替代全局或父级主题。

每个 V2 主题都声明一棵完整的 base 令牌树以及至少一个浅色或深色 hue 调色板。模式仅从该文件的 base 继承;不从内置 OpenCode 主题或其他模式继承。请使用 theme 工具在自定义前生成完整的 base。

以下示例仅展示与各概念相关的部分,并非完整主题文件。

themes/ocean.json

{

"base": {

"text": {

"base": "#16324f"

}

},

"light": {

"hue": {}

},

"dark": {

"hue": {},

"text": { "base": "#d8f3ff" }

}

}

使用十六进制颜色、transparent 或其他主题颜色的引用:

themes/ocean.json

{

"base": {

"text": {

"base": "#d8f3ff",

"muted": "$hue.neutral.400"

},

"background": {

"base": "transparent"

}

}

}

十六进制值可使用 3、4、6 或 8 位。引用以 $ 开头;hue 引用使用 $hue.. 形式。

覆盖 hue 别名可一次性改变一系列相关颜色:

themes/ocean.json

{

"base": {

"categorical": ["accent", "purple", "green"]

},

"dark": {

"hue": {

"accent": "$hue.cyan",

"interactive": "$hue.blue"

}

}

}

  • Kind:Base → gray, red, orange, yellow, green, cyan, blue, purple;Alias → accent, interactive, neutral;Step → 100, 200, 300, 400, 500, 600, 700, 800, 900

Hue 步骤遵循模式的对比方向:浅色主题从 100 的深色到 900 的浅色,深色主题则从 100 的浅色到 900 的深色。categorical 设置用于区分 agent 及其他重复项的有序 hue,须至少包含一个 base hue 或 alias。

使用状态键修改交互颜色。未指定的状态使用最接近的 base 值:

themes/ocean.json

{

"base": {

"text": {

"action": {

"primary": {

"base": "$hue.interactive.400",

"$hovered": "$hue.interactive.300",

"$disabled": "$hue.neutral.600"

}

}

}

}

}

  • Group:Actions → primary, secondary, destructive
  • States:$hovered, $focused, $pressed, $selected, $disabled

表单字段在 text.formfield 或 background.formfield 下直接使用相同的状态键。

完整的 base 包含所有令牌组。提供完整 hue 调色板后,模式可覆盖其任意部分:

themes/ocean.json

{

"base": {

"border": {

"base": "$hue.neutral.700"

},

"syntax": {

"comment": "$hue.neutral.500",

"keyword": "$hue.accent.400"

},

"diff": {

"text": {

"added": "$hue.green.400",

"removed": "$hue.red.400"

}

}

}

}

  • text:基础、弱化、淡色、操作、表单字段及反馈文本
  • background:基础、表面、操作、表单字段及反馈填充
  • border:边框
  • scrollbar:滚动条
  • diff:添加、删除、上下文、高亮及行号颜色
  • syntax:源代码高亮
  • markdown:Markdown 元素

Syntax 键包括 comment、keyword、function、variable、string、number、type、operator 和 punctuation。Markdown 键包括 text、heading、link、linkText、code、blockQuote、emphasis、strong、horizontalRule、listItem、listEnumeration、image、imageText 和 codeBlock。

面板、对话框、菜单和 toast 从 background.raised 选择其深度。对话框额外支持上下文 @dialog 表面。TUI 在应用 @dialog 后重新解析调色板,因此引用 $background.base 的令牌会跟随对话框背景:

themes/ocean.json

{

"base": {

"background": {

"base": "#071521",

"raised": {

"base": "#0c1f2e",

"high": "#102a3c",

"max": "#16364b"

}

},

"@dialog": {

"background": {

"base": "$background.raised.base"

}

}

}

}

@dialog 接受与 base 模式相同的令牌组。操作的上下文 base 也作为其未指定状态的备选值;显式的状态覆盖仍然优先。

评论 (0)