> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

Code Mode 會改變 Claude 使用其[工具](https://code.claude.com/docs/zh-TW/tools-reference.md)的方式。未啟用 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：

```javascript theme={null}
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` 開啟[逐字稿檢視器](https://code.claude.com/docs/zh-TW/interactive-mode.md#transcript-viewer)。每段程式碼都會在其中顯示為收合的 **Code** 列，並附有如何展開的提示。

### 何時使用 Code Mode

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

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

### Code Mode 的限制

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

* **繼續工作階段**：您只能在終端機中、且在 Code Mode 開啟的情況下繼續 Code Mode 工作階段
* **自動模式**：自動模式的分類器會[審查程式碼，而非每個工具呼叫](#permission-checks)
* **長時間執行的程式碼**：除非[程式碼可以在背景執行](#long-running-code)，否則您需要等待它完成，且它會在十分鐘後停止
* **Hook**：當 `PreToolUse` hook 無法執行或逾時時，您可能會看到[工具呼叫被拒絕](#tool-call-refused-by-a-hook)，也可能會看到[程式碼輸出被 `UserPromptSubmit` hook 阻擋](#code-output-withheld-by-a-hook)
* **無法使用的功能**：您無法使用 [Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md)、[Claude in Chrome](https://code.claude.com/docs/zh-TW/chrome.md) 或[電腦操作](https://code.claude.com/docs/zh-TW/computer-use.md)
* **移動工作階段**：您無法將工作階段移至 Desktop 應用程式或將其轉為[背景工作階段](https://code.claude.com/docs/zh-TW/agent-view.md)，且 `/fork` 無法啟動背景副本

## 需求

* **版本**：Claude Code v2.1.323 或更新版本，任一[發布通道](https://code.claude.com/docs/zh-TW/setup.md#configure-release-channel)皆可。較舊的版本啟動時不會啟用 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 設定](https://code.claude.com/docs/zh-TW/hipaa-setup.md)，也未使用[零資料保留](https://code.claude.com/docs/zh-TW/zero-data-retention.md)
* **模型**：Claude Opus 5.5、Sonnet 5.5、Haiku 5.5 或 Fable 5.2
* **使用介面**：在終端機中的互動式 `claude` 工作階段。Code Mode 無法搭配 `-p`、Agent SDK、VS Code 面板、Desktop 應用程式或雲端工作階段使用
* **安裝**：Claude Code 的[原生建置](https://code.claude.com/docs/zh-TW/setup.md)
* **Windows**：已安裝 [Git for Windows](https://git-scm.com/downloads/win)

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

## 試用 Code Mode

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

**1. 檢查您的版本**

執行 `claude --version`。如果版本早於 v2.1.323，請執行 `claude update`。如果您使用的是 `stable` 通道，且更新後未達到 v2.1.323，請等待 `stable` 跟上，或[切換至 `latest`](https://code.claude.com/docs/zh-TW/setup#configure-release-channel)。

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

將 [`CLAUDE_CODE_EXPERIMENTAL_CODE_MODE`](https://code.claude.com/docs/zh-TW/env-vars#variables) 環境變數設為 `1`。若要試用 Code Mode，請在您的 shell 中設定。若要為每個新的工作階段開啟 Code Mode，請在您的使用者設定中設定。

> [tab] macOS, Linux, WSL
>
> ```bash theme={null}
> CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude
> ```

> [tab] Windows PowerShell
>
> ```powershell theme={null}
> $env:CLAUDE_CODE_EXPERIMENTAL_CODE_MODE = "1"
> claude
> ```

> [tab] settings.json
>
> 將此 `env` 區塊儲存在 `~/.claude/settings.json` 中，然後啟動 `claude`：
>
> ```json theme={null}
> {
>   "env": {
>     "CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "1"
>   }
> }
> ```
>
> Claude Code [會忽略專案設定檔中的此變數](https://code.claude.com/docs/zh-TW/settings-reference.md#variables-claude-code-ignores-in-env)，因此您複製的儲存庫無法替您開啟 Code Mode。

**3. 確認您要使用 Code Mode**

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

```text theme={null}
Code Mode (experimental) is on · this session can be resumed only with Code Mode on
```

如果您看到不同的一行或沒有看到任何一行，請參閱 [Code Mode 無法啟動](#code-mode-doesnt-start)。

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

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

```text theme={null}
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` 加入您的[受管設定](https://code.claude.com/docs/zh-TW/managed-settings.md)，讓您組織中的任何人都無法使用 Code Mode：

```json theme={null}
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "0"
  }
}
```

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

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

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

### 權限檢查

Claude 的程式碼所進行的每個工具呼叫，都會經過您的 `deny` 和 `ask` [權限規則](https://code.claude.com/docs/zh-TW/permissions.md)以及您的 [`PreToolUse` hook](https://code.claude.com/docs/zh-TW/hooks#pretooluse)。您不需要為 `Bash` 等工具變更規則或 matcher。除了規則和 hook 之外，在自動模式下會由分類器審查程式碼，而在會詢問的模式下則由您回應權限提示：

* **[自動模式](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode)**：分類器會在每段程式碼執行前審查該段程式碼，而不是審查每個工具呼叫。它看不到在執行時計算出的值，例如取自搜尋輸出的路徑，因此對於您必須控管的呼叫，請保留規則或 hook。[在先前的程式碼執行期間有新的程式碼啟動時](#permission-prompt-with-a-countdown)，您仍可能收到權限提示
* **其他[權限模式](https://code.claude.com/docs/zh-TW/permission-modes.md)**：程式碼會在未經審查的情況下啟動，而對於在該模式下會提示您的每個工具呼叫，您都會收到權限提示

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

> [!WARNING]
>
> Bash 規則比對的是命令文字，因此無論是否啟用 Code Mode，Claude 都可能以[規則無法比對到的形式](https://code.claude.com/docs/zh-TW/permissions.md#bash-rule-limits)執行被拒絕的命令。如需不依賴命令文字的限制，請參閱[沙箱機制](https://code.claude.com/docs/zh-TW/sandboxing.md)。

### 長時間執行的程式碼

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

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

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

* **您切換到了其他模式**：按 `Shift+Tab`，直到回到您啟動時的模式
* **您以其他模式啟動，或從 `claude --resume` 清單中選取了工作階段**：如果您可以使用[自動模式](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode)，請結束，然後在 Code Mode 開啟的情況下執行 `claude --continue --permission-mode auto`
* **您將工具名稱傳給了 `--tools`**：以自動模式重新啟動，且不使用該旗標

## 疑難排解

### Code Mode 無法啟動

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

| 原因包含 | 處理方式 |
| :- | :- |
| `it isn't open to your account yet` | 如果您的版本早於 v2.1.323，請[更新](#try-code-mode)。否則，請檢查您的網路連線並重新啟動。如果原因仍然存在，請改天再試 |
| `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` | 使用[支援的模型](#requirements)啟動，例如使用 `--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` | 取消設定[會關閉功能旗標擷取](https://code.claude.com/docs/zh-TW/env-vars.md#features-that-need-feature-flag-fetching)的變數，例如 `DISABLE_TELEMETRY` |
| `OpenTelemetry is on` | 如果您可以不使用 [OpenTelemetry 匯出](https://code.claude.com/docs/zh-TW/monitoring-usage.md)，請取消設定 `CLAUDE_CODE_ENABLE_TELEMETRY` 和 `ENABLE_BETA_TRACING_DETAILED` |
| `it doesn't yet work with an installed mod` | 關閉會檢查工具呼叫的 [mod](https://code.claude.com/docs/zh-TW/plugins/mods/overview.md) |
| `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` | 向您的管理員詢問相關的[受管設定](#block-code-mode-for-your-organization) |

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

### 附有倒數計時的權限提示

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

```text theme={null}
Claude Code will automatically block this request in 1:59, to avoid holding up an unattended session
```

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

### 工具呼叫被 hook 拒絕

如果 Claude 回報工具呼叫被拒絕，請向它詢問錯誤文字。以下錯誤表示 `PreToolUse` hook 未提供決定，即使未設定 [`onFailure`](https://code.claude.com/docs/zh-TW/hooks#block-the-action-when-a-hook-fails)，這也會拒絕該呼叫：

* **`the hook failed`**：在來自 Claude 程式碼的呼叫上，您的 hook 無法啟動、被終止、以 126、127 或大於 128 的代碼結束，或傳回 HTTP 錯誤或無效輸出。請修正該 hook
* **`the hook did not finish`**：您的 hook 在來自 Claude 程式碼的呼叫上逾時，或在 Claude 於工作階段中執行過程式碼後，於任何其他工具呼叫上逾時。請提高該 hook 的 [`timeout`](https://code.claude.com/docs/zh-TW/hooks#common-fields)

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

### 程式碼輸出被 hook 攔截

如果 Claude 在您預期看到 Claude 程式碼輸出的地方回報了 hook 的阻擋原因，請檢查您的 [`UserPromptSubmit`](https://code.claude.com/docs/zh-TW/hooks#userpromptsubmit) hook。當[程式碼可以在背景執行](#long-running-code)時，該事件上的 `command`、`http` 和 `mcp_tool` hook 也會在程式碼輸出上執行。若要讓輸出通過，請變更該 hook，使其在輸入中的 `source` 為 `poll_event` 時不進行阻擋。

## 相關資源

* [權限模式](https://code.claude.com/docs/zh-TW/permission-modes.md)：比較自動模式與會提示您的模式
* [Hook 參考](https://code.claude.com/docs/zh-TW/hooks.md)：撰寫 `PreToolUse` 和 `UserPromptSubmit` hook
* [受管設定](https://code.claude.com/docs/zh-TW/managed-settings.md)：在整個組織中套用同一套設定