自訂鍵盤快捷鍵

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

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

配置檔案

快捷鍵配置檔案是一個包含 bindings 陣列的物件。每個區塊指定一個上下文和一個按鍵組合到動作的對應。

此範例在聊天上下文中將 Ctrl+E 繫結到開啟外部編輯器，並取消繫結 Ctrl+U：

{
  "$schema": "https://www.schemastore.org/claude-code-keybindings.json",
  "$docs": "https://code.claude.com/docs/zh-TW/keybindings",
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+e": "chat:externalEditor",
        "ctrl+u": 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 之前，confirm:toggleExplanation 動作（預設繫結到 Ctrl+E）在 Bash 和 PowerShell 權限提示上顯示模型產生的命令說明。

權限動作

在 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 上下文中可用的動作：

附件動作

在 Attachments 上下文中可用的動作：

頁尾動作

在 Footer 上下文中可用的動作：

訊息選擇器動作

在 MessageSelector 上下文中可用的動作：

Diff 動作

在 DiffDialog 上下文中可用的動作：

差異詳細資訊檢視也會將分頁器風格的按鍵繫結到標準滾動動作。這些繫結是 DiffDialog 上下文的一部分，僅適用於詳細資訊檢視；滾動動作下列出的 Scroll 上下文預設值保持不變。

Diff 面板動作

用於 /diff 在全螢幕渲染中開啟的 diff 面板 的動作。app:cycleDiffBase 在 DiffPanel 上下文中，在面板開啟時有效；其他的在 Global 中。面板需要 Claude Code v2.1.260 或更新版本。

模型選擇器動作

在 ModelPicker 上下文中可用的動作：

努力滑桿動作

在 EffortSlider 上下文中可用的動作，當您執行不帶引數的 /effort 時開啟的滑桿。滑桿的 Left、Right、Enter 和 Escape 按鍵無法重新繫結。

選擇動作

在 Select 上下文中可用的動作：

Claude Code 在 /skills 選單中套用您的 select:pageUp、select:pageDown、select:first 和 select:last 繫結。在大多數其他清單中，例如 /model 選擇器，Claude Code 使用 PageUp 和 PageDown 進行分頁，無論您的繫結如何，並忽略 Home 和 End。

Plugin 動作

在 Plugin 上下文中可用的動作：

設定動作

在 Settings 上下文中可用的動作。select:accept 和 confirm:no 動作會從選擇和確認上下文中重複使用，具有設定特定的行為：變更會在您變更時立即套用到每個設定，因此 Escape 會關閉面板並儲存您的變更，而不是拒絕。

代理動作

在 Agents 上下文中可用的動作，適用於代理檢視，使用 claude agents 開啟。需要 v2.1.257 或更新版本。

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

分派輸入的外部編輯器快捷鍵不是 Agents 動作。代理檢視遵循 Chat 上下文的 chat:externalEditor 繫結，預設為 Ctrl+G。

繫結在代理檢視中的單鍵擊上觸發，因此繫結到 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

在 v2.1.247 之前，在使用 Kitty 鍵盤協議的終端機（例如 Ghostty、Kitty、WezTerm 和 iTerm2）中，在非拉丁配置下按下 Ctrl 快捷鍵不會觸發其繫結。

和弦

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

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 tab，Task 中的 ctrl+x ctrl+b，以及 DiffPanel 中的 ctrl+x b。ctrl+x enter 和弦需要 v2.1.247 或更新版本，而 ctrl+x b、ctrl+x ctrl+a 和 ctrl+x tab 需要 v2.1.260 或更新版本。若要將 ctrl+x 本身回收為單一鍵繫結，請取消繫結所有這些：

{
  "bindings": [
    {
      "context": "Task",
      "bindings": {
        "ctrl+x ctrl+b": null
      }
    },
    {
      "context": "DiffPanel",
      "bindings": {
        "ctrl+x b": 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 tab": null,
        "ctrl+x": "chat:newline"
      }
    }
  ]
}

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

保留的快捷鍵

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

終端機衝突

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

Vim 模式互動

啟用 vim 模式時（透過 /config → 編輯器模式），快捷鍵和 vim 模式獨立運作：

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

驗證

Claude Code 驗證您的快捷鍵並顯示以下警告：

• 解析錯誤（無效的 JSON 或結構）
• 無效的上下文名稱
• 無效的動作值，例如不是字串或 null 的動作
• 未知的動作名稱，例如已註冊動作的拼寫錯誤。Claude Code 會跳過該繫結並保持該按鍵的任何預設繫結有效。在 v2.1.246 之前，具有未知動作名稱的繫結會無聲地停用該按鍵
• 保留快捷鍵衝突
• 同一上下文中的重複繫結

Claude Code 在檔案載入時報告警告，並將每個警告寫入偵錯日誌。使用 --debug 啟動 Claude Code 以查看詳細資訊。