---
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="/zh-Hant/docs/opencode/official/00-getting-started/tui" />
  <Card title="切換主題" description="快捷鍵之外，主題和 diff 樣式也會影響長期使用體驗。" href="/zh-Hant/docs/opencode/official/01-customization/themes" />
  <Card title="配置 OpenCode" description="區分 `tui.json` 和 `opencode.json`，避免把體驗偏好和執行配置混在一起。" href="/zh-Hant/docs/opencode/official/01-customization/config" />
  <Card title="終端工作流" description="從真實日常任務角度理解什麼時候需要快捷鍵，什麼時候用命令更清楚。" href="/zh-Hant/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)
