Documentation — Spybara

agent-sdk/agent-loop.md +7 −1

Details

216| 選項 | 它控制什麼 | 預設值 |216| 選項 | 它控制什麼 | 預設值 |

217| :- | :- | :- |217| :- | :- | :- |

218| 最大回合（`max_turns` / `maxTurns`） | 最大工具使用往返次數 | 無限制 |218| 最大回合（`max_turns` / `maxTurns`） | 最大工具使用往返次數 | 無限制 |

219| 最大預算（`max_budget_usd` / `maxBudgetUsd`） | 停止前的最大成本 | 無限制 |219| 最大預算（`max_budget_usd` / `maxBudgetUsd`） | 迴圈停止時的預估支出 | 無限制 |

220 220

221當達到任一限制時，SDK 會返回一個 `ResultMessage`，其中包含相應的錯誤子類型（`error_max_turns` 或 `error_max_budget_usd`）。請參閱 [處理結果](#handle-the-result) 以了解如何檢查這些子類型，以及 [`ClaudeAgentOptions`](/docs/zh-TW/agent-sdk/python#claudeagentoptions) / [`Options`](/docs/zh-TW/agent-sdk/typescript#options) 以了解語法。221當達到任一限制時，SDK 會返回一個 `ResultMessage`，其中包含相應的錯誤子類型（`error_max_turns` 或 `error_max_budget_usd`）。請參閱 [處理結果](#handle-the-result) 以了解如何檢查這些子類型，以及 [`ClaudeAgentOptions`](/docs/zh-TW/agent-sdk/python#claudeagentoptions) / [`Options`](/docs/zh-TW/agent-sdk/typescript#options) 以了解語法。

222 222

224 224

225使用 [串流輸入](/docs/zh-TW/agent-sdk/streaming-vs-single-mode)，當回合在最大回合限制時結束時，仍在佇列中的訊息會保持佇列狀態。Claude Code 不會將其新增到該回合的最後一次模型呼叫中。它為訊息開始新的回合，該回合的最大回合計數重新開始。預算總額會持續在訊息間累積，一旦支出達到 `maxBudgetUsd`，同一對話中的後續訊息會以 `error_max_budget_usd` 結果結束。[`/clear`](/docs/zh-TW/agent-sdk/cost-tracking) 會重新開始預算。225使用 [串流輸入](/docs/zh-TW/agent-sdk/streaming-vs-single-mode)，當回合在最大回合限制時結束時，仍在佇列中的訊息會保持佇列狀態。Claude Code 不會將其新增到該回合的最後一次模型呼叫中。它為訊息開始新的回合，該回合的最大回合計數重新開始。預算總額會持續在訊息間累積，一旦支出達到 `maxBudgetUsd`，同一對話中的後續訊息會以 `error_max_budget_usd` 結果結束。[`/clear`](/docs/zh-TW/agent-sdk/cost-tracking) 會重新開始預算。

226 226

227<h4 id="budget-headroom">

228 預算餘裕

229</h4>

230

231Claude Code 會在模型回應送達後，將支出與 `max_budget_usd` / `maxBudgetUsd` 上限進行比較，因為每個回應的成本來自 API 隨該回應傳回的 token 使用量。達到上限的那個回應仍會完成，並計入 [`total_cost_usd`](/docs/zh-TW/agent-sdk/cost-tracking#get-the-total-cost-of-a-query)。因此，支出最多可能超過上限該單一回應的成本，再加上當下仍在執行的 subagent 在停止前的任何支出。設定上限時，請為此預留餘裕。

232

227<h3 id="effort-level">233<h3 id="effort-level">

228 努力等級234 努力等級

229</h3>235</h3>

agent-sdk/mcp.md +9 −5

Details

78 78

79您可以在呼叫 `query()` 時在程式碼中設定 MCP 伺服器，或在透過 [`settingSources`](#from-a-config-file) 載入的 `.mcp.json` 檔案中設定。79您可以在呼叫 `query()` 時在程式碼中設定 MCP 伺服器，或在透過 [`settingSources`](#from-a-config-file) 載入的 `.mcp.json` 檔案中設定。

80 80

~~81<h3 id="in-code">~~81<span id="in-code" />

~~82 在程式碼中~~82

83<h3 id="add-a-server-in-code">

84 在程式碼中新增伺服器

83</h3>85</h3>

84 86

85在 `mcpServers` 選項中直接傳遞 MCP 伺服器。此範例會為 `/Users/me/projects` 啟動本機檔案系統 MCP 伺服器。請將該路徑替換為您機器上的目錄：87在 `mcpServers` 選項中直接傳遞 MCP 伺服器。此範例會為 `/Users/me/projects` 啟動本機檔案系統 MCP 伺服器。請將該路徑替換為您機器上的目錄：

135 ```137 ```

136</CodeGroup>138</CodeGroup>

137 139

138<h3 id="from-a-config-file">140<span id="from-a-config-file" />

139 從設定檔141

142<h3 id="add-a-server-from-a-config-file">

143 從設定檔新增伺服器

140</h3>144</h3>

141 145

142在您的專案根目錄建立 `.mcp.json` 檔案。當啟用 `project` 設定來源時，該檔案會被選取，預設 `query()` 選項已啟用此功能。如果您明確設定 `settingSources`，請包含 `"project"` 以便載入此檔案。請將 `/Users/me/projects` 替換為您機器上的目錄：146在您的專案根目錄建立 `.mcp.json` 檔案。當啟用 `project` 設定來源時，該檔案會被選取，預設 `query()` 選項已啟用此功能。如果您明確設定 `settingSources`，請包含 `"project"` 以便載入此檔案。請將 `/Users/me/projects` 替換為您機器上的目錄：

301 stdio 伺服器305 stdio 伺服器

302</h3>306</h3>

303 307

304透過 stdin/stdout 進行通訊的本機程序。將此用於在同一台機器上執行的 MCP 伺服器。對於 `.mcp.json` 形式，請使用 [From a config file](#from-a-config-file) 中顯示的相同欄位。在程式碼中，傳遞命令及其引數。將 `/Users/me/projects` 替換為您機器上的目錄：308透過 stdin/stdout 進行通訊的本機程序。將此用於在同一台機器上執行的 MCP 伺服器。對於 `.mcp.json` 形式，請使用 [從設定檔新增伺服器](#from-a-config-file) 中顯示的相同欄位。在程式碼中，傳遞命令及其引數。將 `/Users/me/projects` 替換為您機器上的目錄：

305 309

306<CodeGroup>310<CodeGroup>

307 ```typescript TypeScript hidelines={1,-1} theme={null}311 ```typescript TypeScript hidelines={1,-1} theme={null}

agent-sdk/migration-guide.md +8 −4

Details

28 遷移步驟28 遷移步驟

29</h2>29</h2>

30 30

~~31<h3 id="for-typescript/javascript-projects">~~31<span id="for-typescript/javascript-projects" />

~~32 針對 TypeScript/JavaScript 專案~~32

33<h3 id="migrate-a-typescript-or-javascript-project">

34 遷移 TypeScript 或 JavaScript 專案

33</h3>35</h3>

34 36

35**1. 解除安裝舊套件：**37**1. 解除安裝舊套件：**

64 66

65進行任何必要的程式碼變更以完成遷移。67進行任何必要的程式碼變更以完成遷移。

66 68

~~67<h3 id="for-python-projects">~~69<span id="for-python-projects" />

~~68 針對 Python 專案~~70

71<h3 id="migrate-a-python-project">

72 遷移 Python 專案

69</h3>73</h3>

70 74

71**1. 解除安裝舊套件：**75**1. 解除安裝舊套件：**

agent-sdk/permissions.md +1 −1

Details

147 147

148<Warning>148<Warning>

149 **子代理繼承：** 子代理在父工作階段的權限模式中執行，除非您在其 [`AgentDefinition`](/docs/zh-TW/agent-sdk/typescript#agentdefinition) 上設定 `permissionMode`，且父工作階段處於 `default`、`dontAsk` 或 `plan` 模式。即使如此，Claude Code 也永遠不會套用 `"bypassPermissions"` 值。子代理只有在父工作階段本身處於 `bypassPermissions` 模式時，才會在該模式中執行。`bypassPermissions` 例外需要 Claude Code v2.1.267 或更新版本。149 **Subagent 繼承：** subagent 在父工作階段的權限模式中執行，除非您在其 [`AgentDefinition`](/docs/zh-TW/agent-sdk/typescript#agentdefinition) 上設定 `permissionMode`，且父工作階段處於 `default`、`dontAsk` 或 `plan` 模式。即使如此，Claude Code 也永遠不會套用 `"bypassPermissions"` 值，且只有在該 subagent [可使用自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)時才會套用 `"auto"` 值。subagent 只有在父工作階段本身處於 `bypassPermissions` 模式時，才會在該模式中執行。`bypassPermissions` 例外需要 Claude Code v2.1.267 或更新版本。

150 150

151 子代理可能具有不同的系統提示和比您的主代理更少受限的行為，因此繼承 `bypassPermissions` 會授予它們完整的自主系統存取權。[沒有任何模式自動核准的動作](/docs/zh-TW/permission-modes#actions-no-mode-auto-approves)仍然適用。151 子代理可能具有不同的系統提示和比您的主代理更少受限的行為，因此繼承 `bypassPermissions` 會授予它們完整的自主系統存取權。[沒有任何模式自動核准的動作](/docs/zh-TW/permission-modes#actions-no-mode-auto-approves)仍然適用。

152</Warning>152</Warning>

agent-sdk/python.md +21 −18

Details

932| `disallowed_tools` | `list[str]` | `[]` | 要拒絕的工具。裸名稱（例如 `"Bash"`）會從 Claude 的上下文中移除工具。範圍規則（例如 `"Bash(rm *)"`）會保留工具可用，並在每個權限模式（包括 `bypassPermissions`）中拒絕符合的呼叫，針對[如所寫](/docs/zh-TW/permissions#bash-rule-limits)的命令。請參閱[權限](/docs/zh-TW/agent-sdk/permissions#allow-and-deny-rules) |932| `disallowed_tools` | `list[str]` | `[]` | 要拒絕的工具。裸名稱（例如 `"Bash"`）會從 Claude 的上下文中移除工具。範圍規則（例如 `"Bash(rm *)"`）會保留工具可用，並在每個權限模式（包括 `bypassPermissions`）中拒絕符合的呼叫，針對[如所寫](/docs/zh-TW/permissions#bash-rule-limits)的命令。請參閱[權限](/docs/zh-TW/agent-sdk/permissions#allow-and-deny-rules) |

987```987```

988 988

989* `API_TIMEOUT_MS`：Anthropic 用戶端上的每個請求逾時（以毫秒為單位）。預設 `600000`。適用於主迴圈和所有 subagent。989* `API_TIMEOUT_MS`：Anthropic 用戶端上的每個請求逾時（以毫秒為單位）。預設 `600000`。適用於主迴圈和所有 subagent。

990* `CLAUDE_CODE_MAX_RETRIES`：最大 API 重試次數。預設 `10`，上限為 `15`。每次重試都有自己的 `API_TIMEOUT_MS` 視窗，因此最壞情況下的牆面時間大約是 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 加上退避。對於需要等待較長中斷的無人值守執行，設定 [`CLAUDE_CODE_RETRY_WATCHDOG=1`](/docs/zh-TW/errors#tune-retry-behavior)：它無限期重試暫時性容量錯誤，並且在 Claude Code v2.1.199 或更新版本上，將其他暫時性錯誤的預設值提高到 `300` 並移除此變數的上限。990* `CLAUDE_CODE_MAX_RETRIES`：最大 API 重試次數。預設 `10`，上限為 `15`。每次重試都有自己的 `API_TIMEOUT_MS` 視窗。

991

992 對於需要等待較長中斷的無人值守執行，設定 [`CLAUDE_CODE_RETRY_WATCHDOG=1`](/docs/zh-TW/errors#tune-retry-behavior)：它無限期重試暫時性容量錯誤，並且在 Claude Code v2.1.199 或更新版本上，將其他暫時性錯誤的預設值提高到 `300` 並移除此變數的上限。

991* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：subagent 的停滯監視程式。當串流監視程式開啟時，預設值為 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 加上 5 分鐘，總計 `600000`，除非您提高該變數。關閉串流監視程式時，預設值為 `600000`。在 v2.1.257 之前，預設值始終為 `600000`。993* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：subagent 的停滯監視程式。當串流監視程式開啟時，預設值為 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 加上 5 分鐘，總計 `600000`，除非您提高該變數。關閉串流監視程式時，預設值為 `600000`。在 v2.1.257 之前，預設值始終為 `600000`。

992 994

993 計時器在每個串流事件時重設。停滯時，Claude Code 會中止 subagent 並向父 agent 報告停滯。對於背景 subagent，它也會將任務標記為失敗並附加任何部分結果。995 計時器在每個串流事件時重設。停滯時，Claude Code 會中止 subagent 並向父 agent 報告停滯。對於背景 subagent，它也會將任務標記為失敗並附加任何部分結果。

2795}2797}

2796```2798```

2797 2799

2798啟動新代理以自主處理複雜的多步驟任務。2800啟動新 agent 以自主處理複雜的多步驟任務。

2799 2801

2800**輸出（狀態：`"completed"`）：**2802**輸出（狀態：`"completed"`）：**

2801 2803

2852{2854{

2853 "status": "async_launched",2855 "status": "async_launched",

2854 "isAsync": bool | None, # 在背景啟動時為 True2856 "isAsync": bool | None, # 在背景啟動時為 True

2855 "agentId": str, # 啟動的代理的 ID2857 "agentId": str, # 啟動的 agent 的 ID

2856 "description": str, # 任務描述2858 "description": str, # 任務描述

2857 "resolvedModel": str | None, # 在背景轉換時使用的模型2859 "resolvedModel": str | None, # 在背景轉換時使用的模型

2858 "modelsUsed": list[str] | None, # 背景轉換前使用的模型，依序排列，連續重複已摺疊2860 "modelsUsed": list[str] | None, # 背景轉換前使用的模型，依序排列，連續重複已摺疊

2859 "prompt": str, # 代理執行的提示2861 "prompt": str, # agent 執行的提示詞

2860 "outputFile": str, # 代理輸出寫入的檔案路徑2862 "outputFile": str, # agent 輸出寫入的檔案路徑

2861 "canReadOutputFile": bool | None, # 是否可以直接讀取輸出檔案2863 "canReadOutputFile": bool | None, # 是否可以直接讀取輸出檔案

2862}2864}

2863```2865```

2870 "taskId": str, # 分派任務的 ID2872 "taskId": str, # 分派任務的 ID

2871 "sessionUrl": str, # 雲端工作階段的連結2873 "sessionUrl": str, # 雲端工作階段的連結

2872 "description": str, # 任務描述2874 "description": str, # 任務描述

2873 "prompt": str, # 代理執行的提示2875 "prompt": str, # agent 執行的提示詞

2874 "outputFile": str, # 代理輸出寫入的檔案路徑2876 "outputFile": str, # agent 輸出寫入的檔案路徑

2875}2877}

2876```2878```

2877 2879

2878返回來自子代理的結果。輸出根據 `status` 欄位進行區分：`"completed"` 用於已完成的任務，`"async_launched"` 用於背景任務，`"remote_launched"` 用於 Claude Code 分派到雲端工作階段的任務，其中 `sessionUrl` 連結到該工作階段，`taskId` 識別它。如果 Claude Code [保留了子代理的隔離 worktree](/docs/zh-TW/worktrees#isolate-subagents-with-worktrees)，`completed` 變體上的 `worktreePath` 是找到它的位置，`worktreeBranch` 是當 Claude Code 使用 git 建立 worktree 時的分支。2880返回來自 subagent 的結果。輸出根據 `status` 欄位進行區分：`"completed"` 用於已完成的任務，`"async_launched"` 用於背景任務，`"remote_launched"` 用於 Claude Code 分派到雲端工作階段的任務，其中 `sessionUrl` 連結到該工作階段，`taskId` 識別它。如果 Claude Code [保留了 subagent 的隔離 worktree](/docs/zh-TW/worktrees#isolate-subagents-with-worktrees)，`completed` 變體上的 `worktreePath` 是找到它的位置，`worktreeBranch` 是當 Claude Code 使用 git 建立 worktree 時的分支。

2879 2881

2880在 `completed` 變體上，`resolvedModel` 命名子代理啟動時使用的模型，當套用 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection) 或其他覆蓋時，可能與請求的 `model` 輸入不同。此欄位需要 Claude Code v2.1.174 或更新版本。在 `async_launched` 變體上，`resolvedModel` 命名代理移至背景時使用的模型，因此在背景轉換前發生的交換會反映在那裡。兩個變體上的 `modelsUsed` 欄位依序列出使用的模型，連續重複已摺疊；只有在執行中途交換模型時才會設定。`modelsUsed` 和背景轉換時的 `resolvedModel` 行為需要 Claude Code v2.1.212 或更新版本。2882在 `completed` 變體上，`resolvedModel` 命名 subagent 啟動時使用的模型，當套用 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection) 或其他覆寫時，可能與請求的 `model` 輸入不同。此欄位需要 Claude Code v2.1.174 或更新版本。在 `async_launched` 變體上，`resolvedModel` 命名 agent 移至背景時使用的模型，因此在背景轉換前發生的交換會反映在那裡。兩個變體上的 `modelsUsed` 欄位依序列出使用的模型，連續重複已摺疊；只有在執行中途交換模型時才會設定。`modelsUsed` 和背景轉換時的 `resolvedModel` 行為需要 Claude Code v2.1.212 或更新版本。

2881 2883

2882Claude Code 從 subagent 的最終 API 請求填充 `usage` 和 `totalTokens`，而不是從整個執行。當存在時，`usage` 中 `output_tokens_details` 下的 `thinking_tokens` 是該請求的輸出 token 中屬於思考 token 的數量。`output_tokens_details` 鍵需要 Python SDK v0.2.136 或更新版本，其中包含 Claude Code v2.1.228。`fallback_credit` 鍵需要 Python SDK v0.2.162 或更新版本，其中包含 Claude Code v2.1.285。2884Claude Code 從 subagent 的最終 API 請求填充 `usage` 和 `totalTokens`，而不是從整個執行。當存在時，`usage` 中 `output_tokens_details` 下的 `thinking_tokens` 是該請求的輸出 token 中屬於思考 token 的數量。`output_tokens_details` 鍵需要 Python SDK v0.2.136 或更新版本，其中包含 Claude Code v2.1.228。`fallback_credit` 鍵需要 Python SDK v0.2.162 或更新版本，其中包含 Claude Code v2.1.285。

2883 2885

3080 "numLines": int, # 返回內容中的行數3082 "numLines": int, # 返回內容中的行數

3081 "startLine": int, # 內容開始的行號3083 "startLine": int, # 內容開始的行號

3082 "totalLines": int, # 檔案中的總行數3084 "totalLines": int, # 檔案中的總行數

3083 "truncatedByTokenCap": bool | None, # 當整個檔案讀取超過令牌上限且內容是第一頁時出現且為 True3085 "truncatedByTokenCap": bool | None, # 當整個檔案讀取超過 token 上限且內容是第一頁時出現且為 True

3084 },3086 },

3085}3087}

3086```3088```

3140 "count": int, # 提取為影像的頁數3142 "count": int, # 提取為影像的頁數

3141 "outputDir": str, # 包含提取的頁面影像的目錄3143 "outputDir": str, # 包含提取的頁面影像的目錄

3142 },3144 },

3143 "firstPage": int | None, # 選擇性文件頁碼的第一個提取頁面3145 "firstPage": int | None, # 選擇性；第一個提取頁面的文件頁碼

3144}3146}

3145```3147```

3146 3148

3152 "file": {3154 "file": {

3153 "filePath": str,3155 "filePath": str,

3154 },3156 },

3155 "source": "seeded" | None, # 當較早的副本來自在啟動時載入的 CLAUDE.md 或記憶體檔案而不是 Read 呼叫時出現3157 "source": "seeded" | None, # 當較早的副本來自在啟動時載入的 CLAUDE.md 或記憶檔案而不是 Read 呼叫時出現

3156}3158}

3157```3159```

3158 3160

3175 3177

3176```python theme={null}3178```python theme={null}

3177{3179{

3178 "type": "create" | "update", # 寫入是建立新檔案還是覆蓋現有檔案3180 "type": "create" | "update", # 寫入是建立新檔案還是覆寫現有檔案

3179 "filePath": str, # 被寫入的檔案3181 "filePath": str, # 被寫入的檔案

3180 "content": str, # 被寫入的內容3182 "content": str, # 被寫入的內容

3181 "structuredPatch": [ # Diff 區塊；新檔案、未變更或 Claude Code 跳過 diff 時為空3183 "structuredPatch": [ # Diff 區塊；新檔案、未變更或 Claude Code 跳過 diff 時為空

3326```python theme={null}3328```python theme={null}

3327{3329{

3328 "url": str, # 要從中擷取內容的 URL3330 "url": str, # 要從中擷取內容的 URL

3329 "prompt": str, # 要在擷取的內容上執行的提示3331 "prompt": str, # 要在擷取的內容上執行的提示詞

3332 "offset": int | None, # 從頁面開頭略過的字元數。需要 Python Agent SDK 0.2.164 或更新版本

3330}3333}

3331```3334```

3332 3335

3337 "bytes": int, # 擷取內容的大小（位元組）3340 "bytes": int, # 擷取內容的大小（位元組）

3338 "code": int, # HTTP 回應代碼3341 "code": int, # HTTP 回應代碼

3339 "codeText": str, # HTTP 回應代碼文字3342 "codeText": str, # HTTP 回應代碼文字

3340 "result": str, # 透過將提示套用到內容而得到的處理結果3343 "result": str, # 透過將提示詞套用到內容而得到的處理結果

3341 "durationMs": int, # 擷取和處理內容的時間（毫秒）3344 "durationMs": int, # 擷取和處理內容的時間（毫秒）

3342 "url": str, # 被擷取的 URL3345 "url": str, # 被擷取的 URL

3343}3346}

3546 TaskOutput3549 TaskOutput

3547</h3>3550</h3>

3548 3551

3549在 Claude Code v2.1.277 中移除。先前從執行中或已完成的背景任務擷取輸出，`BashOutput` 被接受為別名；Claude 使用 `Read` 讀取背景任務的輸出檔案。3552在 Claude Code v2.1.277 中移除。先前從執行中或已完成的背景任務擷取輸出，`BashOutput` 被接受為別名；Claude 改為使用 `Read` 讀取背景任務的輸出檔案。

3550 3553

3551`disallowed_tools` 項目或仍命名任一名稱的拒絕規則被忽略而不發出警告。3554`disallowed_tools` 項目或仍命名任一名稱的拒絕規則被忽略而不發出警告。

3552 3555

3595```python theme={null}3598```python theme={null}

3596{3599{

3597 "plan": str | None, # 呈現給使用者的計畫3600 "plan": str | None, # 呈現給使用者的計畫

3598 "isAgent": bool, # 當子代理呼叫工具時為 True3601 "isAgent": bool, # 當 subagent 呼叫工具時為 True

3599 "filePath": str | None, # 當計畫被儲存到檔案時出現3602 "filePath": str | None, # 當計畫被儲存到檔案時出現

3600 "hasTaskTool": bool | None, # 選擇性；Agent 工具是否在目前內容中可用3603 "hasTaskTool": bool | None, # 選擇性；Agent 工具是否在目前內容中可用

3601 "planWasEdited": bool | None, # 當使用者在核准前編輯計畫時出現且為 True3604 "planWasEdited": bool | None, # 當使用者在核准前編輯計畫時出現且為 True

agent-sdk/subagents.md +9 −2

Details

323 偵測子代理程式叫用323 偵測子代理程式叫用

324</h2>324</h2>

325 325

326Claude 透過 Agent 工具叫用子代理程式。若要偵測何時叫用子代理程式，請檢查 `tool_use` 區塊，其中 `name` 為 `"Agent"`。來自子代理程式內容中的訊息包含 `parent_tool_use_id` 欄位。326Claude 透過 Agent 工具叫用 subagent。若要偵測何時叫用 subagent，請檢查 `tool_use` 區塊，其中 `name` 為 `"Agent"`。

327

328來自 subagent 內容中的訊息包含 `parent_tool_use_id` 欄位。在 TypeScript 中，subagent 產生的每則助理訊息和使用者訊息也帶有 [`agent_id`](/docs/zh-TW/agent-sdk/typescript#sdkassistantmessage)：即該 subagent 之[任務事件](/docs/zh-TW/agent-sdk/typescript#sdktaskstartedmessage)的 `task_id`。`agent_id` 需要 TypeScript Agent SDK v0.3.292 或更新版本。

327 329

328<Note>330<Note>

329 該工具在 `tool_use` 區塊中顯示為 `"Agent"`，但在 `system:init` 工具清單中顯示為 `"Task"`。在 Claude Code v2.1.63 之前，`tool_use` 區塊也將其命名為 `"Task"`。為了保持偵測在各個 SDK 版本中正常運作，請在 `block.name` 中同時符合兩個值。331 該工具在 `tool_use` 區塊中顯示為 `"Agent"`，但在 `system:init` 工具清單中顯示為 `"Task"`。在 Claude Code v2.1.63 之前，`tool_use` 區塊也將其命名為 `"Task"`。為了保持偵測在各個 SDK 版本中正常運作，請在 `block.name` 中同時符合兩個值。

331 333

332訊息結構在 SDK 之間有所不同。在 Python 中，您可以透過 `message.content` 直接存取內容區塊。在 TypeScript 中，`SDKAssistantMessage` 包裝 Claude API 訊息，因此您透過 `message.message.content` 存取內容。334訊息結構在 SDK 之間有所不同。在 Python 中，您可以透過 `message.content` 直接存取內容區塊。在 TypeScript 中，`SDKAssistantMessage` 包裝 Claude API 訊息，因此您透過 `message.message.content` 存取內容。

333 335

334此範例會逐一查看串流訊息，在叫用子代理程式時以及後續訊息源自該子代理程式執行內容時進行記錄。336此範例會逐一查看串流訊息，在叫用 subagent 時以及後續訊息源自該 subagent 執行內容時進行記錄。TypeScript 版本也會記錄每則帶有 `agent_id` 的 subagent 訊息之 `agent_id`。

335 337

336<CodeGroup>338<CodeGroup>

337 ```python Python theme={null}339 ```python Python theme={null}

403 // Check if this message is from within a subagent's context405 // Check if this message is from within a subagent's context

404 if (msg.parent_tool_use_id) {406 if (msg.parent_tool_use_id) {

405 console.log(" (running inside subagent)");407 console.log(" (running inside subagent)");

408 // On assistant and user messages, agent_id matches the task_id

409 // on that subagent's task_started and other task events

410 if (msg.agent_id) {

411 console.log(` agent_id: ${msg.agent_id}`);

412 }

406 }413 }

407 414

408 if ("result" in message) {415 if ("result" in message) {

agent-sdk/typescript.md +115 −5

Details

571| `managedSettings` | `Settings` | `undefined` | 您的主機程序提供給所產生工作階段的政策層級設定。在有管理員部署受管設定的機器上，除非管理員的最高優先順序受管來源設定了 `parentSettingsBehavior: 'merge'`，否則 Claude Code 會忽略這些設定，且在 [`policyHelper`](/docs/zh-TW/settings-reference#policyhelper) 提供受管設定時永遠不會合併它們。合併的值會通過僅限限制性的篩選器；[限制父層設定](/docs/zh-TW/claude-apps-gateway#restrict-parent-settings)說明了篩選器允許的內容以及 `allowManaged*Only` 鎖定。設定了 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-TW/env-vars) 的主機則會改為直接從此 payload 讀取三個鍵：在 Claude Code v2.1.222 或更新版本上的[模型設定](/docs/zh-TW/model-config#restrict-model-selection)、在 v2.1.246 或更新版本上沒有任何受管來源設定它時的 [`modelPricing`](/docs/zh-TW/settings-reference#modelpricing)，以及在 v2.1.247 或更新版本上的 `ENABLE_TOOL_SEARCH` env 項目 |571| `managedSettings` | `Settings` | `undefined` | 您的主機程序提供給所產生工作階段的政策層級設定。在有管理員部署受管設定的機器上，除非管理員的最高優先順序受管來源設定了 `parentSettingsBehavior: 'merge'`，否則 Claude Code 會忽略這些設定，且在 [`policyHelper`](/docs/zh-TW/settings-reference#policyhelper) 提供受管設定時永遠不會合併它們。合併的值會通過僅限限制性的篩選器；[限制父層設定](/docs/zh-TW/claude-apps-gateway#restrict-parent-settings)說明了篩選器允許的內容以及 `allowManaged*Only` 鎖定。設定了 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-TW/env-vars) 的主機則會改為直接從此 payload 讀取三個鍵：在 Claude Code v2.1.222 或更新版本上的[模型設定](/docs/zh-TW/model-config#restrict-model-selection)、在 v2.1.246 或更新版本上沒有任何受管來源設定它時的 [`modelPricing`](/docs/zh-TW/settings-reference#modelpricing)，以及在 v2.1.247 或更新版本上的 `ENABLE_TOOL_SEARCH` env 項目 |

575| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | MCP 伺服器設定 |575| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | MCP 伺服器設定 |

631```631```

632 632

633* `API_TIMEOUT_MS`：Anthropic 用戶端上每個請求的逾時時間，以毫秒為單位。預設為 `600000`。適用於主迴圈和所有 subagent。633* `API_TIMEOUT_MS`：Anthropic 用戶端上每個請求的逾時時間，以毫秒為單位。預設為 `600000`。適用於主迴圈和所有 subagent。

634* `CLAUDE_CODE_MAX_RETRIES`：API 重試的最大次數。預設為 `10`，上限為 `15`。每次重試都有各自的 `API_TIMEOUT_MS` 時間範圍，因此最壞情況下的實際耗時約為 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 加上退避時間。對於需要撐過較長中斷時間的無人值守執行，請設定 [`CLAUDE_CODE_RETRY_WATCHDOG=1`](/docs/zh-TW/errors#tune-retry-behavior)：它會無限期重試暫時性的容量錯誤，並且在 Claude Code v2.1.199 或更新版本上，將其他暫時性錯誤的預設值提高到 `300`，並移除此變數的上限。634* `CLAUDE_CODE_MAX_RETRIES`：API 重試的最大次數。預設為 `10`，上限為 `15`。每次重試都有自己的 `API_TIMEOUT_MS` 時間範圍。

635

636 對於需要等待較長中斷期間的無人值守執行，請設定 [`CLAUDE_CODE_RETRY_WATCHDOG=1`](/docs/zh-TW/errors#tune-retry-behavior)：它會無限期重試暫時性的容量錯誤，並且在 Claude Code v2.1.199 或更新版本上，會將其他暫時性錯誤的預設值提高到 `300`，並移除此變數的上限。

635* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：subagent 的停滯監控器。當串流監控器開啟時，預設值為 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 加上 5 分鐘，除非您提高該變數，否則為 `600000`。串流監控器關閉時，預設值為 `600000`。在 v2.1.257 之前，預設值一律為 `600000`。637* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：subagent 的停滯監控器。當串流監控器開啟時，預設值為 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 加上 5 分鐘，除非您提高該變數，否則為 `600000`。串流監控器關閉時，預設值為 `600000`。在 v2.1.257 之前，預設值一律為 `600000`。

636 638

637 每次串流事件發生時計時器都會重設。發生停滯時，Claude Code 會中止該 subagent 並向父層回報停滯。對於背景 subagent，它也會將任務標記為失敗並附上任何部分結果。639 每次串流事件發生時計時器都會重設。發生停滯時，Claude Code 會中止該 subagent 並向父層回報停滯。對於背景 subagent，它也會將任務標記為失敗並附上任何部分結果。

1561 parent_tool_use_id: string | null;1563 parent_tool_use_id: string | null;

1562 error?: SDKAssistantMessageError;1564 error?: SDKAssistantMessageError;

1563 aborted?: true;1565 aborted?: true;

1566 agent_id?: string;

1564 timestamp?: string;1567 timestamp?: string;

1565 context_usage?: SDKContextUsage;1568 context_usage?: SDKContextUsage;

1569 usage_report?: SDKUsageReport;

1566 user_message_uuid?: string;1570 user_message_uuid?: string;

1567 user_message_uuids?: string[];1571 user_message_uuids?: string[];

1568 resume_reason?: string;1572 resume_reason?: string;

1580 1584

1581當中斷或中止在串流完成前截斷助手訊息時，`aborted` 為 `true`：訊息沒有 `stop_reason`，內容可能在詞的中間結束。該欄位在正常完成的訊息上不存在。它需要 Agent SDK v0.3.214 或更新版本。1585當中斷或中止在串流完成前截斷助手訊息時，`aborted` 為 `true`：訊息沒有 `stop_reason`，內容可能在詞的中間結束。該欄位在正常完成的訊息上不存在。它需要 Agent SDK v0.3.214 或更新版本。

1582 1586

1587`agent_id` 識別產生該訊息的 subagent，主執行緒的訊息不會有此欄位。其值等於該 subagent 的 [`task_started`](#sdktaskstartedmessage) 及其他任務事件上的 `task_id`，且在 subagent [恢復](/docs/zh-TW/agent-sdk/subagents#resume-subagents)時保持不變。此欄位需要 Agent SDK v0.3.292 或更新版本。

1588

1589請依 `agent_id` 將 subagent 的訊息與其任務事件配對，而不是將訊息的 `parent_tool_use_id` 與任務事件的 `tool_use_id` 配對。當工具呼叫恢復 subagent 時，任務事件會帶有該呼叫的 `tool_use_id`，而訊息則保留最初啟動該 subagent 之工具呼叫的 `parent_tool_use_id`，因此兩者將不再相符。

1590

1583Claude Code 會在回合的第一個助手訊息上設定 `user_message_uuid` 和 `user_message_uuids`，條件請見 [`user_message_uuid`](#user_message_uuid)。當 Claude Code 重新執行被重新啟動中斷的回合時，重新執行中攜帶這些欄位的助手訊息也會攜帶 [`resume_reason`](#resume_reason)。1591Claude Code 會在回合的第一個助手訊息上設定 `user_message_uuid` 和 `user_message_uuids`，條件請見 [`user_message_uuid`](#user_message_uuid)。當 Claude Code 重新執行被重新啟動中斷的回合時，重新執行中攜帶這些欄位的助手訊息也會攜帶 [`resume_reason`](#resume_reason)。

1584 1592

1585`timestamp` 是訊息內容在產生它的程序上完成生成的 ISO 8601 時間。該值來自該機器的時鐘，因此僅用於顯示，不要依其排序訊息。一個 API 回合可以產生多個共用同一 `message.id` 的助手訊息，每個都有自己的 `timestamp`。當欄位不存在時，請改用您收到訊息的時間。1593`timestamp` 是訊息內容在產生它的程序上完成生成的 ISO 8601 時間。該值來自該機器的時鐘，因此僅用於顯示，不要依其排序訊息。一個 API 回合可以產生多個共用同一 `message.id` 的助手訊息，每個都有自己的 `timestamp`。當欄位不存在時，請改用您收到訊息的時間。

1586 1594

1587`context_usage` 是 `/context` 報告的結構化副本，類型為 [`SDKContextUsage`](#sdkcontextusage)，需要 Agent SDK v0.3.232 或更新版本。當您以提示詞形式傳送 `/context` 時，Claude Code 會將報告作為助手訊息傳遞，其 `message.content` 包含 markdown 表格，並將 `context_usage` 附加到同一訊息。Claude Code 不會在任何其他助手訊息上設定該欄位，較早的版本傳遞 `/context` 表格時也不會帶有它，因此當欄位存在時從欄位讀取明細，不存在時則改用 markdown 文字。1595`context_usage` 是 `/context` 報告的結構化副本，類型為 [`SDKContextUsage`](#sdkcontextusage)，需要 Agent SDK v0.3.232 或更新版本。當您以提示詞形式傳送 `/context` 時，Claude Code 會將報告作為助手訊息傳遞，其 `message.content` 包含 markdown 表格，並將 `context_usage` 附加到同一訊息。Claude Code 不會在任何其他助手訊息上設定該欄位，較早的版本傳遞 `/context` 表格時也不會帶有它，因此當欄位存在時從欄位讀取明細，不存在時則改用 markdown 文字。

1588 1596

1597`usage_report` 是 `/usage` 報告的結構化副本，類型為 [`SDKUsageReport`](#sdkusagereport)，需要 Agent SDK v0.3.273 或更新版本。當您將 `/usage` 作為提示詞送出時，Claude Code 會以一則助理訊息傳遞報告，其 `message.content` 包含文字。只有在工作階段符合下列所有條件時，它才會將 `usage_report` 附加到同一則訊息上：

1598

1599* 工作階段使用 claude.ai 憑證進行身分驗證

1600* 該憑證顯示已知的方案類型，或帶有 `user:profile` 範圍

1601* 該帳戶並非採用依用量計費

1602

1603以 `CLAUDE_CODE_OAUTH_TOKEN` 傳入的 `claude setup-token` token 預設不符合條件，因為它只帶有 `user:inference` 範圍。其他工作階段（例如 API 金鑰工作階段）傳遞的文字不含此欄位，較早的版本也是如此。當欄位存在時請從中讀取報告，不存在時則改用文字。

1604

1589<h3 id="sdkusermessage">1605<h3 id="sdkusermessage">

1590 `SDKUserMessage`1606 `SDKUserMessage`

1591</h3>1607</h3>

1597 type: "user";1613 type: "user";

1598 uuid?: UUID;1614 uuid?: UUID;

1599 session_id?: string;1615 session_id?: string;

1616 agent_id?: string;

1600 message: MessageParam; // From Anthropic SDK1617 message: MessageParam; // From Anthropic SDK

1601 pasted_content?: MessageParam["content"][];1618 pasted_content?: MessageParam["content"][];

1602 parent_tool_use_id: string | null;1619 parent_tool_use_id: string | null;

1636};1653};

1637```1654```

1638 1655

1656subagent 產生的使用者訊息（例如其自身某個工具呼叫的 `tool_result`）會帶有 `agent_id`。請參閱 [`SDKAssistantMessage`](#sdkassistantmessage)，其中定義了此欄位及其版本需求。

1657

1639在帶有 `tool_result` 區塊的訊息上，`tool_use_result` 是工具的結構化輸出物件，而非傳送給模型的文字。其形狀取決於對應 `tool_use` 區塊所指名的工具，因此此欄位的型別為 `unknown`；內建形狀列於[工具輸出類型](#tool-output-types)。下列結果需要超出其所列形狀的處理：1658在帶有 `tool_result` 區塊的訊息上，`tool_use_result` 是工具的結構化輸出物件，而非傳送給模型的文字。其形狀取決於對應 `tool_use` 區塊所指名的工具，因此此欄位的型別為 `unknown`；內建形狀列於[工具輸出類型](#tool-output-types)。下列結果需要超出其所列形狀的處理：

1640 1659

1641* `Agent` 工具：`tool_use_result` 為 [`AgentOutput`](#agent-2)。請依據它來呈現，而非剖析 `tool_result` 文字。`completed` 結果的 `content` 包含 subagent 的報告；對於透過 `SubagentHandback` 工具呼叫交回報告的 subagent，則是以一段關於該交回的簡短說明取代報告。在 Claude Code v2.1.271 或更新版本的[自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)中，每個產生 `completed` 結果的 subagent 都會以這種方式回報，除非它是 [fork](/docs/zh-TW/sub-agents#fork-the-current-conversation)，且 Claude 會以來自 subagent 的獨立訊息接收報告。1660* `Agent` 工具：`tool_use_result` 為 [`AgentOutput`](#agent-2)。請依據它來呈現，而非剖析 `tool_result` 文字。`completed` 結果的 `content` 包含 subagent 的報告；對於透過 `SubagentHandback` 工具呼叫交回報告的 subagent，則是以一段關於該交回的簡短說明取代報告。在 Claude Code v2.1.271 或更新版本的[自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)中，每個產生 `completed` 結果的 subagent 都會以這種方式回報，除非它是 [fork](/docs/zh-TW/sub-agents#fork-the-current-conversation)，且 Claude 會以來自 subagent 的獨立訊息接收報告。

1992 `SDKPartialAssistantMessage`2011 `SDKPartialAssistantMessage`

1993</h3>2012</h3>

1994 2013

1995串流部分訊息（僅當 `includePartialMessages` 為 true 時）。`parent_tool_use_id` 欄位一律為 `null`：串流事件僅針對主工作階段發出。若要進行 subagent 歸屬，請使用攜帶 `parent_tool_use_id` 的完整訊息，或啟用 [`forwardSubagentText`](#options) 以完整訊息形式接收 subagent 的文字和思考。2014串流部分訊息（僅在 `includePartialMessages` 為 true 時）。

2015

2016`parent_tool_use_id` 欄位一律為 `null`：串流事件僅針對主工作階段發出。若要歸屬 subagent，請使用完整訊息（其帶有 [`agent_id`](#sdkassistantmessage) 和 `parent_tool_use_id`），或啟用 [`forwardSubagentText`](#options) 以完整訊息形式接收 subagent 的文字和思考內容。

1996 2017

1997```typescript theme={null}2018```typescript theme={null}

1998type SDKPartialAssistantMessage = {2019type SDKPartialAssistantMessage = {

2229* `buffer`：壓縮保留空間2250* `buffer`：壓縮保留空間

2230* `deferred`：Claude Code 保留在視窗之外、不計入使用情況計算的工具 schema，僅列出供您參考2251* `deferred`：Claude Code 保留在視窗之外、不計入使用情況計算的工具 schema，僅列出供您參考

2231 2252

2253<h3 id="sdkusagereport">

2254 `SDKUsageReport`

2255</h3>

2256

2257`/usage` 報告的結構化形式，以 `usage_report` 的形式帶在傳遞 `/usage` 結果的 [`SDKAssistantMessage`](#sdkassistantmessage) 上。Agent SDK v0.3.273 及更新版本會匯出此類型。此類型為實驗性：其形狀可能會變更。

2258

2259```typescript theme={null}

2260type SDKUsageReport = {

2261 session: {

2262 total_cost_usd: number;

2263 total_api_duration_ms: number;

2264 total_duration_ms: number;

2265 total_lines_added: number;

2266 total_lines_removed: number;

2267 model_usage: { [modelName: string]: ModelUsage };

2268 };

2269 rate_limits: {

2270 limits:

2271 | {

2272 kind: string;

2273 group: string;

2274 percent: number;

2275 resets_at: string | null;

2276 scope?: {

2277 model?: { display_name: string } | null;

2278 surface?: { display_name: string } | null;

2279 } | null;

2280 severity: string;

2281 is_active: boolean;

2282 }[]

2283 | null;

2284 extra_usage?: {

2285 is_enabled: boolean;

2286 monthly_limit: number | null;

2287 used_credits: number | null;

2288 utilization: number | null;

2289 currency?: string | null;

2290 } | null;

2291 } | null;

2292};

2293```

2294

2295頂層欄位為 `session` 和 `rate_limits`：

2296

2297* `session`：Claude Code 持續累計的成本與用量總計，讀取自與 [`SDKResultMessage`](#sdkresultmessage) 上的 `total_cost_usd` 和 `modelUsage` 相同的帳本。每個 `model_usage` 項目都是一個 [`ModelUsage`](#modelusage)。

2298* `rate_limits`：`limits` 中的方案用量列，以及 `extra_usage` 中的用量點數支出。當 Claude Code 無法取得方案用量時（例如工作階段的 OAuth token 缺少 `user:profile` 範圍），此欄位為 `null`。

2299

2300Claude Code 依據 token 數在本機計算 `session.total_cost_usd`，因此它是估算值，而非您方案的計費金額。伺服器回報的用量點數支出是另外的 `extra_usage` 區塊。關於準確度的注意事項，請參閱[追蹤成本與用量](/docs/zh-TW/agent-sdk/cost-tracking)。

2301

2302`limits` 依伺服器傳送的原樣包含伺服器的用量列：適用哪些計量、其範圍、標籤、嚴重程度和順序都由伺服器決定，因此請依原樣呈現各列。

2303

2304* 空陣列表示伺服器未回報任何計量。

2305* `null` 表示 Claude Code 沒有可回報的列。

2306

2307`limits` 的每一列描述一個用量計量：

2308

2309| 欄位 | 類型 | 說明 |

2310| - | - | - |

2311| `kind` | `string` | 伺服器的計量種類，例如 `session`、`weekly_all` 或 `weekly_scoped`。請依此分類列，絕不要依標籤分類 |

2312| `group` | `string` | 伺服器的列群組，例如 `session` 或 `weekly`。各列會依伺服器的順序分組呈現於其下 |

2313| `percent` | `number` | 視窗已使用的比例，0-100 |

2316| `severity` | `string` | 伺服器對該列的判讀，用於計量的顏色，例如 `normal`、`warning` 或 `critical` |

2317| `is_active` | `boolean` | 在伺服器選定供單一值指示器顯示的列上為 `true` |

2318

2319在 Agent SDK v0.3.277 之前，此類型將 `severity` 和 `is_active` 宣告為選用且可為 null，列可能在不帶這兩個欄位的情況下抵達。

2320

2321`extra_usage` 是伺服器回報之該計費期間的[用量點數](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)支出與上限，當方案有用量點數時存在。金額以 `currency` 的最小單位表示，美元為美分。

2322

2323* 當此帳戶沒有自己的支出上限時，`monthly_limit` 為 `null`。在 Team 和 Enterprise 方案上，請勿將 `null` 呈現為無限制。

2324* 當用量點數無法支付請求時，`is_enabled` 為 `false`。

2325

2232<h3 id="sdkmessageorigin">2326<h3 id="sdkmessageorigin">

2233 `SDKMessageOrigin`2327 `SDKMessageOrigin`

2234</h3>2328</h3>

3417type WebFetchInput = {3511type WebFetchInput = {

3418 url: string;3512 url: string;

3419 prompt: string;3513 prompt: string;

3514 offset?: number;

3420};3515};

3421```3516```

3422 3517

3423從 URL 擷取內容並使用 AI 模型進行處理。3518從 URL 擷取內容並使用 AI 模型進行處理。

3424 3519

3520`offset` 是從頁面開頭略過的字元數。Claude 會設定它以繼續閱讀較長的頁面。此欄位需要 Agent SDK v0.3.290 或更新版本。

3521

3425<h3 id="websearch">3522<h3 id="websearch">

3426 WebSearch3523 WebSearch

3427</h3>3524</h3>

5604 task_id: string;5701 task_id: string;

5605 tool_use_id?: string;5702 tool_use_id?: string;

5606 status: "completed" | "failed" | "stopped";5703 status: "completed" | "failed" | "stopped";

5704 reason?: "worker_restart";

5607 output_file: string;5705 output_file: string;

5608 summary: string;5706 summary: string;

5609 ambient?: boolean;5707 ambient?: boolean;

5618};5716};

5619```5717```

5620 5718

5719`reason` 會在工作因其自身完成、失敗或停止以外的原因結束時設定，需要 Agent SDK v0.3.273 或更新版本。Claude Code 僅在透過 claude.ai 連線的工作階段中設定它：雲端工作階段（包括在自我託管執行器上的工作階段）以及 Remote Control 工作階段。本機 `query()` 呼叫永遠不會設定它。其唯一的值 `worker_restart` 表示正在執行該工作的 Claude Code 程序已重新啟動。該通知帶有狀態 `"stopped"`，因此請將該工作視為既未完成也未失敗。

5720

5621當 Claude Code [將長 MCP 工具呼叫移至背景](/docs/zh-TW/mcp#automatic-backgrounding-of-long-tool-calls) 時，該呼叫的 `tool_result` 區塊僅保留預留位置，呼叫的實際結果在此通知中到達。使用 `tool_use_id` 將通知與呼叫進行比對。在 `completed` 通知上，`resource_links` 以 [`SDKMcpResourceLink`](#sdkmcpresourcelink) 項目列出工具透過參考傳回的檔案，具有與 [`tool_use_result.resourceLinks`](#sdkusermessage) 相同的 50 連結和 64 KiB 限制。Claude Code 在結果沒有連結時省略 `resource_links`，在不是 MCP 工具呼叫的工作通知上也會省略。`resource_links` 需要 Agent SDK v0.3.257 或更新版本。5721當 Claude Code [將長 MCP 工具呼叫移至背景](/docs/zh-TW/mcp#automatic-backgrounding-of-long-tool-calls) 時，該呼叫的 `tool_result` 區塊僅保留預留位置，呼叫的實際結果在此通知中到達。使用 `tool_use_id` 將通知與呼叫進行比對。在 `completed` 通知上，`resource_links` 以 [`SDKMcpResourceLink`](#sdkmcpresourcelink) 項目列出工具透過參考傳回的檔案，具有與 [`tool_use_result.resourceLinks`](#sdkusermessage) 相同的 50 連結和 64 KiB 限制。Claude Code 在結果沒有連結時省略 `resource_links`，在不是 MCP 工具呼叫的工作通知上也會省略。`resource_links` 需要 Agent SDK v0.3.257 或更新版本。

5622 5722

5623Claude Code 在傳送給模型的每個工作通知前面加上通知，除了帶有 [`scheduled-trigger` 子類型](#task-notification-subkinds) 戳記的傳遞外，它們改為攜帶指派工作框架。通知指出沒有發生人類輸入，因此模型不會將通知視為使用者指令或核准。5723Claude Code 在傳送給模型的每個工作通知前面加上通知，除了帶有 [`scheduled-trigger` 子類型](#task-notification-subkinds) 戳記的傳遞外，它們改為攜帶指派工作框架。通知指出沒有發生人類輸入，因此模型不會將通知視為使用者指令或核准。

5776 task_type?: string;5876 task_type?: string;

5777 is_backgrounded?: boolean;5877 is_backgrounded?: boolean;

5778 spawn_depth?: number;5878 spawn_depth?: number;

5879 parent_task_id?: string;

5779 ambient?: boolean;5880 ambient?: boolean;

5780 uuid: UUID;5881 uuid: UUID;

5781 session_id: string;5882 session_id: string;

5793 5894

5794[已恢復的 subagent](/docs/zh-TW/agent-sdk/subagents#resume-subagents) 始終報告 `is_backgrounded: true`，因為 Claude Code 在背景執行每個已恢復的 subagent。當前景工作稍後移至背景時，Claude Code 在 [`task_updated`](#sdktaskupdatedmessage) 訊息中報告新的 `is_backgrounded` 值，而不是傳送第二個 `task_started`。5895[已恢復的 subagent](/docs/zh-TW/agent-sdk/subagents#resume-subagents) 始終報告 `is_backgrounded: true`，因為 Claude Code 在背景執行每個已恢復的 subagent。當前景工作稍後移至背景時，Claude Code 在 [`task_updated`](#sdktaskupdatedmessage) 訊息中報告新的 `is_backgrounded` 值，而不是傳送第二個 `task_started`。

5795 5896

5897`parent_task_id` 保存啟動此工作的 subagent 的 `task_id`。使用它將每個工作歸類到啟動它的 subagent 之下。Claude Code 在 subagent、Bash 和 [Monitor](#monitor) 工作上設定它。該欄位需要 Agent SDK v0.3.292 或更新版本。在下列情況下，該欄位不存在：

5898

5899* 主執行緒啟動了該工作

5900* Claude Code 不再追蹤父工作

5901* [隊員](/docs/zh-TW/agent-teams)或工作流程內的 agent 啟動了該工作

5902

5903父工作可能是前景工作或已結束的工作，因此請將您不認識的 ID 視為沒有父工作。

5904

5796<h3 id="sdktaskprogressmessage">5905<h3 id="sdktaskprogressmessage">

5797 `SDKTaskProgressMessage`5906 `SDKTaskProgressMessage`

5798</h3>5907</h3>

5849 `SDKBackgroundTasksChangedMessage`5958 `SDKBackgroundTasksChangedMessage`

5850</h3>5959</h3>

5851 5960

5852每當即時背景工作集變更時發出：工作啟動、完成、被終止、前景 agent 被背景化，或工作的 `description` 或 `ambient` 欄位變更。5961每當即時背景工作集變更時發出：工作啟動、完成或被終止；前景 agent 被背景化；或工作的 `description`、`ambient` 或 `parent_task_id` 欄位變更。如需每個項目上的 `parent_task_id` 欄位，請參閱 [`SDKTaskStartedMessage`](#sdktaskstartedmessage)，它定義了該欄位及其版本要求。

5853 5962

5854`tasks` 陣列是完整的即時集。用每個 payload 替換任何快取集，而不是配對 `task_started` 和 `task_notification` 事件，如此下一個成員資格變更會更正您遺漏的任何事件。5963`tasks` 陣列是完整的即時集。用每個 payload 替換任何快取集，而不是配對 `task_started` 和 `task_notification` 事件，如此下一個成員資格變更會更正您遺漏的任何事件。

5855 5964

5856相對於這些每個工作事件的順序未指定，因此不要關聯兩個串流。5965當工作結束時，其 [`task_updated`](#sdktaskupdatedmessage) 和 [`task_notification`](#sdktasknotificationmessage) 會在將其從清單中移除的 `background_tasks_changed` 之前到達。除此之外，相對於每個工作事件的順序未指定。

5857 5966

5858啟動時不發出任何內容。每當工作階段的 CLI 程序啟動或重新啟動時重設為空集，並讓下一個成員資格變更重新填入它。5967啟動時不發出任何內容。每當工作階段的 CLI 程序啟動或重新啟動時重設為空集，並讓下一個成員資格變更重新填入它。

5859 5968

5870 task_type: string;5979 task_type: string;

5871 subagent_type?: string;5980 subagent_type?: string;

5872 description: string;5981 description: string;

5982 parent_task_id?: string;

5873 ambient?: boolean;5983 ambient?: boolean;

5874 }[];5984 }[];

5875 uuid: UUID;5985 uuid: UUID;

agent-sdk/user-input.md +10 −5

Details

36 ```36 ```

37 37

38 ```typescript TypeScript theme={null}38 ```typescript TypeScript theme={null}

~~39 async function handleToolRequest(toolName, input, options) {~~39 import type { CanUseTool } from "@anthropic-ai/claude-agent-sdk";

41 const handleToolRequest: CanUseTool = async (toolName, input, options) => {

40 // options includes { signal: AbortSignal, suggestions?: PermissionUpdate[] }42 // options includes { signal: AbortSignal, suggestions?: PermissionUpdate[] }

~~41 // 提示使用者並返回允許或拒絕~~43 // 在此提示使用者，然後返回允許或拒絕

~~42 }~~44 return { behavior: "deny", message: "User declined" };

45 };

43 46

44 const options = { canUseTool: handleToolRequest };47 const options = { canUseTool: handleToolRequest };

45 ```48 ```

440 // 在您的工具清單中包含 AskUserQuestion443 // 在您的工具清單中包含 AskUserQuestion

441 tools: ["Read", "Glob", "Grep", "AskUserQuestion"],444 tools: ["Read", "Glob", "Grep", "AskUserQuestion"],

442 canUseTool: async (toolName, input) => {445 canUseTool: async (toolName, input) => {

443 // 在此處處理澄清問題446 // 核准每個呼叫的預留位置。「檢測 AskUserQuestion」步驟會取代它。

447 return { behavior: "allow", updatedInput: input };

444 }448 }

445 }449 }

446 })) {450 })) {

763 767

764 ```typescript TypeScript theme={null}768 ```typescript TypeScript theme={null}

765 import { query } from "@anthropic-ai/claude-agent-sdk";769 import { query } from "@anthropic-ai/claude-agent-sdk";

770 import type { PermissionResult } from "@anthropic-ai/claude-agent-sdk";

766 import * as readline from "readline/promises";771 import * as readline from "readline/promises";

767 772

768 // 幫助程式在終端機中提示使用者輸入773 // 幫助程式在終端機中提示使用者輸入

783 }788 }

784 789

785 // 顯示 Claude 的問題並收集使用者答案790 // 顯示 Claude 的問題並收集使用者答案

786 async function handleAskUserQuestion(input: any) {791 async function handleAskUserQuestion(input: any): Promise<PermissionResult> {

787 const answers: Record<string, string> = {};792 const answers: Record<string, string> = {};

788 793

789 for (const q of input.questions) {794 for (const q of input.questions) {

agent-view.md +21 −12

Details

391 391

392您可以從 agent view 分派新的背景工作階段、將現有的互動式工作階段傳送或複製到背景，或直接從 shell 啟動一個。392您可以從 agent view 分派新的背景工作階段、將現有的互動式工作階段傳送或複製到背景，或直接從 shell 啟動一個。

393 393

394<h3 id="from-agent-view">394<span id="from-agent-view" />

395 從 agent view395

396<h3 id="dispatch-an-agent-from-agent-view">

397 從 agent view 分派 agent

396</h3>398</h3>

397 399

398在 agent view 底部的輸入框中輸入提示詞，然後按 `Enter` 即可啟動新的背景工作階段。工作階段會根據提示詞自動命名；稍後可以使用 `Ctrl+R` 重新命名。400在 agent view 底部的輸入框中輸入提示詞，然後按 `Enter` 即可啟動新的背景工作階段。工作階段會根據提示詞自動命名；稍後可以使用 `Ctrl+R` 重新命名。

446 448

447當 agent view 依目錄分組時，分派會將提示詞傳送到所選列的目錄，因此您可以選取一個群組並分派到其中，而無需重新輸入路徑。449當 agent view 依目錄分組時，分派會將提示詞傳送到所選列的目錄，因此您可以選取一個群組並分派到其中，而無需重新輸入路徑。

448 450

449<h3 id="from-inside-a-session">451<span id="from-inside-a-session" />

450 從工作階段內部452

453<h3 id="send-or-copy-a-session-to-the-background">

454 將工作階段傳送或複製到背景

451</h3>455</h3>

452 456

453有兩個命令可將工作從您所在的工作階段移到背景：`/background` 會將目前的對話傳送到背景並釋放您的終端機，而 `/fork` 會傳送一份副本，讓您在原處繼續工作。457有兩個命令可將工作從您所在的工作階段移到背景：`/background` 會將目前的對話傳送到背景並釋放您的終端機，而 `/fork` 會傳送一份副本，讓您在原處繼續工作。

511 515

512您在工作階段期間使用 [`/add-dir`](/docs/zh-TW/permissions#additional-directories-grant-file-access-not-configuration) 新增的目錄也會一併帶入。帶入 `--allow-dangerously-skip-permissions` 會讓 `bypassPermissions` 在已移到背景的工作階段中保持可用，但不會授予任何新的權限：該模式仍需要[權限模式、模型與 effort](#permission-mode-model-and-effort) 中所述的一次性互動式接受。516您在工作階段期間使用 [`/add-dir`](/docs/zh-TW/permissions#additional-directories-grant-file-access-not-configuration) 新增的目錄也會一併帶入。帶入 `--allow-dangerously-skip-permissions` 會讓 `bypassPermissions` 在已移到背景的工作階段中保持可用，但不會授予任何新的權限：該模式仍需要[權限模式、模型與 effort](#permission-mode-model-and-effort) 中所述的一次性互動式接受。

513 517

514<h3 id="from-your-shell">518<span id="from-your-shell" />

515 從您的 shell519

520<h3 id="dispatch-an-agent-from-your-shell">

521 從您的 shell 分派 agent

516</h3>522</h3>

517 523

518傳遞 `--bg` 或其完整形式 `--background`，即可啟動直接進入背景的工作階段：524傳遞 `--bg` 或其完整形式 `--background`，即可啟動直接進入背景的工作階段：

603 609

604在 git 儲存庫外，工作階段會直接寫入工作目錄，彼此之間沒有隔離，因此請避免分派會編輯相同檔案的平行工作階段。如果您使用其他版本控制系統，請設定 [`WorktreeCreate` hook](/docs/zh-TW/worktrees#non-git-version-control)，Claude 就會以與 git 相同的方式隔離編輯。610在 git 儲存庫外，工作階段會直接寫入工作目錄，彼此之間沒有隔離，因此請避免分派會編輯相同檔案的平行工作階段。如果您使用其他版本控制系統，請設定 [`WorktreeCreate` hook](/docs/zh-TW/worktrees#non-git-version-control)，Claude 就會以與 git 相同的方式隔離編輯。

605 611

606當 hook 在非 git 儲存庫的目錄中失敗時，Claude 會略過該目錄的隔離，並就地編輯工作目錄。在 git 儲存庫內，Claude 會在編輯前移入 worktree 的工作階段，在該移動發生之前無法編輯共用簽出中的檔案。612當 hook 在非 git 儲存庫的目錄中失敗時，Claude 會略過該目錄的隔離，並就地編輯工作目錄。在 git 儲存庫內，Claude 會在編輯前移入 worktree 的工作階段，在該移動發生之前無法對共用簽出使用 `Edit`、`Write` 或 `NotebookEdit` 工具。

607 613

608若要找到工作階段的 worktree 路徑，請附加並檢查其工作目錄。614若要找到工作階段的 worktree 路徑，請附加並檢查其工作目錄。

609 615

826| `claude daemon stop --any` | 停止 supervisor 程序及其託管的背景工作階段。傳遞 `--keep-workers` 以保持背景工作階段執行中，以便下一個 supervisor 可以重新連接到它們。下一個 `claude agents` 或 `claude --bg` 會啟動全新的 supervisor |832| `claude daemon stop --any` | 停止 supervisor 程序及其託管的背景工作階段。傳遞 `--keep-workers` 以保持背景工作階段執行中，以便下一個 supervisor 可以重新連接到它們。下一個 `claude agents` 或 `claude --bg` 會啟動全新的 supervisor |

827 833

828`claude attach` 和 `claude logs` 可以使用執行中工作階段名稱的一部分來取代 ID，例如 `claude logs "auth refactor"`。傳遞名稱需要 Claude Code v2.1.290 或更新版本。834`claude attach` 和 `claude logs` 可以使用工作階段名稱的一部分來取代 ID，例如 `claude logs "auth refactor"`。傳遞名稱需要 Claude Code v2.1.290 或更新版本。

829 835

830<h3 id="list-sessions-as-json">836<h3 id="list-sessions-as-json">

831 將工作階段列為 JSON837 將工作階段列為 JSON

979 開啟工作階段時顯示它沒有已儲存的逐字稿985 開啟工作階段時顯示它沒有已儲存的逐字稿

980</h3>986</h3>

981 987

982從[另一個對話背景化](#from-inside-a-session)且在第一個回應完成之前就停止的工作階段，沒有可恢復的內容：在第一個回應完成之前，對話仍然只存在於它被背景化的來源工作階段中。`claude attach` 會拒絕開啟它，並顯示 `This session has no saved transcript`。988當您開啟一個從[另一個對話背景化](#from-inside-a-session)、且在執行自己的回合之前就已停止的工作階段時，Claude Code 會恢復該對話。如果 Claude Code 找不到該對話，則會拒絕開啟該工作階段：

989

990* `claude attach` 會列印 `This session has no saved transcript`。

991* Agent view 會在清單下方顯示 `Press enter again to restart this session fresh`。

983 992

984在 agent view 中，開啟該列會在清單下方顯示 `Press enter again to restart this session fresh`。在同一列上再次按 `Enter` 以使用空對話重新啟動工作階段，或從 shell 執行 `claude respawn <id>`。993在同一列上再次按 `Enter` 以使用空對話重新啟動工作階段，或從 shell 執行 `claude respawn <id>`。

985 994

986原始對話完整無缺；使用 `claude --resume` 恢復它或繼續在其中工作。請參閱[錯誤參考](/docs/zh-TW/errors#this-session-has-no-saved-transcript)以取得詳細資訊。995請參閱[錯誤參考](/docs/zh-TW/errors#this-session-has-no-saved-transcript)以取得詳細資訊。

987 996

988<h3 id="the-terminal-host-died-or-the-session-stopped-responding">997<h3 id="the-terminal-host-died-or-the-session-stopped-responding">

989 終端機主機已終止或工作階段停止回應998 終端機主機已終止或工作階段停止回應

1095 1104

1096| 版本 | 變更 |1105| 版本 | 變更 |

1097| - | - |1106| - | - |

1098| v2.1.290 | [`claude attach` 和 `claude logs`](#manage-sessions-from-the-shell) 可以接受執行中工作階段名稱的一部分來取代 ID。 |1107| v2.1.290 | [`claude attach` 和 `claude logs`](#manage-sessions-from-the-shell) 可以接受工作階段名稱的一部分來取代 ID。 |

1099| v2.1.290 | 作為[查看回覆](#peek-and-reply)傳送給工作中工作階段的 `/model`、`/effort`、`/rename` 和 `/usage` 會立即執行。 |1108| v2.1.290 | 作為[查看回覆](#peek-and-reply)傳送給工作中工作階段的 `/model`、`/effort`、`/rename` 和 `/usage` 會立即執行。 |

1100| v2.1.290 | 無法傳遞的[查看回覆](#peek-and-reply)在以 `/` 開頭時，或在工作階段的程序執行期間回答具有預定義選項的問題時，不再被儲存以供下次重新啟動時使用。 |1109| v2.1.290 | 無法傳遞的[查看回覆](#peek-and-reply)在以 `/` 開頭時，或在工作階段的程序執行期間回答具有預定義選項的問題時，不再被儲存以供下次重新啟動時使用。 |

1101| v2.1.288 | `Ctrl+F` 會依名稱尋找工作階段，`Alt+↑` / `Alt+↓` 會在群組標題之間跳轉。這兩者以及 `Ctrl+R` 都可以[重新繫結](/docs/zh-TW/keybindings#agents-actions)。 |1110| v2.1.288 | `Ctrl+F` 會依名稱尋找工作階段，`Alt+↑` / `Alt+↓` 會在群組標題之間跳轉。這兩者以及 `Ctrl+R` 都可以[重新繫結](/docs/zh-TW/keybindings#agents-actions)。 |

chrome.md +39 −2

Details

202and attach logs/session.log to it202and attach logs/session.log to it

203```203```

204 204

205上傳適用三項限制：205如果 Claude 拒絕附加檔案或上傳失敗，請檢查以下原因：

206 206

207* **權限**：只有在工作階段被允許讀取檔案時，Claude 才能上傳該檔案，因此拒絕對檔案進行 `Read` 存取的[權限規則](/docs/zh-TW/settings-reference#permission-settings)也會阻止上傳該檔案。207* **權限**：只有在工作階段被允許讀取檔案時，Claude 才能上傳該檔案，因此拒絕對檔案進行 `Read` 存取的[權限規則](/docs/zh-TW/settings-reference#permission-settings)也會阻止上傳該檔案。

208* **大小**：單次上傳的檔案總計最多可達 10 MB。208* **大小**：單次上傳的檔案總計最多可達 10 MB。

209* **硬連結**：Claude 會拒絕具有多個硬連結的檔案，這在 `node_modules` 等套件管理器儲存區中很常見。請複製該檔案並上傳副本。209* **硬連結**：Claude 會拒絕具有多個硬連結的檔案，這在 `node_modules` 等套件管理器儲存區中很常見。請複製該檔案並上傳副本。

210* **憑證名稱**：如果檔案的名稱或所在資料夾屬於通常存放憑證的位置，例如 `.env`、`.pem` 或 `.key` 檔案，或 `.ssh` 下的任何內容，Claude 會拒絕該檔案。需要 Claude Code v2.1.293 或更新版本。

210 211

211<h3 id="draft-content-in-google-docs">212<h3 id="draft-content-in-google-docs">

212 在 Google Docs 中起草內容213 在 Google Docs 中起草內容

309 310

310其他基於 Chromium 的瀏覽器會從各自以瀏覽器命名的設定目錄中讀取相同的檔案。例如，macOS 上的 Brave 使用 `~/Library/Application Support/BraveSoftware/Brave-Browser/NativeMessagingHosts/`，而在 Windows 上，每個瀏覽器都有自己的登錄機碼，例如 `HKCU\Software\BraveSoftware\Brave-Browser\NativeMessagingHosts\`。311其他基於 Chromium 的瀏覽器會從各自以瀏覽器命名的設定目錄中讀取相同的檔案。例如，macOS 上的 Brave 使用 `~/Library/Application Support/BraveSoftware/Brave-Browser/NativeMessagingHosts/`，而在 Windows 上，每個瀏覽器都有自己的登錄機碼，例如 `HKCU\Software\BraveSoftware\Brave-Browser\NativeMessagingHosts\`。

311 312

313<h3 id="project-settings-can’t-turn-on-chrome">

314 專案設定無法開啟 Chrome

315</h3>

316

317終端機中出現此警告，表示您正在使用的專案嘗試開啟 Chrome 整合，而 Claude Code 不允許：

318

319```text wrap theme={null}

320Claude Code ignored CLAUDE_CODE_ENABLE_CFC in this project's settings: a project can't turn on Claude in Chrome. To turn it on yourself, run /chrome or start with --chrome.

321```

322

323該專案的 `.claude/settings.json` 或 `.claude/settings.local.json` 在其 `env` 區塊中將 [`CLAUDE_CODE_ENABLE_CFC`](/docs/zh-TW/env-vars#variables) 設為 `1`，以開啟 Chrome 整合。Claude Code 並未套用該設定，因此此工作階段中的 Chrome 整合處於關閉狀態，Claude 沒有瀏覽器工具。

324

325Claude Code 會略過此設定，因為這些檔案儲存在專案目錄中，而您簽出的儲存庫不應能夠將 Claude 連接到您的瀏覽器。

326

327您可以照常繼續工作。如果您想要使用瀏覽器工具，或希望警告消失，請執行下列其中一項：

328

329* **立即取得瀏覽器工具**：結束後在 shell 中以 `claude --chrome` 重新啟動。

330* **在之後的工作階段中取得瀏覽器工具**：在 Claude Code 提示字元中執行 `/chrome`，並選擇[**預設啟用**](#enable-chrome-by-default)。這會套用於之後啟動的工作階段，而不是目前正在執行的工作階段。

331* **停止警告且不使用瀏覽器工具**：從專案的設定檔中移除 `CLAUDE_CODE_ENABLE_CFC` 這一行。

332

312<h3 id="browser-not-responding">333<h3 id="browser-not-responding">

313 瀏覽器無回應334 瀏覽器無回應

314</h3>335</h3>

325 346

326Chrome 擴充功能的服務工作者可能在延長的工作階段期間進入閒置狀態，這會中斷連接。如果瀏覽器工具在一段時間不活動後停止工作，請執行 `/chrome` 並選擇「重新連接擴充功能」。347Chrome 擴充功能的服務工作者可能在延長的工作階段期間進入閒置狀態，這會中斷連接。如果瀏覽器工具在一段時間不活動後停止工作，請執行 `/chrome` 並選擇「重新連接擴充功能」。

327 348

349執行 `/chrome` 時，請查看其 `Status` 行。如果顯示「Not connected」，表示目前執行中的工作階段本身與 Chrome 的連接已失敗。選擇「重新連接擴充功能」以重新啟動該連接。連接成功後，擴充功能的重新連接頁面會在 Chrome 中開啟。在 v2.1.290 之前，「重新連接擴充功能」只會開啟該頁面，而不會重新啟動失敗的連接，因此如果在較早版本上瀏覽器工具沒有恢復，請更新 Claude Code。

350

351<h3 id="extension-signed-in-to-a-different-organization">

352 擴充功能登入了不同的組織

353</h3>

354

355如果您隸屬於多個 claude.ai 組織，擴充功能必須登入與 Claude Code 相同的組織。如果兩者不同，即使兩者使用相同的 claude.ai 帳戶，Claude 的瀏覽器工具也會回傳「Browser extension is not connected」。

356

357若要查看 Claude Code 登入的是哪個組織，請在 Claude Code 提示字元中執行 [`/status`](/docs/zh-TW/commands)，並查看 `Organization` 列。

358

359<Warning>

360 如果您登出擴充功能，將會失去儲存在其中的捷徑和排程任務。請先嘗試[常見錯誤訊息](#common-error-messages)下的其他修復方法。

361</Warning>

362

363若要變更擴充功能的組織，請在擴充功能的設定中登出，然後登入並選擇 `/status` 所顯示的組織。

364

328<h3 id="windows-specific-issues">365<h3 id="windows-specific-issues">

329 Windows 特定問題366 Windows 特定問題

330</h3>367</h3>

343 380

344| 錯誤 | 原因 | 修復 |381| 錯誤 | 原因 | 修復 |

345| - | - | - |382| - | - | - |

346| 「瀏覽器擴充功能未連接」 | 原生訊息主機無法到達擴充功能，或您組織的 IP 允許清單拒絕了與 `bridge.claudeusercontent.com` 的連接 | 檢查擴充功能是否已登入與 Claude Code 相同的 claude.ai 帳戶，重新啟動 Chrome 和 Claude Code，然後執行 `/chrome` 以重新連接。如果您的組織使用 IP 允許清單且錯誤仍然存在，請參閱[組織 IP 允許清單與代理伺服器出口流量](/docs/zh-TW/network-config#organization-ip-allowlists-and-proxy-egress) |383| 「Browser extension is not connected」 | 擴充功能未在 Chrome 中安裝並執行、擴充功能登入的 claude.ai 帳戶或組織與 Claude Code 不同，或您組織的 IP 允許清單拒絕了與 `bridge.claudeusercontent.com` 的連接 | 檢查擴充功能是否已登入與 Claude Code 相同的 claude.ai 帳戶和[組織](#extension-signed-in-to-a-different-organization)，重新啟動 Chrome 和 Claude Code，然後執行 `/chrome` 以重新連接。如果您的組織使用 IP 允許清單且錯誤仍然存在，請參閱[組織 IP 允許清單與代理伺服器出口流量](/docs/zh-TW/network-config#organization-ip-allowlists-and-proxy-egress) |

claude-apps-gateway-config.md +21 −1

Details

1235 1235

1236CLI 將指標、日誌和（啟用時）追蹤傳送到 gateway，gateway 逐字轉發到每個已設定的目的地。匯出使用 OpenTelemetry Protocol (OTLP) over HTTP。要跳過轉發並讓工作階段直接匯出到您的收集器，[在原則中命名收集器](#export-directly-to-your-collector)。請參閱[監控使用](/docs/zh-TW/monitoring-usage)以了解 CLI 發出的指標和事件。1236CLI 將指標、日誌和（啟用時）追蹤傳送到 gateway，gateway 逐字轉發到每個已設定的目的地。匯出使用 OpenTelemetry Protocol (OTLP) over HTTP。要跳過轉發並讓工作階段直接匯出到您的收集器，[在原則中命名收集器](#export-directly-to-your-collector)。請參閱[監控使用](/docs/zh-TW/monitoring-usage)以了解 CLI 發出的指標和事件。

1237 1237

1238在透過 `/login` 登入的工作階段中，CLI 使用從 gateway 發行的 JWT 讀取的已驗證使用者的身分戳記每個匯出：`user.id`、`user.email` 和 `user.groups` 屬性。每位開發者成本和使用歸因因此無需開發者端設定即可運作。1238在透過 `/login` 登入的工作階段中，CLI 會為每筆匯出標記已驗證使用者的身分，這些身分讀取自閘道簽發的 JWT：`user.id`、`user.email` 與 `user.groups` 屬性。因此，每位開發人員的成本與使用量歸屬無需開發人員端的任何設定即可運作。Claude Code 在開發人員登入前記錄的事件[不帶有此身分](/docs/zh-TW/monitoring-usage#standard-attributes)。若要了解哪個屬性會跟隨開發人員群組的變更，請參閱[開啟中工作階段期間的群組變更](#group-changes-during-an-open-session)。

1239 1239

1240[Claude Desktop](#claude-desktop-overlay) 和透過 gateway 登入的 Cowork 工作階段使用 `user.email` 和 `user.groups` 以及 `enduser.id` 戳記其遙測，因此您可以使用一個 `user.email` 或 `user.groups` 查詢涵蓋終端機、Desktop 和 Cowork 使用。`user.groups` 是逗號分隔的 IdP 群組清單。1240[Claude Desktop](#claude-desktop-overlay) 和透過 gateway 登入的 Cowork 工作階段使用 `user.email` 和 `user.groups` 以及 `enduser.id` 戳記其遙測，因此您可以使用一個 `user.email` 或 `user.groups` 查詢涵蓋終端機、Desktop 和 Cowork 使用。`user.groups` 是逗號分隔的 IdP 群組清單。

1241 1241

1345 1345

1346Claude Code 也將每個標籤複製到每個指標資料點，因此您可以在不索引資源屬性的後端中按它篩選指標。要關閉該複製，請參閱[指標基數控制](/docs/zh-TW/monitoring-usage#metrics-cardinality-control)。1346Claude Code 也將每個標籤複製到每個指標資料點，因此您可以在不索引資源屬性的後端中按它篩選指標。要關閉該複製，請參閱[指標基數控制](/docs/zh-TW/monitoring-usage#metrics-cardinality-control)。

1347 1347

1348<h4 id="group-changes-during-an-open-session">

1349 開啟中工作階段期間的群組變更

1350</h4>

1351

1352終端機工作階段會將 `user.groups` 放在 OTLP 資源上，並再次放在每個指標資料點與事件上。若開發人員的群組在工作階段開啟期間變更，下一次[靜默重新整理](#session)之後的使用量所對應的資料點與事件會帶有新的群組。資源會保留舊的群組，直到開發人員重新啟動 Claude Code 為止，因此請依資料點或事件上的屬性進行分組。

1353

1354若您在 OpenTelemetry Collector 的 Prometheus remote write 匯出器中開啟 `resource_to_telemetry_conversion`，匯出器會以資源的 `user.groups` 取代每個資料點的 `user.groups`，因此每個資料點都會顯示舊的群組。若要保留資料點的值，請在該匯出器之前從資源中刪除 `user.groups`。

1355

1356以下 OpenTelemetry Collector `resource` 處理器會在列出它的管線中刪除該屬性：

1357

1358```yaml theme={null}

1359processors:

1360 resource/drop-user-groups:

1361 attributes:

1362 - key: user.groups

1363 action: delete

1364```

1365

1366將 `resource/drop-user-groups` 新增至指標管線的 `processors` 後，每個序列都會帶有來自其自身資料點的 `user_groups` 標籤。

1367

1348<h4 id="export-directly-to-your-collector">1368<h4 id="export-directly-to-your-collector">

1349 直接匯出到您的收集器1369 直接匯出到您的收集器

1350</h4>1370</h4>

claude-apps-gateway-on-aws.md +1 −1

Details

515 遙測515 遙測

516</h2>516</h2>

517 517

518閘道為您提供每位開發者的使用指標，無需任何每台機器的 OTEL 設定。Claude Code 發出 OpenTelemetry (OTLP) 指標、日誌和選擇性追蹤；[監控使用情況](/docs/zh-TW/monitoring-usage)涵蓋 CLI 報告的所有內容。在透過 `/login` 登入的工作階段中，CLI 會使用已驗證的 IdP 身分屬性 `user.id`、`user.email` 和 `user.groups` 為每個匯出加上戳記，因此使用情況會按開發者彙總。518閘道為您提供每位開發者的使用指標，無需任何每台機器的 OTEL 設定。Claude Code 發出 OpenTelemetry (OTLP) 指標、日誌和選擇性追蹤；[監控使用情況](/docs/zh-TW/monitoring-usage)涵蓋 CLI 報告的所有內容。在透過 `/login` 登入的工作階段中，CLI 會使用已驗證的 IdP 身分屬性 `user.id`、`user.email` 和 `user.groups` [為每個匯出加上戳記](/docs/zh-TW/monitoring-usage#standard-attributes)，因此使用情況會按開發者彙總。

519 519

520閘道本身是一個已驗證的 OTLP 中繼。將 [`telemetry.forward_to`](/docs/zh-TW/claude-apps-gateway-config#telemetry) 與 `listen.public_url` 一起設定，它會將 OTEL 匯出器設定推送到每個連接的用戶端，並將其 OTLP 流量逐字轉發到您列出的每個目的地。每個目的地獨立選擇加入指標、日誌和追蹤，預設值為僅限指標；請參閱 [`telemetry` 參考](/docs/zh-TW/claude-apps-gateway-config#telemetry)以了解每個信號欄位及其敏感性權衡。閘道不會緩衝、彙總或儲存遙測，因此資料最終位置完全由收集器的匯出器設定決定。520閘道本身是一個已驗證的 OTLP 中繼。將 [`telemetry.forward_to`](/docs/zh-TW/claude-apps-gateway-config#telemetry) 與 `listen.public_url` 一起設定，它會將 OTEL 匯出器設定推送到每個連接的用戶端，並將其 OTLP 流量逐字轉發到您列出的每個目的地。每個目的地獨立選擇加入指標、日誌和追蹤，預設值為僅限指標；請參閱 [`telemetry` 參考](/docs/zh-TW/claude-apps-gateway-config#telemetry)以了解每個信號欄位及其敏感性權衡。閘道不會緩衝、彙總或儲存遙測，因此資料最終位置完全由收集器的匯出器設定決定。

521 521

claude-code-on-the-web.md +9 −5

Details

91 從 CLI，工作階段交接是單向的：您可以使用 `--teleport` 將雲端工作階段拉入您的終端機，但您無法將現有的終端機工作階段推送到雲端。`--cloud` 旗標搭配任務描述會為您目前的儲存庫建立新的雲端工作階段；搭配 `-p` 和工作階段 ID 或 claude.ai/code URL 時，它會改為 [將訊息加入該現有工作階段的佇列](/docs/zh-TW/claude-code-on-the-web#send-follow-ups-from-the-cli)。[桌面應用程式](/docs/zh-TW/desktop#continue-in-another-surface) 可以從其 **Open in** 功能表，將其 Code 分頁中的本機工作階段傳送到雲端。91 從 CLI，工作階段交接是單向的：您可以使用 `--teleport` 將雲端工作階段拉入您的終端機，但您無法將現有的終端機工作階段推送到雲端。`--cloud` 旗標搭配任務描述會為您目前的儲存庫建立新的雲端工作階段；搭配 `-p` 和工作階段 ID 或 claude.ai/code URL 時，它會改為 [將訊息加入該現有工作階段的佇列](/docs/zh-TW/claude-code-on-the-web#send-follow-ups-from-the-cli)。[桌面應用程式](/docs/zh-TW/desktop#continue-in-another-surface) 可以從其 **Open in** 功能表，將其 Code 分頁中的本機工作階段傳送到雲端。

92</Note>92</Note>

93 93

~~94<h3 id="from-terminal-to-cloud">~~94<span id="from-terminal-to-cloud" />

~~95 從終端機到雲端~~95

96<h3 id="start-a-cloud-session-from-your-terminal">

97 從終端機啟動雲端工作階段

96</h3>98</h3>

97 99

98使用 `--cloud` 旗標從命令列啟動雲端工作階段：100使用 `--cloud` 旗標從命令列啟動雲端工作階段：

215 217

216如果傳送失敗，請參閱 [傳送到雲端工作階段時的錯誤](#errors-when-sending-to-a-cloud-session)。218如果傳送失敗，請參閱 [傳送到雲端工作階段時的錯誤](#errors-when-sending-to-a-cloud-session)。

217 219

218<h3 id="from-cloud-to-terminal">220<span id="from-cloud-to-terminal" />

219 從雲端到終端機221

222<h3 id="continue-a-cloud-session-in-your-terminal">

223 在終端機中繼續雲端工作階段

220</h3>224</h3>

221 225

222使用以下任何方式將雲端工作階段拉入您的終端機：226使用以下任何方式將雲端工作階段拉入您的終端機：

483從 [claude.ai/code](https://claude.ai/code) 重新開啟工作階段以佈建新 VM：487從 [claude.ai/code](https://claude.ai/code) 重新開啟工作階段以佈建新 VM：

484 488

485* **會恢復**：您的對話歷史記錄489* **會恢復**：您的對話歷史記錄

486* **不會恢復**：在 VM 被回收時仍在執行的背景工作，例如 subagents 和 shell 命令490* **不會恢復**：在 VM 被回收時仍在執行的背景工作，例如 subagents 和 shell 命令，以及[自行決定節奏的 `/loop`](/docs/zh-TW/scheduled-tasks#let-claude-choose-the-interval) 尚待執行的喚醒。若要重新啟動迴圈，請再次執行 `/loop`。

487 491

488<h2 id="limitations">492<h2 id="limitations">

489 限制493 限制

claude-projects.md +1 −1

Details

489* **Routines**：當您在 project 中要求排程工作時，Claude 建立一個 [routine](/docs/zh-TW/routines)，在該 project 中作為執行緒執行，並出現在其 **Routines** 標籤上。您在 project 外建立的 Routines 保持自己工作。489* **Routines**：當您在 project 中要求排程工作時，Claude 建立一個 [routine](/docs/zh-TW/routines)，在該 project 中作為執行緒執行，並出現在其 **Routines** 標籤上。您在 project 外建立的 Routines 保持自己工作。

490* **Remote Control**：[Remote Control](/docs/zh-TW/remote-control) 連接 claude.ai 到在您機器上執行的 Claude Code 工作階段。當您在 project 中要求 Claude 在您的電腦上執行執行緒時，project [使用 Remote Control 來執行它](#run-a-thread-on-your-own-computer)。490* **Remote Control**：[Remote Control](/docs/zh-TW/remote-control) 連接 claude.ai 到在您機器上執行的 Claude Code 工作階段。當您在 project 中要求 Claude 在您的電腦上執行執行緒時，project [使用 Remote Control 來執行它](#run-a-thread-on-your-own-computer)。

491* **本地工作階段和代理檢視**：您在終端、IDE 或桌面應用程式的本地環境中啟動的工作階段無法新增到 project。[代理檢視](/docs/zh-TW/agent-view) 是用於並排追蹤多個本地工作階段的螢幕，您仍然自己啟動每個工作階段並給它其任務。491* **本地工作階段和代理檢視**：您在終端、IDE 或桌面應用程式的本地環境中啟動的工作階段無法新增到 project。[代理檢視](/docs/zh-TW/agent-view) 是用於並排追蹤多個本地工作階段的螢幕，您仍然自己啟動每個工作階段並給它其任務。

492* **Worktrees**：[worktree](/docs/zh-TW/worktrees) 給每個本地工作階段其自己的儲存庫工作副本，因此您機器上的平行工作階段不會相互覆蓋。雲端執行緒不需要它們：每個執行緒將其儲存庫克隆到其自己的雲端沙箱中，並在自己的分支上工作。492* **Worktrees**：[worktree](/docs/zh-TW/worktrees) 給每個本機工作階段其自己的儲存庫工作副本。雲端執行緒不需要它們：每個執行緒將其儲存庫克隆到其自己的雲端沙箱中，並在自己的分支上工作。

493* **代理團隊**：[代理團隊](/docs/zh-TW/agent-teams) 是一個工作階段，為單個任務啟動隊友工作階段，在您的機器上或在雲端工作階段內，並以該任務結束。493* **代理團隊**：[代理團隊](/docs/zh-TW/agent-teams) 是一個工作階段，為單個任務啟動隊友工作階段，在您的機器上或在雲端工作階段內，並以該任務結束。

494* **Subagents**：[subagent](/docs/zh-TW/sub-agents) 在一個工作階段內執行，在其自己的內容視窗中執行側面任務，並將摘要返回到該工作階段。project 的執行緒是 Claude 啟動的完整工作階段，並向 project 對話報告，執行緒仍然可以為其自己的側面任務使用 subagents。494* **Subagents**：[subagent](/docs/zh-TW/sub-agents) 在一個工作階段內執行，在其自己的內容視窗中執行側面任務，並將摘要返回到該工作階段。project 的執行緒是 Claude 啟動的完整工作階段，並向 project 對話報告，執行緒仍然可以為其自己的側面任務使用 subagents。

495* **claude.ai 聊天和 Cowork 中的 Projects**：[早期 Projects 體驗](https://support.claude.com/en/articles/9517075-what-are-projects)，它對話和參考檔案進行分組，沒有執行緒或協調者。那些 projects 保持今天的工作方式，直到重新設計的體驗到達它們。495* **claude.ai 聊天和 Cowork 中的 Projects**：[早期 Projects 體驗](https://support.claude.com/en/articles/9517075-what-are-projects)，它對話和參考檔案進行分組，沒有執行緒或協調者。那些 projects 保持今天的工作方式，直到重新設計的體驗到達它們。

cli-reference.md +4 −4

Details

29| `claude auth status` | 以 JSON 格式顯示身分驗證狀態。使用 `--text` 以人類可讀的格式輸出。如果已登入則以代碼 0 退出，如果未登入則以代碼 1 退出。JSON 包含一個 `configDirectory` 欄位，命名 CLI 使用的 [設定目錄](/docs/zh-TW/claude-directory)。該欄位需要 Claude Code v2.1.268 或更新版本。JSON 的 `authMethod` 欄位為 `none`、`claude.ai`、`oauth_token`、`api_key`、`api_key_helper` 或 `third_party` 其中之一 | `claude auth status` |29| `claude auth status` | 以 JSON 格式顯示身分驗證狀態。使用 `--text` 以人類可讀的格式輸出。如果已登入則以代碼 0 退出，如果未登入則以代碼 1 退出。JSON 包含一個 `configDirectory` 欄位，命名 CLI 使用的 [設定目錄](/docs/zh-TW/claude-directory)。該欄位需要 Claude Code v2.1.268 或更新版本。JSON 的 `authMethod` 欄位為 `none`、`claude.ai`、`oauth_token`、`api_key`、`api_key_helper` 或 `third_party` 其中之一 | `claude auth status` |

30| `claude agents` | 開啟 [agent 檢視](/docs/zh-TW/agent-view) 以監控和分派平行背景工作階段。使用 `--cwd <path>` 僅顯示在該目錄下啟動的工作階段，或使用 `--json` 將作用中工作階段列印為 JSON 陣列以供指令碼使用（`--json --all` 也包括已完成的背景工作階段）。傳遞 `--permission-mode`、`--model`、`--effort` 或 `--agent` 以設定 [分派工作階段的預設值](/docs/zh-TW/agent-view#permission-mode-model-and-effort)。接受 `--settings`、`--add-dir`、`--plugin-dir` 和 `--mcp-config`，如同頂層 `claude` 命令。開啟 agent 檢視需要互動式終端機 | `claude agents --json` |30| `claude agents` | 開啟 [agent 檢視](/docs/zh-TW/agent-view) 以監控和分派平行背景工作階段。使用 `--cwd <path>` 僅顯示在該目錄下啟動的工作階段，或使用 `--json` 將作用中工作階段列印為 JSON 陣列以供指令碼使用（`--json --all` 也包括已完成的背景工作階段）。傳遞 `--permission-mode`、`--model`、`--effort` 或 `--agent` 以設定 [分派工作階段的預設值](/docs/zh-TW/agent-view#permission-mode-model-and-effort)。接受 `--settings`、`--add-dir`、`--plugin-dir` 和 `--mcp-config`，如同頂層 `claude` 命令。開啟 agent 檢視需要互動式終端機 | `claude agents --json` |

32| `claude auto-mode defaults` | 以 JSON 格式列印內建 [自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 分類器規則。使用 `claude auto-mode config` 查看應用了設定的有效設定。使用 `--label <prefix>` 僅列印標籤以該前綴開頭的規則，不區分大小寫。需要 Claude Code v2.1.208 或更新版本 | `claude auto-mode defaults --label 'Git Destructive'` |32| `claude auto-mode defaults` | 以 JSON 格式列印內建 [自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 分類器規則。使用 `claude auto-mode config` 查看應用了設定的有效設定。使用 `--label <prefix>` 僅列印標籤以該前綴開頭的規則，不區分大小寫。需要 Claude Code v2.1.208 或更新版本 | `claude auto-mode defaults --label 'Git Destructive'` |

33| `claude auto-mode reset` | 透過從使用者設定檔案中移除 `autoMode` 部分來還原預設 [自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 設定。在寫入前提示確認；傳遞 `-y`/`--yes` 以跳過提示。來自 [受管設定](/docs/zh-TW/server-managed-settings) 或 `--settings` 旗標的規則仍然適用。需要 Claude Code v2.1.212 或更新版本。請參閱 [檢查預設值和您的有效設定](/docs/zh-TW/auto-mode-config#inspect-the-defaults-and-your-effective-config) | `claude auto-mode reset --yes` |33| `claude auto-mode reset` | 透過從使用者設定檔案中移除 `autoMode` 部分來還原預設 [自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 設定。在寫入前提示確認；傳遞 `-y`/`--yes` 以跳過提示。來自 [受管設定](/docs/zh-TW/server-managed-settings) 或 `--settings` 旗標的規則仍然適用。需要 Claude Code v2.1.212 或更新版本。請參閱 [檢查預設值和您的有效設定](/docs/zh-TW/auto-mode-config#inspect-the-defaults-and-your-effective-config) | `claude auto-mode reset --yes` |

37| `claude daemon stop --any` | 停止背景工作階段 [監督程序](/docs/zh-TW/agent-view#the-supervisor-process) 及其託管的工作階段。傳遞 `--keep-workers` 以保持背景工作階段執行，以便下一個監督程序重新連接到它們。`--any` 確認停止隨需監督程序，這是預設值。使用此命令從 [無回應的監督程序](/docs/zh-TW/agent-view#agent-view-says-the-background-service-did-not-respond) 復原 | `claude daemon stop --any --keep-workers` |37| `claude daemon stop --any` | 停止背景工作階段 [監督程序](/docs/zh-TW/agent-view#the-supervisor-process) 及其託管的工作階段。傳遞 `--keep-workers` 以保持背景工作階段執行，以便下一個監督程序重新連接到它們。`--any` 確認停止隨需監督程序，這是預設值。使用此命令從 [無回應的監督程序](/docs/zh-TW/agent-view#agent-view-says-the-background-service-did-not-respond) 復原 | `claude daemon stop --any --keep-workers` |

39| `claude import [source]` | 啟動互動式工作階段，執行 [`/import`](/docs/zh-TW/commands#all-commands) 以將其他編碼 agent 的設定帶入 Claude Code。接受與命令相同的 `--dry-run` 和 `--yes` 選項。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 AWS 上的 Claude Platform 上不可用。當您關閉 [功能旗標擷取](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching) 時也不可用。需要 Claude Code v2.1.213 或更新版本 | `claude import codex --dry-run` |39| `claude import [source]` | 啟動互動式工作階段，執行 [`/import`](/docs/zh-TW/commands#all-commands) 以將其他編碼 agent 的設定帶入 Claude Code。接受與命令相同的 `--dry-run` 和 `--yes` 選項。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 AWS 上的 Claude Platform 上不可用。當您關閉 [功能旗標擷取](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching) 時也不可用。需要 Claude Code v2.1.213 或更新版本 | `claude import codex --dry-run` |

42| `claude mcp login <name>` | 執行已設定 MCP 伺服器的 OAuth 流程，無需開啟互動式 `/mcp` 面板。適用於 HTTP、SSE 和 claude.ai 連接器伺服器。在 SSH 上新增 `--no-browser` 以列印授權 URL 而非開啟瀏覽器，然後將重新導向 URL 貼回提示處。請參閱 [從命令列進行身分驗證](/docs/zh-TW/mcp#authenticate-from-the-command-line) | `claude mcp login sentry` |42| `claude mcp login <name>` | 執行已設定 MCP 伺服器的 OAuth 流程，無需開啟互動式 `/mcp` 面板。適用於 HTTP、SSE 和 claude.ai 連接器伺服器。在 SSH 上新增 `--no-browser` 以列印授權 URL 而非開啟瀏覽器。對於 HTTP 或 SSE 伺服器，請將重新導向 URL 貼回提示處。對於 claude.ai 連接器，請參閱 [從您的 shell 再次授權連接器](/docs/zh-TW/remote-control#authorize-a-connector-again-from-your-shell)。請參閱 [從命令列進行身分驗證](/docs/zh-TW/mcp#authenticate-from-the-command-line) | `claude mcp login sentry` |

44| `claude plugin` | 管理 Claude Code [外掛](/docs/zh-TW/plugins/overview)。別名：`claude plugins`。請參閱 [外掛參考](/docs/zh-TW/plugins/cli-reference#claude-plugin-commands) 以取得子命令 | `claude plugin install code-review@claude-plugins-official` |44| `claude plugin` | 管理 Claude Code [外掛](/docs/zh-TW/plugins/overview)。別名：`claude plugins`。請參閱 [外掛參考](/docs/zh-TW/plugins/cli-reference#claude-plugin-commands) 以取得子命令 | `claude plugin install code-review@claude-plugins-official` |

45| `claude purge [path]` | 刪除專案的所有本機 Claude Code 狀態：逐字稿、工作清單、偵錯日誌、檔案編輯歷史記錄、提示詞歷史記錄行和專案在 `~/.claude.json` 中的項目。省略 `[path]` 以從互動式清單中選擇。旗標：`--dry-run` 以預覽，`-y`/`--yes` 以跳過確認，`-i`/`--interactive` 以確認每個項目，`--all` 用於每個專案。請參閱 [清除本機資料](/docs/zh-TW/claude-directory#clear-local-data) | `claude purge ~/work/repo --dry-run` |45| `claude purge [path]` | 刪除專案的所有本機 Claude Code 狀態：逐字稿、工作清單、偵錯日誌、檔案編輯歷史記錄、提示詞歷史記錄行和專案在 `~/.claude.json` 中的項目。省略 `[path]` 以從互動式清單中選擇。旗標：`--dry-run` 以預覽，`-y`/`--yes` 以跳過確認，`-i`/`--interactive` 以確認每個項目，`--all` 用於每個專案。請參閱 [清除本機資料](/docs/zh-TW/claude-directory#clear-local-data) | `claude purge ~/work/repo --dry-run` |

107| `--json-schema` | 在代理程式完成其工作流程後取得符合 JSON Schema 的驗證 JSON 輸出（僅列印模式）。請參閱[結構化輸出](/docs/zh-TW/agent-sdk/structured-outputs)。Claude Code 在無效的 schema 上結束並接受 `format` 關鍵字作為註釋而不進行用戶端驗證 | `claude -p --json-schema '{"type":"object","properties":{...}}' "query"` |107| `--json-schema` | 在代理程式完成其工作流程後取得符合 JSON Schema 的驗證 JSON 輸出（僅列印模式）。請參閱[結構化輸出](/docs/zh-TW/agent-sdk/structured-outputs)。Claude Code 在無效的 schema 上結束並接受 `format` 關鍵字作為註釋而不進行用戶端驗證 | `claude -p --json-schema '{"type":"object","properties":{...}}' "query"` |

109| `--max-budget-usd` | 在停止前在 API 呼叫上花費的最大美元金額（僅列印模式）。Claude Code 會依據其[用戶端成本估算](/docs/zh-TW/agent-sdk/cost-tracking#estimates-not-billing)檢查上限，這可能與您的帳單不同。來自 [subagent](/docs/zh-TW/sub-agents) 的支出計入上限。當您使用 `--continue` 或 `--resume` 返回對話時，[從較早的執行還原](/docs/zh-TW/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls)的總計不計入上限。一旦支出達到上限，產生另一個 subagent 會失敗並出現 `Budget limit reached`，且 Claude Code 會停止仍在執行的背景 subagent；上限強制行為需要 Claude Code v2.1.217 或更新版本 | `claude -p --max-budget-usd 5.00 "query"` |109| `--max-budget-usd` | 一旦 API 呼叫的估計支出達到此金額即停止執行（僅列印模式）。Claude Code 會依據其[用戶端成本估算](/docs/zh-TW/agent-sdk/cost-tracking#estimates-not-billing)檢查上限，這可能與您的帳單不同。來自 [subagent](/docs/zh-TW/sub-agents) 的支出計入上限。支出可能會超過上限，因此請[保留餘裕](/docs/zh-TW/agent-sdk/agent-loop#budget-headroom)。當您使用 `--continue` 或 `--resume` 返回對話時，[從較早的執行還原](/docs/zh-TW/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls)的總計不計入上限。一旦支出達到上限，產生另一個 subagent 會失敗並出現 `Budget limit reached`，且 Claude Code 會停止仍在執行的背景 subagent；上限強制行為需要 Claude Code v2.1.217 或更新版本 | `claude -p --max-budget-usd 5.00 "query"` |

111| `--mcp-config` | 從 JSON 檔案或字串載入 MCP 伺服器（以空格分隔）。當您使用 `-p` 傳遞此旗標時，Claude Code 會等待仍在擱置的伺服器連線，直到 [`MCP_TIMEOUT`](/docs/zh-TW/env-vars) 啟動逾時（預設 30 秒）；具有[快取工具清單](/docs/zh-TW/mcp#managing-your-servers)的伺服器會跳過等待並在首次使用時連線。等待需要 Claude Code v2.1.221 或更新版本 | `claude --mcp-config ./mcp.json` |111| `--mcp-config` | 從 JSON 檔案或字串載入 MCP 伺服器（以空格分隔）。當您使用 `-p` 傳遞此旗標時，Claude Code 會等待仍在擱置的伺服器連線，直到 [`MCP_TIMEOUT`](/docs/zh-TW/env-vars) 啟動逾時（預設 30 秒）；具有[快取工具清單](/docs/zh-TW/mcp#managing-your-servers)的伺服器會跳過等待並在首次使用時連線。等待需要 Claude Code v2.1.221 或更新版本 | `claude --mcp-config ./mcp.json` |

112| `--model` | 使用[模型別名](/docs/zh-TW/model-config#model-aliases)（例如 `sonnet`、`opus`、`haiku` 或 `fable`）或模型的完整名稱為目前工作階段設定模型。覆蓋 [`model`](/docs/zh-TW/settings-reference#model) 設定和 [`ANTHROPIC_MODEL`](/docs/zh-TW/model-config#environment-variables) | `claude --model claude-sonnet-5` |112| `--model` | 使用[模型別名](/docs/zh-TW/model-config#model-aliases)（例如 `sonnet`、`opus`、`haiku` 或 `fable`）或模型的完整名稱為目前工作階段設定模型。覆蓋 [`model`](/docs/zh-TW/settings-reference#model) 設定和 [`ANTHROPIC_MODEL`](/docs/zh-TW/model-config#environment-variables) | `claude --model claude-sonnet-5` |

cloud-environments.md +3 −3

Details

307| | 在雲端工作階段中可用 | 原因 |307| | 在雲端工作階段中可用 | 原因 |

308| :- | :- | :- |308| :- | :- | :- |

309| 您儲存庫的 `CLAUDE.md` | 是 | 複製的一部分 |309| 您儲存庫的 `CLAUDE.md` | 是 | 複製的一部分 |

312| 您儲存庫的 `.claude/rules/` | 是 | 複製的一部分 |312| 您儲存庫的 `.claude/rules/` | 是 | 複製的一部分 |

313| 您儲存庫的 `.claude/skills/`、`.claude/agents/`、`.claude/commands/` | 是 | 複製的一部分 |313| 您儲存庫的 `.claude/skills/`、`.claude/agents/`、`.claude/commands/` | 是 | 複製的一部分 |

314| 在您儲存庫的 `.claude/settings.json` 中宣告的外掛程式和市集 | 否 | 雲端工作階段不會安裝儲存庫在 [`enabledPlugins`](/docs/zh-TW/settings-reference#enabledplugins) 下開啟的外掛程式，包括來自它在 [`extraKnownMarketplaces`](/docs/zh-TW/settings-reference#extraknownmarketplaces) 下列出的市集的外掛程式 |314| 在您儲存庫的 `.claude/settings.json` 中宣告的外掛程式和市集 | 否 | 雲端工作階段不會安裝儲存庫在 [`enabledPlugins`](/docs/zh-TW/settings-reference#enabledplugins) 下開啟的外掛程式，包括來自它在 [`extraKnownMarketplaces`](/docs/zh-TW/settings-reference#extraknownmarketplaces) 下列出的市集的外掛程式 |

575 575

576SessionStart hooks 在雲端中的行為與本機相同，但有以下注意事項：576SessionStart hooks 在雲端中的行為與本機相同，但有以下注意事項：

577 577

578* **每個工作階段一個儲存庫**：具有多個儲存庫的工作階段不會從任何儲存庫的 `.claude/settings.json` 載入 hooks，因此您在其中定義的 SessionStart hook 不會執行。使用[設定指令碼](#setup-scripts)為這些工作階段安裝相依性。578* **每個工作階段一個儲存庫**：在 Anthropic 託管環境中，具有多個儲存庫的工作階段不會從任何儲存庫的 `.claude/settings.json` 載入 hooks，因此您在其中定義的 SessionStart hook 不會執行。請改用[設定指令碼](#setup-scripts)為這些工作階段安裝相依性。若為自託管環境，請參閱[適用哪個儲存庫的設定](/docs/zh-TW/self-hosted-environments-configuration#repository-settings-in-sessions-with-several-repositories)。

579* **無雲端專用範圍**：hooks 在本機和雲端工作階段中執行。若要跳過本機執行，請在 `CLAUDE_CODE_REMOTE` 環境變數不為 `true` 時提前結束，如[相依性安裝指令碼](#install-dependencies-with-a-sessionstart-hook)所示。579* **無雲端專用範圍**：hooks 在本機和雲端工作階段中執行。若要跳過本機執行，請在 `CLAUDE_CODE_REMOTE` 環境變數不為 `true` 時提前結束，如[相依性安裝指令碼](#install-dependencies-with-a-sessionstart-hook)所示。

580* **需要網路存取**：安裝命令需要連接到套件登錄檔。如果您的環境使用 **None** 網路存取，這些 hooks 會失敗。**Trusted** 下的[預設允許清單](#default-allowed-domains)涵蓋 npm、PyPI、RubyGems 和 crates.io。580* **需要網路存取**：安裝命令需要連接到套件登錄檔。如果您的環境使用 **None** 網路存取，這些 hooks 會失敗。**Trusted** 下的[預設允許清單](#default-allowed-domains)涵蓋 npm、PyPI、RubyGems 和 crates.io。

581* **Proxy 相容性**：在 Anthropic 託管環境中，所有出站流量都通過[安全 proxy](#security-proxy)，某些套件管理員無法與此 proxy 正確搭配運作；Bun 是一個已知的範例。在[自託管環境](/docs/zh-TW/self-hosted-environments-deploy#default-deny-egress)中，出站流量通過您自己的網路邊界。581* **Proxy 相容性**：在 Anthropic 託管環境中，所有出站流量都通過[安全 proxy](#security-proxy)，某些套件管理員無法與此 proxy 正確搭配運作；Bun 是一個已知的範例。在[自託管環境](/docs/zh-TW/self-hosted-environments-deploy#default-deny-egress)中，出站流量通過您自己的網路邊界。

commands.md +1 −1

Details

113| `/loop [interval] [prompt]` | **[Skill](/docs/zh-TW/skills#bundled-skills)。** 在工作階段保持打開時重複運行提示詞。省略間隔，Claude [自行調整迭代之間的步調](/docs/zh-TW/scheduled-tasks#let-claude-choose-the-interval)。省略提示詞，Claude 運行[內建維護提示詞](/docs/zh-TW/scheduled-tasks#run-the-built-in-maintenance-prompt)或您的 [`loop.md`](/docs/zh-TW/scheduled-tasks#customize-the-default-prompt-with-loop-md)。範例：`/loop 5m check if the deploy finished`。請參閱[按排程運行提示詞](/docs/zh-TW/scheduled-tasks)。別名：`/proactive` |113| `/loop [interval] [prompt]` | **[Skill](/docs/zh-TW/skills#bundled-skills)。** 在工作階段保持打開時重複運行提示詞。省略間隔，Claude [自行調整迭代之間的步調](/docs/zh-TW/scheduled-tasks#let-claude-choose-the-interval)。省略提示詞，Claude 運行[內建維護提示詞](/docs/zh-TW/scheduled-tasks#run-the-built-in-maintenance-prompt)或您的 [`loop.md`](/docs/zh-TW/scheduled-tasks#customize-the-default-prompt-with-loop-md)。範例：`/loop 5m check if the deploy finished`。請參閱[按排程運行提示詞](/docs/zh-TW/scheduled-tasks)。別名：`/proactive` |

114| `/mcp [reconnect (<server>\|all)\|enable\|disable [<server>\|all]]` | 管理 MCP 伺服器連線和 OAuth 身分驗證。運行時不帶引數以打開互動式清單，或傳遞 `reconnect`、`enable` 或 `disable` 與伺服器名稱或 `all`，以在不打開清單的情況下變更連線狀態。`reconnect all` 會[重試每個失敗或需要身分驗證的伺服器](/docs/zh-TW/mcp#retry-failed-servers-yourself)。也可在非互動模式 (`-p`) 中使用，其中運行時不帶引數會列印伺服器狀態的文字摘要而不是打開清單；需要 Claude Code v2.1.205 或更新版本 |114| `/mcp [reconnect (<server>\|all)\|enable\|disable [<server>\|all]]` | 管理 MCP 伺服器連線和 OAuth 身分驗證。運行時不帶引數以打開互動式清單，或傳遞 `reconnect`、`enable` 或 `disable` 與伺服器名稱或 `all`，以在不打開清單的情況下變更連線狀態。`reconnect all` 會[重試每個失敗或需要身分驗證的伺服器](/docs/zh-TW/mcp#retry-failed-servers-yourself)。在非互動模式 (`-p`) 中，不帶引數運行它會列印伺服器狀態的文字摘要而不是打開清單；需要 Claude Code v2.1.205 或更新版本 |

117| `/model [model]` | 切換 AI 模型並將其保存為新工作階段的預設值。對於支援它的模型，使用左/右箭頭以[調整 effort 等級](/docs/zh-TW/model-config#adjust-effort-level)。沒有引數時，打開選擇器；在行上按 `s` 以僅為目前工作階段切換。請參閱[何時 Claude Code 要求您確認切換](/docs/zh-TW/prompt-caching#switching-models)。一旦您確認切換（如果 Claude Code 要求），Claude Code 會應用變更而不等待目前回應完成。在 v2.1.242 之前，Claude Code 從它從 Anthropic 擷取的功能旗標決定是在回合中途運行命令還是將其排隊直到該回合完成，並始終在不[擷取功能旗標](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)的工作階段中排隊，例如在[第三方提供者](/docs/zh-TW/third-party-integrations)上。也可在非互動模式 (`-p`) 中使用模型引數而不是選擇器，其中它僅應用於目前工作階段且不保存為您的預設值；需要 Claude Code v2.1.205 或更新版本 |117| `/model [model]` | 切換 AI 模型並將其保存為新工作階段的預設值。對於支援它的模型，使用左/右箭頭以[調整 effort 等級](/docs/zh-TW/model-config#adjust-effort-level)。沒有引數時，打開選擇器；在行上按 `s` 以僅為目前工作階段切換。請參閱[何時 Claude Code 要求您確認切換](/docs/zh-TW/prompt-caching#switching-models)。一旦您確認切換（如果 Claude Code 要求），Claude Code 會應用變更而不等待目前回應完成。在 v2.1.242 之前，Claude Code 從它從 Anthropic 擷取的功能旗標決定是在回合中途運行命令還是將其排隊直到該回合完成，並始終在不[擷取功能旗標](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)的工作階段中排隊，例如在[第三方提供者](/docs/zh-TW/third-party-integrations)上。也可在非互動模式 (`-p`) 中使用模型引數而不是選擇器，其中它僅應用於目前工作階段且不保存為您的預設值；需要 Claude Code v2.1.205 或更新版本 |

desktop.md +1 −1

Details

396 使用工作階段並行工作396 使用工作階段並行工作

397</h3>397</h3>

398 398

399點擊側邊欄中的 **+ New session**，或在 macOS 上按 **Cmd+N** 或在 Windows 上按 **Ctrl+N**，以並行處理多個任務。按 **Ctrl+Tab** 和 **Ctrl+Shift+Tab** 以循環瀏覽側邊欄中的工作階段。對於 Git 儲存庫，選擇分支名稱旁邊的 **worktree** 選項，以使用 [Git worktrees](/docs/zh-TW/worktrees) 為工作階段提供自己的隔離專案副本，因此一個工作階段中的變更不會影響其他工作階段，直到您提交它們。399點擊側邊欄中的 **+ New session**，或在 macOS 上按 **Cmd+N** 或在 Windows 上按 **Ctrl+N**，以並行處理多個任務。按 **Ctrl+Tab** 和 **Ctrl+Shift+Tab** 以循環瀏覽側邊欄中的工作階段。對於 Git 儲存庫，選擇分支名稱旁邊的 **worktree** 選項，以使用 [Git worktrees](/docs/zh-TW/worktrees) 為工作階段提供自己的隔離專案副本。

400 400

401若要同時檢視兩個工作階段，請在 macOS 上按住 **Cmd** 或在 Windows 上按住 **Ctrl**，然後點擊側邊欄中的工作階段。工作階段會在您已開啟的工作階段旁邊的第二個窗格中開啟。當分割處於活動狀態時，點擊另一個側邊欄工作階段會取代具有焦點的窗格。在 macOS 上按 **Cmd+\\** 或在 Windows 上按 **Ctrl+\\** 以關閉焦點窗格並返回單一工作階段。401若要同時檢視兩個工作階段，請在 macOS 上按住 **Cmd** 或在 Windows 上按住 **Ctrl**，然後點擊側邊欄中的工作階段。工作階段會在您已開啟的工作階段旁邊的第二個窗格中開啟。當分割處於活動狀態時，點擊另一個側邊欄工作階段會取代具有焦點的窗格。在 macOS 上按 **Cmd+\\** 或在 Windows 上按 **Ctrl+\\** 以關閉焦點窗格並返回單一工作階段。

402 402

env-vars.md +380 −375

Details

21 21

22您在 shell 中設定的變數只在該終端機工作階段期間有效，而設定檔中的變數則在每次執行 `claude` 時都會套用。22您在 shell 中設定的變數只在該終端機工作階段期間有效，而設定檔中的變數則在每次執行 `claude` 時都會套用。

23 23

~~24<h3 id="in-your-shell">~~24<span id="in-your-shell" />

~~25 在您的 shell 中~~25

26<h3 id="set-variables-in-your-shell">

27 在 shell 中設定變數

26</h3>28</h3>

27 29

28在啟動 `claude` 之前設定變數：30在啟動 `claude` 之前設定變數：

78 </Tab>80 </Tab>

79</Tabs>81</Tabs>

80 82

~~81<h3 id="in-settings-files">~~83<span id="in-settings-files" />

~~82 在設定檔中~~84

85<h3 id="set-variables-in-settings-files">

86 在設定檔中設定變數

83</h3>87</h3>

84 88

85在 `settings.json` 檔案的 `env` 鍵下新增變數，如果檔案不存在則建立它。Claude Code 會直接從檔案讀取它們，因此無論如何啟動 `claude`，它們都會生效。執行中的工作階段會在您儲存檔案時將新的和已變更的值套用到其環境，但在啟動時讀取其變數一次的功能（例如 [OpenTelemetry 監控](/docs/zh-TW/monitoring-usage)）會保留其啟動值，直到您重新啟動為止。從檔案中移除變數不會在執行中的工作階段中取消設定它；移除會在您下次啟動 `claude` 時生效。89在 `settings.json` 檔案的 `env` 鍵下新增變數，如果檔案不存在則建立它。Claude Code 會直接從檔案讀取它們，因此無論如何啟動 `claude`，它們都會生效。執行中的工作階段會在您儲存檔案時將新的和已變更的值套用到其環境，但在啟動時讀取其變數一次的功能（例如 [OpenTelemetry 監控](/docs/zh-TW/monitoring-usage)）會保留其啟動值，直到您重新啟動為止。從檔案中移除變數不會在執行中的工作階段中取消設定它；移除會在您下次啟動 `claude` 時生效。

120 124

121環境變數如何與 CLI 旗標和工作階段內命令互動因功能而異：`--model` 和 `/model` 會覆寫 `ANTHROPIC_MODEL`，而 `CLAUDE_CODE_EFFORT_LEVEL` 會覆寫 `--effort` 和 `/effort`。當變數與另一個設定來源互動時，[變數](#variables) 列表中的其列會說明優先順序或連結到記錄該項目的頁面。125環境變數如何與 CLI 旗標和工作階段內命令互動因功能而異：`--model` 和 `/model` 會覆寫 `ANTHROPIC_MODEL`，而 `CLAUDE_CODE_EFFORT_LEVEL` 會覆寫 `--effort` 和 `/effort`。當變數與另一個設定來源互動時，[變數](#variables) 列表中的其列會說明優先順序或連結到記錄該項目的頁面。

122 126

123Claude Code 在啟動時讀取 shell 環境變數，因此對它們的變更會在您下次啟動 `claude` 時生效。在設定檔中 `env` 鍵下設定的變數會在檔案變更時重新套用到執行中的工作階段，但 [在設定檔中](#in-settings-files) 所述的僅啟動時例外。127Claude Code 在啟動時讀取 shell 環境變數，因此對它們的變更會在您下次啟動 `claude` 時生效。在設定檔中 `env` 鍵下設定的變數會在檔案變更時重新套用到執行中的工作階段，但 [在設定檔中設定變數](#in-settings-files) 所述的僅啟動時例外除外。

124 128

125<h2 id="variables">129<h2 id="variables">

126 變數130 變數

127</h2>131</h2>

128 132

129逾時、token 預算與重試次數等數值變數，除了純數字之外，也接受科學記號與數字分隔符寫法，但若某變數的列註明僅接受純數字則除外。例如，Claude Code 會將 `2e3` 讀取為 2000，將 `64_000` 讀取為 64000。在 v2.1.211 之前，這些寫法可能會在不顯示任何訊息的情況下設定成小得多的值，例如 `1e6` 會將逾時設為 1。133數值型變數（例如逾時、token 預算與重試次數）除了純數字外，也接受科學記號與數字分隔符號寫法，除非該變數的列中註明僅接受純數字。例如，Claude Code 會將 `2e3` 讀取為 2000，將 `64_000` 讀取為 64000。在 v2.1.211 之前，這些寫法可能會在無提示的情況下設定成小得多的值，例如 `1e6` 會將逾時設定為 1。

130 134

131<Note>135<Note>

132 對於用來開啟或關閉某項行為的變數，設定 `1`、`true`、`yes` 或 `on` 可將其開啟，設定 `0`、`false`、`no` 或 `off` 可將其關閉，大小寫不拘。136 對於開啟或關閉某項行為的變數，設定 `1`、`true`、`yes` 或 `on` 即可開啟，設定 `0`、`false`、`no` 或 `off` 即可關閉，不區分大小寫。

133 137

134 有些變數只會判斷是否有設定，因此任何非空值（包括 `0`）都會開啟該行為，而要關閉該行為，則需取消設定該變數或將其設為空值。以下變數採用這種方式運作：138 有些變數只判斷是否已設定，因此任何非空值（包括 `0`）都會開啟該行為，而要關閉該行為，需取消設定該變數或將其設為空值。以下變數採用此方式：

135 139

136 * `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`140 * `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`

137 * `DISABLE_TELEMETRY`141 * `DISABLE_TELEMETRY`

140 * `FALLBACK_FOR_ALL_PRIMARY_MODELS`144 * `FALLBACK_FOR_ALL_PRIMARY_MODELS`

141 * `IS_DEMO`145 * `IS_DEMO`

142 146

143 另有一個變數有其專屬規則：`FORCE_HYPERLINK` 讀取的是數字，因此只有 `0` 會將其關閉。每個變數所在的列也會說明其專屬規則。147 另有一個變數有自己的規則：`FORCE_HYPERLINK` 讀取的是數字，因此只有 `0` 會將其關閉。每個變數的列中也會說明其自己的規則。

144</Note>148</Note>

145 149

146| 變數 | 用途 |150| 變數 | 用途 |

147| :- | :- |151| :- | :- |

148| `ANTHROPIC_API_KEY` | 以 `X-Api-Key` 標頭傳送的 API 金鑰。設定後，即使您已登入，也會改用此金鑰，而非您的 Claude Pro、Max、Team 或 Enterprise 訂閱。在非互動模式（`-p`）下，只要存在此金鑰就一律會使用。在互動模式下，系統會提示您核准此金鑰一次，之後它才會覆寫您的訂閱。若要改用您的訂閱，請執行 `unset ANTHROPIC_API_KEY` |152| `ANTHROPIC_API_KEY` | 以 `X-Api-Key` 標頭傳送的 API 金鑰。設定後，即使您已登入，也會使用此金鑰而非您的 Claude Pro、Max、Team 或 Enterprise 訂閱。在非互動模式（`-p`）下，只要存在此金鑰就一律會使用。在互動模式下，系統會提示您核准此金鑰一次，之後它才會覆寫您的訂閱。若要改用您的訂閱，請執行 `unset ANTHROPIC_API_KEY` |

150| `ANTHROPIC_AWS_API_KEY` | [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 的工作區 API 金鑰，於 AWS Console 中產生。以 `x-api-key` 傳送，並優先於 AWS SigV4 |154| `ANTHROPIC_AWS_API_KEY` | [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 的工作區 API 金鑰，於 AWS Console 中產生。以 `x-api-key` 傳送，且優先於 AWS SigV4 |

151| `ANTHROPIC_AWS_BASE_URL` | 覆寫 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 端點 URL。適用於自訂區域，或透過 [LLM 閘道](/docs/zh-TW/llm-gateway)路由時。預設為 `https://aws-external-anthropic.{region}.api.aws`。Claude Code 解析區域時採用[與 Amazon Bedrock 相同的優先順序](/docs/zh-TW/amazon-bedrock#3-configure-claude-code) |155| `ANTHROPIC_AWS_BASE_URL` | 覆寫 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 端點 URL。用於自訂區域或透過 [LLM 閘道](/docs/zh-TW/llm-gateway)路由時。預設為 `https://aws-external-anthropic.{region}.api.aws`。Claude Code 解析區域時採用[與 Amazon Bedrock 相同的優先順序](/docs/zh-TW/amazon-bedrock#3-configure-claude-code) |

152| `ANTHROPIC_AWS_WORKSPACE_ID` | [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 必填。每個請求都會以 `anthropic-workspace-id` 標頭傳送 |156| `ANTHROPIC_AWS_WORKSPACE_ID` | [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 的必要設定。在每個請求中以 `anthropic-workspace-id` 標頭傳送 |

153| `ANTHROPIC_BASE_URL` | 覆寫 API 端點，以透過代理伺服器或閘道路由請求。設為非第一方主機時，[MCP Tool Search](/docs/zh-TW/mcp#scale-with-mcp-tool-search) 預設會停用。若您的代理伺服器會轉送 `tool_reference` 區塊，請設定 `ENABLE_TOOL_SEARCH=true`。自 v2.1.196 起，當此變數指向 `api.anthropic.com` 以外的主機時，[Remote Control](/docs/zh-TW/remote-control#requirements) 會停用，與其在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上的行為一致 |157| `ANTHROPIC_BASE_URL` | 覆寫 API 端點，以透過代理伺服器或閘道路由請求。設定為非第一方主機時，[MCP tool search](/docs/zh-TW/mcp#scale-with-mcp-tool-search) 預設會停用。若您的代理伺服器會轉送 `tool_reference` 區塊，請設定 `ENABLE_TOOL_SEARCH=true`。自 v2.1.196 起，當此變數指向 `api.anthropic.com` 以外的主機時，[Remote Control](/docs/zh-TW/remote-control#requirements) 會停用，與其在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上的行為一致 |

154| `ANTHROPIC_BEDROCK_BASE_URL` | 覆寫 Amazon Bedrock 端點 URL。適用於自訂 Amazon Bedrock 端點，或透過 [LLM 閘道](/docs/zh-TW/llm-gateway)路由時。請參閱 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) |158| `ANTHROPIC_BEDROCK_BASE_URL` | 覆寫 Amazon Bedrock 端點 URL。用於自訂 Amazon Bedrock 端點或透過 [LLM 閘道](/docs/zh-TW/llm-gateway)路由時。請參閱 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) |

155| `ANTHROPIC_BEDROCK_MANTLE_BASE_URL` | 覆寫 Amazon Bedrock Mantle 端點 URL。請參閱 [Mantle 端點](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint) |159| `ANTHROPIC_BEDROCK_MANTLE_BASE_URL` | 覆寫 Amazon Bedrock Mantle 端點 URL。請參閱 [Mantle 端點](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint) |

156| `ANTHROPIC_BEDROCK_REGION_PREFIX` | Claude Code 優先嘗試的跨區域推論設定檔前綴（`us`、`eu`、`apac`、`jp`、`au` 或 `global`），取代由 AWS 區域推導出的前綴。在 AWS GovCloud 區域中會被忽略。需要 Claude Code v2.1.224 或更新版本。請參閱 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock#cross-region-inference-profile-prefixes) |160| `ANTHROPIC_BEDROCK_REGION_PREFIX` | Claude Code 優先嘗試的跨區域推論設定檔前綴（`us`、`eu`、`apac`、`jp`、`au` 或 `global`），而非從 AWS 區域推導出的前綴。在 AWS GovCloud 區域中會被忽略。需要 Claude Code v2.1.224 或更新版本。請參閱 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock#cross-region-inference-profile-prefixes) |

157| `ANTHROPIC_BEDROCK_SERVICE_TIER` | Amazon Bedrock [服務層級](https://docs.aws.amazon.com/bedrock/latest/userguide/service-tiers-inference.html)（`default`、`flex` 或 `priority`）。以 `X-Amzn-Bedrock-Service-Tier` 標頭傳送。請參閱 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock#service-tiers) |161| `ANTHROPIC_BEDROCK_SERVICE_TIER` | Amazon Bedrock [服務層級](https://docs.aws.amazon.com/bedrock/latest/userguide/service-tiers-inference.html)（`default`、`flex` 或 `priority`）。以 `X-Amzn-Bedrock-Service-Tier` 標頭傳送。請參閱 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock#service-tiers) |

158| `ANTHROPIC_BETAS` | 以逗號分隔的額外 `anthropic-beta` 標頭值清單，會包含在 API 請求中。Claude Code 已會傳送其所需的 beta 標頭；使用此變數可在 Claude Code 加入原生支援之前，選擇加入某項 [Anthropic API beta](https://platform.claude.com/docs/en/api/beta-headers)。與需要 API 金鑰身分驗證的 [`--betas` 旗標](/docs/zh-TW/cli-reference#cli-flags)不同，此變數適用於所有驗證方式，包括 Claude.ai 訂閱 |162| `ANTHROPIC_BETAS` | 要包含在 API 請求中的額外 `anthropic-beta` 標頭值，以逗號分隔。Claude Code 已會傳送其所需的 beta 標頭；在 Claude Code 加入原生支援之前，可使用此變數選擇加入 [Anthropic API beta](https://platform.claude.com/docs/en/api/beta-headers)。不同於需要 API 金鑰身分驗證的 [`--betas` 旗標](/docs/zh-TW/cli-reference#cli-flags)，此變數適用於所有驗證方式，包括 Claude.ai 訂閱 |

159| `ANTHROPIC_CUSTOM_HEADERS` | 要加入請求的自訂標頭（`Name: Value` 格式，多個標頭以換行分隔）。若名稱或值包含 HTTP 標頭無法承載的字元，例如彎引號或零寬空格，請求會失敗，並顯示依位置指出該組標頭的錯誤。需要 Claude Code v2.1.227 或更新版本。[Invalid request header value](/docs/zh-TW/errors#invalid-request-header-value) 列出了確切的字元集以及檢查執行的位置。若某個值設定了憑證、組織或租用戶、路由或 API 行為標頭（例如 `Authorization` 或 `Host`），在由伺服器受管設定傳遞時，會被視為[需要核准的設定](/docs/zh-TW/server-managed-settings#environment-variables-and-the-approval-dialog)。若來自專案或本機設定，此類值則依循[套用 `env` 值的規則](/docs/zh-TW/settings-reference#when-claude-code-applies-env-values) |163| `ANTHROPIC_CUSTOM_HEADERS` | 要加入請求的自訂標頭（`Name: Value` 格式，多個標頭以換行分隔）。若名稱或值包含 HTTP 標頭無法承載的字元，例如彎引號或零寬空格，請求會失敗，並顯示依位置識別該組名稱與值的錯誤。需要 Claude Code v2.1.227 或更新版本。[Invalid request header value](/docs/zh-TW/errors#invalid-request-header-value) 列出確切的字元集以及檢查執行的位置。若值設定的是憑證、組織或租用戶、路由或 API 行為相關的標頭，例如 `Authorization` 或 `Host`，當由伺服器受管設定傳遞時，它會被視為[需要核准的設定](/docs/zh-TW/server-managed-settings#environment-variables-and-the-approval-dialog)。若來自專案或本機設定，此類值會遵循[何時套用 `env` 值的規則](/docs/zh-TW/settings-reference#when-claude-code-applies-env-values) |

160| `ANTHROPIC_CUSTOM_MODEL_OPTION` | 要在 `/model` 選擇器中新增為自訂項目的模型 ID。使用此變數可讓非標準或閘道專屬的模型可供選擇，而不必取代內建別名。請參閱[模型設定](/docs/zh-TW/model-config#add-a-custom-model-option) |164| `ANTHROPIC_CUSTOM_MODEL_OPTION` | 要在 `/model` 選擇器中新增為自訂項目的模型 ID。使用此變數可讓非標準或閘道專屬的模型可供選擇，而不需取代內建別名。請參閱[模型設定](/docs/zh-TW/model-config#add-a-custom-model-option) |

162| `ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` | `/model` 選擇器中自訂模型項目的顯示名稱。未設定時，若 Claude Code [可辨識該 ID](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)，該項目會顯示模型名稱，否則顯示模型 ID |166| `ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` | `/model` 選擇器中自訂模型項目的顯示名稱。未設定時，若 Claude Code [能辨識該 ID](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)，項目會顯示模型名稱，否則顯示模型 ID |

163| `ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES` | 以逗號分隔的自訂模型所支援[功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)清單，例如 `effort,thinking`。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |167| `ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES` | 自訂模型支援的[功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)清單，以逗號分隔，例如 `effort,thinking`。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

164| `ANTHROPIC_DEFAULT_FABLE_MODEL` | `fable` 別名所解析到的模型 ID，也是 Claude Code 在第三方供應商上為了[自動模型備援](/docs/zh-TW/model-config#automatic-model-fallback)而辨識為 Fable 模型的 ID。請參閱[模型設定](/docs/zh-TW/model-config#environment-variables) |168| `ANTHROPIC_DEFAULT_FABLE_MODEL` | `fable` 別名解析成的模型 ID，也是 Claude Code 在第三方提供者上為[自動模型備援](/docs/zh-TW/model-config#automatic-model-fallback)辨識為 Fable 模型的 ID。請參閱[模型設定](/docs/zh-TW/model-config#environment-variables) |

165| `ANTHROPIC_DEFAULT_FABLE_MODEL_DESCRIPTION` | `/model` 選擇器中固定 Fable 模型的顯示說明。未設定時，該列會顯示以 `Custom Fable model` 開頭的預設說明。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |169| `ANTHROPIC_DEFAULT_FABLE_MODEL_DESCRIPTION` | `/model` 選擇器中固定的 Fable 模型的顯示說明。未設定時，該列會顯示以 `Custom Fable model` 開頭的預設說明。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

166| `ANTHROPIC_DEFAULT_FABLE_MODEL_NAME` | `/model` 選擇器中固定 Fable 模型的顯示名稱。未設定時，若 Claude Code 可辨識該固定 ID，該列會顯示模型名稱，否則顯示固定 ID。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |170| `ANTHROPIC_DEFAULT_FABLE_MODEL_NAME` | `/model` 選擇器中固定的 Fable 模型的顯示名稱。未設定時，若 Claude Code 能辨識固定的 ID，該列會顯示模型名稱，否則顯示固定的 ID。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

167| `ANTHROPIC_DEFAULT_FABLE_MODEL_SUPPORTED_CAPABILITIES` | 以逗號分隔的固定 Fable 模型所支援[功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)清單，例如 `effort,thinking`。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |171| `ANTHROPIC_DEFAULT_FABLE_MODEL_SUPPORTED_CAPABILITIES` | 固定的 Fable 模型支援的[功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)清單，以逗號分隔，例如 `effort,thinking`。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

168| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | `haiku` 別名所解析到的模型 ID，也用於[背景功能](/docs/zh-TW/costs#background-token-usage)。請參閱[模型設定](/docs/zh-TW/model-config#environment-variables) |172| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | `haiku` 別名解析成的模型 ID，也用於[背景功能](/docs/zh-TW/costs#background-token-usage)。請參閱[模型設定](/docs/zh-TW/model-config#environment-variables) |

169| `ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION` | `/model` 選擇器中固定 Haiku 模型的顯示說明。未設定時，該列會顯示以 `Custom Haiku model` 開頭的預設說明。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |173| `ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION` | `/model` 選擇器中固定的 Haiku 模型的顯示說明。未設定時，該列會顯示以 `Custom Haiku model` 開頭的預設說明。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

170| `ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME` | `/model` 選擇器中固定 Haiku 模型的顯示名稱。未設定時，若 Claude Code 可辨識該固定 ID，該列會顯示模型名稱，否則顯示固定 ID。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |174| `ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME` | `/model` 選擇器中固定的 Haiku 模型的顯示名稱。未設定時，若 Claude Code 能辨識固定的 ID，該列會顯示模型名稱，否則顯示固定的 ID。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

171| `ANTHROPIC_DEFAULT_HAIKU_MODEL_SUPPORTED_CAPABILITIES` | 以逗號分隔的固定 Haiku 模型所支援[功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)清單，例如 `effort,thinking`。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |175| `ANTHROPIC_DEFAULT_HAIKU_MODEL_SUPPORTED_CAPABILITIES` | 固定的 Haiku 模型支援的[功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)清單，以逗號分隔，例如 `effort,thinking`。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

172| `ANTHROPIC_DEFAULT_MODEL` | 新工作階段預設啟動時使用的模型。需要 Claude Code v2.1.236 或更新版本。請參閱[為新工作階段設定預設模型](/docs/zh-TW/model-config#set-a-default-model-for-new-sessions) |176| `ANTHROPIC_DEFAULT_MODEL` | 新工作階段預設啟動時使用的模型。需要 Claude Code v2.1.236 或更新版本。請參閱[為新工作階段設定預設模型](/docs/zh-TW/model-config#set-a-default-model-for-new-sessions) |

173| `ANTHROPIC_DEFAULT_OPUS_MODEL` | `opus` 別名所解析到的模型 ID，也是 `opusplan` 在 Plan Mode 啟用時使用的模型。請參閱[模型設定](/docs/zh-TW/model-config#environment-variables) |177| `ANTHROPIC_DEFAULT_OPUS_MODEL` | `opus` 別名解析成的模型 ID，也是 Plan Mode 啟用時 `opusplan` 所使用的模型。請參閱[模型設定](/docs/zh-TW/model-config#environment-variables) |

174| `ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION` | `/model` 選擇器中固定 Opus 模型的顯示說明。未設定時，該列會顯示以 `Custom Opus model` 開頭的預設說明。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |178| `ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION` | `/model` 選擇器中固定的 Opus 模型的顯示說明。未設定時，該列會顯示以 `Custom Opus model` 開頭的預設說明。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

175| `ANTHROPIC_DEFAULT_OPUS_MODEL_NAME` | `/model` 選擇器中固定 Opus 模型的顯示名稱。未設定時，若 Claude Code 可辨識該固定 ID，該列會顯示模型名稱，否則顯示固定 ID。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |179| `ANTHROPIC_DEFAULT_OPUS_MODEL_NAME` | `/model` 選擇器中固定的 Opus 模型的顯示名稱。未設定時，若 Claude Code 能辨識固定的 ID，該列會顯示模型名稱，否則顯示固定的 ID。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

176| `ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES` | 以逗號分隔的固定 Opus 模型所支援[功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)清單，例如 `effort,thinking`。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |180| `ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES` | 固定的 Opus 模型支援的[功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)清單，以逗號分隔，例如 `effort,thinking`。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

177| `ANTHROPIC_DEFAULT_SONNET_MODEL` | `sonnet` 別名所解析到的模型 ID，也是 `opusplan` 在 Plan Mode 未啟用時使用的模型。請參閱[模型設定](/docs/zh-TW/model-config#environment-variables) |181| `ANTHROPIC_DEFAULT_SONNET_MODEL` | `sonnet` 別名解析成的模型 ID，也是 Plan Mode 未啟用時 `opusplan` 所使用的模型。請參閱[模型設定](/docs/zh-TW/model-config#environment-variables) |

178| `ANTHROPIC_DEFAULT_SONNET_MODEL_DESCRIPTION` | `/model` 選擇器中固定 Sonnet 模型的顯示說明。未設定時，該列會顯示以 `Custom Sonnet model` 開頭的預設說明。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |182| `ANTHROPIC_DEFAULT_SONNET_MODEL_DESCRIPTION` | `/model` 選擇器中固定的 Sonnet 模型的顯示說明。未設定時，該列會顯示以 `Custom Sonnet model` 開頭的預設說明。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

179| `ANTHROPIC_DEFAULT_SONNET_MODEL_NAME` | `/model` 選擇器中固定 Sonnet 模型的顯示名稱。未設定時，若 Claude Code 可辨識該固定 ID，該列會顯示模型名稱，否則顯示固定 ID。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |183| `ANTHROPIC_DEFAULT_SONNET_MODEL_NAME` | `/model` 選擇器中固定的 Sonnet 模型的顯示名稱。未設定時，若 Claude Code 能辨識固定的 ID，該列會顯示模型名稱，否則顯示固定的 ID。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

180| `ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES` | 以逗號分隔的固定 Sonnet 模型所支援[功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)清單，例如 `effort,thinking`。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |184| `ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES` | 固定的 Sonnet 模型支援的[功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)清單，以逗號分隔，例如 `effort,thinking`。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

181| `ANTHROPIC_FEDERATION_RULE_ID` | [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的聯合規則 ID。當您將其與 `ANTHROPIC_ORGANIZATION_ID` 一起設定時，Claude Code 會選用聯合憑證，其優先順序高於您的 `/login` 憑證。請參閱[身分驗證優先順序](/docs/zh-TW/authentication#authentication-precedence) |185| `ANTHROPIC_FEDERATION_RULE_ID` | [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的聯合規則 ID。當您將其與 `ANTHROPIC_ORGANIZATION_ID` 一起設定時，Claude Code 會選用聯合憑證，其排序高於您的 `/login` 憑證。請參閱[身分驗證優先順序](/docs/zh-TW/authentication#authentication-precedence) |

182| `ANTHROPIC_FOUNDRY_API_KEY` | 用於 Microsoft Foundry 身分驗證的 API 金鑰（請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)） |186| `ANTHROPIC_FOUNDRY_API_KEY` | 用於 Microsoft Foundry 身分驗證的 API 金鑰（請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)） |

183| `ANTHROPIC_FOUNDRY_AUTH_TOKEN` | 用於 Microsoft Foundry 身分驗證的 Bearer token，例如 Microsoft Entra 存取 token。Claude Code 會將其以 `Authorization: Bearer` 標頭傳送。優先於 `ANTHROPIC_FOUNDRY_API_KEY` 以及 Azure 預設憑證鏈。請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)。需要 Claude Code v2.1.203 或更新版本 |187| `ANTHROPIC_FOUNDRY_AUTH_TOKEN` | 用於 Microsoft Foundry 身分驗證的 Bearer token，例如 Microsoft Entra 存取 token。Claude Code 會將其作為 `Authorization: Bearer` 標頭傳送。優先於 `ANTHROPIC_FOUNDRY_API_KEY` 與 Azure 預設憑證鏈。請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)。需要 Claude Code v2.1.203 或更新版本 |

184| `ANTHROPIC_FOUNDRY_BASE_URL` | Microsoft Foundry 資源的完整基底 URL（例如 `https://my-resource.services.ai.azure.com/anthropic`）。可替代 `ANTHROPIC_FOUNDRY_RESOURCE`（請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)） |188| `ANTHROPIC_FOUNDRY_BASE_URL` | Microsoft Foundry 資源的完整基礎 URL（例如 `https://my-resource.services.ai.azure.com/anthropic`）。可替代 `ANTHROPIC_FOUNDRY_RESOURCE`（請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)） |

185| `ANTHROPIC_FOUNDRY_RESOURCE` | Microsoft Foundry 資源名稱（例如 `my-resource`）。Claude Code [會拒絕 URL 或主機名稱](/docs/zh-TW/errors#anthropic-foundry-resource-must-be-a-foundry-resource-name)。若未設定 `ANTHROPIC_FOUNDRY_BASE_URL` 則為必填（請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)） |189| `ANTHROPIC_FOUNDRY_RESOURCE` | Microsoft Foundry 資源名稱（例如 `my-resource`）。Claude Code [會拒絕 URL 或主機名稱](/docs/zh-TW/errors#anthropic-foundry-resource-must-be-a-foundry-resource-name)。若未設定 `ANTHROPIC_FOUNDRY_BASE_URL` 則為必要（請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)） |

187| `ANTHROPIC_ORGANIZATION_ID` | [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的組織 ID。請與 `ANTHROPIC_FEDERATION_RULE_ID` 一起設定。請參閱[身分驗證優先順序](/docs/zh-TW/authentication#authentication-precedence) |191| `ANTHROPIC_ORGANIZATION_ID` | [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的組織 ID。請與 `ANTHROPIC_FEDERATION_RULE_ID` 一起設定。請參閱[身分驗證優先順序](/docs/zh-TW/authentication#authentication-precedence) |

188| `ANTHROPIC_PROFILE` | 用於身分驗證的 Anthropic 設定檔名稱，例如由 [`ant auth login`](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/authentication) 建立，或由[在沒有 API 金鑰的情況下登入 Console 帳戶](/docs/zh-TW/authentication#sign-in-without-an-api-key)所建立的設定檔。請參閱[身分驗證優先順序](/docs/zh-TW/authentication#authentication-precedence) |192| `ANTHROPIC_PROFILE` | 用於身分驗證的 Anthropic 設定檔名稱，例如由 [`ant auth login`](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/authentication) 建立，或由[在沒有 API 金鑰的情況下登入 Console 帳戶](/docs/zh-TW/authentication#sign-in-without-an-api-key)所建立的設定檔。請參閱[身分驗證優先順序](/docs/zh-TW/authentication#authentication-precedence) |

190| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | 使用 Amazon Bedrock 或 Amazon Bedrock Mantle 時，覆寫 Haiku 級模型的 AWS 區域。在 Amazon Bedrock 上，只有在同時設定 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 或已棄用的 `ANTHROPIC_SMALL_FAST_MODEL` 時才會生效，因為否則 Amazon Bedrock 會在工作階段區域中以[預設 Sonnet 模型或主要模型](/docs/zh-TW/amazon-bedrock#4-pin-model-versions)執行背景任務 |194| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | 使用 Amazon Bedrock 或 Amazon Bedrock Mantle 時，覆寫 Haiku 級模型的 AWS 區域。在 Amazon Bedrock 上，只有同時設定 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 或已棄用的 `ANTHROPIC_SMALL_FAST_MODEL` 時才會生效，因為否則 Amazon Bedrock 會在工作階段區域中以[預設 Sonnet 模型或主要模型](/docs/zh-TW/amazon-bedrock#4-pin-model-versions)執行背景任務 |

191| `ANTHROPIC_VERTEX_BASE_URL` | 覆寫 Google Cloud's Agent Platform 端點 URL。適用於自訂 Google Cloud's Agent Platform 端點，或透過 [LLM 閘道](/docs/zh-TW/llm-gateway)路由時。請參閱 [Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai) |195| `ANTHROPIC_VERTEX_BASE_URL` | 覆寫 Google Cloud's Agent Platform 端點 URL。用於自訂 Google Cloud's Agent Platform 端點或透過 [LLM 閘道](/docs/zh-TW/llm-gateway)路由時。請參閱 [Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai) |

192| `ANTHROPIC_VERTEX_PROJECT_ID` | Google Cloud's Agent Platform 請求所指向的 GCP 專案 ID。請參閱[設定 GCP 憑證](/docs/zh-TW/google-vertex-ai#3-configure-gcp-credentials) |196| `ANTHROPIC_VERTEX_PROJECT_ID` | Google Cloud's Agent Platform 請求所指向的 GCP 專案 ID。請參閱[設定 GCP 憑證](/docs/zh-TW/google-vertex-ai#3-configure-gcp-credentials) |

193| `ANTHROPIC_WORKSPACE_ID` | [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的工作區 ID。當您的聯合規則涵蓋多個工作區時請設定此變數，讓 token 交換知道要以哪個工作區為目標 |197| `ANTHROPIC_WORKSPACE_ID` | [workload identity federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的工作區 ID。當您的聯合規則範圍涵蓋多個工作區時設定此變數，讓 token 交換知道要指向哪個工作區 |

194| `API_FORCE_IDLE_TIMEOUT` | 覆寫 5 分鐘的主體閒置逾時，此逾時會在沒有任何位元組抵達時中止串流模型回應。設為 `0` 可關閉此逾時，例如當緩慢的[閘道](/docs/zh-TW/llm-gateway)或本機模型在區塊之間暫停超過 5 分鐘時；設為 `1` 則可對所有供應商保持開啟。未設定時，此逾時會在直接 Anthropic API、[Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 以及設定了 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1` 的 Amazon Bedrock 以外的供應商上生效。[串流監看程式](/docs/zh-TW/network-config#streaming-idle-watchdogs)獨立於此運作，即使您在此設定 `0`，仍會中止長時間的無回應暫停 |198| `API_FORCE_IDLE_TIMEOUT` | 覆寫 5 分鐘的本文閒置逾時，此逾時會在沒有任何位元組抵達時中止串流模型回應。設定為 `0` 可關閉逾時，例如當緩慢的[閘道](/docs/zh-TW/llm-gateway)或本機模型在區塊之間暫停超過 5 分鐘時；設定為 `1` 則可對所有提供者保持開啟。未設定時，此逾時會在直接 Anthropic API、[Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws)，以及設定了 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1` 的 Amazon Bedrock 以外的提供者上啟用。[串流監視機制](/docs/zh-TW/network-config#streaming-idle-watchdogs)獨立於此執行，即使您在此設定 `0`，仍會中止長時間的靜默暫停 |

195| `API_TIMEOUT_MS` | API 請求的逾時時間，單位為毫秒（預設：600000，即 10 分鐘；上限：2147483647）。當請求在緩慢的網路上逾時，或透過代理伺服器路由時，請提高此值。超過上限的值會使底層計時器溢位，導致請求立即失敗 |199| `API_TIMEOUT_MS` | API 請求的逾時時間，單位為毫秒（預設：600000，即 10 分鐘；最大值：2147483647）。在網路緩慢或透過代理伺服器路由而導致請求逾時時，請調高此值。超過最大值的值會使底層計時器溢位，導致請求立即失敗 |

196| `AWS_BEARER_TOKEN_BEDROCK` | 用於身分驗證的 Amazon Bedrock API 金鑰（請參閱 [Amazon Bedrock API keys](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)） |200| `AWS_BEARER_TOKEN_BEDROCK` | 用於身分驗證的 Amazon Bedrock API 金鑰（請參閱 [Amazon Bedrock API 金鑰](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)） |

197| `BASH_DEFAULT_TIMEOUT_MS` | 前景 Bash 或 PowerShell 工具命令的預設逾時，單位為毫秒（預設：120000，即 2 分鐘）。若值超過[背景命令的預設時間限制](/docs/zh-TW/tools-reference#time-limit-for-background-commands)，則會在無人看管的工作階段中取代該預設值。背景時間限制需要 Claude Code v2.1.285 或更新版本 |201| `BASH_DEFAULT_TIMEOUT_MS` | 前景 Bash 或 PowerShell 工具命令的預設逾時，單位為毫秒（預設：120000，即 2 分鐘）。若值高於[背景命令的預設時間限制](/docs/zh-TW/tools-reference#time-limit-for-background-commands)，則會在無人值守的工作階段中取代該預設值。背景時間限制需要 Claude Code v2.1.285 或更新版本 |

198| `BASH_MAX_OUTPUT_LENGTH` | Claude Code 讀回命令結果中的 bash 輸出最大字元數（預設：30000；上限：150000）。若您設定了 [`bashOutputMaxChars`](/docs/zh-TW/settings-reference#bashoutputmaxchars) 設定，Claude Code 會忽略此變數。請參閱[輸出限制](/docs/zh-TW/tools-reference#output-limits) |202| `BASH_MAX_OUTPUT_LENGTH` | Claude Code 讀回命令結果中的 bash 輸出最大字元數（預設：30000；最大值：150000）。若您設定了 [`bashOutputMaxChars`](/docs/zh-TW/settings-reference#bashoutputmaxchars) 設定，Claude Code 會忽略此變數。請參閱[輸出限制](/docs/zh-TW/tools-reference#output-limits) |

199| `BASH_MAX_TIMEOUT_MS` | 模型可為前景 Bash 或 PowerShell 工具命令設定的最大逾時，單位為毫秒（預設：600000，即 10 分鐘）。實際上限為此值與 `BASH_DEFAULT_TIMEOUT_MS` 兩者中較大者。超過 2 小時的實際上限也會成為無人看管工作階段中[背景命令時間限制](/docs/zh-TW/tools-reference#time-limit-for-background-commands)的上限。背景時間限制需要 Claude Code v2.1.285 或更新版本 |203| `BASH_MAX_TIMEOUT_MS` | 模型可為前景 Bash 或 PowerShell 工具命令設定的最大逾時，單位為毫秒（預設：600000，即 10 分鐘）。實際上限為此值與 `BASH_DEFAULT_TIMEOUT_MS` 中較大者。超過 2 小時的實際上限也會成為無人值守工作階段中[背景命令時間限制](/docs/zh-TW/tools-reference#time-limit-for-background-commands)的最大值。背景時間限制需要 Claude Code v2.1.285 或更新版本 |

200| `BETA_TRACING_ENDPOINT` | [詳細 beta 追蹤](/docs/zh-TW/monitoring-usage#traces-beta)的 OTLP/HTTP 端點：搭配 `ENABLE_BETA_TRACING_DETAILED=1` 時，日誌與追蹤會傳送至此處，而非已設定的匯出器。請在您的 shell、使用者設定或受管設定中設定。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略 |204| `BETA_TRACING_ENDPOINT` | 用於[詳細 beta 追蹤](/docs/zh-TW/monitoring-usage#traces-beta)的 OTLP/HTTP 端點：搭配 `ENABLE_BETA_TRACING_DETAILED=1` 時，日誌與追蹤會傳送至此處，而非已設定的匯出器。請在您的 shell、使用者設定或受管設定中設定。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略 |

201| `CCR_FORCE_BUNDLE` | 設為 `1` 可強制 [`claude --cloud`](/docs/zh-TW/claude-code-on-the-web#send-local-repositories-without-github) 打包並上傳您的本機儲存庫，而非從其遠端複製 |205| `CCR_FORCE_BUNDLE` | 設定為 `1` 可強制 [`claude --cloud`](/docs/zh-TW/claude-code-on-the-web#send-local-repositories-without-github) 打包並上傳您的本機儲存庫，而非從其遠端複製 |

202| `CLAUDECODE` | 在 Claude Code 產生的子程序（Bash 與 PowerShell 工具、tmux 工作階段、[hook](/docs/zh-TW/hooks) 命令、[狀態列](/docs/zh-TW/statusline)命令、stdio [MCP 伺服器](/docs/zh-TW/mcp)子程序）中設為 `1`。IDE 擴充功能也會在其整合式終端機中設定此變數。用於偵測指令碼是否在 Claude Code 產生的子程序中執行。若要檢查目前程序是否由工具呼叫或 hook 直接產生，而非在 Claude Code 啟動的 stdio MCP 伺服器內，請改用 `CLAUDE_CODE_CHILD_SESSION` |206| `CLAUDECODE` | 在 Claude Code 產生的子程序中設定為 `1`（Bash 與 PowerShell 工具、tmux 工作階段、[hook](/docs/zh-TW/hooks) 命令、[狀態列](/docs/zh-TW/statusline)命令、stdio [MCP 伺服器](/docs/zh-TW/mcp)子程序）。IDE 擴充功能也會在其整合式終端機中設定此變數。用於偵測腳本是否在 Claude Code 產生的子程序中執行。若要檢查目前程序是否由工具呼叫或 hook 直接產生，而非在 Claude Code 啟動的 stdio MCP 伺服器內，請改用 `CLAUDE_CODE_CHILD_SESSION` |

203| `CLAUDE_AFK_COUNTDOWN_MS` | 未回答的 [`AskUserQuestion`](/docs/zh-TW/tools-reference) 對話框在自動繼續前多少毫秒顯示畫面倒數計時。預設 `20000`（20 秒），上限為自動繼續逾時。除非已開啟自動繼續，否則不會產生作用；請參閱 [`askUserQuestionTimeout`](/docs/zh-TW/settings-reference#askuserquestiontimeout) 設定與 `CLAUDE_AFK_TIMEOUT_MS`。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略。需要 Claude Code v2.1.198 或更新版本 |207| `CLAUDE_AFK_COUNTDOWN_MS` | 在未回答的 [`AskUserQuestion`](/docs/zh-TW/tools-reference) 對話框自動繼續之前多少毫秒，螢幕上會出現倒數計時。預設 `20000`（20 秒），上限為自動繼續逾時。除非已開啟自動繼續，否則沒有作用；請參閱 [`askUserQuestionTimeout`](/docs/zh-TW/settings-reference#askuserquestiontimeout) 設定與 `CLAUDE_AFK_TIMEOUT_MS`。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略。需要 Claude Code v2.1.198 或更新版本 |

204| `CLAUDE_AFK_TIMEOUT_MS` | 未回答的 [`AskUserQuestion`](/docs/zh-TW/tools-reference) 對話框在閒置多少毫秒後，會在沒有您的情況下自動繼續。自動繼續預設為關閉；請透過 [`askUserQuestionTimeout`](/docs/zh-TW/settings-reference#askuserquestiontimeout) 設定選擇加入。此變數是供示範與自動化測試使用的覆寫：設定後，會優先於該設定，即使該設定未設定或為 `never`，也會開啟自動繼續。設定 `0` 不會關閉逾時，而是會立即關閉對話框。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略。在 v2.1.200 之前，自動繼續預設為開啟，逾時為 `60000`（60 秒）。需要 Claude Code v2.1.198 或更新版本 |208| `CLAUDE_AFK_TIMEOUT_MS` | 未回答的 [`AskUserQuestion`](/docs/zh-TW/tools-reference) 對話框在閒置多少毫秒後，會在沒有您的情況下自動繼續。自動繼續預設為關閉；請透過 [`askUserQuestionTimeout`](/docs/zh-TW/settings-reference#askuserquestiontimeout) 設定選擇加入。此變數是供示範與自動化測試使用的覆寫：設定後，它會優先於該設定，即使該設定未設定或為 `never`，也會開啟自動繼續。設定 `0` 不會關閉逾時，而是會立即關閉對話框。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略。在 v2.1.200 之前，自動繼續預設為開啟，逾時為 `60000`（60 秒）。需要 Claude Code v2.1.198 或更新版本 |

205| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 設為 `1` 可停用所有內建 [subagent](/docs/zh-TW/sub-agents) 類型，例如 Explore 與 Plan。僅適用於非互動模式（`-p` 旗標）。適合希望從零開始的 SDK 使用者。這也會移除 `general-purpose`，即當 Agent 工具呼叫省略 `subagent_type` 時 Claude Code 所執行的 subagent。此類呼叫隨後會以 [`subagent_type is required`](/docs/zh-TW/errors#subagent-type-is-required) 失敗 |209| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 設定為 `1` 可停用所有內建 [subagent](/docs/zh-TW/sub-agents) 類型，例如 Explore 與 Plan。僅適用於非互動模式（`-p` 旗標）。適合想要從零開始的 SDK 使用者。這也會移除 `general-purpose`，也就是當 Agent 工具呼叫省略 `subagent_type` 時 Claude Code 執行的 subagent。此類呼叫隨後會因 [`subagent_type is required`](/docs/zh-TW/errors#subagent-type-is-required) 而失敗 |

207| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | subagent 的停滯逾時，單位為毫秒。預設 `600000`（10 分鐘）；若您在串流監看程式開啟時提高 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`，預設值也會隨之提高，如[處理緩慢或停滯的 API 回應](/docs/zh-TW/agent-sdk/typescript#handle-slow-or-stalled-api-responses)所述。計時器會在每個串流進度事件時重設；若在時間範圍內沒有任何進度，Claude Code 會中止該 subagent 並向上層回報停滯 |211| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | subagent 的停滯逾時，單位為毫秒。在 Claude Code v2.1.286 或更新版本中也涵蓋[工作流程 agent](/docs/zh-TW/workflows#when-an-agent-stalls-and-restarts)。預設 `600000`（10 分鐘）；若您在串流監視機制開啟時調高 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`，預設值也會隨之提高，如[處理緩慢或停滯的 API 回應](/docs/zh-TW/agent-sdk/typescript#handle-slow-or-stalled-api-responses)所述 |

208| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 設定自動壓縮觸發時所占自動壓縮視窗的百分比（1-100）。使用較低的值（例如 `50`）可提早壓縮；此變數無法提高閾值，因此高於預設百分比的值會被忽略。它僅適用於[在達到模型上下文上限之前就壓縮](/docs/zh-TW/model-config#context-window-and-auto-compaction)的工作階段。同時適用於主要對話與 subagent |212| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 設定自動壓縮視窗中觸發自動壓縮的百分比（1-100）。使用較低的值（例如 `50`）可提早壓縮；此變數無法提高閾值，因此高於預設百分比的值會被忽略。它僅適用於[在模型上下文限制之前壓縮](/docs/zh-TW/model-config#context-window-and-auto-compaction)的工作階段。同時適用於主要對話與 subagent |

209| `CLAUDE_AUTO_BACKGROUND_TASKS` | 設為 `1` 可強制啟用長時間執行 agent 任務的自動背景化。啟用後，subagent 在執行約兩分鐘後會被移至背景。在 Claude Code v2.1.212 或更新版本中，也會在非互動模式下啟用[長時間 MCP 工具呼叫的自動背景化](/docs/zh-TW/mcp#automatic-backgrounding-of-long-tool-calls) |213| `CLAUDE_AUTO_BACKGROUND_TASKS` | 設定為 `1` 可強制啟用長時間執行 agent 任務的自動背景化。啟用後，subagent 在執行約兩分鐘後會移至背景。在 Claude Code v2.1.212 或更新版本中，也會在非互動模式下啟用[長時間 MCP 工具呼叫的自動背景化](/docs/zh-TW/mcp#automatic-backgrounding-of-long-tool-calls) |

210| `CLAUDE_AX_PREPARK_MS` | 在[螢幕閱讀器模式](/docs/zh-TW/accessibility)中，Claude Code 寫入新行或變更行之前等待的毫秒數。預設 `0`，因此 Claude Code 不會等待。在 v2.1.287 之前，預設值為 `50`。Claude Code 將等待時間上限設為 `5000`。需要 Claude Code v2.1.233 或更新版本 |214| `CLAUDE_AX_PREPARK_MS` | 在[螢幕閱讀器模式](/docs/zh-TW/accessibility)中，Claude Code 寫入新的或變更的行之前等待的毫秒數。預設 `0`，因此 Claude Code 不會等待。在 v2.1.287 之前，預設值為 `50`。Claude Code 將等待時間上限設為 `5000`。需要 Claude Code v2.1.233 或更新版本 |

211| `CLAUDE_AX_SCREEN_READER` | 設為 `1` 可輸出適合螢幕閱讀器的內容：不含裝飾性邊框或動畫的純文字。設為 `0` 可強制關閉螢幕閱讀器模式，即使 [`axScreenReader`](/docs/zh-TW/settings-reference#axscreenreader) 為 `true` 亦然。[`--ax-screen-reader`](/docs/zh-TW/cli-reference#cli-flags) 旗標具有優先權。需要 Claude Code v2.1.181 或更新版本 |215| `CLAUDE_AX_SCREEN_READER` | 設定為 `1` 可呈現適合螢幕閱讀器的輸出：不含裝飾性邊框或動畫的平面文字。設定為 `0` 可強制關閉螢幕閱讀器模式，即使 [`axScreenReader`](/docs/zh-TW/settings-reference#axscreenreader) 為 `true`。[`--ax-screen-reader`](/docs/zh-TW/cli-reference#cli-flags) 旗標優先。需要 Claude Code v2.1.181 或更新版本 |

212| `CLAUDE_AX_STARTUP_QUIET_MS` | 在[螢幕閱讀器模式](/docs/zh-TW/accessibility)中，Claude Code 在啟動確認行之後暫緩第一次介面繪製的毫秒數，讓您的螢幕閱讀器能在新輸出打斷之前完整唸出該行。預設 `3000`。設為 `0` 可立即繪製。Claude Code 將暫緩時間上限設為 `600000`（10 分鐘）。您的第一次按鍵會提早結束暫緩。需要 Claude Code v2.1.217 或更新版本 |216| `CLAUDE_AX_STARTUP_QUIET_MS` | 在[螢幕閱讀器模式](/docs/zh-TW/accessibility)中，Claude Code 在啟動確認行之後延遲第一次介面呈現的毫秒數，讓您的螢幕閱讀器能在新輸出打斷之前完整唸出該行。預設 `3000`。設定 `0` 可立即呈現。Claude Code 將延遲上限設為 `600000`（10 分鐘）。您的第一次按鍵會提早結束延遲。需要 Claude Code v2.1.217 或更新版本 |

214| `CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` | 位元組層級串流閒置監看程式的逾時，單位為毫秒；設定後，對該監看程式而言會優先於 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`，且不會變更事件層級監看程式。Claude Code 會將此變數限制在 10 秒到 30 分鐘之間。需要 Claude Code v2.1.210 或更新版本 |218| `CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` | 位元組層級串流閒置監視機制的逾時，單位為毫秒；設定後，對於該監視機制，它優先於 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`，且不會變更事件層級的監視機制。Claude Code 會將此變數限制在 10 秒到 30 分鐘之間。需要 Claude Code v2.1.210 或更新版本 |

215| `CLAUDE_CLIENT_PRESENCE_FILE` | 某個檔案的路徑，由外部工具（例如螢幕鎖定監聽程式）在您解鎖螢幕時建立、在您鎖定螢幕時刪除。當該檔案存在時，Claude Code 會略過 [Remote Control 行動推播通知](/docs/zh-TW/remote-control#mobile-push-notifications)，因此在您正在使用電腦時不會收到推播。當檔案不存在或無法讀取時，通知會照常傳送。Claude Code 會在每個觸發推播的事件發生時檢查一次該檔案，而不是持續輪詢。需要 Claude Code v2.1.181 或更新版本 |219| `CLAUDE_CLIENT_PRESENCE_FILE` | 一個檔案的路徑，由外部工具（例如螢幕鎖定監聽器）在您解鎖螢幕時建立、在您鎖定螢幕時刪除。檔案存在期間，Claude Code 會略過 [Remote Control 行動推播通知](/docs/zh-TW/remote-control#mobile-push-notifications)，因此您在主動使用電腦時不會收到推播。檔案不存在或無法讀取時，通知會照常傳送。Claude Code 會在每個觸發推播的事件發生時檢查一次檔案，而非輪詢。需要 Claude Code v2.1.181 或更新版本 |

217| `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` | 設為 `1` 可從以 `--add-dir` 指定的目錄載入記憶檔案。會載入 `CLAUDE.md`、`.claude/CLAUDE.md`、`.claude/rules/*.md` 與 `CLAUDE.local.md`。預設情況下，額外目錄不會載入記憶檔案 |221| `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` | 設定為 `1` 可從以 `--add-dir` 指定的目錄載入記憶檔案。會載入 `CLAUDE.md`、`.claude/CLAUDE.md`、`.claude/rules/*.md` 與 `CLAUDE.local.md`。預設情況下，額外目錄不會載入記憶檔案 |

218| `CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT` | 設為 `1` 可在[全螢幕繪製](/docs/zh-TW/fullscreen)中每一格都重繪整個畫面，而非傳送增量更新。若全螢幕模式顯示過時或位置錯誤的文字片段，請使用此變數。Claude Code 會在 Windows 上為背景工作階段與 [agent view](/docs/zh-TW/agent-view) 自動啟用此功能 |222| `CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT` | 設定為 `1` 可在[全螢幕呈現](/docs/zh-TW/fullscreen)中每個影格重繪整個畫面，而非傳送增量更新。若全螢幕模式顯示過時或錯位的文字片段，請使用此設定。Claude Code 會在 Windows 上為背景工作階段與 [agent view](/docs/zh-TW/agent-view) 自動啟用此設定 |

219| `CLAUDE_CODE_ALWAYS_ENABLE_EFFORT` | 設為 `1` 可在每個請求中傳送 [effort](/docs/zh-TW/model-config#adjust-effort-level) 參數，即使 Claude Code 無法辨識該模型 ID 支援 effort 亦然。當您透過以自訂識別碼提供模型的 [LLM 閘道](/docs/zh-TW/llm-gateway)或第三方供應商路由時，請使用此變數。在 API 端拒絕 effort 參數的模型，包括 Claude 3 模型、Sonnet 4.0 與 4.5、Opus 4.0 與 4.1，以及 Haiku 4.5，仍會被排除，以免請求失敗 |223| `CLAUDE_CODE_ALWAYS_ENABLE_EFFORT` | 設定為 `1` 可在每個請求中傳送 [effort](/docs/zh-TW/model-config#adjust-effort-level) 參數，即使 Claude Code 不認為該模型 ID 支援 effort。在透過以自訂識別碼提供模型的 [LLM 閘道](/docs/zh-TW/llm-gateway)或第三方提供者路由時使用。在 API 端拒絕 effort 參數的模型，包括 Claude 3 模型、Sonnet 4.0 與 4.5、Opus 4.0 與 4.1，以及 Haiku 4.5，仍會被排除，以免請求失敗 |

220| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` | 重新整理憑證的間隔，單位為毫秒（使用 [`apiKeyHelper`](/docs/zh-TW/settings-reference#apikeyhelper) 時） |224| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` | 應重新整理憑證的間隔，單位為毫秒（使用 [`apiKeyHelper`](/docs/zh-TW/settings-reference#apikeyhelper) 時） |

221| `CLAUDE_CODE_ARTIFACT_AUTO_OPEN` | 設為 `0` 可讓 Claude Code 在發布新的 [artifact](/docs/zh-TW/artifacts#create-an-artifact) 時不自動開啟瀏覽器 |225| `CLAUDE_CODE_ARTIFACT_AUTO_OPEN` | 設定為 `0` 可阻止 Claude Code 在發布新的 [artifact](/docs/zh-TW/artifacts#create-an-artifact) 時自動開啟瀏覽器 |

222| `CLAUDE_CODE_ARTIFACT_COMMENTS` | 設為 `0` 可讓 Claude 停止讀取與回覆 [artifact 上的留言](/docs/zh-TW/artifacts#collect-comments-on-an-artifact)。當 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 已[關閉 artifact](/docs/zh-TW/artifacts#availability) 時不會產生作用。需要 Claude Code v2.1.221 或更新版本 |226| `CLAUDE_CODE_ARTIFACT_COMMENTS` | 設定為 `0` 可阻止 Claude 讀取及回覆 [artifact 上的留言](/docs/zh-TW/artifacts#collect-comments-on-an-artifact)。當 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 已[關閉 artifact](/docs/zh-TW/artifacts#availability) 時沒有作用。需要 Claude Code v2.1.221 或更新版本 |

223| `CLAUDE_CODE_ARTIFACT_COMMENTS_AUTOREACT` | 設為 `0` 可讓 Claude 停止[自行回覆傳送給它的留言](/docs/zh-TW/artifacts#let-claude-reply-to-comments-on-its-own)。需要 Claude Code v2.1.228 或更新版本 |227| `CLAUDE_CODE_ARTIFACT_COMMENTS_AUTOREACT` | 設定為 `0` 可阻止 Claude [自行回覆傳送給它的留言](/docs/zh-TW/artifacts#let-claude-reply-to-comments-on-its-own)。需要 Claude Code v2.1.228 或更新版本 |

224| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 設為 `0` 可從系統提示詞開頭省略[歸屬區塊](/docs/zh-TW/llm-gateway-protocol#system-prompt-attribution-block)，該區塊包含用戶端版本與提示詞指紋。無論如何，直接連線至 Anthropic API 時的快取都不受影響。在某些直接連線的設定中，即使您設定 `0`，Claude Code 仍會在[自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)分類器請求上保留該區塊。請在[系統提示詞歸屬區塊](/docs/zh-TW/llm-gateway-protocol#system-prompt-attribution-block)中查看涵蓋哪些連線與憑證。在 v2.1.181 之前，該區塊在自訂基底 URL 與 Microsoft Foundry 連線上包含每次請求的 token，因此在這些版本中，當您的 LLM 閘道依據請求主體進行快取或將請求轉送至第三方供應商，或當您直接連線至 Microsoft Foundry 時，請將其設為 `0` |228| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 設定為 `0` 可從系統提示詞開頭省略[歸屬區塊](/docs/zh-TW/llm-gateway-protocol#system-prompt-attribution-block)，該區塊包含用戶端版本與提示詞指紋。無論如何，直接連線至 Anthropic API 時的快取都不受影響。在某些直接連線設定中，即使您設定了 `0`，Claude Code 仍會在[自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)分類器請求中保留此區塊。請在[系統提示詞歸屬區塊](/docs/zh-TW/llm-gateway-protocol#system-prompt-attribution-block)中查看此情況涵蓋哪些連線與憑證。在 v2.1.181 之前，此區塊在自訂基礎 URL 與 Microsoft Foundry 連線上包含每個請求專屬的 token，因此在這些版本上，當您的 LLM 閘道依請求本文進行快取或將請求轉送至第三方提供者時，或當您直接連線至 Microsoft Foundry 時，請將其設定為 `0` |

226| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 以 token 為單位設定[自動壓縮視窗](/docs/zh-TW/model-config#set-the-auto-compact-window)，範圍從 `100000` 到 `1000000`。僅接受純整數，例如 `500000`：像 `500k` 這樣的值會被讀取為 `500`，並被限制為 100K 的最小值。實際視窗也會以模型的上下文視窗為上限。優先於 `/autocompact` 命令、`--autocompact` 旗標與 `autoCompactWindow` 設定。狀態列的 `used_percentage` 一律以模型的完整上下文視窗為基準計算，因此一旦設定此變數，該百分比就不再代表壓縮何時會執行 |230| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 設定[自動壓縮視窗](/docs/zh-TW/model-config#set-the-auto-compact-window)，單位為 token，範圍從 `100000` 到 `1000000`。僅接受純整數，例如 `500000`：像 `500k` 這樣的值會被讀取為 `500`，並被限制為 100K 最小值。實際視窗也以模型的上下文視窗為上限。優先於 `/autocompact` 命令、`--autocompact` 旗標與 `autoCompactWindow` 設定。狀態列的 `used_percentage` 一律以模型的完整上下文視窗為基準，因此一旦設定此變數，該百分比就不再代表壓縮何時會執行 |

227| `CLAUDE_CODE_AUTO_CONNECT_IDE` | 覆寫自動 [IDE 連線](/docs/zh-TW/vs-code)。預設情況下，在受支援 IDE 的整合式終端機中啟動時，Claude Code 會自動連線。設為 `false` 可避免此行為。當自動偵測失敗時（例如 tmux 遮蔽了上層終端機），設為 `true` 可強制嘗試連線。優先於 [`autoConnectIde`](/docs/zh-TW/settings-reference#autoconnectide) 全域設定 |231| `CLAUDE_CODE_AUTO_CONNECT_IDE` | 覆寫自動 [IDE 連線](/docs/zh-TW/vs-code)。預設情況下，在支援的 IDE 整合式終端機中啟動時，Claude Code 會自動連線。設定為 `false` 可防止此行為。設定為 `true` 可在自動偵測失敗時（例如 tmux 遮蔽了父終端機）強制嘗試連線。優先於 [`autoConnectIde`](/docs/zh-TW/settings-reference#autoconnectide) 全域設定 |

228| `CLAUDE_CODE_AUTO_MODE_SERVER` | 控制 Claude Code 是否請求伺服器[審查自動模式動作](/docs/zh-TW/permission-modes#server-side-classifier-review)。設為 `0` 可改用 Claude Code 本身的分類器請求。直接連線至 Anthropic API 時，需要 v2.1.281 或更新版本。連結的章節列出了在未設定此變數時哪些工作階段會請求伺服器，以及自哪個版本起適用。需要 Claude Code v2.1.271 或更新版本 |232| `CLAUDE_CODE_AUTO_MODE_SERVER` | 控制 Claude Code 是否要求伺服器[審查自動模式動作](/docs/zh-TW/permission-modes#server-side-classifier-review)。設定為 `0` 可改用 Claude Code 自己的分類器請求。直接連線至 Anthropic API 時，需要 v2.1.281 或更新版本。連結的章節列出了變數未設定時哪些工作階段會詢問伺服器，以及從哪個版本開始。需要 Claude Code v2.1.271 或更新版本 |

229| `CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS` | Claude Code 等待 AWS 預設憑證提供者鏈產生憑證的時間，單位為毫秒，逾時後請求會以 [`AWS default-chain credential resolve timed out`](/docs/zh-TW/errors#aws-default-chain-credential-resolve-timed-out) 失敗（預設：`60000`）。當您的憑證鏈中某個步驟確實需要更長時間時（例如透過 `aws-vault` 等包裝工具以瀏覽器進行含 MFA 的 SSO 登入），請提高此值。適用於 Amazon Bedrock、[Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 與 [Mantle 端點](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint)。請參閱[憑證快取與解析逾時](/docs/zh-TW/amazon-bedrock#credential-caching-and-resolution-timeout)。需要 Claude Code v2.1.207 或更新版本 |233| `CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS` | Claude Code 等待 AWS 預設憑證提供者鏈產生憑證的時間，單位為毫秒，超過後請求會因 [`AWS default-chain credential resolve timed out`](/docs/zh-TW/errors#aws-default-chain-credential-resolve-timed-out) 而失敗（預設：`60000`）。當您的鏈中某個步驟確實需要更長時間時（例如透過 `aws-vault` 等包裝工具進行含 MFA 的瀏覽器型 SSO 登入），請調高此值。適用於 Amazon Bedrock、[Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 與 [Mantle 端點](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint)。請參閱[憑證快取與解析逾時](/docs/zh-TW/amazon-bedrock#credential-caching-and-resolution-timeout)。需要 Claude Code v2.1.207 或更新版本 |

230| `CLAUDE_CODE_BASH_EDIT_DIFF` | 設為 `0` 可關閉 [Bash 命令執行期間變更之檔案的差異](/docs/zh-TW/hooks#bash)，設為 `1` 則可在每種權限模式下記錄。優先於 [`bashEditDiffEnabled`](/docs/zh-TW/settings-reference#basheditdiffenabled) 設定。需要 Claude Code v2.1.269 或更新版本 |234| `CLAUDE_CODE_BASH_EDIT_DIFF` | 設定為 `0` 可關閉 [Bash 命令執行期間所變更檔案的差異](/docs/zh-TW/hooks#bash)，或設定為 `1` 以在每種權限模式下記錄。優先於 [`bashEditDiffEnabled`](/docs/zh-TW/settings-reference#basheditdiffenabled) 設定。需要 Claude Code v2.1.269 或更新版本 |

231| `CLAUDE_CODE_BG_TASKS_REPORT_RUNNING` | 設為 `0` 可讓非互動工作階段在每個回合結束時向其主機回報閒置狀態，即使背景工作仍在執行亦然。預設情況下，當背景 agent 或[工作流程](/docs/zh-TW/workflows)執行等背景工作仍在進行時，工作階段在回合結束後仍會持續回報執行中狀態。這能避免監看狀態的主機（例如遠端工作階段清單）在工作進行到一半時宣告 Claude 正在等待您的輸入。背景 shell 命令（例如開發伺服器）不會維持執行中狀態。執行中狀態預設值與 `0` 退出選項需要 Claude Code v2.1.269 或更新版本；在較早版本中，請設定 `1` 以維持執行中狀態 |235| `CLAUDE_CODE_BG_TASKS_REPORT_RUNNING` | 設定為 `0` 可讓非互動工作階段在每個回合結束時向其主機回報閒置狀態，即使背景工作仍在執行。預設情況下，當背景 agent 或[工作流程](/docs/zh-TW/workflows)執行等背景工作仍在進行時，工作階段在回合結束後會持續回報執行中狀態。這可避免監看狀態的主機（例如遠端工作階段清單）在工作進行中宣告 Claude 正在等待您的輸入。背景 shell 命令（例如開發伺服器）不會維持執行中狀態。執行中狀態的預設行為與 `0` 退出選項需要 Claude Code v2.1.269 或更新版本；在較早版本中，請設定 `1` 以維持執行中狀態 |

232| `CLAUDE_CODE_BRIDGE_SESSION_ID` | 當工作階段具有作用中的 [Remote Control](/docs/zh-TW/remote-control) 連線時，會在 Bash 工具與 [hook 命令](/docs/zh-TW/hooks)子程序中自動設定，並在連線結束時移除。其值為 `session_` 形式的工作階段 ID，與工作階段的 `claude.ai/code` URL 中出現的識別碼相同，因此指令碼可以連結回執行它的工作階段。需要 Claude Code v2.1.199 或更新版本。在[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)中，請改為讀取 `CLAUDE_CODE_REMOTE_SESSION_ID` |236| `CLAUDE_CODE_BRIDGE_SESSION_ID` | 當工作階段有作用中的 [Remote Control](/docs/zh-TW/remote-control) 連線時，會在 Bash 工具與 [hook 命令](/docs/zh-TW/hooks)子程序中自動設定，並在連線結束時移除。其值為 `session_` 形式的工作階段 ID，與出現在工作階段 `claude.ai/code` URL 中的識別碼相同，因此腳本可以連結回執行它的工作階段。需要 Claude Code v2.1.199 或更新版本。在[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)中，請改為讀取 `CLAUDE_CODE_REMOTE_SESSION_ID` |

233| `CLAUDE_CODE_BS_AS_CTRL_BACKSPACE` | 設為 `0` 可讓 Claude Code 將 `0x08` 位元組（也寫作 `^H`）讀取為一般 Backspace，設為 `1` 則讀取為 Ctrl+Backspace。任一值都會取代平台預設值。預設情況下，Claude Code 在 Windows 上會將其讀取為 Ctrl+Backspace（但 `TERM_PROGRAM` 為 `mintty` 或 `TERM` 為 `cygwin` 時除外），在 macOS 與 Linux 上則讀取為一般 Backspace。在 [Backspace 會刪除整個單字](/docs/zh-TW/terminal-config#fix-backspace-deleting-a-whole-word-on-windows)的 Windows 終端機中，請設定 `0` |237| `CLAUDE_CODE_BS_AS_CTRL_BACKSPACE` | 設定為 `0` 可讓 Claude Code 將 `0x08` 位元組（也寫作 `^H`）讀取為一般 Backspace，設定為 `1` 則讀取為 Ctrl+Backspace。任一值都會取代平台預設值。預設情況下，Claude Code 在 Windows 上將其讀取為 Ctrl+Backspace（`TERM_PROGRAM` 為 `mintty` 或 `TERM` 為 `cygwin` 時除外），在 macOS 與 Linux 上則讀取為一般 Backspace。在 [Backspace 會刪除整個單字](/docs/zh-TW/terminal-config#fix-backspace-deleting-a-whole-word-on-windows)的 Windows 終端機中請設定 `0` |

234| `CLAUDE_CODE_CERT_STORE` | 以逗號分隔的 TLS 連線 CA 憑證來源清單。`bundled` 是 Claude Code 隨附的 Mozilla CA 集合。`system` 是作業系統信任存放區，僅在具有 `tls.getCACertificates` 的執行環境上讀取：原生二進位檔，或 npm 安裝時的 Node 22.15 或更新版本。請參閱 [CA 憑證存放區](/docs/zh-TW/network-config#ca-certificate-store)。預設為 `bundled,system` |238| `CLAUDE_CODE_CERT_STORE` | TLS 連線的 CA 憑證來源清單，以逗號分隔。`bundled` 是隨 Claude Code 提供的 Mozilla CA 集合。`system` 是作業系統信任存放區，僅在具有 `tls.getCACertificates` 的執行環境中讀取：原生二進位檔，或 npm 安裝時的 Node 22.15 或更新版本。請參閱 [CA 憑證存放區](/docs/zh-TW/network-config#ca-certificate-store)。預設為 `bundled,system` |

235| `CLAUDE_CODE_CHILD_SESSION` | 在 Claude Code 透過 Bash、PowerShell 與 Monitor 工具、[hook](/docs/zh-TW/hooks) 命令以及[狀態列](/docs/zh-TW/statusline)命令產生的子程序中設為 `1`。不會為 stdio [MCP 伺服器](/docs/zh-TW/mcp)子程序設定，因為它們是長期存在的，且存活時間比產生它們的工作階段更長。與 `CLAUDECODE` 不同，此變數僅由 Claude Code 本身在啟動子程序時設定，IDE 擴充功能不會設定，因此能可靠地區分巢狀工作階段與在 IDE 整合式終端機中啟動的頂層 `claude`。以此方式啟動的巢狀互動式 `claude` TUI 會自動從 `--resume`、`--continue`、上方向鍵歷史記錄與 `claude agents` 清單中排除。非互動的 `claude -p` 工作階段仍會保存。設定 `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1` 可覆寫此排除。需要 Claude Code v2.1.172 或更新版本 |239| `CLAUDE_CODE_CHILD_SESSION` | 在 Claude Code 透過 Bash、PowerShell 與 Monitor 工具、[hook](/docs/zh-TW/hooks) 命令及[狀態列](/docs/zh-TW/statusline)命令產生的子程序中設定為 `1`。不會為 stdio [MCP 伺服器](/docs/zh-TW/mcp)子程序設定，因為這些子程序長期存在，且會比產生它們的工作階段存活更久。不同於 `CLAUDECODE`，此變數僅由 Claude Code 本身在啟動子程序時設定，而不會由 IDE 擴充功能設定，因此能可靠地區分巢狀工作階段與在 IDE 整合式終端機中啟動的頂層 `claude`。以此方式啟動的巢狀互動式 `claude` TUI 會自動從 `--resume`、`--continue`、向上鍵歷史記錄與 `claude agents` 清單中排除。非互動 `claude -p` 工作階段仍會保存。設定 `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1` 可覆寫此排除。需要 Claude Code v2.1.172 或更新版本 |

239| `CLAUDE_CODE_CONNECT_TIMEOUT_MS` | 已於 v2.1.186 移除，現在不會產生任何作用。先前用於為串流 API 請求的連線、TLS 與回應標頭階段設定個別逾時。請使用 `API_TIMEOUT_MS` 設定每個請求的逾時。關於串流請求的回應標頭階段，請參閱 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` |243| `CLAUDE_CODE_CONNECT_TIMEOUT_MS` | 已於 v2.1.186 移除，現在不會有任何作用。先前用於為串流 API 請求的連線、TLS 與回應標頭階段設定個別逾時。請使用 `API_TIMEOUT_MS` 設定每個請求的逾時。關於串流請求的回應標頭階段，請參閱 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` |

240| `CLAUDE_CODE_DEBUG_LOGS_DIR` | 覆寫偵錯日誌檔案路徑。儘管名稱如此，這是檔案路徑，而非目錄。需要另外透過 `--debug`、`/debug` 或 `DEBUG` 環境變數啟用偵錯模式：單獨設定此變數並不會啟用日誌記錄。[`--debug-file`](/docs/zh-TW/cli-reference#cli-flags) 旗標可一次完成兩者。預設為 `~/.claude/debug/<session-id>.txt` |244| `CLAUDE_CODE_DEBUG_LOGS_DIR` | 覆寫偵錯日誌檔案路徑。儘管名稱如此，這是檔案路徑，而非目錄。需要另外透過 `--debug`、`/debug` 或 `DEBUG` 環境變數啟用偵錯模式：僅設定此變數並不會啟用日誌記錄。[`--debug-file`](/docs/zh-TW/cli-reference#cli-flags) 旗標可同時完成這兩件事。預設為 `~/.claude/debug/<session-id>.txt` |

241| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | 寫入偵錯日誌檔案的最低日誌層級。值：`verbose`、`debug`（預設）、`info`、`warn`、`error`。設為 `verbose` 可包含大量診斷資訊，例如完整的狀態列命令輸出；或提高至 `error` 以減少雜訊 |245| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | 寫入偵錯日誌檔案的最低日誌等級。值：`verbose`、`debug`（預設）、`info`、`warn`、`error`。設定為 `verbose` 可包含大量診斷資訊，例如完整的狀態列命令輸出；或提高至 `error` 以減少雜訊 |

242| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | 設為 `1` 可關閉 [1M 上下文視窗](/docs/zh-TW/model-config#extended-context)支援。Claude Code 會從模型選擇器中移除 `[1m]` 模型變體，並將預設以 1M 視窗執行的模型限制為 200K 視窗。請參閱[關閉 1M 上下文](/docs/zh-TW/model-config#turn-off-1m-context)。適用於有合規要求的企業環境。關於其在修正無法辨識之 `[1m]` 模型 ID 視窗時的作用，請參閱[修正閘道或自訂模型 ID 的視窗](/docs/zh-TW/model-config#correct-the-window-for-a-gateway-or-custom-model-id) |246| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | 設定為 `1` 可關閉 [1M 上下文視窗](/docs/zh-TW/model-config#extended-context)支援。Claude Code 會從模型選擇器中移除 `[1m]` 模型變體，並將預設以 1M 視窗執行的模型限制為 200K 視窗。請參閱[關閉 1M 上下文](/docs/zh-TW/model-config#turn-off-1m-context)。適用於有合規要求的企業環境。關於其在修正無法辨識的 `[1m]` 模型 ID 視窗方面的作用，請參閱[修正閘道或自訂模型 ID 的視窗](/docs/zh-TW/model-config#correct-the-window-for-a-gateway-or-custom-model-id) |

243| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | 設為 `1` 可在 Opus 4.6 與 Sonnet 4.6 上停用[自適應推理](/docs/zh-TW/model-config#adjust-effort-level)，並改用由 `MAX_THINKING_TOKENS` 控制的固定思考預算。對 [Fable 模型](/docs/zh-TW/model-config#extended-thinking)、Sonnet 5 及更新版本、Haiku 5.5，或 Opus 4.7 及更新版本沒有作用，這些模型一律使用自適應推理 |247| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | 設定為 `1` 可在 Opus 4.6 與 Sonnet 4.6 上停用[自適應推理](/docs/zh-TW/model-config#adjust-effort-level)，並改用由 `MAX_THINKING_TOKENS` 控制的固定思考預算。對 [Fable 模型](/docs/zh-TW/model-config#extended-thinking)、Sonnet 5 及更新版本、Haiku 5.5 或 Opus 4.7 及更新版本沒有作用，這些模型一律使用自適應推理 |

244| `CLAUDE_CODE_DISABLE_ADMIN_ENV_UNION` | 設為 `1` 可讓 Claude Code 停止跨管理來源逐鍵合併[受管設定](/docs/zh-TW/managed-settings#precedence-within-the-managed-tier)的 `env` 區塊，因此只會套用最高優先順序來源的整個 `env` 區塊，與 v2.1.223 之前相同。請在啟動 Claude Code 的環境中設定，因為 Claude Code 會忽略透過設定 `env` 區塊傳遞的副本。需要 Claude Code v2.1.223 或更新版本 |248| `CLAUDE_CODE_DISABLE_ADMIN_ENV_UNION` | 設定為 `1` 可阻止 Claude Code 跨管理來源逐鍵合併[受管設定](/docs/zh-TW/managed-settings#precedence-within-the-managed-tier)的 `env` 區塊，因此只會套用最高優先順序來源的整個 `env` 區塊，與 v2.1.223 之前相同。請在啟動 Claude Code 的環境中設定，因為 Claude Code 會忽略透過設定 `env` 區塊傳遞的副本。需要 Claude Code v2.1.223 或更新版本 |

245| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | 設為 `1` 可停用 [advisor 工具](/docs/zh-TW/advisor)。`/advisor` 命令會變得無法使用，任何已設定的 `advisorModel` 都會被忽略，而 `--advisor` 旗標雖會被接受但不會產生作用，因此傳入此旗標的現有指令碼仍可正常運作而不會出錯 |249| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | 設定為 `1` 可停用 [advisor 工具](/docs/zh-TW/advisor)。`/advisor` 命令將無法使用，任何已設定的 `advisorModel` 都會被忽略，而 `--advisor` 旗標會被接受但沒有作用，因此傳遞此旗標的現有腳本仍可繼續運作而不會出錯 |

246| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | 設為 `1` 可關閉[背景 agent 與 agent view](/docs/zh-TW/agent-view)：`claude agents`、`--bg`、`/background` 與隨需 supervisor。等同於 [`disableAgentView`](/docs/zh-TW/settings-reference#disableagentview) 設定 |250| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | 設定為 `1` 可關閉[背景 agent 與 agent view](/docs/zh-TW/agent-view)：`claude agents`、`--bg`、`/background` 以及隨需啟動的 supervisor。等同於 [`disableAgentView`](/docs/zh-TW/settings-reference#disableagentview) 設定 |

247| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | 設為 `1` 可停用[全螢幕繪製](/docs/zh-TW/fullscreen)並使用傳統的主畫面繪製器。對話會保留在終端機的原生捲動緩衝區中，因此 `Cmd+f` 與 tmux 複製模式可照常運作。優先於 `CLAUDE_CODE_NO_FLICKER` 與 [`tui`](/docs/zh-TW/settings-reference#tui) 設定。您也可以使用 `/tui default` 切換。不適用於從 [agent view](/docs/zh-TW/agent-view) 開啟的背景工作階段，這些工作階段一律使用全螢幕繪製 |251| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | 設定為 `1` 可停用[全螢幕呈現](/docs/zh-TW/fullscreen)並使用傳統的主畫面呈現器。對話會保留在終端機的原生捲動緩衝區中，因此 `Cmd+f` 與 tmux 複製模式可照常運作。優先於 `CLAUDE_CODE_NO_FLICKER` 與 [`tui`](/docs/zh-TW/settings-reference#tui) 設定。您也可以使用 `/tui default` 切換。不適用於從 [agent view](/docs/zh-TW/agent-view) 開啟的背景工作階段，這些工作階段一律使用全螢幕呈現 |

248| `CLAUDE_CODE_DISABLE_ARTIFACT` | 設為 `1` 可關閉 [Artifact](/docs/zh-TW/artifacts) 工具，該工具會將工作階段輸出發布為 claude.ai 上的私人網頁。一旦設定，任何設定檔都無法重新開啟此工具。若要改從設定檔關閉此工具，請將 [`enableArtifact`](/docs/zh-TW/settings-reference#enableartifact) 設為 `false`；已棄用的 [`disableArtifact`](/docs/zh-TW/settings-reference#disableartifact) 鍵也能將其關閉 |252| `CLAUDE_CODE_DISABLE_ARTIFACT` | 設定為 `1` 可關閉 [Artifact](/docs/zh-TW/artifacts) 工具，該工具會將工作階段輸出發布為 claude.ai 上的私人網頁。一旦設定，任何設定檔都無法重新開啟此工具。若要改從設定檔關閉此工具，請將 [`enableArtifact`](/docs/zh-TW/settings-reference#enableartifact) 設定為 `false`；已棄用的 [`disableArtifact`](/docs/zh-TW/settings-reference#disableartifact) 鍵也會將其關閉 |

249| `CLAUDE_CODE_DISABLE_ATTACHMENTS` | 設為 `1` 可停用附件處理。以 `@` 語法提及的檔案會以純文字傳送，而不會展開為檔案內容。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略 |253| `CLAUDE_CODE_DISABLE_ATTACHMENTS` | 設定為 `1` 可停用附件處理。使用 `@` 語法的檔案提及會以純文字傳送，而不會展開為檔案內容。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略 |

250| `CLAUDE_CODE_DISABLE_AUTH_REFRESH_LOCK` | 設為 `1` 可讓 Claude Code 程序自行執行其 [`gcpAuthRefresh`](/docs/zh-TW/settings-reference#gcpauthrefresh) 或 [`awsAuthRefresh`](/docs/zh-TW/settings-reference#awsauthrefresh) 命令，而非在另一個程序執行時等待。需要 Claude Code v2.1.286 或更新版本 |254| `CLAUDE_CODE_DISABLE_AUTH_REFRESH_LOCK` | 設定為 `1` 可讓 Claude Code 程序自行執行其 [`gcpAuthRefresh`](/docs/zh-TW/settings-reference#gcpauthrefresh) 或 [`awsAuthRefresh`](/docs/zh-TW/settings-reference#awsauthrefresh) 命令，而非在另一個程序執行時等待。需要 Claude Code v2.1.286 或更新版本 |

251| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | 設為 `1` 可停用[自動記憶](/docs/zh-TW/memory#auto-memory)。設為 `0` 可強制開啟自動記憶，即使 `--bare` 模式或 [`autoMemoryEnabled: false`](/docs/zh-TW/settings-reference#automemoryenabled) 原本會將其停用亦然。停用時，Claude 不會建立或載入自動記憶檔案 |255| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | 設定為 `1` 可停用[自動記憶](/docs/zh-TW/memory#auto-memory)。設定為 `0` 可強制開啟自動記憶，即使 `--bare` 模式或 [`autoMemoryEnabled: false`](/docs/zh-TW/settings-reference#automemoryenabled) 原本會將其停用。停用時，Claude 不會建立或載入自動記憶檔案 |

252| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | 設為 `1` 可停用所有背景任務功能，包括 Bash 與 subagent 工具上的 `run_in_background` 參數、自動背景化，以及 Ctrl+B 快捷鍵 |256| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | 設定為 `1` 可停用所有背景任務功能，包括 Bash 與 subagent 工具上的 `run_in_background` 參數、自動背景化，以及 Ctrl+B 快速鍵 |

253| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_DEFAULT` | 設為 `1` 可讓 Claude Code 停止將缺少或為空的 `Content-Type` 標頭的 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 串流回應視為 Amazon Bedrock 的二進位事件串流。預設情況下，Claude Code 會假設是閘道從原本未修改的回應中移除了該標頭，因此會解碼主體，讓串流繼續運作。請僅在閘道也會將串流重新輸出為 server-sent events 時才設定此變數；屆時 Claude Code 會改將沒有標頭的主體讀取為 server-sent events。需要 Claude Code v2.1.239 或更新版本 |257| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_DEFAULT` | 設定為 `1` 可阻止 Claude Code 將缺少或為空 `Content-Type` 標頭的 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 串流回應視為 Amazon Bedrock 的二進位事件串流。預設情況下，Claude Code 假設是閘道從原本未經修改的回應中移除了該標頭，因此會解碼本文，讓串流持續運作。僅針對也會將串流重新輸出為 server-sent events 的閘道設定此變數；Claude Code 隨後會將沒有標頭的本文讀取為 server-sent events。需要 Claude Code v2.1.239 或更新版本 |

254| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` | 設為 `1` 可略過 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 串流回應是否帶有 `application/vnd.amazon.eventstream` content-type 的檢查。若未設定此變數，當回應帶有不同的 content-type 時，Claude Code 會讓請求失敗，並顯示指出該類型的錯誤，這表示[閘道或代理伺服器正在轉換回應](/docs/zh-TW/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)。請將閘道設定為不經修改地轉送 `Content-Type` 標頭與主體，而非設定此變數。需要 Claude Code v2.1.208 或更新版本 |258| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` | 設定為 `1` 可略過檢查 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 串流回應是否帶有 `application/vnd.amazon.eventstream` content-type。若未設定此變數，當回應帶有不同的 content-type 時，Claude Code 會使請求失敗，並顯示指出該類型的錯誤，這表示[閘道或代理伺服器正在轉換回應](/docs/zh-TW/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)。請將閘道設定為原封不動地轉送 `Content-Type` 標頭與本文，而非設定此變數。需要 Claude Code v2.1.208 或更新版本 |

255| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | 設為 `1` 可在 [supervisor](/docs/zh-TW/agent-view#the-supervisor-process) 停止、重新啟動或更新[背景工作階段](/docs/zh-TW/agent-view)的程序時，停止該工作階段正在執行的背景 shell 命令、動態工作流程，以及自 v2.1.198 起的背景 subagent，而非將它們交接給該工作階段的下一個程序。僅影響該交接：使用 `←` 或 [`/background`](/docs/zh-TW/agent-view#from-inside-a-session) 將工作階段移至背景時，進行中的工作仍會延續，而 `CLAUDE_DISABLE_ADOPT` 會同時關閉兩者。需要 Claude Code v2.1.196 或更新版本 |259| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | 設定為 `1` 可在 [supervisor](/docs/zh-TW/agent-view#the-supervisor-process) 停止、重新啟動或更新[背景工作階段](/docs/zh-TW/agent-view)的程序時，停止該工作階段正在執行的背景 shell 命令、動態工作流程，以及（自 v2.1.198 起）背景 subagent，而非將它們交給該工作階段的下一個程序。僅影響此交接：使用 `←` 或 [`/background`](/docs/zh-TW/agent-view#from-inside-a-session) 將工作階段移至背景時，仍會延續進行中的工作，而 `CLAUDE_DISABLE_ADOPT` 會同時關閉兩者。需要 Claude Code v2.1.196 或更新版本 |

256| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | 設為 `1` 可讓 Claude Code 不在記憶體壓力下終止[背景 shell 命令](/docs/zh-TW/interactive-mode#background-bash-commands)。預設情況下，在 macOS 與 Linux 上，當作業系統回報嚴重記憶體壓力，且工作階段已閒置 30 分鐘、沒有任何回合或 subagent 在執行時，Claude Code 會終止背景 shell。Windows 沒有記憶體壓力訊號，因此此變數在該平台上沒有作用。需要 Claude Code v2.1.193 或更新版本 |260| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | 設定為 `1` 可阻止 Claude Code 在記憶體壓力下終止[背景 shell 命令](/docs/zh-TW/interactive-mode#background-bash-commands)。預設情況下，在 macOS 與 Linux 上，當作業系統回報嚴重記憶體壓力，且工作階段已閒置 30 分鐘、沒有任何回合或 subagent 正在執行時，Claude Code 會終止背景 shell。Windows 沒有記憶體壓力訊號，因此此變數在該平台上沒有作用。需要 Claude Code v2.1.193 或更新版本 |

257| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | 設為 `1` 可停用 Claude Code 隨附的 [skill](/docs/zh-TW/skills) 與工作流程：隨附 skill 與工作流程會被完全移除，而 `/init` 等內建命令仍可輸入，但會對模型隱藏。`/doctor` 與內建命令一樣仍可輸入；請改用 `DISABLE_DOCTOR_COMMAND` 將其隱藏。來自外掛、`.claude/skills/` 與 `.claude/commands/` 的 skill 不受影響。等同於 [`disableBundledSkills`](/docs/zh-TW/settings-reference#disablebundledskills) 設定 |261| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | 設定為 `1` 可停用 Claude Code 隨附的 [skill](/docs/zh-TW/skills) 與工作流程：隨附的 skill 與工作流程會被完全移除，而 `/init` 等內建命令仍可輸入，但會對模型隱藏。`/doctor` 與內建命令一樣仍可輸入；請改用 `DISABLE_DOCTOR_COMMAND` 將其隱藏。來自外掛、`.claude/skills/` 與 `.claude/commands/` 的 skill 不受影響。等同於 [`disableBundledSkills`](/docs/zh-TW/settings-reference#disablebundledskills) 設定 |

258| `CLAUDE_CODE_DISABLE_CFC_PROMPT` | 設為 `1` 可保留 [Claude in Chrome](/docs/zh-TW/chrome) 瀏覽器工具，同時省略系統提示詞中的 Chrome 章節與 `/claude-in-chrome` [隨附 skill](/docs/zh-TW/skills#bundled-skills)。適用於嵌入 Claude Code 並自行提供瀏覽器指引的主機。需要 Claude Code v2.1.257 或更新版本 |262| `CLAUDE_CODE_DISABLE_CFC_PROMPT` | 設定為 `1` 可讓 [Claude in Chrome](/docs/zh-TW/chrome) 瀏覽器工具保持可用，同時省略系統提示詞中的 Chrome 區段與 `/claude-in-chrome` [隨附 skill](/docs/zh-TW/skills#bundled-skills)。適用於嵌入 Claude Code 並自行提供瀏覽器指引的主機。需要 Claude Code v2.1.257 或更新版本 |

260| `CLAUDE_CODE_DISABLE_CRON` | 設為 `1` 可停用[排程任務](/docs/zh-TW/scheduled-tasks)。`/loop` skill 與 cron 工具會變得無法使用，任何已排程的任務都會停止觸發，包括在工作階段中途已經在執行的任務 |264| `CLAUDE_CODE_DISABLE_CRON` | 設定為 `1` 可停用[排程任務](/docs/zh-TW/scheduled-tasks)。`/loop` skill 與 cron 工具將無法使用，任何已排程的任務都會停止觸發，包括已在工作階段中途執行的任務 |

261| `CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT` | 設為 `1` 可關閉[關鍵路徑移除](/docs/zh-TW/permission-modes#critical-paths)提示的時間限制。在 `auto` 模式下，Claude Code 會改為將這些移除操作送交分類器；在 `bypassPermissions` 模式下，提示會等待您的回答。請在啟動 Claude Code 的環境中設定，因為 Claude Code 會忽略透過設定 `env` 區塊傳遞的副本。需要 Claude Code v2.1.281 或更新版本 |265| `CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT` | 設定為 `1` 可關閉[關鍵路徑移除](/docs/zh-TW/permission-modes#critical-paths)提示的時間限制。在 `auto` 模式下，Claude Code 隨後會將這些移除操作改交給分類器；在 `bypassPermissions` 模式下，提示會等待您的回答。請在啟動 Claude Code 的環境中設定，因為 Claude Code 會忽略透過設定 `env` 區塊傳遞的副本。需要 Claude Code v2.1.281 或更新版本 |

262| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | 設為 `1` 可從 API 請求中移除預先發布的 `anthropic-beta` 請求標頭、與其搭配的主體欄位，以及 `defer_loading` 與 `eager_input_streaming` 等 beta 工具結構描述欄位。當代理伺服器閘道以 `anthropic-beta` 標頭的 `Unexpected value(s)` 錯誤或 `Extra inputs are not permitted` 錯誤拒絕請求時，請使用此變數。[停用預先發布功能](/docs/zh-TW/llm-gateway-protocol#disable-pre-release-capabilities)列出了此變數所移除的項目（包括 [MCP Tool Search](/docs/zh-TW/mcp#scale-with-mcp-tool-search)），以及 Claude Code 仍會持續傳送的項目 |266| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | 設定為 `1` 可從 API 請求中移除預先發行的 `anthropic-beta` 請求標頭、與其搭配的本文欄位，以及 `defer_loading` 與 `eager_input_streaming` 等 beta 工具結構描述欄位。當代理伺服器閘道因 `anthropic-beta` 標頭而以 `Unexpected value(s)` 錯誤拒絕請求，或出現 `Extra inputs are not permitted` 錯誤時使用。[停用預先發行功能](/docs/zh-TW/llm-gateway-protocol#disable-pre-release-capabilities)列出此變數移除的項目（包括 [MCP tool search](/docs/zh-TW/mcp#scale-with-mcp-tool-search)）以及 Claude Code 持續傳送的項目 |

263| `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS` | 設為 `1` 可停用內建的 [Explore 與 Plan subagent](/docs/zh-TW/sub-agents#built-in-subagents)。Claude 會改用其搜尋工具或 general-purpose subagent 進行探索，而 [plan mode](/docs/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 會直接讀取檔案，而非啟動 Explore 與 Plan agent。名為 `Explore` 或 `Plan` 的自訂 subagent 不受影響。若要在 Agent SDK 或非互動模式中移除所有內建 subagent 類型，請改用 `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS`。需要 Claude Code v2.1.198 或更新版本 |267| `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS` | 設定為 `1` 可停用內建的 [Explore 與 Plan subagent](/docs/zh-TW/sub-agents#built-in-subagents)。Claude 會改用其搜尋工具或 general-purpose subagent 進行探索，而 [plan mode](/docs/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 會直接讀取檔案，而非啟動 Explore 與 Plan agent。名為 `Explore` 或 `Plan` 的自訂 subagent 不受影響。若要在 Agent SDK 或非互動模式中移除所有內建 subagent 類型，請改用 `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS`。需要 Claude Code v2.1.198 或更新版本 |

265| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | 設為 `1` 可停用「How is Claude doing?」工作階段品質調查。當設定了 `DISABLE_TELEMETRY`、`DO_NOT_TRACK` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 時，調查也會停用，除非 `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` 重新選擇加入。若要設定取樣率而非完全停用，請使用 [`feedbackSurveyRate`](/docs/zh-TW/settings-reference#feedbacksurveyrate) 設定。請參閱[工作階段品質調查](/docs/zh-TW/data-usage#session-quality-surveys) |269| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | 設定為 `1` 可停用「How is Claude doing?」工作階段品質問卷。當設定了 `DISABLE_TELEMETRY`、`DO_NOT_TRACK` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 時，問卷也會停用，除非 `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` 重新選擇加入。若要設定取樣率而非直接停用，請使用 [`feedbackSurveyRate`](/docs/zh-TW/settings-reference#feedbacksurveyrate) 設定。請參閱[工作階段品質問卷](/docs/zh-TW/data-usage#session-quality-surveys) |

266| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | 設為 `1` 可停用檔案[檢查點功能](/docs/zh-TW/checkpointing)。`/rewind` 命令將無法還原程式碼變更。覆寫 [`fileCheckpointingEnabled`](/docs/zh-TW/settings-reference#filecheckpointingenabled) 設定 |270| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | 設定為 `1` 可停用檔案[檢查點功能](/docs/zh-TW/checkpointing)。`/rewind` 命令將無法還原程式碼變更。覆寫 [`fileCheckpointingEnabled`](/docs/zh-TW/settings-reference#filecheckpointingenabled) 設定 |

267| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | 設為 `1` 可從 Claude 的上下文中移除內建的提交與 PR 工作流程指令，以及 git 狀態快照。適用於使用您自己的 git 工作流程 skill 時。設定後會優先於 [`includeGitInstructions`](/docs/zh-TW/settings-reference#includegitinstructions) 設定 |271| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | 設定為 `1` 可從 Claude 的上下文中移除內建的提交與 PR 工作流程指令以及 git 狀態快照。在使用您自己的 git 工作流程 skill 時很有用。設定時優先於 [`includeGitInstructions`](/docs/zh-TW/settings-reference#includegitinstructions) 設定 |

268| `CLAUDE_CODE_DISABLE_INLINE_SHELL_RM_PROMPT` | 設為 `1` 可讓 Claude Code 停止讀取以 `-c` 傳給 shell 的指令碼（例如 `bash -c 'rm -rf ~'`）來檢查[關鍵路徑](/docs/zh-TW/permission-modes#removals-inside-nested-commands-and-inline-scripts)移除操作。Claude Code 仍會檢查這些指令碼中的 shell 變數與位置參數目標，其他關鍵路徑檢查也會持續執行。請在啟動 Claude Code 的環境中設定，因為 Claude Code 會忽略透過設定 `env` 區塊傳遞的副本。需要 Claude Code v2.1.288 或更新版本 |272| `CLAUDE_CODE_DISABLE_INLINE_SHELL_RM_PROMPT` | 設定為 `1` 可阻止 Claude Code 讀取以 `-c` 傳遞給 shell 的腳本（例如 `bash -c 'rm -rf ~'`）來檢查[關鍵路徑](/docs/zh-TW/permission-modes#removals-inside-nested-commands-and-inline-scripts)移除。Claude Code 仍會檢查這些腳本中的 shell 變數與位置參數目標，其他關鍵路徑檢查也會持續執行。請在啟動 Claude Code 的環境中設定，因為 Claude Code 會忽略透過設定 `env` 區塊傳遞的副本。需要 Claude Code v2.1.288 或更新版本 |

269| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | 設為 `1` 可避免在 Anthropic API 上將 Opus 4.0 與 4.1 自動重新對應至目前的 Opus 版本。當您刻意要固定使用較舊的模型時使用。此重新對應不會在 Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry 上執行 |273| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | 設定為 `1` 可防止在 Anthropic API 上將 Opus 4.0 與 4.1 自動重新對應至目前的 Opus 版本。當您刻意想固定使用較舊的模型時使用。此重新對應不會在 Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry 上執行 |

270| `CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK` | 設為 `1` 可讓 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock#when-a-model-is-disabled-mid-session) 與 [Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai#when-a-model-is-disabled-mid-session) 上的 Claude Code 在您的帳戶於工作階段中途失去該工作階段模型的存取權時，不切換至較舊的模型；被拒絕的請求會立即失敗。您設定的[備援模型鏈](/docs/zh-TW/model-config#fallback-model-chains)在遇到該拒絕時仍會切換，而[啟動模型檢查](/docs/zh-TW/amazon-bedrock#startup-model-checks)在啟動時仍會改用其他模型。需要 Claude Code v2.1.285 或更新版本 |274| `CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK` | 設定為 `1` 可阻止 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock#when-a-model-is-disabled-mid-session) 與 [Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai#when-a-model-is-disabled-mid-session) 上的 Claude Code 在您的帳戶於工作階段中途失去對該工作階段模型的存取權時改用較舊的模型；被拒絕的請求會立即失敗。您設定的[備援模型鏈](/docs/zh-TW/model-config#fallback-model-chains)仍會在該拒絕發生時切換，而[啟動模型檢查](/docs/zh-TW/amazon-bedrock#startup-model-checks)仍會在啟動時改用備援。需要 Claude Code v2.1.285 或更新版本 |

271| `CLAUDE_CODE_DISABLE_MOUSE` | 設為 `1` 可在[全螢幕繪製](/docs/zh-TW/fullscreen)中停用滑鼠追蹤。使用 `PgUp` 與 `PgDn` 的鍵盤捲動仍可運作。使用此變數可保留終端機原生的選取即複製行為 |275| `CLAUDE_CODE_DISABLE_MOUSE` | 設定為 `1` 可在[全螢幕呈現](/docs/zh-TW/fullscreen)中停用滑鼠追蹤。使用 `PgUp` 與 `PgDn` 的鍵盤捲動仍可運作。使用此設定可保留終端機原生的選取即複製行為 |

272| `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` | 設為 `1` 可在[全螢幕繪製](/docs/zh-TW/fullscreen)中停用點擊、拖曳與懸停處理，同時保留滑鼠滾輪捲動。當您希望滾輪捲動能在 Claude Code 中運作，但不希望點擊會移動游標位置、展開工具輸出或開啟連結時，請使用此變數。兩者皆設定時，`CLAUDE_CODE_DISABLE_MOUSE` 具有優先權。需要 Claude Code v2.1.195 或更新版本 |276| `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` | 設定為 `1` 可在[全螢幕呈現](/docs/zh-TW/fullscreen)中停用點擊、拖曳與懸停處理，同時保留滑鼠滾輪捲動。當您希望滾輪捲動在 Claude Code 中運作，但不希望點擊會定位游標、展開工具輸出或開啟連結時使用。同時設定兩者時，`CLAUDE_CODE_DISABLE_MOUSE` 優先。需要 Claude Code v2.1.195 或更新版本 |

273| `CLAUDE_CODE_DISABLE_MTLS_RELOAD_ON_STALE_CONNECTION` | 設為 `1` 可讓 Claude Code 在 API 請求因連線層級錯誤（例如連線重設或 TLS 交握錯誤）而失敗時，不重新讀取 [mTLS 用戶端憑證與金鑰](/docs/zh-TW/network-config#mtls-authentication)。停用重新載入後，Claude Code 只會在下次套用設定時或下次啟動時載入輪替後的檔案。需要 Claude Code v2.1.232 或更新版本 |277| `CLAUDE_CODE_DISABLE_MTLS_RELOAD_ON_STALE_CONNECTION` | 設定為 `1` 可阻止 Claude Code 在 API 請求因連線層級錯誤（例如連線重設或 TLS 交握錯誤）而失敗時重新讀取 [mTLS 用戶端憑證與金鑰](/docs/zh-TW/network-config#mtls-authentication)。停用重新載入後，Claude Code 只會在下次套用設定時或下次啟動時載入已輪替的檔案。需要 Claude Code v2.1.232 或更新版本 |

274| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 設為任何非空值（例如 `1`）可停用非必要的網路流量：自動更新、遙測、錯誤回報、`/feedback` 命令、[Claude 草擬的意見回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior)、版本說明、[PR 與 MR 狀態徽章](/docs/zh-TW/interactive-mode#pr-review-status)檢查，以及[快速模式](/docs/zh-TW/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)檢查等可用性檢查。它也會停止[外掛 `command` 來源的背景執行](/docs/zh-TW/plugins/loading#when-a-command-source-re-runs)，這些是本機命令而非網路流量，但可能觸發相依套件安裝。**設為 `0` 或 `false` 仍會停用此流量**，這與大多數開關變數不同；請取消設定此變數以重新允許。也會停用功能旗標擷取，導致 [Remote Control](/docs/zh-TW/remote-control#requirements) 與其他[需要功能旗標擷取的功能](#features-that-need-feature-flag-fetching)無法使用。官方外掛市集自動安裝不在涵蓋範圍內；請以 `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` 停用。不影響[閘道模型探索](/docs/zh-TW/llm-gateway-connect#add-gateway-models-to-the-model-picker)，該功能有其自己的選擇加入機制 |278| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 設定為任何非空值（例如 `1`）可停用非必要的網路流量：自動更新、遙測、錯誤回報、`/feedback` 命令、[Claude 草擬的意見回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior)、版本資訊、[PR 與 MR 狀態徽章](/docs/zh-TW/interactive-mode#pr-review-status)檢查，以及[快速模式](/docs/zh-TW/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)檢查等可用性檢查。它也會停止[外掛 `command` 來源的背景執行](/docs/zh-TW/plugins/loading#when-a-command-source-re-runs)；這些是本機命令而非網路流量，但因為它們可能觸發相依套件安裝，所以也會停止。**設定為 `0` 或 `false` 仍會停用這些流量**，這與大多數開關型變數不同；請取消設定此變數以重新允許。也會停用功能旗標擷取，使 [Remote Control](/docs/zh-TW/remote-control#requirements) 以及其他[需要功能旗標擷取的功能](#features-that-need-feature-flag-fetching)無法使用。官方外掛市集自動安裝不在涵蓋範圍內；請使用 `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` 停用。不會影響[閘道模型探索](/docs/zh-TW/llm-gateway-connect#add-gateway-models-to-the-model-picker)，該功能有其自己的選擇加入機制 |

276| `CLAUDE_CODE_DISABLE_NOTIFICATION_PRESENCE_CHECK` | 設為 `1` 可讓 `PushNotification` 工具即使在您正於終端機中輸入或聚焦於終端機時，仍傳送桌面通知。預設情況下，當工具偵測到最近的鍵盤活動或終端機焦點時，會同時略過桌面通知與[行動推播](/docs/zh-TW/remote-control#mobile-push-notifications)。此變數僅停用該本機檢查，因此伺服器在偵測到您處於活動狀態時仍可抑制行動推播。需要 Claude Code v2.1.193 或更新版本 |280| `CLAUDE_CODE_DISABLE_NOTIFICATION_PRESENCE_CHECK` | 設定為 `1` 可讓 `PushNotification` 工具即使在您正在終端機中輸入或終端機處於焦點時，也傳送桌面通知。預設情況下，當工具偵測到最近的鍵盤活動或終端機焦點時，會同時略過桌面通知與[行動推播](/docs/zh-TW/remote-control#mobile-push-notifications)。此變數僅停用該本機檢查，因此當伺服器偵測到您處於活動狀態時，仍可抑制行動推播。需要 Claude Code v2.1.193 或更新版本 |

277| `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` | 設為 `1` 可停用官方外掛市集的自動註冊。Claude Code 會在即將註冊市集時讀取此變數，通常是在機器首次互動式啟動期間。若此時已設定該變數，Claude Code 會永久略過註冊。之後取消設定變數並不會撤銷此略過。您可以隨時執行 `claude plugin marketplace add anthropics/claude-plugins-official` 來註冊市集 |281| `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` | 設定為 `1` 可停用官方外掛市集的自動註冊。Claude Code 會在即將註冊市集時讀取此變數，通常是在電腦首次互動式啟動期間。若當時已設定此變數，Claude Code 會永久略過註冊。之後取消設定此變數並不會撤銷此略過。隨時執行 `claude plugin marketplace add anthropics/claude-plugins-official` 即可註冊市集 |

278| `CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS` | 設為 `1` 可讓 Claude Code 在會將未回答的權限請求傳送至 Agent SDK `canUseTool` 回呼的工作階段中（也就是 Claude Desktop 與 VS Code 擴充功能承載 Claude Code 的方式），停止執行您的[針對未回答權限請求的 `Notification` hook](/docs/zh-TW/hooks#notification)。在終端機工作階段中沒有作用。需要 Claude Code v2.1.233 或更新版本 |282| `CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS` | 在 Claude Code 將權限請求傳送至 Agent SDK 的 `canUseTool` 回呼的工作階段中（Claude Desktop 與 VS Code 擴充功能即是以此方式託管 Claude Code），設定為 `1` 可阻止 Claude Code 執行您的[針對未回答權限請求的 `Notification` hook](/docs/zh-TW/hooks#notification)。在終端機工作階段中沒有作用。需要 Claude Code v2.1.233 或更新版本 |

280| `CLAUDE_CODE_DISABLE_POWERSHELL_CMD_RM_DENY` | 設為 `1` 可關閉 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool)的檢查，該檢查會拒絕在[系統路徑](/docs/zh-TW/permission-modes#remove-item-in-powershell)（例如磁碟機根目錄或您的家目錄）上使用 `cmd` 內建命令 `rd`、`rmdir`、`del` 與 `erase`。Claude Code 會忽略設定檔 `env` 區塊中的此變數。需要 Claude Code v2.1.283 或更新版本 |284| `CLAUDE_CODE_DISABLE_POWERSHELL_CMD_RM_DENY` | 設定為 `1` 可關閉 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool)的一項檢查，該檢查會拒絕在[系統路徑](/docs/zh-TW/permission-modes#remove-item-in-powershell)（例如磁碟機根目錄或您的家目錄）上使用 `cmd` 內建命令 `rd`、`rmdir`、`del` 與 `erase`。Claude Code 會忽略設定檔 `env` 區塊中的此變數。需要 Claude Code v2.1.283 或更新版本 |

281| `CLAUDE_CODE_DISABLE_REFUSAL_FALLBACK` | 設為 `1` 可關閉[安全分類器標記請求時的自動模型切換](/docs/zh-TW/model-config#automatic-model-fallback)，即 [`switchModelsOnFlag`](/docs/zh-TW/settings-reference#switchmodelsonflag) 設定所控制的行為 |285| `CLAUDE_CODE_DISABLE_REFUSAL_FALLBACK` | 設定為 `1` 可關閉[安全分類器標記請求時的自動模型切換](/docs/zh-TW/model-config#automatic-model-fallback)，也就是 [`switchModelsOnFlag`](/docs/zh-TW/settings-reference#switchmodelsonflag) 設定所控制的行為 |

282| `CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS` | 設為 `1` 可讓 Claude Code 停止傳送結構化輸出 `output_config.format` 欄位以及與其搭配的 `anthropic-beta` 值，適用於上游會拒絕它們的 [LLM 閘道](/docs/zh-TW/llm-gateway-protocol#feature-pass-through)。這會保留 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/zh-TW/llm-gateway-protocol#disable-pre-release-capabilities) 所關閉的其他預先發布功能。需要 Claude Code v2.1.288 或更新版本 |286| `CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS` | 設定為 `1` 可阻止 Claude Code 傳送結構化輸出的 `output_config.format` 欄位與其搭配的 `anthropic-beta` 值，適用於上游會拒絕這些內容的 [LLM 閘道](/docs/zh-TW/llm-gateway-protocol#feature-pass-through)。這會讓 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/zh-TW/llm-gateway-protocol#disable-pre-release-capabilities) 所關閉的其他預先發行功能保持開啟。需要 Claude Code v2.1.288 或更新版本 |

283| `CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT` | 設為 `1` 可關閉針對目標完全為命令替換輸出之遞迴 `rm`（例如 `rm -rf "$(pwd)"`）的[關鍵路徑](/docs/zh-TW/permission-modes#critical-paths)檢查。其他關鍵路徑檢查會持續執行。請在啟動 Claude Code 的環境中設定，因為 Claude Code 會忽略透過設定 `env` 區塊傳遞的副本。需要 Claude Code v2.1.281 或更新版本 |287| `CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT` | 設定為 `1` 可關閉針對遞迴 `rm` 的[關鍵路徑](/docs/zh-TW/permission-modes#critical-paths)檢查，該檢查適用於目標完全是命令替換輸出的情況，例如 `rm -rf "$(pwd)"`。其他關鍵路徑檢查會持續執行。請在啟動 Claude Code 的環境中設定，因為 Claude Code 會忽略透過設定 `env` 區塊傳遞的副本。需要 Claude Code v2.1.281 或更新版本 |

284| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | 設為 `1` 可停用依據對話上下文自動更新終端機標題。這也會略過[產生工作階段標題](/docs/zh-TW/sessions#name-your-sessions)的背景小型/快速模型請求 |288| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | 設定為 `1` 可停用根據對話上下文自動更新終端機標題。這也會略過[產生工作階段標題](/docs/zh-TW/sessions#name-your-sessions)的背景小型/快速模型請求 |

285| `CLAUDE_CODE_DISABLE_THINKING` | 設為 `1` 可從 API 請求中完全省略 `thinking` 參數。這是為了相容會拒絕此參數的代理伺服器與閘道而提供的選項。在預設會思考的模型上，省略此參數意味著模型仍可能會思考。若要在 Anthropic API 上明確停用[延伸思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)，請改用 `MAX_THINKING_TOKENS=0`。這兩個變數都無法在 Opus 5.5、Sonnet 5.5、Haiku 5.5 或 Fable 模型上關閉思考，這些模型無法關閉思考。在[第三方供應商](/docs/zh-TW/third-party-integrations)上，`MAX_THINKING_TOKENS=0` 同樣會省略此參數，因此這兩個變數在該處的行為相同 |289| `CLAUDE_CODE_DISABLE_THINKING` | 設定為 `1` 可從 API 請求中完全省略 `thinking` 參數。這是針對拒絕此參數的代理伺服器與閘道的相容性選項。在預設會思考的模型上，省略此參數代表模型仍可能思考。若要在 Anthropic API 上明確停用[延伸思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)，請改用 `MAX_THINKING_TOKENS=0`。兩個變數都無法在 Opus 5.5、Sonnet 5.5、Haiku 5.5 或 Fable 模型上關閉思考，這些模型無法關閉思考。在[第三方提供者](/docs/zh-TW/third-party-integrations)上，`MAX_THINKING_TOKENS=0` 同樣會省略此參數，因此兩個變數在那裡的行為相同 |

286| `CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT` | 設為 `1` 可在 Claude Code 無法辨識模型 ID（例如 [LLM 閘道](/docs/zh-TW/llm-gateway)別名）時，略過主動[自動壓縮](/docs/zh-TW/costs#reduce-token-usage)。若未設定此變數，Claude Code 會依據其為該 ID 假設的上下文視窗進行壓縮。`CLAUDE_CODE_MAX_CONTEXT_TOKENS` 則可改為修正假設的視窗；關於各變數適用的時機，請參閱[修正閘道或自訂模型 ID 的視窗](/docs/zh-TW/model-config#correct-the-window-for-a-gateway-or-custom-model-id)。需要 Claude Code v2.1.223 或更新版本 |290| `CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT` | 設定為 `1` 可在 Claude Code 無法辨識模型 ID（例如 [LLM 閘道](/docs/zh-TW/llm-gateway)別名）時略過主動[自動壓縮](/docs/zh-TW/costs#reduce-token-usage)。若未設定此變數，Claude Code 會在其為該 ID 假設的上下文視窗處進行壓縮。`CLAUDE_CODE_MAX_CONTEXT_TOKENS` 可改為修正假設的視窗；關於各變數的適用時機，請參閱[修正閘道或自訂模型 ID 的視窗](/docs/zh-TW/model-config#correct-the-window-for-a-gateway-or-custom-model-id)。需要 Claude Code v2.1.223 或更新版本 |

287| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | 設為 `1` 可在[全螢幕繪製](/docs/zh-TW/fullscreen)中停用虛擬捲動，並繪製逐字稿中的每則訊息。若在全螢幕模式中捲動時，應顯示訊息的位置出現空白區域，請使用此變數 |291| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | 設定為 `1` 可在[全螢幕呈現](/docs/zh-TW/fullscreen)中停用虛擬捲動，並呈現逐字稿中的每則訊息。若在全螢幕模式中捲動時，應顯示訊息的地方出現空白區域，請使用此設定 |

288| `CLAUDE_CODE_DISABLE_WEB_FETCH` | 設為 `1` 可關閉 [WebFetch](/docs/zh-TW/tools-reference#webfetch-tool-behavior) 工具。[WebSearch](/docs/zh-TW/tools-reference#websearch-tool-behavior) 工具仍可使用。需要 Claude Code v2.1.285 或更新版本 |292| `CLAUDE_CODE_DISABLE_WEB_FETCH` | 設定為 `1` 可關閉 [WebFetch](/docs/zh-TW/tools-reference#webfetch-tool-behavior) 工具。[WebSearch](/docs/zh-TW/tools-reference#websearch-tool-behavior) 工具仍可使用。需要 Claude Code v2.1.285 或更新版本 |

289| `CLAUDE_CODE_DISABLE_WINDOWS_SHELL_LAUNCHER` | 設為 `1` 可在 Windows 上直接啟動 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool)命令，而非透過 `cmd.exe` 啟動器。預設情況下，啟動器能讓[在背景執行](/docs/zh-TW/tools-reference#background-commands)的 PowerShell 命令[延續至工作階段的下一個程序](/docs/zh-TW/agent-view#the-supervisor-process)，例如當您[將工作階段移至背景](/docs/zh-TW/agent-view#from-inside-a-session)時。若您設定此變數，背景化的 PowerShell 命令會在工作階段的程序結束時停止。Bash 命令不受影響。需要 Claude Code v2.1.269 或更新版本 |293| `CLAUDE_CODE_DISABLE_WINDOWS_SHELL_LAUNCHER` | 設定為 `1` 可在 Windows 上直接啟動 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool)命令，而非透過 `cmd.exe` 啟動器。預設情況下，啟動器可讓[在背景執行](/docs/zh-TW/tools-reference#background-commands)的 PowerShell 命令[延續至工作階段的下一個程序](/docs/zh-TW/agent-view#the-supervisor-process)，例如當您[將工作階段移至背景](/docs/zh-TW/agent-view#from-inside-a-session)時。若您設定此變數，移至背景的 PowerShell 命令會在工作階段的程序結束時停止。Bash 命令不受影響。需要 Claude Code v2.1.269 或更新版本 |

290| `CLAUDE_CODE_DISABLE_WORKFLOWS` | 設為 `1` 可停用[工作流程](/docs/zh-TW/workflows#turn-workflows-off)。等同於 [`disableWorkflows`](/docs/zh-TW/settings-reference#disableworkflows) 設定 |294| `CLAUDE_CODE_DISABLE_WORKFLOWS` | 設定為 `1` 可停用[工作流程](/docs/zh-TW/workflows#turn-workflows-off)。等同於 [`disableWorkflows`](/docs/zh-TW/settings-reference#disableworkflows) 設定 |

291| `CLAUDE_CODE_EFFORT_LEVEL` | 為支援的模型設定 effort 等級。值：`low`、`medium`、`high`、`xhigh`、`max`，或使用 `auto` 採用模型預設值。可用等級取決於模型。優先於 `--effort`、`/effort` 以及 `modelSettings` 與 `effortLevel` 設定。[`maxEffortLevel`](/docs/zh-TW/settings-reference#maxeffortlevel) 上限仍然適用。請參閱[調整 effort 等級](/docs/zh-TW/model-config#adjust-effort-level) |295| `CLAUDE_CODE_EFFORT_LEVEL` | 設定支援模型的 effort 等級。值：`low`、`medium`、`high`、`xhigh`、`max`，或使用 `auto` 以採用模型預設值。可用等級取決於模型。優先於 `--effort`、`/effort`，以及 `modelSettings` 與 `effortLevel` 設定。[`maxEffortLevel`](/docs/zh-TW/settings-reference#maxeffortlevel) 上限仍適用。請參閱[調整 effort 等級](/docs/zh-TW/model-config#adjust-effort-level) |

292| `CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS` | 設為 `1` 可在訊息串流中加入 [`session_state_changed`](/docs/zh-TW/agent-sdk/typescript#sdksessionstatechangedmessage) 訊息，這些訊息帶有工作階段的狀態。需要使用 [Agent SDK](/docs/zh-TW/agent-sdk/overview)，或同時使用 `--print`、`--output-format stream-json` 與 `--verbose` |296| `CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS` | 設為 `1` 可將攜帶工作階段狀態的 [`session_state_changed`](/docs/zh-TW/agent-sdk/typescript#sdksessionstatechangedmessage) 訊息加入訊息串流。需要 [Agent SDK](/docs/zh-TW/agent-sdk/overview)，或同時使用 `--print`、`--output-format stream-json` 與 `--verbose` |

293| `CLAUDE_CODE_ENABLE_AUTO_MODE` | 為了與舊版相容而接受此變數，但沒有任何作用。自動模式在每個供應商上預設皆可使用，包括 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry，以及已登入的 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway) 工作階段。在 v2.1.158 至 v2.1.206 中，必須將此變數設為 `1`，才能在這些供應商上使用[自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) |297| `CLAUDE_CODE_ENABLE_AUTO_MODE` | 為了與舊版相容而接受，但沒有任何作用。自動模式在每個供應商上皆預設可用，包括 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry，以及已登入的 [Claude apps 閘道](/docs/zh-TW/claude-apps-gateway)工作階段。在 v2.1.158 至 v2.1.206 中，必須將此變數設為 `1`，才能在這些供應商上使用[自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) |

294| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | 覆寫[工作階段回顧](/docs/zh-TW/interactive-mode#session-recap)的可用性。設為 `0` 可強制關閉回顧，不論 `/config` 切換為何。設為 `1` 可在 [`awaySummaryEnabled`](/docs/zh-TW/settings-reference#awaysummaryenabled) 為 `false` 時強制開啟回顧。優先於該設定與 `/config` 切換 |298| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | 覆寫[工作階段回顧](/docs/zh-TW/interactive-mode#session-recap)的可用性。設為 `0` 可強制關閉回顧，不論 `/config` 切換開關為何。設為 `1` 可在 [`awaySummaryEnabled`](/docs/zh-TW/settings-reference#awaysummaryenabled) 為 `false` 時強制開啟回顧。優先於該設定與 `/config` 切換開關 |

295| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 設為 `1` 可在[非互動模式](/docs/zh-TW/headless)中，於背景安裝完成後在回合邊界重新整理外掛狀態。預設為關閉，因為重新整理會在工作階段中途變更系統提示詞，使該回合的[提示快取](/docs/zh-TW/prompt-caching)失效 |299| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 設為 `1` 可在[非互動模式](/docs/zh-TW/headless)中，於背景安裝完成後在回合交界處重新整理外掛狀態。預設為關閉，因為重新整理會在工作階段中途變更系統提示詞，使該回合的[提示快取](/docs/zh-TW/prompt-caching)失效 |

296| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | 設為 `1` 可在傳往 Anthropic 的非必要流量遭封鎖時，將「How is Claude doing?」工作階段品質問卷導向您自己的 [OpenTelemetry collector](/docs/zh-TW/monitoring-usage)。問卷評分僅以 OTEL 事件的形式發送至您設定的 collector。在此模式下，不會將任何問卷資料傳送給 Anthropic。適用於已設定 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`、`DISABLE_TELEMETRY` 或 `DO_NOT_TRACK` 的情況，否則沒有作用。`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` 與組織的產品意見回饋政策優先於此變數 |300| `CLAUDE_CODE_ENABLE_CFC` | 設為 `1` 可在開啟 [Chrome 整合](/docs/zh-TW/chrome)的情況下啟動 CLI 工作階段，設為 `0` 則以關閉狀態啟動。優先於 [`claudeInChromeDefaultEnabled`](/docs/zh-TW/settings-reference#claudeinchromedefaultenabled) 設定。`--chrome` 與 `--no-chrome` 旗標優先於兩者。Claude Code [會忽略專案與本機設定中的 `1`](/docs/zh-TW/chrome#project-settings-can’t-turn-on-chrome) |

297| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 控制工具呼叫輸入是否在 Claude 產生時從 API 串流傳送。關閉時，大型工具輸入（例如長檔案寫入）只會在 Claude 產生完成後才送達，看起來可能像是停住了。在 Anthropic API 上預設啟用。在 Amazon Bedrock 與 Google Cloud's Agent Platform 上，會依模型在所部署的容器支援時啟用。設為 `0` 可選擇停用。當透過 `ANTHROPIC_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_BEDROCK_BASE_URL` 經由代理伺服器路由時，設為 `1` 可強制開啟。在 Microsoft Foundry 與[閘道](/docs/zh-TW/llm-gateway)連線上預設關閉 |301| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | 設為 `1` 可在傳往 Anthropic 的非必要流量遭封鎖時，將「How is Claude doing?」工作階段品質問卷導向您自己的 [OpenTelemetry collector](/docs/zh-TW/monitoring-usage)。問卷評分僅會以 OTEL 事件的形式發送至您設定的 collector。在此模式下，不會將任何問卷資料傳送給 Anthropic。在設定了 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`、`DISABLE_TELEMETRY` 或 `DO_NOT_TRACK` 時適用，否則沒有作用。`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` 與組織產品意見回饋政策優先於此變數 |

298| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 設為 `1` 可在 `ANTHROPIC_BASE_URL` 指向 LiteLLM、Kong 或內部代理伺服器等 Anthropic 相容閘道時，從閘道的 `/v1/models` 端點填入 `/model` 選擇器。預設為關閉，否則以共用 API 金鑰為基礎的閘道會向每位使用者顯示該金鑰可存取的所有模型。探索到的模型仍會由工作階段收到的 [`availableModels`](/docs/zh-TW/settings-reference#availablemodels) 允許清單篩選；請透過 [MDM 或受管設定檔](/docs/zh-TW/managed-settings#delivery-mechanisms)傳遞此清單，因為[閘道設定無法使用伺服器管理的傳遞方式](/docs/zh-TW/server-managed-settings#platform-availability) |302| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 控制工具呼叫輸入是否在 Claude 產生時即從 API 串流傳送。關閉時，大型工具輸入（例如長檔案寫入）只會在 Claude 產生完畢後才送達，看起來可能像是卡住了。在 Anthropic API 上預設啟用。在 Amazon Bedrock 與 Google Cloud's Agent Platform 上，會依模型在部署的容器支援時啟用。設為 `0` 可選擇退出。透過 `ANTHROPIC_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_BEDROCK_BASE_URL` 經由代理伺服器路由時，設為 `1` 可強制開啟。在 Microsoft Foundry 與[閘道](/docs/zh-TW/llm-gateway)連線上預設為關閉 |

299| `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE` | 已在 v2.1.142 移除，當時[快速模式](/docs/zh-TW/fast-mode)的預設從 Opus 4.6 改為 Opus 4.7 |303| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 當 `ANTHROPIC_BASE_URL` 指向與 Anthropic 相容的閘道（例如 LiteLLM、Kong 或內部代理伺服器）時，設為 `1` 可從閘道的 `/v1/models` 端點填入 `/model` 選擇器。預設為關閉，因為若非如此，由共用 API 金鑰支援的閘道會向每位使用者顯示該金鑰可存取的每個模型。探索到的模型仍會依工作階段收到的 [`availableModels`](/docs/zh-TW/settings-reference#availablemodels) 允許清單進行篩選；請透過 [MDM 或受管設定檔](/docs/zh-TW/managed-settings#delivery-mechanisms)提供該清單，因為[伺服器管理的提供方式不適用於閘道設定](/docs/zh-TW/server-managed-settings#platform-availability) |

300| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 設為 `false` 可關閉提示詞建議，也就是出現在提示詞輸入框中的灰色預測文字。優先於 [`promptSuggestionEnabled`](/docs/zh-TW/settings-reference#promptsuggestionenabled) 設定，也就是 `/config` 中 **Prompt suggestions** 切換所寫入的設定。當您的帳戶接近或已達用量上限時，Claude Code 也會[暫停建議](/docs/zh-TW/interactive-mode#when-claude-code-skips-suggestions)。設為 `true` 可讓建議保持開啟，直到您達到上限為止。需要 Claude Code v2.1.238 或更新版本。請參閱[提示詞建議](/docs/zh-TW/interactive-mode#prompt-suggestions) |304| `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE` | 已於 v2.1.142 移除，當時[快速模式](/docs/zh-TW/fast-mode)的預設模型從 Opus 4.6 改為 Opus 4.7 |

301| `CLAUDE_CODE_ENABLE_TASKS` | 選擇 Claude Code 在[具備這些工具的工作階段](/docs/zh-TW/tools-reference#task-tool-availability)中提供哪些任務追蹤工具。預設情況下，Claude Code 提供 Task 工具 `TaskCreate`、`TaskUpdate`、`TaskGet` 與 `TaskList`。設為 `0` 則改為取得舊版的 `TodoWrite` 工具。請參閱[任務清單](/docs/zh-TW/interactive-mode#task-list) |305| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 設為 `false` 可關閉提示詞建議，即出現在提示詞輸入框中的灰色預測文字。優先於 [`promptSuggestionEnabled`](/docs/zh-TW/settings-reference#promptsuggestionenabled) 設定，也就是 `/config` 中 **Prompt suggestions** 切換開關所寫入的設定。Claude Code 也會[在您的帳戶接近或達到用量上限時暫停建議](/docs/zh-TW/interactive-mode#when-claude-code-skips-suggestions)。設為 `true` 可讓建議持續開啟，直到您達到上限為止。需要 Claude Code v2.1.238 或更新版本。請參閱[提示詞建議](/docs/zh-TW/interactive-mode#prompt-suggestions) |

302| `CLAUDE_CODE_ENABLE_TELEMETRY` | 設為 `1` 以啟用用於指標與日誌的 OpenTelemetry 資料收集。設定 OTel exporter 之前必須先設定此變數。請在 shell、使用者設定或受管設定中設定。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略。請參閱[監控](/docs/zh-TW/monitoring-usage) |306| `CLAUDE_CODE_ENABLE_TASKS` | 選擇 Claude Code 在[具備這些工具的工作階段](/docs/zh-TW/tools-reference#task-tool-availability)中提供哪些任務追蹤工具。預設情況下，Claude Code 提供 Task 工具 `TaskCreate`、`TaskUpdate`、`TaskGet` 與 `TaskList`。設為 `0` 則改為取得舊版 `TodoWrite` 工具。請參閱[任務清單](/docs/zh-TW/interactive-mode#task-list) |

303| `CLAUDE_CODE_ENABLE_TODO_TOOLS` | 設為 `1` 可在所有模型上取得任務追蹤工具。若未設定，Claude Code 預設只在 [Task 工具可用性](/docs/zh-TW/tools-reference#task-tool-availability)所列的模型上提供這些工具。`CLAUDE_CODE_ENABLE_TASKS` 仍會決定使用 Task 工具或 `TodoWrite`。需要 Claude Code v2.1.233 或更新版本 |307| `CLAUDE_CODE_ENABLE_TELEMETRY` | 設為 `1` 以啟用 OpenTelemetry 資料收集，用於指標與日誌。設定 OTel 匯出器之前必須先設定此變數。請在您的 shell、使用者設定或受管設定中設定。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略。請參閱[監控](/docs/zh-TW/monitoring-usage) |

304| `CLAUDE_CODE_EXIT_AFTER_STOP_DELAY` | 查詢迴圈進入閒置後，自動結束前的等待時間（毫秒）。適用於使用 SDK 模式的自動化工作流程與指令碼 |308| `CLAUDE_CODE_ENABLE_TODO_TOOLS` | 設為 `1` 可在每個模型上取得任務追蹤工具。若未設定，Claude Code 預設只會在 [Task 工具可用性](/docs/zh-TW/tools-reference#task-tool-availability)下列出的模型上提供這些工具。`CLAUDE_CODE_ENABLE_TASKS` 仍會決定使用 Task 工具或 `TodoWrite`。需要 Claude Code v2.1.233 或更新版本 |

306| `CLAUDE_CODE_EXTRA_BODY` | 要合併至每個 API 請求本文頂層的 JSON 物件。適合用於傳遞 Claude Code 未直接提供的供應商特定參數。在 shell 中 export 的值也會套用至您以 `claude agents` 或 `--bg` 派送的[背景工作階段](/docs/zh-TW/agent-view)。在 v2.1.206 之前，背景工作階段會忽略 shell 中 export 的值，而使用背景監督程序所繼承的副本 |310| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | 設為 `1` 以啟用 [agent team](/docs/zh-TW/agent-teams)。agent team 為實驗性功能，預設為停用 |

307| `CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS` | 覆寫檔案讀取的預設 token 上限。當您需要完整讀取較大的檔案時很有用 |311| `CLAUDE_CODE_EXTRA_BODY` | 要合併至每個 API 請求主體最上層的 JSON 物件。適用於傳遞 Claude Code 未直接公開的供應商專屬參數。在 shell 中匯出的值也會套用至您以 `claude agents` 或 `--bg` 分派的[背景工作階段](/docs/zh-TW/agent-view)。在 v2.1.206 之前，背景工作階段會忽略 shell 匯出的值，並使用背景監督程序所繼承的副本 |

308| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | 設為 `1` 可強制保存逐字稿、提示詞歷史記錄與 `claude agents` 註冊，即使此 `claude` 是從另一個 Claude Code 工作階段內部啟動的也一樣。當繼承而來的 `CLAUDE_CODE_CHILD_SESSION` 值（例如來自 `screen` 工作階段，或最初由 Claude Code 的 Bash 工具啟動的背景啟動器）導致真正的頂層工作階段被誤判為巢狀工作階段時使用。自 v2.1.178 起，Claude Code 會自動偵測 tmux 的情況並忽略繼承的標記，因此 tmux 不再需要此變數。v2.1.169 及更早版本也會採用此變數；在 v2.1.170 與 v2.1.171 中沒有作用，因為它所覆寫的巢狀工作階段偵測在這些版本中已被移除 |312| `CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS` | 覆寫檔案讀取的預設 token 上限。在需要完整讀取較大檔案時很有用 |

309| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | 設為 `1` 可在終端機支援但未被自動偵測到時（例如透過 SSH 且未轉送 `TERM_PROGRAM`），強制將 Claude 回應中的 `~~text~~` 以刪除線呈現。若未設定，未被偵測到的終端機會顯示字面上的 `~~` 標記，而不會將文字呈現為刪除線。需要 Claude Code v2.1.186 或更新版本 |313| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | 設為 `1` 可強制保存逐字稿、提示詞歷史與 `claude agents` 註冊，即使這個 `claude` 是從另一個 Claude Code 工作階段內部啟動的。當繼承的 `CLAUDE_CODE_CHILD_SESSION` 值（例如來自 `screen` 工作階段，或最初由 Claude Code 的 Bash 工具啟動的背景啟動器）導致真正的最上層工作階段被誤判為巢狀工作階段時使用。自 v2.1.178 起，Claude Code 會自動偵測 tmux 的情況並忽略繼承的標記，因此 tmux 不再需要此變數。在 v2.1.169 及更早版本中也有效；在 v2.1.170 與 v2.1.171 中沒有作用，因為其所覆寫的巢狀工作階段偵測在這些版本中已被移除 |

310| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 設為 `1` 可在終端機支援但未被自動偵測到時，強制啟用 DEC private mode 2026 [同步輸出](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)。適用於 Emacs `eat` 等實作了 BSU/ESU 但不回應能力探測的模擬器。在 tmux 下沒有作用。與會切換至[全螢幕呈現](/docs/zh-TW/fullscreen)的 `CLAUDE_CODE_NO_FLICKER` 不同，此變數不會變更呈現器 |314| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | 設為 `1` 可在終端機支援但未被自動偵測到時（例如透過 SSH 且未轉送 `TERM_PROGRAM`），強制將 Claude 回應中的 `~~text~~` 呈現為刪除線。若未設定，未被偵測到的終端機會顯示字面上的 `~~` 標記，而不會將文字呈現為刪除線。需要 Claude Code v2.1.186 或更新版本 |

311| `CLAUDE_CODE_FORCE_TERMINAL_IMAGES` | 設為 `1` 可在終端機能以 Unicode 預留位置繪製 kitty graphics protocol 圖片但未被自動偵測到時，將 [mod `Image` 元素](/docs/zh-TW/plugins/mods/reference#elements)繪製為圖片。請參閱 [Claude Code 會偵測哪些終端機](/docs/zh-TW/plugins/mods/gallery#image-and-client)，以及為何此變數在 tmux 或 screen 中沒有幫助 |315| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 設為 `1` 可在終端機支援但未被自動偵測到時，強制啟用 DEC private mode 2026 [同步輸出](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)。適用於實作 BSU/ESU 但不回應功能探測的模擬器，例如 Emacs `eat`。在 tmux 下沒有作用。不同於會切換至[全螢幕呈現](/docs/zh-TW/fullscreen)的 `CLAUDE_CODE_NO_FLICKER`，此變數不會變更呈現器 |

312| `CLAUDE_CODE_FORK_SUBAGENT` | 控制[分叉模式](/docs/zh-TW/sub-agents#turn-fork-mode-on-or-off)，此模式讓 Claude 能自行產生[分叉的 subagent](/docs/zh-TW/sub-agents#fork-the-current-conversation)，且預設僅在互動式工作階段中開啟。設為 `1` 可在 `claude -p` 與 Agent SDK 中也開啟，或設為 `0` 在所有類型的工作階段中關閉。無論分叉模式是否開啟，您都可以執行 `/subtask`。互動式預設需要 Claude Code v2.1.232 或更新版本；在較早版本中，請將此變數設為 `1` 以開啟分叉模式 |316| `CLAUDE_CODE_FORCE_TERMINAL_IMAGES` | 設為 `1` 可在終端機以 Unicode 預留位置繪製 kitty graphics protocol 圖片但未被自動偵測到時，將 [mod `Image` 元素](/docs/zh-TW/plugins/mods/reference#elements)繪製為圖片。請參閱 [Claude Code 會偵測哪些終端機](/docs/zh-TW/plugins/mods/gallery#image-and-client)，以及為何此變數在 tmux 或 screen 內無效 |

313| `CLAUDE_CODE_FORWARD_SUBAGENT_TEXT` | 設為 `1` 可在 `claude -p --output-format stream-json` 輸出中發出 [subagent](/docs/zh-TW/sub-agents) 的文字與思考區塊，行為與 [`--forward-subagent-text`](/docs/zh-TW/cli-reference#cli-flags) 旗標相同。當 harness 呼叫 `claude` 但本身無法傳遞旗標時，請使用此變數。旗標在非互動模式搭配 stream-json 輸出以外的情況會以錯誤結束，而此變數在這些情況下會被忽略，因此當它以整個程序範圍設定時，巢狀呼叫仍能正常運作。需要 Claude Code v2.1.211 或更新版本 |317| `CLAUDE_CODE_FORK_SUBAGENT` | 控制 [fork 模式](/docs/zh-TW/sub-agents#turn-fork-mode-on-or-off)，此模式讓 Claude 能自行產生 [fork 的 subagent](/docs/zh-TW/sub-agents#fork-the-current-conversation)，且僅在互動式工作階段中預設開啟。設為 `1` 可在 `claude -p` 與 Agent SDK 中也開啟，或設為 `0` 在所有類型的工作階段中關閉。無論 fork 模式是否開啟，您都可以執行 `/subtask`。互動式預設值需要 Claude Code v2.1.232 或更新版本；在較早版本中，請將變數設為 `1` 以開啟 fork 模式 |

314| `CLAUDE_CODE_GATEWAY_HINT_HEADERS` | 設為 `1` 可在自訂代理伺服器或第三方供應商（例如 Amazon Bedrock 或 Claude Platform on AWS）上傳送[閘道提示標頭](/docs/zh-TW/llm-gateway-protocol#gateway-hint-headers)，例如 `x-claude-code-request-class` 與 `x-claude-code-compaction`。設為 `0` 可在所有連線上停止傳送這些標頭，包括直接連線至 Anthropic API 的情況，Claude Code 在該情況下預設會傳送這些標頭。需要 Claude Code v2.1.273 或更新版本 |318| `CLAUDE_CODE_FORWARD_SUBAGENT_TEXT` | 設為 `1` 可在 `claude -p --output-format stream-json` 輸出中發出 [subagent](/docs/zh-TW/sub-agents) 文字與思考區塊，行為與 [`--forward-subagent-text`](/docs/zh-TW/cli-reference#cli-flags) 旗標相同。當叫用 `claude` 的 harness 無法自行傳遞旗標時使用此變數。該旗標在非互動模式搭配 stream-json 輸出以外的情況下會以錯誤結束，但此變數在這些情況下會被忽略，因此在整個程序範圍設定時，巢狀叫用仍可正常運作。需要 Claude Code v2.1.211 或更新版本 |

315| `CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS` | `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` 所開啟的[閘道模型探索](/docs/zh-TW/llm-gateway-protocol#model-discovery)請求的逾時時間（毫秒）（預設：`3000`）。當您的閘道在啟動時需要超過三秒才能回應 `/v1/models` 時，請調高此值。僅接受純數字；`0`、負值與其他寫法會保留預設值。需要 Claude Code v2.1.269 或更新版本 |319| `CLAUDE_CODE_GATEWAY_HINT_HEADERS` | 設為 `1` 可在自訂代理伺服器或第三方供應商（例如 Amazon Bedrock 或 Claude Platform on AWS）上傳送[閘道提示標頭](/docs/zh-TW/llm-gateway-protocol#gateway-hint-headers)，例如 `x-claude-code-request-class` 與 `x-claude-code-compaction`。設為 `0` 可停止在每個連線上傳送這些標頭，包括直接連線至 Anthropic API 的情況，Claude Code 在該情況下預設會傳送它們。需要 Claude Code v2.1.273 或更新版本 |

316| `CLAUDE_CODE_GIT_BASH_PATH` | 僅限 Windows：Git Bash 可執行檔（`bash.exe`）的路徑。當 Git Bash 已安裝但不在您的 PATH 中時使用。若路徑不存在，或檔案名稱不是 `bash.exe`、`sh.exe`、`bash` 或 `sh`，Claude Code 會忽略此變數，並如同未設定般自動偵測 Git Bash，同時記錄一則可透過 `--debug` 看到的警告。在 v2.1.219 之前，路徑不存在時 Claude Code 會在啟動時結束，且會將任何既有檔案當作 shell 使用，而不檢查它是否為 bash 或 sh。請參閱 [Windows 設定](/docs/zh-TW/setup#set-up-on-windows) |320| `CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS` | 由 `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` 開啟的[閘道模型探索](/docs/zh-TW/llm-gateway-protocol#model-discovery)請求的逾時時間（毫秒）（預設：`3000`）。當您的閘道在啟動時需要超過三秒才能回應 `/v1/models` 時，請調高此值。僅接受純數字；`0`、負值及其他寫法會保留預設值。需要 Claude Code v2.1.269 或更新版本 |

317| `CLAUDE_CODE_GLOB_HIDDEN` | 設為 `false` 可在 Claude 呼叫 [Glob 工具](/docs/zh-TW/tools-reference#glob-tool-behavior)時，從結果中排除 dotfile。預設會包含。不影響 `@` 檔案自動完成、`ls`、Grep 或 Read |321| `CLAUDE_CODE_GIT_BASH_PATH` | 僅限 Windows：Git Bash 執行檔（`bash.exe`）的路徑。當 Git Bash 已安裝但不在您的 PATH 中時使用。若路徑不存在，或檔案名稱不是 `bash.exe`、`sh.exe`、`bash` 或 `sh`，Claude Code 會忽略此變數，如同未設定般自動偵測 Git Bash，並記錄一則可透過 `--debug` 看到的警告。在 v2.1.219 之前，當路徑不存在時，Claude Code 會在啟動時結束，且會將任何現有檔案當作 shell 使用，而不檢查其是否為 bash 或 sh。請參閱 [Windows 設定](/docs/zh-TW/setup#set-up-on-windows) |

318| `CLAUDE_CODE_GLOB_NO_IGNORE` | 設為 `false` 可讓 [Glob 工具](/docs/zh-TW/tools-reference#glob-tool-behavior)遵循 `.gitignore` 模式。預設情況下，Glob 會傳回所有符合的檔案，包括被 gitignore 的檔案。不影響 `@` 檔案自動完成，它有自己的 [`respectGitignore` 設定](/docs/zh-TW/settings-reference#respectgitignore) |322| `CLAUDE_CODE_GLOB_HIDDEN` | 設為 `false` 可在 Claude 叫用 [Glob 工具](/docs/zh-TW/tools-reference#glob-tool-behavior)時將點檔案排除在結果之外。預設會包含。不影響 `@` 檔案自動完成、`ls`、Grep 或 Read |

323| `CLAUDE_CODE_GLOB_NO_IGNORE` | 設為 `false` 可讓 [Glob 工具](/docs/zh-TW/tools-reference#glob-tool-behavior)遵循 `.gitignore` 模式。預設情況下，Glob 會傳回所有符合的檔案，包括被 gitignore 的檔案。不影響 `@` 檔案自動完成，其有自己的 [`respectGitignore` 設定](/docs/zh-TW/settings-reference#respectgitignore) |

320| `CLAUDE_CODE_GOAL_CHECKIN_MINUTES` | 背景工作可讓進行中的目標等待多少分鐘，之後 Claude Code 會[要求 Claude 檢查該目標](/docs/zh-TW/goal#background-work-defers-evaluation)。預設為 `30`。設為 `0` 可關閉檢查。請以純數字提供整數分鐘數，最多 `10080`，也就是一週。Claude Code 會將其他任何值視為未設定並使用預設值。需要 Claude Code v2.1.234 或更新版本 |325| `CLAUDE_CODE_GOAL_CHECKIN_MINUTES` | 背景工作可讓進行中的目標等待多少分鐘，之後 Claude Code 會[要求 Claude 檢查該目標](/docs/zh-TW/goal#background-work-defers-evaluation)。預設為 `30`。設為 `0` 可關閉檢查。請以純數字提供整數分鐘數，最多 `10080`，即一週。Claude Code 會將任何其他值視為未設定並使用預設值。需要 Claude Code v2.1.234 或更新版本 |

321| `CLAUDE_CODE_GZIP_REQUEST_BODIES` | 設為 `0` 可關閉傳送至 `api.anthropic.com` 的 Claude API、遙測與 [artifact](/docs/zh-TW/artifacts) 發布請求本文的 gzip 壓縮。預設情況下，Claude Code 會在直接連線上壓縮大型請求本文，並在您透過代理伺服器傳送請求、設定用戶端憑證或設定 `NODE_EXTRA_CA_CERTS` 時略過壓縮。若 Claude Code 無法偵測的 [TLS 檢查代理伺服器](/docs/zh-TW/network-config#ca-certificate-store)無法正確處理壓縮的請求，請使用 `0` |326| `CLAUDE_CODE_GZIP_REQUEST_BODIES` | 設為 `0` 可關閉傳送至 `api.anthropic.com` 的 Claude API、遙測與 [artifact](/docs/zh-TW/artifacts) 發佈請求主體的 gzip 壓縮。預設情況下，Claude Code 會在直接連線時壓縮大型請求主體，並在您透過代理伺服器傳送請求、設定用戶端憑證或設定 `NODE_EXTRA_CA_CERTS` 時略過壓縮。若 Claude Code 無法偵測到的 [TLS 檢查代理伺服器](/docs/zh-TW/network-config#ca-certificate-store)錯誤處理壓縮請求，請使用 `0` |

324| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | 設為 `1` 可略過 IDE 擴充功能的自動安裝。等同於將 [`autoInstallIdeExtension`](/docs/zh-TW/settings-reference#autoinstallideextension) 設為 `false` |329| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | 設為 `1` 可略過 IDE 擴充功能的自動安裝。等同於將 [`autoInstallIdeExtension`](/docs/zh-TW/settings-reference#autoinstallideextension) 設為 `false` |

326| `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` | 一個工作階段中可同時執行多少個 [subagent](/docs/zh-TW/sub-agents#concurrent-subagent-limit)，超過後 Agent 工具會拒絕再產生（預設：20）。接受純數字的正整數；其他任何值都會被忽略，因此此變數可調整上限但無法停用上限。需要 Claude Code v2.1.217 或更新版本 |331| `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` | 在 Agent 工具拒絕再產生另一個 subagent 之前，一個工作階段中可同時執行的 [subagent](/docs/zh-TW/sub-agents#concurrent-subagent-limit) 數量（預設：20）。接受純數字的正整數；其他任何值都會被忽略，因此此變數可調整上限，但無法停用上限。需要 Claude Code v2.1.217 或更新版本 |

327| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | 覆寫 Claude Code 為作用中模型假設的上下文視窗大小。自 v2.1.193 起，其套用方式取決於 Claude Code 如何解析模型 ID；請參閱[修正閘道或自訂模型 ID 的視窗](/docs/zh-TW/model-config#correct-the-window-for-a-gateway-or-custom-model-id)。當透過 `ANTHROPIC_BASE_URL` 路由至某個模型，而其上下文視窗與其名稱的內建大小不符時使用 |332| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | 覆寫 Claude Code 為作用中模型假設的上下文視窗大小。自 v2.1.193 起，其套用方式取決於 Claude Code 如何解析模型 ID；請參閱[為閘道或自訂模型 ID 修正視窗](/docs/zh-TW/model-config#correct-the-window-for-a-gateway-or-custom-model-id)。當透過 `ANTHROPIC_BASE_URL` 路由至某個模型，而其上下文視窗與其名稱對應的內建大小不符時使用 |

328| `CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH` | Claude Code 傳送給模型的每個 MCP 工具描述與每個 MCP 伺服器指令的最大長度（字元）（預設：2048）。Claude Code 會[截斷較長的文字](/docs/zh-TW/mcp#for-mcp-server-authors)。接受純數字的正整數。其他任何值都會被忽略並套用預設值。需要 Claude Code v2.1.280 或更新版本 |333| `CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH` | Claude Code 傳送給模型的每個 MCP 工具描述與每個 MCP 伺服器指令的最大長度（字元數）（預設：2048）。Claude Code 會[截斷較長的文字](/docs/zh-TW/mcp#for-mcp-server-authors)。接受純數字的正整數。其他任何值都會被忽略並套用預設值。需要 Claude Code v2.1.280 或更新版本 |

329| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 設定大多數請求的最大輸出 token 數。預設值與上限因模型而異；請參閱[最大輸出 token](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)。Claude Code 會將超過模型上限的值降至上限。對於 Claude Code 無法解析為已知模型的模型 ID，預設值為 32000，上限為 128000。增加此值會減少觸發[自動壓縮](/docs/zh-TW/costs#reduce-token-usage)前可用的有效上下文視窗 |334| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 設定大多數請求的最大輸出 token 數。預設值與上限因模型而異；請參閱[最大輸出 token 數](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)。Claude Code 會將超過模型上限的值降至上限。對於 Claude Code 無法解析為已知模型的模型 ID，預設值為 32000，上限為 128000。增加此值會減少觸發[自動壓縮](/docs/zh-TW/costs#reduce-token-usage)之前可用的有效上下文視窗 |

330| `CLAUDE_CODE_MAX_RETRIES` | 覆寫失敗 API 請求的重試次數（預設：10）。自 v2.1.186 起上限為 15；自 v2.1.199 起，`CLAUDE_CODE_RETRY_WATCHDOG` 會提高預設值並移除上限。對於需要等待較長中斷時間的無人值守工作階段，請改為設定 `CLAUDE_CODE_RETRY_WATCHDOG` |335| `CLAUDE_CODE_MAX_RETRIES` | 覆寫失敗 API 請求的重試次數（預設：10）。自 v2.1.186 起上限為 15；自 v2.1.199 起，`CLAUDE_CODE_RETRY_WATCHDOG` 會提高預設值並移除上限。對於需要等候較長服務中斷的無人值守工作階段，請改為設定 `CLAUDE_CODE_RETRY_WATCHDOG` |

331| `CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION` | 已在 v2.1.224 移除，現在不再有作用。先前用於限制 Claude 在一個工作階段中能以 Agent 工具產生的 [subagent](/docs/zh-TW/sub-agents) 總數（預設：200）；超過上限時產生會失敗並顯示 `Subagent spawn limit reached`。[同時執行的 subagent 上限](/docs/zh-TW/sub-agents#concurrent-subagent-limit)與[深度上限](/docs/zh-TW/sub-agents#let-subagents-spawn-their-own-subagents)仍然適用 |336| `CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION` | 已於 v2.1.224 移除，現在不具作用。先前用於限制 Claude 在一個工作階段中可透過 Agent 工具產生的 [subagent](/docs/zh-TW/sub-agents) 總數（預設：200）；超過上限的產生會以 `Subagent spawn limit reached` 失敗。[同時執行的 subagent 上限](/docs/zh-TW/sub-agents#concurrent-subagent-limit)與[深度上限](/docs/zh-TW/sub-agents#let-subagents-spawn-their-own-subagents)仍然適用 |

332| `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` | 主對話之下允許的 [subagent 層數](/docs/zh-TW/sub-agents#let-subagents-spawn-their-own-subagents) （預設：3）。在預設值下，subagent 可以產生自己的 subagent，而第三層的 subagent 無法再繼續產生；設為 `1` 可關閉巢狀。在 v2.1.217 至 v2.1.218 中，預設值為 1，因此除非您提高上限，否則 subagent 無法產生自己的 subagent；v2.1.219 將預設值提高為 3。接受純數字的正整數；其他任何值都會被忽略，因此上限可以調整但無法移除。需要 Claude Code v2.1.217 或更新版本 |337| `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` | 主對話下方允許的 [subagent 層數](/docs/zh-TW/sub-agents#let-subagents-spawn-their-own-subagents) （預設：3）。在預設值下，subagent 可以產生自己的 subagent，而位於第三層的 subagent 無法再進一步產生；設為 `1` 可關閉巢狀。在 v2.1.217 至 v2.1.218 中，預設值為 1，因此除非您提高上限，否則 subagent 無法產生自己的 subagent；v2.1.219 將預設值提高為 3。接受純數字的正整數；其他任何值都會被忽略，因此上限可以調整但無法移除。需要 Claude Code v2.1.217 或更新版本 |

334| `CLAUDE_CODE_MAX_TURNS` | 在未傳遞明確上限時限制 agentic 回合數。等同於傳遞 [`--max-turns`](/docs/zh-TW/cli-reference#cli-flags)，兩者皆設定時以該旗標優先。非正整數的值會在啟動時以錯誤拒絕，而不會被視為無上限 |339| `CLAUDE_CODE_MAX_TURNS` | 在未傳遞明確上限時，限制 agentic 回合數。等同於傳遞 [`--max-turns`](/docs/zh-TW/cli-reference#cli-flags)，兩者皆設定時以該旗標為優先。非正整數的值會在啟動時以錯誤拒絕，而不會被視為無上限 |

335| `CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION` | [WebSearch](/docs/zh-TW/tools-reference#session-search-limit) 呼叫次數的上限（預設：200）。當 Claude 達到上限時，後續的 WebSearch 呼叫會傳回一則通知，告知它以已收集到的資訊繼續。接受沒有上限的正整數。其他任何值都會被忽略並套用預設值，因此此上限可以提高但無法關閉。需要 Claude Code v2.1.212 或更新版本 |340| `CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION` | [WebSearch](/docs/zh-TW/tools-reference#session-search-limit) 呼叫次數的上限（預設：200）。當 Claude 達到上限時，後續的 WebSearch 呼叫會傳回一則通知，告訴它以已收集的資訊繼續。接受沒有上限的正整數。其他任何值都會被忽略並套用預設值，因此此上限可以提高但無法關閉。需要 Claude Code v2.1.212 或更新版本 |

337| `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` | 仍在執行的 MCP 工具呼叫在經過多少毫秒後會[移至背景任務](/docs/zh-TW/mcp#automatic-backgrounding-of-long-tool-calls)（預設：120000，即 2 分鐘）。設為 `0` 可關閉自動移至背景。需要 Claude Code v2.1.212 或更新版本 |342| `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` | 仍在執行的 MCP 工具呼叫[移至背景任務](/docs/zh-TW/mcp#automatic-backgrounding-of-long-tool-calls)之前經過的時間（毫秒）（預設：120000，即 2 分鐘）。設為 `0` 可關閉自動背景執行。需要 Claude Code v2.1.212 或更新版本 |

338| `CLAUDE_CODE_MCP_STARTUP_WAIT_MS` | [非互動](/docs/zh-TW/headless)工作階段的第一個回合等待仍在連線中的 MCP 伺服器的時間（毫秒），取代預設的[第一回合等待](/docs/zh-TW/agent-sdk/mcp#connection-timing)。設定後，等待會涵蓋所有待連線的伺服器。設為 `0` 可略過等待。[`--permission-prompt-tool`](/docs/zh-TW/cli-reference#cli-flags) 伺服器無論此值為何，都會保留自己的 `MCP_TIMEOUT` 等待。需要 Claude Code v2.1.274 或更新版本 |343| `CLAUDE_CODE_MCP_STARTUP_WAIT_MS` | [非互動](/docs/zh-TW/headless)工作階段的第一個回合等待仍在連線中的 MCP 伺服器的時間（毫秒），取代預設的[第一回合等待](/docs/zh-TW/agent-sdk/mcp#connection-timing)。設定後，等待會涵蓋所有擱置中的伺服器。設為 `0` 可略過等待。無論此值為何，[`--permission-prompt-tool`](/docs/zh-TW/cli-reference#cli-flags) 伺服器都會保留其自己的 `MCP_TIMEOUT` 等待。需要 Claude Code v2.1.274 或更新版本 |

339| `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` | MCP 工具呼叫的閒置逾時時間（毫秒）。當 stdio、HTTP、SSE、WebSocket 或 [claude.ai 連接器](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai) MCP 伺服器在這段時間內沒有傳送任何回應也沒有進度通知時，工具呼叫會以錯誤中止，而不會等待整體的 `MCP_TOOL_TIMEOUT`。覆寫各傳輸方式的預設值：網路伺服器為 300000（5 分鐘），stdio 伺服器為 1800000（30 分鐘）。設為 `0` 可停用閒置檢查。低於 1000 的值會提高為一秒，且此值的上限為實際生效的 `MCP_TOOL_TIMEOUT`。`.mcp.json` 中至少為 1000 的個別伺服器 `timeout`，會將該伺服器的閒置時間窗提高至至少該 `timeout` 值。不適用於 IDE 伺服器或 SDK 程序內伺服器。需要 Claude Code v2.1.187 或更新版本。在 v2.1.203 之前，stdio 伺服器不受閒置逾時限制 |344| `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` | MCP 工具呼叫的閒置逾時（毫秒）。當 stdio、HTTP、SSE、WebSocket 或 [claude.ai 連接器](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai) MCP 伺服器在這段時間內沒有傳送任何回應或進度通知時，工具呼叫會以錯誤中止，而不會等待整體的 `MCP_TOOL_TIMEOUT`。覆寫各傳輸方式的預設值：網路伺服器為 300000（5 分鐘），stdio 伺服器為 1800000（30 分鐘）。設為 `0` 可停用閒置檢查。低於 1000 的值會提高為一秒，且此值的上限為有效的 `MCP_TOOL_TIMEOUT`。`.mcp.json` 中至少為 1000 的個別伺服器 `timeout` 會將該伺服器的閒置時間窗提高至至少為 `timeout` 值。不適用於 IDE 伺服器或 SDK 同程序伺服器。需要 Claude Code v2.1.187 或更新版本。在 v2.1.203 之前，stdio 伺服器不受閒置逾時限制 |

340| `CLAUDE_CODE_MESSAGING_SOCKET` | 由 Claude Code 設定，而非由您設定：在綁定[收件匣 socket](/docs/zh-TW/cross-session-messaging#the-sessions-inbox-socket)的工作階段中，Claude Code 會在綁定 socket 時將該 socket 的路徑匯出給 hook 與 Bash 命令。在啟動時即開啟傳訊功能的工作階段中，Claude Code 會在任何 hook 執行之前綁定 socket。機器上的其他工作階段會將訊息傳遞至此路徑。每個工作階段都會匯出自己的 socket，而非從父工作階段繼承，且抵達的訊息會經過該工作階段的[傳入控制](/docs/zh-TW/cross-session-messaging#control-inbound-messages)。設定的 `env` 區塊無法設定此變數。需要 Claude Code v2.1.224 或更新版本 |345| `CLAUDE_CODE_MESSAGING_SOCKET` | 由 Claude Code 設定，而非由您設定：在繫結[收件匣 socket](/docs/zh-TW/cross-session-messaging#the-sessions-inbox-socket) 的工作階段中，Claude Code 會在繫結 socket 時將該 socket 的路徑匯出給 hook 與 Bash 命令。在以開啟訊息功能啟動的工作階段中，Claude Code 會在任何 hook 執行之前繫結 socket。機器上的其他工作階段會將訊息傳遞至此路徑。每個工作階段會匯出自己的 socket，而非從父工作階段繼承的 socket，且抵達該 socket 的訊息會經過工作階段的[傳入控制](/docs/zh-TW/cross-session-messaging#control-inbound-messages)。設定的 `env` 區塊無法設定此變數。需要 Claude Code v2.1.224 或更新版本 |

341| `CLAUDE_CODE_MESSAGING_TOKEN` | 由 Claude Code 設定，而非由您設定：在綁定[收件匣 socket](/docs/zh-TW/cross-session-messaging#the-sessions-inbox-socket)的工作階段中，Claude Code 會將此工作階段專屬 token 與 `CLAUDE_CODE_MESSAGING_SOCKET` 一併匯出給 hook 與 Bash 命令。向該 socket 傳送訊息的指令碼可以將 `{"type":"auth","token":"<token>"}` 作為第一行傳送，以證明自己屬於該工作階段。在原生 Windows 上，Claude Code 要求必須有此行，並會關閉任何未以有效的此行開頭的連線。[自身子程序規則](/docs/zh-TW/cross-session-messaging#the-sessions-inbox-socket)說明 Claude Code 何時會查驗此 token。每個工作階段都會匯出自己的 token，絕不會從父工作階段繼承。設定的 `env` 區塊無法設定此變數。需要 Claude Code v2.1.228 或更新版本 |346| `CLAUDE_CODE_MESSAGING_TOKEN` | 由 Claude Code 設定，而非由您設定：在繫結[收件匣 socket](/docs/zh-TW/cross-session-messaging#the-sessions-inbox-socket) 的工作階段中，Claude Code 會將此工作階段專屬的 token 與 `CLAUDE_CODE_MESSAGING_SOCKET` 一起匯出給 hook 與 Bash 命令。張貼至 socket 的指令碼可傳送 `{"type":"auth","token":"<token>"}` 作為第一行，以證明其屬於該工作階段。在原生 Windows 上，Claude Code 要求此行，並會關閉任何未以有效此行開頭的連線。[own-child 規則](/docs/zh-TW/cross-session-messaging#the-sessions-inbox-socket)說明 Claude Code 何時會參考此 token。每個工作階段會匯出自己的 token，絕不會是從父工作階段繼承的 token。設定的 `env` 區塊無法設定此變數。需要 Claude Code v2.1.228 或更新版本 |

342| `CLAUDE_CODE_NATIVE_CURSOR` | 設為 `1` 可在輸入插入點顯示終端機本身的游標，而非繪製的方塊。游標會遵循終端機的閃爍、形狀與焦點設定。設為 `0` 與未設定此變數的效果相同，因此在終端機本身游標已開啟的工作階段中，它不會讓繪製的方塊恢復 |347| `CLAUDE_CODE_NATIVE_CURSOR` | 設為 `1` 可在輸入插入點顯示終端機本身的游標，而非繪製的方塊。游標會遵循終端機的閃爍、形狀與焦點設定。設定 `0` 與未設定此變數的效果相同，因此在終端機本身游標已開啟的工作階段中，它不會讓繪製的方塊恢復 |

343| `CLAUDE_CODE_NEW_INIT` | 設為 `1` 可讓 `/init` 執行互動式設定流程。此流程會先詢問要產生哪些檔案，包括 CLAUDE.md、skill 與 hook，然後才探索程式碼庫並寫入這些檔案。若未設定此變數，`/init` 會自動產生 CLAUDE.md 而不提示 |348| `CLAUDE_CODE_NEW_INIT` | 設為 `1` 可讓 `/init` 執行互動式設定流程。此流程會在探索程式碼庫並寫入檔案之前，詢問要產生哪些檔案，包括 CLAUDE.md、skill 與 hook。若未設定此變數，`/init` 會自動產生 CLAUDE.md，不會提示 |

344| `CLAUDE_CODE_NONBLOCKING_STDOUT` | 設為 `1` 可透過第二個非阻塞檔案描述元寫入終端機輸出，如此一來，停止讀取的終端機（例如暫停的 tmux 控制模式窗格或停滯的 SSH 連線）就無法讓 Claude Code 在工作階段中途凍結。當 stdout 為終端機時，適用於 macOS、Linux 與 WSL。需要 Claude Code v2.1.261 或更新版本 |349| `CLAUDE_CODE_NONBLOCKING_STDOUT` | 設為 `1` 可透過第二個非阻塞檔案描述元寫入終端機輸出，讓停止讀取的終端機（例如暫停的 tmux control-mode 窗格或停滯的 SSH 連線）無法在工作階段中途凍結 Claude Code。在 stdout 為終端機時，適用於 macOS、Linux 與 WSL。需要 Claude Code v2.1.261 或更新版本 |

345| `CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES` | 限制 Claude Code 重新傳送逾時的[非串流請求](/docs/zh-TW/errors#streaming-response-ended-before-any-complete-data-was-received)的次數。設為 `0` 時，請求會在第一次逾時時即失敗。逾時時間請參閱[調整重試行為](/docs/zh-TW/errors#tune-retry-behavior)。需要 Claude Code v2.1.285 或更新版本 |350| `CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES` | 限制 Claude Code 重新傳送逾時的[非串流請求](/docs/zh-TW/errors#streaming-response-ended-before-any-complete-data-was-received)的次數。設為 `0` 時，請求會在第一次逾時時失敗。關於逾時時間，請參閱[調整重試行為](/docs/zh-TW/errors#tune-retry-behavior)。需要 Claude Code v2.1.285 或更新版本 |

346| `CLAUDE_CODE_NO_FLICKER` | 設為 `1` 以啟用[全螢幕呈現](/docs/zh-TW/fullscreen)，這是一項研究預覽功能，可減少閃爍並在長對話中維持記憶體用量穩定。覆寫 [`tui`](/docs/zh-TW/settings-reference#tui) 設定；您也可以使用 `/tui fullscreen` 切換 |351| `CLAUDE_CODE_NO_FLICKER` | 設為 `1` 以啟用[全螢幕呈現](/docs/zh-TW/fullscreen)，這是一項研究預覽功能，可減少閃爍並在長對話中保持記憶體用量穩定。覆寫 [`tui`](/docs/zh-TW/settings-reference#tui) 設定；您也可以使用 `/tui fullscreen` 切換 |

347| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | 用於 Claude.ai 身分驗證的 OAuth refresh token。設定後，`claude auth login` 會直接交換此 token，而不開啟瀏覽器。需要 `CLAUDE_CODE_OAUTH_SCOPES`。適用於在自動化環境中佈建身分驗證 |352| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | 用於 Claude.ai 身分驗證的 OAuth refresh token。設定後，`claude auth login` 會直接交換此 token，而不會開啟瀏覽器。需要 `CLAUDE_CODE_OAUTH_SCOPES`。適用於在自動化環境中佈建身分驗證 |

348| `CLAUDE_CODE_OAUTH_SCOPES` | 以空格分隔、核發 refresh token 時所使用的 OAuth 範圍，例如 `"user:profile user:inference user:sessions:claude_code"`。設定 `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` 時為必要 |353| `CLAUDE_CODE_OAUTH_SCOPES` | 以空格分隔、核發 refresh token 時所使用的 OAuth 範圍，例如 `"user:profile user:inference user:sessions:claude_code"`。設定 `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` 時為必要 |

349| `CLAUDE_CODE_OAUTH_TOKEN` | 用於 claude.ai 身分驗證的 OAuth access token。在 SDK 與自動化環境中可作為 `/login` 的替代方案。優先於儲存在 keychain 中的憑證。請使用 [`claude setup-token`](/docs/zh-TW/authentication#generate-a-long-lived-token) 產生。除非您執行 [`/login`](/docs/zh-TW/authentication#authentication-precedence)，否則 Claude Code 會在整個工作階段中使用您設定的 token。若要更換已過期的 token，請產生新的 token 並重新啟動 |354| `CLAUDE_CODE_OAUTH_TOKEN` | 用於 claude.ai 身分驗證的 OAuth access token。在 SDK 與自動化環境中可取代 `/login`。優先於儲存在鑰匙圈中的憑證。使用 [`claude setup-token`](/docs/zh-TW/authentication#generate-a-long-lived-token) 產生。除非您執行 [`/login`](/docs/zh-TW/authentication#authentication-precedence)，否則 Claude Code 會在整個工作階段中使用您設定的 token。若要取代已過期的 token，請產生新的 token 並重新啟動 |

350| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | 已在 v2.1.160 移除，現在不再有作用。先前用於將[快速模式](/docs/zh-TW/fast-mode)固定在 Claude Opus 4.6，而非目前的預設值。Opus 4.6 已不再支援快速模式 |355| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | 已於 v2.1.160 移除，現在不具作用。先前會將[快速模式](/docs/zh-TW/fast-mode)固定為 Claude Opus 4.6，而非目前的預設值。Opus 4.6 已不再支援快速模式 |

351| `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` | 承載內容的 OpenTelemetry 屬性（模型回應、工具內容、系統提示詞、原始 API 本文）的最大長度，包含截斷標記在內，以 UTF-16 碼元計算（預設：61440，即 60 KB）。只有在您的遙測後端接受大於 64 KB 的屬性值時才調高，或調低以減少遙測量。需要 Claude Code v2.1.214 或更新版本。請參閱[監控](/docs/zh-TW/monitoring-usage) |356| `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` | 承載內容的 OpenTelemetry 屬性（模型回應、工具內容、系統提示詞、原始 API 主體）的最大長度，包含截斷標記，以 UTF-16 碼元計算（預設：61440，即 60 KB）。僅在您的遙測後端接受大於 64 KB 的屬性值時才調高，或調低以減少遙測量。需要 Claude Code v2.1.214 或更新版本。請參閱[監控](/docs/zh-TW/monitoring-usage) |

352| `CLAUDE_CODE_OTEL_DIAG_STDERR` | 設為 `1` 可將 OpenTelemetry exporter 診斷錯誤寫入 stderr。預設情況下，這些錯誤只會在使用 `--debug` 時出現，因此設定錯誤的 exporter（例如 Prometheus 連接埠衝突）在其他情況下會無聲地失敗。需要 Claude Code v2.1.179 或更新版本。請參閱[監控](/docs/zh-TW/monitoring-usage) |357| `CLAUDE_CODE_OTEL_DIAG_STDERR` | 設為 `1` 可將 OpenTelemetry 匯出器的診斷錯誤寫入 stderr。預設情況下，這些錯誤只會在使用 `--debug` 時出現，因此設定錯誤的匯出器（例如 Prometheus 連接埠衝突）否則會無聲失敗。需要 Claude Code v2.1.179 或更新版本。請參閱[監控](/docs/zh-TW/monitoring-usage) |

353| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | 清空待處理 OpenTelemetry span 的逾時時間（毫秒）（預設：5000）。請參閱[監控](/docs/zh-TW/monitoring-usage) |358| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | 清空擱置中 OpenTelemetry span 的逾時時間（毫秒）（預設：5000）。請參閱[監控](/docs/zh-TW/monitoring-usage) |

354| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 重新整理動態 OpenTelemetry 標頭的間隔（毫秒）（預設：1740000 / 29 分鐘）。請參閱[動態標頭](/docs/zh-TW/monitoring-usage#dynamic-headers) |359| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 重新整理動態 OpenTelemetry 標頭的間隔（毫秒）（預設：1740000／29 分鐘）。請參閱[動態標頭](/docs/zh-TW/monitoring-usage#dynamic-headers) |

355| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | OpenTelemetry exporter 在關閉時完成作業的逾時時間（毫秒）（預設：2000）。若指標在結束時遺失，請調高此值。請參閱[監控](/docs/zh-TW/monitoring-usage) |360| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | OpenTelemetry 匯出器在關閉時完成作業的逾時時間（毫秒）（預設：2000）。若指標在結束時遺失，請調高此值。請參閱[監控](/docs/zh-TW/monitoring-usage) |

356| `CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS` | 當 API 以 `529` 過載錯誤拒絕請求時，[自動重試](/docs/zh-TW/errors#tune-retry-behavior)之間指數退避的起始延遲（毫秒），取代預設的 500。當 API 已達容量上限時，調高此值可將重試分散在較長的時間範圍內。請以純數字提供 500 至 32000 的整數毫秒；Claude Code 會將其他任何值視為未設定。當 `CLAUDE_CODE_RETRY_WATCHDOG` 設為 `1`，或被拒絕的請求是以[快速模式](/docs/zh-TW/fast-mode#handle-rate-limits)傳送時，沒有作用。需要 Claude Code v2.1.292 或更新版本 |361| `CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS` | 當 API 以 `529` overloaded 錯誤拒絕請求時，該請求[自動重試](/docs/zh-TW/errors#tune-retry-behavior)之間指數退避的起始延遲（毫秒），取代預設的 500。在 API 容量已滿時，調高此值可將重試分散在較長的時間範圍內。請以純數字提供 500 至 32000 之間的整數毫秒數；Claude Code 會將任何其他值視為未設定。當 `CLAUDE_CODE_RETRY_WATCHDOG` 設為 `1`，或被拒絕的請求是在[快速模式](/docs/zh-TW/fast-mode#handle-rate-limits)中傳送時，沒有作用。需要 Claude Code v2.1.292 或更新版本 |

357| `CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE` | 設為 `1` 可讓 Claude Code 在有新版本時於背景執行套件管理員的升級命令。適用於 Homebrew 與 WinGet 安裝。其他套件管理員仍只會顯示升級命令而不執行。請參閱[自動更新](/docs/zh-TW/setup#auto-updates) |362| `CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE` | 設為 `1` 可讓 Claude Code 在有新版本可用時，於背景執行套件管理員的升級命令。適用於 Homebrew 與 WinGet 安裝。其他套件管理員仍會顯示升級命令而不執行。請參閱[自動更新](/docs/zh-TW/setup#auto-updates) |

358| `CLAUDE_CODE_PERFORCE_MODE` | 設為 `1` 以啟用能感知 Perforce 的寫入保護。設定後，若目標檔案缺少擁有者寫入位元（Perforce 會在已同步的檔案上清除此位元，直到 `p4 edit` 開啟它們為止），Edit、Write 與 NotebookEdit 會失敗並顯示 `p4 edit <file>` 提示。這可防止 Claude Code 繞過 Perforce 的變更追蹤 |363| `CLAUDE_CODE_PERFORCE_MODE` | 設為 `1` 以啟用可感知 Perforce 的寫入保護。設定後，若目標檔案缺少擁有者寫入位元，Edit、Write 與 NotebookEdit 會失敗並提示 `p4 edit <file>`；Perforce 會清除已同步檔案的此位元，直到 `p4 edit` 開啟它們為止。這可防止 Claude Code 繞過 Perforce 變更追蹤 |

360| `CLAUDE_CODE_PLUGIN_DIRS` | 要為工作階段載入的外掛目錄，每個目錄的載入方式與 [`--plugin-dir`](/docs/zh-TW/plugins/cli-reference#flags-that-load-a-plugin-for-one-session) 旗標相同。多個路徑在 Unix 上以 `:` 分隔，在 Windows 上以 `;` 分隔。請以絕對路徑或以 `~` 開頭的路徑提供每個路徑，因為 Claude Code 會略過相對路徑。需要 Claude Code v2.1.280 或更新版本。請參閱[為單一工作階段載入外掛](/docs/zh-TW/plugins/create#load-a-directory-or-archive-for-one-session) |365| `CLAUDE_CODE_PLUGIN_DIRS` | 要為工作階段載入的外掛目錄，每個目錄的載入方式與 [`--plugin-dir`](/docs/zh-TW/plugins/cli-reference#flags-that-load-a-plugin-for-one-session) 旗標相同。在 Unix 上以 `:` 分隔多個路徑，在 Windows 上以 `;` 分隔。請以絕對路徑提供每個路徑，或以 `~` 開頭，因為 Claude Code 會略過相對路徑。需要 Claude Code v2.1.280 或更新版本。請參閱[為單一工作階段載入外掛](/docs/zh-TW/plugins/create#load-a-directory-or-archive-for-one-session) |

361| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | 控制 Claude Code 是否在 [mod](/docs/zh-TW/plugins/mods/overview) 的檔案變更時重新載入該 mod。重新載入適用於您以 `--plugin-dir` 從目錄載入的 mod，且在互動式工作階段中預設開啟。設為 `1` 可在非互動式工作階段中也開啟，或設為 `0` 在所有工作階段中關閉。需要 Claude Code v2.1.287 或更新版本。請參閱 [mod 設定與環境變數](/docs/zh-TW/plugins/mods/reference#settings-and-environment-variables) |366| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | 控制 Claude Code 是否在 [mod](/docs/zh-TW/plugins/mods/overview) 的檔案變更時重新載入該 mod。重新載入適用於您使用 `--plugin-dir` 從目錄載入的 mod，且在互動式工作階段中預設為開啟。設為 `1` 可在非互動式工作階段中也開啟，或設為 `0` 在所有工作階段中關閉。需要 Claude Code v2.1.287 或更新版本。請參閱 [mod 設定與環境變數](/docs/zh-TW/plugins/mods/reference#settings-and-environment-variables) |

362| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | clone 或重新整理外掛市集的逾時時間（毫秒）（預設：120000）。對於大型儲存庫或緩慢的網路連線，請調高此值。請參閱 [Git clone timed out](/docs/zh-TW/plugins/troubleshooting#git-clone-timed-out-after-120s) |367| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 複製或重新整理外掛市集的逾時時間（毫秒）（預設：120000）。對於大型儲存庫或緩慢的網路連線，請調高此值。請參閱 [Git clone timed out](/docs/zh-TW/plugins/troubleshooting#git-clone-timed-out-after-120s) |

363| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 設為 `1` 可在市集重新整理無法連線至遠端或無法通過遠端身分驗證時，略過重新 clone 的嘗試，並繼續使用既有的市集 checkout。適用於重新 clone 也會以相同方式失敗的離線或實體隔離環境。請參閱[市集更新在離線環境中失敗](/docs/zh-TW/plugins/troubleshooting#marketplace-updates-keep-failing-offline) |368| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 設為 `1` 可在市集重新整理無法連線至遠端或無法通過遠端身分驗證時，略過重新複製的嘗試並繼續使用現有的市集 checkout。適用於離線或氣隙隔離環境，在這類環境中重新複製也會以相同方式失敗。請參閱[市集更新在離線環境中失敗](/docs/zh-TW/plugins/troubleshooting#marketplace-updates-keep-failing-offline) |

364| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | 設為 `1` 可透過 HTTPS 而非 SSH 來 clone GitHub `owner/repo` 簡寫來源。適用於外掛安裝與更新，以及 `/plugin marketplace add` 與 `update`。適用於 CI runner、容器或任何未為 `github.com` 設定 SSH 金鑰的環境 |369| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | 設為 `1` 可透過 HTTPS 而非 SSH 複製 GitHub `owner/repo` 簡寫來源。適用於外掛安裝與更新，以及 `/plugin marketplace add` 與 `update`。適用於 CI 執行器、容器，或任何未為 `github.com` 設定 SSH 金鑰的環境 |

365| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 一或多個唯讀外掛種子目錄的路徑，在 Unix 上以 `:` 分隔，在 Windows 上以 `;` 分隔。可用於將預先填入的外掛目錄打包至容器映像中。Claude Code 會在啟動時從這些目錄註冊市集，並使用預先快取的外掛而無需重新 clone。請參閱[為容器預先填入外掛](/docs/zh-TW/plugins/org#seed-containers-and-ci) |370| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 一或多個唯讀外掛種子目錄的路徑，在 Unix 上以 `:` 分隔，在 Windows 上以 `;` 分隔。使用此變數可將預先填入的外掛目錄打包至容器映像中。Claude Code 會在啟動時從這些目錄註冊市集，並使用預先快取的外掛而無需重新複製。請參閱[為容器預先填入外掛](/docs/zh-TW/plugins/org#seed-containers-and-ci) |

366| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | 設為 `1` 可讓 Claude Code 在為工具呼叫、hook 與狀態列命令啟動 PowerShell 時不傳遞 `-ExecutionPolicy Bypass`，改為遵循機器的有效執行原則。預設情況下，Claude Code 會在程序範圍略過執行原則，讓 `.ps1` 指令碼與模組匯入能在預設為 Restricted 的 Windows 安裝上運作。無論此設定為何，程序範圍的略過都不會覆寫群組原則 `MachinePolicy` 或 `UserPolicy` |371| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | 設為 `1` 可讓 Claude Code 在為工具呼叫、hook 與狀態列命令產生 PowerShell 時不再傳遞 `-ExecutionPolicy Bypass`，改為遵循機器的有效執行原則。預設情況下，Claude Code 會在程序範圍略過執行原則，讓 `.ps1` 指令碼與模組匯入能在預設為 Restricted 的 Windows 安裝上運作。無論此設定為何，程序範圍的略過絕不會覆寫群組原則 `MachinePolicy` 或 `UserPolicy` |

367| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | 在使用 `-p` 旗標的[非互動模式](/docs/zh-TW/headless#background-tasks-at-exit)中，最後一個回合之後閒置等待背景工作（例如 subagent 與工作流程）的上限（毫秒）。每當 Claude 用一個回合處理背景結果時，閒置等待就會重新計算。預設：`600000`，即 10 分鐘。當閒置等待達到上限時，Claude Code 會停止等待剩餘的背景任務。由主對話啟動且仍在執行的背景命令會讓執行持續超過此上限。設為 `0` 可無限期等待。需要 Claude Code v2.1.182 或更新版本 |372| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | 在使用 `-p` 旗標的[非互動模式](/docs/zh-TW/headless#background-tasks-at-exit)中，最後一個回合之後閒置等待背景工作（例如 subagent 與工作流程）的上限（毫秒）。每當 Claude 進行一個回合來處理背景結果時，閒置等待都會重新開始計算。預設：`600000`，即 10 分鐘。當閒置等待達到上限時，Claude Code 會停止等待其餘的背景任務。由主對話啟動且正在執行的背景命令會讓該次執行在超過上限後仍保持開啟。設為 `0` 可無限期等待。需要 Claude Code v2.1.182 或更新版本 |

368| `CLAUDE_CODE_PROCESS_WRAPPER` | 透過以 argv 前綴形式提供的企業啟動器（例如 `/opt/corp/launcher`），啟動 Claude Code 從自身二進位檔啟動的程序，例如承載 [agent view](/docs/zh-TW/agent-view) 工作階段的背景服務。請在使用者設定或[受管設定](/docs/zh-TW/managed-settings)的 `env` 區塊中設定，而非以 shell export 設定，讓分離的背景服務能繼承它；專案與本機設定無法設定此變數。等同於 [`processWrapper` 設定](/docs/zh-TW/settings-reference#processwrapper)，該設定需要 Claude Code v2.1.210 或更新版本；兩者皆設定時以此變數優先。VS Code 擴充功能會透過其 `claudeProcessWrapper` 設定另外設定自己的啟動器。在 Windows 上會被忽略。關於值的格式、啟動器涵蓋的範圍，以及啟動器必須滿足的約定，請參閱[在企業啟動器後方執行 Claude Code](/docs/zh-TW/corporate-launcher)。需要 Claude Code v2.1.208 或更新版本 |373| `CLAUDE_CODE_PROCESS_WRAPPER` | 透過以 argv 前綴（例如 `/opt/corp/launcher`）提供的企業啟動器，啟動 Claude Code 從自身二進位檔啟動的程序，例如承載 [agent view](/docs/zh-TW/agent-view) 工作階段的背景服務。請在使用者設定或[受管設定](/docs/zh-TW/managed-settings)的 `env` 區塊中設定，而非以 shell 匯出方式設定，如此分離的背景服務才會繼承它；專案與本機設定無法設定此變數。等同於 [`processWrapper` 設定](/docs/zh-TW/settings-reference#processwrapper)，該設定需要 Claude Code v2.1.210 或更新版本；兩者皆設定時，以此變數為優先。VS Code 擴充功能會透過其 `claudeProcessWrapper` 設定另外設定自己的啟動器。在 Windows 上會被忽略。關於值的格式、啟動器涵蓋的範圍，以及啟動器必須滿足的約定，請參閱[在企業啟動器後方執行 Claude Code](/docs/zh-TW/corporate-launcher)。需要 Claude Code v2.1.208 或更新版本 |

369| `CLAUDE_CODE_PROJECT_DIR_NAME` | 與 `CLAUDE_CONFIG_DIR` 一起設定，用以選擇 Claude Code 儲存該工作階段逐字稿與自動記憶的 `projects/` 目錄名稱，取代由工作目錄路徑衍生的名稱。例如，以 `CLAUDE_CONFIG_DIR=/srv/tenant-a CLAUDE_CODE_PROJECT_DIR_NAME=work claude` 啟動 Claude Code，會將它們儲存在 `/srv/tenant-a/projects/work/` 下。未設定 `CLAUDE_CONFIG_DIR` 時，Claude Code 會忽略此變數，且只會從您啟動 `claude` 的環境讀取它，絕不會從[設定檔的 `env` 區塊](#in-settings-files)讀取。請參閱[自行命名專案目錄](/docs/zh-TW/sessions#name-the-project-directory-yourself)。需要 Claude Code v2.1.234 或更新版本 |374| `CLAUDE_CODE_PROJECT_DIR_NAME` | 與 `CLAUDE_CONFIG_DIR` 一起設定，以選擇 Claude Code 儲存該工作階段逐字稿與自動記憶所用的 `projects/` 目錄名稱，取代從工作目錄路徑推導出的名稱。例如，以 `CLAUDE_CONFIG_DIR=/srv/tenant-a CLAUDE_CODE_PROJECT_DIR_NAME=work claude` 啟動 Claude Code 會將它們儲存在 `/srv/tenant-a/projects/work/` 下。當 `CLAUDE_CONFIG_DIR` 未設定時，Claude Code 會忽略此變數，且只會從您啟動 `claude` 的環境中讀取，絕不會從[設定檔的 `env` 區塊](#in-settings-files)讀取。請參閱[自行命名專案目錄](/docs/zh-TW/sessions#name-the-project-directory-yourself)。需要 Claude Code v2.1.234 或更新版本 |

370| `CLAUDE_CODE_PROMPT_CACHE_TTL` | 設為 `5m` 或 `1h`（Claude Code 僅接受這兩個值），以選擇主對話的[提示快取 TTL](/docs/zh-TW/prompt-caching#cache-lifetime)：包括您的互動式、`-p` 與 SDK 回合，以及與其同步執行的輔助程式。優先於 `promptCacheTtl` 設定與 `ENABLE_PROMPT_CACHING_1H`，而 `FORCE_PROMPT_CACHING_5M` 會覆寫它。API 對 1 小時快取寫入收取較高的費率。需要 Claude Code v2.1.242 或更新版本 |375| `CLAUDE_CODE_PROMPT_CACHE_TTL` | 設定 `5m` 或 `1h`（Claude Code 僅接受這兩個值），以選擇主對話的[提示快取 TTL](/docs/zh-TW/prompt-caching#cache-lifetime)：包括您的互動式、`-p` 與 SDK 回合，以及與其內嵌執行的輔助程序。優先於 `promptCacheTtl` 設定與 `ENABLE_PROMPT_CACHING_1H`，而 `FORCE_PROMPT_CACHING_5M` 會覆寫它。API 對 1 小時快取寫入以較高費率計費。需要 Claude Code v2.1.242 或更新版本 |

371| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | 設為 `1` 可在 `ANTHROPIC_BASE_URL` 指向自訂代理伺服器時傳播 W3C 追蹤上下文。傳播涵蓋模型與 HTTP MCP 請求上的 `traceparent` 標頭，以及 Bash、PowerShell 與 hook 子程序的 `TRACEPARENT` 環境變數。預設情況下，只有在直接連線至 Anthropic API 時才會啟用傳播。於 v2.1.152 新增。請參閱[追蹤（beta）](/docs/zh-TW/monitoring-usage#traces-beta) |376| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | 設為 `1` 可在 `ANTHROPIC_BASE_URL` 指向自訂代理伺服器時傳播 W3C trace context。傳播範圍涵蓋模型與 HTTP MCP 請求上的 `traceparent` 標頭，以及 Bash、PowerShell 與 hook 子程序的 `TRACEPARENT` 環境變數。預設情況下，僅在直接連線至 Anthropic API 時啟用傳播。於 v2.1.152 新增。請參閱[追蹤（beta）](/docs/zh-TW/monitoring-usage#traces-beta) |

372| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | 由嵌入 Claude Code 並代為管理模型供應商路由的主機平台設定。設定後，Claude Code 會忽略設定檔中的供應商選擇、端點與身分驗證變數，例如 `CLAUDE_CODE_USE_BEDROCK`、`ANTHROPIC_BASE_URL` 與 `ANTHROPIC_API_KEY`，因此使用者設定無法覆寫主機的路由。Claude Code 也會忽略[受管設定](/docs/zh-TW/managed-settings)中的模型選擇鍵，例如 `model`、`fallbackModel` 與 `modelOverrides`，無論由哪個受管來源傳遞，因此主機的模型設定會優先於過時的受管模型固定設定。Claude Code 也會忽略受管 `env` 區塊中的模型選擇變數，例如 `ANTHROPIC_MODEL` 與 `ANTHROPIC_DEFAULT_*_MODEL` 系列；受管設定中的 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection) 允許清單仍然適用，除非主機提供自己的允許清單。Claude Code 也會略過它原本在 Amazon Bedrock、Claude Platform on AWS、Google Cloud's Agent Platform 與 Microsoft Foundry 等第三方供應商上自動套用的遙測退出設定，因此遙測會遵循標準的 `DISABLE_TELEMETRY` 退出機制。請參閱[依 API 供應商區分的預設行為](/docs/zh-TW/data-usage#default-behaviors-by-api-provider) |377| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | 由內嵌 Claude Code 並代為管理模型供應商路由的主機平台設定。設定後，Claude Code 會忽略設定檔中的供應商選擇、端點與身分驗證變數，例如 `CLAUDE_CODE_USE_BEDROCK`、`ANTHROPIC_BASE_URL` 與 `ANTHROPIC_API_KEY`，讓使用者設定無法覆寫主機的路由。Claude Code 也會忽略[受管設定](/docs/zh-TW/managed-settings)中的模型選擇鍵，例如 `model`、`fallbackModel` 與 `modelOverrides`，無論由哪個受管來源提供，因此主機的模型設定會優先於過時的受管模型固定設定。Claude Code 也會忽略受管 `env` 區塊中的模型選擇變數，例如 `ANTHROPIC_MODEL` 與 `ANTHROPIC_DEFAULT_*_MODEL` 系列；受管設定中的 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection) 允許清單仍然適用，除非主機提供自己的允許清單。Claude Code 也會略過其原本在第三方供應商（例如 Amazon Bedrock、Claude Platform on AWS、Google Cloud's Agent Platform 與 Microsoft Foundry）上套用的自動遙測選擇退出，因此遙測會遵循標準的 `DISABLE_TELEMETRY` 選擇退出。請參閱[依 API 供應商區分的預設行為](/docs/zh-TW/data-usage#default-behaviors-by-api-provider) |

374| `CLAUDE_CODE_REMOTE` | 當 Claude Code 以[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)執行時，會自動設為 `true`。可從 hook 或設定指令碼讀取此變數，以偵測您是否位於雲端工作階段中 |379| `CLAUDE_CODE_REMOTE` | 當 Claude Code 以[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)執行時自動設為 `true`。可從 hook 或設定指令碼讀取此值，以偵測是否處於雲端工作階段中 |

375| `CLAUDE_CODE_REMOTE_SESSION_ID` | 在[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)中自動設為目前工作階段的 ID。讀取此變數可建構返回工作階段逐字稿的連結。請參閱[將輸出連結回工作階段](/docs/zh-TW/cloud-environments#link-output-back-to-the-session) |380| `CLAUDE_CODE_REMOTE_SESSION_ID` | 在[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)中自動設為目前工作階段的 ID。讀取此值可建構返回工作階段逐字稿的連結。請參閱[將輸出連結回工作階段](/docs/zh-TW/cloud-environments#link-output-back-to-the-session) |

376| `CLAUDE_CODE_RESTRICTED` | 設為 `1` 可讓工作階段以受限模式啟動，等同於傳遞 [`--restricted`](/docs/zh-TW/cli-reference#cli-flags)。Claude Code 會忽略設定檔 `env` 區塊中的此變數。需要 Claude Code v2.1.248 或更新版本 |381| `CLAUDE_CODE_RESTRICTED` | 設為 `1` 可以受限模式啟動工作階段，等同於傳遞 [`--restricted`](/docs/zh-TW/cli-reference#cli-flags)。Claude Code 會忽略設定檔 `env` 區塊中的此變數。需要 Claude Code v2.1.248 或更新版本 |

377| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | 設為 `1` 可在前一個工作階段於回合中途結束時自動繼續。用於 SDK 模式，讓模型無需 SDK 重新傳送提示詞即可繼續。若要關閉，請取消設定此變數或將其設為 `0`。關於 VS Code 聊天面板，請參閱[重新載入後繼續對話](/docs/zh-TW/vs-code#continue-conversations-after-a-reload) |382| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | 設為 `1` 可在上一個工作階段於回合中途結束時自動繼續。用於 SDK 模式，讓模型無需 SDK 重新傳送提示詞即可繼續。若要關閉，請取消設定此變數或將其設為 `0`。關於 VS Code 聊天面板，請參閱[重新載入後繼續對話](/docs/zh-TW/vs-code#continue-conversations-after-a-reload) |

378| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN_MAX_AGE_MS` | 對於在回合中途結束的工作階段，最後一則逐字稿訊息的最大存在時間（毫秒），在此時間內繼續時才會自動接續。當最後一則訊息早於此界限時，Claude Code 會略過 `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` 的自動繼續及其 `CLAUDE_CODE_RESUME_PROMPT` 接續訊息，工作階段會以閒置狀態啟動，讓您明確地繼續。未設定或 `0` 表示沒有界限，但最後一個請求因 API 錯誤而失敗的回合，只有在該錯誤發生未滿六小時時才會繼續。正值會限制所有回合，包括這些回合；負值或非數值會套用一小時的界限。長時間執行之 agent 的啟動指令碼可設定此變數，讓以舊逐字稿重新啟動時不會重新執行過時的提示詞。當 Claude Code 重新啟動從互動式工作階段繼承對話而當掉的 [agent view](/docs/zh-TW/agent-view) 工作階段時，會自行設定一小時的界限。需要 Claude Code v2.1.211 或更新版本 |383| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN_MAX_AGE_MS` | 於回合中途結束的工作階段若要在繼續時自動接續，其最後一則逐字稿訊息所允許的最大存在時間（毫秒）。當最後一則訊息早於此界限時，Claude Code 會略過 `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` 自動繼續及其 `CLAUDE_CODE_RESUME_PROMPT` 接續訊息，工作階段會以閒置狀態開始，讓您明確地繼續。未設定或 `0` 表示沒有界限，但最後一個請求因 API 錯誤而失敗的回合，只有在該錯誤發生不到六小時時才會繼續。正值會限制每個回合，包括上述回合；負值或非數值則套用一小時的界限。長時間執行 agent 的啟動指令碼可設定此值，讓針對舊逐字稿重新啟動時不會重新執行過時的提示詞。當 Claude Code 重新啟動一個當機、且從互動式工作階段繼承對話的 [agent view](/docs/zh-TW/agent-view) 工作階段時，會自行設定一小時的界限。需要 Claude Code v2.1.211 或更新版本 |

379| `CLAUDE_CODE_RESUME_PROMPT` | 覆寫當 `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` 接續中斷的回合而不重新傳送其提示詞時，或當您以 `-p` 繼續[延後的工具呼叫](/docs/zh-TW/hooks#defer-a-tool-call-for-later)時，Claude Code 傳送給 Claude 的接續訊息。預設為 `Continue from where you left off.`。空字串會使用預設值 |384| `CLAUDE_CODE_RESUME_PROMPT` | 覆寫當 `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` 接續中斷的回合而非重新傳送其提示詞時，或當您以 `-p` 繼續[延後的工具呼叫](/docs/zh-TW/hooks#defer-a-tool-call-for-later)時，Claude Code 傳送給 Claude 的接續訊息。預設為 `Continue from where you left off.`。空字串會使用預設值 |

380| `CLAUDE_CODE_RETRY_WATCHDOG` | 針對評估 harness、CI 作業或遠端 worker 等無人值守工作階段設為 `1`。會無限期重試 `429` 與 `529` 容量錯誤，而不會在 `CLAUDE_CODE_MAX_RETRIES` 次嘗試後失敗。當標準速度請求收到回報支出上限或用量點數已用盡的 `429` 時，Claude Code 會立即失敗，即使是來自依排程重設的[閘道支出上限](/docs/zh-TW/errors#spend-limit-reached)也一樣。在 v2.1.239 之前，watchdog 會無限期重試這些錯誤。關於快速模式請求，請參閱[處理速率限制](/docs/zh-TW/fast-mode#handle-rate-limits)。watchdog 會在嘗試之間退避最多 5 分鐘，或在回應帶有速率限制重設時間時等到上限重設，因此達到用量上限的工作階段會等待剩餘的時間窗結束。在 v2.1.199 或更新版本中，它也會將其他暫時性錯誤（例如伺服器錯誤、逾時與連線中斷）的預設重試次數提高為 300 次，約為三小時的退避時間，並在您明確設定 `CLAUDE_CODE_MAX_RETRIES` 時移除其 15 次的上限。需要 Claude Code v2.1.186 或更新版本 |385| `CLAUDE_CODE_RETRY_WATCHDOG` | 針對無人值守的工作階段（例如 eval harness、CI 作業或遠端 worker）設為 `1`。無限期重試 `429` 與 `529` 容量錯誤，而不是在 `CLAUDE_CODE_MAX_RETRIES` 次嘗試後失敗。當標準速度請求收到回報支出上限或用量點數已用盡的 `429` 時，Claude Code 會立即失敗，即使是來自會依排程重設的[閘道支出上限](/docs/zh-TW/errors#spend-limit-reached)也是如此。在 v2.1.239 之前，watchdog 會無限期重試這些錯誤。關於快速模式請求，請參閱[處理速率限制](/docs/zh-TW/fast-mode#handle-rate-limits)。watchdog 在每次嘗試之間最多退避 5 分鐘，或在回應攜帶速率限制重設時間時等到限制重設為止，因此達到用量上限的工作階段會等候剩餘的時間範圍。在 v2.1.199 或更新版本中，它也會將其他暫時性錯誤（例如伺服器錯誤、逾時與中斷的連線）的預設重試次數提高至 300 次，約為三小時的退避時間，並在您明確設定 `CLAUDE_CODE_MAX_RETRIES` 時移除其 15 次的上限。需要 Claude Code v2.1.186 或更新版本 |

381| `CLAUDE_CODE_SAFE_MODE` | 設為 `1` 可以安全模式啟動：CLAUDE.md、skill、外掛、hook、MCP 伺服器、自訂命令與 agent、輸出風格、工作流程、自訂主題、自訂快捷鍵、狀態列與檔案建議命令、LSP 伺服器以及自動記憶都不會載入，以便對損壞的設定進行疑難排解。受管設定政策仍然適用，包括政策設定的 hook、狀態列與檔案建議命令；受管外掛、受管 skill、受管 CLAUDE.md 與政策設定的 MCP 伺服器則不會載入。等同於傳遞 [`--safe-mode`](/docs/zh-TW/cli-reference#cli-flags)。直接產生的子程序會繼承此變數 |386| `CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS` | 設定 `CLAUDE_CODE_RETRY_WATCHDOG` 時，每個 API 請求等候 `429` 與 `529` 錯誤的最長時間（毫秒）。用完該時間後，下一個此類錯誤會結束請求。請以純數字提供正整數，例如 `1800000` 代表 30 分鐘。未設定時，等待沒有上限。需要 Claude Code v2.1.295 或更新版本 |

382| `CLAUDE_CODE_SCRIPT_CAPS` | 設定 `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` 時，用於限制特定指令碼在每個工作階段中可被呼叫次數的 JSON 物件。鍵為與命令文字比對的子字串；值為整數呼叫上限。例如，`{"deploy.sh": 2}` 允許 `deploy.sh` 最多被呼叫兩次。比對以子字串為基礎，因此像 `./scripts/deploy.sh $(evil)` 這類 shell 展開技巧仍會計入上限。透過 `xargs` 或 `find -exec` 的執行期擴散不會被偵測到；這是一項縱深防禦控制措施 |387| `CLAUDE_CODE_SAFE_MODE` | 設為 `1` 以安全模式啟動：CLAUDE.md、skill、外掛、hook、MCP 伺服器、自訂命令與 agent、輸出風格、工作流程、自訂佈景主題、自訂快捷鍵、狀態列與檔案建議命令、LSP 伺服器以及自動記憶都不會載入，用於疑難排解損壞的設定。受管設定原則仍然適用，包括原則設定的 hook、狀態列與檔案建議命令；受管外掛、受管 skill、受管 CLAUDE.md 與原則設定的 MCP 伺服器則不會載入。等同於傳遞 [`--safe-mode`](/docs/zh-TW/cli-reference#cli-flags)。直接產生的子程序會繼承此變數 |

383| `CLAUDE_CODE_SCROLL_SPEED` | 設定[全螢幕呈現](/docs/zh-TW/fullscreen#mouse-wheel-scrolling)中的滑鼠滾輪捲動倍數。接受最高 20 的任何正值，包括低於 1 的小數值，例如 `0.5`，可在已放大滾輪事件的終端機中減緩加速的觸控板與滾輪捲動。若您的終端機每一格傳送一個滾輪事件且未放大，設為 `3` 可與 `vim` 一致。在 JetBrains IDE 終端機中會被忽略，因為 Claude Code 在其中使用自己的捲動處理 |388| `CLAUDE_CODE_SCRIPT_CAPS` | JSON 物件，在設定 `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` 時限制特定指令碼在每個工作階段中可被叫用的次數。鍵為與命令文字比對的子字串；值為整數呼叫上限。例如，`{"deploy.sh": 2}` 允許 `deploy.sh` 最多被呼叫兩次。比對以子字串為基礎，因此像 `./scripts/deploy.sh $(evil)` 這類 shell 展開技巧仍會計入上限。透過 `xargs` 或 `find -exec` 的執行時期擴散不會被偵測到；這是一項縱深防禦控制 |

384| `CLAUDE_CODE_SEND_FEEDBACK` | 設為 `0` 可關閉工作階段的 [Claude 草擬的意見回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior)。設為 `1` 可在您的帳戶已有存取權時開啟；此變數本身無法授予存取權，而其他會關閉意見回饋的開關，例如 `DISABLE_FEEDBACK_COMMAND` 與 [`feedbackDrafts`](/docs/zh-TW/settings-reference#feedbackdrafts) 設定的 `off` 值，仍然適用 |389| `CLAUDE_CODE_SCROLL_SPEED` | 設定[全螢幕呈現](/docs/zh-TW/fullscreen#mouse-wheel-scrolling)中的滑鼠滾輪捲動倍數。接受最大為 20 的任何正值，包括低於 1 的小數值，例如 `0.5`，以在已放大滾輪事件的終端機中減慢加速的觸控板與滾輪捲動。若您的終端機每一格只傳送一個滾輪事件且未放大，請設為 `3` 以與 `vim` 一致。在 JetBrains IDE 終端機中會被忽略，Claude Code 在其中使用自己的捲動處理 |

385| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | 覆寫 [SessionEnd](/docs/zh-TW/hooks#sessionend) hook 的時間預算（毫秒）。此值也是每個未設定自身 `timeout` 的 hook 的逾時時間。適用於工作階段結束、`/clear`，以及透過互動式 `/resume` 切換工作階段。預設預算為 1.5 秒，並會自動提高至設定檔中所設定的最高個別 hook `timeout`，最多 60 秒。外掛提供的 hook 的逾時不會提高預算 |390| `CLAUDE_CODE_SEND_FEEDBACK` | 設為 `0` 可為工作階段關閉 [Claude 草擬的意見回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior)。設為 `1` 可在您的帳戶已具備存取權時開啟；此變數本身無法授予存取權，其他關閉意見回饋的開關（例如 `DISABLE_FEEDBACK_COMMAND` 與 [`feedbackDrafts`](/docs/zh-TW/settings-reference#feedbackdrafts) 設定的 `off` 值）仍然適用 |

386| `CLAUDE_CODE_SESSION_ID` | 在 Bash 與 PowerShell 工具子程序、[hook 命令](/docs/zh-TW/hooks)子程序及 stdio [MCP 伺服器](/docs/zh-TW/mcp)子程序中自動設為目前的工作階段 ID。對於 Bash、PowerShell 與 hook，此值與 hook JSON 輸入中的 `session_id` 欄位相符，並會在 `/clear` 時更新。MCP 伺服器子程序會保留其產生時的 ID。使用 `--resume <session-id>` 時，它會收到繼續的 ID，與 hook 和 Bash 一致。使用 `--continue` 或未指定明確 ID 的 `--resume` 時，它可能會改為收到初始啟動時的 ID。可用於將指令碼與外部工具關聯至啟動它們的 Claude Code 工作階段 |391| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | 覆寫 [SessionEnd](/docs/zh-TW/hooks#sessionend) hook 的時間預算（毫秒）。此值也是每個未自行設定 `timeout` 之 hook 的逾時時間。適用於工作階段結束、`/clear`，以及透過互動式 `/resume` 切換工作階段。預設預算為 1.5 秒，會自動提高至設定檔中所設定的最高個別 hook `timeout`，最多 60 秒。外掛提供之 hook 上的逾時不會提高預算 |

387| `CLAUDE_CODE_SHELL` | 設定 Claude Code 用來執行 Bash 工具命令的 shell。接受 `bash` 或 `zsh` 二進位檔的路徑，例如 `/opt/homebrew/bin/bash`。不支援 `fish` 等其他 shell。若值不是可運作的 `bash` 或 `zsh` 路徑，Claude Code 會忽略它並改用自動偵測。自動偵測會在您的 `$SHELL` 指向 `bash` 或 `zsh` 時使用它，否則會選擇在您的 `PATH` 與標準安裝位置中找到的第一個可運作的 `zsh`，其次是 `bash` |392| `CLAUDE_CODE_SESSION_ID` | 在 Bash 與 PowerShell 工具子程序、[hook 命令](/docs/zh-TW/hooks)子程序以及 stdio [MCP 伺服器](/docs/zh-TW/mcp)子程序中自動設為目前的工作階段 ID。對於 Bash、PowerShell 與 hook，此值與 hook JSON 輸入中的 `session_id` 欄位相符，並會在 `/clear` 時更新。MCP 伺服器子程序會保留其產生時的 ID。使用 `--resume <session-id>` 時，它會收到繼續的 ID，與 hook 和 Bash 一致。使用 `--continue` 或未指定明確 ID 的 `--resume` 時，它可能會改為收到初始啟動 ID。用於將指令碼與外部工具關聯至啟動它們的 Claude Code 工作階段 |

388| `CLAUDE_CODE_SHELL_PREFIX` | 包裝 Claude Code 所產生之 shell 命令的命令前綴：Bash 工具呼叫、[hook](/docs/zh-TW/hooks) 命令、[狀態列](/docs/zh-TW/statusline)命令，以及 stdio [MCP 伺服器](/docs/zh-TW/mcp)啟動命令。PowerShell hook 與 exec 形式的 hook 執行時不帶前綴。適用於日誌記錄或稽核。設定單純的可執行檔路徑（例如 `/path/to/logger.sh`）會以 `/path/to/logger.sh '<command>'` 執行每個命令。包裝程式會在 `$1` 中以單一經 shell 引號處理的引數接收命令列，因此包裝程式必須以 shell 重新評估 `$1`，例如 `exec bash -c "$1"`。將 `$1` 當作單純的可執行檔路徑處理，會破壞傳遞 `npx -y <package>` 等引數的 stdio MCP 伺服器。對於 Bash 工具呼叫，`$1` 包含 Claude Code 組合的完整 shell 呼叫，包括環境設定，而不只是 Claude 執行的命令 |393| `CLAUDE_CODE_SHELL` | 設定 Claude Code 用來執行 Bash 工具命令的 shell。接受 `bash` 或 `zsh` 二進位檔的路徑，例如 `/opt/homebrew/bin/bash`。不支援其他 shell，例如 `fish`。若值不是可運作的 `bash` 或 `zsh` 路徑，Claude Code 會忽略它並改用自動偵測。自動偵測會在您的 `$SHELL` 指向 `bash` 或 `zsh` 時使用它，否則會在您的 `PATH` 與標準安裝位置中，先選擇找到的第一個可運作的 `zsh`，其次為 `bash` |

389| `CLAUDE_CODE_SIMPLE` | 設為 `1` 可使用最精簡的系統提示詞執行，且只提供 Bash、檔案讀取與檔案編輯工具。來自 `--mcp-config` 的 MCP 工具仍可使用。停用 hook、skill、自訂命令、subagent、已安裝外掛、MCP 伺服器、自動記憶與 CLAUDE.md 的自動探索。您以 `--add-dir` 傳遞的目錄中的 skill 仍會載入。不會讀取 OAuth token 與 keychain 憑證，因此 Anthropic 身分驗證必須來自 `ANTHROPIC_API_KEY` 或 `--settings` 中的 `apiKeyHelper`。等同於傳遞 [`--bare`](/docs/zh-TW/headless#start-faster-with-bare-mode) |394| `CLAUDE_CODE_SHELL_PREFIX` | 包裝 Claude Code 所產生之 shell 命令的命令前綴：Bash 工具呼叫、[hook](/docs/zh-TW/hooks) 命令、[狀態列](/docs/zh-TW/statusline)命令，以及 stdio [MCP 伺服器](/docs/zh-TW/mcp)啟動命令。PowerShell hook 與 exec 形式的 hook 執行時不會加上前綴。適用於記錄或稽核。設定純執行檔路徑（例如 `/path/to/logger.sh`）會將每個命令以 `/path/to/logger.sh '<command>'` 的形式執行。包裝程式會在 `$1` 中以單一經 shell 引號括住的引數接收命令列，因此包裝程式必須使用 shell 重新評估 `$1`，例如 `exec bash -c "$1"`。將 `$1` 視為純執行檔路徑，會導致傳遞 `npx -y <package>` 等引數的 stdio MCP 伺服器無法運作。對於 Bash 工具呼叫，`$1` 包含 Claude Code 組合的完整 shell 叫用內容，包括環境設定，而不僅是 Claude 執行的命令 |

390| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 在 Claude Code 的完整系統提示詞與工具描述經過縮減的較短系統提示詞之間選擇。未設定時，Haiku 4.5、Sonnet 5、Opus 4.7 及這些系列中的較早模型預設使用完整提示詞，較新的模型則使用較短的提示詞。設為 `1` 可在任何模型上使用較短的提示詞。設為 `0`、`false`、`no` 或 `off` 可在任何模型上使用完整提示詞，即使實驗或伺服器設定原本會選擇較短的提示詞也一樣。兩種提示詞都會保留完整的工具集、hook、MCP 伺服器與 CLAUDE.md 探索 |395| `CLAUDE_CODE_SIMPLE` | 設為 `1` 以最精簡的系統提示詞執行，且僅提供 Bash、檔案讀取與檔案編輯工具。來自 `--mcp-config` 的 MCP 工具仍可使用。停用 hook、skill、自訂命令、subagent、已安裝外掛、MCP 伺服器、自動記憶與 CLAUDE.md 的自動探索。您以 `--add-dir` 傳遞的目錄中的 skill 仍會載入。不會讀取 OAuth token 與鑰匙圈憑證，因此 Anthropic 身分驗證必須來自 `ANTHROPIC_API_KEY` 或 `--settings` 中的 `apiKeyHelper`。等同於傳遞 [`--bare`](/docs/zh-TW/headless#start-faster-with-bare-mode) |

391| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | 略過 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 的用戶端身分驗證，適用於會自行簽署請求的閘道 |396| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 在 Claude Code 的完整系統提示詞與工具描述經過縮減的較短提示詞之間選擇。未設定時，Haiku 4.5、Sonnet 5、Opus 4.7 以及這些系列中的較早模型預設使用完整提示詞，較新的模型則使用較短的提示詞。設為 `1` 可在任何模型上使用較短的提示詞。設為 `0`、`false`、`no` 或 `off` 可在任何模型上使用完整提示詞，即使實驗或伺服器設定原本會選擇較短的提示詞也是如此。兩種提示詞都保留完整的工具集、hook、MCP 伺服器與 CLAUDE.md 探索 |

392| `CLAUDE_CODE_SKIP_AWS_CRED_CACHE` | 設為 `1` 可關閉從 AWS 預設憑證提供者鏈解析出之憑證的程序內快取，讓 Claude Code 在每個 API 請求時都重新解析該鏈。關閉快取時，以 SSO 為基礎的設定檔會在每個請求時向 IAM Identity Center 請求憑證。請參閱[憑證快取與解析逾時](/docs/zh-TW/amazon-bedrock#credential-caching-and-resolution-timeout)。需要 Claude Code v2.1.207 或更新版本 |397| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | 略過 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 的用戶端身分驗證，適用於自行簽署請求的閘道 |

398| `CLAUDE_CODE_SKIP_AWS_CRED_CACHE` | 設為 `1` 可關閉從 AWS 預設憑證提供者鏈解析之憑證的程序內快取，讓 Claude Code 在每個 API 請求時都解析該鏈。關閉快取時，以 SSO 為基礎的設定檔會在每個請求時向 IAM Identity Center 請求憑證。請參閱[憑證快取與解析逾時](/docs/zh-TW/amazon-bedrock#credential-caching-and-resolution-timeout)。需要 Claude Code v2.1.207 或更新版本 |

394| `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS` | 設為 `1` 可將失敗的[快速模式](/docs/zh-TW/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)可用性檢查視為可用，適用於會封鎖該檢查直接傳送至 `api.anthropic.com` 之請求的網路。Claude Code 仍會遵循「disabled by your organization」回應 |400| `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS` | 設為 `1` 可將失敗的[快速模式](/docs/zh-TW/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)可用性檢查視為可用，適用於封鎖該檢查對 `api.anthropic.com` 之直接請求的網路。Claude Code 仍會遵循「disabled by your organization」回應 |

395| `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK` | 設為 `1` 可略過用戶端的[快速模式](/docs/zh-TW/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)可用性檢查，適用於會攔截該檢查請求而非拒絕它的代理伺服器。當您的組織已停用快速模式時，API 仍會拒絕快速模式請求 |401| `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK` | 設為 `1` 可略過用戶端的[快速模式](/docs/zh-TW/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)可用性檢查，適用於攔截而非拒絕該檢查請求的代理伺服器。當您的組織已停用快速模式時，API 仍會拒絕快速模式請求 |

396| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | 略過 Microsoft Foundry 的 Azure 身分驗證，適用於會注入自己 `Authorization` 標頭的代理伺服器或閘道。Claude Code 會在不含 Azure 憑證的情況下傳送請求，並保留您提供的 `Authorization` 標頭，例如透過 `ANTHROPIC_CUSTOM_HEADERS` 提供的標頭。設定 `ANTHROPIC_FOUNDRY_API_KEY` 或 `ANTHROPIC_FOUNDRY_AUTH_TOKEN` 時會被忽略。在 v2.1.203 之前，除非也設定了 API 金鑰，否則此變數會導致 Microsoft Foundry 用戶端無法傳送請求 |402| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | 略過 Microsoft Foundry 的 Azure 身分驗證，適用於注入自己 `Authorization` 標頭的代理伺服器或閘道。Claude Code 會在不附帶 Azure 憑證的情況下傳送請求，並保留您提供的 `Authorization` 標頭，例如透過 `ANTHROPIC_CUSTOM_HEADERS` 提供的標頭。設定 `ANTHROPIC_FOUNDRY_API_KEY` 或 `ANTHROPIC_FOUNDRY_AUTH_TOKEN` 時會被忽略。在 v2.1.203 之前，除非同時設定了 API 金鑰，否則此變數會導致 Microsoft Foundry 用戶端無法傳送請求 |

398| `CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY` | [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 與 [Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai) 上的[啟動模型檢查](/docs/zh-TW/amazon-bedrock#startup-model-checks)會在此機器上記住它們發現您的帳戶無法呼叫的模型，最長一天。設為 `1` 可關閉此記憶。需要 Claude Code v2.1.285 或更新版本 |404| `CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY` | [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 與 [Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai) 上的[啟動模型檢查](/docs/zh-TW/amazon-bedrock#startup-model-checks)會在這台機器上記住它們發現您的帳戶無法叫用的模型，最長一天。設為 `1` 可關閉此記憶。需要 Claude Code v2.1.285 或更新版本 |

399| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 設為 `1` 可略過將提示詞歷史記錄與工作階段逐字稿寫入磁碟。設定此變數後啟動的工作階段不會出現在 `--resume`、`--continue` 或向上鍵歷史記錄中。適用於短暫的指令碼化工作階段 |405| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 設為 `1` 可略過將提示詞歷史與工作階段逐字稿寫入磁碟。設定此變數後啟動的工作階段不會出現在 `--resume`、`--continue` 或向上鍵歷史中。適用於暫時性的指令碼工作階段 |

401| `CLAUDE_CODE_STARTUP_FAILURE_RESULTS` | 設為 `1` 可讓以 `--output-format stream-json` 啟動的工作階段，針對原本只會以 stderr 輸出結束的啟動失敗，寫入一則[說明 Claude Code 拒絕啟動原因的結果訊息](/docs/zh-TW/agent-sdk/typescript#startup_failure_reason)。需要 Claude Code v2.1.274 或更新版本 |407| `CLAUDE_CODE_STARTUP_FAILURE_RESULTS` | 設為 `1` 可讓以 `--output-format stream-json` 啟動的工作階段，針對原本僅以 stderr 結束的啟動失敗，寫入一則[說明 Claude Code 拒絕啟動原因的結果訊息](/docs/zh-TW/agent-sdk/typescript#startup_failure_reason)。需要 Claude Code v2.1.274 或更新版本 |

402| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | [Stop](/docs/zh-TW/hooks#stop) 或 [SubagentStop](/docs/zh-TW/hooks#subagentstop) hook 可連續阻止回合結束的最大次數，超過後 Claude Code 會覆寫它並仍然結束回合（預設：8）。設為 `0` 可停用上限。若您的 hook 確實需要更多次迭代才能解決，請調高此值 |408| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | [Stop](/docs/zh-TW/hooks#stop) 或 [SubagentStop](/docs/zh-TW/hooks#subagentstop) hook 可連續阻止回合結束的最大次數，超過後 Claude Code 會覆寫它並仍然結束回合（預設：8）。設為 `0` 可停用此上限。若您的 hook 確實需要更多次迭代才能完成，請調高此值 |

403| `CLAUDE_CODE_SUBAGENT_MODEL` | 未以其他方式指派模型的 [subagent](/docs/zh-TW/sub-agents#choose-a-model)、[agent team](/docs/zh-TW/agent-teams#specify-teammates-and-models) 隊員與[工作流程](/docs/zh-TW/workflows) agent 的預設模型。接受 `haiku` 等別名或完整模型名稱。有兩個來源優先於此變數：Claude 產生 agent 時傳遞的模型，以及 agent 定義中的 `model` 欄位（包括 `inherit`）。若要改變這一點，請設定 [`CLAUDE_CODE_SUBAGENT_MODEL_FORCE`](/docs/zh-TW/sub-agents#run-every-subagent-on-one-model)。完整順序請參閱[選擇模型](/docs/zh-TW/sub-agents#choose-a-model)。設為 `inherit` 與未設定相同。在 v2.1.251 之前，此變數會同時覆寫每次呼叫的模型與定義中的 `model` 欄位 |409| `CLAUDE_CODE_SUBAGENT_MODEL` | [subagent](/docs/zh-TW/sub-agents#choose-a-model)、[agent team](/docs/zh-TW/agent-teams#specify-teammates-and-models) 隊員與[工作流程](/docs/zh-TW/workflows) agent 在未透過其他方式指派模型時所使用的預設模型。接受別名（例如 `haiku`）或完整模型名稱。有兩個來源優先於它：Claude 產生 agent 時傳遞的模型，以及 agent 定義中的 `model` 欄位，包括 `inherit`。若要改變此行為，請設定 [`CLAUDE_CODE_SUBAGENT_MODEL_FORCE`](/docs/zh-TW/sub-agents#run-every-subagent-on-one-model)。完整順序請參閱[選擇模型](/docs/zh-TW/sub-agents#choose-a-model)。將其設為 `inherit` 與未設定相同。在 v2.1.251 之前，此變數會同時覆寫每次叫用的模型與定義中的 `model` 欄位 |

404| `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` | 設為 `1` 可將單一模型強制套用至 subagent、隊員與工作流程 agent。[讓每個 subagent 都在同一個模型上執行](/docs/zh-TW/sub-agents#run-every-subagent-on-one-model)說明了是哪個模型。需要 Claude Code v2.1.257 或更新版本 |410| `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` | 設為 `1` 可強制 subagent、隊員與工作流程 agent 使用同一個模型。[在同一個模型上執行每個 subagent](/docs/zh-TW/sub-agents#run-every-subagent-on-one-model) 說明了是哪個模型。需要 Claude Code v2.1.257 或更新版本 |

405| `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL` | 設為 `5m` 或 `1h`（Claude Code 僅接受這兩個值），以選擇主對話以外請求的[提示快取 TTL](/docs/zh-TW/prompt-caching#cache-lifetime)，例如 [subagent](/docs/zh-TW/sub-agents)、工作流程與背景工作。優先於 `subagentPromptCacheTtl` 設定與 `ENABLE_PROMPT_CACHING_1H`，而 `FORCE_PROMPT_CACHING_5M` 會覆寫它。API 對 1 小時快取寫入收取較高的費率。需要 Claude Code v2.1.242 或更新版本 |411| `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL` | 設定 `5m` 或 `1h`（Claude Code 僅接受這兩個值），以選擇主對話以外請求（例如 [subagent](/docs/zh-TW/sub-agents)、工作流程與背景工作）的[提示快取 TTL](/docs/zh-TW/prompt-caching#cache-lifetime)。優先於 `subagentPromptCacheTtl` 設定與 `ENABLE_PROMPT_CACHING_1H`，而 `FORCE_PROMPT_CACHING_5M` 會覆寫它。API 對 1 小時快取寫入以較高費率計費。需要 Claude Code v2.1.242 或更新版本 |

406| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | 設為 `1` 可從 Claude Code 啟動的子程序（例如 Bash 命令、hook 與 stdio MCP 伺服器）的環境中移除憑證。清除機制會依變數名稱或其值辨識憑證，並保留 GitHub token 與代理伺服器設定。請參閱[子程序環境清除會移除哪些內容](#what-the-subprocess-environment-scrub-removes)。設定 `allowed_non_write_users` 時，`claude-code-action` 會自動設定此變數 |412| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | 設為 `1` 可從 Claude Code 啟動之子程序（例如 Bash 命令、hook 與 stdio MCP 伺服器）的環境中移除憑證。清除機制會依變數名稱或其值辨識憑證，並保留 GitHub token 與代理伺服器設定。請參閱[子程序環境清除會移除哪些內容](#what-the-subprocess-environment-scrub-removes)。設定 `allowed_non_write_users` 時，`claude-code-action` 會自動設定此變數 |

407| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 在非互動模式（`-p` 旗標）中設為 `1`，可在第一個查詢之前等待外掛安裝完成。若未設定，外掛會在背景安裝，且可能無法在第一個回合使用。可搭配 `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` 限制等待時間 |413| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 在非互動模式（`-p` 旗標）中設為 `1`，以在第一個查詢之前等待外掛安裝完成。若未設定，外掛會在背景安裝，且可能在第一個回合無法使用。可搭配 `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` 來限制等待時間 |

408| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | 同步外掛安裝的逾時時間（毫秒）。超過時，Claude Code 會在沒有外掛的情況下繼續並記錄錯誤。沒有預設值：未設定此變數時，同步安裝會等到完成為止 |414| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | 同步外掛安裝的逾時時間（毫秒）。超過時，Claude Code 會在沒有外掛的情況下繼續並記錄錯誤。沒有預設值：若未設定此變數，同步安裝會等到完成為止 |

409| `CLAUDE_CODE_SYNC_SKILLS` | 在使用 `-p` 旗標的非互動模式中設為 `1`，可讓 Claude Code 在該次執行中下載為您的 claude.ai 帳戶啟用的 skill，並在執行第一個查詢之前等待其清單，最多等待 `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS`。需要 claude.ai 身分驗證。您以 claude.ai 帳戶登入的終端機工作階段不需要此變數即可[同步這些 skill](/docs/zh-TW/skills#where-synced-skills-load)，因此只有在 `-p` 執行需要在第一個查詢就使用您目前的 skill 時才設定 |415| `CLAUDE_CODE_SYNC_SKILLS` | 在使用 `-p` 旗標的非互動模式中設為 `1`，讓 Claude Code 在該次執行中下載您 claude.ai 帳戶已啟用的 skill，並在執行第一個查詢之前等待其清單，最長為 `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS`。需要 claude.ai 身分驗證。以 claude.ai 帳戶登入的終端機工作階段無需此變數即可[同步這些 skill](/docs/zh-TW/skills#where-synced-skills-load)，因此僅在 `-p` 執行需要在第一個查詢中使用您目前的 skill 時才設定 |

410| `CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MS` | 當以 [Agent SDK](/docs/zh-TW/agent-sdk/typescript#query-object) 建構的應用程式重新載入 skill 時，在工作階段中途執行的 skill 重新同步的逾時時間（毫秒）（預設：30000）。超過時，重新載入會以已送達的 skill 繼續，其餘下載則在背景完成 |416| `CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MS` | 當以 [Agent SDK](/docs/zh-TW/agent-sdk/typescript#query-object) 建置的應用程式重新載入 skill 時，在工作階段中途執行之 skill 重新同步的逾時時間（毫秒）（預設：30000）。超過時，重新載入會以已到達的 skill 繼續，其餘下載則在背景完成 |

411| `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` | 設定 `CLAUDE_CODE_SYNC_SKILLS` 時，第一個查詢等待初始 skill 清單的逾時時間（毫秒）（預設：5000）。超過時，第一個查詢會以已送達的 skill 執行。無論如何，下載都會在背景完成，且 Claude 在呼叫某個 skill 時會等待該 skill 下載完成 |417| `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` | 設定 `CLAUDE_CODE_SYNC_SKILLS` 時，第一個查詢等待初始 skill 清單的逾時時間（毫秒）（預設：5000）。超過時，第一個查詢會以已到達的 skill 執行。無論如何，下載都會在背景完成，且 Claude 在叫用某個 skill 時會等待該 skill 下載完成 |

412| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | 設為 `false` 可停用差異輸出中的語法醒目提示。當顏色干擾您的終端機設定時很有用。若也要停用程式碼區塊與檔案預覽中的醒目提示，請使用 [`syntaxHighlightingDisabled`](/docs/zh-TW/settings-reference#syntaxhighlightingdisabled) 設定 |418| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | 設為 `false` 可停用差異輸出中的語法醒目提示。在顏色干擾您的終端機設定時很有用。若也要停用程式碼區塊與檔案預覽中的醒目提示，請使用 [`syntaxHighlightingDisabled`](/docs/zh-TW/settings-reference#syntaxhighlightingdisabled) 設定 |

413| `CLAUDE_CODE_TASK_LIST_ID` | 在工作階段之間共用任務清單。在[具備 Task 工具的工作階段](/docs/zh-TW/tools-reference#task-tool-availability)中，於多個 Claude Code 執行個體中設定相同的 ID，即可在共用任務清單上協作。請參閱[任務清單](/docs/zh-TW/interactive-mode#task-list) |419| `CLAUDE_CODE_TASK_LIST_ID` | 在工作階段之間共用任務清單。在多個 Claude Code 執行個體中設定相同的 ID，以在[具備 Task 工具的工作階段](/docs/zh-TW/tools-reference#task-tool-availability)中協調共用的任務清單。請參閱[任務清單](/docs/zh-TW/interactive-mode#task-list) |

414| `CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MS` | 以毫秒覆寫非互動式工作階段在結束時等待其 [agent team](/docs/zh-TW/agent-teams) 完成拆除的時間。接受 1000 至 60000；超出範圍的值會被忽略並套用預設值 10000。需要 Claude Code v2.1.206 或更新版本 |420| `CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MS` | 以毫秒覆寫非互動式工作階段在結束時等待其 [agent team](/docs/zh-TW/agent-teams) 完成拆除的時間。接受 1000 至 60000；超出範圍的值會被忽略並套用預設值 10000。需要 Claude Code v2.1.206 或更新版本 |

415| `CLAUDE_CODE_TMPDIR` | 覆寫用於內部暫存檔的暫存目錄。Claude Code 在 Unix 上會在此路徑後附加 `/claude-{uid}/`，在 Windows 上則附加 `/claude/`。預設：macOS 上為 `/tmp`，Linux 與 Windows 上為 `os.tmpdir()`。在 macOS 與 Linux 上，當您的覆寫值為較長的路徑時，[沙箱化](/docs/zh-TW/sandboxing)的 Bash 子程序會收到位於系統預設位置下的較短備援 `$TMPDIR`，因為某些工具會在暫存路徑過長時失敗。未沙箱化的 Bash 命令會在您 shell 的 `$TMPDIR` 已設定時繼承它。在原生 Windows 上，當您的 shell 未設定 `$TMPDIR` 時，參照 `$TMPDIR` 的 Bash 命令會收到您的覆寫值，若您未設定覆寫值則收到 `%TEMP%`。Claude Code 自己的暫存檔一律使用您的覆寫值。請在 shell、使用者設定或受管設定中設定。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略 |421| `CLAUDE_CODE_TMPDIR` | 覆寫用於內部暫存檔的暫存目錄。Claude Code 在 Unix 上會於此路徑附加 `/claude-{uid}/`，在 Windows 上附加 `/claude/`。預設：macOS 上為 `/tmp`，Linux 與 Windows 上為 `os.tmpdir()`。在 macOS 與 Linux 上，當您的覆寫值為長路徑時，[沙箱化](/docs/zh-TW/sandboxing)的 Bash 子程序會收到位於系統預設位置下的簡短備援 `$TMPDIR`，因為某些工具在暫存路徑過長時會失敗。未沙箱化的 Bash 命令會在您 shell 的 `$TMPDIR` 已設定時繼承它。在原生 Windows 上，當您的 shell 未設定 `$TMPDIR` 時，參照 `$TMPDIR` 的 Bash 命令會收到您的覆寫值，若您未設定覆寫值則收到 `%TEMP%`。Claude Code 自身的暫存檔一律使用您的覆寫值。請在您的 shell、使用者設定或受管設定中設定。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略 |

416| `CLAUDE_CODE_TMUX_TRUECOLOR` | 設為任何非空值（例如 `1`）可允許在 tmux 中輸出 24 位元真彩色。**設為 `0` 或 `false` 仍會允許真彩色**，這與大多數開關變數不同；請取消設定此變數以恢復 256 色限制。預設情況下，當設定了 `$TMUX` 時，Claude Code 會限制為 256 色，因為除非經過設定，否則 tmux 不會傳遞真彩色跳脫序列。請在將 `set -ga terminal-overrides ',*:Tc'` 加入您的 `~/.tmux.conf` 後設定此變數。其他 tmux 設定請參閱[終端機設定](/docs/zh-TW/terminal-config) |422| `CLAUDE_CODE_TMUX_TRUECOLOR` | 設為任何非空值（例如 `1`）以允許在 tmux 內輸出 24 位元真彩色。**設為 `0` 或 `false` 仍會允許真彩色**，這與大多數開關變數不同；取消設定此變數可恢復 256 色限制。預設情況下，當設定了 `$TMUX` 時，Claude Code 會限制為 256 色，因為除非經過設定，否則 tmux 不會傳遞真彩色跳脫序列。請在將 `set -ga terminal-overrides ',*:Tc'` 加入您的 `~/.tmux.conf` 之後設定此變數。其他 tmux 設定請參閱[終端機設定](/docs/zh-TW/terminal-config) |

417| `CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE` | 在 Linux 與 WSL 上，設為以逗號分隔的程序種類清單，Claude Code 會將這些種類[排除在工具記憶體上限之外](/docs/zh-TW/tools-reference#memory-limit-on-linux-and-wsl)，例如 `mcp` 或 `lsp`。設為 `none` 可限制所有種類，或設為 `all-new` 只限制 Bash、PowerShell 與 Monitor 工具命令。無論您列出什麼，Claude Code 都會讓 Bash、PowerShell 與 Monitor 工具命令受上限限制。需要 Claude Code v2.1.246 或更新版本 |423| `CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE` | 在 Linux 與 WSL 上，設為以逗號分隔的程序類型清單，Claude Code 會將這些類型[排除在工具記憶體上限之外](/docs/zh-TW/tools-reference#memory-limit-on-linux-and-wsl)，例如 `mcp` 或 `lsp`。設為 `none` 可限制所有類型，或設為 `all-new` 僅限制 Bash、PowerShell 與 Monitor 工具命令。無論您列出什麼，Claude Code 都會讓 Bash、PowerShell 與 Monitor 工具命令受上限約束。需要 Claude Code v2.1.246 或更新版本 |

418| `CLAUDE_CODE_TOOL_MEMORY_LIMIT` | 在 Linux 與 WSL 上，設為 `4G` 等大小以[限制 Bash 與 PowerShell 工具命令可使用的記憶體](/docs/zh-TW/tools-reference#memory-limit-on-linux-and-wsl)，在 v2.1.246 或更新版本中也包括 Monitor 工具命令。請以純數字寫入大小，單獨使用代表位元組數，或加上 `K`、`M`、`G` 或 `T` 後綴。設為 `0` 或 `off` 可關閉上限。一旦 Claude Code 啟動的第一個程序已開啟或關閉上限，變更後的值會在您下次啟動 `claude` 時生效。需要 Claude Code v2.1.233 或更新版本 |424| `CLAUDE_CODE_TOOL_MEMORY_LIMIT` | 在 Linux 與 WSL 上，設為 `4G` 等大小，以[限制 Bash 與 PowerShell 工具命令可使用的記憶體](/docs/zh-TW/tools-reference#memory-limit-on-linux-and-wsl)，在 v2.1.246 或更新版本中也包括 Monitor 工具命令。請以純數字寫入大小，單獨使用代表位元組數，或加上 `K`、`M`、`G` 或 `T` 後綴。設為 `0` 或 `off` 可關閉上限。一旦 Claude Code 啟動的第一個程序已開啟或關閉上限，變更後的值會在您下次啟動 `claude` 時生效。需要 Claude Code v2.1.233 或更新版本 |

419| `CLAUDE_CODE_TRANSCRIPT_LOCAL_GC` | 設為 `1` 可限制長時間執行的 `-p` 或 Agent SDK 工作階段的[逐字稿檔案](/docs/zh-TW/sessions#where-transcripts-are-stored)成長的大小。每次壓縮後，一旦檔案大於 5 MB，Claude Code 就會移除該次壓縮之前的歷史記錄。無論檔案是否經過修剪，繼續工作階段時都會還原相同的對話。請在您啟動 Claude Code 的環境中設定，因為設定的 `env` 區塊無法開啟它。需要 Claude Code v2.1.287 或更新版本 |425| `CLAUDE_CODE_TRANSCRIPT_LOCAL_GC` | 設為 `1` 可限制長時間 `-p` 或 Agent SDK 工作階段的[逐字稿檔案](/docs/zh-TW/sessions#where-transcripts-are-stored)成長的大小。每次壓縮後，當檔案大於 5 MB 時，Claude Code 會移除該次壓縮之前的歷史記錄。無論檔案是否經過修剪，繼續工作階段都會還原相同的對話。請在您啟動 Claude Code 的環境中設定，因為設定的 `env` 區塊無法開啟此功能。需要 Claude Code v2.1.287 或更新版本 |

420| `CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS` | Claude Code 取消其轉送至遠端用戶端（例如 [Remote Control](/docs/zh-TW/remote-control) 或 SDK 主機）的對話框，或[被擱置的跨工作階段訊息](/docs/zh-TW/cross-session-messaging#control-inbound-messages)之核准對話框之前的期限（毫秒）；權限提示與 `AskUserQuestion` 問題使用各自的流程，不受此變數規範。在 Claude Code v2.1.236 或更新版本中，它也會限制可能在無人值守情況下執行之工作階段中，於工作階段中途出現的 [Fable 用量點數同意提示](/docs/zh-TW/model-config#fable-and-usage-credits)。[控制傳入訊息](/docs/zh-TW/cross-session-messaging#control-inbound-messages)與[非互動式工作階段](/docs/zh-TW/cross-session-messaging#non-interactive-sessions)涵蓋完整的擱置訊息過期規則，包括期限不適用的情況。覆寫 [`dialogExpiry`](/docs/zh-TW/settings-reference#dialogexpiry) 設定。`0` 或負值會停用期限。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略 |426| `CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS` | Claude Code 取消轉送至遠端用戶端（例如 [Remote Control](/docs/zh-TW/remote-control) 或 SDK 主機）的對話框，或[被暫留的跨工作階段訊息](/docs/zh-TW/cross-session-messaging#control-inbound-messages)之核准對話框前的期限（毫秒）；權限提示與 `AskUserQuestion` 問題使用各自的流程，不受此變數控制。在 Claude Code v2.1.236 或更新版本中，它也會限制可能在無人看管狀態下執行的工作階段中，於工作階段中途出現的 [Fable 用量點數同意提示](/docs/zh-TW/model-config#fable-and-usage-credits)。[控制傳入訊息](/docs/zh-TW/cross-session-messaging#control-inbound-messages)與[非互動工作階段](/docs/zh-TW/cross-session-messaging#non-interactive-sessions)涵蓋完整的暫留訊息到期規則，包括期限不適用的情況。覆寫 [`dialogExpiry`](/docs/zh-TW/settings-reference#dialogexpiry) 設定。`0` 或負值會停用期限。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略 |

425| `CLAUDE_CODE_USE_NATIVE_FILE_SEARCH` | 設為 `1` 以使用 Node.js 檔案 API 而非 ripgrep 來探索自訂命令、subagent 和輸出風格。若內建的 ripgrep 二進位檔在您的環境中無法使用或遭到封鎖，請設定此變數。不影響 Grep 或檔案搜尋工具 |431| `CLAUDE_CODE_USE_NATIVE_FILE_SEARCH` | 設定為 `1` 以使用 Node.js 檔案 API 而非 ripgrep 來探索自訂命令、subagent 與輸出風格。若內建的 ripgrep 二進位檔在您的環境中無法使用或遭封鎖，請設定此變數。不會影響 Grep 或檔案搜尋工具 |

426| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | 控制 PowerShell 工具。在未安裝 Git Bash 的 Windows 上，此工具會自動啟用；設為 `0` 可停用。在已安裝 Git Bash 的 Windows 上，claude.ai 和 Console 帳戶預設開啟此工具；設為 `1` 可在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 工作階段中啟用，或設為 `0` 將其關閉。在 Linux、macOS 和 WSL 上，設為 `1` 可啟用，這需要 `pwsh` 位於您的 `PATH` 中。在 Windows 上啟用時，Claude 可以原生執行 PowerShell 命令，而不必透過 Git Bash 轉送。請參閱 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool) |432| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | 控制 PowerShell 工具。在未安裝 Git Bash 的 Windows 上，此工具會自動啟用；設定為 `0` 可停用。在已安裝 Git Bash 的 Windows 上，claude.ai 與 Console 帳戶預設會開啟此工具；設定為 `1` 可在 Amazon Bedrock、Google Cloud's Agent Platform 與 Microsoft Foundry 工作階段中啟用，或設定為 `0` 將其關閉。在 Linux、macOS 與 WSL 上，設定為 `1` 可啟用，這需要 `PATH` 中有 `pwsh`。在 Windows 上啟用時，Claude 可以原生執行 PowerShell 命令，而不必透過 Git Bash 轉送。請參閱 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool) |

428| `CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS` | 設為 [WebFetch](/docs/zh-TW/tools-reference#webfetch-tool-behavior) 將每個擷取之 URL 的回應保留在快取中的毫秒數。預設值為 `900000`，即 15 分鐘。僅接受純數字；`0`、小數或任何其他寫法都會保留預設值。Claude Code 每次啟動時只讀取此值一次，因此在設定的 `env` 區塊中所做的變更，會在您下次啟動 `claude` 時生效。需要 Claude Code v2.1.233 或更新版本 |434| `CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS` | 設定 [WebFetch](/docs/zh-TW/tools-reference#webfetch-tool-behavior) 將每個已擷取 URL 的回應保留在快取中的毫秒數。預設值為 `900000`，即 15 分鐘。僅接受純數字；`0`、小數或任何其他寫法都會保留預設值。Claude Code 每次啟動時只讀取一次此值，因此在設定的 `env` 區塊中所做的變更會在您下次啟動 `claude` 時生效。需要 Claude Code v2.1.233 或更新版本 |

429| `CLAUDE_CODE_WEBFETCH_DEADLINE_MS` | [WebFetch](/docs/zh-TW/tools-reference#webfetch-tool-behavior) 等待頁面下載的時間上限（毫秒），包括其所遵循的任何重新導向。屆時仍未完成的下載會以截止時間錯誤失敗。預設值為 `300000`，即五分鐘。設為 `0` 可移除限制。僅接受純數字；小數或任何其他寫法都會保留預設值。需要 Claude Code v2.1.268 或更新版本 |435| `CLAUDE_CODE_WEBFETCH_DEADLINE_MS` | [WebFetch](/docs/zh-TW/tools-reference#webfetch-tool-behavior) 等待頁面下載完成（包括其所跟隨的任何重新導向）的時間上限（毫秒）。屆時仍未完成的下載會以期限錯誤失敗。預設值為 `300000`，即五分鐘。設定為 `0` 可移除限制。僅接受純數字；小數或任何其他寫法都會保留預設值。需要 Claude Code v2.1.268 或更新版本 |

430| `CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR` | 工作階段的 [WebSearch 限制](/docs/zh-TW/tools-reference#session-search-limit)補充的速率，以每小時呼叫次數計。在互動式終端機工作階段中，預設值為 `100`。在[非互動](/docs/zh-TW/headless)工作階段中，預設值為 `0`，即關閉補充。僅接受純數字；任何其他寫法都會視為未設定。需要 Claude Code v2.1.290 或更新版本 |436| `CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR` | 工作階段的 [WebSearch 上限](/docs/zh-TW/tools-reference#session-search-limit)的補充速率，單位為每小時呼叫次數。在互動式終端機工作階段中預設值為 `100`。在[非互動](/docs/zh-TW/headless)工作階段中預設值為 `0`，即關閉補充。僅接受純數字；任何其他寫法都視為未設定。需要 Claude Code v2.1.290 或更新版本 |

431| `CLAUDE_CODE_WORKER_CHECKIN_SCHEDULE` | 當 `CLAUDE_AUTO_BACKGROUND_TASKS` 設為 `1` 時，Claude Code 在每次提醒 Claude 檢查仍在執行中的[背景 subagent](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background) 之前所等待的時間。接受一個或多個以逗號分隔的等待時間，以整數秒表示，範圍從 `1` 到 `86400`，例如 `600` 或 `600,1800,3600`。每個值是下一次提醒前的等待時間，最後一個值會重複使用。僅接受純數字；任何其他值或寫法都會視為未設定。未設定時不會有任何提醒。需要 Claude Code v2.1.283 或更新版本 |437| `CLAUDE_CODE_WORKER_CHECKIN_SCHEDULE` | 當 `CLAUDE_AUTO_BACKGROUND_TASKS` 設定為 `1` 時，Claude Code 在每次提醒 Claude 檢查仍在執行中的[背景 subagent](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)之前等待的時間。接受一個或多個以逗號分隔、以整數秒表示且介於 `1` 到 `86400` 之間的等待時間，例如 `600` 或 `600,1800,3600`。每個值都是下一次提醒前的等待時間，最後一個值會重複使用。僅接受純數字；任何其他值或寫法都視為未設定。未設定時不會有提醒。需要 Claude Code v2.1.283 或更新版本 |

432| `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` | 單次[工作流程](/docs/zh-TW/workflows)執行同時執行的 agent 數量，範圍從 `1` 到 `256`。預設情況下，一次執行最多同時執行 16 個 agent，當 Claude Code 可用的 CPU 較少時則更少；排入佇列的 `agent()` 呼叫會等待空閒的位置。每個執行中 agent 的逐字稿都會保留在 Claude Code 的記憶體中，因此較高的值會增加記憶體用量。僅接受純數字；超出範圍的值和其他寫法都會保留預設值。需要 Claude Code v2.1.269 或更新版本 |438| `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` | 單次[工作流程](/docs/zh-TW/workflows)執行同時執行的 agent 數量，範圍為 `1` 到 `256`。預設情況下，一次執行最多同時執行 16 個 agent，當 Claude Code 可用的 CPU 較少時會更少；排入佇列的 `agent()` 呼叫會等待空閒的位置。每個執行中 agent 的逐字稿都會保留在 Claude Code 的記憶體中，因此較高的值會增加記憶體使用量。僅接受純數字；超出範圍的值與其他寫法會保留預設值。需要 Claude Code v2.1.269 或更新版本 |

433| `CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS` | [工作流程](/docs/zh-TW/workflows) agent 在傳送自己的第一個請求之前，等待具有相同前綴之同層 agent 的第一個回應開始的時間上限（毫秒）。當扇出啟動數個共用[提示快取前綴](/docs/zh-TW/workflows#prompt-caching-in-a-fan-out)的 agent 時，Claude Code 會讓第一個以外的所有 agent 最多等待這麼久，讓其餘 agent 讀取已快取的前綴，而不是各自在未快取的情況下處理它。預設值為 `5000`。設為 `0` 可停用等待。設定 `DISABLE_PROMPT_CACHING` 時，agent 永遠不會等待。需要 Claude Code v2.1.229 或更新版本 |439| `CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS` | [工作流程](/docs/zh-TW/workflows) agent 在送出自己的第一個請求之前，等待具有相同前綴的同層 agent 開始第一個回應的時間上限（毫秒）。當扇出啟動多個共用[提示快取前綴](/docs/zh-TW/workflows#prompt-caching-in-a-fan-out)的 agent 時，Claude Code 會將第一個以外的所有 agent 暫停最多這段時間，讓其餘 agent 讀取已快取的前綴，而不是各自在未快取的情況下處理。預設值為 `5000`。設定為 `0` 可停用等待。設定 `DISABLE_PROMPT_CACHING` 時，agent 永遠不會等待。需要 Claude Code v2.1.229 或更新版本 |

434| `CLAUDE_CONFIG_DIR` | 覆寫設定目錄（預設值：`~/.claude`）。所有設定、工作階段歷史記錄和外掛都儲存在此路徑下。關於憑證，請參閱 [Claude Code 儲存憑證的位置](/docs/zh-TW/authentication#credential-management)。適合並行執行多個帳戶：例如 `alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'`。請在您的 shell、使用者設定或受管設定中設定。在設定檔中，請寫入[絕對路徑](#in-settings-files)。在[專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略 |440| `CLAUDE_CONFIG_DIR` | 覆寫設定目錄（預設：`~/.claude`）。所有設定、工作階段歷史記錄與外掛都儲存在此路徑下。關於憑證，請參閱 [Claude Code 儲存憑證的位置](/docs/zh-TW/authentication#credential-management)。適用於並行執行多個帳戶：例如 `alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'`。請在您的 shell、使用者設定或受管設定中設定。在設定檔中，請寫入[絕對路徑](#in-settings-files)。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略 |

435| `CLAUDE_DISABLE_ADOPT` | 設為 `1` 可在您按下 `←` 或使用 [`/background`](/docs/zh-TW/agent-view#from-inside-a-session) 將工作階段轉至背景時，停止進行中的背景工作，而不是將其延續。Claude Code 會在轉至背景前要求您確認，然後停止原本會延續的任務。需要 Claude Code v2.1.195 或更新版本 |441| `CLAUDE_DISABLE_ADOPT` | 設定為 `1`，在您按下 `←` 或使用 [`/background`](/docs/zh-TW/agent-view#from-inside-a-session) 將工作階段移至背景時，停止進行中的背景工作，而不是將其延續。Claude Code 會在移至背景前要求您確認，然後停止原本會延續的任務。需要 Claude Code v2.1.195 或更新版本 |

436| `CLAUDE_EFFORT` | 在 Bash 工具子程序和 hook 命令中，自動設定為子程序啟動時生效的 [effort 等級](/docs/zh-TW/model-config#adjust-effort-level)：`low`、`medium`、`high`、`xhigh` 或 `max`。與傳遞給 [hook](/docs/zh-TW/hooks) 的 `effort.level` 欄位相符。僅在目前模型支援 effort 參數時設定 |442| `CLAUDE_EFFORT` | 在 Bash 工具子程序與 hook 命令中自動設定為子程序啟動時生效的 [effort 等級](/docs/zh-TW/model-config#adjust-effort-level)：`low`、`medium`、`high`、`xhigh` 或 `max`。與傳遞給 [hook](/docs/zh-TW/hooks) 的 `effort.level` 欄位相符。僅在目前模型支援 effort 參數時設定 |

437| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 設為 `1` 可強制啟用位元組層級的串流閒置監控程式，或設為 `0` 強制停用。`0` 也會在執行[首位元組截止時間](/docs/zh-TW/network-config#streaming-idle-watchdogs)的連線上關閉該截止時間。未設定時，監控程式預設會在直接 Anthropic API 和 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 連線上啟用，也會對透過 `ANTHROPIC_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 連線之[閘道](/docs/zh-TW/gateways)連線上的串流回應啟用；在 v2.1.222 之前，它不會在這些閘道連線上執行，因此即使保持連線的 ping 持續抵達，事件層級的監控程式仍可能在該處回報停滯。關於逾時以及各計時器如何互動，請參閱[串流閒置監控程式](/docs/zh-TW/network-config#streaming-idle-watchdogs) |443| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 設定為 `1` 可強制啟用位元組層級串流閒置監視器，設定為 `0` 可強制停用。`0` 也會在執行[首位元組期限](/docs/zh-TW/network-config#streaming-idle-watchdogs)的連線上關閉該期限。未設定時，此監視器預設會針對直接 Anthropic API 與 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 連線，以及透過 `ANTHROPIC_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 連到的[閘道](/docs/zh-TW/gateways)連線上的串流回應啟用；在 v2.1.222 之前，它不會在這些閘道連線上執行，因此即使 keep-alive ping 持續抵達，事件層級監視器仍可能在那裡回報停滯。關於逾時以及各計時器如何交互作用，請參閱[串流閒置監視器](/docs/zh-TW/network-config#streaming-idle-watchdogs) |

438| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | 設為 `1` 可在 Amazon Bedrock `vnd.amazon.eventstream` 回應上啟用位元組層級的串流閒置監控程式，這也會在 Bedrock 串流請求上啟用[首位元組截止時間](/docs/zh-TW/network-config#streaming-idle-watchdogs)。預設關閉。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 設定逾時 |444| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | 設定為 `1` 可在 Amazon Bedrock `vnd.amazon.eventstream` 回應上啟用位元組層級串流閒置監視器，這也會在 Bedrock 串流請求上啟用[首位元組期限](/docs/zh-TW/network-config#streaming-idle-watchdogs)。預設為關閉。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 設定逾時 |

439| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 設為 `0` 可強制停用事件層級的串流閒置監控程式，或設為 `1` 強制啟用。未設定時，監控程式預設對所有提供者開啟。在 v2.1.196 之前，未設定時的預設值在直接 Anthropic API 上由伺服器控制，在其他提供者上則為關閉。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 設定逾時；關於與此監控程式並行運作的其他停滯計時器，請參閱[串流閒置監控程式](/docs/zh-TW/network-config#streaming-idle-watchdogs) |445| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 設定為 `0` 可強制停用事件層級串流閒置監視器，設定為 `1` 可強制啟用。未設定時，此監視器預設對所有提供者開啟。在 v2.1.196 之前，未設定時的預設值在直接 Anthropic API 上由伺服器控制，在其他提供者上則為關閉。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 設定逾時；關於與此監視器一同執行的其他停滯計時器，請參閱[串流閒置監視器](/docs/zh-TW/network-config#streaming-idle-watchdogs) |

440| `CLAUDE_ENV_FILE` | shell 指令碼的路徑，Claude Code 會在每個 Bash 命令之前，於同一個 shell 程序中執行其內容，因此檔案中的 export 對該命令可見。用於在各命令之間保留 virtualenv 或 conda 的啟用狀態。也會由 [SessionStart](/docs/zh-TW/hooks#persist-environment-variables)、[Setup](/docs/zh-TW/hooks#setup)、[CwdChanged](/docs/zh-TW/hooks#cwdchanged) 和 [FileChanged](/docs/zh-TW/hooks#filechanged) hook 動態填入 |446| `CLAUDE_ENV_FILE` | shell 指令碼的路徑，Claude Code 會在同一個 shell 程序中於每個 Bash 命令之前執行其內容，因此檔案中的 export 對該命令可見。可用於在命令之間保留 virtualenv 或 conda 的啟用狀態。也會由 [SessionStart](/docs/zh-TW/hooks#persist-environment-variables)、[Setup](/docs/zh-TW/hooks#setup)、[CwdChanged](/docs/zh-TW/hooks#cwdchanged) 與 [FileChanged](/docs/zh-TW/hooks#filechanged) hook 動態填入 |

441| `CLAUDE_JOB_DIR` | 由 Claude Code 在每個[背景工作階段](/docs/zh-TW/agent-view)中設定為該工作階段的 `~/.claude/jobs/<id>` 目錄。該工作階段執行的 shell 命令會繼承它。請將暫存檔案寫入 [`$CLAUDE_JOB_DIR/tmp`](/docs/zh-TW/agent-view#where-state-is-stored)。Claude 在該處的 `Write` 和 `Edit` 呼叫不會提示要求權限，且刪除工作階段時會移除該目錄 |447| `CLAUDE_JOB_DIR` | 由 Claude Code 在每個[背景工作階段](/docs/zh-TW/agent-view)中設定為該工作階段的 `~/.claude/jobs/<id>` 目錄。工作階段執行的 shell 命令會繼承此變數。請將暫存檔寫入 [`$CLAUDE_JOB_DIR/tmp`](/docs/zh-TW/agent-view#where-state-is-stored)。Claude 在該處的 `Write` 與 `Edit` 呼叫不會要求權限，且該目錄會在工作階段刪除時移除 |

442| `CLAUDE_PID` | Claude Code 會在其產生的子程序中將此變數設為自己的程序 ID：包括 Bash 和 PowerShell 工具命令以及 hook 命令。在 Linux 上，Bash 工具的 shell 整合會用它來拒絕會比對到 Claude Code 程序本身的 `pkill` 模式；請參閱[錯誤參考](/docs/zh-TW/errors#pkill-pattern-matches-the-claude-code-process)。可在您自己的指令碼中讀取它，以刻意識別父 Claude Code 程序或對其傳送訊號。需要 Claude Code v2.1.214 或更新版本 |448| `CLAUDE_PID` | Claude Code 會在其產生的子程序（Bash 與 PowerShell 工具命令以及 hook 命令）中將此變數設定為自己的程序 ID。在 Linux 上，Bash 工具的 shell 整合會使用它來拒絕會符合 Claude Code 程序本身的 `pkill` 模式；請參閱[錯誤參考](/docs/zh-TW/errors#pkill-pattern-matches-the-claude-code-process)。可從您自己的指令碼中讀取它，以刻意識別上層 Claude Code 程序或向其傳送訊號。需要 Claude Code v2.1.214 或更新版本 |

443| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | 未提供明確名稱時，自動產生之 [Remote Control](/docs/zh-TW/remote-control) 工作階段名稱的前綴。預設為您電腦的主機名稱，產生如 `myhost-graceful-unicorn` 的名稱。`--remote-control-session-name-prefix` CLI 旗標可為單次呼叫設定相同的值 |449| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | 未提供明確名稱時，自動產生的 [Remote Control](/docs/zh-TW/remote-control) 工作階段名稱的前綴。預設為您電腦的主機名稱，產生如 `myhost-graceful-unicorn` 的名稱。`--remote-control-session-name-prefix` CLI 旗標會針對單次呼叫設定相同的值 |

444| `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` | 在執行[首位元組截止時間](/docs/zh-TW/network-config#streaming-idle-watchdogs)的連線上，串流請求第一個回應位元組的截止時間（毫秒）。關於 Claude Code 如何限制此值、為大型請求本文增加的額外時間，以及您未設定此值時如何選擇截止時間，請參閱 [No response from API](/docs/zh-TW/errors#no-response-from-api)。需要 Claude Code v2.1.242 或更新版本 |450| `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` | 在執行[首位元組期限](/docs/zh-TW/network-config#streaming-idle-watchdogs)的連線上，串流請求第一個回應位元組的期限（毫秒）。關於 Claude Code 如何限制此值、為大型請求本文額外增加的時間，以及在您未設定此變數時如何選擇期限，請參閱 [No response from API](/docs/zh-TW/errors#no-response-from-api)。需要 Claude Code v2.1.242 或更新版本 |

445| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 事件層級和位元組層級的串流閒置監控程式關閉停滯連線之前的逾時（毫秒）。當您明確設定此變數時，最小值為 `300000`（5 分鐘）；較低的值會被自動限制，以容納延伸思考的暫停和代理伺服器緩衝，且位元組層級的監控程式會將此值上限設為 30 分鐘。對於位元組層級的監控程式，`CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` 優先於此變數。關於各監控程式未設定時的預設值，請參閱[串流閒置監控程式](/docs/zh-TW/network-config#streaming-idle-watchdogs) |451| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 事件層級與位元組層級串流閒置監視器關閉停滯連線前的逾時（毫秒）。當您明確設定此變數時，最小值為 `300000`（5 分鐘）；較低的值會被自動調整，以容納延伸思考的暫停與代理伺服器緩衝，而位元組層級監視器會將此值上限設為 30 分鐘。對於位元組層級監視器，`CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` 優先於此變數。關於各監視器未設定時的預設值，請參閱[串流閒置監視器](/docs/zh-TW/network-config#streaming-idle-watchdogs) |

446| `CLAUDE_SUBAGENT_BG_SHELL_MAX_MS` | 已在 v2.1.260 中移除，現在不起任何作用。先前用於限制由 [subagent](/docs/zh-TW/sub-agents) 啟動的[背景 shell 命令](/docs/zh-TW/interactive-mode#background-bash-commands)可執行的時間（毫秒），預設為 60 分鐘。請參閱[背景命令存留期規則](/docs/zh-TW/tools-reference#background-commands) |452| `CLAUDE_SUBAGENT_BG_SHELL_MAX_MS` | 已在 v2.1.260 中移除，現在不再有任何作用。先前用於限制 [subagent](/docs/zh-TW/sub-agents) 啟動的[背景 shell 命令](/docs/zh-TW/interactive-mode#background-bash-commands)可執行的時間（毫秒），預設為 60 分鐘。請參閱[背景命令存續期規則](/docs/zh-TW/tools-reference#background-commands) |

447| `DEBUG` | 設為 `1` 可啟用偵錯模式，等同於使用 [`--debug`](/docs/zh-TW/cli-reference#cli-flags) 啟動。偵錯日誌會寫入 `~/.claude/debug/<session-id>.txt`，或寫入 `CLAUDE_CODE_DEBUG_LOGS_DIR` 設定的路徑。只有真值 `1`、`true`、`yes` 和 `on` 會啟用偵錯模式，因此為其他工具設定的命名空間模式（例如 `DEBUG=express:*`）不會觸發它 |453| `DEBUG` | 設定為 `1` 可啟用偵錯模式，等同於以 [`--debug`](/docs/zh-TW/cli-reference#cli-flags) 啟動。偵錯日誌會寫入 `~/.claude/debug/<session-id>.txt`，或寫入 `CLAUDE_CODE_DEBUG_LOGS_DIR` 所設定的路徑。只有真值 `1`、`true`、`yes` 與 `on` 會啟用偵錯模式，因此為其他工具設定的命名空間模式（例如 `DEBUG=express:*`）不會觸發它 |

449| `DISABLE_AUTO_COMPACT` | 設為 `1` 可在接近上下文限制時停用自動壓縮。手動 `/compact` 命令仍可使用。當您想要明確控制壓縮發生的時機時使用。覆寫 [`autoCompactEnabled`](/docs/zh-TW/settings-reference#autocompactenabled) 設定 |455| `DISABLE_AUTO_COMPACT` | 設定為 `1` 可在接近上下文限制時停用自動壓縮。手動 `/compact` 命令仍可使用。當您想明確控制壓縮發生的時機時使用。覆寫 [`autoCompactEnabled`](/docs/zh-TW/settings-reference#autocompactenabled) 設定 |

452| `DISABLE_DOCTOR_COMMAND` | 設為 `1` 可隱藏 [`/doctor`](/docs/zh-TW/commands#all-commands) 設定檢查 skill 及其 `/checkup` 別名。適用於使用者不應在工作階段中執行設定診斷的受管部署。不影響 `claude doctor` 終端機命令。在 v2.1.205 之前，此變數會隱藏 `/doctor` 診斷畫面命令 |458| `DISABLE_DOCTOR_COMMAND` | 設定為 `1` 可隱藏 [`/doctor`](/docs/zh-TW/commands#all-commands) 設定檢查 skill 及其 `/checkup` 別名。適用於使用者不應在工作階段中執行設定診斷的受管部署。不會影響 `claude doctor` 終端機命令。在 v2.1.205 之前，此變數會隱藏 `/doctor` 診斷畫面命令 |

455| `DISABLE_FEEDBACK_COMMAND` | 設為 `1` 可停用 `/feedback` 命令和 [Claude 草擬的意見回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior)。也會停用透過相同路徑回報的 `/bug` 和 `/share`；在 v2.1.212 之前，它們是 `/feedback` 的別名，因此該命令在所有名稱下皆會被停用。也接受較舊的名稱 `DISABLE_BUG_COMMAND` |461| `DISABLE_FEEDBACK_COMMAND` | 設定為 `1` 可停用 `/feedback` 命令與 [Claude 草擬的意見回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior)。也會停用透過相同路徑回報的 `/bug` 與 `/share`；在 v2.1.212 之前，它們是 `/feedback` 的別名，因此該命令的每個名稱都會被停用。也接受較舊的名稱 `DISABLE_BUG_COMMAND` |

456| `DISABLE_GROWTHBOOK` | 設為 `1` 或 `true` 可停用 GrowthBook 功能旗標擷取，並對每個旗標使用程式碼中的預設值。這會使 [Remote Control](/docs/zh-TW/remote-control#requirements) 和其他[需要功能旗標擷取的功能](#features-that-need-feature-flag-fetching)無法使用。設為 `0` 或 `false` 會保持擷取開啟。除非也設定了 `DISABLE_TELEMETRY`，否則遙測事件記錄會保持開啟 |462| `DISABLE_GROWTHBOOK` | 設定為 `1` 或 `true` 可停用 GrowthBook 功能旗標擷取，並對每個旗標使用程式碼預設值。這會使 [Remote Control](/docs/zh-TW/remote-control#requirements) 及其他[需要功能旗標擷取的功能](#features-that-need-feature-flag-fetching)無法使用。設定為 `0` 或 `false` 會保持擷取開啟。除非同時設定 `DISABLE_TELEMETRY`，否則遙測事件記錄會保持開啟 |

458| `DISABLE_INSTALL_GITHUB_APP_COMMAND` | 設為 `1` 可隱藏 `/install-github-app` 命令。使用第三方提供者（Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry）時已預先隱藏 |464| `DISABLE_INSTALL_GITHUB_APP_COMMAND` | 設定為 `1` 可隱藏 `/install-github-app` 命令。使用第三方提供者（Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry）時已經隱藏 |

459| `DISABLE_INTERLEAVED_THINKING` | 設為 `1` 可避免傳送 interleaved-thinking beta 標頭。當您的 LLM 閘道或提供者不支援[交錯思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking)時很有用 |465| `DISABLE_INTERLEAVED_THINKING` | 設定為 `1` 可避免傳送 interleaved-thinking beta 標頭。當您的 LLM 閘道或提供者不支援[交錯思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking)時很有用 |

464| `DISABLE_PROMPT_CACHING_HAIKU` | 設為 `1` 可對[預設 Haiku 模型](/docs/zh-TW/prompt-caching#disable-prompt-caching)停用提示快取，無論其在何處執行 |470| `DISABLE_PROMPT_CACHING_HAIKU` | 設定為 `1` 可為[預設 Haiku 模型](/docs/zh-TW/prompt-caching#disable-prompt-caching)停用提示快取，無論其在何處執行 |

467| `DISABLE_TELEMETRY` | 設為任何非空值（例如 `1`）可選擇退出遙測。**設為 `0` 或 `false` 仍會選擇退出**，這與大多數開關變數不同；取消設定該變數即可重新開啟遙測。遙測事件不包含程式碼、檔案路徑或 Bash 命令等使用者資料。也會停用[功能旗標擷取](#features-that-need-feature-flag-fetching)。請參閱[為您的組織關閉遙測](/docs/zh-TW/managed-settings#turn-telemetry-off-for-your-organization) |473| `DISABLE_TELEMETRY` | 設定為任何非空值（例如 `1`）可選擇退出遙測。**與大多數開關變數不同，設定為 `0` 或 `false` 仍會選擇退出**；取消設定此變數即可重新開啟遙測。遙測事件不包含程式碼、檔案路徑或 Bash 命令等使用者資料。也會停用[功能旗標擷取](#features-that-need-feature-flag-fetching)。請參閱[為您的組織關閉遙測](/docs/zh-TW/managed-settings#turn-telemetry-off-for-your-organization) |

468| `DISABLE_UPDATES` | 設為 `1` 可封鎖所有更新，包括手動 `claude update` 和 `claude install`。比 `DISABLE_AUTOUPDATER` 更嚴格。當您透過自己的通道發佈 Claude Code 且使用者不應自行更新時使用 |474| `DISABLE_UPDATES` | 設定為 `1` 可封鎖所有更新，包括手動執行的 `claude update` 與 `claude install`。比 `DISABLE_AUTOUPDATER` 更嚴格。當您透過自己的管道發佈 Claude Code 且使用者不應自行更新時使用 |

470| `DO_NOT_TRACK` | 設為 `1` 可選擇退出遙測，效果與 `DISABLE_TELEMETRY` 相同，包括對[功能旗標擷取](#features-that-need-feature-flag-fetching)的影響。Claude Code 將此變數讀取為標準布林值，因此 `0` 會保持遙測開啟，並將其視為許多開發者 CLI 所認可的跨工具慣例予以遵循 |476| `DO_NOT_TRACK` | 設定為 `1` 可選擇退出遙測，效果與 `DISABLE_TELEMETRY` 相同，包括對[功能旗標擷取](#features-that-need-feature-flag-fetching)的影響。Claude Code 將此變數讀取為標準布林值，因此 `0` 會保持遙測開啟，並將其視為許多開發者 CLI 所認可的跨工具慣例加以遵循 |

471| `ENABLE_BETA_TRACING_DETAILED` | 設為 `1`，並將 `BETA_TRACING_ENDPOINT` 設為您的 OTLP/HTTP 收集器端點，即可開啟[詳細 beta 追蹤](/docs/zh-TW/monitoring-usage#traces-beta)，這會新增包含內容的 span 屬性和 `claude_code.hook` span。互動式 CLI 工作階段還需要您的組織已列入該 beta 的允許清單。這兩個變數在[專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中都會被忽略 |477| `ENABLE_BETA_TRACING_DETAILED` | 設定為 `1`，並將 `BETA_TRACING_ENDPOINT` 設定為您的 OTLP/HTTP 收集器端點，即可開啟[詳細 beta 追蹤](/docs/zh-TW/monitoring-usage#traces-beta)，這會新增帶有內容的 span 屬性以及 `claude_code.hook` span。互動式 CLI 工作階段還需要您的組織已列入此 beta 的允許清單。兩個變數在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中都會被忽略 |

472| `ENABLE_CLAUDEAI_MCP_SERVERS` | 設為 `false` 可阻止 Claude Code 擷取 [claude.ai MCP 伺服器](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai)。已登入的使用者預設啟用。若要針對個別專案或個別組織停用，請改為在設定中設定 [`disableClaudeAiConnectors`](/docs/zh-TW/settings-reference#disableclaudeaiconnectors) |478| `ENABLE_CLAUDEAI_MCP_SERVERS` | 設定為 `false` 可讓 Claude Code 停止擷取 [claude.ai MCP 伺服器](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai)。對已登入的使用者預設為啟用。若要針對個別專案或組織停用，請改在設定中設定 [`disableClaudeAiConnectors`](/docs/zh-TW/settings-reference#disableclaudeaiconnectors) |

473| `ENABLE_PROMPT_CACHING_1H` | 設為 `1` 可請求 1 小時的[提示快取 TTL](/docs/zh-TW/prompt-caching#cache-lifetime)，而非預設的 5 分鐘。適用於 API 金鑰、[Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai)、[Microsoft Foundry](/docs/zh-TW/microsoft-foundry) 和 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 的使用者。在包含用量範圍內的訂閱使用者，會在[主要對話](/docs/zh-TW/prompt-caching#which-ttl-each-request-gets)上自動獲得 1 小時 TTL。使用[用量點數](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)的訂閱使用者可以設定此變數以保留 1 小時 TTL。1 小時的快取寫入會以較高費率計費。若要改為依請求類別選擇 TTL，請使用 `CLAUDE_CODE_PROMPT_CACHE_TTL` 和 `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`，它們優先於此變數 |479| `ENABLE_PROMPT_CACHING_1H` | 設定為 `1` 可請求 1 小時的[提示快取 TTL](/docs/zh-TW/prompt-caching#cache-lifetime)，而非預設的 5 分鐘。適用於 API 金鑰、[Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai)、[Microsoft Foundry](/docs/zh-TW/microsoft-foundry) 與 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 使用者。在包含用量範圍內的訂閱使用者會在[主要對話](/docs/zh-TW/prompt-caching#which-ttl-each-request-gets)上自動獲得 1 小時 TTL。使用[用量點數](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)的訂閱使用者可以設定此變數以保留 1 小時 TTL。1 小時快取寫入會以較高的費率計費。若要改為依請求類別選擇 TTL，請使用 `CLAUDE_CODE_PROMPT_CACHE_TTL` 與 `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`，兩者優先於此變數 |

475| `ENABLE_TOOL_SEARCH` | 控制 [MCP tool search](/docs/zh-TW/mcp#scale-with-mcp-tool-search)。未設定時，Claude Code 預設會延遲載入所有 MCP 工具。但在早於 Claude 4.5 世代的 Google Cloud's Agent Platform 模型上、在託管於 Azure 的 Microsoft Foundry 部署上，以及當 `ANTHROPIC_BASE_URL` 指向非第一方主機時，仍會預先載入它們。`true` 一律延遲載入並傳送 beta 標頭，但上述相同的 Agent Platform 模型和 Microsoft Foundry 部署除外；在不支援 `tool_reference` 的代理伺服器上，請求會失敗。`auto` 會在工具定義佔上下文 10% 以內時預先載入。`auto:N` 設定自訂閾值，例如 `auto:5` 代表 5%。`false` 會預先載入所有工具。設定 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` 時，您自行設定的值會被忽略。在 v2.1.221 之前，除非您將此變數設為 `true`，否則 Claude Code 會對 Google Cloud's Agent Platform 上的所有模型停用 tool search |481| `ENABLE_TOOL_SEARCH` | 控制 [MCP tool search](/docs/zh-TW/mcp#scale-with-mcp-tool-search)。未設定時，Claude Code 預設會延遲載入所有 MCP 工具。但在早於 Claude 4.5 世代的 Google Cloud's Agent Platform 模型上、在託管於 Azure 的 Microsoft Foundry 部署上，以及當 `ANTHROPIC_BASE_URL` 指向非第一方主機時，仍會預先載入這些工具。`true` 一律延遲載入並傳送 beta 標頭，但上述相同的 Agent Platform 模型與 Microsoft Foundry 部署除外；在不支援 `tool_reference` 的代理伺服器上請求會失敗。`auto` 會在工具定義可容納於上下文的 10% 以內時預先載入。`auto:N` 可設定自訂門檻，例如 `auto:5` 代表 5%。`false` 會預先載入所有工具。設定 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` 時，您自行設定的值會被忽略。在 v2.1.221 之前，除非您將此變數設定為 `true`，否則 Claude Code 會在 Google Cloud's Agent Platform 上為所有模型停用 tool search |

476| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | 設為任何非空值（例如 `1`），可讓 Claude Code 在未設定備援模型時，對每個模型在重複發生過載錯誤時停止重試。**設為 `0` 或 `false` 仍會啟用此行為**，這與大多數開關變數不同；取消設定該變數即可恢復預設的重試行為。若未設定此變數，當您使用 API 金鑰或[第三方提供者](/docs/zh-TW/third-party-integrations)而非 Claude 訂閱進行身分驗證時，Claude Code 僅會對其識別為 Opus、Fable 或 Mythos 的模型以此方式停止重試。在 Claude Code v2.1.160 或更新版本上，Claude Code 會在任何主要模型重複發生過載錯誤時，切換到您設定的[備援模型鏈](/docs/zh-TW/model-config#fallback-model-chains)，因此此變數不影響切換到備援模型 |482| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | 設定為任何非空值（例如 `1`），可在未設定備援模型時，讓 Claude Code 對每個模型在重複發生過載錯誤時停止重試。**與大多數開關變數不同，設定為 `0` 或 `false` 仍會啟用此行為**；取消設定此變數即可恢復預設的重試行為。若未設定，當您使用 API 金鑰或[第三方提供者](/docs/zh-TW/third-party-integrations)而非 Claude 訂閱進行身分驗證時，Claude Code 只會對其識別為 Opus、Fable 或 Mythos 的模型以此方式停止重試。在 Claude Code v2.1.160 或更新版本中，Claude Code 會在任何主要模型重複發生過載錯誤時切換至您設定的[備援模型鏈](/docs/zh-TW/model-config#fallback-model-chains)，因此此變數不會影響切換至備援模型 |

478| `FORCE_HYPERLINK` | 設為 `1` 可在您的終端機支援但未被自動偵測到時，啟用可點擊的 OSC 8 超連結，或設為 `0` 將其停用。未設定時，Claude Code 僅在偵測到終端機支援時才會啟用超連結。Claude Code 將此值解析為數字而非布林值，因此 `false`、`no` 或 `off` 等值會啟用超連結，而不是停用。頁尾的 [PR 或合併請求徽章](/docs/zh-TW/interactive-mode#pr-review-status)即使在 Claude Code 無法偵測到終端機支援時（例如透過 SSH）也會以超連結呈現。設為 `0` 可將徽章呈現為純文字 |484| `FORCE_HYPERLINK` | 當您的終端機支援可點擊的 OSC 8 超連結但未被自動偵測到時，設定為 `1` 可啟用它們，設定為 `0` 則可停用。未設定時，Claude Code 僅在偵測到終端機支援時啟用超連結。Claude Code 會將此值解析為數字而非布林值，因此 `false`、`no` 或 `off` 等值會啟用超連結而非停用。即使 Claude Code 無法偵測終端機支援（例如透過 SSH），頁尾的 [PR 或合併請求徽章](/docs/zh-TW/interactive-mode#pr-review-status)仍會顯示為超連結。設定 `0` 可將徽章顯示為純文字 |

479| `FORCE_PROMPT_CACHING_5M` | 設為 `1` 可強制使用 5 分鐘的提示快取 TTL，即使原本會套用 1 小時 TTL。覆寫 `CLAUDE_CODE_PROMPT_CACHE_TTL`、`CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`、`ENABLE_PROMPT_CACHING_1H`，以及 `promptCacheTtl` 和 `subagentPromptCacheTtl` 設定 |485| `FORCE_PROMPT_CACHING_5M` | 設定為 `1` 可強制使用 5 分鐘提示快取 TTL，即使原本會套用 1 小時 TTL。覆寫 `CLAUDE_CODE_PROMPT_CACHE_TTL`、`CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`、`ENABLE_PROMPT_CACHING_1H`，以及 `promptCacheTtl` 與 `subagentPromptCacheTtl` 設定 |

482| `IS_DEMO` | 設為任何非空值（例如 `1`）可啟用示範模式：在標頭和 `/status` 輸出中隱藏您的電子郵件和組織名稱，並略過新手導覽。**設為 `0` 或 `false` 仍會啟用示範模式**，這與大多數開關變數不同；取消設定該變數即可將其關閉。在直播或錄製工作階段時很有用 |488| `IS_DEMO` | 設定為任何非空值（例如 `1`）可啟用示範模式：在標頭與 `/status` 輸出中隱藏您的電子郵件與組織名稱，並略過入門引導。**與大多數開關變數不同，設定為 `0` 或 `false` 仍會啟用示範模式**；取消設定此變數即可將其關閉。適用於直播或錄製工作階段時 |

483| `MAX_MCP_OUTPUT_TOKENS` | MCP 工具回應中允許的最大 token 數（預設值：25000）。當輸出超過 10,000 個 token 時，Claude Code 會顯示警告。宣告 [`anthropic/maxResultSizeChars`](/docs/zh-TW/mcp#raise-the-limit-for-a-specific-tool) 的工具會改為對文字內容使用該字元限制，但這些工具的圖片內容仍受此變數限制。來自未宣告該註解之工具的成功文字結果若超過 50,000 個字元，無論此變數為何，都會被[儲存至檔案](/docs/zh-TW/mcp#mcp-output-limits-and-warnings) |489| `MAX_MCP_OUTPUT_TOKENS` | MCP 工具回應中允許的最大 token 數（預設：25000）。當輸出超過 10,000 個 token 時，Claude Code 會顯示警告。宣告 [`anthropic/maxResultSizeChars`](/docs/zh-TW/mcp#raise-the-limit-for-a-specific-tool) 的工具會改對文字內容使用該字元限制，但這些工具的圖片內容仍受此變數限制。來自未加上該註解之工具、長度超過 50,000 個字元的成功文字結果，無論此變數為何，都會[儲存至檔案](/docs/zh-TW/mcp#mcp-output-limits-and-warnings) |

484| `MAX_STRUCTURED_OUTPUT_RETRIES` | 在使用 `-p` 旗標的非互動模式中，當模型的回應未通過 [`--json-schema`](/docs/zh-TW/cli-reference#cli-flags) 驗證時，Claude Code 允許的嘗試次數；經過該次數的失敗嘗試且沒有有效輸出後，執行即告失敗。當[工作流程](/docs/zh-TW/workflows) subagent 的結構化輸出未通過驗證時，也適用相同的上限。預設值為 5，即一次初始嘗試加上四次重試 |490| `MAX_STRUCTURED_OUTPUT_RETRIES` | 在使用 `-p` 旗標的非互動模式中，當模型的回應未通過 [`--json-schema`](/docs/zh-TW/cli-reference#cli-flags) 驗證時，Claude Code 允許的嘗試次數；在這麼多次嘗試失敗且沒有有效輸出之後，執行會失敗。當[工作流程](/docs/zh-TW/workflows) subagent 的結構化輸出未通過驗證時，也適用相同上限。預設為 5，即第一次嘗試加上四次重試 |

485| `MAX_THINKING_TOKENS` | [延伸思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)的固定 token 預算。Claude Code 會將其上限設為比請求的最大輸出 token 數少一個 token，且永遠不低於 1,024。關於該限制如何設定，請參閱 `CLAUDE_CODE_MAX_OUTPUT_TOKENS`。未設定且已啟用思考時，具備[自適應推理](/docs/zh-TW/model-config#adjust-effort-level)的模型會自行選擇思考深度，其他模型則使用上限。設為 `0` 可在 Anthropic API 上停用思考，但 Opus 5.5、Sonnet 5.5、Haiku 5.5 和 Fable 模型除外，這些模型無法關閉思考。在[第三方提供者](/docs/zh-TW/third-party-integrations)上，`0` 會改為省略 `thinking` 參數。在 Anthropic API 上關閉思考時，對於 Claude Code 已知[不接受該組合](/docs/zh-TW/errors#effort-isnt-available-with-thinking-turned-off)的模型（例如 Opus 5），Claude Code 會傳送 effort `high`，而非更高的等級。對於正值，Claude Code 在自適應推理模型上會忽略該數字本身，除非 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 關閉了自適應推理 |491| `MAX_THINKING_TOKENS` | [延伸思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)的固定 token 預算。Claude Code 會將其上限設為比請求的最大輸出 token 少一個，且絕不低於 1,024。關於該限制如何設定，請參閱 `CLAUDE_CODE_MAX_OUTPUT_TOKENS`。未設定且已啟用思考時，具備[自適應推理](/docs/zh-TW/model-config#adjust-effort-level)的模型會自行選擇思考深度，其他模型則使用上限。設定為 `0` 可在 Anthropic API 上停用思考，但 Opus 5.5、Sonnet 5.5、Haiku 5.5 與 Fable 模型除外，這些模型無法關閉思考。在[第三方提供者](/docs/zh-TW/third-party-integrations)上，`0` 則會改為省略 `thinking` 參數。在 Anthropic API 上關閉思考時，對於 Claude Code 已知[不接受該組合](/docs/zh-TW/errors#effort-isnt-available-with-thinking-turned-off)的模型（例如 Opus 5），Claude Code 會傳送 effort `high` 而非更高的等級。若為正值，Claude Code 會在自適應推理模型上忽略該數字本身，除非 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 關閉了自適應推理 |

486| `MCP_CLIENT_SECRET` | 用於需要[預先設定憑證](/docs/zh-TW/mcp#use-pre-configured-oauth-credentials)之 MCP 伺服器的 OAuth 用戶端密鑰。使用 `--client-secret` 新增伺服器時可避免互動式提示 |492| `MCP_CLIENT_SECRET` | 需要[預先設定憑證](/docs/zh-TW/mcp#use-pre-configured-oauth-credentials)之 MCP 伺服器的 OAuth 用戶端密鑰。可在使用 `--client-secret` 新增伺服器時避免互動式提示 |

487| `MCP_CONNECTION_NONBLOCKING` | 控制啟動時是否在第一次查詢之前等待 MCP 伺服器連線。MCP 啟動預設為非阻塞：伺服器會在背景連線，其工具會在完成連線後陸續可用。設為 `0` 可讓 Claude Code 在第一次查詢之前等待伺服器連線。以 [`alwaysLoad: true`](/docs/zh-TW/mcp#exempt-a-server-from-deferral) 設定的伺服器無論如何仍會讓啟動等待，但從[探索快取](/docs/zh-TW/mcp#server-status-detail)提供時除外，因為建立第一個提示詞時其工具必須已存在。在不含 `--input-format stream-json` 的非互動模式（`-p`）中，無論此變數為何，Claude Code 也會在第一個回合之前等待仍在擱置中的伺服器。當您明確傳遞 [`--mcp-config`](/docs/zh-TW/cli-reference#cli-flags) 時，等待的截止時間會較長；關於已快取伺服器的例外情況，請參閱該旗標的項目 |493| `MCP_CONNECTION_NONBLOCKING` | 控制啟動時是否在第一個查詢之前等待 MCP 伺服器連線。MCP 啟動預設為非阻塞：伺服器會在背景連線，其工具會在完成時變為可用。設定為 `0` 可讓 Claude Code 在第一個查詢之前等待伺服器連線。以 [`alwaysLoad: true`](/docs/zh-TW/mcp#exempt-a-server-from-deferral) 設定的伺服器無論如何仍會讓啟動等待，除非是從[探索快取](/docs/zh-TW/mcp#server-status-detail)提供，因為建構第一個提示詞時必須具備其工具。在未使用 `--input-format stream-json` 的非互動模式（`-p`）中，無論此變數為何，Claude Code 也會在第一個回合之前等待仍在擱置中的伺服器。當您明確傳遞 [`--mcp-config`](/docs/zh-TW/cli-reference#cli-flags) 時，等待的期限較長；關於已快取伺服器的例外，請參閱該旗標的說明 |

488| `MCP_CONNECT_TIMEOUT_MS` | 阻塞式 MCP 啟動在擷取工具清單快照之前，等待連線批次的時間（毫秒）（預設值：5000）。適用於 `MCP_CONNECTION_NONBLOCKING=0` 時，或標記為 [`alwaysLoad: true`](/docs/zh-TW/mcp#exempt-a-server-from-deferral) 的伺服器。截止時間到達時仍在擱置的伺服器會繼續在背景連線。與 `MCP_TIMEOUT` 不同，後者限制的是個別伺服器的連線嘗試 |494| `MCP_CONNECT_TIMEOUT_MS` | 阻塞式 MCP 啟動在擷取工具清單快照之前，等待連線批次的時間（毫秒，預設：5000）。適用於 `MCP_CONNECTION_NONBLOCKING=0` 時，或標記為 [`alwaysLoad: true`](/docs/zh-TW/mcp#exempt-a-server-from-deferral) 的伺服器。在期限時仍處於擱置狀態的伺服器會繼續在背景連線。與 `MCP_TIMEOUT` 不同，後者限制的是個別伺服器的連線嘗試 |

489| `MCP_DISCOVERY_CACHE` | 開啟或關閉 [MCP 探索快取](/docs/zh-TW/mcp#server-status-detail)。快取開啟時，您先前使用過的遠端 HTTP 或 SSE 伺服器可以顯示[`cached` 狀態](/docs/zh-TW/mcp#server-status-detail)，且 Claude Code 會在其第一次工具呼叫時才連線，而非在啟動時連線。除非漸進式推出已為您的帳戶啟用，否則快取預設為關閉。設為 `1` 可將其開啟，或設為 `0` 以在推出已啟用時仍保持關閉。在 v2.1.238 之前，快取預設為開啟。`cached` 狀態需要 Claude Code v2.1.221 或更新版本 |495| `MCP_DISCOVERY_CACHE` | 開啟或關閉 [MCP 探索快取](/docs/zh-TW/mcp#server-status-detail)。快取開啟時，您先前使用過的遠端 HTTP 或 SSE 伺服器可以顯示 [`cached` 狀態](/docs/zh-TW/mcp#server-status-detail)，且 Claude Code 會在其第一次工具呼叫時才連線，而非在啟動時。除非漸進式推出已為您的帳戶啟用，否則快取預設為關閉。設定為 `1` 可將其開啟，設定為 `0` 則即使推出已啟用也會保持關閉。在 v2.1.238 之前，快取預設為開啟。`cached` 狀態需要 Claude Code v2.1.221 或更新版本 |

490| `MCP_DISCOVERY_CACHE_MAX_STALE_S` | [探索快取](/docs/zh-TW/mcp#server-status-detail)項目的最長存在時間（秒）（預設值：14400，即 4 小時）。啟動時若項目超過此時間，Claude Code 會將其捨棄並在啟動時連線伺服器，如同快取關閉時一樣。Claude Code 將此值上限設為 7 天。在 v2.1.238 之前，預設值為 86400，即 24 小時，且 Claude Code 不會限制此值 |496| `MCP_DISCOVERY_CACHE_MAX_STALE_S` | [探索快取](/docs/zh-TW/mcp#server-status-detail)項目的最長存留時間（秒）（預設：14400，即 4 小時）。在項目比這更舊的啟動中，Claude Code 會捨棄該項目並在啟動時連線伺服器，如同快取關閉時的行為。Claude Code 會將此值上限設為 7 天。在 v2.1.238 之前，預設值為 86400，即 24 小時，且 Claude Code 不會限制此值 |

491| `MCP_DISCOVERY_CACHE_STRIKES` | 啟動時若[探索快取](/docs/zh-TW/mcp#server-status-detail)項目超過 `MCP_DISCOVERY_CACHE_TTL_S`，Claude Code 會在背景重新整理它。此變數設定在 Claude Code 捨棄該項目並改為在下次啟動時連線伺服器之前，可連續失敗的重新整理次數（預設值：1）。若您的網路連線偶爾中斷，請調高此值，以免一次重新整理失敗就捨棄該項目。需要 Claude Code v2.1.238 或更新版本 |497| `MCP_DISCOVERY_CACHE_STRIKES` | 在[探索快取](/docs/zh-TW/mcp#server-status-detail)項目比 `MCP_DISCOVERY_CACHE_TTL_S` 更舊的啟動中，Claude Code 會在背景重新整理該項目。此變數設定在 Claude Code 捨棄該項目並改在下次啟動時連線伺服器之前，可連續失敗的重新整理次數（預設：1）。若您的網路連線偶爾會中斷，請提高此值，讓單次重新整理失敗不會捨棄項目。需要 Claude Code v2.1.238 或更新版本 |

492| `MCP_DISCOVERY_CACHE_TTL_S` | Claude Code 使用[探索快取](/docs/zh-TW/mcp#server-status-detail)項目而不重新整理的秒數（預設值：900）。啟動時若項目超過此時間，Claude Code 仍會使用它，但會在背景重新整理。一旦項目超過 `MCP_DISCOVERY_CACHE_MAX_STALE_S`，Claude Code 就會改為將其捨棄。Claude Code 將此值上限設為 `MCP_DISCOVERY_CACHE_MAX_STALE_S`，預設為 4 小時。在 v2.1.238 之前，Claude Code 不會限制此值 |498| `MCP_DISCOVERY_CACHE_TTL_S` | Claude Code 使用[探索快取](/docs/zh-TW/mcp#server-status-detail)項目而不重新整理的秒數（預設：900）。在項目比這更舊的啟動中，Claude Code 仍會使用該項目，但會在背景重新整理。一旦項目比 `MCP_DISCOVERY_CACHE_MAX_STALE_S` 更舊，Claude Code 則會將其捨棄。Claude Code 會將此值上限設為 `MCP_DISCOVERY_CACHE_MAX_STALE_S`，預設為 4 小時。在 v2.1.238 之前，Claude Code 不會限制此值 |

493| `MCP_OAUTH_CALLBACK_PORT` | OAuth 重新導向回呼的固定連接埠，在使用[預先設定憑證](/docs/zh-TW/mcp#use-pre-configured-oauth-credentials)新增 MCP 伺服器時，作為 `--callback-port` 的替代方案 |499| `MCP_OAUTH_CALLBACK_PORT` | OAuth 重新導向回呼的固定連接埠，在新增具有[預先設定憑證](/docs/zh-TW/mcp#use-pre-configured-oauth-credentials)的 MCP 伺服器時，可作為 `--callback-port` 的替代方案 |

494| `MCP_PROTOCOL_NEGOTIATION` | 僅適用於 [v2 MCP 用戶端執行環境](/docs/zh-TW/mcp#mcp-client-runtimes)，控制 Claude Code 是否探測伺服器是否支援 MCP 協定修訂版 2026-07-28。設為 `auto` 可探測 HTTP、claude.ai 連接器和 stdio 伺服器，或設為 `legacy` 不探測任何伺服器。未設定此變數時，Claude Code 會探測 [MCP 用戶端執行環境](/docs/zh-TW/mcp#mcp-client-runtimes)中所述的伺服器。任何其他值都會被忽略，並在偵錯日誌中留下警告。需要 Claude Code v2.1.221 或更新版本 |500| `MCP_PROTOCOL_NEGOTIATION` | 僅在 [v2 MCP 用戶端執行環境](/docs/zh-TW/mcp#mcp-client-runtimes)上，決定 Claude Code 是否探測伺服器是否支援 MCP 協定修訂版 2026-07-28。設定 `auto` 可探測 HTTP、claude.ai 連接器與 stdio 伺服器，設定 `legacy` 則不探測任何伺服器。未設定此變數時，Claude Code 會探測 [MCP 用戶端執行環境](/docs/zh-TW/mcp#mcp-client-runtimes)中所述的伺服器。任何其他值都會被忽略，並在偵錯日誌中記下警告。需要 Claude Code v2.1.221 或更新版本 |

496| `MCP_SDK_GENERATION` | 固定此程序用來連線 MCP 伺服器的 [MCP 用戶端執行環境](/docs/zh-TW/mcp#mcp-client-runtimes)：`v1`，以 MCP TypeScript SDK 1.x 建置，或 `v2`，以 [MCP TypeScript SDK 2.0](https://ts.sdk.modelcontextprotocol.io/v2/) 建置。未設定此變數時，Claude Code 會使用 v2，從該章節列出的版本開始。在 Claude Code v2.1.221 或更新版本上，v2 執行環境會檢查 MCP OAuth 伺服器在其授權回應中傳回的簽發者，若不相符，登入會失敗並顯示以 `Issuer mismatch in authorization response` 開頭的錯誤。v1 執行環境不會執行此檢查。若您設定了無法辨識的值，Claude Code 會將其忽略並在偵錯日誌中寫入警告。Claude Code 每個程序只讀取此值一次。需要 Claude Code v2.1.218 或更新版本 |502| `MCP_SDK_GENERATION` | 固定此程序連線至 MCP 伺服器時使用的 [MCP 用戶端執行環境](/docs/zh-TW/mcp#mcp-client-runtimes)：`v1`（建構於 MCP TypeScript SDK 1.x）或 `v2`（建構於 [MCP TypeScript SDK 2.0](https://ts.sdk.modelcontextprotocol.io/v2/)）。未設定此變數時，Claude Code 會使用 v2，自該節所列的版本起生效。在 Claude Code v2.1.221 或更新版本中，v2 執行環境會檢查 MCP OAuth 伺服器在其授權回應中傳回的簽發者，若不相符，會以開頭為 `Issuer mismatch in authorization response` 的錯誤使登入失敗。v1 執行環境不會執行此檢查。若您設定了無法識別的值，Claude Code 會忽略它並在偵錯日誌中寫入警告。Claude Code 每個程序只讀取一次此值。需要 Claude Code v2.1.218 或更新版本 |

499| `MCP_TOOL_TIMEOUT` | MCP 工具執行的逾時（毫秒）（預設值：100000000，約 28 小時）。對於 HTTP、SSE 或 claude.ai 連接器伺服器，每個請求預設也會在 60 秒後逾時；將此變數或個別伺服器的 `timeout` 設為高於 60000，即可提高該每請求限制。較低的值仍會縮短整體工具執行逾時，但每請求限制仍維持 60 秒。Stdio 和 WebSocket 伺服器沒有每請求計時器。`.mcp.json` 中個別伺服器的 `timeout` 欄位會針對該伺服器覆寫此值。至少為 1000 的個別伺服器 `timeout` 也會設定該伺服器工具呼叫的最小閒置時間窗，因此 `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` 絕不會更早中止它們；此下限需要 Claude Code v2.1.203 或更新版本。對於環境變數，低於 1000 的值會被提高至一秒；對於個別伺服器欄位，低於 1000 的值會被忽略 |505| `MCP_TOOL_TIMEOUT` | MCP 工具執行的逾時（毫秒，預設：100000000，約 28 小時）。對於 HTTP、SSE 或 claude.ai 連接器伺服器，每個請求預設也會在 60 秒後逾時；將此變數或個別伺服器的 `timeout` 設定為高於 60000，可提高該每請求限制。較低的值仍會縮短整體工具執行逾時，但每請求限制維持 60 秒。Stdio 與 WebSocket 伺服器沒有每請求計時器。`.mcp.json` 中個別伺服器的 `timeout` 欄位會針對該伺服器覆寫此值。個別伺服器至少為 1000 的 `timeout` 也會設定該伺服器工具呼叫的最小閒置時間窗，因此 `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` 絕不會更早中止它們；此下限需要 Claude Code v2.1.203 或更新版本。對於環境變數，低於 1000 的值會被提高至一秒；對於個別伺服器欄位，低於 1000 的值會被忽略 |

501| `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` | 標準 OpenTelemetry SDK 的屬性值長度限制。Claude Code 會將包含內容的遙測屬性上限設為此值與 `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 中較小者，使截斷標記保持在 SDK 限制之內。Claude Code 會以相同方式讀取 `OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT` 和 `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` 變體，且設定的最小值會套用至所有訊號。需要 Claude Code v2.1.214 或更新版本。請參閱[監控](/docs/zh-TW/monitoring-usage#common-configuration-variables) |507| `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` | 標準 OpenTelemetry SDK 的屬性值長度限制。Claude Code 會將帶有內容的遙測屬性上限設為此值與 `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 中較小者，使截斷標記保持在 SDK 限制之內。Claude Code 會以相同方式讀取 `OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT` 與 `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` 變體，且最小的已設定值會套用至所有訊號。需要 Claude Code v2.1.214 或更新版本。請參閱[監控](/docs/zh-TW/monitoring-usage#common-configuration-variables) |

502| `OTEL_LOG_ASSISTANT_RESPONSES` | 設為 `1` 可在 `assistant_response` OpenTelemetry 日誌事件中包含模型的回應文字。未設定時，Claude Code 會改用 `OTEL_LOG_USER_PROMPTS` 的值。設為 `0` 可在設定了 `OTEL_LOG_USER_PROMPTS` 時仍保持回應遮蔽。請在您的 shell、使用者設定或受管設定中設定。在[專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略。需要 Claude Code v2.1.193 或更新版本。請參閱[監控](/docs/zh-TW/monitoring-usage#assistant-response-event) |508| `OTEL_LOG_ASSISTANT_RESPONSES` | 設定為 `1` 可在 `assistant_response` OpenTelemetry 日誌事件中包含模型的回應文字。未設定時，Claude Code 會改用 `OTEL_LOG_USER_PROMPTS` 的值。設定為 `0` 可在已設定 `OTEL_LOG_USER_PROMPTS` 的情況下仍保持回應遮蔽。請在您的 shell、使用者設定或受管設定中設定。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略。需要 Claude Code v2.1.193 或更新版本。請參閱[監控](/docs/zh-TW/monitoring-usage#assistant-response-event) |

503| `OTEL_LOG_MANAGED_SETTINGS` | 設為 `1` 可將已遮蔽的受管設定，以及遮蔽前設定的 SHA-256 摘要，加入 `managed_settings_resolved` OpenTelemetry 日誌事件。預設停用。請在您的 shell、使用者設定或受管設定中設定；專案或本機設定中的值不會將其開啟。需要 Claude Code v2.1.274 或更新版本。請參閱[監控](/docs/zh-TW/monitoring-usage#managed-settings-resolved-event) |509| `OTEL_LOG_MANAGED_SETTINGS` | 設定為 `1` 可將遮蔽後的受管設定，以及遮蔽前設定的 SHA-256 摘要，加入 `managed_settings_resolved` OpenTelemetry 日誌事件。預設為停用。請在您的 shell、使用者設定或受管設定中設定；專案或本機設定中的值不會將其開啟。需要 Claude Code v2.1.274 或更新版本。請參閱[監控](/docs/zh-TW/monitoring-usage#managed-settings-resolved-event) |

504| `OTEL_LOG_RAW_API_BODIES` | 將 Anthropic Messages API 的請求和回應 JSON 作為 `api_request_body` / `api_response_body` 日誌事件發出。設為 `1` 可發出在內容限制處截斷的內嵌本文，或設為 `file:<dir>` 將未截斷的本文寫入磁碟，並改為發出 `body_ref` 路徑。`CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 用於設定內容限制，預設為 60 KB。預設停用；本文包含完整的對話歷史記錄。請在您的 shell、使用者設定或受管設定中設定。在[專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略。請參閱[監控](/docs/zh-TW/monitoring-usage#api-request-body-event) |510| `OTEL_LOG_RAW_API_BODIES` | 將 Anthropic Messages API 請求與回應 JSON 以 `api_request_body` / `api_response_body` 日誌事件發出。設定為 `1` 可發出在內容限制處截斷的內嵌本文，或設定為 `file:<dir>` 可將未截斷的本文寫入磁碟並改為發出 `body_ref` 路徑。`CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 可設定內容限制，預設為 60 KB。預設為停用；本文包含完整的對話記錄。請在您的 shell、使用者設定或受管設定中設定。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略。請參閱[監控](/docs/zh-TW/monitoring-usage#api-request-body-event) |

505| `OTEL_LOG_TOOL_CONTENT` | 設為 `1` 可在 `tool.output` OpenTelemetry span 事件中包含工具內容。span 屬性會依據[各自的閘門](/docs/zh-TW/monitoring-usage#new-context-gates)攜帶工具內容。需要[追蹤](/docs/zh-TW/monitoring-usage#traces-beta)。預設停用以保護敏感資料。請在您的 shell、使用者設定或受管設定中設定。在[專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略，但該章節所述的關閉值除外。請參閱[監控](/docs/zh-TW/monitoring-usage#tool-output-span-event) |511| `OTEL_LOG_TOOL_CONTENT` | 設定為 `1` 可在 `tool.output` OpenTelemetry span 事件中包含工具內容。Span 屬性會依[各自的開關](/docs/zh-TW/monitoring-usage#new-context-gates)攜帶工具內容。需要[追蹤](/docs/zh-TW/monitoring-usage#traces-beta)。預設為停用以保護敏感資料。請在您的 shell、使用者設定或受管設定中設定。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略，但該節所述的關閉值除外。請參閱[監控](/docs/zh-TW/monitoring-usage#tool-output-span-event) |

506| `OTEL_LOG_TOOL_DETAILS` | 設為 `1` 可在 OpenTelemetry 指標、追蹤和日誌中包含工具輸入引數；MCP 伺服器名稱；使用者撰寫的工作流程名稱；工具失敗時的原始錯誤字串；`api_refusal` 事件上的拒絕 `category`；[成本和 token 指標](/docs/zh-TW/monitoring-usage#cost-counter)上真實的 agent、skill、外掛和 MCP 伺服器名稱；以及其他工具詳細資訊。預設停用以保護 PII。請在您的 shell、使用者設定或受管設定中設定。在[專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略，但該章節所述的關閉值除外。請參閱[監控](/docs/zh-TW/monitoring-usage) |512| `OTEL_LOG_TOOL_DETAILS` | 設定為 `1` 可在 OpenTelemetry 指標、追蹤與日誌中包含工具輸入引數；MCP 伺服器名稱；使用者撰寫的工作流程名稱；工具失敗時的原始錯誤字串；`api_refusal` 事件上的拒絕 `category`；[成本與 token 指標](/docs/zh-TW/monitoring-usage#cost-counter)上真實的 agent、skill、外掛與 MCP 伺服器名稱；以及其他工具詳細資訊。預設為停用以保護 PII。請在您的 shell、使用者設定或受管設定中設定。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略，但該節所述的關閉值除外。請參閱[監控](/docs/zh-TW/monitoring-usage) |

507| `OTEL_LOG_USER_PROMPTS` | 設為 `1` 可在 OpenTelemetry 追蹤和日誌中包含使用者提示詞文字。預設停用（提示詞會被遮蔽）。請在您的 shell、使用者設定或受管設定中設定。在[專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略，但該章節所述的關閉值除外。請參閱[監控](/docs/zh-TW/monitoring-usage) |513| `OTEL_LOG_USER_PROMPTS` | 設定為 `1` 可在 OpenTelemetry 追蹤與日誌中包含使用者提示詞文字。預設為停用（提示詞會被遮蔽）。請在您的 shell、使用者設定或受管設定中設定。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略，但該節所述的關閉值除外。請參閱[監控](/docs/zh-TW/monitoring-usage) |

509| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | 設為 `true` 可在指標屬性中包含工作階段進入點（預設值：排除）。已於 v2.1.152 新增。請參閱[監控](/docs/zh-TW/monitoring-usage) |515| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | 設定為 `true` 可在指標屬性中包含工作階段進入點（預設：排除）。於 v2.1.152 新增。請參閱[監控](/docs/zh-TW/monitoring-usage) |

510| `OTEL_METRICS_INCLUDE_REPOSITORY` | 設為 `true` 可為 OpenTelemetry 指標和事件加上識別工作階段儲存庫的 `vcs.*` 屬性（預設值：排除）。需要 Claude Code v2.1.269 或更新版本。請參閱[儲存庫屬性](/docs/zh-TW/monitoring-usage#repository-attributes) |516| `OTEL_METRICS_INCLUDE_REPOSITORY` | 設定為 `true` 可為 OpenTelemetry 指標與事件加上識別工作階段儲存庫的 `vcs.*` 屬性（預設：排除）。需要 Claude Code v2.1.269 或更新版本。請參閱[儲存庫屬性](/docs/zh-TW/monitoring-usage#repository-attributes) |

511| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | 自 v2.1.161 起，Claude Code 會將 `OTEL_RESOURCE_ATTRIBUTES` 的鍵附加到指標資料點標籤。設為 `false` 可將其排除（預設值：包含）。請參閱[監控](/docs/zh-TW/monitoring-usage#multi-team-organization-support) |517| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | 自 v2.1.161 起，Claude Code 會將 `OTEL_RESOURCE_ATTRIBUTES` 的鍵附加至指標資料點標籤。設定為 `false` 可將其排除（預設：包含）。請參閱[監控](/docs/zh-TW/monitoring-usage#multi-team-organization-support) |

514| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | 覆寫顯示給 [Skill 工具](/docs/zh-TW/skills#control-who-invokes-a-skill)的 skill 中繼資料字元預算。預算會依上下文視窗的 1% 動態調整，備援值為 8,000 個字元。為了向後相容而保留舊名稱 |520| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | 覆寫顯示給 [Skill 工具](/docs/zh-TW/skills#control-who-invokes-a-skill)之 skill 中繼資料的字元預算。此預算會動態調整為上下文視窗的 1%，備援值為 8,000 個字元。保留舊名稱以維持向下相容 |

515| `TASK_MAX_OUTPUT_LENGTH` | 已在 v2.1.277 中移除，現在不起任何作用，其所設定大小的 `TaskOutput` 工具也一併移除。先前用於設定 `TaskOutput` 工具所保留之[背景任務](/docs/zh-TW/tools-reference#background-commands)輸出的最大字元數。Claude 現在改用 `Read` 讀取背景任務的輸出檔案 |521| `TASK_MAX_OUTPUT_LENGTH` | 已在 v2.1.277 中與其所設定大小的 `TaskOutput` 工具一併移除，現在不再有任何作用。先前用於設定 `TaskOutput` 工具保留的[背景任務](/docs/zh-TW/tools-reference#background-commands)輸出最大字元數。Claude 現在改以 `Read` 讀取背景任務的輸出檔案 |

~~537~~ 543

538也支援標準 OpenTelemetry 匯出器變數（`OTEL_METRICS_EXPORTER`、`OTEL_LOGS_EXPORTER`、`OTEL_EXPORTER_OTLP_ENDPOINT`、`OTEL_EXPORTER_OTLP_PROTOCOL`、`OTEL_EXPORTER_OTLP_HEADERS`、`OTEL_METRIC_EXPORT_INTERVAL`、`OTEL_RESOURCE_ATTRIBUTES`，以及特定訊號的變體）。關於設定詳細資訊，請參閱[監控](/docs/zh-TW/monitoring-usage)。544也支援標準 OpenTelemetry 匯出器變數（`OTEL_METRICS_EXPORTER`、`OTEL_LOGS_EXPORTER`、`OTEL_EXPORTER_OTLP_ENDPOINT`、`OTEL_EXPORTER_OTLP_PROTOCOL`、`OTEL_EXPORTER_OTLP_HEADERS`、`OTEL_METRIC_EXPORT_INTERVAL`、`OTEL_RESOURCE_ATTRIBUTES` 以及特定訊號的變體）。設定詳細資訊請參閱[監控](/docs/zh-TW/monitoring-usage)。

~~539~~ 545

540請在您的 shell、使用者設定或受管設定中，設定 `CLAUDE_CODE_ENABLE_TELEMETRY`，以及用於開啟匯出、選擇匯出目的地或擷取內容的 OpenTelemetry 變數。Claude Code [會在專案和本機設定中忽略它們](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)，但該章節所述的關閉值除外。`OTEL_RESOURCE_ATTRIBUTES` 以及匯出間隔、逾時和壓縮變數（例如 `OTEL_METRIC_EXPORT_INTERVAL`）在專案和本機設定中仍會套用。546請在您的 shell、使用者設定或受管設定中設定 `CLAUDE_CODE_ENABLE_TELEMETRY`，以及用於開啟匯出、選擇匯出目的地或擷取內容的 OpenTelemetry 變數。Claude Code [會在專案與本機設定中忽略它們](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)，但該節所述的關閉值除外。`OTEL_RESOURCE_ATTRIBUTES` 以及匯出間隔、逾時與壓縮變數（例如 `OTEL_METRIC_EXPORT_INTERVAL`）在專案與本機設定中仍會生效。

541 547

542<h2 id="what-the-subprocess-environment-scrub-removes">548<h2 id="what-the-subprocess-environment-scrub-removes">

543 子程序環境清除會移除哪些內容549 子程序環境清除會移除哪些內容

590* 使用 [advisor 工具](/docs/zh-TW/advisor#requirements)596* 使用 [advisor 工具](/docs/zh-TW/advisor#requirements)

591* 閱讀或回覆 [artifact 上的留言](/docs/zh-TW/artifacts#collect-comments-on-an-artifact)597* 閱讀或回覆 [artifact 上的留言](/docs/zh-TW/artifacts#collect-comments-on-an-artifact)

592* 讓 Claude 讀取[其他組織的公開 artifact](/docs/zh-TW/artifacts#read-an-artifact-shared-with-you)598* 讓 Claude 讀取[其他組織的公開 artifact](/docs/zh-TW/artifacts#read-an-artifact-shared-with-you)

593* 讓 Claude Code 探測 claude.ai 連接器伺服器是否支援 [MCP 協定修訂版 2026-07-28](/docs/zh-TW/mcp#mcp-client-runtimes)，除非您設定 `MCP_PROTOCOL_NEGOTIATION=auto`

594* 在已安裝 Git Bash 的 Windows 上，為 claude.ai 和 Console 帳戶預設取得 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool)；除非您設定 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`，否則 Claude Code 會透過 Git Bash 執行 shell 命令。在未安裝 Git Bash 的 Windows 上，該工具會保持啟用599* 在已安裝 Git Bash 的 Windows 上，為 claude.ai 和 Console 帳戶預設取得 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool)；除非您設定 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`，否則 Claude Code 會透過 Git Bash 執行 shell 命令。在未安裝 Git Bash 的 Windows 上，該工具會保持啟用

595* 取得 [Claude 草擬的意見回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior)，Claude Code 是透過擷取的旗標來啟用此功能600* 取得 [Claude 草擬的意見回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior)，Claude Code 是透過擷取的旗標來啟用此功能

596* 讓 Claude [將大量貼上內容視為貼上的文字，而非輸入的文字](/docs/zh-TW/terminal-config#how-claude-treats-pasted-text)；`[Pasted text #N]` 預留位置背後的內容會未經標記地傳送給 Claude601* 讓 Claude [將大量貼上內容視為貼上的文字，而非輸入的文字](/docs/zh-TW/terminal-config#how-claude-treats-pasted-text)；`[Pasted text #N]` 預留位置背後的內容會未經標記地傳送給 Claude

errors.md +125 −172

Details

51| `You've hit your monthly spend limit` / `You've hit your individual spend limit` / `You've hit your org's monthly spend limit` / `You've hit your channel's monthly spend limit` / `You've hit your team's shared budget` / `You've hit your individual usage limit` | [用量上限](#youve-hit-your-monthly-spend-limit) |51| `You've hit your monthly spend limit` / `You've hit your individual spend limit` / `You've hit your org's monthly spend limit` / `You've hit your channel's monthly spend limit` / `You've hit your team's shared budget` / `You've hit your individual usage limit` | [用量上限](#youve-hit-your-monthly-spend-limit) |

52| `Could not update your spend limit` | [用量上限](#could-not-update-your-spend-limit) |52| `Could not update your spend limit` | [用量上限](#could-not-update-your-spend-limit) |

53| `spend limit reached` / `spend limit unavailable` | [用量上限](#spend-limit-reached) |53| `spend limit reached` / `spend limit unavailable` | [用量上限](#spend-limit-reached) |

~~65| `Your organization has disabled Claude subscription access` | [驗證](#your-organization-has-disabled-claude-subscription-access) |~~65| `Your organization has disabled Claude subscription access` | [身分驗證](#your-organization-has-disabled-claude-subscription-access) |

~~67| `Remote Control is only available when using Claude via api.anthropic.com` | [驗證](#remote-control-requires-the-anthropic-api) |~~67| `Remote Control is only available when using Claude via api.anthropic.com` | [身分驗證](#remote-control-requires-the-anthropic-api) |

~~74| `signed-in claude.ai account or organization changed on this machine` | [驗證](#remote-control-stopped-because-the-signed-in-account-changed) |~~74| `signed-in claude.ai account or organization changed on this machine` | [身分驗證](#remote-control-stopped-because-the-signed-in-account-changed) |

75| `Remote Control stopped — the app running this session is now signed in to a different Claude account` | [驗證](#remote-control-stopped-because-the-app-running-the-session-signed-out-or-switched-accounts) |75| `Remote Control stopped — the app running this session is now signed in to a different Claude account` | [身分驗證](#remote-control-stopped-because-the-app-running-the-session-signed-out-or-switched-accounts) |

~~76| `Remote Control stopped — the app running this session is signed out of Claude` | [驗證](#remote-control-stopped-because-the-app-running-the-session-signed-out-or-switched-accounts) |~~76| `Remote Control stopped — the app running this session is signed out of Claude` | [身分驗證](#remote-control-stopped-because-the-app-running-the-session-signed-out-or-switched-accounts) |

77| `Couldn't verify your organization's policy for remote control` | [疑難排解 Remote Control](/docs/zh-TW/remote-control#couldnt-verify-your-organizations-policy-for-remote-control) |77| `Couldn't verify your organization's policy for remote control` | [疑難排解 Remote Control](/docs/zh-TW/remote-control#couldnt-verify-your-organizations-policy-for-remote-control) |

78| `Remote Control is disabled by your organization's policy` | [疑難排解 Remote Control](/docs/zh-TW/remote-control#remote-control-is-disabled-by-your-organizations-policy) |78| `Remote Control is disabled by your organization's policy` | [疑難排解 Remote Control](/docs/zh-TW/remote-control#remote-control-is-disabled-by-your-organizations-policy) |

79| `Remote Control was turned off by your organization's policy` | [疑難排解 Remote Control](/docs/zh-TW/remote-control#remote-control-was-turned-off-by-your-organizations-policy) |79| `Remote Control was turned off by your organization's policy` | [疑難排解 Remote Control](/docs/zh-TW/remote-control#remote-control-was-turned-off-by-your-organizations-policy) |

~~82| `Your account does not have access to Claude. Please login again or contact your administrator.` | [驗證](#oauth-token-revoked-or-expired) |~~82| `Your account does not have access to Claude. Please login again or contact your administrator.` | [身分驗證](#oauth-token-revoked-or-expired) |

~~89| `Administrator policy requires a Cloud gateway sign-in on this machine` | [驗證](#administrator-policy-requires-a-cloud-gateway-sign-in) |~~89| `Administrator policy requires a Cloud gateway sign-in on this machine` | [身分驗證](#administrator-policy-requires-a-cloud-gateway-sign-in) |

~~91| `Could not refresh your login because another Claude Code process is refreshing it` | [驗證](#could-not-refresh-your-login) |~~91| `Could not refresh your login because another Claude Code process is refreshing it` | [身分驗證](#could-not-refresh-your-login) |

~~92| `Failed to refresh OAuth token: another Claude Code process is refreshing it or exited mid-refresh` | [驗證](#could-not-refresh-your-login) |~~92| `Failed to refresh OAuth token: another Claude Code process is refreshing it or exited mid-refresh` | [身分驗證](#could-not-refresh-your-login) |

~~93| `Your account is on hold and can't use Claude Code. View details or appeal: https://claude.ai/restricted` | [驗證](#your-account-is-on-hold) |~~93| `Your account is on hold and can't use Claude Code. View details or appeal: https://claude.ai/restricted` | [身分驗證](#your-account-is-on-hold) |

~~94| `Your account is on hold and can't sign in to Claude Code. View details or appeal: https://claude.ai/restricted` | [驗證](#your-account-is-on-hold) |~~94| `Your account is on hold and can't sign in to Claude Code. View details or appeal: https://claude.ai/restricted` | [身分驗證](#your-account-is-on-hold) |

~~96| `Anthropic profile login expired · Run /login to use your claude.ai account instead, or re-authenticate the profile` | [驗證](#anthropic-profile-login-expired) |~~96| `Anthropic profile login expired · Run /login to use your claude.ai account instead, or re-authenticate the profile` | [身分驗證](#anthropic-profile-login-expired) |

~~99| `MCP server "<name>" needs you to sign in again (run /mcp to re-authenticate)` | [驗證](#mcp-server-needs-you-to-sign-in-again) |~~99| `MCP server "<name>" needs you to sign in again (run /mcp to re-authenticate)` | [身分驗證](#mcp-server-needs-you-to-sign-in-again) |

100| `rejected the credential from its headersHelper` / `rejected the Authorization header in its config` | [驗證](#mcp-server-needs-you-to-sign-in-again) |100| `rejected the credential from its headersHelper` / `rejected the Authorization header in its config` | [身分驗證](#mcp-server-needs-you-to-sign-in-again) |

101| `MCP server "<name>" needs additional permissions (scope: "<scope>") — run /mcp to re-authenticate` | [驗證](#mcp-server-needs-you-to-sign-in-again) |101| `MCP server "<name>" needs additional permissions (scope: "<scope>") — run /mcp to re-authenticate` | [身分驗證](#mcp-server-needs-you-to-sign-in-again) |

103| `This server's URL is missing or not a valid URL, so sign-in can't start` | [驗證](#mcp-server-url-is-missing-or-not-a-valid-url) |103| `This server's URL is missing or not a valid URL, so sign-in can't start` | [身分驗證](#mcp-server-url-is-missing-or-not-a-valid-url) |

105| `Refusing to send credentials to non-https token endpoint` / `<short-name> from the MCP SDK for <server-url>` | [驗證](#refusing-to-send-credentials-to-non-https-token-endpoint) |105| `Refusing to send credentials to non-https token endpoint` / `<short-name> from the MCP SDK for <server-url>` | [身分驗證](#refusing-to-send-credentials-to-non-https-token-endpoint) |

108| `Sign-in timed out while waiting for you to continue. Try again.` | [驗證](#sign-in-timed-out-while-waiting-for-you-to-continue) |108| `Sign-in timed out while waiting for you to continue. Try again.` | [身分驗證](#sign-in-timed-out-while-waiting-for-you-to-continue) |

115| `Could not load AWS credentials` / `Could not load Google Cloud credentials` | [驗證](#could-not-load-aws-or-google-cloud-credentials) |115| `Could not load AWS credentials` / `Could not load Google Cloud credentials` | [身分驗證](#could-not-load-aws-or-google-cloud-credentials) |

118| `A request to AWS timed out. Check your network and proxy settings, then try again.` | [驗證](#bedrock-setup-verification-timed-out-waiting-for-aws) |118| `A request to AWS timed out. Check your network and proxy settings, then try again.` | [身分驗證](#bedrock-setup-verification-timed-out-waiting-for-aws) |

119| `Could not load the default credentials` on Google Cloud's Agent Platform | [驗證](#could-not-load-aws-or-google-cloud-credentials) |119| 在 Google Cloud 的 Agent Platform 上出現的 `Could not load the default credentials` | [身分驗證](#could-not-load-aws-or-google-cloud-credentials) |

121| `Connection refused —` / `Can't reach the API server —` / `No internet route —` / `Couldn't connect through your proxy` / `Connection dropped`，各以括號中的錯誤代碼結尾 | [網路](#unable-to-connect-to-api) |121| `Connection refused —` / `Can't reach the API server —` / `No internet route —` / `Couldn't connect through your proxy` / `Connection dropped`，各以括號中的錯誤代碼結尾 | [網路](#unable-to-connect-to-api) |

126| `Streaming response ended before any complete data was received` | [網路](#streaming-response-ended-before-any-complete-data-was-received) |126| `Streaming response ended before any complete data was received` | [網路](#streaming-response-ended-before-any-complete-data-was-received) |

127| `Bedrock streaming response has content-type "..."; expected "application/vnd.amazon.eventstream"` | [網路](#bedrock-streaming-response-has-an-unexpected-content-type) |127| `Bedrock streaming response has content-type "..."; expected "application/vnd.amazon.eventstream"` | [網路](#bedrock-streaming-response-has-an-unexpected-content-type) |

133| `403` with `GitHub GraphQL is not available from Claude Code sessions` in a cloud session | [GitHub proxy](/docs/zh-TW/cloud-environments#github-proxy) |133| 在雲端工作階段中出現、帶有 `GitHub GraphQL is not available from Claude Code sessions` 的 `403` | [GitHub 代理伺服器](/docs/zh-TW/cloud-environments#github-proxy) |

134| `The cloud environments service returned an empty response` / `The cloud environments service returned a response in an unexpected format` | [網路](#the-cloud-environments-service-returned-an-empty-or-unexpected-response) |134| `The cloud environments service returned an empty response` / `The cloud environments service returned a response in an unexpected format` | [網路](#the-cloud-environments-service-returned-an-empty-or-unexpected-response) |

136| `N sessions ended while this machine was offline — the environment was cleaned up on the server and can't be resumed.` | [網路](#sessions-ended-while-this-machine-was-offline) |136| `N sessions ended while this machine was offline — the environment was cleaned up on the server and can't be resumed.` | [網路](#sessions-ended-while-this-machine-was-offline) |

141| `Prompt is too long · this conversation is a single exchange` / `A single-exchange conversation cannot be compacted` | [請求錯誤](#prompt-is-too-long) |141| `Prompt is too long · this conversation is a single exchange` / `A single-exchange conversation cannot be compacted` | [請求錯誤](#prompt-is-too-long) |

145| `upstream rejected the request` / `request too large for this upstream` on a Claude apps gateway session | [上游錯誤訊息](/docs/zh-TW/claude-apps-gateway-config#upstream-error-messages) |145| 在 Claude apps gateway 工作階段中出現的 `upstream rejected the request` / `request too large for this upstream` | [上游錯誤訊息](/docs/zh-TW/claude-apps-gateway-config#upstream-error-messages) |

146| `upstream rate limit exceeded` on a Claude apps gateway session | [上游錯誤訊息](/docs/zh-TW/claude-apps-gateway-config#upstream-error-messages) |146| 在 Claude apps gateway 工作階段中出現的 `upstream rate limit exceeded` | [上游錯誤訊息](/docs/zh-TW/claude-apps-gateway-config#upstream-error-messages) |

147| `all upstreams failed (N attempted)` on a Claude apps gateway session | [上游錯誤訊息](/docs/zh-TW/claude-apps-gateway-config#upstream-error-messages) |147| 在 Claude apps gateway 工作階段中出現的 `all upstreams failed (N attempted)` | [上游錯誤訊息](/docs/zh-TW/claude-apps-gateway-config#upstream-error-messages) |

148| `Claude Code may not be enabled for your organization` after a Claude apps gateway sign-in | [Claude apps gateway 疑難排解](/docs/zh-TW/claude-apps-gateway-deploy#troubleshooting) |148| 登入 Claude apps gateway 後出現的 `Claude Code may not be enabled for your organization` | [Claude apps gateway 疑難排解](/docs/zh-TW/claude-apps-gateway-deploy#troubleshooting) |

182| `Invalid encrypted_content in search_result block` / `Invalid encrypted_index in text block` / `Failed to decrypt web search result content` | [請求錯誤](#invalid-encrypted-content-in-search-result-block) |182| `Invalid encrypted_content in search_result block` / `Invalid encrypted_index in text block` / `Failed to decrypt web search result content` | [請求錯誤](#invalid-encrypted-content-in-search-result-block) |

183| `Invalid encrypted_stdout in encrypted_code_execution_result block` | [請求錯誤](#invalid-encrypted-content-in-search-result-block) |183| `Invalid encrypted_stdout in encrypted_code_execution_result block` | [請求錯誤](#invalid-encrypted-content-in-search-result-block) |

186| `Claude Code is unable to respond to this request, which appears to violate our Usage Policy` | [請求錯誤](#usage-policy-refusal) |186| `Claude Code is unable to respond to this request, which appears to violate our Usage Policy` | [請求錯誤](#usage-policy-refusal) |

189| `<model> has safety measures that flagged this message for a cybersecurity topic` | [請求錯誤](#safety-measures-flagged-a-cybersecurity-topic) |189| `<model> has safety measures that flagged this message for a cybersecurity topic` | [請求錯誤](#safety-measures-flagged-a-cybersecurity-topic) |

192| `Installation was killed before it could finish (exit code 137)` | [安裝錯誤](#installation-was-killed-before-it-could-finish) |192| `Installation was killed before it could finish (exit code 137)` | [疑難排解安裝和登入](/docs/zh-TW/troubleshoot-install#installation-was-killed-before-it-could-finish) |

193| `The connection dropped while downloading the update` | [安裝錯誤](#the-connection-dropped-while-downloading-the-update) |193| `The connection dropped while downloading the update` | [疑難排解安裝和登入](/docs/zh-TW/troubleshoot-install#the-connection-dropped-while-downloading-the-update) |

194| `Download timed out: exceeded the total deadline` | [安裝錯誤](#the-connection-dropped-while-downloading-the-update) |194| `Download timed out: exceeded the total deadline` | [疑難排解安裝和登入](/docs/zh-TW/troubleshoot-install#the-connection-dropped-while-downloading-the-update) |

196| `Error: Cannot use both --append-subagent-system-prompt and --append-subagent-system-prompt-file. Please use only one.` | [命令列錯誤](#conflict-between-a-system-prompt-flag-and-its-file-form) |196| `Error: Cannot use both --append-subagent-system-prompt and --append-subagent-system-prompt-file. Please use only one.` | [命令列錯誤](#conflict-between-a-system-prompt-flag-and-its-file-form) |

197| `Cloud sessions cannot be created from a --restricted session` | [命令列錯誤](#cloud-sessions-cannot-be-created-from-a-restricted-session) |197| `Cloud sessions cannot be created from a --restricted session` | [命令列錯誤](#cloud-sessions-cannot-be-created-from-a-restricted-session) |

206| `The current directory no longer exists (it was deleted or moved)` / `Can't read the current directory` | [命令列錯誤](#the-current-directory-no-longer-exists) |206| `The current directory no longer exists (it was deleted or moved)` / `Can't read the current directory` | [命令列錯誤](#the-current-directory-no-longer-exists) |

207| `Temp directory <dir> ... Refusing to use it` / `ENOSPC: no space left on device, mkdir '<dir>'` | [命令列錯誤](#temp-directory-refused-or-cannot-be-created) |207| `Temp directory <dir> ... Refusing to use it` / `ENOSPC: no space left on device, mkdir '<dir>'` | [命令列錯誤](#temp-directory-refused-or-cannot-be-created) |

208| `couldn't be resolved to a real location, so its skills, commands, and agents weren't loaded` | [命令列錯誤](#directory-couldnt-be-resolved-to-a-real-location) |208| `couldn't be resolved to a real location, so its skills, commands, and agents weren't loaded` | [命令列錯誤](#directory-couldnt-be-resolved-to-a-real-location) |

209| `Error: Workspace not trusted` when starting Remote Control | [命令列錯誤](#workspace-not-trusted-when-starting-remote-control) |209| 啟動 Remote Control 時出現的 `Error: Workspace not trusted` | [命令列錯誤](#workspace-not-trusted-when-starting-remote-control) |

210| `` `<flag>` before `remote-control` is not carried over to the sessions Remote Control starts `` | [命令列錯誤](#not-carried-over-to-the-sessions-remote-control-starts) |210| `` `<flag>` before `remote-control` is not carried over to the sessions Remote Control starts `` | [命令列錯誤](#not-carried-over-to-the-sessions-remote-control-starts) |

221| `Error: MCP tool <name> (passed via --permission-prompt-tool) not found` | [命令列錯誤](#mcp-permission-prompt-tool-not-found) |221| `Error: MCP tool <name> (passed via --permission-prompt-tool) not found` | [命令列錯誤](#mcp-permission-prompt-tool-not-found) |

222| `OAuth callback port <port> is already in use — another process may be holding it` | [命令列錯誤](#oauth-callback-port-is-already-in-use) |222| `OAuth callback port <port> is already in use — another process may be holding it` | [命令列錯誤](#oauth-callback-port-is-already-in-use) |

224| `Shell command failed for pattern "..."`, from `/security-review` or any skill that injects dynamic context | [命令列錯誤](#security-review-fails-without-origin-head) |224| 來自 `/security-review` 或任何注入動態上下文之 skill 的 `Shell command failed for pattern "..."` | [命令列錯誤](#security-review-fails-without-origin-head) |

225| `Shell command permission check failed for pattern "..."`, from a skill that injects dynamic context | [命令列錯誤](#security-review-fails-without-origin-head) |225| 來自注入動態上下文之 skill 的 `Shell command permission check failed for pattern "..."` | [命令列錯誤](#security-review-fails-without-origin-head) |

226| ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found`` | [命令列錯誤](#security-review-fails-without-origin-head) |226| ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found`` | [命令列錯誤](#security-review-fails-without-origin-head) |

227| `Input must be provided either through stdin or as a prompt argument when using --print` | [命令列錯誤](#input-must-be-provided-when-using-print) |227| `Input must be provided either through stdin or as a prompt argument when using --print` | [命令列錯誤](#input-must-be-provided-when-using-print) |

228| `Claude Code can't read the keyboard here: stdin is not a terminal` | [命令列錯誤](#claude-code-cant-read-the-keyboard-here) |228| `Claude Code can't read the keyboard here: stdin is not a terminal` | [命令列錯誤](#claude-code-cant-read-the-keyboard-here) |

230| `Blank prompt — the message was only whitespace, so nothing was sent to the model.` | [命令列錯誤](#input-contained-only-whitespace) |230| `Blank prompt — the message was only whitespace, so nothing was sent to the model.` | [命令列錯誤](#input-contained-only-whitespace) |

231| `Error: stream-json input carried over 256M characters with no newline` | [命令列錯誤](#stream-json-input-carried-over-256m-characters-with-no-newline) |231| `Error: stream-json input carried over 256M characters with no newline` | [命令列錯誤](#stream-json-input-carried-over-256m-characters-with-no-newline) |

233| `Diff is too large for ultrareview` / `PR #<N> is too large for ultrareview` | [命令列錯誤](#diff-is-too-large-for-ultrareview) |233| `Diff is too large for ultrareview` / `PR #<N> is too large for ultrareview` | [命令列錯誤](#diff-is-too-large-for-ultrareview) |

236| `Ultrareview clones <owner>/<repo> in the cloud with the GitHub account connected to your Claude account, and none is connected` | [命令列錯誤](#no-github-account-is-connected-to-your-claude-account) |236| `Ultrareview clones <owner>/<repo> in the cloud with the GitHub account connected to your Claude account, and none is connected` | [命令列錯誤](#no-github-account-is-connected-to-your-claude-account) |

237| `Your connected GitHub account can't see <owner>/<repo>` | [命令列錯誤](#your-connected-github-account-cant-see-the-repository) |237| `Your connected GitHub account can't see <owner>/<repo>` | [命令列錯誤](#your-connected-github-account-cant-see-the-repository) |

238| `The GitHub App preflight failed transiently (network or service hiccup) — retry in a moment to start from GitHub instead` | [命令列錯誤](#the-github-app-preflight-failed-transiently) |238| `The GitHub App preflight failed transiently (network or service hiccup) — retry in a moment to start from GitHub instead` | [命令列錯誤](#the-github-app-preflight-failed-transiently) |

239| `Not uploading this working tree` with `the upload cannot follow that setting` | [命令列錯誤](#the-repository-upload-cant-follow-a-git-setting) |239| 帶有 `the upload cannot follow that setting` 的 `Not uploading this working tree` | [命令列錯誤](#the-repository-upload-cant-follow-a-git-setting) |

240| `GitHub isn't connected to your Claude account, so this repository can't be cloned in the cloud` | [命令列錯誤](#github-isnt-connected-to-your-claude-account) |240| `GitHub isn't connected to your Claude account, so this repository can't be cloned in the cloud` | [命令列錯誤](#github-isnt-connected-to-your-claude-account) |

241| `Your GitHub organization has an IP allowlist that is blocking Claude` | [命令列錯誤](#a-github-organization-policy-is-blocking-claude) |241| `Your GitHub organization has an IP allowlist that is blocking Claude` | [命令列錯誤](#a-github-organization-policy-is-blocking-claude) |

255| `Custom output styles can't be selected over Remote Control or from a relayed message` | [命令列錯誤](#custom-output-styles-cant-be-selected-over-remote-control) |255| `Custom output styles can't be selected over Remote Control or from a relayed message` | [命令列錯誤](#custom-output-styles-cant-be-selected-over-remote-control) |

256| `Output styles are saved to local settings (.claude/settings.local.json), which this session doesn't load` | [命令列錯誤](#output-styles-are-saved-to-local-settings-which-this-session-doesnt-load) |256| `Output styles are saved to local settings (.claude/settings.local.json), which this session doesn't load` | [命令列錯誤](#output-styles-are-saved-to-local-settings-which-this-session-doesnt-load) |

257| `/recap only runs when you ask for it yourself in this session` | [命令列錯誤](#recap-only-runs-when-you-ask-for-it-yourself) |257| `/recap only runs when you ask for it yourself in this session` | [命令列錯誤](#recap-only-runs-when-you-ask-for-it-yourself) |

258| `` `plugin eval` is currently in early access `` / `` `plugin eval` is currently unavailable `` | [Plugin 錯誤](#plugin-eval-is-currently-in-early-access) |258| `` `plugin eval` is currently in early access `` / `` `plugin eval` is currently unavailable `` | [外掛錯誤](#plugin-eval-is-currently-in-early-access) |

259| `Marketplace "<name>" is registered from an untrusted source` | [Plugin 錯誤](#marketplace-is-registered-from-an-untrusted-source) |259| `Marketplace "<name>" is registered from an untrusted source` | [外掛錯誤](#marketplace-is-registered-from-an-untrusted-source) |

261| `Marketplace name impersonates an official Anthropic/Claude marketplace` | [Plugin 錯誤](#claude-code-refuses-the-marketplace-name) |261| `Marketplace name impersonates an official Anthropic/Claude marketplace` | [外掛錯誤](#claude-code-refuses-the-marketplace-name) |

262| `Marketplace "<name>" is already added from a different source` | [Plugin 錯誤](#marketplace-is-already-added-from-a-different-source) |262| `Marketplace "<name>" is already added from a different source` | [外掛錯誤](#marketplace-is-already-added-from-a-different-source) |

263| `"<name>" is another spelling of "<reserved>", a reserved marketplace name` | [Plugin 錯誤](#marketplace-name-is-another-spelling-of-a-reserved-name) |263| `"<name>" is another spelling of "<reserved>", a reserved marketplace name` | [外掛錯誤](#marketplace-name-is-another-spelling-of-a-reserved-name) |

264| `Marketplace "<name>" is added but ignored` | [Plugin 疑難排解](/docs/zh-TW/plugins/troubleshooting#marketplace-is-added-but-ignored) |264| `Cannot add marketplace "<name>": Claude Code cannot install plugins from a marketplace with this name` | [外掛疑難排解](/docs/zh-TW/plugins/troubleshooting#cannot-install-plugins-from-a-marketplace-with-this-name) |

265| `Marketplace "<name>" is registered but was refused (see the debug log)` | [Plugin 疑難排解](/docs/zh-TW/plugins/troubleshooting#marketplace-is-added-but-ignored) |265| `Marketplace "<name>" is added but ignored` | [外掛疑難排解](/docs/zh-TW/plugins/troubleshooting#marketplace-is-added-but-ignored) |

266| `references ${user_config.*} in a shell-form command` | [Plugin 錯誤](#plugin-command-references-user-config) |266| `Marketplace "<name>" is registered but was refused (see the debug log)` | [外掛疑難排解](/docs/zh-TW/plugins/troubleshooting#marketplace-is-added-but-ignored) |

267| `Monitor "<name>" from plugin <plugin> references ${user_config.*} in its command` | [Plugin 錯誤](#plugin-command-references-user-config) |267| `references ${user_config.*} in a shell-form command` | [外掛錯誤](#plugin-command-references-user-config) |

268| `headersHelper for MCP server '<name>' references ${user_config.*}` | [Plugin 錯誤](#plugin-command-references-user-config) |268| `Monitor "<name>" from plugin <plugin> references ${user_config.*} in its command` | [外掛錯誤](#plugin-command-references-user-config) |

269| `Plugin archive integrity check failed` | [Plugin 錯誤](#plugin-archive-integrity-check-failed) |269| `headersHelper for MCP server '<name>' references ${user_config.*}` | [外掛錯誤](#plugin-command-references-user-config) |

270| `An npm plugin source must name a registry package` | [Plugin 疑難排解](/docs/zh-TW/plugins/troubleshooting#an-npm-plugin-source-must-name-a-registry-package) |270| `Plugin archive integrity check failed` | [外掛錯誤](#plugin-archive-integrity-check-failed) |

271| `The packages it lists are not installed` / `The packages it lists were not installed, because` | [Plugin 疑難排解](/docs/zh-TW/plugins/troubleshooting#the-packages-it-lists-are-not-installed) |271| `An npm plugin source must name a registry package` | [外掛疑難排解](/docs/zh-TW/plugins/troubleshooting#an-npm-plugin-source-must-name-a-registry-package) |

272| `path escapes plugin directory` | [Plugin 錯誤](#path-escapes-plugin-directory) |272| `The packages it lists are not installed` / `The packages it lists were not installed, because` | [外掛疑難排解](/docs/zh-TW/plugins/troubleshooting#the-packages-it-lists-are-not-installed) |

276| `Failed to load marketplace configuration` | [Plugin 錯誤](#failed-to-load-marketplace-configuration) |276| `its marketplace entry path does not stay inside the marketplace directory` | [外掛錯誤](#marketplace-entry-path-does-not-stay-inside-the-marketplace-directory) |

280| `"<plugin>" was not uninstalled: <file> is there and could not be read` | [Plugin 錯誤](#plugin-was-not-uninstalled) |280| `Plugin "<name>@synced" is required by your organization and can't be disabled here` | [外掛錯誤](#plugin-is-required-by-your-organization) |

281| `Plugin "<plugin>" was not uninstalled: installed_plugins.json` | [Plugin 疑難排解](/docs/zh-TW/plugins/troubleshooting#installed-plugins-json-holds-a-record-this-version-cannot-read) |281| `"<plugin>" was not uninstalled: it is still switched on in <file>` | [外掛錯誤](#plugin-was-not-uninstalled) |

282| `"<plugin>" was not uninstalled: <file> is there and could not be read` | [外掛錯誤](#plugin-was-not-uninstalled) |

283| `Plugin "<plugin>" was not uninstalled: installed_plugins.json` | [外掛疑難排解](/docs/zh-TW/plugins/troubleshooting#installed-plugins-json-holds-a-record-this-version-cannot-read) |

284| `Plugin directory does not exist: <path>` | [外掛疑難排解](/docs/zh-TW/plugins/troubleshooting#plugin-directory-does-not-exist) |

338| `Couldn't start a background session (working directory no longer exists or is not accessible: ...)` | [背景工作階段錯誤](#working-directory-no-longer-exists-when-starting-a-background-session) |341| `Couldn't start a background session (working directory no longer exists or is not accessible: ...)` | [背景工作階段錯誤](#working-directory-no-longer-exists-when-starting-a-background-session) |

339| `Workspace not trusted.` when starting or restarting a background session | [背景工作階段錯誤](#workspace-not-trusted-when-dispatching-a-background-session) |342| 啟動或重新啟動背景工作階段時出現的 `Workspace not trusted.` | [背景工作階段錯誤](#workspace-not-trusted-when-dispatching-a-background-session) |

340| `Claude Code is being updated by npm on this machine (still not runnable after 2 min, ...)` | [背景工作階段錯誤](#eacces-when-starting-a-background-session) |343| `Claude Code is being updated by npm on this machine (still not runnable after 2 min, ...)` | [背景工作階段錯誤](#eacces-when-starting-a-background-session) |

342| `The connection to Claude Code ended before this message completed` | [包裝程式和 IDE 錯誤](#the-connection-to-claude-code-ended-before-this-message-completed) |345| `The connection to Claude Code ended before this message completed` | [包裝程式和 IDE 錯誤](#the-connection-to-claude-code-ended-before-this-message-completed) |

386* 在 Claude 完成思考之後、但在開始任何文字或工具呼叫之前到達的伺服器錯誤或過載回應。Claude Code 會在該點重試伺服器錯誤最多兩次。在 v2.1.284 之前，Claude Code 會在該點以錯誤結束回合。389* 在 Claude 完成思考之後、但在開始任何文字或工具呼叫之前到達的伺服器錯誤或過載回應。Claude Code 會在該點重試伺服器錯誤最多兩次。在 v2.1.284 之前，Claude Code 會在該點以錯誤結束回合。

387* 連線中斷。當連線在 Claude 完成其回應的任何部分（包括其思考）之前中途中斷時，Claude Code 會以相同的退避方式重新發出請求，並且回合會繼續，即使某些文字已經開始串流。當連線在 Claude 完成思考之後但在開始任何文字或工具呼叫之前中斷時，Claude Code 會改為快速連續重新發出請求最多兩次，如果連線在該點持續中斷，則以 `Connection lost before a response was produced` 結束回合。390* 連線中斷。當連線在 Claude 完成其回應的任何部分（包括其思考）之前中途中斷時，Claude Code 會以相同的退避方式重新發出請求，並且回合會繼續，即使某些文字已經開始串流。當連線在 Claude 完成思考之後但在開始任何文字或工具呼叫之前中斷時，Claude Code 會改為快速連續重新發出請求最多兩次，如果連線在該點持續中斷，則以 `Connection lost before a response was produced` 結束回合。

388* Claude Code 偵測到的連線在您的電腦進入睡眠狀態時在請求中途被中斷。Claude Code 將其計為上述規則下的連線中斷；一旦重試標籤命名了具體原因，它會讀作 `Connection lost while your computer was asleep`，如果回合在 Claude 完成思考但在任何文字或工具呼叫之前結束，訊息會讀作 `Your computer went to sleep before a response was produced`。391* Claude Code 偵測到的連線在您的電腦進入睡眠狀態時在請求中途被中斷。Claude Code 將其計為上述規則下的連線中斷；一旦重試標籤命名了具體原因，它會讀作 `Connection lost while your computer was asleep`，如果回合在 Claude 完成思考但在任何文字或工具呼叫之前結束，訊息會讀作 `Your computer went to sleep before a response was produced`。

389* 停滯的回應串流，當回應標頭已到達但 Claude 回應的任何部分都未到達，或當 Claude 完成思考但尚未開始任何文字或工具呼叫時：Claude Code 會中止停滯的連線，並最多重新發出一次請求，不在上述 10 次嘗試預算內。如果在 Claude 完成思考但在任何文字或工具呼叫之前回應停滯第二次，Claude Code 會以 `The response stalled before a response was produced` 結束回合。392* 停滯的回應串流，當回應標頭已到達但 Claude 回應的任何部分都未到達，或當 Claude 完成思考但尚未開始任何文字或工具呼叫時：Claude Code 會中止停滯的連線，並最多再以串流方式發出一次請求。如果在 Claude 完成思考但在任何文字或工具呼叫之前回應停滯第二次，Claude Code 會以 `The response stalled before a response was produced` 結束回合。

390* 串流請求 API 從未以回應標頭回答，在 [first-byte deadline 執行](/docs/zh-TW/network-config#streaming-idle-watchdogs) 的連線上：Claude Code 在截止時間中止它，並在重試預算內最多每個模型請求重新發送一次，然後如果該嘗試也未獲得回答，則以 [No response from API](#no-response-from-api) 結束回合。在其他連線上，請求會等待 `API_TIMEOUT_MS`。當您設定 `CLAUDE_CODE_RETRY_WATCHDOG` 時，一次重試上限不適用。393* 串流請求 API 從未以回應標頭回答，在 [first-byte deadline 執行](/docs/zh-TW/network-config#streaming-idle-watchdogs) 的連線上：Claude Code 在截止時間中止它，並在重試預算內最多每個模型請求重新發送一次，然後如果該嘗試也未獲得回答，則以 [No response from API](#no-response-from-api) 結束回合。在其他連線上，請求會等待 `API_TIMEOUT_MS`。當您設定 `CLAUDE_CODE_RETRY_WATCHDOG` 時，一次重試上限不適用。

391* 在 Claude 完成思考或開始任何文字或工具呼叫之前，被 API 輸出內容過濾器停止的串流回應。Claude Code 會在重試預算內重新發送請求一次，如果過濾器也停止了第二個回應，則顯示 [Output blocked by content filtering policy](#output-blocked-by-content-filtering-policy)。394* 在 Claude 完成思考或開始任何文字或工具呼叫之前，被 API 輸出內容過濾器停止的串流回應。Claude Code 會在重試預算內重新發送請求一次，如果過濾器也停止了第二個回應，則顯示 [Output blocked by content filtering policy](#output-blocked-by-content-filtering-policy)。

392* 暫時性 429 節流，但不是閘道的支出限制 `429`，這不是節流；請參閱 [Spend limit reached](#spend-limit-reached)。395* 暫時性 429 節流，但不是閘道的支出限制 `429`，這不是節流；請參閱 [Spend limit reached](#spend-limit-reached)。

2910* 重新措辭您的最後一則訊息，或採取不同的方法2913* 重新措辭您的最後一則訊息，或採取不同的方法

2911* 若要回到觸發封鎖的回合之前的檢查點，請按 Esc 兩次或執行 `/rewind`。請參閱[檢查點功能](/docs/zh-TW/checkpointing)2914* 若要回到觸發封鎖的回合之前的檢查點，請按 Esc 兩次或執行 `/rewind`。請參閱[檢查點功能](/docs/zh-TW/checkpointing)

2912 2915

2913<h2 id="installation-errors">

2914 安裝錯誤

2915</h2>

~~2916~~

2917這些錯誤會在安裝或更新 Claude Code 時出現，來自 [安裝指令碼](/docs/zh-TW/setup#install-claude-code)、`claude install` 或 `claude update`。如需 `command not found`、PATH、權限和設定期間的 TLS 問題，請參閱 [疑難排解安裝和登入](/docs/zh-TW/troubleshoot-install)。

~~2918~~

2919<h3 id="installation-was-killed-before-it-could-finish">

2920 安裝在完成前被中止

2921</h3>

~~2922~~

2923安裝指令碼會在 `claude install` 步驟被信號終止時報告。在 Linux 上，結束代碼 137 表示程序收到 SIGKILL，在低記憶體主機上通常是核心記憶體不足 (OOM) 殺手。指令碼會列印此說明並以代碼 137 結束：

~~2924~~

2925```text theme={null}

2926Installation was killed before it could finish (exit code 137). This usually means the system ran out of memory.

2927Claude Code needs roughly 512MB of free memory to install. Free up memory, then run this script again.

2928```

~~2929~~

2930對於任何其他致命信號，以及 macOS 上的結束代碼 137，指令碼會列印 `Installation was killed before it could finish (exit code <N>)`，其中包含實際結束代碼，並省略記憶體不足的說明。該訊息來自 macOS 和 Linux 使用的安裝指令碼，也涵蓋 WSL 內的安裝；原生 Windows 安裝指令碼永遠不會列印它。在 v2.1.200 之前，指令碼只以 shell 的裸 `Killed` 行結束。

~~2931~~

2932**該怎麼做：**

~~2933~~

2934* 停止其他程序以釋放記憶體，然後重新執行安裝程式

2935* 新增交換空間或移至更大的執行個體。請參閱 [在低記憶體 Linux 伺服器上安裝被中止](/docs/zh-TW/troubleshoot-install#install-killed-on-low-memory-linux-servers) 以取得交換檔案命令。

~~2936~~

2937<h3 id="the-connection-dropped-while-downloading-the-update">

2938 下載更新時連線中斷

2939</h3>

~~2940~~

2941在 `claude install` 或 `claude update` 擷取 Claude Code 二進位檔案時，與下載伺服器的連線已關閉，且重試未能復原。Claude Code 會在連線中斷、傳輸停滯或下載的檔案未通過總和檢查時重試下載，總共最多三次嘗試。已完成的 HTTP 錯誤（例如 404）不會重試，因為伺服器已經回應。在 v2.1.202 之前，單一連線中斷會立即導致下載失敗，並顯示裸錯誤 `aborted`，而不是重試。

~~2942~~

2943```text theme={null}

2944The connection dropped while downloading the update (attempt 3/3: aborted). Check your network — proxies sometimes cut off large downloads.

2945```

~~2946~~

2947括號中的文字命名失敗的嘗試和基礎網路錯誤。`claude update` 在 stderr 上以 `Error: Failed to install native update` 開頭該訊息。

~~2948~~

2949保持連線但未在 10 分鐘內完成的下載會失敗，並顯示 `Download timed out: exceeded the total deadline`。Claude Code 不會重試逾時的下載，因為連線太慢而無法在期限內完成，在立即重試時也不會完成。以下步驟適用於兩個訊息。

~~2950~~

2951代理或閘道可以在長傳輸完成前關閉它，而 Claude Code 二進位檔案是大型下載。

~~2952~~

2953**該怎麼做：**

~~2954~~

2955* 再次執行 `claude update`。在網路狀況良好的情況下，下載通常在下次執行時成功。對於逾時訊息，請從更快或限制較少的網路重新執行。

2956* 如果您的網路需要代理，請在執行安裝程式或 `claude update` 之前設定 `HTTPS_PROXY`。請參閱 [檢查網路連線](/docs/zh-TW/troubleshoot-install#check-network-connectivity)。

2957* 如果公司代理持續關閉傳輸，請要求您的網路團隊允許從 `downloads.claude.ai` 進行完整下載。請參閱 [網路存取需求](/docs/zh-TW/network-config#network-access-requirements)。

2958* 從您的 shell 執行 `claude doctor` 以進行安裝診斷

~~2959~~

2960<h2 id="command-line-errors">2916<h2 id="command-line-errors">

2961 命令列錯誤2917 命令列錯誤

2962</h2>2918</h2>

3990`plugin eval` is currently unavailable3946`plugin eval` is currently unavailable

3991```3947```

3992 3948

3993第一則訊息表示您的組建版本早於 v2.1.269，這是該命令正式推出的第一個版本。第二則訊息表示 Anthropic 已在伺服器端關閉該命令；您的機器上沒有任何設定可以將其重新開啟。3949第一則訊息表示您的建置版本早於 v2.1.269，這是該命令正式推出的第一個版本。第二則訊息表示 Anthropic 已在伺服器端關閉該命令；您的機器上沒有任何設定可以將其重新開啟。

3994 3950

3995**該怎麼做：**3951**該怎麼做：**

3996 3952

3997* 執行 `claude --version`，然後執行 `claude update`，並在新的工作階段中再次執行該命令。請參閱 [plugin evals 的需求](/docs/zh-TW/plugin-evals#requirements)3953* 執行 `claude --version`，然後執行 `claude update`，並在新的工作階段中再次執行該命令。請參閱 [plugin evals 的需求](/docs/zh-TW/plugin-evals#requirements)

3998* 如果您在目前的組建版本上看到第二則訊息，請在執行另一個 `claude update` 後稍後再試一次3954* 如果您在目前的建置版本上看到第二則訊息，請在執行另一個 `claude update` 後稍後再試一次

3999 3955

4000<h3 id="marketplace-is-registered-from-an-untrusted-source">3956<h3 id="marketplace-is-registered-from-an-untrusted-source">

4001 Marketplace 是從不受信任的來源註冊的3957 Marketplace 是從不受信任的來源註冊的

4002</h3>3958</h3>

4003 3959

4004Marketplace 是以 [為官方 Anthropic marketplace 保留的名稱](/docs/zh-TW/plugins/marketplace-reference#marketplace-file) 註冊的，但其註冊的來源不是 `anthropics` GitHub 儲存庫。Claude Code 每次載入或重新整理 marketplace 時都會重新檢查保留的名稱，因此 marketplace 及從中安裝的 plugin 會停止載入。在 v2.1.205 之前，名稱只在新增 marketplace 時檢查，因此在其名稱變成保留名稱之前註冊的項目會繼續載入。3960Marketplace 是以 [為官方 Anthropic marketplace 保留的名稱](/docs/zh-TW/plugins/marketplace-reference#marketplace-file) 註冊的，但其註冊的來源不是 `anthropics` GitHub 儲存庫。Claude Code 每次載入或重新整理 marketplace 時都會重新檢查保留的名稱，因此 marketplace 及從中安裝的 plugin 會停止載入。在 v2.1.205 之前，在其名稱變成保留名稱之前註冊的項目會繼續載入。

4005 3961

4006```text theme={null}3962```text theme={null}

4007Marketplace "claude-community" is registered from an untrusted source: The name 'claude-community' is reserved for official Anthropic marketplaces. Only repositories from 'github.com/anthropics/' can use this name. To fix it, remove the marketplace and re-add it from the official source.3963Marketplace "claude-community" is registered from an untrusted source: The name 'claude-community' is reserved for official Anthropic marketplaces. Only repositories from 'github.com/anthropics/' can use this name. To fix it, remove the marketplace and re-add it from the official source.

4019 Marketplace 名稱是保留名稱的另一種拼寫3975 Marketplace 名稱是保留名稱的另一種拼寫

4020</h3>3976</h3>

4021 3977

4022Marketplace 的名稱本身不是保留名稱，但 Claude Code 將其視為另一種拼寫。[保留的 marketplace 名稱](/docs/zh-TW/plugins/marketplace-reference#reserved-name-spellings) 列出哪些拼寫算作保留名稱。Claude Code 在您新增 marketplace 時拒絕這樣的名稱：3978Marketplace 的名稱本身不是保留名稱，但 Claude Code 將其視為某個保留名稱的另一種拼寫。[保留名稱](/docs/zh-TW/plugins/marketplace-reference#reserved-name-spellings) 列出哪些拼寫算作保留名稱。Claude Code 在您新增 marketplace 時拒絕這樣的名稱：

4023 3979

4024```text theme={null}3980```text theme={null}

4025Failed to add marketplace: "claude.code.plugins" is another spelling of "claude-code-plugins", a reserved marketplace name.3981Failed to add marketplace: "claude.code.plugins" is another spelling of "claude-code-plugins", a reserved marketplace name.

4064 Marketplace 已從不同的來源新增4020 Marketplace 已從不同的來源新增

4065</h3>4021</h3>

4066 4022

4067您透過 [`/plugin install <plugin> --marketplace <source>`](/docs/zh-TW/plugins/install#add-a-marketplace-and-install-in-one-command) 確認新增 marketplace，而 Claude Code 從該來源擷取的目錄將自己命名為與您已從不同來源新增的 marketplace 相同的名稱。Claude Code 保留現有的 marketplace 而不是替換它，plugin 不會被安裝。4023您在工作階段中或從 shell 使用 [安裝命令上的 `--marketplace <source>`](/docs/zh-TW/plugins/install#add-a-marketplace-and-install-in-one-command) 指定了新的 marketplace 來源。Claude Code 從該來源擷取的目錄，與您已從不同來源新增的 marketplace 名稱相同。Claude Code 保留現有的 marketplace 而不是替換它，plugin 不會被安裝。

4068 4024

4069```text theme={null}4025```text theme={null}

4070Marketplace "acme-tools" is already added from a different source (github:acme/plugins). To use this source instead, remove that marketplace first with /plugin marketplace remove acme-tools.4026Marketplace "acme-tools" is already added from a different source (github:acme/plugins). To use this source instead, remove that marketplace first with /plugin marketplace remove acme-tools.

4137 4093

4138在 `claude plugin` 命令輸出中，相同的錯誤讀作 `Path escapes plugin directory: ./../shared.md (commands)`。4094在 `claude plugin` 命令輸出中，相同的錯誤讀作 `Path escapes plugin directory: ./../shared.md (commands)`。

4139 4095

4140Claude Code 拒絕指向 plugin 外部的路徑（如 `../shared-utils`）和導致 plugin 外部的符號連結，以及 [marketplace 符號連結規則](/docs/zh-TW/plugins/host-marketplace#share-files-within-a-marketplace-with-symlinks) 不允許的符號連結。對於符號連結，訊息也會說明路徑解析的位置：4096Claude Code 會拒絕字面上指向 plugin 外部的路徑（例如 `../shared-utils`），以及導向 plugin 外部且不屬於 [marketplace 符號連結規則](/docs/zh-TW/plugins/host-marketplace#share-files-within-a-marketplace-with-symlinks) 所允許的符號連結。對於符號連結，訊息也會說明路徑解析的位置：

4141 4097

4142```text theme={null}4098```text theme={null}

4143commands path escapes plugin directory: ./commands/deploy.md — it resolves to /home/user/shared/deploy.md, outside the plugin directory4099commands path escapes plugin directory: ./commands/deploy.md — it resolves to /home/user/shared/deploy.md, outside the plugin directory

4144```4100```

4145 4101

4146在 macOS 和 Linux 上，Claude Code 也拒絕包含反斜線的元件路徑，即使路徑保持在 plugin 內。使用 Windows 風格分隔符的元件路徑的 plugin 在 Windows 上載入並在其他平台上觸發此拒絕：4102在 macOS 和 Linux 上，Claude Code 也拒絕任何位置包含反斜線的元件路徑，即使路徑保持在 plugin 內。使用 Windows 風格分隔符的元件路徑的 plugin 在 Windows 上載入並在其他平台上觸發此拒絕：

4147 4103

4148```text theme={null}4104```text theme={null}

4149commands path escapes plugin directory: ./commands\deploy.md — its path contains a backslash, which is not resolved reliably on this platform4105commands path escapes plugin directory: ./commands\deploy.md — its path contains a backslash, which is not resolved reliably on this platform

4150```4106```

4151 4107

4152在 v2.1.251 之前，Claude Code 載入在 marketplace 項目中宣告的 `commands` 路徑，即使它指向 plugin 目錄外。Claude Code 已經拒絕在 `plugin.json` 中宣告的路徑和 marketplace 項目中的其他元件路徑。4108在 v2.1.251 之前，Claude Code 載入在 marketplace 項目中宣告的 `commands` 路徑，即使它指向 plugin 目錄外。

4153 4109

4154在 v2.1.257 之前，檢查只查看路徑的拼寫，而不是符號連結導向的位置。4110在 v2.1.257 之前，檢查只查看路徑的拼寫，而不是符號連結導向的位置。

4155 4111

4217 4173

4218**該怎麼做：**4174**該怎麼做：**

4219 4175

4220* 如果您維護 marketplace，將項目的 `source` 寫成純相對路徑（例如 `./plugins/my-plugin`），並保持它跨越的任何符號連結指向 marketplace 目錄內4176* 如果您維護 marketplace，將項目的 `source` 寫成使用正斜線的純相對路徑（例如 `./plugins/my-plugin`），並保持它跨越的任何符號連結指向 marketplace 目錄內

4221* 如果您從直接 URL 新增了 marketplace，相對項目無法解析。要求 marketplace 作者使用 [另一個 plugin 來源](/docs/zh-TW/plugins/marketplace-reference#plugin-sources)，或改為從其 git 儲存庫新增 marketplace4177* 如果您從直接 URL 新增了 marketplace，相對項目無法解析。要求 marketplace 作者使用 [另一個 plugin 來源](/docs/zh-TW/plugins/marketplace-reference#plugin-sources)，或改為從其 git 儲存庫新增 marketplace

4222 4178

4223<h3 id="failed-to-load-marketplace-configuration">4179<h3 id="failed-to-load-marketplace-configuration">

4226 4182

4227Claude Code 將您新增的 plugin marketplace 保留在 `~/.claude/plugins/known_marketplaces.json` 的登錄檔案中。當 Claude Code 無法使用該檔案時，需要登錄的 plugin 命令（例如 `claude plugin install`）會失敗，並顯示以下兩則訊息之一：4183Claude Code 將您新增的 plugin marketplace 保留在 `~/.claude/plugins/known_marketplaces.json` 的登錄檔案中。當 Claude Code 無法使用該檔案時，需要登錄的 plugin 命令（例如 `claude plugin install`）會失敗，並顯示以下兩則訊息之一：

4228 4184

4229* `Failed to load marketplace configuration`：檔案不是有效的 JSON，或無法讀取。空檔案也會以這種方式失敗。4185* `Failed to load marketplace configuration`：檔案存在，但不是有效的 JSON，或無法讀取。空檔案也會以這種方式失敗。

4230* `Marketplace configuration file is corrupted`：檔案是有效的 JSON，但其內容與登錄架構不符。4186* `Marketplace configuration file is corrupted`：檔案是有效的 JSON，但其內容與登錄 schema 不符。

~~4231~~

4232遺失的檔案不是失敗：Claude Code 將其視為沒有 marketplace 的登錄。

4233 4187

4234使用空檔案時，`claude plugin install` 報告：4188使用空檔案時，`claude plugin install` 報告：

4235 4189

4241 4195

4242**該怎麼做：**4196**該怎麼做：**

4243 4197

4244* 開啟 `~/.claude/plugins/known_marketplaces.json` 並修復 JSON，或修復訊息命名為與登錄架構不符的項目4198* 開啟 `~/.claude/plugins/known_marketplaces.json` 並修復 JSON，或修復訊息命名為與登錄 schema 不符的項目

4245* 如果您無法修復它，刪除檔案或用 `{}` 替換其內容，然後使用 `claude plugin marketplace add <source>` 重新新增每個 marketplace。Claude Code 在您下次在已信任的資料夾中啟動它時，重新註冊您的使用者或受管設定在 [`extraKnownMarketplaces`](/docs/zh-TW/settings-reference#extraknownmarketplaces) 中宣告的 marketplace。4199* 如果您無法修復它，刪除檔案或用 `{}` 替換其內容，然後使用 `claude plugin marketplace add <source>` 重新新增每個 marketplace。Claude Code 在您下次在已信任的資料夾中啟動它時，重新註冊您的使用者或受管設定在 [`extraKnownMarketplaces`](/docs/zh-TW/settings-reference#extraknownmarketplaces) 中宣告的 marketplace。

4246 4200

4247<h3 id="plugin-is-required-by-your-organization">4201<h3 id="plugin-is-required-by-your-organization">

4819 This session has no saved transcript4773 This session has no saved transcript

4820</h3>4774</h3>

4821 4775

4822您附加到已停止的[背景工作階段](/docs/zh-TW/agent-view)，該工作階段使用 `←` 或 `/background` 從另一個對話背景化，並在其第一個回應完成之前停止。在該第一個回應完成之前，對話仍然只存在於背景化它的工作階段中，因此 `claude attach` 拒絕啟動已停止的工作階段，而不是在相同工作階段 ID 下開始空白對話。訊息以此工作階段的 `claude respawn` 命令結尾：4776您附加到一個您以 `←` 或 `/background` [移至背景](/docs/zh-TW/agent-view#from-inside-a-session)、且在執行自己的任何一個回合之前就已停止的工作階段。Claude Code 找不到您將其移出的那個對話，因此該工作階段沒有可繼續的內容。訊息以此工作階段的 `claude respawn` 命令結尾：

4823 4777

4824```text theme={null}4778```text theme={null}

4825This session has no saved transcript — it was stopped before its first response finished. If it was backgrounded from another conversation, that one is still intact; `claude respawn <id>` starts this one fresh.4779This session has no saved transcript — it was stopped before its first response finished. If it was backgrounded from another conversation, that one is still intact; `claude respawn <id>` starts this one fresh.

4829 4783

4830**該怎麼做：**4784**該怎麼做：**

4831 4785

4832* 您背景化的對話完整無缺：使用 [`claude --resume`](/docs/zh-TW/sessions) 繼續它或繼續在其中工作4786* 若要全新重新啟動已停止的工作階段，請使用訊息中的 ID 執行 `claude respawn <id>`，或在 agent 檢視中的其列上按 `Enter` 兩次

4833* 若仍要重新啟動已停止的工作階段，請使用訊息中的 ID 執行 `claude respawn <id>`，或在 agent 檢視中的其列上按 `Enter` 兩次

4834* 如果工作階段確實完成了回應，而您在 v2.1.214 之前的版本上仍看到此拒絕，`~/.claude/projects` 中的不可讀資料夾可能會使逐字稿掃描遺漏已儲存的對話；請更新到 v2.1.214 或更新版本，其在掃描期間容許不可讀資料夾4787* 如果工作階段確實完成了回應，而您在 v2.1.214 之前的版本上仍看到此拒絕，`~/.claude/projects` 中的不可讀資料夾可能會使逐字稿掃描遺漏已儲存的對話；請更新到 v2.1.214 或更新版本，其在掃描期間容許不可讀資料夾

4835 4788

4836<h3 id="this-session-is-running-in-another-terminal">4789<h3 id="this-session-is-running-in-another-terminal">

glossary.md +2 −2

Details

465 465

466一個命令 `/teleport`，它將雲 Claude Code 會話拉入您的本地終端。Claude 獲取分支、載入對話歷史並從雲會話的最後狀態恢復。反向方向是 `--cloud`，它將本地任務發送到雲上執行。466一個命令 `/teleport`，它將雲 Claude Code 會話拉入您的本地終端。Claude 獲取分支、載入對話歷史並從雲會話的最後狀態恢復。反向方向是 `--cloud`，它將本地任務發送到雲上執行。

467 467

468了解更多：[從雲到終端](/docs/zh-TW/claude-code-on-the-web#from-cloud-to-terminal)468了解更多：[在終端機中繼續雲端工作階段](/docs/zh-TW/claude-code-on-the-web#from-cloud-to-terminal)

469 469

470<h3 id="tool">470<h3 id="tool">

471 Tool471 Tool

511 Worktree isolation511 Worktree isolation

512</h3>512</h3>

513 513

514一個隔離模式，在 `.claude/worktrees/` 下的單獨 git worktree 中執行 Claude，使用 `-w` 標誌或 subagent 配置中的 `isolation: worktree` 啟用。更改保留在單獨分支的單獨目錄中，因此並行代理不會覆蓋彼此的檔案。514一種隔離模式，在 `.claude/worktrees/` 下的單獨 git worktree 中執行 Claude，使用 `-w` 旗標或 subagent 設定中的 `isolation: worktree` 啟用。變更保留在單獨目錄中的單獨分支上，因此並行的 agent 各自編輯自己的檔案副本。

515 515

516了解更多：[使用 git worktrees 執行並行會話](/docs/zh-TW/worktrees)516了解更多：[使用 git worktrees 執行並行會話](/docs/zh-TW/worktrees)

517 517

goal.md +1 −1

Details

127claude -p "/goal CHANGELOG.md has an entry for every PR merged this week"127claude -p "/goal CHANGELOG.md has an entry for every PR merged this week"

128```128```

129 129

130使用預設文字輸出時，在執行結束前不會列印任何內容，因此執行許多回合的目標可能看起來卡住了。新增 `--output-format stream-json --verbose` 以在迴圈執行時發出每個訊息。130使用預設文字輸出時，Claude 的最終回應會在迴圈結束時列印，因此執行許多回合的目標可能看起來卡住了。新增 `--output-format stream-json --verbose` 以在迴圈執行時發出每個訊息。

131 131

132使用 Ctrl+C 中斷程序以在目標解決前停止非互動式目標。132使用 Ctrl+C 中斷程序以在目標解決前停止非互動式目標。

133 133

headless.md +18 −16

Details

32claude -p "What does the auth module do?"32claude -p "What does the auth module do?"

33```33```

34 34

35Claude Code 在成功時以代碼 0 退出，在執行失敗時以非零代碼退出，因此您的指令碼可以根據退出狀態進行分支。如果您傳遞無效旗標，Claude Code 會在執行開始前向 stderr 報告錯誤。當執行內部發生失敗（例如缺少驗證）時，Claude Code 會將失敗列印為 stdout 上的結果。35Claude Code 在成功時以代碼 0 退出，在執行失敗時以非零代碼退出，因此您的指令碼可以根據退出狀態進行分支。如果您傳遞無效旗標，Claude Code 會在執行開始前向 stderr 報告錯誤。當執行內部發生失敗（例如缺少身分驗證）時，Claude Code 會將失敗列印為 stdout 上的結果。

36 36

37<h3 id="start-faster-with-bare-mode">37<h3 id="start-faster-with-bare-mode">

~~38 使用裸機模式更快啟動~~38 使用 bare 模式更快啟動

39</h3>39</h3>

40 40

41加上 `--bare` 以跳過 hooks、skills、自訂命令、[subagents](/docs/zh-TW/sub-agents)、已安裝的 plugins、MCP 伺服器、自動記憶和 CLAUDE.md 的自動探索來減少啟動時間。沒有它，`claude -p` 會載入互動工作階段會載入的相同 [context](/docs/zh-TW/how-claude-code-works#the-context-window)，包括在工作目錄或 `~/.claude` 中設定的任何內容。41加上 `--bare` 以跳過 hook、skill、自訂命令、[subagent](/docs/zh-TW/sub-agents)、已安裝的外掛、MCP 伺服器、自動記憶和 CLAUDE.md 的自動探索來減少啟動時間。沒有它，`claude -p` 會載入互動工作階段會載入的相同 [context](/docs/zh-TW/how-claude-code-works#the-context-window)，包括在工作目錄或 `~/.claude` 中設定的任何內容。

42 42

43裸機模式對於 CI 和指令碼很有用，您需要在每台機器上獲得相同的結果。隊友 `~/.claude` 中的 hook 或專案 `.mcp.json` 中的 MCP 伺服器不會執行，因為裸機模式永遠不會讀取它們。您使用 `--add-dir` 命名的目錄是部分例外：裸機模式從其 `.claude/skills/` 資料夾載入 skills，但仍然跳過其 `.claude/commands/` 和 `.claude/agents/` 資料夾。[來自其他目錄的 Skills](/docs/zh-TW/skills#skills-from-additional-directories) 涵蓋了哪些會載入和不會載入。43bare 模式對於 CI 和指令碼很有用，您需要在每台機器上獲得相同的結果。隊友 `~/.claude` 中的 hook 或專案 `.mcp.json` 中的 MCP 伺服器不會執行，因為 bare 模式永遠不會讀取它們。您使用 `--add-dir` 命名的目錄是部分例外：bare 模式從其 `.claude/skills/` 資料夾載入 skill，但仍然跳過其 `.claude/commands/` 和 `.claude/agents/` 資料夾。[來自其他目錄的 Skills](/docs/zh-TW/skills#skills-from-additional-directories) 涵蓋了哪些會載入和不會載入。

44 44

45沒有 `--bare`，`-p` 工作階段會執行專案 `.claude/settings.json` 中的 hooks 並連接其 `.mcp.json` 中的伺服器，即使在您從未信任的資料夾中也是如此。`-p` 工作階段不會顯示工作區信任對話框和每個伺服器的核准提示。[在您信任資料夾之前執行的內容](/docs/zh-TW/permissions#what-runs-before-you-trust-a-folder) 涵蓋了 `-p` 下每種類型的儲存庫內容以及如何將其排除。45沒有 `--bare`，`-p` 工作階段會執行專案 `.claude/settings.json` 中的 hook 並連接其 `.mcp.json` 中的伺服器，即使在您從未信任的資料夾中也是如此。`-p` 工作階段不會顯示工作區信任對話框和每個伺服器的核准提示。[在您信任資料夾之前執行的內容](/docs/zh-TW/permissions#what-runs-before-you-trust-a-folder) 涵蓋了 `-p` 下每種類型的儲存庫內容以及如何將其排除。

46 46

47此範例在裸機模式下執行一次性摘要任務，並預先核准 Read 工具，以便呼叫完成而無需權限提示。執行前設定 `ANTHROPIC_API_KEY`，因為裸機模式不使用您的訂閱登入：47此範例在 bare 模式下執行一次性摘要任務，並預先核准 Read 工具，以便呼叫完成而無需權限提示。執行前設定 `ANTHROPIC_API_KEY`，因為 bare 模式不使用您的訂閱登入：

48 48

49```bash theme={null}49```bash theme={null}

50claude --bare -p "Summarize README.md" --allowedTools "Read"50claude --bare -p "Summarize README.md" --allowedTools "Read"

51```51```

52 52

53在裸機模式下，Claude Code 永遠不會讀取 OAuth 認證或系統鑰匙圈。對於 Anthropic API，在環境中設定 `ANTHROPIC_API_KEY`，使用在 [Claude Console](https://platform.claude.com) 中建立的金鑰，或在 `--settings` JSON 中提供 `apiKeyHelper`。Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 繼續照常讀取各自的提供者認證。53在 bare 模式下，Claude Code 永遠不會讀取 OAuth 憑證或系統鑰匙圈。對於 Anthropic API，在環境中設定 `ANTHROPIC_API_KEY`，使用在 [Claude Console](https://platform.claude.com) 中建立的金鑰，或在 `--settings` JSON 中提供 `apiKeyHelper`。Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 繼續照常讀取各自的提供者憑證。

54 54

~~55在裸機模式下，Claude 可以存取 Bash、檔案讀取和檔案編輯工具。使用旗標傳遞您需要的任何 context：~~55在 bare 模式下，Claude 可以存取 Bash、檔案讀取和檔案編輯工具。使用旗標傳遞您需要的任何 context：

56 56

57| 要載入 | 使用 |57| 要載入 | 使用 |

58| - | - |58| - | - |

60| 設定 | `--settings <file-or-json>` |60| 設定 | `--settings <file-or-json>` |

61| MCP 伺服器 | `--mcp-config <file-or-json>` |61| MCP 伺服器 | `--mcp-config <file-or-json>` |

62| [自訂 agent](/docs/zh-TW/sub-agents#choose-the-subagent-scope) | `--agents <file-or-json>` |62| [自訂 agent](/docs/zh-TW/sub-agents#choose-the-subagent-scope) | `--agents <file-or-json>` |

64 64

65bare 模式也會限制工作階段執行期間發生的事情：65bare 模式也會限制工作階段執行期間發生的事情：

66 66

84 84

85執行會等待背景工作，例如背景命令、subagent 和工作流程、Monitor 監視，以及待處理的 `/loop` 喚醒：85執行會等待背景工作，例如背景命令、subagent 和工作流程、Monitor 監視，以及待處理的 `/loop` 喚醒：

86 86

87* **[背景命令](/docs/zh-TW/tools-reference#background-commands)**：對於主對話啟動的命令，例如開發伺服器或監視建置，執行會等待直到該命令退出或達到其 [時間限制](/docs/zh-TW/tools-reference#time-limit-for-background-commands)。接著 Claude 會依據結果再進行一個回合，而該回合的結果會成為執行的最後一個結果，也就是 `text` 和 `json` 輸出所列印的結果。在命令執行期間，10 分鐘上限不會結束等待。87* **[背景命令](/docs/zh-TW/tools-reference#background-commands)**：對於主對話啟動的命令，例如開發伺服器或監視建置，執行會等待直到該命令退出或達到其 [時間限制](/docs/zh-TW/tools-reference#time-limit-for-background-commands)。接著 Claude 會依據結果再進行一個回合。在命令執行期間，10 分鐘上限不會結束等待。

88* **背景 [subagent](/docs/zh-TW/sub-agents) 和工作流程**：執行會保持開啟，直到該工作完成，因為其結果是最終輸出的一部分。88* **背景 [subagent](/docs/zh-TW/sub-agents) 和工作流程**：執行會保持開啟，直到該工作完成，因為其結果是最終輸出的一部分。

89* **[Monitor](/docs/zh-TW/tools-reference#monitor-tool) 監視**：執行會等待直到監視逾時或 10 分鐘上限結束等待，以先發生者為準。在等待期間，Claude 會持續回應監視報告的內容。預設情況下，監視在 Claude 啟動後五分鐘逾時。89* **[Monitor](/docs/zh-TW/tools-reference#monitor-tool) 監視**：執行會等待直到監視逾時或 10 分鐘上限結束等待，以先發生者為準。在等待期間，Claude 會持續回應監視報告的內容。預設情況下，監視在 Claude 啟動後五分鐘逾時。

90* **待處理的喚醒**：在以文字傳遞提示詞（而非使用 `--input-format stream-json`）的執行中，當 Claude 已排定 [自訂節奏的 `/loop` 喚醒](/docs/zh-TW/scheduled-tasks#let-claude-choose-the-interval) 時，執行會等待每次喚醒觸發並執行其迭代，直到 [迴圈結束](/docs/zh-TW/scheduled-tasks#stop-a-loop)，即使超過 10 分鐘上限也是如此。90* **待處理的喚醒**：在以文字傳遞提示詞（而非使用 `--input-format stream-json`）的執行中，當 Claude 已排定 [自訂節奏的 `/loop` 喚醒](/docs/zh-TW/scheduled-tasks#let-claude-choose-the-interval) 時，執行會等待每次喚醒觸發並執行其迭代，直到 [迴圈結束](/docs/zh-TW/scheduled-tasks#stop-a-loop)，即使超過 10 分鐘上限也是如此。

91 91

92如果執行達到其 [`--max-budget-usd`](/docs/zh-TW/cli-reference#cli-flags) 上限，Claude Code 會停止剩餘的背景工作，而不是繼續等待。92如果執行達到其 [`--max-budget-usd`](/docs/zh-TW/cli-reference#cli-flags) 上限，Claude Code 會停止剩餘的背景工作，而不是繼續等待。

93 93

94當背景工作啟動另一個回合時，使用預設的 `text` 輸出時，執行會列印每個回合的結果；使用 `json` 輸出時，則列印最後一個回合的結果。在 v2.1.295 之前，使用 `text` 輸出時，執行也只會列印最後一個回合的結果。

94<h3 id="stop-a-run-with-sigterm">96<h3 id="stop-a-run-with-sigterm">

95 使用 SIGTERM 停止執行97 使用 SIGTERM 停止執行

96</h3>98</h3>

97 99

98如果您使用 SIGTERM 停止 `claude -p` 執行，例如使用 `kill` 或從程序監督程式，Claude Code 會以代碼 143 退出。Claude Code 會將進行中的轉換保留為未完成狀態，並且不會為其記錄任何結果。要改為結束轉換，請傳送 SIGINT，或在停止程序之前呼叫 Agent SDK 的 `interrupt()`。100如果您使用 SIGTERM 停止 `claude -p` 執行，例如使用 `kill` 或從程序監督程式，Claude Code 會以代碼 143 退出。Claude Code 會將進行中的回合保留為未完成狀態，並且不會為其記錄任何結果。要改為結束回合，請傳送 SIGINT，或在停止程序之前呼叫 Agent SDK 的 `interrupt()`。

99 101

100在 SIGTERM 上，Claude Code 會終止仍在執行的任何 Bash 命令的程序樹。Claude Code 然後執行 [`SessionEnd` hooks](/docs/zh-TW/hooks#sessionend) 並退出。退出時，Claude Code 不啟動新的工具呼叫、不傳送新的模型請求，也不執行除 `SessionEnd` 以外的任何 hook。如果執行在命令中間或在信號到達時等待權限提示的答案，Claude Code 會按如下方式處理該步驟：102在 SIGTERM 上，Claude Code 會終止仍在執行的任何 Bash 命令的程序樹。Claude Code 然後執行 [`SessionEnd` hook](/docs/zh-TW/hooks#sessionend) 並退出。退出時，Claude Code 不啟動新的工具呼叫、不傳送新的模型請求，也不執行除 `SessionEnd` 以外的任何 hook。如果執行在命令中間或在信號到達時等待權限提示的答案，Claude Code 會按如下方式處理該步驟：

101 103

102* **執行命令**：Claude Code 在工作階段中將命令記錄為已終止。104* **執行命令**：Claude Code 在工作階段中將命令記錄為已終止。

103* **等待權限提示的答案**：如果您向程序傳送 SIGTERM，Claude Code 會將提示保留為未回答。如果您的程式透過 Agent SDK 關閉工作階段，SDK 會在傳送任何信號之前結束 Claude Code 的輸入，Claude Code 會在輸入結束後立即取消提示。105* **等待權限提示的答案**：如果您向程序傳送 SIGTERM，Claude Code 會將提示保留為未回答。如果您的程式透過 Agent SDK 關閉工作階段，SDK 會在傳送任何信號之前結束 Claude Code 的輸入，Claude Code 會在輸入結束後立即取消提示。

104 106

105當您 [繼續工作階段](#continue-conversations) 時，Claude Code 會將中斷的轉換保留為原樣，您的下一個提示會推動對話。要讓 Claude Code 在繼續時改為繼續中斷的轉換，請設定 [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN=1`](/docs/zh-TW/env-vars)。107當您 [繼續工作階段](#continue-conversations) 時，Claude Code 會將中斷的回合保留為原樣，您的下一個提示詞會推動對話。要讓 Claude Code 在繼續時改為繼續中斷的回合，請設定 [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN=1`](/docs/zh-TW/env-vars)。

106 108

107<h3 id="if-the-working-directory-is-deleted">109<h3 id="if-the-working-directory-is-deleted">

108 如果工作目錄被刪除110 如果工作目錄被刪除

109</h3>111</h3>

110 112

111如果 `claude -p` 或 Agent SDK 工作階段的工作目錄在工作階段中間被刪除，工作階段會繼續執行。當轉換在目錄遺失時啟動時，Claude Code 會在 `stream-json` 輸出中發出 [警告訊息](/docs/zh-TW/agent-sdk/typescript#sdkinformationalmessage)，且 shell 命令會失敗，直到目錄再次存在。113如果 `claude -p` 或 Agent SDK 工作階段的工作目錄在工作階段中間被刪除，工作階段會繼續執行。當回合在目錄遺失時啟動時，Claude Code 會在 `stream-json` 輸出中發出 [警告訊息](/docs/zh-TW/agent-sdk/typescript#sdkinformationalmessage)，且 shell 命令會失敗，直到目錄再次存在。

112 114

113<h2 id="examples">115<h2 id="examples">

114 範例116 範例

268| `no_response` | object，選用 | 僅在失敗的嘗試[未及時收到回應標頭](/docs/zh-TW/errors#no-response-from-api)時出現。`waited_ms` 是該次嘗試等待的時間，`retry_wait_ms` 是重試將等待的時間。在這些事件中，`max_retries` 反映此原因通常獲得的一次重試，而非整個工作階段的預算。需要 Claude Code v2.1.261 或更新版本 |270| `no_response` | object，選用 | 僅在失敗的嘗試[未及時收到回應標頭](/docs/zh-TW/errors#no-response-from-api)時出現。`waited_ms` 是該次嘗試等待的時間，`retry_wait_ms` 是重試將等待的時間。需要 Claude Code v2.1.261 或更新版本 |

269| `error` | string | 錯誤類別：`authentication_failed`、`oauth_org_not_allowed`、`account_on_hold`、`billing_error`、`rate_limit`、`overloaded`、`invalid_request`、`model_not_found`、`server_error`、`max_output_tokens`、`cloud_credential_error` 或 `unknown` |271| `error` | string | 錯誤類別：`authentication_failed`、`oauth_org_not_allowed`、`account_on_hold`、`billing_error`、`rate_limit`、`overloaded`、`invalid_request`、`model_not_found`、`server_error`、`max_output_tokens`、`cloud_credential_error` 或 `unknown` |

hipaa-setup.md +3 −0

Details

139}139}

140```140```

141 141

142若要取得包含沙箱機制、網路允許清單、憑證保護及本機資料保留設定的更完整 `managed-settings.json`，請參閱[設定範例儲存庫](https://github.com/anthropics/claude-code/tree/main/examples/settings)中的 `settings-hipaa.json` 和 `README-hipaa.md`。

143

142<h4 id="what-each-key-does">144<h4 id="what-each-key-does">

143 各設定鍵的作用145 各設定鍵的作用

144</h4>146</h4>

306 308

307* [為 HIPAA-ready 組織設定 Cowork（本機模式）](https://claude.com/docs/cowork/hipaa-setup)309* [為 HIPAA-ready 組織設定 Cowork（本機模式）](https://claude.com/docs/cowork/hipaa-setup)

308* [部署受管設定](/docs/zh-TW/managed-settings)310* [部署受管設定](/docs/zh-TW/managed-settings)

311* [HIPAA 設定範例](https://github.com/anthropics/claude-code/tree/main/examples/settings)

309* [企業網路設定](/docs/zh-TW/network-config)312* [企業網路設定](/docs/zh-TW/network-config)

310* [零資料保留](/docs/zh-TW/zero-data-retention)313* [零資料保留](/docs/zh-TW/zero-data-retention)

311* [法律與合規](/docs/zh-TW/legal-and-compliance)314* [法律與合規](/docs/zh-TW/legal-and-compliance)

hooks.md +124 −35

Details

476| `async` | 否 | 若為 `true`，會在背景執行而不封鎖。請參閱[在背景執行 hook](#run-hooks-in-the-background) |476| `async` | 否 | 若為 `true`，會在背景執行而不封鎖。請參閱[在背景執行 hook](#run-hooks-in-the-background) |

477| `asyncRewake` | 否 | 若為 `true`，會在背景執行，並在退出碼為 2 時喚醒 Claude。Hook 的 stderr（若 stderr 為空則為 stdout）會以[系統提醒](/docs/zh-TW/glossary#system-reminder)的形式顯示給 Claude，讓它能對長時間執行的背景失敗做出反應 |477| `asyncRewake` | 否 | 若為 `true`，會在背景執行，並在退出碼為 2 時喚醒 Claude。Hook 的 stderr（若 stderr 為空則為 stdout）會以[系統提醒](/docs/zh-TW/glossary#system-reminder)的形式顯示給 Claude，讓它能對長時間執行的背景失敗做出反應 |

478| `shell` | 否 | 此 hook 使用的 shell。接受 `"bash"` 或 `"powershell"`。預設為 `"bash"`，在未安裝 Git Bash 的 Windows 上則為 `"powershell"`。設為 `"powershell"` 會在 Windows 上透過 PowerShell 執行命令。由於 hook 會直接產生 PowerShell，因此不需要 `CLAUDE_CODE_USE_POWERSHELL_TOOL`。設定了 `args` 時會被忽略 |478| `shell` | 否 | 此 hook 使用的 shell。接受 `"bash"` 或 `"powershell"`。預設為 `"bash"`，在未安裝 Git Bash 的 Windows 上則為 `"powershell"`。設為 `"powershell"` 會在 Windows 上透過 PowerShell 執行命令。由於 hook 會直接產生 PowerShell，因此不需要 `CLAUDE_CODE_USE_POWERSHELL_TOOL`。設定了 `args` 時會被忽略 |

479| `onFailure` | 否 | hook 失敗時該動作的處理方式：`"continue"`（預設）或 `"block"`。請參閱[在 hook 失敗時封鎖動作](#block-the-action-when-a-hook-fails)。需要 Claude Code v2.1.295 或更新版本 |

479 480

480<a id="exec-form-and-shell-form" />481<a id="exec-form-and-shell-form" />

481 482

533| `url` | 是 | POST 請求要傳送到的 URL |534| `url` | 是 | POST 請求要傳送到的 URL |

534| `headers` | 否 | 以鍵值對表示的額外 HTTP 標頭。值支援使用 `$VAR_NAME` 或 `${VAR_NAME}` 語法插入環境變數。只有列在 `allowedEnvVars` 中的變數會被解析 |535| `headers` | 否 | 以鍵值對表示的額外 HTTP 標頭。值支援使用 `$VAR_NAME` 或 `${VAR_NAME}` 語法插入環境變數。只有列在 `allowedEnvVars` 中的變數會被解析 |

535| `allowedEnvVars` | 否 | 可插入標頭值中的環境變數名稱清單。對未列出之變數的參照會被替換為空字串。任何環境變數插入都必須設定此欄位才能運作 |536| `allowedEnvVars` | 否 | 可插入標頭值中的環境變數名稱清單。對未列出之變數的參照會被替換為空字串。任何環境變數插入都必須設定此欄位才能運作 |

537| `onFailure` | 否 | hook 失敗時該動作的處理方式：`"continue"`（預設）或 `"block"`。請參閱[在 hook 失敗時封鎖動作](#block-the-action-when-a-hook-fails)。需要 Claude Code v2.1.295 或更新版本 |

536 538

537Claude Code 會將 hook 的 [JSON 輸入](#hook-input-and-output)作為 POST 請求主體傳送，並帶有 `Content-Type: application/json`。回應主體使用與命令 hook 相同的 [JSON 輸出格式](#json-output)。539Claude Code 會將 hook 的 [JSON 輸入](#hook-input-and-output)作為 POST 請求主體傳送，並帶有 `Content-Type: application/json`。回應主體使用與命令 hook 相同的 [JSON 輸出格式](#json-output)。

538 540

821 退出碼輸出823 退出碼輸出

822</h3>824</h3>

823 825

824來自您的 hook 命令的退出碼告訴 Claude Code 該操作是應該進行、被阻止還是被忽略。退出碼不單獨起作用。Claude Code 在每個退出碼上從 stdout 讀取 [JSON 輸出欄位](#json-output)，而不僅僅是 0，對於使用標準決定模型的事件，通過 schema 驗證的已解析物件與退出碼一起生效。Exit 2 的阻止是 JSON 無法覆寫的唯一結果。826您的 hook 的退出碼會告訴 Claude Code 是否繼續執行觸發該 hook 的操作，例如工具呼叫或提示詞。完成的執行有以下三種結果之一：

825 827

826兩個表格負責每個事件的例外：[每個事件的退出碼 2 行為](#exit-code-2-behavior-per-event) 說明每個事件的退出碼做什麼，[決定控制](#decision-control) 說明每個事件接受哪些決定欄位。通用欄位（如 `systemMessage`）在大多數事件中工作，並列在 [JSON 輸出](#json-output) 表格中。828* **成功**：您的 hook 以 0 退出。Claude Code 套用您的 hook 列印的任何 [JSON 輸出](#json-output) 欄位，除非這些欄位阻止或拒絕該操作，否則操作會繼續進行。

829* **阻止性錯誤**：您的 hook 以 2 退出。在 [可以阻止的事件](#exit-code-2-behavior-per-event) 上，Claude Code 會停止該操作。

830* **非阻止性錯誤**：您的 hook 以任何其他代碼退出，或以其他方式失敗，例如無法啟動或列印無效的 JSON。操作會繼續進行，且在 `PreToolUse` 等事件上，您會在逐字稿中看到 `<hook name> hook error` 通知。如果您希望失敗的 hook 阻止操作，請設定 [`onFailure: "block"`](#block-the-action-when-a-hook-fails)。

831

832您的 hook 列印到 stdout 的內容可能會改變結果。例如，如果 `PreToolUse` hook 以 1 退出，但列印了通過驗證的 JSON，則該次執行為成功，由 JSON 欄位決定接下來發生的情況。要找出您的 hook 在 `PreToolUse` 等事件上的結果，請將第一欄中它列印到 stdout 的內容與頂端的退出碼對應：

833

834| Stdout | 退出 0 | 退出 2 | 任何其他退出碼 |

835| :- | :- | :- | :- |

838| [純文字](#exit-code-0) 或無內容 | 成功 | 阻止性錯誤。您的 stderr 即為原因 | 非阻止性錯誤。通知帶有您的 stderr 的第一行 |

839

840某些事件有自己的規則：

841

842* **`WorktreeCreate`**：任何非零退出碼都會使 worktree 建立失敗，無論您的 JSON 說什麼。

843* **`WorktreeRemove`**：任何非零退出碼會在目錄之後仍然存在時使 worktree 移除失敗。

844* **`Stop`、`SubagentStop`、`TaskCompleted` 和外掛的 `UserPromptSubmit` hook**：當您的 hook 以 2 退出、stdout 沒有任何內容，且其 stderr 表示找不到檔案（例如 `No such file or directory`）時，Claude Code 將該次執行視為非阻止性錯誤。

845* **`Elicitation` 和 `ElicitationResult`**：當您的 hook 以 0 退出時，Claude Code 套用您的 `hookSpecificOutput`，在任何其他退出碼上則忽略它。

846* **捨棄 hook 輸出的事件，例如 `StopFailure`**：Claude Code 在任何退出碼上都會忽略您的 JSON，但 `terminalSequence` 等副作用欄位仍會觸發。

847

848要查看退出碼 2 在您的事件上的作用，請參閱 [每個事件的退出碼 2 行為](#exit-code-2-behavior-per-event)。要查看它接受哪些決定欄位，請參閱 [決定控制](#decision-control)。

827 849

828<h4 id="exit-code-0">850<h4 id="exit-code-0">

829 退出碼 0851 退出碼 0

835 857

836Claude Code 是否將您的 stdout 讀取為 [JSON 輸出](#json-output) 或純文字取決於它如何開始和結束，忽略周圍的空白：858Claude Code 是否將您的 stdout 讀取為 [JSON 輸出](#json-output) 或純文字取決於它如何開始和結束，忽略周圍的空白：

837 859

838* **以 `{` 開始並以 `}` 結束**：Claude Code 將其解析為 JSON。當輸出是兩行或更多行，每行本身都解析為 JSON，且沒有任何一行是設定欄位的 [JSON 輸出](#json-output) 物件時，Claude Code 將整個輸出視為純文字。當其中一行確實設定欄位時，整個輸出是解析失敗，如下所述。860* **以 `{` 開始並以 `}` 結束**：Claude Code 將其解析為 JSON。當輸出是兩行或更多行，每行本身都解析為 JSON，且沒有任何一行是設定欄位的 [JSON 輸出](#json-output) 物件時，Claude Code 將整個輸出視為純文字。當其中一行確實設定欄位時，整個輸出是解析失敗。

839* **以 `{` 開始但不以 `}` 結束**：Claude Code 將其視為純文字。861* **以 `{` 開始但不以 `}` 結束**：Claude Code 將其視為純文字。

840* **以其他任何內容開始**：Claude Code 將其視為純文字，即使它是 JSON 陣列或帶引號的 JSON 字串也是如此。862* **以其他任何內容開始**：Claude Code 將其視為純文字，即使它是 JSON 陣列或帶引號的 JSON 字串也是如此。

841 863

842對於使用標準決定模型的事件，以已解析物件退出 0 但未通過 schema 驗證是非阻止性錯誤：操作進行，逐字稿顯示 `<hook name> hook error` 通知，帶有驗證訊息。在除 2 以外的任何退出碼上都會發生相同情況，而 [exit 2 仍然阻止](#exit-code-2)。864當 Claude Code 嘗試將您的 stdout 解析為 JSON 但無法解析，或已解析的物件未通過 [schema 驗證](#json-output) 時，該次執行為 [非阻止性錯誤](#exit-code-output)。`<hook name> hook error` 通知帶有解析或驗證訊息。在將純文字 stdout 新增為上下文的事件上，Claude Code 不會新增其無法解析的 stdout。

~~843~~

844對於使用標準決定模型的事件，當 Claude Code 嘗試將您的 stdout 解析為 JSON 且無法時，它在除 2 以外的每個退出碼上報告非阻止性錯誤。逐字稿顯示 `<hook name> hook error` 通知，帶有解析訊息。在新增純文字 stdout 作為上下文的事件上，Claude Code 不新增文字。在 v2.1.248 之前，Claude Code 將該 stdout 視為純文字。

845 865

846來自以 0 退出的 hook 的 stderr 僅進入偵錯日誌，永遠不進入逐字稿，Claude 永遠看不到它。要自己讀取它，請啟用 [偵錯日誌](#debug-hooks)。要從 `PostToolUse` 或 `PostToolUseFailure` hook 向 Claude 顯示警告，請改為退出 2，以便 [Claude 看到 stderr](#exit-code-2-behavior-per-event)，儘管工具已執行。866Claude 永遠看不到以 0 退出的 hook 的 stderr。要在 `PreToolUse` 等事件上自行讀取它，請啟用 [偵錯日誌](#debug-hooks)。要從 `PostToolUse` 或 `PostToolUseFailure` hook 向 Claude 顯示警告，請改為退出 2，以便 [Claude 看到 stderr](#exit-code-2-behavior-per-event)，儘管工具已執行。

847 867

848<h4 id="exit-code-2">868<h4 id="exit-code-2">

849 退出碼 2869 退出碼 2

850</h4>870</h4>

851 871

852退出 2 表示阻止性錯誤。在 [可以阻止的事件](#exit-code-2-behavior-per-event) 上，退出 2 無論您是否列印 JSON 都會阻止：即使 JSON `permissionDecision` 為 `"allow"` 也無法覆寫它。Claude Code 仍然讀取 stdout 上任何有效的 [JSON 輸出](#json-output)。在 `Elicitation` 和 `ElicitationResult` 上，exit-2 hook 的 `hookSpecificOutput` 被忽略。872以代碼 2 退出以阻止操作。在 [可以阻止的事件](#exit-code-2-behavior-per-event) 上，Claude Code 會停止該操作：例如，`PreToolUse` hook 會阻止工具呼叫，`UserPromptSubmit` hook 會拒絕提示詞。

853 873

854阻止訊息是您的 JSON 的阻止決定的原因（當它做出阻止決定時），否則是您的 stderr 文字。阻止做什麼因事件而異：`PreToolUse` 阻止工具呼叫，`UserPromptSubmit` 拒絕提示詞，等等。[每個事件的退出碼 2 行為](#exit-code-2-behavior-per-event) 列出每個事件的效果，每個事件的部分說明訊息去哪裡。874隨阻止一起傳回的訊息是您的 hook 的 stderr。如果您的 hook 也列印了做出阻止決定的 JSON，Claude Code 會改用該決定的原因。

855 875

856在列印未通過 [JSON 輸出](#json-output) schema 驗證的 JSON 時退出 2 的 hook 仍然阻止：Claude Code 使用 stderr 作為阻止原因，並在偵錯日誌中記錄驗證失敗。在 v2.1.214 之前，Claude Code 將該組合視為非阻止性錯誤，操作進行。876即使您的 hook 列印 JSON，退出 2 仍會阻止：

877

878* **通過 schema 驗證的 JSON**：Claude Code 仍會讀取 [JSON 輸出](#json-output) 欄位，但它們無法覆寫阻止。即使 `permissionDecision` 為 `"allow"` 也無法讓操作通過。在 `Elicitation` 和 `ElicitationResult` 上，exit-2 hook 的 `hookSpecificOutput` 會被忽略。

879* **未通過 schema 驗證的 JSON**：hook 仍會阻止。Claude Code 使用您的 stderr 作為阻止原因，並在偵錯日誌中記錄驗證失敗。

857 880

858此指令碼透過退出 2 阻止 `rm` 命令，並將每個其他命令留給正常權限流程：881此指令碼透過退出 2 阻止 `rm` 命令，並將每個其他命令留給正常權限流程：

859 882

871exit 0 # 無決定：正常權限流程適用894exit 0 # 無決定：正常權限流程適用

872```895```

873 896

897將此指令碼註冊為 `Bash` 上的 `PreToolUse` hook 後，以 `rm` 開頭的命令會被阻止，Claude 會收到 hook 的 stderr 作為工具的錯誤，前綴為事件名稱、工具名稱和 hook 的命令：

898

899```text theme={null}

900PreToolUse:Bash hook error: [${CLAUDE_PROJECT_DIR}/.claude/hooks/no-rm.sh]: Blocked: rm commands are not allowed

901```

902

874<h4 id="other-exit-codes">903<h4 id="other-exit-codes">

875 其他退出碼904 其他退出碼

876</h4>905</h4>

877 906

878任何其他退出碼對於大多數 hook 事件本身不會阻止。發生的情況取決於您的 stdout：907當您的 hook 以 0 或 2 以外的代碼退出，並在 stdout 列印純文字或不列印任何內容時，該次執行為 [非阻止性錯誤](#exit-code-output)。您會在逐字稿中看到 `<hook name> hook error` 通知，帶有 `Failed with non-blocking status code:` 和您的 hook 的 stderr 第一行。例如，當 `Bash` 上的 `PreToolUse` hook 將 `something broke` 列印到 stderr 並以 1 退出時，`PreToolUse:Bash hook error` 通知帶有這一行：

879 908

880* 使用通過 schema 驗證的已解析物件，對於使用標準決定模型的事件，Claude Code 忽略退出碼，JSON 單獨決定結果：909```text theme={null}

881 * 事件支援的每個欄位都被接受，包括 `permissionDecision`、`additionalContext`、`updatedInput` 和 `systemMessage`，hook 不被報告為錯誤。910Failed with non-blocking status code: something broke

882 * [決定控制](#decision-control) 列出每個事件的決定欄位；通用欄位如 `systemMessage` 遵循 [JSON 輸出](#json-output) 表格。911```

883* 使用未通過 schema 驗證的已解析物件，對於使用標準決定模型的事件，它是與 [exit 0 上](#exit-code-0) 相同的非阻止性錯誤：操作進行，`<hook name> hook error` 通知帶有驗證訊息。

884* 使用 Claude Code [嘗試解析為 JSON](#exit-code-0) 且無法的 stdout，Claude Code 對於使用標準決定模型的事件報告與 exit 0 上相同的非阻止性錯誤。操作進行，通知帶有解析訊息。

885* 使用 Claude Code [視為純文字](#exit-code-0) 的 stdout，或使用空 stdout，對於大多數 hook 事件是非阻止性錯誤：操作進行，逐字稿顯示 `<hook name> hook error` 通知，後跟 stderr 的第一行，前綴為 `Failed with non-blocking status code:`。要擷取完整 stderr，請啟用 [偵錯日誌](#debug-hooks)。

886 912

887標準決定模型之外的事件在 [每個事件表](#exit-code-2-behavior-per-event) 中保有自己的列：`WorktreeCreate` 在任何非零退出時都會使建立失敗，無論您的 JSON 說什麼；而完全捨棄 hook 輸出的事件（如 `StopFailure`）在每個退出碼上都忽略您的 JSON，但 `terminalSequence` 等副作用欄位仍會觸發。913要擷取完整的 stderr 而不僅是其第一行，請啟用 [偵錯日誌](#debug-hooks)。

888 914

889無法啟動的 hook 落入相同的非阻止性類別。當指令碼路徑不存在或不可執行時，shell 以代碼（如 127）退出，您看到相同的通知，帶有解譯器的訊息，例如 `Failed with non-blocking status code: /bin/sh: /path/to/hook.sh: No such file or directory`。對於大多數 hook 事件，操作進行。當您設定原則 hook 時，請在其第一次執行時留意此通知：`settings.json` 中拼寫錯誤的路徑會使閘門無聲地停用。915無法啟動的 hook 也是非阻止性錯誤。在 shell 形式中，當指令碼路徑不存在或不可執行時，shell 以代碼（如 127）退出，通知帶有解譯器的訊息，例如 `Failed with non-blocking status code: /bin/sh: /path/to/hook.sh: No such file or directory`。當您設定原則 hook 時，請在其第一次執行時留意此通知，因為 `settings.json` 中拼寫錯誤的路徑代表該 hook 永遠不會執行。若要改為阻止操作，請設定 [`onFailure: "block"`](#block-the-action-when-a-hook-fails)。

890 916

891<Warning>917<Warning>

892 對於大多數 hook 事件，退出碼 2 是唯一單靠退出碼就能阻止的退出碼。沒有 stdout 上的有效 JSON，Claude Code 將退出碼 1 視為非阻止性錯誤並繼續操作，儘管 1 是傳統的 Unix 失敗代碼。如果您的 hook 旨在強制執行原則，請使用 `exit 2`。Worktree 事件不同：來自 `WorktreeCreate` 的任何非零退出碼都會中止 worktree 建立，來自 `WorktreeRemove` 的任何非零退出碼會在目錄之後仍然存在時使 worktree 移除失敗。918 沒有 stdout 上的有效 JSON，Claude Code 將退出碼 1 視為非阻止性錯誤，儘管 1 是傳統的 Unix 失敗代碼。如果您的 hook 旨在強制執行原則，請使用 `exit 2`。

893</Warning>919</Warning>

894 920

895<h4 id="timeouts">921<h4 id="timeouts">

900 926

901在 [`PreModelSwitch`](#premodelswitch) 上，在其逾時時被取消的 hook 會阻止模型切換。在 `PreToolUse` 上，兩個 hook 系列不同：927在 [`PreModelSwitch`](#premodelswitch) 上，在其逾時時被取消的 hook 會阻止模型切換。在 `PreToolUse` 上，兩個 hook 系列不同：

902 928

903* 逾時的 `command`、`http` 或 `mcp_tool` hook 不阻止工具呼叫。呼叫透過正常 [權限流程](/docs/zh-TW/permissions) 繼續，因此不要指望停滯的 hook 充當閘門。929* 逾時的 `command`、`http` 或 `mcp_tool` hook 不阻止工具呼叫。呼叫透過正常 [權限流程](/docs/zh-TW/permissions) 繼續，因此不要指望停滯的 hook 充當閘門。要在 `command` 或 `http` hook 逾時時阻止呼叫，請設定 [`onFailure: "block"`](#block-the-action-when-a-hook-fails)。

904* 超過其逾時的 [Agent SDK 回呼 hook](/docs/zh-TW/agent-sdk/hooks) [阻止工具呼叫](#pretooluse)。930* 超過其逾時的 [Agent SDK 回呼 hook](/docs/zh-TW/agent-sdk/hooks) [阻止工具呼叫](#pretooluse)。

905 931

932<h4 id="block-the-action-when-a-hook-fails">

933 在 hook 失敗時阻止操作

934</h4>

935

936在大多數事件上，當 hook 失敗或逾時時，Claude Code 仍會執行該操作，因此路徑錯誤或指令碼當機的原則 hook 會讓所有操作通過。若要改為阻止操作，請在 `command` 或 `http` hook 上設定 `"onFailure": "block"`。預設值為 `"continue"`。需要 Claude Code v2.1.295 或更新版本。

937

938`.claude/settings.json` 中的這個 `PreToolUse` hook 會在每個 Bash 命令之前執行專案指令碼，並在指令碼失敗時阻止該命令：

939

940```json theme={null}

941{

942 "hooks": {

943 "PreToolUse": [

944 {

945 "matcher": "Bash",

946 "hooks": [

947 {

948 "type": "command",

949 "command": "node",

950 "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/check-command.js"],

951 "onFailure": "block"

952 }

953 ]

954 }

955 ]

956 }

957}

958```

959

960要測試它，請讓 `check-command.js` 保持不存在，並要求 Claude 執行 `ls` 之類的 Bash 命令。Claude Code 會阻止該呼叫，錯誤包含 `failed; blocking because onFailure is "block"`，後接 node 本身的錯誤輸出（此處截短為一行）：

961

962```text theme={null}

963PreToolUse:Bash hook error: [node ${CLAUDE_PROJECT_DIR}/.claude/hooks/check-command.js]: failed; blocking because onFailure is "block"

964Error: Cannot find module '/path/to/project/.claude/hooks/check-command.js'

965```

966

967逾時後，訊息會顯示 `timed out` 而不是 `failed`。未設定 `onFailure` 時，同樣缺少的指令碼是非阻止性錯誤，`ls` 會執行。

968

969以下各項都計為失敗：

970

971* **無法啟動**：命令 hook 無法啟動，例如因為指令碼或可執行檔不存在

972* **0 或 2 以外的退出碼**：對命令 hook 而言，即使它列印了允許操作的 JSON（例如 `permissionDecision: "allow"`）也會計入。要傳回 JSON 決定，請以 0 退出

973* **HTTP 錯誤**：HTTP hook 的連線失敗，或回應狀態不是 2xx

974* **逾時**：hook 達到其 [`timeout`](#common-fields)

975* **無效輸出**：JSON 輸出 [無法解析](#exit-code-0) 或未通過 [schema 驗證](#json-output)。對於 HTTP hook，既非空白也非 JSON 物件的 2xx 正文也會計入。命令 hook 的純文字 stdout 不算失敗

976

977設定 `"block"` 後，失敗會執行 [退出碼 2 在該事件上的作用](#exit-code-2-behavior-per-event)，但 `PermissionRequest` 除外，在該事件上它會拒絕請求。例如，`PreToolUse` 失敗會阻止工具呼叫，`UserPromptSubmit` 失敗會阻止提示詞。

978

979該欄位對以下 hook 沒有作用：

980

981* **`Stop`、`SubagentStop`、`TaskCompleted` 和 `TeammateIdle` hook**：在這些事件上，退出碼 2 會讓 Claude 回去繼續工作，而 Claude 無法修復無法執行的 hook

982* **背景命令 hook**：設定 [`async` 或 `asyncRewake`](#run-hooks-in-the-background) 的命令 hook

983

906<h4 id="exit-code-2-behavior-per-event">984<h4 id="exit-code-2-behavior-per-event">

907 每個事件的退出碼 2 行為985 每個事件的退出碼 2 行為

908</h4>986</h4>

960* **連線失敗**：非阻止性錯誤，執行繼續1038* **連線失敗**：非阻止性錯誤，執行繼續

961* **逾時**：hook 被取消，如 [逾時](#timeouts) 下所述1039* **逾時**：hook 被取消，如 [逾時](#timeouts) 下所述

962 1040

963與命令 hook 不同，HTTP hook 無法僅透過狀態碼發出阻止性錯誤信號。要阻止工具呼叫或拒絕權限，請返回 2xx 回應，其 JSON 正文包含適當的決定欄位。1041HTTP hook 無法僅透過狀態碼發出阻止性錯誤信號：非 2xx 狀態或失敗的連線是 [非阻止性錯誤](#exit-code-output)。要阻止工具呼叫或拒絕權限，請返回 2xx 回應，其 JSON 正文包含適當的決定欄位。要在請求失敗或返回非 2xx 狀態時阻止操作，請設定 [`onFailure: "block"`](#block-the-action-when-a-hook-fails)。

964 1042

965<h3 id="json-output">1043<h3 id="json-output">

966 JSON 輸出1044 JSON 輸出

1237 SessionStart 決策控制1315 SessionStart 決策控制

1238</h4>1316</h4>

1239 1317

1240Claude Code 會將其[視為純文字](#exit-code-0)的 stdout 加入 Claude 的上下文。除了所有 hook 都可使用的 [JSON 輸出欄位](#json-output)之外，您還可以傳回下列事件專屬欄位：1318SessionStart hook 可以為 Claude 新增上下文、提供第一則使用者訊息、設定工作階段標題、監看檔案，以及重新載入 skill。除了所有 hook 皆可使用的 [JSON 輸出欄位](#json-output)之外，請針對每項功能傳回對應的欄位：

1241 1319

1242| 欄位 | 說明 |1320| 欄位 | 說明 |

1243| :- | :- |1321| :- | :- |

1245| `initialUserMessage` | 用作工作階段第一則使用者訊息的字串。適用於使用 `-p` 旗標的[非互動模式](/docs/zh-TW/headless)，即使未提供提示詞，它也會成為第一個回合。如果提供了提示詞，提示詞會作為下一個回合接續。與附加到既有回合的 `additionalContext` 不同，此欄位會建立該回合 |1323| `initialUserMessage` | 在使用 `-p` 旗標的[非互動模式](/docs/zh-TW/headless)中，作為工作階段第一則使用者訊息的字串。即使您未傳入提示詞，它也會成為第一個回合。您傳入的提示詞則會作為下一個回合 |

1246| `sessionTitle` | 設定工作階段標題，效果與 `/rename` 相同。可用來依據啟動資料夾、git 分支或 worktree 名稱自動命名工作階段。在 `source` 為 `"startup"`、`"resume"` 或 `"fork"` 時套用；在 `"clear"` 和 `"compact"` 時忽略 |1324| `sessionTitle` | 設定工作階段標題，效果與 `/rename` 相同。當 `source` 為 `"startup"`、`"resume"` 或 `"fork"` 時適用 |

1248| `reloadSkills` | 布林值。為 `true` 時，Claude Code 會在 SessionStart hook 完成後重新掃描 [skill](/docs/zh-TW/skills) 和命令目錄，讓 hook 安裝的 skill 從第一個提示詞開始就能在同一個工作階段中使用 |1326| `reloadSkills` | 布林值。為 `true` 時，Claude Code 會在 SessionStart hook 完成後重新掃描 [skill](/docs/zh-TW/skills) 和命令目錄。請參閱[重新載入 hook 安裝的 skill](#reload-skills-that-a-hook-installs) |

1327

1328此輸出會新增上下文並為工作階段命名：

1249 1329

1250```json theme={null}1330```json theme={null}

1251{1331{

1257}1337}

1258```1338```

1259 1339

1260由於此事件的純 stdout 已會傳達給 Claude，只載入上下文的 hook 可以直接輸出到 stdout，無須建構 JSON。當您需要將上下文與 `sessionTitle` 等其他欄位結合時，請使用 JSON 格式。1340只新增上下文的 hook 可以直接輸出內容而不必建構 JSON，因為 Claude Code 會將 SessionStart hook 的[純文字 stdout](#exit-code-0) 加入 Claude 的上下文。

1341

1342如果您外掛的 SessionStart hook 提供 `initialUserMessage` 或 `sessionTitle`，請在工作階段開始前安裝該外掛。對於在 SessionStart hook 執行後才完成安裝的外掛，Claude Code 會忽略這兩個欄位。

1343

1344<h4 id="reload-skills-that-a-hook-installs">

1345 重新載入 hook 安裝的 skill

1346</h4>

1347

1348若要讓 SessionStart hook 安裝的 skill 在同一個工作階段中可用，請傳回 `reloadSkills`。skill 探索通常會在 SessionStart hook 完成之前執行，因此若沒有此欄位，hook 寫入 `~/.claude/skills/` 或 `.claude/skills/` 的檔案可能在第一個提示詞執行時尚不存在。

1261 1349

1262當 SessionStart hook 會安裝或更新 skill 時，請使用 `reloadSkills`。skill 探索通常會在 SessionStart hook 完成之前執行，因此 hook 寫入 `~/.claude/skills/` 或 `.claude/skills/` 的檔案，否則只會在下一個工作階段中出現。此範例會同步共用的 skill 儲存庫並請求重新掃描：1350此範例會同步共用的 skill 儲存庫並請求重新掃描：

1263 1351

1264```bash theme={null}1352```bash theme={null}

1265#!/bin/bash1353#!/bin/bash

1270echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'1358echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'

1271```1359```

1272 1360

1273儲存庫 URL 只是預留位置，請替換為您自己的 skill 儲存庫。使用預留位置時，clone 會失敗並在 stderr 輸出 `fatal:` 訊息。以 0 結束的 SessionStart hook 的 stderr 僅供參考，因此 `reloadSkills` 請求仍會套用。1361儲存庫 URL 僅為預留位置。請替換為您自己的 skill 儲存庫。

1274 1362

1275<h4 id="persist-environment-variables">1363<h4 id="persist-environment-variables">

1276 保存環境變數1364 保存環境變數

1419 1507

1420`UserPromptSubmit` hook 對 `command`、`http` 和 `mcp_tool` 類型的預設逾時為 30 秒，短於大多數其他事件上這些類型的 600 秒預設值。由於此 hook 會在每個提示詞之前執行，並在完成前阻擋模型處理，卡住的 hook 會使工作階段停滯。如果您的 hook 需要更多時間，請在 hook 項目中設定 `timeout` 欄位。1508`UserPromptSubmit` hook 對 `command`、`http` 和 `mcp_tool` 類型的預設逾時為 30 秒，短於大多數其他事件上這些類型的 600 秒預設值。由於此 hook 會在每個提示詞之前執行，並在完成前阻擋模型處理，卡住的 hook 會使工作階段停滯。如果您的 hook 需要更多時間，請在 hook 項目中設定 `timeout` 欄位。

1421 1509

1422除了您以 [`async: true`](#run-hooks-in-the-background) 執行的命令 hook 之外，達到逾時的 `UserPromptSubmit` 命令、HTTP 或 MCP 工具 hook 會被取消，其輸出（包括任何 `additionalContext`）會被捨棄。提示詞仍會在沒有該上下文的情況下傳達給 Claude。逐字稿會顯示一則通知，說明該 hook 的名稱、觸發的逾時，以及輸出已被捨棄。1510除了以 [`async: true`](#run-hooks-in-the-background) 執行的命令 hook 之外，達到逾時的 `UserPromptSubmit` 命令、HTTP 或 MCP 工具 hook 會被取消，其輸出（包括任何 `additionalContext`）會被捨棄。提示詞仍會在沒有該上下文的情況下傳達給 Claude。若要改為阻擋提示詞，請在命令或 HTTP hook 上設定 [`onFailure: "block"`](#block-the-action-when-a-hook-fails)。逐字稿會顯示一則通知，說明是哪個 hook、觸發的逾時，以及輸出已被捨棄。

1423 1511

1424`UserPromptSubmit` 上達到逾時的 [Agent SDK 回呼 hook](/docs/zh-TW/agent-sdk/hooks) 會阻擋該提示詞，並顯示說明該 hook 和逾時的訊息，因為該處的回呼可能作為不得在失敗時放行的政策關卡。工作階段會繼續。在 v2.1.208 之前，該事件上的回呼逾時會以執行錯誤結束該回合。1512`UserPromptSubmit` 上達到逾時的 [Agent SDK 回呼 hook](/docs/zh-TW/agent-sdk/hooks) 會阻擋該提示詞，並顯示說明該 hook 和逾時的訊息，因為該處的回呼可能作為不得在失敗時放行的政策關卡。工作階段會繼續。在 v2.1.208 之前，該事件上的回呼逾時會以執行錯誤結束該回合。

1425 1513

1860| :- | :- | :- | :- |1948| :- | :- | :- | :- |

1863 1952

1864<h5 id="websearch">1953<h5 id="websearch">

1865 WebSearch1954 WebSearch

2114 2203

2115以退出碼 2 結束但沒有 `decision` 物件的 hook 不會改變權限流程，其 stderr 也會被捨棄。只有 `decision` 物件能授予或拒絕請求。2204以退出碼 2 結束但沒有 `decision` 物件的 hook 不會改變權限流程，其 stderr 會被捨棄。若要授予或拒絕請求，請回傳 `decision` 物件。

2116 2205

2117```json theme={null}2206```json theme={null}

2118{2207{

2678 TaskCreated 決策控制2767 TaskCreated 決策控制

2679</h4>2768</h4>

2680 2769

2681TaskCreated hook 可以透過兩種方式封鎖建立。無論哪種方式，Claude Code 都會刪除該任務，並將您的訊息作為工具錯誤回傳給 Claude。Claude Code 會忽略此事件的 `continue: false`，Claude 會繼續工作。2770TaskCreated hook 可以透過退出碼 2 或 JSON 決策封鎖建立。無論採用哪種方式，Claude Code 都會刪除該任務，並將您的訊息作為工具的錯誤回傳給 Claude。Claude Code 會忽略此事件的 `continue: false`，Claude 會繼續工作。

2682 2771

2683* **退出碼 2**：Claude Code 會將 stderr 文字作為訊息回傳。2772* **退出碼 2**：Claude Code 會將 stderr 文字作為訊息回傳。

2684* **JSON `{"decision": "block", "reason": "..."}`**：Claude Code 會將 `reason` 作為訊息回傳。2773* **JSON `{"decision": "block", "reason": "..."}`**：Claude Code 會將 `reason` 作為訊息回傳。

3560 3649

3561無論決策為何，Claude Code 都會向使用者顯示 hook 回傳的任何 `systemMessage`，因此回報成本的 hook 可以回傳 `{"systemMessage": "..."}` 並以 0 退出。3650無論決策為何，Claude Code 都會向使用者顯示 hook 回傳的任何 `systemMessage`，因此回報成本的 hook 可以回傳 `{"systemMessage": "..."}` 並以 0 退出。

3562 3651

3563在逾時前未回應的 PreModelSwitch hook 會封鎖切換。相較之下，在 [PreToolUse](#timeouts) 上，逾時的命令 hook 會讓工具呼叫繼續進行。此事件的預設逾時為 30 秒。`PreModelSwitch` 只會執行 `command`、`http` 和 `mcp_tool` hook，因此 `prompt` 和 `agent` 的預設值不適用。3652在逾時之前未回應的 PreModelSwitch hook 會封鎖切換。關於逾時在其他事件上的效果，請參閱[逾時](#timeouts)。此事件的預設逾時為 30 秒。`PreModelSwitch` 只會執行 `command`、`http` 和 `mcp_tool` hook，因此 `prompt` 和 `agent` 的預設值不適用。

3564 3653

3565以 0 或 2 以外的代碼退出且未印出 JSON 決策的 hook 不會封鎖：Claude Code 會顯示其 stderr 並套用切換，如[其他退出碼](#other-exit-codes)中所述。3654以 0 或 2 以外的代碼退出且未印出 JSON 決策的 hook，屬於非封鎖錯誤，如[其他退出碼](#other-exit-codes)中所述。

3566 3655

3567<h3 id="postmodelswitch">3656<h3 id="postmodelswitch">

3568 PostModelSwitch3657 PostModelSwitch

4278非同步 hooks 與同步 hooks 相比有額外的限制：4367非同步 hooks 與同步 hooks 相比有額外的限制：

4279 4368

4280* Hook 輸出在下一個對話輪次上傳遞。如果工作階段閒置，回應會等待直到下一個使用者互動。例外：退出代碼為 2 的 `asyncRewake` hook 即使在工作階段閒置時也會立即喚醒 Claude。4369* Hook 輸出在下一個對話輪次上傳遞。如果工作階段閒置，回應會等待直到下一個使用者互動。例外：退出代碼為 2 的 `asyncRewake` hook 即使在工作階段閒置時也會立即喚醒 Claude。

4281* 每次執行都會建立一個單獨的背景程序。同一非同步 hook 的多次觸發之間沒有去重。4370* 每次執行都會建立一個單獨的背景程序。

4282 4371

4283<h2 id="security-considerations">4372<h2 id="security-considerations">

4284 安全考慮4373 安全考慮

hooks-guide.md +14 −11

Details

242 242

243若要測試 hook，請要求 Claude 將帶有單引號字串的行新增到 JavaScript 檔案，然後開啟該檔案：使用 Prettier 的預設設定，hook 會將它們重寫為雙引號。243若要測試 hook，請要求 Claude 將帶有單引號字串的行新增到 JavaScript 檔案，然後開啟該檔案：使用 Prettier 的預設設定，hook 會將它們重寫為雙引號。

244 244

245當 hook 成功時，Claude Code 在對話中不顯示任何內容。若要確認 hook 已執行，請檢查編輯的檔案是否已重新格式化，或參閱[偵錯技術](#debug-techniques)。245當 hook 成功時，Claude Code 在對話中不顯示任何內容。若要確認 hook 已執行，請檢查編輯的檔案是否已重新格式化，或參閱[檢查 hook 執行了什麼](#check-what-a-hook-did)。

246 246

247若要重新格式化特定檔案（無論它如何變更），包括當 `Bash` 命令重寫它時，請改用 [FileChanged](/docs/zh-TW/hooks#filechanged) hook。247若要重新格式化特定檔案（無論它如何變更），包括當 `Bash` 命令重寫它時，請改用 [FileChanged](/docs/zh-TW/hooks#filechanged) hook。

248 248

979}979}

980```980```

981 981

982端點應使用與命令 hooks 相同的[輸出格式](/docs/zh-TW/hooks#json-output)傳回 JSON 回應主體。要阻止工具呼叫，傳回 2xx 回應並包含適當的 `hookSpecificOutput` 欄位。HTTP 狀態代碼本身無法阻止操作。982您的端點會以與命令 hooks 相同的[輸出格式](/docs/zh-TW/hooks#json-output)傳回 JSON 回應主體，而 Claude Code 也會檢查回應狀態：

983

984* **2xx 狀態**：若要阻止工具呼叫，請在主體中傳回適當的 `hookSpecificOutput` 欄位。

985* **任何其他狀態，或請求失敗**：Claude Code 會回報[非阻斷性錯誤](/docs/zh-TW/hooks#exit-code-output)並讓該動作繼續進行。若要讓失敗的端點阻止該動作，請在 hook 上設定 [`onFailure: "block"`](/docs/zh-TW/hooks#block-the-action-when-a-hook-fails)。

983 986

984標頭值支援使用 `$VAR_NAME` 或 `${VAR_NAME}` 語法的環境變數插值。只有在 `allowedEnvVars` 陣列中列出的變數才會被解析；所有其他 `$VAR` 參考保持為空。987標頭值支援使用 `$VAR_NAME` 或 `${VAR_NAME}` 語法的環境變數插值。只有在 `allowedEnvVars` 陣列中列出的變數才會被解析；所有其他 `$VAR` 參考保持為空。

985 988

1103 1106

1104當您的 hook 在頂層而不是在 `hookSpecificOutput` 內傳回 `permissionDecision` 或 `additionalContext` 時，JSON 仍然會解析，Claude Code 會忽略放置錯誤的欄位而不報告錯誤。要查看它忽略了哪些欄位，使用 `claude --debug` 啟動 Claude Code 並在[除錯日誌](/docs/zh-TW/hooks#debug-hooks)中搜尋 `Hook JSON output had unrecognized keys`。1107當您的 hook 在頂層而不是在 `hookSpecificOutput` 內傳回 `permissionDecision` 或 `additionalContext` 時，JSON 仍然會解析，Claude Code 會忽略放置錯誤的欄位而不報告錯誤。要查看它忽略了哪些欄位，使用 `claude --debug` 啟動 Claude Code 並在[除錯日誌](/docs/zh-TW/hooks#debug-hooks)中搜尋 `Hook JSON output had unrecognized keys`。

1105 1108

1106<h3 id="debug-techniques">1109<h3 id="check-what-a-hook-did">

1107 除錯技術1110 檢查 hook 做了什麼

1108</h3>1111</h3>

1109 1112

1110按 `Ctrl+O` 開啟文字記錄檢視以檢查 hook 執行的結果：1113按 `Ctrl+O` 開啟逐字稿檢視，並尋找 hook 的結果：

1111 1114

1112* **成功執行**：您看不到任何內容，除非 hook 的 JSON 顯示某些內容，例如 `systemMessage` 或 Stop hook 回饋。1115* **成功**：您看不到任何內容，除非 hook 的 JSON 顯示某些內容，例如 `systemMessage` 或 Stop hook 回饋。

1113 * 要確認 hook 已執行，檢查其效果，例如重新格式化的檔案，或按照下面所述開啟除錯記錄並再次觸發 hook1116 * 要確認 hook 已執行，請檢查其效果，例如重新格式化的檔案

1114* **阻止錯誤**：在大多數事件上，您會看到 hook 的回饋。當 hook 的 JSON 做出阻止決策時，回饋是該決策的原因；否則它是 hook 的 stderr。在少數事件上，例如 `ConfigChange` 和 `Elicitation`，阻止不會顯示訊息。1117* **阻止錯誤**：在大多數事件上，您會看到隨阻止一起傳回的訊息，例如 `Blocked: rm commands are not allowed`。在少數事件上，例如 `ConfigChange` 和 `Elicitation`，您不會看到任何訊息。[退出碼 2](/docs/zh-TW/hooks#exit-code-2) 說明訊息的來源。

1115* **非阻止錯誤**：操作繼續進行，您會看到 `<hook name> hook error` 通知，其中包含簡短說明，例如 stderr 的第一行，前置 `Failed with non-blocking status code:`，或 JSON 驗證或解析訊息。1118* **非阻止錯誤**：您會看到 `<hook name> hook error` 通知，其中包含簡短說明，例如 `Failed with non-blocking status code:` 之後的 stderr 第一行，或 JSON 驗證或解析訊息。操作仍會繼續進行。

1116 1119

1117哪些退出代碼和 JSON 組合會產生每個結果，包括每個事件的例外，在參考的[退出代碼輸出](/docs/zh-TW/hooks#exit-code-output)部分中定義。1120若要查詢特定退出碼和 stdout 所對應的結果，包括每個事件的例外，請參閱參考文件中的[退出碼輸出](/docs/zh-TW/hooks#exit-code-output)。

1118 1121

1119有關完整的執行詳細資訊，包括哪些 hooks 相符、它們的退出代碼、stdout 和 stderr，請閱讀除錯日誌。使用 `claude --debug-file /tmp/claude.log` 啟動 Claude Code 以寫入已知路徑，然後在另一個終端中執行 `tail -f /tmp/claude.log`。如果您啟動時沒有該旗標，在工作階段中執行 `/debug` 以啟用記錄並找到日誌路徑。1122如需完整的執行詳細資訊，包括 hook 退出碼、stdout 和 stderr，請閱讀除錯日誌。使用 `claude --debug-file /tmp/claude.log` 啟動 Claude Code 以寫入已知路徑，然後在另一個終端機中執行 `tail -f /tmp/claude.log`。如果您啟動時沒有該旗標，請在工作階段中執行 `/debug` 以啟用日誌並找到日誌路徑。

1120 1123

1121<h2 id="learn-more">1124<h2 id="learn-more">

1122 深入瞭解1125 深入瞭解

interactive-mode.md +6 −5

Details

216| `^` | 第一個非空白字元 |216| `^` | 第一個非空白字元 |

217| `gg` | 輸入開始 |217| `gg` | 輸入開始 |

218| `G` | 最後一行的開頭 |218| `G` | 最後一行的開頭 |

219| `f{char}` | 跳到下一個字元出現位置 |219| `f{char}` | 跳到目前行上下一個字元出現位置 |

220| `F{char}` | 跳到上一個字元出現位置 |220| `F{char}` | 跳到目前行上上一個字元出現位置 |

221| `t{char}` | 跳到下一個字元出現位置之前 |221| `t{char}` | 跳到目前行上下一個字元出現位置之前 |

222| `T{char}` | 跳到上一個字元出現位置之後 |222| `T{char}` | 跳到目前行上上一個字元出現位置之後 |

223| `;` | 重複上一個 f/F/t/T 動作 |223| `;` | 重複上一個 f/F/t/T 動作 |

224| `,` | 反向重複上一個 f/F/t/T 動作 |224| `,` | 反向重複上一個 f/F/t/T 動作 |

225| `/` | 開啟反向歷史搜尋，與 `Ctrl+R` 相同。空搜尋提示會顯示提示：按 `Esc` 然後 `i` 然後 `/` 以改為開啟命令選單 |225| `/` | 開啟反向歷史搜尋，與 `Ctrl+R` 相同。空搜尋提示會顯示提示：按 `Esc` 然後 `i` 然後 `/` 以改為開啟命令選單 |

239| `dd` | 刪除行 |239| `dd` | 刪除行 |

240| `D` | 刪除到行尾 |240| `D` | 刪除到行尾 |

242| `df{char}`/`dt{char}` | 刪除到並包括，或刪除到下一個字元出現位置之前 |242| `df{char}`/`dt{char}` | 刪除到並包括，或刪除到目前行上下一個字元出現位置之前 |

245| `d0`/`c0`/`y0` | 從游標刪除、變更或複製回到行首。需要 Claude Code v2.1.281 或更新版本 |245| `d0`/`c0`/`y0` | 從游標刪除、變更或複製回到行首。需要 Claude Code v2.1.281 或更新版本 |

859* 單獨的 `#123`859* 單獨的 `#123`

860* 巢狀的 GitLab 路徑，例如 `group/subgroup/project#123`860* 巢狀的 GitLab 路徑，例如 `group/subgroup/project#123`

861* 程式碼跨度或程式碼區塊內的任何參考861* 程式碼跨度或程式碼區塊內的任何參考

862* 長度超過約 1,000 行或 100,000 個字元的回覆中的任何參考

862 863

863Claude Code 會根據從您的 git remote 識別出的儲存庫主機來建立連結，而不是根據參考所命名的儲存庫：864Claude Code 會根據從您的 git remote 識別出的儲存庫主機來建立連結，而不是根據參考所命名的儲存庫：

864 865

jetbrains.md +8 −4

Details

55 使用方式55 使用方式

56</h2>56</h2>

57 57

~~58<h3 id="from-your-ide">~~58<span id="from-your-ide" />

~~59 從您的 IDE~~59

60<h3 id="run-claude-code-from-your-ide">

61 從您的 IDE 執行 Claude Code

60</h3>62</h3>

61 63

62從 IDE 的整合終端機執行 `claude`，所有整合功能將處於活躍狀態。64從 IDE 的整合終端機執行 `claude`，所有整合功能將處於活躍狀態。

63 65

~~64<h3 id="from-external-terminals">~~66<span id="from-external-terminals" />

~~65 從外部終端機~~67

68<h3 id="connect-from-an-external-terminal">

69 從外部終端機連接

66</h3>70</h3>

67 71

68在任何外部終端機中使用 `/ide` 命令，將 Claude Code 連接到您的 JetBrains IDE 並啟動所有功能：72在任何外部終端機中使用 `/ide` 命令，將 Claude Code 連接到您的 JetBrains IDE 並啟動所有功能：

managed-settings.md +2 −0

Details

79 79

80Jamf、Iru、Intune 和群組原則的入門範本位於 [MDM 範例儲存庫](https://github.com/anthropics/claude-code/tree/main/examples/mdm)。80Jamf、Iru、Intune 和群組原則的入門範本位於 [MDM 範例儲存庫](https://github.com/anthropics/claude-code/tree/main/examples/mdm)。

81 81

82如果您的組織已套用 [HIPAA 設定](/docs/zh-TW/hipaa-setup#deploy-managed-settings)，請參閱[設定範例儲存庫](https://github.com/anthropics/claude-code/tree/main/examples/settings)中的 `settings-hipaa.json` 和 `README-hipaa.md`，以取得更完整的 `managed-settings.json`，其中包含沙箱機制、網路允許清單、憑證保護和本機資料保留。

82對於受管 MCP 伺服器，您可以透過 `managed-mcp.json` 與這些伺服器一起部署或透過 [`managedMcpServers`](/docs/zh-TW/settings-reference#managedmcpservers) 金鑰提供，請參閱[受管 MCP 設定](/docs/zh-TW/managed-mcp)。84對於受管 MCP 伺服器，您可以透過 `managed-mcp.json` 與這些伺服器一起部署或透過 [`managedMcpServers`](/docs/zh-TW/settings-reference#managedmcpservers) 金鑰提供，請參閱[受管 MCP 設定](/docs/zh-TW/managed-mcp)。

83 85

84<h3 id="where-and-when-a-policy-applies">86<h3 id="where-and-when-a-policy-applies">

mcp.md +18 −10

Details

181 181

182每一個都是 [安裝 MCP 伺服器](#installing-mcp-servers)中四個選項之一接受的輸入。在下面找到您擁有的形狀，將其轉換為 Claude Code 接受的命令。除非您新增 `--scope project` 或 `--scope user`，否則每個命令都會寫入 [本機範圍](#local-scope)。182每一個都是 [安裝 MCP 伺服器](#installing-mcp-servers)中四個選項之一接受的輸入。在下面找到您擁有的形狀，將其轉換為 Claude Code 接受的命令。除非您新增 `--scope project` 或 `--scope user`，否則每個命令都會寫入 [本機範圍](#local-scope)。

183 183

184<h4 id="from-a-url">184<span id="from-a-url" />

185 從 URL185

186<h4 id="add-a-server-from-a-url">

187 從 URL 新增伺服器

186</h4>188</h4>

187 189

188URL 表示伺服器是遠端的。對於 `https://` 端點，使用 `--transport http` 新增它，或在指示說端點使用 SSE 時遵循 [選項 2](#option-2-add-a-remote-sse-server)。對於 `wss://` 端點，改為使用 [選項 4](#option-4-add-a-remote-websocket-server)，因為 `--transport` 不接受 `ws`：190URL 表示伺服器是遠端的。對於 `https://` 端點，使用 `--transport http` 新增它，或在指示說端點使用 SSE 時遵循 [選項 2](#option-2-add-a-remote-sse-server)。對於 `wss://` 端點，改為使用 [選項 4](#option-4-add-a-remote-websocket-server)，因為 `--transport` 不接受 `ws`：

193 195

194如果指示也提供 API 金鑰或 token 標頭，請使用 `--header` 傳遞它，如 [選項 1](#option-1-add-a-remote-http-server)所示。196如果指示也提供 API 金鑰或 token 標頭，請使用 `--header` 傳遞它，如 [選項 1](#option-1-add-a-remote-http-server)所示。

195 197

196<h4 id="from-an-npx-uvx-or-binary-command">198<span id="from-an-npx-uvx-or-binary-command" />

197 從 `npx`、`uvx` 或二進位命令199

200<h4 id="add-a-server-from-an-npx-uvx-or-binary-command">

201 從 `npx`、`uvx` 或二進位命令新增伺服器

198</h4>202</h4>

199 203

200啟動命令表示伺服器作為本機 stdio 程序執行。將整個命令放在 `--` 之後，以便 Claude Code 將旗標（例如 `-y`）傳遞給啟動伺服器的命令，而不是將其讀取為自身的選項。使用 `--env` 傳遞指示要求的任何環境變數，在伺服器名稱之後和 `--` 之前：204啟動命令表示伺服器作為本機 stdio 程序執行。將整個命令放在 `--` 之後，以便 Claude Code 將旗標（例如 `-y`）傳遞給啟動伺服器的命令，而不是將其讀取為自身的選項。使用 `--env` 傳遞指示要求的任何環境變數，在伺服器名稱之後和 `--` 之前：

205 209

206[選項 3](#option-3-add-a-local-stdio-server)完整涵蓋 `--` 分隔符。210[選項 3](#option-3-add-a-local-stdio-server)完整涵蓋 `--` 分隔符。

207 211

208<h4 id="from-an-mcpservers-json-block">212<span id="from-an-mcpservers-json-block" />

209 從 `mcpServers` JSON 區塊213

214<h4 id="add-a-server-from-an-mcpservers-json-block">

215 從 `mcpServers` JSON 區塊新增伺服器

210</h4>216</h4>

211 217

212為另一個 MCP 用戶端（例如 Claude Desktop）編寫的 `mcpServers` 區塊使用 Claude Code 讀取的包裝器金鑰和項目形狀。將 `mcpServers` 內的物件傳遞給 `claude mcp add-json`，而不是包裝器。兩個項目需要先修復：218為另一個 MCP 用戶端（例如 Claude Desktop）編寫的 `mcpServers` 區塊使用 Claude Code 讀取的包裝器金鑰和項目形狀。將 `mcpServers` 內的物件傳遞給 `claude mcp add-json`，而不是包裝器。兩個項目需要先修復：

367 373

368在 v2 上，Claude Code 也：374在 v2 上，Claude Code 也：

369 375

370* 詢問 HTTP 和 stdio 伺服器是否支援較新的修訂，並與支援的伺服器一起使用它。在擷取功能旗標的工作階段中，它也會詢問 claude.ai 連接器伺服器。它連接到每個其他伺服器，如 v1 所做的那樣。376* 詢問 HTTP、stdio 和 claude.ai 連接器伺服器是否支援較新的修訂，並與支援的伺服器一起使用它。它連接到每個其他伺服器，如 v1 所做的那樣。

371* 在 [它保持開啟的流](#notification-streams-on-the-v2-runtime)上從較新修訂上的伺服器接收 `list_changed` 通知。377* 在 [它保持開啟的流](#notification-streams-on-the-v2-runtime)上從較新修訂上的伺服器接收 `list_changed` 通知。

372* 不註冊在較新修訂上連接的 [頻道](#push-messages-with-channels)伺服器，因為該修訂無法攜帶頻道訊息。378* 不註冊在較新修訂上連接的 [頻道](#push-messages-with-channels)伺服器，因為該修訂無法攜帶頻道訊息。

373* 失敗 [MCP OAuth 登入](#authenticate-with-remote-mcp-servers)，其授權回應命名意外發行者。379* 失敗 [MCP OAuth 登入](#authenticate-with-remote-mcp-servers)，其授權回應命名意外發行者。

891 從命令列進行身份驗證897 從命令列進行身份驗證

892</h3>898</h3>

893 899

894`claude mcp login <name>` 命令直接從您的 shell 執行已設定伺服器的 OAuth 流程，因此您不需要在工作階段內開啟 `/mcp` 面板。900`claude mcp login <name>` 命令直接從您的 shell 執行已設定伺服器的 OAuth 流程，因此您不需要在工作階段內開啟 `/mcp` 面板。對於 claude.ai 連接器，請按照 [從您的 shell 再次授權連接器](/docs/zh-TW/remote-control#authorize-a-connector-again-from-your-shell) 操作。

895 901

896```bash theme={null}902```bash theme={null}

897claude mcp login sentry903claude mcp login sentry

1581 工具搜尋在 Microsoft Foundry [部署於 Azure 的部署](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)上不受支援，該部署在伺服器端拒絕它：Claude Code 偵測到拒絕並改為對該部署預先載入 MCP 工具。[`ENABLE_TOOL_SEARCH`](#configure-tool-search) 無法覆蓋此設定，因為拒絕來自部署本身。1587 工具搜尋在 Microsoft Foundry [部署於 Azure 的部署](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)上不受支援，該部署在伺服器端拒絕它：Claude Code 偵測到拒絕並改為對該部署預先載入 MCP 工具。[`ENABLE_TOOL_SEARCH`](#configure-tool-search) 無法覆蓋此設定，因為拒絕來自部署本身。

1582</Note>1588</Note>

1583 1589

1584<h3 id="for-mcp-server-authors">1590<span id="for-mcp-server-authors" />

1585 針對 MCP 伺服器作者1591

1592<h3 id="tool-search-for-mcp-server-authors">

1593 針對 MCP 伺服器作者的工具搜尋

1586</h3>1594</h3>

1587 1595

1588如果您正在建立 MCP 伺服器，啟用工具搜尋時伺服器指令欄位會變得更有用。伺服器指令幫助 Claude 瞭解何時搜尋您的工具，類似於 [skills](/docs/zh-TW/skills) 的運作方式。1596如果您正在建立 MCP 伺服器，啟用工具搜尋時伺服器指令欄位會變得更有用。伺服器指令幫助 Claude 瞭解何時搜尋您的工具，類似於 [skills](/docs/zh-TW/skills) 的運作方式。

monitoring-usage.md +425 −411

Details

573在 Claude Tag 頻道工作階段中，Claude 作為組織的[共用身分](/docs/zh-TW/cloud-environments#set-the-environment-a-claude-tag-channel-uses)而不是任何成員工作，因此不要依賴 `user.*` 屬性來識別誰標記了 Claude。573在 Claude Tag 頻道工作階段中，Claude 作為組織的[共用身分](/docs/zh-TW/cloud-environments#set-the-environment-a-claude-tag-channel-uses)而不是任何成員工作，因此不要依賴 `user.*` 屬性來識別誰標記了 Claude。

574 574

575<h2 id="available-metrics-and-events">575<h2 id="available-metrics-and-events">

576 可用的指標和事件576 可用的指標與事件

577</h2>577</h2>

578 578

579<h3 id="standard-attributes">579<h3 id="standard-attributes">

580 標準屬性580 標準屬性

581</h3>581</h3>

582 582

583所有指標和事件都共享這些標準屬性：583所有指標與事件皆共用以下標準屬性：

584 584

585| 屬性 | 描述 | 控制方式 |585| 屬性 | 說明 | 控制方式 |

586| - | - | - |586| - | - | - |

590| `app.entrypoint` | 工作階段的啟動方式，例如 `cli`、`sdk-cli`、`sdk-ts`、`sdk-py`、`claude-vscode` 或 Claude Tag 工作階段的 `claude-in-slack` | `OTEL_METRICS_INCLUDE_ENTRYPOINT`（預設值：false） |590| `app.entrypoint` | 工作階段的啟動方式，例如 `cli`、`sdk-cli`、`sdk-ts`、`sdk-py`、`claude-vscode`，或 Claude Tag 工作階段的 `claude-in-slack` | `OTEL_METRICS_INCLUDE_ENTRYPOINT`（預設：false） |

597| 來自 `OTEL_RESOURCE_ATTRIBUTES` 的鍵 | 您設定的自訂屬性，例如 `department` 或 `team.id`。請參閱[多團隊組織支援](#multi-team-organization-support) | `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES`（預設值：true） |597| 來自 `OTEL_RESOURCE_ATTRIBUTES` 的鍵 | 您設定的自訂屬性，例如 `department` 或 `team.id`。請參閱[多團隊組織支援](#multi-team-organization-support) | `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES`（預設：true） |

598| `vcs.repository.url.full`、`vcs.owner.name`、`vcs.repository.name`、`vcs.provider.name` | 工作階段儲存庫的身份，衍生自其 `origin` 遠端。請參閱[儲存庫屬性](#repository-attributes) | `OTEL_METRICS_INCLUDE_REPOSITORY`（預設值：false）。需要 Claude Code v2.1.269 或更新版本 |598| `vcs.repository.url.full`、`vcs.owner.name`、`vcs.repository.name`、`vcs.provider.name` | 工作階段儲存庫的身分，由其 `origin` 遠端衍生而來。請參閱[儲存庫屬性](#repository-attributes) | `OTEL_METRICS_INCLUDE_REPOSITORY`（預設：false）。需要 Claude Code v2.1.269 或更新版本 |

~~599~~ 599

600在工作階段通過 `/login` 登入到[Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway)時，CLI 會使用已驗證的身份戳記匯出：`user.id` 是 IdP 主體，`user.email` 是已登入的電子郵件，`user.groups` 以逗號分隔的字串形式攜帶 IdP 群組成員資格。每個匯出還攜帶 `identity.source: gateway-oidc`。閘道身份最後應用，因此通過 `OTEL_RESOURCE_ATTRIBUTES` 設定的 `user.*` 和 `identity.*` 鍵在這些工作階段上被忽略。600在透過 `/login` 登入 [Claude apps 閘道](/docs/zh-TW/claude-apps-gateway)的工作階段中，CLI 會以經過身分驗證的身分標記匯出資料：`user.id` 為 IdP subject，`user.email` 為登入的電子郵件，而 `user.groups` 則以逗號分隔的字串承載 IdP 群組成員資格。每次匯出也會帶有 `identity.source: gateway-oidc`。閘道身分會最後套用，因此在這些工作階段中，透過 `OTEL_RESOURCE_ATTRIBUTES` 設定的 `user.*` 與 `identity.*` 鍵會被忽略。

~~601~~ 601

602對於通過閘道連線的 Claude Desktop 和 Cowork 工作階段上的身份屬性，請參閱[閘道 `telemetry` 參考](/docs/zh-TW/claude-apps-gateway-config#telemetry)。602<Note>

~~603~~ 603 Claude Code 在開發人員登入之前記錄的事件不會帶有閘道身分。當 Claude Code 在未登入閘道的狀態下開啟工作階段時（例如在[閘道結束登入](/docs/zh-TW/errors#cloud-gateway-session-expired)之後），登入前記錄的啟動事件會帶有匿名的 `user.id`，且沒有 `identity.source`。這些事件包括 [`managed_settings_resolved`](#managed-settings-resolved-event)、[`plugin_loaded`](#plugin-loaded-event) 與 [`mcp_server_connection`](#mcp-server-connection-event)。

604事件另外包括以下屬性。這些永遠不會附加到指標，因為它們會導致無限的基數：604</Note>

~~605~~ 605

606* `prompt.id`：UUID，將使用者提示與所有後續事件關聯到下一個提示。請參閱[事件相關屬性](#event-correlation-attributes)。606關於透過閘道連線的 Claude Desktop 與 Cowork 工作階段上的身分屬性，請參閱[閘道 `telemetry` 參考](/docs/zh-TW/claude-apps-gateway-config#telemetry)。

607* `workspace.host_paths`：在桌面應用程式中選擇的主機工作區目錄，作為字串陣列607

608* `workflow.run_id`：執行識別碼，前綴為 `wf_`，在屬於[工作流程](/docs/zh-TW/workflows)工具執行的代理程式發出的 API 和工具事件上。按一個 `workflow.run_id` 篩選事件會重建該執行的 API 請求和工具結果。識別碼涵蓋工作流程指令碼產生的代理程式以及這些代理程式依次產生的任何代理程式，例如技能呼叫。它與工作流程工具結果中報告的執行識別碼相符。在所有其他事件上不存在。需要 Claude Code v2.1.202 或更新版本608事件還會額外包含以下屬性。這些屬性永遠不會附加到指標上，因為它們會導致無上限的基數：

609* `workflow.name`：工作流程的名稱，其指令碼的 `meta.name`，與 `workflow.run_id` 一起發出。當執行未修改的內建指令碼時，內建工作流程名稱會逐字出現。使用者撰寫的名稱（包括內建指令碼的編輯副本）會被替換為 `custom`，除非設定了 `OTEL_LOG_TOOL_DETAILS=1`。需要 Claude Code v2.1.202 或更新版本609

610* `prompt.id`：將使用者提示詞與其後直到下一個提示詞之前的所有事件相關聯的 UUID。請參閱[事件關聯屬性](#event-correlation-attributes)。

611* `workspace.host_paths`：在桌面應用程式中選取的主機工作區目錄，以字串陣列表示

612* `workflow.run_id`：執行識別碼，前綴為 `wf_`，出現在隸屬於 [Workflow](/docs/zh-TW/workflows) 工具執行的 agent 所發出的 API 與工具事件上。以單一 `workflow.run_id` 篩選事件，即可重建該次執行的 API 請求與工具結果。此識別碼涵蓋工作流程腳本所產生的 agent，以及這些 agent 再產生的任何 agent，例如 skill 呼叫。它與 Workflow 工具結果中回報的執行識別碼相符。在所有其他事件上皆不存在。需要 Claude Code v2.1.202 或更新版本

613* `workflow.name`：工作流程名稱，即其腳本的 `meta.name`，與 `workflow.run_id` 一同發出。當執行的是未經修改的內建腳本時，內建工作流程名稱會原樣出現。使用者撰寫的名稱（包括內建腳本的編輯副本）會被替換為 `custom`，除非設定了 `OTEL_LOG_TOOL_DETAILS=1`。需要 Claude Code v2.1.202 或更新版本

610 614

611<h4 id="repository-attributes">615<h4 id="repository-attributes">

612 儲存庫屬性616 儲存庫屬性

613</h4>617</h4>

614 618

615設定 `OTEL_METRICS_INCLUDE_REPOSITORY=true` 以使用工作階段儲存庫的身份標記指標和事件，以便共享收集器可以按儲存庫歸因使用情況。需要 Claude Code v2.1.269 或更新版本。619設定 `OTEL_METRICS_INCLUDE_REPOSITORY=true`，即可以工作階段儲存庫的身分標記指標與事件，讓共用的收集器能按儲存庫歸屬使用量。需要 Claude Code v2.1.269 或更新版本。

616 620

617Claude Code 每個工作階段從儲存庫的 `origin` 遠端衍生這些屬性一次。當儲存庫的 HTTPS 和 SSH 遠端命名相同的主機和相同的路徑時（如在 GitHub、GitLab 和 Bitbucket Cloud 上所做的那樣），兩者都會產生相同的值：621Claude Code 會在每個工作階段中從儲存庫的 `origin` 遠端衍生這些屬性一次。當儲存庫的 HTTPS 與 SSH 遠端指向相同的主機與相同的路徑時（如 GitHub、GitLab 與 Bitbucket Cloud），兩者會產生相同的值：

618 622

619| 屬性 | 值 |623| 屬性 | 值 |

620| - | - |624| - | - |

625 629

626值是小寫的，遠端 URL 中的認證、查詢字串和片段永遠不會出現在其中。當工作階段沒有 `origin` 遠端、遠端不是 URL 形狀或唯一的封閉儲存庫是您的主目錄時，屬性會被省略。630值會轉為小寫，且遠端 URL 中的憑證、查詢字串與片段永遠不會出現在其中。當工作階段沒有 `origin` 遠端、遠端不是 URL 形式，或唯一包含的儲存庫是您的家目錄時，這些屬性會被省略。

627 631

628要從[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)取得這些屬性，請在其[雲端環境](/docs/zh-TW/cloud-environments#set-environment-variables)上設定遙測變數，包括 `OTEL_METRICS_INCLUDE_REPOSITORY`。還要在環境的[網路存取](/docs/zh-TW/cloud-environments#network-access)中允許您的收集器的網域。632若要從[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)取得這些屬性，請在其[雲端環境](/docs/zh-TW/cloud-environments#set-environment-variables)上設定遙測變數，包括 `OTEL_METRICS_INCLUDE_REPOSITORY`。同時也請在該環境的[網路存取](/docs/zh-TW/cloud-environments#network-access)中允許您收集器的網域。

629 633

630您在 [`OTEL_RESOURCE_ATTRIBUTES`](#multi-team-organization-support) 中宣告的 `vcs.*` 鍵會替換該鍵的衍生值。如果您宣告 `vcs.repository.url.full`，Claude Code 永遠不會讀取遠端，只會報告您宣告的鍵。634您在 [`OTEL_RESOURCE_ATTRIBUTES`](#multi-team-organization-support) 中宣告的 `vcs.*` 鍵會取代該鍵的衍生值。若您宣告了 `vcs.repository.url.full`，Claude Code 將永遠不會讀取遠端，且只會回報您宣告的鍵。

631 635

632如果一個儲存庫的 HTTPS 和 SSH 複製報告不同的值，例如在自託管安裝上，其 HTTPS 複製 URL 攜帶 SSH URL 缺少的路徑前綴，請在 `OTEL_RESOURCE_ATTRIBUTES` 中宣告 `vcs.repository.url.full` 以及您想要報告的每個其他 `vcs.*` 鍵。然後每個複製都會報告您宣告的身份。636若同一儲存庫的 HTTPS 與 SSH 複製回報不同的值（例如在自行託管的安裝中，HTTPS 複製 URL 帶有 SSH URL 所沒有的路徑前綴），請在 `OTEL_RESOURCE_ATTRIBUTES` 中宣告 `vcs.repository.url.full`，以及您希望回報的所有其他 `vcs.*` 鍵。如此一來，每個複製都會回報您宣告的身分。

633 637

634屬性只流向您自己的匯出器；Anthropic 的遙測會丟棄每個 `vcs.*` 鍵。638這些屬性只會流向您自己的匯出器；Anthropic 的遙測會捨棄所有 `vcs.*` 鍵。

635 639

636<h3 id="metrics">640<h3 id="metrics">

637 指標641 指標

638</h3>642</h3>

639 643

640Claude Code 匯出以下指標。「單位」欄顯示附加到每個指標的 OpenTelemetry 單位字串；計數指標不攜帶任何單位。644Claude Code 會匯出以下指標。「單位」欄顯示附加到每個指標的 OpenTelemetry 單位字串；計數類指標不帶單位。

641 645

642| 指標名稱 | 描述 | 單位 |646| 指標名稱 | 說明 | 單位 |

643| - | - | - |647| - | - | - |

644| `claude_code.session.count` | 啟動的 CLI 工作階段計數 | 無 |648| `claude_code.session.count` | 已啟動的 CLI 工作階段計數 | 無 |

645| `claude_code.lines_of_code.count` | 修改的程式碼行計數 | 無 |649| `claude_code.lines_of_code.count` | 已修改的程式碼行數計數 | 無 |

646| `claude_code.pull_request.count` | 建立的提取請求數 | 無 |650| `claude_code.pull_request.count` | 已建立的 pull request 數量 | 無 |

647| `claude_code.commit.count` | 建立的 git 提交數 | 無 |651| `claude_code.commit.count` | 已建立的 git 提交數量 | 無 |

648| `claude_code.cost.usage` | Claude Code 工作階段的成本 | USD |652| `claude_code.cost.usage` | Claude Code 工作階段的成本 | USD |

650| `claude_code.code_edit_tool.decision` | 程式碼編輯工具權限決定計數 | 無 |654| `claude_code.code_edit_tool.decision` | 程式碼編輯工具權限決定的計數 | 無 |

651| `claude_code.active_time.total` | 總活躍時間 | s |655| `claude_code.active_time.total` | 總活躍時間 | s |

652 656

653當 `prometheus` 是 `OTEL_METRICS_EXPORTER` 中列出的唯一匯出器時，Claude Code 會從匯出的指標中省略 `USD`、`tokens` 和 `s` 單位，以便抓取保持有效的 Prometheus 文字格式。指標名稱不會改變，結合匯出器的配置（例如 `otlp,prometheus`）會保留單位。在 v2.1.216 之前，Prometheus 抓取包含一些抓取器拒絕的 OpenMetrics 專用 `# UNIT` 行。657當 `prometheus` 是 `OTEL_METRICS_EXPORTER` 中列出的唯一匯出器時，Claude Code 會從匯出的指標中省略 `USD`、`tokens` 與 `s` 單位，使抓取結果保持為有效的 Prometheus 文字格式。指標名稱不會改變，而結合多個匯出器的設定（例如 `otlp,prometheus`）會保留單位。在 v2.1.216 之前，Prometheus 抓取結果包含僅適用於 OpenMetrics 的 `# UNIT` 行，部分抓取器會拒絕這些行。

654 658

655<h3 id="metric-details">659<h3 id="metric-details">

656 指標詳細資訊660 指標詳細資訊

657</h3>661</h3>

658 662

659每個指標都包括上面列出的標準屬性。具有額外上下文特定屬性的指標如下所述。663每個指標都包含上方列出的標準屬性。帶有額外情境特定屬性的指標會在下方註明。

660 664

661<h4 id="session-counter">665<h4 id="session-counter">

662 工作階段計數器666 工作階段計數器

667**屬性**：671**屬性**：

668 672

669* 所有[標準屬性](#standard-attributes)673* 所有[標準屬性](#standard-attributes)

670* `start_type`：工作階段的啟動方式。`"fresh"`、`"resume"`、`"continue"` 或 `"agents_view"` 之一。`"agents_view"` 值識別 `claude agents` 儀表板程序，這是使用者啟動的本地 UI 而不是對話工作階段。在此值上篩選以在您的儀表板中將 UI 程序啟動與對話工作階段分開。674* `start_type`：工作階段的啟動方式。為 `"fresh"`、`"resume"`、`"continue"` 或 `"agents_view"` 之一。`"agents_view"` 值代表 `claude agents` 儀表板程序，這是使用者啟動的本機 UI，而非對話工作階段。在您的儀表板中篩選此值，即可將 UI 程序啟動與對話工作階段區分開來。

671 675

672<h4 id="lines-of-code-counter">676<h4 id="lines-of-code-counter">

673 程式碼行計數器677 程式碼行數計數器

674</h4>678</h4>

675 679

676當新增或移除程式碼時遞增。680在新增或移除程式碼時遞增。

677 681

678**屬性**：682**屬性**：

679 683

680* 所有[標準屬性](#standard-attributes)684* 所有[標準屬性](#standard-attributes)

681* `type`：（`"added"`、`"removed"`）685* `type`：（`"added"`、`"removed"`）

682* `model`：進行變更的模型的模型識別碼（例如，"claude-sonnet-5"）686* `model`：進行變更之模型的模型識別碼（例如 "claude-sonnet-5"）

683 687

684<h4 id="pull-request-counter">688<h4 id="pull-request-counter">

685 提取請求計數器689 Pull request 計數器

686</h4>690</h4>

687 691

688當 Claude Code 通過 shell 命令或 MCP 工具建立提取請求或合併請求時遞增。692當 Claude Code 透過 shell 命令或 MCP 工具建立 pull request 或 merge request 時遞增。

689 693

690**屬性**：694**屬性**：

691 695

695 提交計數器699 提交計數器

696</h4>700</h4>

697 701

698通過 Claude Code 建立 git 提交時遞增。702透過 Claude Code 建立 git 提交時遞增。

699 703

700**屬性**：704**屬性**：

701 705

705 成本計數器709 成本計數器

706</h4>710</h4>

707 711

708在每個 API 請求後遞增。712在每次 API 請求之後遞增。

709 713

710`agent.name`、`skill.name`、`plugin.name`、`mcp_server.name` 和 `mcp_tool.name` 屬性預設會將某些名稱編輯為 `"custom"` 或 `"third-party"` 佔位符。如果您設定 `OTEL_LOG_TOOL_DETAILS=1`，它們會改為攜帶真實名稱。在 v2.1.273 之前，成本和權杖計數器以及 `api_request`、`api_error` 和 `api_refusal` 事件即使設定了 `OTEL_LOG_TOOL_DETAILS=1` 也攜帶編輯的值。714`agent.name`、`skill.name`、`plugin.name`、`mcp_server.name` 與 `mcp_tool.name` 屬性預設都會將部分名稱遮蔽為 `"custom"` 或 `"third-party"` 預留值。若您設定了 `OTEL_LOG_TOOL_DETAILS=1`，它們會改為帶有實際名稱。在 v2.1.273 之前，即使設定了 `OTEL_LOG_TOOL_DETAILS=1`，成本與 token 計數器以及 `api_request`、`api_error` 與 `api_refusal` 事件仍帶有遮蔽後的值。

711 715

712**屬性**：716**屬性**：

713 717

714* 所有[標準屬性](#standard-attributes)718* 所有[標準屬性](#standard-attributes)

715* `model`：模型識別碼（例如，"claude-sonnet-5"）719* `model`：模型識別碼（例如 "claude-sonnet-5"）

716* `query_source`：發出請求的子系統的類別。`"main"`、`"subagent"` 或 `"auxiliary"` 之一720* `query_source`：發出請求之子系統的類別。為 `"main"`、`"subagent"` 或 `"auxiliary"` 之一

717* `speed`：當請求使用快速模式時為 `"fast"`。否則不存在721* `speed`：當請求使用快速模式時為 `"fast"`。否則不存在

718* `effort`：應用於請求的[努力級別](/docs/zh-TW/model-config#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。當 Claude Code 不發送努力級別時不存在，例如在不支援努力的模型上。722* `effort`：套用於請求的 [effort 等級](/docs/zh-TW/model-config#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。當 Claude Code 未傳送 effort 等級時不存在，例如在不支援 effort 的模型上。

719* `agent.name`：發出請求的子代理程式類型。內建代理程式名稱和來自官方市場外掛程式的代理程式會逐字出現。其他使用者定義的代理程式名稱會被替換為 `"custom"`。當請求不是由命名的子代理程式類型發出時不存在。723* `agent.name`：發出請求的 subagent 類型。內建 agent 名稱以及來自官方市集外掛的 agent 會原樣出現。其他使用者定義的 agent 名稱會被替換為 `"custom"`。當請求並非由具名的 subagent 類型發出時不存在。

720* `skill.name`：對請求有效的技能，由技能工具或 `/` 命令設定，或由產生的子代理程式繼承。內建、捆綁、使用者定義和官方市場外掛程式技能名稱會逐字出現。第三方外掛程式技能名稱會被替換為 `"third-party"`。當沒有技能有效時不存在。724* `skill.name`：該請求作用中的 skill，由 Skill 工具或 `/` 命令設定，或由產生的 subagent 繼承。內建、隨附、使用者定義及官方市集外掛的 skill 名稱會原樣出現。第三方外掛的 skill 名稱會被替換為 `"third-party"`。當沒有作用中的 skill 時不存在。

721* `plugin.name`：當活躍的技能或子代理程式由外掛程式提供時的擁有外掛程式。官方市場外掛程式名稱會逐字出現。第三方外掛程式名稱會被替換為 `"third-party"`。當技能和子代理程式都沒有擁有外掛程式時不存在。725* `plugin.name`：當作用中的 skill 或 subagent 由外掛提供時，為其所屬外掛。官方市集外掛名稱會原樣出現。第三方外掛名稱會被替換為 `"third-party"`。當 skill 與 subagent 皆沒有所屬外掛時不存在。

722* `marketplace.name`：擁有外掛程式的安裝來源市場。即使設定了 `OTEL_LOG_TOOL_DETAILS=1`，也只針對官方市場外掛程式發出。否則不存在。726* `marketplace.name`：所屬外掛的安裝來源市集。即使設定了 `OTEL_LOG_TOOL_DETAILS=1`，也只會針對官方市集外掛發出。否則不存在。

723* `mcp_server.name`：此請求消費其工具結果的 MCP 伺服器。內建、claude.ai 代理和官方登錄伺服器名稱會逐字出現。使用者配置的伺服器名稱會被替換為 `"custom"`。當請求未消費 MCP 工具結果時不存在。在 v2.1.222 之前，Claude Code 在每個 MCP 工具呼叫後的請求上設定此屬性，而不僅在消費工具結果的請求上，因此聚合它的儀表板在您升級後會顯示下降。727* `mcp_server.name`：此請求所使用之工具結果所屬的 MCP 伺服器。內建、經由 claude.ai 代理及官方登錄檔的伺服器名稱會原樣出現。使用者設定的伺服器名稱會被替換為 `"custom"`。當請求未使用任何 MCP 工具結果時不存在。在 v2.1.222 之前，Claude Code 會在 MCP 工具呼叫之後的每個請求上設定此屬性，而不僅限於使用工具結果的請求，因此彙總此屬性的儀表板在您升級後會出現下降。

724* `mcp_tool.name`：此請求消費其結果的 MCP 工具，具有與 `mcp_server.name` 相同的編輯和版本行為。當請求未消費 MCP 工具結果時不存在。728* `mcp_tool.name`：此請求所使用之結果所屬的 MCP 工具，其遮蔽與版本行為與 `mcp_server.name` 相同。當請求未使用任何 MCP 工具結果時不存在。

725 729

726<h4 id="token-counter">730<h4 id="token-counter">

727 權杖計數器731 Token 計數器

728</h4>732</h4>

729 733

730在每個 API 請求後遞增。734在每次 API 請求之後遞增。

731 735

732**屬性**：736**屬性**：

733 737

734* 所有[標準屬性](#standard-attributes)738* 所有[標準屬性](#standard-attributes)

735* `type`：（`"input"`、`"output"`、`"cacheRead"`、`"cacheCreation"`）。`"input"` 類型不包含從提示詞快取讀取或寫入的 token，這些會計入 `"cacheRead"` 與 `"cacheCreation"`739* `type`：（`"input"`、`"output"`、`"cacheRead"`、`"cacheCreation"`）。`"input"` 類型不包含從提示詞快取讀取或寫入的 token，這些會計入 `"cacheRead"` 與 `"cacheCreation"`

736* `model`：模型識別碼（例如，"claude-sonnet-5"）740* `model`：模型識別碼（例如 "claude-sonnet-5"）

737* `query_source`：發出請求的子系統的類別。`"main"`、`"subagent"` 或 `"auxiliary"` 之一741* `query_source`：發出請求之子系統的類別。為 `"main"`、`"subagent"` 或 `"auxiliary"` 之一

738* `speed`：當請求使用快速模式時為 `"fast"`。否則不存在742* `speed`：當請求使用快速模式時為 `"fast"`。否則不存在

739* `effort`：應用於請求的[努力級別](/docs/zh-TW/model-config#adjust-effort-level)。請參閱[成本計數器](#cost-counter)以了解詳細資訊。743* `effort`：套用於請求的 [effort 等級](/docs/zh-TW/model-config#adjust-effort-level)。詳細資訊請參閱[成本計數器](#cost-counter)。

740* `agent.name`、`skill.name`、`plugin.name`、`marketplace.name`、`mcp_server.name`、`mcp_tool.name`：請求的技能、外掛程式、代理程式和 MCP 歸因。請參閱[成本計數器](#cost-counter)以了解定義和編輯行為。744* `agent.name`、`skill.name`、`plugin.name`、`marketplace.name`、`mcp_server.name`、`mcp_tool.name`：請求的 skill、外掛、agent 與 MCP 歸屬。定義與遮蔽行為請參閱[成本計數器](#cost-counter)。

741 745

742<h4 id="code-edit-tool-decision-counter">746<h4 id="code-edit-tool-decision-counter">

743 程式碼編輯工具決定計數器747 程式碼編輯工具決定計數器

744</h4>748</h4>

745 749

746當使用者接受或拒絕 Edit、Write 或 NotebookEdit 工具使用時遞增。750當使用者接受或拒絕 Edit、Write 或 NotebookEdit 工具的使用時遞增。

747 751

748**屬性**：752**屬性**：

749 753

750* 所有[標準屬性](#standard-attributes)754* 所有[標準屬性](#standard-attributes)

751* `tool_name`：工具名稱（`"Edit"`、`"Write"`、`"NotebookEdit"`）755* `tool_name`：工具名稱（`"Edit"`、`"Write"`、`"NotebookEdit"`）

752* `decision`：使用者決定（`"accept"`、`"reject"`）756* `decision`：使用者決定（`"accept"`、`"reject"`）

753* `source`：決定來自何處。`"config"`、`"hook"`、`"user_permanent"`、`"user_temporary"`、`"user_abort"` 或 `"user_reject"` 之一。請參閱[工具決定事件](#tool-decision-event)以了解每個值的含義。757* `source`：決定的來源。為 `"config"`、`"hook"`、`"user_permanent"`、`"user_temporary"`、`"user_abort"` 或 `"user_reject"` 之一。各值的意義請參閱[工具決定事件](#tool-decision-event)。

754* `language`：編輯檔案的程式設計語言，例如 `"TypeScript"`、`"Python"`、`"JavaScript"` 或 `"Markdown"`。對於無法識別的副檔名傳回 `"unknown"`。758* `language`：所編輯檔案的程式語言，例如 `"TypeScript"`、`"Python"`、`"JavaScript"` 或 `"Markdown"`。對於無法辨識的副檔名會回傳 `"unknown"`。

755 759

756<h4 id="active-time-counter">760<h4 id="active-time-counter">

757 活躍時間計數器761 活躍時間計數器

758</h4>762</h4>

759 763

760追蹤實際花費在主動使用 Claude Code 上的時間，不包括閒置時間。此指標在使用者互動期間（例如輸入和閱讀回應）以及 CLI 處理期間（例如工具執行和 AI 回應產生）遞增。764追蹤實際主動使用 Claude Code 所花費的時間，不包括閒置時間。此指標會在使用者互動期間（例如輸入與閱讀回應）以及 CLI 處理期間（例如工具執行與 AI 回應產生）遞增。

761 765

762**屬性**：766**屬性**：

763 767

764* 所有[標準屬性](#standard-attributes)768* 所有[標準屬性](#standard-attributes)

765* `type`：`"user"` 用於鍵盤互動，`"cli"` 用於工具執行和 AI 回應769* `type`：鍵盤互動為 `"user"`，工具執行與 AI 回應為 `"cli"`

766 770

767<h3 id="events">771<h3 id="events">

768 事件772 事件

769</h3>773</h3>

770 774

771Claude Code 通過 OpenTelemetry 日誌/事件匯出以下事件（當配置了 `OTEL_LOGS_EXPORTER` 時）：775Claude Code 會透過 OpenTelemetry logs/events 匯出以下事件（當設定了 `OTEL_LOGS_EXPORTER` 時）：

772 776

773<h4 id="event-correlation-attributes">777<h4 id="event-correlation-attributes">

774 事件相關屬性778 事件關聯屬性

775</h4>779</h4>

776 780

777當使用者提交提示時，Claude Code 可能會進行多個 API 呼叫並執行多個工具。`prompt.id` 屬性讓您將所有這些事件與觸發它們的單個提示聯繫起來。781當使用者提交提示詞時，Claude Code 可能會進行多次 API 呼叫並執行數個工具。`prompt.id` 屬性可讓您將所有這些事件連結回觸發它們的單一提示詞。

778 782

779| 屬性 | 描述 |783| 屬性 | 說明 |

780| - | - |784| - | - |

783| `message.uuid` | 消息的 UUID，如工作階段文字記錄中保存的那樣，`~/.claude/projects/*/*.jsonl` 檔案。存在於 `assistant_response`、`api_response_body` 和 `user_prompt` 上，除了命令分派，它可以產生零個或多個消息。在 `assistant_response` 和 `api_response_body` 上，這是回應的最終文字記錄項目，下一個回合的 `parentUuid` 從其鏈接。需要 Claude Code v2.1.214 或更新版本，或在 `api_response_body` 上需要 v2.1.274 或更新版本 |787| `message.uuid` | 保存在工作階段逐字稿（`~/.claude/projects/*/*.jsonl` 檔案）中的訊息 UUID。出現在 `assistant_response`、`api_response_body` 上，以及 `user_prompt` 上（命令分派除外，因為命令分派可能產生零或多則訊息）。在 `assistant_response` 與 `api_response_body` 上，這是回應的最後一筆逐字稿項目，下一個回合的 `parentUuid` 會從此項目串接。需要 Claude Code v2.1.214 或更新版本，在 `api_response_body` 上則需要 v2.1.274 或更新版本 |

784| `request_id` | 伺服器指派的 API 請求 ID，從 `request-id` 回應標頭讀取，例如 `req_011...`。在沒有 `request-id` 標頭的回應上，如在 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 上，該值來自 `x-amzn-requestid` 標頭。存在於 `api_request`、`api_error`、`api_refusal`、`assistant_response` 和 `api_response_body` 上，當回應攜帶任一標頭時。與 `llm_request` 追蹤跨度上的相同屬性相符。`x-amzn-requestid` 來源需要 Claude Code v2.1.282 或更新版本 |788| `request_id` | 伺服器指派的 API 請求 ID，從 `request-id` 回應標頭讀取，例如 `req_011...`。在沒有 `request-id` 標頭的回應上（如 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock)），此值改為來自 `x-amzn-requestid` 標頭。當回應帶有任一標頭時，出現在 `api_request`、`api_error`、`api_refusal`、`assistant_response` 與 `api_response_body` 上。與 `llm_request` 追蹤 span 上的同名屬性相符。`x-amzn-requestid` 來源需要 Claude Code v2.1.282 或更新版本 |

785| `client_request_id` | 作為 `x-client-request-id` 請求標頭發送的用戶端產生的 UUID。存在於第一方 API 連線上的 `api_request` 和 `api_error` 上；在第三方提供者後端上不存在，以及當請求通過非串流回退重試時。將請求與其回應配對，並對於永遠不會產生伺服器 `request_id` 的失敗（例如逾時）保持可用。與 `llm_request` 追蹤跨度上的相同屬性相符。需要 Claude Code v2.1.214 或更新版本 |789| `client_request_id` | 用戶端產生的 UUID，作為 `x-client-request-id` 請求標頭傳送。在第一方 API 連線上出現於 `api_request` 與 `api_error`；在第三方提供者後端上，以及請求透過非串流備援重試時則不存在。可將請求與其回應配對，且對於從未產生伺服器 `request_id` 的失敗（例如逾時）仍然可用。與 `llm_request` 追蹤 span 上的同名屬性相符。需要 Claude Code v2.1.214 或更新版本 |

786 790

787要追蹤由單個提示觸發的所有活動，請按特定 `prompt.id` 值篩選您的事件。這會傳回 user\_prompt 事件、任何 api\_request 事件以及處理該提示時發生的任何 tool\_result 事件。791若要追蹤由單一提示詞觸發的所有活動，請以特定的 `prompt.id` 值篩選您的事件。這會傳回處理該提示詞期間發生的 user\_prompt 事件、任何 api\_request 事件以及任何 tool\_result 事件。

788 792

789`event.sequence` 在每次 Claude Code 程序啟動時從 0 開始，並在該程序的生命週期內計數。它在 `/clear` 中繼續計數，這會指派新的 `session.id`。如果您[在不分叉的情況下恢復工作階段](/docs/zh-TW/how-claude-code-works#resume-or-fork-sessions)，工作階段會保留其 `session.id` 但從恢復它的程序中取得其 `event.sequence` 值，因此在一個工作階段內，較晚的事件可以攜帶比較早的事件更低的值，或重複一個。要排序工作階段的事件，請按 `event.timestamp` 排序，並使用 `event.sequence` 排序共享時間戳記的事件。793`event.sequence` 在每次 Claude Code 程序啟動時從 0 開始，並在該程序的整個生命週期中遞增。它在 `/clear`（會指派新的 `session.id`）之後仍會持續計數。若您[在不分叉的情況下繼續工作階段](/docs/zh-TW/how-claude-code-works#resume-or-fork-sessions)，工作階段會保留其 `session.id`，但其 `event.sequence` 值會取自繼續該工作階段的程序，因此在同一工作階段中，較晚的事件可能帶有比較早事件更低的值，或重複某個值。若要排序工作階段的事件，請依 `event.timestamp` 排序，並使用 `event.sequence` 排序具有相同時間戳記的事件。

790 794

791對於消息級別的重建，每個事件類別都攜帶與工作階段文字記錄中的欄位相符的鍵。文字記錄項目格式是[Claude Code 內部的](/docs/zh-TW/sessions#where-transcripts-are-stored)，在版本之間變化，因此在這些欄位上聯接的管道可能在任何版本上中斷；將聯接視為版本特定的而不是穩定的合約：795為了進行訊息層級的重建，每個事件類別都帶有一個與工作階段逐字稿中欄位相符的鍵。逐字稿項目格式是 [Claude Code 內部使用的](/docs/zh-TW/sessions#where-transcripts-are-stored)，且會在版本之間變更，因此依這些欄位進行聯結的管線可能會在任何版本發行時中斷；請將這些聯結視為特定版本的行為，而非穩定的約定：

792 796

793* `message.uuid` 在 `user_prompt`、`assistant_response` 和 `api_response_body` 上797* `user_prompt`、`assistant_response` 與 `api_response_body` 上的 `message.uuid`

794* `request_id` 在 API 事件上，在文字記錄的助手項目上保存為 `requestId`798* API 事件上的 `request_id`，在逐字稿的助理項目中保存為 `requestId`

795* `tool_use_id` 在 `tool_result` 和 `tool_decision` 事件上799* `tool_result` 與 `tool_decision` 事件上的 `tool_use_id`

796 800

797<h4 id="user-prompt-event">801<h4 id="user-prompt-event">

798 使用者提示事件802 使用者提示詞事件

799</h4>803</h4>

800 804

801於提示詞送出時記錄，包括 Claude Code 自行開始的回合。805在提交提示詞時記錄，包括 Claude Code 自行開始的回合。

802 806

803**事件名稱**：`claude_code.user_prompt`807**事件名稱**：`claude_code.user_prompt`

804 808

807* 所有[標準屬性](#standard-attributes)811* 所有[標準屬性](#standard-attributes)

808* `event.name`：`"user_prompt"`812* `event.name`：`"user_prompt"`

809* `event.timestamp`：ISO 8601 時間戳記813* `event.timestamp`：ISO 8601 時間戳記

810* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述814* `event.sequence`：用於排序事件的每程序計數器，說明請參閱[事件關聯屬性](#event-correlation-attributes)

811* `prompt_length`：提示的長度815* `prompt_length`：提示詞長度

812* `prompt`：提示內容。預設情況下編輯。設定 `OTEL_LOG_USER_PROMPTS=1` 以包含它816* `prompt`：提示詞內容。預設會遮蔽。設定 `OTEL_LOG_USER_PROMPTS=1` 即可包含

813* `prompt_text`：與 `prompt` 相同的值，在相同條件下遮蔽。將帶點屬性名稱儲存為巢狀物件的後端，會將 `prompt.id` 讀取為名為 `prompt` 之物件內的 `id`，因而可能遺失提示詞字串。在這類後端上請改讀取 `prompt_text`。需要 Claude Code v2.1.287 或更新版本817* `prompt_text`：與 `prompt` 相同的值，並在相同條件下遮蔽。將帶點的屬性名稱儲存為巢狀物件的後端，會將 `prompt.id` 讀取為名為 `prompt` 之物件內的 `id`，因而可能遺失提示詞字串。在這種情況下，請改為讀取 `prompt_text`。需要 Claude Code v2.1.287 或更新版本

814* `message.uuid`：結果使用者消息的 UUID，與保存的文字記錄項目相符。在命令分派上不存在，它可以產生零個或多個消息。需要 Claude Code v2.1.214 或更新版本818* `message.uuid`：產生之使用者訊息的 UUID，與保存的逐字稿項目相符。在命令分派上不存在，因為命令分派可能產生零或多則訊息。需要 Claude Code v2.1.214 或更新版本

815* `command_name`：當提示呼叫命令時的命令名稱。內建和捆綁命令名稱（例如 `compact` 或 `debug`）按原樣發出；別名（例如 `reset`）按輸入方式發出而不是規範名稱。自訂、外掛程式和 MCP 命令名稱會摺疊為 `custom` 或 `mcp`，除非設定了 `OTEL_LOG_TOOL_DETAILS=1`819* `command_name`：當提示詞呼叫命令時的命令名稱。內建與隨附的命令名稱（例如 `compact` 或 `debug`）會原樣發出；別名（例如 `reset`）會依輸入的形式發出，而非標準名稱。自訂、外掛與 MCP 命令名稱會收斂為 `custom` 或 `mcp`，除非設定了 `OTEL_LOG_TOOL_DETAILS=1`

816* `command_source`：命令存在時的來源：`builtin`、`custom` 或 `mcp`。外掛程式提供的命令報告為 `custom`820* `command_source`：存在時為命令的來源：`builtin`、`custom` 或 `mcp`。外掛提供的命令會回報為 `custom`

817 821

818<h4 id="assistant-response-event">822<h4 id="assistant-response-event">

819 助手回應事件823 助理回應事件

820</h4>824</h4>

821 825

822在每次從模型傳回文字內容的 API 請求之後記錄。只包含回應中的文字區塊；思考區塊與工具使用區塊不包含在內。826在每次從模型傳回文字內容的 API 請求之後記錄。僅包含回應的文字區塊；思考區塊與工具使用區塊會被排除。

823 827

824**事件名稱**：`claude_code.assistant_response`828**事件名稱**：`claude_code.assistant_response`

825 829

828* 所有[標準屬性](#standard-attributes)832* 所有[標準屬性](#standard-attributes)

829* `event.name`：`"assistant_response"`833* `event.name`：`"assistant_response"`

830* `event.timestamp`：ISO 8601 時間戳記834* `event.timestamp`：ISO 8601 時間戳記

831* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述835* `event.sequence`：用於排序事件的每程序計數器，說明請參閱[事件關聯屬性](#event-correlation-attributes)

832* `response_length`：回應文字的長度（以字元為單位）836* `response_length`：回應文字的長度（字元數）

833* `response`：回應文字，在內容限制處截斷（預設為 60 KB）。預設情況下編輯為 `<REDACTED>`。設定 `OTEL_LOG_ASSISTANT_RESPONSES=1` 以包含它。當 `OTEL_LOG_ASSISTANT_RESPONSES` 未設定時，`OTEL_LOG_USER_PROMPTS` 會控制它，因此設定 `OTEL_LOG_ASSISTANT_RESPONSES=0` 以在啟用提示記錄時保持回應編輯837* `response`：回應文字，在內容上限（預設 60 KB）處截斷。預設會遮蔽為 `<REDACTED>`。設定 `OTEL_LOG_ASSISTANT_RESPONSES=1` 即可包含。當 `OTEL_LOG_ASSISTANT_RESPONSES` 未設定時，改由 `OTEL_LOG_USER_PROMPTS` 控制，因此若要在開啟提示詞日誌記錄的同時保持回應遮蔽，請設定 `OTEL_LOG_ASSISTANT_RESPONSES=0`

834* `model`：模型識別碼（例如，"claude-sonnet-5"）838* `model`：模型識別碼（例如 "claude-sonnet-5"）

835* `request_id`：API 請求 ID，在[事件相關屬性](#event-correlation-attributes)下描述839* `request_id`：API 請求 ID，說明請參閱[事件關聯屬性](#event-correlation-attributes)

836* `message.uuid`：回應最終文字記錄項目的 UUID。API 回應每個內容區塊保存為一個文字記錄項目；這是最後一個，下一個回合的 `parentUuid` 從其鏈接。需要 Claude Code v2.1.214 或更新版本840* `message.uuid`：回應之最後一筆逐字稿項目的 UUID。API 回應會依每個內容區塊保存為一筆逐字稿項目；此為最後一筆，下一個回合的 `parentUuid` 會從此項目串接。需要 Claude Code v2.1.214 或更新版本

837* `query_source`：發出請求的子系統，例如 `"repl_main_thread"`、`"compact"` 或子代理程式名稱841* `query_source`：發出請求的子系統，例如 `"repl_main_thread"`、`"compact"` 或 subagent 名稱

838 842

839<h4 id="tool-result-event">843<h4 id="tool-result-event">

840 工具結果事件844 工具結果事件

841</h4>845</h4>

842 846

843當工具完成執行時記錄。如果工具呼叫被拒絕，則不發出；請參閱[工具決定事件](#tool-decision-event)以了解拒絕。847在工具完成執行時記錄。若工具呼叫遭拒絕則不會發出；關於拒絕，請參閱[工具決定事件](#tool-decision-event)。

844 848

845**事件名稱**：`claude_code.tool_result`849**事件名稱**：`claude_code.tool_result`

846 850

849* 所有[標準屬性](#standard-attributes)853* 所有[標準屬性](#standard-attributes)

850* `event.name`：`"tool_result"`854* `event.name`：`"tool_result"`

851* `event.timestamp`：ISO 8601 時間戳記855* `event.timestamp`：ISO 8601 時間戳記

852* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述856* `event.sequence`：用於排序事件的每程序計數器，說明請參閱[事件關聯屬性](#event-correlation-attributes)

853* `tool_name`：工具的名稱857* `tool_name`：工具名稱

854* `tool_use_id`：此工具呼叫的唯一識別碼。與傳遞給鉤子的 `tool_use_id` 相符，允許 OTel 事件和鉤子捕獲資料之間的相關性。858* `tool_use_id`：此次工具呼叫的唯一識別碼。與傳遞給 hook 的 `tool_use_id` 相符，可讓 OTel 事件與 hook 擷取的資料相互關聯。

855* `success`：`"true"` 或 `"false"`859* `success`：`"true"` 或 `"false"`

856* `duration_ms`：執行時間（以毫秒為單位）860* `duration_ms`：執行時間（毫秒）

857* `error_type`：工具失敗時的錯誤類別字串，例如 `"Error:ENOENT"` 或 `"ShellError"`861* `error_type`：工具失敗時的錯誤類別字串，例如 `"Error:ENOENT"` 或 `"ShellError"`

858* `error`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：工具失敗時的完整錯誤消息862* `error`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：工具失敗時的完整錯誤訊息

859* `decision_type`：始終 `"accept"`，因為此事件僅在工具執行後發出。拒絕的呼叫不會產生工具結果863* `decision_type`：一律為 `"accept"`，因為此事件只會在工具執行後發出。遭拒絕的呼叫不會產生工具結果

860* `decision_source`：權限決定來自何處。`"config"`、`"hook"`、`"user_permanent"` 或 `"user_temporary"` 之一。請參閱[工具決定事件](#tool-decision-event)以了解每個值的含義。僅拒絕的來源 `"user_abort"` 和 `"user_reject"` 永遠不會出現在此事件上。864* `decision_source`：權限決定的來源。為 `"config"`、`"hook"`、`"user_permanent"` 或 `"user_temporary"` 之一。各值的意義請參閱[工具決定事件](#tool-decision-event)。僅適用於拒絕的來源 `"user_abort"` 與 `"user_reject"` 永遠不會出現在此事件上。

861* `tool_input_size_bytes`：JSON 序列化工具輸入的大小（以位元組為單位）865* `tool_input_size_bytes`：JSON 序列化後之工具輸入的大小（位元組）

862* `tool_result_size_bytes`：工具結果的大小（以位元組為單位）866* `tool_result_size_bytes`：工具結果的大小（位元組）

863* `mcp_server_scope`：MCP 伺服器範圍識別碼（用於 MCP 工具）867* `mcp_server_scope`：MCP 伺服器範圍識別碼（適用於 MCP 工具）

864* `vcs.ref.head.revision`、`vcs.ref.head.name`、`vcs.ref.head.type`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：由 Bash 或 PowerShell 工具執行的成功 `git commit` 執行的提交身份。`vcs.ref.head.revision` 是提交 SHA，`vcs.ref.head.name` 是提交所在的分支，`vcs.ref.head.type` 是 `branch`。當提交在分離的 HEAD 上進行時，名稱和類型會被省略。需要 Claude Code v2.1.269 或更新版本868* `vcs.ref.head.revision`、`vcs.ref.head.name`、`vcs.ref.head.type`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：由 Bash 或 PowerShell 工具執行之成功 `git commit` 的提交身分。`vcs.ref.head.revision` 為提交 SHA，`vcs.ref.head.name` 為提交所在的分支，而 `vcs.ref.head.type` 為 `branch`。當提交是在 detached HEAD 上進行時，名稱與類型會被省略。需要 Claude Code v2.1.269 或更新版本

865* `tool_parameters`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：包含工具特定參數的 JSON 字串。對於 Claude Desktop 的內建伺服器，在 Claude Desktop 擁有的工作階段中，即使關閉標誌，`mcp_server_name`/`mcp_tool_name` 對也會包含，與[工具決定事件](#tool-decision-event)相同的主機撰寫例外，需要 Claude Code v2.1.214 或更新版本。參數因工具而異：869* `tool_parameters`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：包含工具特定參數的 JSON 字串。對於 Claude Desktop 的內建伺服器，在 Claude Desktop 擁有的工作階段中，即使旗標關閉也會包含 `mcp_server_name`/`mcp_tool_name` 配對，這與[工具決定事件](#tool-decision-event)中由主機定義的例外相同，需要 Claude Code v2.1.214 或更新版本。參數依工具而異：

866 * 對於 Bash 工具：包括 `bash_command`、`full_command`、`timeout`、`description` 和 `dangerouslyDisableSandbox`，以及當 `git commit` 命令成功時的 `git_commit_id` 和 `git_branch`。當提交是工作階段工作目錄的 HEAD 時，`git_commit_id` 是完整提交 SHA，否則是 git 的縮寫 SHA。`git_branch` 是提交所在的分支，在分離的 HEAD 上省略870 * 對於 Bash 工具：包含 `bash_command`、`full_command`、`timeout`、`description` 與 `dangerouslyDisableSandbox`，以及當 `git commit` 命令成功時的 `git_commit_id` 與 `git_branch`。當提交是工作階段工作目錄的 HEAD 時，`git_commit_id` 為完整的提交 SHA，否則為 git 的縮寫 SHA。`git_branch` 為提交所在的分支，在 detached HEAD 上會被省略

867 * 對於桌面應用程式的工作區 Bash 工具，它也將 `tool_name` 報告為 `Bash`：只包括 `bash_command`、`full_command` 和 `timeout`871 * 對於桌面應用程式的工作區 Bash 工具（其 `tool_name` 也回報為 `Bash`）：僅包含 `bash_command`、`full_command` 與 `timeout`

868 * 對於 MCP 工具：包括 `mcp_server_name`、`mcp_tool_name`872 * 對於 MCP 工具：包含 `mcp_server_name`、`mcp_tool_name`

869 * 對於技能工具：包括 `skill_name`873 * 對於 Skill 工具：包含 `skill_name`

870 * 對於代理程式工具或舊版任務工具：包括 `subagent_type`874 * 對於 Agent 工具或舊版 Task 工具：包含 `subagent_type`

871* `tool_input`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：JSON 序列化工具引數。超過 512 個字元的個別值會被截斷，完整有效負載限制為約 4 K 字元。適用於所有工具，包括 MCP 工具。875* `tool_input`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：JSON 序列化後的工具引數。超過 512 個字元的個別值會被截斷，且完整 payload 的上限約為 4 K 個字元。適用於所有工具，包括 MCP 工具。

872 876

873<h4 id="api-request-event">877<h4 id="api-request-event">

874 API 請求事件878 API 請求事件

875</h4>879</h4>

876 880

877為每個 API 請求到 Claude 記錄。881針對每個傳送給 Claude 的 API 請求記錄。

878 882

879**事件名稱**：`claude_code.api_request`883**事件名稱**：`claude_code.api_request`

880 884

883* 所有[標準屬性](#standard-attributes)887* 所有[標準屬性](#standard-attributes)

884* `event.name`：`"api_request"`888* `event.name`：`"api_request"`

885* `event.timestamp`：ISO 8601 時間戳記889* `event.timestamp`：ISO 8601 時間戳記

886* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述890* `event.sequence`：用於排序事件的每程序計數器，說明請參閱[事件關聯屬性](#event-correlation-attributes)

887* `model`：使用的模型（例如，"claude-sonnet-5"）891* `model`：使用的模型（例如 "claude-sonnet-5"）

888* `cost_usd`：以美元計的估計成本892* `cost_usd`：預估成本（USD）

889* `cost_usd_micros`：以美元百萬分之一計的估計成本，作為整數發出893* `cost_usd_micros`：以百萬分之一美元為單位的預估成本，以整數發出

890* `duration_ms`：請求持續時間（以毫秒為單位）894* `duration_ms`：請求持續時間（毫秒）

891* `input_tokens`：輸入 token 數量，不包含從提示詞快取讀取或寫入的 token895* `input_tokens`：輸入 token 數量，不包括從提示詞快取讀取或寫入的 token

892* `output_tokens`：輸出權杖數896* `output_tokens`：輸出 token 數量

893* `cache_read_tokens`：從快取讀取的權杖數897* `cache_read_tokens`：從快取讀取的 token 數量

894* `cache_creation_tokens`：用於快取建立的權杖數898* `cache_creation_tokens`：用於建立快取的 token 數量

895* `request_id`：API 請求 ID，例如 `"req_011..."`，在[事件相關屬性](#event-correlation-attributes)下描述。899* `request_id`：API 請求 ID，例如 `"req_011..."`，說明請參閱[事件關聯屬性](#event-correlation-attributes)。

896* `client_request_id`：作為 `x-client-request-id` 請求標頭發送的用戶端產生的 UUID；請參閱[事件相關屬性](#event-correlation-attributes)表以了解何時存在。需要 Claude Code v2.1.214 或更新版本900* `client_request_id`：用戶端產生的 UUID，作為 `x-client-request-id` 請求標頭傳送；其出現時機請參閱[事件關聯屬性](#event-correlation-attributes)表格。需要 Claude Code v2.1.214 或更新版本

897* `speed`：`"fast"` 或 `"normal"`，指示快速模式是否有效901* `speed`：`"fast"` 或 `"normal"`，表示快速模式是否啟用

898* `query_source`：發出請求的子系統，例如 `"repl_main_thread"`、`"compact"` 或子代理程式名稱902* `query_source`：發出請求的子系統，例如 `"repl_main_thread"`、`"compact"` 或 subagent 名稱

899* `effort`：應用於請求的[努力級別](/docs/zh-TW/model-config#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。當 Claude Code 不發送努力級別時不存在，例如在不支援努力的模型上。903* `effort`：套用於請求的 [effort 等級](/docs/zh-TW/model-config#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。當 Claude Code 未傳送 effort 等級時不存在，例如在不支援 effort 的模型上。

900* `agent.name`、`skill.name`、`plugin.name`、`marketplace.name`、`mcp_server.name`、`mcp_tool.name`：請求的技能、外掛程式、代理程式和 MCP 歸因。請參閱[成本計數器](#cost-counter)以了解定義和編輯行為。904* `agent.name`、`skill.name`、`plugin.name`、`marketplace.name`、`mcp_server.name`、`mcp_tool.name`：請求的 skill、外掛、agent 與 MCP 歸屬。定義與遮蔽行為請參閱[成本計數器](#cost-counter)。

901 905

902<h4 id="api-error-event">906<h4 id="api-error-event">

903 API 錯誤事件907 API 錯誤事件

904</h4>908</h4>

905 909

906當 API 請求到 Claude 失敗時記錄。910當傳送給 Claude 的 API 請求失敗時記錄。

907 911

908**事件名稱**：`claude_code.api_error`912**事件名稱**：`claude_code.api_error`

909 913

912* 所有[標準屬性](#standard-attributes)916* 所有[標準屬性](#standard-attributes)

913* `event.name`：`"api_error"`917* `event.name`：`"api_error"`

914* `event.timestamp`：ISO 8601 時間戳記918* `event.timestamp`：ISO 8601 時間戳記

915* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述919* `event.sequence`：用於排序事件的每程序計數器，說明請參閱[事件關聯屬性](#event-correlation-attributes)

916* `model`：使用的模型（例如，"claude-sonnet-5"）920* `model`：使用的模型（例如 "claude-sonnet-5"）

917* `error`：錯誤消息921* `error`：錯誤訊息

918* `status_code`：HTTP 狀態碼作為數字。對於非 HTTP 錯誤（例如連線失敗）不存在。922* `status_code`：以數字表示的 HTTP 狀態碼。對於非 HTTP 錯誤（例如連線失敗）不存在。

919* `duration_ms`：請求持續時間（以毫秒為單位）923* `duration_ms`：請求持續時間（毫秒）

920* `attempt`：進行的嘗試總數，包括初始請求（`1` 表示未發生重試）924* `attempt`：已進行的嘗試次數，包括初始請求。[偵測重試耗盡](#detect-retry-exhaustion)說明計數何時會重新開始

921* `request_id`：API 請求 ID，例如 `"req_011..."`，在[事件相關屬性](#event-correlation-attributes)下描述。925* `request_id`：API 請求 ID，例如 `"req_011..."`，說明請參閱[事件關聯屬性](#event-correlation-attributes)。

922* `client_request_id`：作為 `x-client-request-id` 請求標頭發送的用戶端產生的 UUID。即使在失敗（例如逾時或連線錯誤）永遠不會產生伺服器 `request_id` 時也可用；請參閱[事件相關屬性](#event-correlation-attributes)表以了解何時存在。需要 Claude Code v2.1.214 或更新版本926* `client_request_id`：用戶端產生的 UUID，作為 `x-client-request-id` 請求標頭傳送。即使逾時或連線錯誤等失敗從未產生伺服器 `request_id`，此值仍然可用；其出現時機請參閱[事件關聯屬性](#event-correlation-attributes)表格。需要 Claude Code v2.1.214 或更新版本

923* `speed`：`"fast"` 或 `"normal"`，指示快速模式是否有效927* `speed`：`"fast"` 或 `"normal"`，表示快速模式是否啟用

924* `query_source`：發出請求的子系統，例如 `"repl_main_thread"`、`"compact"` 或子代理程式名稱928* `query_source`：發出請求的子系統，例如 `"repl_main_thread"`、`"compact"` 或 subagent 名稱

925* `effort`：應用於請求的[努力級別](/docs/zh-TW/model-config#adjust-effort-level)。當 Claude Code 不發送努力級別時不存在，例如在不支援努力的模型上。929* `effort`：套用於請求的 [effort 等級](/docs/zh-TW/model-config#adjust-effort-level)。當 Claude Code 未傳送 effort 等級時不存在，例如在不支援 effort 的模型上。

926* `agent.name`、`skill.name`、`plugin.name`、`marketplace.name`、`mcp_server.name`、`mcp_tool.name`：請求的技能、外掛程式、代理程式和 MCP 歸因。請參閱[成本計數器](#cost-counter)以了解定義和編輯行為。930* `agent.name`、`skill.name`、`plugin.name`、`marketplace.name`、`mcp_server.name`、`mcp_tool.name`：請求的 skill、外掛、agent 與 MCP 歸屬。定義與遮蔽行為請參閱[成本計數器](#cost-counter)。

927 931

928<h4 id="api-refusal-event">932<h4 id="api-refusal-event">

929 API 拒絕事件933 API 拒絕事件

930</h4>934</h4>

931 935

932當 API 請求傳回 `stop_reason: "refusal"` 時記錄。拒絕到達成功回應串流上，而不是作為 HTTP 錯誤，因此 `api_error` 事件不會為它們觸發。此事件讓您追蹤拒絕頻率並按與 `api_request` 和 `api_error` 相同的屬性分組拒絕。936當 API 請求傳回 `stop_reason: "refusal"` 時記錄。拒絕會出現在成功的回應串流中，而非以 HTTP 錯誤的形式出現，因此 `api_error` 事件不會因拒絕而觸發。此事件可讓您追蹤拒絕頻率，並依與 `api_request` 及 `api_error` 相同的屬性將拒絕分組。

933 937

934**事件名稱**：`claude_code.api_refusal`938**事件名稱**：`claude_code.api_refusal`

935 939

938* 所有[標準屬性](#standard-attributes)942* 所有[標準屬性](#standard-attributes)

939* `event.name`：`"api_refusal"`943* `event.name`：`"api_refusal"`

940* `event.timestamp`：ISO 8601 時間戳記944* `event.timestamp`：ISO 8601 時間戳記

941* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述945* `event.sequence`：用於排序事件的每程序計數器，說明請參閱[事件關聯屬性](#event-correlation-attributes)

942* `model`：來自請求的模型識別碼946* `model`：請求中的模型識別碼

943* `request_id`：API 請求 ID，例如 `"req_011..."`，在[事件相關屬性](#event-correlation-attributes)下描述。947* `request_id`：API 請求 ID，例如 `"req_011..."`，說明請參閱[事件關聯屬性](#event-correlation-attributes)。

944* `query_source`：發出請求的子系統，例如 `"repl_main_thread"`、`"compact"` 或子代理程式名稱。請參閱 [`api_request`](#api-request-event) 以了解定義。948* `query_source`：發出請求的子系統，例如 `"repl_main_thread"`、`"compact"` 或 subagent 名稱。定義請參閱 [`api_request`](#api-request-event)。

945* `speed`：當[快速模式](/docs/zh-TW/fast-mode)有效時為 `"fast"`，或 `"normal"`949* `speed`：當[快速模式](/docs/zh-TW/fast-mode)啟用時為 `"fast"`，否則為 `"normal"`

946* `attempt`：重試嘗試編號。第一次嘗試是 `1`。950* `attempt`：重試嘗試的編號。第一次嘗試為 `1`。

947* `effort`：應用於請求的[努力級別](/docs/zh-TW/model-config#adjust-effort-level)。當 Claude Code 不發送努力級別時不存在，例如在不支援努力的模型上。951* `effort`：套用於請求的 [effort 等級](/docs/zh-TW/model-config#adjust-effort-level)。當 Claude Code 未傳送 effort 等級時不存在，例如在不支援 effort 的模型上。

948* `server_fallback_hop`：當 API 的伺服器端模型回退已在不同模型上重試此拒絕時為 `true`，因此使用者沒有看到此特定拒絕。當請求以拒絕結束時為 `false`。單個回合可以發出 `true` 跳躍事件和稍後的 `false` 最終事件，當回退模型也拒絕時。952* `server_fallback_hop`：當 API 的伺服器端模型備援已在不同的模型上重試此拒絕，因此使用者並未看到此特定拒絕時為 `true`。當請求以拒絕結束時為 `false`。當備援模型也拒絕時，單一回合可能會同時發出一個 `true` 的跳轉事件以及之後一個 `false` 的最終事件。

949* `has_category`：當 API 回應攜帶 `stop_details.category` 為 `"cyber"`、`"bio"`、`"frontier_llm"` 或 `"reasoning_extraction"` 時為 `true`。當回應未攜帶類別或值在該集合外時為 `false`。當 `server_fallback_hop` 為 `true` 時不存在，因為跳躍不攜帶 `stop_details`。953* `has_category`：當 API 回應帶有值為 `"cyber"`、`"bio"`、`"frontier_llm"` 或 `"reasoning_extraction"` 的 `stop_details.category` 時為 `true`。當回應未帶有類別或帶有該集合以外的值時為 `false`。當 `server_fallback_hop` 為 `true` 時不存在，因為跳轉區塊不帶有 `stop_details`。

950* `has_explanation`：當 API 回應攜帶 `stop_details.explanation` 時為 `true`，否則為 `false`。當 `server_fallback_hop` 為 `true` 時不存在。954* `has_explanation`：當 API 回應帶有 `stop_details.explanation` 時為 `true`，否則為 `false`。當 `server_fallback_hop` 為 `true` 時不存在。

951* `category`：來自 API 回應的 `stop_details.category` 值。`"cyber"`、`"bio"`、`"frontier_llm"` 或 `"reasoning_extraction"` 之一。僅當設定了 `OTEL_LOG_TOOL_DETAILS=1` 且 `has_category` 為 `true` 時存在。955* `category`：API 回應中的 `stop_details.category` 值。為 `"cyber"`、`"bio"`、`"frontier_llm"` 或 `"reasoning_extraction"` 之一。僅在設定了 `OTEL_LOG_TOOL_DETAILS=1` 且 `has_category` 為 `true` 時存在。

952* `agent.name`、`skill.name`、`plugin.name`、`marketplace.name`、`mcp_server.name`、`mcp_tool.name`：請求的技能、外掛程式、代理程式和 MCP 歸因。請參閱[成本計數器](#cost-counter)以了解定義和編輯行為。956* `agent.name`、`skill.name`、`plugin.name`、`marketplace.name`、`mcp_server.name`、`mcp_tool.name`：請求的 skill、外掛、agent 與 MCP 歸屬。定義與遮蔽行為請參閱[成本計數器](#cost-counter)。

953 957

954<h4 id="api-request-body-event">958<h4 id="api-request-body-event">

955 API 請求本體事件959 API 請求主體事件

956</h4>960</h4>

957 961

958當設定了 `OTEL_LOG_RAW_API_BODIES` 時，為每個 API 請求嘗試記錄。每個嘗試發出一個事件，因此使用調整參數重試時每個都會產生自己的事件。962當設定了 `OTEL_LOG_RAW_API_BODIES` 時，針對每次 API 請求嘗試記錄。每次嘗試發出一個事件，因此以調整後參數進行的重試各自會產生自己的事件。

959 963

960**事件名稱**：`claude_code.api_request_body`964**事件名稱**：`claude_code.api_request_body`

961 965

964* 所有[標準屬性](#standard-attributes)968* 所有[標準屬性](#standard-attributes)

965* `event.name`：`"api_request_body"`969* `event.name`：`"api_request_body"`

966* `event.timestamp`：ISO 8601 時間戳記970* `event.timestamp`：ISO 8601 時間戳記

967* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述971* `event.sequence`：用於排序事件的每程序計數器，說明請參閱[事件關聯屬性](#event-correlation-attributes)

968* `body`：JSON 序列化的 Messages API 請求參數，例如系統提示、消息和工具，在內容限制處截斷（預設為 60 KB）。先前助手回合中的擴展思考內容被編輯。僅在內聯模式下發出（`OTEL_LOG_RAW_API_BODIES=1`）。972* `body`：JSON 序列化後的 Messages API 請求參數，例如系統提示詞、訊息與工具，在內容上限（預設 60 KB）處截斷。先前助理回合中的延伸思考內容會被遮蔽。僅在內嵌模式（`OTEL_LOG_RAW_API_BODIES=1`）下發出。

969* `body_ref`：包含未截斷本體的 `<dir>/<uuid>.request.json` 檔案的絕對路徑。僅在檔案模式下發出（`OTEL_LOG_RAW_API_BODIES=file:<dir>`）。973* `body_ref`：指向包含未截斷主體之 `<dir>/<uuid>.request.json` 檔案的絕對路徑。僅在檔案模式（`OTEL_LOG_RAW_API_BODIES=file:<dir>`）下發出。

970* `body_length`：未截斷本體長度。當 `OTEL_LOG_RAW_API_BODIES=file:<dir>` 時為 UTF-8 位元組，或當 `=1` 時為 UTF-16 程式碼單位974* `body_length`：未截斷的主體長度。當 `OTEL_LOG_RAW_API_BODIES=file:<dir>` 時為 UTF-8 位元組，當 `=1` 時為 UTF-16 程式碼單元

971* `body_truncated`：當發生內聯截斷時為 `"true"`。在檔案模式下不存在，以及當未發生截斷時不存在。975* `body_truncated`：發生內嵌截斷時為 `"true"`。在檔案模式下以及未發生截斷時不存在。

972* `model`：來自請求參數的模型識別碼976* `model`：請求參數中的模型識別碼

973* `query_source`：發出請求的子系統（例如，`"compact"`）977* `query_source`：發出請求的子系統（例如 `"compact"`）

974* `request_body_id`：識別此嘗試請求本體的 UUID。成功的嘗試的 [`api_response_body` 事件](#api-response-body-event)攜帶相同的值，因此您可以將回應與產生它的確切請求配對。需要 Claude Code v2.1.274 或更新版本978* `request_body_id`：識別此嘗試之請求主體的 UUID。成功之嘗試的 [`api_response_body` 事件](#api-response-body-event)帶有相同的值，因此您可以將回應與產生它的確切請求配對。需要 Claude Code v2.1.274 或更新版本

975 979

976<h4 id="api-response-body-event">980<h4 id="api-response-body-event">

977 API 回應本體事件981 API 回應主體事件

978</h4>982</h4>

979 983

980當設定了 `OTEL_LOG_RAW_API_BODIES` 時，為每個成功的 API 回應記錄。984當設定了 `OTEL_LOG_RAW_API_BODIES` 時，針對每個成功的 API 回應記錄。

981 985

982在檔案模式下（`OTEL_LOG_RAW_API_BODIES=file:<dir>`），Claude Code 還會為每個成功的回應將一行 JSON 附加到 `<dir>/index.jsonl`，包含欄位 `timestamp`、`session_id`、`query_source`、`model`、`request_id`、`message_id`、`message_uuid`、`request_file` 和 `response_file`。讀取它以找到給定文字記錄消息後面的請求和回應檔案，而無需查詢您的遙測後端。索引檔案需要 Claude Code v2.1.274 或更新版本。986在檔案模式（`OTEL_LOG_RAW_API_BODIES=file:<dir>`）下，Claude Code 也會針對每個成功的回應，將一行 JSON 附加到 `<dir>/index.jsonl`，其欄位為 `timestamp`、`session_id`、`query_source`、`model`、`request_id`、`message_id`、`message_uuid`、`request_file` 與 `response_file`。讀取此檔案即可找出特定逐字稿訊息背後的請求與回應檔案，而無需查詢您的遙測後端。索引檔案需要 Claude Code v2.1.274 或更新版本。

983 987

984**事件名稱**：`claude_code.api_response_body`988**事件名稱**：`claude_code.api_response_body`

985 989

988* 所有[標準屬性](#standard-attributes)992* 所有[標準屬性](#standard-attributes)

989* `event.name`：`"api_response_body"`993* `event.name`：`"api_response_body"`

990* `event.timestamp`：ISO 8601 時間戳記994* `event.timestamp`：ISO 8601 時間戳記

991* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述995* `event.sequence`：用於排序事件的每程序計數器，說明請參閱[事件關聯屬性](#event-correlation-attributes)

992* `body`：JSON 序列化的 Messages API 回應，包括 id、內容區塊、使用情況和停止原因，在內容限制處截斷（預設為 60 KB）。擴展思考內容被編輯。僅在內聯模式下發出（`OTEL_LOG_RAW_API_BODIES=1`）。996* `body`：JSON 序列化後的 Messages API 回應，包括 id、內容區塊、使用量與停止原因，在內容上限（預設 60 KB）處截斷。延伸思考內容會被遮蔽。僅在內嵌模式（`OTEL_LOG_RAW_API_BODIES=1`）下發出。

993* `body_ref`：包含未截斷本體的 `<dir>/<request_id>.response.json` 檔案的絕對路徑。僅在檔案模式下發出（`OTEL_LOG_RAW_API_BODIES=file:<dir>`）。997* `body_ref`：指向包含未截斷主體之 `<dir>/<request_id>.response.json` 檔案的絕對路徑。僅在檔案模式（`OTEL_LOG_RAW_API_BODIES=file:<dir>`）下發出。

994* `body_length`：未截斷本體長度。當 `OTEL_LOG_RAW_API_BODIES=file:<dir>` 時為 UTF-8 位元組，或當 `=1` 時為 UTF-16 程式碼單位998* `body_length`：未截斷的主體長度。當 `OTEL_LOG_RAW_API_BODIES=file:<dir>` 時為 UTF-8 位元組，當 `=1` 時為 UTF-16 程式碼單元

995* `body_truncated`：當發生內聯截斷時為 `"true"`。在檔案模式下不存在，以及當未發生截斷時不存在。999* `body_truncated`：發生內嵌截斷時為 `"true"`。在檔案模式下以及未發生截斷時不存在。

996* `model`：模型識別碼1000* `model`：模型識別碼

997* `query_source`：發出請求的子系統1001* `query_source`：發出請求的子系統

998* `request_id`：API 請求 ID，例如 `"req_011..."`，在[事件相關屬性](#event-correlation-attributes)下描述。1002* `request_id`：API 請求 ID，例如 `"req_011..."`，說明請參閱[事件關聯屬性](#event-correlation-attributes)。

999* `request_body_id`：此回應回答的 [`api_request_body` 事件](#api-request-body-event)的 `request_body_id`。需要 Claude Code v2.1.274 或更新版本1003* `request_body_id`：此回應所回覆之 [`api_request_body` 事件](#api-request-body-event)的 `request_body_id`。需要 Claude Code v2.1.274 或更新版本

1000* `message.id`：API 指派給回應的消息 ID，回應本體的 `id` 欄位。需要 Claude Code v2.1.274 或更新版本1004* `message.id`：API 指派給回應的訊息 ID，即回應主體的 `id` 欄位。需要 Claude Code v2.1.274 或更新版本

1001* `message.uuid`：回應最終文字記錄項目的 UUID。與 `request_body_id` 一起，它將文字記錄消息連結到其後面的請求和回應本體。需要 Claude Code v2.1.274 或更新版本1005* `message.uuid`：回應之最後一筆逐字稿項目的 UUID。與 `request_body_id` 搭配，可將逐字稿訊息連結到其背後的請求與回應主體。需要 Claude Code v2.1.274 或更新版本

1002 1006

1003<h4 id="tool-decision-event">1007<h4 id="tool-decision-event">

1004 工具決定事件1008 工具決定事件

1005</h4>1009</h4>

1006 1010

1007當進行工具權限決定時記錄（接受/拒絕）。1011在做出工具權限決定（接受/拒絕）時記錄。

1008 1012

1009**事件名稱**：`claude_code.tool_decision`1013**事件名稱**：`claude_code.tool_decision`

1010 1014

1013* 所有[標準屬性](#standard-attributes)1017* 所有[標準屬性](#standard-attributes)

1014* `event.name`：`"tool_decision"`1018* `event.name`：`"tool_decision"`

1015* `event.timestamp`：ISO 8601 時間戳記1019* `event.timestamp`：ISO 8601 時間戳記

1016* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述1020* `event.sequence`：用於排序事件的每程序計數器，說明請參閱[事件關聯屬性](#event-correlation-attributes)

1017* `tool_name`：工具的名稱（例如，"Read"、"Edit"、"Write"、"NotebookEdit"）1021* `tool_name`：工具名稱（例如 "Read"、"Edit"、"Write"、"NotebookEdit"）

1018* `tool_use_id`：此工具呼叫的唯一識別碼。與傳遞給鉤子的 `tool_use_id` 相符，允許 OTel 事件和鉤子捕獲資料之間的相關性。1022* `tool_use_id`：此次工具呼叫的唯一識別碼。與傳遞給 hook 的 `tool_use_id` 相符，可讓 OTel 事件與 hook 擷取的資料相互關聯。

1019* `decision`：`"accept"` 或 `"reject"`1023* `decision`：`"accept"` 或 `"reject"`

1020* `tool_source`：始終存在。工具的來源，作為 CLI 撰寫值的封閉集合。需要 Claude Code v2.1.214 或更新版本1024* `tool_source`：一律存在。工具的來源，為 CLI 定義之值的封閉集合。需要 Claude Code v2.1.214 或更新版本

1021 * `"builtin"`：CLI 自己的工具1025 * `"builtin"`：CLI 本身的工具

1022 * `"mcp"`：一般 MCP 伺服器1026 * `"mcp"`：一般 MCP 伺服器

1023 * `"sdk_host_builtin_mcp"`：內建於 Claude Desktop 本身的進程內伺服器，在 Claude Desktop 擁有的工作階段中。Claude Desktop 擁有它從其自己的進入點之一啟動的工作階段，`claude-desktop`、`claude-desktop-3p` 或 `local-agent`，當該工作階段不是嵌套子項時；嵌套工作階段（包括 Claude Code 本身產生的工作階段）將這些伺服器報告為 `"mcp"`1027 * `"sdk_host_builtin_mcp"`：內建於 Claude Desktop 本身的處理程序內伺服器，位於 Claude Desktop 擁有的工作階段中。當 Claude Desktop 從其自身的進入點 `claude-desktop`、`claude-desktop-3p` 或 `local-agent` 之一啟動工作階段，且該工作階段不是巢狀子工作階段時，Claude Desktop 即擁有該工作階段；巢狀工作階段（包括 Claude Code 本身產生的工作階段）會將這些伺服器回報為 `"mcp"`

1024* `source`：決定來自何處：1028* `source`：決定的來源：

1025 * `"config"`：自動決定而不提示，基於專案設定、使用者個人設定中的允許或拒絕規則、企業管理原則、`--allowedTools` 或 `--disallowedTools` 標誌、活躍權限模式、來自同一互動 CLI 工作階段中較早提示的工作階段範圍授予，或因為工具本質上是安全的。事件不指示這些來源中的哪一個相符。Claude Code 也會在權限提示請求本身失敗時報告 `"config"`，例如當代理程式 SDK 的 [`canUseTool`](/docs/zh-TW/agent-sdk/typescript#canusetool) 回呼或 [`--permission-prompt-tool`](/docs/zh-TW/cli-reference#cli-flags) 工具傳回無效結果時，或當輸入串流在請求待處理時關閉時。在 v2.1.216 之前，Claude Code 將這些失敗報告為 `"user_reject"`。1029 * `"config"`：未經提示而自動決定，依據為專案設定、使用者個人設定中的允許或拒絕規則、企業受管政策、`--allowedTools` 或 `--disallowedTools` 旗標、作用中的權限模式、同一互動式 CLI 工作階段中先前提示所給予的工作階段範圍授權，或因為該工具本身即為安全。此事件不會指出是哪一個來源相符。當權限提示請求本身失敗時，Claude Code 也會回報 `"config"`，例如 Agent SDK 的 [`canUseTool`](/docs/zh-TW/agent-sdk/typescript#canusetool) 回呼或 [`--permission-prompt-tool`](/docs/zh-TW/cli-reference#cli-flags) 工具傳回無效結果時，或在請求等待期間輸入串流關閉時。在 v2.1.216 之前，Claude Code 會將這些失敗回報為 `"user_reject"`。

1026 * `"hook"`：`PreToolUse` 或 `PermissionRequest` 鉤子傳回決定。1030 * `"hook"`：`PreToolUse` 或 `PermissionRequest` hook 傳回了此決定。

1027 * `"user_permanent"`：當使用者在權限提示處選擇「是，不要再問...」時發出，這會將允許規則儲存到其個人設定。在互動 CLI 中，這僅針對該選擇本身發出；稍後與儲存規則相符的呼叫發出 `"config"`。在代理程式 SDK 或非互動 `-p` 工作階段中，初始選擇和稍後規則相符都發出 `"user_permanent"`。視為接受。1031 * `"user_permanent"`：當使用者在權限提示中選擇「Yes, and don't ask again for ...」時發出，這會將允許規則儲存到其個人設定中。在互動式 CLI 中，僅針對該選擇本身發出；之後符合已儲存規則的呼叫會改為發出 `"config"`。在 Agent SDK 或非互動式 `-p` 工作階段中，初始選擇與之後的規則比對都會發出 `"user_permanent"`。視為接受。

1028 * `"user_temporary"`：當使用者在權限提示處選擇「是」進行一次性核准時發出，或在檔案編輯或讀取提示上選擇授予工作階段其餘部分存取權限的選項時發出。在互動 CLI 中，這僅針對選擇本身發出；稍後由該工作階段範圍授予允許的呼叫發出 `"config"`。在代理程式 SDK 或非互動 `-p` 工作階段中，選擇和稍後相符都發出 `"user_temporary"`。視為接受。1032 * `"user_temporary"`：當使用者在權限提示中選擇「Yes」進行一次性核准，或在檔案編輯或讀取提示中選擇授予工作階段剩餘時間存取權的選項時發出。在互動式 CLI 中，僅針對該選擇本身發出；之後因該工作階段範圍授權而允許的呼叫會改為發出 `"config"`。在 Agent SDK 或非互動式 `-p` 工作階段中，該選擇與之後的比對都會發出 `"user_temporary"`。視為接受。

1029 * `"user_abort"`：當使用者在不回答的情況下關閉權限提示時發出。在代理程式 SDK 和非互動 `-p` 工作階段中，這包括在 `canUseTool` 或 `--permission-prompt-tool` 權限請求待處理時中斷回合；在 v2.1.216 之前，Claude Code 將該中斷報告為 `"user_reject"`。視為拒絕。1033 * `"user_abort"`：當使用者未回答即關閉權限提示時發出。在 Agent SDK 與非互動式 `-p` 工作階段中，這包括在 `canUseTool` 或 `--permission-prompt-tool` 權限請求等待期間中斷回合；在 v2.1.216 之前，Claude Code 會將該中斷回報為 `"user_reject"`。視為拒絕。

1030 * `"user_reject"`：當使用者在提示時選擇「否」時發出。在互動 CLI 中，這僅針對該選擇本身發出；與使用者個人設定中的拒絕規則相符的呼叫發出 `"config"`。在代理程式 SDK 或非互動 `-p` 工作階段中，與個人設定中的拒絕規則相符的呼叫發出 `"user_reject"`。視為拒絕。1034 * `"user_reject"`：當使用者在提示時選擇「No」時發出。在互動式 CLI 中，僅針對該選擇本身發出；符合使用者個人設定中拒絕規則的呼叫會改為發出 `"config"`。在 Agent SDK 或非互動式 `-p` 工作階段中，符合個人設定中拒絕規則的呼叫會發出 `"user_reject"`。視為拒絕。

1031* `tool_parameters`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：包含工具特定參數的 JSON 字串。與[工具結果事件](#tool-result-event)相同的形狀，減去執行後欄位，例如 `git_commit_id`。對於接受的呼叫，如果權限決定通過 `updatedInput` 重寫工具輸入，值可能與 `tool_result` 不同。使用此屬性查看當 `decision` 為 `"reject"` 時拒絕了哪個命令。1035* `tool_parameters`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：包含工具特定參數的 JSON 字串。格式與[工具結果事件](#tool-result-event)相同，但不含執行後的欄位，例如 `git_commit_id`。若權限決定透過 `updatedInput` 改寫了工具輸入，已接受呼叫的值可能與 `tool_result` 不同。當 `decision` 為 `"reject"` 時，可使用此屬性查看哪個命令遭到拒絕。

1032 * 對於 `"sdk_host_builtin_mcp"` 工具：即使 `OTEL_LOG_TOOL_DETAILS` 關閉，也會包含 `mcp_server_name` 和 `mcp_tool_name`，因為主應用程式定義這些名稱；沒有它們，對這些內建伺服器之一的拒絕呼叫在預設串流上將無法歸因。對於使用者配置的 MCP 伺服器，事件的 `tool_name` 始終是字面 `"mcp_tool"`，伺服器和工具名稱僅在標誌開啟時出現在 `tool_parameters` 中；引數內容在任何地方都需要標誌。需要 Claude Code v2.1.214 或更新版本1036 * 對於 `"sdk_host_builtin_mcp"` 工具：即使 `OTEL_LOG_TOOL_DETAILS` 關閉，也會包含 `mcp_server_name` 與 `mcp_tool_name`，因為這些名稱是由主機應用程式定義的；若沒有它們，在預設串流上將無法歸屬對這些內建伺服器之一的遭拒呼叫。對於使用者設定的 MCP 伺服器，事件的 `tool_name` 一律為字面值 `"mcp_tool"`，而伺服器與工具名稱僅在旗標開啟時出現在 `tool_parameters` 中；引數內容在任何情況下都需要該旗標。需要 Claude Code v2.1.214 或更新版本

1033 * 對於 Bash 工具：包括 `bash_command`、`full_command`、`timeout`、`description`、`dangerouslyDisableSandbox`。桌面應用程式的工作區 bash 工具也將 `tool_name` 報告為 `Bash`，但只包括 `bash_command`、`full_command` 和 `timeout`1037 * 對於 Bash 工具：包含 `bash_command`、`full_command`、`timeout`、`description`、`dangerouslyDisableSandbox`。桌面應用程式的工作區 bash 工具也會將 `tool_name` 回報為 `Bash`，但僅包含 `bash_command`、`full_command` 與 `timeout`

1034 * 對於 MCP 工具：包括 `mcp_server_name`、`mcp_tool_name`1038 * 對於 MCP 工具：包含 `mcp_server_name`、`mcp_tool_name`

1035 * 對於技能工具：包括 `skill_name`1039 * 對於 Skill 工具：包含 `skill_name`

1036 * 對於代理程式工具或舊版任務工具：包括 `subagent_type`1040 * 對於 Agent 工具或舊版 Task 工具：包含 `subagent_type`

1037 1041

1038<h4 id="permission-mode-changed-event">1042<h4 id="permission-mode-changed-event">

1039 權限模式已變更事件1043 權限模式變更事件

1040</h4>1044</h4>

1041 1045

1042當權限模式變更時記錄，例如從 `Shift+Tab` 循環、退出計畫模式或自動模式閘道檢查。1046在權限模式變更時記錄，例如透過 `Shift+Tab` 循環切換、退出 plan mode，或自動模式閘門檢查。

1043 1047

1044**事件名稱**：`claude_code.permission_mode_changed`1048**事件名稱**：`claude_code.permission_mode_changed`

1045 1049

1048* 所有[標準屬性](#standard-attributes)1052* 所有[標準屬性](#standard-attributes)

1049* `event.name`：`"permission_mode_changed"`1053* `event.name`：`"permission_mode_changed"`

1050* `event.timestamp`：ISO 8601 時間戳記1054* `event.timestamp`：ISO 8601 時間戳記

1051* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述1055* `event.sequence`：用於排序事件的每程序計數器，說明請參閱[事件關聯屬性](#event-correlation-attributes)

1052* `from_mode`：先前的權限模式，例如 `"default"`、`"plan"`、`"acceptEdits"`、`"auto"` 或 `"bypassPermissions"`1056* `from_mode`：先前的權限模式，例如 `"default"`、`"plan"`、`"acceptEdits"`、`"auto"` 或 `"bypassPermissions"`

1053* `to_mode`：新的權限模式1057* `to_mode`：新的權限模式

1054* `trigger`：導致變更的原因。`"shift_tab"`、`"exit_plan_mode"`、`"auto_gate_denied"` 或 `"auto_opt_in"` 之一。當轉換來自 SDK 或橋接時不存在。1058* `trigger`：造成變更的原因。為 `"shift_tab"`、`"exit_plan_mode"`、`"auto_gate_denied"` 或 `"auto_opt_in"` 之一。當轉換源自 SDK 或 bridge 時不存在

1055 1059

1056<h4 id="auth-event">1060<h4 id="auth-event">

1057 驗證事件1061 身分驗證事件

1058</h4>1062</h4>

1059 1063

1060當 `/login` 或 `/logout` 完成時記錄。1064在 `/login` 或 `/logout` 完成時記錄。

1061 1065

1062**事件名稱**：`claude_code.auth`1066**事件名稱**：`claude_code.auth`

1063 1067

1066* 所有[標準屬性](#standard-attributes)1070* 所有[標準屬性](#standard-attributes)

1067* `event.name`：`"auth"`1071* `event.name`：`"auth"`

1068* `event.timestamp`：ISO 8601 時間戳記1072* `event.timestamp`：ISO 8601 時間戳記

1069* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述1073* `event.sequence`：用於排序事件的每程序計數器，說明請參閱[事件關聯屬性](#event-correlation-attributes)

1070* `action`：`"login"` 或 `"logout"`1074* `action`：`"login"` 或 `"logout"`

1071* `success`：`"true"` 或 `"false"`1075* `success`：`"true"` 或 `"false"`

1072* `auth_method`：驗證方法，例如 `"oauth"`1076* `auth_method`：身分驗證方式，例如 `"oauth"`

1073* `error_category`：當動作失敗時的分類錯誤類型。永遠不包括原始錯誤消息1077* `error_category`：動作失敗時的錯誤種類分類。永遠不會包含原始錯誤訊息

1074* `status_code`：當動作因 HTTP 錯誤而失敗時的 HTTP 狀態碼作為字串1078* `status_code`：當動作因 HTTP 錯誤而失敗時，以字串表示的 HTTP 狀態碼

1075 1079

1076<h4 id="mcp-server-connection-event">1080<h4 id="mcp-server-connection-event">

1077 MCP 伺服器連線事件1081 MCP 伺服器連線事件

1078</h4>1082</h4>

1079 1083

1080當 MCP 伺服器連線、斷開連線或無法連線時記錄。1084在 MCP 伺服器連線、中斷連線或連線失敗時記錄。

1081 1085

1082**事件名稱**：`claude_code.mcp_server_connection`1086**事件名稱**：`claude_code.mcp_server_connection`

1083 1087

1086* 所有[標準屬性](#standard-attributes)1090* 所有[標準屬性](#standard-attributes)

1087* `event.name`：`"mcp_server_connection"`1091* `event.name`：`"mcp_server_connection"`

1088* `event.timestamp`：ISO 8601 時間戳記1092* `event.timestamp`：ISO 8601 時間戳記

1089* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述1093* `event.sequence`：用於排序事件的每程序計數器，說明請參閱[事件關聯屬性](#event-correlation-attributes)

1090* `status`：`"connected"`、`"failed"` 或 `"disconnected"`1094* `status`：`"connected"`、`"failed"` 或 `"disconnected"`

1091* `transport_type`：伺服器傳輸，例如 `"stdio"`、`"sse"` 或 `"http"`1095* `transport_type`：伺服器傳輸方式，例如 `"stdio"`、`"sse"` 或 `"http"`

1092* `server_scope`：伺服器配置的範圍，例如 `"user"`、`"project"` 或 `"local"`1096* `server_scope`：伺服器設定所在的範圍，例如 `"user"`、`"project"` 或 `"local"`

1093* `duration_ms`：連線嘗試持續時間（以毫秒為單位）1097* `duration_ms`：連線嘗試的持續時間（毫秒）

1094* `error_code`：連線失敗時的錯誤碼1098* `error_code`：連線失敗時的錯誤代碼

1095* `is_plugin`：當伺服器由外掛程式提供時為 `true`，否則為 `false`1099* `is_plugin`：當伺服器由外掛提供時為 `true`，否則為 `false`

1096* `plugin_id_hash`（當 `is_plugin` 為 `true` 時）：外掛程式名稱和市場的穩定雜湊，用於按外掛程式分組事件而不暴露名稱。Claude Code 按[外掛程式載入事件](#plugin-loaded-event)下描述的方式計算它1100* `plugin_id_hash`（當 `is_plugin` 為 `true` 時）：外掛名稱與市集的穩定雜湊值，可在不暴露名稱的情況下依外掛將事件分組。Claude Code 的計算方式如[外掛載入事件](#plugin-loaded-event)中所述

1097* `plugin.name`（當 `is_plugin` 為 `true` 時）：提供伺服器的外掛程式的名稱。對於第三方外掛程式，此值是字面字串 `"third-party"`，除非 `OTEL_LOG_TOOL_DETAILS=1`；這可防止第三方外掛程式名稱預設出現在日誌中。來自官方 Anthropic 來源的外掛程式始終按名稱識別。`plugin_id_hash` 和 `plugin.name` 屬性流向您自己的監控後端，不會發送給 Anthropic1101* `plugin.name`（當 `is_plugin` 為 `true` 時）：提供該伺服器之外掛的名稱。對於第三方外掛，除非設定了 `OTEL_LOG_TOOL_DETAILS=1`，否則此值為字面字串 `"third-party"`；這可預設防止第三方外掛名稱出現在日誌中。來自 Anthropic 官方來源的外掛一律以名稱識別。`plugin_id_hash` 與 `plugin.name` 屬性會流向您自己的監控後端，不會傳送給 Anthropic

1098* `server_name`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：配置的伺服器名稱1102* `server_name`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：設定的伺服器名稱

1099* `error`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：連線失敗時的完整錯誤消息1103* `error`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：連線失敗時的完整錯誤訊息

1100 1104

1101<h4 id="internal-error-event">1105<h4 id="internal-error-event">

1102 內部錯誤事件1106 內部錯誤事件

1103</h4>1107</h4>

1104 1108

1105當 Claude Code 捕獲意外的內部錯誤時記錄。只記錄錯誤類別名稱和 errno 樣式碼。永遠不包括錯誤消息和堆疊追蹤。在針對 Amazon Bedrock、Google Cloud 的代理程式平台或 Microsoft Foundry 執行時，或設定了 `DISABLE_ERROR_REPORTING` 時，不發出此事件。1109當 Claude Code 捕捉到非預期的內部錯誤時記錄。僅記錄錯誤類別名稱與 errno 風格的代碼。永遠不會包含錯誤訊息與堆疊追蹤。在搭配 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 執行時，或設定了 `DISABLE_ERROR_REPORTING` 時，不會發出此事件。

1106 1110

1107**事件名稱**：`claude_code.internal_error`1111**事件名稱**：`claude_code.internal_error`

1108 1112

1111* 所有[標準屬性](#standard-attributes)1115* 所有[標準屬性](#standard-attributes)

1112* `event.name`：`"internal_error"`1116* `event.name`：`"internal_error"`

1113* `event.timestamp`：ISO 8601 時間戳記1117* `event.timestamp`：ISO 8601 時間戳記

1114* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述1118* `event.sequence`：用於排序事件的每程序計數器，說明請參閱[事件關聯屬性](#event-correlation-attributes)

1115* `error_name`：錯誤類別名稱，例如 `"TypeError"` 或 `"SyntaxError"`1119* `error_name`：錯誤類別名稱，例如 `"TypeError"` 或 `"SyntaxError"`

1116* `error_code`：Node.js errno 碼，例如 `"ENOENT"`（當存在於錯誤上時）1120* `error_code`：錯誤上存在時的 Node.js errno 代碼，例如 `"ENOENT"`

1117 1121

1118<h4 id="plugin-installed-event">1122<h4 id="plugin-installed-event">

1119 外掛程式已安裝事件1123 外掛安裝事件

1120</h4>1124</h4>

1121 1125

1122當外掛程式完成安裝時記錄，來自 `claude plugin install` CLI 命令和互動 `/plugin` UI。1126在外掛完成安裝時記錄，涵蓋 `claude plugin install` CLI 命令與互動式 `/plugin` UI。

1123 1127

1124**事件名稱**：`claude_code.plugin_installed`1128**事件名稱**：`claude_code.plugin_installed`

1125 1129

1128* 所有[標準屬性](#standard-attributes)1132* 所有[標準屬性](#standard-attributes)

1129* `event.name`：`"plugin_installed"`1133* `event.name`：`"plugin_installed"`

1130* `event.timestamp`：ISO 8601 時間戳記1134* `event.timestamp`：ISO 8601 時間戳記

1131* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述1135* `event.sequence`：用於排序事件的每程序計數器，說明請參閱[事件關聯屬性](#event-correlation-attributes)

1132* `marketplace.is_official`：如果市場是官方 Anthropic 市場，則為 `"true"`，否則為 `"false"`1136* `marketplace.is_official`：若市集為 Anthropic 官方市集則為 `"true"`，否則為 `"false"`

1133* `install.trigger`：`"cli"` 或 `"ui"`1137* `install.trigger`：`"cli"` 或 `"ui"`

1134* `plugin.name`：已安裝外掛程式的名稱。對於第三方市場，僅當 `OTEL_LOG_TOOL_DETAILS=1` 時才包含1138* `plugin.name`：已安裝外掛的名稱。對於第三方市集，僅在 `OTEL_LOG_TOOL_DETAILS=1` 時包含

1135* `plugin.version`：在市場項目中宣告時的外掛程式版本。對於第三方市場，僅當 `OTEL_LOG_TOOL_DETAILS=1` 時才包含1139* `plugin.version`：市集項目中宣告的外掛版本。對於第三方市集，僅在 `OTEL_LOG_TOOL_DETAILS=1` 時包含

1136* `marketplace.name`：外掛程式的安裝來源市場。對於第三方市場，僅當 `OTEL_LOG_TOOL_DETAILS=1` 時才包含1140* `marketplace.name`：外掛的安裝來源市集。對於第三方市集，僅在 `OTEL_LOG_TOOL_DETAILS=1` 時包含

1137 1141

1138<h4 id="plugin-loaded-event">1142<h4 id="plugin-loaded-event">

1139 外掛程式已載入事件1143 外掛載入事件

1140</h4>1144</h4>

1141 1145

1142在工作階段開始時為每個啟用的外掛程式記錄一次。使用此事件來清點您的整個車隊中哪些外掛程式有效，作為記錄安裝動作本身的 `plugin_installed` 的補充。1146在工作階段開始時，針對每個已啟用的外掛記錄一次。可使用此事件盤點整個裝置群中作用中的外掛，作為記錄安裝動作本身之 `plugin_installed` 的補充。

1143 1147

1144**事件名稱**：`claude_code.plugin_loaded`1148**事件名稱**：`claude_code.plugin_loaded`

1145 1149

1148* 所有[標準屬性](#standard-attributes)1152* 所有[標準屬性](#standard-attributes)

1149* `event.name`：`"plugin_loaded"`1153* `event.name`：`"plugin_loaded"`

1150* `event.timestamp`：ISO 8601 時間戳記1154* `event.timestamp`：ISO 8601 時間戳記

1151* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述1155* `event.sequence`：用於排序事件的每程序計數器，說明請參閱[事件關聯屬性](#event-correlation-attributes)

1152* `plugin.name`：外掛程式的名稱。對於官方市場和內建捆綁之外的外掛程式，該值為 `"third-party"`，除非 `OTEL_LOG_TOOL_DETAILS=1`1156* `plugin.name`：外掛名稱。對於官方市集與內建套件以外的外掛，除非設定了 `OTEL_LOG_TOOL_DETAILS=1`，否則此值為 `"third-party"`

1153* `marketplace.name`：外掛程式的安裝來源市場（已知時）。在與 `plugin.name` 相同的條件下編輯為 `"third-party"`1157* `marketplace.name`：外掛的安裝來源市集（已知時）。在與 `plugin.name` 相同的條件下遮蔽為 `"third-party"`

1154* `plugin.version`：來自外掛程式清單的版本。僅當名稱未編輯且清單宣告版本時才包含1158* `plugin.version`：外掛資訊清單中的版本。僅在名稱未遮蔽且資訊清單宣告了版本時包含

1155* `plugin.scope`：外掛程式的來源類別：`"official"`、`"community"`、`"org"`、`"user-local"` 或 `"default-bundle"`1159* `plugin.scope`：外掛的來源類別：`"official"`、`"community"`、`"org"`、`"user-local"` 或 `"default-bundle"`

1156* `enabled_via`：外掛程式啟用的方式：`"default-enable"`、`"org-policy"`、`"admin-install"`、`"seed-mount"` 或 `"user-install"`。`"admin-install"` 值表示外掛程式在[**組織設定 > 外掛程式和技能**](https://claude.ai/admin-settings/skills?tab=inventory)中為您的組織設定為必需或自動安裝。在 v2.1.246 之前，Claude Code 將這些外掛程式報告為 `"user-install"` 或 `"seed-mount"`1160* `enabled_via`：外掛被啟用的方式：`"default-enable"`、`"org-policy"`、`"admin-install"`、`"seed-mount"` 或 `"user-install"`。`"admin-install"` 值表示該外掛在 [**Organization settings > Plugins & skills**](https://claude.ai/admin-settings/skills?tab=inventory) 中被設定為您組織的必要或自動安裝外掛。在 v2.1.246 之前，Claude Code 會將這些外掛回報為 `"user-install"` 或 `"seed-mount"`

1157* `plugin_id_hash`：外掛程式名稱和市場的確定性雜湊，僅發送到您配置的匯出器。讓您計算整個車隊中載入的不同第三方外掛程式，而無需記錄其名稱。對於[從 claude.ai 同步的外掛程式](/docs/zh-TW/plugins/loading#synced-plugins)，Claude Code 使用外掛程式名稱與 claude.ai 為外掛程式報告的市場名稱進行雜湊，或使用 `synced`。在 v2.1.246 之前，Claude Code 在雜湊中未使用 claude.ai 報告的市場名稱1161* `plugin_id_hash`：外掛名稱與市集的確定性雜湊值，僅傳送給您設定的匯出器。可讓您在不記錄名稱的情況下，計算整個裝置群中載入的不同第三方外掛數量。對於[從 claude.ai 同步的外掛](/docs/zh-TW/plugins/loading#synced-plugins)，Claude Code 會以 claude.ai 為該外掛回報的市集名稱（否則為 `synced`）與外掛名稱一起計算雜湊。在 v2.1.246 之前，Claude Code 未在雜湊中使用 claude.ai 回報的市集名稱

1158* `has_hooks`：外掛程式是否貢獻鉤子1162* `has_hooks`：外掛是否提供 hook

1159* `has_mcp`：外掛程式是否貢獻 MCP 伺服器1163* `has_mcp`：外掛是否提供 MCP 伺服器

1160* `host_owned_mcp`：當 SDK 主機管理此外掛的 MCP 連線，且 Claude Code 略過讀取外掛的 MCP 伺服器設定時為 `true`，否則為 `false`1164* `host_owned_mcp`：當 SDK 主機管理此外掛的 MCP 連線，且 Claude Code 略過讀取外掛的 MCP 伺服器設定時為 `true`，否則為 `false`

1161* `skill_path_count`：外掛程式宣告的技能目錄數1165* `skill_path_count`：外掛宣告的 skill 目錄數量

1162* `command_path_count`：外掛程式宣告的命令目錄數1166* `command_path_count`：外掛宣告的命令目錄數量

1163* `agent_path_count`：外掛程式宣告的代理程式目錄數1167* `agent_path_count`：外掛宣告的 agent 目錄數量

1164* `safe_mode`：當工作階段以 [`--safe-mode`](/docs/zh-TW/cli-reference) 啟動時為 `"true"`，否則為 `"false"`。在安全模式下，此事件僅報告配置的清單；外掛程式的命令、技能、鉤子和 MCP 伺服器不載入。需要 Claude Code v2.1.169 或更新版本1168* `safe_mode`：當工作階段以 [`--safe-mode`](/docs/zh-TW/cli-reference) 啟動時為 `"true"`，否則為 `"false"`。在安全模式下，此事件僅回報已設定的清單；外掛的命令、skill、hook 與 MCP 伺服器不會載入。需要 Claude Code v2.1.169 或更新版本

1165 1169

1166<h4 id="skill-activated-event">1170<h4 id="skill-activated-event">

1167 技能已啟動事件1171 Skill 啟用事件

1168</h4>1172</h4>

1169 1173

1170當技能被呼叫時記錄，無論 Claude 通過技能工具呼叫它還是您將其作為 `/` 命令執行。1174在 skill 被呼叫時記錄，無論是 Claude 透過 Skill 工具呼叫，或是您以 `/` 命令執行。

1171 1175

1172**事件名稱**：`claude_code.skill_activated`1176**事件名稱**：`claude_code.skill_activated`

1173 1177

1176* 所有[標準屬性](#standard-attributes)1180* 所有[標準屬性](#standard-attributes)

1177* `event.name`：`"skill_activated"`1181* `event.name`：`"skill_activated"`

1178* `event.timestamp`：ISO 8601 時間戳記1182* `event.timestamp`：ISO 8601 時間戳記

1179* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述1183* `event.sequence`：用於排序事件的每程序計數器，說明請參閱[事件關聯屬性](#event-correlation-attributes)

1180* `skill.name`：技能的名稱。對於使用者定義和第三方外掛程式技能，該值是佔位符 `"custom_skill"`，除非 `OTEL_LOG_TOOL_DETAILS=1`1184* `skill.name`：skill 的名稱。對於使用者定義與第三方外掛的 skill，除非設定了 `OTEL_LOG_TOOL_DETAILS=1`，否則此值為預留值 `"custom_skill"`

1181* `invocation_trigger`：技能的觸發方式（`"user-slash"`、`"claude-proactive"` 或 `"nested-skill"`）1185* `invocation_trigger`：skill 的觸發方式（`"user-slash"`、`"claude-proactive"` 或 `"nested-skill"`）

1182* `skill.source`：技能的載入來源（例如，`"bundled"`、`"userSettings"`、`"projectSettings"`、`"plugin"`）1186* `skill.source`：skill 的載入來源（例如 `"bundled"`、`"userSettings"`、`"projectSettings"`、`"plugin"`）

1183* `skill.kind`：當技能是工作流程技能時為 `"workflow"`。否則不存在1187* `skill.kind`：當 skill 為工作流程 skill 時為 `"workflow"`。否則不存在

1184* `plugin.name`（當 `OTEL_LOG_TOOL_DETAILS=1` 或外掛程式來自官方市場時）：當技能由外掛程式提供時的擁有外掛程式的名稱1188* `plugin.name`（當 `OTEL_LOG_TOOL_DETAILS=1` 或外掛來自官方市集時）：當 skill 由外掛提供時，為其所屬外掛的名稱

1185* `marketplace.name`（當 `OTEL_LOG_TOOL_DETAILS=1` 或外掛程式來自官方市場時）：當技能由外掛程式提供時，擁有外掛程式的安裝來源市場1189* `marketplace.name`（當 `OTEL_LOG_TOOL_DETAILS=1` 或外掛來自官方市集時）：當 skill 由外掛提供時，為所屬外掛的安裝來源市集

1186 1190

1187<h4 id="at-mention-event">1191<h4 id="at-mention-event">

1188 @ 提及事件1192 @ 提及事件

1189</h4>1193</h4>

1190 1194

1191當 Claude Code 解析提示中的 `@` 提及時記錄。並非每個提及都發出事件：早期退出路徑，例如權限拒絕、超大檔案、PDF 參考附件和目錄列表失敗，會在不記錄的情況下傳回。1195當 Claude Code 解析提示詞中的 `@` 提及時記錄。並非每個提及都會發出事件：提早結束的路徑（例如權限拒絕、檔案過大、PDF 參考附件與目錄列出失敗）會直接返回而不記錄。

1196

1197每次 Claude Code 讀取提示詞時，最多會記錄 100 個 `mention_type` 為 `"agent"` 的事件，以及 100 個為 `"mcp_resource"` 的事件。超過任一上限的提及仍會被解析，但不會發出事件。

1192 1198

1193**事件名稱**：`claude_code.at_mention`1199**事件名稱**：`claude_code.at_mention`

1194 1200

1197* 所有[標準屬性](#standard-attributes)1203* 所有[標準屬性](#standard-attributes)

1198* `event.name`：`"at_mention"`1204* `event.name`：`"at_mention"`

1199* `event.timestamp`：ISO 8601 時間戳記1205* `event.timestamp`：ISO 8601 時間戳記

1200* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述1206* `event.sequence`：用於排序事件的每程序計數器，說明請參閱[事件關聯屬性](#event-correlation-attributes)

1201* `mention_type`：提及的類型（`"file"`、`"directory"`、`"agent"`、`"mcp_resource"`、`"peer"`）。`"peer"` 值表示您提及了[您的其他 Claude Code 工作階段之一](/docs/zh-TW/cross-session-messaging)。需要 Claude Code v2.1.232 或更新版本1207* `mention_type`：提及的類型（`"file"`、`"directory"`、`"agent"`、`"mcp_resource"`、`"peer"`）。`"peer"` 值表示您提及了[您的其他 Claude Code 工作階段之一](/docs/zh-TW/cross-session-messaging)。需要 Claude Code v2.1.232 或更新版本

1202* `success`：提及是否成功解析（`"true"` 或 `"false"`）1208* `success`：提及是否成功解析（`"true"` 或 `"false"`）

1203 1209

1204<h4 id="api-retries-exhausted-event">1210<h4 id="api-retries-exhausted-event">

1205 API 重試已耗盡事件1211 API 重試用盡事件

1206</h4>1212</h4>

1207 1213

1208當 API 請求在多次嘗試後失敗時記錄一次。與最終 `api_error` 事件一起發出。1214當 API 請求在多次嘗試後失敗時記錄一次。與最終的 `api_error` 事件一同發出。

1209 1215

1210**事件名稱**：`claude_code.api_retries_exhausted`1216**事件名稱**：`claude_code.api_retries_exhausted`

1211 1217

1214* 所有[標準屬性](#standard-attributes)1220* 所有[標準屬性](#standard-attributes)

1215* `event.name`：`"api_retries_exhausted"`1221* `event.name`：`"api_retries_exhausted"`

1216* `event.timestamp`：ISO 8601 時間戳記1222* `event.timestamp`：ISO 8601 時間戳記

1217* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述1223* `event.sequence`：用於排序事件的每程序計數器，說明請參閱[事件關聯屬性](#event-correlation-attributes)

1218* `model`：使用的模型1224* `model`：使用的模型

1219* `error`：最終錯誤消息1225* `error`：最終錯誤訊息

1220* `status_code`：HTTP 狀態碼作為數字。對於非 HTTP 錯誤不存在。1226* `status_code`：以數字表示的 HTTP 狀態碼。對於非 HTTP 錯誤不存在。

1221* `total_attempts`：進行的嘗試總數1227* `total_attempts`：嘗試的總次數

1222* `total_retry_duration_ms`：所有嘗試中的總牆上時間1228* `total_retry_duration_ms`：所有嘗試的總實際經過時間

1223* `speed`：`"fast"` 或 `"normal"`1229* `speed`：`"fast"` 或 `"normal"`

1224 1230

1225<h4 id="hook-registered-event">1231<h4 id="hook-registered-event">

1226 鉤子已註冊事件1232 Hook 註冊事件

1227</h4>1233</h4>

1228 1234

1229在工作階段開始時為每個配置的鉤子記錄一次。使用此事件來清點您的整個車隊中哪些鉤子有效，作為每個執行 `hook_execution_start` 和 `hook_execution_complete` 事件的補充。1235在工作階段開始時，針對每個已設定的 hook 記錄一次。可使用此事件盤點整個裝置群中作用中的 hook，作為每次執行之 `hook_execution_start` 與 `hook_execution_complete` 事件的補充。

1230 1236

1231**事件名稱**：`claude_code.hook_registered`1237**事件名稱**：`claude_code.hook_registered`

1232 1238

1235* 所有[標準屬性](#standard-attributes)1241* 所有[標準屬性](#standard-attributes)

1236* `event.name`：`"hook_registered"`1242* `event.name`：`"hook_registered"`

1237* `event.timestamp`：ISO 8601 時間戳記1243* `event.timestamp`：ISO 8601 時間戳記

1238* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述1244* `event.sequence`：用於排序事件的每程序計數器，說明請參閱[事件關聯屬性](#event-correlation-attributes)

1239* `hook_event`：鉤子事件類型，例如 `"PreToolUse"` 或 `"PostToolUse"`1245* `hook_event`：hook 事件類型，例如 `"PreToolUse"` 或 `"PostToolUse"`

1240* `hook_type`：鉤子實現類型：`"command"`、`"prompt"`、`"mcp_tool"`、`"http"` 或 `"agent"`1246* `hook_type`：hook 實作類型：`"command"`、`"prompt"`、`"mcp_tool"`、`"http"` 或 `"agent"`

1241* `hook_source`：鉤子定義的位置：`"userSettings"`、`"projectSettings"`、`"localSettings"`、`"flagSettings"`、`"policySettings"` 或 `"pluginHook"`1247* `hook_source`：hook 的定義位置：`"userSettings"`、`"projectSettings"`、`"localSettings"`、`"flagSettings"`、`"policySettings"` 或 `"pluginHook"`

1242* `safe_mode`：當工作階段以 [`--safe-mode`](/docs/zh-TW/cli-reference) 啟動時為 `"true"`，否則為 `"false"`。需要 Claude Code v2.1.169 或更新版本1248* `safe_mode`：當工作階段以 [`--safe-mode`](/docs/zh-TW/cli-reference) 啟動時為 `"true"`，否則為 `"false"`。需要 Claude Code v2.1.169 或更新版本

1243* `hook_matcher`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：鉤子配置中的匹配器字串（設定時）1249* `hook_matcher`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：hook 設定中的 matcher 字串（有設定時）

1244* `plugin.name`（當 `hook_source` 為 `"pluginHook"` 時）：貢獻外掛程式的名稱。對於官方市場和內建捆綁之外的外掛程式，該值為 `"third-party"`，除非 `OTEL_LOG_TOOL_DETAILS=1`1250* `plugin.name`（當 `hook_source` 為 `"pluginHook"` 時）：提供該 hook 之外掛的名稱。對於官方市集與內建套件以外的外掛，除非設定了 `OTEL_LOG_TOOL_DETAILS=1`，否則此值為 `"third-party"`

1245* `plugin_id_hash`（當 `hook_source` 為 `"pluginHook"` 時）：外掛程式名稱和市場的確定性雜湊，僅發送到您配置的匯出器。讓您計算不同的貢獻外掛程式而無需記錄其名稱。Claude Code 按[外掛程式載入事件](#plugin-loaded-event)下描述的方式計算它1251* `plugin_id_hash`（當 `hook_source` 為 `"pluginHook"` 時）：外掛名稱與市集的確定性雜湊值，僅傳送給您設定的匯出器。可讓您在不記錄名稱的情況下計算提供 hook 的不同外掛數量。Claude Code 的計算方式如[外掛載入事件](#plugin-loaded-event)中所述

1246 1252

1247<h4 id="hook-execution-start-event">1253<h4 id="hook-execution-start-event">

1248 鉤子執行開始事件1254 Hook 執行開始事件

1249</h4>1255</h4>

1250 1256

1251當一個或多個鉤子開始為鉤子事件執行時記錄。1257當一個或多個 hook 開始針對某個 hook 事件執行時記錄。

1252 1258

1253**事件名稱**：`claude_code.hook_execution_start`1259**事件名稱**：`claude_code.hook_execution_start`

1254 1260

1257* 所有[標準屬性](#standard-attributes)1263* 所有[標準屬性](#standard-attributes)

1258* `event.name`：`"hook_execution_start"`1264* `event.name`：`"hook_execution_start"`

1259* `event.timestamp`：ISO 8601 時間戳記1265* `event.timestamp`：ISO 8601 時間戳記

1260* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述1266* `event.sequence`：用於排序事件的每程序計數器，說明請參閱[事件關聯屬性](#event-correlation-attributes)

1261* `hook_event`：鉤子事件類型，例如 `"PreToolUse"` 或 `"PostToolUse"`1267* `hook_event`：Hook 事件類型，例如 `"PreToolUse"` 或 `"PostToolUse"`

1262* `hook_name`：完整鉤子名稱，包括匹配器，例如 `"PreToolUse:Write"`1268* `hook_name`：包含 matcher 的完整 hook 名稱，例如 `"PreToolUse:Write"`

1263* `num_hooks`：匹配鉤子命令的數量1269* `num_hooks`：相符的 hook 命令數量

1264* `managed_only`：當僅允許管理原則鉤子時為 `"true"`1270* `managed_only`：當僅允許受管政策 hook 時為 `"true"`

1265* `hook_source`：`"policySettings"` 或 `"merged"`1271* `hook_source`：`"policySettings"` 或 `"merged"`

1266* `safe_mode`：當工作階段以 [`--safe-mode`](/docs/zh-TW/cli-reference) 啟動時為 `"true"`，否則為 `"false"`。需要 Claude Code v2.1.169 或更新版本1272* `safe_mode`：當工作階段以 [`--safe-mode`](/docs/zh-TW/cli-reference) 啟動時為 `"true"`，否則為 `"false"`。需要 Claude Code v2.1.169 或更新版本

1267* `hook_definitions`：JSON 序列化的鉤子配置。僅當詳細測試版追蹤和 `OTEL_LOG_TOOL_DETAILS=1` 都啟用時才包含1273* `hook_definitions`：JSON 序列化後的 hook 設定。僅在同時啟用詳細 beta 追蹤與 `OTEL_LOG_TOOL_DETAILS=1` 時包含

1268 1274

1269<h4 id="hook-execution-complete-event">1275<h4 id="hook-execution-complete-event">

1270 鉤子執行完成事件1276 Hook 執行完成事件

1271</h4>1277</h4>

1272 1278

1273當鉤子事件的所有鉤子完成時記錄。1279當某個 hook 事件的所有 hook 都已完成時記錄。

1274 1280

1275**事件名稱**：`claude_code.hook_execution_complete`1281**事件名稱**：`claude_code.hook_execution_complete`

1276 1282

1279* 所有[標準屬性](#standard-attributes)1285* 所有[標準屬性](#standard-attributes)

1280* `event.name`：`"hook_execution_complete"`1286* `event.name`：`"hook_execution_complete"`

1281* `event.timestamp`：ISO 8601 時間戳記1287* `event.timestamp`：ISO 8601 時間戳記

1282* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述1288* `event.sequence`：用於排序事件的每程序計數器，說明請參閱[事件關聯屬性](#event-correlation-attributes)

1283* `hook_event`：鉤子事件類型1289* `hook_event`：Hook 事件類型

1284* `hook_name`：完整鉤子名稱，包括匹配器1290* `hook_name`：包含 matcher 的完整 hook 名稱

1285* `num_hooks`：匹配鉤子命令的數量1291* `num_hooks`：相符的 hook 命令數量

1286* `num_success`：成功完成的計數1292* `num_success`：成功完成的數量

1287* `num_blocking`：傳回阻止決定的計數1293* `num_blocking`：傳回阻擋決定的數量

1288* `num_non_blocking_error`：在不阻止的情況下失敗的計數1294* `num_non_blocking_error`：失敗但未阻擋的數量

1289* `num_cancelled`：在完成前取消的計數1295* `num_cancelled`：完成前被取消的數量

1290* `total_duration_ms`：所有匹配鉤子的牆上持續時間1296* `total_duration_ms`：所有相符 hook 的實際經過時間

1291* `stdout_chars`：成功的匹配鉤子中的 stdout 總字元數。需要 Claude Code v2.1.280 或更新版本1297* `stdout_chars`：成功之相符 hook 的 stdout 總字元數。需要 Claude Code v2.1.280 或更新版本

1292* `additional_context_chars`：匹配鉤子傳回的 `additionalContext` 的總字元數。需要 Claude Code v2.1.280 或更新版本1298* `additional_context_chars`：相符 hook 傳回之 `additionalContext` 的總字元數。需要 Claude Code v2.1.280 或更新版本

1293* `system_message_chars`：匹配鉤子傳回的 `systemMessage` 的總字元數。需要 Claude Code v2.1.280 或更新版本1299* `system_message_chars`：相符 hook 傳回之 `systemMessage` 的總字元數。需要 Claude Code v2.1.280 或更新版本

1294* `initial_user_message_chars`：匹配鉤子傳回的 `initialUserMessage` 的總字元數。需要 Claude Code v2.1.280 或更新版本1300* `initial_user_message_chars`：相符 hook 傳回之 `initialUserMessage` 的總字元數。需要 Claude Code v2.1.280 或更新版本

1295* `num_outputs_persisted`：超過[10,000 字元上限](/docs/zh-TW/hooks#json-output)的鉤子輸出數，Claude Code 儲存到檔案。需要 Claude Code v2.1.280 或更新版本1301* `num_outputs_persisted`：超過 [10,000 字元上限](/docs/zh-TW/hooks#json-output)而由 Claude Code 儲存至檔案的 hook 輸出數量。需要 Claude Code v2.1.280 或更新版本

1296* `managed_only`：當僅允許管理原則鉤子時為 `"true"`1302* `managed_only`：當僅允許受管政策 hook 時為 `"true"`

1297* `hook_source`：`"policySettings"` 或 `"merged"`1303* `hook_source`：`"policySettings"` 或 `"merged"`

1298* `safe_mode`：當工作階段以 [`--safe-mode`](/docs/zh-TW/cli-reference) 啟動時為 `"true"`，否則為 `"false"`。需要 Claude Code v2.1.169 或更新版本1304* `safe_mode`：當工作階段以 [`--safe-mode`](/docs/zh-TW/cli-reference) 啟動時為 `"true"`，否則為 `"false"`。需要 Claude Code v2.1.169 或更新版本

1299* `hook_definitions`：JSON 序列化的鉤子配置。僅當詳細測試版追蹤和 `OTEL_LOG_TOOL_DETAILS=1` 都啟用時才包含1305* `hook_definitions`：JSON 序列化後的 hook 設定。僅在同時啟用詳細 beta 追蹤與 `OTEL_LOG_TOOL_DETAILS=1` 時包含

1300 1306

1301<h4 id="hook-plugin-metrics-event">1307<h4 id="hook-plugin-metrics-event">

1302 鉤子外掛程式指標事件1308 Hook 外掛指標事件

1303</h4>1309</h4>

1304 1310

1305當官方市場外掛程式鉤子發出每次呼叫指標時記錄。只有從官方 Anthropic 市場安裝的外掛程式才能發出這些。第三方市場外掛程式和使用者配置的鉤子不發出到此事件。使用此事件從您自己的可觀測性堆疊監控外掛程式行為，例如尋找率、成本和持續時間。1311當官方市集外掛的 hook 發出每次呼叫的指標時記錄。只有從 Anthropic 官方市集安裝的外掛才能發出這些指標。第三方市集外掛與使用者設定的 hook 不會發出此事件。可使用此事件從您自己的可觀測性堆疊監控外掛行為，例如發現率、成本與持續時間。

1306 1312

1307**事件名稱**：`claude_code.hook_plugin_metrics`1313**事件名稱**：`claude_code.hook_plugin_metrics`

1308 1314

1311* 所有[標準屬性](#standard-attributes)1317* 所有[標準屬性](#standard-attributes)

1312* `event.name`：`"hook_plugin_metrics"`1318* `event.name`：`"hook_plugin_metrics"`

1313* `event.timestamp`：ISO 8601 時間戳記1319* `event.timestamp`：ISO 8601 時間戳記

1314* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述1320* `event.sequence`：用於排序事件的每程序計數器，說明請參閱[事件關聯屬性](#event-correlation-attributes)

1315* `plugin_id`：`<name>@<marketplace>` 形式的外掛程式識別碼1321* `plugin_id`：`<name>@<marketplace>` 形式的外掛識別碼

1316* `hook_event`：發出指標的鉤子事件類型1322* `hook_event`：發出指標的 hook 事件類型

1317* 最多 20 個由外掛發出的指標鍵。名稱符合 `^[a-z][a-z0-9_]{0,39}$`。值為布林值或數字。1323* 最多 20 個外掛發出的指標鍵。名稱需符合 `^[a-z][a-z0-9_]{0,39}$`。值為布林值或數字。

1318 1324

1319<h4 id="compaction-event">1325<h4 id="compaction-event">

1320 壓縮事件1326 壓縮事件

1321</h4>1327</h4>

1322 1328

1323當對話壓縮完成時記錄。1329在對話壓縮完成時記錄。

1324 1330

1325**事件名稱**：`claude_code.compaction`1331**事件名稱**：`claude_code.compaction`

1326 1332

1329* 所有[標準屬性](#standard-attributes)1335* 所有[標準屬性](#standard-attributes)

1330* `event.name`：`"compaction"`1336* `event.name`：`"compaction"`

1331* `event.timestamp`：ISO 8601 時間戳記1337* `event.timestamp`：ISO 8601 時間戳記

1332* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述1338* `event.sequence`：用於排序事件的每程序計數器，說明請參閱[事件關聯屬性](#event-correlation-attributes)

1333* `trigger`：`"auto"` 或 `"manual"`1339* `trigger`：`"auto"` 或 `"manual"`

1334* `success`：`"true"` 或 `"false"`1340* `success`：`"true"` 或 `"false"`

1335* `duration_ms`：壓縮持續時間1341* `duration_ms`：壓縮持續時間

1336* `pre_tokens`：壓縮前的近似權杖計數1342* `pre_tokens`：壓縮前的約略 token 數量

1337* `post_tokens`：壓縮後的近似權杖計數1343* `post_tokens`：壓縮後的約略 token 數量

1338* `error`：壓縮失敗時的錯誤消息1344* `error`：壓縮失敗時的錯誤訊息

1339* `precompute_reuse`：僅在 `trigger` 為 `"manual"` 時設定。自動壓縮可在上下文視窗填滿之前於背景預先準備摘要，而此屬性記錄 `/compact` 是否重複使用了該預先準備的摘要。`"hit"` 表示已重複使用；`"miss_custom_instructions"`、`"miss_hook"` 與 `"miss_not_ready"` 則說明改為重新計算摘要的原因1345* `precompute_reuse`：僅在 `trigger` 為 `"manual"` 時設定。自動壓縮可在上下文視窗填滿前於背景準備摘要，此屬性記錄 `/compact` 是否重複使用了該預先準備的摘要。`"hit"` 表示已重複使用；`"miss_custom_instructions"`、`"miss_hook"` 與 `"miss_not_ready"` 則說明改為重新計算摘要的原因

1340 1346

1341<h4 id="subagent-completed-event">1347<h4 id="subagent-completed-event">

1342 子代理程式已完成事件1348 Subagent 完成事件

1343</h4>1349</h4>

1344 1350

1345當[子代理程式](/docs/zh-TW/sub-agents)完成並將其結果傳回啟動它的對話時記錄。使用它按子代理程式類型匯總工具使用和執行時間；對於權杖或成本匯總，使用[權杖計數器](#token-counter)和[成本計數器](#cost-counter)篩選到 `query_source` `"subagent"`，因為此事件的 `total_tokens` 僅涵蓋最終請求。`"subagent"` 類別也計算來自基於代理程式的鉤子的請求，它們不發出子代理程式事件。1351在 [subagent](/docs/zh-TW/sub-agents) 完成並將結果傳回啟動它的對話時記錄。可用於依 subagent 類型彙總工具使用情況與執行時間；若要彙總 token 或成本，請使用以 `query_source` `"subagent"` 篩選的 [token 計數器](#token-counter)與[成本計數器](#cost-counter)，因為此事件的 `total_tokens` 僅涵蓋最後一個請求。`"subagent"` 類別也會計入來自以 agent 為基礎之 hook 的請求，而這些 hook 不會發出 subagent 事件。

1346 1352

1347**事件名稱**：`claude_code.subagent_completed`1353**事件名稱**：`claude_code.subagent_completed`

1348 1354

1351* 所有[標準屬性](#standard-attributes)1357* 所有[標準屬性](#standard-attributes)

1352* `event.name`：`"subagent_completed"`1358* `event.name`：`"subagent_completed"`

1353* `event.timestamp`：ISO 8601 時間戳記1359* `event.timestamp`：ISO 8601 時間戳記

1354* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述1360* `event.sequence`：用於排序事件的每程序計數器，說明請見[事件關聯屬性](#event-correlation-attributes)

1355* `agent_type`：子代理程式類型。內建代理程式名稱和來自官方市場外掛程式的代理程式會逐字出現；其他代理程式名稱會被替換為 `"custom"`，除非設定了 `OTEL_LOG_TOOL_DETAILS=1`1361* `agent_type`：subagent 類型。內建 agent 名稱及來自官方市集外掛的 agent 會原樣顯示；除非設定了 `OTEL_LOG_TOOL_DETAILS=1`，否則其他 agent 名稱會以 `"custom"` 取代

1356* `agent.source`：代理程式定義的來源：`built-in`、`plugin` 或定義自訂代理程式的設定來源，例如 `userSettings` 或 `projectSettings`1362* `agent.source`：agent 定義的來源：`built-in`、`plugin`，或定義自訂 agent 的設定來源，例如 `userSettings` 或 `projectSettings`

1357* `is_built_in`：子代理程式是否為內建代理程式類型1363* `is_built_in`：subagent 是否為內建 agent 類型

1358* `is_async`：子代理程式是否在[背景](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)中執行1364* `is_async`：subagent 是否在[背景](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)執行

1359* `total_tokens`：子代理程式最終 API 請求的權杖足跡：該單個請求的輸入、快取建立、快取讀取和輸出權杖，大約是子代理程式在完成時的上下文大小。不是整個執行的總和1365* `total_tokens`：subagent 最後一個 API 請求的 token 用量：該請求的輸入、快取建立、快取讀取與輸出 token，大致等於 subagent 完成時的上下文大小。並非整個執行過程的總和

1360* `total_tool_uses`：子代理程式在整個執行中進行的工具呼叫數1366* `total_tool_uses`：subagent 在整個執行過程中進行的工具呼叫次數

1361* `duration_ms`：執行時間（以毫秒為單位）1367* `duration_ms`：執行時間（毫秒）

1362* `model`：子代理程式被解析為執行的模型1368* `model`：subagent 被解析為使用的模型

1363* `final_model`：產生子代理程式最終回應的模型，在中途切換（例如回退）後與 `model` 不同。需要 Claude Code v2.1.212 或更新版本1369* `final_model`：產生 subagent 最終回應的模型；在執行中途切換（例如備援）之後，此值會與 `model` 不同。需要 Claude Code v2.1.212 或更新版本

1364* `model_swapped`：是否有多個模型為子代理程式的請求提供服務。需要 Claude Code v2.1.212 或更新版本1370* `model_swapped`：是否有多個模型處理過 subagent 的請求。需要 Claude Code v2.1.212 或更新版本

1365* `plugin_id_hash`、`plugin.name`：對於外掛程式提供的代理程式存在。官方市場外掛程式名稱會逐字出現；其他外掛程式名稱會被替換為 `"third-party"`，除非設定了 `OTEL_LOG_TOOL_DETAILS=1`1371* `plugin_id_hash`、`plugin.name`：由外掛提供的 agent 才會出現。官方市集外掛名稱會原樣顯示；除非設定了 `OTEL_LOG_TOOL_DETAILS=1`，否則其他外掛名稱會以 `"third-party"` 取代

1366 1372

1367<h4 id="feedback-survey-event">1373<h4 id="feedback-survey-event">

1368 回饋調查事件1374 意見調查事件

1369</h4>1375</h4>

1370 1376

1371當顯示或回答工作階段品質調查時記錄。請參閱[工作階段品質調查](/docs/zh-TW/data-usage#session-quality-surveys)以了解調查收集的內容以及如何控制它們。1377在顯示或回答工作階段品質調查時記錄。關於調查收集的內容及如何控制，請參閱[工作階段品質調查](/docs/zh-TW/data-usage#session-quality-surveys)。

1372 1378

1373**事件名稱**：`claude_code.feedback_survey`1379**事件名稱**：`claude_code.feedback_survey`

1374 1380

1377* 所有[標準屬性](#standard-attributes)1383* 所有[標準屬性](#standard-attributes)

1378* `event.name`：`"feedback_survey"`1384* `event.name`：`"feedback_survey"`

1379* `event.timestamp`：ISO 8601 時間戳記1385* `event.timestamp`：ISO 8601 時間戳記

1380* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述1386* `event.sequence`：用於排序事件的每程序計數器，說明請見[事件關聯屬性](#event-correlation-attributes)

1381* `event_type`：調查生命週期事件，例如 `"appeared"`、`"responded"` 或 `"transcript_prompt_appeared"`1387* `event_type`：調查生命週期事件，例如 `"appeared"`、`"responded"` 或 `"transcript_prompt_appeared"`

1382* `appearance_id`：唯一 ID，連結為一個調查實例發出的事件1388* `appearance_id`：用於連結同一調查實例所發出之事件的唯一 ID

1383* `survey_type`：哪個調查產生事件。`"session"` 是「Claude 做得如何？」評分提示1389* `survey_type`：產生此事件的調查。`"session"` 為「How is Claude doing?」評分提示

1384* `response`：使用者在 `responded` 事件上的選擇1390* `response`：使用者在 `responded` 事件中的選擇

1385* `enabled_via_override`：設定 [`CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL`](/docs/zh-TW/env-vars) 時為 `true`。以布林值而非字串發出。出現在 `session` 調查事件上。可依此屬性篩選，以確認覆寫已套用至整個機群1391* `enabled_via_override`：設定了 [`CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL`](/docs/zh-TW/env-vars) 時為 `true`。以 Boolean 而非字串發出。出現在 `session` 調查事件上。可依此屬性篩選，以確認覆寫已套用至整個裝置群

1386 1392

1387<h4 id="retention-sweep-event">1393<h4 id="retention-sweep-event">

1388 保留掃描事件1394 保留清理事件

1389</h4>1395</h4>

1390 1396

1391每次執行保留清理掃描時記錄一次，該掃描刪除[工作階段文字記錄和其他應用程式資料](/docs/zh-TW/claude-directory#cleaned-up-automatically)早於 [`cleanupPeriodDays`](/docs/zh-TW/settings-reference#cleanupperioddays) 設定的資料。Claude Code 在背景中最多每個工作階段執行一次掃描，刪除任何內容的執行仍會發出事件。如果 Claude Code 在過去 24 小時內在同一台機器上的任何工作階段中執行了掃描，它會將此工作階段的掃描延遲至少 10 分鐘，因此更早退出的工作階段不發出任何內容。當您使用 `--bare` 執行 `claude -p` 時，Claude Code 不執行掃描且不發出任何內容。1397保留清理作業每執行一次記錄一次，此作業會刪除早於 [`cleanupPeriodDays`](/docs/zh-TW/settings-reference#cleanupperioddays) 設定的[工作階段逐字稿及其他應用程式資料](/docs/zh-TW/claude-directory#cleaned-up-automatically)。Claude Code 在每個工作階段中最多於背景執行一次清理作業，即使某次執行未刪除任何內容也會發出此事件。若 Claude Code 在過去 24 小時內已於同一台電腦上的任何工作階段執行過清理作業，則會將此工作階段的清理作業延後至少 10 分鐘，因此較早結束的工作階段不會發出任何內容。使用 `--bare` 執行 `claude -p` 時，Claude Code 不會執行清理作業，也不會發出任何內容。

1392 1398

1393與此頁面上的每個 OTel 事件一樣，它僅流向您配置的遙測後端。需要 Claude Code v2.1.227 或更新版本。1399如同本頁上的所有 OTel 事件，此事件只會傳送至您設定的遙測後端。需要 Claude Code v2.1.227 或更新版本。

1394 1400

1395當 Claude Code 無法安全地確定保留期時，它會暫停掃描並發出事件，`result` 設定為 `"skipped"` 和 `skip_reason`。當[管理設定](/docs/zh-TW/server-managed-settings)設定 `cleanupPeriodDays` 時，管理值會固定保留期，掃描即使在較低優先級範圍中的設定檔案損壞或無效時也會執行。當 `managed-settings.json` 本身無法讀取時，Claude Code 仍會暫停掃描，除非[管理層](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)從其他地方（例如伺服器管理設定或損壞檔案旁邊的 `managed-settings.d/` 放置）提供 `cleanupPeriodDays`。刪除計數器屬性僅當 `result` 為 `"complete"` 時存在。1401當 Claude Code 無法安全地判斷保留期間時，會暫停清理作業，並發出 `result` 設為 `"skipped"` 且帶有 `skip_reason` 的事件。當[受管設定](/docs/zh-TW/server-managed-settings)設定了 `cleanupPeriodDays` 時，受管的值會固定保留期間，即使較低優先順序範圍中的設定檔損毀或無效，清理作業仍會執行。當 `managed-settings.json` 本身無法讀取時，除非[受管層級](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)從其他來源（例如伺服器受管設定或位於損毀檔案旁的 `managed-settings.d/` 附加檔案）提供 `cleanupPeriodDays`，否則 Claude Code 仍會暫停清理作業。刪除計數器屬性只有在 `result` 為 `"complete"` 時才會出現。

1396 1402

1397**事件名稱**：`claude_code.retention_sweep`1403**事件名稱**：`claude_code.retention_sweep`

1398 1404

1401* 所有[標準屬性](#standard-attributes)1407* 所有[標準屬性](#standard-attributes)

1402* `event.name`：`"retention_sweep"`1408* `event.name`：`"retention_sweep"`

1403* `event.timestamp`：ISO 8601 時間戳記1409* `event.timestamp`：ISO 8601 時間戳記

1404* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述1410* `event.sequence`：用於排序事件的每程序計數器，說明請見[事件關聯屬性](#event-correlation-attributes)

1405* `result`：掃描執行時為 `"complete"`，Claude Code 暫停時為 `"skipped"`1411* `result`：清理作業已執行時為 `"complete"`，Claude Code 暫停時為 `"skipped"`

1406* `period_days`：合併設定中的 `cleanupPeriodDays` 值（以天為單位），或當沒有來源設定時為 `30`。在跳過的事件上，掃描會使用的值，從 Claude Code 可以讀取的設定來源計算1412* `period_days`：合併設定中的 `cleanupPeriodDays` 值（以天為單位），若沒有任何來源設定則為 `30`。在略過的事件中，此值為清理作業原本會使用的值，根據 Claude Code 能夠讀取的設定來源計算而得

1407* `used_default`：當沒有可讀的設定來源設定 `cleanupPeriodDays` 時為 `"true"`，否則為 `"false"`。在完成事件上，`"true"` 表示應用了 30 天預設值1413* `used_default`：沒有任何可讀取的設定來源設定 `cleanupPeriodDays` 時為 `"true"`，否則為 `"false"`。在完成的事件中，`"true"` 表示套用了 30 天的預設值

1408* `skip_reason`：Claude Code 暫停掃描的原因。僅當 `result` 為 `"skipped"` 時存在：1414* `skip_reason`：Claude Code 暫停清理作業的原因。僅在 `result` 為 `"skipped"` 時出現：

1409 * `"user_source_disabled"`：使用者設定被排除，例如通過 [`--setting-sources`](/docs/zh-TW/cli-reference#cli-flags) 標誌或 SDK 的 [`settingSources`](/docs/zh-TW/agent-sdk/typescript#options) 選項，且沒有啟用的來源提供 `cleanupPeriodDays`1415 * `"user_source_disabled"`：使用者設定被排除，例如透過 [`--setting-sources`](/docs/zh-TW/cli-reference#cli-flags) 旗標或 SDK 的 [`settingSources`](/docs/zh-TW/agent-sdk/typescript#options) 選項，且沒有任何已啟用的來源提供 `cleanupPeriodDays`

1410 * `"settings_unknowable"`：設定檔案無法讀取或解析，因此 `cleanupPeriodDays` 或 `desktopSessionCleanupPeriodDays` 可能設定為 Claude Code 無法看到的值1416 * `"settings_unknowable"`：某個設定檔無法讀取或剖析，因此 `cleanupPeriodDays` 或 `desktopSessionCleanupPeriodDays` 可能被設為 Claude Code 看不到的值

1411 * `"settings_invalid_key_set"`：設定有驗證錯誤且 `cleanupPeriodDays` 或 `desktopSessionCleanupPeriodDays` 被明確設定，因此回退到預設值可能會刪除或保留違反該設定的檔案1417 * `"settings_invalid_key_set"`：設定有驗證錯誤，且明確設定了 `cleanupPeriodDays` 或 `desktopSessionCleanupPeriodDays`，因此改用預設值可能會違反該設定而刪除或保留檔案

1412* `transcripts_deleted`：掃描刪除的工作階段文字記錄數，頂級 `~/.claude/projects/*/*.jsonl` 檔案1418* `transcripts_deleted`：清理作業刪除的工作階段逐字稿（即頂層的 `~/.claude/projects/*/*.jsonl` 檔案）數量

1413* `transcripts_exempted_desktop`：超過保留期的文字記錄數，掃描在 [Claude Desktop 和 Cowork 規則](/docs/zh-TW/claude-directory#cleaned-up-automatically)下保留。這些不計入 `files_past_cutoff`。需要 Claude Code v2.1.248 或更新版本1419* `transcripts_exempted_desktop`：已超過保留期間、但清理作業依 [Claude Desktop 與 Cowork 規則](/docs/zh-TW/claude-directory#cleaned-up-automatically)保留的逐字稿數量。這些不計入 `files_past_cutoff`。需要 Claude Code v2.1.248 或更新版本

1414* `session_files_deleted`：工作階段檔案掃描刪除的項目數：文字記錄加上每個工作階段的伴隨檔案，例如邊車、錄製和工具結果1420* `session_files_deleted`：工作階段檔案清理作業刪除的 artifact 數量：逐字稿加上每個工作階段的附屬檔案，例如 sidecar、錄製內容與工具結果

1415* `artifacts_deleted`：掃描跨越的資料目錄中刪除的總項目，包括工作階段檔案。某些掃描將整個移除的目錄樹計為一項，少數清理通過不貢獻計數器，因此將該值視為下限而不是確切的檔案計數1421* `artifacts_deleted`：清理作業在其涵蓋的資料目錄中刪除的項目總數，包括工作階段檔案。部分清理作業會將整個移除的目錄樹計為一個項目，且少數清理流程不會計入此計數器，因此請將此值視為下限，而非精確的檔案數量

1416* `files_retained_fresh`：檢查並保留在原位的檔案，因為它們仍在保留期內。只有每個檔案掃描計算這些，因此該值是下限；非零值是正常的穩定狀態1422* `files_retained_fresh`：已檢查但因仍在保留期間內而保留的檔案。只有逐檔案的清理作業會計入這些檔案，因此此值為下限；非零值為正常的穩定狀態

1417* `files_past_cutoff`：早於保留期但清理未能刪除的檔案，例如因權限錯誤或檔案被開啟佔用。此計數也包括清理在 `skills/synced/` 或 `plugins/synced/` 下找到的每個過時資料夾，無論是否已將該資料夾移至垃圾桶。除了這些資料夾之外，大於零的值表示有檔案超過了設定的保留期仍然存在；零並不能證明沒有這種情況，因為移除整個目錄失敗會改計入 `error_count`1423* `files_past_cutoff`：早於保留期間但清理作業未能刪除的檔案，例如因權限錯誤或檔案被開啟佔用。此計數也包含清理作業在 `skills/synced/` 或 `plugins/synced/` 下找到的每個過時資料夾，無論是否將該資料夾移至垃圾桶。除了這些資料夾之外，大於零的值表示有檔案超過了所設定的保留期間；零並不能證明沒有檔案超過，因為移除整個目錄失敗時會改計入 `error_count`

1418* `error_count`：掃描在列出或刪除檔案時遇到的錯誤數1424* `error_count`：清理作業在列出或刪除檔案時遇到的錯誤數量

1419 1425

1420<h4 id="managed-settings-resolved-event">1426<h4 id="managed-settings-resolved-event">

1421 管理設定已解析事件1427 受管設定解析事件

1422</h4>1428</h4>

1423 1429

1424使用工作階段解析的[管理設定](/docs/zh-TW/managed-settings)記錄：在工作階段開始時一次，當管理設定或[原則協助程式](/docs/zh-TW/managed-settings#compute-the-policy-with-a-helper-program)的狀態在工作階段期間變更時再次，以及當 Claude Code 拒絕啟動或因 `error.type` 屬性列出的原因之一而結束工作階段時。1430隨工作階段所解析的[受管設定](/docs/zh-TW/managed-settings)一併記錄：於工作階段開始時記錄一次，在工作階段期間受管設定或[政策輔助程式](/docs/zh-TW/managed-settings#compute-the-policy-with-a-helper-program)的狀態變更時再次記錄，以及當 Claude Code 因 `error.type` 屬性所列的原因之一而拒絕啟動或結束工作階段時記錄。

1425使用此事件尋找在意外管理來源上執行的機器、原則協助程式失敗的機器以及機器拒絕啟動的原因。1431可使用此事件找出在非預期受管來源上執行的電腦、政策輔助程式失敗的電腦，以及電腦拒絕啟動的原因。

1426需要 Claude Code v2.1.274 或更新版本。1432需要 Claude Code v2.1.274 或更新版本。

1427 1433

1428預設情況下，事件攜帶管理來源和原則協助程式的狀態，但不攜帶設定本身。要新增編輯的 `managed_settings.settings` 屬性和 `managed_settings.resolved_sha256` 摘要，請設定 `OTEL_LOG_MANAGED_SETTINGS=1`：1434根據預設，此事件會包含受管來源與政策輔助程式的狀態，但不包含設定本身。若要加入經過遮蔽的 `managed_settings.settings` 屬性與 `managed_settings.resolved_sha256` 摘要，請設定 `OTEL_LOG_MANAGED_SETTINGS=1`：

1429 1435

1430* 在管理設定、使用者設定或 `--settings` 的 `env` 區塊中設定它，或在您啟動 Claude Code 的環境中設定。專案或本地設定中的值不會啟用它，因為複製的儲存庫可以寫入它們。1436* 在受管設定、使用者設定或 `--settings` 的 `env` 區塊中設定，或在啟動 Claude Code 的環境中設定。在專案或本機設定中設定此值不會啟用它，因為複製的儲存庫可以寫入這些設定。

1431* 伺服器管理設定可以在不顯示[安全核准對話框](/docs/zh-TW/server-managed-settings#security-approval-dialogs)的情況下設定它，因為變數僅將您組織自己的編輯原則新增到您的組織已接收的事件。1437* 伺服器受管設定可以設定此值而不顯示[安全性核准對話方塊](/docs/zh-TW/server-managed-settings#security-approval-dialogs)，因為此變數只會將您組織自己經過遮蔽的政策加入您組織已經會收到的事件中。

1432 1438

1433在您尚未[信任](/docs/zh-TW/permissions#what-runs-before-you-trust-a-folder)的資料夾中的互動工作階段中，Claude Code 不匯出拒絕事件。1439在您尚未[信任](/docs/zh-TW/permissions#what-runs-before-you-trust-a-folder)的資料夾中的互動式工作階段，Claude Code 不會匯出拒絕事件。

1434 1440

1435**事件名稱**：`claude_code.managed_settings_resolved`1441**事件名稱**：`claude_code.managed_settings_resolved`

1436 1442

1439* 所有[標準屬性](#standard-attributes)1445* 所有[標準屬性](#standard-attributes)

1440* `event.name`：`"managed_settings_resolved"`1446* `event.name`：`"managed_settings_resolved"`

1441* `event.timestamp`：ISO 8601 時間戳記1447* `event.timestamp`：ISO 8601 時間戳記

1442* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述1448* `event.sequence`：用於排序事件的每程序計數器，說明請見[事件關聯屬性](#event-correlation-attributes)

1443* `managed_settings.trigger`：工作階段啟動事件為 `"startup"`，當管理設定或原則協助程式的狀態在工作階段稍後變更時為 `"change"`，或當管理設定原則停止工作階段時為 `"refused"`。Claude Code 僅在屬性與它發送的最後一個事件不同時發送 `change` 事件，變更的設定值計數即使 `OTEL_LOG_MANAGED_SETTINGS` 關閉1449* `managed_settings.trigger`：工作階段開始事件為 `"startup"`，在工作階段後續受管設定或政策輔助程式狀態變更時為 `"change"`，受管設定政策停止工作階段時為 `"refused"`。只有當某個屬性與上次傳送的事件不同時，Claude Code 才會傳送 `change` 事件；即使 `OTEL_LOG_MANAGED_SETTINGS` 未開啟，設定值的變更也會計入

1444* `error.type`：Claude Code 停止工作階段的原因。僅在 `refused` 事件上存在：1450* `error.type`：Claude Code 停止工作階段的原因。僅出現在 `refused` 事件上：

1445 * `"helper_failed"`：[原則協助程式執行失敗](/docs/zh-TW/settings-reference#helper-failures)1451 * `"helper_failed"`：[政策輔助程式執行失敗](/docs/zh-TW/settings-reference#helper-failures)

1446 * `"policy_invalid"`：管理設定包含停止 Claude Code 啟動的錯誤，或管理來源無法載入，因此 Claude Code 無法檢查組織登入強制執行1452 * `"policy_invalid"`：受管設定包含會阻止 Claude Code 啟動的錯誤，或某個管理來源因讀取被拒以外的原因而載入失敗，導致 Claude Code 無法檢查組織登入或提供者強制規定

1447 * `"provider_not_allowed"`：工作階段會使用 API 提供者，或將提供者的流量發送到管理 [`allowedProviders`](/docs/zh-TW/settings-reference#allowedproviders) 列表不允許的主機。需要 Claude Code v2.1.285 或更新版本1453 * `"provider_not_allowed"`：工作階段會使用受管 [`allowedProviders`](/docs/zh-TW/settings-reference#allowedproviders) 清單不允許的 API 提供者，或將某個提供者的流量傳送至不允許的主機。需要 Claude Code v2.1.285 或更新版本

1448 * `"consent_rejected"`：使用者拒絕了伺服器管理設定的[安全核准對話框](/docs/zh-TW/server-managed-settings#security-approval-dialogs)1454 * `"consent_rejected"`：使用者拒絕了伺服器受管設定的[安全性核准對話方塊](/docs/zh-TW/server-managed-settings#security-approval-dialogs)

1449 * `"force_refresh_failed"`：[`forceRemoteSettingsRefresh`](/docs/zh-TW/settings-reference#forceremotesettingsrefresh) 需要的設定擷取失敗1455 * `"force_refresh_failed"`：[`forceRemoteSettingsRefresh`](/docs/zh-TW/settings-reference#forceremotesettingsrefresh) 所要求的設定擷取失敗

1450 * `"gateway_rejected"`：[Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway)以 HTTP 403 回答管理設定載入1456 * `"gateway_rejected"`：[Claude apps 閘道](/docs/zh-TW/claude-apps-gateway)以 HTTP 403 回應受管設定載入

1451 * `"version_below_minimum"`：此版本的 Claude Code 低於 [`requiredMinimumVersion`](/docs/zh-TW/settings-reference#requiredminimumversion) 或高於 [`requiredMaximumVersion`](/docs/zh-TW/settings-reference#requiredmaximumversion)1457 * `"version_below_minimum"`：此版本的 Claude Code 低於 [`requiredMinimumVersion`](/docs/zh-TW/settings-reference#requiredminimumversion) 或高於 [`requiredMaximumVersion`](/docs/zh-TW/settings-reference#requiredmaximumversion)

1452 * `"_OTHER"`：Claude 應用程式閘道管理設定載入因另一個原因失敗1458 * `"_OTHER"`：Claude apps 閘道的受管設定載入因其他原因失敗

1453* `managed_settings.sources`：每個傳遞至少一個[原則鍵](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)的管理來源，優先級最高優先，包括其鍵在 `first-wins` 下不生效的來源。值為 `"remote"`、`"plist"` 或 `"hklm"` 用於 MDM 或 OS 級原則、`"file"` 用於管理設定檔案和放置、`"parent"` 當[嵌入主機](/docs/zh-TW/managed-settings#let-an-embedding-host-add-policy)提供設定時，以及 `"hkcu"` 用於 [Windows HKCU 登錄值](/docs/zh-TW/managed-settings#where-each-mechanism-stores-the-policy)當 Claude Code [讀取它](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)時。僅攜帶控制鍵或 Claude Code 無法讀取的來源不列出。作為字串陣列發出，當沒有管理來源傳遞原則鍵時為空1459* `managed_settings.sources`：所有提供至少一個[政策鍵](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)的受管來源，依優先順序由高至低排列，包括在 `first-wins` 下其鍵未生效的來源。值包括：MDM 或作業系統層級政策的 `"remote"`、`"plist"` 或 `"hklm"`，受管設定檔與附加檔案的 `"file"`，[嵌入主機](/docs/zh-TW/managed-settings#let-an-embedding-host-add-policy)提供設定時的 `"parent"`，以及 Claude Code [讀取](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)[Windows HKCU 登錄值](/docs/zh-TW/managed-settings#where-each-mechanism-stores-the-policy)時的 `"hkcu"`。僅包含控制鍵的來源，或 Claude Code 無法讀取的來源，不會列出。以字串陣列發出，若沒有任何受管來源提供政策鍵則為空陣列

1454* `managed_settings.source_behavior`：Claude Code 讀取的 [`managedSourcesBehavior`](/docs/zh-TW/settings-reference#managedsourcesbehavior) 值，`"first-wins"` 或 `"merge"`。當沒有來源設定鍵時為 `"first-wins"`1460* `managed_settings.source_behavior`：Claude Code 讀取到的 [`managedSourcesBehavior`](/docs/zh-TW/settings-reference#managedsourcesbehavior) 值，為 `"first-wins"` 或 `"merge"`。沒有任何來源設定此鍵時為 `"first-wins"`

1455* `managed_settings.helper.state`：所選 MDM 或檔案來源配置的原則協助程式的狀態：1461* `managed_settings.helper.state`：所選 MDM 或檔案來源所設定之政策輔助程式的狀態：

1456 * `"ok"`：協助程式的輸出用作管理設定1462 * `"ok"`：輔助程式的輸出作為受管設定使用

1457 * `"bad_path"`、`"not_a_file"`、`"exit_nonzero"`、`"timed_out"`、`"oversize"`、`"parse_failed"`、`"envelope_invalid"` 或 `"schema_rejected"`：協助程式的最後一次執行失敗。[協助程式失敗](/docs/zh-TW/settings-reference#helper-failures)描述案例1463 * `"bad_path"`、`"not_a_file"`、`"exit_nonzero"`、`"timed_out"`、`"oversize"`、`"parse_failed"`、`"envelope_invalid"` 或 `"schema_rejected"`：輔助程式最近一次執行失敗。[輔助程式失敗](/docs/zh-TW/settings-reference#helper-failures)說明了各種情況

1458 * `"none"`：未配置協助程式，或配置它的來源不是 MDM 原則或管理設定檔案1464 * `"none"`：未設定輔助程式，或設定它的來源不是 MDM 政策或受管設定檔

1459* `managed_settings.helper.applied`：當協助程式自己的輸出用作管理設定時為 `"output"`，當它不時為 `"none"`1465* `managed_settings.helper.applied`：當輔助程式本身的輸出作為受管設定使用時為 `"output"`，否則為 `"none"`

1460* `managed_settings.helper.entry`：當 Claude Code 選擇 [`policyHelper`](/docs/zh-TW/settings-reference#policyhelper) 時為 `"policyHelper"`。當它選擇沒有協助程式時不存在1466* `managed_settings.helper.entry`：Claude Code 選取了 [`policyHelper`](/docs/zh-TW/settings-reference#policyhelper) 時為 `"policyHelper"`。未選取任何輔助程式時不會出現

1461* `managed_settings.helper.path`：協助程式的配置 [`path`](/docs/zh-TW/settings-reference#policyhelper-path)。每當 Claude Code 選擇協助程式時存在，無論 `OTEL_LOG_MANAGED_SETTINGS` 是否設定1467* `managed_settings.helper.path`：輔助程式所設定的 [`path`](/docs/zh-TW/settings-reference#policyhelper-path)。只要 Claude Code 選取了輔助程式就會出現，無論是否設定 `OTEL_LOG_MANAGED_SETTINGS`

1462* `managed_settings.resolved_sha256`（當 `OTEL_LOG_MANAGED_SETTINGS=1` 時）：編輯前解析的管理設定的 SHA-256，序列化為 JSON，鍵遞迴排序且無空白。具有相同摘要的機器執行相同的原則。Claude Code 僅使用選擇發送摘要，因為短原則可以通過雜湊猜測恢復。當沒有管理設定解析時不存在，以及在 `refused` 事件上不存在1468* `managed_settings.resolved_sha256`（當 `OTEL_LOG_MANAGED_SETTINGS=1` 時）：遮蔽前已解析受管設定的 SHA-256，以遞迴排序鍵且不含空白的 JSON 序列化後計算。摘要相同的電腦執行相同的政策。Claude Code 僅在選擇啟用時才傳送摘要，因為較短的政策可以透過雜湊猜測值而被還原。沒有解析任何受管設定時不會出現，在 `refused` 事件上也不會出現

1463* `managed_settings.settings`（當 `OTEL_LOG_MANAGED_SETTINGS=1` 時）：解析的管理設定的名稱和形狀作為 JSON 字串，值編輯。在 `refused` 事件上不存在。Claude Code 從其設定架構構建它：1469* `managed_settings.settings`（當 `OTEL_LOG_MANAGED_SETTINGS=1` 時）：已解析受管設定的名稱與結構，以 JSON 字串表示，值經過遮蔽。在 `refused` 事件上不會出現。Claude Code 依據其設定 schema 建置此值：

~~1464~~ 1470

1465 * 架構宣告的設定名稱被匯出，它不宣告的鍵被遺漏1471 * schema 宣告的設定名稱會被匯出，schema 未宣告的鍵則會被省略

1466 * 布林值、數字和架構限制為固定選項集的字串值，例如 `permissions.defaultMode`，按原樣匯出。`sandbox.network.httpProxyPort` 和 `sandbox.network.socksProxyPort` 匯出為 `"[REDACTED]"`1472 * Boolean、數字，以及 schema 限制為固定選項集合的字串值（例如 `permissions.defaultMode`）會原樣匯出。`sandbox.network.httpProxyPort` 與 `sandbox.network.socksProxyPort` 會匯出為 `"[REDACTED]"`

1467 * 每個其他字串，例如 `model`、`apiKeyHelper`、每個 `env` 值、每個 URL 和每個命令，匯出為 `"[REDACTED]"`1473 * 其他所有字串，例如 `model`、`apiKeyHelper`、每個 `env` 值、每個 URL 與每個命令，都會匯出為 `"[REDACTED]"`

1468 * 地圖的項目名稱，例如 `env` 變數名稱和外掛程式 ID，按原樣匯出。架構不鍵入其項目的設定，例如 `vimInsertModeRemaps`，匯出為單個 `"[REDACTED]"`，`sandbox.ignoreViolations` 匯出為其路徑列表的列表，不含命令模式1474 * 對應表的項目名稱，例如 `env` 變數名稱與外掛 ID，會原樣匯出。schema 未定義其項目類型的設定（例如 `vimInsertModeRemaps`）會匯出為單一的 `"[REDACTED]"`，而 `sandbox.ignoreViolations` 會匯出為其路徑清單的清單，不含命令模式

1469 * 列表保留其長度，每個項目按相同規則編輯1475 * 清單會保留其長度，每個項目依相同規則遮蔽

1470 * `permissions.allow`、`permissions.deny` 或 `permissions.ask` 規則匯出為其工具名稱，內容編輯，例如 `Read([REDACTED])`，當工具內建於此版本的 Claude Code 或是 `mcp__` 參考（例如 `mcp__jira__create_issue`）時。任何其他規則匯出為 `"[REDACTED]"`1476 * 當工具內建於此版本的 Claude Code，或為 `mcp__` 參照（例如 `mcp__jira__create_issue`）時，`permissions.allow`、`permissions.deny` 或 `permissions.ask` 規則會匯出為其工具名稱並遮蔽內容，例如 `Read([REDACTED])`。其他任何規則都會匯出為 `"[REDACTED]"`

1471 * 鉤子遵循相同規則，因此固定選項和數字欄位（例如 `type` 和 `timeout`）顯示，而每個命令、URL、`matcher` 和 `if` 條件匯出為 `"[REDACTED]"`1477 * hook 遵循相同規則，因此固定選項與數值欄位（例如 `type` 與 `timeout`）會顯示，而每個命令、URL、`matcher` 與 `if` 條件都會匯出為 `"[REDACTED]"`

~~1472~~ 1478

1473 例如，具有 `apiKeyHelper`、兩個 `env` 變數和拒絕規則的管理設定匯出為 `{"apiKeyHelper":"[REDACTED]","env":{"HTTPS_PROXY":"[REDACTED]","CLAUDE_CODE_ENABLE_TELEMETRY":"[REDACTED]"},"permissions":{"deny":["Read([REDACTED])"]}}`.1479 例如，包含 `apiKeyHelper`、兩個 `env` 變數與一條拒絕規則的受管設定會匯出為 `{"apiKeyHelper":"[REDACTED]","env":{"HTTPS_PROXY":"[REDACTED]","CLAUDE_CODE_ENABLE_TELEMETRY":"[REDACTED]"},"permissions":{"deny":["Read([REDACTED])"]}}`。

~~1474~~ 1480

1475 Claude Code 在 8 KB UTF-8 處切割值，切割值不是有效的 JSON1481 Claude Code 會在 UTF-8 編碼 8 KB 處截斷此值，截斷後的值不是有效的 JSON

1476* `managed_settings.settings_truncated`（當 `managed_settings.settings` 存在時）：當 Claude Code 在 8 KB 處截斷 `managed_settings.settings` 時為 `true`，否則為 `false`。以布林值而非字串發出1482* `managed_settings.settings_truncated`（當 `managed_settings.settings` 存在時）：Claude Code 在 8 KB 處截斷 `managed_settings.settings` 時為 `true`，否則為 `false`。以 Boolean 而非字串發出

1477 1483

1478<h2 id="interpret-metrics-and-events-data">1484<h2 id="interpret-metrics-and-events-data">

1479 解釋指標和事件資料1485 解釋指標和事件資料

1528 1534

1529Claude Code 在內部重試失敗的 API 請求，並僅在放棄後才發出單個 `claude_code.api_error` 事件，因此事件本身是該請求的終端訊號。中間重試嘗試不會作為單獨的事件記錄。1535Claude Code 在內部重試失敗的 API 請求，並僅在放棄後才發出單個 `claude_code.api_error` 事件，因此事件本身是該請求的終端訊號。中間重試嘗試不會作為單獨的事件記錄。

1530 1536

1531事件上的 `attempt` 屬性記錄進行的嘗試總次數。`CLAUDE_CODE_MAX_RETRIES` 預設為 10，上限為 15。在 v2.1.199 或更新版本上，您可以設定 `CLAUDE_CODE_RETRY_WATCHDOG` 以提高預設值並移除上限。1537事件上的 `attempt` 屬性記錄嘗試次數。`CLAUDE_CODE_MAX_RETRIES` 預設為 10，上限為 15。在 v2.1.199 或更新版本上，您可以設定 `CLAUDE_CODE_RETRY_WATCHDOG` 以提高預設值並移除上限。

1538

1539當請求在暫時性錯誤上耗盡所有重試時，`attempt` 最多為該有效限制加一：預設為 11。

1532 1540

1533當請求在暫時性錯誤上耗盡所有重試時，`attempt` 等於該有效限制加一：預設為 11，除非設定了看門狗，否則永遠不超過 16。較低的值表示不可重試的錯誤，例如 `400` 回應，或具有自己較小重試預算的原因。例如，Claude Code 最多重試兩次載入 AWS 或 Google Cloud 認證的失敗。1541較低的值仍可能表示重試已用盡：每次 Claude Code 在串流失敗後重新發出請求時，`attempt` 都會從 `1` 重新開始計算。

1534 1542

1535若要區分從一個恢復的工作階段與停滯的工作階段，請按 `session.id` 分組事件，並檢查錯誤後是否存在更晚的 `api_request` 事件。1543若要區分從一個恢復的工作階段與停滯的工作階段，請按 `session.id` 分組事件，並檢查錯誤後是否存在更晚的 `api_request` 事件。

1536 1544

1699 1707

1700您選擇的指標、日誌和追蹤後端決定了您可以執行的分析類型：1708您選擇的指標、日誌和追蹤後端決定了您可以執行的分析類型：

1701 1709

1702<h3 id="for-metrics">1710<span id="for-metrics" />

1703 對於指標1711

1712<h3 id="backends-for-metrics">

1713 指標後端

1704</h3>1714</h3>

1705 1715

1706* **時間序列資料庫**：速率計算、聚合指標1716* **時間序列資料庫**：速率計算、聚合指標

1707* **欄式存儲**：複雜查詢、唯一使用者分析1717* **欄式存儲**：複雜查詢、唯一使用者分析

1708* **功能完整的可觀測性平台**：進階查詢、視覺化、警報1718* **功能完整的可觀測性平台**：進階查詢、視覺化、警報

1709 1719

1710<h3 id="for-events/logs">1720<span id="for-events/logs" />

1711 對於事件/日誌1721

1722<h3 id="backends-for-events-and-logs">

1723 事件和日誌後端

1712</h3>1724</h3>

1713 1725

1714* **日誌聚合系統**：全文搜尋、日誌分析1726* **日誌聚合系統**：全文搜尋、日誌分析

1715* **欄式存儲**：結構化事件分析1727* **欄式存儲**：結構化事件分析

1716* **功能完整的可觀測性平台**：指標和事件之間的關聯1728* **功能完整的可觀測性平台**：指標和事件之間的關聯

1717 1729

1718<h3 id="for-traces">1730<span id="for-traces" />

1719 對於追蹤1731

1732<h3 id="backends-for-traces">

1733 追蹤後端

1720</h3>1734</h3>

1721 1735

1722選擇支援分散式追蹤儲存和跨度關聯的後端：1736選擇支援分散式追蹤儲存和跨度關聯的後端：

overview.md +5 −5

Details

24 <Tab title="原生安裝（建議）">24 <Tab title="原生安裝（建議）">

25 **macOS、Linux、WSL：**25 **macOS、Linux、WSL：**

26 26

27 ```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}27 ```bash theme={null}

28 curl -fsSL https://claude.ai/install.sh | bash28 curl -fsSL https://claude.ai/install.sh | bash

29 ```29 ```

30 30

32 32

33 **Windows PowerShell：**33 **Windows PowerShell：**

34 34

35 ```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}35 ```powershell theme={null}

36 irm https://claude.ai/install.ps1 | iex36 irm https://claude.ai/install.ps1 | iex

37 ```37 ```

38 38

39 **Windows CMD：**39 **Windows CMD：**

40 40

41 ```batch theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}41 ```batch theme={null}

42 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd42 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

43 ```43 ```

44 44

56 </Tab>56 </Tab>

57 57

58 <Tab title="Homebrew">58 <Tab title="Homebrew">

59 ```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}59 ```bash theme={null}

60 brew install --cask claude-code60 brew install --cask claude-code

61 ```61 ```

62 62

68 </Tab>68 </Tab>

69 69

70 <Tab title="WinGet">70 <Tab title="WinGet">

71 ```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}71 ```powershell theme={null}

72 winget install Anthropic.ClaudeCode72 winget install Anthropic.ClaudeCode

73 ```73 ```

74 74

plugins/cli-reference.md +1 −0

Details

91| `-y, --yes` | 接受顯示的安裝命令，無需 `Run this command now?` 提示。當命令在 Claude Code 工作階段內執行時（例如從 Bash 工具或 hook）被忽略。需要 Claude Code v2.1.229 或更新版本 |91| `-y, --yes` | 接受顯示的安裝命令，無需 `Run this command now?` 提示。當命令在 Claude Code 工作階段內執行時（例如從 Bash 工具或 hook）被忽略。需要 Claude Code v2.1.229 或更新版本 |

92| `--accept-command <sha256>` | 接受顯示的安裝命令，其 `sha256` 先前的 [`--json` 執行](#plugin-json-result) 在 `shownCommand` 中報告，代替 `-y`。無法與 `-y` 結合。請參閱 [接受顯示的安裝命令](#accept-a-displayed-install-command)。需要 Claude Code v2.1.271 或更新版本 |92| `--accept-command <sha256>` | 接受顯示的安裝命令，其 `sha256` 先前的 [`--json` 執行](#plugin-json-result) 在 `shownCommand` 中報告，代替 `-y`。無法與 `-y` 結合。請參閱 [接受顯示的安裝命令](#accept-a-displayed-install-command)。需要 Claude Code v2.1.271 或更新版本 |

93| `--json` | 將結果列印為 stdout 最後一行的一個 JSON 物件，而不是人類可讀的訊息，供指令碼使用。請參閱 [JSON 結果格式](#plugin-json-result)。需要 Claude Code v2.1.268 或更新版本 |93| `--json` | 將結果列印為 stdout 最後一行的一個 JSON 物件，而不是人類可讀的訊息，供指令碼使用。請參閱 [JSON 結果格式](#plugin-json-result)。需要 Claude Code v2.1.268 或更新版本 |

94| `--marketplace <source>` | 從位於 `<source>` 的市集安裝以裸名稱給出的 `<plugin>`，如果您尚未新增該市集，會先新增它。請參閱 [在一個命令中新增市集並安裝](/docs/zh-TW/plugins/install#add-a-marketplace-and-install-in-one-command)。需要 Claude Code v2.1.292 或更新版本 |

94 95

95在您的 shell 中執行 `claude plugin install --help`，查看您的版本支援的每個選項。96在您的 shell 中執行 `claude plugin install --help`，查看您的版本支援的每個選項。

96 97

plugins/create.md +13 −7

Details

185 185

186您可以通過三種方式為單個工作階段載入外掛程式：使用 `--plugin-dir` 從磁碟上的目錄或 `.zip` 存檔，使用 `--plugin-url` 從 URL，或從環境變數（當您無法添加旗標時）。每個外掛程式只為該工作階段載入，沒有任何內容寫入您的設定。當您在工作階段期間編輯外掛程式的檔案時，執行 `/reload-plugins` 以載入變更。186您可以通過三種方式為單個工作階段載入外掛程式：使用 `--plugin-dir` 從磁碟上的目錄或 `.zip` 存檔，使用 `--plugin-url` 從 URL，或從環境變數（當您無法添加旗標時）。每個外掛程式只為該工作階段載入，沒有任何內容寫入您的設定。當您在工作階段期間編輯外掛程式的檔案時，執行 `/reload-plugins` 以載入變更。

187 187

188<h4 id="from-a-directory-or-zip">188<span id="from-a-directory-or-zip" />

189 從目錄或 `.zip`189

190<h4 id="load-a-plugin-from-a-directory-or-zip">

191 從目錄或 `.zip` 載入外掛程式

190</h4>192</h4>

191 193

192當您從 shell 啟動 `claude` 時，使用外掛程式的根目錄或其 `.zip` 存檔傳遞 `--plugin-dir`。重複該旗標以載入多個外掛程式：194當您從 shell 啟動 `claude` 時，使用外掛程式的根目錄或其 `.zip` 存檔傳遞 `--plugin-dir`。重複該旗標以載入多個外掛程式：

196```198```

197 199

198<h4 id="load-a-folder-of-plugins">200<h4 id="load-a-folder-of-plugins">

199 從外掛程式資料夾201 載入外掛程式資料夾

200</h4>202</h4>

201 203

202若要從一個地方載入多個外掛程式，請傳遞一個保存它們的資料夾，例如 `--plugin-dir ./plugins`。載入外掛程式資料夾需要 Claude Code v2.1.265 或更新版本。204若要從一個地方載入多個外掛程式，請傳遞一個保存它們的資料夾，例如 `--plugin-dir ./plugins`。載入外掛程式資料夾需要 Claude Code v2.1.265 或更新版本。

212 214

213對於這些變更中的每一個，工作階段中都會出現一條訊息。如果在對話中途載入或卸載外掛程式會[使提示快取失效](/docs/zh-TW/prompt-caching#enabling-or-disabling-a-plugin)，則該變更會被保留，訊息會告訴您執行 `/reload-plugins` 以應用它。215對於這些變更中的每一個，工作階段中都會出現一條訊息。如果在對話中途載入或卸載外掛程式會[使提示快取失效](/docs/zh-TW/prompt-caching#enabling-or-disabling-a-plugin)，則該變更會被保留，訊息會告訴您執行 `/reload-plugins` 以應用它。

214 216

215<h4 id="fetch-an-archive-from-a-url-for-one-session">217<span id="fetch-an-archive-from-a-url-for-one-session" />

216 從 URL218

219<h4 id="load-a-plugin-from-a-url">

220 從 URL 載入外掛程式

217</h4>221</h4>

218 222

219當您從 shell 啟動 `claude` 時，使用 `.zip` 存檔的位址傳遞 `--plugin-url`，例如您的 CI 發佈的組建成品：223當您從 shell 啟動 `claude` 時，使用 `.zip` 存檔的位址傳遞 `--plugin-url`，例如您的 CI 發佈的組建成品：

228 232

229如果 Claude Code 無法擷取存檔或存檔無效，它會在沒有外掛程式的情況下啟動，並記錄一個外掛程式載入錯誤，您可以在 `/plugin` 管理器的**錯誤**標籤中查看。233如果 Claude Code 無法擷取存檔或存檔無效，它會在沒有外掛程式的情況下啟動，並記錄一個外掛程式載入錯誤，您可以在 `/plugin` 管理器的**錯誤**標籤中查看。

230 234

231<h4 id="from-an-environment-variable">235<span id="from-an-environment-variable" />

232 從環境變數236

237<h4 id="load-plugins-from-an-environment-variable">

238 從環境變數載入外掛程式

233</h4>239</h4>

234 240

235若要在無法添加 `--plugin-dir` 旗標的工作階段中載入外掛程式，請改為在 [`CLAUDE_CODE_PLUGIN_DIRS`](/docs/zh-TW/env-vars#variables) 環境變數中列出它們的絕對路徑。Claude Code 會像載入 `--plugin-dir` 路徑一樣載入每個路徑。這些外掛程式會添加到您使用 `--plugin-dir` 傳遞的任何外掛程式中。[專案和本機設定無法設定此變數](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)。`CLAUDE_CODE_PLUGIN_DIRS` 需要 Claude Code v2.1.280 或更新版本。241若要在無法添加 `--plugin-dir` 旗標的工作階段中載入外掛程式，請改為在 [`CLAUDE_CODE_PLUGIN_DIRS`](/docs/zh-TW/env-vars#variables) 環境變數中列出它們的絕對路徑。Claude Code 會像載入 `--plugin-dir` 路徑一樣載入每個路徑。這些外掛程式會添加到您使用 `--plugin-dir` 傳遞的任何外掛程式中。[專案和本機設定無法設定此變數](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)。`CLAUDE_CODE_PLUGIN_DIRS` 需要 Claude Code v2.1.280 或更新版本。

plugins/host-marketplace.md +8 −2

Details

413 How users accept a headersHelper command413 How users accept a headersHelper command

414</h3>414</h3>

415 415

416使用者在每次自己安裝或更新該一個 plugin 時接受 plugin 項目的命令。他們從 `/plugin` 中的 plugin 自己的檢視執行此操作，或使用 `claude plugin install` 或 `claude plugin update`。Claude Code 顯示命令和存檔 URL，並只在使用者接受後執行命令。416使用者在每次自己單獨安裝或更新該一個 plugin 時接受 plugin 項目的命令。Claude Code 顯示命令和存檔 URL，並只在使用者接受後執行命令。

417

418使用者可以在終端機中的 Claude Code 工作階段內、在未執行任何工作階段的 shell 中，或在 VS Code 擴充功能中安裝或更新 plugin：

419

420* **終端機工作階段**：從 `/plugin` 中的 plugin 自己的檢視。

421* **Shell**：使用 `claude plugin install` 或 `claude plugin update`。

422* **VS Code 擴充功能**：從 [**Manage plugins** 對話框](/docs/zh-TW/vs-code#manage-plugins)，需使用擴充功能 2.1.290 或更新版本。

417 423

418在非互動式 shell 中，傳遞 [`--yes`](/docs/zh-TW/plugins/cli-reference#plugin-install) 以接受命令。若要接受只有先前 `--json` 執行顯示的命令，傳遞 [`--accept-command`](/docs/zh-TW/plugins/cli-reference#plugin-install) 與執行報告的 `sha256`。424在非互動式 shell 中，傳遞 [`--yes`](/docs/zh-TW/plugins/cli-reference#plugin-install) 以接受命令。若要接受只有先前 `--json` 執行顯示的命令，傳遞 [`--accept-command`](/docs/zh-TW/plugins/cli-reference#plugin-install) 與執行報告的 `sha256`。

419 425

420Claude Code 只執行它顯示的命令，用於它顯示的存檔 URL。如果項目的命令或存檔 URL 在之間變更，Claude Code 拒絕安裝或更新。查詢字串中的變更單獨不計。426Claude Code 只執行它顯示的命令，用於它顯示的存檔 URL。如果項目的命令或存檔 URL 在這之間變更，Claude Code 拒絕安裝或更新。僅查詢字串中的變更不計，但在 VS Code 擴充功能中或使用 `--accept-command` 時除外。

421 427

422<h3 id="installs-and-updates-that-refuse-the-command-instead-of-asking">428<h3 id="installs-and-updates-that-refuse-the-command-instead-of-asking">

423 Installs and updates that refuse a command instead of asking429 Installs and updates that refuse a command instead of asking

plugins/install.md +22 −4

Details

189 189

190* **Scope**：預設為使用者範圍。傳遞 `--scope project` 或 `--scope local` 以變更它。190* **Scope**：預設為使用者範圍。傳遞 `--scope project` 或 `--scope local` 以變更它。

191* **When the plugins load**：它安裝的外掛程式在您下次啟動 Claude Code 時載入，或當您在已開啟的工作階段中執行 `/reload-plugins` 時載入。191* **When the plugins load**：它安裝的外掛程式在您下次啟動 Claude Code 時載入，或當您在已開啟的工作階段中執行 `/reload-plugins` 時載入。

192* **The marketplace must be added first**：在沒有人開啟互動式 Claude Code 工作階段的機器上，官方市集未註冊，因此從它安裝的指令碼在安裝前執行 `claude plugin marketplace add anthropics/claude-plugins-official`。192* **The marketplace on a new machine**：在尚未有人開啟互動式 Claude Code 工作階段的機器上，官方市集未註冊，因此從它安裝的指令碼在安裝前執行 `claude plugin marketplace add anthropics/claude-plugins-official`。請參閱 [從您的 shell 新增和安裝](#add-and-install-from-your-shell)。

193 193

194```bash theme={null}194```bash theme={null}

195claude plugin install formatter@your-org --scope project195claude plugin install formatter@your-org --scope project

232 新增市集並在一個命令中安裝232 新增市集並在一個命令中安裝

233</h3>233</h3>

234 234

235若要從您尚未新增的市集安裝外掛程式，請在 Claude Code 工作階段中執行 `/plugin install` 並使用 `--marketplace` 命名市集來源。需要 Claude Code v2.1.275 或更新版本。235若要從您尚未新增的市集安裝外掛程式，請在安裝命令上使用 `--marketplace` 命名市集來源，可在工作階段中或從 shell 執行。來源採用 [與 `/plugin marketplace add` 相同的形式](#add-a-marketplace)，例如 GitHub `owner/repo`、git URL 或本機路徑。單獨給出外掛程式名稱，不帶 `@marketplace` 後綴。

236

237<h4 id="add-and-install-in-a-session">

238 在工作階段中新增並安裝

239</h4>

240

241在 Claude Code 工作階段中執行 `/plugin install`，並提供外掛程式和來源。需要 Claude Code v2.1.275 或更新版本。在工作階段中，來源不能包含空格。

236 242

237```text theme={null}243```text theme={null}

238/plugin install deploy-helper --marketplace your-org/plugins244/plugin install deploy-helper --marketplace your-org/plugins

239```245```

240 246

241來源採用 [與 `/plugin marketplace add` 相同的形式](#add-a-marketplace)，例如 GitHub `owner/repo`、git URL 或本機路徑，除了它不能包含空格。單獨給出外掛程式名稱，不帶 `@marketplace` 後綴。

~~242~~

243如果您尚未新增該市集，Claude Code 會顯示它解析的來源並要求您在新增前確認。市集新增後，外掛程式的詳細資訊開啟，您選擇 [安裝範圍](#install-a-plugin)。如果來源與您已新增的市集相符，Claude Code 會跳過確認並在該市集中開啟外掛程式的詳細資訊。247如果您尚未新增該市集，Claude Code 會顯示它解析的來源並要求您在新增前確認。市集新增後，外掛程式的詳細資訊開啟，您選擇 [安裝範圍](#install-a-plugin)。如果來源與您已新增的市集相符，Claude Code 會跳過確認並在該市集中開啟外掛程式的詳細資訊。

244 248

249<h4 id="add-and-install-from-your-shell">

250 從 shell 新增並安裝

251</h4>

252

253在 shell 中，無需啟動工作階段，執行 `claude plugin install` 並提供外掛程式和來源。需要 Claude Code v2.1.292 或更新版本。

254

255```bash theme={null}

256claude plugin install deploy-helper --marketplace your-org/plugins

257```

258

259shell 命令會新增市集而不經過確認步驟。您已從該來源新增的市集會被重複使用。新的市集會在與 `claude plugin marketplace add` 相同的 [組織政策檢查](/docs/zh-TW/plugins/org#restrict-what-users-can-install) 下新增，並且即使您傳遞 `--scope project`，也會宣告在您的使用者設定中。

260

261如果您尚未新增該市集，命令會列印 `Successfully added marketplace: <name> (declared in user settings)`，然後 [安裝外掛程式](#install-from-your-shell)。

262

245<h3 id="add-a-private-marketplace">263<h3 id="add-a-private-marketplace">

246 新增私人市集264 新增私人市集

247</h3>265</h3>

plugins/manifest-reference.md +1 −1

Details

185| 將 `official` 放在 `claude` 或 `anthropic` 旁邊，例如 `official-claude-tools` | 錯誤 |185| 將 `official` 放在 `claude` 或 `anthropic` 旁邊，例如 `official-claude-tools` | 錯誤 |

186| 在其他地方將 `claude`、`anthropic` 或 `anthropics` 作為整個單詞，例如 `mcp-for-claude` | 警告 |186| 在其他地方將 `claude`、`anthropic` 或 `anthropics` 作為整個單詞，例如 `mcp-for-claude` | 警告 |

187 187

188錯誤讀作 `Plugin name "<name>" is reserved: it passes as one of Anthropic's own`，警告讀作 `Plugin name "<name>" reads as one of Anthropic's own`。`claude plugin init` 和 `claude plugin tag` 拒絕繪製錯誤的名稱。只有這些命令檢查名稱。Claude Code 仍會安裝並載入它們拒絕的名稱的 plugin。188錯誤讀作 `Plugin name "<name>" is reserved: it passes as one of Anthropic's own`，警告讀作 `Plugin name "<name>" reads as one of Anthropic's own`。`claude plugin init` 和 `claude plugin tag` 會拒絕引發該錯誤的名稱。Claude Code 仍會安裝並載入名稱遭它們拒絕的 plugin。

189 189

190<h3 id="displayname">190<h3 id="displayname">

191 `displayName`191 `displayName`

plugins/marketplace-reference.md +1 −1

Details

64 64

65| 欄位 | 類型 | 描述 |65| 欄位 | 類型 | 描述 |

66| :- | :- | :- |66| :- | :- | :- |

67| `name` | 字串 | Marketplace 識別碼：字母、數字、`.`、`_` 和 `-`，以字母或數字開頭，且不得包含 `..`。`claude plugin validate` 會讓任何其他名稱驗證失敗，因為 Claude Code 無法從使用此類名稱的市集安裝外掛。使用者安裝外掛時，會在 [plugin id](/docs/zh-TW/plugins/loading#find-where-a-plugin-came-from)（例如 `my-plugin@my-marketplace`）中的 `@` 後面輸入此名稱。請參閱 [Reserved names](#reserved-names) |67| `name` | 字串 | Marketplace 識別碼：字母、數字、`.`、`_` 和 `-`，以字母或數字開頭，且不得包含 `..`。`claude plugin validate` 會讓任何其他名稱驗證失敗，因為 Claude Code [無法從使用此類名稱的市集安裝外掛](/docs/zh-TW/plugins/troubleshooting#cannot-install-plugins-from-a-marketplace-with-this-name)。使用者安裝外掛時，會在 [plugin id](/docs/zh-TW/plugins/loading#find-where-a-plugin-came-from)（例如 `my-plugin@my-marketplace`）中的 `@` 後面輸入此名稱。請參閱 [Reserved names](#reserved-names) |

68| `owner` | 物件 | 維護者資訊。`name` 是必需的；`email` 和 `url` 是可選的 |68| `owner` | 物件 | 維護者資訊。`name` 是必需的；`email` 和 `url` 是可選的 |

69| `plugins` | 陣列 | [Plugin entries](#plugin-entries)。每個項目都單獨驗證，因此一個無效項目不會導致 marketplace 失敗 |69| `plugins` | 陣列 | [Plugin entries](#plugin-entries)。每個項目都單獨驗證，因此一個無效項目不會導致 marketplace 失敗 |

70| `$schema` | 字串 | JSON Schema URL 用於編輯器自動完成。在載入時忽略 |70| `$schema` | 字串 | JSON Schema URL 用於編輯器自動完成。在載入時忽略 |

plugins/mods/admin.md +1 −1

Details

142 142

143在 `hooks:` 行中，[`tool.call`](/docs/zh-TW/plugins/mods/reference#tools) 和 [`prompt.submit`](/docs/zh-TW/plugins/mods/reference#prompts-and-what-claude-reads) 表示 mod 看到每個工具呼叫和每個提示，並可以更改它們。[`session.append`](/docs/zh-TW/plugins/mods/reference#session) 表示 mod 可以在儲存前重寫對話的每一行。[`ui.render{component=AskUserQuestion}`](/docs/zh-TW/plugins/mods/interface#change-what-claude-code-already-draws) 表示 mod 可以重繪 Claude 用來詢問使用者問題的對話框。`tool.check` 表示 mod 可以在權限提示出現之前批准或拒絕工具呼叫。[了解預設情況下會發生什麼](#know-what-happens-by-default)列出您的哪些規則和 hooks 優先於其答案。143在 `hooks:` 行中，[`tool.call`](/docs/zh-TW/plugins/mods/reference#tools) 和 [`prompt.submit`](/docs/zh-TW/plugins/mods/reference#prompts-and-what-claude-reads) 表示 mod 看到每個工具呼叫和每個提示，並可以更改它們。[`session.append`](/docs/zh-TW/plugins/mods/reference#session) 表示 mod 可以在儲存前重寫對話的每一行。[`ui.render{component=AskUserQuestion}`](/docs/zh-TW/plugins/mods/interface#change-what-claude-code-already-draws) 表示 mod 可以重繪 Claude 用來詢問使用者問題的對話框。`tool.check` 表示 mod 可以在權限提示出現之前批准或拒絕工具呼叫。[了解預設情況下會發生什麼](#know-what-happens-by-default)列出您的哪些規則和 hooks 優先於其答案。

144 144

plugins/mods/api.md +106 −7

Details

79 呼叫模型79 呼叫模型

80</h2>80</h2>

81 81

82模組可以在對話外提出自己的問題，用於排序或摘要文字等小工作。`$.model.complete` 會使用您的工作階段認證向模型發送一個提示，並解析為回覆。它沒有對話歷史。82mod 可以向模型發送自己的請求，用於分類或摘要文字等小工作。`$.model.complete` 會單獨發送您的提示詞，而 `$.model.fork({ prompt })` 則會發送目前的對話，並將您的提示詞附加在最後。

84下表比較每種請求所包含的內容：

86| 請求中的內容 | `$.model.complete` | `$.model.fork` |

87| :- | :- | :- |

88| 模型 | 您傳入的 `model` | 工作階段的模型 |

89| 系統提示詞 | 一段簡短的[歸屬區塊](/docs/zh-TW/llm-gateway-protocol#system-prompt-attribution-block)，若您有傳入 `system`，則接著是您的 `system` | 工作階段的系統提示詞 |

90| 訊息 | 一則使用者訊息，即您的 `prompt` | 目前為止的對話，接著是作為使用者訊息的您的 `prompt` |

91| CLAUDE.md 及其他專案脈絡 | 不包含 | 包含，與對話最後一次請求相同 |

92| 工具 | 無 | Claude 的工具，但模型無法呼叫 |

94fork 會重複對話的最後一次請求，因此在對話仍在快取中時，Claude API 會從[提示快取](/docs/zh-TW/prompt-caching)提供大部分內容。

96這兩種呼叫都使用工作階段的憑證，因此會計費至使用者的方案、API 金鑰或雲端供應商。[您的建置類型](/docs/zh-TW/plugins/mods/create#get-the-types-for-your-build)記載了每個 `$.model` 方法。

98<h3 id="send-one-prompt">

99 發送單一提示詞

100</h3>

101

102將 `model` 和 `prompt` 傳給 `$.model.complete`。`prompt` 會成為使用者訊息。若要給模型指令，例如角色或輸出格式，請同時傳入 `system`，它會成為系統提示詞。

83 103

84此 hook 透過要求小型模型標記在其後輸入的文字來回答 `/triage` 命令（[註冊為命令](#add-a-command)）：104此 hook 透過要求小型模型標記在其後輸入的文字來回答 `/triage` 命令（[註冊為命令](#add-a-command)）：

85 105

100})120})

101```121```

102 122

103當您執行 `/triage the export button does nothing` 時，模組會將該文字傳送給模型並列印其答案，例如 `Label: bug`。Claude 的對話不是請求的一部分。當模型沒有回答時，標籤為 `unknown`。123當您執行 `/triage the export button does nothing` 時，mod 會將該文字傳送給模型並列印其答案，例如 `Label: bug`。當模型沒有回答時，標籤為 `unknown`。

124

125Claude API 失敗不會拒絕呼叫，因此請檢查 `r.isAnswered`，當其為 `false` 時請讀取 `r.reason`。呼叫會因為 Claude Code 不會傳送的請求而被拒絕，例如您的組織封鎖的模型。

126

127[您的建置類型](/docs/zh-TW/plugins/mods/create#get-the-types-for-your-build)列出其他選項，例如 `effort`，而[限制](/docs/zh-TW/plugins/mods/reference#limits)提供 `maxTokens` 預設值。

128

129<h3 id="use-prompt-caching">

130 使用提示快取

131</h3>

132

133`$.model.complete` 支援 Claude API 的[提示快取](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)。API 會快取請求的開頭部分（稱為前綴），直到您設定的[快取斷點](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#explicit-cache-breakpoints)為止。當每次呼叫都以相同的冗長靜態內容開頭時，例如指令或參考資料，請在該內容的結尾設定斷點。之後的呼叫便會從快取讀取該內容，而不必為其支付完整的輸入費用。

134

135若要設定斷點，請將 `prompt` 以 `{ text }` 區塊陣列的形式傳入，而非字串，並在靜態內容的最後一個區塊加上 `cache: true`。Claude Code 會以 API 的 `cache_control` 欄位發送該區塊。`system` 也接受相同的陣列形式。若要決定使用哪一個，請參閱[在 `prompt` 與 `system` 之間選擇](#choose-between-prompt-and-system)。

136

137<Note>

138 區塊陣列需要 Claude Code v2.1.292 或更新版本。較早的版本會拒絕 `prompt` 中的陣列，並顯示以 `takes { model, prompt } (host check)` 結尾的錯誤，且會將 `system` 中的陣列排除在請求之外。

139</Note>

140

141此版本的 [`/triage` hook](#send-one-prompt) 會在要標記的文字之前發送一長串標記規則，並在規則之後設定斷點。`RULES` 是您自己的字串：

142

143```javascript theme={null}

144on('command.run', { command: 'triage' }, async ($, e) => {

145 const r = await $.model.complete({

146 model: 'haiku',

147 prompt: [

148 // Identical on every call, so it forms the cached prefix

149 { text: RULES, cache: true },

150 // Changes on every call, so it goes after the breakpoint

151 { text: e.args },

152 ],

153 })

154 return { text: 'Label: ' + (r.isAnswered ? r.text.trim() : 'unknown') }

155})

156```

157

158TTL 與斷點數量有以下限制：

159

160* **TTL**：快取項目在最後一次使用後會保留五分鐘。TTL 來自使用者的 Claude Code 設定，而非來自呼叫。若要設為一小時，請將 [`subagentPromptCacheTtl`](/docs/zh-TW/prompt-caching#choose-the-ttl-yourself) 設為 `1h`。

161* **每個請求的斷點數**：API 接受[最多四個](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#when-to-use-multiple-breakpoints)，再多一個則會在 `r.reason` 中以 `api-error` 傳回

162

163<h4 id="choose-between-prompt-and-system">

164 在 `prompt` 與 `system` 之間選擇

165</h4>

166

167除非您確定您的請求會直接送往 Claude API，否則請將呼叫共用的靜態內容放在 `prompt` 的開頭：

168

169* **直接送往 Claude API，使用 API 金鑰或 Claude 訂閱**：兩個欄位皆可

170* **透過 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws)、[Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai)、[Microsoft Foundry](/docs/zh-TW/microsoft-foundry) 或 [LLM 閘道](/docs/zh-TW/llm-gateway)**：請使用 `prompt`。Claude Code 會以一段[歸屬區塊](/docs/zh-TW/llm-gateway-protocol#system-prompt-attribution-block)作為系統提示詞的開頭，其指紋來自使用者訊息的開頭。`api.anthropic.com` 端點會在快取前移除該區塊。其他端點則會將其作為提示詞的一部分接收，因此當 `prompt` 的開頭不同時，`system` 中的斷點可能無法命中。

171* **在其他人執行的 mod 中**：請使用 `prompt`，因為您無法選擇他們的供應商

172

173在前綴中，`system` 位於 `prompt` 之前，因此 `prompt` 中的斷點也會涵蓋 `system`，而使用不同 `system` 的呼叫將無法命中快取。

104 174

105Claude API 失敗不會拒絕呼叫，因此請檢查 `r.isAnswered`，當其為 `false` 時請讀取 `r.reason`。呼叫會因為 Claude Code 不會傳送的請求而被拒絕，例如您的組織封鎖的模型。[您的建置類型](/docs/zh-TW/plugins/mods/create#get-the-types-for-your-build)列出其他選項，例如 `effort`，而[限制](/docs/zh-TW/plugins/mods/reference#limits)提供 `maxTokens` 預設值。175<h4 id="check-for-cache-hits">

176 檢查快取命中

177</h4>

106 178

107`$.model.fork({ prompt })` 改為在目前對話上提出一個問題，使用相同的模型和系統提示，因此 Claude API 會從提示快取中提供大部分內容。179`$.model.complete` 的結果包含一個 `usage` 物件，其中有 API 的[快取欄位](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#tracking-cache-performance)。`usage.cache_creation_input_tokens` 計算呼叫寫入快取的 token 數，而 `usage.cache_read_input_tokens` 計算從快取讀取的 token 數。預期第一次呼叫會寫入，而在 TTL 內的後續呼叫會讀取。

108 180

109這些呼叫使用使用者的方案或 API 金鑰。181如果每次呼叫都寫入而從未讀取，表示各次呼叫的前綴不同，或呼叫之間的間隔超過 TTL。關於前綴不同的情況，請參閱[在 `prompt` 與 `system` 之間選擇](#choose-between-prompt-and-system)。

182

183如果在模型有回答的呼叫中，兩個欄位都維持為零，表示沒有任何內容被快取。請逐一檢查以下原因：

184

185* **前綴太短**：API 不會快取短於模型[最小長度](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#cache-limitations)的前綴，且不會傳回錯誤

186* **提示快取已停用**：當 [`DISABLE_PROMPT_CACHING` 變數](/docs/zh-TW/prompt-caching#disable-prompt-caching)套用於該模型時，Claude Code 會移除斷點，並以未快取的方式發送文字

187* **您的閘道移除了 `cache_control`**：閘道可能會[移除該欄位但仍傳回成功](/docs/zh-TW/prompt-caching#where-the-cache-lives)

188* **另一個 mod 改寫了文字的開頭**：此時 Claude Code 會[在沒有斷點的情況下發送](#what-a-model-complete-hook-receives)

189

190<h3 id="what-a-model-complete-hook-receives">

191 `model.complete` hook 接收的內容

192</h3>

193

194如果您 hook [`model.complete`](/docs/zh-TW/plugins/mods/reference#mods-api-calls) 事件以檢查或變更其他 mod 的請求，請從以下欄位讀取文字：

195

196* **`e.prompt`**：一律為字串。當呼叫者傳入陣列時，它是各區塊文字依序串接的結果。

197* **`e.system`**：以相同方式建構的字串，若呼叫者未傳入 `system` 則不存在

198* **`e.promptBlocks` 和 `e.systemBlocks`**：呼叫者的陣列，各自在呼叫者為該欄位傳入陣列時存在

199

200Claude Code 會發送您的 hook 傳給 `next` 的字串，並使用您一併傳入的陣列來放置[快取斷點](#use-prompt-caching)。它會保留仍與字串開頭相符的前導區塊及其斷點，並在沒有斷點的情況下發送字串的其餘部分。例如，`next({ ...e, prompt: e.prompt + NOTE })` 會保留呼叫者的斷點，而變更 `prompt` 開頭的 hook 則會移除這些斷點。

110 201

111<h2 id="run-work-in-the-background">202<h2 id="run-work-in-the-background">

112 在背景執行工作203 在背景執行工作

140| 呼叫 | 使用者看到的內容 |231| 呼叫 | 使用者看到的內容 |

141| :- | :- |232| :- | :- |

145 236

146<h3 id="start-a-turn-from-a-background-job">237<h3 id="start-a-turn-from-a-background-job">

159 在工作階段之間傳送和接收訊息250 在工作階段之間傳送和接收訊息

160</h2>251</h2>

161 252

162一個 mod 可以向另一個工作階段或此工作階段的子代理傳送純文字訊息，並觀察到達和離開的訊息。`$.session.send({ to, text })` 傳送一個訊息，與 SendMessage 工具進行相同的傳遞。`to` 是工作階段的 `{ sessionId }`、來自 `$.agent.list()` 的子代理的 `{ agentId }`，或接收訊息來自的字串位址。呼叫在訊息排隊後解析，返回 `{ isDelivered: true }`。當沒有任何內容被傳遞時，它會以 `{ isDelivered: false, reason }` 解析，`reason` 說明原因。253mod 可以向您的另一個工作階段、此工作階段的某個 subagent，或其 [agent team](/docs/zh-TW/agent-teams) 中的隊員傳送純文字訊息。它也可以觀察到達和離開的訊息。

254

255若要傳送訊息，請呼叫 `$.session.send({ to, text })`，它會進行與 SendMessage 工具相同的傳遞。依據接收訊息的對象設定 `to`：

256

257* **您的另一個工作階段**：`{ sessionId }`

258* **subagent 或隊員**：`{ agentId }`，使用來自 `$.agent.list()` 的 id

259* **您所收到訊息的寄件者**：該訊息來源的字串位址

260

261呼叫在訊息排入佇列後解析，返回 `{ isDelivered: true }`。當沒有任何內容被傳遞時，它會以 `{ isDelivered: false, reason }` 解析，`reason` 說明原因。

163 262

164此 hook 透過詢問您在其後輸入的 id 的工作階段的狀態，來回答 `/ping` 命令（[註冊為命令](#add-a-command)）：263此 hook 透過詢問您在其後輸入的 id 的工作階段的狀態，來回答 `/ping` 命令（[註冊為命令](#add-a-command)）：

165 264

plugins/mods/create.md +1 −1

Details

281 取得你版本的型別定義281 取得你版本的型別定義

282</h3>282</h3>

283 283

284每次 Claude Code 從你傳遞給 `--plugin-dir` 的目錄載入或重新載入 mod，或 mod [Claude 為你寫的](#ask-claude-for-a-mod)，它將 TypeScript 宣告檔案（以 `.d.ts` 結尾）寫入 mod 目錄內的 `.claude-plugin/types/`。它們描述你執行的 Claude Code 版本中的確切事件、mod API 方法和元素，所以你的編輯器可以自動完成和型別檢查你的 hooks。若要線上瀏覽宣告，請閱讀 Claude Code 儲存庫中的 [`mods/types/claude-code.d.ts`](https://github.com/anthropics/claude-code/blob/main/mods/types/claude-code.d.ts)，其第一行命名寫入它的版本。目錄保留這些檔案：284當 Claude Code 在互動式工作階段中從 `--plugin-dir` 載入 mod，或載入 [Claude 為您撰寫的](#ask-claude-for-a-mod) mod 時，它會將 TypeScript 宣告檔案寫入 mod 的 `.claude-plugin/types/` 目錄。這些檔案描述您所執行的 Claude Code 版本中確切的事件、mods API 方法和元素，讓您的編輯器可以對您的 hook 進行自動完成和型別檢查。該目錄包含以下檔案：

285 285

286| 路徑 | 它宣告的內容 |286| 路徑 | 它宣告的內容 |

287| :- | :- |287| :- | :- |

plugins/mods/events.md +12 −3

Details

145 145

146在 Claude 編輯或寫入 `.mdx` 檔案後，逐字稿中會出現一行淡色文字，標示該檔案名稱。對於其他類型的檔案，或是遭拒絕或失敗的呼叫，則不會記錄任何內容。Claude 對該呼叫的認知不會改變，因為 hook 傳回的是它所收到的結果。146在 Claude 編輯或寫入 `.mdx` 檔案後，逐字稿中會出現一行淡色文字，標示該檔案名稱。對於其他類型的檔案，或是遭拒絕或失敗的呼叫，則不會記錄任何內容。Claude 對該呼叫的認知不會改變，因為 hook 傳回的是它所收到的結果。

147 147

148若要變更呼叫，請將變更後的引數傳給 `next`。若要重試呼叫，請再次呼叫 `next(e)`：在第一個結果上看到 `isError` 的 hook 可以再次執行工具，並傳回該結果。若要自行回應呼叫，請在不呼叫 `next` 的情況下傳回具有 `result` 欄位的物件，例如 `{ result: 'Skipped by my-mod' }`。這樣做時，不會出現權限提示，工具也不會執行，因此您傳回的結果就是 Claude 對所發生事情的全部了解。148您的 hook 也可以變更呼叫、重試呼叫、自行回應呼叫，或隱藏其結果：

149

150* **變更呼叫**：將變更後的引數傳給 `next`。

151* **重試呼叫**：再次呼叫 `next(e)`。在第一個結果上看到 `isError` 的 hook 可以再次執行工具，並傳回該結果。

152* **自行回應呼叫**：在不呼叫 `next` 的情況下傳回具有 `result` 欄位的物件；若為內建工具，請讓 `result` 符合該工具本身的結果在[您建置版本的型別](/docs/zh-TW/plugins/mods/create#get-the-types-for-your-build)中的形狀。不會出現權限提示，工具也不會執行，因此您傳回的結果就是 Claude 對所發生事情的全部了解。

153* **對 Claude 隱藏結果**：在 `await next(e)` 之後傳回 `{ deny: reason }`。Claude 會讀取您的原因，而非 `next` 傳回的內容。當工具已執行時，deny 會讓 Claude 看不到其結果，但不會復原工具所做的任何事。當工具已執行且成功時，原因會接在如 `Bash ran, and a plugin withheld its result:` 之類的註記之後。

149 154

150您組織的[受管設定](/docs/zh-TW/server-managed-settings)中的 hook 會在任何 mod 的 `tool.call` hook 之前執行，且其中任一個所做的封鎖都是最終決定。155您組織的[受管設定](/docs/zh-TW/server-managed-settings)中的 hook 會在任何 mod 的 `tool.call` hook 之前執行，且其中任一個所做的封鎖都是最終決定。

151 156

225 230

226| 若要執行此操作 | 請傳回 |231| 若要執行此操作 | 請傳回 |

227| :- | :- |232| :- | :- |

228| 改寫提示詞。逐字稿中的訊息會顯示新文字。 | `next({ ...e, text: newText })` |233| 改寫提示詞。逐字稿和您的[提示詞歷史記錄](/docs/zh-TW/interactive-mode#command-history)會顯示新文字。 | `next({ ...e, text: newText })` |

229| 在提示詞之後加入只有 Claude 會讀取的文字 | `next({ ...e, context: [...(e.context ?? []), extraText] })` |234| 在提示詞之後加入只有 Claude 會讀取的文字 | `next({ ...e, context: [...(e.context ?? []), extraText] })` |

230| 阻止送出提示詞 | `{ drop: 'the reason' }` |235| 阻止送出提示詞 | `{ drop: 'the reason' }` |

231 236

245 250

246當您送出如 `open a PR for this change` 之類的提示詞時，您的訊息在逐字稿中看起來不變，而 Claude 還會在其後讀到如 `Current branch: feature/auth` 之類的一行。未提及 pull request 的提示詞會原封不動地通過，且不會執行 `git`。251當您送出如 `open a PR for this change` 之類的提示詞時，您的訊息在逐字稿中看起來不變，而 Claude 還會在其後讀到如 `Current branch: feature/auth` 之類的一行。未提及 pull request 的提示詞會原封不動地通過，且不會執行 `git`。

247 252

248若要阻止提示詞，請在不呼叫 `next` 的情況下傳回 `{ drop: 'the reason' }`。如果您的 hook 在其 `next(e)` 呼叫已讓提示詞通過之後才傳回 `drop`，回合仍會執行，且該 hook 會[失敗](#handle-a-hook-that-fails)，並顯示包含 `a drop after its next() was answered` 的訊息。253若要阻止提示詞，請在不呼叫 `next` 的情況下傳回 `{ drop: 'the reason' }`。文字會回到使用者的提示詞輸入欄中，而使用者會看到 `Prompt dropped by a hook:` 後接您的原因，因此請以使用者為對象撰寫原因。如果您的 hook 在其 `next(e)` 呼叫已讓提示詞通過之後才傳回 `drop`，回合仍會執行，且該 hook 會[失敗](#handle-a-hook-that-fails)，並顯示包含 `a drop after its next() was answered` 的訊息。

249 254

250[其他事件](/docs/zh-TW/plugins/mods/reference#prompts-and-what-claude-reads)涵蓋 Claude 讀取的其餘內容：`prompt.section` 用於系統提示詞的每個區段，`prompt.context` 用於隨第一則訊息送出的上下文，而 `skill.prompt` 用於 skill 的文字。來自這些 hook、且在請求之間有所變動的文字，會[使提示快取失效](/docs/zh-TW/prompt-caching)。255[其他事件](/docs/zh-TW/plugins/mods/reference#prompts-and-what-claude-reads)涵蓋 Claude 讀取的其餘內容：`prompt.section` 用於系統提示詞的每個區段，`prompt.context` 用於隨第一則訊息送出的上下文，而 `skill.prompt` 用於 skill 的文字。來自這些 hook、且在請求之間有所變動的文字，會[使提示快取失效](/docs/zh-TW/prompt-caching)。

251 256

281 286

282`result.usage` 保存 Claude API 為請求回報的 token 計數，以及回應的 `model`：`input_tokens`、`output_tokens`、`cache_read_input_tokens` 和 `cache_creation_input_tokens`。此 hook 也會針對 subagent 的請求執行，因此若您只想要主要對話，請檢查 `e.agentId`。287`result.usage` 保存 Claude API 為請求回報的 token 計數，以及回應的 `model`：`input_tokens`、`output_tokens`、`cache_read_input_tokens` 和 `cache_creation_input_tokens`。此 hook 也會針對 subagent 的請求執行，因此若您只想要主要對話，請檢查 `e.agentId`。

283 288

289若要查看 API 在請求期間自行執行的工具呼叫，例如對 [advisor 工具](/docs/zh-TW/advisor)的呼叫，請讀取 `result.serverToolUses`。Claude Code 不會執行這些呼叫，因此不會針對它們觸發任何 `tool.call` 或 `tool.check` hook。當回應中沒有此類呼叫時，該欄位不會存在，且此欄位需要 Claude Code v2.1.290 或更新版本。

290

284<h3 id="hook-the-settings-hook-events">291<h3 id="hook-the-settings-hook-events">

285 處理設定 hook 事件292 處理設定 hook 事件

286</h3>293</h3>

369* **`tool.check`**：傳回 `{ decision: 'deny', reason: 'the reason' }`376* **`tool.check`**：傳回 `{ decision: 'deny', reason: 'the reason' }`

370* **`plugin.register`**：傳回 `{ refuse: 'the reason' }`，如[在檢查失敗時拒絕 mod](/docs/zh-TW/plugins/mods/admin#refuse-mods-when-your-check-fails) 所示377* **`plugin.register`**：傳回 `{ refuse: 'the reason' }`，如[在檢查失敗時拒絕 mod](/docs/zh-TW/plugins/mods/admin#refuse-mods-when-your-check-fails) 所示

371 378

379在 `tool.call`，於 `next` 解析後傳回的 `deny` 會[對 Claude 隱藏結果](#guard-or-change-a-tool-call)。

380

372<h2 id="next-steps">381<h2 id="next-steps">

373 後續步驟382 後續步驟

374</h2>383</h2>

plugins/mods/interface.md +11 −3

Details

10 10

11此地圖顯示 mod 可以在終端機工作階段中的繪製位置：11此地圖顯示 mod 可以在終端機工作階段中的繪製位置：

12 12

13<img src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-screen-map.svg?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=5fda26b6609c62b68c6f9e528c1590ea" className="dark:hidden" alt="Claude Code 終端機工作階段的地圖。mod 可以在右側新增窗格作為側邊欄、在逐字稿右上角新增快顯通知、在逐字稿中新增日誌行、在提示上方新增帶狀區域，以及在提示下方新增狀態列。mod 可以重新繪製訊息、工具呼叫列和微調器。提示是 Claude Code 自己的。" width="600" height="336" data-path="images/mods-screen-map.svg" />13<img src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-screen-map.svg?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=5fda26b6609c62b68c6f9e528c1590ea" className="dark:hidden" alt="Claude Code 終端機工作階段在全螢幕轉譯模式下的地圖。mod 可以在右側新增窗格作為側邊欄、在逐字稿右上角新增快顯通知、在逐字稿中新增日誌行、在提示上方新增帶狀區域，以及在提示下方新增狀態列。mod 可以重新繪製訊息、工具呼叫列和微調器。提示是 Claude Code 自己的。" width="600" height="336" data-path="images/mods-screen-map.svg" />

14 14

15<img src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-screen-map-dark.svg?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=5b4161581a1bd2c0450b0c8b57bc1225" className="hidden dark:block" alt="Claude Code 終端機工作階段的地圖。mod 可以在右側新增窗格作為側邊欄、在逐字稿右上角新增快顯通知、在逐字稿中新增日誌行、在提示上方新增帶狀區域，以及在提示下方新增狀態列。mod 可以重新繪製訊息、工具呼叫列和微調器。提示是 Claude Code 自己的。" width="600" height="336" data-path="images/mods-screen-map-dark.svg" />15<img src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-screen-map-dark.svg?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=5b4161581a1bd2c0450b0c8b57bc1225" className="hidden dark:block" alt="Claude Code 終端機工作階段在全螢幕轉譯模式下的地圖。mod 可以在右側新增窗格作為側邊欄、在逐字稿右上角新增快顯通知、在逐字稿中新增日誌行、在提示上方新增帶狀區域，以及在提示下方新增狀態列。mod 可以重新繪製訊息、工具呼叫列和微調器。提示是 Claude Code 自己的。" width="600" height="336" data-path="images/mods-screen-map-dark.svg" />

16 16

17在較窄的終端機中，窗格位於提示上方而不是逐字稿旁邊。17在較窄的終端機中，窗格位於提示上方而不是逐字稿旁邊。

18 18

330 330

337 337

338若要讓命令在 Claude 工作時開啟窗格，請在[註冊命令](/docs/zh-TW/plugins/mods/api#add-a-command)時新增 `immediate: true`。沒有它，在回合期間輸入的命令會等待回合結束。338若要讓命令在 Claude 工作時開啟窗格，請在[註冊命令](/docs/zh-TW/plugins/mods/api#add-a-command)時新增 `immediate: true`。沒有它，在回合期間輸入的命令會等待回合結束。

339 339

340<h4 id="hold-toasts-behind-a-dialog">

341 在對話框後方保留快顯通知

342</h4>

343

344當窗格是使用者回答後即離開的對話框時，請將 `holdToasts: true` 傳遞給 `$.ui.open`，讓快顯通知不會在使用者做決定時出現。在終端機中，保留會在該窗格是正在顯示的窗格期間持續，而在此期間引發的快顯通知會等到保留結束才出現。

345

346Claude Code 會保留其他 mod 的快顯通知及它自己的短暫通知，也會保留您的 mod 透過 [`$.ui.toast`](/docs/zh-TW/plugins/mods/api#show-something-without-starting-a-turn) 引發的通知。對於保持開啟的窗格，請不要設定此欄位，讓使用者能持續看到這些通知。

347

340<h4 id="when-a-pane-waits-for-a-wider-terminal">348<h4 id="when-a-pane-waits-for-a-wider-terminal">

341 當窗格等待更寬的終端機時349 當窗格等待更寬的終端機時

342</h4>350</h4>

plugins/mods/reference.md +5 −3

Details

64| :- | :- | :- |64| :- | :- | :- |

65| [`tool.call`](/docs/zh-TW/plugins/mods/events#guard-or-change-a-tool-call) | 工具即將執行時 | `next(e)`、`{ deny: reason }` 或 `{ result }` |65| [`tool.call`](/docs/zh-TW/plugins/mods/events#guard-or-change-a-tool-call) | 工具即將執行時 | `next(e)`、`{ deny: reason }` 或 `{ result }` |

66| [`tool.check`](/docs/zh-TW/plugins/mods/events#where-settings-hooks-run-in-the-order) | Claude Code 在 `tool.call` 與 `PreToolUse` hook 之後，決定工具呼叫是否可以執行時。`next(e)` 會解析為規則、權限模式與這些 hook 所得出的決定。 | `{ decision }`，值為 `allow`、`ask` 或 `deny` |66| [`tool.check`](/docs/zh-TW/plugins/mods/events#where-settings-hooks-run-in-the-order) | Claude Code 在 `tool.call` 與 `PreToolUse` hook 之後，決定工具呼叫是否可以執行時。`next(e)` 會解析為規則、權限模式與這些 hook 所得出的決定。 | `{ decision }`，值為 `allow`、`ask` 或 `deny` |

67| `tool.describe` | 每個工具一次，在其說明首次傳送給 Claude 時 | `{ description }`，可選擇將 `isDeferred` 設為 `true` 以將該工具置於[工具搜尋](/docs/zh-TW/mcp#scale-with-mcp-tool-search)之後，或設為 `false` 以預先載入 |67| `tool.describe` | 每個工具一次，在其說明首次傳送給 Claude 時。當 Claude 透過[工具搜尋](/docs/zh-TW/mcp#scale-with-mcp-tool-search)載入 MCP 工具時會再觸發一次，此時 `e.description` 設為 Claude 針對已載入工具所讀取的文字。 | `{ description }`，可選擇將 `isDeferred` 設為 `true` 以將該工具置於工具搜尋之後，或設為 `false` 以預先載入 |

68 68

69<h4 id="agent-and-organization-fields-on-tool-check">69<h4 id="agent-and-organization-fields-on-tool-check">

70 `tool.check` 上的 agent 與組織欄位70 `tool.check` 上的 agent 與組織欄位

133| `session.end` | 工作階段結束，或執行 `/clear`、`/resume` 或 `/branch` 時。`e.reason` 為 `clear`、`resume`、`logout`、`prompt_input_exit` 或 `other`。`/branch` 會回報 `resume`。 | `next(e)` |133| `session.end` | 工作階段結束，或執行 `/clear`、`/resume` 或 `/branch` 時。`e.reason` 為 `clear`、`resume`、`logout`、`prompt_input_exit` 或 `other`。`/branch` 會回報 `resume`。 | `next(e)` |

134| `session.compact` | 對話即將被壓縮時 | `{ skip: reason }` |134| `session.compact` | 對話即將被壓縮時 | `{ skip: reason }` |

135| [`session.receive`](/docs/zh-TW/plugins/mods/api#send-and-receive-messages-between-sessions)、[`session.send`](/docs/zh-TW/plugins/mods/api#send-and-receive-messages-between-sessions) | 訊息從另一個 agent 或工作階段送達，或即將傳送至另一個 agent 或工作階段時。請參閱[在工作階段之間傳送與接收訊息](/docs/zh-TW/plugins/mods/api#send-and-receive-messages-between-sessions)。 | `receive` 為 `{ consumed: reason }`，`send` 為 `{ isDelivered: false, reason }` |135| [`session.receive`](/docs/zh-TW/plugins/mods/api#send-and-receive-messages-between-sessions)、[`session.send`](/docs/zh-TW/plugins/mods/api#send-and-receive-messages-between-sessions) | 訊息從另一個 agent 或工作階段送達，或即將傳送至另一個 agent 或工作階段時。請參閱[在工作階段之間傳送與接收訊息](/docs/zh-TW/plugins/mods/api#send-and-receive-messages-between-sessions)。 | `receive` 為 `{ consumed: reason }`，`send` 為 `{ isDelivered: false, reason }` |

136| `session.append` | 對話保留的每一列各一次，例如提示詞、回應區塊、工具結果或通知，在其儲存之前 | 以 `next({ ...e, message })` 改寫該列的 `content` |136| `session.append` | 對話保留的每一列各一次，例如提示詞、回應區塊、工具結果或通知，在其儲存之前 | 以 `next({ ...e, message })` 搭配變更後的 `message.content`，改寫該列的文字區塊，或其中 `tool_result` 區塊的 `content` |

139 139

209| [`$.ui`](/docs/zh-TW/plugins/mods/interface#pick-where-to-draw) | `resolve`、`invalidate`、`open`、`close`、`panes`、`focus`、`scroll`、`toast`、`status`、`log`、`notice`、`ask`、`copy`、`selection`、`blit` |209| [`$.ui`](/docs/zh-TW/plugins/mods/interface#pick-where-to-draw) | `resolve`、`invalidate`、`open`、`close`、`panes`、`focus`、`scroll`、`toast`、`status`、`log`、`notice`、`ask`、`copy`、`selection`、`blit` |

212| `$.agent` | `register`、`spawn`、`list` |212| `$.agent` | `register`、`spawn`、`list`。`list()` 會回傳此工作階段的 subagent 與隊友，每個都帶有 `status`，其值為 `pending`、`running`、`waiting`、`idle`、`completed`、`failed` 或 `killed`，其中 `idle` 與 `waiting` 需要 Claude Code v2.1.289 或更新版本。 |

214| [`$.prompt`](/docs/zh-TW/plugins/mods/api#start-a-turn-from-a-background-job) | `submit`、`read`、`fill`、`suggest`、`compose`。Claude 會在一個指明您的 mod 為傳送者的句子之後，讀取來自 `submit({ text })` 的文字。`submit({ text, asUser: true })` 會將文字當作使用者本人的話傳送，不附帶該句子。 |214| [`$.prompt`](/docs/zh-TW/plugins/mods/api#start-a-turn-from-a-background-job) | `submit`、`read`、`fill`、`suggest`、`compose`。Claude 會在一個指明您的 mod 為傳送者的句子之後，讀取來自 `submit({ text })` 的文字。`submit({ text, asUser: true })` 會將文字當作使用者本人的話傳送，不附帶該句子。 |

320| hook 的 `drop` 原因或 `config.set` `deny` 原因 | 4,096 個字元。較長原因的結尾會被截斷，drop 或 deny 仍會生效。截斷需要 Claude Code v2.1.292 或更新版本，在較早的版本中，hook 則會改為[失敗](/docs/zh-TW/plugins/mods/events#handle-a-hook-that-fails)。 |

320| 單一樹狀結構中的文字 | 只繪製前 100,000 個字元 |321| 單一樹狀結構中的文字 | 只繪製前 100,000 個字元 |

321| `Code` 的 `language` 或 `path`、`Select` 選項的 `value`，或 `Client` 的 `module` | 10,000 個字元。若其中任一項較長，Claude Code 會[自行繪製該位置的版本](/docs/zh-TW/plugins/mods/interface#build-a-tree-from-elements)。 |322| `Code` 的 `language` 或 `path`、`Select` 選項的 `value`，或 `Client` 的 `module` | 10,000 個字元。若其中任一項較長，Claude Code 會[自行繪製該位置的版本](/docs/zh-TW/plugins/mods/interface#build-a-tree-from-elements)。 |

326| `$.ui.toast` | 顯示 4 秒，除非您傳入 `{ timeoutMs }` |327| `$.ui.toast` | 顯示 4 秒，除非您傳入 `{ timeoutMs }` |

327| 未經使用者要求而開啟的窗格 | 自 144 個終端機欄寬起放置，使用者開啟過一次後則為 110 |328| 未經使用者要求而開啟的窗格 | 自 144 個終端機欄寬起放置，使用者開啟過一次後則為 110 |

329| 在 hook 模組的單一檔案中彼此巢狀的作用域，例如函式、區塊與迴圈 | 2,000 |

330 332

plugins/mods/test.md +7 −2

Details

110* `returned neither { value } nor { deny }`：mods API 呼叫的 stub 返回了一個裸值，這會使測試失敗110* `returned neither { value } nor { deny }`：mods API 呼叫的 stub 返回了一個裸值，這會使測試失敗

111* `no implementation for` 後跟一個名稱：您的 mod 進行了該呼叫，沒有 stub 回答它111* `no implementation for` 後跟一個名稱：您的 mod 進行了該呼叫，沒有 stub 回答它

112 112

113該套件還在記憶體中匯出 mocks，為您回答整個命名空間。`mock.clock(on)` 回答 [`$.clock`](/docs/zh-TW/plugins/mods/api#run-work-in-the-background)，`mock.store(on, { count: 7 })` 從以這些項目開始的存儲中回答 `$.store`，`mock.env(on, { CI: 'true' })` 從這些變數中回答 `$.env.get`。`mock.clock` 返回一個您的測試可以推進的模擬時鐘，因此計時器測試不會等待。`mock.store` 不返回任何內容，因此要檢查您的 mod 保存了什麼，請自己編寫兩個 `store` stubs，如 [drawing test](#test-a-drawing) 所做的那樣。113該套件還匯出了現成的 mock，用於時鐘、存儲、環境變數，以及附加到對話中的列：

114

115* **`mock.clock(on)`**：回答 [`$.clock`](/docs/zh-TW/plugins/mods/api#run-work-in-the-background)，並返回一個由您的測試推進的模擬時鐘，因此計時器測試不會等待。

116* **`mock.store(on, { count: 7 })`**：從以這些項目開始的存儲中回答 `$.store`。它不返回任何內容，因此要檢查您的 mod 保存了什麼，請自己編寫兩個 `store` stub，如 [drawing test](#test-a-drawing) 所做的那樣。

117* **`mock.env(on, { CI: 'true' })`**：從這些變數中回答 `$.env.get`。

118* **`mock.session(on)`**：返回一個模擬工作階段，其 `appended()` 方法會列出您的 mod 透過 [`$.session.append`](/docs/zh-TW/plugins/mods/reference#session) 新增的列，由舊到新排列；需要 Claude Code v2.1.293 或更新版本。

114 119

115<h3 id="follow-the-test-kit’s-rules">120<h3 id="follow-the-test-kit’s-rules">

116 遵循測試套件的規則121 遵循測試套件的規則

168 查詢 stub 返回的內容173 查詢 stub 返回的內容

169</h3>174</h3>

170 175

171您的 mod 在測試中進行的每個 mods API 呼叫都需要一個 stub 來回答，除了套件自己回答的少數幾個：[`$.ui.invalidate`](/docs/zh-TW/plugins/mods/interface#redraw-when-something-changes) 和 [`$.state`](/docs/zh-TW/plugins/mods/interface#keep-state) 呼叫。對於 `$.clock` 呼叫，使用 `mock.clock(on)`，否則您的 mod 的 `$.clock.now()` 會失敗，並顯示 `no implementation for clock.now`。176您的 mod 在測試中進行的每個 mods API 呼叫都需要一個代替 Claude Code 回答的 stub，除了套件自己回答的少數幾個：[`$.ui.invalidate`](/docs/zh-TW/plugins/mods/interface#redraw-when-something-changes)、[`$.state`](/docs/zh-TW/plugins/mods/interface#keep-state) 和 `$.session.append` 呼叫。對於 `$.clock` 呼叫，使用 `mock.clock(on)`，否則您的 mod 的 `$.clock.now()` 會失敗，並顯示 `no implementation for clock.now`。

172 177

173此表列出了 mods 最常使用的。第一列是您的 mod 進行的呼叫或它使用 `next(e)` 傳遞的事件。第二列是傳遞給該名稱下的 `on` 的函數，因此 `$.store.get` 列變成 `on('store.get', ($, e) => ({ value: saved.get(e.key) }))`。stub 中的 `'...'` 標記您要填入的文字：178此表列出了 mods 最常使用的。第一列是您的 mod 進行的呼叫或它使用 `next(e)` 傳遞的事件。第二列是傳遞給該名稱下的 `on` 的函數，因此 `$.store.get` 列變成 `on('store.get', ($, e) => ({ value: saved.get(e.key) }))`。stub 中的 `'...'` 標記您要填入的文字：

174 179

plugins/mods/troubleshoot.md +31 −1

Details

116 116

117設定或變更值。該行的末尾命名其在 `settings.json` 中的 `pluginConfigs` 項目。117設定或變更值。該行的末尾命名其在 `settings.json` 中的 `pluginConfigs` 項目。

118 118

119<h3 id="code-nested-too-deep-to-scan-more-than-2000-scopes">

120 `code nested too deep to scan: more than 2000 scopes`

121</h3>

122

123該行以 mod 的名稱開頭，然後是 `hooks module did not load:`、檔案，以及 `code nested too deep to scan: more than 2000 scopes`。hook 模組中的檔案不能將作用域（例如函式、區塊和迴圈）巢狀超過 [2,000 層](/docs/zh-TW/plugins/mods/reference#limits)。[`claude plugin validate`](/docs/zh-TW/plugins/mods/create#check-what-claude-code-reads-from-your-mod) 會回報相同的原因。

124

125重寫程式碼，以減少其作用域的巢狀深度。

126

119<h3 id="no-mod-loads-in-a-directory-you-opened-for-the-first-time">127<h3 id="no-mod-loads-in-a-directory-you-opened-for-the-first-time">

120 沒有 mod 在您首次開啟的目錄中載入128 沒有 mod 在您首次開啟的目錄中載入

121</h3>129</h3>

132 140

133啟動時不使用該旗標。141啟動時不使用該旗標。

134 142

143<h3 id="claude-code-stops-asking-to-enable-hot-reloading">

144 Claude Code 不再詢問是否啟用熱重新載入

145</h3>

146

147Claude 在互動式工作階段中撰寫 mod，但沒有任何內容載入，而且 Claude Code 不再詢問[是否啟用熱重新載入](/docs/zh-TW/plugins/mods/create#ask-claude-for-a-mod)。如果該問題有三次在未選擇答案的情況下結束，熱重新載入會保持關閉。例如，當您設定了 [`askUserQuestionTimeout`](/docs/zh-TW/settings-reference#askuserquestiontimeout)，且在您回答之前時間已到，問題就會以這種方式結束。該設定在此適用，是因為 Claude Code 是在[與 `AskUserQuestion` 相同的問題對話框](/docs/zh-TW/tools-reference#question-auto-continue-timeout)中詢問。您自行關閉的問題不計入這三次。

148

149若要執行該 mod，請[將其目錄從 mods 資料夾複製出來](/docs/zh-TW/plugins/mods/create#use-the-mod-in-other-sessions)，然後在 shell 中使用 `--plugin-dir` 啟動新的工作階段，例如 `claude --plugin-dir ~/mods/git-branch`。

150

135<h2 id="a-hook-is-skipped-or-a-mod-is-unloaded">151<h2 id="a-hook-is-skipped-or-a-mod-is-unloaded">

136 hook 被跳過或 mod 被卸載152 hook 被跳過或 mod 被卸載

137</h2>153</h2>

209 繪圖不出現或不回應225 繪圖不出現或不回應

210</h2>226</h2>

211 227

212mod 已載入，其窗格、帶狀或控制項的行為不符合您的預期。228mod 已載入，其窗格、帶狀、toast 或控制項的行為不符合您的預期。

213 229

214<h3 id="a-pane-or-band-is-empty-or-shows-claude-code’s-usual-content">230<h3 id="a-pane-or-band-is-empty-or-shows-claude-code’s-usual-content">

215 窗格或帶狀為空或顯示 Claude Code 的常見內容231 窗格或帶狀為空或顯示 Claude Code 的常見內容

247 263

248從命令或按鈕開啟窗格，或檢查呼叫的 `isPlaced` 結果。請參閱[在正確的時間開啟窗格](/docs/zh-TW/plugins/mods/interface#open-a-pane-at-the-right-time)。264從命令或按鈕開啟窗格，或檢查呼叫的 `isPlaced` 結果。請參閱[在正確的時間開啟窗格](/docs/zh-TW/plugins/mods/interface#open-a-pane-at-the-right-time)。

249 265

266<h3 id="a-toast-doesn’t-appear">

267 toast 未出現

268</h3>

269

270您的 mod 在互動式終端機工作階段中呼叫 [`$.ui.toast`](/docs/zh-TW/plugins/mods/api#show-something-without-starting-a-turn)，但您沒有看到 toast。若要確認該呼叫已執行，請在[偵錯日誌](#read-the-debug-log)中尋找包含您的 mod 名稱與 toast 文字的行，例如 `$.ui.toast (first-mod): build finished`。接著檢查以下可能原因：

271

272* **缺少該呼叫的行**：尋找說明 Claude Code 拒絕該呼叫原因的行，例如 `first-mod: $.ui.toast dropped: timeoutMs is a whole number of ms, 1 to 60000`。

273* **有窗格正在保留 toast**：您的 mod 或其他 mod 在開啟目前顯示的窗格時傳入了 [`holdToasts`](/docs/zh-TW/plugins/mods/interface#hold-toasts-behind-a-dialog)。關閉該窗格即可結束保留。如果該窗格是您的，且應保持開啟，請從其 `$.ui.open` 呼叫中移除 `holdToasts`，然後重新開啟窗格。

274* **toast 位於提示詞下方**：在[傳統轉譯器](/docs/zh-TW/fullscreen#enable-fullscreen-rendering)中，請查看提示詞下方的右側。該處的 toast 是以 mod 名稱開頭的一行文字，而不是右上角的方框。

275* **您的 mod 發出了較新的 toast**：在傳統轉譯器中，您的 mod 發出的較新 toast 可能會取代正在顯示或等待顯示的 toast。偵錯日誌中會有較舊 toast 的另一行，若該 toast 正在顯示，結尾為 `gave way, cut short`；若從未出現，結尾為 `gave way, unseen`。若要同時顯示兩則訊息，請將它們放在同一個 toast 中。

276* **toast 在繪製前逾時**：在全螢幕轉譯中，Claude Code 一次最多繪製三個 toast，因此 toast 可能在繪製前就已逾時。偵錯日誌中會有該 toast 的另一行，結尾為 `left the stack, never drawn`。當您的 mod 同時發出多個 toast 時，請將訊息放在同一個 toast 中。

277

278在 v2.1.290 之前，Claude Code 會捨棄在其為您的 mod 顯示上一個 toast 後兩秒內發出的 toast，且被捨棄 toast 的偵錯日誌行會顯示 `within 2000ms of the last; dropped`。

279

250<h3 id="hotkeys-do-nothing">280<h3 id="hotkeys-do-nothing">

251 快捷鍵沒有作用281 快捷鍵沒有作用

252</h3>282</h3>

plugins/publish.md +2 −1

Details

110}110}

111```111```

112 112

113在您的 shell 中，在存放庫中執行 `claude plugin validate .` 以在推送前檢查檔案。113在推送之前，請在您的 shell 中於儲存庫內執行 `claude plugin validate .`。關於此執行會檢查的內容，請參閱 [驗證目錄](/docs/zh-TW/plugins/cli-reference#validate-a-directory)。

114 114

115[建立市集](/docs/zh-TW/plugins/create-marketplace) 涵蓋一個存放庫中有多個外掛程式的佈局。115[建立市集](/docs/zh-TW/plugins/create-marketplace) 涵蓋一個存放庫中有多個外掛程式的佈局。

116 116

129* 新增市集一次：`claude plugin marketplace add your-org/your-marketplace`，其中引數是 GitHub `owner/repo` 速記、URL 或路徑129* 新增市集一次：`claude plugin marketplace add your-org/your-marketplace`，其中引數是 GitHub `owner/repo` 速記、URL 或路徑

130* 安裝外掛程式：`claude plugin install deploy-helper@your-marketplace`130* 安裝外掛程式：`claude plugin install deploy-helper@your-marketplace`

131* 或從工作階段內執行兩者：`/plugin install deploy-helper --marketplace your-org/your-marketplace`。需要 Claude Code v2.1.275 或更新版本。請參閱 [在一個命令中新增市集和安裝](/docs/zh-TW/plugins/install#add-a-marketplace-and-install-in-one-command)131* 或從工作階段內執行兩者：`/plugin install deploy-helper --marketplace your-org/your-marketplace`。需要 Claude Code v2.1.275 或更新版本。請參閱 [在一個命令中新增市集和安裝](/docs/zh-TW/plugins/install#add-a-marketplace-and-install-in-one-command)

132* 或從 shell 以一個命令執行兩者：`claude plugin install deploy-helper --marketplace your-org/your-marketplace`。需要 Claude Code v2.1.292 或更新版本

132 133

133<h3 id="ship-updates-to-users">134<h3 id="ship-updates-to-users">

134 向使用者發送更新135 向使用者發送更新

plugins/troubleshooting.md +73 −3

Details

163 `Invalid marketplace source format`163 `Invalid marketplace source format`

164</h3>164</h3>

165 165

166您執行了 `/plugin marketplace add <source>` 或 `claude plugin marketplace add <source>`，Claude Code 回覆 `Invalid marketplace source format. Try: owner/repo, https://..., or ./path`。166您執行了 `/plugin marketplace add <source>`、`claude plugin marketplace add <source>` 或 `claude plugin install <plugin> --marketplace <source>`，Claude Code 回覆 `Invalid marketplace source format. Try: owner/repo, https://..., or ./path`。

167 167

168Claude Code 接受以下形式之一的來源：168Claude Code 接受以下形式之一的來源：

169 169

237* **您擁有市集**：將檔案放在該位置並重新新增市集237* **您擁有市集**：將檔案放在該位置並重新新增市集

238* **其他人託管它**：詢問所有者確切的來源他們發佈238* **其他人託管它**：詢問所有者確切的來源他們發佈

239 239

240<h3 id="cannot-install-plugins-from-a-marketplace-with-this-name">

241 `Cannot add marketplace "<name>": Claude Code cannot install plugins from a marketplace with this name`

242</h3>

243

244您新增了市集，而其 `marketplace.json` 中的 [`name`](/docs/zh-TW/plugins/marketplace-reference#top-level-fields) 無法作為 [外掛 ID](/docs/zh-TW/plugins/loading#find-where-a-plugin-came-from)（例如 `my-plugin@my-marketplace`）中 `@` 之後的部分。Claude Code 會拒絕此新增，且不會註冊任何內容。

245

246訊息的其餘部分說明名稱的規則。在此範例中，`_internal` 因以 `_` 開頭而違反規則：

247

248```text theme={null}

249Cannot add marketplace "_internal": Claude Code cannot install plugins from a marketplace with this name. Each part of a plugin id (plugin@marketplace) may use only the letters a-z and A-Z, digits, ".", "_" and "-", and must start with a letter or digit. The name is set by "name" in the marketplace's marketplace.json; ask its maintainer to change it.

250```

251

252為市集取一個符合該規則的名稱，然後再次新增：

253

254* **您擁有市集**：變更 `marketplace.json` 中的 `name`，例如改為 `internal-tools`

255* **其他人託管它**：請所有者變更名稱

256

257在 v2.1.295 之前，Claude Code 會將此範例中的新增回報為成功。

258

240<h3 id="ssh-authentication-failed-or-https-authentication-failed">259<h3 id="ssh-authentication-failed-or-https-authentication-failed">

241 `SSH authentication failed` or `HTTPS authentication failed`260 `SSH authentication failed` or `HTTPS authentication failed`

242</h3>261</h3>

568 `Marketplace "<name>" is already added from a different source`587 `Marketplace "<name>" is already added from a different source`

569</h3>588</h3>

570 589

571您確認透過 [`/plugin install <plugin> --marketplace <source>`](/docs/zh-TW/plugins/install#add-a-marketplace-and-install-in-one-command) 新增市集，Claude Code 從該來源擷取的目錄與您已從不同來源新增的市集具有相同的名稱。Claude Code 保留現有市集而不是替換它，外掛程式未安裝。590您在工作階段中或從 shell 使用 [安裝命令上的 `--marketplace <source>`](/docs/zh-TW/plugins/install#add-a-marketplace-and-install-in-one-command) 指定了新的市集來源。Claude Code 從該來源擷取的目錄與您已從不同來源新增的市集具有相同的名稱。Claude Code 保留現有市集而不是替換它，外掛程式未安裝。

572 591

573完整訊息如下所示：592完整訊息如下所示：

574 593

786 805

787Claude Code 將無法使用的記錄複製到 `.set-aside` 檔案中，並將其從清單中刪除。Claude Code 永遠不會讀取副本，副本在 [`cleanupPeriodDays`](/docs/zh-TW/settings-reference#cleanupperioddays) 排程上老化。806Claude Code 將無法使用的記錄複製到 `.set-aside` 檔案中，並將其從清單中刪除。Claude Code 永遠不會讀取副本，副本在 [`cleanupPeriodDays`](/docs/zh-TW/settings-reference#cleanupperioddays) 排程上老化。

788 807

808<h3 id="does-not-load-so-claude-code-ignores-the-whole-file">

809 `does not load (...), so Claude Code ignores the whole file`

810</h3>

811

812命令已成功執行。警告所指的設定檔有錯誤，因此在您修正它之前，Claude Code 會忽略整個檔案，包括命令寫入其中的任何內容。

813

814修正警告所指出的錯誤。對於 Claude Code 不接受的值，[修正損壞的設定檔](/docs/zh-TW/settings#fix-a-broken-settings-file) 說明了修正方法。然後，如果命令的變更已不在檔案中，請再次執行該命令。

815

816警告會出現在您 shell 中 `claude plugin install`、`enable`、`disable` 或 `claude plugin marketplace add` 的成功行之後：

817

818```text theme={null}

819⚠ /home/user/.claude/settings.json does not load (its "permissions" is not valid), so Claude Code ignores the whole file, including anything this command wrote there. Fix the file, then run this command again if its change is missing. If a newer Claude Code wrote the file, update Claude Code instead.

820```

821

822括號中的文字指出錯誤：

823

824* **`its "<key>" is not valid`**：加上引號的設定項目持有 Claude Code 不接受的值。請在 [設定參考](/docs/zh-TW/settings-reference) 中查閱該設定項目可接受的值。當有多個值無效時，文字會指出第一個設定項目並計算其他項目的數量，例如 `its "permissions" and 1 other value are not valid`。

825* **`it is not a JSON object`**：檔案的頂層不是 JSON 物件，例如頂層是陣列的檔案。

826

789<h3 id="a-plugin-you-disabled-still-loads">827<h3 id="a-plugin-you-disabled-still-loads">

790 `Disabled in ~/.claude/settings.json but still loads`828 `Disabled in ~/.claude/settings.json but still loads`

791</h3>829</h3>

812 850

813如果您的組織為您預先安裝外掛程式，它會透過受管設定執行此操作。請參閱 [預先安裝和要求外掛程式](/docs/zh-TW/plugins/org#pre-install-and-require-plugins)。851如果您的組織為您預先安裝外掛程式，它會透過受管設定執行此操作。請參閱 [預先安裝和要求外掛程式](/docs/zh-TW/plugins/org#pre-install-and-require-plugins)。

814 852

853<h3 id="a-plugin-stays-installed-after-plugin-uninstall-on-windows">

854 在 Windows 上執行 `plugin uninstall` 後外掛程式仍保持安裝

855</h3>

856

857在 Windows 上，您在專案或本機範圍執行 `claude plugin uninstall`，它回報成功，但 `claude plugin list` 或 `/plugin` 仍列出該外掛程式。

858

859`installed_plugins.json` 中針對該專案資料夾保存了該外掛程式的兩筆安裝記錄，每筆對資料夾路徑的寫法不同，而一次解除安裝只會移除其中一筆。若要檢查，請在 shell 中執行 `claude plugin list --json`。該外掛程式剩餘的列會有一個 `projectPath`，其資料夾寫法與您執行解除安裝的位置不同，例如 `C:\work\app` 寫成 `c:\work\app`。

860

861從同一個資料夾，以相同的 `--scope` 再次執行相同的解除安裝命令。第二次執行在其自身的路徑寫法下找不到記錄，因此會移除另一種寫法下的記錄。對於專案範圍的安裝：

862

863```shell theme={null}

864claude plugin uninstall <name>@<marketplace> --scope project

865```

866

867然後再次執行 `claude plugin list --json`，確認該列已消失。

868

869在 v2.1.295 之前，第二次執行會失敗並顯示 `Plugin "<name>" is not installed in project scope`。請執行 `claude update`，然後再次執行解除安裝。

870

815<h3 id="failed-to-load-hooks-from-and-hooks-that-dont-fire">871<h3 id="failed-to-load-hooks-from-and-hooks-that-dont-fire">

816 `Failed to load hooks from <path>` and hooks that don't fire872 `Failed to load hooks from <path>` and hooks that don't fire

817</h3>873</h3>

835 891

836如果 stderr 顯示外掛程式的路徑在空格處被截斷，hook 的 shell 形式命令在引號外使用 `${CLAUDE_PLUGIN_ROOT}`，且安裝路徑包含空格。將變數用雙引號括起來或使用 [exec 形式](/docs/zh-TW/hooks#exec-form-and-shell-form)。若要找到未引用的變數，請在外掛程式目錄上執行 `claude plugin validate`，並查找其 [引用警告](/docs/zh-TW/plugins/manifest-reference#quoting-and-path-separators)。892如果 stderr 顯示外掛程式的路徑在空格處被截斷，hook 的 shell 形式命令在引號外使用 `${CLAUDE_PLUGIN_ROOT}`，且安裝路徑包含空格。將變數用雙引號括起來或使用 [exec 形式](/docs/zh-TW/hooks#exec-form-and-shell-form)。若要找到未引用的變數，請在外掛程式目錄上執行 `claude plugin validate`，並查找其 [引用警告](/docs/zh-TW/plugins/manifest-reference#quoting-and-path-separators)。

837 893

894如果通知讀作 `Failed to run: Plugin directory does not exist: <path>`，請參閱 [`Plugin directory does not exist`](#plugin-directory-does-not-exist)。

895

838對於任何其他錯誤，從外掛程式目錄自行執行 hook 的命令以查看完整輸出，或使用 [偵錯記錄](/docs/zh-TW/hooks#debug-hooks) 捕捉完整 stderr。896對於任何其他錯誤，從外掛程式目錄自行執行 hook 的命令以查看完整輸出，或使用 [偵錯記錄](/docs/zh-TW/hooks#debug-hooks) 捕捉完整 stderr。

839 897

840<h4 id="a-plugin-hook-blocks-a-tool-call-or-prompt">898<h4 id="a-plugin-hook-blocks-a-tool-call-or-prompt">

869 </Step>927 </Step>

870</Steps>928</Steps>

871 929

930<h3 id="plugin-directory-does-not-exist">

931 `Plugin directory does not exist: <path>`

932</h3>

933

934即使訊息要求重新安裝，也請先在 Claude Code 提示字元執行 `/reload-plugins`。當您的工作階段載入外掛程式 hook 的目錄已從磁碟上消失時，外掛程式的 hook 會失敗並顯示 `Failed to run: Plugin directory does not exist: <path> (<plugin> — run /plugin to reinstall)`，且該 hook 不會執行。[`Plugin directory not found at path: <path>`](#plugin-directory-not-found-at-path) 是另一則訊息，與市集條目有關。

935

936重新載入會從外掛程式目前的目錄載入其 hook。此失敗在每個工作階段中針對每個 hook 事件和命令只會顯示一次，因此 hook 不再報錯並不代表已修正。請改為讀取重新載入的輸出：

937

938* **`Reloaded:` 且沒有錯誤行**：外掛程式的 hook 不再指向遺失的目錄

939* **`N errors during load. Run /plugin for details.`**：在 `/plugin` 中開啟 **Errors** 標籤，並依照本頁中對應其顯示訊息的條目處理

940* **以 `Run /reload-plugins --force to apply.` 結尾的行**：沒有任何內容被重新載入，hook 會持續失敗。請在 Claude Code 提示字元執行 `/reload-plugins --force`

941

872<h3 id="invalid-mcp-server-config-for-and-mcp-servers-that-dont-start">942<h3 id="invalid-mcp-server-config-for-and-mcp-servers-that-dont-start">

873 `Invalid MCP server config for "<server>"` and MCP servers that don't start943 `Invalid MCP server config for "<server>"` and MCP servers that don't start

874</h3>944</h3>

1063 1133

1064您執行了 `claude plugin validate <path>`，或在工作階段中執行了 `/plugin validate <path>`，它列印了 `Found N errors` 和 `Validation failed`，然後以代碼 1 結束。1134您執行了 `claude plugin validate <path>`，或在工作階段中執行了 `/plugin validate <path>`，它列印了 `Found N errors` 和 `Validation failed`，然後以代碼 1 結束。

1065 1135

1066驗證器讀取您提供的路徑處的資訊清單：外掛程式目錄的 `.claude-plugin/plugin.json`，或市集目錄的 `.claude-plugin/marketplace.json`。對於市集，它在項目自身資訊清單中的問題前加上項目索引，如 `plugins[1] plugin.json → json: ...`。1136驗證器讀取您提供的路徑處的資訊清單：外掛程式目錄的 `.claude-plugin/plugin.json`、市集目錄的 `.claude-plugin/marketplace.json`，或者對於同時包含兩者的目錄則讀取兩者。對於市集，它在項目自身資訊清單中的問題前加上項目索引，如 `plugins[1] plugin.json → json: ...`。在 v2.1.289 之前，Claude Code 會將同時包含兩者的目錄僅作為市集進行驗證。

1067 1137

1068該表涵蓋停止驗證的訊息和兩個警告 `No frontmatter block found` 和 `Unknown field '<key>'`，只有在您傳遞 `--strict` 時才會停止。其他警告，例如遺失描述，未列出。1138該表涵蓋停止驗證的訊息和兩個警告 `No frontmatter block found` 和 `Unknown field '<key>'`，只有在您傳遞 `--strict` 時才會停止。其他警告，例如遺失描述，未列出。

1069 1139

remote-control.md +54 −21

Details

364 限制364 限制

365</h2>365</h2>

366 366

367* **每個互動程序一個遠端工作階段**：在伺服器模式之外，每個 Claude Code 實例一次只支援一個遠端工作階段。使用[伺服器模式](#start-a-remote-control-session)從單一程序執行多個並行工作階段。367* **每個互動式程序僅限一個遠端工作階段**：在伺服器模式以外，每個 Claude Code 執行個體一次僅支援一個遠端工作階段。使用[伺服器模式](#start-a-remote-control-session)即可從單一程序執行多個並行工作階段。

368* **本機程序必須保持執行**：Remote Control 以本機程序的形式執行。如果您關閉終端機、結束 Desktop 應用程式或 VS Code，或以其他方式停止 `claude` 程序，工作階段將離線，直到您[將其恢復](#resume-sessions-after-stopping-the-server)。如果您從遠端機器上的終端機執行 `claude`，請在 `tmux` 或 `screen` 內啟動它，以便在您從 SSH 中斷連線後讓工作階段保持執行。368* **本機程序必須保持執行**：Remote Control 以本機程序的形式執行。如果您關閉終端機、結束 Desktop 應用程式或 VS Code，或以其他方式停止 `claude` 程序，工作階段就會離線，直到您[將其恢復](#resume-sessions-after-stopping-the-server)為止。如果您從遠端機器上的終端機執行 `claude`，請在 `tmux` 或 `screen` 中啟動，以便在中斷 SSH 連線後讓工作階段繼續執行。

369* **伺服器模式中的已損毀工作階段**：如果由 `claude remote-control` 提供服務的工作階段損毀，請從已連線的裝置向其傳送訊息。Claude Code 會再次提供服務。您不必重新啟動伺服器。需要 Claude Code v2.1.238 或更新版本。369* **伺服器模式中當機的工作階段**：如果由 `claude remote-control` 提供服務的工作階段當機，請從已連線的裝置向其傳送一則訊息。Claude Code 會再次為其提供服務。您不必重新啟動伺服器。需要 Claude Code v2.1.238 或更新版本。

370* **已連線工作階段上的 HTTP 403 拒絕**：一旦互動工作階段已連線，當您的機器與 Anthropic 伺服器之間的某個位置以 HTTP 403 回應時（在 VPN 或網路變更後可能發生），Claude Code 會重試最多三分鐘。如果拒絕持續更久，Claude Code 會中斷連線，原因會指出拒絕的內容：網路邊界，或您自己網路上的代理伺服器、VPN 或防火牆。370* **已連線工作階段上的 HTTP 403 拒絕**：互動式工作階段連線後，當您的機器與 Anthropic 伺服器之間的某個環節以 HTTP 403 回應時（這可能發生在 VPN 或網路變更之後），Claude Code 會持續重試最多三分鐘。如果拒絕持續更久，Claude Code 會中斷連線，而原因會指出是什麼拒絕了連線：網路邊緣，或您自己網路上的代理伺服器、VPN 或防火牆。

371* **延長的網路中斷**：如果您的機器已開啟但無法連線到網路，您接下來的操作取決於模式：371* **長時間網路中斷**：如果您的機器處於喚醒狀態但無法連上網路，接下來的做法取決於模式：

372 * **伺服器模式**：Claude Code 在大約 10 分鐘後放棄，`claude remote-control` 程序退出。再次執行 `claude remote-control` 以啟動新工作階段。372 * **伺服器模式**：Claude Code 會在大約 10 分鐘後放棄，且 `claude remote-control` 程序會結束。再次執行 `claude remote-control` 以啟動新的工作階段。

373 * **互動工作階段**：繼續在本機工作。Claude Code 會在中斷期間重試，並在網路恢復時自動重新連線。373 * **互動式工作階段**：繼續在本機工作。Claude Code 會在中斷期間持續重試，並在網路恢復時自動重新連線。

374* **無法下載的附件**：如果您從手機或瀏覽器附加的檔案無法下載到您的機器，Claude 仍會收到您的訊息以及已下載的檔案。Claude Code 會在訊息中加入一則附註，例如 `[1 of 3 attachments did not arrive]`，以取代遺失的檔案。374* **無法下載的附件**：如果您從手機或瀏覽器附加的檔案無法下載到您的機器，Claude 仍會收到您的訊息以及已下載的檔案。Claude Code 會在訊息中加入一則附註（例如 `[1 of 3 attachments did not arrive]`）來取代遺失的檔案。

375* **存在心跳失敗**：如果互動工作階段以 `could not reach the Remote Control server for about 30 minutes` 中斷連線，執行 `/remote-control` 以重新連線。375* **狀態心跳失敗**：如果互動式工作階段因 `could not reach the Remote Control server for about 30 minutes` 而中斷連線，請執行 `/remote-control` 重新連線。

376* **轉送的對話框過期**：Claude Code 會保持權限提示和 `AskUserQuestion` 問題開啟，直到您回答。當 Claude Code 將另一種對話框轉送到遠端工作階段時，例如安全拒絕後顯示的模型選擇提示，預設情況下會等待五分鐘，然後關閉對話框並繼續使用對話框的無操作預設值。設定 [`dialogExpiry`](/docs/zh-TW/settings-reference#dialogexpiry) 以調整或停用截止時間。需要 Claude Code v2.1.224 或更新版本。376* **轉發的對話框會過期**：Claude Code 會讓權限提示和 `AskUserQuestion` 問題保持開啟，直到您回答為止。當 Claude Code 將其他類型的對話框轉發到遠端工作階段時（例如在安全性拒絕後顯示的模型選擇提示），預設會等待五分鐘，然後關閉對話框並以該對話框的無動作預設值繼續。設定 [`dialogExpiry`](/docs/zh-TW/settings-reference#dialogexpiry) 以調整或停用此期限。需要 Claude Code v2.1.224 或更新版本。

377* **Fable 用量點數同意提示未轉送**：Claude Code 只在工作階段執行的位置顯示中途[Fable 用量點數同意提示](/docs/zh-TW/model-config#fable-and-usage-credits)，而不是在您的裝置上。當工作階段在終端機中執行，且沒有人在 Claude Code 關閉提示之前回答時，該回合結束而不傳送請求；請參閱[確認提示未被回答](/docs/zh-TW/errors#the-prompt-to-confirm-went-unanswered)。377* **Fable 用量點數同意提示不會被轉發**：Claude Code 只會在工作階段執行的位置顯示工作階段中途的 [Fable 用量點數同意提示](/docs/zh-TW/model-config#fable-and-usage-credits)，而不會顯示在您的裝置上。當工作階段在終端機中執行，且在 Claude Code 關閉提示之前沒有人在那裡回答時，該回合會在未傳送請求的情況下結束；請參閱[需要確認的提示未獲回應](/docs/zh-TW/errors#the-prompt-to-confirm-went-unanswered)。

378* **某些命令僅限本機**：僅在終端機介面中執行的命令，例如 `/plugin` 或 `/resume`，只能從本機 CLI 執行，無論您是否傳遞引數。從行動裝置或網路輸入 `/claude-api` 時也無法使用。Claude 仍可在那裡[自行載入該 skill](/docs/zh-TW/skills#work-on-claude-api-projects)。以下命令可從行動裝置和網路使用：378* **部分命令僅限本機使用**：僅在終端機介面中執行的命令（例如 `/plugin` 或 `/resume`）只能從本機 CLI 使用，無論您是否傳入引數。從行動裝置或網頁輸入 `/claude-api` 時也無法使用。Claude 仍可在那裡[自行載入該 skill](/docs/zh-TW/skills#work-on-claude-api-projects)。以下命令可從行動裝置和網頁使用：

379 * 文字輸出命令：`/compact`、`/clear`、`/context`、`/usage`、`/exit`、`/usage-credits`、`/recap` 和 `/reload-plugins`。`/usage-credits` 列印計費 URL 而不是開啟瀏覽器。`/reload-plugins` 僅在工作階段在互動終端機中執行時有效；沒有終端機的工作階段會拒絕它。379 * 文字輸出命令：`/compact`、`/clear`、`/context`、`/usage`、`/exit`、`/usage-credits`、`/recap` 和 `/reload-plugins`。`/usage-credits` 會輸出計費 URL，而不是開啟瀏覽器。`/reload-plugins` 僅在工作階段於互動式終端機中執行時才能運作；沒有互動式終端機的工作階段會拒絕此命令。

380 * `/model`、`/effort`、`/fast`、`/color` 和 `/rename`：將值作為引數傳遞，例如 `/model sonnet` 或 `/effort high`。從行動裝置和網路，`/model` 和 `/effort` 會取代終端機選擇器或滑桿來接受引數。380 * `/model`、`/effort`、`/fast`、`/color` 和 `/rename`：以引數傳入值，例如 `/model sonnet` 或 `/effort high`。從行動裝置和網頁使用時，`/model` 和 `/effort` 會以引數取代終端機中的選擇器或滑桿。

381 * `/mcp`：從行動應用程式，傳回伺服器狀態的文字摘要而不是開啟選擇器。在網路上，`/mcp` 單獨開啟 [claude.ai 連接器](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai)的目錄，而不是傳回摘要。`reconnect`、`enable` 和 `disable` [子命令](/docs/zh-TW/commands#all-commands)可從兩者使用。不帶伺服器名稱的 `/mcp reconnect` 會重試每個已失敗或需要身分驗證的伺服器。381 * `/mcp`：從行動應用程式使用時，會傳回伺服器狀態的文字摘要，而不是開啟選擇器。在網頁上，單獨使用 `/mcp` 會開啟 [claude.ai 連接器](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai)目錄，而不是傳回摘要。當工作階段於互動式終端機中執行時，`reconnect`、`enable` 和 `disable` [子命令](/docs/zh-TW/commands#all-commands)在兩者上皆可使用。不指定伺服器名稱的 `/mcp reconnect` 會重試所有失敗或需要身分驗證的伺服器。若要在不使用選擇器的情況下授權 claude.ai 連接器，請參閱[從您的 shell 再次授權連接器](#authorize-a-connector-again-from-your-shell)。

382 * `/config`：從行動應用程式，傳遞 `key=value` 以設定設定，或不帶引數執行以列出您可以設定的金鑰。在網路上，`/config` 會改為開啟您設定的 Claude Code 部分，並忽略命令後的文字。382 * `/config`：從行動應用程式使用時，傳入 `key=value` 以變更設定，或不帶引數執行以列出您可以設定的設定鍵。在網頁上，`/config` 會改為開啟您設定中的 Claude Code 區段，並忽略命令後的文字。

383 * 在 Team 和 Enterprise 上，從行動裝置或網路執行的 `/usage-credits` 不會傳送[用量點數請求給您的管理員](/docs/zh-TW/costs#add-usage-credits-to-your-subscription)。傳送需要僅在互動 CLI 中出現的確認，因此命令會告訴您改為在那裡執行它。383 * 在 Team 和 Enterprise 方案中，從行動裝置或網頁執行 `/usage-credits` 不會向您的管理員傳送[用量點數請求](/docs/zh-TW/costs#add-usage-credits-to-your-subscription)。傳送需要一個僅在互動式 CLI 中出現的確認，因此該命令會告知您改在那裡執行。

384 * `/autocompact`，從 v2.1.221：將視窗大小作為引數傳遞，例如 `/autocompact 500k`。不帶引數時，它會列印目前的視窗大小作為文字，而不是開啟命令在終端機工作階段中顯示的對話框。384 * `/autocompact`，自 v2.1.221 起：以引數傳入視窗大小，例如 `/autocompact 500k`。不帶引數時，它會以文字輸出目前的視窗大小，而不是開啟該命令在終端機工作階段中顯示的對話框。

385 * `/advisor`，從 v2.1.260：將模型作為引數傳遞，例如 `/advisor opus`，或傳遞 `off` 以關閉顧問。兩種形式都僅適用於目前工作階段，並保持您儲存的預設值不變。不帶引數時，它會列印目前的顧問作為文字，而不是開啟選擇器。385 * `/advisor`，自 v2.1.260 起：以引數傳入模型，例如 `/advisor opus`，或傳入 `off` 以關閉 advisor。兩種形式都僅適用於目前的工作階段，不會變更您儲存的預設值。不帶引數時，它會以文字輸出目前的 advisor，而不是開啟選擇器。

386 * `/output-style`，從 v2.1.269：將風格名稱作為引數傳遞，例如 `/output-style concise`，或不帶引數執行以列出風格。從行動裝置和網路，您只能列出和選擇[內建風格](/docs/zh-TW/output-styles#built-in-output-styles)。若要使用[自訂風格](/docs/zh-TW/output-styles#create-a-custom-output-style)，請在工作階段本身中選擇它。386 * `/output-style`，自 v2.1.269 起：以引數傳入風格名稱，例如 `/output-style concise`，或不帶引數執行以列出各種風格。從行動裝置和網頁使用時，您只能列出和選擇[內建風格](/docs/zh-TW/output-styles#built-in-output-styles)。若要使用[自訂風格](/docs/zh-TW/output-styles#create-a-custom-output-style)，請在工作階段本身中選擇。

387 * `/focus`，從 v2.1.281：將 `on` 或 `off` 作為引數傳遞，例如 `/focus on`，或不帶引數執行以切換[焦點檢視](/docs/zh-TW/commands#all-commands)。兩種形式都僅適用於目前工作階段，並保持您儲存的選擇不變。387 * `/focus`，自 v2.1.281 起：以引數傳入 `on` 或 `off`，例如 `/focus on`，或不帶引數執行以切換[專注檢視](/docs/zh-TW/commands#all-commands)。兩種形式都僅適用於目前的工作階段，不會變更您儲存的選擇。

388

389<h2 id="authorize-a-connector-again-from-your-shell">

390 從您的 shell 重新授權連接器

391</h2>

392

393當您透過 Remote Control 操作的工作階段中，某個 claude.ai 連接器需要身分驗證時，無法從行動應用程式或網頁使用 `/mcp` 面板。請在執行該工作階段的機器上，從終端機取得授權連結，然後在您正在使用的裝置上開啟該連結。您無法從行動應用程式或網頁執行此命令。從那裡傳送、以 `!` 開頭的內容會作為訊息傳給 Claude，而不會在 [shell 模式](/docs/zh-TW/interactive-mode#shell-mode-with-prefix)中執行。

394

395<Steps>

396 <Step title="取得授權連結">

397 在執行該工作階段的機器上的終端機中（例如透過 SSH），執行 `claude mcp login`，並以引號括住連接器的名稱。連接器的名稱以 `claude.ai` 開頭，例如 Slack 連接器的名稱為 `claude.ai Slack`。以下命令會取得 Slack 連接器的連結：

398

399 ```bash theme={null}

400 claude mcp login "claude.ai Slack" --no-browser

401 ```

402

403 此命令會印出一個 claude.ai 連結並結束。請在瀏覽器中開啟該連結，並在 claude.ai 上完成授權。`--no-browser` 可防止此命令在該機器上開啟瀏覽器，因為該機器可能並非您正在使用的裝置。

404 </Step>

405

406 <Step title="在工作階段中使用連接器">

407 啟動新的工作階段，或在已執行中的工作階段內重新連線該連接器：

408

409 * **新的工作階段**：授權後啟動的工作階段會直接連線到該連接器，無需任何額外步驟。

410 * **執行中的工作階段**：在 Claude Code 提示字元中，或從行動應用程式或網頁，執行 `/mcp reconnect`，並使用相同的名稱，不加引號。若要確認您的工作階段是否接受從那裡傳送的此命令，請參閱[哪些命令可從行動裝置和網頁使用](#limitations)中的 `/mcp` 項目。

411

412 以下命令會重新連線 Slack 連接器：

413

414 ```text theme={null}

415 /mcp reconnect claude.ai Slack

416 ```

417

418 在終端機中，Claude Code 會印出 `Successfully reconnected to claude.ai Slack`。從行動應用程式或網頁執行時，回覆為 `Reconnected "claude.ai Slack".`

419 </Step>

420</Steps>

388 421

389<h2 id="troubleshooting">422<h2 id="troubleshooting">

390 疑難排解423 疑難排解

scheduled-tasks.md +21 −4

Details

191 抖動191 抖動

192</h3>192</h3>

193 193

194為了避免每個工作階段在同一牆上時刻點擊 API，排程器會為執行時間添加一個確定性偏移：194排程任務的實際執行時間可能與其排程所指定的時間不同。如果每個工作階段的任務都完全按照排程執行，許多任務就會在同一時刻呼叫 API，因此 Claude Code 會偏移每個任務的執行時間。重複執行的任務會延後執行，而排程在整點或半點的一次性任務則會稍微提前執行。

195 195

196* 重複執行的任務最多在排程時間後 30 分鐘執行（或對於執行頻率超過每小時的任務，最多為間隔的一半）。為 `:00` 排程的每小時工作可能在 `:00` 到 `:30` 之間的任何時間執行。196<h4 id="how-late-a-recurring-task-runs">

197* 為整點或半點排程的一次性任務最多提前執行 90 秒。197 重複執行的任務會延後多久

198</h4>

198 199

199偏移是從任務 ID 衍生的，所以相同的任務總是獲得相同的偏移。如果精確計時很重要，請選擇不是 `:00` 或 `:30` 的分鐘，例如 `3 9 * * *` 而不是 `0 9 * * *`，一次性抖動將不適用。200當您建立重複執行的任務時，Claude Code 會為其指定一個固定的延遲，並將該延遲加到每次執行上。延遲是根據任務的 ID 計算出來的，因此同一個任務每次都會延後相同的分鐘數，即使工作階段處於閒置且沒有其他任何內容在執行時也是如此。

201

202執行越頻繁的任務獲得的延遲越短，而 30 分鐘是任務可獲得的最長延遲。以下是一些常見排程的延遲範圍：

203

204| 任務執行頻率 | 延遲範圍 |

205| :- | :- |

206| 每 10 分鐘 | 0 到 5 分鐘 |

207| 每 30 分鐘 | 0 到 15 分鐘 |

208| 每小時，或頻率更低（例如每天） | 0 到 30 分鐘 |

209

210例如，`7,37 * * * *` 會將任務排程在 `:07` 和 `:37`，兩者相隔 30 分鐘，因此其延遲介於 0 到 15 分鐘之間。如果此任務的延遲為 14 分鐘，它會在每小時的 `:21` 和 `:51` 執行。將排程改為不同的分鐘會移動執行時間，但仍會在其上加上延遲。

211

212<h4 id="when-a-one-shot-task-runs-early">

213 一次性任務何時會提前執行

214</h4>

215

216排程在 `:00` 或 `:30` 的一次性任務最多會提前 90 秒執行。Claude Code 不會偏移排程在其他任何分鐘的一次性任務，因此當時間點很重要時，請避開整點和半點進行排程：使用 `3 9 * * *` 而不是 `0 9 * * *`。

200 217

201<h3 id="seven-day-expiry">218<h3 id="seven-day-expiry">

202 七天過期219 七天過期

security-guidance.md +12 −6

Details

74 74

75您可以通過 [添加自己的規則](#add-your-own-rules) 擴展每一層。內置檢查無法單獨移除，但您可以 [獨立禁用每一層](#disable-or-uninstall)。75您可以通過 [添加自己的規則](#add-your-own-rules) 擴展每一層。內置檢查無法單獨移除，但您可以 [獨立禁用每一層](#disable-or-uninstall)。

76 76

~~77<h3 id="on-each-file-edit">~~77<span id="on-each-file-edit" />

~~78 在每個檔案編輯上~~78

79<h3 id="checks-on-each-file-edit">

80 每次檔案編輯時的檢查

79</h3>81</h3>

80 82

81當 Claude 寫入檔案時，外掛程式會掃描新內容中的已知危險模式。這是一個沒有模型呼叫的模式匹配，因此不會增加使用成本。83當 Claude 寫入檔案時，外掛程式會掃描新內容中的已知危險模式。這是一個沒有模型呼叫的模式匹配，因此不會增加使用成本。

91 93

92您可以使用 `security-patterns.yaml` 檔案 [添加自己的模式](#add-custom-per-edit-patterns) 到此層。94您可以使用 `security-patterns.yaml` 檔案 [添加自己的模式](#add-custom-per-edit-patterns) 到此層。

93 95

~~94<h3 id="at-the-end-of-each-turn">~~96<span id="at-the-end-of-each-turn" />

~~95 在每個回合結束時~~97

98<h3 id="checks-at-the-end-of-each-turn">

99 每個回合結束時的檢查

96</h3>100</h3>

97 101

98一個回合是 Claude 響應的一輪：您發送一條消息，Claude 工作並回覆，回合結束。在每個回合之後，外掛程式計算工作樹中在回合期間更改的所有內容的 git diff，包括來自 Claude 的編輯工具、Bash 命令和子代理的更改，並將其發送到專注於安全的單獨 Claude 審查。審查在背景中執行，因此 Claude 的回覆不會延遲。如果審查發現問題，Claude 會被重新提示發現的內容，並作為後續行動解決它們。102一個回合是 Claude 響應的一輪：您發送一條消息，Claude 工作並回覆，回合結束。在每個回合之後，外掛程式計算工作樹中在回合期間更改的所有內容的 git diff，包括來自 Claude 的編輯工具、Bash 命令和子代理的更改，並將其發送到專注於安全的單獨 Claude 審查。審查在背景中執行，因此 Claude 的回覆不會延遲。如果審查發現問題，Claude 會被重新提示發現的內容，並作為後續行動解決它們。

107 111

108您可以直接在您的工作階段中看到發現和 Claude 的解決方案。審查涵蓋每個回合最多 30 個更改的檔案，並在最多連續三次後才讓位給您。112您可以直接在您的工作階段中看到發現和 Claude 的解決方案。審查涵蓋每個回合最多 30 個更改的檔案，並在最多連續三次後才讓位給您。

109 113

110<h3 id="on-each-commit-or-push-claude-makes">114<span id="on-each-commit-or-push-claude-makes" />

111 在 Claude 進行的每次提交或推送上115

116<h3 id="checks-on-each-commit-or-push-claude-makes">

117 Claude 每次提交或推送時的檢查

112</h3>118</h3>

113 119

114當 Claude 通過其 Bash 工具執行 `git commit` 或 `git push` 時，外掛程式在背景中執行對變更的更深層代理審查。此審查讀取周圍程式碼，包括呼叫者、清理程式和相關檔案，以決定發現是否真實，然後再報告它。額外的上下文使假陽性在看起來危險但在您的程式碼庫中安全的模式上保持低位。120當 Claude 通過其 Bash 工具執行 `git commit` 或 `git push` 時，外掛程式在背景中執行對變更的更深層代理審查。此審查讀取周圍程式碼，包括呼叫者、清理程式和相關檔案，以決定發現是否真實，然後再報告它。額外的上下文使假陽性在看起來危險但在您的程式碼庫中安全的模式上保持低位。

self-hosted-environments-configuration.md +16 −3

Details

403 403

404* 位於標準系統路徑的企業範圍[受管 MCP 檔案](/docs/zh-TW/managed-mcp)：Linux runner 主機上為 `/etc/claude-code/managed-mcp.json`，macOS 主機上為 `/Library/Application Support/ClaudeCode/managed-mcp.json`。適用於僅允許載入管理員所列伺服器的鎖定機群。優先順序規則請參閱[使用 managed-mcp.json 進行獨占控制](/docs/zh-TW/managed-mcp#exclusive-control-with-managed-mcp-json)。當此檔案存在於 runner 主機上時，Claude Code 會略過 Anthropic 控制平面傳遞給工作階段的 MCP 伺服器（包括 claude.ai 連接器），並在工作階段子程序的 stderr 上以警告列出它們，runner 會以 `debug` 日誌層級記錄這些警告。在 v2.1.229 之前，這些工作階段會在啟動時以 `You cannot dynamically configure MCP servers when an enterprise MCP config is present` 結束。404* 位於標準系統路徑的企業範圍[受管 MCP 檔案](/docs/zh-TW/managed-mcp)：Linux runner 主機上為 `/etc/claude-code/managed-mcp.json`，macOS 主機上為 `/Library/Application Support/ClaudeCode/managed-mcp.json`。適用於僅允許載入管理員所列伺服器的鎖定機群。優先順序規則請參閱[使用 managed-mcp.json 進行獨占控制](/docs/zh-TW/managed-mcp#exclusive-control-with-managed-mcp-json)。當此檔案存在於 runner 主機上時，Claude Code 會略過 Anthropic 控制平面傳遞給工作階段的 MCP 伺服器（包括 claude.ai 連接器），並在工作階段子程序的 stderr 上以警告列出它們，runner 會以 `debug` 日誌層級記錄這些警告。在 v2.1.229 之前，這些工作階段會在啟動時以 `You cannot dynamically configure MCP servers when an enterprise MCP config is present` 結束。

405* runner 主機上[受管設定](/docs/zh-TW/managed-settings)中的 [`managedMcpServers`](/docs/zh-TW/settings-reference#managedmcpservers) 鍵：提供 HTTP 和 SSE 伺服器而不取得獨占控制，因此來自其他來源的伺服器仍會載入。需要 Claude Code v2.1.259 或更新版本。405* runner 主機上[受管設定](/docs/zh-TW/managed-settings)中的 [`managedMcpServers`](/docs/zh-TW/settings-reference#managedmcpservers) 鍵：提供 HTTP 和 SSE 伺服器而不取得獨占控制，因此來自其他來源的伺服器仍會載入。需要 Claude Code v2.1.259 或更新版本。

406* `<repo>/.mcp.json`：專案範圍。將此檔案提交到儲存庫；其伺服器在雲端工作階段中會自動核准。406* `<repo>/.mcp.json`：專案範圍。將此檔案提交到儲存庫；其伺服器在雲端工作階段中會自動核准。在包含多個儲存庫的工作階段中，[最多只會載入一個儲存庫的檔案](#repository-settings-in-sessions-with-several-repositories)。

407 407

408當您的組織啟用連接器傳遞時，Anthropic 的控制平面會透過伺服器提供的 MCP 設定，將您在 claude.ai 上設定的連接器傳遞給以互動方式建立的工作階段，並經由 `api.anthropic.com` 路由。以程式化方式建立的工作階段（例如 [CLI 派送](/docs/zh-TW/self-hosted-environments-testing#run-the-test-loop)）不會接收連接器傳遞；請改為透過本節列出的任何其他來源為它們提供 MCP 伺服器。子程序的 OAuth token 不具備直接擷取連接器的範圍，因此子程序本身不會嘗試該擷取；傳遞是由伺服器驅動的。408當您的組織啟用連接器傳遞時，Anthropic 的控制平面會透過伺服器提供的 MCP 設定，將您在 claude.ai 上設定的連接器傳遞給以互動方式建立的工作階段，並經由 `api.anthropic.com` 路由。以程式化方式建立的工作階段（例如 [CLI 派送](/docs/zh-TW/self-hosted-environments-testing#run-the-test-loop)）不會接收連接器傳遞；請改為透過本節列出的任何其他來源為它們提供 MCP 伺服器。子程序的 OAuth token 不具備直接擷取連接器的範圍，因此子程序本身不會嘗試該擷取；傳遞是由伺服器驅動的。

409 409

542exit 0542exit 0

543```543```

544 544

545掛鉤在會話結束前提示 Claude 提交並推送，當目錄不是 git 儲存庫或沒有遠端時保持沉默。545此 hook 會在工作階段結束前提示 Claude 提交並推送，並在目錄不是 git 儲存庫或沒有遠端時保持沉默。若工作階段包含多個儲存庫，請參閱 [`$CLAUDE_PROJECT_DIR` 所指的目錄](#repository-settings-in-sessions-with-several-repositories)。

546 546

547<h2 id="permissions-and-tool-approval">547<h2 id="permissions-and-tool-approval">

548 權限和工具核准548 權限和工具核准

571 571

572設定 `SELF_HOSTED_RUNNER_HOST_CONFIG_DIR` 以從不同路徑植入，或將其指向空目錄以停用植入。572設定 `SELF_HOSTED_RUNNER_HOST_CONFIG_DIR` 以從不同路徑植入，或將其指向空目錄以停用植入。

573 573

574儲存庫提交的 `.claude/settings.json` 會作為專案設定疊加於其上。工作階段也會從執行器映像中的標準系統路徑讀取 [`managed-settings.json`](/docs/zh-TW/settings#where-settings-live)。其設定鍵是否與[伺服器受管設定](/docs/zh-TW/server-managed-settings)一併套用，取決於 [Claude Code 如何組合受管來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)：預設情況下，當您的組織傳遞任何伺服器受管設定鍵時，工作階段會忽略執行器映像的檔案，但 [Claude Code 從每個管理來源讀取的設定鍵](/docs/zh-TW/managed-settings#keys-read-from-every-admin-source)除外，例如 `env` 區塊、沙箱鎖定、沙箱二進位檔路徑和 `forceRemoteSettingsRefresh`。請參閱[設定優先順序](/docs/zh-TW/settings#settings-precedence)。574儲存庫提交的 `.claude/settings.json` 會作為專案設定疊加於其上。在包含多個儲存庫的工作階段中，[最多只有一個儲存庫的檔案會生效](#repository-settings-in-sessions-with-several-repositories)。工作階段也會從執行器映像中的標準系統路徑讀取 [`managed-settings.json`](/docs/zh-TW/settings#where-settings-live)。其設定鍵是否與[伺服器受管設定](/docs/zh-TW/server-managed-settings)一併套用，取決於 [Claude Code 如何組合受管來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)：預設情況下，當您的組織傳遞任何伺服器受管設定鍵時，工作階段會忽略執行器映像的檔案，但 [Claude Code 從每個管理來源讀取的設定鍵](/docs/zh-TW/managed-settings#keys-read-from-every-admin-source)除外，例如 `env` 區塊、沙箱鎖定、沙箱二進位檔路徑和 `forceRemoteSettingsRefresh`。請參閱[設定優先順序](/docs/zh-TW/settings#settings-precedence)。

575 575

576當 Anthropic 的控制平面為工作階段提供 [Claude Code hook](/docs/zh-TW/hooks) 時，執行器會將其與您自己的設定並存安裝，而非覆寫您的設定。需要 Claude Code v2.1.229 或更新版本。576當 Anthropic 的控制平面為工作階段提供 [Claude Code hook](/docs/zh-TW/hooks) 時，執行器會將其與您自己的設定並存安裝，而非覆寫您的設定。需要 Claude Code v2.1.229 或更新版本。

577 577

583 583

584執行器對主機 `~/.claude/` 的快照不包含 `projects/` 目錄。自動記憶的預設儲存位置就位於該目錄下。如果您將記憶檔案放在那裡，執行器不會將其植入工作階段，這些檔案也不會開啟自動記憶。584執行器對主機 `~/.claude/` 的快照不包含 `projects/` 目錄。自動記憶的預設儲存位置就位於該目錄下。如果您將記憶檔案放在那裡，執行器不會將其植入工作階段，這些檔案也不會開啟自動記憶。

585 585

586<h3 id="repository-settings-in-sessions-with-several-repositories">

587 包含多個儲存庫之工作階段中的儲存庫設定

588</h3>

589

590在包含多個儲存庫的工作階段中，Claude Code 會從工作階段啟動時所在的目錄讀取專案設定，因此最多只有一個儲存庫的 `.claude/settings.json` 會作為專案設定生效。在其他儲存庫檔案中定義的 hook 不會執行，其中的拒絕規則不會套用，其 `env` 也不會被設定。

591

592* **`--capacity 1`（預設值）搭配內建簽出**：工作階段會在其儲存庫清單中的第一個儲存庫啟動。該儲存庫的 `.claude/settings.json` 會作為專案設定生效，其 `.mcp.json` 也會載入，其他儲存庫的則不會。

593* **`--capacity` 大於一，或使用 [`checkout` hook](#checkout)**：工作階段會在包含各簽出內容的個別工作階段目錄中啟動。沒有任何儲存庫的 `.claude/settings.json` 會作為專案設定生效，沒有任何儲存庫的 `.mcp.json` 會載入，且 hook 命令中的 [`$CLAUDE_PROJECT_DIR`](/docs/zh-TW/hooks#reference-scripts-by-path) 為該目錄，而非某個簽出內容。

594

595無論工作階段在何處啟動，每個儲存庫的 `CLAUDE.md` 和 skill 都會載入。執行器會將每個儲存庫作為[額外目錄](/docs/zh-TW/permissions#additional-directories-grant-file-access-not-configuration)傳遞給 Claude Code，因此 Claude Code 也會從每個儲存庫的 `.claude/settings.json` 讀取 `enabledPlugins` 和 `extraKnownMarketplaces` 設定鍵。

596

597若要在每個工作階段中執行 hook 或套用權限規則，請將其放在執行器主機上的 `~/.claude/settings.json` 中。無論工作階段在何處啟動，執行器都會[將主機檔案植入每個工作階段](#how-each-session’s-config-is-assembled)。在 `Read` 或 `Edit` 規則中，請將路徑寫成 `//` 絕對路徑或 `~/` 相對於家目錄的[模式](/docs/zh-TW/permissions#read-and-edit)，因為其他模式會以設定來源或目前目錄為基準。

598

586<h3 id="repository-committed-permission-rules">599<h3 id="repository-committed-permission-rules">

587 儲存庫提交的權限規則600 儲存庫提交的權限規則

588</h3>601</h3>

server-managed-settings.md +4 −0

Details

92 92

93 <Step title="儲存並部署">93 <Step title="儲存並部署">

94 儲存您的變更。Claude Code 用戶端在下次啟動或每小時輪詢週期時會接收更新的設定。94 儲存您的變更。Claude Code 用戶端在下次啟動或每小時輪詢週期時會接收更新的設定。

96 編輯器會根據已發布的 Claude Code 設定 JSON schema 檢查您的 JSON。如果在可解析的 JSON 中發現問題，它會顯示警告並變更儲存按鈕的標籤。當設定已儲存時，標籤為 **Update with errors**；尚未儲存任何設定時，標籤為 **Add with errors**。該按鈕仍會儲存，因為 schema 警告不會阻止儲存。

98 schema [可能落後於最新版本](/docs/zh-TW/settings#edit-a-settings-file)，因此編輯器可能會標記[設定參考](/docs/zh-TW/settings-reference#all-settings)中有記載的鍵或值。Claude Code 會接收您儲存的鍵和值，並在載入時執行[其自身的驗證](#invalid-entries-in-delivered-settings)。

95 </Step>99 </Step>

96</Steps>100</Steps>

97 101

settings.md +2 −2

Details

521 521

522在 Claude Desktop 應用程式中於您的機器上執行的 [Cowork](https://claude.com/docs/cowork/overview) 工作階段中，Claude Code 不會從 claude.ai 管理主控台擷取伺服器受管設定，且它會讀取部署到您裝置的政策，除非您組織的 Claude Desktop 設定設定了 `requireCoworkFullVmSandbox`。[政策適用的位置和時間](/docs/zh-TW/managed-settings#where-and-when-a-policy-applies)涵蓋 Cowork 和雲端工作階段。522在 Claude Desktop 應用程式中於您的機器上執行的 [Cowork](https://claude.com/docs/cowork/overview) 工作階段中，Claude Code 不會從 claude.ai 管理主控台擷取伺服器受管設定，且它會讀取部署到您裝置的政策，除非您組織的 Claude Desktop 設定設定了 `requireCoworkFullVmSandbox`。[政策適用的位置和時間](/docs/zh-TW/managed-settings#where-and-when-a-policy-applies)涵蓋 Cowork 和雲端工作階段。

523 523

524如果您是管理員，[為您的組織設定 Claude Code](/docs/zh-TW/admin-setup) 會逐步說明選擇要強制執行的內容，而[部署受管設定](/docs/zh-TW/managed-settings)涵蓋傳遞以及如何確認政策生效。524如果您是管理員，[為您的組織設定 Claude Code](/docs/zh-TW/admin-setup) 會逐步說明選擇要強制執行的內容，而[部署受管設定](/docs/zh-TW/managed-settings)涵蓋傳遞以及如何確認政策生效。關於 claude.ai 管理主控台中受管設定編輯器可能顯示的警告，請參閱[設定伺服器受管設定](/docs/zh-TW/server-managed-settings#configure-server-managed-settings)。

525 525

526<h2 id="change-a-setting">526<h2 id="change-a-setting">

527 變更設定527 變更設定

809 809

810[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)在[雲端環境](/docs/zh-TW/cloud-environments)中執行，在您儲存庫的新複製上，而不是在您的機器上。這改變了哪些設定到達它：810[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)在[雲端環境](/docs/zh-TW/cloud-environments)中執行，在您儲存庫的新複製上，而不是在您的機器上。這改變了哪些設定到達它：

811 811

812* **共享專案設定**（`.claude/settings.json`）：在一個儲存庫的工作階段中讀取，因為檔案是複製的一部分，且工作階段在其內部啟動。在那裡提交設定以在這些工作階段中應用它。具有多個儲存庫的工作階段在複製上方啟動，並從每個儲存庫的 `.claude/settings.json` 只讀取 `enabledPlugins` 和 `extraKnownMarketplaces` 金鑰，而不是權限規則、hooks、`env` 或其他金鑰。這些兩個金鑰宣告的市集和外掛仍然[不會在雲端工作階段中載入](/docs/zh-TW/cloud-environments#what-carries-over-from-your-setup)。812* **共享專案設定**（`.claude/settings.json`）：在一個儲存庫的工作階段中讀取，因為檔案是複製的一部分，且工作階段在其內部啟動。在那裡提交設定以在這些工作階段中應用它。在 Anthropic 託管的環境中，具有多個儲存庫的工作階段在複製上方啟動，並從每個儲存庫的 `.claude/settings.json` 只讀取 `enabledPlugins` 和 `extraKnownMarketplaces` 金鑰，而不是權限規則、hook、`env` 或其他金鑰。這兩個金鑰宣告的市集和外掛仍然[不會在雲端工作階段中載入](/docs/zh-TW/cloud-environments#what-carries-over-from-your-setup)。若為自託管環境，請參閱[適用哪個儲存庫的設定](/docs/zh-TW/self-hosted-environments-configuration#repository-settings-in-sessions-with-several-repositories)。

813* **使用者和專案本機設定**（`~/.claude/settings.json` 和 `.claude/settings.local.json`）：未讀取。兩者都保留在您的機器上，本機檔案不在複製中。813* **使用者和專案本機設定**（`~/.claude/settings.json` 和 `.claude/settings.local.json`）：未讀取。兩者都保留在您的機器上，本機檔案不在複製中。

814* **受管設定**：您組織的[伺服器管理設定](/docs/zh-TW/server-managed-settings)會到達雲端工作階段；您裝置上的 `managed-settings.json` 檔案或 MDM 設定檔不會。[表面涵蓋範圍](/docs/zh-TW/model-config#surface-coverage)列出哪些雲端工作階段接收它們。[自託管環境](/docs/zh-TW/self-hosted-environments)也讀取其執行器映像中的受管設定檔案。[Claude Code 如何合併受管來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)說明該檔案何時適用。814* **受管設定**：您組織的[伺服器管理設定](/docs/zh-TW/server-managed-settings)會到達雲端工作階段；您裝置上的 `managed-settings.json` 檔案或 MDM 設定檔不會。[表面涵蓋範圍](/docs/zh-TW/model-config#surface-coverage)列出哪些雲端工作階段接收它們。[自託管環境](/docs/zh-TW/self-hosted-environments)也讀取其執行器映像中的受管設定檔案。[Claude Code 如何合併受管來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)說明該檔案何時適用。

815* **`/config`**：在您的瀏覽器中的 claude.ai/code，開啟您的 claude.ai 設定的 Claude Code 部分而不是變更值。若要為雲端工作階段變更設定，請在環境上設定[環境變數](/docs/zh-TW/cloud-environments#set-environment-variables)，或在具有一個儲存庫的工作階段中，將金鑰提交到該儲存庫的 `.claude/settings.json`。815* **`/config`**：在您的瀏覽器中的 claude.ai/code，開啟您的 claude.ai 設定的 Claude Code 部分而不是變更值。若要為雲端工作階段變更設定，請在環境上設定[環境變數](/docs/zh-TW/cloud-environments#set-environment-variables)，或在具有一個儲存庫的工作階段中，將金鑰提交到該儲存庫的 `.claude/settings.json`。

setup.md +20 −10

Details

638 638

639若要移除 Claude Code，請按照您的安裝方法的說明進行。如果之後 `claude` 仍然執行，您可能有第二個安裝或來自舊版安裝程式的遺留 shell 別名。請參閱[檢查衝突的安裝](/docs/zh-TW/troubleshoot-install#check-for-conflicting-installations)以找到並移除它。639若要移除 Claude Code，請按照您的安裝方法的說明進行。如果之後 `claude` 仍然執行，您可能有第二個安裝或來自舊版安裝程式的遺留 shell 別名。請參閱[檢查衝突的安裝](/docs/zh-TW/troubleshoot-install#check-for-conflicting-installations)以找到並移除它。

640 640

641<h3 id="native-installation">641<span id="native-installation" />

642 原生安裝642

643<h3 id="uninstall-a-native-installation">

644 卸載原生安裝

643</h3>645</h3>

644 646

645移除 Claude Code 二進位檔案和版本檔案：647移除 Claude Code 二進位檔案和版本檔案：

660 </Tab>662 </Tab>

661</Tabs>663</Tabs>

662 664

663<h3 id="homebrew-installation">665<span id="homebrew-installation" />

664 Homebrew 安裝666

667<h3 id="uninstall-with-homebrew">

668 使用 Homebrew 卸載

665</h3>669</h3>

666 670

667移除您安裝的 Homebrew cask。如果您安裝了穩定版 cask：671移除您安裝的 Homebrew cask。如果您安裝了穩定版 cask：

676brew uninstall --cask claude-code@latest680brew uninstall --cask claude-code@latest

677```681```

678 682

679<h3 id="winget-installation">683<span id="winget-installation" />

680 WinGet 安裝684

685<h3 id="uninstall-with-winget">

686 使用 WinGet 卸載

681</h3>687</h3>

682 688

683移除 WinGet 套件：689移除 WinGet 套件：

686winget uninstall Anthropic.ClaudeCode692winget uninstall Anthropic.ClaudeCode

687```693```

688 694

689<h3 id="apt-/-dnf-/-apk">695<span id="apt-/-dnf-/-apk" />

690 apt / dnf / apk696

697<h3 id="uninstall-with-apt-dnf-or-apk">

698 使用 apt、dnf 或 apk 卸載

691</h3>699</h3>

692 700

693移除套件和儲存庫配置：701移除套件和儲存庫配置：

716 </Tab>724 </Tab>

717</Tabs>725</Tabs>

718 726

719<h3 id="npm">727<span id="npm" />

720 npm728

729<h3 id="uninstall-with-npm">

730 使用 npm 卸載

721</h3>731</h3>

722 732

723移除全域 npm 套件：733移除全域 npm 套件：

skills.md +2 −0

Details

94| `migrate` | 將您現有的 Claude API 程式碼更新到較新的模型 | 早於 v2.1.221 |94| `migrate` | 將您現有的 Claude API 程式碼更新到較新的模型 | 早於 v2.1.221 |

96| `managed-agents-onboard` | 逐步完成建立新的受管代理 | 早於 v2.1.221 |96| `managed-agents-onboard` | 逐步完成建立新的受管代理 | 早於 v2.1.221 |

97| `managed-agents-onboard <url>` | 建立該 URL 頁面所描述的 Managed Agent，例如 [Managed Agents 文件](https://platform.claude.com/docs/en/managed-agents/overview)中的頁面 | v2.1.290 或更新版本 |

98| `managed-agents-onboard <quickstart-name>` | 建立 Console 的其中一個快速入門範本，例如 `deep-researcher`。如果您提供的單一字詞不是範本名稱，Claude 會列出有效的名稱 | v2.1.290 或更新版本 |

sub-agents.md +4 −2

Details

609主對話的權限模式決定 Claude Code 是否使用您設定的值：609主對話的權限模式決定 Claude Code 是否使用您設定的值：

610 610

611* 當主對話在 `bypassPermissions`、`acceptEdits` 或[自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)中時，子代理在該相同模式中執行，Claude Code 忽略您設定的 `permissionMode`。在自動模式下，分類器使用主對話的阻止和允許規則評估子代理的工具呼叫。當子代理完成時，分類器也在報告被傳遞之前檢查其工作和最終報告，如[自動模式如何處理子代理](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)所述。611* 當主對話在 `bypassPermissions`、`acceptEdits` 或[自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)中時，子代理在該相同模式中執行，Claude Code 忽略您設定的 `permissionMode`。在自動模式下，分類器使用主對話的阻止和允許規則評估子代理的工具呼叫。當子代理完成時，分類器也在報告被傳遞之前檢查其工作和最終報告，如[自動模式如何處理子代理](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)所述。

612* 當主對話在 `default`、`dontAsk` 或 `plan` 模式中時，子代理在您設定的權限模式中執行，除了 `bypassPermissions`。宣告 `bypassPermissions` 的子代理保持主對話的模式。`bypassPermissions` 例外需要 Claude Code v2.1.267 或更新版本。612* 當主對話處於 `default`、`dontAsk` 或 `plan` 模式時，subagent 會以您設定的權限模式執行。在以下情況下，它會改為保持主對話的權限模式：

613 * 您設定了 `bypassPermissions`。`bypassPermissions` 例外需要 Claude Code v2.1.267 或更新版本。

614 * 您設定了 `auto`，但 subagent [無法使用自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)，例如設定檔設定了 [`disableAutoMode`](/docs/zh-TW/settings-reference#disableautomode)，或 subagent 的模型不支援自動模式。

613 615

614`permissionMode` 接受這些值，以及 `manual` 作為 `default` 的別名：616`permissionMode` 接受這些值，以及 `manual` 作為 `default` 的別名：

615 617

640Implement API endpoints. Follow the conventions and patterns from the preloaded skills.642Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

641```643```

642 644

643每個列出的技能的完整內容在啟動時注入子代理的上下文。此欄位控制哪些技能被預載入，而不是子代理可以存取哪些技能：沒有它，子代理仍然可以在執行期間透過 Skill 工具發現和叫用專案、使用者和 plugin 技能。若要防止子代理完全叫用技能，從 [`tools`](#available-tools) 列表中省略 `Skill` 或將其新增到 `disallowedTools`。645每個列出之 skill 的完整內容會在啟動時注入 subagent 的上下文，最多為清單中前 32 個不重複的名稱。此欄位控制哪些 skill 會被預先載入，而不是 subagent 可以存取哪些 skill：沒有它，subagent 仍可在執行期間透過 Skill 工具探索並叫用專案、使用者和外掛 skill。若要完全禁止 subagent 叫用 skill，請從 [`tools`](#available-tools) 清單中省略 `Skill`，或將其新增到 `disallowedTools`。

644 646

645您無法預先載入設定了 [`disable-model-invocation: true`](/docs/zh-TW/skills#control-who-invokes-a-skill) 的 skill，因為預先載入取自 Claude 可叫用的同一組 skill。這包括內建的 `/verify` skill，Claude 無法自行執行它。647您無法預先載入設定了 [`disable-model-invocation: true`](/docs/zh-TW/skills#control-who-invokes-a-skill) 的 skill，因為預先載入取自 Claude 可叫用的同一組 skill。這包括內建的 `/verify` skill，Claude 無法自行執行它。

646 648

tools-reference.md +1 −1

Details

666 666

667* WebFetch 拒絕 `localhost` 和任何其他沒有點的主機名稱，例如裸露的內部網路名稱，在發出請求之前。它[返回的錯誤](/docs/zh-TW/errors#webfetch-cannot-fetch-localhost)告訴 Claude 改為透過 Bash 使用 `curl` 來到達本機伺服器。667* WebFetch 拒絕 `localhost` 和任何其他沒有點的主機名稱，例如裸露的內部網路名稱，在發出請求之前。它[返回的錯誤](/docs/zh-TW/errors#webfetch-cannot-fetch-localhost)告訴 Claude 改為透過 Bash 使用 `curl` 來到達本機伺服器。

668* HTTP URL 會自動升級為 HTTPS。668* HTTP URL 會自動升級為 HTTPS。

669* 大型頁面會在處理前被截斷至固定字元限制。669* WebFetch 每次呼叫最多讀取頁面內容的 100,000 個字元。在 Claude Code v2.1.290 或更新版本上，較長頁面的結果會告訴 Claude 有多少內容未被讀取，讓 Claude 可以擷取下一部分。

670* WebFetch 預設會快取每個回應 15 分鐘，所以重複擷取相同 URL 會快速返回。在 Claude Code v2.1.233 或更新版本上，設定 [`CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS`](/docs/zh-TW/env-vars#variables) 以變更 WebFetch 保留每個回應的時間長度。670* WebFetch 預設會快取每個回應 15 分鐘，所以重複擷取相同 URL 會快速返回。在 Claude Code v2.1.233 或更新版本上，設定 [`CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS`](/docs/zh-TW/env-vars#variables) 以變更 WebFetch 保留每個回應的時間長度。

671* 一個頁面如果在五分鐘內未完成下載（包括 WebFetch 跟隨的任何重新導向），會因為截止時間錯誤而失敗。在 Claude Code v2.1.268 或更新版本上，設定 [`CLAUDE_CODE_WEBFETCH_DEADLINE_MS`](/docs/zh-TW/env-vars#variables) 以變更限制，或設定為 `0` 以移除它。671* 一個頁面如果在五分鐘內未完成下載（包括 WebFetch 跟隨的任何重新導向），會因為截止時間錯誤而失敗。在 Claude Code v2.1.268 或更新版本上，設定 [`CLAUDE_CODE_WEBFETCH_DEADLINE_MS`](/docs/zh-TW/env-vars#variables) 以變更限制，或設定為 `0` 以移除它。

672* 當 URL 重新導向到不同的主機時，WebFetch 會返回一個文字結果，命名原始 URL 和重新導向目標，而不是跟隨它。Claude 隨後會使用第二個 WebFetch 呼叫擷取新 URL。672* 當 URL 重新導向到不同的主機時，WebFetch 會返回一個文字結果，命名原始 URL 和重新導向目標，而不是跟隨它。Claude 隨後會使用第二個 WebFetch 呼叫擷取新 URL。

troubleshoot-install.md +191 −29

Details

4 4

5# 排除安裝和登入問題5# 排除安裝和登入問題

6 6

~~7> 修復安裝或登入 Claude Code 時的 command not found、PATH、權限、網路和身份驗證錯誤。~~7> 修復安裝或登入 Claude Code 時的 command not found、PATH、權限、網路和身分驗證錯誤。

8 8

9如果安裝失敗或無法登入，請在下方找到您的錯誤。如需 Claude Code 正常運作後的執行時問題，請參閱[排除故障](/docs/zh-TW/troubleshooting)。如需設定問題（例如設定未套用或 hooks 未觸發），請參閱[偵錯您的設定](/docs/zh-TW/debug-your-config)。9如果安裝失敗或無法登入，請在下方找到您的錯誤。如需 Claude Code 正常運作後的執行時問題，請參閱[疑難排解](/docs/zh-TW/troubleshooting)。如需設定問題（例如設定未套用或 hook 未觸發），請參閱[偵錯您的設定](/docs/zh-TW/debug-your-config)。

10 10

11<h2 id="find-your-error">11<h2 id="find-your-error">

12 找到您的錯誤12 找到您的錯誤

17| 您看到的內容 | 解決方案 |17| 您看到的內容 | 解決方案 |

18| :- | :- |18| :- | :- |

19| `command not found: claude` 或 `'claude' is not recognized` | [修復您的 PATH](#command-not-found-claude-after-installation) |19| `command not found: claude` 或 `'claude' is not recognized` | [修復您的 PATH](#command-not-found-claude-after-installation) |

20| `Native installation exists but ... is not in your PATH` | [將安裝目錄新增到您的 PATH](#verify-your-path) |

21| `where.exe claude` 傳回 `INFO: Could not find files for the given pattern(s).` | [檢查是否已安裝 Claude Code](#check-for-conflicting-installations) |

22| `zsh: permission denied: /Users/you/.zshrc` 或 `bash: /home/you/.bashrc: Permission denied` | [讓您的 shell 設定檔可寫入](#permission-denied-when-adding-to-your-path) |

20| `syntax error near unexpected token '<'` | [安裝指令碼傳回 HTML](#install-script-returns-html-instead-of-a-shell-script) |23| `syntax error near unexpected token '<'` | [安裝指令碼傳回 HTML](#install-script-returns-html-instead-of-a-shell-script) |

24| CMD 中出現 `< was unexpected at this time` | [安裝指令碼傳回 HTML](#install-script-returns-html-instead-of-a-shell-script) |

25| `The term 'System.Xml.XmlDocument' is not recognized` | [安裝指令碼傳回 HTML](#install-script-returns-html-instead-of-a-shell-script) |

21| `curl: (22) The requested URL returned error: 403` | [安裝指令碼傳回 403](#install-script-returns-html-instead-of-a-shell-script) |26| `curl: (22) The requested URL returned error: 403` | [安裝指令碼傳回 403](#install-script-returns-html-instead-of-a-shell-script) |

22| `curl: (23)` 或 `curl: (56) Failure writing output to destination` | [檢查連線或使用替代安裝程式](#curl-56-failure-writing-output-to-destination) |27| `curl: (23)` 或 `curl: (56) Failure writing output to destination` | [檢查連線或使用替代安裝程式](#curl-56-failure-writing-output-to-destination) |

29| `Installation was killed before it could finish` | [釋放記憶體，然後重新執行安裝程式](#installation-was-killed-before-it-could-finish) |

24| `Raw mode is not supported` 安裝期間 | [重新執行安裝程式](#raw-mode-is-not-supported-during-install) |30| `Raw mode is not supported` 安裝期間 | [重新執行安裝程式](#raw-mode-is-not-supported-during-install) |

25| 安裝期間出現 `EACCES: permission denied` | [修復安裝目錄的權限](#permission-errors-during-installation) |31| 安裝期間出現 `EACCES: permission denied` | [修復安裝目錄的權限](#permission-errors-during-installation) |

26| `TLS connect error` 或 `SSL/TLS secure channel` | [更新 CA 憑證](#tls-or-ssl-connection-errors) |32| `TLS connect error` 或 `SSL/TLS secure channel` | [更新 CA 憑證](#tls-or-ssl-connection-errors) |

34| `Failed to fetch version` 或無法連線到下載伺服器 | [檢查網路和代理伺服器設定](#check-network-connectivity) |

35| `The connection dropped while downloading the update` 或 `Download timed out: exceeded the total deadline` | [再次執行更新或設定您的代理伺服器](#the-connection-dropped-while-downloading-the-update) |

28| `irm is not recognized` 或 `The token '&&' is not a valid statement separator` | [在您的 shell 上使用正確的命令](#wrong-install-command-on-windows) |36| `irm is not recognized` 或 `The token '&&' is not a valid statement separator` | [在您的 shell 上使用正確的命令](#wrong-install-command-on-windows) |

29| `Cask 'claude-code' is unavailable: No Cask with this name exists` | [更新 Homebrew](#homebrew-cask-unavailable-or-outdated) |37| `Cask 'claude-code' is unavailable: No Cask with this name exists` | [更新 Homebrew](#homebrew-cask-unavailable-or-outdated) |

38| `Cask 'claude-code@latest' is not installed` | [升級您安裝的 cask](#cask-is-not-installed) |

30| `'bash' is not recognized as the name of a cmdlet` | [使用 Windows 安裝程式命令](#wrong-install-command-on-windows) |39| `'bash' is not recognized as the name of a cmdlet` | [使用 Windows 安裝程式命令](#wrong-install-command-on-windows) |

31| `A parameter cannot be found that matches parameter name 'fsSL'` | [使用 Windows 安裝程式命令](#wrong-install-command-on-windows) |40| `A parameter cannot be found that matches parameter name 'fsSL'` | [使用 Windows 安裝程式命令](#wrong-install-command-on-windows) |

32| `Claude Code on Windows requires either Git for Windows (for bash) or PowerShell` | [安裝 shell](#claude-code-on-windows-requires-either-git-for-windows-for-bash-or-powershell) |41| `Claude Code on Windows requires either Git for Windows (for bash) or PowerShell` | [安裝 shell](#claude-code-on-windows-requires-either-git-for-windows-for-bash-or-powershell) |

36| `Illegal instruction` | [架構或 CPU 指令集不相符](#illegal-instruction) |45| `Illegal instruction` | [架構或 CPU 指令集不相符](#illegal-instruction) |

37| WSL 中的 `cannot execute binary file: Exec format error` | [WSL1 原生二進位回歸](#exec-format-error-on-wsl1) |46| WSL 中的 `cannot execute binary file: Exec format error` | [WSL1 原生二進位回歸](#exec-format-error-on-wsl1) |

38| 工作階段執行期間出現 `Bus error` 或 `oh no: Bun has crashed` | [保持可執行檔可讀取](#bus-error-while-a-session-is-running) |47| 工作階段執行期間出現 `Bus error` 或 `oh no: Bun has crashed` | [保持可執行檔可讀取](#bus-error-while-a-session-is-running) |

40| macOS 上的 `dyld: Symbol not found`、`dyld: cannot load` 或 `Abort trap` | [二進位不相容](#dyld-cannot-load-on-macos) |49| macOS 上的 `dyld: Symbol not found`、`dyld: cannot load` 或 `Abort trap` | [二進位不相容](#dyld-cannot-load-on-macos) |

41| `claude update` 在 `Checking for updates` 後掛起，或 `claude doctor` 掛起且無輸出 | [移動 shell 設定路徑上的目錄](#claude-update-or-claude-doctor-hangs) |50| `claude update` 在 `Checking for updates` 後掛起，或 `claude doctor` 掛起且無輸出 | [移動 shell 設定路徑上的目錄](#claude-update-or-claude-doctor-hangs) |

42| `Invoke-Expression` 或 `iex` 解析錯誤引用 HTML 標籤或 CSS，或 `ParserError` 搭配 `ParseException` | [安裝指令碼傳回 HTML](#install-script-returns-html-instead-of-a-shell-script) |51| `Invoke-Expression` 或 `iex` 解析錯誤引用 HTML 標籤或 CSS，或 `ParserError` 搭配 `ParseException` | [安裝指令碼傳回 HTML](#install-script-returns-html-instead-of-a-shell-script) |

43| `running scripts is disabled on this system` 或 `PSSecurityException` | [允許 npm shims 執行](#running-scripts-is-disabled-on-this-system) |52| `running scripts is disabled on this system` 或 `PSSecurityException` | [允許 npm shims 執行](#running-scripts-is-disabled-on-this-system) |

44| `Error: claude native binary not installed` | [完成 npm 安裝](#native-binary-not-found-after-npm-install) |53| `Error: claude native binary not installed` | [完成 npm 安裝](#native-binary-not-found-after-npm-install) |

45| `npm error code ENOTEMPTY` 在更新或重新安裝期間 | [移除剩餘的套件目錄](#npm-enotempty-during-update-or-reinstall) |54| `npm error code ENOTEMPTY` 在更新或重新安裝期間 | [移除剩餘的套件目錄](#npm-enotempty-during-update-or-reinstall) |

~~46| 在 Windows 上，安裝命令列印指令碼文字且未安裝任何內容 | [執行完整的安裝命令](#wrong-install-command-on-windows) |~~

47| `'claude' is not recognized` 在 Windows 上更新後立即出現 | [從其備份還原 `claude.exe`](#claude-exe-missing-after-an-update-on-windows) |55| `'claude' is not recognized` 在 Windows 上更新後立即出現 | [從其備份還原 `claude.exe`](#claude-exe-missing-after-an-update-on-windows) |

56| 在 Windows 上，安裝命令列印指令碼文字且未安裝任何內容 | [執行完整的安裝命令](#wrong-install-command-on-windows) |

48| `App unavailable in region` | Claude Code 在您的國家/地區不可用。請參閱[支援的國家/地區](https://www.anthropic.com/supported-countries)。 |57| `App unavailable in region` | Claude Code 在您的國家/地區不可用。請參閱[支援的國家/地區](https://www.anthropic.com/supported-countries)。 |

49| `unable to get local issuer certificate` | [設定公司 CA 憑證](#tls-or-ssl-connection-errors) |58| `unable to get local issuer certificate` | [設定公司 CA 憑證](#tls-or-ssl-connection-errors) |

51| `Claude Code access has not been granted for this account` | [取得包含 Claude Code 的角色](#claude-code-access-has-not-been-granted-for-this-account) |60| `Claude Code access has not been granted for this account` | [取得包含 Claude Code 的角色](#claude-code-access-has-not-been-granted-for-this-account) |

52| 設定期間 `Unable to connect to Anthropic services` | 請參閱錯誤參考中的 [Unable to connect to Anthropic services](/docs/zh-TW/errors#unable-to-connect-to-anthropic-services) |61| 設定期間 `Unable to connect to Anthropic services` | 請參閱錯誤參考中的 [Unable to connect to Anthropic services](/docs/zh-TW/errors#unable-to-connect-to-anthropic-services) |

53| `Could not load the default credentials` 或 `Could not load credentials from any providers` | [Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 認證](#bedrock-agent-platform-or-foundry-credentials-not-loading) |62| `Could not load the default credentials` 或 `Could not load credentials from any providers` | [Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 憑證](#bedrock-agent-platform-or-foundry-credentials-not-loading) |

54| `ChainedTokenCredential authentication failed` 或 `CredentialUnavailableError` | [Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 認證](#bedrock-agent-platform-or-foundry-credentials-not-loading) |63| `ChainedTokenCredential authentication failed` 或 `CredentialUnavailableError` | [Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 憑證](#bedrock-agent-platform-or-foundry-credentials-not-loading) |

55| `API Error: 500`、`529 Overloaded`、`429` 或上面未列出的其他 4xx 和 5xx 錯誤 | 請參閱[錯誤參考](/docs/zh-TW/errors) |64| `API Error: 500`、`529 Overloaded`、`429` 或上面未列出的其他 4xx 和 5xx 錯誤 | 請參閱[錯誤參考](/docs/zh-TW/errors) |

56 65

57如果您的問題未列出，請執行下面的診斷檢查以縮小原因範圍。66如果您的問題未列出，請執行下面的診斷檢查以縮小原因範圍。

58 67

59<Tip>68<Tip>

60 如果您寧願完全跳過終端，[Claude Code Desktop 應用程式](/docs/zh-TW/desktop-quickstart)可讓您透過圖形介面安裝和使用 Claude Code。下載適用於 [macOS](https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code\&utm_medium=docs) 或 [Windows](https://claude.com/download?utm_source=claude_code\&utm_medium=docs) 的版本，無需任何命令列設定即可開始編碼。在 Linux 上，請按照 [Linux 安裝說明](/docs/zh-TW/desktop-linux)使用 apt 安裝應用程式。69 如果您寧願完全跳過終端機，[Claude Code Desktop 應用程式](/docs/zh-TW/desktop-quickstart)可讓您透過圖形介面安裝和使用 Claude Code。下載適用於 [macOS](https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code\&utm_medium=docs) 或 [Windows](https://claude.com/download?utm_source=claude_code\&utm_medium=docs) 的版本，無需任何命令列設定即可開始編碼。在 Linux 上，請按照 [Linux 安裝說明](/docs/zh-TW/desktop-linux)使用 apt 安裝應用程式。

61</Tip>70</Tip>

62 71

63<h2 id="run-diagnostic-checks">72<h2 id="run-diagnostic-checks">

99 108

100如果您在公司代理伺服器後面，在安裝前設定 `HTTPS_PROXY` 和 `HTTP_PROXY` 為您代理伺服器的位址。如果您不知道代理伺服器 URL，請詢問您的 IT 團隊，或檢查您瀏覽器的代理伺服器設定。109如果您在公司代理伺服器後面，在安裝前設定 `HTTPS_PROXY` 和 `HTTP_PROXY` 為您代理伺服器的位址。如果您不知道代理伺服器 URL，請詢問您的 IT 團隊，或檢查您瀏覽器的代理伺服器設定。

101 110

102此範例設定兩個代理變數，然後透過您的代理伺服器執行安裝程式：111此範例設定兩個代理伺服器變數，然後透過您的代理伺服器執行安裝程式：

103 112

104<Tabs>113<Tabs>

105 <Tab title="macOS/Linux">114 <Tab title="macOS/Linux">

125 134

126如果安裝成功但執行 `claude` 時收到 `command not found` 或 `not recognized` 錯誤，安裝目錄不在您的 PATH 中。您的 shell 會在 PATH 中列出的目錄中搜尋程式，安裝程式在 macOS/Linux 上將 `claude` 放在 `~/.local/bin/claude`，或在 Windows 上放在 `%USERPROFILE%\.local\bin\claude.exe`。135如果安裝成功但執行 `claude` 時收到 `command not found` 或 `not recognized` 錯誤，安裝目錄不在您的 PATH 中。您的 shell 會在 PATH 中列出的目錄中搜尋程式，安裝程式在 macOS/Linux 上將 `claude` 放在 `~/.local/bin/claude`，或在 Windows 上放在 `%USERPROFILE%\.local\bin\claude.exe`。

127 136

137安裝程式會偵測到這種情況，並在其輸出的 `Setup notes:` 下回報：在 macOS 和 Linux 上為 `Native installation exists but ~/.local/bin is not in your PATH.`，在 Windows 上則為 `Native installation exists but C:\Users\you\.local\bin is not in your PATH.`。它會隨該說明列印修正方式，但不會自行變更 PATH。

138

128<Note>139<Note>

129 [VS Code 擴充功能](/docs/zh-TW/vs-code)不會在此位置放置 `claude`。它在擴充功能目錄內為其自己的聊天面板捆綁了 CLI 的私人副本，並且不會將其新增到 PATH。如果您只安裝了擴充功能，`~/.local/bin/claude` 將不存在。執行[獨立安裝](/docs/zh-TW/setup)以從終端使用 `claude`，然後繼續下面的步驟。140 [VS Code 擴充功能](/docs/zh-TW/vs-code)不會在此位置放置 `claude`。它在擴充功能目錄內為其自己的聊天面板捆綁了 CLI 的私人副本，並且不會將其新增到 PATH。如果您只安裝了擴充功能，`~/.local/bin/claude` 將不存在。執行[獨立安裝](/docs/zh-TW/setup)以從終端機使用 `claude`，然後繼續下面的步驟。

130</Note>141</Note>

131 142

132透過列出您的 PATH 項目並篩選 `local/bin` 來檢查安裝目錄是否在您的 PATH 中：143首先檢查程式是否確實存在，然後檢查其資料夾是否在您的 PATH 中。PATH 的修正是永久性的，因此只需套用一次。選擇您平台的分頁並在對應環境中執行其命令：在 macOS 和 Linux 上於終端機中執行，在 Windows 上則於 PowerShell 或命令提示字元中執行。

133 144

134<Tabs>145<Tabs>

135 <Tab title="macOS/Linux">146 <Tab title="macOS/Linux">

147 檢查安裝程式是否已將程式放置到位：

148

149 ```bash theme={null}

150 ls -la ~/.local/bin/claude

151 ```

152

153 * **`No such file or directory`**：沒有原生安裝。如果您尚未以其他方式（例如透過 npm、Homebrew 或 Linux 套件管理員）安裝 Claude Code，請[安裝 Claude Code](/docs/zh-TW/setup#install-claude-code)。如果您以其他方式安裝，請參閱[檢查衝突的安裝](#check-for-conflicting-installations)。

154 * **顯示該檔案的列表**：程式已存在。接下來檢查您的 PATH。

155

156 列出您的 PATH 項目並篩選安裝資料夾：

157

136 ```bash theme={null}158 ```bash theme={null}

137 echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"159 echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"

138 ```160 ```

139 161

140 如果這列印出 `/Users/you/.local/bin` 或 `/home/you/.local/bin`，該目錄在您的 PATH 中，您可以跳到[檢查衝突的安裝](#check-for-conflicting-installations)。如果沒有輸出，將其新增到您的 shell 設定。162 如果這列印出 `/Users/you/.local/bin` 或 `/home/you/.local/bin`，該目錄在您的 PATH 中，您可以跳到[檢查衝突的安裝](#check-for-conflicting-installations)。如果沒有輸出，請使用適用於您 shell 的兩個命令將其新增到您的 shell 設定。`echo` 命令會為每個新的終端機儲存此設定，而 `source` 會將其套用到您目前所在的視窗。`echo` 命令成功時不會列印任何內容。

141 163

142 對於 Zsh（macOS 上的預設值）：164 對於 Zsh（macOS 上的預設值）：

143 165

153 source ~/.bashrc175 source ~/.bashrc

154 ```176 ```

155 177

156 對於 macOS 上的 Bash，改為將該行新增到 `~/.bash_profile`。macOS 上的終端以登入 shell 的形式啟動 Bash，它會忽略 `~/.bashrc` 並只讀取存在的 `~/.bash_profile`、`~/.bash_login` 或 `~/.profile` 中的第一個。如果您已經有 `~/.bash_login` 或 `~/.profile` 且沒有 `~/.bash_profile`，請將該行放在該檔案中，而不是建立 `~/.bash_profile`：178 對於 macOS 上的 Bash，改為將該行新增到 `~/.bash_profile`。macOS 上的終端機以登入 shell 的形式啟動 Bash，它會忽略 `~/.bashrc` 並只讀取存在的 `~/.bash_profile`、`~/.bash_login` 或 `~/.profile` 中的第一個。如果您已經有 `~/.bash_login` 或 `~/.profile` 且沒有 `~/.bash_profile`，請將該行放在該檔案中，而不是建立 `~/.bash_profile`：

157 179

158 ```bash theme={null}180 ```bash theme={null}

159 echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bash_profile181 echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bash_profile

160 source ~/.bash_profile182 source ~/.bash_profile

161 ```183 ```

162 184

163 或者，關閉並重新開啟您的終端。185 或者，關閉並重新開啟您的終端機。

186

187 如果 `echo` 命令列印 `permission denied`，請參閱[新增到 PATH 時出現 `permission denied`](#permission-denied-when-adding-to-your-path)。

164 188

165 對於其他 shell（例如 fish 或 Nushell），使用您的 shell 自己的設定語法將 `~/.local/bin` 新增到您的 PATH，然後重新啟動您的終端。189 對於其他 shell（例如 fish 或 Nushell），使用您的 shell 自己的設定語法將 `~/.local/bin` 新增到您的 PATH，然後重新啟動您的終端機。

166 190

167 驗證修復是否有效：191 驗證修復是否有效：

168 192

169 ```bash theme={null}193 ```bash theme={null}

170 claude --version194 claude --version

171 ```195 ```

196

197 如果仍然找不到 `claude`，請檢查以下原因：

198

199 * **終端機是在變更之前開啟的**：已經開啟的視窗會保留其舊的 PATH，而編輯器內的終端機會從編輯器取得其 PATH。請開啟新視窗，或結束並重新開啟編輯器。

200 * **該行未儲存**：執行 `grep -n '.local/bin' ~/.zshrc`，並使用您 shell 的檔案名稱。如果該行存在，它會列印該行及其行號。如果沒有列印任何內容，請再次執行這兩個 PATH 命令。

201 * **該行被寫入另一個 shell 的檔案**：執行 `echo $0` 查看您的 shell，然後執行適用於該 shell 的兩個 PATH 命令。

172 </Tab>202 </Tab>

173 203

174 <Tab title="Windows PowerShell">204 <Tab title="Windows PowerShell">

205 檢查安裝程式是否已將程式放置到位：

206

207 ```powershell theme={null}

208 Test-Path "$env:USERPROFILE\.local\bin\claude.exe"

209 ```

210

211 * **`False`**：沒有原生安裝。如果您尚未以其他方式（例如透過 npm 或 WinGet）安裝 Claude Code，請[安裝 Claude Code](/docs/zh-TW/setup#install-claude-code)。如果您以其他方式安裝，請參閱[檢查衝突的安裝](#check-for-conflicting-installations)。

212 * **`True`**：程式已存在。接下來檢查您的 PATH。

213

214 列出您的 PATH 項目並篩選安裝資料夾：

215

175 ```powershell theme={null}216 ```powershell theme={null}

176 $env:PATH -split ';' | Select-String '\.local\\bin'217 $env:PATH -split ';' | Select-String '\.local\\bin'

177 ```218 ```

178 219

179 如果沒有輸出，將安裝目錄新增到您的使用者 PATH：220 如果這列印出 `C:\Users\you\.local\bin`，該目錄在您的 PATH 中，您可以跳到[檢查衝突的安裝](#check-for-conflicting-installations)。如果沒有輸出，將安裝目錄新增到您的使用者 PATH：

180 221

181 ```powershell theme={null}222 ```powershell theme={null}

182 $currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')223 $currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')

183 [Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')224 [Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

184 ```225 ```

185 226

186 重新啟動您的終端以使變更生效。227 重新啟動您的終端機以使變更生效。

187 228

188 驗證修復是否有效：229 驗證修復是否有效：

189 230

190 ```powershell theme={null}231 ```powershell theme={null}

191 claude --version232 claude --version

192 ```233 ```

234

235 如果在新的終端機中仍然找不到 `claude`，請檢查以下原因：

236

237 * **終端機在編輯器內執行**：它會從編輯器取得其 PATH，因此請結束並重新開啟編輯器。

238 * **變更未儲存**：執行 `[Environment]::GetEnvironmentVariable('PATH', 'User')`，並在其列印的 PATH 中尋找 `.local\bin`。如果不存在，請再次執行這兩個命令。

193 </Tab>239 </Tab>

194 240

195 <Tab title="Windows CMD">241 <Tab title="Windows CMD">

242 檢查安裝程式是否已將程式放置到位：

243

244 ```batch theme={null}

245 dir "%USERPROFILE%\.local\bin\claude.exe"

246 ```

247

248 * **`File Not Found` 或 `The system cannot find the path specified.`**：沒有原生安裝。如果您尚未以其他方式（例如透過 npm 或 WinGet）安裝 Claude Code，請[安裝 Claude Code](/docs/zh-TW/setup#install-claude-code)。如果您以其他方式安裝，請參閱[檢查衝突的安裝](#check-for-conflicting-installations)。

249 * **顯示 `claude.exe` 的列表**：程式已存在。接下來檢查您的 PATH。

250

251 列出您的 PATH 項目並篩選安裝資料夾：

252

196 ```batch theme={null}253 ```batch theme={null}

197 echo %PATH% | findstr /i "local\bin"254 echo %PATH% | findstr /i "local\bin"

198 ```255 ```

199 256

200 如果沒有輸出，開啟系統設定，前往環境變數，並將 `%USERPROFILE%\.local\bin` 新增到您的使用者 PATH 變數。重新啟動您的終端。257 如果沒有輸出，開啟系統設定，前往環境變數，並將 `%USERPROFILE%\.local\bin` 新增到您的使用者 PATH 變數。重新啟動您的終端機。

201 258

202 驗證修復是否有效：259 驗證修復是否有效：

203 260

204 ```batch theme={null}261 ```batch theme={null}

205 claude --version262 claude --version

206 ```263 ```

264

265 如果在新的終端機中仍然找不到 `claude`，由於編輯器內的終端機會從編輯器取得其 PATH，因此也請結束並重新開啟編輯器。

207 </Tab>266 </Tab>

208</Tabs>267</Tabs>

209 268

221 which -a claude280 which -a claude

222 ```281 ```

223 282

224 如果這不列印任何內容，您的 PATH 上還沒有 `claude`。回到[驗證您的 PATH](#verify-your-path)。283 如果這列印出 `claude not found`、`no claude in` 行，或沒有列印任何內容，表示您的 PATH 上沒有 `claude`。接下來的檢查會顯示是否有安裝任何 `claude`。

225 284

226 檢查 `claude` 二進位檔可能來自的三個位置。`~/.local/bin/claude` 是原生安裝程式，`~/.claude/local/` 是由舊版 Claude Code 建立的舊版本地 npm 安裝，npm 全域清單顯示 `-g` 安裝：285 檢查 `claude` 二進位檔可能來自的三個位置。`~/.local/bin/claude` 是原生安裝程式，`~/.claude/local/` 是由舊版 Claude Code 建立的舊版本地 npm 安裝，npm 全域清單顯示 `-g` 安裝：

227 286

240 ```bash theme={null}299 ```bash theme={null}

241 npm -g ls @anthropic-ai/claude-code 2>/dev/null300 npm -g ls @anthropic-ai/claude-code 2>/dev/null

242 ```301 ```

302

303 如果 `ls -la ~/.local/bin/claude` 列印 `No such file or directory`，表示沒有原生安裝。如果您尚未以其他方式（例如透過 npm、Homebrew 或 Linux 套件管理員）安裝 Claude Code，請[安裝 Claude Code](/docs/zh-TW/setup#install-claude-code)。如果 `~/.local/bin/claude` 存在但 `which -a claude` 沒有列出它，表示該資料夾不在您的 PATH 中：請參閱[驗證您的 PATH](#verify-your-path)。

243 </Tab>304 </Tab>

244 305

245 <Tab title="Windows PowerShell">306 <Tab title="Windows PowerShell">

249 where.exe claude310 where.exe claude

250 ```311 ```

251 312

313 如果這列印出 `INFO: Could not find files for the given pattern(s).`，表示您的 PATH 上沒有 `claude`。

314

252 檢查原生安裝程式是否放置了二進位檔：315 檢查原生安裝程式是否放置了二進位檔：

253 316

254 ```powershell theme={null}317 ```powershell theme={null}

255 Test-Path "$env:USERPROFILE\.local\bin\claude.exe"318 Test-Path "$env:USERPROFILE\.local\bin\claude.exe"

256 ```319 ```

320

321 * **`True`**：原生安裝存在。如果 `where.exe` 沒有找到任何內容，表示其資料夾不在您的 PATH 中：請參閱[驗證您的 PATH](#verify-your-path)。

322 * **`False`**：沒有原生安裝。如果您尚未以其他方式（例如透過 npm 或 WinGet）安裝 Claude Code，請[安裝 Claude Code](/docs/zh-TW/setup#install-claude-code)。

257 </Tab>323 </Tab>

258</Tabs>324</Tabs>

259 325

368 安裝指令碼傳回 HTML 而非 shell 指令碼434 安裝指令碼傳回 HTML 而非 shell 指令碼

369</h3>435</h3>

370 436

371執行安裝命令時，您可能會看到以下其中一個錯誤：437當下載到的內容不是安裝指令碼時，安裝命令會因以下其中一個錯誤而失敗。

438

439**Bash 或 Zsh**：錯誤會引用傳回頁面的第一行。

372 440

373```text theme={null}441```text theme={null}

374bash: line 1: syntax error near unexpected token `<'442bash: line 1: syntax error near unexpected token `<'

375bash: line 1: `<!DOCTYPE html>'443bash: line 1: `<!DOCTYPE html>'

376```444```

377 445

378在 PowerShell 上，同樣的問題顯示為解析錯誤，指向傳回的頁面，`iex` 嘗試執行 HTML 和 CSS 作為 PowerShell：446**PowerShell，解析錯誤**：錯誤指向傳回的頁面，`iex` 嘗試將 HTML 和 CSS 當作 PowerShell 執行。

379 447

380```text theme={null}448```text theme={null}

381iex : At line:1 char:2310449iex : At line:1 char:2310

386 454

387措辭因 PowerShell 版本和系統語言而異：您可能會看到 `Missing expression after unary operator '--'` 或帶有 `ParseException` 的 `ParserError`。引用文字中的 HTML 標籤或 CSS 識別此失敗。如果您改用 `-OutFile install.ps1` 下載，保存的檔案是相同的網頁，所以這也無法幫助。455措辭因 PowerShell 版本和系統語言而異：您可能會看到 `Missing expression after unary operator '--'` 或帶有 `ParseException` 的 `ParserError`。引用文字中的 HTML 標籤或 CSS 識別此失敗。如果您改用 `-OutFile install.ps1` 下載，保存的檔案是相同的網頁，所以這也無法幫助。

388 456

389根據請求的路由方式，您可能會看到 403 且沒有 HTML 主體：457**PowerShell，`System.Xml.XmlDocument`**：錯誤會指出此型別名稱，而非引用頁面內容。

458

459```text theme={null}

460System.Xml.XmlDocument : The term 'System.Xml.XmlDocument' is not recognized as the name of a cmdlet, function, script

461file, or operable program.

462```

463

464當 `irm` 能將回應解析為 XML 時，它會傳回 XML 物件而非文字，接著 `iex` 會嘗試將該物件的型別名稱當作命令執行。安裝指令碼是 PowerShell 程式碼，無法解析為 XML，因此此錯誤同樣表示回應並非指令碼。型別名稱周圍的措辭因 PowerShell 版本和系統語言而異，但 `System.Xml.XmlDocument` 本身保持不變，因此請以型別名稱比對。

465

466**CMD**：您會看到此錯誤，後面接著傳回頁面的 HTML。

467

468```text theme={null}

469< was unexpected at this time.

470

471C:\Users\you><!DOCTYPE html>...

472```

473

474第一行會以您的系統語言顯示，因此請尋找其後的 HTML。

475

476**沒有頁面的 403**：根據請求的路由方式，curl 會報告 403 狀態且沒有 HTML 主體。

390 477

391```text theme={null}478```text theme={null}

392curl: (22) The requested URL returned error: 403479curl: (22) The requested URL returned error: 403

393```480```

394 481

395這些都表示安裝 URL 傳回了 HTML 頁面或錯誤狀態，而非安裝指令碼。如果 HTML 頁面顯示「App unavailable in region」，Claude Code 在您的國家/地區不可用。請參閱[支援的國家/地區](https://www.anthropic.com/supported-countries)。482這些都表示安裝 URL 傳回了網頁、XML 文件或錯誤狀態，而非安裝指令碼。如果錯誤輸出引用了「App unavailable in region」，Claude Code 在您的國家/地區不可用。請參閱[支援的國家/地區](https://www.anthropic.com/supported-countries)。

396 483

397沒有主體的單純 403 通常有相同的原因，但也可能來自公司代理伺服器或防火牆阻止下載。如果您在支援的國家/地區但仍然看到 403，在嘗試下面的替代安裝程式前，請先完成[檢查網路連線](#check-network-connectivity)，因為這些會連線到相同的主機。484沒有主體的單純 403 通常有相同的原因，但也可能來自公司代理伺服器或防火牆阻止下載。如果您在支援的國家/地區但仍然看到 403，在嘗試下面的替代安裝程式前，請先完成[檢查網路連線](#check-network-connectivity)，因為這些會連線到相同的主機。

398 485

400 487

401**解決方案：**488**解決方案：**

402 489

4031. **使用替代安裝方法**：4901. **幾分鐘後重試**：問題通常是暫時的。等待並再次嘗試原始命令。

491

4922. **使用替代安裝方法**：與原生安裝不同，Homebrew 或 WinGet 安裝[預設不會自動更新](/docs/zh-TW/setup#auto-updates)。

404 493

405 在 macOS 上，透過 Homebrew 安裝：494 在 macOS 上，透過 Homebrew 安裝：

406 495

416 505

417 然後執行 `claude --version` 以確認：命令列印版本號，例如 `2.1.211 (Claude Code)`。如果 shell 報告找不到 `claude`，開啟新的終端機視窗並重試：您安裝的工作階段保留其舊的 `PATH`。506 然後執行 `claude --version` 以確認：命令列印版本號，例如 `2.1.211 (Claude Code)`。如果 shell 報告找不到 `claude`，開啟新的終端機視窗並重試：您安裝的工作階段保留其舊的 `PATH`。

418 507

4192. **幾分鐘後重試**：問題通常是暫時的。等待並再次嘗試原始命令。

~~420~~

421<h3 id="command-not-found-claude-after-installation">508<h3 id="command-not-found-claude-after-installation">

422 安裝後 `command not found: claude`509 安裝後 `command not found: claude`

423</h3>510</h3>

435 522

436否則，請參閱[驗證您的 PATH](#verify-your-path) 以取得每個平台上的修復。523否則，請參閱[驗證您的 PATH](#verify-your-path) 以取得每個平台上的修復。

437 524

525<h3 id="permission-denied-when-adding-to-your-path">

526 新增至 PATH 時出現 `permission denied`

527</h3>

528

529如果將 `~/.local/bin` 新增到 PATH 的 `echo` 命令列印 `zsh: permission denied: /Users/you/.zshrc` 或 `bash: /home/you/.bashrc: Permission denied`，表示您的使用者無法寫入該檔案，且沒有任何內容被儲存。在終端機中檢查該檔案的擁有者，並以您 shell 的檔案名稱取代 `~/.zshrc`：

530

531```bash theme={null}

532ls -l ~/.zshrc

533```

534

535輸出的第三個欄位是擁有者。

536

537* **擁有者是其他使用者，例如 `root`**：使用 `sudo chown $(whoami) ~/.zshrc` 取得擁有權，這需要管理員權限。

538* **擁有者是您**：該檔案為唯讀。使用 `chmod u+w ~/.zshrc` 使其可寫入。

539

540然後再次執行[驗證您的 PATH](#verify-your-path) 中適用於您 shell 的兩個 PATH 命令。

541

438<h3 id="curl-56-failure-writing-output-to-destination">542<h3 id="curl-56-failure-writing-output-to-destination">

439 `curl: (56) Failure writing output to destination`543 `curl: (56) Failure writing output to destination`

440</h3>544</h3>

456 560

457如果 Homebrew 安裝的 Claude Code 版本比您預期的舊，通常是相同的過時索引導致的。`claude-code` cask 追蹤穩定通道，通常比最新版本晚約一週；若要取得最新版本，請改為執行 `brew install --cask claude-code@latest`。請參閱[設定發布通道](/docs/zh-TW/setup#configure-release-channel) 以了解兩個 cask 之間的差異。561如果 Homebrew 安裝的 Claude Code 版本比您預期的舊，通常是相同的過時索引導致的。`claude-code` cask 追蹤穩定通道，通常比最新版本晚約一週；若要取得最新版本，請改為執行 `brew install --cask claude-code@latest`。請參閱[設定發布通道](/docs/zh-TW/setup#configure-release-channel) 以了解兩個 cask 之間的差異。

458 562

563<h3 id="cask-is-not-installed">

564 `Cask 'claude-code@latest' is not installed`

565</h3>

566

567Homebrew 提供兩個 cask：`claude-code` 和 `claude-code@latest`。當已安裝的不是該 cask 時執行 `brew upgrade --cask claude-code@latest`，會列印 `Error: Cask 'claude-code@latest' is not installed.`。若要查看您安裝的是哪個 cask，請在終端機中執行：

568

569```bash theme={null}

570brew list --cask | grep claude-code

571```

572

573升級它所列印的 cask。如果沒有列印任何內容，表示兩個 cask 都未安裝。

574

459<h3 id="tls-or-ssl-connection-errors">575<h3 id="tls-or-ssl-connection-errors">

460 TLS 或 SSL 連線錯誤576 TLS 或 SSL 連線錯誤

461</h3>577</h3>

467* PowerShell 的 `Could not create SSL/TLS secure channel`583* PowerShell 的 `Could not create SSL/TLS secure channel`

468* PowerShell 的 `Could not establish trust relationship for the SSL/TLS secure channel`584* PowerShell 的 `Could not establish trust relationship for the SSL/TLS secure channel`

469 585

586若為 `CRYPT_E_NO_REVOCATION_CHECK` 或 `CRYPT_E_REVOCATION_OFFLINE`，請跳至步驟 4。

587

470**解決方案：**588**解決方案：**

471 589

4721. **更新您的系統 CA 憑證**：5901. **更新您的系統 CA 憑證**：

479 597

480 在 macOS 上，系統 curl 使用 Keychain 信任存放區；更新 macOS 本身會更新根憑證。598 在 macOS 上，系統 curl 使用 Keychain 信任存放區；更新 macOS 本身會更新根憑證。

481 599

4822. **在 Windows 上，在執行安裝程式前在 PowerShell 中啟用 TLS 1.2**：6002. **在 Windows PowerShell 5.1 中，啟用 TLS 1.2**：

483 ```powershell theme={null}601 ```powershell theme={null}

484 [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12602 [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

603 ```

604 然後在同一視窗中執行安裝程式：

605 ```powershell theme={null}

485 irm https://claude.ai/install.ps1 | iex606 irm https://claude.ai/install.ps1 | iex

486 ```607 ```

487 608

537 658

538安裝程式無法連線到下載伺服器。這通常表示 `downloads.claude.ai` 在您的網路上被阻止。請參閱[檢查網路連線](#check-network-connectivity)。659安裝程式無法連線到下載伺服器。這通常表示 `downloads.claude.ai` 在您的網路上被阻止。請參閱[檢查網路連線](#check-network-connectivity)。

539 660

661<h3 id="the-connection-dropped-while-downloading-the-update">

662 The connection dropped while downloading the update

663</h3>

664

665在 `claude install` 或 `claude update` 擷取 Claude Code 二進位檔時，與下載伺服器的連線關閉，且重試未能恢復。當連線中斷、傳輸停滯，或下載的檔案未通過檢查碼驗證時，Claude Code 會重試下載，總共最多三次嘗試。已完成的 HTTP 錯誤（例如 404）不會重試，因為伺服器已經回應。在 v2.1.202 之前，單次連線中斷會立即以單純的錯誤 `aborted` 使下載失敗，而不會重試。

666

667```text theme={null}

668The connection dropped while downloading the update (attempt 3/3: aborted). Check your network — proxies sometimes cut off large downloads.

669```

670

671括號中的文字指出哪一次嘗試失敗以及底層的網路錯誤。`claude update` 會在 stderr 上於此訊息之前顯示 `Error: Failed to install native update`。

672

673保持連線但未在 10 分鐘內完成的下載，會改以 `Download timed out: exceeded the total deadline` 失敗。Claude Code 不會重試逾時的下載，因為慢到無法在期限內完成的連線，立即重試也同樣無法完成。以下步驟適用於這兩種訊息。

674

675代理伺服器或閘道可能在長時間傳輸完成前將其關閉，而 Claude Code 二進位檔是大型下載。

676

677**處理方式：**

678

679* 再次執行 `claude update`。在其他方面正常的網路上，下載通常會在下一次執行時成功。若為逾時訊息，請從速度較快或較少限流的網路再次執行。

680* 如果您的網路需要代理伺服器，請在執行安裝程式或 `claude update` 之前設定 `HTTPS_PROXY`。請參閱[檢查網路連線](#check-network-connectivity)。

681* 如果公司代理伺服器持續關閉傳輸，請要求您的網路團隊允許從 `downloads.claude.ai` 進行完整下載。請參閱[網路存取需求](/docs/zh-TW/network-config#network-access-requirements)。

682* 從您的 shell 執行 `claude doctor` 以取得安裝診斷

683

540<h3 id="wrong-install-command-on-windows">684<h3 id="wrong-install-command-on-windows">

541 Windows 上的錯誤安裝命令685 Windows 上的錯誤安裝命令

542</h3>686</h3>

682 826

6833. **如果可能，使用更大的執行個體**。Claude Code 需要至少 4 GB 的 RAM。8273. **如果可能，使用更大的執行個體**。Claude Code 需要至少 4 GB 的 RAM。

684 828

829<h3 id="installation-was-killed-before-it-could-finish">

830 Installation was killed before it could finish

831</h3>

832

833當 `claude install` 步驟被訊號終止時，安裝指令碼會回報。在 Linux 上，退出碼 137 表示程序收到 SIGKILL，而在低記憶體主機上，這通常是核心的記憶體不足 (OOM) 殺手。指令碼會列印此說明並以代碼 137 結束：

834

835```text theme={null}

836Installation was killed before it could finish (exit code 137). This usually means the system ran out of memory.

837Claude Code needs roughly 512MB of free memory to install. Free up memory, then run this script again.

838```

839

840對於任何其他致命訊號，以及 macOS 上的退出碼 137，指令碼會列印 `Installation was killed before it could finish (exit code <N>)` 並附上實際的退出碼，且省略記憶體不足的說明。此訊息來自 macOS 和 Linux 使用的安裝指令碼，該指令碼也涵蓋 WSL 內的安裝；原生 Windows 安裝指令碼永遠不會列印此訊息。在 v2.1.200 之前，指令碼結束時只有 shell 單純的 `Killed` 行。

841

842**處理方式：**

843

844* 停止其他程序以釋放記憶體，然後重新執行安裝程式

845* 新增交換空間或改用更大的執行個體。如需交換檔案命令，請參閱[低記憶體 Linux 伺服器上安裝被終止](#install-killed-on-low-memory-linux-servers)。

846

685<h3 id="install-hangs-in-docker">847<h3 id="install-hangs-in-docker">

686 Docker 中安裝掛起848 Docker 中安裝掛起

687</h3>849</h3>

troubleshooting.md +1 −1

Details

11| 症狀 | 前往 |11| 症狀 | 前往 |

12| :- | :- |12| :- | :- |

13| `command not found`、安裝失敗、PATH 問題、`EACCES`、TLS 錯誤 | [故障排除安裝和登入](/docs/zh-TW/troubleshoot-install) |13| `command not found`、安裝失敗、PATH 問題、`EACCES`、TLS 錯誤 | [故障排除安裝和登入](/docs/zh-TW/troubleshoot-install) |

~~14| 更新或安裝下載失敗，出現 `The connection dropped while downloading the update` 或 `aborted` | [錯誤參考](/docs/zh-TW/errors#the-connection-dropped-while-downloading-the-update) |~~14| 更新或安裝下載失敗，出現 `The connection dropped while downloading the update` 或 `aborted` | [疑難排解安裝和登入](/docs/zh-TW/troubleshoot-install#the-connection-dropped-while-downloading-the-update) |

15| 登入迴圈、OAuth 錯誤、`403 Forbidden`、「組織已停用」、Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 認證 | [故障排除安裝和登入](/docs/zh-TW/troubleshoot-install#login-and-authentication) |15| 登入迴圈、OAuth 錯誤、`403 Forbidden`、「組織已停用」、Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 認證 | [故障排除安裝和登入](/docs/zh-TW/troubleshoot-install#login-and-authentication) |

16| 設定未套用、hooks 未觸發、MCP 伺服器未載入 | [偵錯您的設定](/docs/zh-TW/debug-your-config) |16| 設定未套用、hooks 未觸發、MCP 伺服器未載入 | [偵錯您的設定](/docs/zh-TW/debug-your-config) |

17| 工作階段以自動模式啟動，或 Claude 編輯檔案並執行命令而不詢問 | [工作階段啟動的模式](/docs/zh-TW/permission-modes#which-mode-a-session-starts-in) |17| 工作階段以自動模式啟動，或 Claude 編輯檔案並執行命令而不詢問 | [工作階段啟動的模式](/docs/zh-TW/permission-modes#which-mode-a-session-starts-in) |

ultrareview.md +6 −6

Details

56 審查提取請求56 審查提取請求

57</h3>57</h3>

58 58

~~59若要審查 GitHub 提取請求而不是本機分支，請傳遞 PR 編號：~~59若要審查 `github.com` 上的 pull request 而不是本機分支，請傳遞 PR 編號：

60 60

61```text theme={null}61```text theme={null}

62/code-review ultra 123462/code-review ultra 1234

64 64

65該命令也接受 `#1234`、`PR 1234` 和貼上的 PR URL；貼上的 URL 必須指向您目前目錄中的儲存庫。65該命令也接受 `#1234`、`PR 1234` 和貼上的 PR URL；貼上的 URL 必須指向您目前目錄中的儲存庫。

66 66

67在 PR 模式中，雲端沙箱直接從主機複製提取請求，而不是組合您的本機工作樹。PR 模式適用於 `github.com` 上的儲存庫和[GitHub Enterprise Server](/docs/zh-TW/github-enterprise-server) 執行個體上的儲存庫，這些執行個體已由擁有者連接到 Claude Code。67PR 模式需要 `github.com` 上的儲存庫。對於 [GitHub Enterprise Server](/docs/zh-TW/github-enterprise-server) 執行個體上的儲存庫，請改為不帶 PR 編號執行 `/code-review ultra` 以審查您的本機分支。

68 68

~~69對於 `github.com` 上的儲存庫，沙箱使用連接到您 Claude 帳戶的 GitHub 帳戶進行複製，因此該帳戶必須能夠讀取 PR 的儲存庫。~~69在 PR 模式中，雲端沙箱會從 `github.com` 複製 pull request，而不是上傳您的工作樹。它使用連接到您 Claude 帳戶的 GitHub 帳戶，因此該帳戶需要具有該儲存庫的讀取權限。

70 70

71執行 [`/web-setup`](/docs/zh-TW/web-quickstart#connect-from-your-terminal) 以將您的 GitHub CLI 登入連接到您的 Claude 帳戶。71執行 [`/web-setup`](/docs/zh-TW/web-quickstart#connect-from-your-terminal) 以將您的 GitHub CLI 登入連接到您的 Claude 帳戶。

72 72

74 將發現結果發佈到提取請求74 將發現結果發佈到提取請求

75</h3>75</h3>

76 76

77在 Claude Code v2.1.227 或更新版本上，當您在 `github.com` 上審查提取請求時，您可以讓 Claude 將完成的發現結果作為來自您自己 GitHub 帳戶的單一純文字評論發佈到 PR。該評論不是審查或核准，並以「由 Claude Code 生成」的備註結尾。當您審查分支或 GitHub Enterprise Server 提取請求時，Claude Code 只會在您的工作階段中顯示發現結果。77在 Claude Code v2.1.227 或更新版本上，當您在 `github.com` 上審查 pull request 時，您可以讓 Claude 將完成的發現結果作為來自您自己 GitHub 帳戶的單一純文字評論發佈到 PR。該評論不是審查或核准，並以「Generated by Claude Code」的備註結尾。當您審查分支時，Claude Code 只會在您的工作階段中顯示發現結果。

78 78

79Claude Code 絕不會發佈，除非您在該執行中選擇發佈，且 `--no-post` 是預設值。發佈是您為每次執行所做的選擇：79Claude Code 絕不會發佈，除非您在該執行中選擇發佈，且 `--no-post` 是預設值。發佈是您為每次執行所做的選擇：

80 80

106Claude Code 只有在文字超過一個單字且不是分支名稱或 PR 參考時，才會將其視為備註。它將單一單字讀取為分支名稱或 PR 參考，因此拼寫錯誤的分支名稱會從[針對不同的基礎進行審查](#review-against-a-different-base)獲得最接近分支的錯誤，而不是使用備註啟動。如果您的文字結合 PR 參考與其他單字（例如 `check PR 123 again`），Claude Code 也不會啟動；它會要求您重新執行，僅使用 PR 編號來審查該 PR，或不使用參考來審查您的目前分支。106Claude Code 只有在文字超過一個單字且不是分支名稱或 PR 參考時，才會將其視為備註。它將單一單字讀取為分支名稱或 PR 參考，因此拼寫錯誤的分支名稱會從[針對不同的基礎進行審查](#review-against-a-different-base)獲得最接近分支的錯誤，而不是使用備註啟動。如果您的文字結合 PR 參考與其他單字（例如 `check PR 123 again`），Claude Code 也不會啟動；它會要求您重新執行，僅使用 PR 編號來審查該 PR，或不使用參考來審查您的目前分支。

107 107

108<Tip>108<Tip>

109 如果您的儲存庫太大而無法組合，Claude Code 會提示您改用 PR 模式。推送您的分支並開啟草稿 PR，然後執行 `/code-review ultra <PR-number>`。109 如果您的儲存庫太大而無法組合，Claude Code 會提示您改用 PR 模式。對於 `github.com` 上的儲存庫，請推送您的分支並開啟草稿 PR，然後執行 `/code-review ultra <PR-number>`。

110</Tip>110</Tip>

111 111

112<h3 id="diff-limits-and-fallbacks">112<h3 id="diff-limits-and-fallbacks">

173claude ultrareview origin/main173claude ultrareview origin/main

174```174```

175 175

176不帶引數的情況下，該子命令會審查您目前分支與預設分支之間的差異，當不存在合併基礎時，使用與 `/code-review ultra` 相同的[整個儲存庫回退](#diff-limits-and-fallbacks)。傳遞 PR 編號以審查提取請求，或傳遞基礎分支以針對它進行審查；[基礎分支處理](#review-against-a-different-base)與互動命令相符。176不帶引數的情況下，該子命令會審查您目前分支與預設分支之間的差異，當不存在合併基礎時，使用與 `/code-review ultra` 相同的[整個儲存庫備援](#diff-limits-and-fallbacks)。傳遞 PR 編號以[審查 `github.com` 上的 pull request](#review-a-pull-request)，或傳遞基礎分支以針對它進行審查；[基礎分支處理](#review-against-a-different-base)與互動命令相符。

177 177

178當您執行該子命令時，您同意整個儲存庫回退以及帳單和條款提示，因此執行會在不等待輸入的情況下開始。您自己執行它才算是同意。當 Claude 改為為您執行該子命令時（例如透過 Bash 工具），Claude Code 會拒絕整個儲存庫審查。178當您執行該子命令時，您同意整個儲存庫回退以及帳單和條款提示，因此執行會在不等待輸入的情況下開始。您自己執行它才算是同意。當 Claude 改為為您執行該子命令時（例如透過 Bash 工具），Claude Code 會拒絕整個儲存庫審查。

179 179

vs-code.md +2 −0

Details

166* **Bookmarks**：將滑鼠懸停在回應上並點擊 **Bookmark response** 以儲存它，或在已儲存的回應上點擊 **Remove bookmark** 以移除它。166* **Bookmarks**：將滑鼠懸停在回應上並點擊 **Bookmark response** 以儲存它，或在已儲存的回應上點擊 **Remove bookmark** 以移除它。

167 167

168 若要檢閱已儲存的回應，請開啟 Bookmarks 面板：點擊 Claude Code 面板頂部的書籤圖示、在命令選單的 Context 部分中選擇 **Bookmarks**，或輸入 `/bookmarks`。需要 Claude Code v2.1.286 或更新版本。168 若要檢閱已儲存的回應，請開啟 Bookmarks 面板：點擊 Claude Code 面板頂部的書籤圖示、在命令選單的 Context 部分中選擇 **Bookmarks**，或輸入 `/bookmarks`。需要 Claude Code v2.1.286 或更新版本。

169* **Files Claude sends you**：當工作階段連線到 [Remote Control](/docs/zh-TW/remote-control#start-a-remote-control-session) 且 Claude 使用 [`SendUserFile` 工具](/docs/zh-TW/tools-reference)傳送檔案給您時，對話會顯示一列，例如 **Sent report.md, chart.png**。點擊檔案名稱以在編輯器中開啟它。

169* **Context indicator**：提示框顯示您使用了多少 Claude 的內容視窗。Claude 會在需要時自動壓縮，或您可以手動執行 `/compact`。170* **Context indicator**：提示框顯示您使用了多少 Claude 的內容視窗。Claude 會在需要時自動壓縮，或您可以手動執行 `/compact`。

170* **Prompt cache clock**：內容指示器旁邊的時鐘圖示估計對話的[提示快取](/docs/zh-TW/prompt-caching)在過期前還剩多少時間。它從快取的五分鐘或一小時[生命週期](/docs/zh-TW/prompt-caching#cache-lifetime)倒數，每個使用快取的回應都會重新啟動倒數。除了壓縮外，[使快取失效的操作](/docs/zh-TW/prompt-caching#actions-that-invalidate-the-cache)不會重設時鐘，因此在您切換模型後它仍可以顯示剩餘的分鐘數。171* **Prompt cache clock**：內容指示器旁邊的時鐘圖示估計對話的[提示快取](/docs/zh-TW/prompt-caching)在過期前還剩多少時間。它從快取的五分鐘或一小時[生命週期](/docs/zh-TW/prompt-caching#cache-lifetime)倒數，每個使用快取的回應都會重新啟動倒數。除了壓縮外，[使快取失效的操作](/docs/zh-TW/prompt-caching#actions-that-invalidate-the-cache)不會重設時鐘，因此在您切換模型後它仍可以顯示剩餘的分鐘數。

171 * 在倒數結束前，圖示會顯示剩餘的分鐘數，例如 **12m**。172 * 在倒數結束前，圖示會顯示剩餘的分鐘數，例如 **12m**。

601| `spinnerVerbs` | `{"mode": "append", "verbs": []}` | 設定回合執行期間對話載入指示器輪替顯示的動詞，使用與 CLI 的 [`spinnerVerbs`](/docs/zh-TW/settings-reference#spinnerverbs) 相同的 `mode` 和 `verbs` 欄位。 |

602| `archiveInactiveSessions` | `14` | 在無活動的這許多天後[自動封存工作階段](#resume-past-conversations)：`1`、`2`、`7` 或 `14`。設定為 `0` 以關閉。需要 Claude Code v2.1.265 或更新版本 |604| `archiveInactiveSessions` | `14` | 在無活動的這許多天後[自動封存工作階段](#resume-past-conversations)：`1`、`2`、`7` 或 `14`。設定為 `0` 以關閉。需要 Claude Code v2.1.265 或更新版本 |

workflows.md +27 −1

Details

354 354

355主體是具有頂級 `await` 的純 JavaScript。`agent()` 生成一個子代理，`pipeline()` 為清單中的每個項目執行一個，而 `parallel()` 同時執行一組代理任務並等待所有任務完成。355主體是具有頂級 `await` 的純 JavaScript。`agent()` 生成一個子代理，`pipeline()` 為清單中的每個項目執行一個，而 `parallel()` 同時執行一組代理任務並等待所有任務完成。

356 356

357如果您停止 `agent()` 呼叫中途或它遇到無法恢復的 API 錯誤，該呼叫會解析為 `null`。`pipeline()` 在結果陣列中保留每個 `null`，這就是為什麼範例以 `.filter(Boolean)` 結尾以刪除這些項目。357如果您在執行中途停止 `agent()` 呼叫，或它遇到無法恢復的 API 錯誤，該呼叫會解析為 `null`。`pipeline()` 在結果陣列中保留每個 `null`，這就是為什麼範例以 `.filter(Boolean)` 結尾以刪除這些項目，包括[每次嘗試都停滯的 agent](#when-an-agent-stalls-and-restarts) 所佔的位置。

358 358

359在[自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)中，您的指令碼傳遞給 `agent()` 的提示不會計為您的請求，當分類器審查該子代理的動作時，因為 Claude Code 將其標記為指令碼計算的文字。359在[自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)中，您的指令碼傳遞給 `agent()` 的提示不會計為您的請求，當分類器審查該子代理的動作時，因為 Claude Code 將其標記為指令碼計算的文字。

360 360

463* 限制在 24 小時內重設。每週限制可能會更晚重設。463* 限制在 24 小時內重設。每週限制可能會更晚重設。

464* 執行尚未已等待兩次。當它第三次達到限制時，代理會失敗。464* 執行尚未已等待兩次。當它第三次達到限制時，代理會失敗。

465 465

466<h3 id="when-an-agent-stalls-and-restarts">

467 當 agent 停滯並重新啟動時

468</h3>

469

470若 agent 的輸出停止傳來達一定時間，該 agent 會以相同的提示詞重新開始。在 [`/workflows`](#watch-the-run) 中，其名稱會加上 `(retry 1)` 後綴，其詳細資訊會顯示 `attempt 2 (stalled)`。重新啟動是自動的，因此您不需要執行任何操作。

471

472新的嘗試在啟動時不會帶有停滯嘗試的逐字稿。停滯嘗試已變更的檔案會維持變更，其花費的 token 也會保留在執行的總數中。停滯時間窗是 Claude Code 在結束該次嘗試之前等待 agent 輸出的時間長度。agent 等待其自身工具呼叫或等待[用量上限重設](#when-a-run-hits-your-usage-limit)所花費的時間，不會計入停滯時間窗。

473

474一個 agent 最多重新啟動五次，包括您使用 `r` 要求的任何重新啟動。如果第六次嘗試也停滯，`agent()` 呼叫會失敗，錯誤的開頭會說明原因：

475

476* `agent stalled on all 6 attempts`：每次嘗試都在整個時間窗內沒有輸出。如果 agent 的工作會讓它保持沉默這麼久，請延長時間窗

477* `agent lost its reply on all 6 attempts`：每次嘗試的回應串流都變得沉默，而 Claude Code 放棄了等待。延長停滯時間窗沒有幫助，因為[串流閒置監控程式](/docs/zh-TW/network-config#streaming-idle-watchdogs)會先結束回應，而 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 用於設定該監控程式的逾時

478* `agent abandoned after 6 attempts`：各次嘗試以不同方式結束，錯誤會依序列出這些方式

479

480若要在時間窗結束前給予 agent 更多時間產生輸出：

481

482* **單一 agent**：在其 `agent()` 呼叫上傳入以毫秒為單位的 `stallMs`，例如 `agent(prompt, { stallMs: 1800000 })` 表示 30 分鐘

483* **每個 agent**：設定 [`CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`](/docs/zh-TW/env-vars#variables)，這也適用於工作流程以外的 subagent

484

485失敗後執行是否繼續，取決於您的指令碼如何呼叫該 agent：

486

487* **在 [`parallel()` 或 `pipeline()`](#what-the-saved-script-looks-like) 內**：執行會繼續，並以 `null` 取代該 agent 的結果

488* **直接 await**：執行會隨錯誤結束

489

490若要再試一次，請要求 Claude 重新啟動工作流程。[暫停後恢復](#resume-after-a-pause)說明了哪些部分會再次執行。

491

466<h3 id="cost">492<h3 id="cost">

467 成本493 成本

468</h3>494</h3>

worktrees.md +1 −1

Details

104* **Git 重定向**：Claude Code 會阻止將 git 重定向到主要檢出的 Bash 或 Monitor 命令。重定向可以透過 `git -C`、`--git-dir`、`GIT_DIR` 或 `GIT_WORK_TREE` 變數，或在執行 git 之前 `cd` 到主要檢出。104* **Git 重定向**：Claude Code 會阻止將 git 重定向到主要檢出的 Bash 或 Monitor 命令。重定向可以透過 `git -C`、`--git-dir`、`GIT_DIR` 或 `GIT_WORK_TREE` 變數，或在執行 git 之前 `cd` 到主要檢出。

105* **命令形狀**：當 Claude Code 無法從命令文字驗證命令執行的任何 git 保持在 worktree 內時，Claude Code 會阻止 Bash 或 Monitor 命令。例如，當命令名稱在執行時計算、語法無法解析，或像 `${!name}` 或 `${ command; }` 這樣的展開可能執行文字中未明確說明的命令時，就會發生這種情況。Claude Code 會告訴 Claude 如何重寫被拒絕的命令，例如將其分割成純粹的、獨立的命令。您無法關閉此檢查。105* **命令形狀**：當 Claude Code 無法從命令文字驗證命令執行的任何 git 保持在 worktree 內時，Claude Code 會阻止 Bash 或 Monitor 命令。例如，當命令名稱在執行時計算、語法無法解析，或像 `${!name}` 或 `${ command; }` 這樣的展開可能執行文字中未明確說明的命令時，就會發生這種情況。Claude Code 會告訴 Claude 如何重寫被拒絕的命令，例如將其分割成純粹的、獨立的命令。您無法關閉此檢查。

106 106

107這些檢查會讀取編輯所針對的路徑、命令執行所在的目錄，以及命令的文字。它們都不會追蹤 shell 命令寫入了哪些檔案，因此未在主要檢出中執行 git 卻寫入主要檢出的命令（例如 `cp` 或 shell 重定向）不會被這些檢查拒絕。Claude Code 會將該命令視為任何其他 shell 命令處理，因此它是直接執行還是向您顯示權限提示，取決於您的[權限模式](/docs/zh-TW/permission-modes)和規則。107這些檢查會讀取編輯所針對的路徑、命令執行所在的目錄，以及命令的文字。它們都不會追蹤 shell 命令寫入了哪些檔案，因此未在主要檢出中執行 git 卻寫入主要檢出的命令（例如 `cp` 或 shell 重定向）不會被這些檢查拒絕。Claude Code 會依據您的[權限](/docs/zh-TW/permissions)和[沙箱機制](/docs/zh-TW/sandboxing)設定，將該命令視為任何其他 shell 命令處理。

108 108

109檢查適用於您啟動 Claude Code 的儲存庫。它們也涵蓋連結 worktree 連結自的主要檢出。對於 PowerShell 命令，Claude Code 只應用工作目錄檢查。109檢查適用於您啟動 Claude Code 的儲存庫。它們也涵蓋連結 worktree 連結自的主要檢出。對於 PowerShell 命令，Claude Code 只應用工作目錄檢查。

110 110

Documentation 2026-10-08 22:58 UTC to 2026-10-09 22:01 UTC