SpyBara
Go Premium

code-mode.md 2026-11-12 23:02 UTC to 2026-11-13 23:02 UTC

This page contains 224 additions and 0 deletions.

2026
Fri 13 23:02

使用 Code Mode 從程式碼執行工具呼叫

試用 Code Mode，這是一項實驗性功能，Claude 會在其中撰寫 JavaScript，在一個步驟中進行多個工具呼叫。

Code Mode 會改變 Claude 使用其工具的方式。未啟用 Code Mode 時，Claude 會直接請求 Bash、Read 或 Edit 等工具呼叫，並在決定下一步之前讀取每個結果。啟用 Code Mode 後，Claude 會撰寫一段進行工具呼叫的 JavaScript，並由 Claude Code 在您的工作階段中執行該程式碼。

[!NOTE]

Code Mode 為實驗性功能，預設為關閉。它可能會在任何版本中變更或移除。如需分享意見回饋，請執行 /feedback。

Code Mode 的運作方式

在 Code Mode 工作階段中，您仍然在提示詞中描述您的任務，而 Claude 會撰寫 JavaScript 來執行它。一段程式碼可以平行執行命令、在下一次呼叫中使用某個結果，並傳回 Claude 需要讀取的那部分輸出。

例如，如果您請 Claude 提高重試上限，Claude 可能會撰寫以下程式碼來尋找檔案、編輯檔案並執行測試。最後一行會將檔案路徑和測試輸出傳回給 Claude：

const files = await $`rg -l "function retryPolicy" src`.text();
const target = files.trim().split("\n")[0];
await edit(target, "maxAttempts: 3", "maxAttempts: 5");
({ edited: target, tests: $`npm test -- retryPolicy`.nothrow() });

在對話中，您會看到工具呼叫（例如編輯的差異），而不是程式碼。若要讀取程式碼，請按 Ctrl+O 開啟逐字稿檢視器。每段程式碼都會在其中顯示為收合的 Code 列，並附有如何展開的提示。

何時使用 Code Mode

請在需要許多相關工具呼叫的任務上試用 Code Mode，例如：

  • 在許多檔案中重複進行的變更
  • 在 Claude 讀取結果之前需要先篩選結果的搜尋
  • 可以同時執行的數個獨立命令

Code Mode 的限制

在開啟 Code Mode 之前，請確認您可以接受以下限制：

需求

  • 版本：Claude Code v2.1.323 或更新版本，任一發布通道皆可。較舊的版本啟動時不會啟用 Code Mode，可能會也可能不會顯示原因 it isn't open to your account yet
  • 帳戶：Claude 訂閱或 Console 帳戶。您無法透過閘道、Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 或 Microsoft Foundry 使用 Code Mode
  • 組織：您的組織未使用 HIPAA 設定，也未使用零資料保留
  • 模型：Claude Opus 5.5、Sonnet 5.5、Haiku 5.5 或 Fable 5.2
  • 使用介面：在終端機中的互動式 claude 工作階段。Code Mode 無法搭配 -p、Agent SDK、VS Code 面板、Desktop 應用程式或雲端工作階段使用
  • 安裝：Claude Code 的原生建置
  • Windows：已安裝 Git for Windows

在開啟某些設定的情況下，您也無法啟動 Code Mode，例如 API 金鑰輔助程式、agent team、OpenTelemetry 匯出或 DISABLE_TELEMETRY。各項的修正方式請參閱 Code Mode 無法啟動。

試用 Code Mode

開啟 Code Mode，交給 Claude 一項任務，然後查看 Claude 撰寫的程式碼。

1. 檢查您的版本

執行 claude --version。如果版本早於 v2.1.323，請執行 claude update。如果您使用的是 stable 通道，且更新後未達到 v2.1.323，請等待 stable 跟上，或切換至 latest。

2. 在開啟 Code Mode 的情況下啟動 Claude Code

將 CLAUDE_CODE_EXPERIMENTAL_CODE_MODE 環境變數設為 1。若要試用 Code Mode，請在您的 shell 中設定。若要為每個新的工作階段開啟 Code Mode，請在您的使用者設定中設定。

[tab] macOS, Linux, WSL

CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude

[tab] Windows PowerShell

$env:CLAUDE_CODE_EXPERIMENTAL_CODE_MODE = "1"
claude

[tab] settings.json

將此 env 區塊儲存在 ~/.claude/settings.json 中，然後啟動 claude：

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "1"
  }
}

Claude Code 會忽略專案設定檔中的此變數，因此您複製的儲存庫無法替您開啟 Code Mode。

3. 確認您要使用 Code Mode

在您的第一個 Code Mode 工作階段之前，Claude Code 會請您確認。請選取 Yes, turn on Code Mode。Claude Code 會重新啟動，並在工作階段頂端附近顯示這一行：

Code Mode (experimental) is on · this session can be resumed only with Code Mode on

如果您看到不同的一行或沒有看到任何一行，請參閱 Code Mode 無法啟動。

4. 交給 Claude 一項需要許多工具呼叫的任務

在您熟悉的專案中，傳送如下的提示詞：

Read every Markdown file in this project and list the links that point to local files that don't exist.

5. 閱讀 Claude 撰寫的程式碼

按 Ctrl+O 並展開 Code 列，即可查看工具呼叫背後的 JavaScript。再按一次 Ctrl+O 即可返回對話。

[!WARNING]

若要在之後繼續 Code Mode 工作階段，請在執行 claude --continue 或 claude --resume 時，讓 CLAUDE_CODE_EXPERIMENTAL_CODE_MODE 維持設為 1。在 Code Mode 關閉的情況下，Claude Code 會拒絕繼續該工作階段。您在未啟用 Code Mode 時啟動的工作階段，即使設定了該變數，也會在未啟用 Code Mode 的情況下繼續。

關閉 Code Mode

從您的 shell 和 ~/.claude/settings.json 中移除 CLAUDE_CODE_EXPERIMENTAL_CODE_MODE，然後啟動新的工作階段。您也可以保留該變數，並在任一處將其值改為 0。只要其中一處為 0，即使您在另一處設定了 1，Code Mode 仍會保持關閉。

為您的組織封鎖 Code Mode

將值為 0 的 CLAUDE_CODE_EXPERIMENTAL_CODE_MODE 加入您的受管設定，讓您組織中的任何人都無法使用 Code Mode：

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "0"
  }
}

正處於 Code Mode 工作階段中的使用者會留在其中，直到他們結束或重新啟動 Claude Code。之後，您的使用者在啟動時不會啟用 Code Mode，且在 0 生效期間無法繼續他們的 Code Mode 工作階段。您無法從受管設定為您的使用者開啟 Code Mode。

權限與長時間執行的程式碼

您的權限模式決定了 Claude 的程式碼如何接受檢查，以及在程式碼執行期間您是否能與 Claude 交談。

權限檢查

Claude 的程式碼所進行的每個工具呼叫，都會經過您的 deny 和 ask 權限規則以及您的 PreToolUse hook。您不需要為 Bash 等工具變更規則或 matcher。除了規則和 hook 之外，在自動模式下會由分類器審查程式碼，而在會詢問的模式下則由您回應權限提示：

  • 自動模式：分類器會在每段程式碼執行前審查該段程式碼，而不是審查每個工具呼叫。它看不到在執行時計算出的值，例如取自搜尋輸出的路徑，因此對於您必須控管的呼叫，請保留規則或 hook。在先前的程式碼執行期間有新的程式碼啟動時，您仍可能收到權限提示
  • 其他權限模式：程式碼會在未經審查的情況下啟動，而對於在該模式下會提示您的每個工具呼叫，您都會收到權限提示

若要檢查程式碼本身，請撰寫一個比對 REPL（執行 Claude 程式碼的工具）的 PreToolUse hook，並從 tool_input.code 讀取 JavaScript。

[!WARNING]

Bash 規則比對的是命令文字，因此無論是否啟用 Code Mode，Claude 都可能以規則無法比對到的形式執行被拒絕的命令。如需不依賴命令文字的限制，請參閱沙箱機制。

長時間執行的程式碼

當程式碼執行長時間的建置或測試時，Claude 會等待它，或讓它在背景繼續執行：

  • 等待：Claude 會在程式碼完成後回覆，且程式碼會在十分鐘後停止，其中包括您在權限提示上花費的時間
  • 背景：您可以繼續與 Claude 交談，且程式碼最多可執行兩小時

若要讓程式碼在背景執行，請以自動或 bypassPermissions 模式啟動您的工作階段。如果 Claude 仍然等待，請檢查您目前的模式以及您啟動工作階段的方式：

  • 您切換到了其他模式：按 Shift+Tab，直到回到您啟動時的模式
  • 您以其他模式啟動，或從 claude --resume 清單中選取了工作階段：如果您可以使用自動模式，請結束，然後在 Code Mode 開啟的情況下執行 claude --continue --permission-mode auto
  • 您將工具名稱傳給了 --tools：以自動模式重新啟動，且不使用該旗標

疑難排解

Code Mode 無法啟動

工作階段頂端附近出現 Code Mode (experimental) isn't available，表示 Claude Code 啟動時未啟用 Code Mode。原因會接在同一行後面，/status 也會顯示。請在此表中找到原因，進行變更，然後啟動新的工作階段。如果原因未列在表中，請檢查需求。

原因包含 處理方式
it isn't open to your account yet 如果您的版本早於 v2.1.323，請更新。否則，請檢查您的網路連線並重新啟動。如果原因仍然存在，請改天再試
it only works with the Anthropic API 移除透過雲端供應商、閘道或自訂 ANTHROPIC_BASE_URL 轉送請求的設定
it doesn't work with an API key helper 移除 apiKeyHelper、ANTHROPIC_AUTH_TOKEN，以及 ANTHROPIC_CUSTOM_HEADERS 中的任何 Authorization 或 X-Api-Key 標頭。然後登入或設定 ANTHROPIC_API_KEY
it only works with Opus 5.5, Sonnet 5.5 and later models 使用支援的模型啟動，例如使用 --model opus。Haiku 5.5 和 Fable 5.2 也可使用
it doesn't work in background jobs 在前景啟動，且不使用 --remote-control
it needs settings that Claude Code downloads from Anthropic 取消設定會關閉功能旗標擷取的變數，例如 DISABLE_TELEMETRY
OpenTelemetry is on 如果您可以不使用 OpenTelemetry 匯出，請取消設定 CLAUDE_CODE_ENABLE_TELEMETRY 和 ENABLE_BETA_TRACING_DETAILED
it doesn't yet work with an installed mod 關閉會檢查工具呼叫的 mod
it can't be used together with agent teams yet 取消設定 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS
this launch's tool options 不使用 --restricted 啟動，將 REPL 加入 --tools，並從 --disallowedTools 和您的 deny 規則中移除 REPL
couldn't save your answer 讓 ~/.claude.json 可寫入
your organization's settings don't allow it 向您的管理員詢問相關的受管設定

如果您沒有看到任何關於 Code Mode 的行，請執行 claude --version。如果您的版本早於 v2.1.323，請更新。接著確認您的 shell 或使用者設定中的 CLAUDE_CODE_EXPERIMENTAL_CODE_MODE 為 1，並從這些位置以及任何 --settings 檔案中移除所有 0。

附有倒數計時的權限提示

在自動模式下，當先前的程式碼仍在執行時 Claude 又啟動了更多程式碼，先前的程式碼就會失去分類器審查。Claude Code 接著會針對先前程式碼中需要審查的剩餘呼叫詢問您。在未連接 IDE 的情況下，權限提示會顯示倒數計時：

Claude Code will automatically block this request in 1:59, to avoid holding up an unattended session

請在倒數計時結束前回應。否則該呼叫會被拒絕，且之後會顯示倒數計時的呼叫會在不提示的情況下被拒絕。若要再次看到權限提示，請傳送訊息給 Claude。

工具呼叫被 hook 拒絕

如果 Claude 回報工具呼叫被拒絕，請向它詢問錯誤文字。以下錯誤表示 PreToolUse hook 未提供決定，即使未設定 onFailure，這也會拒絕該呼叫：

  • the hook failed：在來自 Claude 程式碼的呼叫上，您的 hook 無法啟動、被終止、以 126、127 或大於 128 的代碼結束，或傳回 HTTP 錯誤或無效輸出。請修正該 hook
  • the hook did not finish：您的 hook 在來自 Claude 程式碼的呼叫上逾時，或在 Claude 於工作階段中執行過程式碼後，於任何其他工具呼叫上逾時。請提高該 hook 的 timeout

若要在 command 或 http hook 失敗或逾時時讓呼叫繼續進行，請在該 hook 上設定 "onFailure": "continue"。如果 command hook 以 1 之類的一般代碼結束，除非您設定了 "onFailure": "block"，否則該呼叫會繼續進行。

程式碼輸出被 hook 攔截

如果 Claude 在您預期看到 Claude 程式碼輸出的地方回報了 hook 的阻擋原因，請檢查您的 UserPromptSubmit hook。當程式碼可以在背景執行時，該事件上的 command、http 和 mcp_tool hook 也會在程式碼輸出上執行。若要讓輸出通過，請變更該 hook，使其在輸入中的 source 為 poll_event 時不進行阻擋。

相關資源