自訂鍵盤快捷鍵

使用快捷鍵配置檔案在 Claude Code 中自訂鍵盤快捷鍵。

Claude Code 支援可自訂的鍵盤快捷鍵。執行 /keybindings 以在 ~/.claude/keybindings.json 建立或開啟您的配置檔案。

設定檔

快捷鍵設定檔是一個包含 bindings 陣列的物件。每個區塊指定一個情境，以及按鍵與動作之間的對應。

[!NOTE]

對快捷鍵檔案所做的變更會自動偵測並套用，無需重新啟動 Claude Code。

此範例將 Ctrl+E 綁定為在聊天情境中開啟外部編輯器，並解除 Ctrl+S 的綁定：

{
  "$schema": "https://www.schemastore.org/claude-code-keybindings.json",
  "$docs": "https://code.claude.com/docs/en/keybindings",
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+e": "chat:externalEditor",
        "ctrl+s": null
      }
    }
  ]
}

上下文

每個繫結區塊都指定一個上下文，其中繫結適用：

在 v2.1.205 之前，/doctor 診斷畫面存在 Doctor 上下文和 doctor:fix 動作。

可用動作

動作採用 namespace:action 格式，例如 chat:submit 用於傳送訊息，app:toggleTodos 用於顯示任務清單。每個情境都有其特定的可用動作。

應用程式動作

在 Global 情境中可用的動作：

歷史記錄動作

用於瀏覽命令歷史記錄的動作：

聊天動作

在 Chat 情境中可用的動作：

*在未啟用 VT 模式的 Windows 上（Node <24.2.0/<22.17.0、Bun <1.2.23），預設為 Meta+M。

自動完成動作

在 Autocomplete 情境中可用的動作：

確認動作

在 Confirmation 情境中可用的動作：

*在未啟用 VT 模式的 Windows 上（Node <24.2.0/<22.17.0、Bun <1.2.23），預設為 Meta+M。

在 v2.1.257 之前，有一個預設繫結至 Ctrl+E 的 confirm:toggleExplanation 動作，會在 Bash 和 PowerShell 權限提示上顯示由模型產生的命令說明。

對話框使用 confirm:yes 和 confirm:no 來接受與取消，即使對話框並未提出是非問題也是如此。如果您在此情境中繫結單一字母（例如 y 或 n），該字母也會作用於從未將其顯示為按鍵的對話框。將 y 和 n 顯示為按鍵的對話框會自行讀取這些字母，不需要繫結。

在大多數對話框中，按兩次 Ctrl+C 或 Ctrl+D 會關閉對話框，而不是結束 Claude Code。第一次按下後的提示會說明第二次按下是關閉對話框還是結束。這兩個按鍵都是保留的，無法重新繫結。

此範例將 y 繫結至 confirm:yes，將 n 繫結至 confirm:no：

{
  "bindings": [
    {
      "context": "Confirmation",
      "bindings": {
        "y": "confirm:yes",
        "n": "confirm:no"
      }
    }
  ]
}

使用這些繫結時，當文字欄位取得焦點時，y 和 n 仍會以字母形式輸入。

在 v2.1.280 之前，y 預設也繫結至 confirm:yes，n 則繫結至 confirm:no。如果您在 v2.1.280 之前使用 /keybindings 建立了 keybindings.json，該檔案會列出這兩個繫結，且在您刪除這兩行之前它們會持續生效。

權限動作

在 Confirmation 情境中可用於權限對話框的動作：

逐字稿動作

在 Transcript 情境中可用的動作：

transcript:toggleShowAll 僅適用於傳統渲染器；在全螢幕渲染中，逐字稿檢視器不提供顯示全部的切換功能。

歷史記錄搜尋動作

在 HistorySearch 情境中可用的動作：

historySearch:next、historySearch:accept、historySearch:cancel 和 historySearch:execute 的預設值適用於傳統渲染器中的行內歷史記錄搜尋，該搜尋一律會搜尋所有專案的提示詞。historySearch:cycleScope 僅在全螢幕渲染中生效，在此模式下 Ctrl+R 會改為開啟搜尋對話框，而 Ctrl+S 會循環切換其範圍。該對話框的其他按鍵是固定的，無法重新繫結：Enter 或 Tab 會將醒目提示的符合項目放入提示詞輸入中，Esc 則會取消。

任務動作

在 Task 情境中可用的動作：

主題動作

在 ThemePicker 情境中可用的動作：

說明動作

在 Help 情境中可用的動作：

分頁動作

在 Tabs 情境中可用的動作：

在含有分頁的對話框中，當分頁列取得焦點時，tabs:next 和 tabs:previous 會切換分頁。在某些對話框中（例如 /help 和 /sandbox），分頁切換按鍵在分頁內容中也能運作。

Up 和 Down 會在分頁列與分頁內容之間移動焦點，而內容中的清單只有在取得焦點時才會回應按鍵。

附件動作

在 Attachments 情境中可用的動作：

頁尾動作

在 Footer 情境中可用的動作：

當選取了頁尾項目（例如提示詞下方 agent 面板中的某一列）時，即使您在 Chat 情境中將 Enter 重新繫結至 chat:queueSubmit 或 chat:newline，Enter 仍會開啟該項目。

Footer 情境未繫結之按鍵上的 Chat 繫結（例如用於 chat:cycleMode 的 Shift+Tab），在選取項目時仍會繼續運作。

訊息選擇器動作

在倒轉選單的訊息清單中，您可以使用 Select 動作及其預設按鍵來瀏覽訊息並挑選其中一則。您為這些動作設定的 Select 繫結也適用於此處。MessageSelector 情境本身沒有任何動作或預設繫結。您可以使用它來僅針對此清單變更按鍵，方法是在 MessageSelector 區塊中繫結 Select 動作，例如 select:accept。

此範例將 o 繫結為在倒轉選單中挑選醒目提示的訊息，而不變更任何其他清單：

{
  "bindings": [
    {
      "context": "MessageSelector",
      "bindings": {
        "o": "select:accept"
      }
    }
  ]
}

在 v2.1.283 之前，此清單會忽略 Select 繫結，並擁有自己的動作：messageSelector:up、messageSelector:down、messageSelector:top、messageSelector:bottom 和 messageSelector:select。如果您的 keybindings.json 繫結了其中一個名稱，該繫結會在此清單中繼續運作，作為執行相同功能的 Select 動作。Home 和 End 會跳至清單的任一端；在 v2.1.283 之前，預設是由 Shift+K 和 Shift+J 等按鍵執行此功能。

差異動作

這些動作僅作用於 Claude Code 較早期的差異檢視器，也就是在您於 /plugin 中停用 cc-plugin-diff mod 後，/diff 在全螢幕渲染以外開啟的檢視器。當該 mod 啟用時，/diff 會改為開啟差異對話框。

在 DiffDialog 情境中可用的動作：

檔案清單也會透過 Select 動作的預設按鍵和您的 Select 繫結來回應這些動作。select:previous 和 select:next 會移至上一個和下一個檔案，而 Enter 會透過 select:accept 開啟所選檔案的差異。若要僅針對檔案清單變更其中一個按鍵，請在 DiffDialog 區塊中繫結該 Select 動作。

在 v2.1.283 之前，檔案清單會忽略 Select 繫結，而 Enter 是透過獨立的 diff:viewDetails 動作開啟所選檔案的差異。如果您的 keybindings.json 繫結了 diff:viewDetails，該繫結會在檔案清單中繼續作為 select:accept 運作。

差異詳細檢視也將分頁器風格的按鍵繫結至標準的捲動動作。這些繫結屬於 DiffDialog 情境，且僅適用於詳細檢視；捲動動作下列出的 Scroll 情境預設值保持不變。

差異面板動作

用於在全螢幕渲染中由 /diff 開啟之差異面板的動作。app:cycleDiffBase 屬於 DiffPanel 情境，該情境在面板開啟時啟用；其他動作則屬於 Global。

內建的 cc-plugin-diff mod 會繪製此面板，並處理 app:cycleDiffBase、app:diffFileListUp 和 app:diffFileListDown。app:toggleReplTab、app:toggleDiffNoiseFilter 和 app:toggleDiffPreSession 僅作用於 Claude Code 較早期的面板，也就是在您於 /plugin 中停用 cc-plugin-diff 後由 /diff 開啟的面板。

模型選擇器動作

在 ModelPicker 情境中可用的動作：

Effort 滑桿動作

在 EffortSlider 情境中可用的動作，該情境即為您在不帶引數執行 /effort 時開啟的滑桿。滑桿的 Enter 和 Escape 按鍵無法重新繫結。

Select 動作

在 Select 情境中可用的動作：

在 /skills、/mcp 和 /tasks 等清單面板中，Claude Code 會套用您的 select:pageUp、select:pageDown、select:first 和 select:last 繫結。在大多數其他清單中（例如 /model 選擇器），會套用您的 select:first 和 select:last 繫結。無論您的繫結為何，PageUp 和 PageDown 都會在這些清單中翻頁瀏覽選項。

在 v2.1.280 之前，這些其他清單會忽略 Home、End 以及您的 select:first 和 select:last 繫結。

在 v2.1.283 之前，無論您的繫結為何，/mcp 工具清單都使用固定的 PageUp 和 PageDown 按鍵翻頁。

外掛動作

在 Plugin 情境中可用的動作：

提示詞上方動作

用於提示詞上方區帶的動作，該區帶是 mod 繪製按鈕、輸入欄位和選擇框的共用區域。abovePrompt:toggle 和 abovePrompt:focus 適用於 Chat 情境。其他動作則適用於區帶或窗格中目前取得鍵盤焦點之項目的情境。

在 AbovePrompt 情境中，Right 和 Left 預設也會執行 abovePrompt:next 和 abovePrompt:previous，而 Space 也會執行 abovePrompt:press。

AbovePrompt 情境也將 Up、Down、PageUp、PageDown、Home 和 End 繫結至窗格捲動動作 pane:scrollUp 至 pane:bottom，因此若要為區帶變更其中一個按鍵，請在 AbovePrompt 區塊中繫結該捲動動作。

窗格動作

用於由 mod 繪製之窗格的動作。捲動、調整大小和關閉動作適用於 Pane 情境。pane:close 也適用於 PaneField 情境，因此在窗格的某個欄位取得焦點時也能運作。pane:next 和 pane:previous 在開啟多個窗格時適用於 Global 情境。

Pane 情境也將 Tab、Shift+Tab、Enter 和 Escape 繫結至與區帶相同的提示詞上方動作，而窗格的輸入欄位和選擇框則使用 AbovePromptInput 和 AbovePromptSelect 情境。鍵盤焦點與快速鍵列出了每個按鍵在窗格中的作用。

設定動作

在 Settings 情境中可用的動作。select:accept 和 confirm:no 動作沿用自 Select 和 Confirmation 情境，但具有 Settings 特有的行為：每個設定在您變更後會立即套用，因此 Escape 會在儲存您的變更後關閉面板，而非拒絕變更。

Agents 動作

在 Agents 情境中可用的動作，該情境適用於以 claude agents 開啟的 agent 檢視。需要 v2.1.257 或更新版本。

當 agent 檢視開啟時，對於 Agents 情境所繫結的任何按鍵，Claude Code 都會使用 Agents 繫結，並忽略同一按鍵上的 Chat 或 Global 繫結。例如，在 agent 檢視中按下 Ctrl+S 會切換工作階段分組，而不是觸發預設的 chat:stash。

dispatch 輸入的外部編輯器快捷鍵不是 Agents 動作。agent 檢視會遵循 Chat 情境的 chat:externalEditor 繫結，預設為 Ctrl+G。

在 agent 檢視中，繫結會在單一按鍵時觸發，因此繫結至 chat:externalEditor 的 Ctrl+X Ctrl+E 組合鍵不會在該處開啟編輯器。

語音動作

啟用語音聽寫時，在 Chat 情境中可用的動作：

捲動動作

啟用全螢幕渲染時，在 Scroll 情境中可用的動作：

按鍵組合語法

修飾鍵

使用 + 分隔符搭配修飾鍵：

• ctrl 或 control - Control 鍵
• shift - Shift 鍵
• alt、opt、option 或 meta - Windows 和 Linux 上的 Alt 鍵，macOS 上的 Option 鍵
• cmd、command、super 或 win - macOS 上的 Command 鍵，Windows 上的 Windows 鍵，Linux 上的 Super 鍵

cmd 群組只在報告 Super 修飾鍵的終端機中被偵測，例如支援 Kitty 鍵盤協議或 xterm 的 modifyOtherKeys 模式的終端機。大多數終端機不會發送它，因此對於您想在任何地方都能運作的繫結，請使用 ctrl 或 meta。

例如：

ctrl+k          Ctrl + K
shift+tab       Shift + Tab
meta+p          macOS 上的 Option + P，其他地方為 Alt + P
ctrl+shift+c    多個修飾鍵

大寫字母

Claude Code 不區分大小寫地解析按鍵名稱，因此 K 與 k 的繫結相同，ctrl+K 與 ctrl+k 相同。若要繫結 Shift 和一個字母，請寫 shift+k。

非美式鍵盤配置

即使您的作用中鍵盤配置輸入其他字元，也請將 Ctrl 快捷鍵的按鍵名稱寫成拉丁字元。

Claude Code 如何將您按下的按鍵與繫結相符取決於配置的類型：

• 在西里爾字母等非拉丁配置下，當終端機使用 Kitty 鍵盤協議並報告該位置時，Claude Code 會根據按鍵的美式配置位置來符合 Ctrl 快捷鍵。在這樣的終端機中，使用俄文配置時，按下 Ctrl 和實體 W 鍵會觸發 ctrl+w。在不報告位置的終端機中，Claude Code 會符合終端機為按鍵發送的任何內容：ASCII 控制碼會觸發拉丁快捷鍵，而作為西里爾字元到達的按鍵不符合任何繫結
• 在重新排列拉丁字母的配置下，例如 AZERTY，Claude Code 會符合按鍵輸入的字母，因此按下 Ctrl 和標記為 A 的按鍵會觸發 ctrl+a

和弦

和弦是由空格分隔的按鍵組合序列：

ctrl+k ctrl+s   按 Ctrl+K，放開，然後按 Ctrl+S

在每個按鍵組合的 3 秒內按下下一個。如果您等待更長時間，Claude Code 會取消和弦並顯示簡短通知。

特殊鍵

• escape 或 esc - Escape 鍵
• enter 或 return - Enter 鍵
• tab - Tab 鍵
• space - 空格鍵
• up、down、left、right - 方向鍵
• pageup、pagedown - Page Up 和 Page Down 鍵
• home、end - Home 和 End 鍵
• backspace、delete - 刪除鍵
• wheelup、wheeldown - 滑鼠滾輪捲動事件

取消繫結預設快捷鍵

將動作設定為 null 以取消繫結預設快捷鍵：

{
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+s": null
      }
    }
  ]
}

這也適用於和弦繫結。取消繫結共享前綴的每個和弦會釋放該前綴以用作單一鍵繫結。任何作用中的內容中的和弦會保留其前綴的保留狀態，因此您必須在定義該和弦的內容中取消繫結每個和弦。

Claude Code 在 ctrl+x 前綴上繫結這些預設和弦，依內容分列如下：

• Chat：ctrl+x ctrl+k、ctrl+x ctrl+e、ctrl+x enter、ctrl+x ctrl+a、ctrl+x ctrl+s 和 ctrl+x tab
• Task：ctrl+x ctrl+b
• DiffPanel：ctrl+x b
• Pane：ctrl+x left、ctrl+x right、ctrl+x up、ctrl+x down 和 ctrl+x x
• PaneField：ctrl+x x

ctrl+x enter 和弦需要 v2.1.247 或更新版本，ctrl+x b、ctrl+x ctrl+a 和 ctrl+x tab 需要 v2.1.260 或更新版本，而 ctrl+x ctrl+s 需要 v2.1.275 或更新版本。

若要將 ctrl+x 本身回收為單一鍵繫結，請取消繫結所有這些：

{
  "bindings": [
    {
      "context": "Task",
      "bindings": {
        "ctrl+x ctrl+b": null
      }
    },
    {
      "context": "DiffPanel",
      "bindings": {
        "ctrl+x b": null
      }
    },
    {
      "context": "Pane",
      "bindings": {
        "ctrl+x left": null,
        "ctrl+x right": null,
        "ctrl+x up": null,
        "ctrl+x down": null,
        "ctrl+x x": null
      }
    },
    {
      "context": "PaneField",
      "bindings": {
        "ctrl+x x": null
      }
    },
    {
      "context": "Chat",
      "bindings": {
        "ctrl+x ctrl+k": null,
        "ctrl+x ctrl+e": null,
        "ctrl+x enter": null,
        "ctrl+x ctrl+a": null,
        "ctrl+x ctrl+s": null,
        "ctrl+x tab": null,
        "ctrl+x": "chat:newline"
      }
    }
  ]
}

如果您取消繫結前綴上的某些但不是全部和弦，按下前綴仍會進入和弦等待模式以進行剩餘的繫結。

保留的快捷鍵

這些快捷鍵無法重新繫結：

終端機衝突

某些快捷鍵可能與終端機多工器衝突：

文字欄位

如果你綁定一個裸露的字母、數字或空格鍵，你仍然可以在對話框或面板內的文字欄位中輸入該字元。其中一個欄位是 Claude 提出問題時的 Other 答案。當欄位獲得焦點時，你按下的可列印鍵（不含 Ctrl、Alt 或 Cmd）會進入該欄位，Claude Code 不會根據你的綁定來匹配它。

這些鍵在欄位獲得焦點時仍會執行其綁定：

• 不輸入字元的鍵，例如 Enter、Escape、Tab 和方向鍵
• 任何使用 Ctrl、Alt 或 Cmd 按下的鍵
• 已在進行中的和弦的第二個按鍵

在主提示符處，Claude Code 根據作用中的內容（例如 Chat）來匹配每個鍵，只有在沒有綁定取用該鍵時才會輸入該鍵。

Vim 模式互動

當您透過 /config 中的編輯器模式設定啟用 vim 模式時，快捷鍵和 vim 模式會獨立運作：

• Vim 模式在文字輸入層級處理輸入：游標移動、模式和動作
• 快捷鍵在元件層級處理動作，例如切換待辦事項或提交訊息
• 在 vim 模式中，Escape 鍵會將 INSERT 模式切換為 NORMAL 模式；它不會觸發 chat:cancel
• 大多數 Ctrl+鍵快捷鍵通過 vim 模式傳遞到快捷鍵系統
• Vim 鍵無法透過快捷鍵檔案重新對應。若要對應兩鍵 INSERT 模式序列（例如 jj）至 Escape，請使用 vimInsertModeRemaps 設定
• 在 vim NORMAL 模式中，? 顯示說明選單（vim 行為）
• 在 vim NORMAL 模式中，/ 開啟歷史搜尋，與標準模式中的 Ctrl+R 相同

在 Claude 提出的問題的 Other 列中，vim 模式下的 Escape 不會立即取消該問題。除了在螢幕閱讀器模式中以外，每次您將焦點移至該列時，該列都會從 INSERT 模式開始。當您在 Other 列中按下 Escape 時，該列會切換到 NORMAL 模式或捨棄輸入到一半的 vim 命令，而問題仍會保持開啟。在 NORMAL 模式中再按一次 Escape 即可取消該問題。

按一個鍵取消問題

若要在 vim 模式中按一個鍵即取消問題，請在 Select 情境中將另一個鍵綁定至 select:cancel。您可以在只能選擇一個選項的問題的 Other 列中以此方式取消。在螢幕閱讀器模式中，或在可選擇多個選項的問題中，綁定的鍵不會取消問題，因此請改用 Escape 取消。

請選擇搭配 Ctrl 或 Alt 按下的鍵。單獨的字母或數字會改為輸入至 Other 列，而不會觸發您的綁定。例如，若要綁定 Ctrl+Q，請將以下內容新增至 ~/.claude/keybindings.json：

{
  "bindings": [
    {
      "context": "Select",
      "bindings": {
        "ctrl+q": "select:cancel"
      }
    }
  ]
}

儲存檔案後，在只能選擇一個選項的問題的 Other 列中按下 Ctrl+Q。無論該列處於 INSERT 或 NORMAL 模式，問題都會關閉。

驗證

Claude Code 驗證您的快捷鍵並為以下項目寫入警告到偵錯日誌：

• 解析錯誤（無效的 JSON 或結構）
• 拼寫錯誤的修飾鍵，例如 ctl+k。Claude Code 會捨棄它無法識別的部分，並將繫結應用於剩餘的按鍵，在此範例中為 k。
• 按鍵字串中 + 旁邊有空格，例如 ctrl+ k。Claude Code 會將該字串解讀為由 ctrl+ 後接 k 組成的組合鍵。沒有任何按鍵會單獨符合 ctrl+，因此該繫結永遠不會觸發。請移除該空格。
• 無效的上下文名稱
• 無效的動作值，例如不是字串或 null 的動作
• 未知的動作名稱，例如已註冊動作的拼寫錯誤。Claude Code 會跳過該繫結並保持該按鍵的任何預設繫結有效。
• 保留快捷鍵衝突
• 同一上下文中的重複繫結

使用 --debug 啟動 Claude Code 以查看詳細資訊。