OpenCode 中文教程

简体中文

English

简体中文

English

Appearance

5.6b 快捷键 ​

60+ 快捷键全自定义，打造顺手的操作体验。

📝 课程笔记 ​

本课核心知识点整理：

快捷键学霸笔记

学完你能做什么 ​

  • 掌握 Leader 键机制
  • 自定义任意快捷键
  • 禁用不需要的快捷键
  • 解决终端快捷键冲突

Leader 键 ​

OpenCode 使用 Leader 键 避免与终端快捷键冲突。

默认 Leader 键：Ctrl+X

使用方式：先按 Leader 键，松开，再按第二个键。

Ctrl+X → n    # 新建会话
Ctrl+X → l    # 会话列表
Ctrl+X → m    # 模型列表

快捷键配置 ​

TUI 快捷键使用扁平的 keybinds 映射，配置在独立的 tui.json 或 tui.jsonc 中：

jsonc
{
  "$schema": "https://opencode.ai/tui.json",
  "keybinds": {
    // 修改 Leader 键
    "leader": "ctrl+x",
    
    // 自定义快捷键
    "session_new": "<leader>n",
    "model_list": "<leader>m",
    
    // 多个按键绑定同一功能（逗号分隔）
    "app_exit": "ctrl+c,ctrl+d,<leader>q",
    
    // 禁用快捷键
    "session_compact": false
  }
}

常用配置位置如下，后加载的配置覆盖先加载的配置：

  1. 全局配置目录中的 tui.json / tui.jsonc
  2. OPENCODE_TUI_CONFIG 指向的自定义文件
  3. 从当前打开目录向文件系统根逐层发现，再按根侧到当前目录应用的 tui.json / tui.jsonc
  4. 沿途 .opencode/tui.json / .opencode/tui.jsonc
  5. OPENCODE_CONFIG_DIR 中的 TUI 配置

普通项目文件按根侧到当前目录应用，越近当前目录越优先；多个 .opencode 目录按当前侧到根侧合并，冲突时更靠根侧者后加载并取胜。OPENCODE_CONFIG_DIR 最后加载。

从旧版本升级时，启动 TUI 会检查全局、项目沿途、配置目录和 OPENCODE_CONFIG 指定的旧主配置，把其中的 theme、keybinds 和旧 tui 字段迁移到同目录的 tui.json。如果目标 tui.json 已存在，则跳过该目录；只有 tui.jsonc 不会阻止迁移。成功写入新文件并创建或复用 .tui-migration.bak 备份后，才从原配置删除旧字段。主配置已不再读取这些 TUI 字段。

禁用快捷键 ​

设置为 "none" 或 false 均可禁用：

jsonc
{
  "keybinds": {
    "session_compact": "none",
    "sidebar_toggle": false
  }
}

多键绑定 ​

用逗号分隔多个按键：

jsonc
{
  "keybinds": {
    "input_newline": "shift+return,ctrl+return,alt+return,ctrl+j"
  }
}

常用可配置快捷键 ​

应用控制 ​

键名默认值说明
leaderctrl+xLeader 键
app_exitctrl+c,ctrl+d,<leader>q退出应用
diff_opennone打开 diff viewer（默认通过 /diff 或命令面板进入）
terminal_suspendctrl+z挂起终端
terminal_title_togglenone切换终端标题

界面控制 ​

键名默认值说明
editor_open<leader>e打开外部编辑器
theme_list<leader>t主题列表
sidebar_toggle<leader>b切换侧边栏
scrollbar_togglenone切换滚动条
status_view<leader>s状态视图
tool_detailsnone切换工具详情
tips_toggle<leader>h切换首页提示

会话管理 ​

键名默认值说明
session_new<leader>n新建会话
session_list<leader>l会话列表
session_export<leader>x导出会话
session_timeline<leader>g会话时间线
session_interruptescape中断响应
session_backgroundctrl+b将同步运行的子 Agent 转入后台
session_compact<leader>c压缩上下文
session_forknone从消息分叉
session_renamectrl+r重命名会话
session_sharenone分享会话
session_unsharenone取消分享

会话导航 ​

键名默认值说明
session_child_cycleright切换子会话
session_child_cycle_reverseleft反向切换子会话
session_parentup返回父会话

消息操作 ​

键名默认值说明
messages_copy<leader>y复制消息
messages_undo<leader>u撤销消息
messages_redo<leader>r重做消息
messages_toggle_conceal<leader>h切换代码块折叠

这里的 messages_undo / messages_redo 是会话级撤销与恢复：撤销会回到选定消息，并回滚其后的关联文件补丁；重做会恢复被撤销的状态。主配置 opencode.json / opencode.jsonc 中设置 "snapshot": false 时，消息仍可回退，但不会撤销或恢复文件改动。它们不同于输入框内的 input_undo / input_redo。

Diff viewer ​

Diff viewer 默认启用，可通过 /diff、命令面板，或为 diff_open 自定义快捷键进入。它带文件树，可在工作区改动和最后一轮 AI 改动之间切换；当前分支不是默认分支时，还会提供与主分支比较。它支持按文件或 hunk 导航、单文件 patch、统一/分栏视图和已审阅标记。

键名默认值说明
diff_closeescape,q关闭并返回上一屏
diff_toggleenter,space展开目录或选择文件
diff_expand / diff_collapseright / left展开或折叠文件树项目
diff_expand_allE展开全部目录
diff_switch_focustab在文件树与 patch 区之间切换
diff_next_hunk / diff_previous_hunk] / [跳到下一个/上一个 hunk
diff_next_file / diff_previous_filen / p跳到下一个/上一个文件
diff_toggle_file_treeb显示或隐藏文件树
diff_single_patchs在单个 patch 与全部 patch 之间切换
diff_switch_sourced切换 diff 来源
diff_toggle_viewv切换分栏或统一视图
diff_help?显示完整 diff 快捷键帮助

m 是 diff viewer 内置的“标记已审阅”按键，不属于 keybinds 配置项。

消息滚动 ​

键名默认值说明
messages_page_uppageup,ctrl+alt+b向上翻页
messages_page_downpagedown,ctrl+alt+f向下翻页
messages_half_page_upctrl+alt+u向上半页
messages_half_page_downctrl+alt+d向下半页
messages_firstctrl+g,home跳到第一条
messages_lastctrl+alt+g,end跳到最后一条
messages_nextnone下一条消息
messages_previousnone上一条消息
messages_last_usernone最后一条用户消息

模型与 Agent ​

键名默认值说明
model_list<leader>m模型列表
model_cycle_recentf2切换最近模型
model_cycle_recent_reverseshift+f2反向切换
model_cycle_favoritenone切换收藏模型
model_cycle_favorite_reversenone反向切换收藏
variant_cyclectrl+t切换模型变体
agent_list<leader>aAgent 列表
agent_cycletab切换 Agent
agent_cycle_reverseshift+tab反向切换 Agent
command_listctrl+p命令面板
prompt_skillsnone打开 Skill 选择器

输入区基础 ​

键名默认值说明
input_submitreturn发送消息
input_newlineshift+return,ctrl+return,alt+return,ctrl+j换行
input_clearctrl+c清空输入
input_pastectrl+v粘贴
input_undoctrl+-,super+z撤销输入
input_redoctrl+.,super+shift+z重做输入

输入区光标移动 ​

键名默认值说明
input_move_leftleft,ctrl+b左移一字符
input_move_rightright,ctrl+f右移一字符
input_move_upup上移一行
input_move_downdown下移一行
input_word_forwardalt+f,alt+right,ctrl+right前进一单词
input_word_backwardalt+b,alt+left,ctrl+left后退一单词
input_line_homectrl+a行首
input_line_endctrl+e行尾
input_visual_line_homealt+a可视行首
input_visual_line_endalt+e可视行尾
input_buffer_homehome缓冲区开头
input_buffer_endend缓冲区结尾

光标外观 ​

光标外观不是键绑定，和 keybinds 同级配置：

jsonc
{
  "$schema": "https://opencode.ai/tui.json",
  "cursor": {
    "style": "line",
    "blinking": true
  }
}

style 可设为 block、underline、line 或 default；default 保留终端设置，此时 blinking 不生效。

输入区选择 ​

键名默认值说明
input_select_leftshift+left向左选择
input_select_rightshift+right向右选择
input_select_upshift+up向上选择
input_select_downshift+down向下选择
input_select_word_forwardalt+shift+f,alt+shift+right选择下一单词
input_select_word_backwardalt+shift+b,alt+shift+left选择上一单词
input_select_line_homectrl+shift+a选择到行首
input_select_line_endctrl+shift+e选择到行尾
input_select_visual_line_homealt+shift+a选择到可视行首
input_select_visual_line_endalt+shift+e选择到可视行尾
input_select_buffer_homeshift+home选择到开头
input_select_buffer_endshift+end选择到结尾

输入区删除 ​

键名默认值说明
input_backspacebackspace,shift+backspace退格
input_deletectrl+d,delete,shift+delete删除字符
input_delete_linectrl+shift+d删除整行
input_delete_to_line_endctrl+k删除到行尾
input_delete_to_line_startctrl+u删除到行首
input_delete_word_forwardalt+d,alt+delete,ctrl+delete删除下一单词
input_delete_word_backwardctrl+w,ctrl+backspace,alt+backspace删除上一单词

历史记录 ​

键名默认值说明
history_previousup上一条历史
history_nextdown下一条历史

Desktop 桌面版快捷键 ​

OpenCode 桌面版的输入框支持 Readline/Emacs 风格快捷键（内置，不可通过配置修改）：

快捷键功能
Ctrl+A移到行首
Ctrl+E移到行尾
Ctrl+B后退一字符
Ctrl+F前进一字符
Alt+B后退一单词
Alt+F前进一单词
Ctrl+D删除当前字符
Ctrl+K删除到行尾
Ctrl+U删除到行首
Ctrl+W删除上一单词
Alt+D删除下一单词
Ctrl+T交换字符
Ctrl+G取消弹窗 / 中断响应

终端兼容性 ​

Shift+Enter 问题 ​

部分终端默认不发送 Shift+Enter 修饰键。

症状：按 Shift+Enter 不换行，直接发送消息。

Windows Terminal 配置 ​

编辑 settings.json（路径：%LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json）：

在 actions 数组添加：

json
{
  "command": {
    "action": "sendInput",
    "input": "\u001b[13;2u"
  },
  "id": "User.sendInput.ShiftEnterCustom"
}

在 keybindings 数组添加：

json
{
  "keys": "shift+enter",
  "id": "User.sendInput.ShiftEnterCustom"
}

保存后重启 Windows Terminal。

其他终端 ​

  • iTerm2：默认支持，无需配置
  • Alacritty：默认支持
  • Kitty：默认支持
  • GNOME Terminal：可能需要更新到较新版本

常用场景配置 ​

Vim 风格 ​

jsonc
{
  "keybinds": {
    "leader": "space",
    "messages_page_up": "ctrl+u",
    "messages_page_down": "ctrl+d",
    "messages_first": "gg",
    "messages_last": "G"
  }
}

精简模式 ​

禁用不常用的快捷键：

jsonc
{
  "keybinds": {
    "sidebar_toggle": "none",
    "scrollbar_toggle": "none",
    "session_fork": "none",
    "session_share": "none",
    "session_unshare": "none",
    "tips_toggle": "none"
  }
}

单手操作 ​

将常用操作集中到左手：

jsonc
{
  "keybinds": {
    "session_new": "ctrl+n",
    "session_list": "ctrl+l",
    "model_list": "ctrl+m",
    "agent_cycle": "ctrl+tab"
  }
}

踩坑提醒 ​

现象原因解决
快捷键不生效终端劫持了该按键检查终端设置，或换个按键
Shift+Enter 不换行终端不发送修饰键配置终端（见上文）
配置了但没反应用了 keybind（单数）应使用 keybinds（复数）
用 null 禁用不行语法错误应使用 "none" 或 false
Leader 键冲突和其他程序冲突改用其他 Leader 键如 ctrl+space
Ctrl+C 不清空输入被终端的 SIGINT 拦截使用其他按键或接受默认行为

快捷键速记口诀 ​

Tab 切 Agent，Ctrl+C 清
Leader 加字母，功能随便挑
n 新建 l 列表 m 模型
u 撤销 r 重做不用愁
方向键左右，子会话来回走

本课小结 ​

你学会了：

  1. 使用 Leader 键机制避免冲突
  2. 在 keybinds 中自定义快捷键
  3. 用 "none" 或 false 禁用不需要的快捷键
  4. 用逗号分隔绑定多个按键
  5. 解决终端 Shift+Enter 兼容性问题

相关资源 ​