LowHow 文档

中文

English

中文

English

深色模式

OpenCode 快捷键自定义实战指南：从配置到冲突解决 ​

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

你将学到什么 ​

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

  • [ ] 理解 OpenCode 快捷键的核心配置文件和结构
  • [ ] 独立修改高频操作的快捷键，提升效率
  • [ ] 排查并解决快捷键与终端/系统的冲突问题
  • [ ] 掌握 leader key 的概念与使用方法

最终效果 ​

你将得到一个高度个性化、与你的终端和编辑器不冲突的 OpenCode 快捷键配置。例如：用 Ctrl+x 然后 n 快速创建新会话，用 Ctrl+x 然后 m 快速切换模型。

前置准备 ​

在开始前，请确认你已了解以下概念：

术语解释
tui.jsonOpenCode 的配置文件，用于自定义外观、快捷键等 TUI (终端用户界面) 行为。
keymaptui.json 中用于定义快捷键的字段。
leader key一个前缀键，用于组合出多个快捷键，例如 Ctrl+x 作为 leader，那么 Ctrl+x + n 就是一个快捷键。

1. 找到你的 tui.json 文件 ​

OpenCode 的配置文件通常位于以下路径：

  • macOS / Linux: ~/.config/opencode/tui.json
  • Windows: %APPDATA%\opencode\tui.json

💡 提示：如果文件不存在，你可以手动创建一个。

第 1 步：理解核心配置思路 —— 只改高频和冲突键 ​

🎯 目标：避免被庞大的配置项吓倒，掌握“最小化修改”原则。

很多新手会尝试复制一份完整的快捷键列表，但这是错误的。keymap 配置会自动与内置默认值合并。你只需要修改那些你每天都会用且与终端/编辑器冲突的少数几个键。

🤔 为什么要这样做？

  1. 易于维护：只保留你修改过的配置，未来排查问题时一目了然。
  2. 避免冲突：只改动必要的键，减少意外覆盖默认功能的风险。
  3. 提升效率：集中精力优化高频操作，而不是所有操作。

📝 操作：请记住这个原则，我们将在下一步应用它。

✅ 验证：理解即可，无需操作。

第 2 步：编写你的第一个 keymap 配置 ​

🎯 目标：创建一个覆盖核心高频操作的快捷键配置。

我们将配置以下几个最常用的操作：

  • 创建新会话 (session.new)
  • 查看会话列表 (session.list)
  • 选择模型 (model.list)
  • 选择 Agent (agent.list)
  • 压缩上下文 (session.compact)
  • 输入换行 (input.newline)

📝 操作：

  1. 用文本编辑器打开你的 tui.json 文件。
  2. 将以下内容粘贴进去。请注意，这是你唯一需要的配置，不需要复制任何其他内容。
json
{
  "$schema": "https://opencode.ai/tui.json",
  "keymap": {
    "leader": "ctrl+x",          // 设置 leader key 为 Ctrl+x
    "leader_timeout": 2000,       // leader key 等待输入的超时时间（毫秒）
    "sections": {
      "global": {
        "session.new": "<leader>n",   // Ctrl+x 然后 n：创建新会话
        "session.list": "<leader>l",  // Ctrl+x 然后 l：打开会话列表
        "model.list": "<leader>m",    // Ctrl+x 然后 m：打开模型选择
        "agent.list": "<leader>a"     // Ctrl+x 然后 a：打开 Agent 选择
      },
      "session": {
        "session.compact": "<leader>c" // Ctrl+x 然后 c：压缩上下文
      },
      "input": {
        "input.newline": ["shift+return", "ctrl+return", "alt+return", "ctrl+j"] // 多行输入的换行方式
      }
    }
  }
}

💡 提示：

  • <leader> 会被自动替换为你设置的 "leader": "ctrl+x"。
  • input.newline 提供了多种换行方式，避免与 Enter 提交冲突。

✅ 验证： 保存文件后，重启 OpenCode 或重新打开 TUI 界面。然后尝试：

  1. 按下 Ctrl+x，你会看到屏幕底部或顶部出现提示，等待下一个按键。
  2. 按下 n，应该会创建一个新会话。

第 3 步：处理快捷键冲突 —— 设为 none ​

🎯 目标：优雅地解决快捷键被终端、编辑器或系统占用的问题。

如果你的某个快捷键（例如 Ctrl+c，常用于复制和中断命令）与系统冲突，但你并不想在 OpenCode 中使用它，可以将其禁用。

📝 操作：

假设你的终端占用了 Ctrl+c，而你想禁用 OpenCode 中的 session.compact 快捷键（假设它默认绑定了 Ctrl+c）。

  1. 在 tui.json 的 keymap.sections.session 中，将 session.compact 的值改为 "none"。
json
{
  "$schema": "https://opencode.ai/tui.json",
  "keymap": {
    "sections": {
      "session": {
        "session.compact": "none"  // [!code --]  // 禁用这个快捷键
        // "session.compact": "<leader>c" // [!code ++]  // 或者绑定到其他键
      }
    }
  }
}

🤔 为什么要这样写？"none" 是一个特殊值，告诉 OpenCode 忽略这个快捷键绑定，从而避免与系统发生冲突。

✅ 验证： 保存配置并重启 OpenCode 后，按下之前冲突的键（如 Ctrl+c），OpenCode 将不再响应，该操作会正常传递给你的终端或编辑器。

第 4 步：处理常见问题 —— Shift+Enter 不能换行 ​

🎯 目标：解决在多行输入时，Shift+Enter 无法换行的问题。

这个问题通常不是 OpenCode 的问题，而是你的终端没有正确发送 Shift+Enter 组合键的信号。

📝 操作：

  • Windows Terminal 用户：

    1. 打开 Windows Terminal 的 设置 -> 配置文件 (例如 PowerShell) -> 高级。
    2. 找到 按键绑定，点击 添加。
    3. 命令 选择 将输入发送到 shell。
    4. 按键 设置为 Shift+Enter。
    5. 发送文本 输入 \u001b[13;2u。
    6. 保存设置并重启终端。

  • macOS 终端 (Terminal.app / iTerm2) 用户： 通常不需要额外配置。如果遇到问题，请检查终端自身的快捷键设置，看是否有其他功能占用了 Shift+Enter。

✅ 验证： 在 OpenCode 的输入框中，按下 Shift+Enter，如果光标移动到下一行而不是提交，说明配置成功。

进阶技巧（可选） ​

1. 善用输入区内置快捷键 ​

OpenCode 的输入框支持许多类似 Shell 的快捷键，这些通常不需要配置，但非常高效：

快捷键功能
Ctrl+a移动到当前行开头
Ctrl+e移动到当前行末尾
Ctrl+u删除到行首
Ctrl+k删除到行尾
Ctrl+w删除前一个单词

熟悉它们，比修改快捷键配置更能提升你的输入效率。

2. 验证你的配置是否生效 ​

改完 tui.json 后，重启 OpenCode，逐一验证以下操作：

  • [ ] <leader>n (即 Ctrl+x 然后 n)：创建新会话
  • [ ] <leader>m (即 Ctrl+x 然后 m)：打开模型选择
  • [ ] <leader>a (即 Ctrl+x 然后 a)：打开 Agent 选择
  • [ ] <leader>c (即 Ctrl+x 然后 c)：压缩上下文（如果未禁用）
  • [ ] Tab 键：在主代理之间切换
  • [ ] Shift+Enter：在输入框中换行

如果某个快捷键没反应，请优先检查它是否被你的终端、tmux 或编辑器截获了。OpenCode 收不到按键时，修改它的配置是不会生效的。

常见问题 (FAQ) ​

Q1: 我改了配置，但重启后没有效果？A:

  1. 检查文件路径：确保你修改的是正确的 tui.json 文件。
  2. 检查 JSON 语法：可以使用在线的 JSON 校验工具检查你的文件是否有语法错误（例如缺少逗号、括号不匹配）。
  3. 完全重启：确保你完全关闭了 OpenCode 的终端进程，而不仅仅是关闭了标签页。

Q2: 旧的 keybinds 字段和新的 keymap 字段有什么区别？A: keybinds 是旧版配置方式，已被弃用，将在 OpenCode v2.0 中移除。keymap 是新的配置方式，使用点分隔的命令名（如 session.new）并按 sections 分组。如果两者同时存在，只有 keymap 生效。请务必使用 keymap。

总结 ​

恭喜你完成了本教程！🎉

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

  1. 最小化修改原则：只修改你高频使用和与系统冲突的快捷键。
  2. 核心配置：通过 tui.json 的 keymap 字段进行配置，leader key 是避免冲突的好方法。
  3. 冲突解决：使用 "none" 值可以优雅地禁用冲突快捷键。
  4. 问题排查：Shift+Enter 无法换行时，问题通常出在终端配置上。

© 2026 LowHow