1. OpenCode 快捷键自定义到底改什么tui.json 与 keybinds 的完整关系OpenCode 是一个跑在终端里的 AI 编程助手你可以把它理解成「住在命令行里的结对程序员」。它默认给了一套快捷键但每个人的手感和终端环境都不一样所以它把键位配置完全开放出来放在tui.json这个文件里。这篇要解决的就是怎么在不改源码的前提下通过tui.json的keybinds字段和 Leader Key 机制把 OpenCode 的快捷键改成自己顺手的一套。适合谁看三类人最需要一是每天在终端里泡很久、对键位有肌肉记忆的老手二是用 Windows Terminal 或 iTerm2发现某些组合键被终端抢走的用户三是想把 OpenCode 接进自己工作流、需要统一键位风格的开发者。核心检索词就三个OpenCode、快捷键、tui.json围绕它们展开。先说清楚tui.json的定位。OpenCode 的配置分两层一层是opencode.json管模型、Provider、权限这些「业务」配置另一层就是tui.json专门管终端界面相关的行为快捷键就在这里面。两者职责不重叠改键位只动tui.json别去opencode.json里找keybinds找不到的。tui.json里跟快捷键相关的核心字段是keybinds它是一个对象键是「操作名」值是这个操作绑定的按键。操作名是 OpenCode 内部定义好的比如app_exit、session_new、messages_copy你不能自己造操作名只能改它绑的键。这一点很关键很多人第一次改配置失败就是因为把操作名写错了。还有一个字段是leader_timeout单位毫秒默认 2000。它跟 Leader Key 机制绑定后面会细讲。整个文件顶部通常有一行$schema指向官方的 JSON Schema写配置时编辑器能给你补全和校验强烈建议保留。我实测下来改键位这件事最容易踩的坑不是语法而是「不知道有哪些操作名可用」。官方 Schema 里列了全部操作名你可以打开https://opencode.ai/tui.json看或者在编辑器里靠 Schema 补全一个个翻。把常用的十几个记住剩下的用到再查就够了。下面这张表先给你一个全局印象把最常改的几类操作和默认键位列出来方便对照操作名作用默认键位leader前缀键本身ctrlxapp_exit退出应用ctrlc,ctrld,leaderqsession_new新建会话leadernsession_rename重命名会话ctrlrsession_compact压缩会话上下文leadercmessages_copy复制消息leaderyinput_paste粘贴输入ctrlvinput_undo撤销输入平台相关看懂这张表你就知道改键位的本质左边操作名不动右边键位随便换。接下来从 Leader Key 讲起因为它是 OpenCode 键位体系里最特别、也最容易被误解的设计。2. Leader Key 机制与 tui.json 前置准备keybinds 配置前必须搞懂的事Leader Key 是 OpenCode 键位体系的核心。你可以把它类比成 Vim 的leader或者 tmux 的 prefix 键先按一个「前缀键」松开再按第二个键两个键组合起来触发一个命令。默认前缀键是ctrlx所以「新建会话」这个操作绑的是leadern实际按法是先ctrlx再n。为什么要这么设计因为终端本身已经占用了一大批组合键ctrlc、ctrld、ctrlz这些都有既定含义。如果 OpenCode 直接把「新建会话」绑成ctrln很可能跟终端或 shell 的快捷键打架。用 Leader Key 相当于开辟了一个「命名空间」leader后面的键归 OpenCode 管冲突概率大大降低。leader_timeout控制的就是这个「等待第二个键」的时间窗口。默认 2000 毫秒也就是按下ctrlx之后你有 2 秒时间按下一个键超时没按这次前缀就作废不会触发任何命令。如果你手速快可以把它调小到 800 甚至 500减少误触等待如果你习惯慢一点调到 3000 也行。这个值只影响体验不影响功能。在动手改之前先确认几件事。第一找到你的tui.json在哪。OpenCode 的配置文件通常放在用户配置目录下Linux/macOS 一般在~/.config/opencode/Windows 在%APPDATA%\opencode\或用户目录下的.config\opencode\。如果文件不存在直接新建一个即可OpenCode 启动时会读取。第二确认你的 OpenCode 版本支持keybinds。这个字段是较新版本才完善的老版本可能只有部分操作可配。跑一下opencode --version看版本号太老的话先升级。第三备份原文件。改配置前把tui.json复制一份成tui.json.bak改崩了能秒回滚这个习惯能省你很多时间。第三点特别提醒tui.json必须是合法 JSON不能有注释、不能有尾逗号。很多人从别处复制配置带了//注释结果 OpenCode 直接报解析错误、整个 TUI 起不来。如果你确实想留注释就在文件外面单独记别写进 JSON 里。前置准备做完就可以进入实际配置了。下一节给你一份可以直接复制的完整tui.json片段包含 Leader Key 重映射、常用操作改键、以及preventDefault这种进阶写法逐段解释每个字段在干什么。3. 可直接复制的 tui.json 配置片段keybinds 与 Leader Key 重映射实战这一节是全文的核心给你一份能直接用的tui.json。先看完整片段再逐段拆解。假设你想把 Leader Key 从ctrlx换成ctrlspace把新建会话改成leadert复制消息绑成两个键并且关掉容易误触的压缩会话快捷键{ $schema: https://opencode.ai/tui.json, leader_timeout: 1500, keybinds: { leader: ctrlspace, app_exit: ctrlc,ctrld,leaderq, session_new: leadert, session_rename: ctrlr, session_compact: none, messages_copy: [leadery, ctrlshiftc], input_paste: { key: ctrlv, preventDefault: false } } }逐段看。$schema指向官方 Schema保留它编辑器会给你补全和红线提示。leader_timeout我设成 1500比默认 2000 短一点手速中等的人用着刚好。leader改成ctrlspace注意这个键在很多终端里是输入法切换键如果你用中文输入法可能会冲突那就换成ctrlx或ctrla之类不常用的组合。session_new从默认的leadern改成leadert纯粹是个人习惯t对应「tab/new」的联想。session_compact设成none表示这个操作不绑任何键防止手滑压缩上下文。messages_copy用了数组写法同时绑leadery和ctrlshiftc前者是 OpenCode 风格后者是很多终端的复制习惯两个都能触发。input_paste用了对象写法这是进阶用法。key是绑定的键preventDefault控制是否阻止终端默认行为。粘贴这个操作比较特殊有些终端自己会处理ctrlv如果你发现 OpenCode 里粘贴没反应把preventDefault设成false让事件透传给终端往往就好了。关于绑定值的写法这里系统总结一下你改任何操作都用得上写法示例说明单键字符串ctrlr绑一个键多键字符串ctrlc,ctrld逗号分隔任一触发数组[leadery, ctrlshiftc]等价于多键字符串更清晰对象{key: ctrlv, preventDefault: false}需要控制默认行为时用禁用none或false不绑任何键改完保存重启 OpenCode 让配置生效。如果 TUI 起不来或者键位没变先检查 JSON 是否合法再检查操作名是否拼错。下一节讲怎么验证配置真的生效了以及验证过程中会看到什么。4. 验证快捷键是否生效从启动日志到实际按键的完整检查流程配置写完不代表生效得验证。验证分三步语法校验、启动检查、实际按键测试。三步都过才算真的改成功。第一步语法校验。最省事的办法是用命令行工具跑一遍 JSON 解析。如果你装了jq直接jq . ~/.config/opencode/tui.json能正常输出格式化后的 JSON 就说明语法没问题报错的话它会告诉你第几行出错。没装jq也行用 Pythonpython -m json.tool ~/.config/opencode/tui.json效果一样。这一步能拦掉绝大多数「尾逗号」「缺引号」的低级错误。第二步启动检查。重新打开 OpenCode观察启动过程有没有报错。如果tui.json解析失败OpenCode 通常会在启动时打印一行警告或者直接回退到默认配置。注意有些版本解析失败是静默回退的也就是不报错但你的配置没生效所以不能只看有没有报错还得进第三步。第三步实际按键测试。这是最关键的。先测 Leader Key按下你新设的前缀键比如ctrlspace然后按t看是否新建了会话。如果新建成功说明leader和session_new都生效了。再测禁用项按原来的压缩会话快捷键应该毫无反应说明none生效了。最后测多键绑定分别按leadery和ctrlshiftc看是否都能复制消息。测试时有个小技巧把leader_timeout临时调大比如设成 5000这样你按完前缀键有充足时间找下一个键方便确认映射对不对。确认无误后再调回正常值。这个办法在排查「到底是键位没生效还是我按太慢」时特别有用。如果某一步没通过别急着重写整个文件先定位是哪个操作的问题。把其他配置注释掉当然 JSON 不能注释就临时删掉只留出问题的那一项单独测。缩小范围后问题通常很明显要么操作名拼错要么键位被终端占用要么写法不对。下一节把最常见的几类报错和排查方法集中列出来。5. 常见报错与排查401、local proxy failed、reading choices、OAuth 对照处理改键位本身很少直接引发网络类报错但你在配置 OpenCode 的过程中很可能同时遇到接入相关的错误。这一节把几类高频报错和排查思路集中讲清楚方便你对照。先说401。这个错误跟键位无关是认证失败通常出现在你配置了模型 Provider 但 API Key 不对或过期的时候。排查顺序确认 Key 有没有复制全前后空格、换行都算错、确认 Key 对应的账户还有额度、确认 Base URL 写对了。如果你用的是 TaoToken 这类兼容接口Base URL 要填https://taotoken.net/apiKey 在控制台的 API Keys 页面生成模型 ID 按文档填。三件套Base URL Key Model ID缺一不可任何一个错都会 401 或 404。再说local proxy failed。这个报错一般出现在 OpenCode 尝试走本地代理端口但连不上的时候。排查确认你配置里的代理地址和端口跟实际运行的服务一致确认那个服务确实在跑确认没有多个进程抢同一个端口。如果你根本没配代理却报这个错检查一下环境变量里有没有残留的代理设置清掉再试。reading choices这类报错通常跟模型返回格式有关。它表示 OpenCode 在解析模型响应时没找到预期的choices字段。常见原因是 Base URL 指向的接口不是 OpenAI 兼容格式或者模型 ID 填错导致返回了错误结构。解决确认接口是兼容 OpenAI 的/v1/chat/completions风格确认模型 ID 跟服务商文档一致。用 TaoToken 的话模型对话页面可以直接验证某个模型 ID 是否可用先在那里测通再填进配置。OAuth相关报错出现在你用 OAuth 方式登录某些 Provider 时。如果登录流程卡住或回调失败先确认本地回调端口没被占用再确认浏览器能正常跳转。有些环境比如远程服务器没有浏览器OAuth 就走不通这种情况改用 API Key 方式接入更省事。排查通用原则一次只改一个变量。改完键位测键位改完 Provider 测 Provider别同时改一堆然后不知道是哪个出的问题。另外OpenCode 的日志通常会写明错误来源遇到报错先看日志第一行往往直接指向根因。把上面这几类对照着查大部分接入问题都能自己解决。6. 把键位调成自己的长期使用与 Coding Plan 的配合建议键位改完之后真正的价值在于长期用起来顺手。我的建议是别一次性改太多。先改三五个你最常按、最别扭的键用一周形成肌肉记忆后再改下一批。一次性把几十个键全重映射结果就是你自己都记不住反而降低效率。Leader Key 的选择有个实用原则选一个终端和 shell 都不常用的组合。ctrlx是默认值够用ctrlspace在中文输入法环境下容易冲突ctrla在 tmux 里是 prefix会打架。如果你用 tmux避开ctrla和ctrlb如果你用 Vim避开ctrlw。选之前先想想自己日常环境里哪些键被占了。如果你打算把 OpenCode 当成长期编码助手配合 Coding Plan 用会更划算。Coding Plan 面向的是持续性的编码和 Agent 场景适合每天都要跟模型来回多轮的人。配置方式跟普通接入一样Base URL 填https://taotoken.net/apiKey 和模型 ID 按文档来。键位调顺了再配上稳定的额度日常写代码的体验会明显不一样。最后给一个实用技巧把你的tui.json纳入 dotfiles 管理。如果你用 Git 管理配置文件把tui.json加进去换机器时直接拉下来键位习惯跟着走不用重新配。改配置前先 commit改崩了git checkout秒回滚比手动备份还方便。想验证某个模型 ID 能不能用去模型对话页面直接发一条消息测要生成和管理 Key去 API Keys 页面接入细节看文档长期编码需求了解 Coding Plan。键位是你自己的怎么顺手怎么来OpenCode 把权限交出来了剩下的就是动手调。