叶云梦天

OpenCode TUI 配置与快捷键完全指南：用 tui.json 打造极致的终端编程体验

引言

在日常使用 OpenCode 的过程中，你是否曾感到某些快捷键不够顺手？是否希望象 VS Code 或 Vim 那样，让每一个操作都流畅地融入你的肌肉记忆？OpenCode 提供了一个强大的终端界面（TUI）配置文件 tui.json，让你可以精细地控制主题、快捷键、滚动行为、通知等方方面面。

本文将深入介绍 tui.json 的完整配置能力，涵盖内置主题选择与自定义主题创建、Leader Key 快捷键体系、完整的键绑定参考、以及实用的生产力配置技巧。

tui.json 是什么

tui.json 是 OpenCode 的终端界面配置文件，它与 opencode.json 是两套独立的配置体系：

opencode.json 负责服务端/运行时行为配置，如模型选择、权限策略、Agent 定义、MCP 服务器等
tui.json 专门负责终端界面的视觉和交互配置，包括主题、快捷键、滚动行为、通知等

你可以在项目根目录创建 tui.json 或 tui.jsonc，也可以使用 OPENCODE_TUI_CONFIG 环境变量指定自定义路径：

export OPENCODE_TUI_CONFIG=/path/to/my-tui.json

所有配置项都与内置默认值合并，你只需要设置想要修改的部分。

主题配置

内置主题一览

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 主题 |

其中 system 主题很特别 —— 它不会使用固定颜色，而是根据你终端的背景色动态生成灰度值，并使用标准 ANSI 颜色（0-15）做语法高亮。如果你已经精心调教过终端配色，选择 system 能让 OpenCode 完美融入你的终端环境。

切换主题

有两种方式切换主题：

方式一：使用命令面板

在 TUI 中输入 /theme 命令，会弹出主题选择列表，使用 j/k 上下移动，Enter 确认选择。

方式二：在 tui.json 中配置

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

自定义主题

如果你对内置主题都不满意，可以创建自己的主题文件。OpenCode 按以下优先级加载主题（后面的覆盖前面的）：

二进制内置主题

~/.config/opencode/themes/*.json（用户级）

<project-root>/.opencode/themes/*.json（项目级）

./.opencode/themes/*.json（当前工作目录）

创建一个自定义主题：

mkdir -p ~/.config/opencode/themes

主题使用 JSON 格式，需要支持 truecolor（24 位色）的终端。你可以使用 echo $COLORTERM 检查终端是否支持 truecolor，如果不支持，需要设置 COLORTERM=truecolor。

一个精简的自定义主题示例：

{
  "$schema": "https://opencode.ai/theme.json",
  "theme": {
    "primary": "#81A1C1",
    "secondary": "#88C0D0",
    "accent": "#8FBCBB",
    "error": "#BF616A",
    "warning": "#D08770",
    "success": "#A3BE8C",
    "text": "#D8DEE4",
    "textMuted": "#4C566A",
    "background": "#2E3440",
    "backgroundPanel": "#3B4252",
    "border": "#434C5E",
    "borderActive": "#4C566A",
    "diffAdded": "#A3BE8C",
    "diffRemoved": "#BF616A",
    "syntaxComment": "#616E88",
    "syntaxKeyword": "#81A1C1",
    "syntaxFunction": "#88C0D0",
    "syntaxString": "#A3BE8C",
    "syntaxNumber": "#B48EAD"
  }
}

如果想让某些颜色继承终端默认值，可以使用特殊值 "none"：

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

主题还支持 defs 定义区域来管理可复用的颜色变量：

{
  "$schema": "https://opencode.ai/theme.json",
  "defs": {
    "dark_bg": "#1a1b26",
    "dark_fg": "#a9b1d6",
    "blue": "#7aa2f7"
  },
  "theme": {
    "primary": "blue",
    "text": "dark_fg",
    "background": "dark_bg"
  }
}

快捷键体系

Leader Key 机制

OpenCode 借鉴了 Vim/NeoVim 的设计理念，引入了 Leader Key 机制。默认的 Leader Key 是 Ctrl+X。大多数操作需要先按下 Leader Key，再按下对应的快捷键。

例如，要创建新的会话，你需要：

Ctrl+X → n

这种设计避免了快捷键与终端内的其他程序冲突，是终端 TUI 应用的最佳实践。

leader_timeout 控制按下 Leader Key 后等待下一个按键的超时时间，默认为 2000 毫秒。如果你快捷键敲得慢，可以适当调大：

{
  "keybinds": {
    "leader": "ctrl+x",
  },
  "leader_timeout": 3000
}

键绑定值的三种写法

在 tui.json 中配置快捷键支持三种格式：

字符串格式（单个或多个快捷键，逗号分隔）：

{
  "keybinds": {
    "app_exit": "ctrl+c,ctrl+d"
  }
}

数组格式：

{
  "keybinds": {
    "messages_copy": ["<leader>y", "ctrl+shift+c"]
  }
}

对象格式（高级选项，支持 preventDefault 和 fallthrough）：

{
  "keybinds": {
    "input_paste": {
      "key": "ctrl+v",
      "preventDefault": false
    }
  }
}

使用 <leader> 引用位符来引用你配置的 Leader Key：

{
  "keybinds": {
    "leader": "ctrl+o",
    "session_new": "<leader>n"
  }
}

要禁用某个快捷键，将其值设为 "none" 或 false：

{
  "keybinds": {
    "tips_toggle": "none"
  }
}

核心快捷键分类速查

以下是按功能分类的核心快捷键，默认绑定以 <leader> 表示 Ctrl+X。

#### 会话管理

| 操作 | 默认快捷键 | 说明 |
|------|-----------|------|
| 新建会话 | <leader>n | 创建全新会话，清除当前对话 |
| 会话列表 | <leader>l | 查看并切换已有会话 |
| 会话重命名 | Ctrl+R | 重命名当前会话 |
| 删除会话 | Ctrl+D | 删除当前会话 |
| 会话时间线 | <leader>g | 查看会话的操作时间线 |
| 导出会话 | <leader>x | 将会话导出为文件 |
| Fork 会话 | 默认无 | 从当前点分叉一个新会话 |

#### 中断与撤销

| 操作 | 默认快捷键 | 说明 |
|------|-----------|------|
| 中断 AI 响应 | Esc | 取消正在进行的 AI 操作 |
| 撤销消息 | <leader>u | 撤销上一条 AI 回复 |
| 重做消息 | <leader>r | 重做被撤销的 AI 回复 |
| 收起/展开对话 | <leader>h | 切换对话内容的折叠状态 |

#### 模型与 Agent 管理

| 操作 | 默认快捷键 | 说明 |
|------|-----------|------|
| 模型列表 | <leader>m | 打开模型选择对话框 |
| 切换提供商 | Ctrl+A | 切换 LLM 提供商 |
| 收藏模型 | Ctrl+F | 收藏/取消收藏当前模型 |
| 轮换最近模型 | F2 | 切换到上一个使用的模型 |
| 反向轮换模型 | Shift+F2 | 切换到下一个模型 |
| Agent 列表 | <leader>a | 打开 Agent 选择对话框 |
| 轮换 Agent | Tab | 切换到下一个 Agent |
| 反向轮换 Agent | Shift+Tab | 切换到上一个 Agent |
| 轮换变体 | Ctrl+T | 在不同模型变体间切换 |

#### 界面与导航

| 操作 | 默认快捷键 | 说明 |
|------|-----------|------|
| 命令面板 | Ctrl+P | 打开命令面板/Which Key |
| 切换侧边栏 | <leader>b | 切换侧边栏显示 |
| 切换主题 | <leader>t | 打开主题切换器 |
| 状态视图 | <leader>s | 查看当前状态（模型、Agent 等） |
| 打开外部编辑器 | <leader>e | 在 $EDITOR 中打开当前文件 |
| 消息压缩 | <leader>c | 执行 /compact 压缩上下文 |
| 显示帮助 | 默认禁用 | 显示快捷键帮助 |
| 打开文档 | 默认禁用 | 打开 opencode.ai 文档 |

#### 消息区域导航

| 操作 | 默认快捷键 | 说明 |
|------|-----------|------|
| 向上翻页 | PageUp, Ctrl+Alt+B | 消息区域向上翻页 |
| 向下翻页 | PageDown, Ctrl+Alt+F | 消息区域向下翻页 |
| 向上一行 | Ctrl+Alt+Y | 消息向上滚动一行 |
| 向下一行 | Ctrl+Alt+E | 消息向下滚动一行 |
| 上半页 | Ctrl+Alt+U | 消息向上滚动半页 |
| 下半页 | Ctrl+Alt+D | 消息向下滚动半页 |
| 跳转到顶部 | Ctrl+G, Home | 跳转到消息最顶端 |
| 跳转到底部 | Ctrl+Alt+G, End | 跳转到消息最底端 |
| 复制消息 | <leader>y | 复制当前选中的消息 |

#### 输入框编辑

OpenCode 的输入框支持类 Emacs/Readline 风格的快捷键，以下是最常用的：

| 操作 | 快捷键 | 说明 |
|------|--------|------|
| 行首 | Ctrl+A | 光标移动到行首 |
| 行尾 | Ctrl+E | 光标移动到行尾 |
| 前进一个词 | Alt+F | 光标前进一个单词 |
| 后退一个词 | Alt+B | 光标后退一个单词 |
| 删除到行尾 | Ctrl+K | 删除光标到行尾的内容 |
| 删除到行首 | Ctrl+U | 删除光标到行首的内容 |
| 删除前一词 | Ctrl+W | 删除光标前的一个单词 |
| 删除后一词 | Alt+D | 删除光标后的一个单词 |
| 全选 | Super+A（Ctrl+A） | 全选输入内容 |
| 提交消息 | Enter | 发送消息 |
| 输入换行 | Shift+Enter, Ctrl+J | 输入换行符而不发送 |
| 清空输入 | Ctrl+C | 清空当前输入框 |

#### 对话框通用操作

在各类对话框（会话列表、模型列表、主题选择器等）中，统一的导航快捷键：

| 操作 | 快捷键 | 说明 |
|------|--------|------|
| 上一项 | ↑, Ctrl+P | 移动到上一项 |
| 下一项 | ↓, Ctrl+N | 移动到下一项 |
| 上一页 | PageUp | 翻到上一页 |
| 下一页 | PageDown | 翻到下一页 |
| 页首 | Home | 跳转到列表顶部 |
| 页尾 | End | 跳转到列表底部 |
| 确认 | Enter | 确认选择 |
| 取消 | Esc | 关闭对话框 |

#### SubAgent 会话导航

当 AI 启动了 SubAgent（子智能体）时，你可以用以下快捷键在父会话和子会话之间导航：

| 操作 | 默认快捷键 | 说明 |
|------|-----------|------|
| 进入第一个子会话 | <leader>↓ | 查看第一个 SubAgent 会话 |
| 切换到下一个子会话 | → | 轮换到下一个 SubAgent |
| 切换到上一个子会话 | ← | 轮换到上一个 SubAgent |
| 返回父会话 | ↑ | 返回到父 Agent 会话 |

#### Which Key 导航

Which Key 是 OpenCode 的快捷键发现工具（默认 Ctrl+Alt+K），帮助你逐步探索所有可用快捷键：

| 操作 | 快捷键 |
|------|--------|
| 显示/隐藏 Which Key | Ctrl+Alt+K |
| 切换布局 | Ctrl+Alt+Shift+K |
| 切换待处理模式 | Ctrl+Alt+Shift+P |
| 上一组 | Ctrl+Alt+← |
| 下一组 | Ctrl+Alt+→ |

Which Key：你的快捷键导师

如果你记不住这么多快捷键，Which Key 是你的救星。按下 Ctrl+Alt+K，一个浮层面板会显示当前上下文下所有可用的快捷键分组。你可以继续按键深入探索，就像在 NeoVim 中使用 which-key.nvim 插件一样。

TUI 行为配置

除了主题和快捷键，tui.json 还提供了多项 UI 行为配置：

{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "catppuccin",
  "scroll_speed": 5,
  "scroll_acceleration": {
    "enabled": true
  },
  "diff_style": "auto",
  "mouse": true,
  "attention": {
    "enabled": true,
    "notifications": true,
    "sound": false,
    "volume": 0.4
  }
}

scroll_speed：控制滚动速度，默认值为 3。值越大滚动越快（最小 0.001，支持小数）。如果你习惯快速浏览，可以调到 5 或更高。

scroll_acceleration：启用 macOS 风格的滚动加速。快速滚动时会动态提升速度，慢速滚动时保持精确。启用后 scroll_speed 设置会被忽略。

diff_style：控制代码 diff 的显示方式。"auto" 会根据终端宽度自适应切换为单列或双列布局；"stacked" 始终使用单列布局，适合窗口较窄的场景。

mouse：启用或禁用鼠标捕获（默认 true）。如果你习惯了在终端中使用鼠标选中和滚动文本，可以将其设为 false，让终端的原生鼠标行为生效。

attention：桌面通知和声音配置。enabled 控制总开关，notifications 控制桌面通知，sound 控制声音提示。你还可以使用自定义音效包：

{
  "attention": {
    "enabled": true,
    "sound": true,
    "sound_pack": "opencode.default",
    "sounds": {
      "error": "./sounds/error.mp3"
    }
  }
}

实战：一套高效的生产力配置

以下是一套经过验证的高效配置模板，兼顾了美观、速度和操作效率：

{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "tokyonight",
  "leader_timeout": 1500,
  "keybinds": {
    "leader": "ctrl+o",
    "session_new": "<leader>n",
    "session_list": "<leader>l",
    "session_compact": "<leader>c",
    "session_export": "<leader>x",
    "session_rename": "ctrl+r",
    "session_delete": "ctrl+d",
    "session_interrupt": "ctrl+c",
    "command_list": "ctrl+p",
    "editor_open": "<leader>e",
    "theme_list": "<leader>t",
    "sidebar_toggle": "<leader>b",
    "status_view": "<leader>s",
    "agent_list": "<leader>a",
    "agent_cycle": "tab",
    "agent_cycle_reverse": "shift+tab",
    "model_list": "<leader>m",
    "model_cycle_recent": "f2",
    "model_cycle_recent_reverse": "shift+f2",
    "messages_copy": "<leader>y",
    "messages_undo": "<leader>u",
    "messages_redo": "<leader>r",
    "messages_toggle_conceal": "<leader>h",
    "messages_page_up": "pageup,ctrl+b",
    "messages_page_down": "pagedown,ctrl+f",
    "messages_half_page_up": "ctrl+u",
    "messages_half_page_down": "ctrl+d",
    "messages_first": "home,g",
    "messages_last": "end,G",
    "which_key_toggle": "ctrl+alt+k"
  },
  "scroll_acceleration": {
    "enabled": true
  },
  "diff_style": "auto",
  "mouse": true,
  "attention": {
    "enabled": true,
    "notifications": false,
    "sound": true,
    "volume": 0.3
  }
}

这套配置的几个亮点：

Leader Key 改为 Ctrl+O：比默认的 Ctrl+X 更顺手，减少了手指的伸展距离。

消息导航更 Vim 化：Ctrl+B/Ctrl+F 翻页，Ctrl+U/Ctrl+D 半页滚动，g/G 跳转首尾 —— 完全匹配 Vim 用户的肌肉记忆。

leader_timeout 缩短到 1500ms：更快的响应节奏，适合熟练用户。

关闭桌面通知，保留声音：弹窗通知会打断思路，但声音提醒可以在 AI 完成任务时及时知道。

滚动加速：浏览长对话时体验更流畅。

注意事项

Windows 用户：Windows 上的 input_undo 和 terminal_suspend 默认按键与 Linux/macOS 不同，注意不要被文档中的默认值误导。

Shift+Enter 问题：部分终端不会将 Shift+Enter 正确发送给 TUI 应用。如果遇到无法输入换行的情况，可以使用 Ctrl+J 作为替代方案，或配置终端发送 Shift+Enter 的转义序列。

快捷键冲突：某些快捷键可能与你的终端、tmux 或 shell 的快捷键冲突。例如 Ctrl+A 在 tmux 中是默认的前缀键。遇到冲突时，优先调整 OpenCode 的绑定或 tmux 的前缀键。

总结

tui.json 是 OpenCode 中一个强大而精细的配置工具，它让你可以像定制代码编辑器一样定制你的 AI 编程终端。从主题的选择到每一个按键的行为，你都能精确控制。一个精心调校的 TUI 配置，能在日常使用中节省大量时间，让 AI 辅助编程的体验无缝融入你的工作流。

花半小时配置好你的 tui.json，然后坐下来，按下 Ctrl+O → n，开始你和 AI 的下一段高效编码之旅吧。

OpenCode TUI 配置与快捷键完全指南：用 tui.json 打造极致的终端编程体验

OpenCode TUI 配置与快捷键完全指南：用 tui.json 打造极致的终端编程体验

引言

tui.json 是什么

主题配置

内置主题一览

切换主题

自定义主题

快捷键体系

Leader Key 机制

键绑定值的三种写法

核心快捷键分类速查

Which Key：你的快捷键导师

TUI 行为配置

实战：一套高效的生产力配置

注意事项

总结

叶云梦天

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