Open Code 文档

主题

首页文档搜索

OpenCode 快捷键配置实战教程 ​

📚 分类: 工具配置 ⏱️ 预计耗时: 10 分钟 🎯 难度: 入门 🔧 环境要求: 已安装并运行过 OpenCode 🌐 原文来源: OpenCode 官方文档

你将学到什么 ​

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

  • [ ] 理解 OpenCode 快捷键（Keybinds）的核心概念
  • [ ] 通过修改 tui.json 配置文件，自定义高频操作快捷键
  • [ ] 解决快捷键与终端或系统冲突的问题
  • [ ] 验证自己的配置是否生效

最终效果 ​

你将拥有一套为自己量身定制的、不与现有工具冲突的 OpenCode 快捷键。例如，你可以通过 Ctrl+X 然后按 N 来快速创建一个新会话，而不是在菜单里寻找入口。

前置准备 ​

在开始前，请确认你已满足以下条件：

检查项要求验证方法
OpenCode 已安装任意版本在终端输入 opencode --version
定位配置文件找到 tui.json见下方步骤1
一个文本编辑器如 VS Code，Sublime Text-

1. 定位并打开 tui.json 文件 ​

OpenCode 的所有界面（TUI）设置都保存在 tui.json 文件中。

📝 操作：

  1. 打开你的终端。

  2. 运行以下命令，用你的文本编辑器打开配置文件。如果文件不存在，此命令会自动创建它。

    bash
    # 使用 VS Code 打开
$ code ~/.config/opencode/tui.json

# 或者使用 Vim 打开
$ vim ~/.config/opencode/tui.json

✅ 验证： 你应该会看到一个空文件或一个包含一些默认配置的 JSON 文件。

💡 提示：~/.config/opencode/ 是 OpenCode 在 Linux/macOS 上的默认配置目录。如果你是 Windows 用户，路径通常是 C:\Users\你的用户名\.config\opencode\。

第 1 步：理解核心概念 - 从“旧”到“新” ​

🎯 目标：了解 OpenCode 快捷键配置方式的演变，确保你使用的是最新、推荐的写法。

OpenCode 的快捷键配置方式经历过一次更新。如果你在网上看到旧教程，可能会感到困惑。

  • 旧方式（已弃用）：使用 keybinds 字段，命令名用下划线连接，例如 session_new。
  • 新方式（推荐）：使用 keymap 字段，命令名用点号连接，例如 session.new。

🤔 为什么要这样做？ 新方式 (keymap) 结构更清晰，支持分组，并且是未来的发展方向。旧方式 (keybinds) 将在 OpenCode v2.0 中彻底移除。请确保你使用的是 keymap。

📝 操作：

在 tui.json 文件中，写入以下基础结构：

json
{
  "$schema": "https://opencode.ai/tui.json",
  "keymap": {
    "leader": "ctrl+x",
    "leader_timeout": 2000,
    "sections": {}
  }
}

✅ 验证：保存文件。OpenCode 会自动识别新配置。目前 sections 还是空的，所以不会改变任何行为。

第 2 步：配置你的第一个快捷键 - “Leader Key” ​

🎯 目标：理解并设置“前导键”（Leader Key），这是你所有自定义快捷键的“总开关”。

leader 键就像一个快捷键的前缀。默认是 ctrl+x。当你定义了快捷键 <leader>n，它的意思就是：先按住 Ctrl 和 X，松开，然后按 N。

📝 操作：

我们使用 leader 键来创建最常用的几个操作。在刚才的 tui.json 文件的 sections 对象内，添加以下内容：

json
// ~/.config/opencode/tui.json
{
  "$schema": "https://opencode.ai/tui.json",
  "keymap": {
    "leader": "ctrl+x", // 前导键，可根据习惯修改
    "leader_timeout": 2000, // 按下前导键后，等待下一按键的超时时间（毫秒）
    "sections": {
      // 新增：全局操作
      "global": {
        "session.new": "<leader>n", // 创建新会话
        "session.list": "<leader>l", // 显示会话列表
        "model.list": "<leader>m", // 选择模型
        "agent.list": "<leader>a" // 选择 Agent
      },
      // 新增：会话操作
      "session": {
        "session.compact": "<leader>c" // 压缩当前会话上下文
      },
      // 新增：输入框操作
      "input": {
        "input.newline": ["shift+return", "ctrl+return", "alt+return", "ctrl+j"] // 多行输入时换行
      }
    }
  }
}

🤔 为什么要用前导键？ 终端、Shell、编辑器（如 Vim、VS Code）和 Tmux 等工具会占用大量的单键或组合键（如 Ctrl+C 用于复制，Ctrl+D 用于关闭终端）。使用前导键可以极大降低快捷键冲突的概率。

✅ 验证：保存 tui.json，然后重启 OpenCode 或重新打开 TUI 界面。尝试按下 Ctrl+X，然后松开，再按 N。你应该会看到创建了一个新的会话。

第 3 步：解决冲突 - 禁用“不听话”的快捷键 ​

🎯 目标：学会如何禁用与系统或其它程序冲突的快捷键。

有时，某个快捷键（比如 Ctrl+C）被 OpenCode 和你的终端同时占用了。解决方法是直接在 OpenCode 中禁用它。

📝 操作：

假设 session.compact（压缩上下文）的默认快捷键与你的 Tmux 冲突了。你可以在 session 分组中将它设置为 "none"。

json
// ~/.config/opencode/tui.json
{
  "$schema": "https://opencode.ai/tui.json",
  "keymap": {
    // ... 其他配置
    "sections": {
      // ... 其他分组
      "session": {
        // [!code --] "session.compact": "<leader>c" // 旧的，会冲突的快捷键
        "session.compact": "none" // 禁用此快捷键
      }
    }
  }
}

⚠️ 常见错误：不要试图复制一份完整的官方快捷键列表，然后只修改其中几个。只写你需要修改的键。OpenCode 会自动将你的配置与默认配置合并。只写差异部分，能让你的配置文件保持简洁，也更容易排查问题。

✅ 验证：保存后重启 OpenCode，尝试按下之前冲突的快捷键。如果它不再触发 OpenCode 的 session.compact 功能，说明禁用成功。

第 4 步：排查与验证 - 确保一切工作正常 ​

🎯 目标：学习如何系统地测试你的快捷键配置，并解决常见问题。

📝 操作：

  1. 重启 OpenCode：每次修改 tui.json 后，都必须重启 OpenCode 或重新打开 TUI 界面。
  2. 逐项测试：按照下面的列表，逐一验证你的快捷键是否生效。

✅ 验证清单：

  • [ ] <leader>n（即 Ctrl+X 然后 N）：能创建新会话。
  • [ ] <leader>m：能打开模型选择列表。
  • [ ] <leader>a：能打开 Agent 选择列表。
  • [ ] <leader>c：能压缩上下文（如果你没有禁用它）。
  • [ ] Shift+Enter：在输入多行提示词时能正常换行。
  • [ ] Tab：能在主代理（Agent）之间切换。

⚠️ 常见问题：Shift+Enter 不能换行

如果你的 Shift+Enter 无法在输入框中换行，问题通常不在 OpenCode，而在于你的终端模拟器没有正确传递这个按键组合。

  • Windows Terminal 用户：需要在 settings.json 中为 shift+enter 绑定一个特定的转义序列。
    1. 打开 Windows Terminal 的设置 (Ctrl+,)。
    2. 选择左下角的“打开 JSON 文件”。
    3. 找到 "actions" 数组，添加以下内容：
      json
      { "command": { "action": "sendInput", "input": "\u001b[13;2u" }, "keys": "shift+enter" }
    4. 保存文件并重启终端。
  • macOS 用户：通常无需额外配置。如果问题依旧，请检查 iTerm2 或 Terminal.app 自身的快捷键设置，看是否有冲突。

进阶技巧（可选） ​

掌握基础后，你可以尝试：

  1. 修改 Leader Key：如果你觉得 Ctrl+X 不好按，可以改成 Ctrl+Space，只需将 "leader": "ctrl+space" 即可。
  2. 了解输入区快捷键：OpenCode 的输入框支持常见的 Readline/Emacs 风格快捷键，这些通常无需配置：
    • Ctrl+A：跳到行首
    • Ctrl+E：跳到行尾
    • Ctrl+K：删除到行尾
    • Ctrl+U：删除到行首

常见问题 (FAQ) ​

Q1: 我改完了 tui.json，但快捷键没反应，怎么办？A: 请按以下顺序排查：

  1. 确认你重启了 OpenCode。
  2. 检查 tui.json 的 JSON 格式是否正确（可以在 JSONLint 上验证）。
  3. 检查该快捷键是否被你的终端、Tmux 或 编辑器 拦截了。例如，在终端中按下该快捷键，看看是触发了终端的功能，还是没反应。如果被终端拦截，OpenCode 是收不到按键的，此时修改 OpenCode 配置无效。

Q2: 如何查看 OpenCode 的所有默认快捷键？A: 官方文档是最佳来源。你可以在 OpenCode Keybinds 官方文档 中查看完整列表。

总结 ​

恭喜你完成了本教程！🎉

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

  1. 配置方式：使用 tui.json 文件中的 keymap 字段（而非旧的 keybinds）。
  2. 核心概念：“前导键”（Leader Key）是降低快捷键冲突的有效方式。
  3. 最小修改原则：只修改你高频使用或存在冲突的快捷键，保持配置简洁。
  4. 禁用冲突：将冲突快捷键的值设为 "none" 即可禁用。
  5. 验证方法：修改后必须重启，并逐一测试。

下一步 ​

如果你想继续深入，建议学习：

💡 练习任务：尝试将 leader key 改为 ctrl+z，然后重新配置第 2 步中的所有快捷键。这是巩固知识的最佳方式。

yaml

Open Code 文档社区

© 2026 Open Code. All rights reserved.