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

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

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 終端機主機已終止或工作階段停止回應

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

Details

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 +15 −18

Details

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

387* 連線中斷。當連線在 Claude 完成其回應的任何部分（包括其思考）之前中途中斷時，Claude Code 會以相同的退避方式重新發出請求，並且回合會繼續，即使某些文字已經開始串流。當連線在 Claude 完成思考之後但在開始任何文字或工具呼叫之前中斷時，Claude Code 會改為快速連續重新發出請求最多兩次，如果連線在該點持續中斷，則以 `Connection lost before a response was produced` 結束回合。387* 連線中斷。當連線在 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`。388* 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` 結束回合。389* 停滯的回應串流，當回應標頭已到達但 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` 時，一次重試上限不適用。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` 時，一次重試上限不適用。

391* 在 Claude 完成思考或開始任何文字或工具呼叫之前，被 API 輸出內容過濾器停止的串流回應。Claude Code 會在重試預算內重新發送請求一次，如果過濾器也停止了第二個回應，則顯示 [Output blocked by content filtering policy](#output-blocked-by-content-filtering-policy)。391* 在 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)。392* 暫時性 429 節流，但不是閘道的支出限制 `429`，這不是節流；請參閱 [Spend limit reached](#spend-limit-reached)。

3990`plugin eval` is currently unavailable3990`plugin eval` is currently unavailable

3991```3991```

3992 3992

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

3994 3994

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

3996 3996

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

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

3999 3999

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

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

4002</h3>4002</h3>

4003 4003

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

4005 4005

4006```text theme={null}4006```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.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.

4019 Marketplace 名稱是保留名稱的另一種拼寫4019 Marketplace 名稱是保留名稱的另一種拼寫

4020</h3>4020</h3>

4021 4021

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

4023 4023

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

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

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

4065</h3>4065</h3>

4066 4066

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

4069```text theme={null}4069```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.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.

4137 4137

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

4139 4139

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

4141 4141

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

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

4144```4144```

4145 4145

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

4147 4147

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

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

4150```4150```

4151 4151

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

4153 4153

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

4155 4155

4217 4217

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

4219 4219

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

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

4222 4222

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

4226 4226

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

4228 4228

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

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

~~4231~~

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

4233 4231

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

4235 4233

4241 4239

4242**該怎麼做：**4240**該怎麼做：**

4243 4241

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

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

4246 4244

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

4819 This session has no saved transcript4817 This session has no saved transcript

4820</h3>4818</h3>

4821 4819

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

4823 4821

4824```text theme={null}4822```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.4823This 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 4827

4830**該怎麼做：**4828**該怎麼做：**

4831 4829

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

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

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

4835 4832

4836<h3 id="this-session-is-running-in-another-terminal">4833<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 +19 −8

Details

1237 SessionStart 決策控制1237 SessionStart 決策控制

1238</h4>1238</h4>

1239 1239

1240Claude Code 會將其[視為純文字](#exit-code-0)的 stdout 加入 Claude 的上下文。除了所有 hook 都可使用的 [JSON 輸出欄位](#json-output)之外，您還可以傳回下列事件專屬欄位：1240SessionStart hook 可以為 Claude 新增上下文、提供第一則使用者訊息、設定工作階段標題、監看檔案，以及重新載入 skill。除了所有 hook 皆可使用的 [JSON 輸出欄位](#json-output)之外，請針對每項功能傳回對應的欄位：

1241 1241

1242| 欄位 | 說明 |1242| 欄位 | 說明 |

1243| :- | :- |1243| :- | :- |

1245| `initialUserMessage` | 用作工作階段第一則使用者訊息的字串。適用於使用 `-p` 旗標的[非互動模式](/docs/zh-TW/headless)，即使未提供提示詞，它也會成為第一個回合。如果提供了提示詞，提示詞會作為下一個回合接續。與附加到既有回合的 `additionalContext` 不同，此欄位會建立該回合 |1245| `initialUserMessage` | 在使用 `-p` 旗標的[非互動模式](/docs/zh-TW/headless)中，作為工作階段第一則使用者訊息的字串。即使您未傳入提示詞，它也會成為第一個回合。您傳入的提示詞則會作為下一個回合 |

1246| `sessionTitle` | 設定工作階段標題，效果與 `/rename` 相同。可用來依據啟動資料夾、git 分支或 worktree 名稱自動命名工作階段。在 `source` 為 `"startup"`、`"resume"` 或 `"fork"` 時套用；在 `"clear"` 和 `"compact"` 時忽略 |1246| `sessionTitle` | 設定工作階段標題，效果與 `/rename` 相同。當 `source` 為 `"startup"`、`"resume"` 或 `"fork"` 時適用 |

1248| `reloadSkills` | 布林值。為 `true` 時，Claude Code 會在 SessionStart hook 完成後重新掃描 [skill](/docs/zh-TW/skills) 和命令目錄，讓 hook 安裝的 skill 從第一個提示詞開始就能在同一個工作階段中使用 |1248| `reloadSkills` | 布林值。為 `true` 時，Claude Code 會在 SessionStart hook 完成後重新掃描 [skill](/docs/zh-TW/skills) 和命令目錄。請參閱[重新載入 hook 安裝的 skill](#reload-skills-that-a-hook-installs) |

1249

1250此輸出會新增上下文並為工作階段命名：

1249 1251

1250```json theme={null}1252```json theme={null}

1251{1253{

1257}1259}

1258```1260```

1259 1261

1260由於此事件的純 stdout 已會傳達給 Claude，只載入上下文的 hook 可以直接輸出到 stdout，無須建構 JSON。當您需要將上下文與 `sessionTitle` 等其他欄位結合時，請使用 JSON 格式。1262只新增上下文的 hook 可以直接輸出內容而不必建構 JSON，因為 Claude Code 會將 SessionStart hook 的[純文字 stdout](#exit-code-0) 加入 Claude 的上下文。

1263

1264如果您外掛的 SessionStart hook 提供 `initialUserMessage` 或 `sessionTitle`，請在工作階段開始前安裝該外掛。對於在 SessionStart hook 執行後才完成安裝的外掛，Claude Code 會忽略這兩個欄位。

1265

1266<h4 id="reload-skills-that-a-hook-installs">

1267 重新載入 hook 安裝的 skill

1268</h4>

1269

1270若要讓 SessionStart hook 安裝的 skill 在同一個工作階段中可用，請傳回 `reloadSkills`。skill 探索通常會在 SessionStart hook 完成之前執行，因此若沒有此欄位，hook 寫入 `~/.claude/skills/` 或 `.claude/skills/` 的檔案可能在第一個提示詞執行時尚不存在。

1261 1271

1262當 SessionStart hook 會安裝或更新 skill 時，請使用 `reloadSkills`。skill 探索通常會在 SessionStart hook 完成之前執行，因此 hook 寫入 `~/.claude/skills/` 或 `.claude/skills/` 的檔案，否則只會在下一個工作階段中出現。此範例會同步共用的 skill 儲存庫並請求重新掃描：1272此範例會同步共用的 skill 儲存庫並請求重新掃描：

1263 1273

1264```bash theme={null}1274```bash theme={null}

1265#!/bin/bash1275#!/bin/bash

1270echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'1280echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'

1271```1281```

1272 1282

1273儲存庫 URL 只是預留位置，請替換為您自己的 skill 儲存庫。使用預留位置時，clone 會失敗並在 stderr 輸出 `fatal:` 訊息。以 0 結束的 SessionStart hook 的 stderr 僅供參考，因此 `reloadSkills` 請求仍會套用。1283儲存庫 URL 僅為預留位置。請替換為您自己的 skill 儲存庫。

1274 1284

1275<h4 id="persist-environment-variables">1285<h4 id="persist-environment-variables">

1276 保存環境變數1286 保存環境變數

1860| :- | :- | :- | :- |1870| :- | :- | :- | :- |

1863 1874

1864<h5 id="websearch">1875<h5 id="websearch">

1865 WebSearch1876 WebSearch

4278非同步 hooks 與同步 hooks 相比有額外的限制：4289非同步 hooks 與同步 hooks 相比有額外的限制：

4279 4290

4280* Hook 輸出在下一個對話輪次上傳遞。如果工作階段閒置，回應會等待直到下一個使用者互動。例外：退出代碼為 2 的 `asyncRewake` hook 即使在工作階段閒置時也會立即喚醒 Claude。4291* Hook 輸出在下一個對話輪次上傳遞。如果工作階段閒置，回應會等待直到下一個使用者互動。例外：退出代碼為 2 的 `asyncRewake` hook 即使在工作階段閒置時也會立即喚醒 Claude。

4281* 每次執行都會建立一個單獨的背景程序。同一非同步 hook 的多次觸發之間沒有去重。4292* 每次執行都會建立一個單獨的背景程序。

4282 4293

4283<h2 id="security-considerations">4294<h2 id="security-considerations">

4284 安全考慮4295 安全考慮

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 +411 −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 參考附件與目錄列出失敗）會直接返回而不記錄。

1192 1196

1193**事件名稱**：`claude_code.at_mention`1197**事件名稱**：`claude_code.at_mention`

1194 1198

1197* 所有[標準屬性](#standard-attributes)1201* 所有[標準屬性](#standard-attributes)

1198* `event.name`：`"at_mention"`1202* `event.name`：`"at_mention"`

1199* `event.timestamp`：ISO 8601 時間戳記1203* `event.timestamp`：ISO 8601 時間戳記

1200* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述1204* `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 或更新版本1205* `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"`）1206* `success`：提及是否成功解析（`"true"` 或 `"false"`）

1203 1207

1204<h4 id="api-retries-exhausted-event">1208<h4 id="api-retries-exhausted-event">

1205 API 重試已耗盡事件1209 API 重試用盡事件

1206</h4>1210</h4>

1207 1211

1208當 API 請求在多次嘗試後失敗時記錄一次。與最終 `api_error` 事件一起發出。1212當 API 請求在多次嘗試後失敗時記錄一次。與最終的 `api_error` 事件一同發出。

1209 1213

1210**事件名稱**：`claude_code.api_retries_exhausted`1214**事件名稱**：`claude_code.api_retries_exhausted`

1211 1215

1214* 所有[標準屬性](#standard-attributes)1218* 所有[標準屬性](#standard-attributes)

1215* `event.name`：`"api_retries_exhausted"`1219* `event.name`：`"api_retries_exhausted"`

1216* `event.timestamp`：ISO 8601 時間戳記1220* `event.timestamp`：ISO 8601 時間戳記

1217* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述1221* `event.sequence`：用於排序事件的每程序計數器，說明請參閱[事件關聯屬性](#event-correlation-attributes)

1218* `model`：使用的模型1222* `model`：使用的模型

1219* `error`：最終錯誤消息1223* `error`：最終錯誤訊息

1220* `status_code`：HTTP 狀態碼作為數字。對於非 HTTP 錯誤不存在。1224* `status_code`：以數字表示的 HTTP 狀態碼。對於非 HTTP 錯誤不存在。

1221* `total_attempts`：進行的嘗試總數1225* `total_attempts`：嘗試的總次數

1222* `total_retry_duration_ms`：所有嘗試中的總牆上時間1226* `total_retry_duration_ms`：所有嘗試的總實際經過時間

1223* `speed`：`"fast"` 或 `"normal"`1227* `speed`：`"fast"` 或 `"normal"`

1224 1228

1225<h4 id="hook-registered-event">1229<h4 id="hook-registered-event">

1226 鉤子已註冊事件1230 Hook 註冊事件

1227</h4>1231</h4>

1228 1232

1229在工作階段開始時為每個配置的鉤子記錄一次。使用此事件來清點您的整個車隊中哪些鉤子有效，作為每個執行 `hook_execution_start` 和 `hook_execution_complete` 事件的補充。1233在工作階段開始時，針對每個已設定的 hook 記錄一次。可使用此事件盤點整個裝置群中作用中的 hook，作為每次執行之 `hook_execution_start` 與 `hook_execution_complete` 事件的補充。

1230 1234

1231**事件名稱**：`claude_code.hook_registered`1235**事件名稱**：`claude_code.hook_registered`

1232 1236

1235* 所有[標準屬性](#standard-attributes)1239* 所有[標準屬性](#standard-attributes)

1236* `event.name`：`"hook_registered"`1240* `event.name`：`"hook_registered"`

1237* `event.timestamp`：ISO 8601 時間戳記1241* `event.timestamp`：ISO 8601 時間戳記

1238* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述1242* `event.sequence`：用於排序事件的每程序計數器，說明請參閱[事件關聯屬性](#event-correlation-attributes)

1239* `hook_event`：鉤子事件類型，例如 `"PreToolUse"` 或 `"PostToolUse"`1243* `hook_event`：hook 事件類型，例如 `"PreToolUse"` 或 `"PostToolUse"`

1240* `hook_type`：鉤子實現類型：`"command"`、`"prompt"`、`"mcp_tool"`、`"http"` 或 `"agent"`1244* `hook_type`：hook 實作類型：`"command"`、`"prompt"`、`"mcp_tool"`、`"http"` 或 `"agent"`

1241* `hook_source`：鉤子定義的位置：`"userSettings"`、`"projectSettings"`、`"localSettings"`、`"flagSettings"`、`"policySettings"` 或 `"pluginHook"`1245* `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 或更新版本1246* `safe_mode`：當工作階段以 [`--safe-mode`](/docs/zh-TW/cli-reference) 啟動時為 `"true"`，否則為 `"false"`。需要 Claude Code v2.1.169 或更新版本

1243* `hook_matcher`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：鉤子配置中的匹配器字串（設定時）1247* `hook_matcher`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：hook 設定中的 matcher 字串（有設定時）

1244* `plugin.name`（當 `hook_source` 為 `"pluginHook"` 時）：貢獻外掛程式的名稱。對於官方市場和內建捆綁之外的外掛程式，該值為 `"third-party"`，除非 `OTEL_LOG_TOOL_DETAILS=1`1248* `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)下描述的方式計算它1249* `plugin_id_hash`（當 `hook_source` 為 `"pluginHook"` 時）：外掛名稱與市集的確定性雜湊值，僅傳送給您設定的匯出器。可讓您在不記錄名稱的情況下計算提供 hook 的不同外掛數量。Claude Code 的計算方式如[外掛載入事件](#plugin-loaded-event)中所述

1246 1250

1247<h4 id="hook-execution-start-event">1251<h4 id="hook-execution-start-event">

1248 鉤子執行開始事件1252 Hook 執行開始事件

1249</h4>1253</h4>

1250 1254

1251當一個或多個鉤子開始為鉤子事件執行時記錄。1255當一個或多個 hook 開始針對某個 hook 事件執行時記錄。

1252 1256

1253**事件名稱**：`claude_code.hook_execution_start`1257**事件名稱**：`claude_code.hook_execution_start`

1254 1258

1257* 所有[標準屬性](#standard-attributes)1261* 所有[標準屬性](#standard-attributes)

1258* `event.name`：`"hook_execution_start"`1262* `event.name`：`"hook_execution_start"`

1259* `event.timestamp`：ISO 8601 時間戳記1263* `event.timestamp`：ISO 8601 時間戳記

1260* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述1264* `event.sequence`：用於排序事件的每程序計數器，說明請參閱[事件關聯屬性](#event-correlation-attributes)

1261* `hook_event`：鉤子事件類型，例如 `"PreToolUse"` 或 `"PostToolUse"`1265* `hook_event`：Hook 事件類型，例如 `"PreToolUse"` 或 `"PostToolUse"`

1262* `hook_name`：完整鉤子名稱，包括匹配器，例如 `"PreToolUse:Write"`1266* `hook_name`：包含 matcher 的完整 hook 名稱，例如 `"PreToolUse:Write"`

1263* `num_hooks`：匹配鉤子命令的數量1267* `num_hooks`：相符的 hook 命令數量

1264* `managed_only`：當僅允許管理原則鉤子時為 `"true"`1268* `managed_only`：當僅允許受管政策 hook 時為 `"true"`

1265* `hook_source`：`"policySettings"` 或 `"merged"`1269* `hook_source`：`"policySettings"` 或 `"merged"`

1266* `safe_mode`：當工作階段以 [`--safe-mode`](/docs/zh-TW/cli-reference) 啟動時為 `"true"`，否則為 `"false"`。需要 Claude Code v2.1.169 或更新版本1270* `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` 都啟用時才包含1271* `hook_definitions`：JSON 序列化後的 hook 設定。僅在同時啟用詳細 beta 追蹤與 `OTEL_LOG_TOOL_DETAILS=1` 時包含

1268 1272

1269<h4 id="hook-execution-complete-event">1273<h4 id="hook-execution-complete-event">

1270 鉤子執行完成事件1274 Hook 執行完成事件

1271</h4>1275</h4>

1272 1276

1273當鉤子事件的所有鉤子完成時記錄。1277當某個 hook 事件的所有 hook 都已完成時記錄。

1274 1278

1275**事件名稱**：`claude_code.hook_execution_complete`1279**事件名稱**：`claude_code.hook_execution_complete`

1276 1280

1279* 所有[標準屬性](#standard-attributes)1283* 所有[標準屬性](#standard-attributes)

1280* `event.name`：`"hook_execution_complete"`1284* `event.name`：`"hook_execution_complete"`

1281* `event.timestamp`：ISO 8601 時間戳記1285* `event.timestamp`：ISO 8601 時間戳記

1282* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述1286* `event.sequence`：用於排序事件的每程序計數器，說明請參閱[事件關聯屬性](#event-correlation-attributes)

1283* `hook_event`：鉤子事件類型1287* `hook_event`：Hook 事件類型

1284* `hook_name`：完整鉤子名稱，包括匹配器1288* `hook_name`：包含 matcher 的完整 hook 名稱

1285* `num_hooks`：匹配鉤子命令的數量1289* `num_hooks`：相符的 hook 命令數量

1286* `num_success`：成功完成的計數1290* `num_success`：成功完成的數量

1287* `num_blocking`：傳回阻止決定的計數1291* `num_blocking`：傳回阻擋決定的數量

1288* `num_non_blocking_error`：在不阻止的情況下失敗的計數1292* `num_non_blocking_error`：失敗但未阻擋的數量

1289* `num_cancelled`：在完成前取消的計數1293* `num_cancelled`：完成前被取消的數量

1290* `total_duration_ms`：所有匹配鉤子的牆上持續時間1294* `total_duration_ms`：所有相符 hook 的實際經過時間

1291* `stdout_chars`：成功的匹配鉤子中的 stdout 總字元數。需要 Claude Code v2.1.280 或更新版本1295* `stdout_chars`：成功之相符 hook 的 stdout 總字元數。需要 Claude Code v2.1.280 或更新版本

1292* `additional_context_chars`：匹配鉤子傳回的 `additionalContext` 的總字元數。需要 Claude Code v2.1.280 或更新版本1296* `additional_context_chars`：相符 hook 傳回之 `additionalContext` 的總字元數。需要 Claude Code v2.1.280 或更新版本

1293* `system_message_chars`：匹配鉤子傳回的 `systemMessage` 的總字元數。需要 Claude Code v2.1.280 或更新版本1297* `system_message_chars`：相符 hook 傳回之 `systemMessage` 的總字元數。需要 Claude Code v2.1.280 或更新版本

1294* `initial_user_message_chars`：匹配鉤子傳回的 `initialUserMessage` 的總字元數。需要 Claude Code v2.1.280 或更新版本1298* `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 或更新版本1299* `num_outputs_persisted`：超過 [10,000 字元上限](/docs/zh-TW/hooks#json-output)而由 Claude Code 儲存至檔案的 hook 輸出數量。需要 Claude Code v2.1.280 或更新版本

1296* `managed_only`：當僅允許管理原則鉤子時為 `"true"`1300* `managed_only`：當僅允許受管政策 hook 時為 `"true"`

1297* `hook_source`：`"policySettings"` 或 `"merged"`1301* `hook_source`：`"policySettings"` 或 `"merged"`

1298* `safe_mode`：當工作階段以 [`--safe-mode`](/docs/zh-TW/cli-reference) 啟動時為 `"true"`，否則為 `"false"`。需要 Claude Code v2.1.169 或更新版本1302* `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` 都啟用時才包含1303* `hook_definitions`：JSON 序列化後的 hook 設定。僅在同時啟用詳細 beta 追蹤與 `OTEL_LOG_TOOL_DETAILS=1` 時包含

1300 1304

1301<h4 id="hook-plugin-metrics-event">1305<h4 id="hook-plugin-metrics-event">

1302 鉤子外掛程式指標事件1306 Hook 外掛指標事件

1303</h4>1307</h4>

1304 1308

1305當官方市場外掛程式鉤子發出每次呼叫指標時記錄。只有從官方 Anthropic 市場安裝的外掛程式才能發出這些。第三方市場外掛程式和使用者配置的鉤子不發出到此事件。使用此事件從您自己的可觀測性堆疊監控外掛程式行為，例如尋找率、成本和持續時間。1309當官方市集外掛的 hook 發出每次呼叫的指標時記錄。只有從 Anthropic 官方市集安裝的外掛才能發出這些指標。第三方市集外掛與使用者設定的 hook 不會發出此事件。可使用此事件從您自己的可觀測性堆疊監控外掛行為，例如發現率、成本與持續時間。

1306 1310

1307**事件名稱**：`claude_code.hook_plugin_metrics`1311**事件名稱**：`claude_code.hook_plugin_metrics`

1308 1312

1311* 所有[標準屬性](#standard-attributes)1315* 所有[標準屬性](#standard-attributes)

1312* `event.name`：`"hook_plugin_metrics"`1316* `event.name`：`"hook_plugin_metrics"`

1313* `event.timestamp`：ISO 8601 時間戳記1317* `event.timestamp`：ISO 8601 時間戳記

1314* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述1318* `event.sequence`：用於排序事件的每程序計數器，說明請參閱[事件關聯屬性](#event-correlation-attributes)

1315* `plugin_id`：`<name>@<marketplace>` 形式的外掛程式識別碼1319* `plugin_id`：`<name>@<marketplace>` 形式的外掛識別碼

1316* `hook_event`：發出指標的鉤子事件類型1320* `hook_event`：發出指標的 hook 事件類型

1317* 最多 20 個由外掛發出的指標鍵。名稱符合 `^[a-z][a-z0-9_]{0,39}$`。值為布林值或數字。1321* 最多 20 個外掛發出的指標鍵。名稱需符合 `^[a-z][a-z0-9_]{0,39}$`。值為布林值或數字。

1318 1322

1319<h4 id="compaction-event">1323<h4 id="compaction-event">

1320 壓縮事件1324 壓縮事件

1321</h4>1325</h4>

1322 1326

1323當對話壓縮完成時記錄。1327在對話壓縮完成時記錄。

1324 1328

1325**事件名稱**：`claude_code.compaction`1329**事件名稱**：`claude_code.compaction`

1326 1330

1329* 所有[標準屬性](#standard-attributes)1333* 所有[標準屬性](#standard-attributes)

1330* `event.name`：`"compaction"`1334* `event.name`：`"compaction"`

1331* `event.timestamp`：ISO 8601 時間戳記1335* `event.timestamp`：ISO 8601 時間戳記

1332* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述1336* `event.sequence`：用於排序事件的每程序計數器，說明請參閱[事件關聯屬性](#event-correlation-attributes)

1333* `trigger`：`"auto"` 或 `"manual"`1337* `trigger`：`"auto"` 或 `"manual"`

1334* `success`：`"true"` 或 `"false"`1338* `success`：`"true"` 或 `"false"`

1335* `duration_ms`：壓縮持續時間1339* `duration_ms`：壓縮持續時間

1336* `pre_tokens`：壓縮前的近似權杖計數1340* `pre_tokens`：壓縮前的約略 token 數量

1337* `post_tokens`：壓縮後的近似權杖計數1341* `post_tokens`：壓縮後的約略 token 數量

1338* `error`：壓縮失敗時的錯誤消息1342* `error`：壓縮失敗時的錯誤訊息

1339* `precompute_reuse`：僅在 `trigger` 為 `"manual"` 時設定。自動壓縮可在上下文視窗填滿之前於背景預先準備摘要，而此屬性記錄 `/compact` 是否重複使用了該預先準備的摘要。`"hit"` 表示已重複使用；`"miss_custom_instructions"`、`"miss_hook"` 與 `"miss_not_ready"` 則說明改為重新計算摘要的原因1343* `precompute_reuse`：僅在 `trigger` 為 `"manual"` 時設定。自動壓縮可在上下文視窗填滿前於背景準備摘要，此屬性記錄 `/compact` 是否重複使用了該預先準備的摘要。`"hit"` 表示已重複使用；`"miss_custom_instructions"`、`"miss_hook"` 與 `"miss_not_ready"` 則說明改為重新計算摘要的原因

1340 1344

1341<h4 id="subagent-completed-event">1345<h4 id="subagent-completed-event">

1342 子代理程式已完成事件1346 Subagent 完成事件

1343</h4>1347</h4>

1344 1348

1345當[子代理程式](/docs/zh-TW/sub-agents)完成並將其結果傳回啟動它的對話時記錄。使用它按子代理程式類型匯總工具使用和執行時間；對於權杖或成本匯總，使用[權杖計數器](#token-counter)和[成本計數器](#cost-counter)篩選到 `query_source` `"subagent"`，因為此事件的 `total_tokens` 僅涵蓋最終請求。`"subagent"` 類別也計算來自基於代理程式的鉤子的請求，它們不發出子代理程式事件。1349在 [subagent](/docs/zh-TW/sub-agents) 完成並將結果傳回啟動它的對話時記錄。可用於依 subagent 類型彙總工具使用情況與執行時間；若要彙總 token 或成本，請使用以 `query_source` `"subagent"` 篩選的 [token 計數器](#token-counter)與[成本計數器](#cost-counter)，因為此事件的 `total_tokens` 僅涵蓋最後一個請求。`"subagent"` 類別也會計入來自以 agent 為基礎之 hook 的請求，而這些 hook 不會發出 subagent 事件。

1346 1350

1347**事件名稱**：`claude_code.subagent_completed`1351**事件名稱**：`claude_code.subagent_completed`

1348 1352

1351* 所有[標準屬性](#standard-attributes)1355* 所有[標準屬性](#standard-attributes)

1352* `event.name`：`"subagent_completed"`1356* `event.name`：`"subagent_completed"`

1353* `event.timestamp`：ISO 8601 時間戳記1357* `event.timestamp`：ISO 8601 時間戳記

1354* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述1358* `event.sequence`：用於排序事件的每程序計數器，說明請見[事件關聯屬性](#event-correlation-attributes)

1355* `agent_type`：子代理程式類型。內建代理程式名稱和來自官方市場外掛程式的代理程式會逐字出現；其他代理程式名稱會被替換為 `"custom"`，除非設定了 `OTEL_LOG_TOOL_DETAILS=1`1359* `agent_type`：subagent 類型。內建 agent 名稱及來自官方市集外掛的 agent 會原樣顯示；除非設定了 `OTEL_LOG_TOOL_DETAILS=1`，否則其他 agent 名稱會以 `"custom"` 取代

1356* `agent.source`：代理程式定義的來源：`built-in`、`plugin` 或定義自訂代理程式的設定來源，例如 `userSettings` 或 `projectSettings`1360* `agent.source`：agent 定義的來源：`built-in`、`plugin`，或定義自訂 agent 的設定來源，例如 `userSettings` 或 `projectSettings`

1357* `is_built_in`：子代理程式是否為內建代理程式類型1361* `is_built_in`：subagent 是否為內建 agent 類型

1358* `is_async`：子代理程式是否在[背景](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)中執行1362* `is_async`：subagent 是否在[背景](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)執行

1359* `total_tokens`：子代理程式最終 API 請求的權杖足跡：該單個請求的輸入、快取建立、快取讀取和輸出權杖，大約是子代理程式在完成時的上下文大小。不是整個執行的總和1363* `total_tokens`：subagent 最後一個 API 請求的 token 用量：該請求的輸入、快取建立、快取讀取與輸出 token，大致等於 subagent 完成時的上下文大小。並非整個執行過程的總和

1360* `total_tool_uses`：子代理程式在整個執行中進行的工具呼叫數1364* `total_tool_uses`：subagent 在整個執行過程中進行的工具呼叫次數

1361* `duration_ms`：執行時間（以毫秒為單位）1365* `duration_ms`：執行時間（毫秒）

1362* `model`：子代理程式被解析為執行的模型1366* `model`：subagent 被解析為使用的模型

1363* `final_model`：產生子代理程式最終回應的模型，在中途切換（例如回退）後與 `model` 不同。需要 Claude Code v2.1.212 或更新版本1367* `final_model`：產生 subagent 最終回應的模型；在執行中途切換（例如備援）之後，此值會與 `model` 不同。需要 Claude Code v2.1.212 或更新版本

1364* `model_swapped`：是否有多個模型為子代理程式的請求提供服務。需要 Claude Code v2.1.212 或更新版本1368* `model_swapped`：是否有多個模型處理過 subagent 的請求。需要 Claude Code v2.1.212 或更新版本

1365* `plugin_id_hash`、`plugin.name`：對於外掛程式提供的代理程式存在。官方市場外掛程式名稱會逐字出現；其他外掛程式名稱會被替換為 `"third-party"`，除非設定了 `OTEL_LOG_TOOL_DETAILS=1`1369* `plugin_id_hash`、`plugin.name`：由外掛提供的 agent 才會出現。官方市集外掛名稱會原樣顯示；除非設定了 `OTEL_LOG_TOOL_DETAILS=1`，否則其他外掛名稱會以 `"third-party"` 取代

1366 1370

1367<h4 id="feedback-survey-event">1371<h4 id="feedback-survey-event">

1368 回饋調查事件1372 意見調查事件

1369</h4>1373</h4>

1370 1374

1371當顯示或回答工作階段品質調查時記錄。請參閱[工作階段品質調查](/docs/zh-TW/data-usage#session-quality-surveys)以了解調查收集的內容以及如何控制它們。1375在顯示或回答工作階段品質調查時記錄。關於調查收集的內容及如何控制，請參閱[工作階段品質調查](/docs/zh-TW/data-usage#session-quality-surveys)。

1372 1376

1373**事件名稱**：`claude_code.feedback_survey`1377**事件名稱**：`claude_code.feedback_survey`

1374 1378

1377* 所有[標準屬性](#standard-attributes)1381* 所有[標準屬性](#standard-attributes)

1378* `event.name`：`"feedback_survey"`1382* `event.name`：`"feedback_survey"`

1379* `event.timestamp`：ISO 8601 時間戳記1383* `event.timestamp`：ISO 8601 時間戳記

1380* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述1384* `event.sequence`：用於排序事件的每程序計數器，說明請見[事件關聯屬性](#event-correlation-attributes)

1381* `event_type`：調查生命週期事件，例如 `"appeared"`、`"responded"` 或 `"transcript_prompt_appeared"`1385* `event_type`：調查生命週期事件，例如 `"appeared"`、`"responded"` 或 `"transcript_prompt_appeared"`

1382* `appearance_id`：唯一 ID，連結為一個調查實例發出的事件1386* `appearance_id`：用於連結同一調查實例所發出之事件的唯一 ID

1383* `survey_type`：哪個調查產生事件。`"session"` 是「Claude 做得如何？」評分提示1387* `survey_type`：產生此事件的調查。`"session"` 為「How is Claude doing?」評分提示

1384* `response`：使用者在 `responded` 事件上的選擇1388* `response`：使用者在 `responded` 事件中的選擇

1385* `enabled_via_override`：設定 [`CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL`](/docs/zh-TW/env-vars) 時為 `true`。以布林值而非字串發出。出現在 `session` 調查事件上。可依此屬性篩選，以確認覆寫已套用至整個機群1389* `enabled_via_override`：設定了 [`CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL`](/docs/zh-TW/env-vars) 時為 `true`。以 Boolean 而非字串發出。出現在 `session` 調查事件上。可依此屬性篩選，以確認覆寫已套用至整個裝置群

1386 1390

1387<h4 id="retention-sweep-event">1391<h4 id="retention-sweep-event">

1388 保留掃描事件1392 保留清理事件

1389</h4>1393</h4>

1390 1394

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 不執行掃描且不發出任何內容。1395保留清理作業每執行一次記錄一次，此作業會刪除早於 [`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 1396

1393與此頁面上的每個 OTel 事件一樣，它僅流向您配置的遙測後端。需要 Claude Code v2.1.227 或更新版本。1397如同本頁上的所有 OTel 事件，此事件只會傳送至您設定的遙測後端。需要 Claude Code v2.1.227 或更新版本。

1394 1398

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"` 時存在。1399當 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 1400

1397**事件名稱**：`claude_code.retention_sweep`1401**事件名稱**：`claude_code.retention_sweep`

1398 1402

1401* 所有[標準屬性](#standard-attributes)1405* 所有[標準屬性](#standard-attributes)

1402* `event.name`：`"retention_sweep"`1406* `event.name`：`"retention_sweep"`

1403* `event.timestamp`：ISO 8601 時間戳記1407* `event.timestamp`：ISO 8601 時間戳記

1404* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述1408* `event.sequence`：用於排序事件的每程序計數器，說明請見[事件關聯屬性](#event-correlation-attributes)

1405* `result`：掃描執行時為 `"complete"`，Claude Code 暫停時為 `"skipped"`1409* `result`：清理作業已執行時為 `"complete"`，Claude Code 暫停時為 `"skipped"`

1406* `period_days`：合併設定中的 `cleanupPeriodDays` 值（以天為單位），或當沒有來源設定時為 `30`。在跳過的事件上，掃描會使用的值，從 Claude Code 可以讀取的設定來源計算1410* `period_days`：合併設定中的 `cleanupPeriodDays` 值（以天為單位），若沒有任何來源設定則為 `30`。在略過的事件中，此值為清理作業原本會使用的值，根據 Claude Code 能夠讀取的設定來源計算而得

1407* `used_default`：當沒有可讀的設定來源設定 `cleanupPeriodDays` 時為 `"true"`，否則為 `"false"`。在完成事件上，`"true"` 表示應用了 30 天預設值1411* `used_default`：沒有任何可讀取的設定來源設定 `cleanupPeriodDays` 時為 `"true"`，否則為 `"false"`。在完成的事件中，`"true"` 表示套用了 30 天的預設值

1408* `skip_reason`：Claude Code 暫停掃描的原因。僅當 `result` 為 `"skipped"` 時存在：1412* `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`1413 * `"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 無法看到的值1414 * `"settings_unknowable"`：某個設定檔無法讀取或剖析，因此 `cleanupPeriodDays` 或 `desktopSessionCleanupPeriodDays` 可能被設為 Claude Code 看不到的值

1411 * `"settings_invalid_key_set"`：設定有驗證錯誤且 `cleanupPeriodDays` 或 `desktopSessionCleanupPeriodDays` 被明確設定，因此回退到預設值可能會刪除或保留違反該設定的檔案1415 * `"settings_invalid_key_set"`：設定有驗證錯誤，且明確設定了 `cleanupPeriodDays` 或 `desktopSessionCleanupPeriodDays`，因此改用預設值可能會違反該設定而刪除或保留檔案

1412* `transcripts_deleted`：掃描刪除的工作階段文字記錄數，頂級 `~/.claude/projects/*/*.jsonl` 檔案1416* `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 或更新版本1417* `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`：工作階段檔案掃描刪除的項目數：文字記錄加上每個工作階段的伴隨檔案，例如邊車、錄製和工具結果1418* `session_files_deleted`：工作階段檔案清理作業刪除的 artifact 數量：逐字稿加上每個工作階段的附屬檔案，例如 sidecar、錄製內容與工具結果

1415* `artifacts_deleted`：掃描跨越的資料目錄中刪除的總項目，包括工作階段檔案。某些掃描將整個移除的目錄樹計為一項，少數清理通過不貢獻計數器，因此將該值視為下限而不是確切的檔案計數1419* `artifacts_deleted`：清理作業在其涵蓋的資料目錄中刪除的項目總數，包括工作階段檔案。部分清理作業會將整個移除的目錄樹計為一個項目，且少數清理流程不會計入此計數器，因此請將此值視為下限，而非精確的檔案數量

1416* `files_retained_fresh`：檢查並保留在原位的檔案，因為它們仍在保留期內。只有每個檔案掃描計算這些，因此該值是下限；非零值是正常的穩定狀態1420* `files_retained_fresh`：已檢查但因仍在保留期間內而保留的檔案。只有逐檔案的清理作業會計入這些檔案，因此此值為下限；非零值為正常的穩定狀態

1417* `files_past_cutoff`：早於保留期但清理未能刪除的檔案，例如因權限錯誤或檔案被開啟佔用。此計數也包括清理在 `skills/synced/` 或 `plugins/synced/` 下找到的每個過時資料夾，無論是否已將該資料夾移至垃圾桶。除了這些資料夾之外，大於零的值表示有檔案超過了設定的保留期仍然存在；零並不能證明沒有這種情況，因為移除整個目錄失敗會改計入 `error_count`1421* `files_past_cutoff`：早於保留期間但清理作業未能刪除的檔案，例如因權限錯誤或檔案被開啟佔用。此計數也包含清理作業在 `skills/synced/` 或 `plugins/synced/` 下找到的每個過時資料夾，無論是否將該資料夾移至垃圾桶。除了這些資料夾之外，大於零的值表示有檔案超過了所設定的保留期間；零並不能證明沒有檔案超過，因為移除整個目錄失敗時會改計入 `error_count`

1418* `error_count`：掃描在列出或刪除檔案時遇到的錯誤數1422* `error_count`：清理作業在列出或刪除檔案時遇到的錯誤數量

1419 1423

1420<h4 id="managed-settings-resolved-event">1424<h4 id="managed-settings-resolved-event">

1421 管理設定已解析事件1425 受管設定解析事件

1422</h4>1426</h4>

1423 1427

1424使用工作階段解析的[管理設定](/docs/zh-TW/managed-settings)記錄：在工作階段開始時一次，當管理設定或[原則協助程式](/docs/zh-TW/managed-settings#compute-the-policy-with-a-helper-program)的狀態在工作階段期間變更時再次，以及當 Claude Code 拒絕啟動或因 `error.type` 屬性列出的原因之一而結束工作階段時。1428隨工作階段所解析的[受管設定](/docs/zh-TW/managed-settings)一併記錄：於工作階段開始時記錄一次，在工作階段期間受管設定或[政策輔助程式](/docs/zh-TW/managed-settings#compute-the-policy-with-a-helper-program)的狀態變更時再次記錄，以及當 Claude Code 因 `error.type` 屬性所列的原因之一而拒絕啟動或結束工作階段時記錄。

1425使用此事件尋找在意外管理來源上執行的機器、原則協助程式失敗的機器以及機器拒絕啟動的原因。1429可使用此事件找出在非預期受管來源上執行的電腦、政策輔助程式失敗的電腦，以及電腦拒絕啟動的原因。

1426需要 Claude Code v2.1.274 或更新版本。1430需要 Claude Code v2.1.274 或更新版本。

1427 1431

1428預設情況下，事件攜帶管理來源和原則協助程式的狀態，但不攜帶設定本身。要新增編輯的 `managed_settings.settings` 屬性和 `managed_settings.resolved_sha256` 摘要，請設定 `OTEL_LOG_MANAGED_SETTINGS=1`：1432根據預設，此事件會包含受管來源與政策輔助程式的狀態，但不包含設定本身。若要加入經過遮蔽的 `managed_settings.settings` 屬性與 `managed_settings.resolved_sha256` 摘要，請設定 `OTEL_LOG_MANAGED_SETTINGS=1`：

1429 1433

1430* 在管理設定、使用者設定或 `--settings` 的 `env` 區塊中設定它，或在您啟動 Claude Code 的環境中設定。專案或本地設定中的值不會啟用它，因為複製的儲存庫可以寫入它們。1434* 在受管設定、使用者設定或 `--settings` 的 `env` 區塊中設定，或在啟動 Claude Code 的環境中設定。在專案或本機設定中設定此值不會啟用它，因為複製的儲存庫可以寫入這些設定。

1431* 伺服器管理設定可以在不顯示[安全核准對話框](/docs/zh-TW/server-managed-settings#security-approval-dialogs)的情況下設定它，因為變數僅將您組織自己的編輯原則新增到您的組織已接收的事件。1435* 伺服器受管設定可以設定此值而不顯示[安全性核准對話方塊](/docs/zh-TW/server-managed-settings#security-approval-dialogs)，因為此變數只會將您組織自己經過遮蔽的政策加入您組織已經會收到的事件中。

1432 1436

1433在您尚未[信任](/docs/zh-TW/permissions#what-runs-before-you-trust-a-folder)的資料夾中的互動工作階段中，Claude Code 不匯出拒絕事件。1437在您尚未[信任](/docs/zh-TW/permissions#what-runs-before-you-trust-a-folder)的資料夾中的互動式工作階段，Claude Code 不會匯出拒絕事件。

1434 1438

1435**事件名稱**：`claude_code.managed_settings_resolved`1439**事件名稱**：`claude_code.managed_settings_resolved`

1436 1440

1439* 所有[標準屬性](#standard-attributes)1443* 所有[標準屬性](#standard-attributes)

1440* `event.name`：`"managed_settings_resolved"`1444* `event.name`：`"managed_settings_resolved"`

1441* `event.timestamp`：ISO 8601 時間戳記1445* `event.timestamp`：ISO 8601 時間戳記

1442* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述1446* `event.sequence`：用於排序事件的每程序計數器，說明請見[事件關聯屬性](#event-correlation-attributes)

1443* `managed_settings.trigger`：工作階段啟動事件為 `"startup"`，當管理設定或原則協助程式的狀態在工作階段稍後變更時為 `"change"`，或當管理設定原則停止工作階段時為 `"refused"`。Claude Code 僅在屬性與它發送的最後一個事件不同時發送 `change` 事件，變更的設定值計數即使 `OTEL_LOG_MANAGED_SETTINGS` 關閉1447* `managed_settings.trigger`：工作階段開始事件為 `"startup"`，在工作階段後續受管設定或政策輔助程式狀態變更時為 `"change"`，受管設定政策停止工作階段時為 `"refused"`。只有當某個屬性與上次傳送的事件不同時，Claude Code 才會傳送 `change` 事件；即使 `OTEL_LOG_MANAGED_SETTINGS` 未開啟，設定值的變更也會計入

1444* `error.type`：Claude Code 停止工作階段的原因。僅在 `refused` 事件上存在：1448* `error.type`：Claude Code 停止工作階段的原因。僅出現在 `refused` 事件上：

1445 * `"helper_failed"`：[原則協助程式執行失敗](/docs/zh-TW/settings-reference#helper-failures)1449 * `"helper_failed"`：[政策輔助程式執行失敗](/docs/zh-TW/settings-reference#helper-failures)

1446 * `"policy_invalid"`：管理設定包含停止 Claude Code 啟動的錯誤，或管理來源無法載入，因此 Claude Code 無法檢查組織登入強制執行1450 * `"policy_invalid"`：受管設定包含會阻止 Claude Code 啟動的錯誤，或某個管理來源因讀取被拒以外的原因而載入失敗，導致 Claude Code 無法檢查組織登入或提供者強制規定

1447 * `"provider_not_allowed"`：工作階段會使用 API 提供者，或將提供者的流量發送到管理 [`allowedProviders`](/docs/zh-TW/settings-reference#allowedproviders) 列表不允許的主機。需要 Claude Code v2.1.285 或更新版本1451 * `"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)1452 * `"consent_rejected"`：使用者拒絕了伺服器受管設定的[安全性核准對話方塊](/docs/zh-TW/server-managed-settings#security-approval-dialogs)

1449 * `"force_refresh_failed"`：[`forceRemoteSettingsRefresh`](/docs/zh-TW/settings-reference#forceremotesettingsrefresh) 需要的設定擷取失敗1453 * `"force_refresh_failed"`：[`forceRemoteSettingsRefresh`](/docs/zh-TW/settings-reference#forceremotesettingsrefresh) 所要求的設定擷取失敗

1450 * `"gateway_rejected"`：[Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway)以 HTTP 403 回答管理設定載入1454 * `"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)1455 * `"version_below_minimum"`：此版本的 Claude Code 低於 [`requiredMinimumVersion`](/docs/zh-TW/settings-reference#requiredminimumversion) 或高於 [`requiredMaximumVersion`](/docs/zh-TW/settings-reference#requiredmaximumversion)

1452 * `"_OTHER"`：Claude 應用程式閘道管理設定載入因另一個原因失敗1456 * `"_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 無法讀取的來源不列出。作為字串陣列發出，當沒有管理來源傳遞原則鍵時為空1457* `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"`1458* `managed_settings.source_behavior`：Claude Code 讀取到的 [`managedSourcesBehavior`](/docs/zh-TW/settings-reference#managedsourcesbehavior) 值，為 `"first-wins"` 或 `"merge"`。沒有任何來源設定此鍵時為 `"first-wins"`

1455* `managed_settings.helper.state`：所選 MDM 或檔案來源配置的原則協助程式的狀態：1459* `managed_settings.helper.state`：所選 MDM 或檔案來源所設定之政策輔助程式的狀態：

1456 * `"ok"`：協助程式的輸出用作管理設定1460 * `"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)描述案例1461 * `"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 原則或管理設定檔案1462 * `"none"`：未設定輔助程式，或設定它的來源不是 MDM 政策或受管設定檔

1459* `managed_settings.helper.applied`：當協助程式自己的輸出用作管理設定時為 `"output"`，當它不時為 `"none"`1463* `managed_settings.helper.applied`：當輔助程式本身的輸出作為受管設定使用時為 `"output"`，否則為 `"none"`

1460* `managed_settings.helper.entry`：當 Claude Code 選擇 [`policyHelper`](/docs/zh-TW/settings-reference#policyhelper) 時為 `"policyHelper"`。當它選擇沒有協助程式時不存在1464* `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` 是否設定1465* `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` 事件上不存在1466* `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 從其設定架構構建它：1467* `managed_settings.settings`（當 `OTEL_LOG_MANAGED_SETTINGS=1` 時）：已解析受管設定的名稱與結構，以 JSON 字串表示，值經過遮蔽。在 `refused` 事件上不會出現。Claude Code 依據其設定 schema 建置此值：

~~1464~~ 1468

1465 * 架構宣告的設定名稱被匯出，它不宣告的鍵被遺漏1469 * schema 宣告的設定名稱會被匯出，schema 未宣告的鍵則會被省略

1466 * 布林值、數字和架構限制為固定選項集的字串值，例如 `permissions.defaultMode`，按原樣匯出。`sandbox.network.httpProxyPort` 和 `sandbox.network.socksProxyPort` 匯出為 `"[REDACTED]"`1470 * Boolean、數字，以及 schema 限制為固定選項集合的字串值（例如 `permissions.defaultMode`）會原樣匯出。`sandbox.network.httpProxyPort` 與 `sandbox.network.socksProxyPort` 會匯出為 `"[REDACTED]"`

1467 * 每個其他字串，例如 `model`、`apiKeyHelper`、每個 `env` 值、每個 URL 和每個命令，匯出為 `"[REDACTED]"`1471 * 其他所有字串，例如 `model`、`apiKeyHelper`、每個 `env` 值、每個 URL 與每個命令，都會匯出為 `"[REDACTED]"`

1468 * 地圖的項目名稱，例如 `env` 變數名稱和外掛程式 ID，按原樣匯出。架構不鍵入其項目的設定，例如 `vimInsertModeRemaps`，匯出為單個 `"[REDACTED]"`，`sandbox.ignoreViolations` 匯出為其路徑列表的列表，不含命令模式1472 * 對應表的項目名稱，例如 `env` 變數名稱與外掛 ID，會原樣匯出。schema 未定義其項目類型的設定（例如 `vimInsertModeRemaps`）會匯出為單一的 `"[REDACTED]"`，而 `sandbox.ignoreViolations` 會匯出為其路徑清單的清單，不含命令模式

1469 * 列表保留其長度，每個項目按相同規則編輯1473 * 清單會保留其長度，每個項目依相同規則遮蔽

1470 * `permissions.allow`、`permissions.deny` 或 `permissions.ask` 規則匯出為其工具名稱，內容編輯，例如 `Read([REDACTED])`，當工具內建於此版本的 Claude Code 或是 `mcp__` 參考（例如 `mcp__jira__create_issue`）時。任何其他規則匯出為 `"[REDACTED]"`1474 * 當工具內建於此版本的 Claude Code，或為 `mcp__` 參照（例如 `mcp__jira__create_issue`）時，`permissions.allow`、`permissions.deny` 或 `permissions.ask` 規則會匯出為其工具名稱並遮蔽內容，例如 `Read([REDACTED])`。其他任何規則都會匯出為 `"[REDACTED]"`

1471 * 鉤子遵循相同規則，因此固定選項和數字欄位（例如 `type` 和 `timeout`）顯示，而每個命令、URL、`matcher` 和 `if` 條件匯出為 `"[REDACTED]"`1475 * hook 遵循相同規則，因此固定選項與數值欄位（例如 `type` 與 `timeout`）會顯示，而每個命令、URL、`matcher` 與 `if` 條件都會匯出為 `"[REDACTED]"`

~~1472~~ 1476

1473 例如，具有 `apiKeyHelper`、兩個 `env` 變數和拒絕規則的管理設定匯出為 `{"apiKeyHelper":"[REDACTED]","env":{"HTTPS_PROXY":"[REDACTED]","CLAUDE_CODE_ENABLE_TELEMETRY":"[REDACTED]"},"permissions":{"deny":["Read([REDACTED])"]}}`.1477 例如，包含 `apiKeyHelper`、兩個 `env` 變數與一條拒絕規則的受管設定會匯出為 `{"apiKeyHelper":"[REDACTED]","env":{"HTTPS_PROXY":"[REDACTED]","CLAUDE_CODE_ENABLE_TELEMETRY":"[REDACTED]"},"permissions":{"deny":["Read([REDACTED])"]}}`。

~~1474~~ 1478

1475 Claude Code 在 8 KB UTF-8 處切割值，切割值不是有效的 JSON1479 Claude Code 會在 UTF-8 編碼 8 KB 處截斷此值，截斷後的值不是有效的 JSON

1476* `managed_settings.settings_truncated`（當 `managed_settings.settings` 存在時）：當 Claude Code 在 8 KB 處截斷 `managed_settings.settings` 時為 `true`，否則為 `false`。以布林值而非字串發出1480* `managed_settings.settings_truncated`（當 `managed_settings.settings` 存在時）：Claude Code 在 8 KB 處截斷 `managed_settings.settings` 時為 `true`，否則為 `false`。以 Boolean 而非字串發出

1477 1481

1478<h2 id="interpret-metrics-and-events-data">1482<h2 id="interpret-metrics-and-events-data">

1479 解釋指標和事件資料1483 解釋指標和事件資料

1528 1532

1529Claude Code 在內部重試失敗的 API 請求，並僅在放棄後才發出單個 `claude_code.api_error` 事件，因此事件本身是該請求的終端訊號。中間重試嘗試不會作為單獨的事件記錄。1533Claude Code 在內部重試失敗的 API 請求，並僅在放棄後才發出單個 `claude_code.api_error` 事件，因此事件本身是該請求的終端訊號。中間重試嘗試不會作為單獨的事件記錄。

1530 1534

1531事件上的 `attempt` 屬性記錄進行的嘗試總次數。`CLAUDE_CODE_MAX_RETRIES` 預設為 10，上限為 15。在 v2.1.199 或更新版本上，您可以設定 `CLAUDE_CODE_RETRY_WATCHDOG` 以提高預設值並移除上限。1535事件上的 `attempt` 屬性記錄嘗試次數。`CLAUDE_CODE_MAX_RETRIES` 預設為 10，上限為 15。在 v2.1.199 或更新版本上，您可以設定 `CLAUDE_CODE_RETRY_WATCHDOG` 以提高預設值並移除上限。

1536

1537當請求在暫時性錯誤上耗盡所有重試時，`attempt` 最多為該有效限制加一：預設為 11。

1532 1538

1533當請求在暫時性錯誤上耗盡所有重試時，`attempt` 等於該有效限制加一：預設為 11，除非設定了看門狗，否則永遠不超過 16。較低的值表示不可重試的錯誤，例如 `400` 回應，或具有自己較小重試預算的原因。例如，Claude Code 最多重試兩次載入 AWS 或 Google Cloud 認證的失敗。1539較低的值仍可能表示重試已用盡：每次 Claude Code 在串流失敗後重新發出請求時，`attempt` 都會從 `1` 重新開始計算。

1534 1540

1535若要區分從一個恢復的工作階段與停滯的工作階段，請按 `session.id` 分組事件，並檢查錯誤後是否存在更晚的 `api_request` 事件。1541若要區分從一個恢復的工作階段與停滯的工作階段，請按 `session.id` 分組事件，並檢查錯誤後是否存在更晚的 `api_request` 事件。

1536 1542

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/install.md +20 −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

245<h3 id="add-a-private-marketplace">261<h3 id="add-a-private-marketplace">

246 新增私人市集262 新增私人市集

247</h3>263</h3>

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

Details

140| 呼叫 | 使用者看到的內容 |140| 呼叫 | 使用者看到的內容 |

141| :- | :- |141| :- | :- |

145 145

146<h3 id="start-a-turn-from-a-background-job">146<h3 id="start-a-turn-from-a-background-job">

159 在工作階段之間傳送和接收訊息159 在工作階段之間傳送和接收訊息

160</h2>160</h2>

161 161

162一個 mod 可以向另一個工作階段或此工作階段的子代理傳送純文字訊息，並觀察到達和離開的訊息。`$.session.send({ to, text })` 傳送一個訊息，與 SendMessage 工具進行相同的傳遞。`to` 是工作階段的 `{ sessionId }`、來自 `$.agent.list()` 的子代理的 `{ agentId }`，或接收訊息來自的字串位址。呼叫在訊息排隊後解析，返回 `{ isDelivered: true }`。當沒有任何內容被傳遞時，它會以 `{ isDelivered: false, reason }` 解析，`reason` 說明原因。162mod 可以向您的另一個工作階段、此工作階段的某個 subagent，或其 [agent team](/docs/zh-TW/agent-teams) 中的隊員傳送純文字訊息。它也可以觀察到達和離開的訊息。

163

164若要傳送訊息，請呼叫 `$.session.send({ to, text })`，它會進行與 SendMessage 工具相同的傳遞。依據接收訊息的對象設定 `to`：

165

166* **您的另一個工作階段**：`{ sessionId }`

167* **subagent 或隊員**：`{ agentId }`，使用來自 `$.agent.list()` 的 id

168* **您所收到訊息的寄件者**：該訊息來源的字串位址

169

170呼叫在訊息排入佇列後解析，返回 `{ isDelivered: true }`。當沒有任何內容被傳遞時，它會以 `{ isDelivered: false, reason }` 解析，`reason` 說明原因。

163 171

164此 hook 透過詢問您在其後輸入的 id 的工作階段的狀態，來回答 `/ping` 命令（[註冊為命令](#add-a-command)）：172此 hook 透過詢問您在其後輸入的 id 的工作階段的狀態，來回答 `/ping` 命令（[註冊為命令](#add-a-command)）：

165 173

plugins/mods/events.md +2 −0

Details

281 281

282`result.usage` 保存 Claude API 為請求回報的 token 計數，以及回應的 `model`：`input_tokens`、`output_tokens`、`cache_read_input_tokens` 和 `cache_creation_input_tokens`。此 hook 也會針對 subagent 的請求執行，因此若您只想要主要對話，請檢查 `e.agentId`。282`result.usage` 保存 Claude API 為請求回報的 token 計數，以及回應的 `model`：`input_tokens`、`output_tokens`、`cache_read_input_tokens` 和 `cache_creation_input_tokens`。此 hook 也會針對 subagent 的請求執行，因此若您只想要主要對話，請檢查 `e.agentId`。

283 283

284若要查看 API 在請求期間自行執行的工具呼叫，例如對 [advisor 工具](/docs/zh-TW/advisor)的呼叫，請讀取 `result.serverToolUses`。Claude Code 不會執行這些呼叫，因此不會針對它們觸發任何 `tool.call` 或 `tool.check` hook。當回應中沒有此類呼叫時，該欄位不會存在，且此欄位需要 Claude Code v2.1.290 或更新版本。

285

284<h3 id="hook-the-settings-hook-events">286<h3 id="hook-the-settings-hook-events">

285 處理設定 hook 事件287 處理設定 hook 事件

286</h3>288</h3>

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

Details

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

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

Details

209 繪圖不出現或不回應209 繪圖不出現或不回應

210</h2>210</h2>

211 211

212mod 已載入，其窗格、帶狀或控制項的行為不符合您的預期。212mod 已載入，其窗格、帶狀、toast 或控制項的行為不符合您的預期。

213 213

214<h3 id="a-pane-or-band-is-empty-or-shows-claude-code’s-usual-content">214<h3 id="a-pane-or-band-is-empty-or-shows-claude-code’s-usual-content">

215 窗格或帶狀為空或顯示 Claude Code 的常見內容215 窗格或帶狀為空或顯示 Claude Code 的常見內容

247 247

248從命令或按鈕開啟窗格，或檢查呼叫的 `isPlaced` 結果。請參閱[在正確的時間開啟窗格](/docs/zh-TW/plugins/mods/interface#open-a-pane-at-the-right-time)。248從命令或按鈕開啟窗格，或檢查呼叫的 `isPlaced` 結果。請參閱[在正確的時間開啟窗格](/docs/zh-TW/plugins/mods/interface#open-a-pane-at-the-right-time)。

249 249

250<h3 id="a-toast-doesn’t-appear">

251 toast 未出現

252</h3>

253

254您的 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`。接著檢查以下可能原因：

255

256* **缺少該呼叫的行**：尋找說明 Claude Code 拒絕該呼叫原因的行，例如 `first-mod: $.ui.toast dropped: timeoutMs is a whole number of ms, 1 to 60000`。

257* **有窗格正在保留 toast**：您的 mod 或其他 mod 在開啟目前顯示的窗格時傳入了 [`holdToasts`](/docs/zh-TW/plugins/mods/interface#hold-toasts-behind-a-dialog)。關閉該窗格即可結束保留。如果該窗格是您的，且應保持開啟，請從其 `$.ui.open` 呼叫中移除 `holdToasts`，然後重新開啟窗格。

258* **toast 位於提示詞下方**：在[傳統轉譯器](/docs/zh-TW/fullscreen#enable-fullscreen-rendering)中，請查看提示詞下方的右側。該處的 toast 是以 mod 名稱開頭的一行文字，而不是右上角的方框。

259* **您的 mod 發出了較新的 toast**：在傳統轉譯器中，您的 mod 發出的較新 toast 可能會取代正在顯示或等待顯示的 toast。偵錯日誌中會有較舊 toast 的另一行，若該 toast 正在顯示，結尾為 `gave way, cut short`；若從未出現，結尾為 `gave way, unseen`。若要同時顯示兩則訊息，請將它們放在同一個 toast 中。

260* **toast 在繪製前逾時**：在全螢幕轉譯中，Claude Code 一次最多繪製三個 toast，因此 toast 可能在繪製前就已逾時。偵錯日誌中會有該 toast 的另一行，結尾為 `left the stack, never drawn`。當您的 mod 同時發出多個 toast 時，請將訊息放在同一個 toast 中。

261

262在 v2.1.290 之前，Claude Code 會捨棄在其為您的 mod 顯示上一個 toast 後兩秒內發出的 toast，且被捨棄 toast 的偵錯日誌行會顯示 `within 2000ms of the last; dropped`。

263

250<h3 id="hotkeys-do-nothing">264<h3 id="hotkeys-do-nothing">

251 快捷鍵沒有作用265 快捷鍵沒有作用

252</h3>266</h3>

plugins/publish.md +1 −0

Details

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

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

568 `Marketplace "<name>" is already added from a different source`568 `Marketplace "<name>" is already added from a different source`

569</h3>569</h3>

570 570

571您確認透過 [`/plugin install <plugin> --marketplace <source>`](/docs/zh-TW/plugins/install#add-a-marketplace-and-install-in-one-command) 新增市集，Claude Code 從該來源擷取的目錄與您已從不同來源新增的市集具有相同的名稱。Claude Code 保留現有市集而不是替換它，外掛程式未安裝。571您在工作階段中或從 shell 使用 [安裝命令上的 `--marketplace <source>`](/docs/zh-TW/plugins/install#add-a-marketplace-and-install-in-one-command) 指定了新的市集來源。Claude Code 從該來源擷取的目錄與您已從不同來源新增的市集具有相同的名稱。Claude Code 保留現有市集而不是替換它，外掛程式未安裝。

572 572

573完整訊息如下所示：573完整訊息如下所示：

574 574

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

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 15:58 UTC