叶云梦天

OpenCode 主题定制完全指南：用色彩重塑你的 AI 编程终端

引言

每天在终端里和 AI 助手打交道，一个养眼的配色方案能极大提升编码的愉悦感。OpenCode 内置了一套强大的主题系统，不仅提供了多款精心设计的预设主题，还支持从零开始创建完全自定义的配色方案。更妙的是，这一切都基于 JSON 配置，学习成本极低。无论你是想一键切换内置主题，还是想打造专属的"黑客帝国"风格配色，读完这篇文章你就能全部掌握。

终端前置要求：开启 True Color

在正式上手主题配置之前，有一个关键前提需要确认：你的终端必须支持 True Color（24 位色）。如果终端不支持，主题可能会降到 256 色的近似值，色彩还原度大打折扣。

检查你的终端是否已支持 True Color：

echo $COLORTERM

如果输出为 truecolor 或 24bit，说明已经就绪。如果没有输出，可以手动设置环境变量：

export COLORTERM=truecolor

建议将上述命令添加到你的 shell 配置文件中（如 ~/.bashrc、~/.zshrc），确保每次启动终端时自动启用。

目前主流的终端模拟器 —— iTerm2、Alacritty、Kitty、WezTerm、Windows Terminal 以及新版 GNOME Terminal —— 都已原生支持 True Color，可以直接使用。

内置主题一览：一键切换配色方案

OpenCode 预置了十多款主题，覆盖了开发者社区中最受欢迎的几个配色方案。以下是当前可用的内置主题：

| 主题名 | 说明 |
|--------|------|
| opencode | OpenCode 官方默认主题 |
| system | 自动适配终端背景色 |
| tokyonight | 基于著名 Tokyonight 配色 |
| everforest | 基于 Everforest 护眼配色 |
| ayu | 基于 Ayu 暗色主题 |
| catppuccin | 基于 Catppuccin 主题 |
| catppuccin-macchiato | Catppuccin Macchiato 变体 |
| gruvbox | 经典复古暖色 Gruvbox |
| kanagawa | 日系 Kanagawa 配色 |
| nord | 北欧极简 Nord 风格 |
| matrix | 黑客风格黑底绿字 |
| one-dark | Atom One Dark 经典暗色 |

两种切换方式

方式一：交互式命令

在 OpenCode TUI 中直接输入：

/theme

系统会弹出主题选择面板，你可以实时预览并选择心仪的主题，所见即所得。

方式二：tui.json 配置文件

在项目的 .opencode/tui.json 或全局 ~/.config/opencode/tui.json 中直接指定：

{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "tokyonight"
}

个人推荐使用配置文件的方式，这样可以版本管理你的主题设置，在团队中共享统一的配色方案。

System 主题：让 AI 助手融入你的终端生态

system 主题是内置主题中非常特别的一个。它不会使用固定的颜色值，而是动态地从你的终端背景色生成一套灰度色谱，并利用终端本身的 ANSI 颜色（0-15）来做语法高亮和 UI 渲染。

这带来的好处是：OpenCode 的配色会自动和你终端中其他应用（如 Neovim、tmux）的配色风格保持一致。当你切换终端的全局配色方案时，OpenCode 也会随之变化，无需手动调整。

system 主题对于以下场景非常合适：

你已经精心调校过终端配色，不想让 OpenCode 打破一致性
你使用定制终端配色方案，且希望所有 CLI 工具外观统一
你经常在不同终端配色之间切换

自定义主题：打造你的专属配色

切换内置主题固然方便，但真正的乐趣在于自己动手。OpenCode 的自定义主题系统基于 JSON 文件，结构清晰，上手门槛极低。

主题文件的存放位置与优先级

OpenCode 按以下优先级加载主题文件，后加载的会覆盖先加载的同名主题：

内置主题（编译在二进制中，优先级最低）

用户全局目录：~/.config/opencode/themes/*.json（或 $XDG_CONFIG_HOME/opencode/themes/*.json）

项目根目录：<项目根>/.opencode/themes/*.json

当前工作目录：./.opencode/themes/*.json（优先级最高）

这种分层设计非常灵活：你可以为所有项目设置一个全局默认主题，再为特定项目覆盖不同的配色。

创建第一个自定义主题

首先创建主题文件的存放目录：

# 全局主题（所有项目生效）
mkdir -p ~/.config/opencode/themes

# 项目级主题（仅当前项目生效）
mkdir -p .opencode/themes

然后创建一个 JSON 主题文件，例如 .opencode/themes/my-theme.json。

JSON 格式详解

OpenCode 主题支持以下颜色值格式：

十六进制颜色："#2E3440"
ANSI 索引色：3（0-255 范围内的数字）
引用自定义定义："primary"（引用 defs 中定义的名称）
亮/暗双模式：{"dark": "#000000", "light": "#FFFFFF"}
继承终端默认色："none"（使用终端的默认前景或背景色）

#### 颜色定义块（defs）

defs 是可选的预定义颜色块，用于集中管理可复用的颜色变量。先在 defs 中定义，再在 theme 中按名称引用。这种方式让主题维护变得极为简单 —— 修改一个定义，所有引用处同步更新。

#### 主题配置项（theme）

theme 块包含所有 UI 元素的颜色定义，每个属性都支持 {"dark": "...", "light": "..."} 的双模式写法。主要配置项分为以下几类：

基础 UI 颜色：

| 属性 | 说明 |
|------|------|
| primary | 主色调 |
| secondary | 辅助色 |
| accent | 强调色 |
| text | 正文文字颜色 |
| textMuted | 次级/淡化文字颜色 |
| background | 主背景色 |
| backgroundPanel | 面板背景色 |
| backgroundElement | 元素背景色 |
| border | 边框颜色 |
| borderActive | 激活状态边框色 |
| borderSubtle | 淡边框颜色 |

状态指示色：

| 属性 | 说明 |
|------|------|
| error | 错误信息颜色 |
| warning | 警告信息颜色 |
| success | 成功信息颜色 |
| info | 提示信息颜色 |

Git Diff 相关颜色：

| 属性 | 说明 |
|------|------|
| diffAdded | 新增行颜色 |
| diffRemoved | 删除行颜色 |
| diffContext | 上下文行颜色 |
| diffHunkHeader | Hunk 头部颜色 |
| diffHighlightAdded | 新增行高亮色 |
| diffHighlightRemoved | 删除行高亮色 |
| diffAddedBg | 新增行背景色 |
| diffRemovedBg | 删除行背景色 |
| diffContextBg | 上下文行背景色 |
| diffLineNumber | 行号颜色 |
| diffAddedLineNumberBg | 新增行行号背景 |
| diffRemovedLineNumberBg | 删除行行号背景 |

Markdown 渲染颜色：

| 属性 | 说明 |
|------|------|
| markdownHeading | 标题颜色 |
| markdownLink | 链接颜色 |
| markdownCode | 行内代码颜色 |
| markdownCodeBlock | 代码块颜色 |
| markdownBlockQuote | 引用块颜色 |
| markdownEmph | 斜体文本颜色 |
| markdownStrong | 粗体文本颜色 |
| markdownListItem | 列表符号颜色 |
| markdownHorizontalRule | 分割线颜色 |

语法高亮颜色：

| 属性 | 说明 |
|------|------|
| syntaxComment | 注释 |
| syntaxKeyword | 关键字 |
| syntaxFunction | 函数名 |
| syntaxVariable | 变量名 |
| syntaxString | 字符串 |
| syntaxNumber | 数字 |
| syntaxType | 类型名称 |
| syntaxOperator | 运算符 |
| syntaxPunctuation | 标点符号 |

实战示例：创建一个复古暖色主题

下面是一个完整的自定义主题示例，以 Nord 配色为基础，支持暗色和亮色双模式：

{
  "$schema": "https://opencode.ai/theme.json",
  "defs": {
    "nord0": "#2E3440",
    "nord1": "#3B4252",
    "nord2": "#434C5E",
    "nord3": "#4C566A",
    "nord4": "#D8DEE9",
    "nord5": "#E5E9F0",
    "nord6": "#ECEFF4",
    "nord8": "#88C0D0",
    "nord9": "#81A1C1",
    "nord10": "#5E81AC",
    "nord11": "#BF616A",
    "nord12": "#D08770",
    "nord13": "#EBCB8B",
    "nord14": "#A3BE8C",
    "nord15": "#B48EAD"
  },
  "theme": {
    "primary":     { "dark": "nord8",  "light": "nord10" },
    "secondary":   { "dark": "nord9",  "light": "nord9" },
    "accent":      { "dark": "nord7",  "light": "nord7" },
    "error":       { "dark": "nord11", "light": "nord11" },
    "warning":     { "dark": "nord12", "light": "nord12" },
    "success":     { "dark": "nord14", "light": "nord14" },
    "info":        { "dark": "nord8",  "light": "nord10" },
    "text":        { "dark": "nord4",  "light": "nord0" },
    "textMuted":   { "dark": "nord3",  "light": "nord1" },
    "background":  { "dark": "nord0",  "light": "nord6" },
    "border":      { "dark": "nord2",  "light": "nord3" },
    "diffAdded":   { "dark": "nord14", "light": "nord14" },
    "diffRemoved": { "dark": "nord11", "light": "nord11" },
    "syntaxComment":     { "dark": "nord3",  "light": "nord3" },
    "syntaxKeyword":     { "dark": "nord9",  "light": "nord9" },
    "syntaxFunction":    { "dark": "nord8",  "light": "nord8" },
    "syntaxString":      { "dark": "nord14", "light": "nord14" },
    "syntaxNumber":      { "dark": "nord15", "light": "nord15" },
    "syntaxType":        { "dark": "nord7",  "light": "nord7" },
    "syntaxOperator":    { "dark": "nord9",  "light": "nord9" },
    "markdownHeading":   { "dark": "nord8",  "light": "nord10" },
    "markdownCode":      { "dark": "nord14", "light": "nord14" },
    "markdownLink":      { "dark": "nord9",  "light": "nord9" },
    "markdownBlockQuote": { "dark": "nord3", "light": "nord3" }
  }
}

将此文件保存为 .opencode/themes/my-nord.json，然后在 tui.json 中引用 "theme": "my-nord" 即可生效。

技巧与最佳实践

1. 利用 `none` 值实现透明感

将 text 或 background 设置为 "none"，可以让这两个区域继承终端的默认颜色。这对于希望 OpenCode "消隐"在终端中、完全融入整体配色风格的用户来说非常实用：

{
  "theme": {
    "text": "none",
    "background": "none"
  }
}

2. defs 集中管理颜色常量

将常用颜色提取到 defs 中，便于批量调整。当你想要微调整体色调时，只需修改 defs 中的几个颜色定义，所有引用处自动更新。

3. 版本管理你的主题

将 .opencode/themes/ 目录和 tui.json 纳入 Git 版本管理，团队成员克隆项目后即可自动获得统一配色。如果你在多个项目间切换，一致的视觉体验能有效降低认知负担。

4. 从内置主题开始魔改

不必从零开始。参考内置主题的 JSON 结构，选一个最接近你理想效果的作为基础模板，逐步调整各个颜色值。OpenCode 内置主题的源码可以在其 GitHub 仓库中找到。

总结

OpenCode 的主题系统同时兼顾了"开箱即用"和"深度定制"两个维度。对于大多数用户来说，内置主题已经足够丰富，/theme 一键切换即可满足日常需求。而对于喜欢折腾的开发者，JSON 格式的主题定义提供了极高的自由度，每个 UI 元素都可以独立配色，甚至支持亮/暗双模式自动切换。

最重要的是 —— 一个让你看了舒服的配色，真的会让你更愿意在终端里多待一会儿。花十分钟调一套自己的主题，绝对值回票价。

> 提示：如果你创建了一款好看的主题，别忘了在 OpenCode 社区分享！

OpenCode 主题定制完全指南：用色彩重塑你的 AI 编程终端

OpenCode 主题定制完全指南：用色彩重塑你的 AI 编程终端

引言

终端前置要求：开启 True Color

内置主题一览：一键切换配色方案

两种切换方式

System 主题：让 AI 助手融入你的终端生态

自定义主题：打造你的专属配色

主题文件的存放位置与优先级

创建第一个自定义主题

JSON 格式详解

实战示例：创建一个复古暖色主题

技巧与最佳实践

1. 利用 none 值实现透明感

2. defs 集中管理颜色常量

3. 版本管理你的主题

4. 从内置主题开始魔改

总结

叶云梦天

叶云梦天，专注微信，小程序，服务器管理，数据分析的信息博客

1. 利用 `none` 值实现透明感