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/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 +30 −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;

1566 user_message_uuid?: string;1569 user_message_uuid?: string;

1580 1583

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

1582 1585

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

1587

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

1589

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

1584 1591

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

1597 type: "user";1604 type: "user";

1598 uuid?: UUID;1605 uuid?: UUID;

1599 session_id?: string;1606 session_id?: string;

1607 agent_id?: string;

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

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

1602 parent_tool_use_id: string | null;1610 parent_tool_use_id: string | null;

1636};1644};

1637```1645```

1638 1646

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

1648

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

1640 1650

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 的獨立訊息接收報告。1651* `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`2002 `SDKPartialAssistantMessage`

1993</h3>2003</h3>

1994 2004

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

2006

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

1996 2008

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

1998type SDKPartialAssistantMessage = {2010type SDKPartialAssistantMessage = {

3417type WebFetchInput = {3429type WebFetchInput = {

3418 url: string;3430 url: string;

3419 prompt: string;3431 prompt: string;

3432 offset?: number;

3420};3433};

3421```3434```

3422 3435

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

3424 3437

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

3439

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

3426 WebSearch3441 WebSearch

3427</h3>3442</h3>

5776 task_type?: string;5791 task_type?: string;

5777 is_backgrounded?: boolean;5792 is_backgrounded?: boolean;

5778 spawn_depth?: number;5793 spawn_depth?: number;

5794 parent_task_id?: string;

5779 ambient?: boolean;5795 ambient?: boolean;

5780 uuid: UUID;5796 uuid: UUID;

5781 session_id: string;5797 session_id: string;

5793 5809

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`。5810[已恢復的 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 5811

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

5813

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

5815* Claude Code 不再追蹤父工作

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

5817

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

5819

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

5797 `SDKTaskProgressMessage`5821 `SDKTaskProgressMessage`

5798</h3>5822</h3>

5849 `SDKBackgroundTasksChangedMessage`5873 `SDKBackgroundTasksChangedMessage`

5850</h3>5874</h3>

5851 5875

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

5853 5877

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

5855 5879

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

5857 5881

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

5859 5883

5870 task_type: string;5894 task_type: string;

5871 subagent_type?: string;5895 subagent_type?: string;

5872 description: string;5896 description: string;

5897 parent_task_id?: string;

5873 ambient?: boolean;5898 ambient?: boolean;

5874 }[];5899 }[];

5875 uuid: UUID;5900 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 +9 −6

Details

603 603

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

605 605

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

607 607

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

609 609

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

827 827

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

829 829

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

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

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

980</h3>980</h3>

981 981

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

983 983

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

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

985 986

986原始對話完整無缺；使用 `claude --resume` 恢復它或繼續在其中工作。請參閱[錯誤參考](/docs/zh-TW/errors#this-session-has-no-saved-transcript)以取得詳細資訊。987在同一列上再次按 `Enter` 以使用空對話重新啟動工作階段，或從 shell 執行 `claude respawn <id>`。

988

989請參閱[錯誤參考](/docs/zh-TW/errors#this-session-has-no-saved-transcript)以取得詳細資訊。

987 990

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

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

1095 1098

1096| 版本 | 變更 |1099| 版本 | 變更 |

1097| - | - |1100| - | - |

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

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

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

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

claude-apps-gateway-config.md +1 −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 使用從 gateway 發行的 JWT 讀取的已驗證使用者的身分戳記每個匯出：`user.id`、`user.email` 和 `user.groups` 屬性。每位開發者成本和使用歸因因此無需開發者端設定即可運作。Claude Code 在開發者登入之前記錄的事件[不會攜帶此身分](/docs/zh-TW/monitoring-usage#standard-attributes)。

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

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 +1 −1

Details

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

484 484

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

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

487 487

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

489 限制489 限制

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 +3 −3

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 而非開啟瀏覽器，然後將重新導向 URL 貼回提示處。請參閱 [從命令列進行身分驗證](/docs/zh-TW/mcp#authenticate-from-the-command-line) | `claude mcp login sentry` |

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)中，出站流量通過您自己的網路邊界。

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 +2 −2

Details

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 或更新版本 |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 或更新版本 |

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) 失敗 |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) 失敗 |

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 並向上層回報停滯 |207| `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 |208| `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) |209| `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 或更新版本 |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 或更新版本 |

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 或更新版本 |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 或更新版本 |

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.`。空字串會使用預設值 |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.`。空字串會使用預設值 |

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 或更新版本 |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 或更新版本 |

381| `CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS` | 設定 `CLAUDE_CODE_RETRY_WATCHDOG` 時，每個 API 請求等候 `429` 與 `529` 錯誤所花費的最長時間（毫秒）。時間用完後，下一次發生此類錯誤就會結束該請求。請以純數字提供正整數，例如 `1800000` 代表 30 分鐘。未設定時，等待沒有限制。需要 Claude Code v2.1.295 或更新版本 |

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)。直接產生的子程序會繼承此變數 |382| `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)。直接產生的子程序會繼承此變數 |

382| `CLAUDE_CODE_SCRIPT_CAPS` | 設定 `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` 時，用於限制特定指令碼在每個工作階段中可被呼叫次數的 JSON 物件。鍵為與命令文字比對的子字串；值為整數呼叫上限。例如，`{"deploy.sh": 2}` 允許 `deploy.sh` 最多被呼叫兩次。比對以子字串為基礎，因此像 `./scripts/deploy.sh $(evil)` 這類 shell 展開技巧仍會計入上限。透過 `xargs` 或 `find -exec` 的執行期擴散不會被偵測到；這是一項縱深防禦控制措施 |383| `CLAUDE_CODE_SCRIPT_CAPS` | 設定 `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` 時，用於限制特定指令碼在每個工作階段中可被呼叫次數的 JSON 物件。鍵為與命令文字比對的子字串；值為整數呼叫上限。例如，`{"deploy.sh": 2}` 允許 `deploy.sh` 最多被呼叫兩次。比對以子字串為基礎，因此像 `./scripts/deploy.sh $(evil)` 這類 shell 展開技巧仍會計入上限。透過 `xargs` 或 `find -exec` 的執行期擴散不會被偵測到；這是一項縱深防禦控制措施 |

383| `CLAUDE_CODE_SCROLL_SPEED` | 設定[全螢幕呈現](/docs/zh-TW/fullscreen#mouse-wheel-scrolling)中的滑鼠滾輪捲動倍數。接受最高 20 的任何正值，包括低於 1 的小數值，例如 `0.5`，可在已放大滾輪事件的終端機中減緩加速的觸控板與滾輪捲動。若您的終端機每一格傳送一個滾輪事件且未放大，設為 `3` 可與 `vim` 一致。在 JetBrains IDE 終端機中會被忽略，因為 Claude Code 在其中使用自己的捲動處理 |384| `CLAUDE_CODE_SCROLL_SPEED` | 設定[全螢幕呈現](/docs/zh-TW/fullscreen#mouse-wheel-scrolling)中的滑鼠滾輪捲動倍數。接受最高 20 的任何正值，包括低於 1 的小數值，例如 `0.5`，可在已放大滾輪事件的終端機中減緩加速的觸控板與滾輪捲動。若您的終端機每一格傳送一個滾輪事件且未放大，設為 `3` 可與 `vim` 一致。在 JetBrains IDE 終端機中會被忽略，因為 Claude Code 在其中使用自己的捲動處理 |

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

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

592* 讓 Claude 讀取[其他組織的公開 artifact](/docs/zh-TW/artifacts#read-an-artifact-shared-with-you)593* 讓 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 上，該工具會保持啟用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 上，該工具會保持啟用

595* 取得 [Claude 草擬的意見回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior)，Claude Code 是透過擷取的旗標來啟用此功能595* 取得 [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]` 預留位置背後的內容會未經標記地傳送給 Claude596* 讓 Claude [將大量貼上內容視為貼上的文字，而非輸入的文字](/docs/zh-TW/terminal-config#how-claude-treats-pasted-text)；`[Pasted text #N]` 預留位置背後的內容會未經標記地傳送給 Claude

errors.md +18 −18

Details

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` | [Plugin 錯誤](#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` | [Plugin 錯誤](#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` | [Plugin 錯誤](#marketplace-name-is-another-spelling-of-a-reserved-name) |

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

264| `Marketplace "<name>" is added but ignored` | [Plugin 疑難排解](/docs/zh-TW/plugins/troubleshooting#marketplace-is-added-but-ignored) |265| `Marketplace "<name>" is added but ignored` | [Plugin 疑難排解](/docs/zh-TW/plugins/troubleshooting#marketplace-is-added-but-ignored) |

265| `Marketplace "<name>" is registered but was refused (see the debug log)` | [Plugin 疑難排解](/docs/zh-TW/plugins/troubleshooting#marketplace-is-added-but-ignored) |266| `Marketplace "<name>" is registered but was refused (see the debug log)` | [Plugin 疑難排解](/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) |267| `references ${user_config.*} in a shell-form command` | [Plugin 錯誤](#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) |271| `An npm plugin source must name a registry package` | [Plugin 疑難排解](/docs/zh-TW/plugins/troubleshooting#an-npm-plugin-source-must-name-a-registry-package) |

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) |272| `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) |

273| `does not load (...), so Claude Code ignores the whole file` | [Plugin 疑難排解](/docs/zh-TW/plugins/troubleshooting#does-not-load-so-claude-code-ignores-the-whole-file) |

274| `its marketplace entry path does not stay inside the marketplace directory` | [Plugin 錯誤](#marketplace-entry-path-does-not-stay-inside-the-marketplace-directory) |276| `its marketplace entry path does not stay inside the marketplace directory` | [Plugin 錯誤](#marketplace-entry-path-does-not-stay-inside-the-marketplace-directory) |

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

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

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)。

3990`plugin eval` is currently unavailable3993`plugin eval` is currently unavailable

3991```3994```

3992 3995

3993第一則訊息表示您的組建版本早於 v2.1.269，這是該命令正式推出的第一個版本。第二則訊息表示 Anthropic 已在伺服器端關閉該命令；您的機器上沒有任何設定可以將其重新開啟。3996第一則訊息表示您的建置版本早於 v2.1.269，這是該命令正式推出的第一個版本。第二則訊息表示 Anthropic 已在伺服器端關閉該命令；您的機器上沒有任何設定可以將其重新開啟。

3994 3997

3995**該怎麼做：**3998**該怎麼做：**

3996 3999

3997* 執行 `claude --version`，然後執行 `claude update`，並在新的工作階段中再次執行該命令。請參閱 [plugin evals 的需求](/docs/zh-TW/plugin-evals#requirements)4000* 執行 `claude --version`，然後執行 `claude update`，並在新的工作階段中再次執行該命令。請參閱 [plugin evals 的需求](/docs/zh-TW/plugin-evals#requirements)

3998* 如果您在目前的組建版本上看到第二則訊息，請在執行另一個 `claude update` 後稍後再試一次4001* 如果您在目前的建置版本上看到第二則訊息，請在執行另一個 `claude update` 後稍後再試一次

3999 4002

4000<h3 id="marketplace-is-registered-from-an-untrusted-source">4003<h3 id="marketplace-is-registered-from-an-untrusted-source">

4001 Marketplace 是從不受信任的來源註冊的4004 Marketplace 是從不受信任的來源註冊的

4002</h3>4005</h3>

4003 4006

4004Marketplace 是以 [為官方 Anthropic marketplace 保留的名稱](/docs/zh-TW/plugins/marketplace-reference#marketplace-file) 註冊的，但其註冊的來源不是 `anthropics` GitHub 儲存庫。Claude Code 每次載入或重新整理 marketplace 時都會重新檢查保留的名稱，因此 marketplace 及從中安裝的 plugin 會停止載入。在 v2.1.205 之前，名稱只在新增 marketplace 時檢查，因此在其名稱變成保留名稱之前註冊的項目會繼續載入。4007Marketplace 是以 [為官方 Anthropic marketplace 保留的名稱](/docs/zh-TW/plugins/marketplace-reference#marketplace-file) 註冊的，但其註冊的來源不是 `anthropics` GitHub 儲存庫。Claude Code 每次載入或重新整理 marketplace 時都會重新檢查保留的名稱，因此 marketplace 及從中安裝的 plugin 會停止載入。在 v2.1.205 之前，在其名稱變成保留名稱之前註冊的項目會繼續載入。

4005 4008

4006```text theme={null}4009```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.4010Marketplace "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 名稱是保留名稱的另一種拼寫4022 Marketplace 名稱是保留名稱的另一種拼寫

4020</h3>4023</h3>

4021 4024

4022Marketplace 的名稱本身不是保留名稱，但 Claude Code 將其視為另一種拼寫。[保留的 marketplace 名稱](/docs/zh-TW/plugins/marketplace-reference#reserved-name-spellings) 列出哪些拼寫算作保留名稱。Claude Code 在您新增 marketplace 時拒絕這樣的名稱：4025Marketplace 的名稱本身不是保留名稱，但 Claude Code 將其視為某個保留名稱的另一種拼寫。[保留名稱](/docs/zh-TW/plugins/marketplace-reference#reserved-name-spellings) 列出哪些拼寫算作保留名稱。Claude Code 在您新增 marketplace 時拒絕這樣的名稱：

4023 4026

4024```text theme={null}4027```text theme={null}

4025Failed to add marketplace: "claude.code.plugins" is another spelling of "claude-code-plugins", a reserved marketplace name.4028Failed to add marketplace: "claude.code.plugins" is another spelling of "claude-code-plugins", a reserved marketplace name.

4064 Marketplace 已從不同的來源新增4067 Marketplace 已從不同的來源新增

4065</h3>4068</h3>

4066 4069

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 不會被安裝。4070您在工作階段中或從 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 4071

4069```text theme={null}4072```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.4073Marketplace "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 4140

4138在 `claude plugin` 命令輸出中，相同的錯誤讀作 `Path escapes plugin directory: ./../shared.md (commands)`。4141在 `claude plugin` 命令輸出中，相同的錯誤讀作 `Path escapes plugin directory: ./../shared.md (commands)`。

4139 4142

4140Claude Code 拒絕指向 plugin 外部的路徑（如 `../shared-utils`）和導致 plugin 外部的符號連結，以及 [marketplace 符號連結規則](/docs/zh-TW/plugins/host-marketplace#share-files-within-a-marketplace-with-symlinks) 不允許的符號連結。對於符號連結，訊息也會說明路徑解析的位置：4143Claude Code 會拒絕字面上指向 plugin 外部的路徑（例如 `../shared-utils`），以及導向 plugin 外部且不屬於 [marketplace 符號連結規則](/docs/zh-TW/plugins/host-marketplace#share-files-within-a-marketplace-with-symlinks) 所允許的符號連結。對於符號連結，訊息也會說明路徑解析的位置：

4141 4144

4142```text theme={null}4145```text theme={null}

4143commands path escapes plugin directory: ./commands/deploy.md — it resolves to /home/user/shared/deploy.md, outside the plugin directory4146commands path escapes plugin directory: ./commands/deploy.md — it resolves to /home/user/shared/deploy.md, outside the plugin directory

4144```4147```

4145 4148

4146在 macOS 和 Linux 上，Claude Code 也拒絕包含反斜線的元件路徑，即使路徑保持在 plugin 內。使用 Windows 風格分隔符的元件路徑的 plugin 在 Windows 上載入並在其他平台上觸發此拒絕：4149在 macOS 和 Linux 上，Claude Code 也拒絕任何位置包含反斜線的元件路徑，即使路徑保持在 plugin 內。使用 Windows 風格分隔符的元件路徑的 plugin 在 Windows 上載入並在其他平台上觸發此拒絕：

4147 4150

4148```text theme={null}4151```text theme={null}

4149commands path escapes plugin directory: ./commands\deploy.md — its path contains a backslash, which is not resolved reliably on this platform4152commands path escapes plugin directory: ./commands\deploy.md — its path contains a backslash, which is not resolved reliably on this platform

4150```4153```

4151 4154

4152在 v2.1.251 之前，Claude Code 載入在 marketplace 項目中宣告的 `commands` 路徑，即使它指向 plugin 目錄外。Claude Code 已經拒絕在 `plugin.json` 中宣告的路徑和 marketplace 項目中的其他元件路徑。4155在 v2.1.251 之前，Claude Code 載入在 marketplace 項目中宣告的 `commands` 路徑，即使它指向 plugin 目錄外。

4153 4156

4154在 v2.1.257 之前，檢查只查看路徑的拼寫，而不是符號連結導向的位置。4157在 v2.1.257 之前，檢查只查看路徑的拼寫，而不是符號連結導向的位置。

4155 4158

4217 4220

4218**該怎麼做：**4221**該怎麼做：**

4219 4222

4220* 如果您維護 marketplace，將項目的 `source` 寫成純相對路徑（例如 `./plugins/my-plugin`），並保持它跨越的任何符號連結指向 marketplace 目錄內4223* 如果您維護 marketplace，將項目的 `source` 寫成使用正斜線的純相對路徑（例如 `./plugins/my-plugin`），並保持它跨越的任何符號連結指向 marketplace 目錄內

4221* 如果您從直接 URL 新增了 marketplace，相對項目無法解析。要求 marketplace 作者使用 [另一個 plugin 來源](/docs/zh-TW/plugins/marketplace-reference#plugin-sources)，或改為從其 git 儲存庫新增 marketplace4224* 如果您從直接 URL 新增了 marketplace，相對項目無法解析。要求 marketplace 作者使用 [另一個 plugin 來源](/docs/zh-TW/plugins/marketplace-reference#plugin-sources)，或改為從其 git 儲存庫新增 marketplace

4222 4225

4223<h3 id="failed-to-load-marketplace-configuration">4226<h3 id="failed-to-load-marketplace-configuration">

4226 4229

4227Claude Code 將您新增的 plugin marketplace 保留在 `~/.claude/plugins/known_marketplaces.json` 的登錄檔案中。當 Claude Code 無法使用該檔案時，需要登錄的 plugin 命令（例如 `claude plugin install`）會失敗，並顯示以下兩則訊息之一：4230Claude Code 將您新增的 plugin marketplace 保留在 `~/.claude/plugins/known_marketplaces.json` 的登錄檔案中。當 Claude Code 無法使用該檔案時，需要登錄的 plugin 命令（例如 `claude plugin install`）會失敗，並顯示以下兩則訊息之一：

4228 4231

4229* `Failed to load marketplace configuration`：檔案不是有效的 JSON，或無法讀取。空檔案也會以這種方式失敗。4232* `Failed to load marketplace configuration`：檔案存在，但不是有效的 JSON，或無法讀取。空檔案也會以這種方式失敗。

4230* `Marketplace configuration file is corrupted`：檔案是有效的 JSON，但其內容與登錄架構不符。4233* `Marketplace configuration file is corrupted`：檔案是有效的 JSON，但其內容與登錄 schema 不符。

~~4231~~

4232遺失的檔案不是失敗：Claude Code 將其視為沒有 marketplace 的登錄。

4233 4234

4234使用空檔案時，`claude plugin install` 報告：4235使用空檔案時，`claude plugin install` 報告：

4235 4236

4241 4242

4242**該怎麼做：**4243**該怎麼做：**

4243 4244

4244* 開啟 `~/.claude/plugins/known_marketplaces.json` 並修復 JSON，或修復訊息命名為與登錄架構不符的項目4245* 開啟 `~/.claude/plugins/known_marketplaces.json` 並修復 JSON，或修復訊息命名為與登錄 schema 不符的項目

4245* 如果您無法修復它，刪除檔案或用 `{}` 替換其內容，然後使用 `claude plugin marketplace add <source>` 重新新增每個 marketplace。Claude Code 在您下次在已信任的資料夾中啟動它時，重新註冊您的使用者或受管設定在 [`extraKnownMarketplaces`](/docs/zh-TW/settings-reference#extraknownmarketplaces) 中宣告的 marketplace。4246* 如果您無法修復它，刪除檔案或用 `{}` 替換其內容，然後使用 `claude plugin marketplace add <source>` 重新新增每個 marketplace。Claude Code 在您下次在已信任的資料夾中啟動它時，重新註冊您的使用者或受管設定在 [`extraKnownMarketplaces`](/docs/zh-TW/settings-reference#extraknownmarketplaces) 中宣告的 marketplace。

4246 4247

4247<h3 id="plugin-is-required-by-your-organization">4248<h3 id="plugin-is-required-by-your-organization">

4819 This session has no saved transcript4820 This session has no saved transcript

4820</h3>4821</h3>

4821 4822

4822您附加到已停止的[背景工作階段](/docs/zh-TW/agent-view)，該工作階段使用 `←` 或 `/background` 從另一個對話背景化，並在其第一個回應完成之前停止。在該第一個回應完成之前，對話仍然只存在於背景化它的工作階段中，因此 `claude attach` 拒絕啟動已停止的工作階段，而不是在相同工作階段 ID 下開始空白對話。訊息以此工作階段的 `claude respawn` 命令結尾：4823您附加到一個您以 `←` 或 `/background` [移至背景](/docs/zh-TW/agent-view#from-inside-a-session)、且在執行自己的任何一個回合之前就已停止的工作階段。Claude Code 找不到您將其移出的那個對話，因此該工作階段沒有可繼續的內容。訊息以此工作階段的 `claude respawn` 命令結尾：

4823 4824

4824```text theme={null}4825```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.4826This 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 4830

4830**該怎麼做：**4831**該怎麼做：**

4831 4832

4832* 您背景化的對話完整無缺：使用 [`claude --resume`](/docs/zh-TW/sessions) 繼續它或繼續在其中工作4833* 若要全新重新啟動已停止的工作階段，請使用訊息中的 ID 執行 `claude respawn <id>`，或在 agent 檢視中的其列上按 `Enter` 兩次

4833* 若仍要重新啟動已停止的工作階段，請使用訊息中的 ID 執行 `claude respawn <id>`，或在 agent 檢視中的其列上按 `Enter` 兩次

4834* 如果工作階段確實完成了回應，而您在 v2.1.214 之前的版本上仍看到此拒絕，`~/.claude/projects` 中的不可讀資料夾可能會使逐字稿掃描遺漏已儲存的對話；請更新到 v2.1.214 或更新版本，其在掃描期間容許不可讀資料夾4834* 如果工作階段確實完成了回應，而您在 v2.1.214 之前的版本上仍看到此拒絕，`~/.claude/projects` 中的不可讀資料夾可能會使逐字稿掃描遺漏已儲存的對話；請更新到 v2.1.214 或更新版本，其在掃描期間容許不可讀資料夾

4835 4835

4836<h3 id="this-session-is-running-in-another-terminal">4836<h3 id="this-session-is-running-in-another-terminal">

glossary.md +1 −1

Details

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` |

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

mcp.md +1 −1

Details

367 367

368在 v2 上，Claude Code 也：368在 v2 上，Claude Code 也：

369 369

370* 詢問 HTTP 和 stdio 伺服器是否支援較新的修訂，並與支援的伺服器一起使用它。在擷取功能旗標的工作階段中，它也會詢問 claude.ai 連接器伺服器。它連接到每個其他伺服器，如 v1 所做的那樣。370* 詢問 HTTP、stdio 和 claude.ai 連接器伺服器是否支援較新的修訂，並與支援的伺服器一起使用它。它連接到每個其他伺服器，如 v1 所做的那樣。

371* 在 [它保持開啟的流](#notification-streams-on-the-v2-runtime)上從較新修訂上的伺服器接收 `list_changed` 通知。371* 在 [它保持開啟的流](#notification-streams-on-the-v2-runtime)上從較新修訂上的伺服器接收 `list_changed` 通知。

372* 不註冊在較新修訂上連接的 [頻道](#push-messages-with-channels)伺服器，因為該修訂無法攜帶頻道訊息。372* 不註冊在較新修訂上連接的 [頻道](#push-messages-with-channels)伺服器，因為該修訂無法攜帶頻道訊息。

373* 失敗 [MCP OAuth 登入](#authenticate-with-remote-mcp-servers)，其授權回應命名意外發行者。373* 失敗 [MCP OAuth 登入](#authenticate-with-remote-mcp-servers)，其授權回應命名意外發行者。

monitoring-usage.md +413 −405

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

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/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

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 七天過期

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`。

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。

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 +1 −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**。

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 21:01 UTC