---
title: "配置快捷键"
description: "用 tui.json 调整少数真正影响效率的 OpenCode TUI 快捷键。"
verifiedAt: "2026-05-09"
---

OpenCode 的快捷键通过 `tui.json` 的 `keymap` 字段自定义（新手不需要复制完整快捷键表，只改每天会用、且和终端冲突的少数几个键）。

> [!IMPORTANT]
> **从 `keybinds` 迁移到 `keymap`**：旧的 `keybinds` 字段（用 `_` 分隔的扁平命令名，如 `session_new`）官方已弃用，将在 OpenCode **v2.0 移除**；新的 `keymap` 用 `.` 分隔的命令名（如 `session.new`），并按 sections 分组。两者同时存在时只 `keymap` 生效。本篇示例统一用 `keymap`。

> [!NOTE]
> **这一篇用 6 分钟换什么**：你会知道先改哪些高频快捷键、leader key 怎么理解、冲突键怎么禁用，以及 `Shift+Enter` 不能换行时该排查哪里。

## 先给结论：只改高频和冲突

快捷键不是为了把所有功能都背下来，而是减少高频动作的打断感。新手真正会遇到的问题通常有三个：找不到会话/模型/agent 列表，输入多行提示词不顺手，终端、tmux、编辑器和 OpenCode 抢同一个快捷键。

```mermaid
flowchart LR
  Need["高频动作"] --> Leader["保留 leader key"]
  Leader --> Bind["绑定会话 / 模型 / agent / 压缩"]
  Bind --> Conflict["冲突键设为 none"]
  Conflict --> Verify["重启 TUI 验证"]

  style Need fill:#dbeafe,stroke:#3b82f6
  style Conflict fill:#fef3c7,stroke:#f59e0b
  style Verify fill:#dcfce7,stroke:#22c55e,stroke-width:2px
```

配置思路应该是“只改高频和冲突”，不是复制一份完整快捷键表。

## 最小配置

推荐从这几个键开始（按 `keymap.sections` 分组）：

```jsonc title="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"
      },
      "session": {
        "session.compact": "<leader>c"
      },
      "input": {
        "input.newline": ["shift+return", "ctrl+return", "alt+return", "ctrl+j"]
      }
    }
  }
}
```

这段配置覆盖的是高频入口：新会话、会话列表、模型选择、agent 选择、压缩上下文和输入换行。`keymap` 会和内置默认值合并，所以你只需要写自己想改的键，不用复制完整列表。

## leader key 怎么理解

`leader` 是组合快捷键的前缀。默认用 `ctrl+x`，例如 `<leader>n` 就是先按 `ctrl+x`，再按 `n`。

建议保留一个前导键，而不是把所有动作都绑定成单键。终端、Shell、编辑器、tmux 都会占用快捷键，前导键可以降低冲突。

## 禁用冲突键

如果某个快捷键和你的终端或编辑器冲突，把它设为 `"none"`：

```jsonc title="tui.json"
{
  "$schema": "https://opencode.ai/tui.json",
  "keymap": {
    "sections": {
      "session": {
        "session.compact": "none"
      }
    }
  }
}
```

不要为了“完整”复制官方全量 keymap。完整配置会让你以后看不出自己到底改了什么。

## 输入区常用键

桌面版提示词输入框支持常见 Readline / Emacs 风格快捷键，这部分通常不用配置：

- `ctrl+a`：移动到当前行开头。
- `ctrl+e`：移动到当前行末尾。
- `ctrl+b` / `ctrl+f`：向左 / 向右移动一个字符。
- `alt+b` / `alt+f`：向左 / 向右移动一个单词。
- `ctrl+k`：删除到行尾。
- `ctrl+u`：删除到行首。
- `ctrl+w`：删除前一个单词。

这些键和 Shell 输入习惯一致。先熟悉它们，通常比改一大份快捷键配置更有收益。

## `Shift+Enter` 不能换行怎么办

如果 `Shift+Enter` 不能换行，问题通常不在 OpenCode，而在终端没有发送带修饰键的 Enter 序列。

Windows Terminal 需要在 `settings.json` 里给 `shift+enter` 绑定 `sendInput`，输入值是 `\u001b[13;2u`。改完后重启终端或新开一个标签页再测试。

macOS 常见终端通常不需要额外配置；如果遇到冲突，优先检查终端自己的快捷键设置。

## 怎么判断配置有效

改完 `tui.json` 后，重启 OpenCode 或重新打开 TUI，再验证：

- `<leader>n`（即 `ctrl+x` 然后 `n`）能创建新会话。
- `<leader>m` 能打开模型选择。
- `<leader>a` 能打开 agent 选择。
- `<leader>c` 能压缩上下文，或按你的设置被禁用。
- `Tab` 能在主代理之间切换（默认绑 `agent.cycle`，是 03 篇 Plan/Build 切换的底层机制）。
- 提示词输入区能按预期换行和提交。

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

## 接下来去哪

<Cards>
  <Card title="TUI 工作流" description="把快捷键放回 TUI 的 `@`、`!`、`/`、会话和模型切换流程里理解。" href="/docs/opencode/official/00-getting-started/tui" />
  <Card title="切换主题" description="快捷键之外，主题和 diff 样式也会影响长期使用体验。" href="/docs/opencode/official/01-customization/themes" />
  <Card title="配置 OpenCode" description="区分 `tui.json` 和 `opencode.json`，避免把体验偏好和运行配置混在一起。" href="/docs/opencode/official/01-customization/config" />
  <Card title="终端工作流" description="从真实日常任务角度理解什么时候需要快捷键，什么时候用命令更清楚。" href="/docs/opencode/understanding/03-terminal-workflow" />
</Cards>

## 官方资料

- OpenCode Keybinds：[https://opencode.ai/docs/keybinds](https://opencode.ai/docs/keybinds)
- OpenCode TUI：[https://opencode.ai/docs/tui](https://opencode.ai/docs/tui)
