LowHow 文档

中文

English

中文

English

深色模式

OpenCode 主题切换与自定义实战教程：提升可读性 ​

📚 分类: OpenCode 个性化配置 ⏱️ 预计耗时: 10 分钟 🎯 难度: 入门 🔧 环境要求: 已安装并运行 OpenCode

你将学到什么 ​

完成本教程后，你将能够：

  • [ ] 区分主题的作用（可读性）与模型能力无关
  • [ ] 在 OpenCode 中快速切换并预览内置主题
  • [ ] 检查终端是否支持真彩色，确保主题正确显示
  • [ ] 创建并应用一个自定义的最小主题，改善阅读体验

最终效果 ​

你将能够根据自己的喜好和终端环境，为 OpenCode 的 TUI (文本用户界面) 选择或定制一套清晰、易读的配色方案，告别默认界面的视觉疲劳。

前置准备 ​

  • OpenCode 已安装并运行：确保你能在终端中打开 OpenCode 的 TUI 界面。
  • 一个终端：用于执行命令和编辑配置文件。
  • 一个文本编辑器：如 vim, nano, VS Code 等，用于创建和编辑 JSON 文件。

第 1 步：了解主题的核心作用——可读性 ​

🎯 目标：明确主题配置的优先级，避免陷入过度美化的误区。

📝 操作： 主题配置的核心目标是解决可读性问题，而不是单纯的装饰。你需要关注的关键区域是：

  • 正文文本：长时间阅读是否舒适。
  • 选中项：菜单中当前选中的项目是否醒目。
  • Diff 对比：代码增删改的区域是否能一眼区分。
  • 错误/警告/成功提示：状态信息是否清晰可辨。

✅ 验证：在开始之前，请记住这个原则：可读性优先于花哨。我们后续的所有操作都将围绕这个原则展开。

第 2 步：快速试用内置主题 ​

🎯 目标：通过尝试不同的内置主题，找到最接近你审美和阅读习惯的起点。

📝 操作： OpenCode 内置了多种主题，例如 tokyonight, catppuccin, nord, one-dark 等。你可以在 TUI 中实时切换并预览效果。

  1. 打开你的终端，进入 OpenCode 的 TUI 界面。
  2. 在命令输入框中输入 /theme 后按回车键。
  3. 你会看到一个主题列表，使用上下方向键选择不同的主题，界面会实时更新预览效果。
  4. 建议优先尝试以下三个主题：
    • system：跟随你的终端背景色，适合终端配色已经精调过的用户。
    • tokyonight：暗色主题，层次清晰，非常流行。
    • catppuccin：对比度温和，适合长时间阅读。

✅ 验证：选择一个你觉得最顺眼的主题。例如，如果你选择了 tokyonight，记下这个名字，我们下一步会用到它。

第 3 步：确认终端支持真彩色 ​

🎯 目标：确保你选择的主题颜色能够被正确、饱满地显示，避免出现颜色发灰或不准的情况。

📝 操作： 在终端中执行以下命令，检查 COLORTERM 环境变量：

bash
$ echo $COLORTERM

✅ 验证：

  • 预期输出：truecolor 或 24bit。
  • 如果输出不是：说明你的终端模拟器可能不支持真彩色。你可以尝试在 Shell 配置文件（如 ~/.bashrc, ~/.zshrc）中强制设置：
    bash
    # 在文件末尾添加
export COLORTERM=truecolor
    然后重新打开一个终端窗口。

💡 提示：大多数现代终端（如 iTerm2, Windows Terminal, GNOME Terminal）默认都支持真彩色。

第 4 步：在配置文件中指定主题 ​

🎯 目标：将你选中的主题固定下来，使其成为 OpenCode 的默认外观。

📝 操作： OpenCode 的 TUI 配置存储在 tui.json 文件中。你需要找到并编辑它。

  1. 打开你的 OpenCode 配置文件目录。通常位于 ~/.config/opencode/。

  2. 找到或创建 tui.json 文件。

  3. 在 tui.json 中添加或修改 theme 字段，值为你选择的主题名。

    json
    // ~/.config/opencode/tui.json
{
  "$schema": "https://opencode.ai/tui.json", // [!code ++]  // 添加 schema 引用，可获得代码提示
  "theme": "tokyonight" // [!code ++]  // 将 "tokyonight" 替换为你选择的主题名
}

✅ 验证：保存文件后，重启 OpenCode TUI 界面（或使用 /reload 命令），你应该能看到主题已经变为 tokyonight。

⚠️ 常见错误：如果主题没有变化，请检查：

  • 文件名是否为 tui.json。
  • JSON 格式是否正确（例如，键名和字符串值是否用双引号括起来）。
  • 主题名是否拼写正确。

第 5 步：创建并应用一个最小自定义主题 ​

🎯 目标：如果内置主题都无法满足你的需求，学习如何用最少的配置创建一个自定义主题。

📝 操作： 你不需要从头编写几百行的配色表。从修改几个核心颜色开始即可。

  1. 创建主题文件目录：

    bash
    $ mkdir -p ~/.config/opencode/themes

  2. 创建主题 JSON 文件，例如 my-theme.json：

    bash
    $ vim ~/.config/opencode/themes/my-theme.json

  3. 写入最小配置：以下是一个基于 Nord 配色的最小主题示例，只定义了最核心的颜色。

    json
    // ~/.config/opencode/themes/my-theme.json
{
  "$schema": "https://opencode.ai/theme.json", // [!code ++]  // 引用 schema
  "theme": {
    "primary": "#88C0D0",        // 主色，用于链接、高亮
    "accent": "#A3BE8C",         // 强调色，用于成功状态、选中等
    "error": "#BF616A",          // 错误颜色
    "text": "none",              // 文本颜色，"none" 表示继承终端前景色
    "background": "none",        // 背景色，"none" 表示继承终端背景色
    "backgroundPanel": "#2E3440", // 面板背景色
    "border": "#4C566A"          // 边框颜色
  }
}

    💡 提示："none" 是非常有用的值。它让 OpenCode 使用你终端的默认前景色和背景色，可以保持和终端外观的一致性。

  4. 应用自定义主题：回到 tui.json，将 theme 字段的值改为你的主题文件名（不含 .json 后缀）。

    json
    // ~/.config/opencode/tui.json
{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "my-theme" // [!code --]  // 旧的主题名
  "theme": "my-theme" // [!code ++]  // 应用自定义主题
}

✅ 验证：保存文件并重启 OpenCode TUI。你应该能看到一个新的配色方案。

🤔 为什么要这样做？"none" 让你可以只覆盖你想改变的颜色，而其他部分继承自终端。这是一种“增量”配置方法，比从头定义所有颜色要简单得多，也更容易维护。

第 6 步：验证主题的可读性 ​

🎯 目标：通过实际使用，确认新主题是否真正改善了阅读体验。

📝 操作： 应用新主题后，在一个真实的 AI 对话会话中检查以下几点：

  1. 普通回答：能否连续阅读十分钟而不感到眼睛疲劳。
  2. 代码块：代码块和普通正文是否有明显的视觉区分。
  3. Diff 对比：代码的增删改部分是否清晰可辨，不需要猜测。
  4. 菜单项：当前选中的菜单项是否足够醒目。
  5. 状态提示：错误（红色）、警告（黄色）、成功（绿色）状态是否能一眼分辨。

✅ 验证：

  • 如果以上所有检查点都“是”，那么恭喜你，主题配置已经完成了！不需要再继续调色。
  • 如果某个区域（如 Diff 对比）看不清楚，你可以回到 my-theme.json，只修改与该区域相关的颜色属性。例如，你可以查阅官方文档，添加 diff.add 和 diff.remove 等更细粒度的颜色配置。

进阶技巧：项目级主题 ​

🎯 目标：为不同的项目设置不同的主题，实现视觉隔离。

📝 操作： 除了用户级目录 ~/.config/opencode/themes/，你也可以在项目根目录下创建 .opencode/themes/ 目录，并将主题文件放在其中。优先级：项目级 > 用户级。

  1. 进入你的项目目录。
  2. 创建 .opencode/themes/ 目录：
    bash
    $ mkdir -p .opencode/themes
  3. 将主题文件放入此目录，并在项目根目录下的 tui.json 中引用它。

✅ 验证：在该项目目录下打开 OpenCode，你会看到项目专属的主题。

常见问题 (FAQ) ​

Q1: 主题会影响 AI 模型的回答质量吗？A: 完全不会。主题只改变 OpenCode 界面的视觉外观，与 AI 模型的对话能力、代码生成质量等核心功能无关。

Q2: 我创建了主题文件，但 OpenCode 没有识别到。A: 请检查以下几点：

  • 确认主题文件放在正确的目录下（~/.config/opencode/themes/ 或项目 .opencode/themes/）。
  • 确认 tui.json 中 theme 字段的值是主题文件名，不带 .json 后缀。
  • 确认 JSON 文件格式正确（可以使用在线 JSON 验证工具检查）。

Q3: 如何恢复到默认主题？A: 将 tui.json 中的 theme 字段删除或设置为 "default"，然后重启 OpenCode。

总结 ​

恭喜你完成了本教程！🎉

回顾一下我们今天学到的核心内容：

  1. 主题核心是解决可读性：优先关注正文、菜单、Diff 和错误提示的清晰度。
  2. 从内置主题开始：使用 /theme 命令快速预览和切换，找到喜欢的起点。
  3. 检查终端真彩色：确保颜色能正确显示。
  4. 最小化自定义：从修改几个核心颜色开始，使用 "none" 继承终端配色，避免一次配置过多。

© 2026 LowHow