第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 也作为其未指定状态的备选值;显式的状态覆盖仍然优先。