Documentation — Spybara

admin-setup.md +1 −3

Details

83啟用 WSL 會話後，將您的受管設定擴展到它們：83啟用 WSL 會話後，將您的受管設定擴展到它們：

84 84

85* 透過 HKLM 登錄或 `C:\Program Files\ClaudeCode` 檔案部署 `wslInheritsWindowsSettings: true`，以便 WSL 會話繼承與主機會話相同的政策。85* 透過 HKLM 登錄或 `C:\Program Files\ClaudeCode` 檔案部署 `wslInheritsWindowsSettings: true`，以便 WSL 會話繼承與主機會話相同的政策。

86* 透過在 WSL 會話內執行 `/status` 進行驗證，並讀取 `Setting sources` 行。Claude Code 僅命名[它選擇的受管來源](/docs/zh-TW/server-managed-settings#settings-precedence)，因此該行告訴您的內容取決於會話：86* 透過在 WSL 會話內執行 `/status` 進行驗證，並讀取 `Setting sources` 行。若要解釋它列出的內容，請參閱[在 /status 中讀取來源](/docs/zh-TW/managed-settings#read-the-source-in-/status)。

87 * **在[擷取 server-managed 設定](/docs/zh-TW/server-managed-settings#platform-availability)並接收任何金鑰的會話中**：`Enterprise managed settings (remote)`，因為 Claude Code 在 Windows 來源之前選擇它們，所以該行不會顯示旗標是否到達。

88 * **在任何其他會話中**：`Enterprise managed settings (HKLM)` 確認登錄部署。`(file)` 命名 Windows 檔案或發行版自己的 `/etc/claude-code/managed-settings.json`，因此當發行版沒有自己的受管檔案時，它僅確認 Windows 檔案部署。

89 87

90WSL 2 公用程式 VM 內的程序對 Windows 端端點偵測感應器不可見。若要觀察發行版內的程序和檔案活動，請檢查您的端點偵測廠商的 WSL 指南，以取得您可以在發行版內執行的 Linux 感應器及其需要的排除項目。Claude Code 的 [OpenTelemetry 工具執行遙測](/docs/zh-TW/monitoring-usage)對 WSL 和原生會話的發出方式相同。88WSL 2 公用程式 VM 內的程序對 Windows 端端點偵測感應器不可見。若要觀察發行版內的程序和檔案活動，請檢查您的端點偵測廠商的 WSL 指南，以取得您可以在發行版內執行的 Linux 感應器及其需要的排除項目。Claude Code 的 [OpenTelemetry 工具執行遙測](/docs/zh-TW/monitoring-usage)對 WSL 和原生會話的發出方式相同。

91 89

advisor.md +10 −7

Details

98顧問的能力必須至少與主要模型相同。每個主要模型接受的顧問為：98顧問的能力必須至少與主要模型相同。每個主要模型接受的顧問為：

99 99

100| 主要模型 | 接受的顧問 | 備註 |100| 主要模型 | 接受的顧問 | 備註 |

101| ------------------- | ---------------------- | ----------------------------------------------------------------------------------------- |101| ------------------- | ----------------------------- | ----------------------------------------------------------------- |

103| Sonnet 4.6 | Fable、Opus、Sonnet | |103| Sonnet 4.6 | Fable、Opus、Sonnet | |

108| Fable 5 | Fable 5.1 或 Fable 5 | Opus 或 Sonnet 顧問會被拒絕 |

109| Fable 5.1 | Fable 5.1 | Opus 或 Sonnet 顧問會被拒絕，使用 Fable 5 顧問的請求會因 API 錯誤而失敗 |

108 110

109Fable 5.1 需要 Claude Code v2.1.257 或更新版本。兩個 Fable 模型都需要 [Fable 存取權](/docs/zh-TW/model-config#work-with-fable)。111Fable 5.1 需要 Claude Code v2.1.257 或更新版本。兩個 Fable 模型都需要 [Fable 存取權](/docs/zh-TW/model-config#work-with-fable)。

110 112

112 114

113子代理繼承已設定的顧問，並針對其自身模型應用相同的配對檢查。115子代理繼承已設定的顧問，並針對其自身模型應用相同的配對檢查。

114 116

115Claude Code 在傳送請求前驗證配對：117Claude Code 在傳送請求前驗證配對，API 也會再次驗證：

116 118

117* 如果顧問的能力低於主要模型，顧問不會附加到主要模型的請求。`/advisor` 命令輸出和通知會顯示此情況。其自身模型滿足配對的子代理仍可使用顧問。119* 對於表格中列為被拒絕的顧問，Claude Code 不會將其附加到主要模型的請求。`/advisor` 命令輸出和通知會顯示此情況。其自身模型滿足配對的子代理仍可使用顧問。

120* 對於表格中列為因 API 錯誤而失敗的顧問，Claude Code 會附加它，但 API 會拒絕它。每個請求都會失敗，並顯示 `'<advisor model>' cannot be used as an advisor when the request model is '<main model>'`，直到您使用 `/advisor` 變更顧問或將其關閉。

118* 如果主要模型或顧問是 Claude Code 無法識別的模型，顧問不會附加。121* 如果主要模型或顧問是 Claude Code 無法識別的模型，顧問不會附加。

119 122

120<h3 id="fable-advisor-and-usage-credits">123<h3 id="fable-advisor-and-usage-credits">

agent-sdk/agent-loop.md +3 −3

Details

62 * `"init"`：執行的工作階段中繼資料。當 `SessionStart` 或 `Setup` hook 在工作階段啟動期間執行時，其 [hook 生命週期訊息](/docs/zh-TW/agent-sdk/typescript#sdkhookstartedmessage) 會在 `init` 訊息之前到達62 * `"init"`：執行的工作階段中繼資料。當 `SessionStart` 或 `Setup` hook 在工作階段啟動期間執行時，其 [hook 生命週期訊息](/docs/zh-TW/agent-sdk/typescript#sdkhookstartedmessage) 會在 `init` 訊息之前到達

63 * `"compact_boundary"`：在 [壓縮](#automatic-compaction) 後觸發63 * `"compact_boundary"`：在 [壓縮](#automatic-compaction) 後觸發

64 * `"informational"`：來自迴圈的純文字狀態橫幅64 * `"informational"`：來自迴圈的純文字狀態橫幅

~~65 * `"worker_shutting_down"`：迴圈將在目前回合後結束，因為主機正在退出或遠端控制已斷開連線~~65 * `"worker_shutting_down"`：主機正在退出或遠端控制已斷開連線

66 66

67 在 TypeScript 中，除了 `"init"` 之外的每個子類型都是 [`SDKMessage` 聯合](/docs/zh-TW/agent-sdk/typescript#sdkmessage) 中的自己的類型，而不是 `SDKSystemMessage` 的子類型。67 在 TypeScript 中，除了 `"init"` 之外的每個子類型都是 [`SDKMessage` 聯合](/docs/zh-TW/agent-sdk/typescript#sdkmessage) 中的自己的類型，而不是 `SDKSystemMessage` 的子類型。

68* **`AssistantMessage`：** 在 Claude 回應的每個內容區塊後發出，包括最終純文字區塊。每個訊息都帶有單一內容區塊，例如文字或工具呼叫，來自一個回應的訊息共享一個訊息 ID。68* **`AssistantMessage`：** 在 Claude 回應的每個內容區塊後發出，包括最終純文字區塊。每個訊息都帶有單一內容區塊，例如文字或工具呼叫，來自一個回應的訊息共享一個訊息 ID。

239| `"max"` | 最大推理深度 | 需要深入分析的多步驟問題 |239| `"max"` | 最大推理深度 | 需要深入分析的多步驟問題 |

240 240

241如果您不設定 `effort`，兩個 SDK 都會保留參數未設定，並遵循模型的預設行為。241如果您不設定 `effort`，Claude Code 會自行解析努力等級，按照 [調整努力等級](/docs/zh-TW/model-config#adjust-effort-level) 所述的順序。

242 242

243<Note>243<Note>

244 `effort` 在每個回應內交換延遲和代幣成本以獲得推理深度。[擴展思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) 是一個單獨的功能，在輸出中產生 `thinking` 區塊，而 [Python](/docs/zh-TW/agent-sdk/python#thinkingconfig) 或 [TypeScript](/docs/zh-TW/agent-sdk/typescript#thinkingconfig) 上 `ThinkingConfig` 的 `display` 欄位控制您是否接收其文字。它們是獨立的：您可以設定 `effort: "low"` 並啟用擴展思考，或 `effort: "max"` 而不啟用它。244 `effort` 在每個回應內交換延遲和代幣成本以獲得推理深度。[擴展思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) 是一個單獨的功能，在輸出中產生 `thinking` 區塊，而 [Python](/docs/zh-TW/agent-sdk/python#thinkingconfig) 或 [TypeScript](/docs/zh-TW/agent-sdk/typescript#thinkingconfig) 上 `ThinkingConfig` 的 `display` 欄位控制您是否接收其文字。它們是獨立的：您可以設定 `effort: "low"` 並啟用擴展思考，或 `effort: "max"` 而不啟用它。

357| `success` | Claude 正常完成了任務 | 是 |357| `success` | Claude 正常完成了任務 | 是 |

358| `error_max_turns` | 在完成前達到 `maxTurns` 限制 | 否 |358| `error_max_turns` | 在完成前達到 `maxTurns` 限制 | 否 |

359| `error_max_budget_usd` | 在完成前達到 `maxBudgetUsd` 限制 | 否 |359| `error_max_budget_usd` | 在完成前達到 `maxBudgetUsd` 限制 | 否 |

360| `error_during_execution` | 錯誤中斷了迴圈（例如，API 失敗或取消的請求） | 否 |360| `error_during_execution` | 錯誤中斷了迴圈（例如，已取消的請求） | 否 |

361| `error_max_structured_output_retries` | 在配置的重試限制內未產生有效的結構化輸出：每次嘗試都未通過驗證，或模型後備撤回了已完成的輸出且沒有成功重試 | 否 |361| `error_max_structured_output_retries` | 在配置的重試限制內未產生有效的結構化輸出：每次嘗試都未通過驗證，或模型後備撤回了已完成的輸出且沒有成功重試 | 否 |

362 362

363`result` 欄位保存最終文字輸出，僅在 `success` 變體上存在，因此在讀取它之前始終檢查子類型。363`result` 欄位保存最終文字輸出，僅在 `success` 變體上存在，因此在讀取它之前始終檢查子類型。

agent-sdk/claude-code-features.md +0 −2

Details

196* **檔案系統 hooks：** 在 `settings.json` 中定義的 shell 命令，當 `settingSources` 包含相關來源時載入。這些是您為 [互動式 Claude Code 工作階段](/docs/zh-TW/hooks-guide) 設定的相同 hooks。196* **檔案系統 hooks：** 在 `settings.json` 中定義的 shell 命令，當 `settingSources` 包含相關來源時載入。這些是您為 [互動式 Claude Code 工作階段](/docs/zh-TW/hooks-guide) 設定的相同 hooks。

197* **程式設計 hooks：** 直接傳遞給 `query()` 的回呼函式。這些在您的應用程式程序中執行，可以返回結構化決策。請參閱 [使用 hooks 控制執行](/docs/zh-TW/agent-sdk/hooks)。197* **程式設計 hooks：** 直接傳遞給 `query()` 的回呼函式。這些在您的應用程式程序中執行，可以返回結構化決策。請參閱 [使用 hooks 控制執行](/docs/zh-TW/agent-sdk/hooks)。

198 198

199兩種類型都在相同的 hook 生命週期中執行。如果您已經在專案的 `.claude/settings.json` 中有 hooks，並且您設定 `settingSources: ["project"]`，那些 hooks 會在 SDK 中自動執行，無需額外設定。

~~200~~

201Hook 回呼接收工具輸入並返回決策字典。返回 `{}` 表示允許工具繼續。若要阻止執行，請返回一個 `hookSpecificOutput` 物件，其中包含 `permissionDecision: "deny"` 和 `permissionDecisionReason`。原因會作為工具結果發送給 Claude。請參閱 [hooks 指南](/docs/zh-TW/agent-sdk/hooks) 以取得完整的回呼簽名和返回型別。199Hook 回呼接收工具輸入並返回決策字典。返回 `{}` 表示允許工具繼續。若要阻止執行，請返回一個 `hookSpecificOutput` 物件，其中包含 `permissionDecision: "deny"` 和 `permissionDecisionReason`。原因會作為工具結果發送給 Claude。請參閱 [hooks 指南](/docs/zh-TW/agent-sdk/hooks) 以取得完整的回呼簽名和返回型別。

202 200

203<CodeGroup>201<CodeGroup>

agent-sdk/hooks.md +4 −5

Details

589 從 hooks 發出 HTTP 請求589 從 hooks 發出 HTTP 請求

590</h3>590</h3>

591 591

592Hooks 可以執行非同步操作，例如 HTTP 請求。在您的 hook 內捕捉錯誤，而不是讓它們傳播，因為未處理的異常可能會中斷代理。592Hooks 可以執行非同步操作，例如 HTTP 請求。在您的 hook 內捕捉錯誤，而不是讓它們傳播。

593 593

594此範例在每個工具完成後傳送 webhook，記錄哪個工具執行以及何時執行。hook 捕捉錯誤，以便失敗的 webhook 不會中斷代理：594此範例在每個工具完成後傳送 webhook，記錄哪個工具執行以及何時執行。hook 捕捉來自失敗 webhook 的錯誤：

595 595

596<CodeGroup>596<CodeGroup>

597 ```python Python theme={null}597 ```python Python theme={null}

627 # 在執行緒中執行阻止 HTTP 呼叫以避免阻止事件迴圈627 # 在執行緒中執行阻止 HTTP 呼叫以避免阻止事件迴圈

628 await asyncio.to_thread(_send_webhook, input_data["tool_name"])628 await asyncio.to_thread(_send_webhook, input_data["tool_name"])

629 except Exception as e:629 except Exception as e:

630 # 記錄錯誤但不引發。失敗的 webhook 不應停止代理630 # 記錄錯誤但不引發

631 print(f"Webhook request failed: {e}")631 print(f"Webhook request failed: {e}")

632 632

633 return {}633 return {}

656 if (error instanceof Error && error.name === "AbortError") {656 if (error instanceof Error && error.name === "AbortError") {

657 console.log("Webhook request cancelled");657 console.log("Webhook request cancelled");

658 }658 }

659 // 不重新拋出。失敗的 webhook 不應停止代理659 // 不重新拋出

660 }660 }

661 661

662 return {};662 return {};

901 901

902生成子代理的 `UserPromptSubmit` hook 如果這些子代理觸發相同的 hook，可能會建立無限迴圈。要防止這種情況：902生成子代理的 `UserPromptSubmit` hook 如果這些子代理觸發相同的 hook，可能會建立無限迴圈。要防止這種情況：

903 903

904* 在生成子代理前檢查 hook 輸入中的子代理指示器

905* 使用共享變數或會話狀態來追蹤您是否已在子代理內904* 使用共享變數或會話狀態來追蹤您是否已在子代理內

906* 將 hooks 範圍限制為僅針對頂級代理會話執行905* 將 hooks 範圍限制為僅針對頂級代理會話執行

907 906

agent-sdk/mcp.md +1 −1

Details

162| :------------------------------------ | :-------------- | :------------------------------------------------- |162| :------------------------------------ | :-------------- | :------------------------------------------------- |

165| 同處理序 [SDK 伺服器](#sdk-mcp-servers) | 否；永不延遲第一輪 | 無 |165| 同處理序 [SDK 伺服器](#sdk-mcp-servers) | 是，直到連線並列出其工具為止 | 無；連線和工具列出請求各有其自己的逾時 |

166 166

167若要在發送 init 訊息之前，在與第一輪等待不同的早期階段阻止啟動本身：167若要在發送 init 訊息之前，在與第一輪等待不同的早期階段阻止啟動本身：

168 168

agent-sdk/modifying-system-prompts.md +1 −1

Details

160 const options = { settings: { outputStyle: "Explanatory" } };160 const options = { settings: { outputStyle: "Explanatory" } };

161 ```161 ```

162 162

163Python SDK 沒有以程式設計方式選擇輸出樣式的選項。對於無法寫入 `.claude/settings.local.json` 的僅程式碼部署，請改用 `append` 或自訂提示詞字串。163在 Python SDK 中，通過 `settings` 選項設定 `outputStyle`，該選項接受 JSON 字串（例如 `'{"outputStyle": "Explanatory"}'`）或設定該值的設定檔的路徑。

164 164

165**SDK 使用者注意：** 當您在選項中包含 `settingSources: ['user']` 或 `settingSources: ['project']`（TypeScript）/ `setting_sources=["user"]` 或 `setting_sources=["project"]`（Python）時，輸出樣式會被載入。165**SDK 使用者注意：** 當您在選項中包含 `settingSources: ['user']` 或 `settingSources: ['project']`（TypeScript）/ `setting_sources=["user"]` 或 `setting_sources=["project"]`（Python）時，輸出樣式會被載入。

166 166

agent-sdk/permissions.md +68 −68

Details

6 6

7> 使用權限模式、hooks 和宣告式允許/拒絕規則來控制您的代理程式如何使用工具。7> 使用權限模式、hooks 和宣告式允許/拒絕規則來控制您的代理程式如何使用工具。

8 8

9Claude Agent SDK 提供權限控制來管理 Claude 如何使用工具。使用權限模式和規則來定義自動允許的內容，並使用 [`canUseTool` 回呼](/docs/zh-TW/agent-sdk/user-input) 在執行時處理其他所有情況。9Claude Agent SDK 提供權限控制來管理 Claude 如何使用工具。使用權限模式和規則來定義自動允許的內容，以及使用 [`canUseTool` callback](/docs/zh-TW/agent-sdk/user-input) 來在執行時處理其他所有情況。

10 10

11<h2 id="how-permissions-are-evaluated">11<h2 id="how-permissions-are-evaluated">

12 權限如何被評估12 權限如何被評估

13</h2>13</h2>

14 14

~~15當 Claude 請求工具時，SDK 會按照以下順序檢查權限：~~15當 Claude 請求一個工具時，SDK 按照以下順序檢查權限：

16 16

17<Steps>17<Steps>

18 <Step title="Hooks">18 <Step title="Hooks">

19 首先執行 [hooks](/docs/zh-TW/agent-sdk/hooks)。Hook 可以直接拒絕呼叫或將其傳遞。返回 `allow` 的 hook 不會跳過下面的拒絕和詢問規則；無論 hook 結果如何，這些規則都會被評估。返回 `allow` 的 `PreToolUse` hook 也無法批准針對[關鍵路徑](/docs/zh-TW/permission-modes#critical-paths)的 `rm` 或 `rmdir` 移除。19 首先執行 [hooks](/docs/zh-TW/agent-sdk/hooks)。Hook 可以直接拒絕呼叫或將其傳遞下去。返回 `allow` 的 hook 不會跳過下面的拒絕和詢問規則；無論 hook 結果如何，這些規則都會被評估。`PreToolUse` hook allow 也無法批准針對 [關鍵路徑](/docs/zh-TW/permission-modes#critical-paths) 的 `rm` 或 `rmdir` 移除。

20 </Step>20 </Step>

21 21

22 <Step title="拒絕規則">22 <Step title="拒絕規則">

23 檢查 `deny` 規則（來自 `disallowed_tools` 和 [settings.json](/docs/zh-TW/settings-reference#permission-settings)）。如果拒絕規則符合，工具會被阻止，即使在 `bypassPermissions` 模式下也是如此。裸名稱拒絕規則（如 `Bash`）會在此評估開始前將工具從 Claude 的上下文中移除，因此只有範圍規則（如 `Bash(rm *)`）會在此步驟中被檢查。23 檢查 `deny` 規則（來自 `disallowed_tools` 和 [settings.json](/docs/zh-TW/settings-reference#permission-settings)）。如果拒絕規則匹配，工具會被阻止，即使在 `bypassPermissions` 模式下也是如此。裸名稱拒絕規則（如 `Bash`）會在此評估開始前將工具從 Claude 的上下文中移除，因此只有作用域規則（如 `Bash(rm *)`）會在此步驟中被檢查。

24 </Step>24 </Step>

25 25

26 <Step title="詢問規則">26 <Step title="詢問規則">

27 檢查來自 [settings.json](/docs/zh-TW/settings-reference#permission-settings) 的 `ask` 規則。如果詢問規則符合，呼叫會傳遞到您的 [`canUseTool` 回呼](/docs/zh-TW/agent-sdk/user-input) 以進行確認，即使在 `bypassPermissions` 模式下也是如此。27 檢查來自 [settings.json](/docs/zh-TW/settings-reference#permission-settings) 的 `ask` 規則。如果詢問規則匹配，呼叫會傳遞到您的 [`canUseTool` 回呼](/docs/zh-TW/agent-sdk/user-input) 以進行確認，即使在 `bypassPermissions` 模式下也是如此。

28 28

29 需要使用者互動的工具行為相同：`AskUserQuestion` 和 MCP 工具（其伺服器設定 [`_meta["anthropic/requiresUserInteraction"]`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool)）總是會傳遞到回呼，即使允許規則符合時也是如此。在 `dontAsk` 模式下，兩種情況都會被拒絕，因為該模式永遠不會提示。MCP 註解需要 Claude Code v2.1.199 或更新版本。29 需要使用者互動的工具行為相同：`AskUserQuestion` 和 MCP 工具（其伺服器設定了 [`_meta["anthropic/requiresUserInteraction"]`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool)）總是傳遞到回呼，即使當 allow 規則匹配時也是如此。在 `dontAsk` 模式下，兩種情況都會被拒絕，因為該模式永遠不會提示。MCP 註解需要 Claude Code v2.1.199 或更新版本。

30 30

31 [claude.ai 連接器](/docs/zh-TW/mcp#organization-controls-on-connector-tools) 工具（您的組織已設定為 `ask`）也會在此步驟離開流程。每個呼叫都會傳遞到回呼，即使在 `bypassPermissions` 模式下，即使允許規則符合時也是如此。回呼會收到原因 `Your organization requires approval for this tool`。在 `dontAsk` 模式下，呼叫會被拒絕，因為該模式永遠不會提示。31 您的組織設定為 `ask` 的 [claude.ai connector](/docs/zh-TW/mcp#organization-controls-on-connector-tools) 工具也會在此步驟離開流程。每個呼叫都會傳遞到回呼，即使在 `bypassPermissions` 模式下，即使當 allow 規則匹配時也是如此。回呼會收到原因 `Your organization requires approval for this tool`。在 `dontAsk` 模式下，呼叫會被拒絕，因為該模式永遠不會提示。

32 </Step>32 </Step>

33 33

34 <Step title="權限模式">34 <Step title="權限模式">

~~35 應用活躍的[權限模式](#permission-modes)：~~35 應用活躍的 [權限模式](#permission-modes)：

36 36

37 * 在 `bypassPermissions` 模式下，Claude Code 批准到達此步驟的所有內容，除了針對[關鍵路徑](/docs/zh-TW/permission-modes#critical-paths)的 `rm` 和 `rmdir` 移除，這些會傳遞到回呼。37 * 在 `bypassPermissions` 模式下，Claude Code 批准到達此步驟的所有內容，除了針對 [關鍵路徑](/docs/zh-TW/permission-modes#critical-paths) 的 `rm` 和 `rmdir` 移除，這些會傳遞下去。

~~38 * 在 `acceptEdits` 模式下，Claude Code 批准[接受編輯模式](#accept-edits-mode-acceptedits)下列出的檔案操作。~~38 * 在 `acceptEdits` 模式下，Claude Code 批准 [接受編輯模式](#accept-edits-mode-acceptedits) 下列出的檔案操作。

~~39 * 在 `plan` 模式下，Claude Code 將檔案編輯和 shell 寫入工具傳送到您的 `canUseTool` 回呼，無論允許規則如何，因此在規劃時寫入操作無法自動批准。~~39 * 在 `plan` 模式下，Claude Code 將檔案編輯和 shell 寫入工具發送到您的 `canUseTool` 回呼，無論 allow 規則如何，因此在規劃時寫入操作無法自動批准。

~~40 * 在其他模式下，請求會傳遞到回呼。~~40 * 在其他模式下，請求會傳遞下去。

41 </Step>41 </Step>

42 42

43 <Step title="允許規則">43 <Step title="允許規則">

44 檢查 `allow` 規則（來自 `allowed_tools` 和 settings.json）。如果規則符合，工具會被批准。呼叫工具本身批准的情況也會在此步驟解決，無需規則：例如在您的工作目錄內的檔案讀取或[唯讀 Bash 命令](/docs/zh-TW/permissions#read-only-commands)。針對[關鍵路徑](/docs/zh-TW/permission-modes#critical-paths)的 `rm` 和 `rmdir` 移除永遠不會被允許規則批准：它們在提示的模式下到達您的回呼，在 Claude Code v2.1.218 或更新版本的 `auto` 模式下進入[分類器](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)，並在 `dontAsk` 模式下被拒絕。44 檢查 `allow` 規則（來自 `allowed_tools` 和 settings.json）。如果規則匹配，工具會被批准。工具自行批准的呼叫也會在此步驟解決，無需規則：例如在您的工作目錄內的檔案讀取或 [唯讀 Bash 命令](/docs/zh-TW/permissions#read-only-commands)。針對 [關鍵路徑](/docs/zh-TW/permission-modes#critical-paths) 的 `rm` 和 `rmdir` 移除永遠不會被 allow 規則批准：它們在提示的模式下到達您的回呼，在 Claude Code v2.1.218 或更新版本的 `auto` 模式下進入 [分類器](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)，並在 `dontAsk` 模式下被拒絕。

45 </Step>45 </Step>

46 46

47 <Step title="canUseTool 回呼">47 <Step title="canUseTool 回呼">

48 如果上述任何步驟都未解決，請呼叫您的 [`canUseTool` 回呼](/docs/zh-TW/agent-sdk/user-input) 以做出決定。在 `dontAsk` 模式下，此步驟會被跳過，工具會被拒絕。48 如果上述任何步驟都未解決，請呼叫您的 [`canUseTool` 回呼](/docs/zh-TW/agent-sdk/user-input) 以獲得決定。在 `dontAsk` 模式下，此步驟會被跳過，工具會被拒絕。

49 49

50 在 TypeScript SDK 中，如果您設定 [`permissionPrompts: 'none'`](/docs/zh-TW/agent-sdk/typescript#options)，您的回呼在此步驟不會被呼叫。[`PermissionRequest` hook](/docs/zh-TW/hooks#permissionrequest) 仍然有機會做出決定，如果它沒有，Claude Code 會拒絕呼叫。此選項需要 Claude Code v2.1.259 或更新版本。50 在 TypeScript SDK 中，如果您設定了 [`permissionPrompts: 'none'`](/docs/zh-TW/agent-sdk/typescript#options)，您的回呼在此步驟不會被呼叫。[`PermissionRequest` hook](/docs/zh-TW/hooks#permissionrequest) 仍然有機會決定，如果它不決定，Claude Code 會拒絕呼叫。此選項需要 Claude Code v2.1.259 或更新版本。

51 </Step>51 </Step>

52</Steps>52</Steps>

53 53

54<img src="https://mintcdn.com/claude-code/jYgs7qigNjO1Badj/images/agent-sdk/permissions-flow.svg?fit=max&auto=format&n=jYgs7qigNjO1Badj&q=85&s=c771ad9085b1277d3708027a49c744bc" className="dark:hidden" alt="六步驟權限評估流程圖，與上述步驟相符：工具請求通過 hooks、拒絕規則、詢問規則、權限模式、允許規則和 canUseTool。Hooks、拒絕規則和 canUseTool 可以路由到'已阻止'；權限模式繞過、允許規則和 canUseTool 可以路由到'執行'；詢問規則路由到 canUseTool。" width="1180" height="260" data-path="images/agent-sdk/permissions-flow.svg" />54<img src="https://mintcdn.com/claude-code/jYgs7qigNjO1Badj/images/agent-sdk/permissions-flow.svg?fit=max&auto=format&n=jYgs7qigNjO1Badj&q=85&s=c771ad9085b1277d3708027a49c744bc" className="dark:hidden" alt="六步權限評估流程的圖表，與上述步驟相符：工具請求通過 hooks、拒絕規則、詢問規則、權限模式、允許規則和 canUseTool。Hooks、拒絕規則和 canUseTool 可以路由到被阻止；權限模式繞過、允許規則和 canUseTool 可以路由到執行；詢問規則路由到 canUseTool。" width="1180" height="260" data-path="images/agent-sdk/permissions-flow.svg" />

55 55

56<img src="https://mintcdn.com/claude-code/_xqph1dUOslCOwsj/images/agent-sdk/permissions-flow-dark.svg?fit=max&auto=format&n=_xqph1dUOslCOwsj&q=85&s=e53a91e9059cbf51852b7cedb4dd4251" className="hidden dark:block" alt="六步驟權限評估流程圖，與上述步驟相符：工具請求通過 hooks、拒絕規則、詢問規則、權限模式、允許規則和 canUseTool。Hooks、拒絕規則和 canUseTool 可以路由到'已阻止'；權限模式繞過、允許規則和 canUseTool 可以路由到'執行'；詢問規則路由到 canUseTool。" width="1180" height="260" data-path="images/agent-sdk/permissions-flow-dark.svg" />56<img src="https://mintcdn.com/claude-code/_xqph1dUOslCOwsj/images/agent-sdk/permissions-flow-dark.svg?fit=max&auto=format&n=_xqph1dUOslCOwsj&q=85&s=e53a91e9059cbf51852b7cedb4dd4251" className="hidden dark:block" alt="六步權限評估流程的圖表，與上述步驟相符：工具請求通過 hooks、拒絕規則、詢問規則、權限模式、允許規則和 canUseTool。Hooks、拒絕規則和 canUseTool 可以路由到被阻止；權限模式繞過、允許規則和 canUseTool 可以路由到執行；詢問規則路由到 canUseTool。" width="1180" height="260" data-path="images/agent-sdk/permissions-flow-dark.svg" />

57 57

58如果您在 TypeScript SDK 預期評估順序會在諮詢回呼之前自動批准呼叫的配置中傳遞 `canUseTool` 回呼，SDK 會在建構查詢時發出一次 Node.js 程序警告。警告的代碼是 `CLAUDE_SDK_CAN_USE_TOOL_SHADOWED`。兩種配置會觸發它：58如果您在 TypeScript SDK 期望評估順序在諮詢回呼之前自動批准呼叫的設定中傳遞 `canUseTool` 回呼，SDK 會在構造查詢時發出一次 Node.js 程序警告。警告的代碼是 `CLAUDE_SDK_CAN_USE_TOOL_SHADOWED`。兩個設定會觸發它：

59 59

60* `permissionMode: 'bypassPermissions'`，它會自動批准到達權限模式步驟的每個呼叫，除了[任何模式都不會自動批准的動作](/docs/zh-TW/permission-modes#actions-no-mode-auto-approves)60* `permissionMode: 'bypassPermissions'`，它自動批准到達權限模式步驟的每個呼叫，除了 [任何模式都不自動批准的操作](/docs/zh-TW/permission-modes#actions-no-mode-auto-approves)

61* 每個裸 `allowedTools` 項目，例如 `"Read"`，它會在諮詢回呼之前自動批准整個工具，除了[任何模式都不會自動批准的動作](/docs/zh-TW/permission-modes#actions-no-mode-auto-approves)61* 每個裸 `allowedTools` 條目，例如 `"Read"`，它在諮詢回呼之前自動批准整個工具，除了 [任何模式都不自動批准的操作](/docs/zh-TW/permission-modes#actions-no-mode-auto-approves)

62 62

~~63具有指定符的項目（例如 `Bash(ls *)`）和 `acceptEdits` 模式不會觸發它，來自設定檔的允許規則對檢查不可見。~~63具有指定符的條目（如 `Bash(ls *)`）和 `acceptEdits` 模式不會觸發它，來自設定檔的 allow 規則對檢查不可見。

64 64

65使用 `process.on('warning', ...)` 進行監聽，並匹配代碼以記錄或抑制它。若要無論模式和規則如何都控制每個工具呼叫，請改用 [`PreToolUse` hook](/docs/zh-TW/agent-sdk/hooks)。65使用 `process.on('warning', ...)` 進行監聽並匹配代碼以記錄或抑制它。要無論模式和規則如何都控制每個工具呼叫，請改用 [`PreToolUse` hook](/docs/zh-TW/agent-sdk/hooks)。

66 66

~~67本頁重點關注 **允許和拒絕規則** 以及 **權限模式**。對於其他步驟：~~67此頁面重點關注 **allow 和 deny 規則** 以及 **權限模式**。對於其他步驟：

68 68

69* **Hooks：** 執行自訂程式碼以允許、拒絕或修改工具請求。請參閱 [使用 hooks 控制執行](/docs/zh-TW/agent-sdk/hooks)。69* **Hooks：** 執行自訂程式碼以允許、拒絕或修改工具請求。請參閱 [使用 hooks 控制執行](/docs/zh-TW/agent-sdk/hooks)。

~~70* **canUseTool 回呼：** 在執行時提示使用者核准，當沒有較早的步驟解決呼叫時。請參閱 [處理核准和使用者輸入](/docs/zh-TW/agent-sdk/user-input)。~~70* **canUseTool 回呼：** 在執行時提示使用者批准，當沒有較早的步驟解決呼叫時。請參閱 [處理批准和使用者輸入](/docs/zh-TW/agent-sdk/user-input)。

71 71

72<h2 id="allow-and-deny-rules">72<h2 id="allow-and-deny-rules">

73 允許和拒絕規則73 允許和拒絕規則

74</h2>74</h2>

75 75

76`allowed_tools` 和 `disallowed_tools`（TypeScript：`allowedTools` / `disallowedTools`）將條目新增到上述評估流程中的允許和拒絕規則清單。如果您在 `allowed_tools` 中命名其中一個[任務追蹤工具](/docs/zh-TW/agent-sdk/todo-tracking#model-availability)，Claude Code 也會選擇加入工作階段。未列在 `allowed_tools` 中的任何其他工具仍然可供 Claude 使用，並且對其的呼叫若需要批准會通過權限模式。拒絕規則的行為取決於它們是命名工具還是在工具內限定模式。76`allowed_tools` 和 `disallowed_tools`（TypeScript：`allowedTools` / `disallowedTools`）在上述評估流程中新增允許和拒絕規則清單的項目。如果您在 `allowed_tools` 中命名其中一個[任務追蹤工具](/docs/zh-TW/agent-sdk/todo-tracking#model-availability)，Claude Code 也會選擇加入該工作階段。任何未列在 `allowed_tools` 中的其他工具仍可供 Claude 使用，對其進行的需要批准的呼叫會進入權限模式。拒絕規則的行為取決於它們是命名工具還是在工具內限定模式。

77 77

78| 選項 | 效果 |78| 選項 | 效果 |

~~79| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------ |~~79| :-------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- |

82| `disallowed_tools=["Bash(rm *)"]` | `Bash` 保持可用。符合 `rm *` [如所寫](/docs/zh-TW/permissions#bash-rule-limits) 的呼叫在每個權限模式中都會被拒絕，包括 `bypassPermissions`。其他 `Bash` 呼叫（包括 `/bin/rm`）會通過權限模式。 |82| `disallowed_tools=["Bash(rm *)"]` | `Bash` 保持可用。符合 `rm *` [如所寫](/docs/zh-TW/permissions#bash-rule-limits)的呼叫在每個權限模式中都會被拒絕，包括 `bypassPermissions`。其他 `Bash` 呼叫（包括 `/bin/rm`）會進入權限模式。 |

84 84

85允許規則只在字面 `mcp__<server>__` 前綴之後接受工具名稱萬用字元。伺服器段必須不含萬用字元，以便規則命名您設定的特定伺服器：`mcp__puppeteer__*` 符合來自 `puppeteer` 伺服器的每個工具，`mcp__github__get_*` 符合其 `get_` 工具。未錨定的條目（如 `allowed_tools=["*"]` 或 `allowed_tools=["mcp__*"]`）會被忽略並顯示啟動警告，不會自動批准任何內容。85允許規則僅在字面 `mcp__<server>__` 前綴之後接受工具名稱萬用字元。伺服器段必須無萬用字元，以便規則命名您設定的特定伺服器：`mcp__puppeteer__*` 符合來自 `puppeteer` 伺服器的每個工具，`mcp__github__get_*` 符合其 `get_` 工具。未錨定的項目（如 `allowed_tools=["*"]` 或 `allowed_tools=["mcp__*"]`）會被忽略並顯示啟動警告，不會自動批准任何內容。

86 86

87`Read` 和 `Edit` 的限定規則採用路徑模式。`Edit(path)` 規則管理所有寫入檔案的內建工具，包括 `Write` 和 `NotebookEdit`；`Write(path)` 規則永遠不會被檔案權限檢查符合。87`Read` 和 `Edit` 的限定規則採用路徑模式。`Edit(path)` 規則管理所有寫入檔案的內建工具，包括 `Write` 和 `NotebookEdit`；`Write(path)` 規則永遠不會被檔案權限檢查符合。

88 88

89使用 `//path` 表示絕對檔案系統路徑：`Edit(//secrets/**)` 的拒絕規則會阻止在磁碟上 `/secrets` 下任何位置的寫入。使用單個前導斜線，`Edit(/secrets/**)` 會在規則的來源處錨定。對於通過 `allowed_tools` 或 `disallowed_tools` 傳遞的規則，這表示工作階段的工作目錄，因此規則不會阻止磁碟上的 `/secrets`。請參閱 [Read 和 Edit 規則](/docs/zh-TW/permissions#read-and-edit) 以了解四種錨定形式以及來自設定檔案的規則如何解析。89使用 `//path` 表示絕對檔案系統路徑：`Edit(//secrets/**)` 的拒絕規則會阻止在磁碟上 `/secrets` 下任何位置的寫入。使用單個前導斜線時，`Edit(/secrets/**)` 會在規則的來源處錨定。對於透過 `allowed_tools` 或 `disallowed_tools` 傳遞的規則，這表示工作階段的工作目錄，因此規則不會阻止磁碟上的 `/secrets`。請參閱[讀取和編輯規則](/docs/zh-TW/permissions#read-and-edit)以了解四種錨定形式以及來自設定檔的規則如何解析。

90 90

91<Warning>91<Warning>

92 **自動批准的工具永遠不會到達 `canUseTool`。** 在任何較早步驟中批准的工具呼叫，由 `acceptEdits` 或 `bypassPermissions` 或允許規則批准，會跳過您的 `canUseTool` 回呼，因此您在那裡放置的權限檢查會被該工具無聲地略過。`AskUserQuestion`、標記為 [`_meta["anthropic/requiresUserInteraction"]`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具、連接器工具[您的組織設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools) 以及 `rm` 和 `rmdir` 移除針對[關鍵路徑](/docs/zh-TW/permission-modes#critical-paths) 仍會到達回呼，即使允許規則符合時也是如此。在 `auto` 模式中，關鍵路徑移除會進入[分類器](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 而不是回呼，而此處列出的其他呼叫仍會到達它；分類器路由需要 Claude Code v2.1.218 或更新版本。在 `dontAsk` 模式中，這些呼叫會被拒絕，不會叫用回呼。92 **自動批准的工具永遠不會到達 `canUseTool`。** 在任何較早步驟中批准的工具呼叫，透過 `acceptEdits` 或 `bypassPermissions`，或透過允許規則，會跳過您的 `canUseTool` 回呼，因此您在那裡放置的權限檢查會被該工具無聲地繞過。`AskUserQuestion`、標記為 [`_meta["anthropic/requiresUserInteraction"]`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具、連接器工具[您的組織設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools)，以及 `rm` 和 `rmdir` 移除針對[關鍵路徑](/docs/zh-TW/permission-modes#critical-paths)的移除仍會到達回呼，即使允許規則符合也是如此。在 `auto` 模式中，關鍵路徑移除會進入[分類器](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)而不是回呼，而上面列出的其他呼叫仍會到達它；分類器路由需要 Claude Code v2.1.218 或更新版本。在 `dontAsk` 模式中，這些呼叫會被拒絕，不會呼叫回呼。

93 93

94 涵蓋範圍取決於條目的形式：像 `Read` 或 `mcp__github__get_issue` 這樣的裸名稱會自動批准對該工具的每個呼叫（除了上述例外），而像 `Bash(npm test *)` 這樣的限定規則只會自動批准符合的呼叫，其他 `Bash` 呼叫若需要批准仍會通過回呼。對於必須在每個工具呼叫上執行的檢查，請使用 [`PreToolUse` hook](/docs/zh-TW/agent-sdk/hooks)：hook 在每個其他步驟之前執行，hook 拒絕甚至在 `bypassPermissions` 模式中也適用。94 涵蓋範圍取決於項目的形式：像 `Read` 或 `mcp__github__get_issue` 這樣的裸名稱會自動批准對該工具的每個呼叫，除了上述例外情況，而像 `Bash(npm test *)` 這樣的限定規則只會自動批准符合的呼叫，其他需要批准的 `Bash` 呼叫仍會進入回呼。對於必須在每個工具呼叫上執行的檢查，請使用 [`PreToolUse` hook](/docs/zh-TW/agent-sdk/hooks)：hook 在每個其他步驟之前執行，hook 拒絕即使在 `bypassPermissions` 模式中也適用。

95</Warning>95</Warning>

96 96

~~97對於鎖定的代理程式，將 `allowedTools` 與 `permissionMode: "dontAsk"` 配對：~~97對於鎖定的代理，將 `allowedTools` 與 `permissionMode: "dontAsk"` 配對：

98 98

99```typescript theme={null}99```typescript theme={null}

100const options = {100const options = {

103};103};

104```104```

105 105

106列出的工具會被批准，除了[任何模式都不會自動批准的動作](/docs/zh-TW/permission-modes#actions-no-mode-auto-approves)，並且其他任何會提示的呼叫都會被拒絕。在 `default` 模式中不需要批准的呼叫會執行，無論您是否列出它們，例如[唯讀 Bash 命令](/docs/zh-TW/permissions#read-only-commands)、不會在執行前詢問的工具（如 `Agent`），以及工作目錄內的檔案讀取。若要將工具完全置於 Claude 的範圍之外，請將其裸名稱新增到 `disallowedTools`。106列出的工具會被批准，除了[任何模式都不自動批准的動作](/docs/zh-TW/permission-modes#actions-no-mode-auto-approves)，以及每個其他會提示的呼叫都會被拒絕。在 `default` 模式中不需要批准的呼叫會執行，無論您是否列出它們，例如[唯讀 Bash 命令](/docs/zh-TW/permissions#read-only-commands)、不在執行前詢問的工具（如 `Agent`），以及工作目錄內的檔案讀取。要將工具完全置於 Claude 的範圍之外，請將其裸名稱新增到 `disallowedTools`。

107 107

108<Warning>108<Warning>

109 **`allowed_tools` 不會限制 `bypassPermissions`。** `allowed_tools` 只會預先批准您列出的工具。未列出的工具不會被任何允許規則符合，並會通過權限模式，其中 `bypassPermissions` 會批准它們。將 `allowed_tools=["Read"]` 與 `permission_mode="bypassPermissions"` 一起設定仍然會批准每個工具，包括 `Bash`、`Write` 和 `Edit`。如果您需要 `bypassPermissions` 但想要阻止特定工具，請使用 `disallowed_tools`。109 **`allowed_tools` 不限制 `bypassPermissions`。** `allowed_tools` 預先批准您列出的工具。其他未列出的工具不符合任何允許規則，會進入權限模式，其中 `bypassPermissions` 會批准它們。將 `allowed_tools=["Read"]` 與 `permission_mode="bypassPermissions"` 一起設定仍會批准每個工具，包括 `Bash`、`Write` 和 `Edit`。如果您需要 `bypassPermissions` 但想要阻止特定工具，請使用 `disallowed_tools`。

110</Warning>110</Warning>

111 111

112您也可以在 `.claude/settings.json` 中宣告式地設定允許、拒絕和詢問規則。當啟用 `project` 設定來源時，這些規則會被讀取，預設 `query()` 選項就是這樣。如果您明確設定 `setting_sources`（TypeScript：`settingSources`），請包含 `"project"` 以便它們適用。請參閱 [權限設定](/docs/zh-TW/settings-reference#permission-settings) 以了解規則語法。112您也可以在 `.claude/settings.json` 中以宣告方式設定允許、拒絕和詢問規則。當啟用 `project` 設定來源時會讀取這些規則，預設 `query()` 選項就是這樣。如果您明確設定 `setting_sources`（TypeScript：`settingSources`），請包含 `"project"` 以便它們適用。請參閱[權限設定](/docs/zh-TW/settings-reference#permission-settings)以了解規則語法。

113 113

114<h2 id="permission-modes">114<h2 id="permission-modes">

115 權限模式115 權限模式

116</h2>116</h2>

117 117

118權限模式提供對 Claude 如何使用工具的全域控制。您可以在呼叫 `query()` 時設定權限模式，或在串流會話期間動態更改它。118權限模式提供對 Claude 如何使用工具的全域控制。您可以在呼叫 `query()` 時設定權限模式，或在串流工作階段期間動態變更它。

119 119

120<h3 id="available-modes">120<h3 id="available-modes">

121 可用模式121 可用模式

123 123

124SDK 支援這些權限模式：124SDK 支援這些權限模式：

125 125

126| 模式 | 描述 | 工具行為 |126| 模式 | 說明 | 工具行為 |

127| :------------------ | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |127| :------------------ | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

129| `dontAsk` | 拒絕而不是提示 | 任何會提示的呼叫都會被拒絕。由 `allowed_tools` 或規則批准的呼叫會執行，在 `default` 模式中不需要批准的呼叫也會執行；連接器工具[您的組織設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools)和需要使用者互動的工具即使您已預先批准它們也會被拒絕，`rm` 和 `rmdir` 移除針對[關鍵路徑](/docs/zh-TW/permission-modes#critical-paths)的操作也會被拒絕。`canUseTool` 永遠不會被呼叫 |129| `dontAsk` | 拒絕而非提示 | 任何原本會提示的呼叫都會被拒絕。由 `allowed_tools` 或規則核准的呼叫會執行，在 `default` 模式中不需要核准的呼叫也會執行；您的組織[設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools) 的連接器工具和需要使用者互動的工具會被拒絕，即使您已預先核准它們，針對[關鍵路徑](/docs/zh-TW/permission-modes#critical-paths)的 `rm` 和 `rmdir` 移除也會被拒絕。`canUseTool` 永遠不會被呼叫 |

134 134

135<Warning>135<Warning>

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

137 137

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

139</Warning>139</Warning>

140 140

141<h3 id="set-permission-mode">141<h3 id="set-permission-mode">

142 設定權限模式142 設定權限模式

143</h3>143</h3>

144 144

145您可以在開始查詢時設定一次權限模式，或在會話活躍時動態更改它。145您可以在開始查詢時設定一次權限模式，或在工作階段進行中動態變更它。

146 146

147<Tabs>147<Tabs>

148 <Tab title="在查詢時">148 <Tab title="在查詢時">

149 在建立查詢時傳遞 `permission_mode`（Python）或 `permissionMode`（TypeScript）。此模式適用於整個會話，除非動態更改。149 在建立查詢時傳遞 `permission_mode`（Python）或 `permissionMode`（TypeScript）。此模式適用於整個工作階段，除非動態變更。

150 150

151 <CodeGroup>151 <CodeGroup>

152 ```python Python theme={null}152 ```python Python theme={null}

190 </Tab>190 </Tab>

191 191

192 <Tab title="在串流期間">192 <Tab title="在串流期間">

193 呼叫 `set_permission_mode()`（Python）或 `setPermissionMode()`（TypeScript）以在會話中途更改模式。新模式會立即對所有後續工具請求生效。這讓您可以從限制性開始，並隨著信任建立而放寬權限，例如在檢查 Claude 的初始方法後切換到 `acceptEdits`。193 呼叫 `set_permission_mode()`（Python）或 `setPermissionMode()`（TypeScript）以在工作階段中途變更模式。新模式會立即對所有後續工具請求生效。這讓您可以從限制性開始，並隨著信任建立而放寬權限，例如在檢閱 Claude 的初始方法後切換到 `acceptEdits`。

194 194

195 <CodeGroup>195 <CodeGroup>

196 ```python Python theme={null}196 ```python Python theme={null}

254 接受編輯模式（`acceptEdits`）254 接受編輯模式（`acceptEdits`）

255</h4>255</h4>

256 256

257自動批准檔案操作，以便 Claude 可以編輯程式碼而無需提示。其他工具（例如不是檔案系統操作的 Bash 命令）仍然需要正常權限。257自動核准檔案操作，讓 Claude 可以編輯程式碼而不會提示。其他工具（例如不是檔案系統操作的 Bash 命令）仍然需要正常權限。

258 258

259**自動批准的操作：**259**自動核准的操作：**

260 260

261* 檔案編輯（Edit、Write 工具）261* 檔案編輯（Edit、Write 工具）

262* 檔案系統命令：`mkdir`、`touch`、`rm`、`rmdir`、`mv`、`cp`、`sed`262* 檔案系統命令：`mkdir`、`touch`、`rm`、`rmdir`、`mv`、`cp`、`sed`

263 263

264兩者都只適用於工作目錄或 `additionalDirectories` 內的路徑。在 `acceptEdits` 模式中，當 Claude 執行以下操作時，Claude Code 不會自動批准請求：264兩者都只適用於工作目錄或 `additionalDirectories` 內的路徑。在 `acceptEdits` 模式中，當 Claude 執行以下操作時，Claude Code 不會自動核准請求：

265 265

266* 在該範圍外的路徑上工作266* 在該範圍外的路徑上工作

267* 寫入受保護的路徑267* 寫入受保護的路徑

270**使用時機：** 您信任 Claude 的編輯並想要更快的迭代，例如在原型設計期間或在隔離目錄中工作時。270**使用時機：** 您信任 Claude 的編輯並想要更快的迭代，例如在原型設計期間或在隔離目錄中工作時。

271 271

272<h4 id="don’t-ask-mode-dontask">272<h4 id="don’t-ask-mode-dontask">

273 不詢問模式（`dontAsk`）273 不要詢問模式（`dontAsk`）

274</h4>274</h4>

275 275

276將任何會提示的呼叫轉換為拒絕，而不呼叫 `canUseTool`。由 `allowed_tools`、`settings.json` 允許規則或 hook 預先批准的工具會正常執行，在 `default` 模式中不需要批准的呼叫（例如在您的工作目錄內的檔案讀取和對 `Agent` 的呼叫）也會執行。連接器工具[您的組織設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools)、需要使用者互動的工具，以及 `rm` 和 `rmdir` 移除針對[關鍵路徑](/docs/zh-TW/permission-modes#critical-paths)的操作即使允許規則符合也會被拒絕。`PreToolUse` hook 允許也不會清除關鍵路徑移除。276將任何權限提示轉換為拒絕，而不呼叫 `canUseTool`。由 `allowed_tools`、`settings.json` 允許規則或鉤子預先核准的工具會正常執行，在 `default` 模式中不需要核准的呼叫也會執行，例如在您的工作目錄內的檔案讀取和對 `Agent` 的呼叫。您的組織[設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools) 的連接器工具、需要使用者互動的工具，以及針對[關鍵路徑](/docs/zh-TW/permission-modes#critical-paths)的 `rm` 和 `rmdir` 移除即使符合允許規則也會被拒絕。`PreToolUse` 鉤子允許也不會清除關鍵路徑移除。

277 277

278**使用時機：** 您想要為無頭代理程式提供固定的明確工具表面，並且更喜歡硬拒絕而不是無聲依賴 `canUseTool` 不存在。278**使用時機：** 您想要為無頭代理提供固定、明確的工具表面，並偏好硬拒絕而非無聲依賴 `canUseTool` 不存在。

279 279

280<h4 id="bypass-permissions-mode-bypasspermissions">280<h4 id="bypass-permissions-mode-bypasspermissions">

281 繞過權限模式（`bypassPermissions`）281 略過權限模式（`bypassPermissions`）

282</h4>282</h4>

283 283

284自動批准工具使用而無需提示，除了下方警告中列出的情況。Hooks 仍然執行，如果需要可以阻止操作。284自動核准工具使用而不提示，除了下面警告中列出的情況。鉤子仍然執行，如果需要可以阻止操作。

285 285

286<Warning>286<Warning>

287 謹慎使用。Claude 在此模式下具有完整的系統存取權。僅在您信任所有可能操作的受控環境中使用。287 請極其謹慎使用。Claude 在此模式中具有完整的系統存取權。僅在您信任所有可能操作的受控環境中使用。

288 288

289 `allowed_tools` 不會限制此模式。每個工具都會被批准，而不僅僅是您列出的工具。這些控制仍然適用：289 `allowed_tools` 不會限制此模式。每個工具都會被核准，而不僅僅是您列出的工具。這些控制仍然適用：

290 290

291 * 拒絕規則、明確的 `ask` 規則和 hooks 會在模式檢查之前被評估，仍然可以阻止工具。291 * 拒絕規則、明確的 `ask` 規則和鉤子在模式檢查之前被評估，仍然可以阻止工具。

292 * 連接器工具[您的組織設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools)、需要使用者互動的工具，以及 `rm` 和 `rmdir` 移除針對[關鍵路徑](/docs/zh-TW/permission-modes#critical-paths)的操作仍然會透過您的 `canUseTool` 回呼進行。292 * 您的組織[設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools) 的連接器工具、需要使用者互動的工具，以及針對[關鍵路徑](/docs/zh-TW/permission-modes#critical-paths)的 `rm` 和 `rmdir` 移除仍然會進入您的 `canUseTool` 回呼。

293 * [跨會話訊息安全防護](/docs/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode)仍然適用。293 * [跨工作階段訊息保護措施](/docs/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode)仍然適用。

294</Warning>294</Warning>

295 295

296<h4 id="plan-mode-plan">296<h4 id="plan-mode-plan">

297 規劃模式（`plan`）297 規劃模式（`plan`）

298</h4>298</h4>

299 299

300Claude 探索程式碼庫並產生計畫而不編輯您的原始檔案。唯讀工具在 `default` 權限模式中執行。300Claude 探索程式碼庫並產生計畫，而不編輯您的原始檔案。唯讀工具的執行方式與在 `default` 權限模式中相同。

301 301

302檔案編輯在規劃模式下永遠不會自動批准，即使允許規則符合。它們改為透過您的 `canUseTool` 回呼提示。在 Claude Code v2.1.212 或更新版本上，修改檔案的 shell 命令（例如 `touch` 和 `rm`）會以相同方式到達您的 `canUseTool` 回呼。302在規劃模式中，檔案編輯永遠不會自動被核准，即使符合允許規則。它們會改為透過您的 `canUseTool` 回呼提示。在 Claude Code v2.1.212 或更新版本上，修改檔案的 shell 命令（例如 `touch` 和 `rm`）會以相同方式到達您的 `canUseTool` 回呼。

303 303

304Claude 可能會使用 `AskUserQuestion` 在最終確定計畫之前澄清需求。請參閱[處理核准和使用者輸入](/docs/zh-TW/agent-sdk/user-input#handle-clarifying-questions)以處理這些提示。304Claude 可能會使用 `AskUserQuestion` 在最終確定計畫之前澄清需求。請參閱[處理核准和使用者輸入](/docs/zh-TW/agent-sdk/user-input#handle-clarifying-questions)以處理這些提示。

305 305

306**使用時機：** 您想要 Claude 提出變更建議而不執行它們，例如在程式碼審查期間或當您需要在進行變更之前核准變更時。306**使用時機：** 您想要 Claude 提議變更而不執行它們，例如在程式碼審查期間或當您需要在進行變更之前核准變更時。

307 307

308<h2 id="related-resources">308<h2 id="related-resources">

309 相關資源309 相關資源

310</h2>310</h2>

311 311

312對於權限評估流程中的其他步驟：312如需了解權限評估流程中的其他步驟：

313 313

314* [處理核准和使用者輸入](/docs/zh-TW/agent-sdk/user-input)：互動式核准提示和澄清問題314* [處理核准和使用者輸入](/docs/zh-TW/agent-sdk/user-input)：互動式核准提示和澄清問題

315* [Hooks 指南](/docs/zh-TW/agent-sdk/hooks)：在代理程式生命週期中的關鍵點執行自訂程式碼315* [Hooks 指南](/docs/zh-TW/agent-sdk/hooks)：在代理程式生命週期中的關鍵點執行自訂程式碼

agent-sdk/plugins.md +1 −1

Details

69 69

70Plugin 路徑可以是：70Plugin 路徑可以是：

71 71

~~72* **相對路徑**：相對於您的當前工作目錄解析（例如，`"./plugins/my-plugin"`）~~72* **相對路徑**：相對於 `cwd` 選項解析（例如，`"./plugins/my-plugin"`）

73* **絕對路徑**：完整文件系統路徑（例如，`"/home/user/plugins/my-plugin"`）73* **絕對路徑**：完整文件系統路徑（例如，`"/home/user/plugins/my-plugin"`）

74 74

75<Note>75<Note>

agent-sdk/python.md +11 −4

Details

513 async def receive_messages(self) -> AsyncIterator[Message]513 async def receive_messages(self) -> AsyncIterator[Message]

514 async def receive_response(self) -> AsyncIterator[Message]514 async def receive_response(self) -> AsyncIterator[Message]

515 async def interrupt(self) -> None515 async def interrupt(self) -> None

516 async def set_permission_mode(self, mode: str) -> None516 async def set_permission_mode(self, mode: PermissionMode) -> None

517 async def set_model(self, model: str | None = None) -> None517 async def set_model(self, model: str | None = None) -> None

518 async def rewind_files(self, user_message_id: str) -> None518 async def rewind_files(self, user_message_id: str) -> None

519 async def get_mcp_status(self) -> McpStatusResponse519 async def get_mcp_status(self) -> McpStatusResponse

548 548

549<h4 id="context-manager-support">549<h4 id="context-manager-support">

2006所有內容區塊的聯合類型。2006所有內容區塊的聯合類型。

2007 2007

2008```python theme={null}2008```python theme={null}

2009ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock2009ContentBlock = (

2010 TextBlock

2011 | ThinkingBlock

2012 | ToolUseBlock

2013 | ToolResultBlock

2014 | ServerToolUseBlock

2015 | ServerToolResultBlock

2016)

2010```2017```

2011 2018

2012<h3 id="textblock">2019<h3 id="textblock">

agent-sdk/skills.md +3 −3

Details

103 確認 Skills 已加載103 確認 Skills 已加載

104</h3>104</h3>

105 105

106在流的開始附近，SDK 會產生一個子類型為 `init` 的系統消息。檢查其 `skills` 陣列以確認您的 Skills 在 Claude 開始工作之前已加載。該陣列包括您已定義的使用者可調用 Skills，以及 [Claude Code 包含的捆綁 Skills](/docs/zh-TW/skills#bundled-skills)。106在流的開始附近，SDK 會產生一個子類型為 `init` 的系統訊息。檢查其 `skills` 陣列以確認您的 Skills 在 Claude 開始工作之前已加載。該陣列包括您已定義的使用者可調用 Skills（具有 `description` 或 `when_to_use` frontmatter 欄位），以及 [Claude Code 包含的捆綁 Skills](/docs/zh-TW/skills#bundled-skills)。

107 107

108該陣列僅列出使用者可調用的 Skills。具有 frontmatter 中 [`user-invocable: false`](/docs/zh-TW/skills#control-who-invokes-a-skill) 的 Skill 會加載並保持對 Claude 可用，但不會出現在陣列中。該陣列反映會話發現的內容，並列出相同的 Skills，無論它們是否在您的 `skills` 列表中。108該陣列僅列出使用者可調用的 Skills。具有 frontmatter 中 [`user-invocable: false`](/docs/zh-TW/skills#control-who-invokes-a-skill) 的 Skill 會加載並保持對 Claude 可用，但不會出現在陣列中。該陣列列出相同的 Skills，無論它們是否在您的 `skills` 列表中。

109 109

110<h3 id="allow-only-specific-skills">110<h3 id="allow-only-specific-skills">

111 僅允許特定 Skills111 僅允許特定 Skills

173Available commands: ["clear", "compact", "context", "usage", "code-review", "verify", "security-check", ...]173Available commands: ["clear", "compact", "context", "usage", "code-review", "verify", "security-check", ...]

174```174```

175 175

176您的使用者可呼叫技能會出現在此清單和[確認技能已載入](#confirm-skills-loaded)中的 `skills` 陣列中。`slash_commands` 清單新增了工作階段中可用的其餘命令。在其前置資料中具有 [`user-invocable: false`](/docs/zh-TW/skills#control-who-invokes-a-skill) 的技能不會出現在任一個中。設定[MCP 伺服器](/docs/zh-TW/agent-sdk/mcp)的工作階段也可以公開 [MCP 提示作為命令](/docs/zh-TW/mcp#use-mcp-prompts-as-commands)。176在其前置資料中具有 [`user-invocable: false`](/docs/zh-TW/skills#control-who-invokes-a-skill) 的技能不會出現在此清單或[確認技能已載入](#confirm-skills-loaded)中的 `skills` 陣列中。設定 [MCP 伺服器](/docs/zh-TW/agent-sdk/mcp)的工作階段也可以公開 [MCP 提示作為命令](/docs/zh-TW/mcp#use-mcp-prompts-as-commands)。

177 177

178<h3 id="dispatch-commands-by-name">178<h3 id="dispatch-commands-by-name">

179 按名稱分派命令179 按名稱分派命令

agent-sdk/streaming-output.md +3 −26

Details

79 79

80啟用部分訊息時，您會收到包裝在物件中的原始 Claude API 串流事件。該類型在每個 SDK 中有不同的名稱：80啟用部分訊息時，您會收到包裝在物件中的原始 Claude API 串流事件。該類型在每個 SDK 中有不同的名稱：

81 81

~~82* **Python**：`StreamEvent`（從 `claude_agent_sdk.types` 匯入）~~82* **Python**：[`StreamEvent`](/docs/zh-TW/agent-sdk/python#streamevent)（從 `claude_agent_sdk.types` 匯入）

~~83* **TypeScript**：`SDKPartialAssistantMessage`，其中 `type: 'stream_event'`~~83* **TypeScript**：[`SDKPartialAssistantMessage`](/docs/zh-TW/agent-sdk/typescript#sdkpartialassistantmessage)，其中 `type: 'stream_event'`

84 84

~~85兩者都包含原始 Claude API 事件，而非累積的文字。您需要自行提取和累積文字差異。以下是每種類型的結構：~~85兩者都包含原始 Claude API 事件，而非累積的文字。您需要自行提取和累積文字差異。

~~87<CodeGroup>~~

~~88 ```python Python theme={null}~~

~~89 @dataclass~~

~~90 class StreamEvent:~~

~~91 uuid: str # Unique identifier for this event~~

~~92 session_id: str # Session identifier~~

~~93 event: dict[str, Any] # The raw Claude API stream event~~

~~94 parent_tool_use_id: str | None # Always None~~

~~95 ```~~

~~97 ```typescript TypeScript theme={null}~~

~~98 type SDKPartialAssistantMessage = {~~

~~99 type: "stream_event";~~

100 event: BetaRawMessageStreamEvent; // From Anthropic SDK

101 parent_tool_use_id: string | null;

102 uuid: UUID;

103 session_id: string;

104 ttft_ms?: number; // Time to first token in ms, present only on message_start events

105 user_message_uuid?: string;

106 };

107 ```

108</CodeGroup>

109 86

110在 Python 中，`parent_tool_use_id` 欄位始終為 `None`，在 TypeScript 中為 `null`。串流事件僅針對主工作階段發出；來自子代理的權杖級差異不會被轉發。若要將輸出歸因於子代理，請使用完整訊息，其中包含 `parent_tool_use_id`。請參閱[偵測子代理叫用](/docs/zh-TW/agent-sdk/subagents#detect-subagent-invocation)。87在 Python 中，`parent_tool_use_id` 欄位始終為 `None`，在 TypeScript 中為 `null`。串流事件僅針對主工作階段發出；來自子代理的權杖級差異不會被轉發。若要將輸出歸因於子代理，請使用完整訊息，其中包含 `parent_tool_use_id`。請參閱[偵測子代理叫用](/docs/zh-TW/agent-sdk/subagents#detect-subagent-invocation)。

111 88

agent-sdk/typescript.md +2 −2

Details

498| `disallowedTools` | `string[]` | `[]` | 要拒絕的工具。裸名稱如 `"Bash"` 會從 Claude 的上下文中移除該工具。作用域規則如 `"Bash(rm *)"` 會保留該工具可用，並在每個權限模式中拒絕匹配的調用，包括 `bypassPermissions`，針對 [as written](/docs/zh-TW/permissions#bash-rule-limits) 的命令。見 [Permissions](/docs/zh-TW/agent-sdk/permissions#allow-and-deny-rules) |498| `disallowedTools` | `string[]` | `[]` | 要拒絕的工具。裸名稱如 `"Bash"` 會從 Claude 的上下文中移除該工具。作用域規則如 `"Bash(rm *)"` 會保留該工具可用，並在每個權限模式中拒絕匹配的調用，包括 `bypassPermissions`，針對 [as written](/docs/zh-TW/permissions#bash-rule-limits) 的命令。見 [Permissions](/docs/zh-TW/agent-sdk/permissions#allow-and-deny-rules) |

501| `env` | `Record<string, string \| undefined>` | `process.env` | 環境變數。設置此項時，這會替換子進程環境而不是與 `process.env` 合併，因此傳遞 `{ ...process.env, YOUR_VAR: 'value' }` 以保留繼承的變數如 `PATH`。見 [Handle slow or stalled API responses](#handle-slow-or-stalled-api-responses) 了解此模式的範例，以及 [Environment variables](/docs/zh-TW/env-vars) 了解底層 CLI 讀取的變數。設置 `CLAUDE_AGENT_SDK_CLIENT_APP` 以在 User-Agent 標頭中識別您的應用程式 |501| `env` | `Record<string, string \| undefined>` | `process.env` | 環境變數。設置此項時，這會替換子進程環境而不是與 `process.env` 合併，因此傳遞 `{ ...process.env, YOUR_VAR: 'value' }` 以保留繼承的變數如 `PATH`。見 [Handle slow or stalled API responses](#handle-slow-or-stalled-api-responses) 了解此模式的範例，以及 [Environment variables](/docs/zh-TW/env-vars) 了解底層 CLI 讀取的變數。設置 `CLAUDE_AGENT_SDK_CLIENT_APP` 以在 User-Agent 標頭中識別您的應用程式 |

5535 `SDKLocalCommandOutputMessage`5535 `SDKLocalCommandOutputMessage`

5536</h3>5536</h3>

5537 5537

5538本地命令（例如 `/voice` 或 `/usage`）的輸出。在記錄中顯示為助手風格的文本。5538Claude Code 不發出此消息類型。當您發送命令（例如 `/context` 或 `/usage`）作為提示時，其輸出作為 [`SDKAssistantMessage`](#sdkassistantmessage) 到達。

5539 5539

5540```typescript theme={null}5540```typescript theme={null}

5541type SDKLocalCommandOutputMessage = {5541type SDKLocalCommandOutputMessage = {

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

Details

12 12

13對於澄清問題，Claude 會生成問題和選項。您的角色是將它們呈現給使用者並返回他們的選擇。您無法將自己的問題添加到此流程中；如果您需要自己詢問使用者某些事項，請在應用程式邏輯中單獨進行。13對於澄清問題，Claude 會生成問題和選項。您的角色是將它們呈現給使用者並返回他們的選擇。您無法將自己的問題添加到此流程中；如果您需要自己詢問使用者某些事項，請在應用程式邏輯中單獨進行。

14 14

15回呼可以無限期地保持待處理狀態。執行保持暫停狀態，直到您的回呼返回，SDK 只在查詢本身被取消時才取消等待。如果使用者可能需要比您的流程合理保持運行的時間更長的時間來回應，請註冊一個 [`PreToolUse` hook](/docs/zh-TW/agent-sdk/hooks)，它返回 [`defer` 決定](/docs/zh-TW/hooks#defer-a-tool-call-for-later)而不是在回呼中等待，以便流程可以退出並稍後從持久化會話恢復。15回呼可以無限期地保持待處理狀態。執行保持暫停狀態，直到您的回呼返回。如果使用者可能需要比您的流程合理保持運行的時間更長的時間來回應，請註冊一個 [`PreToolUse` hook](/docs/zh-TW/agent-sdk/hooks)，它返回 [`defer` 決定](/docs/zh-TW/hooks#defer-a-tool-call-for-later)而不是在回呼中等待，以便流程可以退出並稍後從持久化會話恢復。

16 16

17本指南向您展示如何檢測每種類型的請求並做出適當的回應。17本指南向您展示如何檢測每種類型的請求並做出適當的回應。

18 18

204 ```204 ```

205</CodeGroup>205</CodeGroup>

206 206

207<Note>

208 在 Python 中，`can_use_tool` 需要[串流模式](/docs/zh-TW/agent-sdk/streaming-vs-single-mode)。當您透過 `query(prompt=generator)` 或 `ClaudeSDKClient.connect(prompt=async_iterable)` 傳遞有限的訊息流時，SDK 會在最後一條訊息之後關閉輸入流，在權限回呼可以被調用之前，除非已註冊的 hook 或進程內 MCP 伺服器保持它開放。上面的範例使用返回 `{"continue_": True}` 的 `PreToolUse` hook 保持它開放。使用沒有提示的連接並透過 `ClaudeSDKClient.query()` 發送訊息會自動保持流開放，不需要 hook。

209</Note>

~~210~~

211此範例使用 y/n 流程，其中除 `y` 以外的任何輸入都被視為拒絕。在實踐中，您可能會構建一個更豐富的 UI，讓使用者修改請求、提供回饋或完全重定向 Claude。有關所有回應方式，請參閱[回應工具請求](#respond-to-tool-requests)。207此範例使用 y/n 流程，其中除 `y` 以外的任何輸入都被視為拒絕。在實踐中，您可能會構建一個更豐富的 UI，讓使用者修改請求、提供回饋或完全重定向 Claude。有關所有回應方式，請參閱[回應工具請求](#respond-to-tool-requests)。

212 208

213<h3 id="respond-to-tool-requests">209<h3 id="respond-to-tool-requests">

amazon-bedrock.md +1 −1

Details

239 239

240自 Claude Code v2.1.181 起，也接受來自 `aws configure export-credentials --format process` 的平面輸出，其中相同的金鑰位於頂層而不是巢狀在 `Credentials` 下。240自 Claude Code v2.1.181 起，也接受來自 `aws configure export-credentials --format process` 的平面輸出，其中相同的金鑰位於頂層而不是巢狀在 `Credentials` 下。

241 241

242`Expiration` 是選用的。自 Claude Code v2.1.176 起，當命令傳回有效的 ISO 8601 `Expiration` 時，Claude Code 會快取認證直到該時間前五分鐘。沒有它，或在較早的版本上，認證會快取一小時。242`Expiration` 是選用的。當命令傳回有效的 ISO 8601 `Expiration` 時，Claude Code 會快取認證直到該時間前五分鐘。沒有它，認證會快取一小時。

243 243

244當您設定 `awsCredentialExport` 而不設定 `awsAuthRefresh` 時，Claude Code 直接使用匯出的認證，不會在啟動時重新解析 AWS 預設認證提供者鏈。需要 Claude Code v2.1.206 或更新版本。244當您設定 `awsCredentialExport` 而不設定 `awsAuthRefresh` 時，Claude Code 直接使用匯出的認證，不會在啟動時重新解析 AWS 預設認證提供者鏈。需要 Claude Code v2.1.206 或更新版本。

245 245

authentication.md +1 −6

Details

170* **`claude setup-token` 和 `/install-github-app`**：僅強制執行 `forceLoginMethod`，因此它們可以在不同的組織中鑄造權杖170* **`claude setup-token` 和 `/install-github-app`**：僅強制執行 `forceLoginMethod`，因此它們可以在不同的組織中鑄造權杖

171* **[閘道](/docs/zh-TW/claude-apps-gateway) 登入**：由 `forceLoginMethod: "gateway"` 選擇而不是受其限制，並且不針對 Anthropic 組織進行驗證，因此 `forceLoginOrgUUID` 不適用；使用您的閘道身分提供者來限制存取171* **[閘道](/docs/zh-TW/claude-apps-gateway) 登入**：由 `forceLoginMethod: "gateway"` 選擇而不是受其限制，並且不針對 Anthropic 組織進行驗證，因此 `forceLoginOrgUUID` 不適用；使用您的閘道身分提供者來限制存取

172 172

173透過您的裝置管理工具部署金鑰。[伺服器受管設定](/docs/zh-TW/server-managed-settings) 只能到達已驗證到您的組織的帳戶，因此它們無法重新導向開發人員的首次登入。如果您的組織也分發伺服器受管設定，請在兩個位置設定金鑰：受管設定來源 [不會合併](/docs/zh-TW/server-managed-settings#settings-precedence)，快取的伺服器受管設定會取代裝置受管檔案，除了兩種金鑰仍然從失敗的來源填入：173透過您的裝置管理工具部署金鑰。[伺服器受管設定](/docs/zh-TW/server-managed-settings) 只能到達已驗證到您的組織的帳戶，因此它們無法重新導向開發人員的首次登入。如果您的組織也分發伺服器受管設定，請在兩個位置設定金鑰：受管設定來源 [不會合併](/docs/zh-TW/server-managed-settings#settings-precedence)，快取的伺服器受管設定會取代裝置受管檔案，除了幾個 [各受管來源的個別金鑰例外](/docs/zh-TW/server-managed-settings#per-key-exceptions-across-managed-sources)。`forceLoginOrgUUID` 和 `forceLoginMethod` 的 `"claudeai"` 和 `"console"` 值不在這些例外中，因此請將它們保留在兩個位置。

~~174~~

175* **`env` 區塊**：在 Claude Code v2.1.223 或更新版本中 [按金鑰合併](/docs/zh-TW/server-managed-settings#per-key-exceptions-across-managed-sources)

176* **[跨來源鎖定金鑰](/docs/zh-TW/server-managed-settings#per-key-exceptions-across-managed-sources)**：從任何管理來源接受

~~177~~

178`forceLoginMethod` 和 `forceLoginOrgUUID` 都不是，因此請將它們保留在兩個位置。

179 174

180金鑰也決定不使用登入認證的工作階段是否可以啟動。請參閱設定參考中的 [`forceLoginOrgUUID`](/docs/zh-TW/settings-reference#forceloginorguuid) 以了解完整行為。175金鑰也決定不使用登入認證的工作階段是否可以啟動。請參閱設定參考中的 [`forceLoginOrgUUID`](/docs/zh-TW/settings-reference#forceloginorguuid) 以了解完整行為。

181 176

best-practices.md +0 −2

Details

568claude -p "<your prompt>" --output-format json | your_command568claude -p "<your prompt>" --output-format json | your_command

569```569```

570 570

571在開發期間使用 `--verbose` 進行偵錯，在生產中關閉它。

~~572~~

573<h3 id="run-autonomously-with-auto-mode">571<h3 id="run-autonomously-with-auto-mode">

574 使用 auto mode 自主運行572 使用 auto mode 自主運行

575</h3>573</h3>

claude-code-on-the-web.md +2 −2

Details

87 `--cloud` 建立雲端工作階段。`--remote-control` 無關：它公開本機 CLI 工作階段以從網頁進行監控。請參閱[遠端控制](/docs/zh-TW/remote-control)。87 `--cloud` 建立雲端工作階段。`--remote-control` 無關：它公開本機 CLI 工作階段以從網頁進行監控。請參閱[遠端控制](/docs/zh-TW/remote-control)。

88</Note>88</Note>

89 89

90在 Claude Code CLI 中使用 `/tasks` 檢查進度，或在 claude.ai 或 Claude 行動應用程式上開啟工作階段以直接互動。從那裡，您可以引導 Claude、提供反饋或回答問題，就像任何其他對話一樣。90在 claude.ai 或 Claude 行動應用程式上開啟工作階段以檢查進度或直接互動。從那裡，您可以引導 Claude、提供反饋或回答問題，就像任何其他對話一樣。

91 91

92如果 Claude 提出問題且工作階段閒置，您仍然可以在回來時回答，直到[環境過期](#environment-expired)，工作階段會從您的回答繼續。92如果 Claude 提出問題且工作階段閒置，您仍然可以在回來時回答，直到[環境過期](#environment-expired)，工作階段會從您的回答繼續。

93 93

115claude --cloud "Refactor the logger to use structured output"115claude --cloud "Refactor the logger to use structured output"

116```116```

117 117

118使用 Claude Code CLI 中的 `/tasks` 監控所有工作階段。當工作階段完成時，您可以從網頁介面建立 PR，或[傳送](#from-web-to-terminal)工作階段到終端以繼續工作。118當工作階段完成時，您可以從網頁介面建立 PR，或[傳送](#from-web-to-terminal)工作階段到終端以繼續工作。

119 119

120<h4 id="send-local-repositories-without-github">120<h4 id="send-local-repositories-without-github">

121 發送沒有 GitHub 的本機儲存庫121 發送沒有 GitHub 的本機儲存庫

claude-directory.md +5 −5

Details

1451探索器涵蓋您編寫和編輯的檔案。一些相關檔案位於其他位置：1451探索器涵蓋您編寫和編輯的檔案。一些相關檔案位於其他位置：

1452 1452

1453| 檔案 | 位置 | 用途 |1453| 檔案 | 位置 | 用途 |

1454| ----------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1454| ----------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1455| `managed-settings.json` | 系統級別，因作業系統而異 | 企業強制執行的設定，您無法覆蓋，除了[狹隘的例外](/docs/zh-TW/settings#security-keys-where-the-stricter-value-applies)。請參閱[檔案儲存位置](/docs/zh-TW/managed-settings#deploy-a-managed-settings-file)和[Claude Code 使用的受管來源](/docs/zh-TW/managed-settings#precedence-within-the-managed-tier)。 |1455| `managed-settings.json` | 系統層級，因作業系統而異 | 企業強制執行的設定，您無法覆寫，除了[狹隘的例外](/docs/zh-TW/settings#security-keys-where-the-stricter-value-applies)。請參閱[檔案儲存位置](/docs/zh-TW/managed-settings#deploy-a-managed-settings-file)和[Claude Code 使用的受管來源](/docs/zh-TW/managed-settings#precedence-within-the-managed-tier)。 |

1457| 已安裝的 plugins | `~/.claude/plugins` | 複製的市場、已安裝的 plugin 版本和每個 plugin 的資料，由 `claude plugin` 命令管理。對於從市場[`command` 來源](/docs/zh-TW/plugin-marketplaces#command-sources)以連結模式安裝的 plugin，Claude Code 在此儲存連結而不是副本，plugin 的檔案保留在命令列印的目錄中。請參閱 [plugin 快取](/docs/zh-TW/plugins-reference#plugin-caching-and-file-resolution)以了解孤立版本如何被清理。 |1457| 已安裝的 plugins | `~/.claude/plugins` | 複製的市集、已安裝的 plugin 版本和各 plugin 資料，由 `claude plugin` 命令管理。對於從市集[`command` 來源](/docs/zh-TW/plugin-marketplaces#command-sources)以連結模式安裝的 plugin，Claude Code 在此儲存連結而非副本，plugin 的檔案保留在命令列印的目錄中。`command` 來源需要 Claude Code v2.1.229 或更新版本。請參閱 [plugin 快取](/docs/zh-TW/plugins-reference#plugin-caching-and-file-resolution)以了解孤立版本如何被清理。 |

1458 1458

1459`~/.claude` 還保存 Claude Code 在您工作時寫入的資料：文字記錄、提示歷史記錄、檔案快照、快取和日誌。請參閱下方的[應用程式資料](#application-data)。1459`~/.claude` 也保存 Claude Code 在您工作時寫入的資料：文字記錄、提示歷史記錄、檔案快照、快取和日誌。請參閱下方的[應用程式資料](#application-data)。

1460 1460

1461<h2 id="choose-the-right-file">1461<h2 id="choose-the-right-file">

1462 選擇正確的檔案1462 選擇正確的檔案

cloud-environments.md +5 −8

Details

540<AccordionGroup>540<AccordionGroup>

541 <Accordion title="Anthropic 服務">541 <Accordion title="Anthropic 服務">

542 * api.anthropic.com542 * api.anthropic.com

543 * statsig.anthropic.com

544 * docs.claude.com543 * docs.claude.com

545 * platform.claude.com544 * platform.claude.com

546 * code.claude.com545 * code.claude.com

612 * [www.java.net](http://www.java.net)611 * [www.java.net](http://www.java.net)

613 * download.oracle.com612 * download.oracle.com

614 * yum.oracle.com613 * yum.oracle.com

614 * \*.r2.cloudflarestorage.com

615 </Accordion>615 </Accordion>

616 616

617 <Accordion title="JavaScript 和 Node 套件管理員">617 <Accordion title="JavaScript 和 Node 套件管理員">

622 * npmjs.org622 * npmjs.org

623 * yarnpkg.com623 * yarnpkg.com

624 * registry.yarnpkg.com624 * registry.yarnpkg.com

625 * jsr.io

626 * npm.jsr.io

625 </Accordion>627 </Accordion>

626 628

627 <Accordion title="Python 套件管理員">629 <Accordion title="Python 套件管理員">

676 * central.maven.org678 * central.maven.org

677 * repo1.maven.org679 * repo1.maven.org

678 * repo.maven.apache.org680 * repo.maven.apache.org

681 * maven.google.com

679 * jcenter.bintray.com682 * jcenter.bintray.com

680 * gradle.org683 * gradle.org

681 * [www.gradle.org](http://www.gradle.org)684 * [www.gradle.org](http://www.gradle.org)

682 * services.gradle.org685 * services.gradle.org

683 * plugins.gradle.org686 * plugins.gradle.org

687 * plugins-artifacts.gradle.org

684 * kotlinlang.org688 * kotlinlang.org

685 * [www.kotlinlang.org](http://www.kotlinlang.org)689 * [www.kotlinlang.org](http://www.kotlinlang.org)

686 * spring.io690 * spring.io

758 </Accordion>762 </Accordion>

759 763

760 <Accordion title="雲端服務和監控">764 <Accordion title="雲端服務和監控">

761 * statsig.com

762 * [www.statsig.com](http://www.statsig.com)

763 * api.statsig.com

764 * sentry.io

765 * \*.sentry.io

766 * downloads.sentry-cdn.com

767 * http-intake.logs.datadoghq.com765 * http-intake.logs.datadoghq.com

768 * browser-intake-us5-datadoghq.com

769 * \*.datadoghq.com766 * \*.datadoghq.com

770 * \*.datadoghq.eu767 * \*.datadoghq.eu

771 * api.honeycomb.io768 * api.honeycomb.io

common-workflows.md +1 −1

Details

438 438

439<Tip>439<Tip>

440 為排程任務編寫提示時，明確說明成功是什麼樣子以及如何處理結果。任務自主執行，所以它無法提出澄清問題。例如：「檢查標記為 `needs-review` 的開放 PR，對任何問題留下內聯評論，並在 `#eng-reviews` Slack 頻道中發佈摘要。」440 為排程任務編寫提示時，明確說明成功是什麼樣子以及如何處理結果。任務自主執行，所以它無法提出澄清問題。例如：「檢查標記為 `needs-review` 的開放 PR，對任何問題留下內聯評論，並在 `#eng-reviews` Slack 頻道中發佈摘要。」

computer-use.md +2 −2

Details

112 一次一個工作階段112 一次一個工作階段

113</h3>113</h3>

114 114

115一次只有一個工作階段可以使用您的電腦。工作階段在其第一個電腦使用操作時持有機器範圍的鎖定，並在工作階段退出時釋放它，而不是在任務完成時。第二個工作階段的電腦使用會失敗，並出現一個錯誤，指出持有鎖定的工作階段。先退出該工作階段。115一次只有一個工作階段可以使用您的電腦。工作階段在其第一個電腦使用操作時持有鎖定，並在工作階段退出時釋放它，而不是在任務完成時。第二個工作階段的電腦使用會失敗，並出現一個錯誤，指出持有鎖定的工作階段。先退出該工作階段。

116 116

117<h3 id="apps-are-hidden-while-claude-works">117<h3 id="apps-are-hidden-while-claude-works">

118 Claude 工作時應用程式被隱藏118 Claude 工作時應用程式被隱藏

134 隨時停止134 隨時停止

135</h3>135</h3>

136 136

137當 Claude 獲得鎖定時，會出現 macOS 通知：「Claude 正在使用您的電腦 · 按 Esc 停止」。在任何地方按 `Esc` 立即中止目前操作，或在終端機中按 `Ctrl+C`。無論哪種方式，Claude 都會停止、取消隱藏您的應用程式，並將控制權返回給您。工作階段會保持 [computer use 鎖定](#one-session-at-a-time)，直到它退出。137Claude 在每個輪次中首次使用您的電腦時，會出現 macOS 通知：「Claude 正在使用您的電腦 · 按 Esc 停止」。在任何地方按 `Esc` 立即中止目前操作，或在終端機中按 `Ctrl+C`。無論哪種方式，Claude 都會停止、取消隱藏您的應用程式，並將控制權返回給您。工作階段會保持 [computer use 鎖定](#one-session-at-a-time)，直到它退出。

138 138

139Claude 完成時會出現第二個通知。139Claude 完成時會出現第二個通知。

140 140

costs.md +3 −2

Details

71 71

72按 `d` 或 `w` 在過去 24 小時和過去 7 天之間切換。這些數字是近似值，根據此機器上的本地工作階段歷史記錄計算，因此不包括來自其他裝置或 claude.ai 的使用情況。72按 `d` 或 `w` 在過去 24 小時和過去 7 天之間切換。這些數字是近似值，根據此機器上的本地工作階段歷史記錄計算，因此不包括來自其他裝置或 claude.ai 的使用情況。

73 73

74在 [VS Code 擴充功能](/docs/zh-TW/vs-code#check-account-and-usage)中，歸因份額和行為標記會出現在「帳戶與使用情況」對話框中，並提供「日」和「週」切換，不包括「迴圈」行。需要 Claude Code v2.1.174 或更新版本。74在 [VS Code 擴充功能](/docs/zh-TW/vs-code#check-account-and-usage)中，歸因份額和行為標記會出現在「帳戶與使用情況」對話框中，並提供「日」和「週」切換，不包括「迴圈」行。

75 75

76<h4 id="check-your-usage-credits-spend">76<h4 id="check-your-usage-credits-spend">

77 檢查您的使用額度支出77 檢查您的使用額度支出

222 當開發人員詢問限制時222 當開發人員詢問限制時

223</h3>223</h3>

224 224

225開發人員通常會向其管理員提出限制問題，因此了解他們達到的上限會很有幫助。四種情況意味著不同的事情：225開發人員通常會向其管理員提出限制問題，因此了解他們達到的上限會很有幫助。這些情況意味著不同的事情：

226 226

227* **「您已達到工作階段限制」或「您已達到每週限制」**：訂閱方案上基於座位的使用視窗，在所有模型中共享，因此開發人員無法透過使用 `/model` 切換模型來恢復存取權限。該訊息顯示視窗何時重設。在模型特定的「您已達到 Opus 限制」或「您已達到 Sonnet 限制」訊息之後，使用 `/model` 切換到該系列外的模型確實會讓開發人員繼續工作。請參閱[使用限制錯誤](/docs/zh-TW/errors#youve-hit-your-session-limit)。開發人員在此期間可以做什麼：227* **「您已達到工作階段限制」或「您已達到每週限制」**：訂閱方案上基於座位的使用視窗，在所有模型中共享，因此開發人員無法透過使用 `/model` 切換模型來恢復存取權限。該訊息顯示視窗何時重設。在模型特定的「您已達到 Opus 限制」或「您已達到 Sonnet 限制」訊息之後，使用 `/model` 切換到該系列外的模型確實會讓開發人員繼續工作。請參閱[使用限制錯誤](/docs/zh-TW/errors#youve-hit-your-session-limit)。開發人員在此期間可以做什麼：

228 * 執行 `/usage-credits` 以請求超過額度的使用量，如果您已啟用[使用額度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)。228 * 執行 `/usage-credits` 以請求超過額度的使用量，如果您已啟用[使用額度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)。

229 * 在 Claude Code v2.1.234 或更新版本上，[在重設後自動等待並繼續中斷的任務](/docs/zh-TW/interactive-mode#wait-for-a-usage-limit-to-reset)；該部分列出 Claude Code 何時自行開始等待以及開發人員何時從 `/rate-limit-options` 選擇它。若要控制您的機隊 Claude Code 是否自行開始該等待，請在[受管設定](/docs/zh-TW/settings#settings-precedence)中設定 [`autoContinueAtUsageLimit`](/docs/zh-TW/settings-reference#autocontinueatusagelimit)。229 * 在 Claude Code v2.1.234 或更新版本上，[在重設後自動等待並繼續中斷的任務](/docs/zh-TW/interactive-mode#wait-for-a-usage-limit-to-reset)；該部分列出 Claude Code 何時自行開始等待以及開發人員何時從 `/rate-limit-options` 選擇它。若要控制您的機隊 Claude Code 是否自行開始該等待，請在[受管設定](/docs/zh-TW/settings#settings-precedence)中設定 [`autoContinueAtUsageLimit`](/docs/zh-TW/settings-reference#autocontinueatusagelimit)。

230* **「您已達到個人支出限制」、「組織的每月支出限制」或「團隊的共享預算」**：開發人員的請求將被計費至使用額度，而這些額度已達到您設定的支出限制。若要讓開發人員繼續，請前往[**管理員設定 > 使用**](https://claude.ai/admin-settings/usage)並增加訊息命名的限制。當訊息也命名計畫重設時間時，開發人員可以改為等待直到那時。請參閱[錯誤參考](/docs/zh-TW/errors#youve-hit-your-monthly-spend-limit)以了解每個變體。

230* **來自 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway) 的支出限制訊息**：開發人員超過了您在自託管閘道上設定的支出上限，閘道會阻止他們的請求，直到期間重設或您提高上限。請參閱[閘道支出限制](/docs/zh-TW/claude-apps-gateway-spend-limits)以了解上限、重設時間表和開發人員看到的訊息。231* **來自 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway) 的支出限制訊息**：開發人員超過了您在自託管閘道上設定的支出上限，閘道會阻止他們的請求，直到期間重設或您提高上限。請參閱[閘道支出限制](/docs/zh-TW/claude-apps-gateway-spend-limits)以了解上限、重設時間表和開發人員看到的訊息。

231* **上下文或自動壓縮警告**：不是使用限制。對話已接近工作階段的[自動壓縮視窗](/docs/zh-TW/model-config#set-the-auto-compact-window)，Claude Code 會總結較舊的歷史記錄以釋放空間的閾值。將開發人員指向[減少 token 使用量](#reduce-token-usage)。232* **上下文或自動壓縮警告**：不是使用限制。對話已接近工作階段的[自動壓縮視窗](/docs/zh-TW/model-config#set-the-auto-compact-window)，Claude Code 會總結較舊的歷史記錄以釋放空間的閾值。將開發人員指向[減少 token 使用量](#reduce-token-usage)。

232* **API 或雲端提供者方案上的意外高支出**：通常可追溯到從未清除的長工作階段或留作預設模型的 Opus。分享的最高影響習慣是在不相關的任務之間清除和將模型與工作相匹配，兩者都涵蓋在[減少 token 使用量](#reduce-token-usage)中。233* **API 或雲端提供者方案上的意外高支出**：通常可追溯到從未清除的長工作階段或留作預設模型的 Opus。分享的最高影響習慣是在不相關的任務之間清除和將模型與工作相匹配，兩者都涵蓋在[減少 token 使用量](#reduce-token-usage)中。

desktop-quickstart.md +17 −17

Details

65 選擇 **Local** 以在您的機器上執行 Claude，直接使用您的檔案。點擊 **Select folder** 並選擇您的專案目錄。65 選擇 **Local** 以在您的機器上執行 Claude，直接使用您的檔案。點擊 **Select folder** 並選擇您的專案目錄。

66 66

67 <Tip>67 <Tip>

68 從一個您熟悉的小型專案開始。這是最快看到 Claude Code 能做什麼的方式。在 Windows 上，必須安裝 [Git](https://git-scm.com/downloads/win) 才能讓本機工作階段正常運作。大多數 Mac 預設包含 Git。68 從一個您熟悉的小型專案開始。這是最快看到 Claude Code 能做什麼的方式。

69 </Tip>69 </Tip>

70 70

71 您也可以選擇：71 您也可以選擇：

86 * `Add tests for the main function`86 * `Add tests for the main function`

87 * `Create a CLAUDE.md with instructions for this codebase`87 * `Create a CLAUDE.md with instructions for this codebase`

88 88

89 [session](/docs/zh-TW/desktop#work-in-parallel-with-sessions) 是與 Claude 關於您的程式碼的對話。每個工作階段追蹤其自己的內容和變更，因此您可以在多個任務上工作，而不會相互干擾。89 [session](/docs/zh-TW/desktop#work-in-parallel-with-sessions) 是與 Claude 關於您的程式碼的對話。每個工作階段追蹤其自己的內容和變更。

90 </Step>90 </Step>

91 91

92 <Step title="檢視並接受變更">92 <Step title="檢視並接受變更">

107 接下來呢？107 接下來呢？

108</h2>108</h2>

109 109

110您已經完成了第一次編輯。如需了解 Desktop 的完整功能參考，請參閱 [使用 Claude Code Desktop](/docs/zh-TW/desktop)。以下是一些可以嘗試的事項。110您已經完成了第一次編輯。如需了解 Desktop 的完整功能參考，請參閱[使用 Claude Code Desktop](/docs/zh-TW/desktop)。以下是一些可以嘗試的事項。

111 111

112**中斷並調整方向。** 您可以隨時重新導向 Claude。點擊停止按鈕立即中斷，或輸入更正並按 **Enter** 鍵發送，無需停止正在執行的操作。無論哪種方式，您都不必等待它完成或重新開始。112**中斷並調整方向。** 您可以隨時重新導向 Claude。點擊停止按鈕立即中斷，或輸入更正並按 **Enter** 鍵發送，無需停止執行中的操作。無論哪種方式，您都不必等待它完成或重新開始。

113 113

114**為 Claude 提供更多背景資訊。** 在提示框中輸入 `@filename` 以將特定檔案拉入對話中，使用附件按鈕附加影片和 PDF，或直接將檔案拖放到提示框中。Claude 擁有的背景資訊越多，結果就越好。請參閱 [新增檔案和背景資訊](/docs/zh-TW/desktop#add-files-and-context-to-prompts)。114**為 Claude 提供更多背景資訊。** 在提示框中輸入 `@filename` 以將特定檔案引入對話，使用附件按鈕附加影像和 PDF，或直接將檔案拖放到提示框中。Claude 擁有的背景資訊越多，結果就越好。請參閱[新增檔案和背景資訊至提示](/docs/zh-TW/desktop#add-files-and-context-to-prompts)。

115 115

116**使用 skills 執行可重複的任務。** 輸入 `/` 或點擊 **+** → **Slash commands** 以瀏覽 [內建命令](/docs/zh-TW/commands)、[自訂 skills](/docs/zh-TW/skills) 和外掛程式 skills。Skills 是可重複使用的提示，您可以在需要時隨時調用，例如程式碼審查檢查清單或部署步驟。116**使用 skills 執行可重複的工作。** 輸入 `/` 或點擊 **+** → **Slash commands** 以瀏覽[內建命令](/docs/zh-TW/commands)、[自訂 skills](/docs/zh-TW/skills) 和外掛 skills。Skills 是可重複使用的提示，您可以在需要時隨時叫用，例如程式碼審查檢查清單或部署步驟。

117 117

118**在提交前檢查變更。** Claude 編輯檔案後，會出現 `+12 -1` 指示器。點擊它以開啟 [diff 檢視](/docs/zh-TW/desktop#review-changes-with-diff-view)，逐個檔案檢查修改，並在特定行上留下評論。Claude 會讀取您的評論並進行修訂。點擊 **Review code** 讓 Claude 自行評估 diffs 並留下內嵌建議。118**在提交前檢查變更。** Claude 編輯檔案後，會出現 `+12 -1` 指示器。點擊它以開啟[差異檢視](/docs/zh-TW/desktop#review-changes-with-diff-view)，逐個檔案檢查修改，並在特定行上留下評論。Claude 會讀取您的評論並進行修訂。點擊**檢查程式碼**讓 Claude 自行評估差異並留下內嵌建議。

119 119

120**調整您擁有的控制程度。** 您的 [permission mode](/docs/zh-TW/desktop#choose-a-permission-mode) 設定了 Claude 在不請求批准的情況下可以執行的操作：120**調整您擁有的控制程度。** 您的[權限模式](/docs/zh-TW/desktop#choose-a-permission-mode)設定了 Claude 在不請求批准的情況下可以執行的操作：

121 121

122* **Auto**：分類器在背景中檢查操作，並阻止風險操作，而不是詢問您。122* **自動**：分類器在背景中檢查操作，並阻止有風險的操作，而不是詢問您。

123* **Manual**：Claude 在編輯檔案或執行命令前會詢問。123* **手動**：Claude 在編輯檔案或執行命令前會詢問。

124* **Accept edits**：Claude 自動接受檔案編輯以加快迭代速度。124* **接受編輯**：Claude 自動接受檔案編輯以加快迭代速度。

125* **Plan**：Claude 提出方法而不編輯任何檔案，這在大型重構前很有用。125* **Plan**：Claude 提出方法而不編輯任何檔案，這在大型重構前很有用。

126 126

127**新增外掛程式以獲得更多功能。** 點擊提示框旁的 **+** 按鈕並選擇 **Plugins** 以瀏覽並安裝 [外掛程式](/docs/zh-TW/desktop#install-plugins)，這些外掛程式可新增 skills、agents、MCP 伺服器等。127**新增外掛以獲得更多功能。** 點擊提示框旁的 **+** 按鈕並選擇 **Plugins** 以瀏覽並安裝[外掛](/docs/zh-TW/desktop#install-plugins)，這些外掛可新增 skills、agents、MCP 伺服器等。

128 128

129**整理您的工作區。** 將聊天、diff、終端機、檔案和瀏覽器窗格拖放到您想要的任何版面配置中。使用 **Ctrl+\`** 開啟終端機以在您的工作階段旁執行命令，或點擊檔案路徑以在檔案窗格中開啟它。請參閱 [整理您的工作區](/docs/zh-TW/desktop#arrange-your-workspace)。129**整理您的工作區。** 將聊天、差異、終端機、檔案和瀏覽器窗格拖放到您想要的任何版面配置中。使用 **Ctrl+\`** 開啟終端機以在您的工作階段旁執行命令，或點擊檔案路徑以在檔案窗格中開啟它。請參閱[整理您的工作區](/docs/zh-TW/desktop#arrange-your-workspace)。

130 130

131**預覽您的應用程式。** 當您在 desktop 中執行開發伺服器時，您的應用程式會在瀏覽器窗格中開啟，該窗格也可以 [開啟外部網站](/docs/zh-TW/desktop#browse-external-sites)。Claude 可以檢視執行中的應用程式、測試端點、檢查日誌，並根據所看到的內容進行迭代。請參閱 [預覽您的應用程式](/docs/zh-TW/desktop#preview-your-app)。131**預覽您的應用程式。** 當您在 desktop 中執行開發伺服器時，您的應用程式會在瀏覽器窗格中開啟，該窗格也可以[開啟外部網站](/docs/zh-TW/desktop#browse-external-sites)。Claude 可以檢視執行中的應用程式、測試端點、檢查日誌，並根據所看到的內容進行迭代。請參閱[預覽您的應用程式](/docs/zh-TW/desktop#preview-your-app)。

132 132

133**追蹤您的 pull request。** 開啟 PR 後，Claude Code 會監控 CI 檢查結果，並可在所有檢查通過後自動修復失敗或合併 PR。請參閱 [監控 pull request 狀態](/docs/zh-TW/desktop#monitor-pull-request-status)。133**追蹤您的提取請求。** 開啟 PR 後，Claude Code 會監控 CI 檢查結果，並可在所有檢查通過後自動修復失敗或合併 PR。請參閱[監控提取請求狀態](/docs/zh-TW/desktop#monitor-pull-request-status)。

134 134

135**將 Claude 設定為排程執行。** 設定 [排程任務](/docs/zh-TW/desktop-scheduled-tasks) 以定期自動執行 Claude：每天早上進行程式碼審查、每週進行相依性審計，或提取來自您連接工具的簡報。135**將 Claude 排程執行。** 設定[排程工作](/docs/zh-TW/desktop-scheduled-tasks)以定期自動執行 Claude：每天早上進行程式碼審查、每週進行相依性稽核，或從您連接的工具提取資訊的簡報。

136 136

137**準備好時進行擴展。** 從側邊欄開啟 [平行工作階段](/docs/zh-TW/desktop#work-in-parallel-with-sessions) 以同時處理多個任務，每個任務都在自己的 Git worktree 中，並開啟 [tasks 窗格](/docs/zh-TW/desktop#watch-background-tasks) 以監控工作階段正在執行的子代理和背景命令。開啟 [side chat](/docs/zh-TW/desktop#ask-a-side-question-without-derailing-the-session) 以提出問題而不會偏離主線程。將 [長期執行的工作發送到雲端](/docs/zh-TW/desktop#run-long-running-tasks-remotely)，以便即使您關閉應用程式也能繼續執行，或 [在網路或 IDE 中繼續工作階段](/docs/zh-TW/desktop#continue-in-another-surface)（如果任務花費的時間超過預期）。[連接外部工具](/docs/zh-TW/desktop#extend-claude-code)（如 GitHub、Slack 和 Linear）以整合您的工作流程。137**準備好時進行擴展。** 從側邊欄開啟[平行工作階段](/docs/zh-TW/desktop#work-in-parallel-with-sessions)以同時處理多個工作，可選擇每個工作都在自己的 Git worktree 中，並開啟[工作窗格](/docs/zh-TW/desktop#watch-background-tasks)以監控工作階段正在執行的子代理和背景命令。開啟[側邊聊天](/docs/zh-TW/desktop#ask-a-side-question-without-derailing-the-session)以提出問題而不會偏離主線。將[長期執行的工作發送到雲端](/docs/zh-TW/desktop#run-long-running-tasks-remotely)以便即使您關閉應用程式也能繼續執行，或[在網路或 IDE 中繼續工作階段](/docs/zh-TW/desktop#continue-in-another-surface)（如果工作耗時超過預期）。[連接外部工具](/docs/zh-TW/desktop#extend-claude-code)（例如 GitHub、Slack 和 Linear）以整合您的工作流程。

138 138

139<h2 id="what’s-next">139<h2 id="what’s-next">

140 接下來140 接下來

env-vars.md +1 −0

Details

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

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

478| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | 從 v2.1.161 開始，Claude Code 將 `OTEL_RESOURCE_ATTRIBUTES` 金鑰附加到指標資料點標籤。設定為 `false` 以排除它們（預設值：包含）。請參閱 [監控](/docs/zh-TW/monitoring-usage#multi-team-organization-support) |479| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | 從 v2.1.161 開始，Claude Code 將 `OTEL_RESOURCE_ATTRIBUTES` 金鑰附加到指標資料點標籤。設定為 `false` 以排除它們（預設值：包含）。請參閱 [監控](/docs/zh-TW/monitoring-usage#multi-team-organization-support) |

errors.md +37 −7

Details

21將您看到的訊息與下面的部分進行比對。21將您看到的訊息與下面的部分進行比對。

22 22

23| 訊息 | 部分 |23| 訊息 | 部分 |

24| :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------ |24| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------ |

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

581* 執行 `/usage-credits` 以在 Pro 和 Max 上購買額外使用量，或在 Team 和 Enterprise 上向您的管理員請求。請參閱[付費方案的使用額度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)以了解如何計費。582* 執行 `/usage-credits` 以在 Pro 和 Max 上購買額外使用量，或在 Team 和 Enterprise 上向您的管理員請求。請參閱[付費方案的使用額度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)以了解如何計費。

582* 若要升級您的方案以獲得更高的基本限制，請參閱 [claude.com/pricing](https://claude.com/pricing)583* 若要升級您的方案以獲得更高的基本限制，請參閱 [claude.com/pricing](https://claude.com/pricing)

583 584

584若要在達到限制之前監視您的剩餘額度，請將 `rate_limits` 欄位新增至[自訂狀態行](/docs/zh-TW/statusline#rate-limit-usage)，或在桌面應用程式中按一下模型選擇器旁的[使用量環](/docs/zh-TW/desktop#check-usage)。585在視窗用完之前，Claude Code 可以警告您已使用大部分額度，訊息例如 `You've used 85% of your session limit · resets 3:45pm`。若要持續監視您的剩餘額度，請將 `rate_limits` 欄位新增至[自訂狀態行](/docs/zh-TW/statusline#rate-limit-usage)，或在桌面應用程式中按一下模型選擇器旁的[使用量環](/docs/zh-TW/desktop#check-usage)。

585 586

586<h3 id="usage-credits-required-for-1m-context">587<h3 id="usage-credits-required-for-1m-context">

587 1M 上下文需要使用額度588 1M 上下文需要使用額度

663* 對於 Anthropic API 金鑰，請參閱[速率限制參考](https://platform.claude.com/docs/en/api/rate-limits)以了解層級如何運作以及如何設定每個工作區的上限664* 對於 Anthropic API 金鑰，請參閱[速率限制參考](https://platform.claude.com/docs/en/api/rate-limits)以了解層級如何運作以及如何設定每個工作區的上限

664* 降低並行性：降低 [`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`](/docs/zh-TW/env-vars)、避免執行許多平行子代理，或使用 `/model` 切換到較小的模型以進行高容量指令碼執行665* 降低並行性：降低 [`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`](/docs/zh-TW/env-vars)、避免執行許多平行子代理，或使用 `/model` 切換到較小的模型以進行高容量指令碼執行

665 666

667<h3 id="youve-hit-your-monthly-spend-limit">

668 您已達到每月支出限制

669</h3>

670

671您的方案包含的使用量無法涵蓋此請求，而原本會為其付費的[使用額度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)已達到支出限制。這發生在您的方案的其中一個使用視窗已用完時，或當請求是僅由使用額度支付的請求時，例如對[計費至使用額度](/docs/zh-TW/model-config#fable-and-usage-credits)的模型的請求。訊息會命名哪個限制阻止了您。`·` 後面的文字說明如何提高該限制，並因您的方案和您是否管理計費而異：

672

673```text theme={null}

674You've hit your monthly spend limit · raise it at claude.ai/settings/usage

675You've hit your individual spend limit · ask your admin for a higher limit

676You've hit your org's monthly spend limit · visit claude.ai/admin-settings/usage to raise it

677You've hit your team's shared budget · ask your admin to raise it at claude.ai/admin-settings/usage

678You've hit your channel's monthly spend limit · an org owner or channel manager can raise it in the channel's Claude settings

679```

680

681`team's shared budget` 是管理員分配給您所屬群組的集區預算；訊息不會命名該群組。`channel's monthly spend limit` 是工作階段執行所在的 Slack 頻道的預算，因此您的組織可能在其外仍有預算。

682

683當您的方案的其中一個視窗是用完的視窗時，訊息也會說明該視窗何時重設，例如 `· your session limit resets 3:45pm`，存取會在那時返回，無需任何人提高限制。在具有基於使用量的計費的組織上，訊息會說 `usage limit` 而不是 `spend limit`，如 `You've hit your individual usage limit`。

684

685在 v2.1.239 之前，訊息不會命名方案視窗的重設時間。在 v2.1.268 之前，群組的集區預算產生了 `individual spend limit` 訊息，而不是 `team's shared budget`。

686

687如果您透過 Claude 應用程式閘道連接並看到小寫 `spend limit reached`，那是您的閘道運營商的上限；請參閱[支出限制已達到](#spend-limit-reached)。

688

689**該怎麼做：**

690

691* 在 Pro 和 Max 上，在 claude.ai 的[**設定 > 使用量**](https://claude.ai/settings/usage)中提高您的每月支出限制，或執行 `/usage-credits`

692* 在 Team 和 Enterprise 上，如果您管理計費，請在[**管理設定 > 使用量**](https://claude.ai/admin-settings/usage)中提高限制，或要求管理員提高。`/usage-credits` 會為您向您的管理員發送該請求

693* 對於頻道的限制，要求組織擁有者或頻道的管理員在 claude.ai 上提高它。請參閱 Claude Tag 文件中的[每頻道限制](https://claude.com/docs/claude-tag/admins/set-spend-limit#per-channel-limits)

694* 如果訊息命名您的方案視窗的重設時間，您可以改為等待它

695* 執行 `/usage` 以查看您的方案視窗和每個視窗何時重設

696

666<h3 id="spend-limit-reached">697<h3 id="spend-limit-reached">

667 已達到支出限制698 已達到支出限制

668</h3>699</h3>

1036 1067

1037```text theme={null}1068```text theme={null}

1038OAuth token revoked · Please run /login1069OAuth token revoked · Please run /login

1039OAuth token has expired · Please run /login1070Please run /login · API Error: 401 OAuth token has expired ...

1040API Error: 401 ... authentication_error

1041```1071```

1042 1072

1043**該怎麼做：**1073**該怎麼做：**

1083Failed to authenticate: OAuth session expired and could not be refreshed1113Failed to authenticate: OAuth session expired and could not be refreshed

1084```1114```

1085 1115

1086這與[OAuth 權杖已撤銷或已過期](#oauth-token-revoked-or-expired)的狀態不同。這些訊息報告 API 傳回的 401。Claude Code 本身為已失敗更新的登入產生 `Login expired`，因此它不傳送請求。當更新失敗是因為帳戶本身被暫停而不是登入過時時，Claude Code 會改為顯示[您的帳戶已被暫停](#your-account-is-on-hold)。1116這與[OAuth 權杖已撤銷或已過期](#oauth-token-revoked-or-expired)的狀態不同。這些訊息報告 API 傳回的拒絕。Claude Code 本身為已失敗更新的登入產生 `Login expired`，因此它不傳送請求。當更新失敗是因為帳戶本身被暫停而不是登入過時時，Claude Code 會改為顯示[您的帳戶已被暫停](#your-account-is-on-hold)。

1087 1117

1088使用 API 金鑰、[`CLAUDE_CODE_OAUTH_TOKEN`](/docs/zh-TW/env-vars) 或第三方提供者進行驗證的工作階段不使用已儲存的登入，永遠不會看到此訊息。1118使用 API 金鑰、[`CLAUDE_CODE_OAUTH_TOKEN`](/docs/zh-TW/env-vars) 或第三方提供者進行驗證的工作階段不使用已儲存的登入，永遠不會看到此訊息。

1089 1119

1725Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.1755Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.

1726```1756```

1727 1757

1728當您超過的限制是小於模型上下文視窗的壓縮視窗（例如 1M 上下文模型上的 200K 邊界）時，警告讀取方式不同。請求在壓縮視窗之外仍然成功；執行命名的命令以將使用量帶回其下方。1758當您超過的限制是小於模型上下文視窗的壓縮視窗（例如 1M 上下文模型上的 200K 邊界）時，警告讀取方式不同。壓縮視窗可以位於模型的上下文視窗下方，因此在其之外的請求仍然可以成功。

1729 1759

1730```text theme={null}1760```text theme={null}

1731Context is 94k tokens past the 200k-token compaction window — run /compact to reduce usage.1761Context is 94k tokens past the 200k-token compaction window — run /compact to reduce usage.

3054`claude plugin install` 報告拒絕如下：3084`claude plugin install` 報告拒絕如下：

3055 3085

3056```text theme={null}3086```text theme={null}

3057Cannot install my-plugin@my-marketplace: its marketplace entry path does not stay inside the marketplace directory (an absolute, climbing, network-shaped or link-traversing entry, an entry of a fetched marketplace that resolves outside its tree — or a relative entry in a url-catalog marketplace, which has no local directory)3087Cannot install my-plugin@my-marketplace: its marketplace entry path does not stay inside the marketplace directory (an absolute, climbing, network-shaped, backslash-containing or link-traversing entry, an entry of a fetched marketplace that resolves or opens outside its tree — or a relative entry in a url-catalog marketplace, which has no local directory)

3058```3088```

3059 3089

3060當已安裝的 plugin 的項目失敗相同的檢查時，`claude plugin list` 將 plugin 顯示為 `failed to load`，並顯示：3090當已安裝的 plugin 的項目失敗相同的檢查時，`claude plugin list` 將 plugin 顯示為 `failed to load`，並顯示：

fast-mode.md +28 −28

Details

117您可以結合兩者：在直接任務上使用快速模式搭配較低的[努力等級](/docs/zh-TW/model-config#adjust-effort-level)以獲得最大速度。117您可以結合兩者：在直接任務上使用快速模式搭配較低的[努力等級](/docs/zh-TW/model-config#adjust-effort-level)以獲得最大速度。

118 118

119<h2 id="requirements">119<h2 id="requirements">

120 要求120 需求

121</h2>121</h2>

122 122

123快速模式需要以下所有條件：123快速模式需要以下所有條件：

124 124

125* **僅限 Anthropic API 或訂閱**：快速模式可透過 Anthropic Console API 和使用額度的 Claude 訂閱方案取得。它在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 AWS 上的 Claude Platform 上不可用。Console 組織也必須[啟用快速模式](#enable-fast-mode-for-your-organization)。125* **僅限 Anthropic API 或訂閱**：快速模式可透過 Anthropic Console API 和使用額度的 Claude 訂閱方案取得。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 AWS 上的 Claude Platform 上無法使用。Console 組織還必須[為您的組織佈建快速模式存取](#enable-fast-mode-for-your-organization)。

126* **訂閱方案啟用使用額度**：在 Pro、Max、Team 或 Enterprise 方案上，您的帳戶必須[啟用使用額度](/docs/zh-TW/costs#add-usage-credits-to-your-subscription)，這允許超出您方案包含使用量的計費。在啟用之前，`/fast` 會顯示「Fast mode requires usage credits · /usage-credits to turn them on」。您啟用它們的方式取決於您的方案：126* **為訂閱方案開啟使用額度**：在 Pro、Max、Team 或 Enterprise 方案上，您的帳戶必須[開啟使用額度](/docs/zh-TW/costs#add-usage-credits-to-your-subscription)，這允許超出您方案包含使用量的計費。在開啟之前，`/fast` 會報告「快速模式需要使用額度」。您開啟它們的方式取決於您的方案：

127 * 在 Pro 和 Max 上，在 claude.ai 上的 [**Settings > Usage**](https://claude.ai/settings/usage) 中的 **Usage credits** 部分啟用它們，或執行 `/usage-credits` 以開啟該頁面。127 * 在 Pro 和 Max 上，在 claude.ai 上的 [**設定 > 使用量**](https://claude.ai/settings/usage) 的 **使用額度** 部分開啟它們，或執行 `/usage-credits` 以開啟該頁面。

128 * 在 Team 和 Enterprise 上，具有計費存取權限的成員在 [**Admin settings > Usage**](https://claude.ai/admin-settings/usage) 中為組織啟用它們，沒有計費存取權限的成員執行 `/usage-credits` 以向組織的管理員發送請求。128 * 在 Team 和 Enterprise 上，具有計費存取權限的成員在 [**管理設定 > 使用量**](https://claude.ai/admin-settings/usage) 為組織開啟它們，沒有存取權限的成員執行 `/usage-credits` 以向組織的管理員發送請求。

129 129

130<Note>130<Note>

131 快速模式使用直接計費到使用額度，即使您的方案上還有剩餘使用量。131 快速模式使用量直接從使用額度中扣除，即使您在方案上還有剩餘使用量。

132</Note>132</Note>

133 133

134* **付費 Console 組織**：Claude Console 帳戶不使用使用額度，您的組織按 token 為快速模式付費，與其餘 API 使用量一起。在 Console 的免費 Evaluation 方案上，`/fast` 會顯示「Fast mode unavailable during evaluation. Please purchase credits.」若要清除它，在您的 [Console 計費設定](https://platform.claude.com/settings/billing)中購買額度。134* **付費 Console 組織**：Claude Console 帳戶不使用使用額度，您的組織按令牌為快速模式付費，與其餘 API 使用量一起。在 Console 的免費評估方案上，`/fast` 顯示「評估期間快速模式不可用。請購買額度。」若要清除它，請在您的 [Console 計費設定](https://platform.claude.com/settings/billing)中購買額度。

135* **Team 和 Enterprise 的管理員啟用**：快速模式預設對 Team 和 Enterprise 組織禁用。管理員必須明確[啟用快速模式](#enable-fast-mode-for-your-organization)，使用者才能存取它。135* **Team 和 Enterprise 的擁有者啟用**：快速模式在預設情況下對 Team 和 Enterprise 組織停用。擁有者必須明確[啟用快速模式](#enable-fast-mode-for-your-organization)，使用者才能存取它。

136 136

137<Note>137<Note>

138 如果您的管理員尚未為您的組織啟用快速模式，`/fast` 命令將顯示「Fast mode has been disabled by your organization.」如果您組織的 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection) 允許清單排除了快速模式 Opus 模型，`/fast` 會被拒絕，顯示「is not in your organization's allowed models」。例外情況是已在允許的 Opus 模型上執行的工作階段，該模型支援快速模式：`/fast` 則在您目前的模型上啟用快速模式，而不是切換模型。138 如果尚未為您的組織啟用快速模式，`/fast` 命令將顯示「快速模式已被您的組織停用。」如果您組織的 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection) 允許清單排除快速模式 Opus 模型，`/fast` 會被拒絕，顯示「不在您組織的允許模型中」。例外是已在支援快速模式的允許 Opus 模型上執行的工作階段：`/fast` 在您目前的模型上啟用快速模式，而不是切換模型。

139</Note>139</Note>

140 140

141<h3 id="enable-fast-mode-for-your-organization">141<h3 id="enable-fast-mode-for-your-organization">

142 為您的組織啟用快速模式142 為您的組織啟用快速模式

143</h3>143</h3>

144 144

145您啟用快速模式的位置取決於您的組織使用的產品：145您啟用快速模式的位置取決於您的組織使用哪個產品：

146 146

147* **Console**（API 客戶）：管理員在 [Claude Code preferences](https://platform.claude.com/claude-code/preferences) 中啟用它。快速模式處於[研究預覽](#research-preview)中，因此您的組織必須先啟用快速模式存取權限，快速模式請求才能成功。若要取得存取權限，請聯絡您的帳戶經理或加入等候清單，如 [Claude API 上的快速模式](https://platform.claude.com/docs/en/build-with-claude/fast-mode)中所述。147* **Console**（API 客戶）：管理員在 [Claude Code 偏好設定](https://platform.claude.com/claude-code/preferences)中啟用它。快速模式處於[研究預覽](#research-preview)中，因此您的組織還必須在快速模式請求成功之前佈建快速模式存取。若要取得存取權，請聯絡您的帳戶經理或加入等候清單，如 [Claude API 上的快速模式](https://platform.claude.com/docs/en/build-with-claude/fast-mode)中所述。

148 148

149 沒有佈建的存取權限，API 會以 429 拒絕每個快速模式請求，Claude Code 會將每個拒絕視為[快速模式速率限制](#handle-rate-limits)。與速率限制的冷卻時間不同，拒絕會持續到存取權限被佈建為止。149 沒有佈建的存取權，API 會以 429 拒絕每個快速模式請求，Claude Code 會將每個拒絕視為[快速模式速率限制](#handle-rate-limits)。與速率限制的冷卻時間不同，拒絕會持續到佈建存取權為止。

150* **Claude AI**（Team 和 Enterprise）：管理員在 [管理員設定 > Claude Code](https://claude.ai/admin-settings/claude-code)中啟用它150* **Claude AI**（Team 和 Enterprise）：擁有者在 [管理設定 > Claude Code](https://claude.ai/admin-settings/claude-code) 啟用它

151 151

152另一個完全禁用快速模式的選項是設定 `CLAUDE_CODE_DISABLE_FAST_MODE=1`。詳見[環境變數](/docs/zh-TW/env-vars)。152另一個完全停用快速模式的選項是設定 `CLAUDE_CODE_DISABLE_FAST_MODE=1`。請參閱[環境變數](/docs/zh-TW/env-vars)。

153 153

154<h3 id="use-fast-mode-behind-proxies-and-llm-gateways">154<h3 id="use-fast-mode-behind-proxies-and-llm-gateways">

155 在代理和 LLM 閘道後面使用快速模式155 在代理和 LLM 閘道後面使用快速模式

156</h3>156</h3>

157 157

158在提供快速模式之前，Claude Code 會透過直接請求 `api.anthropic.com` 來檢查您組織的快速模式可用性。該檢查不遵循 [`ANTHROPIC_BASE_URL`](/docs/zh-TW/llm-gateway-connect#set-the-base-url-and-credential)，因此在透過 [LLM 閘道](/docs/zh-TW/llm-gateway)路由 Claude 流量並阻止直接出站到 `api.anthropic.com` 的網路上，即使推理請求有效，檢查也會失敗。該檢查確實使用已設定的 [HTTP 代理](/docs/zh-TW/network-config#proxy-configuration)，因此網路阻止只在 `api.anthropic.com` 即使透過代理也無法到達的地方才會導致檢查失敗。158在提供快速模式之前，Claude Code 會透過直接向 `api.anthropic.com` 的請求檢查您組織的快速模式可用性。該檢查不遵循 [`ANTHROPIC_BASE_URL`](/docs/zh-TW/llm-gateway-connect#set-the-base-url-and-credential)，因此在將 Claude 流量路由透過 [LLM 閘道](/docs/zh-TW/llm-gateway)並阻止直接出口到 `api.anthropic.com` 的網路上，即使推理請求有效，檢查也會失敗。該檢查確實使用已設定的 [HTTP 代理](/docs/zh-TW/network-config#proxy-configuration)，因此網路阻止只在 `api.anthropic.com` 即使透過代理也無法到達的地方才會使檢查失敗。

159 159

160當檢查失敗時，`/fast` 報告「Fast mode unavailable due to network connectivity issues」，請求以標準速度執行，即使您的組織已啟用快速模式。過去成功的檢查會從其快取結果繼續工作，因此被阻止的檢查主要影響新安裝。160當檢查失敗時，`/fast` 報告「由於網路連線問題，快速模式不可用」，請求以標準速度執行，即使您的組織已啟用快速模式。過去成功的檢查會從其快取結果繼續工作，因此被阻止的檢查主要影響新安裝。

161 161

162當檢查到達 `api.anthropic.com` 但呈現 Anthropic 拒絕的認證時，開放網路上也會出現相同的連線訊息。其解析的金鑰是閘道發行的認證的工作階段，保存在 [`ANTHROPIC_API_KEY`](/docs/zh-TW/llm-gateway-connect#set-the-base-url-and-credential) 中或由 [`apiKeyHelper`](/docs/zh-TW/settings-reference#apikeyhelper) 產生，會使用該金鑰發送檢查，被拒絕的請求會報告為連線失敗。162當檢查到達 `api.anthropic.com` 但呈現 Anthropic 拒絕的認證時，開放網路上也會出現相同的連線訊息。其解析金鑰是閘道發行的認證的工作階段，保存在 [`ANTHROPIC_API_KEY`](/docs/zh-TW/llm-gateway-connect#set-the-base-url-and-credential) 中或由 [`apiKeyHelper`](/docs/zh-TW/settings-reference#apikeyhelper) 產生，會使用該金鑰發送檢查，被拒絕的請求會報告為連線失敗。

163 163

164若要還原快速模式，在網路阻止是原因的地方允許直接出站到 `api.anthropic.com`，或設定與檢查失敗方式相符的任何變數：164若要復原快速模式，在網路阻止是原因的地方允許直接出口到 `api.anthropic.com`，或設定與檢查失敗方式相符的任何變數：

165 165

166* `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS=1` 將失敗的檢查視為可用，並仍然遵守「disabled by your organization」回應。當您的網路拒絕連線，或當 Anthropic 拒絕閘道認證時使用它；允許清單不會幫助認證情況，因為沒有任何東西被阻止。166* `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS=1` 將失敗的檢查視為可用，並仍然遵守「已被您的組織停用」的回應。當您的網路拒絕連線，或當 Anthropic 拒絕閘道認證時使用它；允許清單無法幫助認證情況，因為沒有任何東西被阻止。

167* `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK=1` 完全跳過檢查。當您的網路攔截請求而不是拒絕它時使用它。167* `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK=1` 完全跳過檢查。當您的網路攔截請求而不是拒絕它時使用它。

168 168

169兩個閘道設定報告「Fast mode has been disabled by your organization」而不是連線訊息，即使您的組織已啟用快速模式：169兩個閘道配置報告「快速模式已被您的組織停用」而不是連線訊息，即使您的組織已啟用快速模式：

170 170

171* 僅使用 [`ANTHROPIC_AUTH_TOKEN`](/docs/zh-TW/llm-gateway-connect#set-the-base-url-and-credential) 進行驗證的工作階段會跳過檢查：沒有 claude.ai 登入或 Anthropic API 金鑰，以及沒有快取的成功檢查，Claude Code 會將快速模式視為由您的組織禁用，而不發送請求。171* 僅使用 [`ANTHROPIC_AUTH_TOKEN`](/docs/zh-TW/llm-gateway-connect#set-the-base-url-and-credential) 進行驗證的工作階段會跳過檢查：沒有 claude.ai 登入或 Anthropic API 金鑰，以及沒有快取的成功檢查，Claude Code 會將快速模式視為由您的組織停用，而不發送請求。

172* 攔截檢查並用自己的頁面回答的代理，例如傳回 HTTP 200 阻止頁面的 TLS 檢查代理，被讀取為您的組織已禁用快速模式的回應。172* 攔截檢查並用自己的頁面回答的代理，例如傳回 HTTP 200 阻止頁面的 TLS 檢查代理，被讀取為回應，表示您的組織已停用快速模式。

173 173

174在這兩種情況下，設定 `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK=1` 以還原快速模式。`CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS` 不適用於任何一種情況，因為它只繞過失敗的檢查，而這兩種都會產生禁用回應。允許清單不會幫助持有人令牌情況，它永遠不會發送請求。174在這兩種情況下，設定 `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK=1` 以復原快速模式。`CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS` 不適用於任何一種情況，因為它只繞過失敗的檢查，而這兩種都會產生停用回應。允許清單直接出口無法幫助持有人令牌情況，它永遠不會發送請求。

175 175

176這些變數只影響用戶端檢查。當您的組織已禁用快速模式時，API 會拒絕快速模式請求，無論是否設定了它們。176這些變數只影響用戶端檢查。當您的組織已停用快速模式時，API 會拒絕快速模式請求，無論是否設定了它們。

177 177

178設定 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 也會抑制可用性檢查。沒有先前快取的成功檢查，`/fast` 報告「Fast mode is currently unavailable」；兩個跳過變數在該設定中也會還原快速模式。178設定 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 也會抑制可用性檢查。沒有先前快取的成功檢查，`/fast` 報告「快速模式目前不可用」；兩個跳過變數在該配置中也會復原快速模式。

179 179

180<h3 id="require-per-session-opt-in">180<h3 id="require-per-session-opt-in">

181 要求每個工作階段選擇加入181 需要每個工作階段的選擇加入

182</h3>182</h3>

183 183

184預設情況下，使用者在互動式工作階段中啟用的快速模式會在工作階段之間保持。若要變更此行為，在任何[設定檔](/docs/zh-TW/settings#where-settings-live)中將 `fastModePerSessionOptIn` 設定為 `true`，這會導致每個工作階段以快速模式關閉開始，並要求使用者使用 `/fast` 明確啟用它。[Team](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_teams#team-&-enterprise) 或 [Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_enterprise) 方案上的擁有者可以透過[伺服器受管設定](/docs/zh-TW/server-managed-settings)在組織範圍內部署它。184預設情況下，使用者在互動式工作階段中開啟的快速模式會在工作階段之間持續。若要變更此設定，請在任何[設定檔](/docs/zh-TW/settings#where-settings-live)中將 `fastModePerSessionOptIn` 設定為 `true`，這會導致每個工作階段以快速模式關閉開始，並要求使用者使用 `/fast` 明確啟用它。[Team](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_teams#team-&-enterprise) 或 [Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_enterprise) 方案上的擁有者可以透過[伺服器管理的設定](/docs/zh-TW/server-managed-settings)在整個組織範圍內部署它。

185 185

186```json theme={null}186```json theme={null}

187{187{

189}189}

190```190```

191 191

192這對於控制執行多個並行工作階段的使用者的組織成本很有用。使用者的快速模式偏好設定仍會保存，因此移除此設定會還原預設的持久行為。192這對於在使用者執行多個並行工作階段的組織中控制成本很有用。使用者的快速模式偏好設定仍會被保存，因此移除此設定會復原預設的持續行為。

193 193

194<h2 id="handle-rate-limits">194<h2 id="handle-rate-limits">

195 處理速率限制195 處理速率限制

github-enterprise-server.md +1 −1

Details

116claude --cloud "Add retry logic to the payment webhook handler"116claude --cloud "Add retry logic to the payment webhook handler"

117```117```

118 118

119工作階段會從 GHES 複製您的儲存庫，並將變更推送回分支。使用 `/tasks` 或在 [claude.ai/code](https://claude.ai/code) 監控進度。請參閱 [Claude Code on the web](/docs/zh-TW/claude-code-on-the-web) 以了解完整的雲端工作階段工作流程，包括差異檢閱、自動修復和例行程序。119工作階段會從 GHES 複製您的儲存庫，並將變更推送回分支。在 [claude.ai/code](https://claude.ai/code) 監控進度。請參閱 [Claude Code on the web](/docs/zh-TW/claude-code-on-the-web) 以了解完整的雲端工作階段工作流程，包括差異檢閱、自動修復和例行程序。

120 120

121<h3 id="teleport-sessions-to-your-terminal">121<h3 id="teleport-sessions-to-your-terminal">

122 將 Teleport 工作階段傳送到您的終端機122 將 Teleport 工作階段傳送到您的終端機

goal.md +23 −6

Details

22三種方法在提示之間保持目前工作階段執行。根據應該開始下一個回合的內容進行選擇：22三種方法在提示之間保持目前工作階段執行。根據應該開始下一個回合的內容進行選擇：

23 23

24| 方法 | 下一個回合開始於 | 停止於 |24| 方法 | 下一個回合開始於 | 停止於 |

25| :--------------------------------------------------------------------- | :----------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------- |25| :--------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------- |

26| `/goal` | 上一個回合完成時，或在背景工作保持目標等待期間有[閒置檢查](#background-work-defers-evaluation)到期，每個目標在你的提示之間最多三次 | 模型確認條件已滿足或判斷其不可能時，或回合因[你必須修復的錯誤](#errors-you-have-to-fix-clear-the-goal)而失敗時，或你執行[`/goal clear`](#clear-a-goal)時 |26| `/goal` | 上一個回合完成時，或在互動式工作階段中，[閒置檢查](#background-work-defers-evaluation)或[自動重試](#other-errors-retry-or-pause-the-goal)到期時 | 模型確認條件已滿足或判斷其不可能時，或回合因[你必須修復的錯誤](#errors-you-have-to-fix-clear-the-goal)而失敗時，或你執行[`/goal clear`](#clear-a-goal)時 |

29 29

143 143

144如果 Claude 持續回答評估器而沒有取得進展（連續多個回合沒有工具使用），Claude Code 會停止迴圈、列印警告，並將控制權返回給你，目標仍然設定。評估在你的下一個提示後繼續。[hooks 指南](/docs/zh-TW/hooks-guide#stop-hook-hits-the-block-cap)解釋了底層機制。144如果 Claude 持續回答評估器而沒有取得進展（連續多個回合沒有工具使用），Claude Code 會停止迴圈、列印警告，並將控制權返回給你，目標仍然設定。評估在你的下一個提示後繼續。[hooks 指南](/docs/zh-TW/hooks-guide#stop-hook-hits-the-block-cap)解釋了底層機制。

145 145

146<h3 id="errors-you-have-to-fix-clear-the-goal">146<h3 id="when-a-turn-fails">

147 你必須修復的錯誤會清除目標147 當回合失敗時

148</h3>148</h3>

149 149

150當回合失敗時，如果錯誤是你必須修復的錯誤，Claude Code 會清除目標。在任何其他錯誤之後，目標保持設定。

151

152<h4 id="errors-you-have-to-fix-clear-the-goal">

153 你必須修復的錯誤會清除目標

154</h4>

155

150如果回合因無法清除的錯誤而失敗，Claude Code 會清除目標並列印警告，說明原因。警告以 `Goal cleared after an unrecoverable error` 開始，以 `Run /goal again to continue` 結束。修復原因，然後使用 `/goal <condition>` [再次設定目標](#set-a-goal)。四種失敗會清除目標：156如果回合因無法清除的錯誤而失敗，Claude Code 會清除目標並列印警告，說明原因。警告以 `Goal cleared after an unrecoverable error` 開始，以 `Run /goal again to continue` 結束。修復原因，然後使用 `/goal <condition>` [再次設定目標](#set-a-goal)。四種失敗會清除目標：

151 157

152* 驗證失敗，當 Claude Code 管理自己的認證時。當主機為你管理認證時，例如桌面應用程式、VS Code 擴充功能或[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)，Claude Code 會保持目標活躍，因為主機會自動恢復存取權。158* 驗證失敗，當 Claude Code 管理自己的認證時。當主機為你管理認證時，例如桌面應用程式、VS Code 擴充功能或[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)，Claude Code 會保持目標活躍，因為主機會自動恢復存取權。

154* [自動壓縮](/docs/zh-TW/model-config#set-the-auto-compact-window)無法清除的內容溢位160* [自動壓縮](/docs/zh-TW/model-config#set-the-auto-compact-window)無法清除的內容溢位

155* 不可用的模型161* 不可用的模型

156 162

157在任何其他失敗之後，包括速率限制和伺服器過載等暫時性錯誤，Claude Code 會保持目標活躍。163<h4 id="other-errors-retry-or-pause-the-goal">

164 其他錯誤重試或暫停目標

165</h4>

166

167在任何其他失敗之後，目標保持設定。在 Claude Code v2.1.269 或更新版本的互動式工作階段中，Claude Code 也會列印一行命名原因，並自動重試或等待你：

168

169* **重試**：在傾向於自行清除的失敗之後，例如伺服器過載或連線中斷，以 `Goal still active` 開始的通知會顯示下一次嘗試前的等待時間。在三次自動重試後，目標會改為暫停。

170* **暫停**：在重試只會重複的失敗之後，例如 API 速率限制、claude.ai [使用限制](/docs/zh-TW/errors#youve-hit-your-session-limit)或結束回合的 hook，以 `Goal paused` 開始的通知會命名原因。如果工作階段[等待在使用限制重設時自動繼續](/docs/zh-TW/interactive-mode#wait-for-a-usage-limit-to-reset)，Claude 會在那時繼續朝著目標努力。

171

172隨時發送訊息以立即開始下一個回合。要關閉自動重試，請將 [`CLAUDE_CODE_GOAL_CHECKIN_MINUTES`](/docs/zh-TW/env-vars) 設定為 `0`，這也會關閉[簽到](#background-work-defers-evaluation)。

158 173

159<h3 id="background-work-defers-evaluation">174<h3 id="background-work-defers-evaluation">

160 背景工作延遲評估175 背景工作延遲評估

169 184

170在 v2.1.239 之前，只有閒置簽到以這種方式退避；在回合結束時傳遞的簽到在第一個間隔重複。185在 v2.1.239 之前，只有閒置簽到以這種方式退避；在回合結束時傳遞的簽到在第一個間隔重複。

171 186

172要更改第一個間隔，請設定 [`CLAUDE_CODE_GOAL_CHECKIN_MINUTES`](/docs/zh-TW/env-vars)。Claude Code 使用你的值代替 30 分鐘間隔，並相應地縮放後續間隔。將其設定為 `0` 以關閉簽到。簽到需要 Claude Code v2.1.234 或更新版本。187要更改第一個間隔，請設定 [`CLAUDE_CODE_GOAL_CHECKIN_MINUTES`](/docs/zh-TW/env-vars)。Claude Code 使用你的值代替 30 分鐘間隔，並相應地縮放後續間隔。將其設定為 `0` 以關閉簽到和[自動重試](#other-errors-retry-or-pause-the-goal)。

188

189簽到需要 Claude Code v2.1.234 或更新版本。

173 190

174<h3 id="evaluation-model-and-cost">191<h3 id="evaluation-model-and-cost">

175 評估模型和成本192 評估模型和成本

how-claude-code-works.md +1 −1

Details

211 211

212內建命令也會引導您完成設定：212內建命令也會引導您完成設定：

213 213

214* `/init` 引導您為您的專案建立 CLAUDE.md214* `/init` 為您的專案產生一個入門 CLAUDE.md

215* `/doctor` 執行設定檢查，診斷安裝和配置問題，並可以修復它們215* `/doctor` 執行設定檢查，診斷安裝和配置問題，並可以修復它們

216 216

217<h3 id="it’s-a-conversation">217<h3 id="it’s-a-conversation">

jetbrains.md +2 −2

Details

256**向模型公開的工具。** 伺服器裝載多個工具，但只有一個對模型可見。其餘的是 CLI 用於自己的 UI 的內部 RPC，例如開啟差異和讀取選擇，並在工具清單到達 Claude 之前被篩選出來。256**向模型公開的工具。** 伺服器裝載多個工具，但只有一個對模型可見。其餘的是 CLI 用於自己的 UI 的內部 RPC，例如開啟差異和讀取選擇，並在工具清單到達 Claude 之前被篩選出來。

257 257

258| 工具名稱（如 hooks 所見） | 它的作用 | 唯讀 |258| 工具名稱（如 hooks 所見） | 它的作用 | 唯讀 |

259| -------------------------- | ---------------------------------------- | -- |259| -------------------------- | ---------------------------------------------------------------------------------- | -- |

260| `mcp__ide__getDiagnostics` | 傳回 IDE 的檢查診斷，即編輯器中顯示的錯誤和警告。可選擇性地限定於一個檔案。 | 是 |260| `mcp__ide__getDiagnostics` | 傳回 IDE 的檢查診斷，即編輯器中顯示的錯誤和警告。每次呼叫涵蓋一個檔案：Claude 指定的檔案，或如果 Claude 未指定檔案，則為您的活動編輯器中的檔案。 | 是 |

261 261

262JetBrains 外掛程式不會向模型公開程式碼執行工具。262JetBrains 外掛程式不會向模型公開程式碼執行工具。

263 263

large-codebases.md +2 −2

Details

385 保持技能可發現385 保持技能可發現

386</h3>386</h3>

387 387

388隨著技能分散在許多目錄中，Claude 選擇的清單可能會增長很大。Claude 通過讀取每個發現的技能的名稱和描述來選擇技能，只有選定技能的完整內容載入上下文。本部分涵蓋如何保持該清單較小並編寫在縮短時倖存的描述。388隨著技能分散在許多目錄中，Claude 選擇的清單可能會增長很大。Claude 通過讀取每個發現的技能的名稱和描述來選擇技能，只有選定技能的完整內容載入上下文。本部分涵蓋如何保持該清單較小。

389 389

390哪些技能在範圍內取決於您從何處啟動 Claude：390哪些技能在範圍內取決於您從何處啟動 Claude：

391 391

393* **從儲存庫根目錄**：根目錄技能，加上來自 Claude 在工作階段期間接觸的每個子目錄的技能，可能累積到數百個393* **從儲存庫根目錄**：根目錄技能，加上來自 Claude 在工作階段期間接觸的每個子目錄的技能，可能累積到數百個

394* **在使用 [`--add-dir`](#grant-access-across-packages-or-repositories) 添加同級後**：該同級的技能也會載入。`additionalDirectories` 設定僅授予檔案存取權限，不載入技能394* **在使用 [`--add-dir`](#grant-access-across-packages-or-repositories) 添加同級後**：該同級的技能也會載入。`additionalDirectories` 設定僅授予檔案存取權限，不載入技能

395 395

396名稱始終載入，但[當有許多時描述會被縮短](/docs/zh-TW/skills#skill-descriptions-are-cut-short)，這可能會剝離 Claude 用來決定技能是否適用的關鍵字。保持描述簡短並以請求會包含的詞語開頭，例如「在 `packages/api/` 中編寫或修改測試」。396名稱始終載入，但[當有許多時，某些技能會完全失去其描述](/docs/zh-TW/skills#skill-descriptions-are-cut-short)，這可能會剝離 Claude 用來決定技能是否適用的關鍵字。保持描述簡短並以請求會包含的詞語開頭，例如「在 `packages/api/` 中編寫或修改測試」。

397 397

398對於許多目錄共享的技能，例如 PR 約定或部署檢查清單，請將它們放在儲存庫根目錄的 `.claude/skills/` 中，以便從任何啟動目錄載入。當共享技能需要自己的版本歷史或必須跨儲存庫工作時，請改為將它們打包為[外掛](/docs/zh-TW/plugins)。外掛技能使用 `plugin-name:skill-name` 命名空間，因此它們永遠不會與按目錄的技能衝突。平台團隊可以在一個地方對其進行版本化和更新。398對於許多目錄共享的技能，例如 PR 約定或部署檢查清單，請將它們放在儲存庫根目錄的 `.claude/skills/` 中，以便從任何啟動目錄載入。當共享技能需要自己的版本歷史或必須跨儲存庫工作時，請改為將它們打包為[外掛](/docs/zh-TW/plugins)。外掛技能使用 `plugin-name:skill-name` 命名空間，因此它們永遠不會與按目錄的技能衝突。平台團隊可以在一個地方對其進行版本化和更新。

399 399

monitoring-usage.md +318 −293

Details

150以下環境變數控制指標中包含哪些屬性以管理基數：150以下環境變數控制指標中包含哪些屬性以管理基數：

151 151

152| 環境變數 | 描述 | 預設值 | 停用範例 |152| 環境變數 | 描述 | 預設值 | 停用範例 |

153| ------------------------------------------ | ----------------------------------------------- | ------- | ------- |153| ------------------------------------------ | --------------------------------------------------------------------------------- | ------- | ------- |

159 160

160較低的基數通常意味著更好的效能和更低的儲存成本，但分析的資料粒度較低。161較低的基數通常意味著更好的效能和更低的儲存成本，但分析的資料粒度較低。

161 162

390* 建立團隊特定的儀表板391* 建立團隊特定的儀表板

391* 為特定團隊設定警報392* 為特定團隊設定警報

392 393

393Claude Code 將這些值作為屬性附加到每個指標資料點和事件記錄上，除了在 OTLP 資源區塊中傳送它們之外。因為大多數指標後端將資料點屬性公開為可查詢的標籤，您可以直接按自訂鍵分組和篩選指標。自訂鍵永遠不會覆蓋[標準屬性](#standard-attributes)，例如 `user.id` 或 `session.id`：當鍵衝突時，Claude Code 保留內建值。394Claude Code 將這些值作為屬性附加到每個指標資料點和事件記錄上，除了在 OTLP 資源區塊中傳送它們之外。因為大多數指標後端將資料點屬性公開為可查詢的標籤，您可以直接按自訂鍵分組和篩選指標。除了 `vcs.*` [儲存庫屬性](#repository-attributes)外，自訂鍵永遠不會覆蓋[標準屬性](#standard-attributes)，例如 `user.id` 或 `session.id`：當鍵衝突時，Claude Code 保留內建值。

394 395

395每個自訂鍵都會成為每個指標序列上的標籤，因此高基數值會增加指標後端中的儲存成本。若要僅在資源區塊中傳送自訂屬性並從資料點標籤中省略它們，請設定 `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES=false`。請參閱[指標基數控制](#metrics-cardinality-control)。396每個自訂鍵都會成為每個指標序列上的標籤，因此高基數值會增加指標後端中的儲存成本。若要僅在資源區塊中傳送自訂屬性並從資料點標籤中省略它們，請設定 `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES=false`。請參閱[指標基數控制](#metrics-cardinality-control)。

396 397

496 標準屬性497 標準屬性

497</h3>498</h3>

498 499

499所有指標和事件共享這些標準屬性：500所有指標和事件都共享這些標準屬性：

500 501

501| 屬性 | 描述 | 控制者 |502| 屬性 | 描述 | 控制方式 |

502| ------------------------------------ | ------------------------------------------------------------------------------------------- | --------------------------------------------------- |503| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |

512| Keys from `OTEL_RESOURCE_ATTRIBUTES` | 您設定的自訂屬性，例如 `department` 或 `team.id`。詳見[多團隊組織支援](#multi-team-organization-support) | `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES`（預設：true） |513| 來自 `OTEL_RESOURCE_ATTRIBUTES` 的金鑰 | 您設定的自訂屬性，例如 `department` 或 `team.id`。請參閱[多團隊組織支援](#multi-team-organization-support) | `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES`（預設值：true） |

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

513 515

514當 Claude Code 登入到 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway) 時，CLI 會使用來自閘道工作階段的已驗證身份戳記匯出：`user.id` 是 IdP 主體而不是匿名安裝識別碼，`user.email` 是已登入的電子郵件，`user.groups` 以逗號分隔的字串形式帶有 IdP 群組成員資格。每個匯出還帶有 `identity.source: gateway-oidc`。閘道身份最後應用，因此透過 `OTEL_RESOURCE_ATTRIBUTES` 設定的 `user.*` 和 `identity.*` 鍵在閘道工作階段上被忽略。516當 Claude Code 登入到[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.*` 金鑰在閘道工作階段上會被忽略。

515 517

516事件另外包含以下屬性。這些永遠不會附加到指標，因為它們會導致無限制的基數：518事件另外還包括以下屬性。這些永遠不會附加到指標，因為它們會導致無限的基數：

517 519

518* `prompt.id`：UUID 將使用者提示與所有後續事件關聯到下一個提示。請參閱[事件關聯屬性](#event-correlation-attributes)。520* `prompt.id`：UUID，將使用者提示與所有後續事件關聯到下一個提示。請參閱[事件關聯屬性](#event-correlation-attributes)。

519* `workspace.host_paths`：在桌面應用程式中選擇的主機工作區目錄，作為字串陣列521* `workspace.host_paths`：在桌面應用程式中選擇的主機工作區目錄，作為字串陣列

520* `workflow.run_id`：執行識別碼，前綴為 `wf_`，在 API 和工具事件上發出，由屬於 [Workflow](/docs/zh-TW/workflows) 工具執行的代理發出。按一個 `workflow.run_id` 篩選事件會重建該執行的 API 請求和工具結果。識別碼涵蓋工作流程指令碼衍生的代理以及這些代理依次衍生的任何代理，例如 skill 叫用。它符合在 Workflow 工具結果中報告的執行識別碼。在所有其他事件上不存在。需要 Claude Code v2.1.202 或更新版本522* `workflow.run_id`：執行識別碼，前綴為 `wf_`，在屬於[工作流程](/docs/zh-TW/workflows)工具執行的代理程式發出的 API 和工具事件上。按一個 `workflow.run_id` 篩選事件會重建該執行的 API 請求和工具結果。識別碼涵蓋工作流程指令碼產生的代理程式以及這些代理程式依次產生的任何代理程式，例如技能叫用。它與工作流程工具結果中報告的執行識別碼相符。在所有其他事件上不存在。需要 Claude Code v2.1.202 或更新版本

521* `workflow.name`：工作流程的名稱，其指令碼的 `meta.name`，與 `workflow.run_id` 一起發出。內建工作流程名稱在執行未修改的內建指令碼時按原樣出現。使用者撰寫的名稱（包括內建指令碼的編輯副本）被替換為 `custom`，除非設定 `OTEL_LOG_TOOL_DETAILS=1`。需要 Claude Code v2.1.202 或更新版本523* `workflow.name`：工作流程的名稱，其指令碼的 `meta.name`，與 `workflow.run_id` 一起發出。內建工作流程名稱在執行未修改的內建指令碼時逐字出現。使用者撰寫的名稱（包括內建指令碼的編輯副本）會被替換為 `custom`，除非設定了 `OTEL_LOG_TOOL_DETAILS=1`。需要 Claude Code v2.1.202 或更新版本

524

525<h4 id="repository-attributes">

526 儲存庫屬性

527</h4>

528

529設定 `OTEL_METRICS_INCLUDE_REPOSITORY=true` 以使用工作階段儲存庫的身分標籤指標和事件，以便共用收集器可以按儲存庫歸因使用情況。需要 Claude Code v2.1.269 或更新版本。

530

531Claude Code 每個工作階段從儲存庫的 `origin` 遠端衍生這些屬性一次。一個儲存庫的 HTTPS 和 SSH 遠端會產生相同的值：

532

533| 屬性 | 值 |

534| ------------------------- | ------------------------------------------------------------------------------------- |

535| `vcs.repository.url.full` | 儲存庫的瀏覽器 URL，不含 `.git`，例如 `https://github.com/example-org/example-repo` |

536| `vcs.owner.name` | 擁有者或群組路徑，例如 `example-org`；當遠端路徑只有一個區段時省略 |

537| `vcs.repository.name` | 裸儲存庫名稱，例如 `example-repo` |

538| `vcs.provider.name` | 當 Claude Code 將遠端的主機或 URL 形狀識別為其中一個提供者時為 `github`、`gitlab`、`bitbucket` 或 `gitea`；否則省略 |

539

540值會轉換為小寫，遠端 URL 中的認證、查詢字串和片段永遠不會出現在其中。當工作階段沒有 `origin` 遠端、遠端不是 URL 形狀或唯一的封閉儲存庫是您的主目錄時，屬性會被省略。

541

542您在 [`OTEL_RESOURCE_ATTRIBUTES`](#multi-team-organization-support) 中宣告的 `vcs.*` 金鑰會替換該金鑰的衍生值。如果您宣告 `vcs.repository.url.full`，Claude Code 永遠不會讀取遠端，只會報告您宣告的金鑰。

543

544屬性只流向您自己的匯出器；Anthropic 的遙測會捨棄每個 `vcs.*` 金鑰。

522 545

523<h3 id="metrics">546<h3 id="metrics">

524 指標547 指標

525</h3>548</h3>

526 549

527Claude Code 匯出以下指標。「單位」欄顯示附加到每個指標的 OpenTelemetry 單位字串；計數指標不帶任何單位。550Claude Code 匯出以下指標。「單位」欄顯示附加到每個指標的 OpenTelemetry 單位字串；計數指標不包含任何單位。

528 551

529| 指標名稱 | 描述 | 單位 |552| 指標名稱 | 描述 | 單位 |

530| ------------------------------------- | ------------------- | ------ |553| ------------------------------------- | ------------------- | ------ |

535| `claude_code.cost.usage` | Claude Code 工作階段的成本 | USD |558| `claude_code.cost.usage` | Claude Code 工作階段的成本 | USD |

538| `claude_code.active_time.total` | 總活躍時間 | s |561| `claude_code.active_time.total` | 總活躍時間 | s |

539 562

540當 `prometheus` 是 `OTEL_METRICS_EXPORTER` 中列出的唯一匯出器時，Claude Code 會從匯出的指標中省略 `USD`、`tokens` 和 `s` 單位，以便抓取保持有效的 Prometheus 文字格式。指標名稱不會變更，結合匯出器的配置（例如 `otlp,prometheus`）會保留單位。在 v2.1.216 之前，Prometheus 抓取包含一些抓取器拒絕的僅限 OpenMetrics 的 `# UNIT` 行。563當 `prometheus` 是 `OTEL_METRICS_EXPORTER` 中列出的唯一匯出器時，Claude Code 會從匯出的指標中省略 `USD`、`tokens` 和 `s` 單位，以便抓取保持有效的 Prometheus 文字格式。指標名稱不會變更，結合匯出器的設定（例如 `otlp,prometheus`）會保留單位。在 v2.1.216 之前，Prometheus 抓取包含一些抓取器拒絕的僅限 OpenMetrics 的 `# UNIT` 行。

541 564

542<h3 id="metric-details">565<h3 id="metric-details">

543 指標詳情566 指標詳細資訊

544</h3>567</h3>

545 568

546每個指標都包含上面列出的標準屬性。具有額外內容特定屬性的指標如下所述。569每個指標都包括上面列出的標準屬性。具有其他內容特定屬性的指標如下所述。

547 570

548<h4 id="session-counter">571<h4 id="session-counter">

549 工作階段計數器572 工作階段計數器

554**屬性**：577**屬性**：

555 578

556* 所有[標準屬性](#standard-attributes)579* 所有[標準屬性](#standard-attributes)

557* `start_type`：工作階段的啟動方式。`"fresh"`、`"resume"`、`"continue"` 或 `"agents_view"` 之一。`"agents_view"` 值識別 `claude agents` 儀表板程序，這是使用者啟動的本機 UI，而不是對話工作階段。在您的儀表板中篩選此值以將 UI 程序啟動與對話工作階段分開。580* `start_type`：工作階段的啟動方式。`"fresh"`、`"resume"`、`"continue"` 或 `"agents_view"` 之一。`"agents_view"` 值識別 `claude agents` 儀表板程序，這是使用者啟動的本機 UI 而非對話工作階段。在儀表板中篩選此值以將 UI 程序啟動與對話工作階段分開。

558 581

559<h4 id="lines-of-code-counter">582<h4 id="lines-of-code-counter">

560 程式碼行計數器583 程式碼行計數器

566 589

567* 所有[標準屬性](#standard-attributes)590* 所有[標準屬性](#standard-attributes)

568* `type`：（`"added"`、`"removed"`）591* `type`：（`"added"`、`"removed"`）

569* `model`：進行變更的模型識別碼（例如，"claude-sonnet-5"）592* `model`：進行變更的模型的模型識別碼（例如 "claude-sonnet-5"）

570 593

571<h4 id="pull-request-counter">594<h4 id="pull-request-counter">

572 提取請求計數器595 提取請求計數器

573</h4>596</h4>

574 597

575透過 Claude Code 建立提取請求或合併請求時遞增。598當 Claude Code 透過 shell 命令或 MCP 工具建立提取請求或合併請求時遞增。

576 599

577**屬性**：600**屬性**：

578 601

597**屬性**：620**屬性**：

598 621

599* 所有[標準屬性](#standard-attributes)622* 所有[標準屬性](#standard-attributes)

600* `model`：模型識別碼（例如，"claude-sonnet-5"）623* `model`：模型識別碼（例如 "claude-sonnet-5"）

601* `query_source`：發出請求的子系統的類別。`"main"`、`"subagent"` 或 `"auxiliary"` 之一624* `query_source`：發出請求的子系統的類別。`"main"`、`"subagent"` 或 `"auxiliary"` 之一

602* `speed`：當請求使用快速模式時為 `"fast"`。否則不存在625* `speed`：當請求使用快速模式時為 `"fast"`。否則不存在

603* `effort`：應用於請求的[努力等級](/docs/zh-TW/model-config#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。當模型不支援努力時不存在。626* `effort`：套用到請求的[努力等級](/docs/zh-TW/model-config#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。當模型不支援努力時不存在。

604* `agent.name`：發出請求的子代理類型。內建代理名稱和官方市場 plugin 的代理按原樣出現。其他使用者定義的代理名稱被替換為 `"custom"`。當請求不是由命名的子代理類型發出時不存在。627* `agent.name`：發出請求的子代理程式類型。內建代理程式名稱和來自官方市場的外掛程式的代理程式逐字出現。其他使用者定義的代理程式名稱會被替換為 `"custom"`。當請求不是由具名子代理程式類型發出時不存在。

605* `skill.name`：對請求有效的 Skill，由 Skill 工具、`/` 命令設定或由衍生的子代理繼承。內建、捆綁、使用者定義和官方市場 plugin skill 名稱按原樣出現。第三方 plugin skill 名稱被替換為 `"third-party"`。當沒有 skill 有效時不存在。628* `skill.name`：對請求有效的技能，由技能工具、`/` 命令設定或由產生的子代理程式繼承。內建、捆綁、使用者定義和官方市場外掛程式技能名稱逐字出現。第三方外掛程式技能名稱會被替換為 `"third-party"`。當沒有技能有效時不存在。

606* `plugin.name`：當活躍 skill 或子代理由 plugin 提供時的擁有 plugin。官方市場 plugin 名稱按原樣出現。第三方 plugin 名稱被替換為 `"third-party"`。當 skill 和子代理都沒有擁有 plugin 時不存在。629* `plugin.name`：當有效技能或子代理程式由外掛程式提供時的擁有外掛程式。官方市場外掛程式名稱逐字出現。第三方外掛程式名稱會被替換為 `"third-party"`。當技能和子代理程式都沒有擁有外掛程式時不存在。

607* `marketplace.name`：擁有 plugin 的安裝市場。僅針對官方市場 plugin 發出。否則不存在。630* `marketplace.name`：擁有外掛程式的安裝來源市場。僅針對官方市場外掛程式發出。否則不存在。

608* `mcp_server.name`：MCP 伺服器，其工具結果此請求消耗。內建、claude.ai 代理和官方登錄伺服器名稱按原樣出現。使用者配置的伺服器名稱被替換為 `"custom"`。當請求未消耗任何 MCP 工具結果時不存在。在 v2.1.222 之前，Claude Code 在每個 MCP 工具呼叫後的請求上設定此屬性，而不僅僅是消耗工具結果的請求，因此聚合它的儀表板在您升級後會顯示下降。631* `mcp_server.name`：此請求消耗其工具結果的 MCP 伺服器。內建、claude.ai 代理和官方登錄伺服器名稱逐字出現。使用者設定的伺服器名稱會被替換為 `"custom"`。當請求未消耗任何 MCP 工具結果時不存在。在 v2.1.222 之前，Claude Code 在每個 MCP 工具呼叫後的每個請求上設定此屬性，而不僅是在消耗工具結果的請求上，因此聚合它的儀表板在升級後會顯示下降。

609* `mcp_tool.name`：MCP 工具，其結果此請求消耗，與 `mcp_server.name` 具有相同的編輯和版本行為。當請求未消耗任何 MCP 工具結果時不存在。632* `mcp_tool.name`：此請求消耗其結果的 MCP 工具，具有與 `mcp_server.name` 相同的編輯和版本行為。當請求未消耗任何 MCP 工具結果時不存在。

610 633

611<h4 id="token-counter">634<h4 id="token-counter">

612 權杖計數器635 權杖計數器

618 641

619* 所有[標準屬性](#standard-attributes)642* 所有[標準屬性](#standard-attributes)

620* `type`：（`"input"`、`"output"`、`"cacheRead"`、`"cacheCreation"`）643* `type`：（`"input"`、`"output"`、`"cacheRead"`、`"cacheCreation"`）

621* `model`：模型識別碼（例如，"claude-sonnet-5"）644* `model`：模型識別碼（例如 "claude-sonnet-5"）

622* `query_source`：發出請求的子系統的類別。`"main"`、`"subagent"` 或 `"auxiliary"` 之一645* `query_source`：發出請求的子系統的類別。`"main"`、`"subagent"` 或 `"auxiliary"` 之一

623* `speed`：當請求使用快速模式時為 `"fast"`。否則不存在646* `speed`：當請求使用快速模式時為 `"fast"`。否則不存在

624* `effort`：應用於請求的[努力等級](/docs/zh-TW/model-config#adjust-effort-level)。詳見[成本計數器](#cost-counter)以了解詳情。647* `effort`：套用到請求的[努力等級](/docs/zh-TW/model-config#adjust-effort-level)。請參閱[成本計數器](#cost-counter)以取得詳細資訊。

625* `agent.name`、`skill.name`、`plugin.name`、`marketplace.name`、`mcp_server.name`、`mcp_tool.name`：請求的 Skill、plugin、代理和 MCP 歸屬。詳見[成本計數器](#cost-counter)以了解定義和編輯行為。648* `agent.name`、`skill.name`、`plugin.name`、`marketplace.name`、`mcp_server.name`、`mcp_tool.name`：請求的技能、外掛程式、代理程式和 MCP 歸因。請參閱[成本計數器](#cost-counter)以取得定義和編輯行為。

626 649

627<h4 id="code-edit-tool-decision-counter">650<h4 id="code-edit-tool-decision-counter">

628 程式碼編輯工具決定計數器651 程式碼編輯工具決定計數器

635* 所有[標準屬性](#standard-attributes)658* 所有[標準屬性](#standard-attributes)

636* `tool_name`：工具名稱（`"Edit"`、`"Write"`、`"NotebookEdit"`）659* `tool_name`：工具名稱（`"Edit"`、`"Write"`、`"NotebookEdit"`）

637* `decision`：使用者決定（`"accept"`、`"reject"`）660* `decision`：使用者決定（`"accept"`、`"reject"`）

638* `source`：決定來源。`"config"`、`"hook"`、`"user_permanent"`、`"user_temporary"`、`"user_abort"` 或 `"user_reject"` 之一。詳見[工具決定事件](#tool-decision-event)以了解每個值的含義。661* `source`：決定的來源。`"config"`、`"hook"`、`"user_permanent"`、`"user_temporary"`、`"user_abort"` 或 `"user_reject"` 之一。請參閱[工具決定事件](#tool-decision-event)以瞭解每個值的含義。

639* `language`：編輯檔案的程式設計語言，例如 `"TypeScript"`、`"Python"`、`"JavaScript"` 或 `"Markdown"`。對於無法識別的副檔名，傳回 `"unknown"`。662* `language`：編輯檔案的程式設計語言，例如 `"TypeScript"`、`"Python"`、`"JavaScript"` 或 `"Markdown"`。對於無法識別的副檔名傳回 `"unknown"`。

640 663

641<h4 id="active-time-counter">664<h4 id="active-time-counter">

642 活躍時間計數器665 活躍時間計數器

643</h4>666</h4>

644 667

645追蹤實際花費在主動使用 Claude Code 上的時間，不包括閒置時間。此指標在使用者互動期間遞增，例如輸入和讀取回應，以及在 CLI 處理期間遞增，例如工具執行和 AI 回應產生。668追蹤實際花費在主動使用 Claude Code 上的時間，不包括閒置時間。此指標在使用者互動期間（例如輸入和讀取回應）以及 CLI 處理期間（例如工具執行和 AI 回應產生）遞增。

646 669

647**屬性**：670**屬性**：

648 671

653 事件676 事件

654</h3>677</h3>

655 678

656Claude Code 透過 OpenTelemetry 日誌/事件匯出以下事件（當配置 `OTEL_LOGS_EXPORTER` 時）：679Claude Code 透過 OpenTelemetry 日誌/事件匯出以下事件（當設定了 `OTEL_LOGS_EXPORTER` 時）：

657 680

658<h4 id="event-correlation-attributes">681<h4 id="event-correlation-attributes">

659 事件關聯屬性682 事件關聯屬性

660</h4>683</h4>

661 684

662當使用者提交提示時，Claude Code 可能會進行多個 API 呼叫並執行多個工具。`prompt.id` 屬性可讓您將所有這些事件與觸發它們的單個提示相關聯。685當使用者提交提示時，Claude Code 可能會進行多個 API 呼叫並執行多個工具。`prompt.id` 屬性可讓您將所有這些事件與觸發它們的單一提示相關聯。

663 686

664| 屬性 | 描述 |687| 屬性 | 描述 |

665| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |688| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

667| `message.uuid` | 訊息的 UUID，如工作階段文字記錄中所保存，`~/.claude/projects/*/*.jsonl` 檔案。存在於 `assistant_response` 上，以及 `user_prompt` 上，除了命令分派，可能產生零個或多個訊息。在 `assistant_response` 上，這是回應的最終文字記錄條目，下一個轉換的 `parentUuid` 從其鏈接。需要 Claude Code v2.1.214 或更新版本 |690| `message.uuid` | 訊息的 UUID，如工作階段文字記錄中所保存，`~/.claude/projects/*/*.jsonl` 檔案。出現在 `assistant_response` 上，以及 `user_prompt` 上，除了命令分派外，它可以產生零個或多個訊息。在 `assistant_response` 上，這是回應的最終文字記錄項目，下一個回合的 `parentUuid` 從其鏈接。需要 Claude Code v2.1.214 或更新版本 |

668| `client_request_id` | 用戶端產生的 UUID，作為 `x-client-request-id` 請求標頭傳送。存在於 `api_request` 和 `api_error` 上，用於第一方 API 連線；在第三方提供者後端上不存在，以及當請求透過非串流後備重試時。將請求與其回應配對，並且對於永遠不會產生伺服器 `request_id` 的失敗（例如逾時）保持可用。符合 `llm_request` 追蹤跨度上的相同屬性。需要 Claude Code v2.1.214 或更新版本 |691| `client_request_id` | 用戶端產生的 UUID，作為 `x-client-request-id` 請求標頭傳送。出現在第一方 API 連線上的 `api_request` 和 `api_error` 上；在第三方提供者後端上不存在，以及當請求透過非串流回退重試時。將請求與其回應配對，並且對於永遠不會產生伺服器 `request_id` 的逾時等失敗仍然可用。與 `llm_request` 追蹤跨度上的相同屬性相符。需要 Claude Code v2.1.214 或更新版本 |

669 692

670若要追蹤由單個提示觸發的所有活動，請按特定 `prompt.id` 值篩選您的事件。這會傳回使用者提示事件、任何 api\_request 事件以及處理該提示時發生的任何 tool\_result 事件。693若要追蹤由單一提示觸發的所有活動，請按特定 `prompt.id` 值篩選您的事件。這會傳回 user\_prompt 事件、任何 api\_request 事件以及處理該提示時發生的任何 tool\_result 事件。

671 694

672對於訊息級別重建，每個事件類別帶有與工作階段文字記錄中欄位相符的鍵。文字記錄條目格式是[內部於 Claude Code](/docs/zh-TW/sessions#where-transcripts-are-stored)，並在版本之間變更，因此在這些欄位上聯接的管道可能在任何版本上中斷；將聯接視為版本特定而不是穩定合約：695對於訊息層級重建，每個事件類別都攜帶與工作階段文字記錄中的欄位相符的金鑰。文字記錄項目格式是[Claude Code 內部的](/docs/zh-TW/sessions#where-transcripts-are-stored)，在版本之間變更，因此在這些欄位上聯接的管道可能會在任何版本上中斷；將聯接視為版本特定的而非穩定的合約：

673 696

674* `message.uuid` 在 `user_prompt` 和 `assistant_response` 上697* `message.uuid` 在 `user_prompt` 和 `assistant_response` 上

675* `request_id` 在 API 事件上，在文字記錄的助手條目上保存為 `requestId`698* `request_id` 在 API 事件上，在文字記錄的助理項目上保存為 `requestId`

676* `tool_use_id` 在 `tool_result` 和 `tool_decision` 事件上699* `tool_use_id` 在 `tool_result` 和 `tool_decision` 事件上

677 700

678<h4 id="user-prompt-event">701<h4 id="user-prompt-event">

687 710

688* 所有[標準屬性](#standard-attributes)711* 所有[標準屬性](#standard-attributes)

689* `event.name`：`"user_prompt"`712* `event.name`：`"user_prompt"`

690* `event.timestamp`：ISO 8601 時間戳713* `event.timestamp`：ISO 8601 時間戳記

691* `event.sequence`：單調遞增計數器，用於排序工作階段內的事件714* `event.sequence`：單調遞增的計數器，用於排序工作階段內的事件

692* `prompt_length`：提示的長度715* `prompt_length`：提示的長度

693* `prompt`：提示內容。預設為編輯。設定 `OTEL_LOG_USER_PROMPTS=1` 以包含它716* `prompt`：提示內容。預設情況下編輯。設定 `OTEL_LOG_USER_PROMPTS=1` 以包含它

694* `message.uuid`：產生的使用者訊息的 UUID，符合保存的文字記錄條目。在命令分派上不存在，可能產生零個或多個訊息。需要 Claude Code v2.1.214 或更新版本717* `message.uuid`：產生的使用者訊息的 UUID，與保存的文字記錄項目相符。在命令分派上不存在，它可以產生零個或多個訊息。需要 Claude Code v2.1.214 或更新版本

695* `command_name`：當提示叫用命令時的命令名稱。內建和捆綁的命令名稱（例如 `compact` 或 `debug`）按原樣發出；別名（例如 `reset`）按輸入方式發出而不是規範名稱。自訂、plugin 和 MCP 命令名稱除非設定 `OTEL_LOG_TOOL_DETAILS=1`，否則會摺疊為 `custom` 或 `mcp`718* `command_name`：當提示叫用命令時的命令名稱。內建和捆綁的命令名稱（例如 `compact` 或 `debug`）按原樣發出；別名（例如 `reset`）按輸入的方式發出而非規範名稱。自訂、外掛程式和 MCP 命令名稱會摺疊為 `custom` 或 `mcp`，除非設定了 `OTEL_LOG_TOOL_DETAILS=1`

696* `command_source`：命令的來源（如果存在）：`builtin`、`custom` 或 `mcp`。Plugin 提供的命令報告為 `custom`719* `command_source`：命令存在時的來源：`builtin`、`custom` 或 `mcp`。外掛程式提供的命令報告為 `custom`

697 720

698<h4 id="assistant-response-event">721<h4 id="assistant-response-event">

699 助手回應事件722 助理回應事件

700</h4>723</h4>

701 724

702在每個 API 請求傳回來自模型的文字內容後記錄。僅包含回應的文字區塊；思考區塊和工具使用區塊被排除。需要 Claude Code v2.1.193 或更新版本。725在每個傳回來自模型的文字內容的 API 請求後記錄。僅包含回應的文字區塊；思考區塊和工具使用區塊被排除。需要 Claude Code v2.1.193 或更新版本。

703 726

704**事件名稱**：`claude_code.assistant_response`727**事件名稱**：`claude_code.assistant_response`

705 728

707 730

708* 所有[標準屬性](#standard-attributes)731* 所有[標準屬性](#standard-attributes)

709* `event.name`：`"assistant_response"`732* `event.name`：`"assistant_response"`

710* `event.timestamp`：ISO 8601 時間戳733* `event.timestamp`：ISO 8601 時間戳記

711* `event.sequence`：單調遞增計數器，用於排序工作階段內的事件734* `event.sequence`：單調遞增的計數器，用於排序工作階段內的事件

712* `response_length`：回應文字的長度（字元數）735* `response_length`：回應文字的長度（以字元為單位）

713* `response`：回應文字，在內容限制處截斷（預設 60 KB）。預設為 `<REDACTED>`。設定 `OTEL_LOG_ASSISTANT_RESPONSES=1` 以包含它。當 `OTEL_LOG_ASSISTANT_RESPONSES` 未設定時，`OTEL_LOG_USER_PROMPTS` 會控制它，因此設定 `OTEL_LOG_ASSISTANT_RESPONSES=0` 以在啟用提示記錄時保持回應編輯736* `response`：回應文字，在內容限制處截斷（預設為 60 KB）。預設情況下編輯為 `<REDACTED>`。設定 `OTEL_LOG_ASSISTANT_RESPONSES=1` 以包含它。當 `OTEL_LOG_ASSISTANT_RESPONSES` 未設定時，`OTEL_LOG_USER_PROMPTS` 會控制它，因此設定 `OTEL_LOG_ASSISTANT_RESPONSES=0` 以在啟用提示記錄時保持回應編輯

714* `model`：模型識別碼（例如，"claude-sonnet-5"）737* `model`：模型識別碼（例如 "claude-sonnet-5"）

715* `request_id`：來自回應的 `request-id` 標頭的 Anthropic API 請求 ID。僅當 API 傳回時才存在738* `request_id`：來自回應的 `request-id` 標頭的 Anthropic API 請求 ID。僅當 API 傳回時才存在

716* `message.uuid`：回應的最終文字記錄條目的 UUID。API 回應被保存為每個內容區塊一個文字記錄條目；這是最後一個，下一個轉換的 `parentUuid` 從其鏈接。需要 Claude Code v2.1.214 或更新版本739* `message.uuid`：回應的最終文字記錄項目的 UUID。API 回應會保存為每個內容區塊一個文字記錄項目；這是最後一個，下一個回合的 `parentUuid` 從其鏈接。需要 Claude Code v2.1.214 或更新版本

717* `query_source`：發出請求的子系統，例如 `"repl_main_thread"`、`"compact"` 或子代理名稱740* `query_source`：發出請求的子系統，例如 `"repl_main_thread"`、`"compact"` 或子代理程式名稱

718 741

719<h4 id="tool-result-event">742<h4 id="tool-result-event">

720 工具結果事件743 工具結果事件

721</h4>744</h4>

722 745

723當工具完成執行時記錄。不會在工具呼叫被拒絕時發出；詳見[工具決定事件](#tool-decision-event)以了解拒絕。746當工具完成執行時記錄。如果工具呼叫被拒絕，則不發出；請參閱[工具決定事件](#tool-decision-event)以取得拒絕。

724 747

725**事件名稱**：`claude_code.tool_result`748**事件名稱**：`claude_code.tool_result`

726 749

728 751

729* 所有[標準屬性](#standard-attributes)752* 所有[標準屬性](#standard-attributes)

730* `event.name`：`"tool_result"`753* `event.name`：`"tool_result"`

731* `event.timestamp`：ISO 8601 時間戳754* `event.timestamp`：ISO 8601 時間戳記

732* `event.sequence`：單調遞增計數器，用於排序工作階段內的事件755* `event.sequence`：單調遞增的計數器，用於排序工作階段內的事件

733* `tool_name`：工具的名稱756* `tool_name`：工具的名稱

734* `tool_use_id`：此工具叫用的唯一識別碼。符合傳遞給 hooks 的 `tool_use_id`，允許 OTel 事件和 hook 擷取資料之間的關聯。757* `tool_use_id`：此工具叫用的唯一識別碼。與傳遞給鉤子的 `tool_use_id` 相符，允許 OTel 事件和鉤子擷取資料之間的關聯。

735* `success`：`"true"` 或 `"false"`758* `success`：`"true"` 或 `"false"`

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

737* `error_type`：工具失敗時的錯誤類別字串，例如 `"Error:ENOENT"` 或 `"ShellError"`760* `error_type`：工具失敗時的錯誤類別字串，例如 `"Error:ENOENT"` 或 `"ShellError"`

738* `error`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：工具失敗時的完整錯誤訊息761* `error`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：工具失敗時的完整錯誤訊息

739* `decision_type`：始終為 `"accept"`，因為此事件僅在工具執行後發出。拒絕的呼叫不會產生工具結果762* `decision_type`：一律為 `"accept"`，因為此事件僅在工具執行後發出。拒絕的呼叫不會產生工具結果

740* `decision_source`：決定來源。`"config"`、`"hook"`、`"user_permanent"` 或 `"user_temporary"` 之一。詳見[工具決定事件](#tool-decision-event)以了解每個值的含義。拒絕專用來源 `"user_abort"` 和 `"user_reject"` 永遠不會出現在此事件上。763* `decision_source`：權限決定的來源。`"config"`、`"hook"`、`"user_permanent"` 或 `"user_temporary"` 之一。請參閱[工具決定事件](#tool-decision-event)以瞭解每個值的含義。僅拒絕的來源 `"user_abort"` 和 `"user_reject"` 永遠不會出現在此事件上。

741* `tool_input_size_bytes`：JSON 序列化工具輸入的大小（位元組）764* `tool_input_size_bytes`：JSON 序列化工具輸入的大小（以位元組為單位）

742* `tool_result_size_bytes`：工具結果的大小（位元組）765* `tool_result_size_bytes`：工具結果的大小（以位元組為單位）

743* `mcp_server_scope`：MCP 伺服器範圍識別碼（用於 MCP 工具）766* `mcp_server_scope`：MCP 伺服器範圍識別碼（用於 MCP 工具）

744* `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 或更新版本。參數因工具而異：767* `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 或更新版本

745 * 對於 Bash 工具：包括 `bash_command`、`full_command`、`timeout`、`description`、`dangerouslyDisableSandbox` 和 `git_commit_id`（git commit 命令成功時的提交 SHA）。桌面應用程式的工作區 bash 工具也將 `tool_name` 報告為 `Bash`，但僅包括 `bash_command`、`full_command` 和 `timeout`768* `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 或更新版本。參數因工具而異：

769 * 對於 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 上省略

770 * 對於桌面應用程式的工作區 Bash 工具，它也將 `tool_name` 報告為 `Bash`：僅包括 `bash_command`、`full_command` 和 `timeout`

746 * 對於 MCP 工具：包括 `mcp_server_name`、`mcp_tool_name`771 * 對於 MCP 工具：包括 `mcp_server_name`、`mcp_tool_name`

747 * 對於 Skill 工具：包括 `skill_name`772 * 對於技能工具：包括 `skill_name`

748 * 對於 Agent 工具或舊版 Task 工具：包括 `subagent_type`773 * 對於代理程式工具或舊版工作工具：包括 `subagent_type`

749* `tool_input`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：JSON 序列化的工具引數。超過 512 個字元的個別值會被截斷，整個承載的上限約為 4 K 字元。適用於所有工具，包括 MCP 工具。774* `tool_input`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：JSON 序列化工具引數。超過 512 個字元的個別值會被截斷，完整承載限制在約 4 K 個字元。適用於所有工具，包括 MCP 工具。

750 775

751<h4 id="api-request-event">776<h4 id="api-request-event">

752 API 請求事件777 API 請求事件

753</h4>778</h4>

754 779

755為每個 API 請求記錄到 Claude。780針對每個 API 請求記錄到 Claude。

756 781

757**事件名稱**：`claude_code.api_request`782**事件名稱**：`claude_code.api_request`

758 783

760 785

761* 所有[標準屬性](#standard-attributes)786* 所有[標準屬性](#standard-attributes)

762* `event.name`：`"api_request"`787* `event.name`：`"api_request"`

763* `event.timestamp`：ISO 8601 時間戳788* `event.timestamp`：ISO 8601 時間戳記

764* `event.sequence`：單調遞增計數器，用於排序工作階段內的事件789* `event.sequence`：單調遞增的計數器，用於排序工作階段內的事件

765* `model`：使用的模型（例如，"claude-sonnet-5"）790* `model`：使用的模型（例如 "claude-sonnet-5"）

766* `cost_usd`：估計成本（美元）791* `cost_usd`：以美元計的估計成本

767* `cost_usd_micros`：估計成本（美元的百萬分之一），作為整數發出792* `cost_usd_micros`：以美元百萬分之一計的估計成本，作為整數發出

768* `duration_ms`：請求持續時間（毫秒）793* `duration_ms`：請求持續時間（以毫秒為單位）

769* `input_tokens`：輸入權杖數794* `input_tokens`：輸入權杖數

770* `output_tokens`：輸出權杖數795* `output_tokens`：輸出權杖數

771* `cache_read_tokens`：從快取讀取的權杖數796* `cache_read_tokens`：從快取讀取的權杖數

772* `cache_creation_tokens`：用於快取建立的權杖數797* `cache_creation_tokens`：用於快取建立的權杖數

773* `request_id`：來自回應的 `request-id` 標頭的 Anthropic API 請求 ID，例如 `"req_011..."`。僅當 API 傳回時才存在。798* `request_id`：來自回應的 `request-id` 標頭的 Anthropic API 請求 ID，例如 `"req_011..."`。僅當 API 傳回時才存在。

774* `client_request_id`：用戶端產生的 UUID，作為 `x-client-request-id` 請求標頭傳送；詳見[事件關聯屬性](#event-correlation-attributes)表以了解何時存在。需要 Claude Code v2.1.214 或更新版本799* `client_request_id`：用戶端產生的 UUID，作為 `x-client-request-id` 請求標頭傳送；請參閱[事件關聯屬性](#event-correlation-attributes)表以瞭解何時存在。需要 Claude Code v2.1.214 或更新版本

775* `speed`：`"fast"` 或 `"normal"`，指示是否啟用了快速模式800* `speed`：`"fast"` 或 `"normal"`，指示快速模式是否有效

776* `query_source`：發出請求的子系統，例如 `"repl_main_thread"`、`"compact"` 或子代理名稱801* `query_source`：發出請求的子系統，例如 `"repl_main_thread"`、`"compact"` 或子代理程式名稱

777* `effort`：應用於請求的[努力等級](/docs/zh-TW/model-config#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。當模型不支援努力時不存在。802* `effort`：套用到請求的[努力等級](/docs/zh-TW/model-config#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。當模型不支援努力時不存在。

778* `agent.name`、`skill.name`、`plugin.name`、`marketplace.name`、`mcp_server.name`、`mcp_tool.name`：請求的 Skill、plugin、代理和 MCP 歸屬。詳見[成本計數器](#cost-counter)以了解定義和編輯行為。803* `agent.name`、`skill.name`、`plugin.name`、`marketplace.name`、`mcp_server.name`、`mcp_tool.name`：請求的技能、外掛程式、代理程式和 MCP 歸因。請參閱[成本計數器](#cost-counter)以取得定義和編輯行為。

779 804

780<h4 id="api-error-event">805<h4 id="api-error-event">

781 API 錯誤事件806 API 錯誤事件

789 814

790* 所有[標準屬性](#standard-attributes)815* 所有[標準屬性](#standard-attributes)

791* `event.name`：`"api_error"`816* `event.name`：`"api_error"`

792* `event.timestamp`：ISO 8601 時間戳817* `event.timestamp`：ISO 8601 時間戳記

793* `event.sequence`：單調遞增計數器，用於排序工作階段內的事件818* `event.sequence`：單調遞增的計數器，用於排序工作階段內的事件

794* `model`：使用的模型（例如，"claude-sonnet-5"）819* `model`：使用的模型（例如 "claude-sonnet-5"）

795* `error`：錯誤訊息820* `error`：錯誤訊息

796* `status_code`：HTTP 狀態碼（數字形式）。對於非 HTTP 錯誤（例如連線失敗），不存在。821* `status_code`：HTTP 狀態碼作為數字。對於非 HTTP 錯誤（例如連線失敗）不存在。

797* `duration_ms`：請求持續時間（毫秒）822* `duration_ms`：請求持續時間（以毫秒為單位）

798* `attempt`：進行的嘗試總次數，包括初始請求（`1` 表示未發生重試）823* `attempt`：進行的嘗試總數，包括初始請求（`1` 表示未發生重試）

799* `request_id`：來自回應的 `request-id` 標頭的 Anthropic API 請求 ID，例如 `"req_011..."`。僅當 API 傳回時才存在。824* `request_id`：來自回應的 `request-id` 標頭的 Anthropic API 請求 ID，例如 `"req_011..."`。僅當 API 傳回時才存在。

800* `client_request_id`：用戶端產生的 UUID，作為 `x-client-request-id` 請求標頭傳送。即使失敗（例如逾時或連線錯誤）永遠不會產生伺服器 `request_id`，也可用；詳見[事件關聯屬性](#event-correlation-attributes)表以了解何時存在。需要 Claude Code v2.1.214 或更新版本825* `client_request_id`：用戶端產生的 UUID，作為 `x-client-request-id` 請求標頭傳送。即使失敗（例如逾時或連線錯誤）永遠不會產生伺服器 `request_id` 時也可用；請參閱[事件關聯屬性](#event-correlation-attributes)表以瞭解何時存在。需要 Claude Code v2.1.214 或更新版本

801* `speed`：`"fast"` 或 `"normal"`，指示是否啟用了快速模式826* `speed`：`"fast"` 或 `"normal"`，指示快速模式是否有效

802* `query_source`：發出請求的子系統，例如 `"repl_main_thread"`、`"compact"` 或子代理名稱827* `query_source`：發出請求的子系統，例如 `"repl_main_thread"`、`"compact"` 或子代理程式名稱

803* `effort`：應用於請求的[努力等級](/docs/zh-TW/model-config#adjust-effort-level)。當模型不支援努力時不存在。828* `effort`：套用到請求的[努力等級](/docs/zh-TW/model-config#adjust-effort-level)。當模型不支援努力時不存在。

804* `agent.name`、`skill.name`、`plugin.name`、`marketplace.name`、`mcp_server.name`、`mcp_tool.name`：請求的 Skill、plugin、代理和 MCP 歸屬。詳見[成本計數器](#cost-counter)以了解定義和編輯行為。829* `agent.name`、`skill.name`、`plugin.name`、`marketplace.name`、`mcp_server.name`、`mcp_tool.name`：請求的技能、外掛程式、代理程式和 MCP 歸因。請參閱[成本計數器](#cost-counter)以取得定義和編輯行為。

805 830

806<h4 id="api-refusal-event">831<h4 id="api-refusal-event">

807 API 拒絕事件832 API 拒絕事件

808</h4>833</h4>

809 834

810當 API 請求傳回 `stop_reason: "refusal"` 時記錄。拒絕會在成功的回應串流上到達，而不是作為 HTTP 錯誤，因此 `api_error` 事件不會為它們觸發。此事件可讓您追蹤拒絕頻率並按與 `api_request` 和 `api_error` 相同的屬性分組拒絕。835當 API 請求傳回 `stop_reason: "refusal"` 時記錄。拒絕到達成功回應串流上，而非作為 HTTP 錯誤，因此 `api_error` 事件不會針對它們觸發。此事件可讓您追蹤拒絕頻率並按與 `api_request` 和 `api_error` 相同的屬性分組拒絕。

811 836

812**事件名稱**：`claude_code.api_refusal`837**事件名稱**：`claude_code.api_refusal`

813 838

815 840

816* 所有[標準屬性](#standard-attributes)841* 所有[標準屬性](#standard-attributes)

817* `event.name`：`"api_refusal"`842* `event.name`：`"api_refusal"`

818* `event.timestamp`：ISO 8601 時間戳843* `event.timestamp`：ISO 8601 時間戳記

819* `event.sequence`：單調遞增計數器，用於排序工作階段內的事件844* `event.sequence`：單調遞增的計數器，用於排序工作階段內的事件

820* `model`：來自請求的模型識別碼845* `model`：來自請求的模型識別碼

821* `request_id`：來自回應的 `request-id` 標頭的 Anthropic API 請求 ID，例如 `"req_011..."`。僅當 API 傳回時才存在。846* `request_id`：來自回應的 `request-id` 標頭的 Anthropic API 請求 ID，例如 `"req_011..."`。僅當 API 傳回時才存在。

822* `query_source`：發出請求的子系統，例如 `"repl_main_thread"`、`"compact"` 或子代理名稱。詳見[`api_request`](#api-request-event)以了解定義。847* `query_source`：發出請求的子系統，例如 `"repl_main_thread"`、`"compact"` 或子代理程式名稱。請參閱 [`api_request`](#api-request-event) 以取得定義。

823* `speed`：當[快速模式](/docs/zh-TW/fast-mode)啟用時為 `"fast"`，或 `"normal"`848* `speed`：當[快速模式](/docs/zh-TW/fast-mode)有效時為 `"fast"`，或 `"normal"`

824* `attempt`：重試嘗試編號。第一次嘗試是 `1`。849* `attempt`：重試嘗試編號。第一次嘗試是 `1`。

825* `effort`：應用於請求的[努力等級](/docs/zh-TW/model-config#adjust-effort-level)。當模型不支援努力時不存在。850* `effort`：套用到請求的[努力等級](/docs/zh-TW/model-config#adjust-effort-level)。當模型不支援努力時不存在。

826* `server_fallback_hop`：當 API 的伺服器端模型後備已在不同模型上重試此拒絕時為 `true`，因此使用者沒有看到此特定拒絕。當請求以拒絕結束時為 `false`。單個轉換可以發出 `true` hop 事件和稍後的 `false` 最終事件，當後備模型也拒絕時。851* `server_fallback_hop`：當 API 的伺服器端模型回退已在不同模型上重試此拒絕時為 `true`，因此使用者未看到此特定拒絕。當請求以拒絕結束時為 `false`。單一回合可以發出 `true` 跳躍事件和稍後的 `false` 最終事件，當回退模型也拒絕時。

827* `has_category`：當 API 回應帶有 `stop_details.category` 為 `"cyber"`、`"bio"`、`"frontier_llm"` 或 `"reasoning_extraction"` 時為 `true`。當回應沒有類別或值在該集合之外時為 `false`。當 `server_fallback_hop` 為 `true` 時不存在，因為 hop 區塊不帶 `stop_details`。852* `has_category`：當 API 回應攜帶 `stop_details.category` 為 `"cyber"`、`"bio"`、`"frontier_llm"` 或 `"reasoning_extraction"` 時為 `true`。當回應未攜帶類別或值在該集合外時為 `false`。當 `server_fallback_hop` 為 `true` 時不存在，因為跳躍區塊不攜帶 `stop_details`。

828* `has_explanation`：當 API 回應帶有 `stop_details.explanation` 時為 `true`，否則為 `false`。當 `server_fallback_hop` 為 `true` 時不存在。853* `has_explanation`：當 API 回應攜帶 `stop_details.explanation` 時為 `true`，否則為 `false`。當 `server_fallback_hop` 為 `true` 時不存在。

829* `category`：來自 API 回應的 `stop_details.category` 值。`"cyber"`、`"bio"`、`"frontier_llm"` 或 `"reasoning_extraction"` 之一。僅當設定 `OTEL_LOG_TOOL_DETAILS=1` 且 `has_category` 為 `true` 時才存在。854* `category`：來自 API 回應的 `stop_details.category` 值。`"cyber"`、`"bio"`、`"frontier_llm"` 或 `"reasoning_extraction"` 之一。僅當設定了 `OTEL_LOG_TOOL_DETAILS=1` 且 `has_category` 為 `true` 時才存在。

830* `agent.name`、`skill.name`、`plugin.name`、`marketplace.name`、`mcp_server.name`、`mcp_tool.name`：請求的 Skill、plugin、代理和 MCP 歸屬。詳見[成本計數器](#cost-counter)以了解定義和編輯行為。855* `agent.name`、`skill.name`、`plugin.name`、`marketplace.name`、`mcp_server.name`、`mcp_tool.name`：請求的技能、外掛程式、代理程式和 MCP 歸因。請參閱[成本計數器](#cost-counter)以取得定義和編輯行為。

831 856

832<h4 id="api-request-body-event">857<h4 id="api-request-body-event">

833 API 請求主體事件858 API 請求本體事件

834</h4>859</h4>

835 860

836當設定 `OTEL_LOG_RAW_API_BODIES` 時，為每個 API 請求嘗試記錄。每次嘗試發出一個事件，因此使用調整參數的重試各自產生自己的事件。861當設定了 `OTEL_LOG_RAW_API_BODIES` 時，針對每個 API 請求嘗試記錄。每次嘗試發出一個事件，因此使用調整參數的重試各自產生自己的事件。

837 862

838**事件名稱**：`claude_code.api_request_body`863**事件名稱**：`claude_code.api_request_body`

839 864

841 866

842* 所有[標準屬性](#standard-attributes)867* 所有[標準屬性](#standard-attributes)

843* `event.name`：`"api_request_body"`868* `event.name`：`"api_request_body"`

844* `event.timestamp`：ISO 8601 時間戳869* `event.timestamp`：ISO 8601 時間戳記

845* `event.sequence`：單調遞增計數器，用於排序工作階段內的事件870* `event.sequence`：單調遞增的計數器，用於排序工作階段內的事件

846* `body`：JSON 序列化的 Messages API 請求參數，例如系統提示、訊息和工具，在內容限制處截斷（預設 60 KB）。先前助手轉換中的擴展思考內容被編輯。僅在內聯模式下發出（`OTEL_LOG_RAW_API_BODIES=1`）。871* `body`：JSON 序列化的 Messages API 請求參數，例如系統提示、訊息和工具，在內容限制處截斷（預設為 60 KB）。先前助理回合中的擴展思考內容會被編輯。僅在內聯模式下發出（`OTEL_LOG_RAW_API_BODIES=1`）。

847* `body_ref`：包含未截斷主體的 `<dir>/<uuid>.request.json` 檔案的絕對路徑。僅在檔案模式下發出（`OTEL_LOG_RAW_API_BODIES=file:<dir>`）。872* `body_ref`：包含未截斷本體的 `<dir>/<uuid>.request.json` 檔案的絕對路徑。僅在檔案模式下發出（`OTEL_LOG_RAW_API_BODIES=file:<dir>`）。

848* `body_length`：未截斷的主體長度。當 `OTEL_LOG_RAW_API_BODIES=file:<dir>` 時為 UTF-8 位元組，或當 `=1` 時為 UTF-16 程式碼單位873* `body_length`：未截斷的本體長度。當 `OTEL_LOG_RAW_API_BODIES=file:<dir>` 時為 UTF-8 位元組，或當 `=1` 時為 UTF-16 程式碼單位

849* `body_truncated`：當發生內聯截斷時為 `"true"`。在檔案模式下和未發生截斷時不存在。874* `body_truncated`：當發生內聯截斷時為 `"true"`。在檔案模式下不存在，未發生截斷時不存在。

850* `model`：來自請求參數的模型識別碼875* `model`：來自請求參數的模型識別碼

851* `query_source`：發出請求的子系統（例如，`"compact"`）876* `query_source`：發出請求的子系統（例如 `"compact"`）

852 877

853<h4 id="api-response-body-event">878<h4 id="api-response-body-event">

854 API 回應主體事件879 API 回應本體事件

855</h4>880</h4>

856 881

857當設定 `OTEL_LOG_RAW_API_BODIES` 時，為每個成功的 API 回應記錄。882當設定了 `OTEL_LOG_RAW_API_BODIES` 時，針對每個成功的 API 回應記錄。

858 883

859**事件名稱**：`claude_code.api_response_body`884**事件名稱**：`claude_code.api_response_body`

860 885

862 887

863* 所有[標準屬性](#standard-attributes)888* 所有[標準屬性](#standard-attributes)

864* `event.name`：`"api_response_body"`889* `event.name`：`"api_response_body"`

865* `event.timestamp`：ISO 8601 時間戳890* `event.timestamp`：ISO 8601 時間戳記

866* `event.sequence`：單調遞增計數器，用於排序工作階段內的事件891* `event.sequence`：單調遞增的計數器，用於排序工作階段內的事件

867* `body`：JSON 序列化的 Messages API 回應，包括 id、內容區塊、使用情況和停止原因，在內容限制處截斷（預設 60 KB）。擴展思考內容被編輯。僅在內聯模式下發出（`OTEL_LOG_RAW_API_BODIES=1`）。892* `body`：JSON 序列化的 Messages API 回應，包括 id、內容區塊、使用情況和停止原因，在內容限制處截斷（預設為 60 KB）。擴展思考內容會被編輯。僅在內聯模式下發出（`OTEL_LOG_RAW_API_BODIES=1`）。

868* `body_ref`：包含未截斷主體的 `<dir>/<request_id>.response.json` 檔案的絕對路徑。僅在檔案模式下發出（`OTEL_LOG_RAW_API_BODIES=file:<dir>`）。893* `body_ref`：包含未截斷本體的 `<dir>/<request_id>.response.json` 檔案的絕對路徑。僅在檔案模式下發出（`OTEL_LOG_RAW_API_BODIES=file:<dir>`）。

869* `body_length`：未截斷的主體長度。當 `OTEL_LOG_RAW_API_BODIES=file:<dir>` 時為 UTF-8 位元組，或當 `=1` 時為 UTF-16 程式碼單位894* `body_length`：未截斷的本體長度。當 `OTEL_LOG_RAW_API_BODIES=file:<dir>` 時為 UTF-8 位元組，或當 `=1` 時為 UTF-16 程式碼單位

870* `body_truncated`：當發生內聯截斷時為 `"true"`。在檔案模式下和未發生截斷時不存在。895* `body_truncated`：當發生內聯截斷時為 `"true"`。在檔案模式下不存在，未發生截斷時不存在。

871* `model`：模型識別碼896* `model`：模型識別碼

872* `query_source`：發出請求的子系統897* `query_source`：發出請求的子系統

873* `request_id`：來自回應的 `request-id` 標頭的 Anthropic API 請求 ID，例如 `"req_011..."`。僅當 API 傳回時才存在。898* `request_id`：來自回應的 `request-id` 標頭的 Anthropic API 請求 ID，例如 `"req_011..."`。僅當 API 傳回時才存在。

876 工具決定事件901 工具決定事件

877</h4>902</h4>

878 903

879當做出工具權限決定（接受/拒絕）時記錄。904當進行工具權限決定（接受/拒絕）時記錄。

880 905

881**事件名稱**：`claude_code.tool_decision`906**事件名稱**：`claude_code.tool_decision`

882 907

884 909

885* 所有[標準屬性](#standard-attributes)910* 所有[標準屬性](#standard-attributes)

886* `event.name`：`"tool_decision"`911* `event.name`：`"tool_decision"`

887* `event.timestamp`：ISO 8601 時間戳912* `event.timestamp`：ISO 8601 時間戳記

888* `event.sequence`：單調遞增計數器，用於排序工作階段內的事件913* `event.sequence`：單調遞增的計數器，用於排序工作階段內的事件

889* `tool_name`：工具的名稱（例如，"Read"、"Edit"、"Write"、"NotebookEdit"）914* `tool_name`：工具的名稱（例如 "Read"、"Edit"、"Write"、"NotebookEdit"）

890* `tool_use_id`：此工具叫用的唯一識別碼。符合傳遞給 hooks 的 `tool_use_id`，允許 OTel 事件和 hook 擷取資料之間的關聯。915* `tool_use_id`：此工具叫用的唯一識別碼。與傳遞給鉤子的 `tool_use_id` 相符，允許 OTel 事件和鉤子擷取資料之間的關聯。

891* `decision`：`"accept"` 或 `"reject"`916* `decision`：`"accept"` 或 `"reject"`

892* `tool_source`：始終存在。工具的來源，作為 CLI 撰寫值的封閉集合。需要 Claude Code v2.1.214 或更新版本917* `tool_source`：一律存在。工具的來源，作為 CLI 撰寫值的封閉集合。需要 Claude Code v2.1.214 或更新版本

893 * `"builtin"`：CLI 自己的工具918 * `"builtin"`：CLI 自己的工具

894 * `"mcp"`：MCP 伺服器通常919 * `"mcp"`：一般 MCP 伺服器

895 * `"sdk_host_builtin_mcp"`：內建於 Claude Desktop 本身的進程內伺服器，在 Claude Desktop 擁有的工作階段中。Claude Desktop 擁有它從其自己的進入點之一啟動的工作階段，`claude-desktop`、`claude-desktop-3p` 或 `local-agent`，當該工作階段不是嵌套子項時；嵌套工作階段，包括 Claude Code 本身衍生的工作階段，將這些伺服器報告為 `"mcp"`920 * `"sdk_host_builtin_mcp"`：內建於 Claude Desktop 本身的進程內伺服器，在 Claude Desktop 擁有的工作階段中。Claude Desktop 擁有它從自己的其中一個進入點 `claude-desktop`、`claude-desktop-3p` 或 `local-agent` 啟動的工作階段，當該工作階段不是嵌套子項時；嵌套工作階段（包括 Claude Code 本身產生的工作階段）將這些伺服器報告為 `"mcp"`

896* `source`：決定來源：921* `source`：決定的來源：

897 * `"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"`。922 * `"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"`。

898 * `"hook"`：`PreToolUse` 或 `PermissionRequest` hook 傳回了決定。923 * `"hook"`：`PreToolUse` 或 `PermissionRequest` 鉤子傳回決定。

899 * `"user_permanent"`：當使用者在權限提示時選擇「是，且不再詢問...」時發出，將允許規則儲存到其個人設定。在互動 CLI 中，僅針對該選擇本身發出；稍後符合儲存規則的呼叫發出 `"config"` 代替。在 Agent SDK 或非互動 `-p` 工作階段中，初始選擇和稍後的規則相符都發出 `"user_permanent"`。視為接受。924 * `"user_permanent"`：當使用者在權限提示中選擇「是，不要再問...」時發出，這會將允許規則儲存到其個人設定。在互動 CLI 中，這僅針對該選擇本身發出；稍後與儲存規則相符的呼叫發出 `"config"`。在代理程式 SDK 或非互動 `-p` 工作階段中，初始選擇和稍後的規則相符都發出 `"user_permanent"`。視為接受。

900 * `"user_temporary"`：當使用者在權限提示時選擇「是」或在檔案編輯或讀取提示時選擇授予工作階段其餘部分存取權的選項時發出。在互動 CLI 中，僅針對選擇本身發出；稍後由該工作階段範圍授予允許的呼叫發出 `"config"` 代替。在 Agent SDK 或非互動 `-p` 工作階段中，選擇和稍後的相符都發出 `"user_temporary"`。視為接受。925 * `"user_temporary"`：當使用者在權限提示中選擇「是」進行一次性核准時發出，或在檔案編輯或讀取提示上選擇授予工作階段其餘部分存取權限的選項時發出。在互動 CLI 中，這僅針對選擇本身發出；稍後由該工作階段範圍授予允許的呼叫發出 `"config"`。在代理程式 SDK 或非互動 `-p` 工作階段中，選擇和稍後的相符都發出 `"user_temporary"`。視為接受。

901 * `"user_abort"`：當使用者關閉權限提示而不回答時發出。在 Agent SDK 和非互動 `-p` 工作階段中，這包括在 `canUseTool` 或 `--permission-prompt-tool` 權限請求待處理時中斷轉換；在 v2.1.216 之前，Claude Code 將該中斷報告為 `"user_reject"`。視為拒絕。926 * `"user_abort"`：當使用者在未回答的情況下關閉權限提示時發出。在代理程式 SDK 和非互動 `-p` 工作階段中，這包括在 `canUseTool` 或 `--permission-prompt-tool` 權限請求待處理時中斷回合；在 v2.1.216 之前，Claude Code 將該中斷報告為 `"user_reject"`。視為拒絕。

902 * `"user_reject"`：當使用者選擇「否」時發出。在互動 CLI 中，僅針對該選擇本身發出；符合使用者個人設定中拒絕規則的呼叫發出 `"config"` 代替。在 Agent SDK 或非互動 `-p` 工作階段中，符合個人設定中拒絕規則的呼叫發出 `"user_reject"`。視為拒絕。927 * `"user_reject"`：當使用者在提示時選擇「否」時發出。在互動 CLI 中，這僅針對該選擇本身發出；與使用者個人設定中的拒絕規則相符的呼叫發出 `"config"`。在代理程式 SDK 或非互動 `-p` 工作階段中，與個人設定中的拒絕規則相符的呼叫發出 `"user_reject"`。視為拒絕。

903* `tool_parameters`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：包含工具特定參數的 JSON 字串。形狀與[工具結果事件](#tool-result-event)相同，除了執行後欄位（例如 `git_commit_id`）。如果權限決定透過 `updatedInput` 重寫工具輸入，值可能與接受呼叫的 `tool_result` 不同。使用此屬性查看當 `decision` 為 `"reject"` 時拒絕了哪個命令。928* `tool_parameters`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：包含工具特定參數的 JSON 字串。與[工具結果事件](#tool-result-event)相同的形狀，減去執行後欄位，例如 `git_commit_id`。對於接受的呼叫，如果權限決定透過 `updatedInput` 重寫工具輸入，值可能與 `tool_result` 不同。使用此屬性查看當 `decision` 為 `"reject"` 時拒絕了哪個命令。

904 * 對於 `"sdk_host_builtin_mcp"` 工具：`mcp_server_name` 和 `mcp_tool_name` 即使旗標關閉時也包含，因為主機應用程式定義這些名稱；沒有它們，對這些內建伺服器之一的拒絕呼叫在預設串流上將無法歸屬。對於使用者配置的 MCP 伺服器，事件的 `tool_name` 始終是字面 `"mcp_tool"`，伺服器和工具名稱僅在旗標開啟時出現在 `tool_parameters` 中；引數內容在任何地方都需要旗標。需要 Claude Code v2.1.214 或更新版本929 * 對於 `"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 或更新版本

905 * 對於 Bash 工具：包括 `bash_command`、`full_command`、`timeout`、`description`、`dangerouslyDisableSandbox`。桌面應用程式的工作區 bash 工具也將 `tool_name` 報告為 `Bash`，但僅包括 `bash_command`、`full_command` 和 `timeout`930 * 對於 Bash 工具：包括 `bash_command`、`full_command`、`timeout`、`description`、`dangerouslyDisableSandbox`。桌面應用程式的工作區 bash 工具也將 `tool_name` 報告為 `Bash`，但僅包括 `bash_command`、`full_command` 和 `timeout`

906 * 對於 MCP 工具：包括 `mcp_server_name`、`mcp_tool_name`931 * 對於 MCP 工具：包括 `mcp_server_name`、`mcp_tool_name`

907 * 對於 Skill 工具：包括 `skill_name`932 * 對於技能工具：包括 `skill_name`

908 * 對於 Agent 工具或舊版 Task 工具：包括 `subagent_type`933 * 對於代理程式工具或舊版工作工具：包括 `subagent_type`

909 934

910<h4 id="permission-mode-changed-event">935<h4 id="permission-mode-changed-event">

911 權限模式變更事件936 權限模式變更事件

919 944

920* 所有[標準屬性](#standard-attributes)945* 所有[標準屬性](#standard-attributes)

921* `event.name`：`"permission_mode_changed"`946* `event.name`：`"permission_mode_changed"`

922* `event.timestamp`：ISO 8601 時間戳947* `event.timestamp`：ISO 8601 時間戳記

923* `event.sequence`：單調遞增計數器，用於排序工作階段內的事件948* `event.sequence`：單調遞增的計數器，用於排序工作階段內的事件

924* `from_mode`：先前的權限模式，例如 `"default"`、`"plan"`、`"acceptEdits"`、`"auto"` 或 `"bypassPermissions"`949* `from_mode`：先前的權限模式，例如 `"default"`、`"plan"`、`"acceptEdits"`、`"auto"` 或 `"bypassPermissions"`

925* `to_mode`：新的權限模式950* `to_mode`：新的權限模式

926* `trigger`：導致變更的原因。`"shift_tab"`、`"exit_plan_mode"`、`"auto_gate_denied"` 或 `"auto_opt_in"` 之一。當轉換來自 SDK 或橋接時不存在。951* `trigger`：導致變更的原因。`"shift_tab"`、`"exit_plan_mode"`、`"auto_gate_denied"` 或 `"auto_opt_in"` 之一。當轉換源自 SDK 或橋接時不存在。

927 952

928<h4 id="auth-event">953<h4 id="auth-event">

929 身份驗證事件954 驗證事件

930</h4>955</h4>

931 956

932當 `/login` 或 `/logout` 完成時記錄。957當 `/login` 或 `/logout` 完成時記錄。

937 962

938* 所有[標準屬性](#standard-attributes)963* 所有[標準屬性](#standard-attributes)

939* `event.name`：`"auth"`964* `event.name`：`"auth"`

940* `event.timestamp`：ISO 8601 時間戳965* `event.timestamp`：ISO 8601 時間戳記

941* `event.sequence`：單調遞增計數器，用於排序工作階段內的事件966* `event.sequence`：單調遞增的計數器，用於排序工作階段內的事件

942* `action`：`"login"` 或 `"logout"`967* `action`：`"login"` 或 `"logout"`

943* `success`：`"true"` 或 `"false"`968* `success`：`"true"` 或 `"false"`

944* `auth_method`：身份驗證方法，例如 `"oauth"`969* `auth_method`：驗證方法，例如 `"oauth"`

945* `error_category`：操作失敗時的分類錯誤類型。永遠不包括原始錯誤訊息970* `error_category`：當動作失敗時的分類錯誤類型。永遠不包含原始錯誤訊息

946* `status_code`：操作因 HTTP 錯誤而失敗時的 HTTP 狀態碼（字串形式）971* `status_code`：當動作因 HTTP 錯誤而失敗時的 HTTP 狀態碼作為字串

947 972

948<h4 id="mcp-server-connection-event">973<h4 id="mcp-server-connection-event">

949 MCP 伺服器連線事件974 MCP 伺服器連線事件

957 982

958* 所有[標準屬性](#standard-attributes)983* 所有[標準屬性](#standard-attributes)

959* `event.name`：`"mcp_server_connection"`984* `event.name`：`"mcp_server_connection"`

960* `event.timestamp`：ISO 8601 時間戳985* `event.timestamp`：ISO 8601 時間戳記

961* `event.sequence`：單調遞增計數器，用於排序工作階段內的事件986* `event.sequence`：單調遞增的計數器，用於排序工作階段內的事件

962* `status`：`"connected"`、`"failed"` 或 `"disconnected"`987* `status`：`"connected"`、`"failed"` 或 `"disconnected"`

963* `transport_type`：伺服器傳輸，例如 `"stdio"`、`"sse"` 或 `"http"`988* `transport_type`：伺服器傳輸，例如 `"stdio"`、`"sse"` 或 `"http"`

964* `server_scope`：伺服器配置的範圍，例如 `"user"`、`"project"` 或 `"local"`989* `server_scope`：伺服器設定的範圍，例如 `"user"`、`"project"` 或 `"local"`

965* `duration_ms`：連線嘗試持續時間（毫秒）990* `duration_ms`：連線嘗試持續時間（以毫秒為單位）

966* `error_code`：連線失敗時的錯誤碼991* `error_code`：連線失敗時的錯誤碼

967* `is_plugin`：當伺服器由 plugin 提供時為 `true`，否則為 `false`992* `is_plugin`：當伺服器由外掛程式提供時為 `true`，否則為 `false`

968* `plugin_id_hash`（當 `is_plugin` 為 `true` 時）：plugin 名稱和市場的穩定雜湊，用於按 plugin 分組事件而不暴露名稱。Claude Code 按[plugin 已載入事件](#plugin-loaded-event)下所述計算它993* `plugin_id_hash`（當 `is_plugin` 為 `true` 時）：外掛程式名稱和市場的穩定雜湊，用於按外掛程式分組事件而不暴露名稱。Claude Code 按[外掛程式載入事件](#plugin-loaded-event)下所述計算它

969* `plugin.name`（當 `is_plugin` 為 `true` 時）：提供伺服器的 plugin 名稱。對於第三方 plugin，除非 `OTEL_LOG_TOOL_DETAILS=1`，否則這是字面字串 `"third-party"`；這可保護第三方 plugin 名稱預設不出現在日誌中。來自官方 Anthropic 來源的 Plugin 始終按名稱識別。`plugin_id_hash` 和 `plugin.name` 屬性流向您自己的監控後端，不會傳送給 Anthropic994* `plugin.name`（當 `is_plugin` 為 `true` 時）：提供伺服器的外掛程式的名稱。對於第三方外掛程式，此值是字面字串 `"third-party"`，除非 `OTEL_LOG_TOOL_DETAILS=1`；這可保護第三方外掛程式名稱預設不出現在日誌中。來自官方 Anthropic 來源的外掛程式一律按名稱識別。`plugin_id_hash` 和 `plugin.name` 屬性流向您自己的監控後端，不會傳送給 Anthropic

970* `server_name`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：配置的伺服器名稱995* `server_name`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：設定的伺服器名稱

971* `error`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：連線失敗時的完整錯誤訊息996* `error`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：連線失敗時的完整錯誤訊息

972 997

973<h4 id="internal-error-event">998<h4 id="internal-error-event">

974 內部錯誤事件999 內部錯誤事件

975</h4>1000</h4>

976 1001

977當 Claude Code 捕捉到意外的內部錯誤時記錄。僅記錄錯誤類別名稱和 errno 樣式碼。永遠不包括錯誤訊息和堆疊追蹤。當針對 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 執行或設定 `DISABLE_ERROR_REPORTING` 時，不會發出此事件。1002當 Claude Code 捕捉到意外的內部錯誤時記錄。僅記錄錯誤類別名稱和 errno 樣式碼。永遠不包含錯誤訊息和堆疊追蹤。針對 Amazon Bedrock、Google Cloud 的代理程式平台或 Microsoft Foundry 執行時，或設定了 `DISABLE_ERROR_REPORTING` 時，不發出此事件。

978 1003

979**事件名稱**：`claude_code.internal_error`1004**事件名稱**：`claude_code.internal_error`

980 1005

982 1007

983* 所有[標準屬性](#standard-attributes)1008* 所有[標準屬性](#standard-attributes)

984* `event.name`：`"internal_error"`1009* `event.name`：`"internal_error"`

985* `event.timestamp`：ISO 8601 時間戳1010* `event.timestamp`：ISO 8601 時間戳記

986* `event.sequence`：單調遞增計數器，用於排序工作階段內的事件1011* `event.sequence`：單調遞增的計數器，用於排序工作階段內的事件

987* `error_name`：錯誤類別名稱，例如 `"TypeError"` 或 `"SyntaxError"`1012* `error_name`：錯誤類別名稱，例如 `"TypeError"` 或 `"SyntaxError"`

988* `error_code`：Node.js errno 碼，例如 `"ENOENT"`（如果存在於錯誤上）1013* `error_code`：Node.js errno 碼，例如錯誤上存在時的 `"ENOENT"`

989 1014

990<h4 id="plugin-installed-event">1015<h4 id="plugin-installed-event">

991 Plugin 已安裝事件1016 外掛程式已安裝事件

992</h4>1017</h4>

993 1018

994當 plugin 完成安裝時記錄，來自 `claude plugin install` CLI 命令和互動式 `/plugin` UI。1019當外掛程式完成安裝時記錄，來自 `claude plugin install` CLI 命令和互動 `/plugin` UI。

995 1020

996**事件名稱**：`claude_code.plugin_installed`1021**事件名稱**：`claude_code.plugin_installed`

997 1022

999 1024

1000* 所有[標準屬性](#standard-attributes)1025* 所有[標準屬性](#standard-attributes)

1001* `event.name`：`"plugin_installed"`1026* `event.name`：`"plugin_installed"`

1002* `event.timestamp`：ISO 8601 時間戳1027* `event.timestamp`：ISO 8601 時間戳記

1003* `event.sequence`：單調遞增計數器，用於排序工作階段內的事件1028* `event.sequence`：單調遞增的計數器，用於排序工作階段內的事件

1004* `marketplace.is_official`：如果市場是官方 Anthropic 市場，則為 `"true"`，否則為 `"false"`1029* `marketplace.is_official`：如果市場是官方 Anthropic 市場則為 `"true"`，否則為 `"false"`

1005* `install.trigger`：`"cli"` 或 `"ui"`1030* `install.trigger`：`"cli"` 或 `"ui"`

1006* `plugin.name`：已安裝 plugin 的名稱。對於第三方市場，僅當 `OTEL_LOG_TOOL_DETAILS=1` 時才包含1031* `plugin.name`：已安裝外掛程式的名稱。對於第三方市場，僅當 `OTEL_LOG_TOOL_DETAILS=1` 時才包含

1007* `plugin.version`：Plugin 版本（如果在市場條目中宣告）。對於第三方市場，僅當 `OTEL_LOG_TOOL_DETAILS=1` 時才包含1032* `plugin.version`：在市場項目中宣告時的外掛程式版本。對於第三方市場，僅當 `OTEL_LOG_TOOL_DETAILS=1` 時才包含

1008* `marketplace.name`：安裝 plugin 的市場。對於第三方市場，僅當 `OTEL_LOG_TOOL_DETAILS=1` 時才包含1033* `marketplace.name`：外掛程式的安裝來源市場。對於第三方市場，僅當 `OTEL_LOG_TOOL_DETAILS=1` 時才包含

1009 1034

1010<h4 id="plugin-loaded-event">1035<h4 id="plugin-loaded-event">

1011 Plugin 已載入事件1036 外掛程式已載入事件

1012</h4>1037</h4>

1013 1038

1014在工作階段開始時為每個啟用的 plugin 記錄一次。使用此事件來清點您的整個環境中哪些 plugin 是活躍的，作為記錄安裝動作本身的 `plugin_installed` 的補充。1039在工作階段開始時針對每個啟用的外掛程式記錄一次。使用此事件來清點您的整個車隊中哪些外掛程式有效，作為記錄安裝動作本身的 `plugin_installed` 的補充。

1015 1040

1016**事件名稱**：`claude_code.plugin_loaded`1041**事件名稱**：`claude_code.plugin_loaded`

1017 1042

1019 1044

1020* 所有[標準屬性](#standard-attributes)1045* 所有[標準屬性](#standard-attributes)

1021* `event.name`：`"plugin_loaded"`1046* `event.name`：`"plugin_loaded"`

1022* `event.timestamp`：ISO 8601 時間戳1047* `event.timestamp`：ISO 8601 時間戳記

1023* `event.sequence`：單調遞增計數器，用於排序工作階段內的事件1048* `event.sequence`：單調遞增的計數器，用於排序工作階段內的事件

1024* `plugin.name`：plugin 的名稱。對於官方市場和內建捆綁之外的 plugin，除非 `OTEL_LOG_TOOL_DETAILS=1`，否則值為 `"third-party"`1049* `plugin.name`：外掛程式的名稱。對於官方市場和內建捆綁之外的外掛程式，除非 `OTEL_LOG_TOOL_DETAILS=1`，否則值為 `"third-party"`

1025* `marketplace.name`：plugin 的安裝市場（如果已知）。在與 `plugin.name` 相同的條件下編輯為 `"third-party"`1050* `marketplace.name`：外掛程式的安裝來源市場（已知時）。在與 `plugin.name` 相同的條件下編輯為 `"third-party"`

1026* `plugin.version`：來自 plugin 清單的版本。僅當名稱未被編輯且清單宣告版本時才包含1051* `plugin.version`：來自外掛程式資訊清單的版本。僅當名稱未編輯且資訊清單宣告版本時才包含

1027* `plugin.scope`：plugin 的來源類別：`"official"`、`"community"`、`"org"`、`"user-local"` 或 `"default-bundle"`1052* `plugin.scope`：外掛程式的來源類別：`"official"`、`"community"`、`"org"`、`"user-local"` 或 `"default-bundle"`

1028* `enabled_via`：plugin 如何被啟用的方式：`"default-enable"`、`"org-policy"`、`"admin-install"`、`"seed-mount"` 或 `"user-install"`。值 `"admin-install"` 表示 plugin 在[**組織設定 > Plugins**](https://claude.ai/admin-settings/plugins)中為您的組織設定為必需或自動安裝。在 v2.1.246 之前，Claude Code 將這些 plugin 報告為 `"user-install"` 或 `"seed-mount"`1053* `enabled_via`：外掛程式啟用的方式：`"default-enable"`、`"org-policy"`、`"admin-install"`、`"seed-mount"` 或 `"user-install"`。`"admin-install"` 值表示外掛程式在[**組織設定 > 外掛程式**](https://claude.ai/admin-settings/plugins)中設定為您的組織所需或自動安裝。在 v2.1.246 之前，Claude Code 將這些外掛程式報告為 `"user-install"` 或 `"seed-mount"`

1029* `plugin_id_hash`：plugin 名稱和市場的確定性雜湊，僅傳送到您配置的匯出器。讓您計算整個環境中載入了多少個不同的第三方 plugin，而無需記錄其名稱。對於[從 claude.ai 同步的 plugin](/docs/zh-TW/plugins-reference#synced-plugins)，Claude Code 使用 claude.ai 為 plugin 報告的市場名稱或 `synced` 否則對 plugin 名稱進行雜湊。在 v2.1.246 之前，Claude Code 在雜湊中沒有使用 claude.ai 報告的市場名稱1054* `plugin_id_hash`：外掛程式名稱和市場的確定性雜湊，僅傳送到您設定的匯出器。可讓您計算整個車隊中載入的不同第三方外掛程式，而無需記錄其名稱。對於[從 claude.ai 同步的外掛程式](/docs/zh-TW/plugins-reference#synced-plugins)，Claude Code 使用 claude.ai 為外掛程式報告的市場名稱或 `synced` 雜湊外掛程式名稱。在 v2.1.246 之前，Claude Code 在雜湊中未使用 claude.ai 報告的市場名稱

1030* `has_hooks`：plugin 是否貢獻 hooks1055* `has_hooks`：外掛程式是否貢獻鉤子

1031* `has_mcp`：plugin 是否貢獻 MCP 伺服器1056* `has_mcp`：外掛程式是否貢獻 MCP 伺服器

1032* `host_owned_mcp`：當 SDK 主機管理此 plugin 的 MCP 連線且 Claude Code 跳過讀取 plugin 的 MCP 伺服器配置時為 `true`，否則為 `false`。需要 Claude Code v2.1.172 或更新版本1057* `host_owned_mcp`：當 SDK 主機管理此外掛程式的 MCP 連線且 Claude Code 跳過讀取外掛程式的 MCP 伺服器設定時為 `true`，否則為 `false`。需要 Claude Code v2.1.172 或更新版本

1033* `skill_path_count`：plugin 宣告的 skill 目錄數1058* `skill_path_count`：外掛程式宣告的技能目錄數

1034* `command_path_count`：plugin 宣告的命令目錄數1059* `command_path_count`：外掛程式宣告的命令目錄數

1035* `agent_path_count`：plugin 宣告的代理目錄數1060* `agent_path_count`：外掛程式宣告的代理程式目錄數

1036* `safe_mode`：當工作階段以 [`--safe-mode`](/docs/zh-TW/cli-reference) 啟動時為 `"true"`，否則為 `"false"`。在安全模式下，此事件僅報告配置的清單；plugin 的命令、skill、hooks 和 MCP 伺服器不會載入。需要 Claude Code v2.1.169 或更新版本1061* `safe_mode`：當工作階段以 [`--safe-mode`](/docs/zh-TW/cli-reference) 啟動時為 `"true"`，否則為 `"false"`。在安全模式中，此事件僅報告設定的清單；外掛程式的命令、技能、鉤子和 MCP 伺服器不會載入。需要 Claude Code v2.1.169 或更新版本

1037 1062

1038<h4 id="skill-activated-event">1063<h4 id="skill-activated-event">

1039 Skill 已啟動事件1064 技能已啟動事件

1040</h4>1065</h4>

1041 1066

1042當叫用 skill 時記錄，無論 Claude 是透過 Skill 工具呼叫它，還是您將其作為 `/` 命令執行。1067當叫用技能時記錄，無論 Claude 是透過技能工具呼叫它還是您將其作為 `/` 命令執行。

1043 1068

1044**事件名稱**：`claude_code.skill_activated`1069**事件名稱**：`claude_code.skill_activated`

1045 1070

1047 1072

1048* 所有[標準屬性](#standard-attributes)1073* 所有[標準屬性](#standard-attributes)

1049* `event.name`：`"skill_activated"`1074* `event.name`：`"skill_activated"`

1050* `event.timestamp`：ISO 8601 時間戳1075* `event.timestamp`：ISO 8601 時間戳記

1051* `event.sequence`：單調遞增計數器，用於排序工作階段內的事件1076* `event.sequence`：單調遞增的計數器，用於排序工作階段內的事件

1052* `skill.name`：Skill 的名稱。對於使用者定義和第三方 plugin skill，除非 `OTEL_LOG_TOOL_DETAILS=1`，否則值為預留位置 `"custom_skill"`1077* `skill.name`：技能的名稱。對於使用者定義和第三方外掛程式技能，除非 `OTEL_LOG_TOOL_DETAILS=1`，否則值為佔位符 `"custom_skill"`

1053* `invocation_trigger`：Skill 的觸發方式（`"user-slash"`、`"claude-proactive"` 或 `"nested-skill"`）1078* `invocation_trigger`：技能的觸發方式（`"user-slash"`、`"claude-proactive"` 或 `"nested-skill"`）

1054* `skill.source`：Skill 的載入位置（例如，`"bundled"`、`"userSettings"`、`"projectSettings"`、`"plugin"`）1079* `skill.source`：技能的載入來源（例如 `"bundled"`、`"userSettings"`、`"projectSettings"`、`"plugin"`）

1055* `skill.kind`：當 skill 是工作流程 skill 時為 `"workflow"`。否則不存在1080* `skill.kind`：當技能是工作流程技能時為 `"workflow"`。否則不存在

1056* `plugin.name`（當 `OTEL_LOG_TOOL_DETAILS=1` 或 plugin 來自官方市場時）：當 skill 由 plugin 提供時的擁有 plugin 名稱1081* `plugin.name`（當 `OTEL_LOG_TOOL_DETAILS=1` 或外掛程式來自官方市場時）：當技能由外掛程式提供時的擁有外掛程式的名稱

1057* `marketplace.name`（當 `OTEL_LOG_TOOL_DETAILS=1` 或 plugin 來自官方市場時）：當 skill 由 plugin 提供時，擁有 plugin 的安裝市場1082* `marketplace.name`（當 `OTEL_LOG_TOOL_DETAILS=1` 或外掛程式來自官方市場時）：當技能由外掛程式提供時，擁有外掛程式的安裝來源市場

1058 1083

1059<h4 id="at-mention-event">1084<h4 id="at-mention-event">

1060 @ 提及事件1085 @ 提及事件

1061</h4>1086</h4>

1062 1087

1063當 Claude Code 解析提示中的 `@` 提及時記錄。並非每個提及都會發出事件：早期退出路徑（例如權限拒絕、超大檔案、PDF 參考附件和目錄列表失敗）會在不記錄的情況下返回。1088當 Claude Code 解析提示中的 `@` 提及時記錄。並非每個提及都發出事件：早期退出路徑，例如權限拒絕、超大檔案、PDF 參考附件和目錄列表失敗，會在不記錄的情況下傳回。

1064 1089

1065**事件名稱**：`claude_code.at_mention`1090**事件名稱**：`claude_code.at_mention`

1066 1091

1068 1093

1069* 所有[標準屬性](#standard-attributes)1094* 所有[標準屬性](#standard-attributes)

1070* `event.name`：`"at_mention"`1095* `event.name`：`"at_mention"`

1071* `event.timestamp`：ISO 8601 時間戳1096* `event.timestamp`：ISO 8601 時間戳記

1072* `event.sequence`：單調遞增計數器，用於排序工作階段內的事件1097* `event.sequence`：單調遞增的計數器，用於排序工作階段內的事件

1073* `mention_type`：提及的類型（`"file"`、`"directory"`、`"agent"`、`"mcp_resource"`、`"peer"`）。值 `"peer"` 表示您提及了[您的其他 Claude Code 工作階段之一](/docs/zh-TW/cross-session-messaging)。需要 Claude Code v2.1.232 或更新版本1098* `mention_type`：提及的類型（`"file"`、`"directory"`、`"agent"`、`"mcp_resource"`、`"peer"`）。`"peer"` 值表示您提及了[您的其他 Claude Code 工作階段之一](/docs/zh-TW/cross-session-messaging)。需要 Claude Code v2.1.232 或更新版本

1074* `success`：提及是否成功解析（`"true"` 或 `"false"`）1099* `success`：提及是否成功解析（`"true"` 或 `"false"`）

1075 1100

1076<h4 id="api-retries-exhausted-event">1101<h4 id="api-retries-exhausted-event">

1085 1110

1086* 所有[標準屬性](#standard-attributes)1111* 所有[標準屬性](#standard-attributes)

1087* `event.name`：`"api_retries_exhausted"`1112* `event.name`：`"api_retries_exhausted"`

1088* `event.timestamp`：ISO 8601 時間戳1113* `event.timestamp`：ISO 8601 時間戳記

1089* `event.sequence`：單調遞增計數器，用於排序工作階段內的事件1114* `event.sequence`：單調遞增的計數器，用於排序工作階段內的事件

1090* `model`：使用的模型1115* `model`：使用的模型

1091* `error`：最終錯誤訊息1116* `error`：最終錯誤訊息

1092* `status_code`：HTTP 狀態碼（數字形式）。對於非 HTTP 錯誤，不存在。1117* `status_code`：HTTP 狀態碼作為數字。對於非 HTTP 錯誤不存在。

1093* `total_attempts`：進行的嘗試總次數1118* `total_attempts`：進行的嘗試總數

1094* `total_retry_duration_ms`：所有嘗試的總牆上時間1119* `total_retry_duration_ms`：所有嘗試的總掛鐘時間

1095* `speed`：`"fast"` 或 `"normal"`1120* `speed`：`"fast"` 或 `"normal"`

1096 1121

1097<h4 id="hook-registered-event">1122<h4 id="hook-registered-event">

1098 Hook 已註冊事件1123 鉤子已註冊事件

1099</h4>1124</h4>

1100 1125

1101在工作階段開始時為每個配置的 hook 記錄一次。使用此事件來清點您的整個環境中哪些 hook 是活躍的，作為每次執行 `hook_execution_start` 和 `hook_execution_complete` 事件的補充。1126在工作階段開始時針對每個設定的鉤子記錄一次。使用此事件來清點您的整個車隊中哪些鉤子有效，作為每次執行 `hook_execution_start` 和 `hook_execution_complete` 事件的補充。

1102 1127

1103**事件名稱**：`claude_code.hook_registered`1128**事件名稱**：`claude_code.hook_registered`

1104 1129

1106 1131

1107* 所有[標準屬性](#standard-attributes)1132* 所有[標準屬性](#standard-attributes)

1108* `event.name`：`"hook_registered"`1133* `event.name`：`"hook_registered"`

1109* `event.timestamp`：ISO 8601 時間戳1134* `event.timestamp`：ISO 8601 時間戳記

1110* `event.sequence`：單調遞增計數器，用於排序工作階段內的事件1135* `event.sequence`：單調遞增的計數器，用於排序工作階段內的事件

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

1112* `hook_type`：hook 實作類型：`"command"`、`"prompt"`、`"mcp_tool"`、`"http"` 或 `"agent"`1137* `hook_type`：鉤子實作類型：`"command"`、`"prompt"`、`"mcp_tool"`、`"http"` 或 `"agent"`

1113* `hook_source`：hook 的定義位置：`"userSettings"`、`"projectSettings"`、`"localSettings"`、`"flagSettings"`、`"policySettings"` 或 `"pluginHook"`1138* `hook_source`：鉤子的定義位置：`"userSettings"`、`"projectSettings"`、`"localSettings"`、`"flagSettings"`、`"policySettings"` 或 `"pluginHook"`

1114* `safe_mode`：當工作階段以 [`--safe-mode`](/docs/zh-TW/cli-reference) 啟動時為 `"true"`，否則為 `"false"`。需要 Claude Code v2.1.169 或更新版本1139* `safe_mode`：當工作階段以 [`--safe-mode`](/docs/zh-TW/cli-reference) 啟動時為 `"true"`，否則為 `"false"`。需要 Claude Code v2.1.169 或更新版本

1115* `hook_matcher`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：hook 配置中的匹配器字串（如果已設定）1140* `hook_matcher`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：鉤子設定中的匹配器字串（已設定時）

1116* `plugin.name`（當 `hook_source` 是 `"pluginHook"` 時）：貢獻 plugin 的名稱。對於官方市場和內建捆綁之外的 plugin，除非 `OTEL_LOG_TOOL_DETAILS=1`，否則值為 `"third-party"`1141* `plugin.name`（當 `hook_source` 為 `"pluginHook"` 時）：貢獻外掛程式的名稱。對於官方市場和內建捆綁之外的外掛程式，除非 `OTEL_LOG_TOOL_DETAILS=1`，否則值為 `"third-party"`

1117* `plugin_id_hash`（當 `hook_source` 是 `"pluginHook"` 時）：plugin 名稱和市場的確定性雜湊，僅傳送到您配置的匯出器。讓您計算不同的貢獻 plugin，而無需記錄其名稱。Claude Code 按[plugin 已載入事件](#plugin-loaded-event)下所述計算它1142* `plugin_id_hash`（當 `hook_source` 為 `"pluginHook"` 時）：外掛程式名稱和市場的確定性雜湊，僅傳送到您設定的匯出器。可讓您計算不同的貢獻外掛程式而無需記錄其名稱。Claude Code 按[外掛程式載入事件](#plugin-loaded-event)下所述計算它

1118 1143

1119<h4 id="hook-execution-start-event">1144<h4 id="hook-execution-start-event">

1120 Hook 執行開始事件1145 鉤子執行開始事件

1121</h4>1146</h4>

1122 1147

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

1124 1149

1125**事件名稱**：`claude_code.hook_execution_start`1150**事件名稱**：`claude_code.hook_execution_start`

1126 1151

1128 1153

1129* 所有[標準屬性](#standard-attributes)1154* 所有[標準屬性](#standard-attributes)

1130* `event.name`：`"hook_execution_start"`1155* `event.name`：`"hook_execution_start"`

1131* `event.timestamp`：ISO 8601 時間戳1156* `event.timestamp`：ISO 8601 時間戳記

1132* `event.sequence`：單調遞增計數器，用於排序工作階段內的事件1157* `event.sequence`：單調遞增的計數器，用於排序工作階段內的事件

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

1134* `hook_name`：完整 hook 名稱，包括匹配器，例如 `"PreToolUse:Write"`1159* `hook_name`：完整鉤子名稱，包括匹配器，例如 `"PreToolUse:Write"`

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

1136* `managed_only`：當僅允許受管原則 hook 時為 `"true"`1161* `managed_only`：當僅允許受管原則鉤子時為 `"true"`

1137* `hook_source`：`"policySettings"` 或 `"merged"`1162* `hook_source`：`"policySettings"` 或 `"merged"`

1138* `safe_mode`：當工作階段以 [`--safe-mode`](/docs/zh-TW/cli-reference) 啟動時為 `"true"`，否則為 `"false"`。需要 Claude Code v2.1.169 或更新版本1163* `safe_mode`：當工作階段以 [`--safe-mode`](/docs/zh-TW/cli-reference) 啟動時為 `"true"`，否則為 `"false"`。需要 Claude Code v2.1.169 或更新版本

1139* `hook_definitions`：JSON 序列化的 hook 配置。僅當詳細 beta 追蹤和 `OTEL_LOG_TOOL_DETAILS=1` 都啟用時才包含1164* `hook_definitions`：JSON 序列化的鉤子設定。僅當啟用詳細 Beta 追蹤和 `OTEL_LOG_TOOL_DETAILS=1` 時才包含

1140 1165

1141<h4 id="hook-execution-complete-event">1166<h4 id="hook-execution-complete-event">

1142 Hook 執行完成事件1167 鉤子執行完成事件

1143</h4>1168</h4>

1144 1169

1145當 hook 事件的所有 hook 完成時記錄。1170當鉤子事件的所有鉤子完成時記錄。

1146 1171

1147**事件名稱**：`claude_code.hook_execution_complete`1172**事件名稱**：`claude_code.hook_execution_complete`

1148 1173

1150 1175

1151* 所有[標準屬性](#standard-attributes)1176* 所有[標準屬性](#standard-attributes)

1152* `event.name`：`"hook_execution_complete"`1177* `event.name`：`"hook_execution_complete"`

1153* `event.timestamp`：ISO 8601 時間戳1178* `event.timestamp`：ISO 8601 時間戳記

1154* `event.sequence`：單調遞增計數器，用於排序工作階段內的事件1179* `event.sequence`：單調遞增的計數器，用於排序工作階段內的事件

1155* `hook_event`：Hook 事件類型1180* `hook_event`：鉤子事件類型

1156* `hook_name`：完整 hook 名稱，包括匹配器1181* `hook_name`：完整鉤子名稱，包括匹配器

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

1158* `num_success`：成功完成的計數1183* `num_success`：成功完成的計數

1159* `num_blocking`：傳回阻止決定的計數1184* `num_blocking`：傳回阻止決定的計數

1160* `num_non_blocking_error`：在不阻止的情況下失敗的計數1185* `num_non_blocking_error`：在不阻止的情況下失敗的計數

1161* `num_cancelled`：在完成前取消的計數1186* `num_cancelled`：在完成前取消的計數

1162* `total_duration_ms`：所有匹配 hook 的牆上時間持續時間1187* `total_duration_ms`：所有相符鉤子的掛鐘持續時間

1163* `managed_only`：當僅允許受管原則 hook 時為 `"true"`1188* `managed_only`：當僅允許受管原則鉤子時為 `"true"`

1164* `hook_source`：`"policySettings"` 或 `"merged"`1189* `hook_source`：`"policySettings"` 或 `"merged"`

1165* `safe_mode`：當工作階段以 [`--safe-mode`](/docs/zh-TW/cli-reference) 啟動時為 `"true"`，否則為 `"false"`。需要 Claude Code v2.1.169 或更新版本1190* `safe_mode`：當工作階段以 [`--safe-mode`](/docs/zh-TW/cli-reference) 啟動時為 `"true"`，否則為 `"false"`。需要 Claude Code v2.1.169 或更新版本

1166* `hook_definitions`：JSON 序列化的 hook 配置。僅當詳細 beta 追蹤和 `OTEL_LOG_TOOL_DETAILS=1` 都啟用時才包含1191* `hook_definitions`：JSON 序列化的鉤子設定。僅當啟用詳細 Beta 追蹤和 `OTEL_LOG_TOOL_DETAILS=1` 時才包含

1167 1192

1168<h4 id="hook-plugin-metrics-event">1193<h4 id="hook-plugin-metrics-event">

1169 Hook plugin 指標事件1194 鉤子外掛程式指標事件

1170</h4>1195</h4>

1171 1196

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

1173 1198

1174**事件名稱**：`claude_code.hook_plugin_metrics`1199**事件名稱**：`claude_code.hook_plugin_metrics`

1175 1200

1177 1202

1178* 所有[標準屬性](#standard-attributes)1203* 所有[標準屬性](#standard-attributes)

1179* `event.name`：`"hook_plugin_metrics"`1204* `event.name`：`"hook_plugin_metrics"`

1180* `event.timestamp`：ISO 8601 時間戳1205* `event.timestamp`：ISO 8601 時間戳記

1181* `event.sequence`：單調遞增計數器，用於排序工作階段內的事件1206* `event.sequence`：單調遞增的計數器，用於排序工作階段內的事件

1182* `plugin_id`：plugin 識別碼，格式為 `<name>@<marketplace>`1207* `plugin_id`：`<name>@<marketplace>` 形式的外掛程式識別碼

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

1184* 最多 20 個 plugin 發出的指標鍵。名稱符合 `^[a-z][a-z0-9_]{0,39}$`。值為布林值或數字。1209* 最多 20 個外掛程式發出的指標金鑰。名稱符合 `^[a-z][a-z0-9_]{0,39}$`。值為布林值或數字。

1185 1210

1186<h4 id="compaction-event">1211<h4 id="compaction-event">

1187 壓縮事件1212 壓縮事件

1195 1220

1196* 所有[標準屬性](#standard-attributes)1221* 所有[標準屬性](#standard-attributes)

1197* `event.name`：`"compaction"`1222* `event.name`：`"compaction"`

1198* `event.timestamp`：ISO 8601 時間戳1223* `event.timestamp`：ISO 8601 時間戳記

1199* `event.sequence`：單調遞增計數器，用於排序工作階段內的事件1224* `event.sequence`：單調遞增的計數器，用於排序工作階段內的事件

1200* `trigger`：`"auto"` 或 `"manual"`1225* `trigger`：`"auto"` 或 `"manual"`

1201* `success`：`"true"` 或 `"false"`1226* `success`：`"true"` 或 `"false"`

1202* `duration_ms`：壓縮持續時間1227* `duration_ms`：壓縮持續時間

1203* `pre_tokens`：壓縮前的近似權杖計數1228* `pre_tokens`：壓縮前的近似權杖計數

1204* `post_tokens`：壓縮後的近似權杖計數1229* `post_tokens`：壓縮後的近似權杖計數

1205* `error`：壓縮失敗時的錯誤訊息1230* `error`：壓縮失敗時的錯誤訊息

1206* `precompute_reuse`：僅在 `trigger` 為 `"manual"` 時設定。自動壓縮可以在內容視窗填滿之前在背景中準備摘要，此屬性記錄 `/compact` 是否重複使用該準備的摘要。`"hit"` 表示它被重複使用；`"miss_custom_instructions"`、`"miss_hook"` 和 `"miss_not_ready"` 給出改為計算新摘要的原因。需要 Claude Code v2.1.153 或更新版本1231* `precompute_reuse`：僅在 `trigger` 為 `"manual"` 時設定。自動壓縮可以在內容視窗填滿之前在背景中準備摘要，此屬性記錄 `/compact` 是否重用該準備的摘要。`"hit"` 表示它被重用；`"miss_custom_instructions"`、`"miss_hook"` 和 `"miss_not_ready"` 給出改為計算新摘要的原因。需要 Claude Code v2.1.153 或更新版本

1207 1232

1208<h4 id="subagent-completed-event">1233<h4 id="subagent-completed-event">

1209 子代理已完成事件1234 子代理程式已完成事件

1210</h4>1235</h4>

1211 1236

1212當[子代理](/docs/zh-TW/sub-agents)完成並將其結果傳回啟動它的對話時記錄。使用它按子代理類型匯總工具使用和執行時間；對於權杖或成本匯總，使用[權杖計數器](#token-counter)和[成本計數器](#cost-counter)篩選到 `query_source` `"subagent"`，因為此事件的 `total_tokens` 僅涵蓋最終請求。`"subagent"` 類別也計算來自代理型 hooks 的請求，不發出子代理事件。1237當[子代理程式](/docs/zh-TW/sub-agents)完成並將其結果傳回啟動它的對話時記錄。使用它按子代理程式類型匯總工具使用和執行時間；對於權杖或成本匯總，使用[權杖計數器](#token-counter)和[成本計數器](#cost-counter)篩選到 `query_source` `"subagent"`，因為此事件的 `total_tokens` 僅涵蓋最終請求。`"subagent"` 類別也計算來自代理程式型鉤子的請求，它不發出子代理程式事件。

1213 1238

1214**事件名稱**：`claude_code.subagent_completed`1239**事件名稱**：`claude_code.subagent_completed`

1215 1240

1217 1242

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

1219* `event.name`：`"subagent_completed"`1244* `event.name`：`"subagent_completed"`

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

1221* `event.sequence`：單調遞增計數器，用於排序工作階段內的事件1246* `event.sequence`：單調遞增的計數器，用於排序工作階段內的事件

1222* `agent_type`：子代理類型。內建代理名稱和官方市場 plugin 的代理按原樣出現；其他代理名稱除非 `OTEL_LOG_TOOL_DETAILS=1` 設定，否則被替換為 `"custom"`1247* `agent_type`：子代理程式類型。內建代理程式名稱和來自官方市場外掛程式的代理程式逐字出現；其他代理程式名稱會被替換為 `"custom"`，除非設定了 `OTEL_LOG_TOOL_DETAILS=1`

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

1224* `is_built_in`：子代理是否為內建代理類型1249* `is_built_in`：子代理程式是否為內建代理程式類型

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

1226* `total_tokens`：子代理最終 API 請求的權杖足跡：該單個請求的輸入、快取建立、快取讀取和輸出權杖，大約是子代理在完成時的內容大小。不是整個執行的總和1251* `total_tokens`：子代理程式最終 API 請求的權杖足跡：該一個請求的輸入、快取建立、快取讀取和輸出權杖，大約是子代理程式在完成時的內容大小。不是整個執行的總和

1227* `total_tool_uses`：子代理在整個執行中進行的工具呼叫數1252* `total_tool_uses`：子代理程式在整個執行過程中進行的工具呼叫數

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

1229* `model`：子代理被解析為執行的模型1254* `model`：子代理程式解析為執行的模型

1230* `final_model`：產生子代理最終回應的模型，在中途切換（例如後備）後與 `model` 不同。需要 Claude Code v2.1.212 或更新版本1255* `final_model`：產生子代理程式最終回應的模型，在回退等中途切換後與 `model` 不同。需要 Claude Code v2.1.212 或更新版本

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

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

1233 1258

1234<h4 id="feedback-survey-event">1259<h4 id="feedback-survey-event">

1235 回饋調查事件1260 意見反應調查事件

1236</h4>1261</h4>

1237 1262

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

1239 1264

1240**事件名稱**：`claude_code.feedback_survey`1265**事件名稱**：`claude_code.feedback_survey`

1241 1266

1243 1268

1244* 所有[標準屬性](#standard-attributes)1269* 所有[標準屬性](#standard-attributes)

1245* `event.name`：`"feedback_survey"`1270* `event.name`：`"feedback_survey"`

1246* `event.timestamp`：ISO 8601 時間戳1271* `event.timestamp`：ISO 8601 時間戳記

1247* `event.sequence`：單調遞增計數器，用於排序工作階段內的事件1272* `event.sequence`：單調遞增的計數器，用於排序工作階段內的事件

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

1249* `appearance_id`：唯一 ID，連結為一個調查實例發出的事件1274* `appearance_id`：唯一 ID，連結為一個調查實例發出的事件

1250* `survey_type`：哪個調查產生了事件。`"session"` 是「Claude 表現如何？」評分提示1275* `survey_type`：哪個調查產生事件。`"session"` 是「Claude 做得如何？」評分提示

1251* `response`：使用者在 `responded` 事件上的選擇1276* `response`：使用者在 `responded` 事件上的選擇

1252* `enabled_via_override`：當設定 [`CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL`](/docs/zh-TW/env-vars) 時為 `true`。作為布林值而非字串發出。存在於 `session` 調查事件上。篩選此屬性以確認覆蓋在整個環境中應用1277* `enabled_via_override`：當設定了 [`CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL`](/docs/zh-TW/env-vars) 時為 `true`。作為布林值而非字串發出。出現在 `session` 調查事件上。篩選此屬性以確認整個車隊中套用了覆蓋

1253 1278

1254<h4 id="retention-sweep-event">1279<h4 id="retention-sweep-event">

1255 保留掃描事件1280 保留期掃描事件

1256</h4>1281</h4>

1257 1282

1258在保留清理掃描執行時記錄一次，該掃描刪除[工作階段文字記錄和其他應用程式資料](/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 不會執行掃描且不會發出任何內容。1283在保留期清理掃描執行時記錄一次，該掃描刪除[工作階段文字記錄和其他應用程式資料](/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 不會執行掃描，也不會發出任何內容。

1259 1284

1260與此頁面上的每個 OTel 事件一樣，它僅進入您配置的遙測後端。需要 Claude Code v2.1.227 或更新版本。1285與此頁面上的每個 OTel 事件一樣，它僅流向您設定的遙測後端。需要 Claude Code v2.1.227 或更新版本。

1261 1286

1262當 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"` 時存在。1287當 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"` 時存在。

1263 1288

1264**事件名稱**：`claude_code.retention_sweep`1289**事件名稱**：`claude_code.retention_sweep`

1265 1290

1267 1292

1268* 所有[標準屬性](#standard-attributes)1293* 所有[標準屬性](#standard-attributes)

1269* `event.name`：`"retention_sweep"`1294* `event.name`：`"retention_sweep"`

1270* `event.timestamp`：ISO 8601 時間戳1295* `event.timestamp`：ISO 8601 時間戳記

1271* `event.sequence`：單調遞增計數器，用於排序工作階段內的事件1296* `event.sequence`：單調遞增的計數器，用於排序工作階段內的事件

1272* `result`：掃描執行時為 `"complete"`，Claude Code 暫停時為 `"skipped"`1297* `result`：掃描執行時為 `"complete"`，Claude Code 暫停時為 `"skipped"`

1273* `period_days`：合併設定中的 `cleanupPeriodDays` 值（以天為單位），或當沒有來源設定時為 `30`。在跳過的事件上，掃描會使用的值，從 Claude Code 可以讀取的設定來源計算1298* `period_days`：來自合併設定的 `cleanupPeriodDays` 值（以天為單位），或當沒有來源設定時為 `30`。在跳過的事件上，掃描會使用的值，從 Claude Code 可以讀取的設定來源計算

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

1275* `skip_reason`：Claude Code 暫停掃描的原因。僅當 `result` 為 `"skipped"` 時存在：1300* `skip_reason`：Claude Code 暫停掃描的原因。僅當 `result` 為 `"skipped"` 時存在：

1276 * `"user_source_disabled"`：使用者設定被排除，例如透過 [`--setting-sources`](/docs/zh-TW/cli-reference#cli-flags) 旗標或 SDK 的 [`settingSources`](/docs/zh-TW/agent-sdk/typescript#options) 選項，且沒有啟用的來源提供 `cleanupPeriodDays`1301 * `"user_source_disabled"`：使用者設定被排除，例如透過 [`--setting-sources`](/docs/zh-TW/cli-reference#cli-flags) 旗標或 SDK 的 [`settingSources`](/docs/zh-TW/agent-sdk/typescript#options) 選項，且沒有啟用的來源提供 `cleanupPeriodDays`

1277 * `"settings_unknowable"`：設定檔案無法讀取或解析，因此 `cleanupPeriodDays` 或 `desktopSessionCleanupPeriodDays` 可能設定為 Claude Code 無法看到的值1302 * `"settings_unknowable"`：設定檔案無法讀取或解析，因此 `cleanupPeriodDays` 或 `desktopSessionCleanupPeriodDays` 可能設定為 Claude Code 無法看到的值

1278 * `"settings_invalid_key_set"`：設定有驗證錯誤且 `cleanupPeriodDays` 或 `desktopSessionCleanupPeriodDays` 被明確設定，因此回退到預設值可能會刪除或保留違反該設定的檔案1303 * `"settings_invalid_key_set"`：設定有驗證錯誤且 `cleanupPeriodDays` 或 `desktopSessionCleanupPeriodDays` 已明確設定，因此回退到預設值可能會刪除或保留針對該設定的檔案

1279* `transcripts_deleted`：掃描刪除的工作階段文字記錄數，頂級 `~/.claude/projects/*/*.jsonl` 檔案1304* `transcripts_deleted`：掃描刪除的工作階段文字記錄（頂層 `~/.claude/projects/*/*.jsonl` 檔案）數

1280* `transcripts_exempted_desktop`：超過保留期的文字記錄數，掃描在[Claude Desktop 和 Cowork 規則](/docs/zh-TW/claude-directory#cleaned-up-automatically)下保留。這些不計入 `files_past_cutoff`。需要 Claude Code v2.1.248 或更新版本1305* `transcripts_exempted_desktop`：超過保留期的文字記錄數，掃描在 [Claude Desktop 和 Cowork 規則](/docs/zh-TW/claude-directory#cleaned-up-automatically)下保留。這些不計入 `files_past_cutoff`。需要 Claude Code v2.1.248 或更新版本

1281* `session_files_deleted`：工作階段檔案掃描刪除的項目數：文字記錄加每個工作階段的伴隨檔案，例如邊車、錄製和工具結果1306* `session_files_deleted`：工作階段檔案掃描刪除的成品數：文字記錄加上每個工作階段的伴隨檔案，例如邊車、錄製和工具結果

1282* `artifacts_deleted`：掃描跨越其涵蓋的資料目錄刪除的總項目，包括工作階段檔案。某些掃描將整個移除的目錄樹計為一個項目，少數清理通過不貢獻計數器，因此將值視為下限而不是精確檔案計數1307* `artifacts_deleted`：掃描跨越的資料目錄刪除的總項目，包括工作階段檔案。某些掃描將整個移除的目錄樹計為一個項目，少數清理通過不貢獻計數器，因此將值視為下限而非精確檔案計數

1283* `files_retained_fresh`：檢查並保留在原位的檔案，因為它們仍在保留期內。僅每個檔案掃描計算這些，因此值是下限；非零值是正常穩定狀態1308* `files_retained_fresh`：檢查並保留在原位的檔案，因為它們仍在保留期內。僅每個檔案掃描計算這些，因此值是下限；非零值是正常穩定狀態

1284* `files_past_cutoff`：超過保留期的檔案，掃描無法刪除，例如因為權限錯誤或檔案被保持開啟。值高於零表示檔案超過配置的保留期；零不是證明沒有任何檔案，因為整個目錄的失敗移除計入 `error_count` 代替1309* `files_past_cutoff`：早於保留期的檔案，掃描無法刪除，例如因為權限錯誤或檔案被保持開啟。值高於零表示檔案超過了設定的保留期；零不是沒有任何檔案的證明，因為整個目錄的移除失敗計入 `error_count`

1285* `error_count`：掃描在列出或刪除檔案時遇到的錯誤數1310* `error_count`：掃描在列出或刪除檔案時遇到的錯誤數

1286 1311

1287<h2 id="interpret-metrics-and-events-data">1312<h2 id="interpret-metrics-and-events-data">

permissions.md +3 −1

Details

67 67

68一個廣泛的 deny 規則（例如 `Bash(aws *)`）會阻止每個符合的呼叫，包括也符合較窄 allow 規則（例如 `Bash(aws s3 ls)`）的呼叫，因此 deny 規則無法攜帶允許清單例外。ask 和 allow 之間也適用相同的優先順序：符合的 ask 規則即使有更具體的 allow 規則也符合相同的呼叫時，也會提示。68一個廣泛的 deny 規則（例如 `Bash(aws *)`）會阻止每個符合的呼叫，包括也符合較窄 allow 規則（例如 `Bash(aws s3 ls)`）的呼叫，因此 deny 規則無法攜帶允許清單例外。ask 和 allow 之間也適用相同的優先順序：符合的 ask 規則即使有更具體的 allow 規則也符合相同的呼叫時，也會提示。

69 69

70Deny 規則的行為取決於它們是否命名工具或在工具內限定模式。像 `Bash` 這樣的裸工具名稱會將工具從 Claude 的上下文中完全移除，因此 Claude 永遠看不到它。裸名稱移除適用於除了 [`EndConversation`](/docs/zh-TW/tools-reference#endconversation-tool-behavior) 之外的每個工具：deny 規則在任何其他工具仍然存在時無法移除它，ask 規則永遠不會為它提示。像 `Bash(rm *)` 這樣的限定規則會保留工具可用性，並在 Claude 嘗試時阻止符合的呼叫。70Deny 規則的行為取決於它們是否命名工具或在工具內限定模式。像 `Bash` 這樣的裸工具名稱會將工具從 Claude 的上下文中完全移除，因此 Claude 永遠看不到它。如果您在工作階段中途新增此類規則，Claude 無法從其下一個工具呼叫開始呼叫該工具；[拒絕整個工具](/docs/zh-TW/prompt-caching#denying-an-entire-tool)涵蓋 Claude 已經看過的定義會發生什麼。像 `Bash(rm *)` 這樣的限定規則會保留工具可用性，並在 Claude 嘗試時阻止符合的呼叫。

72裸名稱移除適用於除了 [`EndConversation`](/docs/zh-TW/tools-reference#endconversation-tool-behavior) 之外的每個工具：deny 規則在任何其他工具仍然存在時無法移除它，ask 規則永遠不會為它提示。

71 73

72<Note>74<Note>

73 權限規則由 Claude Code 強制執行，而不是由模型強制執行。您的提示或 `CLAUDE.md` 中的指令會影響 Claude 嘗試執行的操作，但不會改變 Claude Code 允許的操作。若要授予或撤銷存取權限，請使用 `/permissions`、此處描述的規則、[permission mode](/docs/zh-TW/permission-modes) 或 [PreToolUse hook](#extend-permissions-with-hooks)。75 權限規則由 Claude Code 強制執行，而不是由模型強制執行。您的提示或 `CLAUDE.md` 中的指令會影響 Claude 嘗試執行的操作，但不會改變 Claude Code 允許的操作。若要授予或撤銷存取權限，請使用 `/permissions`、此處描述的規則、[permission mode](/docs/zh-TW/permission-modes) 或 [PreToolUse hook](#extend-permissions-with-hooks)。

plugin-marketplaces.md +504 −104

Details

63 {63 {

64 "name": "quality-review-plugin",64 "name": "quality-review-plugin",

65 "description": "新增 quality-review skill 以進行快速程式碼審查",65 "description": "新增 quality-review skill 以進行快速程式碼審查",

~~66 "version": "1.0.0"~~66 "version": "1.0.0",

67 "author": {

68 "name": "Your Name"

69 }

67 }70 }

68 ```71 ```

69 72

70 <Note>73 <Note>

71 設定 `version` 表示使用者只會在您變更此欄位時收到更新，因此在每次發行時都要提升版本。如果您省略 `version` 並在 git 中託管此 marketplace，每次提交都會自動計為新版本。請參閱 [Version resolution](#version-resolution-and-release-channels) 以選擇正確的方法。74 設定 `version` 表示使用者只會在您變更此欄位時收到更新，因此在每次發行時都要提升版本。具有 `command` 來源的 plugin 不會由此欄位固定。如果您省略 `version`，版本會來自[版本管理](/docs/zh-TW/plugins-reference#version-management)中的下一個來源。

72 </Note>75 </Note>

73 </Step>76 </Step>

74 77

93 </Step>96 </Step>

94 97

95 <Step title="新增並安裝">98 <Step title="新增並安裝">

~~96 新增 marketplace 並安裝 plugin。~~99 從包含 `my-marketplace` 的目錄啟動 Claude Code 並執行下列命令。安裝命令會開啟 plugin 詳細資訊檢視，您可以在其中選擇安裝範圍以確認安裝。檢查安裝摘要：如果它報告 `Run /reload-plugins to activate.`，請參閱[不重新啟動即可套用 plugin 變更](/docs/zh-TW/discover-plugins#apply-plugin-changes-without-restarting)。

97 100

98 ```shell theme={null}101 ```shell theme={null}

99 /plugin marketplace add ./my-marketplace102 /plugin marketplace add ./my-marketplace

113若要深入瞭解 plugin 可以執行的操作，包括 hooks、agents、MCP servers 和 LSP servers，請參閱 [Plugins](/docs/zh-TW/plugins)。116若要深入瞭解 plugin 可以執行的操作，包括 hooks、agents、MCP servers 和 LSP servers，請參閱 [Plugins](/docs/zh-TW/plugins)。

114 117

115<Note>118<Note>

116 **plugin 如何安裝**：當使用者安裝 plugin 時，Claude Code 會將 plugin 目錄複製到快取位置。這表示 plugin 無法使用 `../shared-utils` 之類的路徑參考其目錄外的檔案，因為這些檔案不會被複製。119 **plugin 如何安裝**：當使用者安裝 plugin 時，Claude Code 會將 plugin 目錄複製到快取位置，除了[連結模式](#copy-mode-and-link-mode)中的 `command` 來源（會被就地使用）。複製的 plugin 無法使用 `../shared-utils` 之類的路徑參考其目錄外的檔案，因為這些檔案不會被複製。

117 120

118 如果您需要在 plugin 之間共享檔案，請使用符號連結。有關詳細資訊，請參閱 [Plugin caching and file resolution](/docs/zh-TW/plugins-reference#plugin-caching-and-file-resolution)。121 如果您需要在 plugin 之間共享檔案，請使用符號連結。有關詳細資訊，請參閱 [Plugin caching and file resolution](/docs/zh-TW/plugins-reference#plugin-caching-and-file-resolution)。

119</Note>122</Note>

164</h3>167</h3>

165 168

166| 欄位 | 類型 | 描述 | 範例 |169| 欄位 | 類型 | 描述 | 範例 |

167| :-------- | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------- |170| :-------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------- |

168| `name` | string | Marketplace 識別碼（kebab-case，無空格）。這是公開的：使用者在安裝 plugin 時會看到它（例如，`/plugin install my-tool@your-marketplace`）。每個使用者只能為每個名稱註冊一個 marketplace：新增第二個同名 marketplace 會取代第一個。若要在一個 marketplace 名稱下發佈多個 plugin，請在[單一 `marketplace.json`](#create-the-marketplace-file) 中列出它們全部。 | `"acme-tools"` |171| `name` | string | Marketplace 識別碼（kebab-case，無空格、控制字元或雙向格式化字元）。這是公開的：使用者在安裝 plugin 時會看到它（例如，`/plugin install my-tool@your-marketplace`）。每個使用者只能為每個名稱註冊一個 marketplace：新增第二個同名 marketplace 會取代第一個。若要在一個 marketplace 名稱下發佈多個 plugin，請在[單一 `marketplace.json`](#create-the-marketplace-file) 中列出它們全部。 | `"acme-tools"` |

171 174

172<Note>175<Note>

173 **保留名稱**：以下 marketplace 名稱保留供 Anthropic 官方使用，第三方 marketplace 無法使用：`claude-code-marketplace`、`claude-code-plugins`、`claude-plugins-official`、`claude-plugins-community`、`claude-community`、`anthropic-marketplace`、`anthropic-plugins`、`agent-skills`、`anthropic-agent-skills`、`knowledge-work-plugins`、`life-sciences`、`claude-for-legal`、`claude-for-financial-services`、`financial-services-plugins`、`first-party-plugins`、`healthcare`。模仿官方 marketplace 的名稱（如 `official-claude-plugins` 或 `anthropic-plugins-v2`）也被阻止。保留這些名稱可防止第三方 marketplace 將自己冒充為 Anthropic 發佈的來源。176 **保留名稱**：以下 marketplace 名稱保留供 Anthropic 官方使用，第三方 marketplace 無法使用：`claude-code-marketplace`、`claude-code-plugins`、`claude-plugins-official`、`claude-plugins-community`、`claude-community`、`anthropic-marketplace`、`anthropic-plugins`、`agent-skills`、`anthropic-agent-skills`、`knowledge-work-plugins`、`life-sciences`、`claude-for-legal`、`claude-for-financial-services`、`financial-services-plugins`、`first-party-plugins`、`claude-tag-plugins`、`healthcare`。模仿官方 marketplace 的名稱（如 `official-claude-plugins` 或 `anthropic-plugins-v2`）也被阻止。保留這些名稱可防止第三方 marketplace 將自己冒充為 Anthropic 發佈的來源。

174 177

175 Claude Code 每次載入 marketplace 時都會重新檢查保留名稱，而不僅在您新增 marketplace 時檢查。在名稱成為保留名稱之前以其中一個名稱註冊的 marketplace 會停止載入，並報告它是[從不受信任的來源註冊](/docs/zh-TW/errors#marketplace-is-registered-from-an-untrusted-source)。移除該 marketplace，並從官方 Anthropic 來源重新新增它。受新保留名稱影響的第三方 marketplace 在您以不同名稱重新新增它後立即再次載入。在 v2.1.205 之前，`first-party-plugins` 和 `healthcare` 未被保留，已在保留名稱下註冊的 marketplace 繼續載入。178 Claude Code 每次載入 marketplace 時都會重新檢查保留名稱，而不僅在您新增 marketplace 時檢查。在名稱成為保留名稱之前以其中一個名稱註冊的 marketplace 會停止載入，並報告它是[從不受信任的來源註冊](/docs/zh-TW/errors#marketplace-is-registered-from-an-untrusted-source)。移除該 marketplace，並從官方 Anthropic 來源重新新增它。受新保留名稱影響的第三方 marketplace 在您以不同名稱重新新增它後立即再次載入。在 v2.1.205 之前，`first-party-plugins` 和 `healthcare` 未被保留，已在保留名稱下註冊的 marketplace 繼續載入。在 v2.1.265 之前，`claude-tag-plugins` 未被保留。

176</Note>179</Note>

177 180

178<h3 id="owner-fields">181<h3 id="owner-fields">

180</h3>183</h3>

181 184

182| 欄位 | 類型 | 必需 | 描述 |185| 欄位 | 類型 | 必需 | 描述 |

183| :------ | :----- | :- | :--------- |186| :------ | :----- | :- | :-------------------- |

189| `url` | string | 否 | 網站、GitHub 個人檔案或組織 URL |

186 190

187<h3 id="optional-fields">191<h3 id="optional-fields">

188 選用欄位192 選用欄位

197| `allowCrossMarketplaceDependenciesOn` | array | 此 marketplace 中的 plugin 可能依賴的其他 marketplace。來自此處未列出的 marketplace 的相依性在安裝時被阻止。請參閱[依賴來自另一個 marketplace 的 plugin](/docs/zh-TW/plugin-dependencies#depend-on-a-plugin-from-another-marketplace)。 |201| `allowCrossMarketplaceDependenciesOn` | array | 此 marketplace 中的 plugin 可能依賴的其他 marketplace。來自此處未列出的 marketplace 的相依性在安裝時被阻止。請參閱[依賴來自另一個 marketplace 的 plugin](/docs/zh-TW/plugin-dependencies#depend-on-a-plugin-from-another-marketplace)。 |

198| `renames` | object | 從前一個 plugin `name` 對應到其目前名稱，或對應到 `null`（如果 plugin 已移除）的對應。當您重新命名或移除 `plugins` 中的項目時，可讓現有使用者自動遷移。請參閱[重新命名或移除 plugin](#rename-or-remove-a-plugin)。需要 Claude Code v2.1.193 或更新版本。 |202| `renames` | object | 從前一個 plugin `name` 對應到其目前名稱，或對應到 `null`（如果 plugin 已移除）的對應。當您重新命名或移除 `plugins` 中的項目時，可讓現有使用者自動遷移。請參閱[重新命名或移除 plugin](#rename-or-remove-a-plugin)。需要 Claude Code v2.1.193 或更新版本。 |

199 203

203 Plugin 項目207 Plugin 項目

204</h2>208</h2>

205 209

206`plugins` 陣列中的每個 plugin 項目描述一個 plugin 及其位置。您可以包含 [plugin manifest 架構](/docs/zh-TW/plugins-reference#plugin-manifest-schema)中的任何欄位（如 `description`、`version`、`author`、`commands`、`hooks` 等），加上這些 marketplace 特定欄位：`source`、`category`、`tags`、`strict` 和 `relevance`。210`plugins` 陣列中的每個 plugin 項目描述一個 plugin 及其位置。您可以包含 [plugin manifest 架構](/docs/zh-TW/plugins-reference#plugin-manifest-schema)中的任何欄位，例如 `description`、`version`、`author`、`commands` 和 `hooks`，加上這些 marketplace 特定欄位：`source`、`category`、`tags`、`strict`、`relevance`、`headers` 和 `headersHelper`。

207 211

208<h3 id="required-fields-2">212<h3 id="required-fields-2">

209 必需欄位213 必需欄位

210</h3>214</h3>

211 215

212| 欄位 | 類型 | 描述 |216| 欄位 | 類型 | 描述 |

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

216 220

217<h3 id="optional-plugin-fields">221<h3 id="optional-plugin-fields">

221**標準中繼資料欄位：**225**標準中繼資料欄位：**

222 226

223| 欄位 | 類型 | 描述 |227| 欄位 | 類型 | 描述 |

224| :--------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |228| :--------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

227| `version` | string | Plugin 版本。如果設定（在此處或在 `plugin.json` 中），plugin 會固定到此字串，使用者只有在版本變更時才會收到更新。省略以回退到 git commit SHA。請參閱 [版本解析](#version-resolution-and-release-channels)。 |231| `version` | string | Plugin 版本。如果設定（在此處或在 `plugin.json` 中），plugin 會固定到此字串，使用者只有在版本變更時才會收到更新。具有 [`command` 來源](#command-sources)的 plugin 不會由任一欄位固定。如果在兩個地方都未設定，版本來自 [版本管理](/docs/zh-TW/plugins-reference#version-management)中的下一個來源。 |

237| `metadata` | object | 自由格式物件，用於您自己的欄位，例如權利或目錄資料。Claude Code 不會讀取它。在 v2.1.222 之前，`claude plugin validate` 會將該鍵報告為無法識別的欄位。 |

237| `defaultEnabled` | boolean | 安裝後 plugin 是否啟用（預設值：true）。設定為 `false` 以安裝已停用的 plugin，直到使用者選擇加入。優先於 plugin 的 `plugin.json` 中的相同欄位。請參閱 [預設啟用](/docs/zh-TW/plugins-reference#default-enablement)。需要 Claude Code v2.1.154 或更新版本。 |242| `defaultEnabled` | boolean | 安裝後 plugin 是否啟用（預設值：true）。設定為 `false` 以安裝已停用的 plugin，直到使用者選擇加入。優先於 plugin 的 `plugin.json` 中的相同欄位。請參閱 [預設啟用](/docs/zh-TW/plugins-reference#default-enablement)。 |

243

244兩個項目和 plugin 自己的 `plugin.json` 都可以設定顯示欄位 `displayName`、`description`、`author`、`homepage`、`repository`、`license` 和 `keywords`。在 plugin 清單和詳細資訊中，安裝前後：

245

246* 對於您在項目上設定的欄位，使用者會看到項目的值，即使 `plugin.json` 設定了不同的值。

247* 對於項目未設定的欄位，使用者會看到 `plugin.json` 值。

248

249安裝前，Claude Code 只能為具有 [相對路徑來源](#relative-paths)的項目讀取 `plugin.json`，其 plugin 檔案位於 marketplace 內部。對於具有任何其他來源類型的項目，使用者在安裝 plugin 之前只會看到項目自己的欄位。

238 250

239**元件配置欄位：**251**元件配置欄位：**

240 252

249 261

262**檔案驗證欄位：**

263

264當項目在需要認證的伺服器上具有 [`archive` 來源](#zip-archives)時，設定這些欄位。

265

266| 欄位 | 類型 | 描述 |

267| :-------------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- |

268| `headers` | object | Claude Code 在下載此項目的檔案時發送的 HTTP 標頭。覆蓋 marketplace 的相同名稱的標頭。需要 Claude Code v2.1.238 或更新版本。 |

269| `headersHelper` | string | 命令，將此項目的檔案下載的 HTTP 標頭列印為一個 JSON 物件，用於過期的認證。請參閱 [驗證檔案下載](#authenticate-archive-downloads)。項目還必須設定 [`"strict": false`](#strict-mode)。需要 Claude Code v2.1.238 或更新版本。 |

270

250<h2 id="plugin-sources">271<h2 id="plugin-sources">

251 Plugin 來源272 Plugin 來源

252</h2>273</h2>

253 274

254Plugin 來源告訴 Claude Code 在您的 marketplace 中列出的每個個別 plugin 從何處取得。這些在 `marketplace.json` 中每個 plugin 項目的 `source` 欄位中設定。275Plugin 來源告訴 Claude Code 在您的 marketplace 中列出的每個個別 plugin 從何處取得。這些在 `marketplace.json` 中每個 plugin 項目的 `source` 欄位中設定。

255 276

256一旦 Claude Code 複製或下載 plugin 到本機，它就會將 plugin 複製到本機版本化 plugin 快取中，位於 `~/.claude/plugins/cache`。277Claude Code 將每個已安裝的 plugin 複製到本機版本化 plugin 快取中，位於 `~/.claude/plugins/cache`，除了[連結模式中的 `command` 來源](#copy-mode-and-link-mode)，Claude Code 會改為使用該來源。Claude Code 也會[將 plugin 的合格 Node.js 套件相依性安裝](/docs/zh-TW/plugins-reference#node-js-package-dependencies)到快取副本中。

257 278

258| 來源 | 類型 | 欄位 | 備註 |279| 來源 | 類型 | 欄位 | 備註 |

259| ------------ | ---------------------------- | -------------------------------- | -------------------------------------------------------------------------------- |280| ------------ | ---------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

265 288

266<Note>289<Note>

267 **Marketplace 來源與 plugin 來源**：這些是控制不同事物的不同概念。290 **Marketplace 來源與 plugin 來源**：這些是控制不同事物的不同概念。

268 291

269 * **Marketplace 來源**：從何處取得 `marketplace.json` 目錄本身。在使用者執行 `/plugin marketplace add` 或在 `extraKnownMarketplaces` 設定中設定。支援 `ref`（分支/標籤）但不支援 `sha`。292 * **Marketplace 來源**：從何處取得 `marketplace.json` 目錄本身。在使用者執行 `/plugin marketplace add` 或在 `extraKnownMarketplaces` 設定中設定。基於 Git 的 marketplace 來源支援 `ref`（分支/標籤）但不支援 `sha`。

270 * **Plugin 來源**：從何處取得 marketplace 中列出的個別 plugin。在 `marketplace.json` 內每個 plugin 項目的 `source` 欄位中設定。支援 `ref`（分支/標籤）和 `sha`（確切提交）。293 * **Plugin 來源**：從何處取得 marketplace 中列出的個別 plugin。在 `marketplace.json` 內每個 plugin 項目的 `source` 欄位中設定。基於 Git 的 plugin 來源同時支援 `ref`（分支/標籤）和 `sha`（確切提交）。

271 294

272 例如，託管在 `acme-corp/plugin-catalog`（marketplace 來源）的 marketplace 可以列出從 `acme-corp/code-formatter`（plugin 來源）取得的 plugin。marketplace 來源和 plugin 來源指向不同的儲存庫，並獨立固定。295 例如，託管在 `acme-corp/plugin-catalog`（marketplace 來源）的 marketplace 可以列出從 `acme-corp/code-formatter`（plugin 來源）取得的 plugin。marketplace 來源和 plugin 來源指向不同的儲存庫，並獨立固定。

273</Note>296</Note>

274 297

275基於 git 的來源類型如下為 `github`、`url` 和 `git-subdir`。當任何一個上同時設定 `ref` 和 `sha` 時，`sha` 是有效的固定。Claude Code 直接取得並簽出固定的提交。在大多數 git 主機上，包括 GitHub、GitLab 和 Bitbucket，這表示即使上游的 `ref` 命名的分支或標籤已被刪除，只要提交仍可從儲存庫到達，安裝就會成功。某些伺服器（例如 AWS CodeCommit）不支援透過 SHA 取得提交。在這些伺服器上，`ref` 仍必須存在，且固定的提交必須可從其到達。298下面的基於 git 的來源類型為 `github`、`url` 和 `git-subdir`。當任何一個上同時設定 `ref` 和 `sha` 時，`sha` 是有效的固定。Claude Code 直接取得並簽出固定的提交。

299

300在大多數 git 主機上，包括 GitHub、GitLab 和 Bitbucket，這表示即使上游的 `ref` 命名的分支或標籤已被刪除，只要提交仍可從儲存庫到達，安裝就會成功。某些伺服器（例如 AWS CodeCommit）不支援透過 SHA 取得提交。在這些伺服器上，`ref` 仍必須存在，且固定的提交必須可從其到達。

301

302如果您透過**組織設定 > Plugins** 分發 plugin，只允許某些來源類型。請參閱[透過組織設定分發](#distribute-through-organization-settings)。

276 303

277<h3 id="relative-paths">304<h3 id="relative-paths">

278 相對路徑305 相對路徑

287}314}

288```315```

289 316

290路徑相對於 marketplace 根目錄解析，即包含 `.claude-plugin/` 的目錄。在上面的範例中，`./plugins/my-plugin` 指向 `<repo>/plugins/my-plugin`，即使 `marketplace.json` 位於 `<repo>/.claude-plugin/marketplace.json`。不要使用 `../` 參考 marketplace 根目錄外的路徑。317路徑相對於 marketplace 根目錄解析，即包含 `.claude-plugin/` 的目錄。在上面的範例中，`./plugins/my-plugin` 指向 `<repo>/plugins/my-plugin`，即使 `marketplace.json` 位於 `<repo>/.claude-plugin/marketplace.json`。不要使用 `../` 參考 marketplace 根目錄外的路徑。在 macOS 和 Linux 上，Claude Code 拒絕在前導 `./` 之後任何地方有反斜線的項目路徑，因此在每個平台上將分隔符寫為 `/`。

318

319裸名稱是沒有 `/` 的單一目錄名稱，例如 `"formatter"`。若要寫入裸名稱而不是 `./` 路徑，請將 [`metadata.pluginRoot`](#optional-fields) 設定為它們解析的目錄。使用 `"pluginRoot": "./plugins"`，Claude Code 將 `"source": "formatter"` 解析為 `./plugins/formatter`。需要 Claude Code v2.1.239 或更新版本。

320

321`metadata.pluginRoot` 本身必須是 marketplace 內的相對路徑。Claude Code 會忽略已以 `./` 開頭的來源。包含 `/` 的來源（例如 `team-a/formatter`）不是裸名稱，即使設定了 `metadata.pluginRoot`，仍需要 `./` 前綴。

291 322

292<Note>323<Note>

293 相對路徑會針對 marketplace 的本機副本解析，因此當使用者從 git 來源或本機目錄新增您的 marketplace 時可以運作。如果使用者透過直接 URL 新增您的 marketplace 到 `marketplace.json` 檔案，相對路徑將無法解析，因為只會下載該檔案。對於基於 URL 的分發，請改用 GitHub、npm 或 git URL 來源。有關詳細資訊，請參閱[疑難排解](#plugins-with-relative-paths-fail-in-url-based-marketplaces)。324 Claude Code 相對於 marketplace 的本機副本解析相對路徑，因此當使用者從 git 來源或本機目錄新增您的 marketplace 時可以運作。如果使用者透過直接 URL 新增您的 marketplace 到 `marketplace.json` 檔案，相對路徑將無法解析，因為 Claude Code 只會下載該檔案。對於基於 URL 的分發，請改用任何其他 [plugin 來源](#plugin-sources)。請參閱[疑難排解](#plugins-with-relative-paths-fail-in-url-based-marketplaces)以了解詳細資訊。

294</Note>325</Note>

295 326

296<h3 id="github-repositories">327<h3 id="github-repositories">

453 484

485<h3 id="zip-archives">

486 Zip 封存

487</h3>

488

489使用 `archive` 將 plugin 分發為 Claude Code 透過 HTTPS 下載的 zip 檔案，因此安裝在使用者的機器上無需 git 或 npm 即可運作。在任何靜態檔案伺服器或成品儲存庫上託管該檔案，例如 S3 儲存桶、Artifactory 通用儲存庫或 nginx。需要 Claude Code v2.1.224 或更新版本。在 v2.1.120 到 v2.1.223 版本上，安裝 plugin 失敗，並顯示 `This plugin uses a source type your Claude Code version does not support. Update Claude Code and try again.`；在較舊版本上，包含 `archive` 項目的 marketplace 完全無法載入。

490

491此項目從成品伺服器上的 zip 檔案安裝 plugin：

492

493```json theme={null}

494{

495 "name": "my-plugin",

496 "source": {

497 "source": "archive",

498 "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip"

499 }

500}

501```

502

503當您建立 zip 時，您可以直接壓縮 plugin 的內容或壓縮 plugin 資料夾本身。Claude Code 在封存的頂部查找 `.claude-plugin/`，然後在單一頂層資料夾內查找，因此兩種配置都會安裝：

504

505```text theme={null}

506my-plugin.zip my-plugin.zip

507├── .claude-plugin/ └── my-plugin/

508│ └── plugin.json ├── .claude-plugin/

509└── commands/ │ └── plugin.json

510 └── commands/

511```

512

513Claude Code 不會查找超過一個資料夾，因此嵌套更深的 plugin 無法安裝。Claude Code 拒絕大於 256 MiB 的封存。

514

515若要固定確切檔案，請新增 `sha256` 欄位，其中包含封存的摘要：

516

517```json theme={null}

518{

519 "name": "my-plugin",

520 "source": {

521 "source": "archive",

522 "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip",

523 "sha256": "6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1"

524 }

525}

526```

527

528如果下載的檔案與固定不符，Claude Code 拒絕安裝並報告 [`Plugin archive integrity check failed`](/docs/zh-TW/errors#plugin-archive-integrity-check-failed)。

529

530封存來源接受這些欄位：

531

532| 欄位 | 類型 | 描述 |

533| :------- | :----- | :---------------------------------------------------------------------------------------------------------- |

534| `url` | string | 必需。zip 封存的 HTTPS URL。Claude Code 拒絕 `http://` URL，以及迴圈、連結本機和雲端中繼資料主機。每個重新導向躍點都必須滿足相同的規則，否則 Claude Code 拒絕下載 |

535| `sha256` | string | 選用。封存的 SHA-256 摘要，為 64 個十六進位字元，大寫或小寫。Claude Code 驗證每次下載並在不符時拒絕安裝 |

536

537`sha256` 摘要也會在 `plugin.json` 或 marketplace 項目都未宣告版本時作為 plugin 的版本。請參閱[版本管理](/docs/zh-TW/plugins-reference#version-management)。如果您宣告 `version`，該版本字串是更新信號，因此在變更 zip 及其摘要後，也要提升版本，否則使用者會保留快取副本。

538

539<h4 id="authenticate-archive-downloads">

540 驗證封存下載

541</h4>

542

543若要驗證封存下載（例如從私人登錄表下載），請設定 Claude Code 隨其發送的 HTTP 標頭。在您註冊 marketplace 的 `url` 來源上設定 `headers`，例如 [`extraKnownMarketplaces`](/docs/zh-TW/settings-reference#extraknownmarketplaces) 項目。在 Claude Code v2.1.238 或更新版本上，您可以改為在 plugin 的項目上設定它，在 `source` 旁邊。

544

545如果您要放在 `headers` 中的值是短期的，例如您的登錄表應要求時鑄造的權杖，請改為在同一位置設定 `headersHelper` 命令。Claude Code 執行命令並將其列印的 JSON 物件作為該位置的標頭發送。需要 Claude Code v2.1.238 或更新版本。

546

547您選擇的位置決定哪些下載取得標頭以及 Claude Code 何時執行命令：

548

549| 位置 | 取得標頭的下載 | Claude Code 何時執行在該處設定的 `headersHelper` |

550| :------------------- | :--------------------------------------- | :--------------------------------------------------------------------------------------- |

551| Marketplace `url` 來源 | marketplace URL 來源上的封存下載，意思是相同的配置、主機和連接埠 | 在每次取得 marketplace 的 `marketplace.json` 之前以及在該來源上每次封存下載之前。Claude Code 將一次執行的輸出重複使用最多 60 秒 |

552| Plugin 項目 | 該項目的下載只有 | 只有當使用者自行安裝或更新該一個 plugin 並[接受命令](#how-users-accept-a-headershelper-command)時 |

553

554當兩個位置都設定相同名稱的標頭時，Claude Code 發送項目的值。在一個位置內，命令列印的標頭會覆蓋相同名稱的列出標頭。

555

556<h5 id="add-a-headershelper-to-a-plugin-entry">

557 將 headersHelper 新增到 plugin 項目

558</h5>

559

560此項目在 `source` 旁邊設定 `headersHelper`。它也設定 `"strict": false`，Claude Code 要求設定 `headersHelper` 的 `marketplace.json` 項目。使用 [`"strict": false`](#strict-mode)，marketplace 項目是 plugin 的完整定義，因此使用者可以在接受命令之前檢查 plugin 包含的內容：

561

562```json theme={null}

563{

564 "name": "my-plugin",

565 "description": "內部服務的格式化命令",

566 "strict": false,

567 "commands": "./commands",

568 "source": {

569 "source": "archive",

570 "url": "https://registry.example.com/plugins/my-plugin-2.1.0.zip"

571 },

572 "headersHelper": "/opt/bin/mint-registry-token.sh"

573}

574```

575

576若要檢查項目，請執行 `claude plugin install my-plugin@your-marketplace`。Claude Code 向您顯示命令和封存 URL，並在您接受後下載 zip。

577

578在 v2.1.238 之前，Claude Code 下載項目的封存時沒有其 `headers` 或 `headersHelper`，因此依賴它們的安裝失敗，並顯示 `HTTP 401 while downloading plugin archive from`，後面跟著 URL，登錄表的狀態碼代替 401。

579

580<h4 id="write-the-headershelper-command">

581 寫入 headersHelper 命令

582</h4>

583

584無論您在 marketplace 的 `url` 來源或 plugin 項目上設定 `headersHelper`，請寫入命令以滿足這些要求：

585

586* **命令文字**：最多 500 個可列印 ASCII 字元，沒有四個或更多空格的執行。

587* **輸出**：在 stdout 上列印一個標頭名稱和字串值的 JSON 物件，然後在 10 秒內以代碼 0 結束。

588* **Shell 和工作目錄**：Claude Code 透過 `sh` 或 Windows 上的 `cmd.exe` 從設定目錄 `~/.claude` 或 [`CLAUDE_CONFIG_DIR`](/docs/zh-TW/env-vars#variables) 執行命令。給出絕對路徑或 `PATH` 上的命令，因為相對路徑相對於該目錄解析，而不是使用者的專案。

589* **Claude Code 移除的變數**：從 `marketplace.json` 項目或專案的 `.claude/settings.json` 或 `.claude/settings.local.json` 中設定的命令環境中，Claude Code 移除每個名稱包含 `TOKEN`、`SECRET`、`KEY` 或 `AUTH` 等字詞的變數，包括 `ANTHROPIC_API_KEY`。Claude Code 不會將此移除應用於在使用者設定、`--settings` 檔案或受管設定中設定的命令。

590* **Claude Code 設定的變數**：`CLAUDE_CODE_MARKETPLACE_URL` 和 `CLAUDE_CODE_MARKETPLACE_NAME` 用於 `url` 來源的命令，以及 `CLAUDE_CODE_PLUGIN_NAME` 和 `CLAUDE_CODE_PLUGIN_ARCHIVE_URL` 用於項目的命令。`CLAUDE_CODE_MARKETPLACE_NAME` 在使用者透過 URL 新增 marketplace 後的第一次取得時未設定，因為該取得是提供名稱的內容。

591

592鑄造持有人權杖的命令列印如下物件：

593

594```json theme={null}

595{"Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9"}

596```

597

598<h4 id="when-claude-code-skips-a-headershelper-command-or-drops-its-output">

599 Claude Code 何時跳過 headersHelper 命令或捨棄其輸出

600</h4>

601

602Claude Code 不執行 `headersHelper` 命令，或在這些情況下捨棄來自 `headers` 或命令輸出的標頭：

603

604* **命令失敗**：如果命令以非零代碼結束、執行超過 10 秒或列印除字串值的 JSON 物件以外的任何內容，Claude Code 不會進行它執行命令的取得或下載。

605* **Marketplace URL 不以 `https://` 開頭**：Claude Code 不執行該 `url` 來源的命令，只發送其 `headers` 欄位中列出的標頭。

606* **重新導向離開來源**：當下載從封存 URL 的來源重新導向時，Claude Code 捨棄 marketplace `url` 來源和 plugin 項目的 `headers` 值和命令輸出。

607* **項目設定路由或身分標頭**：Claude Code 從項目的 `headers` 和命令輸出中捨棄請求路由和用戶端身分名稱（例如 `Host`、`Cookie` 和 `X-Forwarded-*`），並保留驗證名稱（例如 `Authorization`）。Claude Code 以這種方式篩選每個 `marketplace.json` 項目，以及[內嵌設定項目](/docs/zh-TW/settings-reference#extraknownmarketplaces)取決於哪個檔案宣告它。

608* **在 `--add-dir` 目錄的設定中設定的命令**：Claude Code 忽略它，在 `url` 來源和[內嵌 plugin 項目](/docs/zh-TW/settings-reference#extraknownmarketplaces)上都一樣，只發送該檔案的 `headers`。

609* **受管設定阻止命令**：將 [`disableCommandPluginSources`](/docs/zh-TW/settings-reference#disablecommandpluginsources) 設定為 `true` 會阻止 `headersHelper` 命令，[`allowManagedHooksOnly`](/docs/zh-TW/settings-reference#allowmanagedhooksonly) 也會阻止它們，除非 `disableCommandPluginSources` 明確為 `false`。在任一阻止下，Claude Code 仍會為受管設定本身宣告的 marketplace 執行命令。

610

611<h4 id="how-users-accept-a-headershelper-command">

612 使用者如何接受 headersHelper 命令

613</h4>

614

615使用者每次從 plugin 的自己的檢視在 `/plugin` 或使用 `claude plugin install` 或 `claude plugin update` 自行安裝或更新該一個 plugin 時接受 plugin 項目的命令。Claude Code 顯示命令和封存 URL，並僅在使用者接受後執行命令。在非互動式 shell 中，傳遞 [`--yes`](/docs/zh-TW/plugins-reference#plugin-install) 以接受它。

616

617Claude Code 只執行它顯示的命令，用於它顯示的封存 URL。如果項目的命令或封存 URL 在中間變更，Claude Code 拒絕安裝或更新。查詢字串中的變更單獨不計算。

618

619<h5 id="installs-and-updates-that-refuse-the-command-instead-of-asking">

620 拒絕命令而不是詢問的安裝和更新

621</h5>

622

623在任何其他操作上，而不是單一 plugin 安裝或更新，Claude Code 既不執行項目的命令也不下載其封存，因此 plugin 保持在其已安裝版本或保持未安裝。使用者看到的內容取決於操作：

624

625* **一次安裝多個 plugin、從 plugin 建議或作為另一個 plugin 的相依性**：Claude Code 拒絕具有命令的 plugin 並將使用者指向該 plugin 在 `/plugin` 中的自己的檢視。批量安裝中的其他 plugin 仍會安裝。依賴被拒絕 plugin 的 plugin 無法安裝，直到使用者自行安裝被拒絕的 plugin。

626* **背景自動更新，或工作階段開始用於其封存從未下載的 plugin**：Claude Code 在 `/plugin` 錯誤標籤中列出 plugin，以便使用者知道手動安裝或更新它。找到項目的自動更新仍會宣傳已安裝版本列出任何內容。

627

628<h5 id="when-a-marketplace-url-source’s-command-runs">

629 Marketplace `url` 來源的命令何時執行

630</h5>

631

632Marketplace `url` 來源的 `headersHelper` 在設定檔案中宣告，例如 [`extraKnownMarketplaces`](/docs/zh-TW/settings-reference#extraknownmarketplaces) 項目，而不是在 marketplace 發佈的目錄中，因此 Claude Code 不會在每次安裝或更新時詢問使用者接受它。宣告它的設定檔案決定 Claude Code 何時執行它：

633

634| 設定檔案 | Claude Code 何時執行命令 |

635| :---------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- |

636| 使用者設定、`--settings` 檔案或機器上的受管設定檔案 | 無需詢問，包括在背景 marketplace 重新整理期間 |

637| 專案的 `.claude/settings.json` 或 `.claude/settings.local.json` | 只有在使用者接受該資料夾本身的[工作區信任對話](/docs/zh-TW/permissions#what-runs-before-you-trust-a-folder)後。`-p` 或 SDK 工作階段不計算為接受它，父資料夾的信任也不計算 |

638| 伺服器受管設定 | 只有在使用者在[安全核准對話](/docs/zh-TW/server-managed-settings#security-approval-dialogs)中核准傳遞的設定後 |

639

640在 `-p` 或 SDK 工作階段中，Claude Code 無法顯示安全核准對話。它應用其他傳遞的設定，但 marketplace 取得以及任何需要命令的封存下載失敗，直到使用者在互動式工作階段中核准。

641

642對於這些檔案之一中的[內嵌 plugin 項目](/docs/zh-TW/settings-reference#extraknownmarketplaces)，Claude Code 要求與該檔案中 marketplace 層級命令相同的資料夾信任或設定核准，使用者也在每次安裝或更新時接受項目的命令。

643

644<h3 id="command-sources">

645 Command 來源

646</h3>

647

648當本機安裝的工具產生 plugin 目錄時使用 `command`，例如為目前選定的工具鏈呈現其 plugin 的 IDE。Claude Code 在使用者安裝 plugin 時執行命令，並在背景中每個工作階段重新執行一次，因此您的使用者無需重新安裝即可取得工具的變更輸出。需要 Claude Code v2.1.229 或更新版本。在 v2.1.120 到 v2.1.228 上，安裝 plugin 失敗，並顯示 `This plugin uses a source type your Claude Code version does not support. Update Claude Code and try again.`，在較舊版本上整個 marketplace 無法載入。

649

650此項目從工具列印的任何目錄安裝 plugin：

651

652```json theme={null}

653{

654 "name": "my-plugin",

655 "source": {

656 "source": "command",

657 "command": "my-tool claude-plugin-path"

658 }

659}

660```

661

662Claude Code 透過平台 shell（macOS 和 Linux 上的 `sh` 或 Windows 上的 `cmd.exe`）從使用者的主目錄執行命令。命令必須在 stdout 上列印恰好一行並以代碼 0 結束。該行是包含完整 plugin 的目錄的絕對路徑，命令結束時，路徑可能在執行之間變更。

663

664Claude Code 停止執行時間超過 `timeout` 秒的命令，安裝或更新失敗。Claude Code 也在這些情況下拒絕列印的路徑，安裝或更新以相同方式失敗：

665

666* 目錄在其頂層沒有 plugin 內容，例如 `.claude-plugin/` 目錄或 `skills/`、`commands/`、`agents/` 或 `hooks/` 目錄

667* 目錄是 Claude Code 啟動的目錄，或其父目錄之一

668* 在 Windows 上，路徑是 UNC 路徑

669

670Command 來源接受這些欄位：

671

672| 欄位 | 類型 | 描述 |

673| :-------- | :----- | :----------------------------------------------------------------------------------------------------------- |

674| `command` | string | 必需。Shell 命令，在 stdout 上列印 plugin 目錄的絕對路徑作為單一行並結束 0。必須是可列印 ASCII，最多 500 個字元，沒有四個或更多空格的執行，以便使用者可以檢查他們被要求接受的整個命令 |

675| `timeout` | number | 選用。放棄前等待命令的整數秒數（預設：60，最大：600） |

676| `mode` | string | 選用。`"copy"`（預設）將列印的目錄複製到 plugin 快取中。`"link"` 使用列印的目錄就地。請參閱[複製模式和連結模式](#copy-mode-and-link-mode) |

677

678<h4 id="copy-mode-and-link-mode">

679 複製模式和連結模式

680</h4>

681

682使用預設 `"mode": "copy"`，Claude Code 將列印的目錄複製到版本化 plugin 快取中，並從目錄內容的雜湊衍生[plugin 版本](/docs/zh-TW/plugins-reference#version-management)。您的工具可以在命令結束後刪除或重寫目錄，產生相同內容的重新執行計為最新。Claude Code 拒絕安裝大於 256 MiB 或包含超過 20,000 項目的目錄。

683

684為大型 plugin 目錄設定 `"mode": "link"`，不應複製，例如呈現的 SDK 匯出。Claude Code 使用連結填充 plugin 的快取項目到列印目錄的每個頂層項目，並就地使用檔案，因此不複製任何內容、不雜湊檔案內容，大小限制不適用。如果頂層項目是指向列印目錄外的符號連結，安裝失敗。Claude Code 也跳過連結模式 plugin 的 [Node.js 套件相依性安裝](/docs/zh-TW/plugins-reference#node-js-package-dependencies)，因此列印已包含 plugin 需要的任何 `node_modules` 的目錄。

685

686保持列印的目錄就地，只要 plugin 保持安裝。Claude Code 在每次啟動時透過這些連結載入 plugin。Claude Code 從列印目錄的真實路徑及其頂層項目衍生[plugin 版本](/docs/zh-TW/plugins-reference#version-management)，而不是檔案內部，因此列印不同的路徑以表示新內容。在列印目錄或其下方啟動的工作階段中，Claude Code 完全不載入 plugin。

687

688Claude Code 不支援 Windows 上的連結模式，拒絕在那裡安裝連結模式 plugin。改為宣告 `"mode": "copy"`。

689

690<h4 id="how-users-accept-the-command">

691 使用者如何接受命令

692</h4>

693

694Claude Code 在使用者的機器上執行您的命令，因此它將每次執行繫結到使用者的明確接受：

695

696* 當使用者從 `/plugin` 中的其詳細資訊畫面安裝 plugin，或在互動式終端中使用 `claude plugin install` 或 `claude plugin update` 安裝或更新它時，Claude Code 首先向他們顯示確切的命令字串，並記錄該安裝的已接受命令。可以在相同命令的已記錄接受上進行的 `claude plugin update` 不顯示任何內容。在非互動式 shell 中，例如佈建指令碼，傳遞 `--yes` 到 `claude plugin install` 或 `claude plugin update` 以接受它列印的命令。

697* 每條其他路徑只執行使用者已接受的命令。這包括從 `/plugin` 啟動的更新以及[Claude Code 何時重新執行命令](#when-claude-code-re-runs-the-command)中描述的背景執行。當未接受任何內容時，Claude Code 拒絕執行命令並告訴使用者如何檢查它。Claude Code 從不將 command 來源的 plugin 安裝為另一個 plugin 的相依性，因此使用者自行先安裝它。

698* 如果您變更項目的 `command` 或切換其 `mode`，使用者保留他們已有的版本，Claude Code 停止重新執行命令。在互動式工作階段中，`/plugin` 錯誤標籤顯示新命令，直到使用者透過執行 `claude plugin update <plugin>@<marketplace>` 檢查並接受它。

699

700系統管理員可以使用受管設定 [`disableCommandPluginSources`](/docs/zh-TW/settings-reference#disablecommandpluginsources) 在整個組織中阻止 command 來源。如果組織設定 [`allowManagedHooksOnly`](/docs/zh-TW/settings-reference#allowmanagedhooksonly)，Claude Code 預設會阻止 command 來源。

701

702<h4 id="when-claude-code-re-runs-the-command">

703 Claude Code 何時重新執行命令

704</h4>

705

706列印的目錄反映工具在命令執行時的狀態，因此 Claude Code 在這些時間重新執行命令：

707

708* 每次使用者安裝或更新 plugin

709* 每個工作階段一次用於每個啟用的 command 來源 plugin，在背景中，工作階段啟動後不久。此執行不透過 marketplace 自動更新進行，因此不取決於 marketplace 的[自動更新設定](/docs/zh-TW/discover-plugins#configure-auto-updates)

710* 在啟動或 `/reload-plugins` 上，當啟用的 plugin 的已安裝版本從 plugin 快取中遺失時

711

712當使用者設定 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/zh-TW/env-vars) 時，Claude Code 跳過兩個背景執行。明確安裝和更新仍會使用該變數集執行命令。

713

714當命令的雜湊輸出已變更時，Claude Code 將結果安裝為新版本，並在執行中的互動式工作階段中重新載入它，切換 [`/reload-plugins` 切換的相同元件](/docs/zh-TW/plugins-reference#environment-variables)。使用者看到 plugin 已重新載入的通知。如果就地重新載入會使工作階段的提示快取失效，Claude Code 改為提示使用者執行 `/reload-plugins`，[警告快取成本並在使用 `--force` 重新執行時應用](/docs/zh-TW/prompt-caching#enabling-or-disabling-a-plugin)。

715

454<h3 id="advanced-plugin-entries">716<h3 id="advanced-plugin-entries">

455 進階 plugin 項目717 進階 plugin 項目

456</h3>718</h3>

506 768

507需要注意的關鍵事項：769需要注意的關鍵事項：

508 770

509* **`commands` 和 `agents`**：您可以指定多個目錄或個別檔案。路徑相對於 plugin 根目錄。771* **`commands` 和 `agents`**：您可以指定多個目錄或個別檔案。路徑相對於 plugin 根目錄，必須保持在其內部。

510* **`${CLAUDE_PLUGIN_ROOT}`**：在 hooks 和 MCP server 配置中使用此變數來參考 plugin 安裝目錄內的檔案。這是必要的，因為 plugin 在安裝時被複製到快取位置。772 * Claude Code 拒絕解析在 plugin 目錄外的路徑，例如 `./../shared.md`，並顯示 [`path escapes plugin directory`](/docs/zh-TW/errors#path-escapes-plugin-directory) 錯誤，仍會載入 plugin 而不包含該元件

773* **`${CLAUDE_PLUGIN_ROOT}`**：在 hook 命令和 MCP 伺服器配置中使用此變數來參考 plugin 安裝目錄內的檔案。

511 * 請參閱[替換表](/docs/zh-TW/plugins-reference#environment-variables)以了解每個伺服器類型的哪些配置欄位會替換它774 * 請參閱[替換表](/docs/zh-TW/plugins-reference#environment-variables)以了解每個伺服器類型的哪些配置欄位會替換它

512 * 對於應在 plugin 更新後保留的相依性或狀態，請改用 [`${CLAUDE_PLUGIN_DATA}`](/docs/zh-TW/plugins-reference#persistent-data-directory)775 * 對於應在 plugin 更新後保留的相依性或狀態，請改用 [`${CLAUDE_PLUGIN_DATA}`](/docs/zh-TW/plugins-reference#persistent-data-directory)

513* **`strict: false`**：由於此設定為 false，plugin 不需要自己的 `plugin.json`。marketplace 項目定義所有內容。請參閱下面的 [Strict mode](#strict-mode)。776* **`strict: false`**：由於此設定為 false，plugin 不需要自己的 `plugin.json`。marketplace 項目定義所有內容。請參閱下面的 [Strict mode](#strict-mode)。

573 私人儲存庫836 私人儲存庫

574</h3>837</h3>

575 838

576Claude Code 支援從私人儲存庫安裝 plugin。對於手動安裝和更新，Claude Code 使用您現有的 git 認證助手，因此 HTTPS 存取透過 `gh auth login`、macOS Keychain 或 `git-credential-store` 的方式與在您的終端中相同。只要主機已在您的 `known_hosts` 檔案中且金鑰已載入 `ssh-agent`，SSH 存取就可以運作，因為 Claude Code 會抑制主機指紋和金鑰密碼的互動式 SSH 提示。GitHub `owner/repo` 簡寫來源預設透過 SSH 複製；設定 [`CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`](/docs/zh-TW/env-vars#variables) 以改為透過 HTTPS 複製它們。839Claude Code 支援從私人儲存庫安裝 plugin。如果您改為透過[**組織設定 > Plugins**](https://claude.ai/admin-settings/plugins)分發您的 marketplace，您的 git 認證不涉及其中：組織同步透過 Claude GitHub App 或您組織的 GitHub Enterprise App 讀取 marketplace 儲存庫，而 plugin 來源若無法驗證則必須是公開的。請參閱[透過組織設定分發](#distribute-through-organization-settings)以了解完整規則。

840

841<h4 id="commands-you-run">

842 您執行的命令

843</h4>

577 844

578背景自動更新的運作方式不同。根據預設，背景重新整理會為其 `git pull` 停用 git 認證助手，因此即使已配置助手，pull 也無法對私人儲存庫進行 HTTPS 驗證。SSH 遠端不受影響：載入在 `ssh-agent` 中的金鑰會以與手動操作相同的方式驗證背景 pull。當背景 pull 失敗時，Claude Code 會回退到從頭重新複製 marketplace。重新複製確實會使用您儲存的 git 認證，但它可能會在大型儲存庫上[逾時](#git-operations-time-out)，因此私人 marketplace 自動更新可能會間歇性失敗。845當您執行 `/plugin marketplace add`、`/plugin install`、`/plugin update` 或 `/plugin marketplace update` 時，Claude Code 使用您現有的 git 認證助手，因此 HTTPS 存取透過 `gh auth login`、macOS Keychain 或 `git-credential-store` 的方式與在您的終端中相同。只要主機已在您的 `known_hosts` 檔案中且金鑰已載入 `ssh-agent`，SSH 存取就可以運作，因為 Claude Code 會抑制主機指紋和金鑰密碼的互動式 SSH 提示。GitHub `owner/repo` 簡寫來源預設透過 SSH 複製；設定 [`CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`](/docs/zh-TW/env-vars#variables) 以改為透過 HTTPS 複製它們。

846

847<h4 id="background-auto-updates">

848 背景自動更新

849</h4>

850

851根據預設，背景重新整理會為其 `git pull` 停用 git 認證助手，因此即使已配置助手，pull 也無法對私人儲存庫進行 HTTPS 驗證。SSH 遠端不受影響：載入在 `ssh-agent` 中的金鑰會以與您執行的命令相同的方式驗證背景 pull。當背景 pull 失敗時，Claude Code 會回退到從頭重新複製 marketplace。重新複製確實會使用您儲存的 git 認證，但它可能會在大型儲存庫上[逾時](#git-operations-time-out)，因此私人 marketplace 自動更新可能會間歇性失敗。

579 852

580兩個設定使私人 marketplace 的行為可預測：853兩個設定使私人 marketplace 的行為可預測：

581 854

606 在 CI/CD 環境中，在從私人儲存庫安裝 plugin 之前配置 git 認證助手。在 GitHub Actions 上，匯出具有對 marketplace 儲存庫的讀取存取權的令牌作為 `GH_TOKEN`，然後執行 `gh auth setup-git`。預設工作流程令牌只能存取工作流程自己的儲存庫，因此另一個儲存庫中的私人 marketplace 需要個人存取令牌或應用程式令牌。在管道中配置的全域 URL 重寫也會直接驗證背景 pull。879 在 CI/CD 環境中，在從私人儲存庫安裝 plugin 之前配置 git 認證助手。在 GitHub Actions 上，匯出具有對 marketplace 儲存庫的讀取存取權的令牌作為 `GH_TOKEN`，然後執行 `gh auth setup-git`。預設工作流程令牌只能存取工作流程自己的儲存庫，因此另一個儲存庫中的私人 marketplace 需要個人存取令牌或應用程式令牌。在管道中配置的全域 URL 重寫也會直接驗證背景 pull。

607</Note>880</Note>

608 881

609<h3 id="test-locally-before-distribution">882<h3 id="distribute-through-organization-settings">

610 在分發前在本機測試883 透過組織設定分發

611</h3>884</h3>

612 885

613在分享前在本機測試您的 marketplace：886如果您在 Team 或 Enterprise 方案上透過[**組織設定 > Plugins**](https://claude.ai/admin-settings/plugins)分發 plugin，這些來源規則適用：

614 887

615```shell theme={null}888* marketplace 儲存庫必須是私人或內部的。組織同步透過 Claude GitHub App 或您組織的 GitHub Enterprise App 讀取它。

616/plugin marketplace add ./my-marketplace889* 每個 plugin 來源必須是 `github`、`url` 或 `git-subdir` 類型，或以 `./` 開頭的[相對路徑](#relative-paths)。如果您在 `metadata.pluginRoot` 下按裸名稱列出 plugin，組織同步會拒絕它作為不支援的來源，因此請寫出路徑，例如 `./plugins/deploy-tools`。

617/plugin install quality-review-plugin@my-plugins890* Plugin 來源可以在兩種情況下是私人的：

891 * 共享 marketplace 儲存庫擁有者的 github.com 來源

892 * 您組織的 GitHub Enterprise 主機上已安裝 GHE App 的來源

893* 組織同步在沒有認證的情況下取得每個其他來源，因此不同擁有者下的 github.com 儲存庫和其他主機上的儲存庫（例如 GitLab 或 Bitbucket）必須是公開的。

894

895請參閱[為您的組織管理 plugin](https://support.claude.com/en/articles/13837433)以了解管理員工作流程。

896

897若要包含私人 plugin，請將 plugin 資料夾放在 marketplace 儲存庫內，並使用[相對路徑](#relative-paths)參考它們。組織同步在分發期間打包每個 plugin，因此使用者永遠不需要存取單獨的來源儲存庫。

898

899例如，此 `marketplace.json` plugin 項目參考您在 marketplace 儲存庫中的 `plugins/deploy-tools` 提交的 plugin：

900

901```json theme={null}

902{

903 "name": "deploy-tools",

904 "source": "./plugins/deploy-tools"

905}

618```906```

619 907

620有關完整的新增命令範圍（GitHub、Git URL、本機路徑、遠端 URL），請參閱[新增 marketplace](/docs/zh-TW/discover-plugins#add-marketplaces)。908<h4 id="keep-executables-out-of-the-top-level-bin-directory">

909 將可執行檔保留在頂層 bin 目錄之外

910</h4>

911

912不要在您透過組織設定分發的任何 plugin 中包含頂層 `bin/` 目錄。claude.ai 會拒絕具有該目錄的 plugin，無論 plugin 是透過 marketplace 同步還是直接上傳到達：

913

914* **Marketplace 同步**：組織同步拒絕該 plugin 並同步 marketplace 的其餘部分。錯誤訊息以 `Plugin contains a top-level bin/ directory` 開頭。

915* **直接上傳**：如果您改為在[**組織設定 > Plugins**](https://claude.ai/admin-settings/plugins)中上傳 plugin，claude.ai 會以相同訊息拒絕上傳。

916

917將可執行檔保留在另一個目錄中，例如 `scripts/`，並從您的[skills、hooks 或 MCP 伺服器配置](/docs/zh-TW/plugins-reference#environment-variables)中將它們參考為 `${CLAUDE_PLUGIN_ROOT}/scripts/<name>`。

621 918

622<h3 id="require-marketplaces-for-your-team">919<h3 id="require-marketplaces-for-your-team">

623 為您的團隊要求 marketplace920 為您的團隊要求 marketplace

624</h3>921</h3>

625 922

626您可以配置您的儲存庫，以便當團隊成員信任專案資料夾時，他們會自動被提示安裝您的 marketplace。將您的 marketplace 新增到 `.claude/settings.json`：923您可以配置您的儲存庫，以便當團隊成員[信任專案資料夾](/docs/zh-TW/permissions#what-runs-before-you-trust-a-folder)時，Claude Code 會為他們新增您的 marketplace，無需單獨提示。將您的 marketplace 新增到 `.claude/settings.json`：

627 924

628```json theme={null}925```json theme={null}

629{926{

649}946}

650```947```

651 948

652有關完整的配置選項，請參閱 [Plugin settings](/docs/zh-TW/settings#plugin-settings)。949有關完整的配置選項，請參閱 [Plugin settings](/docs/zh-TW/settings-reference#plugin-settings)。

653 950

654<Note>951<Note>

655 如果您使用具有相對路徑的本機 `directory` 或 `file` 來源，路徑會針對您的儲存庫的主要簽出進行解析。當您從 git worktree 執行 Claude Code 時，路徑仍然指向主要簽出，因此所有 worktrees 共享相同的 marketplace 位置。Marketplace 狀態每個使用者儲存一次在 `~/.claude/plugins/known_marketplaces.json` 中，而不是每個專案。952 如果您使用具有相對路徑的本機 `directory` 或 `file` 來源，路徑會針對您的儲存庫的主要簽出進行解析。當您從 git worktree 執行 Claude Code 時，路徑仍然指向主要簽出，因此所有 worktrees 共享相同的 marketplace 位置。Marketplace 狀態每個使用者儲存一次在 `~/.claude/plugins/known_marketplaces.json` 中，而不是每個專案。

697 受管 marketplace 限制994 受管 marketplace 限制

698</h3>995</h3>

699 996

700對於需要對 plugin 來源進行嚴格控制的組織，管理員可以使用受管設定中的 [`strictKnownMarketplaces`](/docs/zh-TW/settings#strictknownmarketplaces) 設定限制使用者允許新增的 plugin marketplace。若要也拒絕為單次執行側載 plugin、agent 和 MCP 伺服器的 CLI 旗標，請將其與 [`disableSideloadFlags`](/docs/zh-TW/settings#available-settings) 配對。若要允許清單化哪些 marketplace 的 plugin 可以顯示為內容相關安裝建議，請設定 [`pluginSuggestionMarketplaces`](/docs/zh-TW/settings#available-settings)。997對於需要對 plugin 來源進行嚴格控制的組織，管理員可以使用受管設定中的 [`strictKnownMarketplaces`](/docs/zh-TW/settings-reference#strictknownmarketplaces) 設定限制使用者允許新增的 plugin marketplace。若要也拒絕為單次執行側載 plugin、agent 和 MCP 伺服器的 CLI 旗標，請將其與 [`disableSideloadFlags`](/docs/zh-TW/settings-reference#disablesideloadflags) 配對。若要允許清單化哪些 marketplace 的 plugin 可以顯示為內容相關安裝建議，請設定 [`pluginSuggestionMarketplaces`](/docs/zh-TW/settings-reference#pluginsuggestionmarketplaces)。

998

999`strictKnownMarketplaces` 符合 plugin 來自的 marketplace，而不是其內的項目，因此使用者仍然可以從允許的 marketplace 安裝具有[`command` 來源](#command-sources)的 plugin。若要也阻止 command 來源，請設定 [`disableCommandPluginSources`](/docs/zh-TW/settings-reference#disablecommandpluginsources)。

701 1000

702當在受管設定中配置 `strictKnownMarketplaces` 時，限制行為取決於值：1001當在受管設定中配置 `strictKnownMarketplaces` 時，限制行為取決於值：

703 1002

704| 值 | 行為 |1003| 值 | 行為 |

705| -------- | ----------------------------- |1004| -------- | --------------------------------------------------- |

706| 未定義（預設） | 無限制。使用者可以新增任何 marketplace |1005| 未定義（預設） | 無限制。使用者可以新增任何 marketplace |

707| 空陣列 `[]` | 完全鎖定。使用者無法新增任何新 marketplace |1006| 空陣列 `[]` | 完全鎖定。阻止每個 marketplace 來源，包括官方 Anthropic marketplace |

708| 來源清單 | 使用者只能新增與允許清單完全相符的 marketplace |1007| 來源清單 | 允許清單強制執行。使用者只能新增符合項目的 marketplace |

709 1008

710<h4 id="common-configurations">1009<h4 id="common-configurations">

711 常見配置1010 常見配置

712</h4>1011</h4>

713 1012

714停用所有 marketplace 新增：1013停用所有 marketplace 新增，包括官方 Anthropic marketplace：

715 1014

716```json theme={null}1015```json theme={null}

717{1016{

719}1018}

720```1019```

721 1020

1021僅允許官方 Anthropic marketplace。單一儲存庫項目的匹配是精確的，因此此項目不涵蓋同一儲存庫的 `ref` 或 `path` 變體：

1022

1023```json theme={null}

1024{

1025 "strictKnownMarketplaces": [

1026 {

1027 "source": "github",

1028 "repo": "anthropics/claude-plugins-official"

1029 }

1030 ]

1031}

1032```

1033

1034使用此項目，Claude Code 保持已註冊的官方 marketplace 可用，並在新機器上，在您第一次以互動方式啟動 Claude Code 時自動註冊 marketplace。

1035

1036自動註冊不涵蓋每台機器。它最常遺漏：

1037

1038* 在機器首次互動啟動之前執行的非互動環境。

1039* Claude Code 已在阻止 marketplace 的原則下以互動方式執行的機器，例如空陣列鎖定。Claude Code 記錄被阻止的嘗試，並在原則變更後不重試。

1040

1041在這些機器上，將 marketplace 新增到同一 `managed-settings.json` 中的 [`extraKnownMarketplaces`](/docs/zh-TW/settings-reference#extraknownmarketplaces)，以便 Claude Code 自動註冊它，或執行 `claude plugin marketplace add anthropics/claude-plugins-official`。

1042

722僅允許特定 marketplace：1043僅允許特定 marketplace：

723 1044

724```json theme={null}1045```json theme={null}

741}1062}

742```1063```

743 1064

1065使用[擁有者萬用字元](/docs/zh-TW/settings-reference#owner-wildcards)項目允許 GitHub 組織下的每個 marketplace 儲存庫。擁有者萬用字元需要 Claude Code v2.1.223 或更新版本。

1066

1067```json theme={null}

1068{

1069 "strictKnownMarketplaces": [

1070 {

1071 "source": "github",

1072 "repo": "acme-corp/*"

1073 }

1074 ]

1075}

1076```

1077

744使用主機上的正規表達式模式匹配允許來自內部 git 伺服器的所有 marketplace。這是 [GitHub Enterprise Server](/docs/zh-TW/github-enterprise-server#plugin-marketplaces-on-ghes) 或自託管 GitLab 執行個體的推薦方法：1078使用主機上的正規表達式模式匹配允許來自內部 git 伺服器的所有 marketplace。這是 [GitHub Enterprise Server](/docs/zh-TW/github-enterprise-server#plugin-marketplaces-on-ghes) 或自託管 GitLab 執行個體的推薦方法：

745 1079

746```json theme={null}1080```json theme={null}

770使用 `".*"` 作為 `pathPattern` 以允許任何檔案系統路徑，同時仍使用 `hostPattern` 控制網路來源。1104使用 `".*"` 作為 `pathPattern` 以允許任何檔案系統路徑，同時仍使用 `hostPattern` 控制網路來源。

771 1105

772<Note>1106<Note>

773 `strictKnownMarketplaces` 限制使用者可以新增的內容，但不會自行註冊 marketplace。若要在不需要使用者執行 `/plugin marketplace add` 的情況下自動提供允許的 marketplace，請將其與同一 `managed-settings.json` 中的 [`extraKnownMarketplaces`](/docs/zh-TW/settings#extraknownmarketplaces) 配對。請參閱[同時使用兩者](/docs/zh-TW/settings#strictknownmarketplaces)。1107 `strictKnownMarketplaces` 限制使用者可以新增的內容，但不會自行註冊 marketplace。若要為使用者自動註冊允許的 marketplace，請將其新增到同一 `managed-settings.json` 中的 [`extraKnownMarketplaces`](/docs/zh-TW/settings-reference#extraknownmarketplaces)。

1108

1109 官方 Anthropic marketplace 是唯一 Claude Code 自行註冊的，且僅當允許清單允許時。自動註冊也遺漏某些機器，例如非互動環境和早期原則阻止它的機器。若要涵蓋這些機器，也將官方 marketplace 新增到 `extraKnownMarketplaces`。有關兩個設定並排，請參閱 [`strictKnownMarketplaces` 參考](/docs/zh-TW/settings-reference#strictknownmarketplaces)。

774</Note>1110</Note>

775 1111

776<h4 id="how-restrictions-work">1112<h4 id="how-restrictions-work">

779 1115

780限制在任何網路或檔案系統操作之前進行檢查。檢查在 marketplace 新增以及 plugin 安裝、更新、重新整理和自動更新時執行。如果 marketplace 在配置原則之前被新增，且其來源不再符合允許清單，Claude Code 會拒絕從中安裝或更新 plugin。相同的強制執行也適用於 `blockedMarketplaces`。1116限制在任何網路或檔案系統操作之前進行檢查。檢查在 marketplace 新增以及 plugin 安裝、更新、重新整理和自動更新時執行。如果 marketplace 在配置原則之前被新增，且其來源不再符合允許清單，Claude Code 會拒絕從中安裝或更新 plugin。相同的強制執行也適用於 `blockedMarketplaces`。

781 1117

782允許清單對大多數來源類型使用精確匹配。若要允許 marketplace，所有指定的欄位必須完全相符：1118若要阻止 GitHub 擁有者下的每個 marketplace 儲存庫，請在 `blockedMarketplaces` 項目中使用擁有者萬用字元形式：`{ "source": "github", "repo": "untrusted-org/*" }`。需要 Claude Code v2.1.223 或更新版本。有關匹配規則（在封鎖清單和允許清單之間不同），請參閱[擁有者萬用字元](/docs/zh-TW/settings-reference#owner-wildcards)。

1119

1120當使用者新增 Claude Code [複製而不是取得](/docs/zh-TW/discover-plugins#add-from-other-git-hosts)的 `https://` 儲存庫 URL（例如裸 `github.com` 或 `gitlab.com` 儲存庫 URL）時，Claude Code 也會根據 `blockedMarketplaces` 中的 `url` 項目檢查它。如果項目命名相同的 URL，Claude Code 會阻止新增。在該比較中，Claude Code 忽略 `.git` 後綴和使用者在 `#` 後附加的任何 ref。需要 Claude Code v2.1.232 或更新版本。在 v2.1.232 之前，Claude Code 僅針對它作為託管 `marketplace.json` 檔案取得的 URL 符合 `url` 項目。

783 1121

784* 對於 GitHub 來源：`repo` 是必需的，如果在允許清單中指定，`ref` 或 `path` 也必須相符1122允許清單對大多數來源類型使用精確匹配，除了擁有者萬用字元 `github` 項目。若要允許 marketplace，所有指定的欄位必須相符：

1123

1124* 對於 GitHub 來源：`repo` 是必需的，要麼命名一個儲存庫，要麼使用擁有者萬用字元形式 `owner/*` 涵蓋該擁有者下的每個儲存庫。有關萬用字元項目如何匹配（包括大小寫規則），請參閱[擁有者萬用字元](/docs/zh-TW/settings-reference#owner-wildcards)。對於單一儲存庫項目，`ref` 必須精確相符或在 marketplace 來源和允許清單項目中都不存在，相同的規則適用於 `path`

785* 對於 URL 來源：完整 URL 必須完全相符1125* 對於 URL 來源：完整 URL 必須完全相符

786* 對於 `hostPattern` 來源：marketplace 主機與正規表達式模式相符1126* 對於 `hostPattern` 來源：marketplace 主機與正規表達式模式相符

787* 對於 `pathPattern` 來源：marketplace 的檔案系統路徑與正規表達式模式相符1127* 對於 `pathPattern` 來源：marketplace 的檔案系統路徑與正規表達式模式相符

788 1128

789精確匹配不會正規化 URL：尾部斜線、`.git` 後綴或 `ssh://` 與 `https://` 形式被視為不同的值。如果您的組織 marketplace 可以透過多個 URL 形式複製，請優先使用 `hostPattern` 項目而不是字面 URL，以便所有形式都相符。1129允許清單的精確匹配將僅因尾部斜線、`.git` 後綴或 `ssh://` 和 `https://` 方案而異的 URL 視為不同的值。如果您的組織 marketplace 可以透過多個 URL 形式複製，請優先使用 `hostPattern` 項目而不是字面 URL，以便 `https://`、`ssh://` 和 `user@host:path` 形式都相符。

790 1130

791因為 `strictKnownMarketplaces` 在[受管設定](/docs/zh-TW/settings#settings-files)中設定，個別使用者和專案配置無法覆蓋這些限制。1131因為 `strictKnownMarketplaces` 在[受管設定](/docs/zh-TW/managed-settings)中設定，個別使用者和專案配置無法覆蓋這些限制。

792 1132

793有關完整的配置詳細資訊，包括所有支援的來源類型和與 `extraKnownMarketplaces` 的比較，請參閱 [strictKnownMarketplaces 參考](/docs/zh-TW/settings#strictknownmarketplaces)。1133有關完整的配置詳細資訊，包括所有支援的來源類型和與 `extraKnownMarketplaces` 的比較，請參閱 [strictKnownMarketplaces 參考](/docs/zh-TW/settings-reference#strictknownmarketplaces)。

794 1134

795<h3 id="version-resolution-and-release-channels">1135<h3 id="version-resolution-and-release-channels">

796 版本解析和發行通道1136 版本解析和發行通道

797</h3>1137</h3>

798 1138

799Plugin 版本決定快取路徑和更新偵測：如果解析的版本與使用者已有的版本相符，`/plugin update` 和自動更新會跳過 plugin。1139Plugin 版本決定快取路徑和更新偵測：如果解析的版本與使用者已有的版本相符，`/plugin update` 和自動更新會跳過 plugin。對於 git 型來源，如果您省略 `version`，Claude Code 使用來源的解析提交 SHA，因此使用者在該提交變更時獲得更新；這是內部或積極開發的 plugin 的最簡單設定。請參閱[版本管理](/docs/zh-TW/plugins-reference#version-management)以了解完整的解析順序，包括 `archive` 來源。

~~800~~

801Claude Code 從以下第一個設定的項目解析 plugin 的版本：

~~802~~

8031. plugin 的 `plugin.json` 中的 `version`

8042. plugin 的 marketplace 項目中的 `version`

8053. plugin 來源的 git 提交 SHA

~~806~~

807對於 git 型來源類型 `github`、`url`、`git-subdir` 和 git 託管 marketplace 內的相對路徑，您可以完全省略 `version`，每個新提交都被視為新版本。這是內部或積極開發的 plugin 的最簡單設定。

808 1140

809<Warning>1141<Warning>

810 設定 `version` 會固定 plugin。如果 `plugin.json` 宣告 `"version": "1.0.0"`，推送新提交而不更改該字串對現有使用者沒有任何作用，因為 Claude Code 看到相同的版本並保留快取副本。在每次發行時提升該欄位，或省略它以使用提交 SHA。1142 設定 `version` 會固定 plugin，除了 [`command`](#command-sources)（其版本始終包含命令產生內容的雜湊）的每個來源類型。如果您在 `plugin.json` 中宣告 `"version": "1.0.0"` 並推送新提交而不更改該字串，這些來源的現有使用者保留快取副本，因為 Claude Code 看到相同的版本。在每次發行時提升該欄位，或省略它以回退到解析的版本。

811 1143

812 避免在 `plugin.json` 和 marketplace 項目中同時設定 `version`。Claude Code 總是無聲地使用 `plugin.json` 值，因此過時的 manifest 版本可能會掩蓋您在 `marketplace.json` 中設定的版本。1144 避免在 `plugin.json` 和 marketplace 項目中同時設定 `version`。Claude Code 總是無聲地使用 `plugin.json` 值，因此過時的 manifest 版本可能會掩蓋您在 `marketplace.json` 中設定的版本。

813</Warning>1145</Warning>

816 設定發行通道1148 設定發行通道

817</h4>1149</h4>

818 1150

819若要為您的 plugin 支援「穩定」和「最新」發行通道，您可以設定兩個指向同一儲存庫的不同 ref 或 SHA 的 marketplace。然後，您可以透過[受管設定](/docs/zh-TW/settings#settings-files)將兩個 marketplace 指派給不同的使用者群組。1151若要為您的 plugin 支援「穩定」和「最新」發行通道，您可以設定兩個指向同一儲存庫的不同 ref 或 SHA 的 marketplace。然後，您可以透過以下兩種方式之一透過受管設定將每個使用者群組指派給其自己的 marketplace：

1152

1153* 將單獨的[端點管理設定](/docs/zh-TW/managed-settings#delivery-mechanisms)（例如受管設定檔案或 MDM 設定檔）部署到每個群組的裝置。[Claude Code 如何組合受管來源](/docs/zh-TW/managed-settings#precedence-within-the-managed-tier)說明每個群組檔案或設定檔是否適用於也具有組織範圍來源的裝置。

1154* 為每個群組定義一個 [Claude apps gateway 原則](/docs/zh-TW/claude-apps-gateway-config#managed)。gateway 適用第一個符合使用者的原則，因此排序原則以便每個使用者到達其群組的原則。群組原則的 `extraKnownMarketplaces` 替換全面原則的對應，而不是與其合併，因此在群組的原則中列出群組需要的每個 marketplace，而不僅僅是其通道 marketplace。

1155

1156來自管理員主控台的伺服器管理設定[適用於您組織中的每個使用者](/docs/zh-TW/server-managed-settings#current-limitations)，因此無法進行每個群組的指派。

820 1157

821<Warning>1158<Warning>

822 每個通道必須解析為不同的版本。如果您使用明確版本，`plugin.json` 必須在每個固定的 ref 處宣告不同的 `version`。如果您省略 `version`，不同的提交 SHA 已經區分通道。如果兩個 ref 解析為相同的版本字串，Claude Code 會將它們視為相同並跳過更新。1159 每個通道必須解析為不同的版本。如果您使用明確版本，`plugin.json` 必須在每個固定的 ref 處宣告不同的 `version`。如果您省略 `version`，不同的提交 SHA 已經區分通道。如果兩個 ref 解析為相同的版本字串，Claude Code 會將它們視為相同並跳過更新。

862 將通道指派給使用者群組1199 將通道指派給使用者群組

863</h5>1200</h5>

864 1201

865透過受管設定將每個 marketplace 指派給適當的使用者群組。例如，穩定群組接收：1202透過上述[設定發行通道](#set-up-release-channels)下描述的每個群組端點管理設定或 gateway 原則將每個 marketplace 指派給其使用者群組。例如，穩定群組接收：

866 1203

867```json theme={null}1204```json theme={null}

868{1205{

940 驗證和測試1277 驗證和測試

941</h2>1278</h2>

942 1279

943在分享前測試您的 marketplace。1280在分享前測試您的 marketplace。驗證會檢查檔案結構；若要測試 plugin 是否會改變 Claude 在實際提示上的行為，請在發佈新版本前使用 [`claude plugin eval`](/docs/zh-TW/plugin-evals) 執行其評估套件。

944 1281

945驗證您的 marketplace JSON 語法：1282從您的 marketplace 目錄，驗證 JSON 語法：

946 1283

947```bash theme={null}1284```bash theme={null}

948claude plugin validate .1285claude plugin validate .

969有關完整的 plugin 測試工作流程，請參閱[在本機測試您的 plugin](/docs/zh-TW/plugins#test-your-plugins-locally)。有關技術疑難排解，請參閱 [Plugins reference](/docs/zh-TW/plugins-reference)。1306有關完整的 plugin 測試工作流程，請參閱[在本機測試您的 plugin](/docs/zh-TW/plugins#test-your-plugins-locally)。有關技術疑難排解，請參閱 [Plugins reference](/docs/zh-TW/plugins-reference)。

970 1307

971<h2 id="manage-marketplaces-from-the-cli">1308<h2 id="manage-marketplaces-from-the-cli">

972 從 CLI 管理 marketplace1309 從 CLI 管理市集

973</h2>1310</h2>

974 1311

975Claude Code 提供非互動式 `claude plugin marketplace` 子命令用於指令碼和自動化。這些等同於互動式工作階段內可用的 `/plugin marketplace` 命令。1312Claude Code 提供非互動式的 `claude plugin marketplace` 子命令，用於指令碼和自動化。這些命令等同於互動式工作階段中可用的 `/plugin marketplace` 命令。

976 1313

977<h3 id="plugin-marketplace-add">1314<h3 id="plugin-marketplace-add">

978 Plugin marketplace add1315 Plugin marketplace add

979</h3>1316</h3>

980 1317

981從 GitHub 儲存庫、git URL、遠端 URL 或本機路徑新增 marketplace。1318從 GitHub 儲存庫、git URL、遠端 URL 或本機路徑新增市集。

982 1319

983```bash theme={null}1320```bash theme={null}

984claude plugin marketplace add <source> [options]1321claude plugin marketplace add <source> [options]

986 1323

987**引數：**1324**引數：**

988 1325

989* `<source>`：GitHub `owner/repo` 簡寫、git URL、遠端 URL 到 `marketplace.json` 檔案或本機目錄路徑。若要固定到分支或標籤，請將 `@ref` 附加到 GitHub 簡寫或 `#ref` 附加到 git URL1326* `<source>`：GitHub `owner/repo` 簡寫、git URL、指向 `marketplace.json` 檔案的遠端 URL，或本機目錄路徑。若要釘選到分支或標籤，請在 GitHub 簡寫後附加 `@ref`，或在 git URL 後附加 `#ref`

990 1327

991URL 必須包含其配置。自 Claude Code v2.1.196 起，未輸入配置的主機（例如 `gitlab.example.com/team/plugins`）會被拒絕為無效的 `owner/repo` 簡寫，錯誤訊息會告訴您新增 `https://` 或使用 `./` 作為本機路徑。較早的版本會將其誤讀為 GitHub 儲存庫路徑，並在複製時因 GitHub 找不到錯誤而失敗。1328URL 必須包含其配置。自 Claude Code v2.1.196 起，未輸入配置的主機（例如 `gitlab.example.com/team/plugins`）會被拒絕為無效的 `owner/repo` 簡寫，錯誤訊息會告訴您新增 `https://` 或使用 `./` 作為本機路徑。較早的版本會將其誤讀為 GitHub 儲存庫路徑，並在複製時因 GitHub 找不到錯誤而失敗。

992 1329

993**選項：**1330**選項：**

994 1331

995| 選項 | 描述 | 預設 |1332| 選項 | 說明 | 預設值 |

996| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------- | :----- |1333| :-------------------- | :-------------------------------------------------------------------------------------------------------- | :----- |

999 1336

1000從 GitHub 使用 `owner/repo` 簡寫新增 marketplace：1337使用 `owner/repo` 簡寫從 GitHub 新增市集：

1001 1338

1002```bash theme={null}1339```bash theme={null}

1003claude plugin marketplace add acme-corp/claude-plugins1340claude plugin marketplace add acme-corp/claude-plugins

1004```1341```

1005 1342

1006使用 `@ref` 固定到特定分支或標籤：1343使用 `@ref` 釘選到特定分支或標籤：

1007 1344

1008```bash theme={null}1345```bash theme={null}

1009claude plugin marketplace add acme-corp/claude-plugins@v2.01346claude plugin marketplace add acme-corp/claude-plugins@v2.0

1027claude plugin marketplace add ./my-marketplace1364claude plugin marketplace add ./my-marketplace

1028```1365```

1029 1366

1030在專案範圍宣告 marketplace，以便透過 `.claude/settings.json` 與您的團隊共享：1367在專案範圍宣告市集，以便透過 `.claude/settings.json` 與您的團隊共享：

1031 1368

1032```bash theme={null}1369```bash theme={null}

1033claude plugin marketplace add acme-corp/claude-plugins --scope project1370claude plugin marketplace add acme-corp/claude-plugins --scope project

1034```1371```

1035 1372

1036對於 monorepo，限制簽出到包含 plugin 內容的目錄：1373對於 monorepo，限制簽出到包含外掛程式內容的目錄：

1037 1374

1038```bash theme={null}1375```bash theme={null}

1039claude plugin marketplace add acme-corp/monorepo --sparse .claude-plugin plugins1376claude plugin marketplace add acme-corp/monorepo --sparse .claude-plugin plugins

1043 Plugin marketplace list1380 Plugin marketplace list

1044</h3>1381</h3>

1045 1382

1046列出所有已配置的 marketplace。1383列出所有已設定的市集。

1047 1384

1048```bash theme={null}1385```bash theme={null}

1049claude plugin marketplace list [options]1386claude plugin marketplace list [options]

1051 1388

1052**選項：**1389**選項：**

1053 1390

1054| 選項 | 描述 |1391| 選項 | 說明 |

1055| :------- | :------- |1392| :------- | :------- |

1057 1394

1058使用 `--json` 時，每個項目包括 `name`、`source` 和來源特定的欄位：GitHub 來源的 `repo`、git 和 URL 來源的 `url`，以及本機來源的 `path`。當 marketplace 使用固定的分支或標籤新增時，GitHub 和 git 來源也包括 `ref` 欄位。1395使用 `--json` 時，每個項目包括 `name`、`source`、一個 `installLocation` 欄位（包含市集儲存所在的本機快取路徑），以及來源特定的欄位：GitHub 來源的 `repo`、git 和 URL 來源的 `url`，以及本機來源的 `path`。當市集新增時使用釘選的分支或標籤時，GitHub 和 git 來源也包括 `ref` 欄位。

1059 1396

1060<h3 id="plugin-marketplace-remove">1397<h3 id="plugin-marketplace-remove">

1061 Plugin marketplace remove1398 Plugin marketplace remove

1062</h3>1399</h3>

1063 1400

1064移除已配置的 marketplace。別名 `rm` 也被接受。1401移除已設定的市集。別名 `rm` 也可接受。

1065 1402

1066```bash theme={null}1403```bash theme={null}

1067claude plugin marketplace remove <name> [options]1404claude plugin marketplace remove <name> [options]

1069 1406

1070**引數：**1407**引數：**

1071 1408

1072* `<name>`：marketplace 名稱以移除，如 `claude plugin marketplace list` 所示。這是 `marketplace.json` 中的 `name`，而不是您傳遞給 `add` 的來源1409* `<name>`：要移除的市集名稱，如 `claude plugin marketplace list` 所示。這是來自 `marketplace.json` 的 `name`，而不是您傳遞給 `add` 的來源

1073 1410

1074**選項：**1411**選項：**

1075 1412

1076| 選項 | 描述 | 預設 |1413| 選項 | 說明 | 預設值 |

1077| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- |1414| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----- |

1078| `--scope <scope>` | 限制移除到單一設定範圍：`user`、`project` 或 `local`。請參閱 [Plugin installation scopes](/docs/zh-TW/plugins-reference#plugin-installation-scopes)。省略時，宣告會從每個可編輯的範圍中移除。指定時，只會移除該範圍的宣告；當 marketplace 仍在另一個範圍中宣告時，共享狀態、快取和已安裝的 plugin 資料會被保留 | (所有範圍) |1415| `--scope <scope>` | 限制移除到單一設定範圍：`user`、`project` 或 `local`。請參閱 [Plugin 安裝範圍](/docs/zh-TW/plugins-reference#plugin-installation-scopes)。省略時，宣告會從每個可編輯的範圍中移除。指定時，只會移除該範圍的宣告；當市集仍在另一個範圍中宣告時，共享狀態、快取和已安裝的外掛程式資料會保留 | （所有範圍） |

1079 1416

1080<Warning>1417<Warning>

1081 從其最後剩餘的範圍移除 marketplace 也會卸載您從中安裝的任何 plugin。若要重新整理 marketplace 而不失去已安裝的 plugin，請改用 `claude plugin marketplace update`。1418 從其最後剩餘的範圍移除市集也會解除安裝您從中安裝的任何外掛程式。若要重新整理市集而不遺失已安裝的外掛程式，請改用 `claude plugin marketplace update`。

1082</Warning>1419</Warning>

1083 1420

1084<h3 id="plugin-marketplace-update">1421<h3 id="plugin-marketplace-update">

1085 Plugin marketplace update1422 Plugin marketplace update

1086</h3>1423</h3>

1087 1424

1088從其來源重新整理 marketplace 以檢索新 plugin 和版本變更。使用分支或標籤 `ref` 新增的 marketplace 會更新到該 ref 的最新提交，而不是儲存庫的預設分支。1425從其來源重新整理市集，以擷取新外掛程式和版本變更。使用分支或標籤 `ref` 新增的市集會更新到該 ref 的最新提交，而不是儲存庫的預設分支。

1089 1426

1090```bash theme={null}1427```bash theme={null}

1091claude plugin marketplace update [name]1428claude plugin marketplace update [name]

1093 1430

1094**引數：**1431**引數：**

1095 1432

1096* `[name]`：marketplace 名稱以更新，如 `claude plugin marketplace list` 所示。如果省略，更新所有 marketplace1433* `[name]`：要更新的市集名稱，如 `claude plugin marketplace list` 所示。省略時會更新所有市集

1097 1434

1098`remove` 和 `update` 在針對種子管理的 marketplace 執行時都會失敗，該 marketplace 是唯讀的。更新所有 marketplace 時，種子管理的項目被跳過，其他 marketplace 仍然更新。若要變更種子提供的 plugin，請要求您的管理員更新種子映像。請參閱[為容器預先填充 plugin](#pre-populate-plugins-for-containers)。1435當針對種子管理的市集執行時，`remove` 和 `update` 都會失敗，該市集是唯讀的。更新所有市集時，種子管理的項目會被跳過，其他市集仍會更新。若要變更種子提供的外掛程式，請要求您的管理員更新種子映像。請參閱 [為容器預先填入外掛程式](#pre-populate-plugins-for-containers)。

1099 1436

1100<h2 id="troubleshooting">1437<h2 id="troubleshooting">

1101 疑難排解1438 疑難排解

1111 1448

1112* 驗證 marketplace URL 可存取1449* 驗證 marketplace URL 可存取

1113* 檢查 `.claude-plugin/marketplace.json` 是否存在於指定路徑1450* 檢查 `.claude-plugin/marketplace.json` 是否存在於指定路徑

1114* 使用 `claude plugin validate` 或 `/plugin validate` 確保 JSON 語法有效。若要檢查 skill、agent 和 command frontmatter，請針對每個 plugin 目錄執行該命令1451* 使用 `claude plugin validate .` 或 `/plugin validate .` 確保 JSON 語法有效。若要檢查 skill、agent 和 command frontmatter，請參閱[驗證沒有 manifest 的 plugin 或目錄](#validate-a-plugin-or-a-directory-without-a-manifest)

1115* 對於私人儲存庫，確認您有存取權限1452* 對於私人儲存庫，確認您有存取權限

1116 1453

1117<h3 id="marketplace-validation-errors">1454<h3 id="marketplace-validation-errors">

1128 1465

1129較早的版本會跳過 marketplace 根目錄中的 plugin，並且只從 `.claude-plugin/marketplace.json` 開始下降。1466較早的版本會跳過 marketplace 根目錄中的 plugin，並且只從 `.claude-plugin/marketplace.json` 開始下降。

1130 1467

1131若要驗證個別 plugin 的 `plugin.json` 及其 skill、agent、command 和 hook 檔案，請針對 plugin 目錄本身執行該命令，例如 `claude plugin validate ./plugins/my-plugin`。常見錯誤：1468從 marketplace 目錄，Claude Code 不會開啟 plugin 的 skill、agent、command 或 hook 檔案。若要在這些檔案中找到錯誤，請參閱[驗證沒有 manifest 的 plugin 或目錄](#validate-a-plugin-or-a-directory-without-a-manifest)。下表列出從 marketplace 目錄最常見的錯誤，以及每個錯誤的原因和修正方式：

1132 1469

1133| 錯誤 | 原因 | 解決方案 |1470| 錯誤 | 原因 | 解決方案 |

1134| :------------------------------------------------ | :--------------------------------- | :--------------------------------------------------------------------- |1471| :------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------- |

1135| `File not found: .claude-plugin/marketplace.json` | 缺少 manifest | 使用必需欄位建立 `.claude-plugin/marketplace.json` |1472| `No manifest found in directory. Expected .claude-plugin/marketplace.json or .claude-plugin/plugin.json` | 您命名的目錄沒有 `.claude-plugin/marketplace.json` 或 `plugin.json`，也沒有 skill、agent 或 command 檔案可檢查 | 從 marketplace 根目錄執行，或使用必需欄位建立 `.claude-plugin/marketplace.json` |

1139| `YAML frontmatter failed to parse: ...` | skill、agent 或 command 檔案中的 YAML 無效 | 修正 frontmatter 區塊中的 YAML 語法。在執行時，此檔案載入時不含中繼資料。僅在驗證 plugin 目錄時報告 |1476| `Marketplace name cannot contain control or bidirectional-formatting characters` | marketplace `name` 包含 Unicode 雙向格式化字元或控制字元，例如逸出或換行符 | 從名稱中移除該字元。在 v2.1.247 之前，這些字元會產生 `Marketplace name impersonates an official Anthropic/Claude marketplace` 錯誤 |

1141 1478

1142**警告**（非阻止性）：1479**警告**（非阻止性）：

1143 1480

1144* `Marketplace has no plugins defined`：將至少一個 plugin 新增到 `plugins` 陣列1481* `Marketplace has no plugins defined`：將至少一個 plugin 新增到 `plugins` 陣列

1145* `No marketplace description provided`：新增頂層 `description` 以幫助使用者瞭解您的 marketplace1482* `No marketplace description provided`：新增頂層 `description` 以幫助使用者瞭解您的 marketplace

1146* `Plugin name "x" is not kebab-case`：plugin 名稱包含大寫字母、空格或特殊字元。重新命名為僅包含小寫字母、數字和連字號（例如，`my-plugin`）。Claude Code 接受其他形式，但 claude.ai marketplace 同步會拒絕它們。1483* `Plugin name "x" is not kebab-case`：重新命名為僅包含小寫字母、數字和連字號（例如，`my-plugin`）。Claude Code 接受其他形式，但 claude.ai marketplace 同步會拒絕它們。

1484* `Marketplace name "x" is reserved in Claude Desktop`：marketplace 名稱為 `org`、`org-provisioned` 或 `unknown`（任何大小寫）。Claude Code 接受這些名稱，但 Claude Desktop 的受管 marketplace 同步會拒絕整個 marketplace。重新命名 marketplace。在 v2.1.221 之前，`claude plugin validate` 不執行此檢查。

1485* `Marketplace name "x" is not accepted by Claude Desktop` 或 `Plugin name "x" is not accepted by Claude Desktop`：Claude Desktop 接受最多 128 個字元的名稱，由字母、數字、`.`、`_` 和 `-` 組成，以字母或數字開頭。Claude Code 接受其他形式，但 Claude Desktop 的受管 marketplace 同步會拒絕名稱檢查失敗的 marketplace，並以無聲方式捨棄名稱檢查失敗的 plugin 項目。重新命名 marketplace 或 plugin。在 v2.1.221 之前，`claude plugin validate` 不執行這些檢查。

1486

1487<h4 id="validate-a-plugin-or-a-directory-without-a-manifest">

1488 驗證沒有 manifest 的 plugin 或目錄

1489</h4>

1490

1491若要找到 frontmatter 無法解析的 skill、agent 和 command 檔案，請執行 `claude plugin validate` 並命名保存它們的目錄。Claude Code 不會查看您命名的目錄外的檔案。除了一次針對具有 `plugin.json` 的 plugin 執行外，每次執行都需要 Claude Code v2.1.233 或更新版本。

1492

1493<h5 id="pick-the-directory-to-name">

1494 選擇要命名的目錄

1495</h5>

1496

1497Claude Code 根據您命名的目錄檢查不同的檔案。在第一欄中找到您想檢查的內容，並執行該列的命令：

1498

1499| 若要檢查 | 執行 | Claude Code 檢查 |

1500| :------------------------------------------------------ | :-------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------- |

1501| 具有 `plugin.json` 的 plugin | `claude plugin validate ./plugins/my-plugin` | `plugin.json`、`hooks/hooks.json` 以及 plugin 根目錄下的 `skills`、`agents` 和 `commands` 目錄 |

1502| 一個 skill、agent 或 command 目錄，例如尚無 `plugin.json` 的 plugin | `claude plugin validate .claude/skills`、`~/.claude/agents` 或 `./my-plugin/agents` | 該目錄中的每個 skill、agent 或 command 檔案 |

1503| 其 skill 為其根 `SKILL.md` 的資料夾 | `claude plugin validate ./skills`，命名保存該資料夾的 `skills` 目錄 | 每個資料夾的根 `SKILL.md`。保存目錄必須命名為 `skills`；位於另一個名稱下的資料夾（例如 `plugins/`）沒有檢查其根 `SKILL.md` 的執行 |

1504| 一個專案的三個目錄一次 | `claude plugin validate .claude`，或沒有 `.claude-plugin/` manifest 的專案根目錄 | `.claude/skills`、`.claude/agents` 和 `.claude/commands` |

1505| 您的使用者層級目錄 | `claude plugin validate ~/.claude` | `~/.claude/skills`、`~/.claude/agents` 和 `~/.claude/commands` |

1506

1507<h5 id="check-a-plugin-whose-skill-is-its-root-skill-md">

1508 檢查其 skill 為其根 `SKILL.md` 的 plugin

1509</h5>

1510

1511當您針對 plugin 目錄執行 `claude plugin validate` 時，Claude Code 不檢查 plugin 根目錄下的 `SKILL.md`。當 plugin 位於名為 `skills` 的目錄中時，執行該命令兩次：

1512

1513* 命名該 `skills` 目錄以檢查 plugin 的根 `SKILL.md`。

1514* 命名 plugin 目錄以檢查其餘部分。

1515

1516當 plugin 位於另一個名稱下（例如 `plugins/`）時，`skills` 目錄執行不可用，沒有執行檢查其根 `SKILL.md`。

1517

1518<h5 id="check-files-behind-symlinks">

1519 檢查符號連結後的檔案

1520</h5>

1521

1522當您執行 `claude plugin validate` 時，Claude Code 不會跟隨您命名的目錄內的符號連結。它的作用取決於連結的位置：

1523

1524* **plugin 或 `.claude` 根目錄下的連結 `skills`、`agents` 或 `commands` 目錄**：Claude Code 警告其中沒有任何內容被讀取。

1525* **`skills`、`agents` 或 `commands` 目錄內的連結項目**：Claude Code 跳過它並警告，每個目錄，它跳過了多少個項目，工作階段會載入。

1526* **您命名的 `skills`、`agents` 或 `commands` 目錄本身是符號連結，或其父 `.claude` 目錄是**：Claude Code 報告錯誤並檢查其中沒有任何內容。改為命名真實目錄。

1527

1528在兩個 skill 情況下，執行通過並帶有警告。若要檢查連結的檔案，再次執行並命名直接保存它們的目錄：

1529

1530* **其 `skills` 目錄[連結到同級 plugin 的 skill](/docs/zh-TW/plugins-reference#share-files-within-a-marketplace-with-symlinks) 的 plugin**：命名同級 plugin 的目錄。

1531* **`~/.claude/skills` 或 `.claude/skills` 中的[符號連結 skill 項目](/docs/zh-TW/skills#where-skills-live)**：Claude Code 在工作階段中跟隨該項目。若要檢查它，命名一個名為 `skills` 的目錄，保存真實資料夾。

1532

1533<h5 id="read-the-validation-results">

1534 讀取驗證結果

1535</h5>

1536

1537乾淨的執行以 `Validation passed` 結束。

1538

1539`No manifest found in directory` 表示 Claude Code 在那裡找不到 `plugin.json` 或 `marketplace.json`，也找不到它在其下探測的目錄中的 skill、agent 或 command 檔案。改為命名保存您的檔案的 `skills`、`agents` 或 `commands` 目錄。

1540

1541Claude Code 從這些執行報告的兩個錯誤，以及每個的修正方式：

1542

1543* `YAML frontmatter failed to parse: ...`：修正 skill、agent 或 command 檔案的 frontmatter 區塊中的 YAML。在您執行此操作之前，工作階段從檔案讀取沒有 frontmatter 欄位

1544* `Invalid JSON syntax: ...` 在 `hooks/hooks.json` 上：修正 JSON 語法。在您執行此操作之前，工作階段載入 plugin 而不載入該檔案中的 hook。Claude Code 僅在 plugin 執行中報告此錯誤

1545

1546在 plugin 執行中，Claude Code 也警告 plugin 根目錄下的 `CLAUDE.md`。對於您透過 `plugin.json` 中的[元件路徑欄位](/docs/zh-TW/plugins-reference#component-path-fields)設定的路徑，Claude Code 檢查每個路徑是否存在，但不讀取那裡的檔案。

1147 1547

1148<h3 id="plugin-installation-failures">1548<h3 id="plugin-installation-failures">

1149 Plugin 安裝失敗1549 Plugin 安裝失敗

1171 1571

1172* 驗證您已使用您的 git 提供者進行驗證（例如，為 GitHub 執行 `gh auth status`）1572* 驗證您已使用您的 git 提供者進行驗證（例如，為 GitHub 執行 `gh auth status`）

1173* 檢查您的認證助手是否正確配置：`git config --global credential.helper`1573* 檢查您的認證助手是否正確配置：`git config --global credential.helper`

1174* 嘗試手動複製儲存庫以驗證您的認證有效1574* 執行 `git ls-remote <marketplace-url>` 以測試 git 是否可以自行驗證。如果 git 要求使用者名稱或密碼，請先儲存認證：對於 GitHub over HTTPS，執行 `gh auth setup-git`，對於 SSH 遠端，將您的金鑰載入 `ssh-agent`

1175 1575

1176對於背景自動更新：1576對於背景自動更新：

1177 1577

1196export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=11596export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

1197```1597```

1198 1598

1199設定此變數後，Claude Code 在 `git pull` 失敗時保留過時的 marketplace 複製，並繼續使用最後已知的良好狀態。對於儲存庫永遠無法到達的完全離線部署，請改用 [`CLAUDE_CODE_PLUGIN_SEED_DIR`](#pre-populate-plugins-for-containers) 在建置時預先填充 plugin 目錄。1599對於儲存庫永遠無法到達的完全離線部署，請改用 [`CLAUDE_CODE_PLUGIN_SEED_DIR`](#pre-populate-plugins-for-containers) 在建置時預先填充 plugin 目錄。

1200 1600

1201<h3 id="git-operations-time-out">1601<h3 id="git-operations-time-out">

1202 Git 操作逾時1602 Git 操作逾時

1216 相對路徑 plugin 在基於 URL 的 marketplace 中失敗1616 相對路徑 plugin 在基於 URL 的 marketplace 中失敗

1217</h3>1617</h3>

1218 1618

1219**症狀**：透過 URL（例如 `https://example.com/marketplace.json`）新增 marketplace，但具有相對路徑來源（如 `"./plugins/my-plugin"`）的 plugin 無法安裝，出現「path not found」錯誤。1619**症狀**：透過 URL（例如 `https://example.com/marketplace.json`）新增 marketplace，但具有相對路徑來源（如 `"./plugins/my-plugin"`）的 plugin 無法安裝，出現 `its marketplace entry path does not stay inside the marketplace directory` 錯誤。已安裝的 plugin 無法載入，出現 `Plugin source path refused` 錯誤。兩個訊息都有[錯誤參考項目](/docs/zh-TW/errors#marketplace-entry-path-does-not-stay-inside-the-marketplace-directory)。

1220 1620

1221**原因**：基於 URL 的 marketplace 僅下載 `marketplace.json` 檔案本身。它們不從伺服器下載 plugin 檔案。marketplace 項目中的相對路徑參考未下載的遠端伺服器上的檔案。1621**原因**：新增基於 URL 的 marketplace 僅下載 `marketplace.json` 檔案本身，Claude Code 不會從該伺服器按相對路徑擷取 plugin 檔案。marketplace 項目中的相對路徑參考未下載的遠端伺服器上的檔案。

1222 1622

1223**解決方案**：1623**解決方案**：

1224 1624

1225* **使用外部來源**：將 plugin 項目變更為使用 GitHub、npm 或 git URL 來源，而不是相對路徑：1625* **使用外部來源**：將 plugin 項目變更為相對路徑以外的任何 [plugin 來源](#plugin-sources)：

1226 ```json theme={null}1626 ```json theme={null}

1227 { "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }1627 { "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }

1228 ```1628 ```

1234 1634

1235**症狀**：Plugin 安裝但對檔案的參考失敗，特別是 plugin 目錄外的檔案1635**症狀**：Plugin 安裝但對檔案的參考失敗，特別是 plugin 目錄外的檔案

1236 1636

1237**原因**：Plugin 被複製到快取目錄而不是就地使用。參考 plugin 目錄外檔案的路徑（例如 `../shared-utils`）無法運作，因為這些檔案不會被複製。1637**原因**：Plugin 被複製到快取目錄而不是就地使用，除了[連結模式中的 `command` 來源](#copy-mode-and-link-mode)。參考複製 plugin 目錄外檔案的路徑（例如 `../shared-utils`）無法運作，因為這些檔案不會被複製。

1238 1638

1239**解決方案**：有關解決方案（包括符號連結和目錄重組），請參閱 [Plugin caching and file resolution](/docs/zh-TW/plugins-reference#plugin-caching-and-file-resolution)。1639**解決方案**：有關解決方案（包括符號連結和目錄重組），請參閱 [Plugin caching and file resolution](/docs/zh-TW/plugins-reference#plugin-caching-and-file-resolution)。

1240 1640

1247* [探索並安裝預先建立的 plugins](/docs/zh-TW/discover-plugins) - 從現有 marketplace 安裝 plugins1647* [探索並安裝預先建立的 plugins](/docs/zh-TW/discover-plugins) - 從現有 marketplace 安裝 plugins

1248* [Plugins](/docs/zh-TW/plugins) - 建立您自己的 plugins1648* [Plugins](/docs/zh-TW/plugins) - 建立您自己的 plugins

1249* [Plugins reference](/docs/zh-TW/plugins-reference) - 完整的技術規格和架構1649* [Plugins reference](/docs/zh-TW/plugins-reference) - 完整的技術規格和架構

1250* [Plugin settings](/docs/zh-TW/settings#plugin-settings) - Plugin 配置選項1650* [Plugin settings](/docs/zh-TW/settings-reference#plugin-settings) - Plugin 配置選項

1251* [strictKnownMarketplaces reference](/docs/zh-TW/settings#strictknownmarketplaces) - 受管 marketplace 限制1651* [strictKnownMarketplaces reference](/docs/zh-TW/settings-reference#strictknownmarketplaces) - 受管 marketplace 限制

prompt-caching.md +4 −2

Details

185 拒絕整個工具185 拒絕整個工具

186</h3>186</h3>

187 187

188新增裸工具名稱（如 `Bash` 或 `WebFetch`）作為[拒絕規則](/docs/zh-TW/permissions#manage-permissions)會將該工具從 Claude 的內容中完全移除。Claude Code 將內建工具定義載入到系統提示層，因此在工作階段中途新增或移除其中一個規則會使快取失效。Claude Code 會在下一個請求時套用變更，無論您是通過 `/permissions` 新增規則還是通過[直接編輯設定檔](/docs/zh-TW/settings#when-edits-take-effect)。這包括您在回合中途通過 `/permissions` 新增的規則。188新增裸工具名稱（如 `Bash` 或 `WebFetch`）作為[拒絕規則](/docs/zh-TW/permissions#manage-permissions)，Claude 無法從您的下一個請求開始呼叫該工具，無論您是通過 `/permissions` 新增規則還是通過[直接編輯設定檔](/docs/zh-TW/settings#when-edits-take-effect)。這包括您在回合中途通過 `/permissions` 新增的規則。

189 189

190只有在工具名稱位置相符的拒絕規則才有此效果：裸工具名稱、等效的 `Bash(*)` 形式或[工具名稱 glob](/docs/zh-TW/permissions#tool-name-wildcards)（如 `"*"`）。與只有 MCP 工具相符的 glob（如 `"mcp__*"`）會以相同方式移除這些工具，但當相符的工具[延遲](#connecting-or-disconnecting-an-mcp-server)（預設值）時會保留快取，因為延遲定義從未在快取的前綴中。範圍拒絕規則（如 `Bash(rm *)`）以及所有允許和詢問規則都不會變更 Claude 看到的工具。Claude Code 在 Claude 嘗試呼叫時檢查它們，保留前綴完整。190當[工具搜尋](/docs/zh-TW/mcp#scale-with-mcp-tool-search)處於活動狀態時（在支援的模型上為預設值），請求的工具定義不會變更，快取的前綴會保留。當工具搜尋不可用或已停用時，Claude Code 會從下一個請求中移除定義，這會使快取失效，稍後移除規則也會如此。

191

192只有在工具名稱位置相符的拒絕規則才有此效果：裸工具名稱、等效的 `Bash(*)` 形式或[工具名稱 glob](/docs/zh-TW/permissions#tool-name-wildcards)（如 `"*"`）。與只有 MCP 工具相符的 glob（如 `"mcp__*"`）會以相同方式阻止這些工具。範圍拒絕規則（如 `Bash(rm *)`）以及所有允許和詢問規則都不會變更 Claude 看到的工具。Claude Code 在 Claude 嘗試呼叫時檢查它們，保留前綴完整。

191 193

192<h3 id="compacting-the-conversation">194<h3 id="compacting-the-conversation">

193 壓縮對話195 壓縮對話

remote-control.md +2 −4

Details

138 138

139如果連接失敗，Claude Code 會顯示一個通知，說明失敗原因，將失敗原因的警告行新增到對話中，並將指示器切換到保留在原位的失敗狀態。要重新連接，執行 `/remote-control`，除非[原因說會話在其他地方被接管或結束，或伺服器找不到它](#session-ended-elsewhere)。139如果連接失敗，Claude Code 會顯示一個通知，說明失敗原因，將失敗原因的警告行新增到對話中，並將指示器切換到保留在原位的失敗狀態。要重新連接，執行 `/remote-control`，除非[原因說會話在其他地方被接管或結束，或伺服器找不到它](#session-ended-elsewhere)。

140 140

141在重新連接之前讀取原因。當會話從另一個裝置、應用程式或 Claude Code 會話被接管或結束，或伺服器找不到它時，原因會說明是哪一個，Claude Code 會省略其通常的執行 `/remote-control` 的建議：141<span id="session-ended-elsewhere" />在重新連接之前讀取原因。當會話從另一個裝置、應用程式或 Claude Code 會話被接管或結束，或伺服器找不到它時，原因會說明是哪一個，Claude Code 會省略其通常的執行 `/remote-control` 的建議：

~~142~~

143<span id="session-ended-elsewhere" />

144 142

145* **另一個裝置或 Claude Code 會話接管了會話**：只有在您想從該裝置奪回它時才執行 `/remote-control`。143* **另一個裝置或 Claude Code 會話接管了會話**：只有在您想從該裝置奪回它時才執行 `/remote-control`。

146* **您從另一個裝置或應用程式結束或封存了會話**：只有在您想要它回來時才執行 `/remote-control`；Claude Code 會重新開啟已封存的會話。144* **您從另一個裝置或應用程式結束或封存了會話**：只有在您想要它回來時才執行 `/remote-control`；Claude Code 會重新開啟已封存的會話。

1763. 現有對話歷史記錄中最後一條有意義的訊息1743. 現有對話歷史記錄中最後一條有意義的訊息

1774. 類似 `myhost-graceful-unicorn` 的自動生成名稱，其中 `myhost` 是您機器的主機名稱或您使用 `--remote-control-session-name-prefix` 設定的前綴1754. 類似 `myhost-graceful-unicorn` 的自動生成名稱，其中 `myhost` 是您機器的主機名稱或您使用 `--remote-control-session-name-prefix` 設定的前綴

178 176

179如果您沒有設定明確名稱，Claude Code 會在您發送提示後更新標題以反映您的提示。Claude Code 將自動生成的標題與您對話的語言相符，或與 [`language`](/docs/zh-TW/settings-reference#language) 設定相符（如果已配置）；語言匹配需要 Claude Code v2.1.176 或更新版本。177如果您沒有設定明確名稱，Claude Code 會在您發送提示後更新標題以反映您的提示。Claude Code 將自動生成的標題與您對話的語言相符，或與 [`language`](/docs/zh-TW/settings-reference#language) 設定相符（如果已配置）。

180 178

181當您從 claude.ai 或 Claude 應用程式重新命名會話時，Claude Code 也會更新在 `claude --resume` 中顯示的本地標題。Claude Code 將相同的重新命名應用於提示欄上顯示的會話名稱，以及當會話[在背景執行](/docs/zh-TW/agent-view)時 `claude agents` 清單中顯示的會話名稱。在 v2.1.221 之前，從 claude.ai 的會話清單或 Claude 應用程式中重新命名只會更新標題，CLI 會保留其先前的會話名稱；`/rename`（在 CLI 本身中執行）在任何版本上設定名稱。179當您從 claude.ai 或 Claude 應用程式重新命名會話時，Claude Code 也會更新在 `claude --resume` 中顯示的本地標題。Claude Code 將相同的重新命名應用於提示欄上顯示的會話名稱，以及當會話[在背景執行](/docs/zh-TW/agent-view)時 `claude agents` 清單中顯示的會話名稱。在 v2.1.221 之前，從 claude.ai 的會話清單或 Claude 應用程式中重新命名只會更新標題，CLI 會保留其先前的會話名稱；`/rename`（在 CLI 本身中執行）在任何版本上設定名稱。

182 180

sandbox-environments.md +1 −1

Details

83每個命令沙箱不涵蓋在會話中執行的所有內容：83每個命令沙箱不涵蓋在會話中執行的所有內容：

84 84

85* 其他 [built-in tools](/docs/zh-TW/tools-reference)（如 Read、Edit 和 WebFetch）在 Claude Code 進程內執行，不會生成任意程式碼。[Permission rules](/docs/zh-TW/permissions) 用於路徑或域來控制它們。85* 其他 [built-in tools](/docs/zh-TW/tools-reference)（如 Read、Edit 和 WebFetch）在 Claude Code 進程內執行，不會生成任意程式碼。[Permission rules](/docs/zh-TW/permissions) 用於路徑或域來控制它們。

~~86* [MCP](/docs/zh-TW/mcp) 伺服器和 hooks 是在主機上無約束執行的獨立進程。~~86* [MCP](/docs/zh-TW/mcp) 伺服器和 [command hooks](/docs/zh-TW/hooks#command-hook-fields) 是在主機上無約束執行的獨立進程。

87 87

88要將內建工具、MCP 伺服器和 hooks 全部放在一個作業系統邊界後面，請在 [sandbox runtime](#sandbox-runtime)、[dev container](#dev-containers) 或 [custom container](#custom-container) 內執行整個 Claude Code 進程。88要將內建工具、MCP 伺服器和 hooks 全部放在一個作業系統邊界後面，請在 [sandbox runtime](#sandbox-runtime)、[dev container](#dev-containers) 或 [custom container](#custom-container) 內執行整個 Claude Code 進程。

89 89

self-hosted-environments-deploy.md +1 −1

Details

486 486

487`--kill-session-after-min` 是失控工作階段的後擋。在 v2.1.260 或更新版本上的執行器上，達到限制的工作階段不會立即終止。執行器給它一個寬限窗口，預設 15 分鐘，您可以使用 [`SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS`](/docs/zh-TW/self-hosted-environments-reference#environment-variable-only-settings) 更改：487`--kill-session-after-min` 是失控工作階段的後擋。在 v2.1.260 或更新版本上的執行器上，達到限制的工作階段不會立即終止。執行器給它一個寬限窗口，預設 15 分鐘，您可以使用 [`SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS`](/docs/zh-TW/self-hosted-environments-reference#environment-variable-only-settings) 更改：

488 488

489* 如果工作階段等待其使用者，或其轉向已結束並且它僅持有背景任務，執行器立即釋放它。工作階段在其使用者發送下一條訊息時恢復。489* 如果工作階段等待其使用者，執行器會釋放它。如果其轉向已結束並且它僅持有背景任務，執行器會等待最多 60 秒讓這些任務完成，然後釋放它。當其使用者發送下一條訊息時，工作階段會恢復。

490* 如果轉向仍在執行，執行器等待轉向完成，或工作階段下一次等待其使用者，然後釋放它。490* 如果轉向仍在執行，執行器等待轉向完成，或工作階段下一次等待其使用者，然後釋放它。

491* 如果工作階段在寬限窗口結束時仍在執行器上，執行器終止它，任何執行中轉向的工作都會丟失。等待從執行中工具呼叫內部請求的批准的轉向是工作階段超過窗口的一種方式。491* 如果工作階段在寬限窗口結束時仍在執行器上，執行器終止它，任何執行中轉向的工作都會丟失。等待從執行中工具呼叫內部請求的批准的轉向是工作階段超過窗口的一種方式。

492 492

server-managed-settings.md +5 −4

Details

163 跨受管來源的個別金鑰例外163 跨受管來源的個別金鑰例外

164</h3>164</h3>

165 165

166有兩種金鑰是無合併規則的例外：166三種金鑰是無合併規則的例外：

167 167

168* **跨來源鎖定金鑰**：一小組金鑰，例如沙箱允許清單鎖定，[列在受管設定頁面上](/docs/zh-TW/managed-settings#precedence-within-the-managed-tier)。當任何管理員控制的受管來源設定它們時，Claude Code 會遵守它們；使用者可寫入的 HKCU 登錄層級被排除。當 [`policyHelper`](/docs/zh-TW/settings-reference#policyhelper) 提供受管設定時，其輸出是這些檢查讀取的唯一來源，除了 [`forceRemoteSettingsRefresh`](/docs/zh-TW/settings-reference#forceremotesettingsrefresh)，Claude Code 在啟動時直接從管理員來源讀取它。168* **跨來源鎖定金鑰**：一小組金鑰，例如沙箱允許清單鎖定，[列在受管設定頁面上](/docs/zh-TW/managed-settings#precedence-within-the-managed-tier)。當任何管理員控制的受管來源設定它們時，Claude Code 會遵守它們；使用者可寫入的 HKCU 登錄層級被排除。當 [`policyHelper`](/docs/zh-TW/settings-reference#policyhelper) 提供受管設定時，其輸出是這些檢查讀取的唯一來源，除了 [`forceRemoteSettingsRefresh`](/docs/zh-TW/settings-reference#forceremotesettingsrefresh)，Claude Code 在啟動時直接從管理員來源讀取它。

169* **`env` 區塊**：除了與認證金鑰配對的遙測單位和路由變數（下面涵蓋）外，它會跨管理員控制的來源按金鑰合併。對於每個環境變數，定義它的最高優先順序來源會獲勝，較低的管理員來源會填入較高來源未設定的變數。因此，端點管理的 `env` 項目會在伺服器管理的設定未設定該變數時套用，或在快取的伺服器值[等待伺服器確認時被保留](#fetch-and-caching-behavior)時套用。需要 Claude Code v2.1.223 或更新版本。在 v2.1.223 之前，Claude Code 僅套用選定來源的整個 `env` 區塊。169* **`env` 區塊**：除了與認證金鑰配對的遙測單位和路由變數（下面涵蓋）外，它會跨管理員控制的來源按金鑰合併。對於每個環境變數，定義它的最高優先順序來源會獲勝，較低的管理員來源會填入較高來源未設定的變數。因此，端點管理的 `env` 項目會在伺服器管理的設定未設定該變數時套用，或在快取的伺服器值[等待伺服器確認時被保留](#fetch-and-caching-behavior)時套用。需要 Claude Code v2.1.223 或更新版本。在 v2.1.223 之前，Claude Code 僅套用選定來源的整個 `env` 區塊。

170 * **遙測單位**：`OTEL_EXPORTER_OTLP_*` 匯出器金鑰、`OTEL_LOG_*` 內容擷取切換、`OTEL_LOGS_EXPORTER` 以及測試版追蹤變數 `ENABLE_BETA_TRACING_DETAILED` 和 `BETA_TRACING_ENDPOINT` 遵循設定任何這些變數的最高來源作為一個單位。傳遞 `otelHeadersHelper` 認證金鑰的來源也會聲稱該單位，但僅在它是選定來源時才會放置這些變數：未被選定但傳遞該金鑰的來源不會貢獻其中任何一個，仍然會阻止較低來源填入它們。無論哪種方式，來自一個來源的匯出器端點永遠無法與來自另一個來源的認證配對。170 * **遙測單位**：`OTEL_EXPORTER_OTLP_*` 匯出器金鑰、`OTEL_LOG_*` 內容擷取切換、`OTEL_LOGS_EXPORTER` 以及測試版追蹤變數 `ENABLE_BETA_TRACING_DETAILED` 和 `BETA_TRACING_ENDPOINT` 遵循設定任何這些變數的最高來源作為一個單位。傳遞 `otelHeadersHelper` 認證金鑰的來源也會聲稱該單位，但僅在它是選定來源時才會放置這些變數：未被選定但傳遞該金鑰的來源不會貢獻其中任何一個，仍然會阻止較低來源填入它們。無論哪種方式，來自一個來源的匯出器端點永遠無法與來自另一個來源的認證配對。

171 * **認證配對的路由**：將路由變數與選定來源專用認證金鑰（例如 `apiKeyHelper` 或 `otelHeadersHelper`）配對的來源，僅在它贏得該位置時才會貢獻這些路由變數。171 * **認證配對的路由**：將路由變數與選定來源專用認證金鑰（例如 `apiKeyHelper` 或 `otelHeadersHelper`）配對的來源，僅在它贏得該位置時才會貢獻這些路由變數。

172* **閘道登入金鑰**：Claude Code 永遠不會從伺服器管理的設定讀取 [`forceLoginGatewayUrl`](/docs/zh-TW/settings-reference#forcelogingatewayurl) 或 [`forceLoginMethod`](/docs/zh-TW/settings-reference#forceloginmethod) 的 `"gateway"` 值，因此選擇伺服器管理的設定既不會提供閘道登入，也不會隱藏在 MDM 原則或受管設定檔中設定的登入。[`managedSourcesBehavior` 項目](/docs/zh-TW/settings-reference#managedsourcesbehavior)說明機器上的哪個管理員來源提供它們。

172 173

173<h3 id="fetch-and-caching-behavior">174<h3 id="fetch-and-caching-behavior">

174 擷取和快取行為175 擷取和快取行為

286 Claude Code 不會為透過純 HTTP 到達的迴圈開發閘道儲存任何核准，因此對話方塊會在每次登入後再次出現。287 Claude Code 不會為透過純 HTTP 到達的迴圈開發閘道儲存任何核准，因此對話方塊會在每次登入後再次出現。

287* **任何其他認證**，例如 API 金鑰或 `CLAUDE_CODE_OAUTH_TOKEN`：一次核准傳遞的設定，與該設定目錄中設定的快取副本一起保留。當需要核准的設定變更，以及在您執行 `/logout` 或 `claude auth logout` 後（其中任何一個都會刪除快取副本），Claude Code 會再次顯示對話方塊。288* **任何其他認證**，例如 API 金鑰或 `CLAUDE_CODE_OAUTH_TOKEN`：一次核准傳遞的設定，與該設定目錄中設定的快取副本一起保留。當需要核准的設定變更，以及在您執行 `/logout` 或 `claude auth logout` 後（其中任何一個都會刪除快取副本），Claude Code 會再次顯示對話方塊。

288 289

290`sandbox.credentials` 或 `sandbox.network.tlsTerminate` 的核准也涵蓋這些相同傳遞設定中的 [`sandbox.network.allowedDomains`](/docs/zh-TW/settings-reference#sandbox-network-alloweddomains) 項目，因為兩個設定都作用於該允許清單。當您的管理員新增或移除其中一個項目時，對話方塊會再次出現，即使 `sandbox.network.allowedDomains` 本身不需要核准。

291

289使用已儲存的 claude.ai 登入：292使用已儲存的 claude.ai 登入：

290 293

291* 如果您登出並重新登入，或切換到另一個組織，稍後返回，Claude Code 在這些設定保持不變時不會再次顯示對話方塊，除非另一個帳戶在同一設定目錄中為該組織核准了它們。294* 如果您登出並重新登入，或切換到另一個組織，稍後返回，Claude Code 在這些設定保持不變時不會再次顯示對話方塊，除非另一個帳戶在同一設定目錄中為該組織核准了它們。

292* 如果您使用不同的帳戶登入同一個組織，Claude Code 即使設定保持不變也會再次顯示對話方塊。該帳戶的核准會取代前一個，因此當您切換回去時，Claude Code 會再次顯示對話方塊。295* 如果您使用不同的帳戶登入同一個組織，Claude Code 即使設定保持不變也會再次顯示對話方塊。該帳戶的核准會取代前一個，因此當您切換回去時，Claude Code 會再次顯示對話方塊。

293 296

294`sandbox.credentials` 或 `sandbox.network.tlsTerminate` 的核准也涵蓋這些相同傳遞設定中的 [`sandbox.network.allowedDomains`](/docs/zh-TW/settings-reference#sandbox-network-alloweddomains) 項目，因為兩個設定都作用於該允許清單。當您的管理員新增或移除其中一個項目時，對話方塊會再次出現，即使 `sandbox.network.allowedDomains` 本身不需要核准。

~~295~~

296Claude Code 無法總是顯示對話方塊。下面的每個案例都說明當它無法顯示時哪些設定會套用，以及您何時會再次看到對話方塊：297Claude Code 無法總是顯示對話方塊。下面的每個案例都說明當它無法顯示時哪些設定會套用，以及您何時會再次看到對話方塊：

297 298

298* **無法顯示對話方塊的互動工作階段**：Claude Code 不會套用傳遞的設定，並保留最後核准的設定。對話方塊會在下一個可以顯示它的工作階段中出現。需要 Claude Code v2.1.211 或更新版本。299* **無法顯示對話方塊的互動工作階段**：Claude Code 不會套用傳遞的設定，並保留最後核准的設定。對話方塊會在下一個可以顯示它的工作階段中出現。需要 Claude Code v2.1.211 或更新版本。

318 319

319Claude Code 也根據傳遞的值決定 [`API_FORCE_IDLE_TIMEOUT`](/docs/zh-TW/env-vars) 是否需要核准：真值只會開啟[主體閒置逾時](/docs/zh-TW/network-config#streaming-idle-watchdogs)，因此 Claude Code 會在不詢問使用者的情況下套用它。對於任何其他非空值，Claude Code 會顯示對話方塊。在 v2.1.248 之前，任何非空值都會觸發對話方塊。320Claude Code 也根據傳遞的值決定 [`API_FORCE_IDLE_TIMEOUT`](/docs/zh-TW/env-vars) 是否需要核准：真值只會開啟[主體閒置逾時](/docs/zh-TW/network-config#streaming-idle-watchdogs)，因此 Claude Code 會在不詢問使用者的情況下套用它。對於任何其他非空值，Claude Code 會顯示對話方塊。在 v2.1.248 之前，任何非空值都會觸發對話方塊。

320 321

321[`ANTHROPIC_CUSTOM_HEADERS`](/docs/zh-TW/env-vars#variables) 是否需要核准也取決於傳遞的值。僅標記請求的標頭（例如 `Accept-Language`）會在沒有對話方塊的情況下套用。命名認證、組織或租戶選擇器、路由或主機覆蓋，或 API 行為標頭（例如 `Authorization`、`X-Api-Key`、`Host`、`anthropic-beta` 或 `X-Amzn-Bedrock-*` 標頭）的行需要核准。命名不是有效 HTTP 標頭權杖的行，或其值包含 HTTP 標頭無法攜帶的字元的行也需要核准。檢查會符合標頭名稱內的單字，因此包含 `client` 和 `version` 的 `X-Client-Version` 也需要核准。在 v2.1.251 之前，任何 `ANTHROPIC_CUSTOM_HEADERS` 值都會在沒有核准的情況下套用。322[`ANTHROPIC_CUSTOM_HEADERS`](/docs/zh-TW/env-vars#variables) 是否需要核准也取決於傳遞的值。僅標記請求的標頭（例如 `Accept-Language`）會在沒有對話方塊的情況下套用。命名認證、組織或租戶選擇器、路由或主機覆蓋，或 API 行為標頭（例如 `Authorization`、`X-Api-Key`、`Host`、`anthropic-beta` 或 `X-Amzn-Bedrock-*` 標頭）的行需要核准。命名不是有效 HTTP 標頭權杖的行，或其值包含 HTTP 標頭無法攜帶的字元的行也需要核准。檢查會符合標頭名稱內的單字，所以包含 `client` 和 `version` 的 `X-Client-Version` 也需要核准。在 v2.1.251 之前，任何 `ANTHROPIC_CUSTOM_HEADERS` 值都會在沒有核准的情況下套用。

322 323

323[`ENABLE_BETA_TRACING_DETAILED`](/docs/zh-TW/env-vars#variables) 或 [`OTEL_LOG_RAW_API_BODIES`](/docs/zh-TW/env-vars#variables) 的 `0` 或 `false` 等假值會在沒有對話方塊的情況下套用，因為它只會關閉詳細追蹤或原始 API 主體擷取。任何其他非空值都需要核准。324[`ENABLE_BETA_TRACING_DETAILED`](/docs/zh-TW/env-vars#variables) 或 [`OTEL_LOG_RAW_API_BODIES`](/docs/zh-TW/env-vars#variables) 的 `0` 或 `false` 等假值會在沒有對話方塊的情況下套用，因為它只會關閉詳細追蹤或原始 API 主體擷取。任何其他非空值都需要核准。

324 325

settings-reference.md +8 −10

Details

830 `advisorModel`830 `advisorModel`

831</h3>831</h3>

832 832

833選擇當 Claude 呼叫伺服器端[顧問工具](/docs/zh-TW/advisor)時回答的模型。取消設定以關閉顧問。顧問的能力必須至少與您的主要模型相同；當不符合時，Claude Code 會傳送不含顧問的請求。請參閱[選擇顧問模型](/docs/zh-TW/advisor#choose-an-advisor-model)。833選擇當 Claude 呼叫伺服器端[顧問工具](/docs/zh-TW/advisor)時回答的模型。取消設定以關閉顧問。顧問的能力必須至少與您的主要模型相同。請參閱[選擇顧問模型](/docs/zh-TW/advisor#choose-an-advisor-model)以了解接受的配對及選擇未接受的配對時會發生什麼。

834 834

835您通常不會手動編輯此金鑰。執行 `/advisor` 以開啟選擇器，顯示目前選擇、可以提供建議的模型和**無顧問**。Claude Code 會將您的選擇儲存到 `~/.claude/settings.json` 中的此金鑰。如果您從[遠端控制](/docs/zh-TW/remote-control)用戶端或附加到遠端工作者的工作階段中選擇，該選擇僅適用於該工作階段，不會變更此金鑰。835您通常不會手動編輯此金鑰。執行 `/advisor` 以開啟選擇器，顯示目前選擇、可以提供建議的模型和**無顧問**。Claude Code 會將您的選擇儲存到 `~/.claude/settings.json` 中的此金鑰。如果您從[遠端控制](/docs/zh-TW/remote-control)用戶端或附加到遠端工作者的工作階段中選擇，該選擇僅適用於該工作階段，不會變更此金鑰。

836 836

3308 `footerLinksRegexes`3308 `footerLinksRegexes`

3309</h3>3309</h3>

3310 3310

3311當正規表達式符合轉換輸出時，在輸入框下方的頁尾中渲染額外的可點擊徽章：工具結果，包括檔案內容和擷取的頁面，以及 Claude 自己的回應。使用它將專案 CLI 列印的 ID（例如審查工具和問題追蹤器）轉換為工作階段連結。需要 Claude Code v2.1.176 或更新版本。3311當正規表達式符合轉換輸出時，在輸入框下方的頁尾中渲染額外的可點擊徽章：工具結果，包括檔案內容和擷取的頁面，以及 Claude 自己的回應。使用它將專案 CLI 列印的 ID（例如審查工具和問題追蹤器）轉換為工作階段連結。

3312 3312

3313* **範圍**：[`使用者或受管`](#scopes)3313* **範圍**：[`使用者或受管`](#scopes)

3314* **類型**：物件陣列，每個物件的 `type` 設定為 `"regex"`、`pattern` 正規表達式、`url` 範本和可選的 `label`；`url` 和 `label` 中的 `{name}` 預留位置從 `pattern` 中的具名擷取群組填充3314* **類型**：物件陣列，每個物件的 `type` 設定為 `"regex"`、`pattern` 正規表達式、`url` 範本和可選的 `label`；`url` 和 `label` 中的 `{name}` 預留位置從 `pattern` 中的具名擷取群組填充

3329}3329}

3330```3330```

3331 3331

3332配置此項後，當 `PROJ-1234` 出現在工具結果或 Claude 的回覆中時，頁尾中會出現 `PROJ-1234` 徽章，連結到 `https://issues.example.com/browse/PROJ-1234`。需要 Claude Code v2.1.176 或更新版本。3332配置此項後，當 `PROJ-1234` 出現在工具結果或 Claude 的回覆中時，頁尾中會出現 `PROJ-1234` 徽章，連結到 `https://issues.example.com/browse/PROJ-1234`。

3333 3333

3334<h4 id="badge-constraints">3334<h4 id="badge-constraints">

3335 徽章限制3335 徽章限制

3916 `wheelScrollAccelerationEnabled`3916 `wheelScrollAccelerationEnabled`

3917</h3>3917</h3>

3918 3918

3919在[全螢幕渲染](/docs/zh-TW/fullscreen#mouse-wheel-scrolling)中快速捲動期間加速滑鼠滾輪捲動速度。將其設定為 `false` 以獲得每個滾輪凹口的恆定捲動速率。需要 Claude Code v2.1.174 或更新版本。3919在[全螢幕渲染](/docs/zh-TW/fullscreen#mouse-wheel-scrolling)中快速捲動期間加速滑鼠滾輪捲動速度。將其設定為 `false` 以獲得每個滾輪凹口的恆定捲動速率。

3920 3920

3921* **範圍**：[`任何檔案`](#scopes)3921* **範圍**：[`任何檔案`](#scopes)

3922* **類型**：布林值3922* **類型**：布林值

3930}3930}

3931```3931```

3932 3932

3933需要 Claude Code v2.1.174 或更新版本。

~~3934~~

3935<h2 id="git-and-attribution">3933<h2 id="git-and-attribution">

3936 Git 和歸屬3934 Git 和歸屬

3937</h2>3935</h2>

6156在 `"merge"` 下，Claude Code 按其種類合併每個金鑰。此表格為每種金鑰提供規則。限制允許清單、整體取值和最高來源專用列命名它們涵蓋的每個金鑰，其他列提供範例：6154在 `"merge"` 下，Claude Code 按其種類合併每個金鑰。此表格為每種金鑰提供規則。限制允許清單、整體取值和最高來源專用列命名它們涵蓋的每個金鑰，其他列提供範例：

6157 6155

6158| 金鑰種類 | Claude Code 如何合併它 | 金鑰 |6156| 金鑰種類 | Claude Code 如何合併它 | 金鑰 |

6159| :----------- | :--------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |6157| :----------- | :--------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

6160| 清單 | 合併來自每個來源的項目 | [`permissions.allow`](#permissions-allow)、[`sandbox.network.allowedDomains`](#sandbox-network-alloweddomains) 和其他清單金鑰 |6158| 清單 | 合併來自每個來源的項目 | [`permissions.allow`](#permissions-allow)、[`sandbox.network.allowedDomains`](#sandbox-network-alloweddomains) 和其他清單金鑰 |

6161| 鎖定 | 套用任何來源設定的最嚴格值。當沒有來源設定嚴格值時，只從最高來源套用較寬鬆的值 | [`allowManagedPermissionRulesOnly`](#allowmanagedpermissionrulesonly)、[`permissions.disableBypassPermissionsMode`](#permissions-disablebypasspermissionsmode) 和其他布林值或列舉鎖定 |6159| 鎖定 | 套用任何來源設定的最嚴格值。當沒有來源設定嚴格值時，只從最高來源套用較寬鬆的值 | [`allowManagedPermissionRulesOnly`](#allowmanagedpermissionrulesonly)、[`permissions.disableBypassPermissionsMode`](#permissions-disablebypasspermissionsmode) 和其他布林值或列舉鎖定 |

6162| 限制允許清單 | 從設定它的最高來源整體取值清單，不從較低的來源新增項目。當最高來源未設定時，從下一個較低的來源整體取值 | [`availableModels`](#availablemodels)、[`allowedMcpServers`](#allowedmcpservers)、[`strictKnownMarketplaces`](#strictknownmarketplaces)、[`allowedChannelPlugins`](#allowedchannelplugins) 和 [`fallbackModel`](#fallbackmodel) 鏈 |6160| 限制允許清單 | 從設定它的最高來源整體取值清單，不從較低的來源新增項目。當最高來源未設定時，從下一個較低的來源整體取值 | [`availableModels`](#availablemodels)、[`allowedMcpServers`](#allowedmcpservers)、[`strictKnownMarketplaces`](#strictknownmarketplaces)、[`allowedChannelPlugins`](#allowedchannelplugins) 和 [`fallbackModel`](#fallbackmodel) 鏈 |

6163| 整體取值 | 從設定它的最高來源整體取值，不合併來自較低來源的項目或欄位。當最高來源未設定時，從下一個較低的來源整體取值 | [`sandbox.credentials.awsPairs`](#sandbox-credentials-awspairs)、[`sandbox.ripgrep`](#sandbox-ripgrep) |6161| 整體取值 | 從設定它的最高來源整體取值，不合併來自較低來源的項目或欄位。當最高來源未設定時，從下一個較低的來源整體取值 | [`sandbox.credentials.awsPairs`](#sandbox-credentials-awspairs)、[`sandbox.ripgrep`](#sandbox-ripgrep) |

6165| 只從最高優先順序來源讀取 | 只從攜帶原則金鑰的最高優先順序來源讀取金鑰，因此即使最高來源未設定任何值，較低來源的值也會被忽略 | [`apiKeyHelper`](#apikeyhelper)、[`awsAuthRefresh`](#awsauthrefresh)、[`awsCredentialExport`](#awscredentialexport)、[`gcpAuthRefresh`](#gcpauthrefresh)、[`otelHeadersHelper`](#otelheadershelper)、`proxyAuthHelper`、[`forceLoginOrgUUID`](#forceloginorguuid)、[`forceLoginMethod`](#forceloginmethod)、[`forceLoginGatewayUrl`](#forcelogingatewayurl)、[`parentSettingsBehavior`](#parentsettingsbehavior)、[`modelPicker`](#modelpicker)、[`policyHelper`](#policyhelper)、[`permissions.defaultMode`](#permissions-defaultmode) |6163| 只從最高優先順序來源讀取 | 只從攜帶原則金鑰的最高優先順序來源讀取金鑰，因此即使最高來源未設定任何值，較低來源的值也會被忽略 | [`apiKeyHelper`](#apikeyhelper)、[`awsAuthRefresh`](#awsauthrefresh)、[`awsCredentialExport`](#awscredentialexport)、[`gcpAuthRefresh`](#gcpauthrefresh)、[`otelHeadersHelper`](#otelheadershelper)、`proxyAuthHelper`、[`forceLoginOrgUUID`](#forceloginorguuid)、[`forceLoginMethod`](#forceloginmethod) 的 `"claudeai"` 和 `"console"` 值、[`parentSettingsBehavior`](#parentsettingsbehavior)、[`modelPicker`](#modelpicker)、[`policyHelper`](#policyhelper)、[`permissions.defaultMode`](#permissions-defaultmode) |

6166| `env` | [在管理員來源間按變數合併](/docs/zh-TW/managed-settings#keys-read-from-every-admin-source)，在 `"first-wins"` 和 `"merge"` 下都是 | [`env`](#env) |6164| `env` | [在管理員來源間按變數合併](/docs/zh-TW/managed-settings#keys-read-from-every-admin-source)，在 `"first-wins"` 和 `"merge"` 下都是 | [`env`](#env) |

6168 6166

6169整體取值 `sandbox.credentials.awsPairs` 和 `sandbox.ripgrep` 需要 Claude Code v2.1.257 或更新版本。6167整體取值 `sandbox.credentials.awsPairs` 和 `sandbox.ripgrep` 需要 Claude Code v2.1.257 或更新版本。

6170 6168

6171這些金鑰中的三個新增了它們自己的條件：6169這些金鑰中的幾個新增了表格未顯示的條件：

6172 6170

6173* **[`policyHelper`](#policyhelper)**：Claude Code 只在攜帶原則金鑰的最高來源是 MDM 原則或受管設定檔案時接受它，因此在伺服器受管設定下它不適用。6171* **[`policyHelper`](#policyhelper)**：Claude Code 只在攜帶原則金鑰的最高來源是 MDM 原則或受管設定檔案時接受它，因此在伺服器受管設定下它不適用。

6174* **[`modelOverrides`](#modeloverrides)**：與 `availableModels` 配對。Claude Code 從設定它的最高來源取值 `modelOverrides`，除非較高的來源設定 `availableModels` 而不設定 `modelOverrides`。在這種情況下，它會忽略來自每個來源的 `modelOverrides`。6172* **[`modelOverrides`](#modeloverrides)**：與 `availableModels` 配對。Claude Code 從設定它的最高來源取值 `modelOverrides`，除非較高的來源設定 `availableModels` 而不設定 `modelOverrides`。在這種情況下，它會忽略來自每個來源的 `modelOverrides`。

6175* **[`forceLoginGatewayUrl`](#forcelogingatewayurl) 和 [`forceLoginMethod`](#forceloginmethod) 的 `"gateway"` 值**：Claude Code 只從機器本身上的受管來源讀取它們，並忽略伺服器受管設定中的它們。機器的值即使在伺服器受管設定也存在時也適用。6173* **[`forceLoginGatewayUrl`](#forcelogingatewayurl) 和 [`forceLoginMethod`](#forceloginmethod) 的 `"gateway"` 值**：Claude Code 永遠不會從伺服器受管設定讀取它們，因此那裡的值既不適用也不隱藏在 MDM 原則或受管設定檔案中設定的值。在機器上的管理員來源中，只有攜帶原則金鑰的最高排名來源提供它們，無論伺服器受管設定是否也存在。

6176 6174

6177若要確認機器上合併了哪些來源，請執行 `/status` 並[讀取 `Setting sources` 行](/docs/zh-TW/managed-settings#read-the-source-in-/status)。6175若要確認機器上合併了哪些來源，請執行 `/status` 並[讀取 `Setting sources` 行](/docs/zh-TW/managed-settings#read-the-source-in-/status)。

6178 6176

terminal-config.md +4 −3

Details

27在大多數終端機中，您也可以按 Shift+Enter，但支援情況因終端機模擬器而異：27在大多數終端機中，您也可以按 Shift+Enter，但支援情況因終端機模擬器而異：

28 28

29| 終端機 | Shift+Enter 用於換行 |29| 終端機 | Shift+Enter 用於換行 |

~~30| :---------------------------------------------------------------- | :--------------------------- |~~30| :---------------------------------------------------------------- | :------------------------------------- |

31| Ghostty、Kitty、iTerm2、WezTerm、Warp、Apple Terminal、Windows Terminal | 無需設定即可使用 |31| Ghostty、Kitty、iTerm2、WezTerm、Warp、Apple Terminal、Windows Terminal | 無需設定即可使用 |

~~32| VS Code、Cursor、Devin Desktop、Alacritty、Zed | 執行一次 `/terminal-setup` |~~32| 支援 kitty 鍵盤協議的其他終端機，例如 foot 和 Alacritty 0.16 或更新版本 | 無需設定即可使用。需要 Claude Code v2.1.269 或更新版本 |

33| VS Code、Cursor、Devin Desktop、Alacritty 0.16 之前的版本、Zed | 執行一次 `/terminal-setup` |

33| gnome-terminal、JetBrains IDE（例如 PyCharm 和 Android Studio） | 不可用；使用 Ctrl+J 或 `\` 然後 Enter |34| gnome-terminal、JetBrains IDE（例如 PyCharm 和 Android Studio） | 不可用；使用 Ctrl+J 或 `\` 然後 Enter |

34 35

35對於 VS Code、Cursor、Devin Desktop、Alacritty 和 Zed，`/terminal-setup` 會將 Shift+Enter 快捷鍵寫入終端機的設定檔。在首次執行時，您會看到確認訊息，例如 `Installed VSCode terminal Shift+Enter key binding`。現有的快捷鍵設定會保留；如果您看到類似 `VSCode terminal Shift+Enter key binding already configured` 的訊息，表示未進行任何變更。請直接在主機終端機中執行 `/terminal-setup`，而不是在 tmux 或 screen 內執行，因為它需要寫入主機終端機的設定。36對於 VS Code、Cursor、Devin Desktop、Alacritty 0.16 之前的版本和 Zed，`/terminal-setup` 會將 Shift+Enter 快捷鍵寫入終端機的設定檔。在首次執行時，您會看到確認訊息，例如 `Installed VSCode terminal Shift+Enter key binding`。現有的快捷鍵設定會保留；如果您看到類似 `VSCode terminal Shift+Enter key binding already configured` 的訊息，表示未進行任何變更。請直接在主機終端機中執行 `/terminal-setup`，而不是在 tmux 或 screen 內執行，因為它需要寫入主機終端機的設定。

36 37

37在 VS Code、Cursor 和 Devin Desktop 中，`/terminal-setup` 也會更新兩個編輯器設定：它將 `terminal.integrated.gpuAcceleration` 設定為 `"off"` 以防止整合終端機中的文字亂碼，並設定 `terminal.integrated.mouseWheelScrollSensitivity` 以在[全螢幕模式](/docs/zh-TW/fullscreen)中實現更平順的捲動。若要復原 GPU 加速變更，請將其設回 `"auto"` 並重新載入編輯器視窗。38在 VS Code、Cursor 和 Devin Desktop 中，`/terminal-setup` 也會更新兩個編輯器設定：它將 `terminal.integrated.gpuAcceleration` 設定為 `"off"` 以防止整合終端機中的文字亂碼，並設定 `terminal.integrated.mouseWheelScrollSensitivity` 以在[全螢幕模式](/docs/zh-TW/fullscreen)中實現更平順的捲動。若要復原 GPU 加速變更，請將其設回 `"auto"` 並重新載入編輯器視窗。

38 39

troubleshoot-install.md +1 −29

Details

417 417

418`curl ... | bash` 命令下載指令碼並將其傳送到 Bash 以執行。此錯誤以及相關的 `curl: (23) Failure writing output to destination` 表示 Bash 未收到完整的指令碼。結束代碼 56 表示下載本身被中斷，結束代碼 23 表示 curl 無法將其收到的內容寫入管道，通常是因為 Bash 提前結束。418`curl ... | bash` 命令下載指令碼並將其傳送到 Bash 以執行。此錯誤以及相關的 `curl: (23) Failure writing output to destination` 表示 Bash 未收到完整的指令碼。結束代碼 56 表示下載本身被中斷，結束代碼 23 表示 curl 無法將其收到的內容寫入管道，通常是因為 Bash 提前結束。

419 419

420**解決方案：**420測試您是否可以連線到 `downloads.claude.ai`，請參閱[檢查網路連線](#check-network-connectivity)中的檢查。如果您連線到伺服器，原始失敗可能是間歇性的；重試安裝命令。您也可以[嘗試替代安裝方法](/docs/zh-TW/setup#install-claude-code)。

~~421~~

4221. **檢查網路穩定性**：Claude Code 二進位檔託管在 `downloads.claude.ai`。測試您是否可以連線到它：

~~423~~

424 ```bash theme={null}

425 curl -sI https://downloads.claude.ai/claude-code-releases/latest

426 ```

~~427~~

428 `HTTP/2 200` 行表示您已連線到伺服器，原始失敗可能是間歇性的；重試安裝命令。其他結果指向原因：

~~429~~

430 * `403`：通常是代理或網路篩選器阻止主機，或 Claude Code [在您的地區不可用](https://www.anthropic.com/supported-countries)

431 * `5xx`：通常是暫時服務問題；等待幾分鐘並重試

432 * `Could not resolve host` 或連線逾時：您的網路正在阻止下載

~~433~~

4342. **嘗試替代安裝方法**：

~~435~~

436 在 macOS 上：

~~437~~

438 ```bash theme={null}

439 brew install --cask claude-code

440 ```

~~441~~

442 在 Windows 上：

~~443~~

444 ```powershell theme={null}

445 winget install Anthropic.ClaudeCode

446 ```

~~447~~

448 然後執行 `claude --version` 以確認：命令列印版本號，例如 `2.1.211 (Claude Code)`。如果 shell 報告找不到 `claude`，開啟新的終端視窗並重試：您安裝的工作階段保留其舊的 `PATH`。

449 421

450<h3 id="homebrew-cask-unavailable-or-outdated">422<h3 id="homebrew-cask-unavailable-or-outdated">

451 Homebrew cask 無法使用或已過時423 Homebrew cask 無法使用或已過時

vs-code.md +17 −10

Details

58 58

59 * **活動列**：點擊左側邊欄中的 Spark 圖示以開啟工作階段清單。點擊任何工作階段以將其開啟至您的[偏好位置](#extension-settings)，或開始新的工作階段。此圖示在活動列中始終可見。59 * **活動列**：點擊左側邊欄中的 Spark 圖示以開啟工作階段清單。點擊任何工作階段以將其開啟至您的[偏好位置](#extension-settings)，或開始新的工作階段。此圖示在活動列中始終可見。

60 * **命令面板**：`Cmd+Shift+P`（Mac）或 `Ctrl+Shift+P`（Windows/Linux），輸入「Claude Code」，然後選擇一個選項，例如「在新標籤中開啟」60 * **命令面板**：`Cmd+Shift+P`（Mac）或 `Ctrl+Shift+P`（Windows/Linux），輸入「Claude Code」，然後選擇一個選項，例如「在新標籤中開啟」

61 * **狀態列**：如果您已將 [`preferredLocation`](#extension-settings) 設定為 `sidebar`，或使用**Claude Code: Open in Side Bar** 開啟 Claude，請點擊視窗右下角的 **✱ Claude Code**。即使沒有開啟檔案，這也能運作。61 * **狀態列**：如果您已將 [`preferredLocation`](#extension-settings) 設定為 `sidebar`，或使用**Claude Code: Open in Side Bar** 開啟 Claude，請點擊視窗右下角的 **✻ Claude Code**。即使沒有開啟檔案，這也能運作。

62 62

63 您可以拖曳 Claude 面板以在 VS Code 中的任何位置重新定位。詳細資訊請參閱[自訂您的工作流程](#customize-your-workflow)。63 您可以拖曳 Claude 面板以在 VS Code 中的任何位置重新定位。詳細資訊請參閱[自訂您的工作流程](#customize-your-workflow)。

64 </Step>64 </Step>

116 * 在 Customize 部分中選擇 **Output styles** 以選擇[輸出樣式](/docs/zh-TW/output-styles)，包括您的自訂樣式。需要 Claude Code v2.1.257 或更新版本。116 * 在 Customize 部分中選擇 **Output styles** 以選擇[輸出樣式](/docs/zh-TW/output-styles)，包括您的自訂樣式。需要 Claude Code v2.1.257 或更新版本。

117 117

118 若要改為建立自訂樣式，請從 **Output styles** 菜單中選擇 **Build a custom style**。Claude Code 會在專案或使用者層級為您寫入[樣式檔案](/docs/zh-TW/output-styles#create-a-custom-output-style)。需要 Claude Code v2.1.261 或更新版本。118 若要改為建立自訂樣式，請從 **Output styles** 菜單中選擇 **Build a custom style**。Claude Code 會在專案或使用者層級為您寫入[樣式檔案](/docs/zh-TW/output-styles#create-a-custom-output-style)。需要 Claude Code v2.1.261 或更新版本。

119 * 在 Customize 部分中選擇 **Hooks** 以檢視會話中載入的 [hooks](/docs/zh-TW/hooks)，按事件分組。您可以新增、編輯或移除儲存在您的使用者、專案和本機設定檔中的 hooks。來自其他來源（例如受管設定或外掛程式）的 Hooks 是唯讀的。需要 Claude Code v2.1.269 或更新版本。

120 * 在 Customize 部分中選擇 **Permissions** 以檢視會話的[權限規則](/docs/zh-TW/permissions)，分組為 Allow、Ask 和 Deny。您可以將規則新增到您的使用者、專案或本機設定，並移除儲存在那裡的規則。來自其他來源（例如受管設定或僅針對此會話進行的批准）的規則是唯讀的。需要 Claude Code v2.1.269 或更新版本。

119 * Settings 部分包括 **Enable Remote Control for all sessions**，它設定 [`remoteControlAtStartup`](/docs/zh-TW/settings-reference#remotecontrolatstartup) 以控制[新的互動式會話是否自動連接到 Remote Control](/docs/zh-TW/remote-control#enable-remote-control-for-all-sessions)。需要 Claude Code v2.1.203 或更新版本。121 * Settings 部分包括 **Enable Remote Control for all sessions**，它設定 [`remoteControlAtStartup`](/docs/zh-TW/settings-reference#remotecontrolatstartup) 以控制[新的互動式會話是否自動連接到 Remote Control](/docs/zh-TW/remote-control#enable-remote-control-for-all-sessions)。需要 Claude Code v2.1.203 或更新版本。

120 122

121 當您在 VS Code 視窗中開啟或關閉切換開關時，變更會套用到該 VS Code 視窗中已開啟的會話，而不僅僅是您之後啟動的會話。如果您關閉它，開啟的會話會中斷連接。使用 Claude Code v2.1.261 或更新版本，變更也會到達您其他 VS Code 視窗中開啟的會話。123 當您在 VS Code 視窗中開啟或關閉切換開關時，變更會套用到該 VS Code 視窗中已開啟的會話，而不僅僅是您之後啟動的會話。如果您關閉它，開啟的會話會中斷連接。使用 Claude Code v2.1.261 或更新版本，變更也會到達您其他 VS Code 視窗中開啟的會話。

122 * Settings 部分也包括 **Focus view**，它隱藏工具呼叫、工具結果和思考在可展開的列後面，只留下您的提示和 Claude 的回應。Claude 最新的待辦事項清單保持可見，待處理問題中 Claude 詢問的文字也保持可見；這需要 Claude Code v2.1.225 或更新版本。在那裡切換它，使用 `Ctrl+Option+F`（Mac）/ `Ctrl+Alt+F`（Windows/Linux），或從命令選擇區使用 **Claude Code: Toggle Focus view**。變更會套用到每個開啟的會話並在會話間保持。需要 Claude Code v2.1.221 或更新版本。124 * Settings 部分也包括 **Focus view**，它隱藏工具呼叫、工具結果和思考在可展開的列後面，只留下您的提示和 Claude 的回應。在那裡切換它，使用 `Ctrl+Option+F`（Mac）/ `Ctrl+Alt+F`（Windows/Linux），或從命令選擇區使用 **Claude Code: Toggle Focus view**。變更會套用到每個開啟的會話並在會話間保持。需要 Claude Code v2.1.221 或更新版本。

125

126 Claude 最新的待辦事項清單保持可見，待處理問題中 Claude 詢問的文字也保持可見；這需要 Claude Code v2.1.225 或更新版本。當 Claude 執行 [subagents](/docs/zh-TW/sub-agents) 時，帶有其最新活動的即時進度列會出現在啟動它們的工具呼叫群組下。這需要 Claude Code v2.1.269 或更新版本。

123 * 若要報告錯誤，請點擊菜單底部的 **Report a problem**，或輸入 `/bug` 或 `/feedback` 並附上可選的描述以預填報告。當您提交報告且您已在第一方連接上登入 Anthropic 時，Claude Code 會將其傳送給 Anthropic。在第三方提供者上，或沒有 Anthropic 認證時，對話方塊仍會開啟，但提交會顯示錯誤且不傳送任何內容：與 CLI 的 `/bug` 不同，擴充功能不會寫入本機存檔。需要 Claude Code v2.1.229 或更新版本。127 * 若要報告錯誤，請點擊菜單底部的 **Report a problem**，或輸入 `/bug` 或 `/feedback` 並附上可選的描述以預填報告。當您提交報告且您已在第一方連接上登入 Anthropic 時，Claude Code 會將其傳送給 Anthropic。在第三方提供者上，或沒有 Anthropic 認證時，對話方塊仍會開啟，但提交會顯示錯誤且不傳送任何內容：與 CLI 的 `/bug` 不同，擴充功能不會寫入本機存檔。需要 Claude Code v2.1.229 或更新版本。

124* **Side questions**：輸入 `/btw` 後跟一個問題以詢問有關您的會話的問題[而不新增到對話](/docs/zh-TW/interactive-mode#side-questions-with-%2Fbtw)。答案會在聊天旁的面板中開啟，您可以在其中提出後續問題。執行緒在視窗重新載入後仍然存在。Claude Code 保留最新的 20 個交換，並根據 [`cleanupPeriodDays`](/docs/zh-TW/settings-reference#cleanupperioddays) 排程過期儲存的執行緒，只要 Claude Code 可以[安全地確定保留期](/docs/zh-TW/claude-directory#cleaned-up-automatically)。若要清除執行緒，請點擊面板中的垃圾桶圖示。需要 Claude Code v2.1.227 或更新版本。128* **Side questions**：輸入 `/btw` 後跟一個問題以詢問有關您的會話的問題[而不新增到對話](/docs/zh-TW/interactive-mode#side-questions-with-%2Fbtw)。答案會在聊天旁的面板中開啟，您可以在其中提出後續問題。執行緒在視窗重新載入後仍然存在。Claude Code 保留最新的 20 個交換，並根據 [`cleanupPeriodDays`](/docs/zh-TW/settings-reference#cleanupperioddays) 排程過期儲存的執行緒，只要 Claude Code 可以[安全地確定保留期](/docs/zh-TW/claude-directory#cleaned-up-automatically)。若要清除執行緒，請點擊面板中的垃圾桶圖示。需要 Claude Code v2.1.227 或更新版本。

125* **Context indicator**：提示框顯示您使用了多少 Claude 的內容視窗。Claude 會在需要時自動壓縮，或您可以手動執行 `/compact`。129* **Context indicator**：提示框顯示您使用了多少 Claude 的內容視窗。Claude 會在需要時自動壓縮，或您可以手動執行 `/compact`。

130* **Agent map**：當對話包括 [subagents](/docs/zh-TW/sub-agents) 時，代理計數（例如 **2 agents**）會出現在提示框底部。其點顯示任何 subagent 是否正在工作或等待您的權限。

131

132 點擊代理計數以開啟代理地圖，它將對話的 subagents 繪製為主代理下的樹，每個都有其狀態、經過的時間和令牌計數。點擊 subagent 以查看其提示和工具呼叫、開啟其唯讀文字記錄，或在其執行時停止它。需要 Claude Code v2.1.269 或更新版本。

126* **Extended thinking**：讓 Claude 花更多時間推理複雜問題。透過命令菜單（`/`）開啟它。Claude 的推理在對話中顯示為摺疊的區塊：點擊一個區塊以閱讀它，或按 `Ctrl+O` 以展開或摺疊會話中的每個思考區塊。請參閱[Extended thinking](/docs/zh-TW/model-config#extended-thinking)以了解詳細資訊。133* **Extended thinking**：讓 Claude 花更多時間推理複雜問題。透過命令菜單（`/`）開啟它。Claude 的推理在對話中顯示為摺疊的區塊：點擊一個區塊以閱讀它，或按 `Ctrl+O` 以展開或摺疊會話中的每個思考區塊。請參閱[Extended thinking](/docs/zh-TW/model-config#extended-thinking)以了解詳細資訊。

127* **Multi-line input**：按 `Shift+Enter` 以新增一行而不傳送。這也適用於問題對話的「Other」自由文字輸入。134* **Multi-line input**：按 `Shift+Enter` 以新增一行而不傳送。這也適用於問題對話的「Other」自由文字輸入。

128 135

139 146

140對於大型 PDF，您可以要求 Claude 讀取特定頁面而不是整個檔案：單一頁面、範圍如第 1-10 頁，或開放式範圍如第 3 頁起。147對於大型 PDF，您可以要求 Claude 讀取特定頁面而不是整個檔案：單一頁面、範圍如第 1-10 頁，或開放式範圍如第 3 頁起。

141 148

142當您在編輯器中選擇文字時，Claude 可以自動看到您的反白程式碼。提示框頁尾顯示選擇了多少行。按 `Option+K`（Mac）/ `Alt+K`（Windows/Linux）以插入帶有檔案路徑和行號的 @-mention（例如 `@app.ts#5-10`）。點擊選擇指示器以切換 Claude 是否可以看到您的反白文字 - 眼睛斜線圖示表示選擇對 Claude 隱藏。149當您在編輯器中選擇文字時，Claude 可以自動看到您的反白程式碼。提示框頁尾顯示選擇了多少行。按 `Option+K`（Mac）/ `Alt+K`（Windows/Linux）以插入帶有檔案路徑和行號的 @-mention（例如 `@app.ts#5-10`）。點擊選擇指示器上的 **X** 以將其從內容中移除，使 Claude 不會接收選擇。當您選擇其他文字或切換到不同檔案時，指示器會重新出現。

143 150

144若要附加影像，請從您的剪貼簿將其貼到提示框中。您也可以在將檔案拖入提示框時按住 `Shift` 以將它們新增為附件。點擊任何附件上的 X 以將其從內容中移除。151若要附加影像，請從您的剪貼簿將其貼到提示框中。您也可以在將檔案拖入提示框時按住 `Shift` 以將它們新增為附件。點擊任何附件上的 X 以將其從內容中移除。

145 152

193 200

194執行 `/usage` 以開啟帳戶和使用情況對話方塊。對話方塊需要 claude.ai 登入，因此在[第三方提供者](#use-third-party-providers)上不提供。它顯示您登入的帳戶、您的方案和您方案限制的使用情況列，例如目前會話和週。每個列顯示其限制重設的時間。201執行 `/usage` 以開啟帳戶和使用情況對話方塊。對話方塊需要 claude.ai 登入，因此在[第三方提供者](#use-third-party-providers)上不提供。它顯示您登入的帳戶、您的方案和您方案限制的使用情況列，例如目前會話和週。每個列顯示其限制重設的時間。

195 202

196對話方塊也會分解對您的方案限制有貢獻的內容。它標記佔最近使用情況 10% 或以上的行為，例如快取未命中、長內容和子代理程式繁重或高度平行會話，每個都有減少它的提示。Attribution 表格顯示每個 skill、subagent、外掛程式和 MCP 伺服器貢獻了多少使用情況。需要 Claude Code v2.1.174 或更新版本。203對話方塊也會分解對您的方案限制有貢獻的內容。它標記佔最近使用情況 10% 或以上的行為，例如快取未命中、長內容和子代理程式繁重或高度平行會話，每個都有減少它的提示。Attribution 表格顯示每個 skill、subagent、外掛程式和 MCP 伺服器貢獻了多少使用情況。

197 204

198使用 Day 和 Week 切換以在過去 24 小時和過去 7 天之間切換。這些數字是近似值，並從此機器上的本機會話計算，因此不包括來自其他裝置或 claude.ai 的使用情況。如需有關追蹤和減少使用情況的更多資訊，請參閱[追蹤您的成本](/docs/zh-TW/costs#track-your-costs)。205使用 Day 和 Week 切換以在過去 24 小時和過去 7 天之間切換。這些數字是近似值，並從此機器上的本機會話計算，因此不包括來自其他裝置或 claude.ai 的使用情況。如需有關追蹤和減少使用情況的更多資訊，請參閱[追蹤您的成本](/docs/zh-TW/costs#track-your-costs)。

199 206

238 245

239* **群組或取消群組工作階段**：右鍵點擊工作階段以從其建立群組、將其移動到現有群組，或將其從其群組中移除。每個工作階段一次只屬於一個群組，因此將其移動到另一個群組會將其從第一個群組中移除。246* **群組或取消群組工作階段**：右鍵點擊工作階段以從其建立群組、將其移動到現有群組，或將其從其群組中移除。每個工作階段一次只屬於一個群組，因此將其移動到另一個群組會將其從第一個群組中移除。

240* **一次移動多個工作階段**：`Cmd`-點擊 (Mac) / `Ctrl`-點擊 (Windows/Linux) 每個工作階段，或 `Shift`-點擊以選擇一個範圍，然後右鍵點擊選擇。247* **一次移動多個工作階段**：`Cmd`-點擊 (Mac) / `Ctrl`-點擊 (Windows/Linux) 每個工作階段，或 `Shift`-點擊以選擇一個範圍，然後右鍵點擊選擇。

241* **從其標籤群組工作階段**：從命令選擇板執行 **Claude Code: Add Session Tab to Group**，或右鍵點擊工作階段的編輯器標籤，然後選擇或建立群組。需要 Claude Code v2.1.257 或更新版本。248* **從其標籤群組工作階段**：從命令選擇板執行 **Claude Code: Add Session Tab to Group**，然後選擇或建立群組。需要 Claude Code v2.1.257 或更新版本。

242* **重新命名或刪除群組**：右鍵點擊群組標題。刪除群組只會移除群組，其工作階段會回到未群組的清單。249* **重新命名或刪除群組**：右鍵點擊群組標題。刪除群組只會移除群組，其工作階段會回到未群組的清單。

243 250

244擴充功能會按工作區資料夾儲存群組，因此它們在視窗重新載入後仍然存在，並在您開啟相同資料夾的每個視窗中出現。當您搜尋清單時，擴充功能會在所有群組中的一個平面清單中顯示符合項目。251擴充功能會按工作區資料夾儲存群組，因此它們在視窗重新載入後仍然存在，並在您開啟相同資料夾的每個視窗中出現。當您搜尋清單時，擴充功能會在所有群組中的一個平面清單中顯示符合項目。

359| Reopen Closed Session | `Cmd+Shift+T` (Mac) / `Ctrl+Shift+T` (Windows/Linux) | 重新開啟最近關閉的 Claude 工作階段標籤頁。當最後關閉的標籤頁不是 Claude 工作階段時，會回退到 VS Code 的正常重新開啟關閉編輯器功能。可使用 `enableReopenClosedSessionShortcut` 停用 |366| Reopen Closed Session | `Cmd+Shift+T` (Mac) / `Ctrl+Shift+T` (Windows/Linux) | 重新開啟最近關閉的 Claude 工作階段標籤頁。當最後關閉的標籤頁不是 Claude 工作階段時，會回退到 VS Code 的正常重新開啟關閉編輯器功能。可使用 `enableReopenClosedSessionShortcut` 停用 |

362| Rename Session Tab | - | 重新命名作用中 Claude 標籤頁中的工作階段。該命令也會出現在標籤頁的右鍵選單中。需要 Claude Code v2.1.257 或更新版本 |369| Rename Session Tab | - | 重新命名作用中 Claude 標籤頁中的工作階段。需要 Claude Code v2.1.257 或更新版本 |

363| Add Session Tab to Group | - | 將作用中 Claude 標籤頁中的工作階段新增至您選擇或建立的[工作階段群組](#organize-sessions-into-groups)。該命令也會出現在標籤頁的右鍵選單中。需要 Claude Code v2.1.257 或更新版本 |370| Add Session Tab to Group | - | 將作用中 Claude 標籤頁中的工作階段新增至您選擇或建立的[工作階段群組](#organize-sessions-into-groups)。需要 Claude Code v2.1.257 或更新版本 |

364| Mark Session as Unread | - | 在工作階段清單中將作用中 Claude 標籤頁中的工作階段標記為未讀。該命令也會出現在標籤頁的右鍵選單中。需要 Claude Code v2.1.257 或更新版本 |371| Mark Session as Unread | - | 在工作階段清單中將作用中 Claude 標籤頁中的工作階段標記為未讀。需要 Claude Code v2.1.257 或更新版本 |

365| Show Logs | - | 檢視擴充功能偵錯日誌 |372| Show Logs | - | 檢視擴充功能偵錯日誌 |

366| Logout | - | 登出您的 Anthropic 帳戶 |373| Logout | - | 登出您的 Anthropic 帳戶 |

367 374

424 431

425此擴充功能有兩種類型的設定：432此擴充功能有兩種類型的設定：

426 433

427* **VS Code 中的擴充功能設定**：控制擴充功能在 VS Code 中的行為。使用 `Cmd+,`（Mac）或 `Ctrl+,`（Windows/Linux）開啟，然後前往 Extensions → Claude Code。您也可以輸入 `/` 並選擇 **General Config** 來開啟設定。434* **VS Code 中的擴充功能設定**：控制擴充功能在 VS Code 中的行為。使用 `Cmd+,`（Mac）或 `Ctrl+,`（Windows/Linux）開啟，然後前往 Extensions → Claude Code。您也可以輸入 `/` 並選擇 **General config…** 來開啟設定。

428* **`~/.claude/settings.json` 中的 Claude Code 設定**：在擴充功能和 CLI 之間共享。用於允許的命令、環境變數、hooks 和 MCP 伺服器。在 Pro、Max 和 Team 方案上，它也是權限模式對話開始時的一個輸入。[切換權限模式](/docs/zh-TW/permission-modes#switch-permission-modes)列出順序。詳見[設定](/docs/zh-TW/settings)。435* **`~/.claude/settings.json` 中的 Claude Code 設定**：在擴充功能和 CLI 之間共享。用於允許的命令、環境變數、hooks 和 MCP 伺服器。在 Pro、Max 和 Team 方案上，它也是權限模式對話開始時的一個輸入。[切換權限模式](/docs/zh-TW/permission-modes#switch-permission-modes)列出順序。詳見[設定](/docs/zh-TW/settings)。

429 436

430<Tip>437<Tip>

6594. **停用衝突的擴充功能**：暫時停用其他 AI 擴充功能（Cline、Continue 等）6664. **停用衝突的擴充功能**：暫時停用其他 AI 擴充功能（Cline、Continue 等）

6605. **檢查工作區信任**：擴充功能在受限模式下無法運作6675. **檢查工作區信任**：擴充功能在受限模式下無法運作

661 668

662或者，如果您已將 [`preferredLocation`](#extension-settings) 設定為 `sidebar`，或使用 **Claude Code: Open in Side Bar** 開啟 Claude，請點擊**狀態列**（右下角）中的「✱ Claude Code」。即使沒有開啟檔案，這也能運作。您也可以使用**命令選擇板**（`Cmd+Shift+P` / `Ctrl+Shift+P`）並輸入「Claude Code」。669或者，如果您已將 [`preferredLocation`](#extension-settings) 設定為 `sidebar`，或使用 **Claude Code: Open in Side Bar** 開啟 Claude，請點擊**狀態列**（右下角）中的「✻ Claude Code」。即使沒有開啟檔案，這也能運作。您也可以使用**命令選擇板**（`Cmd+Shift+P` / `Ctrl+Shift+P`）並輸入「Claude Code」。

663 670

664<h3 id="cmd-esc-does-nothing-on-macos">671<h3 id="cmd-esc-does-nothing-on-macos">

665 Cmd+Esc 在 macOS 上無法運作672 Cmd+Esc 在 macOS 上無法運作

worktrees.md +1 −1

Details

9[git worktree](https://git-scm.com/docs/git-worktree) 是一個獨立的工作目錄，具有自己的檔案和分支，但與主要檢出共享相同的儲存庫歷史記錄和遠端。在自己的 worktree 中執行每個 Claude Code 會話意味著一個會話中的編輯永遠不會觸及另一個會話中的檔案，因此一個會話可以建置功能，而第二個會話可以修復錯誤。9[git worktree](https://git-scm.com/docs/git-worktree) 是一個獨立的工作目錄，具有自己的檔案和分支，但與主要檢出共享相同的儲存庫歷史記錄和遠端。在自己的 worktree 中執行每個 Claude Code 會話意味著一個會話中的編輯永遠不會觸及另一個會話中的檔案，因此一個會話可以建置功能，而第二個會話可以修復錯誤。

10 10

11<Note>11<Note>

12 Worktrees 需要 git 儲存庫；對於其他版本控制系統，請[配置 hooks 以取代 git 邏輯](#non-git-version-control)。在[桌面應用程式](/docs/zh-TW/desktop#work-in-parallel-with-sessions)中，每個新會話都會自動獲得自己的 worktree。12 Worktrees 需要 git 儲存庫；對於其他版本控制系統，請[配置 hooks 以取代 git 邏輯](#non-git-version-control)。在[桌面應用程式](/docs/zh-TW/desktop#work-in-parallel-with-sessions)中，當您啟動會話時選擇 **worktree** 選項，為其提供自己的 worktree。

13</Note>13</Note>

14 14

15Worktrees 是執行 Claude 平行處理的幾種方式之一。它們隔離檔案編輯。[子代理](/docs/zh-TW/sub-agents)在一個會話內分割工作，[跨會話訊息傳遞](/docs/zh-TW/cross-session-messaging)讓 Claude 在您的 worktrees 中的會話之間傳遞發現。請參閱[平行執行代理](/docs/zh-TW/agents)以比較這些方法，或跳到[使用 worktrees 隔離子代理](#isolate-subagents-with-worktrees)以同時使用 worktrees 和子代理。15Worktrees 是執行 Claude 平行處理的幾種方式之一。它們隔離檔案編輯。[子代理](/docs/zh-TW/sub-agents)在一個會話內分割工作，[跨會話訊息傳遞](/docs/zh-TW/cross-session-messaging)讓 Claude 在您的 worktrees 中的會話之間傳遞發現。請參閱[平行執行代理](/docs/zh-TW/agents)以比較這些方法，或跳到[使用 worktrees 隔離子代理](#isolate-subagents-with-worktrees)以同時使用 worktrees 和子代理。

Documentation 2026-09-13 21:00 UTC to 2026-09-14 22:58 UTC