---
title: "切换主题"
description: "选择内置主题，或用少量颜色定义自己的 OpenCode TUI 主题。"
verifiedAt: "2026-05-09"
---

主题只影响阅读体验，不影响模型能力。新手优先从内置主题开始，不要一上来复制一份几百行配色表。

> [!NOTE]
> **这一篇用 6 分钟换什么**：你会知道主题该解决什么问题、先试哪些内置主题、主题文件放哪里，以及怎么用最少配置改善 TUI 可读性。

## 先给结论：主题先解决可读性

主题配置解决的是长时间阅读、菜单定位和 diff 对比时的可读性问题。不要把主题当装饰，真正要检查的是正文、选中项、diff、新增删除和错误提示。

正确顺序是：

1. 先选一个内置主题。
2. 确认终端支持真彩色。
3. 只在确实读不清时自定义少数颜色。
4. 最后才考虑完整主题。

```mermaid
flowchart LR
  BuiltIn["内置主题"] --> Terminal["确认终端真彩色"]
  Terminal --> Check["真实会话检查 diff / 菜单 / 错误状态"]
  Check --> Minimal["少量自定义颜色"]
  Minimal --> Full["必要时再做完整主题"]

  style BuiltIn fill:#dbeafe,stroke:#3b82f6
  style Check fill:#dcfce7,stroke:#22c55e,stroke-width:2px
  style Full fill:#fef3c7,stroke:#f59e0b
```

## 先选内置主题

OpenCode 内置多种主题，例如 `system`、`tokyonight`、`everforest`、`ayu`、`catppuccin`、`catppuccin-macchiato`、`gruvbox`、`kanagawa`、`nord`、`matrix`、`one-dark`，并且官方在持续添加。可以在 TUI 里用 `/theme` 命令现场切换试看。

建议先试三个：

- `system`：跟随终端背景，适合已经精调过终端配色的人。
- `tokyonight`：暗色终端常用，层次比较清晰。
- `catppuccin`：对比度温和，适合长时间阅读。

在 `tui.json` 中指定主题：

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

## 终端先支持真彩色

如果主题颜色看起来发灰或不准，先检查终端是否支持真彩色：

```bash
echo $COLORTERM
```

输出最好是 `truecolor` 或 `24bit`。多数现代终端默认支持；如果没有，可以在 shell 配置里设置 `COLORTERM=truecolor`。

## 自定义主题放哪里

自定义主题是 JSON 文件。OpenCode 会从这些位置加载：

| 位置 | 适合场景 |
| --- | --- |
| `~/.config/opencode/themes/*.json` | 个人长期偏好 |
| `<project-root>/.opencode/themes/*.json` | 项目统一视觉风格 |
| `./.opencode/themes/*.json` | 当前工作目录临时主题 |

同名主题会被更高优先级的目录覆盖。个人偏好放用户级；团队统一视觉风格才放项目级。

## 最小自定义主题

自定义主题不需要从完整配色表开始。先定义基础颜色，确认读写舒服，再逐步细化语法高亮和 diff 颜色。

```jsonc title="~/.config/opencode/themes/my-theme.json"
{
  "$schema": "https://opencode.ai/theme.json",
  "theme": {
    "primary": "#88C0D0",
    "accent": "#A3BE8C",
    "error": "#BF616A",
    "text": "none",
    "background": "none",
    "backgroundPanel": "#2E3440",
    "border": "#4C566A"
  }
}
```

`"none"` 表示继承终端默认前景色或背景色。它适合想让 OpenCode 和终端整体外观保持一致的场景。

## 创建和启用主题

用户级主题：

```bash
mkdir -p ~/.config/opencode/themes
vim ~/.config/opencode/themes/my-theme.json
```

项目级主题：

```bash
mkdir -p .opencode/themes
vim .opencode/themes/my-theme.json
```

创建后，在 `tui.json` 中把 `theme` 设置为文件名对应的主题名。

## 怎么判断主题可用

切换主题后，用一个真实会话检查：

- 普通回答是否能连续阅读十分钟不累。
- 代码块和正文是否有明显区分。
- diff 新增和删除是否不用猜。
- 当前选中的菜单项是否足够醒目。
- 错误、警告、成功状态是否能一眼分辨。

如果这些都没问题，就不需要继续调色。主题配置的目标是降低阅读负担，不是追求配置完整。

## 接下来去哪

<Cards>
  <Card title="TUI 工作流" description="主题、鼠标、diff 样式和命令面板都属于 TUI 使用体验。" href="/docs/opencode/official/00-getting-started/tui" />
  <Card title="快捷键" description="视觉调顺以后，再处理 leader key 和高频快捷键冲突。" href="/docs/opencode/official/01-customization/keybinds" />
  <Card title="配置 OpenCode" description="理解 `tui.json` 和 `opencode.json` 的职责边界。" href="/docs/opencode/official/01-customization/config" />
  <Card title="终端 TUI 工作流" description="从日常任务角度理解 OpenCode TUI 里的高频控制点。" href="/docs/opencode/understanding/03-terminal-workflow" />
</Cards>

## 官方资料

- OpenCode Themes：[https://opencode.ai/docs/themes](https://opencode.ai/docs/themes)
- OpenCode TUI：[https://opencode.ai/docs/tui](https://opencode.ai/docs/tui)
