Documentation — Spybara

admin-setup.md +6 −6

Details

15</Note>15</Note>

16 16

17| 決策 | 您正在選擇什麼 | 參考 |17| 決策 | 您正在選擇什麼 | 參考 |

18| :----------------------------------------------- | :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ |18| :----------------------------------------------- | :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

19| [選擇您的 API 提供者](#choose-your-api-provider) | Claude Code 驗證的位置以及如何計費 | [Authentication](/zh-TW/authentication)、[Bedrock](/zh-TW/amazon-bedrock)、[Vertex AI](/zh-TW/google-vertex-ai)、[Foundry](/zh-TW/microsoft-foundry) |19| [選擇您的 API 提供者](#choose-your-api-provider) | Claude Code 驗證的位置以及如何計費 | [Authentication](/zh-TW/authentication)、[Amazon Bedrock](/zh-TW/amazon-bedrock)、[Google Cloud's Agent Platform](/zh-TW/google-vertex-ai)、[Microsoft Foundry](/zh-TW/microsoft-foundry) |

33| Claude for Teams / Enterprise | 您希望 Claude Code 和 claude.ai 在一個按座位訂閱下，無需執行基礎設施。這是預設建議。 |33| Claude for Teams / Enterprise | 您希望 Claude Code 和 claude.ai 在一個按座位訂閱下，無需執行基礎設施。這是預設建議。 |

34| Claude Console | 您是 API 優先或希望按使用量付費計費 |34| Claude Console | 您是 API 優先或希望按使用量付費計費 |

35| Amazon Bedrock | 您希望繼承現有的 AWS 合規控制和計費 |35| Amazon Bedrock | 您希望繼承現有的 AWS 合規控制和計費 |

~~36| Google Vertex AI | 您希望繼承現有的 GCP 合規控制和計費 |~~36| Google Cloud's Agent Platform | 您希望繼承現有的 GCP 合規控制和計費 |

37| Microsoft Foundry | 您希望繼承現有的 Azure 合規控制和計費 |37| Microsoft Foundry | 您希望繼承現有的 Azure 合規控制和計費 |

38 38

39某些 Claude Code 功能需要 claude.ai 帳戶。[Claude Code on the web](/zh-TW/claude-code-on-the-web)、[Routines](/zh-TW/routines)、[Code Review](/zh-TW/code-review)、[Remote Control](/zh-TW/remote-control) 和 [Chrome extension](/zh-TW/chrome) 無法透過 Console API 金鑰或雲端提供者認證單獨使用。如果您透過 Bedrock、Vertex 或 Foundry 部署，請規劃開發人員是否也需要 Claude for Teams 或 Enterprise 座位。每個功能頁面都列出其計畫要求。39某些 Claude Code 功能需要 claude.ai 帳戶。[Claude Code on the web](/zh-TW/claude-code-on-the-web)、[Routines](/zh-TW/routines)、[Code Review](/zh-TW/code-review)、[Remote Control](/zh-TW/remote-control) 和 [Chrome extension](/zh-TW/chrome) 無法透過 Console API 金鑰或雲端提供者認證單獨使用。如果您透過 Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry 部署，請規劃開發人員是否也需要 Claude for Teams 或 Enterprise 座位。每個功能頁面都列出其計畫要求。

40 40

41有關涵蓋驗證、區域和功能奇偶性的完整提供者比較，請參閱 [企業部署概述](/zh-TW/third-party-integrations)。每個提供者的驗證設定位於 [Authentication](/zh-TW/authentication)。41有關涵蓋驗證、區域和功能奇偶性的完整提供者比較，請參閱 [企業部署概述](/zh-TW/third-party-integrations)。每個提供者的驗證設定位於 [Authentication](/zh-TW/authentication)。

42 42

57 57

58已配置的 [`policyHelper`](/zh-TW/settings#compute-managed-settings-with-a-policy-helper) 會優先於所有四個來源：其輸出成為該執行的唯一受管配置。請參閱[設定優先順序](/zh-TW/settings#settings-precedence)。58已配置的 [`policyHelper`](/zh-TW/settings#compute-managed-settings-with-a-policy-helper) 會優先於所有四個來源：其輸出成為該執行的唯一受管配置。請參閱[設定優先順序](/zh-TW/settings#settings-precedence)。

59 59

60Server-managed 設定在驗證時到達裝置，並在活動會話期間每小時刷新一次，無需端點基礎設施。透過 claude.ai 管理員控制台傳遞需要 Claude for Teams 或 Enterprise 計畫。在 Bedrock、Vertex AI 或 Foundry 上的部署可以透過執行 [Claude apps gateway](/zh-TW/claude-apps-gateway) 獲得相同的遠端傳遞，或改用其中一個基於檔案或作業系統級別的機制。60Server-managed 設定在驗證時到達裝置，並在活動會話期間每小時刷新一次，無需端點基礎設施。透過 claude.ai 管理員控制台傳遞需要 Claude for Teams 或 Enterprise 計畫。在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上的部署可以透過執行 [Claude apps gateway](/zh-TW/claude-apps-gateway) 獲得相同的遠端傳遞，或改用其中一個基於檔案或作業系統級別的機制。

61 61

62如果您的組織混合使用提供者，請為 claude.ai 使用者配置 [server-managed settings](/zh-TW/server-managed-settings) 加上 [基於檔案或 plist/registry 備用](/zh-TW/settings#settings-files)，以便其他使用者仍然接收受管政策。62如果您的組織混合使用提供者，請為 claude.ai 使用者配置 [server-managed settings](/zh-TW/server-managed-settings) 加上 [基於檔案或 plist/registry 備用](/zh-TW/settings#settings-files)，以便其他使用者仍然接收受管政策。

63 63

153* [Server-managed settings](/zh-TW/server-managed-settings)：從 Claude 管理員控制台傳遞受管政策153* [Server-managed settings](/zh-TW/server-managed-settings)：從 Claude 管理員控制台傳遞受管政策

154* [Settings reference](/zh-TW/settings)：每個設定鍵、檔案位置和優先級規則154* [Settings reference](/zh-TW/settings)：每個設定鍵、檔案位置和優先級規則

155* [Monorepos and large repos](/zh-TW/large-codebases)：為部署到 monorepo 的組織提供的每個目錄配置模式155* [Monorepos and large repos](/zh-TW/large-codebases)：為部署到 monorepo 的組織提供的每個目錄配置模式

156* [Amazon Bedrock](/zh-TW/amazon-bedrock)、[Google Vertex AI](/zh-TW/google-vertex-ai)、[Microsoft Foundry](/zh-TW/microsoft-foundry)：提供者特定部署156* [Amazon Bedrock](/zh-TW/amazon-bedrock)、[Google Cloud's Agent Platform](/zh-TW/google-vertex-ai)、[Microsoft Foundry](/zh-TW/microsoft-foundry)：提供者特定部署

157* [Claude Enterprise Administrator Guide](https://claude.com/resources/tutorials/claude-enterprise-administrator-guide)：SSO、SCIM、座位管理和推出劇本157* [Claude Enterprise Administrator Guide](https://claude.com/resources/tutorials/claude-enterprise-administrator-guide)：SSO、SCIM、座位管理和推出劇本

advisor.md +2 −2

Details

9{/* plan-availability: feature=advisor providers=anthropic */}9{/* plan-availability: feature=advisor providers=anthropic */}

10 10

11<Note>11<Note>

12 顧問工具是實驗性功能，需要 Claude Code v2.1.98 或更新版本搭配 Anthropic API。它在 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 上不可用。行為、定價和可用性可能會變更。12 顧問工具是實驗性功能，需要 Claude Code v2.1.98 或更新版本搭配 Anthropic API。它在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用。行為、定價和可用性可能會變更。

13</Note>13</Note>

14 14

15顧問工具讓 Claude 在任務期間的關鍵時刻諮詢第二個通常更強大的模型，例如在提交方案前、遇到重複錯誤時，或在宣佈任務完成前。顧問會收到完整的對話記錄，包括每個工具呼叫和結果，並返回 Claude 在繼續前應用的指導。15顧問工具讓 Claude 在任務期間的關鍵時刻諮詢第二個通常更強大的模型，例如在提交方案前、遇到重複錯誤時，或在宣佈任務完成前。顧問會收到完整的對話記錄，包括每個工具呼叫和結果，並返回 Claude 在繼續前應用的指導。

162顧問工具需要以下所有條件：162顧問工具需要以下所有條件：

163 163

164* **Claude Code v2.1.98 或更新版本**：執行 `claude update` 以升級。164* **Claude Code v2.1.98 或更新版本**：執行 `claude update` 以升級。

165* **僅限 Anthropic API**：顧問是伺服器執行的工具。它在 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 上不可用。透過配置有 `ANTHROPIC_BASE_URL` 的 [LLM 閘道](/zh-TW/llm-gateway)，可用性取決於閘道是否將請求完整轉發到 Anthropic API。165* **僅限 Anthropic API**：顧問是伺服器執行的工具。它在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用。透過配置有 `ANTHROPIC_BASE_URL` 的 [LLM 閘道](/zh-TW/llm-gateway)，可用性取決於閘道是否將請求完整轉發到 Anthropic API。

166* **支援的主要模型**：Opus 4.6 或更新版本、Sonnet 4.6 或更新版本，或 Haiku 4.5。{/* min-version: 2.1.170 */}Fable 5 在 Claude Code v2.1.170 或更新版本上也符合條件。166* **支援的主要模型**：Opus 4.6 或更新版本、Sonnet 4.6 或更新版本，或 Haiku 4.5。{/* min-version: 2.1.170 */}Fable 5 在 Claude Code v2.1.170 或更新版本上也符合條件。

167 167

168<h2 id="turn-the-advisor-off">168<h2 id="turn-the-advisor-off">

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

Details

202 202

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

204 204

205使用 [串流輸入](/zh-TW/agent-sdk/streaming-vs-single-mode)，當回合在最大回合限制時結束時，您在回合仍在執行時發送的訊息會保持佇列狀態，並且它會以自己的最大回合限制開始自己的回合。在 v2.1.205 之前，在回合最後一次迭代時到達的訊息可能會被消耗到結束回合中並遺失，而不會到達模型。

206

205<h3 id="effort-level">207<h3 id="effort-level">

206 努力等級208 努力等級

207</h3>209</h3>

231權限模式選項（Python 中的 `permission_mode`、TypeScript 中的 `permissionMode`）控制代理程式是否在使用工具前要求批准：233權限模式選項（Python 中的 `permission_mode`、TypeScript 中的 `permissionMode`）控制代理程式是否在使用工具前要求批准：

232 234

233| 模式 | 行為 |235| 模式 | 行為 |

234| :--------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |236| :-------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

240| `"bypassPermissions"` | 執行所有允許的工具而不詢問，除非明確的 [`ask` 規則](/zh-TW/settings#permission-settings) 符合；請參閱 [權限如何被評估](/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated) 以了解 ask 規則在優先順序中的位置。在 Unix 上以 root 身份執行時無法使用。僅在隔離環境中使用，其中代理程式的操作無法影響您關心的系統 |242| `"bypassPermissions"` | 執行所有允許的工具而不詢問，除非明確的 [`ask` 規則](/zh-TW/settings#permission-settings) 符合；請參閱 [權限如何被評估](/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated) 以了解 ask 規則在優先順序中的位置。在 Unix 上以 root 身份執行時無法使用。僅在隔離環境中使用，其中代理程式的操作無法影響您關心的系統 |

241 243

242對於互動式應用程式，使用 `"default"` 和工具批准回呼來顯示批准提示。對於開發機器上的自主代理程式，`"acceptEdits"` 自動批准檔案編輯和常見的檔案系統命令（`mkdir`、`touch`、`mv`、`cp` 等），同時仍然在允許規則後面限制其他 `Bash` 命令。為 CI、容器或其他隔離環境保留 `"bypassPermissions"`。請參閱 [權限](/zh-TW/agent-sdk/permissions) 以了解完整詳細資訊。244對於互動式應用程式，使用 `"default"` 和工具批准回呼來顯示批准提示。對於開發機器上的自主代理程式，`"acceptEdits"` 自動批准檔案編輯和常見的檔案系統命令（`mkdir`、`touch`、`mv`、`cp` 等），同時仍然在允許規則後面限制其他 `Bash` 命令。為 CI、容器或其他隔離環境保留 `"bypassPermissions"`。請參閱 [權限](/zh-TW/agent-sdk/permissions) 以了解完整詳細資訊。

260以下是每個元件如何影響 SDK 中上下文的方式：262以下是每個元件如何影響 SDK 中上下文的方式：

261 263

262| 來源 | 何時加載 | 影響 |264| 來源 | 何時加載 | 影響 |

263| :--------------- | :------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |265| :--------------- | :------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

266| **工具定義** | 每個請求；MCP 架構預設延遲 | 內建工具架構在每個請求時加載。[工具搜尋](/zh-TW/agent-sdk/mcp#mcp-tool-search) 預設延遲 MCP 工具架構，在 Vertex AI 或非第一方 `ANTHROPIC_BASE_URL` 上回退到預先加載。請參閱 [配置工具搜尋](/zh-TW/agent-sdk/tool-search#configure-tool-search) 以了解完整矩陣 |268| **工具定義** | 每個請求；MCP 架構預設延遲 | 內建工具架構在每個請求時加載。[工具搜尋](/zh-TW/agent-sdk/mcp#mcp-tool-search) 預設延遲 MCP 工具架構，在 Google Cloud 的 Agent Platform 或非第一方 `ANTHROPIC_BASE_URL` 上回退到預先加載。請參閱 [配置工具搜尋](/zh-TW/agent-sdk/tool-search#configure-tool-search) 以了解完整矩陣 |

269 271

305 307

306* **為子任務使用子代理程式。** 每個子代理程式以新鮮的對話開始（沒有先前的訊息歷史記錄，儘管它確實加載自己的系統提示和專案級上下文，如 CLAUDE.md）。它看不到父級的回合，只有其最終回應作為工具結果返回給父級。主代理程式的上下文增長該摘要，而不是完整的子任務成績單。請參閱 [子代理程式繼承什麼](/zh-TW/agent-sdk/subagents#what-subagents-inherit) 以了解詳細資訊。308* **為子任務使用子代理程式。** 每個子代理程式以新鮮的對話開始（沒有先前的訊息歷史記錄，儘管它確實加載自己的系統提示和專案級上下文，如 CLAUDE.md）。它看不到父級的回合，只有其最終回應作為工具結果返回給父級。主代理程式的上下文增長該摘要，而不是完整的子任務成績單。請參閱 [子代理程式繼承什麼](/zh-TW/agent-sdk/subagents#what-subagents-inherit) 以了解詳細資訊。

307* **選擇性地使用工具。** 每個工具定義都佔用上下文空間。在 [`AgentDefinition`](/zh-TW/agent-sdk/subagents#agentdefinition-configuration) 上使用 `tools` 欄位將子代理程式限制在它們需要的最小集合。309* **選擇性地使用工具。** 每個工具定義都佔用上下文空間。在 [`AgentDefinition`](/zh-TW/agent-sdk/subagents#agentdefinition-configuration) 上使用 `tools` 欄位將子代理程式限制在它們需要的最小集合。

308* **監視 MCP 伺服器成本。** [MCP 工具搜尋](/zh-TW/agent-sdk/mcp#mcp-tool-search) 預設延遲 MCP 工具架構，並按需加載它們。當工具搜尋關閉、在 Vertex AI 上或在非第一方 `ANTHROPIC_BASE_URL` 後面時，每個 MCP 伺服器將其所有工具架構添加到每個請求，因此具有許多工具的幾個伺服器可以在代理程式執行任何工作之前消耗大量上下文。310* **監視 MCP 伺服器成本。** [MCP 工具搜尋](/zh-TW/agent-sdk/mcp#mcp-tool-search) 預設延遲 MCP 工具架構，並按需加載它們。當工具搜尋關閉、在 Google Cloud 的 Agent Platform 上或在非第一方 `ANTHROPIC_BASE_URL` 後面時，每個 MCP 伺服器將其所有工具架構添加到每個請求，因此具有許多工具的幾個伺服器可以在代理程式執行任何工作之前消耗大量上下文。

309* **為常規任務使用較低的努力。** 為僅需要讀取檔案或列出目錄的代理程式設定 [努力](#effort-level) 為 `"low"`。這會減少代幣使用量和成本。311* **為常規任務使用較低的努力。** 為僅需要讀取檔案或列出目錄的代理程式設定 [努力](#effort-level) 為 `"low"`。這會減少代幣使用量和成本。

310 312

311有關每個功能上下文成本的詳細分解，請參閱 [了解上下文成本](/zh-TW/features-overview#understand-context-costs)。313有關每個功能上下文成本的詳細分解，請參閱 [了解上下文成本](/zh-TW/features-overview#understand-context-costs)。

agent-sdk/cost-tracking.md +2 −2

Details

292 將 prompt 快取 TTL 延長至一小時292 將 prompt 快取 TTL 延長至一小時

293</h3>293</h3>

294 294

295當您使用 API 金鑰進行身份驗證或在 Amazon Bedrock、Google Cloud Vertex AI 或 Microsoft Foundry 上執行時，SDK 寫入的快取項目預設使用 5 分鐘的 TTL。如果您的工作負載針對相同的系統提示和上下文執行許多短會話，且它們之間的間隔超過 5 分鐘，快取會在會話之間過期，每個新會話都會支付完整的輸入價格。295當您使用 API 金鑰進行身份驗證或在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上執行時，SDK 寫入的快取項目預設使用 5 分鐘的 TTL。如果您的工作負載針對相同的系統提示和上下文執行許多短會話，且它們之間的間隔超過 5 分鐘，快取會在會話之間過期，每個新會話都會支付完整的輸入價格。

296 296

297要請求快取寫入的 1 小時 TTL，請設定 [`ENABLE_PROMPT_CACHING_1H`](/zh-TW/env-vars) 環境變數。您可以在 shell 或容器環境中匯出它，或通過 `options.env` 傳遞它。297要請求快取寫入的 1 小時 TTL，請設定 [`ENABLE_PROMPT_CACHING_1H`](/zh-TW/env-vars) 環境變數。您可以在 shell 或容器環境中匯出它，或通過 `options.env` 傳遞它。

298 298

299以下範例為在 Bedrock 上執行的代理啟用 1 小時 TTL：299以下範例為在 Amazon Bedrock 上執行的代理啟用 1 小時 TTL：

300 300

301<CodeGroup>301<CodeGroup>

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

agent-sdk/custom-tools.md +15 −13

Details

21| 預先核准工具 | 新增至您允許的工具。請參閱[設定允許的工具](#configure-allowed-tools)。 |21| 預先核准工具 | 新增至您允許的工具。請參閱[設定允許的工具](#configure-allowed-tools)。 |

27| 擴展到許多工具 | 使用[工具搜尋](/zh-TW/agent-sdk/tool-search)按需載入工具。 |27| 擴展到許多工具 | 使用[工具搜尋](/zh-TW/agent-sdk/tool-search)按需載入工具。 |

356 處理錯誤356 處理錯誤

357</h2>357</h2>

358 358

359您的處理程式報告錯誤的方式決定代理迴圈是繼續還是停止：359處理程式錯誤不會停止代理迴圈。SDK 的同處理程序 MCP 伺服器會捕獲未捕獲的例外，並將其作為錯誤結果傳回，因此您報告錯誤的方式決定了 Claude 讀取的內容，而不是查詢是否失敗：

360 360

361| 發生的情況 | 結果 |361| 發生的情況 | 結果 |

362| :---------------------------------------------------------- | :--------------------------------------- |362| :---------------------------------------------------------- | :--------------------------------------------- |

363| 處理程式擲出未捕獲的例外 | 代理迴圈停止。Claude 永遠看不到錯誤，`query` 呼叫失敗。 |363| 處理程式擲出未捕獲的例外 | MCP 伺服器將其轉換為錯誤結果，攜帶原始例外訊息。Claude 看到該訊息，代理迴圈繼續。 |

365 365

366下面的範例在處理程式內捕獲兩種失敗，而不是讓它們擲出。非 200 HTTP 狀態從回應中捕獲並作為錯誤結果傳回。網路錯誤或無效 JSON 由周圍的 `try/except`（Python）或 `try/catch`（TypeScript）捕獲，也作為錯誤結果傳回。在兩種情況下，處理程式正常傳回，代理迴圈繼續。366在兩種情況下，Claude 都可以重試、嘗試不同的工具或解釋失敗。當原始例外訊息不足以讓 Claude 採取行動時，請自行捕獲錯誤。

367

368下面的範例在處理程式內捕獲兩種失敗，並撰寫 Claude 讀取的錯誤訊息。非 200 HTTP 狀態從回應中捕獲並作為錯誤結果傳回。網路錯誤或無效 JSON 由周圍的 `try/except`（Python）或 `try/catch`（TypeScript）捕獲，也作為錯誤結果傳回。在兩種情況下，Claude 都會收到描述失敗的訊息，而不是裸露的例外字串。

367 369

368<CodeGroup>370<CodeGroup>

369 ```python Python theme={null}371 ```python Python theme={null}

397 data = response.json()399 data = response.json()

398 return {"content": [{"type": "text", "text": json.dumps(data, indent=2)}]}400 return {"content": [{"type": "text", "text": json.dumps(data, indent=2)}]}

399 except Exception as e:401 except Exception as e:

400 # Catching here keeps the agent loop alive. An uncaught exception402 # Composes the message Claude reads. An uncaught exception would

401 # would end the whole query() call.403 # reach Claude as the raw str(e) with no context.

402 return {404 return {

403 "content": [{"type": "text", "text": f"Failed to fetch data: {str(e)}"}],405 "content": [{"type": "text", "text": f"Failed to fetch data: {str(e)}"}],

404 "is_error": True,406 "is_error": True,

440 ]442 ]

441 };443 };

442 } catch (error) {444 } catch (error) {

443 // Catching here keeps the agent loop alive. An uncaught throw445 // Composes the message Claude reads. An uncaught throw would

444 // would end the whole query() call.446 // reach Claude as the raw error message with no context.

445 return {447 return {

446 content: [448 content: [

447 {449 {

461 傳回影像和資源463 傳回影像和資源

462</h2>464</h2>

463 465

464工具結果中的 `content` 陣列接受 `text`、`image`、`audio`、`resource` 和 `resource_link` 區塊。您可以在同一回應中混合它們。音訊區塊會儲存到磁碟，Claude 會收到一個包含已儲存檔案路徑的文字區塊。資源連結區塊會轉換為包含連結名稱、URI 和描述的文字區塊。466工具結果中的 `content` 陣列接受 `text`、`image`、`audio`、`resource` 和 `resource_link` 區塊。您可以在同一回應中混合它們。在 TypeScript 中，音訊區塊會儲存到磁碟，Claude 會收到一個包含已儲存檔案路徑的文字區塊；在 Python 中，SDK 會從工具結果中捨棄音訊區塊並記錄警告。資源連結區塊會轉換為包含連結名稱、URI 和描述的文字區塊。

465 467

466<h3 id="images">468<h3 id="images">

467 影像469 影像

535資源區塊嵌入由 URI 識別的內容片段。URI 是 Claude 參考的標籤；實際內容位於區塊的 `text` 或 `blob` 欄位中。當您的工具產生稍後按名稱尋址有意義的內容時使用此項，例如生成的檔案或來自外部系統的記錄。537資源區塊嵌入由 URI 識別的內容片段。URI 是 Claude 參考的標籤；實際內容位於區塊的 `text` 或 `blob` 欄位中。當您的工具產生稍後按名稱尋址有意義的內容時使用此項，例如生成的檔案或來自外部系統的記錄。

536 538

537| 欄位 | 類型 | 備註 |539| 欄位 | 類型 | 備註 |

538| :------------------ | :----------- | :----------------------------- |540| :------------------ | :----------- | :--------------------------------------------------------------- |

543| `resource.mimeType` | `string` | 選用 |545| `resource.mimeType` | `string` | 選用 |

544 546

545此範例顯示從工具處理程式內傳回的資源區塊。URI `file:///tmp/report.md` 是 Claude 稍後可以參考的標籤；SDK 不會從該路徑讀取。547此範例顯示從工具處理程式內傳回的資源區塊。URI `file:///tmp/report.md` 是 Claude 稍後可以參考的標籤；SDK 不會從該路徑讀取。

agent-sdk/hooks.md +1 −1

Details

250 250

251* **輸入資料：** 一個包含事件詳細資訊的類型物件。每個 hook 類型都有自己的輸入形狀。例如，`PreToolUseHookInput` 包括 `tool_name` 和 `tool_input`，而 `NotificationHookInput` 包括 `message`。請參閱 [TypeScript](/zh-TW/agent-sdk/typescript#hookinput) 和 [Python](/zh-TW/agent-sdk/python#hookinput) SDK 參考中的完整類型定義。251* **輸入資料：** 一個包含事件詳細資訊的類型物件。每個 hook 類型都有自己的輸入形狀。例如，`PreToolUseHookInput` 包括 `tool_name` 和 `tool_input`，而 `NotificationHookInput` 包括 `message`。請參閱 [TypeScript](/zh-TW/agent-sdk/typescript#hookinput) 和 [Python](/zh-TW/agent-sdk/python#hookinput) SDK 參考中的完整類型定義。

252 * 所有 hook 輸入共享 `session_id`、`cwd` 和 `hook_event_name`。252 * 所有 hook 輸入共享 `session_id`、`cwd` 和 `hook_event_name`。

253 * 當 hook 在子代理內觸發時，`agent_id` 和 `agent_type` 會被填充。在 TypeScript 中，這些在基本 hook 輸入上，可供所有 hook 類型使用。在 Python 中，它們僅在 `PreToolUse`、`PostToolUse` 和 `PostToolUseFailure` 上。253 * 當 hook 在子代理內觸發時，`agent_id` 和 `agent_type` 會被填充。在 TypeScript 中，這些在基本 hook 輸入上，可供所有 hook 類型使用。在 Python 中，它們是 `PreToolUse`、`PostToolUse`、`PostToolUseFailure` 和 `PermissionRequest` 上的可選欄位，以及 `SubagentStart` 和 `SubagentStop` 上的必需欄位。

254* **工具使用 ID**（`str | None` / `string | undefined`）：關聯同一工具呼叫的 `PreToolUse` 和 `PostToolUse` 事件。254* **工具使用 ID**（`str | None` / `string | undefined`）：關聯同一工具呼叫的 `PreToolUse` 和 `PostToolUse` 事件。

255* **上下文：** 在 TypeScript 中，包含用於取消的 `signal` 屬性（`AbortSignal`）。在 Python 中，此參數保留供將來使用。255* **上下文：** 在 TypeScript 中，包含用於取消的 `signal` 屬性（`AbortSignal`）。在 Python 中，此參數保留供將來使用。

256 256

agent-sdk/hosting.md +1 −1

Details

189 網絡189 網絡

190</h3>190</h3>

191 191

192SDK 需要對 `api.anthropic.com` 的出站 HTTPS，或在 Bedrock 或 Vertex 上運行時對您提供商的區域端點的出站 HTTPS。如果您的代理使用 [MCP servers](/zh-TW/agent-sdk/mcp) 或外部工具，它們還需要對這些端點的出站訪問。對於生產環境，通過強制執行域名允許列表、注入憑證和記錄請求的出站代理路由出站流量。有關完整模式，請參閱[安全部署](/zh-TW/agent-sdk/secure-deployment)。192SDK 需要對 `api.anthropic.com` 的出站 HTTPS，或在 Amazon Bedrock 或 Google Cloud 的 Agent Platform 上運行時對您提供商的區域端點的出站 HTTPS。如果您的代理使用 [MCP servers](/zh-TW/agent-sdk/mcp) 或外部工具，它們還需要對這些端點的出站訪問。對於生產環境，通過強制執行域名允許列表、注入憑證和記錄請求的出站代理路由出站流量。有關完整模式，請參閱[安全部署](/zh-TW/agent-sdk/secure-deployment)。

193 193

194對於入站流量，在容器上公開 HTTP 或 WebSocket 端口。您的應用程式在該端口上處理客戶端請求並在內部調用 SDK；子進程本身不在網絡上監聽。194對於入站流量，在容器上公開 HTTP 或 WebSocket 端口。您的應用程式在該端口上處理客戶端請求並在內部調用 SDK；子進程本身不在網絡上監聽。

195 195

agent-sdk/mcp.md +1 −1

Details

823 連接逾時823 連接逾時

824</h3>824</h3>

825 825

826MCP SDK 對伺服器連接的預設逾時為 60 秒。如果您的伺服器需要更長時間才能啟動，連接將失敗。對於需要更多啟動時間的伺服器，請考慮：826MCP 伺服器連接預設逾時為 30 秒。如果您的伺服器需要更長時間才能啟動，連接將失敗。使用 [`MCP_TIMEOUT`](/zh-TW/env-vars) 環境變數（以毫秒為單位）提高限制。對於需要更多啟動時間的伺服器，也請考慮：

827 827

828* 使用更輕量級的伺服器（如果可用）828* 使用更輕量級的伺服器（如果可用）

829* 在啟動代理程式前預熱伺服器829* 在啟動代理程式前預熱伺服器

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

Details

152 152

153* **CLI**：執行 `/config` 並選擇輸出樣式153* **CLI**：執行 `/config` 並選擇輸出樣式

154* **設定**：在 `.claude/settings.local.json` 中設定 `outputStyle`154* **設定**：在 `.claude/settings.local.json` 中設定 `outputStyle`

155* **TypeScript SDK**：在傳遞給 `query()` 的內聯 `settings` 物件內設定 `outputStyle`，或將 `settings` 指向設定該值的設定檔。`outputStyle` 不是頂級 `Options` 欄位155* **TypeScript SDK**：在傳遞給 `query()` 的內聯 `settings` 物件內設定 `outputStyle`，或將 `settings` 指向設定該值的設定檔。`outputStyle` 不是頂級 `Options` 欄位：

156

157 ```typescript theme={null}

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

159 ```

156 160

157Python SDK 沒有以程式設計方式選擇輸出樣式的選項。對於無法寫入 `.claude/settings.local.json` 的僅程式碼部署，請改用 `append` 或自訂提示詞字串。161Python SDK 沒有以程式設計方式選擇輸出樣式的選項。對於無法寫入 `.claude/settings.local.json` 的僅程式碼部署，請改用 `append` 或自訂提示詞字串。

158 162

agent-sdk/observability.md +2 −2

Details

206 206

207CLI 根據它用來呼叫 Anthropic 的認證將[身份屬性](/zh-TW/monitoring-usage#standard-attributes)附加到每個事件。當您建立一個從一個部署為許多終端使用者提供服務的應用程式時，這些屬性識別您的服務認證，而不是代理代表其行動的終端使用者。207CLI 根據它用來呼叫 Anthropic 的認證將[身份屬性](/zh-TW/monitoring-usage#standard-attributes)附加到每個事件。當您建立一個從一個部署為許多終端使用者提供服務的應用程式時，這些屬性識別您的服務認證，而不是代理代表其行動的終端使用者。

208 208

209若要使工具呼叫和 MCP 活動可歸因於您應用程式的終端使用者，請在每個 `query()` 呼叫上將終端使用者身份注入為資源屬性。在插值前對值進行百分比編碼，因為 `OTEL_RESOURCE_ATTRIBUTES` [保留逗號、空格和等號](/zh-TW/monitoring-usage#multi-team-organization-support)。以下範例將請求使用者和租戶附加到來自一個請求的每個 span 和事件：209若要使工具呼叫和 MCP 活動可歸因於您應用程式的終端使用者，請在每個 `query()` 呼叫上將終端使用者身份注入為資源屬性。在插值前對值進行百分比編碼，因為 `OTEL_RESOURCE_ATTRIBUTES` [保留逗號、空格和等號](/zh-TW/monitoring-usage#multi-team-organization-support)。以下範例將請求使用者和租戶附加到來自一個請求的每個 span 和事件。它假設您的網頁框架中有一個 `request` 物件，其中包含使用者和租戶 ID：

210 210

211<CodeGroup>211<CodeGroup>

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

231 ```231 ```

232</CodeGroup>232</CodeGroup>

233 233

234附加終端使用者身份後，`tool_decision`、`tool_result`、`mcp_server_connection` 和 `permission_mode_changed` 事件會變成您可以轉發到安全資訊和事件管理 (SIEM) 平台的按使用者稽核追蹤。請參閱監控參考中的[稽核安全事件](/zh-TW/monitoring-usage#audit-security-events)以了解完整的安全相關事件清單和每個事件攜帶的屬性。234附加終端使用者身份後，`tool_decision`、`tool_result`、`mcp_server_connection` 和 `permission_mode_changed` 事件（以 `claude_code.` 前綴命名的日誌記錄匯出）會變成您可以轉發到安全資訊和事件管理 (SIEM) 平台的按使用者稽核追蹤。請參閱監控參考中的[稽核安全事件](/zh-TW/monitoring-usage#audit-security-events)以了解完整的安全相關事件清單和每個事件攜帶的屬性。

235 235

236<h2 id="control-sensitive-data-in-exports">236<h2 id="control-sensitive-data-in-exports">

237 控制匯出中的敏感資料237 控制匯出中的敏感資料

agent-sdk/overview.md +2 −2

Details

87 87

88 * **Amazon Bedrock**：設定 `CLAUDE_CODE_USE_BEDROCK=1` 環境變數並配置 AWS 認證88 * **Amazon Bedrock**：設定 `CLAUDE_CODE_USE_BEDROCK=1` 環境變數並配置 AWS 認證

89 * **Claude Platform on AWS**：設定 `CLAUDE_CODE_USE_ANTHROPIC_AWS=1` 和 `ANTHROPIC_AWS_WORKSPACE_ID`，然後配置 AWS 認證89 * **Claude Platform on AWS**：設定 `CLAUDE_CODE_USE_ANTHROPIC_AWS=1` 和 `ANTHROPIC_AWS_WORKSPACE_ID`，然後配置 AWS 認證

~~90 * **Google Vertex AI**：設定 `CLAUDE_CODE_USE_VERTEX=1` 環境變數並配置 Google Cloud 認證~~90 * **Google Cloud's Agent Platform**：設定 `CLAUDE_CODE_USE_VERTEX=1` 環境變數並配置 Google Cloud 認證

91 * **Microsoft Azure**：設定 `CLAUDE_CODE_USE_FOUNDRY=1` 環境變數並配置 Azure 認證91 * **Microsoft Azure**：設定 `CLAUDE_CODE_USE_FOUNDRY=1` 環境變數並配置 Azure 認證

92 92

93 有關詳細資訊，請參閱 [Bedrock](/zh-TW/amazon-bedrock)、[Claude Platform on AWS](/zh-TW/claude-platform-on-aws)、[Vertex AI](/zh-TW/google-vertex-ai) 或 [Azure AI Foundry](/zh-TW/microsoft-foundry) 的設定指南。93 有關詳細資訊，請參閱 [Amazon Bedrock](/zh-TW/amazon-bedrock)、[Claude Platform on AWS](/zh-TW/claude-platform-on-aws)、[Google Cloud's Agent Platform](/zh-TW/google-vertex-ai) 或 [Microsoft Foundry](/zh-TW/microsoft-foundry) 的設定指南。

94 94

95 <Note>95 <Note>

96 除非事先獲得批准，否則 Anthropic 不允許第三方開發人員為其產品（包括基於 Claude Agent SDK 構建的代理）提供 claude.ai 登入或速率限制。請改用本文件中描述的 API 金鑰身份驗證方法。96 除非事先獲得批准，否則 Anthropic 不允許第三方開發人員為其產品（包括基於 Claude Agent SDK 構建的代理）提供 claude.ai 登入或速率限制。請改用本文件中描述的 API 金鑰身份驗證方法。

agent-sdk/permissions.md +2 −2

Details

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

110 110

111| 模式 | 描述 | 工具行為 |111| 模式 | 描述 | 工具行為 |

112| :------------------- | :------- | :---------------------------------------------------------------------------------------------- |112| :------------------ | :------- | :---------------------------------------------------------------------------------------------- |

119 119

120<Warning>120<Warning>

121 **子代理程式繼承：** 當父代理程式使用 `bypassPermissions`、`acceptEdits` 或 `auto` 時，所有子代理程式都會繼承該模式，且無法按子代理程式覆蓋。子代理程式可能有不同的系統提示和行為限制較少，因此繼承 `bypassPermissions` 會授予它們完整的自主系統存取權。明確的[`ask` 規則](#how-permissions-are-evaluated)仍然會強制提示。121 **子代理程式繼承：** 當父代理程式使用 `bypassPermissions`、`acceptEdits` 或 `auto` 時，所有子代理程式都會繼承該模式，且無法按子代理程式覆蓋。子代理程式可能有不同的系統提示和行為限制較少，因此繼承 `bypassPermissions` 會授予它們完整的自主系統存取權。明確的[`ask` 規則](#how-permissions-are-evaluated)仍然會強制提示。

agent-sdk/python.md +27 −5

Details

854class ClaudeAgentOptions:854class ClaudeAgentOptions:

855 tools: list[str] | ToolsPreset | None = None855 tools: list[str] | ToolsPreset | None = None

856 allowed_tools: list[str] = field(default_factory=list)856 allowed_tools: list[str] = field(default_factory=list)

858 mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict)858 mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict)

859 strict_mcp_config: bool = False859 strict_mcp_config: bool = False

860 permission_mode: PermissionMode | None = None860 permission_mode: PermissionMode | None = None

900| :---------------------------- | :--------------------------------------------------------------------------------------- | :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |900| :---------------------------- | :--------------------------------------------------------------------------------------- | :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

901| `tools` | `list[str] \| ToolsPreset \| None` | `None` | Tools 配置。使用 `{"type": "preset", "preset": "claude_code"}` 以取得 Claude Code 的預設 tools |901| `tools` | `list[str] \| ToolsPreset \| None` | `None` | Tools 配置。使用 `{"type": "preset", "preset": "claude_code"}` 以取得 Claude Code 的預設 tools |

902| `allowed_tools` | `list[str]` | `[]` | 自動批准的 tools，無需提示。這不會限制 Claude 僅使用這些 tools；未列出的 tools 會進入 `permission_mode` 和 `can_use_tool`。使用 `disallowed_tools` 來阻止 tools。見 [權限](/zh-TW/agent-sdk/permissions#allow-and-deny-rules) |902| `allowed_tools` | `list[str]` | `[]` | 自動批准的 tools，無需提示。這不會限制 Claude 僅使用這些 tools；未列出的 tools 會進入 `permission_mode` 和 `can_use_tool`。使用 `disallowed_tools` 來阻止 tools。見 [權限](/zh-TW/agent-sdk/permissions#allow-and-deny-rules) |

903| `system_prompt` | `str \| SystemPromptPreset \| None` | `None` | 系統提示配置。傳遞字串以取得自訂提示，或使用 `{"type": "preset", "preset": "claude_code"}` 以取得 Claude Code 的系統提示。新增 `"append"` 以擴展預設 |903| `system_prompt` | `str \| SystemPromptPreset \| SystemPromptFile \| None` | `None` | 系統提示配置。傳遞字串以取得自訂提示，`{"type": "preset", "preset": "claude_code"}` 以取得 Claude Code 的系統提示（可選 `"append"`），或 `{"type": "file", "path": "..."}` 以從磁碟載入大型提示。見 [`SystemPromptPreset`](#systempromptpreset) 和 [`SystemPromptFile`](#systempromptfile) |

904| `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | MCP 伺服器配置或配置檔案路徑 |904| `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | MCP 伺服器配置或配置檔案路徑 |

905| `strict_mcp_config` | `bool` | `False` | 當為 `True` 時，僅使用在 `mcp_servers` 中傳遞的伺服器，並忽略專案 `.mcp.json`、使用者設定、外掛程式提供的 MCP 伺服器和 [claude.ai 連接器](/zh-TW/mcp#use-mcp-servers-from-claude-ai)。對應到 CLI `--strict-mcp-config` 旗標 |905| `strict_mcp_config` | `bool` | `False` | 當為 `True` 時，僅使用在 `mcp_servers` 中傳遞的伺服器，並忽略專案 `.mcp.json`、使用者設定、外掛程式提供的 MCP 伺服器和 [claude.ai 連接器](/zh-TW/mcp#use-mcp-servers-from-claude-ai)。對應到 CLI `--strict-mcp-config` 旗標 |

1002| `append` | 否 | 要附加到預設系統提示的其他指示 |1002| `append` | 否 | 要附加到預設系統提示的其他指示 |

1003| `exclude_dynamic_sections` | 否 | 將每個 session 上下文（例如工作目錄、git 狀態和記憶體路徑）從系統提示移到第一個使用者消息。改進跨使用者和機器的提示快取重複使用。見 [修改系統提示](/zh-TW/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |1003| `exclude_dynamic_sections` | 否 | 將每個 session 上下文（例如工作目錄、git 狀態和記憶體路徑）從系統提示移到第一個使用者消息。改進跨使用者和機器的提示快取重複使用。見 [修改系統提示](/zh-TW/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |

1004 1004

1005<h3 id="systempromptfile">

1006 `SystemPromptFile`

1007</h3>

1008

1009用於從檔案而不是作為字串傳遞自訂系統提示的配置。SDK 將此對應到 CLI [`--system-prompt-file`](/zh-TW/cli-reference#system-prompt-flags) 旗標。當提示很大時使用檔案形式：SDK 在 CLI 子程序 argv 上傳遞字串 `system_prompt`，受限於 OS 命令列長度限制，在 SDK 發送任何 API 請求之前。在 Linux 上，單個參數長於大約 128 KB 會在程序生成時失敗，出現 `Argument list too long`。在 Windows 上，整個命令列上限為大約 32 KB，因此字串形式在較低閾值失敗。

1010

1011```python theme={null}

1012class SystemPromptFile(TypedDict):

1013 type: Literal["file"]

1014 path: str

1015```

1016

1017| 欄位 | 必需 | 描述 |

1018| :----- | :- | :-------------------- |

1019| `type` | 是 | 必須是 `"file"` 以從磁碟載入提示 |

1020| `path` | 是 | 包含系統提示的檔案路徑 |

1021

1005<h3 id="settingsource">1022<h3 id="settingsource">

1006 `SettingSource`1023 `SettingSource`

1007</h3>1024</h3>

1192 "plan", # Planning mode - explore without editing1209 "plan", # Planning mode - explore without editing

1193 "dontAsk", # Deny anything not pre-approved instead of prompting1210 "dontAsk", # Deny anything not pre-approved instead of prompting

1194 "bypassPermissions", # Bypass permission checks; explicit ask rules still prompt (use with caution)1211 "bypassPermissions", # Bypass permission checks; explicit ask rules still prompt (use with caution)

1212 "auto", # A model classifier approves or denies each tool call

1195]1213]

1196```1214```

1197 1215

1755```1773```

1756 1774

1757| 欄位 | 類型 | 描述 |1775| 欄位 | 類型 | 描述 |

1758| :------------------- | :--------------- | :------------------------ |1776| :------------------- | :--------------- | :---------------------------------------------------------------------------------------- |

1759| `uuid` | `str` | 此事件的唯一識別碼 |1777| `uuid` | `str` | 此事件的唯一識別碼 |

1760| `session_id` | `str` | session 識別碼 |1778| `session_id` | `str` | session 識別碼 |

1763 1781

1764<h3 id="ratelimitevent">1782<h3 id="ratelimitevent">

1765 `RateLimitEvent`1783 `RateLimitEvent`

2393 tool_name: str2411 tool_name: str

2394 tool_input: dict[str, Any]2412 tool_input: dict[str, Any]

2395 permission_suggestions: NotRequired[list[Any]]2413 permission_suggestions: NotRequired[list[Any]]

2414 agent_id: NotRequired[str]

2415 agent_type: NotRequired[str]

2396```2416```

2397 2417

2398| 欄位 | 類型 | 描述 |2418| 欄位 | 類型 | 描述 |

2399| :----------------------- | :----------------------------- | :---------------------- |2419| :----------------------- | :----------------------------- | :----------------------- |

2401| `tool_name` | `str` | 請求權限的 tool 名稱 |2421| `tool_name` | `str` | 請求權限的 tool 名稱 |

2424| `agent_id` | `str`（可選） | 子代理識別碼，當 hook 在子代理內觸發時出現 |

2425| `agent_type` | `str`（可選） | 子代理類型，當 hook 在子代理內觸發時出現 |

2404 2426

2405<h3 id="hookjsonoutput">2427<h3 id="hookjsonoutput">

2406 `HookJSONOutput`2428 `HookJSONOutput`

agent-sdk/quickstart.md +4 −4

Details

121 121

122 * **Amazon Bedrock**：設定 `CLAUDE_CODE_USE_BEDROCK=1` 環境變數並設定 AWS 認證122 * **Amazon Bedrock**：設定 `CLAUDE_CODE_USE_BEDROCK=1` 環境變數並設定 AWS 認證

123 * **Claude Platform on AWS**：設定 `CLAUDE_CODE_USE_ANTHROPIC_AWS=1` 和 `ANTHROPIC_AWS_WORKSPACE_ID`，然後設定 AWS 認證123 * **Claude Platform on AWS**：設定 `CLAUDE_CODE_USE_ANTHROPIC_AWS=1` 和 `ANTHROPIC_AWS_WORKSPACE_ID`，然後設定 AWS 認證

124 * **Google Vertex AI**：設定 `CLAUDE_CODE_USE_VERTEX=1` 環境變數並設定 Google Cloud 認證124 * **Google Cloud 的 Agent Platform**：設定 `CLAUDE_CODE_USE_VERTEX=1` 環境變數並設定 Google Cloud 認證

125 * **Microsoft Azure**：設定 `CLAUDE_CODE_USE_FOUNDRY=1` 環境變數並設定 Azure 認證125 * **Microsoft Azure**：設定 `CLAUDE_CODE_USE_FOUNDRY=1` 環境變數並設定 Azure 認證

126 126

127 如需詳細資訊，請參閱 [Bedrock](/zh-TW/amazon-bedrock)、[Claude Platform on AWS](/zh-TW/claude-platform-on-aws)、[Vertex AI](/zh-TW/google-vertex-ai) 或 [Azure AI Foundry](/zh-TW/microsoft-foundry) 的設置指南。127 如需詳細資訊，請參閱 [Amazon Bedrock](/zh-TW/amazon-bedrock)、[Claude Platform on AWS](/zh-TW/claude-platform-on-aws)、[Google Cloud 的 Agent Platform](/zh-TW/google-vertex-ai) 或 [Microsoft Foundry](/zh-TW/microsoft-foundry) 的設置指南。

128 128

129 <Note>129 <Note>

130 除非事先獲得批准，否則 Anthropic 不允許第三方開發人員提供 claude.ai 登入或對其產品的速率限制，包括基於 Claude Agent SDK 構建的代理。請改用本文件中描述的 API 金鑰身份驗證方法。130 除非事先獲得批准，否則 Anthropic 不允許第三方開發人員提供 claude.ai 登入或對其產品的速率限制，包括基於 Claude Agent SDK 構建的代理。請改用本文件中描述的 API 金鑰身份驗證方法。

368**權限模式**控制您想要多少人工監督：368**權限模式**控制您想要多少人工監督：

369 369

370| 模式 | 行為 | 用例 |370| 模式 | 行為 | 用例 |

371| -------------------- | ------------------------------------------------------------------------------------------ | -------------- |371| ------------------- | ------------------------------------------------------------------------------------------ | -------------- |

378 378

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

Details

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

92 session_id: str # Session identifier92 session_id: str # Session identifier

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

~~94 parent_tool_use_id: str | None # Parent tool ID if from a subagent~~94 parent_tool_use_id: str | None # Always None

95 ```95 ```

96 96

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

106 ```106 ```

107</CodeGroup>107</CodeGroup>

108 108

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

110

109`event` 欄位包含來自 [Claude API](https://platform.claude.com/docs/en/build-with-claude/streaming#event-types) 的原始串流事件。常見的事件類型包括：111`event` 欄位包含來自 [Claude API](https://platform.claude.com/docs/en/build-with-claude/streaming#event-types) 的原始串流事件。常見的事件類型包括：

110 112

111| 事件類型 | 說明 |113| 事件類型 | 說明 |

agent-sdk/structured-outputs.md +4 −0

Details

247 247

248SDK 支援標準 JSON Schema 功能，包括所有基本類型（object、array、string、number、boolean、null）、`enum`、`const`、`required`、嵌套物件和 `$ref` 定義。有關支援的功能和限制的完整列表，請參閱 [JSON Schema 限制](https://platform.claude.com/docs/zh-TW/build-with-claude/structured-outputs#json-schema-limitations)。248SDK 支援標準 JSON Schema 功能，包括所有基本類型（object、array、string、number、boolean、null）、`enum`、`const`、`required`、嵌套物件和 `$ref` 定義。有關支援的功能和限制的完整列表，請參閱 [JSON Schema 限制](https://platform.claude.com/docs/zh-TW/build-with-claude/structured-outputs#json-schema-limitations)。

249 249

250不是有效 JSON Schema 的架構在啟動時會因錯誤而失敗執行，並命名該問題。在 v2.1.205 之前，無效的架構會被無聲地忽略，代理會返回非結構化文字。

251

252`format` 關鍵字（例如 `"format": "email"`）被接受為註解，SDK 的驗證器不會強制執行。在 v2.1.205 之前，任何包含 `format` 的架構都被視為無效。

253

250<h2 id="example-todo-tracking-agent">254<h2 id="example-todo-tracking-agent">

251 範例：TODO 追蹤代理255 範例：TODO 追蹤代理

252</h2>256</h2>

agent-sdk/subagents.md +3 −1

Details

234 父代理逐字接收子代理的最終消息作為 Agent 工具結果，但可能在其自己的回應中進行摘要。要在面向用戶的回應中逐字保留子代理輸出，請在您傳遞給主 `query()` 調用的提示詞或 `systemPrompt` 選項中包含執行此操作的指令。234 父代理逐字接收子代理的最終消息作為 Agent 工具結果，但可能在其自己的回應中進行摘要。要在面向用戶的回應中逐字保留子代理輸出，請在您傳遞給主 `query()` 調用的提示詞或 `systemPrompt` 選項中包含執行此操作的指令。

235</Note>235</Note>

236 236

237{/* min-version: 2.1.199 */}自 Claude Code v2.1.199 起，結束子代理早期的 API 錯誤（例如速率限制）永遠不會作為其結果傳遞。如果子代理已經產生輸出，Agent 工具會返回該部分輸出並附註子代理未完成；否則工具結果是一條錯誤消息 `Agent terminated early due to an API error`，後跟錯誤詳情。請參閱[子代理中的 API 錯誤](/zh-TW/sub-agents#api-errors-in-subagents)以了解前景和背景行為。237{/* min-version: 2.1.199 */}結束子代理早期的 API 錯誤（例如速率限制）永遠不會作為其結果傳遞。如果速率限制、過載或伺服器錯誤中斷已經產生文本輸出的前景子代理，Agent 工具會返回該部分輸出並附註子代理未完成。{/* min-version: 2.1.200 */}未產生任何內容的子代理，或其唯一輸出是沒有文本的工具調用，會失敗並顯示錯誤消息 `Agent terminated early due to an API error`，後跟錯誤詳情。請參閱[子代理中的 API 錯誤](/zh-TW/sub-agents#api-errors-in-subagents)以了解前景和背景行為。

238

239此部分輸出處理需要 Claude Code v2.1.199 或更高版本。在 v2.1.199 中，速率限制、過載或伺服器錯誤使僅工具調用的形狀保留為空的部分結果，僅包含截斷注釋。

238 240

239<h2 id="invoke-subagents">241<h2 id="invoke-subagents">

240 調用子代理242 調用子代理

agent-sdk/tool-search.md +4 −4

Details

33 配置工具搜尋33 配置工具搜尋

34</h2>34</h2>

35 35

36工具搜尋預設為開啟。在 Vertex AI 上預設為關閉，其中支援 Claude Sonnet 4.5 及更高版本以及 Claude Opus 4.5 及更高版本。當 `ANTHROPIC_BASE_URL` 指向非第一方主機時，它也會被禁用，因為大多數代理不轉發 `tool_reference` 塊。您可以使用 `ENABLE_TOOL_SEARCH` 環境變數覆蓋任一預設值：36工具搜尋預設為開啟。在 Google Cloud 的 Agent Platform 上預設為關閉，其中支援 Claude Sonnet 4.5 及更高版本以及 Claude Opus 4.5 及更高版本。當 `ANTHROPIC_BASE_URL` 指向非第一方主機時，它也會被禁用，因為大多數代理不轉發 `tool_reference` 塊。您可以使用 `ENABLE_TOOL_SEARCH` 環境變數覆蓋任一預設值：

37 37

38| 值 | 行為 |38| 值 | 行為 |

~~39| :------- | :-------------------------------------------------------------------------------------------------------------------------- |~~39| :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

40| （未設置） | 工具搜尋已開啟。工具定義被延遲並按需發現。在 Vertex AI 或非第一方 `ANTHROPIC_BASE_URL` 上回退到預先加載。 |40| （未設置） | 工具搜尋已開啟。工具定義被延遲並按需發現。在 Google Cloud 的 Agent Platform 或非第一方 `ANTHROPIC_BASE_URL` 上回退到預先加載。 |

41| `true` | 工具搜尋始終開啟。SDK 即使在 Vertex AI 和通過代理時也會發送 beta 標頭。在 Sonnet 4.5 或 Opus 4.5 之前的 Vertex AI 模型上，或在不支援 `tool_reference` 塊的代理上，請求會失敗。 |41| `true` | 工具搜尋始終開啟。SDK 即使在 Google Cloud 的 Agent Platform 和通過代理時也會發送 beta 標頭。在 Sonnet 4.5 或 Opus 4.5 之前的 Google Cloud 的 Agent Platform 模型上，或在不支援 `tool_reference` 塊的代理上，請求會失敗。 |

agent-sdk/typescript.md +132 −46

Details

296</h4>296</h4>

297 297

298| 屬性 | 類型 | 描述 |298| 屬性 | 類型 | 描述 |

299| :------------------- | :---------------------- | :----------------------------------------------------------- |299| :------------------- | :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

305| `parent_agent_id` | `string \| null` | 對於來自[嵌套子代理](/zh-TW/sub-agents#spawn-nested-subagents)的消息，生成它的子代理的 `agentId`。對於主會話消息、來自頂級子代理的消息和較舊的會話為 `null`。{/* min-version: 2.1.202 */}需要 Claude Code v2.1.202 或更高版本 |

305 306

306<h4 id="example">307<h4 id="example">

307 示例308 示例

466`query()` 函數的配置對象。467`query()` 函數的配置對象。

467 468

468| 屬性 | 類型 | 默認值 | 描述 |469| 屬性 | 類型 | 默認值 | 描述 |

469| :-------------------------------- | :------------------------------------------------------------------------------------------------------- | :---------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |470| :-------------------------------- | :------------------------------------------------------------------------------------------------------- | :---------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

478| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | 自定義權限函數，僅在 [權限流](/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated) 進入提示時調用。不會為 `allowedTools`、allow 規則或 `permissionMode` 自動批准的調用調用。見 [`CanUseTool`](#canusetool) 了解詳情 |479| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | 自定義權限函數，僅在 [permission flow](/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated) 進入提示時調用。不會為 `allowedTools`、allow 規則或 `permissionMode` 自動批准的調用調用。見 [`CanUseTool`](#canusetool) 了解詳情 |

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

486| `env` | `Record<string, string \| undefined>` | `process.env` | 環境變量。設置此項時，這會替換子進程環境而不是與 `process.env` 合併，因此傳遞 `{ ...process.env, YOUR_VAR: 'value' }` 以保留繼承的變量如 `PATH`。見 [處理緩慢或停滯的 API 響應](#handle-slow-or-stalled-api-responses) 了解此模式的示例，以及 [環境變量](/zh-TW/env-vars) 了解底層 CLI 讀取的變量。設置 `CLAUDE_AGENT_SDK_CLIENT_APP` 以在 User-Agent 標頭中標識您的應用程序 |487| `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](/zh-TW/env-vars) 了解底層 CLI 讀取的變量。設置 `CLAUDE_AGENT_SDK_CLIENT_APP` 以在 User-Agent 標頭中標識您的應用程序 |

489| `extraArgs` | `Record<string, string \| null>` | `{}` | 其他參數 |490| `extraArgs` | `Record<string, string \| null>` | `{}` | 其他參數 |

493| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | 事件的 hooks 回調 |494| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | 事件的 hooks 回調 |

494| `includeHookEvents` | `boolean` | `false` | 將 hooks 生命週期事件包括在消息流中，作為 [`SDKHookStartedMessage`](#sdkhookstartedmessage)、[`SDKHookProgressMessage`](#sdkhookprogressmessage) 和 [`SDKHookResponseMessage`](#sdkhookresponsemessage) |495| `includeHookEvents` | `boolean` | `false` | 將 hooks 生命週期事件包括在消息流中，作為 [`SDKHookStartedMessage`](#sdkhookstartedmessage)、[`SDKHookProgressMessage`](#sdkhookprogressmessage) 和 [`SDKHookResponseMessage`](#sdkhookresponsemessage) |

501| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | MCP 服務器配置 |502| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | MCP 服務器配置 |

503| `onElicitation` | `(request: ElicitationRequest, options: { signal: AbortSignal }) => Promise<ElicitationResult>` | `undefined` | 用於處理 MCP 引出請求的回調。當 MCP 服務器請求用戶輸入且沒有 hooks 首先處理它時調用。未提供時，未處理的引出請求會自動被拒絕 |504| `onElicitation` | `(request: ElicitationRequest, options: { signal: AbortSignal }) => Promise<ElicitationResult>` | `undefined` | 用於處理 MCP elicitation 請求的回調。當 MCP 服務器請求用戶輸入且沒有 hooks 首先處理它時調用。未提供時，未處理的 elicitation 請求會自動被拒絕 |

504| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | 為代理結果定義輸出格式。見 [結構化輸出](/zh-TW/agent-sdk/structured-outputs) 了解詳情 |505| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | 為代理結果定義輸出格式。見 [Structured outputs](/zh-TW/agent-sdk/structured-outputs) 了解詳情 |

520| `settingSources` | [`SettingSource`](#settingsource)`[]` | CLI 默認值（所有源） | 控制加載哪些文件系統設置。傳遞 `[]` 以禁用用戶、項目和本地設置。無論如何都會加載託管策略設置；當會話使用組織憑證在 [符合條件的配置](/zh-TW/server-managed-settings#platform-availability) 上進行身份驗證時，會獲取服務器管理的設置。見 [使用 Claude Code 功能](/zh-TW/agent-sdk/claude-code-features#what-settingsources-does-not-control) |521| `settingSources` | [`SettingSource`](#settingsource)`[]` | CLI 默認值（所有源） | 控制加載哪些文件系統設置。傳遞 `[]` 以禁用用戶、項目和本地設置。無論如何都會加載 [Endpoint-managed policy](/zh-TW/settings#settings-files)；當會話使用組織憑證在 [eligible configuration](/zh-TW/server-managed-settings#platform-availability) 上進行身份驗證時，會獲取服務器管理的設置。見 [Use Claude Code features](/zh-TW/agent-sdk/claude-code-features#what-settingsources-does-not-control) |

525| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }` | `undefined`（最小提示） | 系統提示配置。傳遞字符串以獲得自定義提示，或 `{ type: 'preset', preset: 'claude_code' }` 以使用 Claude Code 的系統提示。使用預設對象形式時，添加 `append` 以使用其他指令擴展它，並設置 `excludeDynamicSections: true` 以將每個會話上下文移到第一個用戶消息中以獲得 [跨機器更好的提示 cache 重用](/zh-TW/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |526| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }` | `undefined`（最小提示） | 系統提示配置。傳遞字符串以獲得自定義提示，或 `{ type: 'preset', preset: 'claude_code' }` 以使用 Claude Code 的系統提示。使用預設對象形式時，添加 `append` 以使用其他指令擴展它，並設置 `excludeDynamicSections: true` 以將每個會話上下文移到第一個用戶消息中以獲得 [better prompt-cache reuse across machines](/zh-TW/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |

526| `taskBudget` | `{ total: number }` | `undefined` | *Alpha。* API 端任務預算（以令牌為單位）。設置後，模型會被告知其剩餘令牌預算，以便它可以調整工具使用速度並在達到限制前完成 |527| `taskBudget` | `{ total: number }` | `undefined` | *Alpha.* API 端任務預算（以令牌為單位）。設置後，模型會被告知其剩餘令牌預算，以便它可以調整工具使用速度並在達到限制前完成 |

527| `thinking` | [`ThinkingConfig`](#thinkingconfig) | 支持的模型為 `{ type: 'adaptive' }` | 控制 Claude 的思考/推理行為。見 [`ThinkingConfig`](#thinkingconfig) 了解選項 |528| `thinking` | [`ThinkingConfig`](#thinkingconfig) | 支持的模型為 `{ type: 'adaptive' }` | 控制 Claude 的思考/推理行為。見 [`ThinkingConfig`](#thinkingconfig) 了解選項 |

529| `toolAliases` | `Record<string, string>` | `undefined` | 將內置工具名稱映射到 MCP 工具名稱，以便 Claude 調用您的 MCP 實現而不是內置工具。例如，`{ Bash: 'mcp__workspace__bash' }` |530| `toolAliases` | `Record<string, string>` | `undefined` | 將內置工具名稱映射到 MCP 工具名稱，以便 Claude 調用您的 MCP 實現而不是內置工具。例如，`{ Bash: 'mcp__workspace__bash' }` |

531| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | 工具配置。傳遞工具名稱數組或使用預設以獲得 Claude Code 的默認工具 |532| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | 工具配置。傳遞工具名稱數組或使用預設以獲得 Claude Code 的默認工具 |

532 533

533<h4 id="handle-slow-or-stalled-api-responses">534<h4 id="handle-slow-or-stalled-api-responses">

534 處理緩慢或停滯的 API 響應535 Handle slow or stalled API responses

535</h4>536</h4>

536 537

537CLI 子進程讀取多個環境變量，這些變量控制 API 超時和停滯檢測。通過 `env` 選項傳遞它們：538CLI 子進程讀取多個環境變量，這些變量控制 API 超時和停滯檢測。通過 `env` 選項傳遞它們：

553* `API_TIMEOUT_MS`：Anthropic 客戶端上的每個請求超時，以毫秒為單位。默認 `600000`。適用於主循環和所有子代理。554* `API_TIMEOUT_MS`：Anthropic 客戶端上的每個請求超時，以毫秒為單位。默認 `600000`。適用於主循環和所有子代理。

554* `CLAUDE_CODE_MAX_RETRIES`：最大 API 重試次數。默認 `10`，上限為 `15`。每次重試都有自己的 `API_TIMEOUT_MS` 窗口，因此最壞情況下的牆時間大約是 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 加上退避。對於需要等待更長時間中斷的無人值守運行，設置 `CLAUDE_CODE_RETRY_WATCHDOG=1`：它無限期重試容量錯誤，{/* min-version: 2.1.199 */}自 Claude Code v2.1.199 起，為其他瞬時錯誤提高默認值至 `300` 並移除此變量的上限。555* `CLAUDE_CODE_MAX_RETRIES`：最大 API 重試次數。默認 `10`，上限為 `15`。每次重試都有自己的 `API_TIMEOUT_MS` 窗口，因此最壞情況下的牆時間大約是 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 加上退避。對於需要等待更長時間中斷的無人值守運行，設置 `CLAUDE_CODE_RETRY_WATCHDOG=1`：它無限期重試容量錯誤，{/* min-version: 2.1.199 */}自 Claude Code v2.1.199 起，為其他瞬時錯誤提高默認值至 `300` 並移除此變量的上限。

555* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：使用 `run_in_background` 啟動的子代理的停滯監視程序。默認 `600000`。在每個流事件上重置；在停滯時中止子代理，將任務標記為失敗，並將錯誤與任何部分結果一起呈現給父代理。不適用於同步子代理。556* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：使用 `run_in_background` 啟動的子代理的停滯監視程序。默認 `600000`。在每個流事件上重置；在停滯時中止子代理，將任務標記為失敗，並將錯誤與任何部分結果一起呈現給父代理。不適用於同步子代理。

556* `CLAUDE_ENABLE_STREAM_WATCHDOG` 與 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`：當標頭已到達但響應正文停止流式傳輸時中止請求。當 `CLAUDE_ENABLE_STREAM_WATCHDOG` 未設置時，默認值在直接 Anthropic API 上由服務器控制，在其他提供商上關閉。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` 默認為 `300000` 並被限制為該最小值。中止的請求通過正常重試路徑進行。557* `CLAUDE_ENABLE_STREAM_WATCHDOG` 與 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`：當標頭已到達但響應正文停止流式傳輸時中止請求。監視程序對所有提供商默認開啟；設置 `CLAUDE_ENABLE_STREAM_WATCHDOG=0` 以禁用它。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` 默認為 `300000` 並被限制為該最小值。中止的請求通過正常重試路徑進行。

557 558

558<h3 id="query-object">559<h3 id="query-object">

559 `Query` 對象560 `Query` object

560</h3>561</h3>

561 562

562由 `query()` 函數返回的介面。563由 `query()` 函數返回的介面。

563 564

564```typescript theme={null}565```typescript theme={null}

565interface Query extends AsyncGenerator<SDKMessage, void> {566interface Query extends AsyncGenerator<SDKMessage, void> {

566 interrupt(): Promise<void>;567 interrupt(): Promise<SDKControlInterruptResponse | undefined>;

567 rewindFiles(568 rewindFiles(

568 userMessageId: string,569 userMessageId: string,

569 options?: { dryRun?: boolean }570 options?: { dryRun?: boolean }

589```590```

590 591

591<h4 id="methods">592<h4 id="methods">

592 方法593 Methods

593</h4>594</h4>

594 595

595| 方法 | 描述 |596| 方法 | 描述 |

596| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |597| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

597| `interrupt()` | 中斷查詢（僅在流式輸入模式下可用） |598| `interrupt()` | 中斷查詢。僅在流式輸入模式下可用。{/* min-version: 2.1.205 */}當 CLI 在 [`SDKSystemMessage.capabilities`](#sdksystemmessage) 中公告 `interrupt_receipt_v1` 功能時，使用列出存活中斷的排隊消息的 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) 進行解決。在 v2.1.205 之前的 CLI 上解決為 `undefined` |

598| `rewindFiles(userMessageId, options?)` | 將文件恢復到指定用戶消息時的狀態。傳遞 `{ dryRun: true }` 以預覽更改。需要 `enableFileCheckpointing: true`。見 [文件 checkpointing](/zh-TW/agent-sdk/file-checkpointing) |599| `rewindFiles(userMessageId, options?)` | 將文件恢復到指定用戶消息時的狀態。傳遞 `{ dryRun: true }` 以預覽更改。需要 `enableFileCheckpointing: true`。見 [File checkpointing](/zh-TW/agent-sdk/file-checkpointing) |

618 `applyFlagSettings()`619 `applyFlagSettings()`

619</h4>620</h4>

620 621

621在運行會話上更改任何 [設置](/zh-TW/settings)，無需重新啟動查詢。當沒有專用設置器的設置需要在會話中期更改時使用它，例如在代理讀取不受信任的輸入後收緊 `permissions`。`setModel()` 和 `setPermissionMode()` 是這兩個鍵的專用設置器；`applyFlagSettings()` 是接受任何設置鍵子集的通用形式，在此處傳遞 `model` 的行為與 `setModel()` 相同。622在運行會話上更改任何 [settings](/zh-TW/settings)，無需重新啟動查詢。當沒有專用設置器的設置需要在會話中期更改時使用它，例如在代理讀取不受信任的輸入後收緊 `permissions`。`setModel()` 和 `setPermissionMode()` 是這兩個鍵的專用設置器；`applyFlagSettings()` 是接受任何設置鍵子集的通用形式，在此處傳遞 `model` 的行為與 `setModel()` 相同。

622 623

623只有某些鍵在會話中期生效：624只有某些鍵在會話中期生效：

624 625

625* **在下一個轉數上應用**：`model`、`effortLevel`、`ultracode`、`permissions`、`hooks`、`skillOverrides`、`fastMode`、`awaySummaryEnabled`、`agent`。切換 `agent` 也會在下一個轉數上應用該代理的模型覆蓋、hooks 和系統提示。626* **在下一個轉數上應用**：`model`、`effortLevel`、`ultracode`、`permissions`、`hooks`、`skillOverrides`、`fastMode`、`awaySummaryEnabled`、`agent`。切換 `agent` 也會在下一個轉數上應用該代理的模型覆蓋、hooks 和系統提示。

626* **在會話中期無效**：系統提示選項。這些在啟動時解決一次，因此運行會話保持原始值，即使調用成功。要更改它們，請啟動新會話。627* **在會話中期無效**：系統提示選項。這些在啟動時解決一次，因此運行會話保持原始值，即使調用成功。要更改它們，請啟動新會話。

627 628

628這些值被寫入標誌設置層，這是內聯 `query()` 的 `settings` 選項在啟動時填充的同一層。標誌設置位於 [設置優先級順序](/zh-TW/settings#settings-precedence) 的頂部附近：它們覆蓋用戶、項目和本地設置，只有託管策略設置可以覆蓋它們。這是 [優先級部分](#settings-precedence) 稱為編程選項的同一層。629`effortLevel` 接受 [effort level](/zh-TW/model-config#adjust-effort-level) 名稱。它也接受 `"ultracode"`，它以 `xhigh` 努力運行會話並打開 [ultracode](/zh-TW/workflows#let-claude-decide-with-ultracode)。`Settings` 類型聲明 `effortLevel` 沒有該值，因此在 TypeScript 中傳遞等效的 `{ ultracode: true }`。{/* min-version: 2.1.203 */}`ultracode` 值需要 Claude Code v2.1.203 或更高版本，並且僅由 `applyFlagSettings()` 接受，不由設置文件中的 `effortLevel` 鍵接受。

630

631這些值被寫入標誌設置層，這是內聯 `query()` 的 `settings` 選項在啟動時填充的同一層。標誌設置位於 [settings precedence order](/zh-TW/settings#settings-precedence) 的頂部附近：它們覆蓋用戶、項目和本地設置，只有託管策略設置可以覆蓋它們。這是 [on-page precedence section](#settings-precedence) 稱為編程選項的同一層。

629 632

630連續調用淺合併頂級鍵。第二次調用 `{ permissions: {...} }` 會替換先前調用中的整個 `permissions` 對象，而不是深度合併到其中。要從標誌層清除鍵並回退到較低優先級源，請為該鍵傳遞 `null`。傳遞 `undefined` 沒有效果，因為 JSON 序列化會將其刪除。633連續調用淺合併頂級鍵。第二次調用 `{ permissions: {...} }` 會替換先前調用中的整個 `permissions` 對象，而不是深度合併到其中。要從標誌層清除鍵並回退到較低優先級源，請為該鍵傳遞 `null`。傳遞 `undefined` 沒有效果，因為 JSON 序列化會將其刪除。

631 634

661```664```

662 665

663<h4 id="methods-1">666<h4 id="methods-1">

664 方法667 Methods

665</h4>668</h4>

666 669

667| 方法 | 描述 |670| 方法 | 描述 |

693 696

694這些是在客戶端連接之前發出的請求，仍在等待回复。SDK 為您讀取數組並將每個條目分派到您的 [`canUseTool`](#canusetool) 回調，這是 [`reinitialize()`](#query-object) 在傳輸間隙後觸發的相同重新傳遞。以冪等方式處理重複的請求 ID，因為一個條目可以重複回調已經收到的請求，然後連接斷開。697這些是在客戶端連接之前發出的請求，仍在等待回复。SDK 為您讀取數組並將每個條目分派到您的 [`canUseTool`](#canusetool) 回調，這是 [`reinitialize()`](#query-object) 在傳輸間隙後觸發的相同重新傳遞。以冪等方式處理重複的請求 ID，因為一個條目可以重複回調已經收到的請求，然後連接斷開。

695 698

699<h3 id="sdkcontrolinterruptresponse">

700 `SDKControlInterruptResponse`

701</h3>

702

703中斷收據：[`interrupt()`](#query-object) 在公告 [`SDKSystemMessage.capabilities`](#sdksystemmessage) 中的 `interrupt_receipt_v1` 功能的 CLI 上解決的值。需要 Claude Code v2.1.205 或更高版本。較早的 CLI 使用空成功有效負載回答中斷，因此 `interrupt()` 解決為 `undefined`。

704

705```typescript theme={null}

706type SDKControlInterruptResponse = {

707 still_queued: string[];

708};

709```

710

711`still_queued` 列出存活中斷的用戶消息的 UUID：仍在隊列中的消息，加上任何已出隊用於下一個轉數但尚未被中止到達的批次。除非您先取消它，否則每個都作為其自己的轉數在中斷後運行。使用收據決定是否重新發送任何內容；重新發送已列出的消息會產生重複轉數。

712

713使用這些注意事項解釋列表：

714

715* 僅出現已使用 UUID 入隊的消息。空數組並不意味著沒有其他內容會運行。

716* 僅列出主線程消息。發送給子代理的消息超出範圍。

717* 列表可以包括您的客戶端從未發送的 UUID，例如 [scheduled task](/zh-TW/scheduled-tasks) 觸發器。忽略您不認識的 UUID，而不是將其視為錯誤。

718

719收據是在處理中斷時拍攝的快照，在乾淨中斷時，它在中斷轉數的 [`SDKResultMessage`](#sdkresultmessage) 之前到達。在該結果之後讀取收據而不是檢查隊列：循環立即啟動下一個排隊轉數，因此您在結果後檢查的隊列已經改變。

720

696<h3 id="agentdefinition">721<h3 id="agentdefinition">

697 `AgentDefinition`722 `AgentDefinition`

698</h3>723</h3>

765 790

766<h4 id="default-behavior">791<h4 id="default-behavior">

767 默認行為792 Default behavior

768</h4>793</h4>

769 794

770當 `settingSources` 被省略或 `undefined` 時，`query()` 加載與 Claude Code CLI 相同的文件系統設置：用戶、項目和本地。託管策略設置在所有情況下都會加載；當會話使用組織憑證在 [符合條件的配置](/zh-TW/server-managed-settings#platform-availability) 上進行身份驗證時，會獲取服務器管理的設置。見 [settingSources 不控制什麼](/zh-TW/agent-sdk/claude-code-features#what-settingsources-does-not-control) 了解無論此選項如何都會讀取的輸入，以及如何禁用它們。795當 `settingSources` 被省略或 `undefined` 時，`query()` 加載與 Claude Code CLI 相同的文件系統設置：用戶、項目和本地。託管策略設置在所有情況下都會加載；當會話使用組織憑證在 [eligible configuration](/zh-TW/server-managed-settings#platform-availability) 上進行身份驗證時，會獲取服務器管理的設置。見 [What settingSources does not control](/zh-TW/agent-sdk/claude-code-features#what-settingsources-does-not-control) 了解無論此選項如何都會讀取的輸入，以及如何禁用它們。

771 796

772<h4 id="why-use-settingsources">797<h4 id="why-use-settingsources">

773 為什麼使用 settingSources798 Why use settingSources

774</h4>799</h4>

775 800

776**禁用文件系統設置：**801**禁用文件系統設置：**

857```882```

858 883

859<h4 id="settings-precedence">884<h4 id="settings-precedence">

860 設置優先級885 Settings precedence

861</h4>886</h4>

862 887

863加載多個源時，設置按此優先級（最高到最低）合併：888加載多個源時，設置按此優先級（最高到最低）合併：

888 913

889用於控制工具使用的自定義權限函數類型。914用於控制工具使用的自定義權限函數類型。

890 915

891函數是 SDK 替代交互式權限提示：它僅在 [權限評估流](/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated) 解決為提示時調用。已由 `allowedTools` 條目、設置 allow 規則或權限模式（如 `acceptEdits` 或 `bypassPermissions`）批准的工具調用永遠不會調用它。要限制每個工具調用，改用 [`PreToolUse` hook](/zh-TW/agent-sdk/hooks)。916函數是 SDK 替代交互式權限提示：它僅在 [permission evaluation flow](/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated) 解決為提示時調用。已由 `allowedTools` 條目、設置 allow 規則或權限模式（如 `acceptEdits` 或 `bypassPermissions`）批准的工具調用永遠不會調用它。要限制每個工具調用，改用 [`PreToolUse` hook](/zh-TW/agent-sdk/hooks)。

892 917

893```typescript theme={null}918```typescript theme={null}

894type CanUseTool = (919type CanUseTool = (

907```932```

908 933

909| 選項 | 類型 | 描述 |934| 選項 | 類型 | 描述 |

910| :--------------- | :------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- |935| :--------------- | :------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

912| `suggestions` | [`PermissionUpdate`](#permissionupdate)`[]` | 建議的權限更新，以便用戶不會再次被提示此工具。Bash 提示包括帶有 `localSettings` [目標](#permissionupdatedestination) 的建議，因此在 `updatedPermissions` 中返回它會將規則寫入 `.claude/settings.local.json` 並在會話中持久化。 |937| `suggestions` | [`PermissionUpdate`](#permissionupdate)`[]` | 建議的權限更新，以便用戶不會再次被提示此工具。Bash 提示包括帶有 `localSettings` [destination](#permissionupdatedestination) 的建議，因此在 `updatedPermissions` 中返回它會將規則寫入 `.claude/settings.local.json` 並在會話中持久化。 |

1097 | SDKTaskStartedMessage1122 | SDKTaskStartedMessage

1098 | SDKTaskProgressMessage1123 | SDKTaskProgressMessage

1099 | SDKTaskUpdatedMessage1124 | SDKTaskUpdatedMessage

1125 | SDKBackgroundTasksChangedMessage

1100 | SDKSessionStateChangedMessage1126 | SDKSessionStateChangedMessage

1101 | SDKWorkerShuttingDownMessage1127 | SDKWorkerShuttingDownMessage

1102 | SDKCommandsChangedMessage1128 | SDKCommandsChangedMessage

1110 | SDKPromptSuggestionMessage1136 | SDKPromptSuggestionMessage

1111 | SDKAPIRetryMessage1137 | SDKAPIRetryMessage

1112 | SDKMirrorErrorMessage1138 | SDKMirrorErrorMessage

1113 | SDKInformationalMessage;1139 | SDKInformationalMessage

1140 | SDKConversationResetMessage;

1114```1141```

1115 1142

1116<h3 id="sdkassistantmessage">1143<h3 id="sdkassistantmessage">

1273 output_style: string;1300 output_style: string;

1274 skills: string[];1301 skills: string[];

1275 plugins: { name: string; path: string }[];1302 plugins: { name: string; path: string }[];

1303 capabilities?: string[];

1276};1304};

1277```1305```

1278 1306

1307{/* min-version: 2.1.205 */}

1308

1309`capabilities` 陣列命名此 CLI 實現的協議行為，因此您可以進行功能檢測而不是比較 `claude_code_version` 字符串。這是一個開放集合：忽略您不認識的值，並檢查您依賴其行為的特定功能。該字段需要 Claude Code v2.1.205 或更高版本，在較早的 CLI 上不存在。

1310

1311| 功能 | 含義 |

1312| ---------------------- | ------------------------------------------------------------------------------------------------------------------ |

1313| `interrupt_receipt_v1` | [`interrupt()`](#query-object) 使用命名存活中斷的排隊消息的 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) 收據進行解析 |

1314

1279<h3 id="sdkpartialassistantmessage">1315<h3 id="sdkpartialassistantmessage">

1280 `SDKPartialAssistantMessage`1316 `SDKPartialAssistantMessage`

1281</h3>1317</h3>

1282 1318

1283流式部分消息（僅當 `includePartialMessages` 為 true 時）。1319流式部分消息（僅當 `includePartialMessages` 為 true 時）。`parent_tool_use_id` 字段始終為 `null`：流事件僅針對主會話發出。對於子代理歸因，使用完整消息（攜帶 `parent_tool_use_id`），或啟用 [`forwardSubagentText`](#options) 以接收子代理文本和思考作為完整消息。

1284 1320

1285```typescript theme={null}1321```typescript theme={null}

1286type SDKPartialAssistantMessage = {1322type SDKPartialAssistantMessage = {

1421type SDKMessageOrigin =1457type SDKMessageOrigin =

1422 | { kind: "human" }1458 | { kind: "human" }

1423 | { kind: "channel"; server: string }1459 | { kind: "channel"; server: string }

1424 | { kind: "peer"; from: string; name?: string; senderTaskId?: string }1460 | {

1461 kind: "peer";

1462 from: string;

1463 name?: string;

1464 senderTaskId?: string;

1465 body?: string;

1466 }

1425 | { kind: "task-notification" }1467 | { kind: "task-notification" }

1426 | { kind: "coordinator" }1468 | { kind: "coordinator" }

1427 | { kind: "auto-continuation" };1469 | { kind: "auto-continuation" };

1428```1470```

1429 1471

1430| `kind` | 含義 |1472| `kind` | 含義 |

1431| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |1473| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1434| `peer` | 來自另一個代理的消息。對於通過 `SendMessage` 發送到 `main` 的進程內[隊友](/zh-TW/agent-teams)，`from` 是隊友的名稱，`senderTaskId` 是其任務 ID。對於跨會話對等體（例如另一個本地 Claude Code 進程），`from` 是發送者地址，`senderTaskId` 不存在。`name` 字段已保留。 |1476| `peer` | 來自另一個代理的消息。對於通過 `SendMessage` 發送到 `main` 的進程內[隊友](/zh-TW/agent-teams)，`from` 是隊友的名稱，`senderTaskId` 是其任務 ID。對於跨會話對等體（例如另一個本地 Claude Code 進程），`from` 是發送者地址，`senderTaskId` 不存在。{/* min-version: 2.1.205 */}}`name` 和 `body` 需要 Claude Code v2.1.205 或更高版本。`name` 是發送者的顯示名稱，由 Claude Code 規範化：它去除 Unicode 控制、格式、代理和行或段落分隔符代碼點，然後修剪結果並將其限制為 64 個代碼點，並帶有省略號。`body` 是去除對等信封的已解碼消息正文，與模型看到的內容完全相同。對於隊友消息，`body` 始終存在；對於跨會話對等體，僅當轉數恰好是由 Claude Code 形成的一個對等信封時才存在。呈現 `name` 和 `body` 而不是重新解析消息文本。 |

2357 2399

2358```typescript theme={null}2400```typescript theme={null}

2359type ExitPlanModeInput = {2401type ExitPlanModeInput = {

2402 /** 已棄用：不再使用。 */

2360 allowedPrompts?: Array<{2403 allowedPrompts?: Array<{

2361 tool: "Bash";2404 tool: "Bash";

2362 prompt: string;2405 prompt: string;

2364};2407};

2365```2408```

2366 2409

2367退出規劃模式。可選地指定實施計劃所需的基於提示的權限。2410退出規劃模式。`allowedPrompts` 字段已棄用且被忽略；Claude Code 仍然接受它，以便現有調用者和記錄驗證。在 v2.1.205 之前，它請求基於提示的 Bash 權限以實施計劃。

2368 2411

2369<h3 id="listmcpresources">2412<h3 id="listmcpresources">

2370 ListMcpResources2413 ListMcpResources

2408};2451};

2409```2452```

2410 2453

2411創建並進入臨時 git worktree 以進行隔離工作。傳遞 `path` 以切換到當前存儲庫的現有 worktree，而不是創建新的。`name` 和 `path` 互斥。2454創建並進入臨時 git worktree 以進行隔離工作。傳遞 `path` 以切換到現有 worktree，而不是創建新的。在首次進入時，目標必須是當前存儲庫的已註冊 worktree，或在多存儲庫工作區中，必須是嵌套在其中的存儲庫的已註冊 worktree；從 worktree 會話內進入時，必須在會話存儲庫的 `.claude/worktrees/` 下。`name` 和 `path` 互斥。

2412 2455

2413<h2 id="tool-output-types">2456<h2 id="tool-output-types">

2414 工具輸出類型2457 工具輸出類型

3656};3699};

3657```3700```

3658 3701

3702<h3 id="sdkbackgroundtaskschangedmessage">

3703 `SDKBackgroundTasksChangedMessage`

3704</h3>

3705

3706每當實時後台任務集合發生變化時發出：任務啟動、完成、被殺死，或前台代理被後台化。`tasks` 陣列是完整的實時集合。用每個有效負載替換任何緩存的集合，而不是配對 `task_started` 和 `task_notification` 事件，以便下一個成員資格變化更正您可能錯過的任何事件。

3707

3708相對於這些每個任務事件的順序是未指定的，因此不要關聯這兩個流。

3709

3710啟動時不發出任何內容。每當會話的 CLI 進程啟動或重新啟動時重置為空集，並讓下一個成員資格變化重新填充它。

3711

3712{/* min-version: 2.1.203 */}需要 Claude Code v2.1.203 或更高版本。

3713

3714```typescript theme={null}

3715type SDKBackgroundTasksChangedMessage = {

3716 type: "system";

3717 subtype: "background_tasks_changed";

3718 tasks: {

3719 task_id: string;

3720 task_type: string;

3721 description: string;

3722 }[];

3723 uuid: UUID;

3724 session_id: string;

3725};

3726```

3727

3659<h3 id="sdkfilespersistedevent">3728<h3 id="sdkfilespersistedevent">

3660 `SDKFilesPersistedEvent`3729 `SDKFilesPersistedEvent`

3661</h3>3730</h3>

3745};3814};

3746```3815```

3747 3816

3817<h3 id="sdkconversationresetmessage">

3818 `SDKConversationResetMessage`

3819</h3>

3820

3821會話的對話被替換而不結束會話時發出，例如在 `/clear` 之後、計劃模式退出時，或當新對話啟動時。在 `new_conversation_id` 下掛載空記錄，並丟棄任何緩存的會話標題。

3822

3823```typescript theme={null}

3824type SDKConversationResetMessage = {

3825 type: "conversation_reset";

3826 new_conversation_id: UUID;

3827 uuid: UUID;

3828 session_id: string;

3829};

3830```

3831

3832{/* min-version: 2.1.203 */}SDK 的已發佈類型在 Claude Code v2.1.203 及更高版本中聲明 `SDKConversationResetMessage`。在 v2.1.203 之前，`SDKMessage` 引用該類型而不聲明它，因此當 `skipLibCheck` 被禁用時，在 `type === "conversation_reset"` 上縮小範圍失敗類型檢查。

3833

3748<h3 id="aborterror">3834<h3 id="aborterror">

3749 `AbortError`3835 `AbortError`

3750</h3>3836</h3>

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

Details

198</CodeGroup>198</CodeGroup>

199 199

200<Note>200<Note>

201 在 Python 中，`can_use_tool` 需要[串流模式](/zh-TW/agent-sdk/streaming-vs-single-mode)和返回 `{"continue_": True}` 的 `PreToolUse` hook 以保持流開放。沒有此 hook，流會在權限回呼可以被調用之前關閉。201 在 Python 中，`can_use_tool` 需要[串流模式](/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。

202</Note>202</Note>

203 203

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

6864. **對應答案**：程式碼檢查輸入是否為數字（使用選項的標籤）或自由文字（直接使用文字）6864. **對應答案**：程式碼檢查輸入是否為數字（使用選項的標籤）或自由文字（直接使用文字）

6875. **返回給 Claude**：回應包括原始 `questions` 陣列和 `answers` 對應6875. **返回給 Claude**：回應包括原始 `questions` 陣列和 `answers` 對應

688 688

689將 TypeScript 版本儲存為 `ask.ts` 並使用 `npx tsx ask.ts` 執行，或將 Python 版本儲存為 `ask.py` 並使用 `python ask.py` 執行。

690

689<CodeGroup>691<CodeGroup>

690 ```python Python theme={null}692 ```python Python theme={null}

691 import asyncio693 import asyncio

agent-view.md +71 −27

Details

90 90

91```text theme={null}91```text theme={null}

92Pinned92Pinned

~~93 ✽ clawd walk cycle Write assets/sprites/clawd-walk.png 3m~~93 ✽ clawd walk cycle Drawing the walk-cycle sprite frames 3m

94 94

95Ready for review95Ready for review

96 ∙ jump physics Opened PR with collision fix #2048 2h96 ∙ jump physics Opened PR with collision fix #2048 2h

97 97

98Needs input98Needs input

~~99 ✻ power-up design needs input: double jump or wall climb? 1m~~99 ✻ power-up design double jump or wall climb? 1m

100 100

101Working101Working

102 ✽ collision detection Edit src/physics/CollisionSystem.ts 2m102 ✽ collision detection Adding swept-AABB checks to CollisionSystem 2m

103 ✢ playtest level 3 run 12 · all checkpoints cleared in 4m103 ✢ playtest level 3 run 12 · all checkpoints cleared in 4m

104 104

105Completed105Completed

141 141

142工作階段狀態通過自動更新和監督程序重新啟動在磁碟上持久化。工作階段也會在您的機器進入睡眠時保留。它們的程序在喚醒時恢復，監督程序會重新連接到它們，而不是將時間間隔視為閒置。關閉仍會停止執行中的工作階段；請參閱[工作階段在關閉後顯示為失敗](#sessions-show-as-failed-after-shutdown)以了解如何恢復它們。142工作階段狀態通過自動更新和監督程序重新啟動在磁碟上持久化。工作階段也會在您的機器進入睡眠時保留。它們的程序在喚醒時恢復，監督程序會重新連接到它們，而不是將時間間隔視為閒置。關閉仍會停止執行中的工作階段；請參閱[工作階段在關閉後顯示為失敗](#sessions-show-as-failed-after-shutdown)以了解如何恢復它們。

143 143

144當您開啟已停止回應的工作階段時，監督程序會重新啟動其程序，工作階段會從中斷的地方繼續中斷的回應。當機器在中途回應時進入睡眠時，工作階段可能會陷入該狀態。需要 Claude Code v2.1.200 或更新版本。

145

144<h3 id="row-summaries">146<h3 id="row-summaries">

145 行摘要147 行摘要

146</h3>148</h3>

147 149

148每行中的單行摘要由 [Haiku-class 模型](/zh-TW/model-config)生成，因此該行可以告訴您工作階段正在做什麼、需要什麼或生成了什麼，無需開啟記錄。當工作階段主動工作時，摘要最多每 15 秒刷新一次，加上每個回合結束時刷新一次。150每行中的單行摘要由 [Haiku-class 模型](/zh-TW/model-config)生成，因此該行可以告訴您工作階段正在做什麼、需要什麼或生成了什麼，無需開啟記錄。當工作階段主動工作時，該行文字最多每 15 秒從工作階段自己的最近輸出更新一次，無需發送模型請求，模型在每個回合結束時寫入新摘要。

151

152工作中的行顯示工作階段說它正在做什麼，被阻止的行顯示它正在詢問的問題。在長回合期間，模型也會大約每分鐘重寫一次摘要，每次重寫後等待時間加倍，最多四分鐘，因此繁忙的行不會持續顯示過時的摘要。文字在 64 列處截斷；開啟[查看面板](#peek-and-reply)以讀取整個句子。在 v2.1.205 之前，工作中的行可能會顯示原始工具調用而不是報告，執行平行工作項目的工作階段在文字之前顯示 `done/total` 計數，例如 `2/5`。

153

154當列表[按目錄分組](#organize-the-list)時，摘要以工作階段的狀態作為著色詞開頭，例如 `Needs input · double jump or wall climb?`。在預設狀態分組中，組標題已命名狀態，因此該行只顯示摘要。在 v2.1.205 之前，按目錄分組的行不帶狀態詞。

149 155

150當工作階段執行兩個或更多平行工作項目時，例如 subagents、背景 shell 命令或監視器，`done/total` 計數（例如 `2/5`）會出現在摘要文字之前。156整個輸出不包含字母或數字的回合，例如在安靜迭代中列印單個符號的 [`/loop`](/zh-TW/scheduled-tasks) 工作階段，保持該行的先前摘要和狀態。在 v2.1.205 之前，該回合被重新分類，可能會將等待您輸入的工作階段翻轉回 `Working`。

151 157

152每次刷新都是通過您的正常提供者的一個簡短 Haiku-class 請求，按照與工作階段本身相同的[資料使用條款](/zh-TW/data-usage)計費和處理。在第三方提供者（例如 Bedrock、Vertex AI、Microsoft Foundry 和自訂閘道）上，當未配置 Haiku 模型時，請求會回退到工作階段的主要模型。設定 [`ANTHROPIC_DEFAULT_HAIKU_MODEL`](/zh-TW/model-config#environment-variables)以在這些提供者上為這些摘要選擇模型。158回合結束摘要和每次中途重寫都是通過您的正常提供者的一個簡短 Haiku-class 請求，按照與工作階段本身相同的[資料使用條款](/zh-TW/data-usage)計費和處理。15 秒的模型重寫之間的更新重用工作階段自己的輸出，不發送請求。在第三方提供者（例如 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和自訂閘道）上，當未配置 Haiku 模型時，請求會回退到工作階段的主要模型。設定 [`ANTHROPIC_DEFAULT_HAIKU_MODEL`](/zh-TW/model-config#environment-variables)以在這些提供者上為這些摘要選擇模型。

153 159

154<h3 id="pull-request-status">160<h3 id="pull-request-status">

155 拉取請求狀態161 拉取請求狀態

157 163

158當工作階段開啟拉取請求時，`#1234` 標籤會出現在該行的右邊緣，在支援超連結的終端中連結到拉取請求。當您向工作階段發送後續訊息時標籤會保留，因此拉取請求在該行恢復為即時進度時保持可見。隔離其變更在 worktree 中的背景工作階段會自己開啟這些拉取請求；[檔案編輯如何隔離](#how-file-edits-are-isolated)涵蓋何時發生以及工作階段在未詢問的情況下永遠不會做什麼。164當工作階段開啟拉取請求時，`#1234` 標籤會出現在該行的右邊緣，在支援超連結的終端中連結到拉取請求。當您向工作階段發送後續訊息時標籤會保留，因此拉取請求在該行恢復為即時進度時保持可見。隔離其變更在 worktree 中的背景工作階段會自己開啟這些拉取請求；[檔案編輯如何隔離](#how-file-edits-are-isolated)涵蓋何時發生以及工作階段在未詢問的情況下永遠不會做什麼。

159 165

160當工作階段開啟了多個拉取請求時，標籤會顯示計數，例如 `3 PRs`，按最需要關注的開啟拉取請求著色。開啟[查看面板](#peek-and-reply)以查看它們全部。166在現有拉取請求上工作的工作階段以相同方式連結到它。使用 `gh` 編輯、評論、關閉或標記拉取請求為準備好會連結該命令自己的輸出命名的拉取請求，因此其捕獲的輸出不命名拉取請求的 `gh` 命令不會建立連結；`gh pr merge` 是常見情況，因為它只將其結果列印到互動終端。使用 `gh pr checkout` 簽出拉取請求，或推送到具有開啟拉取請求的分支，會改為使用 `gh pr view` 查詢該分支來連結它。在 v2.1.205 之前，只有工作階段建立或簽出的拉取請求被連結，推送只在本機分支名稱匹配時連結一個。

167

168Claude Code 從完整命令輸出讀取拉取請求，包括當命令輸出超過內聯限制時保存到檔案的部分。在 v2.1.205 之前，在 Bash 呼叫中建立的拉取請求，其輸出超過約 30,000 個字元，未被連結。

169

170當工作階段連結到多個拉取請求時，標籤會顯示計數，例如 `3 PRs`，按最需要關注的開啟拉取請求著色。開啟[查看面板](#peek-and-reply)以查看它們全部。

161 171

162拉取請求編號按其狀態著色：172拉取請求編號按其狀態著色：

163 173

174 查看和回覆184 查看和回覆

175</h3>185</h3>

176 186

177在選定的行上按 `Space` 開啟查看面板。它顯示工作階段需要您提供什麼、其最近的輸出以及它開啟的任何拉取請求。大多數時候這就足夠了，您永遠不需要開啟完整記錄。187在選定的行上按 `Space` 開啟查看面板。它開啟時顯示工作階段的完整狀態句子（該行會截斷），以及它上次更改的時間，後面跟著連結到工作階段的任何拉取請求。對於等待您的工作階段，它正在詢問的確切問題也會出現在回覆輸入上方。大多數時候查看面板就足夠了，您不需要開啟完整記錄。

178 188

179當工作階段執行平行工作項目時，面板也會命名執行時間最長的項目及其執行時間，因此您可以看到工作階段在等待什麼，而無需附加。189在 v2.1.205 之前，面板只在沒有其他內容可顯示時重複狀態句子，並命名執行時間最長的平行工作項目。

180 190

181在查看面板中輸入回覆並按 `Enter` 將其發送到該工作階段。當工作階段詢問多選問題時，查看面板顯示選項，您可以按數字鍵選擇一個。對於其他被阻止的工作階段，按 `Tab` 用建議的回覆填充輸入，您可以在發送前編輯。使用 `!` 前綴回覆以發送 Bash 命令。191在查看面板中輸入回覆並按 `Enter` 將其發送到該工作階段。當工作階段詢問多選問題時，查看面板顯示選項，您可以按數字鍵選擇一個。對於其他被阻止的工作階段，按 `Tab` 用建議的回覆填充輸入，您可以在發送前編輯。使用 `!` 前綴回覆以發送 Bash 命令。

182 192

202 212

203分離永遠不會停止背景工作階段：`←`、`Ctrl+Z`、`/exit` 和雙 `Ctrl+C` 或雙 `Ctrl+D` 都會讓它繼續執行。要從內部結束工作階段，執行 `/stop`。213分離永遠不會停止背景工作階段：`←`、`Ctrl+Z`、`/exit` 和雙 `Ctrl+C` 或雙 `Ctrl+D` 都會讓它繼續執行。要從內部結束工作階段，執行 `/stop`。

204 214

205在空提示上按 `←` 可從任何 Claude Code 工作階段工作，而不僅僅是您從 agent view 附加的工作階段。它背景化當前工作階段並開啟 agent view，預先選擇該工作階段，因此您可以在不離開終端的情況下切換工作階段。該行會被建立，即使是從沒有對話歷史的全新工作階段，所以 `→` 會返回到它。當該行是唯一的行時，agent view 會在其下方顯示一個入門提示。215在前景中執行的工作階段中，您在終端中啟動的工作階段而不是從 agent view 附加的工作階段，在空提示上按 `←` 會背景化它並開啟 agent view，預先選擇該行，因此您可以在不離開終端的情況下切換工作階段。同一個按鍵會分離附加的工作階段。

206 216

207如果工具在您按 `←` 時執行，Claude Code 會等待最多約十秒鐘讓它完成，然後背景化，回應在背景工作階段中繼續。再次按 `←` 以立即背景化，而不是等待。當進行中的工作無法轉移到背景工作階段時，`Background this session?` 對話會首先出現，與 [`/background`](#from-inside-a-session) 相同。217如果工具在您按 `←` 時執行，Claude Code 會等待最多約十秒鐘讓它完成然後背景化，回應在背景工作階段中繼續。再次按 `←` 以立即背景化，而不是等待。當進行中的工作無法轉移到背景工作階段時，`Background this session?` 對話會首先出現，與 [`/background`](#from-inside-a-session) 相同。

208 218

209該行會被建立，即使是從沒有對話歷史的全新工作階段，所以 `→` 會返回到它。當該行是唯一的行時，agent view 會在其下方顯示一個入門提示。219當 [subagents](/zh-TW/sub-agents) 執行時，十秒限制不適用。Claude Code 會繼續等待，以便它們的工作能夠轉移，並在等待時顯示 `Still backgrounding after the current tool` 通知；再次按 `←` 以立即背景化而不等待，這會從頭開始重新啟動 subagents。在 v2.1.203 之前，等待在十秒後結束，執行中的 subagents 會在沒有警告的情況下從頭開始重新啟動。

210 220

211您可以在 `/config` 中關閉此快捷鍵（`leftArrowOpensAgents` 設定）。221該行會被建立，即使是從沒有對話歷史的全新工作階段，所以 `→` 會返回到它。{/* max-version: 2.1.202 */}在 v2.1.203 之前，當該行是唯一的行時，agent view 會在其下方顯示一個入門提示。

222

223您可以在 `/config` 中使用 `leftArrowOpensAgents` 設定關閉此快捷鍵。

212 224

213<h3 id="organize-the-list">225<h3 id="organize-the-list">

214 組織列表226 組織列表

229 241

230刪除會從 agent view 中移除工作階段。如果 Claude[為工作階段建立了 worktree](#how-file-edits-are-isolated)，刪除會移除該 worktree，包括其中的任何未提交的更改，因此在刪除前推送或提交您想保留的工作。您自己建立的 worktree 並在其中啟動工作階段的會保留在原地。對話記錄會保留在您的本機上，並且仍然可以通過 `claude --resume` 存取。242刪除會從 agent view 中移除工作階段。如果 Claude[為工作階段建立了 worktree](#how-file-edits-are-isolated)，刪除會移除該 worktree，包括其中的任何未提交的更改，因此在刪除前推送或提交您想保留的工作。您自己建立的 worktree 並在其中啟動工作階段的會保留在原地。對話記錄會保留在您的本機上，並且仍然可以通過 `claude --resume` 存取。

231 243

232較舊的已完成工作階段摺疊為 `… N more` 行以保持列表簡短。失敗和具有開啟拉取請求的工作階段始終保持可見。`Completed` 組填充在即時組之後剩餘的垂直空間，在短終端上，標題會壓縮為單行摘要，以便正在工作或需要輸入的工作階段保持可見。244不適合螢幕的已完成工作階段摺疊為 `… N more` 行。失敗和具有開啟拉取請求的工作階段始終保持可見。`Completed` 組填充在即時組之後剩餘的垂直空間，在短終端上，標題會壓縮為單行摘要，以便正在工作或需要輸入的工作階段保持可見。

233 245

234<h3 id="filter-sessions">246<h3 id="filter-sessions">

235 篩選工作階段247 篩選工作階段

302* `/model` 設定[分派模型](#set-the-model)314* `/model` 設定[分派模型](#set-the-model)

303* {/* min-version: 2.1.198 */}自 v2.1.198 起，`/login` 開啟登入對話框，讓您無需附加到工作階段即可再次登入315* {/* min-version: 2.1.198 */}自 v2.1.198 起，`/login` 開啟登入對話框，讓您無需附加到工作階段即可再次登入

304 316

305Skills、您自己的命令和提示擴展內建命令（例如 `/init`）會作為新背景工作階段的第一個提示發送。其他內建命令會顯示 `attach to a session to run it` 提示。317Skills、您自己的命令和提示擴展內建命令（例如 `/init`）會作為新背景工作階段的第一個提示發送。其他內建命令會顯示 `attach to a session to run it` 提示。{/* min-version: 2.1.203 */}您輸入的所有內容都會保留在提示旁邊的輸入框中，以便您可以編輯它。在 v2.1.203 之前，提示會清除輸入，輸入的文字會遺失。

306 318

307將重複任務打包為 [skill](/zh-TW/skills)可讓您從 agent view 多次啟動相同的工作流程，無需重新輸入提示。319將重複任務打包為 [skill](/zh-TW/skills)可讓您從 agent view 多次啟動相同的工作流程，無需重新輸入提示。

308 320

315新工作階段在您開啟 agent view 的目錄中執行。要針對不同的目錄，請使用以下任何方法：327新工作階段在您開啟 agent view 的目錄中執行。要針對不同的目錄，請使用以下任何方法：

316 328

317* 在該目錄中開啟 `claude agents`。329* 在該目錄中開啟 `claude agents`。

318* 在父目錄中開啟 `claude agents`，並在提示中使用 `@<repo>` 提及子儲存庫。輸入 `@` 會列出啟動目錄下一級的 git 儲存庫，加上任何已在列表中有工作階段的目錄。名稱包含空格的目錄不會被列出。330* 在父目錄中開啟 `claude agents`，並在提示中使用 `@<repo>` 提及子儲存庫。輸入 `@` 會列出這些目標：

331

332 * 啟動目錄下一級的 Git 儲存庫

333 * 您啟動的儲存庫的已註冊 [git worktrees](/zh-TW/worktrees)，位於其目錄樹內，例如 Claude 在 `.claude/worktrees/` 下建立的那些，標記有其簽出的分支。使用 `git worktree add ../feature` 等方式在儲存庫外新增的 Worktrees 不會被列出

334 * 任何已在列表中有工作階段的目錄

335

336 名稱包含空格的目錄不會被列出。{/* min-version: 2.1.203 */}在 v2.1.203 之前，已註冊的 worktrees 不會被列出，因此分派到其中意味著從該 worktree 的目錄執行 `claude --bg`。

319* 從 shell，`cd` 進入目錄並執行 `claude --bg "<prompt>"`。337* 從 shell，`cd` 進入目錄並執行 `claude --bg "<prompt>"`。

320 338

321當 agent view 按目錄分組時，突出顯示的行的目錄成為分派目標，因此您可以滾動到組並在其中分派，無需重新輸入路徑。339當 agent view 按目錄分組時，突出顯示的行的目錄成為分派目標，因此您可以滾動到組並在其中分派，無需重新輸入路徑。

371claude --bg --name "flaky-test-fix" "investigate the flaky SettingsChangeDetector test"389claude --bg --name "flaky-test-fix" "investigate the flaky SettingsChangeDetector test"

372```390```

373 391

374背景化後，Claude 列印工作階段的短 ID 和管理它的命令。當您傳遞 `--name` 時，名稱會出現在短 ID 之後：392背景化後，Claude 列印工作階段的短 ID 和管理它的命令。當主機背景工作階段的服務尚未執行時，`--bg` 可能會先列印 `Starting background service…`。當您傳遞 `--name` 時，名稱會出現在短 ID 之後：

375 393

376```text theme={null}394```text theme={null}

377backgrounded · 7c5dcf5d · flaky-test-fix395backgrounded · 7c5dcf5d · flaky-test-fix

425 443

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

427 445

446當 hook 在不是 git 儲存庫的目錄中失敗時，工作階段會跳過該目錄的隔離並就地編輯工作目錄。在 git 儲存庫內，寫入會保持被阻止，直到工作階段隔離。在 v2.1.203 之前，處於該狀態的背景工作階段無法編輯任何檔案：每次寫入都被拒絕，直到它隔離，hook 永遠無法隔離該目錄。

447

428在 agent view 中刪除工作階段（`Ctrl+X` 兩次）會移除 Claude 為其建立的 worktree，包括任何未提交的更改，因此在刪除前合併或推送您想保留的更改。從 shell 使用 [`claude rm`](#manage-sessions-from-the-shell)刪除會保留具有未提交更改的 worktree 並列印其路徑，以便您可以自己清理它。您自己建立並在其中啟動工作階段的 worktree 無論如何都會保留在原位。448在 agent view 中刪除工作階段（`Ctrl+X` 兩次）會移除 Claude 為其建立的 worktree，包括任何未提交的更改，因此在刪除前合併或推送您想保留的更改。從 shell 使用 [`claude rm`](#manage-sessions-from-the-shell)刪除會保留具有未提交更改的 worktree 並列印其路徑，以便您可以自己清理它。您自己建立並在其中啟動工作階段的 worktree 無論如何都會保留在原位。

429 449

430要找到工作階段的 worktree 路徑，查看工作階段或附加並檢查其工作目錄。450要找到工作階段的 worktree 路徑，查看工作階段或附加並檢查其工作目錄。

464 484

465背景工作階段從它執行的目錄讀取其 [settings](/zh-TW/settings)，就像您在那裡啟動了 `claude` 一樣。這包括專案設定中的 [`env` values](/zh-TW/settings#available-settings)，因此在那裡設定的 `ANTHROPIC_MODEL` 或提供者變數適用於該目錄中的背景工作階段。485背景工作階段從它執行的目錄讀取其 [settings](/zh-TW/settings)，就像您在那裡啟動了 `claude` 一樣。這包括專案設定中的 [`env` values](/zh-TW/settings#available-settings)，因此在那裡設定的 `ANTHROPIC_MODEL` 或提供者變數適用於該目錄中的背景工作階段。

466 486

467雲提供者選擇，例如 `CLAUDE_CODE_USE_BEDROCK` 或 `CLAUDE_CODE_USE_VERTEX`，以及 `ANTHROPIC_DEFAULT_*_MODEL` 別名遵循分派工作階段的 shell。閘道端點變數，例如 `ANTHROPIC_BASE_URL` 及其配對的 `ANTHROPIC_AUTH_TOKEN` 則不遵循。請參閱[the supervisor process](#the-supervisor-process)以了解背景工作階段如何源自提供者設定和認證。487雲提供者選擇，例如 `CLAUDE_CODE_USE_BEDROCK` 或 `CLAUDE_CODE_USE_VERTEX`，以及 `ANTHROPIC_DEFAULT_*_MODEL` 別名遵循分派工作階段的 shell。閘道 `ANTHROPIC_BASE_URL` 在該 shell 中匯出時遵循它，以及 `ANTHROPIC_CUSTOM_HEADERS`，當監督者使用相同的閘道環境執行且工作階段在您分派的目錄中執行或是您自己的工作階段使用 `←` 或 `/background` 背景化時。這是當第一個開啟 agent view 或分派背景工作階段的 shell 是閘道 shell 時的正常情況。使用 `@repo` 或 `--cwd` 分派到不同目錄不會攜帶 shell 的閘道；該專案的 [settings](/zh-TW/settings)提供端點。請參閱[the supervisor process](#the-supervisor-process)以了解背景工作階段如何源自提供者設定和認證。

468 488

469[permission mode](/zh-TW/permissions)取決於您如何啟動工作階段。使用 `/bg` 或 `←` 背景化現有工作階段會保持當前權限模式，因此您切換到 `acceptEdits` 或 `auto` 的工作階段在分離後仍保持該模式。從 agent view 輸入分派或從 shell 執行 `claude --bg` 使用該目錄設定中的 `defaultMode`，或分派的 [subagent 的 frontmatter](/zh-TW/sub-agents#supported-frontmatter-fields)中的 `permissionMode`。489[permission mode](/zh-TW/permissions)取決於您如何啟動工作階段。使用 `/bg` 或 `←` 背景化現有工作階段會保持當前權限模式，因此您切換到 `acceptEdits` 或 `auto` 的工作階段在分離後仍保持該模式。從 agent view 輸入分派或從 shell 執行 `claude --bg` 使用該目錄設定中的 `defaultMode`，或分派的 [subagent 的 frontmatter](/zh-TW/sub-agents#supported-frontmatter-fields)中的 `permissionMode`。

470 490

471背景工作階段啟動時的權限模式、模型和努力，以及它攜帶的 [configuration flags](#from-inside-a-session)，在監督者稍後 [stops and restarts](#the-supervisor-process)其進程時都會持續。您使用 `claude --bg --dangerously-skip-permissions` 或 `claude --bg --permission-mode bypassPermissions` 啟動的工作階段在該重新啟動後保持 `bypassPermissions`，而不是回退到目錄的 `defaultMode`，並且您使用 `/model` 或 `/effort` 在工作階段中途更改的模型或努力會被保留。491背景工作階段啟動時的權限模式、模型和努力，以及它攜帶的 [configuration flags](#from-inside-a-session)，在監督者稍後 [stops and restarts](#the-supervisor-process)其進程時都會持續。您使用 `claude --bg --dangerously-skip-permissions` 或 `claude --bg --permission-mode bypassPermissions` 啟動的工作階段在該重新啟動後保持 `bypassPermissions`，而不是回退到目錄的 `defaultMode`，並且您使用 `/model` 或 `/effort` 在工作階段中途更改的模型或努力會被保留。

472 492

493工作階段從 [`effortLevel` setting](/zh-TW/settings#available-settings)而不是從 `--effort` 或 `/effort` 取得的努力不會在分派時固定：為工作階段啟動的每個進程都會再次讀取設定，因此編輯 `settings.json` 中的 `effortLevel` 會到達您使用 `←` 或 `/bg` 背景化的工作階段及其稍後的重新啟動。在 v2.1.203 之前，背景化工作階段會記錄其設定衍生的努力，就像您傳遞了 `--effort` 一樣，因此稍後的 `effortLevel` 編輯永遠無法到達它。

494

495您使用 [`/rename`](/zh-TW/commands) 或 `Ctrl+R` 設定的名稱也會在該重新啟動時持續，因此 [`claude --resume <name>`](/zh-TW/sessions#name-your-sessions) 仍會解析工作階段。在 v2.1.202 之前，重新啟動會將工作階段還原為分派時的名稱，新名稱停止解析。

496

473要為您從 agent view 分派的每個工作階段設定預設值，請在開啟它時傳遞 `--permission-mode`、`--model`、`--effort` 或 `--agent` 中的任何一個：497要為您從 agent view 分派的每個工作階段設定預設值，請在開啟它時傳遞 `--permission-mode`、`--model`、`--effort` 或 `--agent` 中的任何一個：

474 498

475```bash theme={null}499```bash theme={null}

544 568

545監督程序及其工作階段使用與互動工作階段相同的認證進行身份驗證，並且除了模型 API 外不進行額外的網路連接。提供者選擇變數（例如 `CLAUDE_CODE_USE_BEDROCK` 和 `ANTHROPIC_DEFAULT_*_MODEL` 別名）從分派每個工作階段的 shell 中讀取，並應用於其工作程序。569監督程序及其工作階段使用與互動工作階段相同的認證進行身份驗證，並且除了模型 API 外不進行額外的網路連接。提供者選擇變數（例如 `CLAUDE_CODE_USE_BEDROCK` 和 `ANTHROPIC_DEFAULT_*_MODEL` 別名）從分派每個工作階段的 shell 中讀取，並應用於其工作程序。

546 570

547背景工作階段不會繼承閘道端點變數（例如 `ANTHROPIC_BASE_URL`、等效的 Bedrock、Vertex 和 Foundry 基礎 URL 變數，或配對的 `ANTHROPIC_AUTH_TOKEN`）來自啟動監督程序的 shell 或分派 shell。工作階段改用您的儲存認證和專案目錄的[設定](/zh-TW/settings)中 `env` 區塊中的任何 `env` 值。要在專案中指向背景工作階段到 [LLM 閘道](/zh-TW/llm-gateway)，請在該專案的 `.claude/settings.json` `env` 區塊中設定 `ANTHROPIC_BASE_URL`，而不是在您的 shell 中匯出它。571分派 shell 的 `PATH` 以相同方式應用於工作程序，因此工作階段執行的 shell 命令會找到您的終端所擁有的相同工具。在 v2.1.203 之前，背景工作階段保持啟動監督程序的 shell 的 `PATH`，因此自那時以來添加到您 `PATH` 的工具可能會遺失，最常見的是在 Windows 上。

572

573背景工作階段不會繼承閘道端點變數（例如 `ANTHROPIC_BASE_URL` 或等效的 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 基礎 URL 變數）來自啟動監督程序的 shell。如果您分派的 shell 中未匯出閘道，工作階段會使用您的儲存認證和專案目錄的[設定](/zh-TW/settings)中 `env` 區塊中的任何 `env` 值。要在專案中指向每個工作階段到 [LLM 閘道](/zh-TW/llm-gateway)，請在該專案的 `.claude/settings.json` `env` 區塊中設定 `ANTHROPIC_BASE_URL`。

574

575{/* min-version: 2.1.203 */}在您分派的 shell 中匯出的閘道 `ANTHROPIC_BASE_URL` 會到達該工作階段的工作程序，連同 `ANTHROPIC_CUSTOM_HEADERS` 和與它們一起匯出的認證，當監督程序從具有相同閘道的環境啟動時。監督程序從開啟 agent view 或分派背景工作階段的第一個 shell 捕獲其環境，因此從閘道 shell 啟動會給予它該環境。轉發也僅適用於分派到您分派的目錄或使用 `←` 或 `/background` 從您自己的工作階段背景化的工作階段：使用 `@repo` 或 `--cwd` 分派到不同目錄不會攜帶 shell 的閘道，該專案的 `settings.json` `env` 區塊改為提供端點。當監督程序的環境攜帶不同的閘道或沒有閘道時，工作程序會針對預設端點保持您的儲存認證，而不是混合一個環境的認證與另一個環境的端點。在 v2.1.203 之前，分派 shell 的 `ANTHROPIC_BASE_URL` 被丟棄，而與它一起匯出的 `ANTHROPIC_API_KEY` 被保留，因此閘道的金鑰被發送到預設端點，每個請求都失敗並出現 401。

576

577轉發的端點僅適用於該活動程序，永遠不會寫入磁碟。當監督程序停止閒置工作階段並稍後重新啟動它時，重新啟動的程序會再次從您的設定中讀取其端點：使用閘道 `ANTHROPIC_AUTH_TOKEN` 時，它會回退到您的儲存認證，使用閘道發行的 `ANTHROPIC_API_KEY` 時，在設定中設定閘道之前可能無法進行身份驗證。

548 578

549每個背景工作階段都是其自己的 Claude Code 程序，由監督程序管理而不是與您的終端相關聯。正在主動工作、等待您的輸入或已連接終端的工作階段保持其程序執行。執行中的背景 shell 命令、子代理、動態工作流程或監視器計為主動工作，因此長時間執行的程序（例如開發伺服器）會保持工作階段活躍。579每個背景工作階段都是其自己的 Claude Code 程序，由監督程序管理而不是與您的終端相關聯。正在主動工作、等待您的輸入或已連接終端的工作階段保持其程序執行。執行中的背景 shell 命令、子代理、動態工作流程或監視器計為主動工作，因此長時間執行的程序（例如開發伺服器）會保持工作階段活躍。

550 580

570 600

571監督程序監視磁碟上已安裝的 Claude Code 二進位檔案，並在常規[自動更新程序](/zh-TW/setup#auto-updates)替換它後重新啟動到新版本。這是本地檔案監視，不是網路檢查。背景工作階段是分離的程序，因此它們在重新啟動期間繼續執行，新監督程序重新連接到它們。閒置的釘選工作階段也會就地重新啟動到新版本，以便它在您不重新附加的情況下獲取更新。601監督程序監視磁碟上已安裝的 Claude Code 二進位檔案，並在常規[自動更新程序](/zh-TW/setup#auto-updates)替換它後重新啟動到新版本。這是本地檔案監視，不是網路檢查。背景工作階段是分離的程序，因此它們在重新啟動期間繼續執行，新監督程序重新連接到它們。閒置的釘選工作階段也會就地重新啟動到新版本，以便它在您不重新附加的情況下獲取更新。

572 602

603在監督程序重新啟動工作階段時執行 `claude attach`，無論是為了更新、停滯或遷移，會等待替換程序而不是失敗。狀態行（例如 `Agent is updating to the new Claude Code…`）會命名它正在等待的內容並計算經過的秒數，命令會在工作階段準備好時立即連接。大約 60 秒後，它會停止等待並報告錯誤。在 v2.1.205 之前，`claude attach` 在幾秒後停止重試並列印錯誤，而工作階段仍在重新啟動。

604

573<h3 id="where-state-is-stored">605<h3 id="where-state-is-stored">

574 狀態存儲位置606 狀態存儲位置

575</h3>607</h3>

585 617

586每個背景工作階段都設定了 `CLAUDE_JOB_DIR` 環境變數，指向其 `~/.claude/jobs/<id>` 目錄，因此工作階段執行的 shell 命令可以將臨時檔案寫入 `$CLAUDE_JOB_DIR/tmp`，而不會與平行工作階段衝突。618每個背景工作階段都設定了 `CLAUDE_JOB_DIR` 環境變數，指向其 `~/.claude/jobs/<id>` 目錄，因此工作階段執行的 shell 命令可以將臨時檔案寫入 `$CLAUDE_JOB_DIR/tmp`，而不會與平行工作階段衝突。

587 619

588要在不直接讀取檔案的情況下檢查此狀態，請執行 `claude daemon status`。它報告監督程序是否可達、其程序 ID 和版本、socket 目錄，以及有多少背景工作階段處於活動狀態。`/doctor` 包含相同檢查的摘要。620要在不直接讀取檔案的情況下檢查此狀態，請執行 `claude daemon status`。它報告監督程序是否可達、其程序 ID 和版本、socket 目錄，以及有多少背景工作階段處於活動狀態。

589 621

590該命令也會在執行中的監督程序版本與您叫用的 `claude` 版本不同時發出警告，這會在監督程序尚未重新啟動到新版本的更新後發生。警告會顯示兩個版本，並告訴您執行 `claude daemon stop --any` 以採用新版本。當 Claude Code 安裝為作業系統服務時，建議的命令是 `claude daemon stop`，不帶該旗標。622該命令也會在執行中的監督程序版本與您叫用的 `claude` 版本不同時發出警告，這會在監督程序尚未重新啟動到新版本的更新後發生。警告會顯示兩個版本，並告訴您執行 `claude daemon stop --any` 以採用新版本。當 Claude Code 安裝為作業系統服務時，建議的命令是 `claude daemon stop`，不帶該旗標。

591 623

592工作階段在該版本不匹配時保持完整：較舊的 Claude Code 版本更新工作階段的 `state.json` 時會保留它不識別的欄位，並保持工作階段列出。624工作階段在該版本不匹配時保持完整：較舊的 Claude Code 版本更新工作階段的 `state.json` 時會保留它不識別的欄位，並保持工作階段列出。{/* min-version: 2.1.200 */}在 `roster.json` 中的工作階段列表遵循相同規則：較舊的版本在重寫時會保留較新版本寫入的欄位，因此由較新版本啟動的工作階段保持可達，並在監督程序重新啟動後繼續接受輸入。在 v2.1.200 之前，較舊的版本在重寫時可能會丟棄這些欄位。

593 625

594在 Windows 上，當 daemon 的 pipe-key 檔案被鎖定或無法讀取時，`claude daemon status` 會顯示基礎檔案錯誤，而不是報告通用連接失敗。626在 Windows 上，當 daemon 的 pipe-key 檔案被鎖定或無法讀取時，`claude daemon status` 會顯示基礎檔案錯誤，而不是報告通用連接失敗。

595 627

615 Agent view 開啟時沒有工作階段647 Agent view 開啟時沒有工作階段

616</h3>648</h3>

617 649

618在您分派第一個工作階段之前，agent view 會顯示簡短的入門提示，並在工作階段清單的位置顯示範例提示。在底部的輸入框中輸入提示並按 `Enter` 以分派您的第一個工作階段。650在您分派第一個工作階段之前，agent view 會顯示空的區段標題，每個標題下方有描述，以及輸入上方有一行說明，代替工作階段清單。在底部的輸入框中輸入提示並按 `Enter` 以分派您的第一個工作階段。

619 651

620<h3 id="backgrounding-shows-a-background-this-session-dialog">652<h3 id="backgrounding-shows-a-background-this-session-dialog">

621 背景化顯示 `Background this session?` 對話653 背景化顯示 `Background this session?` 對話

637 669

638睡眠單獨不會導致這種情況。工作階段在睡眠期間會被保留，監督程序在喚醒時會重新連接到它們。670睡眠單獨不會導致這種情況。工作階段在睡眠期間會被保留，監督程序在喚醒時會重新連接到它們。

639 671

672<h3 id="opening-a-session-says-the-conversation-is-already-open">

673 開啟工作階段時顯示對話已開啟

674</h3>

675

676開啟一個已停止的列，其對話也由另一個執行中的非互動式 Claude Code 程序持有，例如同一對話的背景工作程序仍在關閉中，會顯示 `This conversation is already open in another running Claude session` 而不是啟動該列的程序，因為兩個程序無法寫入同一個文字記錄。在已經持有對話開啟的工作階段中回覆，或退出它並再次開啟該列。您在拒絕嘗試時輸入的回覆不會遺失；它會在工作階段下次啟動時發送。

677

678在 v2.1.203 之前，此狀態無論如何都會啟動第二個程序。該程序以 `currently running as a background agent` 錯誤退出，該列顯示為失敗。

679

640<h3 id="a-session-fails-before-starting-with-a-possibly-low-memory-note">680<h3 id="a-session-fails-before-starting-with-a-possibly-low-memory-note">

641 工作階段在啟動前失敗，並出現 `possibly low memory` 註記681 工作階段在啟動前失敗，並出現 `possibly low memory` 註記

642</h3>682</h3>

731 771

732| 版本 | 變更 |772| 版本 | 變更 |

733| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |773| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

774| v2.1.205 | {/* min-version: 2.1.205 */}列摘要顯示工作階段自己的單行報告（在 64 欄處截斷），而不是原始工具叫用或 `done/total` 計數；目錄分組列以彩色狀態字開啟。查看面板以完整狀態句子開啟，對於等待您的工作階段，其確切問題顯示在回覆輸入上方。編輯、評論、關閉或使用 `gh` 標記拉取請求為就緒的工作階段會連結到它，不僅是建立或簽出拉取請求的工作階段，推送會連結拉取請求，即使本機分支名稱不符，建立命令的輸出超過內聯限制的拉取請求也會連結。沒有可讀文字的轉向會保留工作階段的先前狀態，而不是將其翻轉回 `Working`。`claude attach` 會等待最多約 60 秒以重新啟動的工作階段，並顯示狀態行說明原因，而不是失敗。 |

775| v2.1.203 | {/* min-version: 2.1.203 */}在分派 shell 中匯出的閘道 `ANTHROPIC_BASE_URL` 會到達從它分派的工作階段進入同一目錄，當監督程序共享該閘道環境時，而不是在保留隨之匯出的 API 金鑰時被丟棄。分派 shell 的 `PATH` 會套用到每個工作階段的工作程序。在子代理執行時按 `←` 會等待它們，而不是在十秒後重新啟動它們。空清單始終顯示區段標題，每個標題下方有描述。在分派輸入中輸入 `@` 也會列出啟動儲存庫的已註冊 git worktrees，這些 worktrees 位於其目錄樹內。從 `effortLevel` 設定繼承的努力會在稍後編輯該設定時跟隨，而不是在分派時固定。開啟其對話已在另一個執行中工作階段中開啟的已停止工作階段會被拒絕並顯示訊息，而不是使列失敗。在 agent view 中不可用的命令會在輸入中保留輸入的文字。在 git 儲存庫外失敗的 `WorktreeCreate` hook 不再阻止工作階段編輯檔案。 |

776| v2.1.202 | {/* min-version: 2.1.202 */}使用 `/rename` 或 `Ctrl+R` 在背景工作階段上設定的名稱在監督程序停止並重新啟動其程序時會保留，而不是還原為工作階段分派時的名稱。 |

777| v2.1.200 | {/* min-version: 2.1.200 */}較舊的 Claude Code 版本在 `roster.json` 中重寫工作階段清單時會保留較新版本寫入的欄位，符合現有的 `state.json` 保證，因此由較新版本啟動的工作階段在監督程序重新啟動後繼續接受輸入。當您開啟已停止回應的工作階段時，監督程序會重新啟動其程序，工作階段會從中斷的地方繼續中斷的回應。 |

734| v2.1.199 | {/* min-version: 2.1.199 */}背景工作階段的程序在低記憶體主機上完成啟動前退出時，其列狀態會顯示 `possibly low memory — free some up and retry`，而不是只顯示裸露的退出原因。使用 `←` 或 `/background` 背景化工作階段會將其 `/color` 帶到新列。 |778| v2.1.199 | {/* min-version: 2.1.199 */}背景工作階段的程序在低記憶體主機上完成啟動前退出時，其列狀態會顯示 `possibly low memory — free some up and retry`，而不是只顯示裸露的退出原因。使用 `←` 或 `/background` 背景化工作階段會將其 `/color` 帶到新列。 |

735| v2.1.198 | {/* min-version: 2.1.198 */}Agent view 在背景工作階段需要輸入、完成或失敗時透過 `preferredNotifChannel` 傳送通知，並使用 `agent_needs_input` 或 `agent_completed` 類型觸發 `Notification` hook。`←` 和 `/exit` 在 `claude attach <id>` 內返回 agent view 而不是退出到 shell；`Ctrl+Z` 返回到 shell。隔離其工作在 worktree 中的背景工作階段會提交、推送其自己的隔離分支（絕不是 `main` 或 `master`），並在完成時開啟草稿拉取請求，而不是先詢問。`/login` 在 agent view 中執行並開啟登入對話框。`Background work is running` 退出對話框提供 `Move to background and exit`。退出交付也涵蓋背景子代理，它們在下次喚醒時從其記錄恢復，而不是被報告為失敗。`claude --bg` 與 `-p` 或 `--print` 結合會被拒絕並出現錯誤。 |779| v2.1.198 | {/* min-version: 2.1.198 */}Agent view 在背景工作階段需要輸入、完成或失敗時透過 `preferredNotifChannel` 傳送通知，並使用 `agent_needs_input` 或 `agent_completed` 類型觸發 `Notification` hook。`←` 和 `/exit` 在 `claude attach <id>` 內返回 agent view 而不是退出到 shell；`Ctrl+Z` 返回到 shell。隔離其工作在 worktree 中的背景工作階段會提交、推送其自己的隔離分支（絕不是 `main` 或 `master`），並在完成時開啟草稿拉取請求，而不是先詢問。`/login` 在 agent view 中執行並開啟登入對話框。`Background work is running` 退出對話框提供 `Move to background and exit`。退出交付也涵蓋背景子代理，它們在下次喚醒時從其記錄恢復，而不是被報告為失敗。`claude --bg` 與 `-p` 或 `--print` 結合會被拒絕並出現錯誤。 |

736| v2.1.196 | {/* min-version: 2.1.196 */}單一 `←` 按下會背景化前景工作階段；較早的版本需要兩次按下，帶有頁尾提示和確認。傳遞給 `claude agents` 的 `--dangerously-skip-permissions` 會顯示繞過免責聲明，而不是被無聲地丟棄。您從未命名的互動工作階段在工作階段清單和 `claude agents --json` 中帶有預設名稱，例如 `my-app-3f`。背景 shell 命令和動態工作流程在工作階段的程序被停止、重新啟動或更新時存活，包括在 Windows 上；設定 `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF=1` 以關閉交付。在重新啟動時誤讀為空的記錄會被重命名為 `.orphaned-` 後綴，而不是被刪除。 |780| v2.1.196 | {/* min-version: 2.1.196 */}單一 `←` 按下會背景化前景工作階段；較早的版本需要兩次按下，帶有頁尾提示和確認。傳遞給 `claude agents` 的 `--dangerously-skip-permissions` 會顯示繞過免責聲明，而不是被無聲地丟棄。您從未命名的互動工作階段在工作階段清單和 `claude agents --json` 中帶有預設名稱，例如 `my-app-3f`。背景 shell 命令和動態工作流程在工作階段的程序被停止、重新啟動或更新時存活，包括在 Windows 上；設定 `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF=1` 以關閉交付。在重新啟動時誤讀為空的記錄會被重命名為 `.orphaned-` 後綴，而不是被刪除。 |

737| v2.1.195 | {/* min-version: 2.1.195 */}進行中的工作在您背景化 Windows 上的工作階段時也會轉移；設定 `CLAUDE_DISABLE_ADOPT=1` 以改為停止它。`Completed` 組填充剩餘的垂直空間，標題在短終端上壓縮。較舊的 Claude Code 版本不再丟棄較新工作階段的 `state.json` 欄位或隱藏這些工作階段。附加到已停止的工作階段會立即切換，而不是顯示空白螢幕最多五秒。無法接受連接的監督程序會自行退出並釋放其鎖定。 |781| v2.1.195 | {/* min-version: 2.1.195 */}進行中的工作在您背景化 Windows 上的工作階段時也會轉移；設定 `CLAUDE_DISABLE_ADOPT=1` 以改為停止它。`Completed` 組填充剩餘的垂直空間，標題在短終端上壓縮。較舊的 Claude Code 版本不再丟棄較新工作階段的 `state.json` 欄位或隱藏這些工作階段。附加到已停止的工作階段會立即切換，而不是顯示空白螢幕最多五秒。無法接受連接的監督程序會自行退出並釋放其鎖定。 |

738| v2.1.174 | {/* min-version: 2.1.174 */}背景工作階段不再繼承閘道端點變數，例如來自監督程序啟動 shell 的 `ANTHROPIC_BASE_URL`；監督程序向預先準備的工作程序提供新的認證快照，修復虛假的 `Could not resolve authentication method` 錯誤。 |782| v2.1.174 | {/* min-version: 2.1.174 */}背景工作階段不再繼承閘道端點變數，例如來自監督程序啟動 shell 的 `ANTHROPIC_BASE_URL`；監督程序向預先準備的工作程序提供新的認證快照，修復虛假的 `Could not resolve authentication method` 錯誤。 |

739| v2.1.172 | {/* min-version: 2.1.172 */}分派輸入中的 `/model` 設定工作階段範圍的分派模型覆蓋。 |783| v2.1.172 | {/* min-version: 2.1.172 */}分派輸入中的 `/model` 設定工作階段範圍的分派模型覆蓋。 |

740| v2.1.161 | {/* min-version: 2.1.161 */}行摘要顯示平行工作項目的 `done/total` 計數；查看面板命名最長執行的平行工作項目。 |784| v2.1.161 | {/* min-version: 2.1.161 */}列摘要顯示平行工作項目的 `done/total` 計數；查看面板命名最長執行的平行工作項目。 |

741| v2.1.157 | {/* min-version: 2.1.157 */}}`claude agents` 接受 `--agent`；分派的工作階段尊重 `agent` 設定。 |785| v2.1.157 | {/* min-version: 2.1.157 */}`claude agents` 接受 `--agent`；分派的工作階段尊重 `agent` 設定。 |

742| v2.1.145 | {/* min-version: 2.1.145 */}查看面板回覆輸入和分派輸入中支援語音聽寫。 |786| v2.1.145 | {/* min-version: 2.1.145 */}查看面板回覆輸入和分派輸入中支援語音聽寫。 |

743| v2.1.143 | {/* min-version: 2.1.143 */}}`worktree.bgIsolation` 設定新增；`claude agents` 接受 `--allow-dangerously-skip-permissions`。 |787| v2.1.143 | {/* min-version: 2.1.143 */}`worktree.bgIsolation` 設定新增；`claude agents` 接受 `--allow-dangerously-skip-permissions`。 |

744| v2.1.142 | {/* min-version: 2.1.142 */}}`claude agents` 接受 `--permission-mode`、`--model`、`--effort`、`--dangerously-skip-permissions`、`--settings`、`--add-dir`、`--plugin-dir`、`--mcp-config` 和 `--strict-mcp-config`。 |788| v2.1.142 | {/* min-version: 2.1.142 */}`claude agents` 接受 `--permission-mode`、`--model`、`--effort`、`--dangerously-skip-permissions`、`--settings`、`--add-dir`、`--plugin-dir`、`--mcp-config` 和 `--strict-mcp-config`。 |

745| v2.1.141 | {/* min-version: 2.1.141 */}}`claude agents` 接受 `--cwd` 以將清單範圍限定為一個專案。 |789| v2.1.141 | {/* min-version: 2.1.141 */}`claude agents` 接受 `--cwd` 以將清單範圍限定為一個專案。 |

746| v2.1.139 | {/* min-version: 2.1.139 */}Agent view 作為研究預覽版本引入。 |790| v2.1.139 | {/* min-version: 2.1.139 */}Agent view 作為研究預覽版本引入。 |

amazon-bedrock.md +37 −37

Details

82 先決條件82 先決條件

83</h2>83</h2>

84 84

~~85在使用 Bedrock 設定 Claude Code 之前，請確保您具有：~~85在使用 Amazon Bedrock 設定 Claude Code 之前，請確保您具有：

86 86

~~87* 已啟用 Bedrock 存取的 AWS 帳戶~~87* 已啟用 Amazon Bedrock 存取的 AWS 帳戶

~~88* 在 Bedrock 中存取所需的 Claude 模型（例如 Claude Sonnet 4.6）~~88* 在 Amazon Bedrock 中存取所需的 Claude 模型（例如 Claude Sonnet 4.6）

89* 已安裝並設定 AWS CLI（選用 - 僅在您沒有其他取得認證機制時才需要）89* 已安裝並設定 AWS CLI（選用 - 僅在您沒有其他取得認證機制時才需要）

90* 適當的 IAM 權限90* 適當的 IAM 權限

91 91

92若要使用您自己的 Bedrock 認證登入，請遵循下面的[使用 Bedrock 登入](#sign-in-with-bedrock)。若要在整個團隊中部署 Claude Code，請使用[手動設定](#set-up-manually)步驟並在推出前[固定您的模型版本](#4-pin-model-versions)。92若要使用您自己的 Amazon Bedrock 認證登入，請遵循下面的[使用 Amazon Bedrock 登入](#sign-in-with-bedrock)。若要在整個團隊中部署 Claude Code，請使用[手動設定](#set-up-manually)步驟並在推出前[固定您的模型版本](#4-pin-model-versions)。

93 93

94<h2 id="sign-in-with-bedrock">94<h2 id="sign-in-with-bedrock">

95 使用 Bedrock 登入95 使用 Bedrock 登入

96</h2>96</h2>

97 97

98如果您有 AWS 認證並想開始透過 Bedrock 使用 Claude Code，登入精靈會引導您完成整個過程。您每個帳戶完成一次 AWS 端的先決條件；精靈會處理 Claude Code 端。98如果您有 AWS 認證並想開始透過 Amazon Bedrock 使用 Claude Code，登入精靈會引導您完成整個過程。您每個帳戶完成一次 AWS 端的先決條件；精靈會處理 Claude Code 端。

99 99

100<Steps>100<Steps>

101 <Step title="在您的 AWS 帳戶中啟用 Anthropic 模型">101 <Step title="在您的 AWS 帳戶中啟用 Anthropic 模型">

102 在 [Amazon Bedrock 主控台](https://console.aws.amazon.com/bedrock/)中，開啟模型目錄，選取 Anthropic 模型，然後提交使用案例表單。提交後立即授予存取權限。請參閱[提交使用案例詳細資訊](#1-submit-use-case-details)以了解 AWS Organizations，以及[IAM 設定](#iam-configuration)以了解您的角色所需的權限。102 在 [Amazon Bedrock 主控台](https://console.aws.amazon.com/bedrock/)中，開啟模型目錄，選取 Anthropic 模型，然後提交使用案例表單。提交後立即授予存取權限。請參閱[提交使用案例詳細資訊](#1-submit-use-case-details)以了解 AWS Organizations，以及[IAM 設定](#iam-configuration)以了解您的角色所需的權限。

103 </Step>103 </Step>

104 104

105 <Step title="啟動 Claude Code 並選擇 Bedrock">105 <Step title="啟動 Claude Code 並選擇 Amazon Bedrock">

106 執行 `claude`。在登入提示處，選取**第三方平台**，然後選取 **Amazon Bedrock**。106 執行 `claude`。在登入提示處，選取**第三方平台**，然後選取 **Amazon Bedrock**。

107 </Step>107 </Step>

108 108

109 <Step title="遵循精靈提示">109 <Step title="遵循精靈提示">

110 選擇您如何向 AWS 進行驗證：從您的 `~/.aws` 目錄偵測到的 AWS 設定檔、Bedrock API 金鑰、存取金鑰和密碼，或已在您的環境中的認證。精靈會選取您的區域，驗證您的帳戶可以叫用哪些 Claude 模型，並讓您固定它們。它會將結果儲存到您的[使用者設定檔](/zh-TW/settings)的 `env` 區塊，因此您不需要自己匯出環境變數。110 選擇您如何向 AWS 進行驗證：從您的 `~/.aws` 目錄偵測到的 AWS 設定檔、Amazon Bedrock API 金鑰、存取金鑰和密碼，或已在您的環境中的認證。精靈會選取您的區域，驗證您的帳戶可以叫用哪些 Claude 模型，並讓您固定它們。它會將結果儲存到您的[使用者設定檔](/zh-TW/settings)的 `env` 區塊，因此您不需要自己匯出環境變數。

111 </Step>111 </Step>

112</Steps>112</Steps>

113 113

117 手動設定117 手動設定

118</h2>118</h2>

119 119

120若要透過環境變數而不是精靈來設定 Bedrock，例如在 CI 或指令碼化企業推出中，請遵循下面的步驟。120若要透過環境變數而不是精靈來設定 Amazon Bedrock，例如在 CI 或指令碼化企業推出中，請遵循下面的步驟。

121 121

122<h3 id="1-submit-use-case-details">122<h3 id="1-submit-use-case-details">

123 1. 提交使用案例詳細資訊123 1. 提交使用案例詳細資訊

168 168

169[深入了解](https://docs.aws.amazon.com/signin/latest/userguide/command-line-sign-in.html) `aws login`。169[深入了解](https://docs.aws.amazon.com/signin/latest/userguide/command-line-sign-in.html) `aws login`。

170 170

171**選項 E：Bedrock API 金鑰**171**選項 E：Amazon Bedrock API 金鑰**

172 172

173```bash theme={null}173```bash theme={null}

174export AWS_BEARER_TOKEN_BEDROCK=your-bedrock-api-key174export AWS_BEARER_TOKEN_BEDROCK=your-bedrock-api-key

175```175```

176 176

177Bedrock API 金鑰提供了一種更簡單的驗證方法，無需完整的 AWS 認證。[深入了解 Bedrock API 金鑰](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)。177Amazon Bedrock API 金鑰提供了一種更簡單的驗證方法，無需完整的 AWS 認證。[深入了解 Amazon Bedrock API 金鑰](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)。

178 178

179<h4 id="advanced-credential-configuration">179<h4 id="advanced-credential-configuration">

180 進階認證設定180 進階認證設定

185這兩個設定有不同的觸發條件：185這兩個設定有不同的觸發條件：

186 186

187* **`awsAuthRefresh`**：僅在 Claude Code 偵測到您的 AWS 認證已過期時執行，基於本機時間戳記或當 API 傳回認證錯誤時，然後使用重新整理的認證重試請求。187* **`awsAuthRefresh`**：僅在 Claude Code 偵測到您的 AWS 認證已過期時執行，基於本機時間戳記或當 API 傳回認證錯誤時，然後使用重新整理的認證重試請求。

188* **`awsCredentialExport`**：在工作階段開始時和每次認證重新載入時執行，即使您的 AWS 預設認證提供者鏈中的認證仍然有效。當您的 Bedrock 帳戶需要與預設提供者鏈會解析的認證不同的跨帳戶認證時，請使用此選項。188* **`awsCredentialExport`**：在工作階段開始時和每次認證重新載入時執行，即使您的 AWS 預設認證提供者鏈中的認證仍然有效。當您的 Amazon Bedrock 帳戶需要與預設提供者鏈會解析的認證不同的跨帳戶認證時，請使用此選項。

189 189

190<h5 id="example-configuration">190<h5 id="example-configuration">

191 範例設定191 範例設定

227 3. 設定 Claude Code227 3. 設定 Claude Code

228</h3>228</h3>

229 229

230設定下列環境變數以啟用 Bedrock：230設定下列環境變數以啟用 Amazon Bedrock：

231 231

232```bash theme={null}232```bash theme={null}

233# 啟用 Bedrock 整合233# 啟用 Bedrock 整合

243# export ANTHROPIC_BEDROCK_BASE_URL=https://bedrock-runtime.us-east-1.amazonaws.com243# export ANTHROPIC_BEDROCK_BASE_URL=https://bedrock-runtime.us-east-1.amazonaws.com

244```244```

245 245

246為 Claude Code 啟用 Bedrock 時，請記住以下事項：246為 Claude Code 啟用 Amazon Bedrock 時，請記住以下事項：

247 247

248* {/* min-version: 2.1.172 */}自 v2.1.172 起，您只需設定 `AWS_REGION` 以覆寫您的 AWS 設定檔的區域，或在您的設定檔沒有區域時設定。Claude Code 按此順序解析區域：248* {/* min-version: 2.1.172 */}自 v2.1.172 起，您只需設定 `AWS_REGION` 以覆寫您的 AWS 設定檔的區域，或在您的設定檔沒有區域時設定。Claude Code 按此順序解析區域：

249 249

253 * `us-east-1`253 * `us-east-1`

254 254

255 作用中設定檔是 `AWS_PROFILE`（如果已設定），否則為 `default`。設定 `AWS_SHARED_CREDENTIALS_FILE` 或 `AWS_CONFIG_FILE` 以指向非預設檔案路徑。執行 `/status` 以查看已解析的區域。當區域來自您的 AWS 設定檔或預設回退時，`/status` 也會記錄來源。在 v2.1.171 及更早版本上，Claude Code 不會讀取 AWS 設定檔，因此請明確設定 `AWS_REGION`。255 作用中設定檔是 `AWS_PROFILE`（如果已設定），否則為 `default`。設定 `AWS_SHARED_CREDENTIALS_FILE` 或 `AWS_CONFIG_FILE` 以指向非預設檔案路徑。執行 `/status` 以查看已解析的區域。當區域來自您的 AWS 設定檔或預設回退時，`/status` 也會記錄來源。在 v2.1.171 及更早版本上，Claude Code 不會讀取 AWS 設定檔，因此請明確設定 `AWS_REGION`。

256* 使用 Bedrock 時，`/logout` 命令無法使用，因為驗證是透過 AWS 認證處理的。256* 使用 Amazon Bedrock 時，`/logout` 命令無法使用，因為驗證是透過 AWS 認證處理的。

257* WebSearch 工具在 Bedrock 上無法使用。請參閱 [WebSearch 工具行為](/zh-TW/tools-reference#websearch-tool-behavior)。257* WebSearch 工具在 Amazon Bedrock 上無法使用。請參閱 [WebSearch 工具行為](/zh-TW/tools-reference#websearch-tool-behavior)。

258* 您可以使用設定檔來設定環境變數，例如 `AWS_PROFILE`，您不想將其洩露給其他程序。請參閱[設定](/zh-TW/settings)以取得更多資訊。258* 您可以使用設定檔來設定環境變數，例如 `AWS_PROFILE`，您不想將其洩露給其他程序。請參閱[設定](/zh-TW/settings)以取得更多資訊。

259 259

260<h3 id="4-pin-model-versions">260<h3 id="4-pin-model-versions">

262</h3>262</h3>

263 263

264<Warning>264<Warning>

265 在部署給多個使用者時固定特定的模型版本。如果不固定，模型別名（例如 `sonnet` 和 `opus`）會解析為 Claude Code 針對 Bedrock 的內建預設值，該預設值可能落後於最新版本，且可能在您的帳戶中尚不可用。Claude Code 在啟動時會在預設值無法使用時[回退](#startup-model-checks)到先前版本，但固定可讓您控制使用者何時移至新模型。265 在部署給多個使用者時固定特定的模型版本。如果不固定，模型別名（例如 `sonnet` 和 `opus`）會解析為 Claude Code 針對 Amazon Bedrock 的內建預設值，該預設值可能落後於最新版本，且可能在您的帳戶中尚不可用。Claude Code 在啟動時會在預設值無法使用時[回退](#startup-model-checks)到先前版本，但固定可讓您控制使用者何時移至新模型。

266</Warning>266</Warning>

267 267

268將這些環境變數設定為特定的 Bedrock 模型 ID。268將這些環境變數設定為特定的 Amazon Bedrock 模型 ID。

269 269

270如果沒有 `ANTHROPIC_DEFAULT_OPUS_MODEL`，Bedrock 上的 `opus` 別名會解析為 Opus 4.6。將其設定為 Opus 4.8 ID 以使用最新模型：270如果沒有 `ANTHROPIC_DEFAULT_OPUS_MODEL`，Amazon Bedrock 上的 `opus` 別名會解析為 Opus 4.6。將其設定為 Opus 4.8 ID 以使用最新模型：

271 271

272```bash theme={null}272```bash theme={null}

273export ANTHROPIC_DEFAULT_OPUS_MODEL='us.anthropic.claude-opus-4-8'273export ANTHROPIC_DEFAULT_OPUS_MODEL='us.anthropic.claude-opus-4-8'

285| 小型/快速模型 | 與主要模型相同 |285| 小型/快速模型 | 與主要模型相同 |

286 286

287背景工作（例如工作階段標題產生）使用小型/快速模型，通常是 Haiku 級模型。在 Bedrock 上，Claude Code 預設為主要模型，因為 Haiku 可能不會在每個帳戶或區域中啟用。若要使用 Haiku 進行背景工作，請將 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 設定為您帳戶中可用的模型 ID。287背景工作（例如工作階段標題產生）使用小型/快速模型，通常是 Haiku 級模型。在 Amazon Bedrock 上，Claude Code 預設為主要模型，因為 Haiku 可能不會在每個帳戶或區域中啟用。若要使用 Haiku 進行背景工作，請將 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 設定為您帳戶中可用的模型 ID。

288 288

289若要進一步自訂模型，請使用以下其中一種方法：289若要進一步自訂模型，請使用以下其中一種方法：

290 290

305 305

3061 小時快取 TTL 的計費費率高於 5 分鐘預設值。請參閱[快取生命週期](/zh-TW/prompt-caching#cache-lifetime)。3061 小時快取 TTL 的計費費率高於 5 分鐘預設值。請參閱[快取生命週期](/zh-TW/prompt-caching#cache-lifetime)。

307 307

308<Note>Prompt caching 可能不適用於所有 Bedrock 區域。如果快取權杖計數保持為零，請檢查 Bedrock 文件中的[支援的模型、區域和限制](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html#prompt-caching-models)。</Note>308<Note>Prompt caching 可能不適用於所有 Amazon Bedrock 區域。如果快取權杖計數保持為零，請檢查 Amazon Bedrock 文件中的[支援的模型、區域和限制](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html#prompt-caching-models)。</Note>

309 309

310<h4 id="map-each-model-version-to-an-inference-profile">310<h4 id="map-each-model-version-to-an-inference-profile">

311 將每個模型版本對應至推論設定檔311 將每個模型版本對應至推論設定檔

326}326}

327```327```

328 328

329當使用者在 `/model` 中選取其中一個版本時，Claude Code 會使用對應的 ARN 呼叫 Bedrock。沒有覆寫的版本會回退到內建的 Bedrock 模型 ID 或在啟動時發現的任何相符推論設定檔。請參閱[覆寫每個版本的模型 ID](/zh-TW/model-config#override-model-ids-per-version)，以了解覆寫如何與 `availableModels` 和其他模型設定互動的詳細資訊。329當使用者在 `/model` 中選取其中一個版本時，Claude Code 會使用對應的 ARN 呼叫 Amazon Bedrock。{/* min-version: 2.1.200 */}當您透過 `--model` 或 `ANTHROPIC_MODEL` 直接傳遞 Anthropic 模型 ID 時，相同的對應也適用。沒有覆寫的版本會回退到內建的 Amazon Bedrock 模型 ID 或在啟動時發現的任何相符推論設定檔。在 v2.1.200 之前，`--model` 和 `ANTHROPIC_MODEL` 值會直接到達 Amazon Bedrock，而不會通過覆寫對應。請參閱[覆寫每個版本的模型 ID](/zh-TW/model-config#override-model-ids-per-version)，以了解覆寫如何與 `availableModels` 和其他模型設定互動的詳細資訊。

330 330

331<h2 id="startup-model-checks">331<h2 id="startup-model-checks">

332 啟動模型檢查332 啟動模型檢查

333</h2>333</h2>

334 334

335當 Claude Code 以 Bedrock 設定啟動時，它會驗證它打算使用的模型在您的帳戶中是否可存取。此檢查需要 Claude Code v2.1.94 或更新版本。335當 Claude Code 以 Amazon Bedrock 設定啟動時，它會驗證它打算使用的模型在您的帳戶中是否可存取。此檢查需要 Claude Code v2.1.94 或更新版本。

336 336

337如果您已固定的模型版本比目前 Claude Code 預設值更舊，且您的帳戶可以叫用較新版本，Claude Code 會提示您更新固定。接受會將新模型 ID 寫入您的[使用者設定檔](/zh-TW/settings)並重新啟動 Claude Code。拒絕會被記住，直到下一次預設版本變更。指向[應用程式推論設定檔 ARN](#map-each-model-version-to-an-inference-profile) 的固定會被跳過，因為這些由您的管理員管理。337如果您已固定的模型版本比目前 Claude Code 預設值更舊，且您的帳戶可以叫用較新版本，Claude Code 會提示您更新固定。接受會將新模型 ID 寫入您的[使用者設定檔](/zh-TW/settings)並重新啟動 Claude Code。拒絕會被記住，直到下一次預設版本變更。指向[應用程式推論設定檔 ARN](#map-each-model-version-to-an-inference-profile) 的固定會被跳過，因為這些由您的管理員管理。

338 338

339如果您尚未固定模型且目前預設值在您的帳戶中不可用，Claude Code 會在目前工作階段中回退到先前版本並顯示通知。回退不會被保留。在您的 Bedrock 帳戶中啟用較新模型或[固定版本](#4-pin-model-versions)以使選擇永久化。339如果您尚未固定模型且目前預設值在您的帳戶中不可用，Claude Code 會在目前工作階段中回退到先前版本並顯示通知。回退不會被保留。在您的 Amazon Bedrock 帳戶中啟用較新模型或[固定版本](#4-pin-model-versions)以使選擇永久化。

340 340

341<h2 id="iam-configuration">341<h2 id="iam-configuration">

342 IAM 設定342 IAM 設定

387 387

388如果權杖缺少此權限，Claude Code 會透過使用替代形狀重試一次來自動復原，因此請求仍會成功，但每個新模型都會增加額外的往返。授予權限可避免重試。這最常適用於 `AWS_BEARER_TOKEN_BEDROCK` 部署，其中權杖的政策通常比完整 IAM 角色更狹隘。388如果權杖缺少此權限，Claude Code 會透過使用替代形狀重試一次來自動復原，因此請求仍會成功，但每個新模型都會增加額外的往返。授予權限可避免重試。這最常適用於 `AWS_BEARER_TOKEN_BEDROCK` 部署，其中權杖的政策通常比完整 IAM 角色更狹隘。

389 389

390如需詳細資訊，請參閱 [Bedrock IAM 文件](https://docs.aws.amazon.com/bedrock/latest/userguide/security-iam.html)。390如需詳細資訊，請參閱 [Amazon Bedrock IAM 文件](https://docs.aws.amazon.com/bedrock/latest/userguide/security-iam.html)。

391 391

392<Note>392<Note>

393 為 Claude Code 建立專用的 AWS 帳戶，以簡化成本追蹤和存取控制。393 為 Claude Code 建立專用的 AWS 帳戶，以簡化成本追蹤和存取控制。

433 使用 Mantle 端點433 使用 Mantle 端點

434</h2>434</h2>

435 435

436Mantle 是一個 Amazon Bedrock 端點，透過原生 Anthropic API 形狀而不是 Bedrock Invoke API 提供 Claude 模型。它使用相同的 AWS 認證、IAM 權限和本頁面前面所述的 `awsAuthRefresh` 設定。436Mantle 是一個 Amazon Bedrock 端點，透過原生 Anthropic API 形狀而不是 Amazon Bedrock Invoke API 提供 Claude 模型。它使用相同的 AWS 認證、IAM 權限和本頁面前面所述的 `awsAuthRefresh` 設定。

437 437

438<Note>438<Note>

439 Mantle 需要 Claude Code v2.1.94 或更新版本。執行 `claude --version` 以檢查。439 Mantle 需要 Claude Code v2.1.94 或更新版本。執行 `claude --version` 以檢查。

450export AWS_REGION=us-east-1450export AWS_REGION=us-east-1

451```451```

452 452

453Claude Code 從 AWS 區域構造端點 URL。{/* min-version: 2.1.172 */}自 v2.1.172 起，區域的解析優先順序與[上面的 Bedrock](#3-configure-claude-code) 相同；較早的版本僅使用 `AWS_REGION`。若要為自訂端點或閘道覆寫 URL，請設定 `ANTHROPIC_BEDROCK_MANTLE_BASE_URL`。453Claude Code 從 AWS 區域構造端點 URL。{/* min-version: 2.1.172 */}自 v2.1.172 起，區域的解析優先順序與[上面的 Amazon Bedrock](#3-configure-claude-code) 相同；較早的版本僅使用 `AWS_REGION`。若要為自訂端點或閘道覆寫 URL，請設定 `ANTHROPIC_BEDROCK_MANTLE_BASE_URL`。

454 454

455在 Claude Code 內執行 `/status` 以確認。當 Mantle 處於作用中時，提供者行會顯示 `Amazon Bedrock (Mantle)`。455在 Claude Code 內執行 `/status` 以確認。當 Mantle 處於作用中時，提供者行會顯示 `Amazon Bedrock (Mantle)`。

456 456

470 與 Invoke API 並行執行 Mantle470 與 Invoke API 並行執行 Mantle

471</h3>471</h3>

472 472

473您在 Mantle 上可用的模型可能不包括您今天使用的每個模型。設定 `CLAUDE_CODE_USE_BEDROCK` 和 `CLAUDE_CODE_USE_MANTLE` 可讓 Claude Code 從同一工作階段呼叫兩個端點。符合 Mantle 格式的模型 ID 會路由到 Mantle，所有其他模型 ID 會進入 Bedrock Invoke API。473您在 Mantle 上可用的模型可能不包括您今天使用的每個模型。設定 `CLAUDE_CODE_USE_BEDROCK` 和 `CLAUDE_CODE_USE_MANTLE` 可讓 Claude Code 從同一工作階段呼叫兩個端點。符合 Mantle 格式的模型 ID 會路由到 Mantle，所有其他模型 ID 會進入 Amazon Bedrock Invoke API。

474 474

475```bash theme={null}475```bash theme={null}

476export CLAUDE_CODE_USE_BEDROCK=1476export CLAUDE_CODE_USE_BEDROCK=1

508這些變數特定於 Mantle 端點。請參閱[環境變數](/zh-TW/env-vars)以取得完整清單。508這些變數特定於 Mantle 端點。請參閱[環境變數](/zh-TW/env-vars)以取得完整清單。

509 509

510| 變數 | 目的 |510| 變數 | 目的 |

511| :-------------------------------------- | :--------------------------------- |511| :-------------------------------------- | :---------------------------------------- |

516 516

517<h2 id="troubleshooting">517<h2 id="troubleshooting">

518 故障排除518 故障排除

540 540

541* 將模型指定為[推論設定檔](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html) ID541* 將模型指定為[推論設定檔](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html) ID

542 542

543Claude Code 使用 Bedrock [Invoke API](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html)，不支援 Converse API。543Claude Code 使用 Amazon Bedrock [Invoke API](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html)，不支援 Converse API。

544 544

545<h3 id="zero-token-counts-in-/context">545<h3 id="zero-token-counts-in-/context">

546 /context 中的零權杖計數546 /context 中的零權杖計數

547</h3>547</h3>

548 548

549`/context` 命令透過將工具架構傳送至 Bedrock count-tokens API 來計算每個工具群組的權杖。在 Claude Code v2.1.196 之前的版本中，Bedrock 拒絕了該請求，因為架構包含其 count-tokens API 不接受的欄位，因此每個工具群組都顯示 0 個權杖。分解中的其他列（例如訊息和記憶體檔案）不受影響。549`/context` 命令透過將工具架構傳送至 Amazon Bedrock count-tokens API 來計算每個工具群組的權杖。在 Claude Code v2.1.196 之前的版本中，Amazon Bedrock 拒絕了該請求，因為架構包含其 count-tokens API 不接受的欄位，因此每個工具群組都顯示 0 個權杖。分解中的其他列（例如訊息和記憶體檔案）不受影響。

550 550

551更新至 v2.1.196 或更新版本。551更新至 v2.1.196 或更新版本。

552 552

558 558

559來自 Mantle 端點的 `403`（具有有效認證）表示您的 AWS 帳戶尚未被授予存取您要求的模型的權限。請聯絡您的 AWS 帳戶團隊以要求存取。559來自 Mantle 端點的 `403`（具有有效認證）表示您的 AWS 帳戶尚未被授予存取您要求的模型的權限。請聯絡您的 AWS 帳戶團隊以要求存取。

560 560

561命名模型 ID 的 `400` 表示該模型未在 Mantle 上提供。Mantle 有其自己的模型陣容，與標準 Bedrock 目錄分開，因此推論設定檔 ID（例如 `us.anthropic.claude-sonnet-4-6`）將無法運作。使用 Mantle 格式的 ID，或啟用[兩個端點](#run-mantle-alongside-the-invoke-api)，以便 Claude Code 將每個請求路由到模型可用的端點。561命名模型 ID 的 `400` 表示該模型未在 Mantle 上提供。Mantle 有其自己的模型陣容，與標準 Amazon Bedrock 目錄分開，因此推論設定檔 ID（例如 `us.anthropic.claude-sonnet-4-6`）將無法運作。使用 Mantle 格式的 ID，或啟用[兩個端點](#run-mantle-alongside-the-invoke-api)，以便 Claude Code 將每個請求路由到模型可用的端點。

562 562

563<h2 id="additional-resources">563<h2 id="additional-resources">

564 其他資源564 其他資源

565</h2>565</h2>

566 566

567* [Bedrock 文件](https://docs.aws.amazon.com/bedrock/)567* [Amazon Bedrock 文件](https://docs.aws.amazon.com/bedrock/)

568* [Bedrock 定價](https://aws.amazon.com/bedrock/pricing/)568* [Amazon Bedrock 定價](https://aws.amazon.com/bedrock/pricing/)

569* [Bedrock 推論設定檔](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html)569* [Amazon Bedrock 推論設定檔](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html)

570* [Bedrock 權杖燃盡和配額](https://docs.aws.amazon.com/bedrock/latest/userguide/quotas-token-burndown.html)570* [Amazon Bedrock 權杖燃盡和配額](https://docs.aws.amazon.com/bedrock/latest/userguide/quotas-token-burndown.html)

571* [Amazon Bedrock 上的 Claude Code：快速設定指南](https://community.aws/content/2tXkZKrZzlrlu0KfH8gST5Dkppq/claude-code-on-amazon-bedrock-quick-setup-guide)571* [Amazon Bedrock 上的 Claude Code：快速設定指南](https://community.aws/content/2tXkZKrZzlrlu0KfH8gST5Dkppq/claude-code-on-amazon-bedrock-quick-setup-guide)

572* [Claude Code 監控實施 (Bedrock)](https://github.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock/blob/main/assets/docs/MONITORING.md)572* [Claude Code 監控實施 (Amazon Bedrock)](https://github.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock/blob/main/assets/docs/MONITORING.md)

artifacts.md +1 −1

Details

192| :---- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |192| :---- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

193| 方案 | Pro、Max、Team 或 Enterprise。在 Pro 和 Max 方案上，成品僅供您私人使用，不適用管理員管理。在 Team 方案上，成品預設開啟。在 Enterprise 方案上，Owner 在 claude.ai 管理設定中[啟用它們](#manage-artifacts-for-your-organization)。 |193| 方案 | Pro、Max、Team 或 Enterprise。在 Pro 和 Max 方案上，成品僅供您私人使用，不適用管理員管理。在 Team 方案上，成品預設開啟。在 Enterprise 方案上，Owner 在 claude.ai 管理設定中[啟用它們](#manage-artifacts-for-your-organization)。 |

194| 驗證 | 使用 `/login` 登入 claude.ai。使用 API 金鑰、[閘道令牌](/zh-TW/llm-gateway)或雲端提供者認證的工作階段無法發佈。 |194| 驗證 | 使用 `/login` 登入 claude.ai。使用 API 金鑰、[閘道令牌](/zh-TW/llm-gateway)或雲端提供者認證的工作階段無法發佈。 |

195| 模型提供者 | Anthropic API。在 [Amazon Bedrock](/zh-TW/amazon-bedrock)、[Google Cloud Vertex AI](/zh-TW/google-vertex-ai) 或 [Microsoft Foundry](/zh-TW/microsoft-foundry) 上不可用。 |195| 模型提供者 | Anthropic API。在 [Amazon Bedrock](/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/zh-TW/google-vertex-ai) 或 [Microsoft Foundry](/zh-TW/microsoft-foundry) 上不可用。 |

196| 組織政策 | 客戶管理的加密金鑰 (CMEK)、HIPAA 和[零資料保留](/zh-TW/zero-data-retention)未為組織啟用。 |196| 組織政策 | 客戶管理的加密金鑰 (CMEK)、HIPAA 和[零資料保留](/zh-TW/zero-data-retention)未為組織啟用。 |

197| 表面 | Claude Code CLI，或 Claude 桌面應用程式版本 1.13576.0 或更新版本。在 [Agent SDK](/zh-TW/agent-sdk/overview)、GitHub Action 和 MCP 伺服器上下文中預設關閉，以及當設定 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/zh-TW/env-vars) 時。 |197| 表面 | Claude Code CLI，或 Claude 桌面應用程式版本 1.13576.0 或更新版本。在 [Agent SDK](/zh-TW/agent-sdk/overview)、GitHub Action 和 MCP 伺服器上下文中預設關閉，以及當設定 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/zh-TW/env-vars) 時。 |

198 198

authentication.md +20 −8

Details

6 6

7> 登入 Claude Code 並為個人、團隊和組織配置驗證。7> 登入 Claude Code 並為個人、團隊和組織配置驗證。

8 8

9Claude Code 支援多種驗證方法，具體取決於您的設定。個人使用者可以使用 Claude.ai 帳戶登入，而團隊可以使用 Claude for Teams 或 Enterprise、Claude Console 或雲端提供商（如 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry）。9Claude Code 支援多種驗證方法，具體取決於您的設定。個人使用者可以使用 Claude.ai 帳戶登入，而團隊可以使用 Claude for Teams 或 Enterprise、Claude Console 或雲端提供商（如 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry）。

10 10

11<h2 id="log-in-to-claude-code">11<h2 id="log-in-to-claude-code">

12 登入 Claude Code12 登入 Claude Code

23* **Claude Pro 或 Max 訂閱**：使用您的 Claude.ai 帳戶登入。在 [claude.com/pricing](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_pro_max) 訂閱。23* **Claude Pro 或 Max 訂閱**：使用您的 Claude.ai 帳戶登入。在 [claude.com/pricing](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_pro_max) 訂閱。

24* **Claude for Teams 或 Enterprise**：使用您的團隊管理員邀請您的 Claude.ai 帳戶登入。24* **Claude for Teams 或 Enterprise**：使用您的團隊管理員邀請您的 Claude.ai 帳戶登入。

25* **Claude Console**：使用您的 Console 認證登入。您的管理員必須先 [邀請您](#claude-console-authentication)。25* **Claude Console**：使用您的 Console 認證登入。您的管理員必須先 [邀請您](#claude-console-authentication)。

26* **雲端提供商**：如果您的組織使用 [Amazon Bedrock](/zh-TW/amazon-bedrock)、[Google Vertex AI](/zh-TW/google-vertex-ai) 或 [Microsoft Foundry](/zh-TW/microsoft-foundry)，請在執行 `claude` 之前設定所需的環境變數。不需要瀏覽器登入。26* **雲端提供商**：如果您的組織使用 [Amazon Bedrock](/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/zh-TW/google-vertex-ai) 或 [Microsoft Foundry](/zh-TW/microsoft-foundry)，請在執行 `claude` 之前設定所需的環境變數。不需要瀏覽器登入。

27* **雲端閘道**：如果您的組織執行自託管的 [Claude 應用程式閘道](/zh-TW/claude-apps-gateway)，請透過 `/login` 使用公司 SSO 登入。閘道簽發的權杖是工作階段的唯一認證。27* **雲端閘道**：如果您的組織執行自託管的 [Claude 應用程式閘道](/zh-TW/claude-apps-gateway)，請透過 `/login` 使用公司 SSO 登入。閘道簽發的權杖是工作階段的唯一認證。

28 28

29若要登出並重新驗證，請在 Claude Code 提示符處輸入 `/logout`。29若要登出並重新驗證，請在 Claude Code 提示符處輸入 `/logout`。

40* [Claude Console](#claude-console-authentication)40* [Claude Console](#claude-console-authentication)

41* [Claude apps gateway](/zh-TW/claude-apps-gateway)，一個自託管閘道，使用您的 IdP 簽署開發人員，並將推論路由到您配置的雲端提供商41* [Claude apps gateway](/zh-TW/claude-apps-gateway)，一個自託管閘道，使用您的 IdP 簽署開發人員，並將推論路由到您配置的雲端提供商

42* [Amazon Bedrock](/zh-TW/amazon-bedrock)42* [Amazon Bedrock](/zh-TW/amazon-bedrock)

~~43* [Google Vertex AI](/zh-TW/google-vertex-ai)~~43* [Google Cloud's Agent Platform](/zh-TW/google-vertex-ai)

44* [Microsoft Foundry](/zh-TW/microsoft-foundry)44* [Microsoft Foundry](/zh-TW/microsoft-foundry)

45 45

46<h3 id="claude-for-teams-or-enterprise">46<h3 id="claude-for-teams-or-enterprise">

105 雲端提供商驗證105 雲端提供商驗證

106</h3>106</h3>

107 107

108對於使用 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 的團隊：108對於使用 Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry 的團隊：

109 109

110<Steps>110<Steps>

111 <Step title="遵循提供商設定">111 <Step title="遵循提供商設定">

112 遵循 [Bedrock 文件](/zh-TW/amazon-bedrock)、[Vertex 文件](/zh-TW/google-vertex-ai) 或 [Microsoft Foundry 文件](/zh-TW/microsoft-foundry)。112 遵循 [Amazon Bedrock 文件](/zh-TW/amazon-bedrock)、[Google Cloud's Agent Platform 文件](/zh-TW/google-vertex-ai) 或 [Microsoft Foundry 文件](/zh-TW/microsoft-foundry)。

113 </Step>113 </Step>

114 114

115 <Step title="分發配置">115 <Step title="分發配置">

140 140

141`apiKeyHelper`、`ANTHROPIC_API_KEY` 和 `ANTHROPIC_AUTH_TOKEN` 適用於 CLI 和包裝它的介面，包括 VS Code 擴充功能、Agent SDK 和 GitHub Actions。Claude Desktop 和雲端工作階段不會呼叫 `apiKeyHelper` 或讀取這些環境變數：它們使用 OAuth，除了執行[組織分散式第三方推論配置](/zh-TW/llm-gateway-connect#desktop-app)的桌面工作階段外，該工作階段使用該配置的認證進行驗證。141`apiKeyHelper`、`ANTHROPIC_API_KEY` 和 `ANTHROPIC_AUTH_TOKEN` 適用於 CLI 和包裝它的介面，包括 VS Code 擴充功能、Agent SDK 和 GitHub Actions。Claude Desktop 和雲端工作階段不會呼叫 `apiKeyHelper` 或讀取這些環境變數：它們使用 OAuth，除了執行[組織分散式第三方推論配置](/zh-TW/llm-gateway-connect#desktop-app)的桌面工作階段外，該工作階段使用該配置的認證進行驗證。

142 142

143<h3 id="renew-an-expiring-login">

144 續約即將過期的登入

145</h3>

146

147當您使用 `/login` 建立的登入在五天內即將過期時，Claude Code 會在啟動時顯示警告：`您的登入將在 3 天後過期 · 執行 /login 以續約`。需要 Claude Code v2.1.203 或更新版本。

148

149執行 `/login` 以續約。警告僅供參考，永遠不會阻止請求：驗證會持續運作，直到登入實際過期。登入生命週期本身保持不變；提前警告是 v2.1.203 新增的功能。

150

151警告僅在 claude.ai 或 Claude Console 登入是有效認證時出現，而不是在雲端提供商、`ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 提供認證時出現。

152

153對於執行無人值守的工作階段，提前續約最為重要。在[代理檢視中的背景工作階段](/zh-TW/agent-view)或[遠端控制](/zh-TW/remote-control)工作階段一旦超過登入生命週期，一旦認證過期就會停止進行，在您再次登入之前無法恢復。

154

143<h3 id="authentication-precedence">155<h3 id="authentication-precedence">

144 驗證優先順序156 驗證優先順序

145</h3>157</h3>

146 158

147當存在多個認證時，Claude Code 按此順序選擇一個：159當存在多個認證時，Claude Code 按此順序選擇一個：

148 160

1491. 雲端提供商認證，當設定了 `CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_VERTEX` 或 `CLAUDE_CODE_USE_FOUNDRY` 時。請參閱 [第三方整合](/zh-TW/third-party-integrations) 以取得設定。1611. 雲端提供商認證，當設定了 `CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_VERTEX` 或 `CLAUDE_CODE_USE_FOUNDRY` 時。請參閱[第三方整合](/zh-TW/third-party-integrations)以取得設定。

1502. `ANTHROPIC_AUTH_TOKEN` 環境變數。作為 `Authorization: Bearer` 標頭傳送。當透過 [LLM 閘道或代理](/zh-TW/llm-gateway) 路由時使用此選項，該閘道或代理使用持有人令牌而不是 Anthropic API 金鑰進行驗證。1622. `ANTHROPIC_AUTH_TOKEN` 環境變數。作為 `Authorization: Bearer` 標頭傳送。當透過[LLM 閘道或代理](/zh-TW/llm-gateway)路由時使用此選項，該閘道或代理使用持有人令牌而不是 Anthropic API 金鑰進行驗證。

1513. `ANTHROPIC_API_KEY` 環境變數。作為 `X-Api-Key` 標頭傳送。用於直接 Anthropic API 存取，使用來自 [Claude Console](https://platform.claude.com) 的金鑰。在互動模式下，系統會提示您一次以核准或拒絕金鑰，您的選擇會被記住。若要稍後變更，請使用 `/config` 中的「使用自訂 API 金鑰」切換。在非互動模式 (`-p`) 中，當金鑰存在時始終使用該金鑰。1633. `ANTHROPIC_API_KEY` 環境變數。作為 `X-Api-Key` 標頭傳送。用於直接 Anthropic API 存取，使用來自 [Claude Console](https://platform.claude.com) 的金鑰。在互動模式下，系統會提示您一次以核准或拒絕金鑰，您的選擇會被記住。若要稍後變更，請使用 `/config` 中的「使用自訂 API 金鑰」切換。在非互動模式 (`-p`) 中，當金鑰存在時始終使用該金鑰。

1524. [`apiKeyHelper`](/zh-TW/settings#available-settings) 指令碼輸出。用於動態或輪換認證，例如從保管庫擷取的短期令牌。1644. [`apiKeyHelper`](/zh-TW/settings#available-settings) 指令碼輸出。用於動態或輪換認證，例如從保管庫擷取的短期令牌。

1535. `CLAUDE_CODE_OAUTH_TOKEN` 環境變數。由 [`claude setup-token`](#generate-a-long-lived-token) 產生的長期 OAuth 令牌。用於 CI 管道和指令碼，其中瀏覽器登入不可用。1655. `CLAUDE_CODE_OAUTH_TOKEN` 環境變數。由 [`claude setup-token`](#generate-a-long-lived-token) 產生的長期 OAuth 令牌。用於 CI 管道和指令碼，其中瀏覽器登入不可用。

1546. 來自 `/login` 的訂閱 OAuth 認證。這是 Claude Pro、Max、Team 和 Enterprise 使用者的預設值。1666. 來自 `/login` 的訂閱 OAuth 認證。這是 Claude Pro、Max、Team 和 Enterprise 使用者的預設值。

155 167

156已簽署的 [Claude apps gateway](/zh-TW/claude-apps-gateway) 工作階段位於此清單之外：它是一個提供商選擇，如 Bedrock 或 Vertex，並且優先於它們。當閘道工作階段存在時，CLI 使用閘道令牌進行驗證，即使設定了 `CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_VERTEX` 或 `CLAUDE_CODE_USE_FOUNDRY`，上面的持有人令牌、API 金鑰和 `apiKeyHelper` 項目也不會被使用。168已簽署的 [Claude apps gateway](/zh-TW/claude-apps-gateway) 工作階段位於此清單之外：它是一個提供商選擇，如 Amazon Bedrock 或 Google Cloud 的 Agent Platform，並且優先於它們。當閘道工作階段存在時，CLI 使用閘道令牌進行驗證，即使設定了 `CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_VERTEX` 或 `CLAUDE_CODE_USE_FOUNDRY`，上面的持有人令牌、API 金鑰和 `apiKeyHelper` 項目也不會被使用。

157 169

158如果您有有效的 Claude 訂閱，但您的環境中也設定了 `ANTHROPIC_API_KEY`，則 API 金鑰在核准後優先。如果金鑰屬於已停用或過期的組織，這可能會導致驗證失敗。執行 `unset ANTHROPIC_API_KEY` 以回退到您的訂閱，並檢查 `/status` 以確認哪種方法處於活動狀態。170如果您有有效的 Claude 訂閱，但您的環境中也設定了 `ANTHROPIC_API_KEY`，則 API 金鑰在核准後優先。如果金鑰屬於已停用或過期的組織，這可能會導致驗證失敗。執行 `unset ANTHROPIC_API_KEY` 以回退到您的訂閱，並檢查 `/status` 以確認哪種方法處於活動狀態。

159 171

auto-mode-config.md +3 −3

Details

9[自動模式](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)讓 Claude Code 無需常規權限提示即可執行，方法是透過分類器路由工具呼叫，該分類器會阻止任何不可逆、破壞性或針對您環境外部的操作。拒絕和明確詢問規則會在分類器之前進行評估，仍然會阻止或提示。使用 `autoMode` 設定區塊告訴該分類器您的組織信任哪些儲存庫、儲存桶和網域，以便它停止阻止常規內部操作。9[自動模式](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)讓 Claude Code 無需常規權限提示即可執行，方法是透過分類器路由工具呼叫，該分類器會阻止任何不可逆、破壞性或針對您環境外部的操作。拒絕和明確詢問規則會在分類器之前進行評估，仍然會阻止或提示。使用 `autoMode` 設定區塊告訴該分類器您的組織信任哪些儲存庫、儲存桶和網域，以便它停止阻止常規內部操作。

10 10

11<Note>11<Note>

12 自動模式可在 Anthropic API 上供所有使用者使用。在 Amazon Bedrock、Google Cloud Vertex AI、Microsoft Foundry 和已登入的 [Claude apps gateway](/zh-TW/claude-apps-gateway) 工作階段上，您必須先[設定 `CLAUDE_CODE_ENABLE_AUTO_MODE`](/zh-TW/permission-modes#enable-auto-mode-on-bedrock-vertex-ai-or-foundry)。如果 Claude Code 報告您的帳戶無法使用自動模式，請檢查[完整要求](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)，其中也涵蓋支援的模型和 Team 與 Enterprise 方案上的擁有者啟用。12 自動模式可在 Anthropic API 上供所有使用者使用。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和已登入的 [Claude apps gateway](/zh-TW/claude-apps-gateway) 工作階段上，您必須先[設定 `CLAUDE_CODE_ENABLE_AUTO_MODE`](/zh-TW/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)。如果 Claude Code 報告您的帳戶無法使用自動模式，請檢查[完整要求](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)，其中也涵蓋支援的模型和 Team 與 Enterprise 方案上的擁有者啟用。

13</Note>13</Note>

14 14

15根據預設，分類器只信任工作目錄和目前儲存庫的已設定遠端。推送到您公司的原始碼控制組織或寫入團隊雲端儲存桶等操作會被阻止，直到您將它們新增到 `autoMode.environment`。15根據預設，分類器只信任工作目錄和目前儲存庫的已設定遠端。推送到您公司的原始碼控制組織或寫入團隊雲端儲存桶等操作會被阻止，直到您將它們新增到 `autoMode.environment`。

60 * **組織**60 * **組織**

61 * **Claude Code 的主要用途**：預設為軟體開發61 * **Claude Code 的主要用途**：預設為軟體開發

62 * **雲端提供者**62 * **雲端提供者**

~~63 * **儲存庫可見性**：除非其遠端主機和名稱另有指示，否則儲存庫被假定為私人~~63 * **儲存庫可見性**：除非其遠端主機和名稱另有指示，{/* min-version: 2.1.200 */}或工作階段中較早的可見性檢查分類器讀取顯示它是公開的。分類器讀取您的訊息和 Claude 執行的命令，而不是它們的輸出，因此證據必須是它能讀取的東西，例如您自己的訊息將儲存庫命名為公開；單獨執行 `gh repo view` 的輸出無法到達它。成績單證據檢查需要 Claude Code v2.1.200 或更新版本

64 * **內部共享 / 程式碼片段託管**：公開貼上和 gist 服務被視為在信任邊界外，直到您命名一個64 * **內部共享 / 程式碼片段託管**：公開貼上和 gist 服務被視為在信任邊界外，直到您命名一個

65 * **組織特定的 CLI**65 * **組織特定的 CLI**

66 * **祕密管理**66 * **祕密管理**

69 * **網路態勢**69 * **網路態勢**

70 * **受保護的部署命名空間 / 環境**：回退到敏感遠端目標啟發式方法，直到您命名它們70 * **受保護的部署命名空間 / 環境**：回退到敏感遠端目標啟發式方法，直到您命名它們

71 * **資料保留 / 解密**71 * **資料保留 / 解密**

72* **信任槽位**：命名分類器視為在您邊界內的內容。槽位是受信任儲存庫、原始碼控制、受信任內部網域、受信任雲端儲存桶、關鍵內部服務和內部套件登錄。儲存庫和原始碼控制項目預設為工作儲存庫及其設定的遠端。所有其他信任槽位預設為 `None configured`，因此在您新增之前沒有其他內容是受信任的。72* **信任槽位**：命名分類器視為在您邊界內的內容。槽位是受信任儲存庫、原始碼控制、受信任內部網域、受信任雲端儲存桶、關鍵內部服務和內部套件登錄。儲存庫和原始碼控制項目預設為工作儲存庫及其設定的遠端。所有其他信任槽位預設為 `None configured`，因此在您新增之前沒有其他內容是受信任的。{/* min-version: 2.1.203 */}儲存庫的可見性僅限於機密材料：私人儲存庫是機密材料的可接受目的地，但將儲存庫設為私人永遠不會清除祕密或個人或受信任的資料到其中，分類器將從工作儲存庫外部移植、重新指向或首次讀取的內容視為不是該儲存庫自己的工作。此範圍設定需要 Claude Code v2.1.203 或更新版本。

73* **敏感度槽位**：命名保護規則視為高風險的內容。槽位是敏感資料位置與受眾、敏感遠端目標和受保護的 IaC 範圍。每個預設為廣泛的啟發式方法，例如將任何名稱包含 `prod` 或 `production` 的主機或命名空間視為敏感遠端目標，因此保護規則在您設定任何內容之前就處於活動狀態。在敏感度槽位中命名具體目標會使這些規則應用於命名的目標而不是啟發式方法。73* **敏感度槽位**：命名保護規則視為高風險的內容。槽位是敏感資料位置與受眾、敏感遠端目標和受保護的 IaC 範圍。每個預設為廣泛的啟發式方法，例如將任何名稱包含 `prod` 或 `production` 的主機或命名空間視為敏感遠端目標，因此保護規則在您設定任何內容之前就處於活動狀態。在敏感度槽位中命名具體目標會使這些規則應用於命名的目標而不是啟發式方法。

74 74

75要在預設值旁邊新增您自己的項目，請在陣列中包含字面字串 `"$defaults"`。預設項目會在該位置被插入，因此您的自訂項目可以在它們之前或之後。75要在預設值旁邊新增您自己的項目，請在陣列中包含字面字串 `"$defaults"`。預設項目會在該位置被插入，因此您的自訂項目可以在它們之前或之後。

channels.md +1 −1

Details

7> 使用 channels 從 MCP 伺服器將訊息、警報和 webhooks 推送到您的 Claude Code 工作階段。轉發 CI 結果、聊天訊息和監控事件，讓 Claude 在您不在時做出反應。7> 使用 channels 從 MCP 伺服器將訊息、警報和 webhooks 推送到您的 Claude Code 工作階段。轉發 CI 結果、聊天訊息和監控事件，讓 Claude 在您不在時做出反應。

8 8

9<Note>9<Note>

10 Channels 處於[研究預覽](#research-preview)階段，需要 Claude Code v2.1.80 或更新版本。它們需要透過 claude.ai 或 Console API 金鑰進行 Anthropic 驗證，且在 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 上不可用。Team 和 Enterprise 組織必須[明確啟用它們](#enterprise-controls)。10 Channels 處於[研究預覽](#research-preview)階段，需要 Claude Code v2.1.80 或更新版本。它們需要透過 claude.ai 或 Console API 金鑰進行 Anthropic 驗證，且在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用。Team 和 Enterprise 組織必須[明確啟用它們](#enterprise-controls)。

11</Note>11</Note>

12 12

13Channel 是一個 MCP 伺服器，可將事件推送到您執行中的 Claude Code 工作階段，讓 Claude 能對您不在終端時發生的事情做出反應。Channels 可以是雙向的：Claude 讀取事件並通過同一 channel 回覆，就像聊天橋接一樣。事件只在工作階段開啟時到達，因此對於始終開啟的設定，您可以在背景程序或持久終端中執行 Claude。13Channel 是一個 MCP 伺服器，可將事件推送到您執行中的 Claude Code 工作階段，讓 Claude 能對您不在終端時發生的事情做出反應。Channels 可以是雙向的：Claude 讀取事件並通過同一 channel 回覆，就像聊天橋接一樣。事件只在工作階段開啟時到達，因此對於始終開啟的設定，您可以在背景程序或持久終端中執行 Claude。

channels-reference.md +2 −2

Details

36* **聊天平台**（Telegram、Discord）：您的外掛程式在本機執行並輪詢平台的 API 以取得新訊息。當有人傳送 DM 給您的機器人時，外掛程式會接收訊息並將其轉發給 Claude。無需公開 URL。36* **聊天平台**（Telegram、Discord）：您的外掛程式在本機執行並輪詢平台的 API 以取得新訊息。當有人傳送 DM 給您的機器人時，外掛程式會接收訊息並將其轉發給 Claude。無需公開 URL。

37* **Webhooks**（CI、監控）：您的伺服器在本機 HTTP 連接埠上監聽。外部系統 POST 到該連接埠，您的伺服器將承載推送給 Claude。37* **Webhooks**（CI、監控）：您的伺服器在本機 HTTP 連接埠上監聽。外部系統 POST 到該連接埠，您的伺服器將承載推送給 Claude。

38 38

39<img src="https://mintlify.s3.us-west-1.amazonaws.com/claude-code/zh-TW/images/channel-architecture.svg" alt="架構圖，顯示外部系統連接到您的本機 channel 伺服器，該伺服器透過 stdio 與 Claude Code 通訊" />39<img src="https://mintcdn.com/claude-code/9FG0ZKj9uKYiHmbi/images/channel-architecture.svg?fit=max&auto=format&n=9FG0ZKj9uKYiHmbi&q=85&s=9a037b7da80184ae49015c0256b21a1f" alt="架構圖，顯示外部系統連接到您的本機 channel 伺服器，該伺服器透過 stdio 與 Claude Code 通訊" width="600" height="220" data-path="images/channel-architecture.svg" />

40 40

41<h2 id="what-you-need">41<h2 id="what-you-need">

42 您需要什麼42 您需要什麼

474 474

475本機終端機對話框在所有這一切中保持開啟。如果終端機上的某人在遠端判決到達之前回答，該答案會改為應用，待處理的遠端要求會被捨棄。475本機終端機對話框在所有這一切中保持開啟。如果終端機上的某人在遠端判決到達之前回答，該答案會改為應用，待處理的遠端要求會被捨棄。

476 476

477<img src="https://mintlify.s3.us-west-1.amazonaws.com/claude-code/zh-TW/images/channel-permission-relay.svg" alt="序列圖：Claude Code 傳送 permission_request 通知到 channel 伺服器，伺服器格式化並傳送提示到聊天應用，人類回覆判決，伺服器將該回覆解析為權限通知回到 Claude Code" />477<img src="https://mintcdn.com/claude-code/9FG0ZKj9uKYiHmbi/images/channel-permission-relay.svg?fit=max&auto=format&n=9FG0ZKj9uKYiHmbi&q=85&s=97d57f128f0da55f105ab1e3a7e10240" alt="序列圖：Claude Code 傳送 permission_request 通知到 channel 伺服器，伺服器格式化並傳送提示到聊天應用，人類回覆判決，伺服器將該回覆解析為權限通知回到 Claude Code" width="600" height="230" data-path="images/channel-permission-relay.svg" />

478 478

479<h3 id="permission-request-fields">479<h3 id="permission-request-fields">

480 權限要求欄位480 權限要求欄位

chrome.md +1 −1

Details

40* 直接 Anthropic 計畫（Pro、Max、Team 或 Enterprise）40* 直接 Anthropic 計畫（Pro、Max、Team 或 Enterprise）

41 41

42<Note>42<Note>

43 Chrome 整合不適用於 Amazon Bedrock、Google Cloud Vertex AI 或 Microsoft Foundry 等第三方提供商。如果您只透過第三方提供商存取 Claude，則需要單獨的 claude.ai 帳戶才能使用此功能。43 Chrome 整合不適用於 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 等第三方提供商。如果您只透過第三方提供商存取 Claude，則需要單獨的 claude.ai 帳戶才能使用此功能。

44</Note>44</Note>

45 45

46<h2 id="get-started-in-the-cli">46<h2 id="get-started-in-the-cli">

claude-apps-gateway-config.md +6 −4

Details

4 4

5# Claude 應用程式閘道設定5# Claude 應用程式閘道設定

6 6

7> 每個 gateway.yaml 選項的參考資料：監聽器和 TLS、OIDC、工作階段、Postgres 存放區、Bedrock/Claude Platform on AWS/Agent Platform/Foundry 上游、模型路由、受管原則和遙測。7> 每個 gateway.yaml 選項的參考資料：監聽器和 TLS、OIDC、工作階段、Postgres 存放區、Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上游、模型路由、受管原則和遙測。

8 8

9Claude 應用程式閘道部署由一個 YAML 檔案設定，按慣例稱為 `gateway.yaml`。該檔案定義閘道執行的所有操作：它在哪裡監聽、開發人員如何登入、推論去往何處，以及哪些原則和遙測適用。本頁是該檔案中每個選項的參考資料。若要撰寫您的第一個，請從[快速入門](/zh-TW/claude-apps-gateway#quickstart)開始，它會建立最小的工作設定並執行它；一旦您有了滿意的設定，[部署指南](/zh-TW/claude-apps-gateway-deploy)涵蓋將其容器化並在 Kubernetes、Cloud Run 或您自己的平台上託管。9Claude 應用程式閘道部署由一個 YAML 檔案設定，按慣例稱為 `gateway.yaml`。該檔案定義閘道執行的所有操作：它在哪裡監聽、開發人員如何登入、推論去往何處，以及哪些原則和遙測適用。本頁是該檔案中每個選項的參考資料。若要撰寫您的第一個，請從[快速入門](/zh-TW/claude-apps-gateway#quickstart)開始，它會建立最小的工作設定並執行它；一旦您有了滿意的設定，[部署指南](/zh-TW/claude-apps-gateway-deploy)涵蓋將其容器化並在 Kubernetes、Cloud Run 或您自己的平台上託管。

10 10

24* [`oidc`](#oidc)：您的身分識別提供者 (IdP)，包括簽發者、用戶端、宣告對應和誰可以登入24* [`oidc`](#oidc)：您的身分識別提供者 (IdP)，包括簽發者、用戶端、宣告對應和誰可以登入

25* [`session`](#session)：閘道鑄造的持有人令牌，包括祕密和生命週期25* [`session`](#session)：閘道鑄造的持有人令牌，包括祕密和生命週期

26* [`store`](#store)：PostgreSQL，用於裝置授權和速率限制計數器26* [`store`](#store)：PostgreSQL，用於裝置授權和速率限制計數器

~~27* [`upstreams`](#upstreams)：推論去往何處，無論是 Anthropic、Bedrock、Claude Platform on AWS、Agent Platform 還是 Foundry~~27* [`upstreams`](#upstreams)：推論去往何處，無論是 Anthropic、Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 或 Microsoft Foundry

28 28

29**選用部分：**29**選用部分：**

30 30

125 125

126`upstreams` 是一個有序清單。閘道將推論轉發到解析所請求模型的第一個上游。在 `5xx`、`429`、`401`、`403`、`404` 或逾時時，它會故障轉移到下一個；其他 `4xx` 不會，因為這些錯誤可歸因於請求而不是上游。`401` 或 `403` 表示閘道自己的認證對該上游失敗，`404` 表示該上游不服務所請求的模型，因此清單中稍後的上游仍然可以。126`upstreams` 是一個有序清單。閘道將推論轉發到解析所請求模型的第一個上游。在 `5xx`、`429`、`401`、`403`、`404` 或逾時時，它會故障轉移到下一個；其他 `4xx` 不會，因為這些錯誤可歸因於請求而不是上游。`401` 或 `403` 表示閘道自己的認證對該上游失敗，`404` 表示該上游不服務所請求的模型，因此清單中稍後的上游仍然可以。

127 127

128故障轉移於 `404` 需要閘道 v2.1.198 或更新版本。較早的版本即使清單中稍後的上游服務該模型，也會將第一個 `404` 返回給用戶端。

129

128相同提供者的多個上游必須設定不同的 `name:`。130相同提供者的多個上游必須設定不同的 `name:`。

129 131

130Bedrock、Claude Platform on AWS、Agent Platform 和 Foundry 用戶端在啟動時建立一次，其 SDK 在內部重新整理認證，因此輪換雲認證不需要重新啟動。靜態 Anthropic API 金鑰和持有人在啟動時讀取；請參閱 [Anthropic API](#anthropic-api)。132Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 和 Microsoft Foundry 用戶端在啟動時建立一次，其 SDK 在內部重新整理認證，因此輪換雲認證不需要重新啟動。靜態 Anthropic API 金鑰和持有人在啟動時讀取；請參閱 [Anthropic API](#anthropic-api)。

131 133

132<h4 id="anthropic-api">134<h4 id="anthropic-api">

133 Anthropic API135 Anthropic API

401 `models`403 `models`

402</h3>404</h3>

403 405

404`models` 區塊是選用的管理員策劃模型清單，在 `/v1/models` 提供並用於轉換每個上游的模型 ID。對於非美國 Bedrock 地區、Bedrock 佈建輸送量 ARN 和 Foundry 部署名稱是必需的。406`models` 區塊是選用的管理員策劃模型清單，在 `/v1/models` 提供並用於轉換每個上游的模型 ID。對於非美國 Amazon Bedrock 地區、Amazon Bedrock 佈建輸送量 ARN 和 Microsoft Foundry 部署名稱是必需的。

405 407

406```yaml theme={null}408```yaml theme={null}

407auto_include_builtin_models: true # false：僅公開下面的清單409auto_include_builtin_models: true # false：僅公開下面的清單

claude-apps-gateway-deploy.md +1 −1

Details

284| `/oauth/callback` 顯示「Sign-in could not be completed」 | 電子郵件網域被拒絕、id\_token 驗證失敗，或 `email_verified` 明確為 `false`，閘道始終拒絕，沒有覆蓋 | 檢查 `allowed_email_domains` 以及 IdP 是否傳回驗證的 `email` 聲明。對於 `email_verified: false`，修復 IdP 端驗證。如果您的 IdP 在不同的聲明名稱下發出電子郵件，設定 `oidc.email_claim`。 |284| `/oauth/callback` 顯示「Sign-in could not be completed」 | 電子郵件網域被拒絕、id\_token 驗證失敗，或 `email_verified` 明確為 `false`，閘道始終拒絕，沒有覆蓋 | 檢查 `allowed_email_domains` 以及 IdP 是否傳回驗證的 `email` 聲明。對於 `email_verified: false`，修復 IdP 端驗證。如果您的 IdP 在不同的聲明名稱下發出電子郵件，設定 `oidc.email_claim`。 |

285| 日誌：`token exchange failed: id_token missing email claim` | IdP 預設不在 id\_token 中包含 `email`。此拒絕僅在設定 `allowed_email_domains` 時觸發；沒有它，缺失的電子郵件鑄造沒有電子郵件的會話 | 配置 IdP 在 id\_token 中發出 `email`。Okta：將 `email` 新增到自訂授權伺服器的 ID 令牌聲明。Entra：在應用程式註冊上新增 `email` 作為可選聲明。PingFederate：啟用發出 `email` 的 OpenID Connect 原則。如果 IdP 從 userinfo 端點提供 `email` 但不會在 id\_token 中包含它，例如 Okta 組織授權伺服器，設定 `oidc.userinfo_fallback: true`。 |285| 日誌：`token exchange failed: id_token missing email claim` | IdP 預設不在 id\_token 中包含 `email`。此拒絕僅在設定 `allowed_email_domains` 時觸發；沒有它，缺失的電子郵件鑄造沒有電子郵件的會話 | 配置 IdP 在 id\_token 中發出 `email`。Okta：將 `email` 新增到自訂授權伺服器的 ID 令牌聲明。Entra：在應用程式註冊上新增 `email` 作為可選聲明。PingFederate：啟用發出 `email` 的 OpenID Connect 原則。如果 IdP 從 userinfo 端點提供 `email` 但不會在 id\_token 中包含它，例如 Okta 組織授權伺服器，設定 `oidc.userinfo_fallback: true`。 |

286| 每個 Bedrock 請求傳回 502；日誌顯示 `Could not load credentials from any providers` | 在 EC2 上，IMDSv2 的預設躍點限制 1 阻止來自容器內的實例中繼資料請求。啟動和 `/readyz` 仍然通過，因為 AWS SDK 在第一個請求時解析實例認證，而不是在用戶端構造時 | 使用 `aws ec2 modify-instance-metadata-options --instance-id <id> --http-put-response-hop-limit 2` 提高躍點限制，或在啟動範本中設定它。變更適用於實例上的每個容器。優先選擇 ECS 任務角色（如果可用），它從 ECS 容器認證端點讀取認證，完全避免變更，或在專用閘道實例上應用變更以限制暴露。 |286| 每個 Amazon Bedrock 請求傳回 502；日誌顯示 `Could not load credentials from any providers` | 在 EC2 上，IMDSv2 的預設躍點限制 1 阻止來自容器內的實例中繼資料請求。啟動和 `/readyz` 仍然通過，因為 AWS SDK 在第一個請求時解析實例認證，而不是在用戶端構造時 | 使用 `aws ec2 modify-instance-metadata-options --instance-id <id> --http-put-response-hop-limit 2` 提高躍點限制，或在啟動範本中設定它。變更適用於實例上的每個容器。優先選擇 ECS 任務角色（如果可用），它從 ECS 容器認證端點讀取認證，完全避免變更，或在專用閘道實例上應用變更以限制暴露。 |

claude-apps-gateway-on-gcp.md +5 −5

Details

17</h2>17</h2>

18 18

19<Frame>19<Frame>

20 <img src="https://mintcdn.com/claude-code/-uq-4JE0W_JO5Er5/images/claude-gateway-gcp-architecture.svg?fit=max&auto=format&n=-uq-4JE0W_JO5Er5&q=85&s=cb705151c69128ac0da235852d5600ab" alt="Google Cloud 上 Claude 應用程式閘道的圖表：Claude Code 用戶端透過 HTTPS 連接到閘道（Cloud Run 或 GKE），閘道在 VPC 內執行，旁邊有一個私有 IP Cloud SQL 資料庫用於工作階段狀態。閘道透過 OIDC 針對 Google Workspace 簽署使用者，從 Secret Manager 讀取配置和祕密，將模型請求轉發到 Agent Platform，並在部署時從 Artifact Registry 提取其映像。" width="760" height="400" data-path="images/claude-gateway-gcp-architecture.svg" />20 <img src="https://mintcdn.com/claude-code/-uq-4JE0W_JO5Er5/images/claude-gateway-gcp-architecture.svg?fit=max&auto=format&n=-uq-4JE0W_JO5Er5&q=85&s=cb705151c69128ac0da235852d5600ab" alt="Google Cloud 上 Claude 應用程式閘道的圖表：Claude Code 用戶端透過 HTTPS 連接到閘道（Cloud Run 或 GKE），閘道在 VPC 內執行，旁邊有一個私有 IP Cloud SQL 資料庫用於工作階段狀態。閘道透過 OIDC 針對 Google Workspace 簽署使用者，從 Secret Manager 讀取配置和祕密，將模型請求轉發到 Google Cloud 的 Agent Platform，並在部署時從 Artifact Registry 提取其映像。" width="760" height="400" data-path="images/claude-gateway-gcp-architecture.svg" />

21</Frame>21</Frame>

22 22

23參考配置會配置：23參考配置會配置：

80 </Step>80 </Step>

81 81

82 <Step title="建立服務帳戶並授予 IAM">82 <Step title="建立服務帳戶並授予 IAM">

~~83 閘道以專用服務帳戶執行，具有呼叫 Agent Platform 的權限。它透過 VPC 使用密碼使用者到達 Cloud SQL，因此不需要 Cloud SQL IAM 角色：~~83 閘道以專用服務帳戶執行，具有呼叫 Google Cloud 的 Agent Platform 的權限。它透過 VPC 使用密碼使用者到達 Cloud SQL，因此不需要 Cloud SQL IAM 角色：

84 84

85 ```bash theme={null}85 ```bash theme={null}

86 gcloud iam service-accounts create claude-gateway --display-name="Claude apps gateway"86 gcloud iam service-accounts create claude-gateway --display-name="Claude apps gateway"

141 </Step>141 </Step>

142 142

143 <Step title="撰寫 gateway.yaml">143 <Step title="撰寫 gateway.yaml">

144 `upstreams` 區塊使用 `auth: {}` 指向 Agent Platform，因此閘道透過執行時服務帳戶的應用程式預設認證進行驗證。如需每個欄位，請參閱[配置參考](/zh-TW/claude-apps-gateway-config)。144 `upstreams` 區塊使用 `auth: {}` 指向 Google Cloud 的 Agent Platform，因此閘道透過執行時服務帳戶的應用程式預設認證進行驗證。如需每個欄位，請參閱[配置參考](/zh-TW/claude-apps-gateway-config)。

145 145

146 兩個 `listen` 欄位取決於什麼在閘道前面：146 兩個 `listen` 欄位取決於什麼在閘道前面：

147 147

226 --no-invoker-iam-check226 --no-invoker-iam-check

227 ```227 ```

228 228

229 直接 VPC 出口（透過 `--network`、`--subnet` 和 `--vpc-egress=private-ranges-only`）讓服務直接到達 Cloud SQL 私有 IP。對 Agent Platform 端點和 `accounts.google.com` 的公用出口直接進入網際網路，而不是透過 VPC，因此不需要 Cloud NAT。229 直接 VPC 出口（透過 `--network`、`--subnet` 和 `--vpc-egress=private-ranges-only`）讓服務直接到達 Cloud SQL 私有 IP。對 Google Cloud 的 Agent Platform 端點和 `accounts.google.com` 的公用出口直接進入網際網路，而不是透過 VPC，因此不需要 Cloud NAT。

230 230

231 呼叫者 IAM 檢查必須開啟或停用。閘道執行自己的 OIDC，其用戶端不攜帶 GCP 令牌，因此 Cloud Run 的呼叫者檢查必須允許未驗證的請求。閘道的 OIDC 登入在請求到達容器後驗證請求，使用 `allowed_email_domains` 限制哪些網域可以登入。231 呼叫者 IAM 檢查必須開啟或停用。閘道執行自己的 OIDC，其用戶端不攜帶 GCP 令牌，因此 Cloud Run 的呼叫者檢查必須允許未驗證的請求。閘道的 OIDC 登入在請求到達容器後驗證請求，使用 `allowed_email_domains` 限制哪些網域可以登入。

232 232

318| `--no-invoker-iam-check` 被拒絕，出現 `invoker_iam_disabled is not currently available` | 被 `constraints/run.managed.requireInvokerIam` 阻止 | 使用 `--allow-unauthenticated`。如果透過 `constraints/iam.allowedPolicyMemberDomains` 的網域受限共用也阻止了它，請使用 GKE 路徑，它在網路層公開閘道，無需 `allUsers` 繫結。 |318| `--no-invoker-iam-check` 被拒絕，出現 `invoker_iam_disabled is not currently available` | 被 `constraints/run.managed.requireInvokerIam` 阻止 | 使用 `--allow-unauthenticated`。如果透過 `constraints/iam.allowedPolicyMemberDomains` 的網域受限共用也阻止了它，請使用 GKE 路徑，它在網路層公開閘道，無需 `allUsers` 繫結。 |

320| 閘道啟動在 Cloud Run 上以 Postgres 連線逾時錯誤退出 | 服務未附加到 VPC，或 Cloud SQL 在該 VPC 上沒有私有 IP；儲存在 5 秒後停止等待 | 使用 `--network` 和 `--subnet` 部署以進行直接 VPC 出口，並使用 `--no-assign-ip` 和指向相同 VPC 的 `--network` 建立 Cloud SQL 執行個體 |320| 閘道啟動在 Cloud Run 上以 Postgres 連線逾時錯誤退出 | 服務未附加到 VPC，或 Cloud SQL 在該 VPC 上沒有私有 IP；儲存在 5 秒後停止等待 | 使用 `--network` 和 `--subnet` 部署以進行直接 VPC 出口，並使用 `--no-assign-ip` 和指向相同 VPC 的 `--network` 建立 Cloud SQL 執行個體 |

321| Agent Platform 請求返回 `403 PERMISSION_DENIED` | 執行時未使用 `claude-gateway` 服務帳戶，或模型未在 Model Garden 中為專案啟用 | 在 Cloud Run 上設定 `--service-account` 或在 GKE 上繫結 Workload Identity，並在 Model Garden 中為目標區域啟用每個 Claude 模型 |321| Google Cloud 的 Agent Platform 請求返回 `403 PERMISSION_DENIED` | 執行時未使用 `claude-gateway` 服務帳戶，或模型未在 Model Garden 中為專案啟用 | 在 Cloud Run 上設定 `--service-account` 或在 GKE 上繫結 Workload Identity，並在 Model Garden 中為目標區域啟用每個 Claude 模型 |

323 323

324<h2 id="next-steps">324<h2 id="next-steps">

claude-apps-gateway-spend-limits.md +2 −2

Details

61 61

62在每個回應之後，使用量計量器從回應中讀取令牌計數，當其流向用戶端時，以 USD 列表價格對其進行定價，並為所有三個期間儲存桶增加 Postgres 計數器。計量器是流上的單一讀取器，因此用戶端的位元組不受影響，計量失敗不會破壞回應。62在每個回應之後，使用量計量器從回應中讀取令牌計數，當其流向用戶端時，以 USD 列表價格對其進行定價，並為所有三個期間儲存桶增加 Postgres 計數器。計量器是流上的單一讀取器，因此用戶端的位元組不受影響，計量失敗不會破壞回應。

63 63

64支出限制根據 USD 列表價格的令牌計數估計支出；它們是斷路器，而不是發票。如需權威計費，請根據您提供商自己的使用情況報告進行協調，例如 Anthropic 使用情況與成本管理員 API、Bedrock 上的呼叫日誌或 Google Cloud 上的雲端監控。64支出限制根據 USD 列表價格的令牌計數估計支出；它們是斷路器，而不是發票。如需權威計費，請根據您提供商自己的使用情況報告進行協調，例如 Anthropic 使用情況與成本管理員 API、Amazon Bedrock 上的呼叫日誌或 Google Cloud 上的雲端監控。

65 65

66定價使用與 Claude Code CLI 用於自己的成本顯示相同的表格，在 Anthropic、Bedrock (`us.anthropic.…-v1:0`)、Agent Platform (`claude-…@date`) 和 Foundry ID 形式中具有相同的模型 ID 規範化。表格無法識別的模型 ID（例如 Foundry 部署名稱或推論設定檔 ARN）以未知模型預設層級 \$5/\$25 每百萬輸入/輸出令牌定價，而不是零，因此無法識別的 ID 無法透過不計量來繞過上限。閘道在啟動時和執行時每個 ID 一次警告當模型透過後備定價時。66定價使用與 Claude Code CLI 用於自己的成本顯示相同的表格，在 Anthropic、Amazon Bedrock (`us.anthropic.…-v1:0`)、Google Cloud 的 Agent Platform (`claude-…@date`) 和 Microsoft Foundry ID 形式中具有相同的模型 ID 規範化。表格無法識別的模型 ID（例如 Microsoft Foundry 部署名稱或推論設定檔 ARN）以未知模型預設層級 \$5/\$25 每百萬輸入/輸出令牌定價，而不是零，因此無法識別的 ID 無法透過不計量來繞過上限。閘道在啟動時和執行時每個 ID 一次警告當模型透過後備定價時。

67 67

68用戶端中止也會被計費。上游僅在流的終端框架中報告輸出令牌，因此中止的流不會攜帶它們。計量器從流式內容大小保持保守的下限估計，約每令牌四個字元，並在終端使用量框架遺失時計費。完整流始終計費上游報告的計數。沒有這個，被限制的開發人員可以流式傳輸輸出並在結束前立即中止每個請求，花費而不被計數。68用戶端中止也會被計費。上游僅在流的終端框架中報告輸出令牌，因此中止的流不會攜帶它們。計量器從流式內容大小保持保守的下限估計，約每令牌四個字元，並在終端使用量框架遺失時計費。完整流始終計費上游報告的計數。沒有這個，被限制的開發人員可以流式傳輸輸出並在結束前立即中止每個請求，花費而不被計數。

69 69

claude-code-on-the-web.md +20 −18

Details

4 4

5# 在網頁上使用 Claude Code5# 在網頁上使用 Claude Code

6 6

~~7> 配置雲端環境、設定指令碼、網路存取和 Docker 在 Anthropic 的沙箱中。使用 `--remote` 和 `--teleport` 在網頁和終端之間移動工作階段。~~7> 配置雲端環境、設定指令碼、網路存取和 Docker 在 Anthropic 的沙箱中。使用 `--cloud` 和 `--teleport` 在網頁和終端之間移動工作階段。

8 8

9<Note>9<Note>

10 Claude Code 網頁版目前處於研究預覽階段，適用於 Pro、Max 和 Team 使用者，以及具有高級席位或 Chat + Claude Code 席位的 Enterprise 使用者。10 Claude Code 網頁版目前處於研究預覽階段，適用於 Pro、Max 和 Team 使用者，以及具有高級席位或 Chat + Claude Code 席位的 Enterprise 使用者。

22* [雲端環境](#the-cloud-environment)：哪些配置會保留、安裝了哪些工具以及如何配置環境22* [雲端環境](#the-cloud-environment)：哪些配置會保留、安裝了哪些工具以及如何配置環境

23* [設定指令碼](#setup-scripts)和依賴管理23* [設定指令碼](#setup-scripts)和依賴管理

24* [網路存取](#network-access)：級別、代理和預設允許清單24* [網路存取](#network-access)：級別、代理和預設允許清單

~~25* [在網頁和終端之間移動任務](#move-tasks-between-web-and-terminal)，使用 `--remote` 和 `--teleport`~~25* [在網頁和終端之間移動任務](#move-tasks-between-web-and-terminal)，使用 `--cloud` 和 `--teleport`

26* [使用工作階段](#work-with-sessions)：檢查、共享、封存、刪除26* [使用工作階段](#work-with-sessions)：檢查、共享、封存、刪除

27* [自動修復拉取請求](#auto-fix-pull-requests)：自動回應 CI 失敗和審查評論27* [自動修復拉取請求](#auto-fix-pull-requests)：自動回應 CI 失敗和審查評論

28* [安全性和隔離](#security-and-isolation)：工作階段如何隔離28* [安全性和隔離](#security-and-isolation)：工作階段如何隔離

186| 新增環境 | 選擇目前環境以開啟選擇器，然後選擇**新增環境**。對話框包括名稱、網路存取級別、環境變數和設定指令碼。 |186| 新增環境 | 選擇目前環境以開啟選擇器，然後選擇**新增環境**。對話框包括名稱、網路存取級別、環境變數和設定指令碼。 |

187| 編輯環境 | 選擇顯示目前環境名稱的雲端圖示以開啟選擇器，將滑鼠懸停在環境上，然後按一下右側出現的設定圖示。 |187| 編輯環境 | 選擇顯示目前環境名稱的雲端圖示以開啟選擇器，將滑鼠懸停在環境上，然後按一下右側出現的設定圖示。 |

188| 封存環境 | 開啟環境進行編輯並選擇**封存**。封存的環境隱藏在選擇器中，但現有工作階段繼續執行。 |188| 封存環境 | 開啟環境進行編輯並選擇**封存**。封存的環境隱藏在選擇器中，但現有工作階段繼續執行。 |

190 190

191環境變數使用 `.env` 格式，每行一個 `KEY=value` 對。不要用引號包裝值，因為引號會存儲為值的一部分。此範例定義三個變數：191環境變數使用 `.env` 格式，每行一個 `KEY=value` 對。不要用引號包裝值，因為引號會存儲為值的一部分。此範例定義三個變數：

192 192

629這些工作流程需要[Claude Code CLI](/zh-TW/quickstart)登入到相同的 claude.ai 帳戶。您可以從終端啟動新的雲端工作階段，或將雲端工作階段拉入終端以在本機繼續。雲端工作階段即使在您關閉筆記型電腦後仍會保留，您可以從任何地方（包括 Claude 行動應用程式）監控它們。629這些工作流程需要[Claude Code CLI](/zh-TW/quickstart)登入到相同的 claude.ai 帳戶。您可以從終端啟動新的雲端工作階段，或將雲端工作階段拉入終端以在本機繼續。雲端工作階段即使在您關閉筆記型電腦後仍會保留，您可以從任何地方（包括 Claude 行動應用程式）監控它們。

630 630

631<Note>631<Note>

632 從 CLI，工作階段交接是單向的：您可以使用 `--teleport` 將雲端工作階段拉入終端，但無法將現有終端工作階段推送到網頁。`--remote` 旗標為您目前的儲存庫建立新的雲端工作階段。[Desktop 應用程式](/zh-TW/desktop#continue-in-another-surface)提供可將本機工作階段發送到網頁的'在另一個表面繼續'功能表。632 從 CLI，工作階段交接是單向的：您可以使用 `--teleport` 將雲端工作階段拉入終端，但無法將現有終端工作階段推送到網頁。`--cloud` 旗標為您目前的儲存庫建立新的雲端工作階段。[Desktop 應用程式](/zh-TW/desktop#continue-in-another-surface)提供可將本機工作階段發送到網頁的「在另一個表面繼續」功能表。

633</Note>633</Note>

634 634

635<h3 id="from-terminal-to-web">635<h3 id="from-terminal-to-web">

636 從終端到網頁636 從終端到網頁

637</h3>637</h3>

638 638

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

640 640

641```bash theme={null}641```bash theme={null}

642claude --remote "Fix the authentication bug in src/auth/login.ts"642claude --cloud "Fix the authentication bug in src/auth/login.ts"

643```643```

644 644

645這會在 claude.ai 上建立新的雲端工作階段。工作階段複製您目前目錄的 GitHub 遠端，位於您目前的分支，因此如果您有本機提交，請先推送，因為 VM 從 GitHub 而不是您的機器複製。`--remote` 一次適用於單一儲存庫。任務在雲端執行，而您繼續在本機工作。645這會在 claude.ai 上建立新的雲端工作階段。工作階段複製您目前目錄的 GitHub 遠端，位於您目前的分支，因此如果您有本機提交，請先推送，因為 VM 從 GitHub 而不是您的機器複製。`--cloud` 一次適用於單一儲存庫。任務在雲端執行，而您繼續在本機工作。較舊的 `--remote` 拼寫仍然可作為 `--cloud` 的已棄用別名。

646 646

647{/* min-version: 2.1.195 */}自 v2.1.195 起，CLI 會顯示設定步驟的即時檢查清單，例如複製儲存庫和執行您的[設定指令碼](#setup-scripts)，同時雲端容器啟動。您在容器佈建時輸入的訊息會排隊，並在工作階段準備好後發送。647{/* min-version: 2.1.195 */}自 v2.1.195 起，CLI 會顯示設定步驟的即時檢查清單，例如複製儲存庫和執行您的[設定指令碼](#setup-scripts)，同時雲端容器啟動。您在容器佈建時輸入的訊息會排隊，並在工作階段準備好後發送。

648 648

649<Note>649<Note>

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

651</Note>651</Note>

652 652

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

665在規劃模式下，Claude 讀取檔案、執行命令以探索並提出計畫，而不編輯原始程式碼。一旦您對計畫感到滿意，將計畫保存到儲存庫、提交和推送，以便雲端 VM 可以複製它。然後為自主執行啟動雲端工作階段：665在規劃模式下，Claude 讀取檔案、執行命令以探索並提出計畫，而不編輯原始程式碼。一旦您對計畫感到滿意，將計畫保存到儲存庫、提交和推送，以便雲端 VM 可以複製它。然後為自主執行啟動雲端工作階段：

666 666

667```bash theme={null}667```bash theme={null}

668claude --remote "Execute the migration plan in docs/migration-plan.md"668claude --cloud "Execute the migration plan in docs/migration-plan.md"

669```669```

670 670

671此模式讓您可以控制策略，同時讓 Claude 在雲端自主執行。671此模式讓您可以控制策略，同時讓 Claude 在雲端自主執行。

672 672

673**使用 ultraplan 在雲端規劃**：若要在網頁工作階段中起草和檢查計畫本身，請使用 [ultraplan](/zh-TW/ultraplan)。Claude 在 Claude Code 網頁版上生成計畫，同時您繼續工作，然後您在瀏覽器中對部分進行評論並選擇遠端執行或將計畫發送回終端。673**使用 ultraplan 在雲端規劃**：若要在網頁工作階段中起草和檢查計畫本身，請使用 [ultraplan](/zh-TW/ultraplan)。Claude 在 Claude Code 網頁版上生成計畫，同時您繼續工作，然後您在瀏覽器中對部分進行評論並選擇遠端執行或將計畫發送回終端。

674 674

675**並行執行任務**：每個 `--remote` 命令建立自己的雲端工作階段，獨立執行。您可以啟動多個任務，它們都會在單獨的工作階段中同時執行：675**並行執行任務**：每個 `--cloud` 命令建立自己的雲端工作階段，獨立執行。您可以啟動多個任務，它們都會在單獨的工作階段中同時執行：

676 676

677```bash theme={null}677```bash theme={null}

678claude --remote "Fix the flaky test in auth.spec.ts"678claude --cloud "Fix the flaky test in auth.spec.ts"

679claude --remote "Update the API documentation"679claude --cloud "Update the API documentation"

680claude --remote "Refactor the logger to use structured output"680claude --cloud "Refactor the logger to use structured output"

681```681```

682 682

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

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

687</h4>687</h4>

688 688

689當您從未連接到 GitHub 的儲存庫執行 `claude --remote` 時，Claude Code 會捆綁您的本機儲存庫並直接上傳到雲端工作階段。捆綁包括您的完整儲存庫歷史記錄，跨所有分支，加上任何未提交的對追蹤檔案的變更。689當您從未連接到 GitHub 的儲存庫執行 `claude --cloud` 時，Claude Code 會捆綁您的本機儲存庫並直接上傳到雲端工作階段。捆綁包括您的完整儲存庫歷史記錄，跨所有分支，加上任何未提交的對追蹤檔案的變更。

690 690

691當 GitHub 存取不可用時，此回退會自動啟動。若要即使在 GitHub 已連接時也強制它，請設定 `CCR_FORCE_BUNDLE=1`：691當 GitHub 存取不可用時，此回退會自動啟動。若要即使在 GitHub 已連接時也強制它，請設定 `CCR_FORCE_BUNDLE=1`：

692 692

693```bash theme={null}693```bash theme={null}

694CCR_FORCE_BUNDLE=1 claude --remote "Run the test suite and fix any failures"694CCR_FORCE_BUNDLE=1 claude --cloud "Run the test suite and fix any failures"

695```695```

696 696

697捆綁的儲存庫必須符合這些限制：697捆綁的儲存庫必須符合這些限制：

733 `--teleport` 不可用733 `--teleport` 不可用

734</h4>734</h4>

735 735

736傳送需要 claude.ai 訂閱驗證。如果您通過 API 金鑰、Bedrock、Vertex AI 或 Microsoft Foundry 進行驗證，請執行 `/login` 以改為使用您的 claude.ai 帳戶登入。如果您已通過 claude.ai 登入，`--teleport` 仍不可用，您的組織可能已禁用雲端工作階段。736傳送需要 claude.ai 訂閱驗證。如果您通過 API 金鑰、Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 進行驗證，請執行 `/login` 以改為使用您的 claude.ai 帳戶登入。如果您已通過 claude.ai 登入，`--teleport` 仍不可用，您的組織可能已禁用雲端工作階段。

737 737

738<h2 id="work-with-sessions">738<h2 id="work-with-sessions">

739 使用工作階段739 使用工作階段

745 管理上下文745 管理上下文

746</h3>746</h3>

747 747

748雲端工作階段支援產生文字輸出的[內建命令](/zh-TW/commands)。開啟互動式終端選擇器的命令（如 `/model` 或 `/config`）不可用。748雲端工作階段支援產生文字輸出的[內建命令](/zh-TW/commands)。只在終端介面中執行的命令，例如 `/plugin` 或 `/resume`，無法使用。{/* min-version: 2.1.205 */}}`/model`、`/effort`、`/fast`、`/color` 和 `/rename` 與值一起作為引數運作，例如 `/model sonnet`，而不是開啟終端選擇器或滑塊；引數形式需要工作階段環境中的 Claude Code v2.1.205 或更新版本，並遵循每個命令的[可用性說明](/zh-TW/commands#all-commands)，因此當模型的[啟動預設努力保持](/zh-TW/model-config#adjust-effort-level)生效時，`/effort` 會報告 `Not applied`，而 `/fast` 僅在以快速模式啟動的工作階段中有效。`/config` 在您傳遞 `key=value` 時設定設定。

749 749

750對於上下文管理特別：750對於上下文管理特別：

751 751

757 757

758自動壓縮在上下文視窗接近容量時自動執行。若要更早觸發它，請在您的[環境變數](#configure-your-environment)中設定 [`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`](/zh-TW/env-vars)。例如，`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70` 在 70% 容量而不是等待視窗幾乎滿時壓縮。若要更改壓縮計算的有效視窗大小，請使用 [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`](/zh-TW/env-vars)。758自動壓縮在上下文視窗接近容量時自動執行。若要更早觸發它，請在您的[環境變數](#configure-your-environment)中設定 [`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`](/zh-TW/env-vars)。例如，`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70` 在 70% 容量而不是等待視窗幾乎滿時壓縮。若要更改壓縮計算的有效視窗大小，請使用 [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`](/zh-TW/env-vars)。

759 759

760[Subagents](/zh-TW/sub-agents) 的運作方式與本機相同。Claude 可以使用 Task 工具生成它們，以將研究或並行工作卸載到單獨的上下文視窗中，保持主對話更輕。在您的儲存庫的 `.claude/agents/` 中定義的 Subagents 會自動選擇。[Agent teams](/zh-TW/agent-teams) 預設關閉，但可以通過將 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 新增到您的[環境變數](#configure-your-environment)來啟用。760[Subagents](/zh-TW/sub-agents) 的運作方式與本機相同。Claude 可以使用 Task 工具生成它們，以將研究或並行工作卸載到單獨的上下文視窗中，保持主對話更輕。在您的儲存庫的 `.claude/agents/` 中定義的 Subagents 會自動選擇。

761

762[Agent teams](/zh-TW/agent-teams) 預設關閉，但可以通過將 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 新增到您的[環境變數](#configure-your-environment)來啟用。

761 763

762<h3 id="review-changes">764<h3 id="review-changes">

763 檢查變更765 檢查變更

claude-platform-on-aws.md +1 −1

Details

270 270

271`ANTHROPIC_AWS_WORKSPACE_ID` 是必需的，並在每個請求上作為 `anthropic-workspace-id` 標頭傳送。基礎 URL 從 `AWS_REGION` 計算為 `https://aws-external-anthropic.{region}.api.aws`。若要直接覆寫 URL，請設定 `ANTHROPIC_AWS_BASE_URL`。271`ANTHROPIC_AWS_WORKSPACE_ID` 是必需的，並在每個請求上作為 `anthropic-workspace-id` 標頭傳送。基礎 URL 從 `AWS_REGION` 計算為 `https://aws-external-anthropic.{region}.api.aws`。若要直接覆寫 URL，請設定 `ANTHROPIC_AWS_BASE_URL`。

272 272

273即使您的環境中存在 AWS 認證，AWS 上的 Claude Platform 也是選擇加入的。Bedrock 和 Foundry 在提供者路由中優先，因此如果設定了 `CLAUDE_CODE_USE_BEDROCK` 和 `CLAUDE_CODE_USE_FOUNDRY`，請取消設定它們。273即使您的環境中存在 AWS 認證，AWS 上的 Claude Platform 也是選擇加入的。Amazon Bedrock 和 Microsoft Foundry 在提供者路由中優先，因此如果設定了 `CLAUDE_CODE_USE_BEDROCK` 和 `CLAUDE_CODE_USE_FOUNDRY`，請取消設定它們。

274 274

275<h3 id="3-pin-model-versions">275<h3 id="3-pin-model-versions">

276 3. 固定模型版本276 3. 固定模型版本

cli-reference.md +10 −7

Details

25| `claude gateway` | 啟動自託管 [Claude apps gateway](/zh-TW/claude-apps-gateway) 伺服器，供在 Bedrock、Vertex AI 或 Foundry 上部署 SSO 和原則在 Claude Code 前面的管理員使用。需要 `--config` 指向 [`gateway.yaml`](/zh-TW/claude-apps-gateway-config)。在 Claude Code v2.1.195 及更新版本中可用。 | `claude gateway --config gateway.yaml` |25| `claude gateway` | 啟動自託管 [Claude apps gateway](/zh-TW/claude-apps-gateway) 伺服器，供在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上部署 SSO 和原則在 Claude Code 前面的管理員使用。需要 `--config` 指向 [`gateway.yaml`](/zh-TW/claude-apps-gateway-config)。在 Claude Code v2.1.195 及更新版本中可用。 | `claude gateway --config gateway.yaml` |

27| `claude auth login` | 登入您的 Anthropic 帳戶。使用 `--email` 預先填入您的電子郵件地址，使用 `--sso` 強制進行 SSO 驗證，使用 `--console` 以 Anthropic Console 登入以進行 API 使用計費，而不是 Claude 訂閱 | `claude auth login --console` |27| `claude auth login` | 登入您的 Anthropic 帳戶。使用 `--email` 預先填入您的電子郵件地址，使用 `--sso` 強制進行 SSO 驗證，使用 `--console` 以 Anthropic Console 登入以進行 API 使用計費，而不是 Claude 訂閱 | `claude auth login --console` |

32| `claude auto-mode defaults` | 以 JSON 格式列印內建的 [auto mode](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 分類器規則。使用 `claude auto-mode config` 查看您的有效設定及套用的設定 | `claude auto-mode defaults > rules.json` |32| `claude auto-mode defaults` | 以 JSON 格式列印內建的 [auto mode](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 分類器規則。使用 `claude auto-mode config` 查看您的有效設定及套用的設定 | `claude auto-mode defaults > rules.json` |

33| `claude daemon status` | 列印背景工作階段 [supervisor](/zh-TW/agent-view#the-supervisor-process) 的狀態、版本、socket 目錄和工作者計數以進行診斷。如果 supervisor 未執行則以代碼 1 退出 | `claude daemon status` |33| `claude daemon status` | 列印背景工作階段 [supervisor](/zh-TW/agent-view#the-supervisor-process) 的狀態、版本、socket 目錄和工作者計數以進行診斷。如果 supervisor 未執行則以代碼 1 退出 | `claude daemon status` |

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

35| `claude doctor` | 從終端列印唯讀安裝和設定診斷而不啟動工作階段，包括安裝健康狀況、設定檔驗證錯誤和遠端控制資格。如需可以套用修復的工作階段內設定檢查，請執行 [`/doctor`](/zh-TW/commands#all-commands) | `claude doctor` |

37| `claude mcp login <name>` | {/* min-version: 2.1.186 */}執行已設定的 MCP 伺服器的 OAuth 流程而不開啟互動式 `/mcp` 面板。適用於 HTTP、SSE 和 claude.ai 連接器伺服器。在 SSH 上新增 `--no-browser` 以列印授權 URL 而不是開啟瀏覽器，然後將重新導向 URL 貼回提示。需要 Claude Code v2.1.186 或更新版本。請參閱 [從命令列驗證](/zh-TW/mcp#authenticate-from-the-command-line) | `claude mcp login sentry` |38| `claude mcp login <name>` | {/* min-version: 2.1.186 */}執行已設定的 MCP 伺服器的 OAuth 流程而不開啟互動式 `/mcp` 面板。適用於 HTTP、SSE 和 claude.ai 連接器伺服器。在 SSH 上新增 `--no-browser` 以列印授權 URL 而不是開啟瀏覽器，然後將重新導向 URL 貼回提示。需要 Claude Code v2.1.186 或更新版本。請參閱 [從命令列驗證](/zh-TW/mcp#authenticate-from-the-command-line) | `claude mcp login sentry` |

63| `--agents` | 透過 JSON 動態定義自訂 subagents。使用與 subagent [frontmatter](/zh-TW/sub-agents#supported-frontmatter-fields) 相同的欄位名稱，加上代理程式指示的 `prompt` 欄位 | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` |64| `--agents` | 透過 JSON 動態定義自訂 subagents。使用與 subagent [frontmatter](/zh-TW/sub-agents#supported-frontmatter-fields) 相同的欄位名稱，加上代理程式指示的 `prompt` 欄位 | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` |

64| `--allow-dangerously-skip-permissions` | 新增 `bypassPermissions` 到 `Shift+Tab` 模式循環而不立即啟動它。允許您以不同的模式（如 `plan`）開始，稍後切換到 `bypassPermissions`。請參閱 [permission modes](/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode) | `claude --permission-mode plan --allow-dangerously-skip-permissions` |65| `--allow-dangerously-skip-permissions` | 新增 `bypassPermissions` 到 `Shift+Tab` 模式循環而不立即啟動它。允許您以不同的模式（如 `plan`）開始，稍後切換到 `bypassPermissions`。請參閱 [permission modes](/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode) | `claude --permission-mode plan --allow-dangerously-skip-permissions` |

65| `--allowedTools`、`--allowed-tools` | 無需提示權限即可執行的工具。請參閱 [permission rule syntax](/zh-TW/settings#permission-rule-syntax) 以了解模式匹配。若要限制可用的工具，請改用 `--tools` | `"Bash(git log *)" "Bash(git diff *)" "Read"` |66| `--allowedTools`、`--allowed-tools` | 無需提示權限即可執行的工具。請參閱 [permission rule syntax](/zh-TW/settings#permission-rule-syntax) 以了解模式匹配。若要限制可用的工具，請改用 `--tools` | `"Bash(git log *)" "Bash(git diff *)" "Read"` |

67| `--append-subagent-system-prompt` | {/* min-version: 2.1.205 */}將自訂文字附加到每個 [subagent](/zh-TW/sub-agents) 系統提示的末尾，包括巢狀 subagents。僅適用於使用 `-p` 的非互動模式。需要 Claude Code v2.1.205 或更新版本 | `claude -p --append-subagent-system-prompt "Cite file paths in every answer" "query"` |

68| `--ax-screen-reader` | {/* min-version: 2.1.181 */}呈現螢幕閱讀器友善的輸出：平面文字，無裝飾邊框或動畫。強制使用經典渲染器，因此 [`tui`](/zh-TW/settings#available-settings) 設定在工作階段中無效。優先於 [`CLAUDE_AX_SCREEN_READER`](/zh-TW/env-vars) 和 [`axScreenReader`](/zh-TW/settings#available-settings) 設定。需要 Claude Code v2.1.181 或更新版本 | `claude --ax-screen-reader` |70| `--ax-screen-reader` | {/* min-version: 2.1.181 */}呈現螢幕閱讀器友善的輸出：平面文字，無裝飾邊框或動畫。強制使用經典渲染器，因此 [`tui`](/zh-TW/settings#available-settings) 設定在工作階段中無效。優先於 [`CLAUDE_AX_SCREEN_READER`](/zh-TW/env-vars) 和 [`axScreenReader`](/zh-TW/settings#available-settings) 設定。需要 Claude Code v2.1.181 或更新版本 | `claude --ax-screen-reader` |

71| `--bg`、`--background` | 以 [background agent](/zh-TW/agent-view) 身份啟動工作階段並立即返回。列印工作階段 ID 和管理命令。與 `--exec` 結合以執行 shell 命令作為背景工作而不是 Claude 工作階段，或與 `--agent` 結合以執行特定 subagent。{/* min-version: 2.1.198 */}無法與 `-p`/`--print` 結合；請參閱 [error reference](/zh-TW/errors#command-line-errors) | `claude --bg "investigate the flaky test"` |73| `--bg`、`--background` | 以 [background agent](/zh-TW/agent-view) 身份啟動工作階段並立即返回。列印工作階段 ID 和管理命令。與 `--exec` 結合以執行 shell 命令作為背景工作而不是 Claude 工作階段，或與 `--agent` 結合以執行特定 subagent。{/* min-version: 2.1.198 */}無法與 `-p`/`--print` 結合；請參閱 [error reference](/zh-TW/errors#command-line-errors) | `claude --bg "investigate the flaky test"` |

72| `--channels` | （研究預覽）MCP 伺服器，其 [channel](/zh-TW/channels) 通知 Claude 應在此工作階段中監聽。以空格分隔的 `plugin:<name>@<marketplace>` 項目清單。需要 Claude.ai 驗證 | `claude --channels plugin:my-notifier@my-marketplace` |74| `--channels` | （研究預覽）MCP 伺服器，其 [channel](/zh-TW/channels) 通知 Claude 應在此工作階段中監聽。以空格分隔的 `plugin:<name>@<marketplace>` 項目清單。需要 Claude.ai 驗證 | `claude --channels plugin:my-notifier@my-marketplace` |

76| `--cloud` | 在 claude.ai 上建立新的 [web session](/zh-TW/claude-code-on-the-web)，並提供工作描述 | `claude --cloud "Fix the login bug"` |

75| `--dangerously-load-development-channels` | 啟用不在核准允許清單上的 [channels](/zh-TW/channels-reference#test-during-the-research-preview)，用於本機開發。接受 `plugin:<name>@<marketplace>` 和 `server:<name>` 項目。提示確認 | `claude --dangerously-load-development-channels server:webhook` |78| `--dangerously-load-development-channels` | 啟用不在核准允許清單上的 [channels](/zh-TW/channels-reference#test-during-the-research-preview)，用於本機開發。接受 `plugin:<name>@<marketplace>` 和 `server:<name>` 項目。提示確認 | `claude --dangerously-load-development-channels server:webhook` |

76| `--dangerously-skip-permissions` | 略過權限提示。等同於 `--permission-mode bypassPermissions`。請參閱 [permission modes](/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode) 以了解此操作會和不會略過的內容 | `claude --dangerously-skip-permissions` |79| `--dangerously-skip-permissions` | 略過權限提示。等同於 `--permission-mode bypassPermissions`。請參閱 [permission modes](/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode) 以了解此操作會和不會略過的內容 | `claude --dangerously-skip-permissions` |

80| `--disallowedTools`、`--disallowed-tools` | 拒絕規則。裸工具名稱會從模型的內容中移除該工具：`"Edit"` 移除 Edit、`"*"` 移除每個工具，`"mcp__*"` 移除每個 MCP 工具。範圍規則（例如 `Bash(rm *)` ）會保留工具可用，但只拒絕符合的呼叫 | `"Bash(git log *)" "Bash(git diff *)" "Edit"` |83| `--disallowedTools`、`--disallowed-tools` | 拒絕規則。裸工具名稱會從模型的內容中移除該工具：`"Edit"` 移除 Edit、`"*"` 移除每個工具，`"mcp__*"` 移除每個 MCP 工具。範圍規則（例如 `Bash(rm *)` ）會保留工具可用，但只拒絕符合的呼叫 | `"Bash(git log *)" "Bash(git diff *)" "Edit"` |

81| `--effort` | 為目前工作階段設定 [effort level](/zh-TW/model-config#adjust-effort-level)。選項：`low`、`medium`、`high`、`xhigh`、`max`；可用的層級取決於模型。覆蓋此工作階段的 [`effortLevel`](/zh-TW/settings#available-settings) 設定，且不會持久化 | `claude --effort high` |84| `--effort` | 為目前工作階段設定 [effort level](/zh-TW/model-config#adjust-effort-level)。選項：`low`、`medium`、`high`、`xhigh`、`max` 或 {/* min-version: 2.1.203 */}}`ultracode`。可用的層級取決於模型。`ultracode` 以 `xhigh` 努力開始工作階段，並啟用 [ultracode](/zh-TW/workflows#let-claude-decide-with-ultracode)，需要 Claude Code v2.1.203 或更新版本。覆蓋此工作階段的 [`effortLevel`](/zh-TW/settings#available-settings) 設定，且不會持久化 | `claude --effort high` |

82| `--enable-auto-mode` | {/* max-version: 2.1.110 */}在 v2.1.111 中移除。Auto mode 現在預設在 `Shift+Tab` 循環中；使用 `--permission-mode auto` 以它開始 | `claude --permission-mode auto` |85| `--enable-auto-mode` | {/* max-version: 2.1.110 */}在 v2.1.111 中移除。Auto mode 現在預設在 `Shift+Tab` 循環中；使用 `--permission-mode auto` 以它開始 | `claude --permission-mode auto` |

83| `--exclude-dynamic-system-prompt-sections` | 將每台機器的系統提示部分（工作目錄、環境資訊、記憶體路徑、git 狀態旗標）移至第一個使用者訊息。改善在執行相同工作的不同使用者和機器之間的提示快取重複使用。僅適用於預設系統提示；設定 `--system-prompt` 或 `--system-prompt-file` 時忽略。與 `-p` 搭配使用以進行指令碼化、多使用者工作負載 | `claude -p --exclude-dynamic-system-prompt-sections "query"` |86| `--exclude-dynamic-system-prompt-sections` | 將每台機器的系統提示部分（工作目錄、環境資訊、記憶體路徑、git 狀態旗標）移至第一個使用者訊息。改善在執行相同工作的不同使用者和機器之間的提示快取重複使用。僅適用於預設系統提示；設定 `--system-prompt` 或 `--system-prompt-file` 時忽略。與 `-p` 搭配使用以進行指令碼化、多使用者工作負載 | `claude -p --exclude-dynamic-system-prompt-sections "query"` |

92| `--include-partial-messages` | 在輸出中包含部分串流事件。需要 `--print` 和 `--output-format stream-json` | `claude -p --output-format stream-json --verbose --include-partial-messages "query"` |95| `--include-partial-messages` | 在輸出中包含部分串流事件。需要 `--print` 和 `--output-format stream-json` | `claude -p --output-format stream-json --verbose --include-partial-messages "query"` |

94| `--json-schema` | 在代理程式完成其工作流程後取得符合 JSON Schema 的驗證 JSON 輸出（僅列印模式，請參閱 [structured outputs](/zh-TW/agent-sdk/structured-outputs)） | `claude -p --json-schema '{"type":"object","properties":{...}}' "query"` |97| `--json-schema` | 在代理程式完成其工作流程後取得符合 JSON Schema 的驗證 JSON 輸出（僅列印模式）。請參閱 [structured outputs](/zh-TW/agent-sdk/structured-outputs)。{/* min-version: 2.1.205 */}Claude Code 在無效的 schema 上以錯誤退出，並接受 `format` 關鍵字作為註解而不進行用戶端驗證。在 v2.1.205 之前，無效的 schema 產生無結構輸出且無錯誤，使用 `format` 的 schemas 被視為無效 | `claude -p --json-schema '{"type":"object","properties":{...}}' "query"` |

97| `--max-turns` | 限制代理程式轉數（僅列印模式）。達到限制時以錯誤退出。預設無限制 | `claude -p --max-turns 3 "query"` |100| `--max-turns` | 限制代理程式轉數（僅列印模式）。達到限制時以錯誤退出。預設無限制。{/* min-version: 2.1.205 */}使用 `--input-format stream-json` 時，在 Claude 工作時傳送的訊息會保持佇列狀態，並在限制結束目前轉數時作為自己的轉數執行，具有自己的限制。在 v2.1.205 之前，Claude Code 丟棄該訊息 | `claude -p --max-turns 3 "query"` |

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

100| `--name`、`-n` | 為工作階段設定顯示名稱，顯示在 `/resume` 和終端標題中。您可以使用 `claude --resume <name>` 繼續已命名的工作階段。<br /><br />[`/rename`](/zh-TW/commands) 在工作階段中途變更名稱，也會在提示列中顯示 | `claude -n "my-feature-work"` |103| `--name`、`-n` | 為工作階段設定顯示名稱，顯示在 `/resume` 和終端標題中。您可以使用 `claude --resume <name>` 繼續已命名的工作階段。<br /><br />[`/rename`](/zh-TW/commands) 在工作階段中途變更名稱，也會在提示列中顯示 | `claude -n "my-feature-work"` |

102| `--no-session-persistence` | 停用工作階段持久性，使工作階段不會儲存到磁碟且無法繼續。僅列印模式。[`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/zh-TW/env-vars) 環境變數在任何模式中執行相同操作 | `claude -p --no-session-persistence "query"` |105| `--no-session-persistence` | 停用工作階段持久性，使工作階段不會儲存到磁碟且無法繼續。僅列印模式。[`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/zh-TW/env-vars) 環境變數在任何模式中執行相同操作 | `claude -p --no-session-persistence "query"` |

104| `--permission-mode` | 以指定的 [permission mode](/zh-TW/permission-modes) 開始。接受 `default`、`acceptEdits`、`plan`、`auto`、`dontAsk` 或 `bypassPermissions`。覆蓋設定檔案中的 `defaultMode` | `claude --permission-mode plan` |107| `--permission-mode` | 以指定的 [permission mode](/zh-TW/permission-modes) 開始。接受 `default`、`acceptEdits`、`plan`、`auto`、`dontAsk`、`bypassPermissions` 或 {/* min-version: 2.1.200 */}}`manual` 作為 `default` 的別名。`manual` 別名選擇 UI 標記為「手動」的模式，需要 Claude Code v2.1.200 或更新版本；`claude --help` 會列出它以取代 `default`，兩個值都有效。覆蓋設定檔案中的 `defaultMode` | `claude --permission-mode plan` |

105| `--permission-prompt-tool` | 指定 MCP 工具以在非互動模式下處理權限提示。{/* min-version: 2.1.199 */}自 v2.1.199 起，提示工具無法核准標記為 [requiring user interaction](/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具：一個的 `allow` 結果會轉換為拒絕 | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |108| `--permission-prompt-tool` | 指定 MCP 工具以在非互動模式下處理權限提示。{/* min-version: 2.1.199 */}自 v2.1.199 起，提示工具無法核准標記為 [requiring user interaction](/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具：一個的 `allow` 結果會轉換為拒絕 | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |

109| `--prompt-suggestions` | 在每個轉數後發出 `prompt_suggestion` 訊息，其中包含預測的下一個使用者提示。需要 `--print`、`--output-format stream-json` 和 `--verbose`。請參閱 [Prompt suggestions](/zh-TW/interactive-mode#prompt-suggestions) | `claude -p --prompt-suggestions --output-format stream-json --verbose "query"` |112| `--prompt-suggestions` | 在每個轉數後發出 `prompt_suggestion` 訊息，其中包含預測的下一個使用者提示。需要 `--print`、`--output-format stream-json` 和 `--verbose`。請參閱 [Prompt suggestions](/zh-TW/interactive-mode#prompt-suggestions) | `claude -p --prompt-suggestions --output-format stream-json --verbose "query"` |

111| `--remote-control`、`--rc` | 啟動互動式工作階段，並啟用 [Remote Control](/zh-TW/remote-control#start-a-remote-control-session)，以便您也可以從 claude.ai 或 Claude 應用程式控制它。可選擇傳遞工作階段的名稱 | `claude --remote-control "My Project"` |114| `--remote-control`、`--rc` | 啟動互動式工作階段，並啟用 [Remote Control](/zh-TW/remote-control#start-a-remote-control-session)，以便您也可以從 claude.ai 或 Claude 應用程式控制它。可選擇傳遞工作階段的名稱 | `claude --remote-control "My Project"` |

112| `--remote-control-session-name-prefix <prefix>` | [Remote Control](/zh-TW/remote-control) 工作階段名稱的前綴，當未設定明確名稱時自動產生。預設為您的機器主機名稱，產生如 `myhost-graceful-unicorn` 的名稱。設定 `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` 以獲得相同效果 | `claude remote-control --remote-control-session-name-prefix dev-box` |115| `--remote-control-session-name-prefix <prefix>` | [Remote Control](/zh-TW/remote-control) 工作階段名稱的前綴，當未設定明確名稱時自動產生。預設為您的機器主機名稱，產生如 `myhost-graceful-unicorn` 的名稱。設定 `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` 以獲得相同效果 | `claude remote-control --remote-control-session-name-prefix dev-box` |

113| `--replay-user-messages` | 從 stdin 重新發出使用者訊息回到 stdout 以進行確認。需要 `--input-format stream-json` 和 `--output-format stream-json` | `claude -p --input-format stream-json --output-format stream-json --verbose --replay-user-messages` |116| `--replay-user-messages` | 從 stdin 重新發出使用者訊息回到 stdout 以進行確認。需要 `--input-format stream-json` 和 `--output-format stream-json` | `claude -p --input-format stream-json --output-format stream-json --verbose --replay-user-messages` |

123| `--teammate-mode` | 設定 [agent team](/zh-TW/agent-teams) 隊友的顯示方式：`in-process`（預設）、`auto`、`tmux` 或 {/* min-version: 2.1.186 */}`iterm2`（在 v2.1.186 中新增）。預設在 v2.1.179 中從 `auto` 變更。覆蓋此工作階段的 [`teammateMode`](/zh-TW/settings#available-settings) 設定。請參閱 [選擇顯示模式](/zh-TW/agent-teams#choose-a-display-mode) | `claude --teammate-mode auto` |126| `--teammate-mode` | 設定 [agent team](/zh-TW/agent-teams) 隊友的顯示方式：`in-process`（預設）、`auto`、`tmux` 或 {/* min-version: 2.1.186 */}}`iterm2`（在 v2.1.186 中新增）。預設在 v2.1.179 中從 `auto` 變更。覆蓋此工作階段的 [`teammateMode`](/zh-TW/settings#available-settings) 設定。請參閱 [選擇顯示模式](/zh-TW/agent-teams#choose-a-display-mode) | `claude --teammate-mode auto` |

125| `--tools` | 限制 Claude 可以使用的內建工具。使用 `""` 停用全部、`"default"` 為全部，或工具名稱如 `"Bash,Edit,Read"`。MCP 工具不受影響；若要拒絕這些工具，請改用 `--disallowedTools "mcp__*"`，或傳遞 `--strict-mcp-config` 而不使用 `--mcp-config` 以便不載入 MCP 伺服器 | `claude --tools "Bash,Edit,Read"` |128| `--tools` | 限制 Claude 可以使用的內建工具。使用 `""` 停用全部、`"default"` 為全部，或工具名稱如 `"Bash,Edit,Read"`。MCP 工具不受影響；若要拒絕這些工具，請改用 `--disallowedTools "mcp__*"`，或傳遞 `--strict-mcp-config` 而不使用 `--mcp-config` 以便不載入 MCP 伺服器 | `claude --tools "Bash,Edit,Read"` |

code-review.md +1 −1

Details

270 270

271在任何模式下，評論 `@claude review` [選擇 PR 進入推送觸發的審查](#manually-trigger-reviews)，因此在該評論之後每次推送都會產生額外成本。要運行單次審查而不訂閱未來推送，請改為評論 `@claude review once`。271在任何模式下，評論 `@claude review` [選擇 PR 進入推送觸發的審查](#manually-trigger-reviews)，因此在該評論之後每次推送都會產生額外成本。要運行單次審查而不訂閱未來推送，請改為評論 `@claude review once`。

272 272

273成本出現在您的 Anthropic 帳單上，無論您的組織是否為其他 Claude Code 功能使用 Amazon Bedrock 或 Google Vertex AI。要為 Code Review 設定月度支出上限，請前往 [claude.ai/admin-settings/usage](https://claude.ai/admin-settings/usage) 並為 Claude Code Review 服務配置限制。273成本出現在您的 Anthropic 帳單上，無論您的組織是否為其他 Claude Code 功能使用 Amazon Bedrock 或 Google Cloud 的 Agent Platform。要為 Code Review 設定月度支出上限，請前往 [claude.ai/admin-settings/usage](https://claude.ai/admin-settings/usage) 並為 Claude Code Review 服務配置限制。

274 274

275通過 [analytics](#view-usage) 中的每週成本圖表或管理員設定中的每個存儲庫平均成本列監控支出。275通過 [analytics](#view-usage) 中的每週成本圖表或管理員設定中的每個存儲庫平均成本列監控支出。

276 276

commands.md +15 −15

Details

24 24

25**並行執行工作。** Claude 委派側邊任務給 [subagents](/zh-TW/sub-agents)，`/tasks` 列出目前工作階段背景中執行的內容。`/background` 分離整個工作階段以繼續作為 [background agent](/zh-TW/agent-view) 執行並釋放您的終端機。對於跨越程式碼庫的大型變更，`/batch` 將其分解為獨立單位，並在各自的 [worktree](/zh-TW/worktrees) 中執行每個單位。請參閱 [Run agents in parallel](/zh-TW/agents) 以了解這些方法如何相關。25**並行執行工作。** Claude 委派側邊任務給 [subagents](/zh-TW/sub-agents)，`/tasks` 列出目前工作階段背景中執行的內容。`/background` 分離整個工作階段以繼續作為 [background agent](/zh-TW/agent-view) 執行並釋放您的終端機。對於跨越程式碼庫的大型變更，`/batch` 將其分解為獨立單位，並在各自的 [worktree](/zh-TW/worktrees) 中執行每個單位。請參閱 [Run agents in parallel](/zh-TW/agents) 以了解這些方法如何相關。

26 26

27**在您推送前。** `/diff` 顯示變更的內容，`/code-review` 檢查差異以找出正確性錯誤和清理，並可以使用 `--fix` 應用發現的結果，`/review` 在 GitHub pull request 上執行相同的唯讀審查，`/security-review` 進行更深入的唯讀檢查。`/code-review ultra` 在雲端執行多代理審查。27**在您推送前。** `/diff` 顯示變更的內容，`/code-review` 檢查差異以找出正確性錯誤和清理，並可以使用 `--fix` 應用發現的結果，`/review` 在 GitHub pull request 上執行快速單次通過的唯讀審查，`/code-review <level> <pr#>` 執行其中一個的多代理審查，`/security-review` 檢查差異以找出安全性漏洞。`/code-review ultra` 在雲端執行多代理審查。

28 28

29**在工作階段之間。** `/clear` 在保持專案記憶的同時開始新工作的新鮮開始。`/resume` 和 `/branch` 讓您返回或分叉較早的對話。`/teleport` 將網頁工作階段拉入此終端機，`/remote-control` 讓您從另一個裝置繼續此本地工作階段。29**在工作階段之間。** `/clear` 在保持專案記憶的同時開始新工作的新鮮開始。`/resume` 和 `/branch` 讓您返回或分叉較早的對話。`/teleport` 將網頁工作階段拉入此終端機，`/remote-control` 讓您從另一個裝置繼續此本地工作階段。

30 30

31**當出現問題時。** `/rewind` 將程式碼和對話倒帶到 checkpoint，或總結對話的一部分。`/doctor` 和 `/debug` 診斷安裝和執行時問題，`/feedback` 報告附加工作階段上下文的錯誤。31**當出現問題時。** `/rewind` 將程式碼和對話倒帶到 checkpoint，或總結對話的一部分。`/doctor` 執行設定檢查以診斷安裝和配置問題，並可以修復它們，`/debug` 診斷執行時問題，`/feedback` 報告附加工作階段上下文的錯誤。

32 32

33<h2 id="all-commands">33<h2 id="all-commands">

34 所有命令34 所有命令

48</Note>48</Note>

49 49

50| 命令 | 用途 |50| 命令 | 用途 |

51| :--------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |51| :--------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

52| `/add-dir <path>` | 為目前工作階段期間的檔案存取添加工作目錄。大多數 `.claude/` 配置[未從添加的目錄發現](/zh-TW/permissions#additional-directories-grant-file-access-not-configuration)。您可以稍後使用 `--continue` 或 `--resume` 從添加的目錄繼續工作階段 |52| `/add-dir <path>` | 為目前工作階段期間的檔案存取添加工作目錄。大多數 `.claude/` 配置[未從添加的目錄發現](/zh-TW/permissions#additional-directories-grant-file-access-not-configuration)。您可以稍後使用 `--continue` 或 `--resume` 從添加的目錄繼續工作階段 |

53| `/advisor [model\|off]` | {/* min-version: 2.1.98 */}啟用或停用[顧問工具](/zh-TW/advisor)，它在工作期間的關鍵時刻諮詢第二個模型以獲得指導。接受 `opus`、`sonnet`、`fable`（{/* min-version: 2.1.170 */}v2.1.170+）或完整的模型 ID。不帶引數時，開啟選擇器。需要 Claude Code v2.1.98 或更新版本 |53| `/advisor [model\|off]` | {/* min-version: 2.1.98 */}啟用或停用[顧問工具](/zh-TW/advisor)，它在工作期間的關鍵時刻諮詢第二個模型以獲得指導。接受 `opus`、`sonnet`、`fable`（{/* min-version: 2.1.170 */}v2.1.170+）或完整的模型 ID。不帶引數時，開啟選擇器。需要 Claude Code v2.1.98 或更新版本 |

54| `/agents` | {/* min-version: 2.1.198 */}自 v2.1.198 起，執行 `/agents` 會列印提醒，要求您詢問 Claude 以建立或管理 [subagents](/zh-TW/sub-agents)，或直接編輯 `.claude/agents/` 或 `~/.claude/agents/`。{/* max-version: 2.1.197 */}在 v2.1.197 及更早版本上，開啟互動式介面以建立和管理 subagent 配置 |54| `/agents` | {/* min-version: 2.1.198 */}自 v2.1.198 起，執行 `/agents` 會列印提醒，要求您詢問 Claude 以建立或管理 [subagents](/zh-TW/sub-agents)，或直接編輯 `.claude/agents/` 或 `~/.claude/agents/`。{/* max-version: 2.1.197 */}在 v2.1.197 及更早版本上，開啟互動式介面以建立和管理 subagent 配置 |

62| `/claude-api [migrate\|managed-agents-onboard]` | **[Skill](/zh-TW/skills#bundled-skills).** 為您的專案語言（Python、TypeScript、Java、Go、Ruby、C#、PHP 或 cURL）和 Managed Agents 參考加載 Claude API 參考資料。涵蓋工具使用、串流、批次、結構化輸出和常見陷阱。當您的程式碼導入 `anthropic` 或 `@anthropic-ai/sdk` 時也會自動激活。執行 `/claude-api migrate` 以將現有 Claude API 程式碼升級到較新的模型：Claude 詢問要掃描哪些檔案以及要針對哪個模型，然後更新在版本之間變更的模型 ID、thinking 配置和其他參數。執行 `/claude-api managed-agents-onboard` 以進行互動式逐步解說，從頭開始建立新的 Managed Agent |62| `/claude-api [migrate\|managed-agents-onboard]` | **[Skill](/zh-TW/skills#bundled-skills).** 為您的專案語言（Python、TypeScript、Java、Go、Ruby、C#、PHP 或 cURL）和 Managed Agents 參考加載 Claude API 參考資料。涵蓋工具使用、串流、批次、結構化輸出和常見陷阱。當您的程式碼導入 `anthropic` 或 `@anthropic-ai/sdk` 時也會自動激活。執行 `/claude-api migrate` 以將現有 Claude API 程式碼升級到較新的模型：Claude 詢問要掃描哪些檔案以及要針對哪個模型，然後更新在版本之間變更的模型 ID、thinking 配置和其他參數。執行 `/claude-api managed-agents-onboard` 以進行互動式逐步解說，從頭開始建立新的 Managed Agent |

63| `/clear [name]` | 使用空上下文開始新對話。上一個對話在 `/resume` 中保持可用。傳遞名稱以在 `/resume` 選擇器中標記上一個對話。若要在繼續同一對話時釋放上下文，請改用 `/compact`。別名：`/reset`、`/new` |63| `/clear [name]` | 使用空上下文開始新對話。上一個對話在 `/resume` 中保持可用。傳遞名稱以在 `/resume` 選擇器中標記上一個對話。若要在繼續同一對話時釋放上下文，請改用 `/compact`。別名：`/reset`、`/new` |

64| `/code-review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [target]` | **[Skill](/zh-TW/skills#bundled-skills).** 審閱目前的差異以查找正確性錯誤並進行重用、簡化和效率清理。傳遞 `--fix` 以將發現應用到您的工作樹，傳遞 `--comment` 以將其作為內聯 GitHub PR 評論發佈，或傳遞 `ultra` 以運行深度[雲端審閱](/zh-TW/ultrareview)。{/* min-version: 2.1.154 */}從 v2.1.154 開始，`/simplify` 運行單獨的僅清理審閱，應用修復而不尋找錯誤。請參閱[本地審閱差異](/zh-TW/code-review#review-a-diff-locally)以了解努力程度和目標設定 |64| `/code-review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [target]` | **[Skill](/zh-TW/skills#bundled-skills).** 審閱目前的差異以查找正確性錯誤並進行重用、簡化和效率清理。傳遞 `--fix` 以將發現應用到您的工作樹，傳遞 `--comment` 以將其作為內聯 GitHub PR 評論發佈，或傳遞 `ultra` 以運行深度[雲端審閱](/zh-TW/ultrareview)。{/* min-version: 2.1.154 */}從 v2.1.154 開始，`/simplify` 運行單獨的僅清理審閱，應用修復而不尋找錯誤。請參閱[本地審閱差異](/zh-TW/code-review#review-a-diff-locally)以了解努力程度和目標設定 |

65| `/color [color\|default]` | 設定目前工作階段的提示列顏色。可用顏色：`red`、`blue`、`green`、`yellow`、`purple`、`orange`、`pink`、`cyan`。使用 `default` 重設，或不帶引數執行以選擇隨機顏色。當[遠端控制](/zh-TW/remote-control)已連接時，顏色會同步到 claude.ai/code |65| `/color [color\|default]` | 設定目前工作階段的提示列顏色。可用顏色：`red`、`blue`、`green`、`yellow`、`purple`、`orange`、`pink`、`cyan`。使用 `default` 重設，或不帶引數執行以選擇隨機顏色。當[遠端控制](/zh-TW/remote-control)已連接時，顏色會同步到 claude.ai/code。{/* min-version: 2.1.205 */}也可在非互動模式（`-p`）中使用；需要 Claude Code v2.1.205 或更新版本 |

66| `/compact [instructions]` | 通過總結到目前為止的對話來釋放上下文。可選擇性地傳遞焦點指示以進行摘要。請參閱[壓縮如何處理規則、skills 和記憶體檔案](/zh-TW/context-window#what-survives-compaction) |66| `/compact [instructions]` | 通過總結到目前為止的對話來釋放上下文。可選擇性地傳遞焦點指示以進行摘要。請參閱[壓縮如何處理規則、skills 和記憶體檔案](/zh-TW/context-window#what-survives-compaction) |

67| `/config [key=value ...]` | 開啟[設定](/zh-TW/settings)介面以調整主題、模型、[輸出樣式](/zh-TW/output-styles)和其他偏好設定。{/* min-version: 2.1.181 */}從 v2.1.181 開始，傳遞一個或多個 `key=value` 對以直接設定設定，無需開啟介面，例如 `/config thinking=false`。{/* min-version: 2.1.182 */}從 v2.1.182 開始，也接受命名的簡寫鍵，例如 `/config theme=dark` 或 `/config model=sonnet`。`key=value` 形式也適用於非互動模式（`-p`）和[遠端控制](/zh-TW/remote-control)。執行 `/config --help` 以列出每個可設定的鍵及其選項。別名：`/settings` |67| `/config [key=value ...]` | 開啟[設定](/zh-TW/settings)介面以調整主題、模型、[輸出樣式](/zh-TW/output-styles)和其他偏好設定。{/* min-version: 2.1.181 */}從 v2.1.181 開始，傳遞一個或多個 `key=value` 對以直接設定設定，無需開啟介面，例如 `/config thinking=false`。{/* min-version: 2.1.182 */}從 v2.1.182 開始，也接受命名的簡寫鍵，例如 `/config theme=dark` 或 `/config model=sonnet`。`key=value` 形式也適用於非互動模式（`-p`）和[遠端控制](/zh-TW/remote-control)。執行 `/config --help` 以列出每個可設定的鍵及其選項。別名：`/settings` |

68| `/context [all]` | 將目前的上下文使用情況視覺化為彩色網格。顯示上下文繁重工具、記憶體膨脹和容量警告的最佳化建議。在[全螢幕模式](/zh-TW/fullscreen)中，每個項目的分解會折疊以保持網格可見。傳遞 `all` 以展開它 |68| `/context [all]` | 將目前的上下文使用情況視覺化為彩色網格。顯示上下文繁重工具、記憶體膨脹和容量警告的最佳化建議。在[全螢幕模式](/zh-TW/fullscreen)中，每個項目的分解會折疊以保持網格可見。傳遞 `all` 以展開它 |

75| `/design-sync [hint]` | **[Skill](/zh-TW/skills#bundled-skills).** 轉換您的存放庫的 React 設計系統並將其上傳到 [Claude Design](https://claude.ai/design)，以便它產生的設計使用您的真實元件。可選擇性地命名設計系統，例如 `/design-sync Acme DS`。首次同步會驗證每個元件，在大型存放庫上可能需要幾個小時。在 Anthropic API 上可用；在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，基礎工具無法到達 claude.ai，因此命令不可用 |75| `/design-sync [hint]` | **[Skill](/zh-TW/skills#bundled-skills).** 轉換您的存放庫的 React 設計系統並將其上傳到 [Claude Design](https://claude.ai/design)，以便它產生的設計使用您的真實元件。可選擇性地命名設計系統，例如 `/design-sync Acme DS`。首次同步會驗證每個元件，在大型存放庫上可能需要幾個小時。在 Anthropic API 上可用；在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，基礎工具無法到達 claude.ai，因此命令不可用 |

77| `/diff` | 開啟互動式差異檢視器，顯示未提交的變更和每個回合的差異。使用左/右箭頭在目前的 git 差異和個別 Claude 回合之間切換，使用上/下箭頭瀏覽檔案。{/* min-version: 2.1.198 */}自 v2.1.198 起，開啟的檢視器也會在存放庫的 git 狀態在工作階段外變更時自動重新整理，例如在另一個終端機中進行分支切換或提交 |77| `/diff` | 開啟互動式差異檢視器，顯示未提交的變更和每個回合的差異。使用左/右箭頭在目前的 git 差異和個別 Claude 回合之間切換，使用上/下箭頭瀏覽檔案。{/* min-version: 2.1.198 */}自 v2.1.198 起，開啟的檢視器也會在存放庫的 git 狀態在工作階段外變更時自動重新整理，例如在另一個終端機中進行分支切換或提交 |

78| `/doctor` | 診斷並驗證您的 Claude Code 安裝和設定。結果顯示狀態圖示。按 `f` 讓 Claude 修復任何報告的問題 |78| `/doctor` | **[Skill](/zh-TW/skills#bundled-skills).** 執行設定檢查以診斷問題並可以修復它們。檢查安裝健康狀況，包括重複或遺留的安裝、`PATH` 問題和無法解析的設定檔案。查找未使用的 skills、MCP 伺服器和 plugins 與其上下文成本，針對簽入的檔案進行本地 `CLAUDE.md` 檔案的重複資料刪除，將始終載入的指導遷移到 [skills](/zh-TW/skills) 和按需載入的嵌套 `CLAUDE.md` 檔案，標記緩慢的 [hooks](/zh-TW/hooks)，並檢查是否有更新版本。也提供使 [auto mode](/zh-TW/permissions#permission-modes) 成為您的預設值的選項，以及[預先批准](/zh-TW/permissions)經常被拒絕的唯讀命令。首先報告發現並在變更任何內容之前要求確認。從終端機，`claude doctor` 列印唯讀安裝診斷而不啟動工作階段。別名：`/checkup`。{/* min-version: 2.1.205 */}在 v2.1.205 之前，`/doctor` 開啟唯讀診斷螢幕，按 `f` 將報告發送給 Claude |

79| `/effort [level\|auto]` | 設定模型[努力程度](/zh-TW/model-config#adjust-effort-level)。接受 `low`、`medium`、`high`、`xhigh`、`max` 或 `ultracode`；可用的程度取決於模型，`max` 和 `ultracode` 僅限工作階段。`ultracode` 是一個 Claude Code 設定，結合 `xhigh` 推理與自動[工作流](/zh-TW/workflows#let-claude-decide-with-ultracode)協調。`auto` 重設為模型預設值。不帶引數時，開啟互動式滑塊；使用左右箭頭選擇程度，按 `Enter` 應用。立即生效，無需等待目前回應完成 |79| `/effort [level\|auto]` | 設定模型[努力程度](/zh-TW/model-config#adjust-effort-level)。接受 `low`、`medium`、`high`、`xhigh`、`max` 或 `ultracode`；可用的程度取決於模型，`max` 和 `ultracode` 僅限工作階段。`ultracode` 是一個 Claude Code 設定，結合 `xhigh` 推理與自動[工作流](/zh-TW/workflows#let-claude-decide-with-ultracode)協調。`auto` 重設為模型預設值。不帶引數時，開啟互動式滑塊；使用左右箭頭選擇程度，按 `Enter` 應用。立即生效，無需等待目前回應完成。{/* min-version: 2.1.205 */}也可在非互動模式（`-p`）中使用程度引數，其中它僅適用於目前工作階段且不會儲存為您的預設值；需要 Claude Code v2.1.205 或更新版本。在 Fable 5、Opus 4.8 和 Opus 4.7 上，非互動 `/effort` 在[模型預設努力程度保持](/zh-TW/model-config#adjust-effort-level)生效時報告 `Not applied`，因此改為在啟動時傳遞 `--effort` |

82| `/fast [on\|off]` | 切換[快速模式](/zh-TW/fast-mode)開啟或關閉 |82| `/fast [on\|off]` | 切換[快速模式](/zh-TW/fast-mode)開啟或關閉。{/* min-version: 2.1.205 */}在非互動模式（`-p`）中，`/fast` 僅在使用快速模式在其 [`--settings`](/zh-TW/cli-reference#cli-flags) 值中啟動的工作階段中工作，例如 `claude -p --settings '{"fastMode": true}'`；切換然後僅適用於目前工作階段且不會儲存為您的預設值，在任何其他非互動工作階段中命令報告快速模式不可用。需要 Claude Code v2.1.205 或更新版本 |

84| `/fewer-permission-prompts` | **[Skill](/zh-TW/skills#bundled-skills).** 掃描您的記錄以查找常見的唯讀 Bash 和 MCP 工具呼叫，然後將優先允許清單添加到專案 `.claude/settings.json` 以減少權限提示 |84| `/fewer-permission-prompts` | **[Skill](/zh-TW/skills#bundled-skills).** 掃描您的記錄以查找常見的唯讀 Bash 和 MCP 工具呼叫，然後將優先允許清單添加到專案 `.claude/settings.json` 以減少權限提示 |

85| `/focus` | 切換焦點檢視，僅顯示您的最後一個提示、帶有編輯 diffstats 的單行工具呼叫摘要和最終回應。{/* min-version: 2.1.198 */}自 v2.1.198 起，工具呼叫摘要也會計算在回合中啟動的 subagents 數量，並將已完成的背景工作通知折疊為單一計數。選擇在工作階段之間保持；設定設定中的 [`viewMode`](/zh-TW/settings#available-settings) 以覆蓋它。僅在[全螢幕渲染](/zh-TW/fullscreen)中可用 |85| `/focus` | 切換焦點檢視，僅顯示您的最後一個提示、帶有編輯 diffstats 的單行工具呼叫摘要和最終回應。{/* min-version: 2.1.198 */}自 v2.1.198 起，工具呼叫摘要也會計算在回合中啟動的 subagents 數量，並將已完成的背景工作通知折疊為單一計數。選擇在工作階段之間保持；設定設定中的 [`viewMode`](/zh-TW/settings#available-settings) 以覆蓋它。僅在[全螢幕渲染](/zh-TW/fullscreen)中可用 |

99| `/loop [interval] [prompt]` | **[Skill](/zh-TW/skills#bundled-skills).** 在工作階段保持開啟時重複執行提示。省略間隔，Claude 會在迭代之間自動調整步調。省略提示，[如果可用](/zh-TW/scheduled-tasks#run-the-built-in-maintenance-prompt)Claude 運行自主維護檢查或 `.claude/loop.md` 中的提示。示例：`/loop 5m check if the deploy finished`。請參閱[按計劃運行提示](/zh-TW/scheduled-tasks)。別名：`/proactive` |99| `/loop [interval] [prompt]` | **[Skill](/zh-TW/skills#bundled-skills).** 在工作階段保持開啟時重複執行提示。省略間隔，Claude 會在迭代之間自動調整步調。省略提示，[如果可用](/zh-TW/scheduled-tasks#run-the-built-in-maintenance-prompt)Claude 運行自主維護檢查或 `.claude/loop.md` 中的提示。示例：`/loop 5m check if the deploy finished`。請參閱[按計劃運行提示](/zh-TW/scheduled-tasks)。別名：`/proactive` |

100| `/mcp [reconnect <server>\|enable\|disable [<server>\|all]]` | 管理 MCP 伺服器連線和 OAuth 驗證。不帶引數執行以開啟互動式清單，傳遞 `reconnect <server>` 以重新連接一個已斷開連接的伺服器，或傳遞 `enable`/`disable` 與伺服器名稱或 `all` 以在不開啟對話框的情況下變更連接狀態 |100| `/mcp [reconnect <server>\|enable\|disable [<server>\|all]]` | 管理 MCP 伺服器連線和 OAuth 驗證。不帶引數執行以開啟互動式清單，傳遞 `reconnect <server>` 以重新連接一個已斷開連接的伺服器，或傳遞 `enable`/`disable` 與伺服器名稱或 `all` 以在不開啟對話框的情況下變更連接狀態。{/* min-version: 2.1.205 */}也可在非互動模式（`-p`）中使用，其中不帶引數執行時列印伺服器狀態的文字摘要而不是開啟清單；需要 Claude Code v2.1.205 或更新版本 |

103| `/model [model]` | 切換 AI 模型並將其儲存為新工作階段的預設值。對於支援此功能的模型，使用左/右箭頭以[調整努力程度](/zh-TW/model-config#adjust-effort-level)。不帶引數時，開啟選擇器；在列上按 `s` 以僅為目前工作階段切換。當對話有先前輸出時，選擇器會要求確認，因為下一個回應會重新讀取完整歷史記錄而不使用快取上下文。確認後，變更立即應用，無需等待目前回應完成 |103| `/model [model]` | 切換 AI 模型並將其儲存為新工作階段的預設值。對於支援此功能的模型，使用左/右箭頭以[調整努力程度](/zh-TW/model-config#adjust-effort-level)。不帶引數時，開啟選擇器；在列上按 `s` 以僅為目前工作階段切換。當對話有先前輸出時，選擇器會要求確認，因為下一個回應會重新讀取完整歷史記錄而不使用快取上下文。確認後，變更立即應用，無需等待目前回應完成。{/* min-version: 2.1.205 */}也可在非互動模式（`-p`）中使用模型引數而不是選擇器，其中它僅適用於目前工作階段且不會儲存為您的預設值；需要 Claude Code v2.1.205 或更新版本 |

105| `/permissions` | 管理工具權限的允許、詢問和拒絕規則。開啟互動式對話框，您可以按範圍檢視規則、添加或移除規則、管理工作目錄，以及檢視[最近的自動模式拒絕](/zh-TW/auto-mode-config#review-denials)。別名：`/allowed-tools` |105| `/permissions` | 管理工具權限的允許、詢問和拒絕規則。開啟互動式對話框，您可以按範圍檢視規則、添加或移除規則、管理工作目錄，以及檢視[最近的自動模式拒絕](/zh-TW/auto-mode-config#review-denials)。別名：`/allowed-tools` |

109| `/pr-comments [PR]` | {/* max-version: 2.1.90 */}在 v2.1.91 中移除。直接詢問 Claude 以查看 pull request 評論。在較早的版本上，從 GitHub pull request 擷取並顯示評論；自動偵測目前分支的 PR，或傳遞 PR URL 或編號。需要 `gh` CLI |109| `/pr-comments [PR]` | {/* max-version: 2.1.90 */}在 v2.1.91 中移除。直接詢問 Claude 以查看 pull request 評論。在較早的版本上，從 GitHub pull request 擷取並顯示評論；自動偵測目前分支的 PR，或傳遞 PR URL 或編號。需要 `gh` CLI |

114| `/reload-plugins [--force]` | 重新載入所有作用中的 [plugins](/zh-TW/plugins) 以套用待處理的變更，無需重新啟動。報告每個已重新載入的元件的計數，並標記任何載入錯誤。當重新載入會變更載入的 MCP 工具並使提示快取失效時，命令會警告並跳過，除非您傳遞 `--force` |114| `/reload-plugins [--force]` | 重新載入所有作用中的 [plugins](/zh-TW/plugins) 以套用待處理的變更，無需重新啟動。報告每個已重新載入的元件的計數，並標記任何載入錯誤。當重新載入會變更載入的 MCP 工具並使提示快取失效時，命令會警告並跳過，除非您傳遞 `--force` |

115| `/reload-skills` | {/* min-version: 2.1.152 */}重新掃描 [skill](/zh-TW/skills) 和命令目錄，以便在工作階段期間添加或更改的 skills 在磁碟上變得可用，無需重新啟動。報告有多少 skills 可用以及添加或移除了多少 |115| `/reload-skills` | {/* min-version: 2.1.152 */}重新掃描 [skill](/zh-TW/skills) 和命令目錄，以便在工作階段期間添加或更改的 skills 在磁碟上變得可用，無需重新啟動。報告有多少 skills 可用以及添加或移除了多少 |

118| `/rename [name]` | 重新命名目前的工作階段並在提示列上顯示名稱。不使用名稱時，從對話歷史記錄自動產生名稱 |118| `/rename [name]` | 重新命名目前的工作階段並在提示列上顯示名稱。不使用名稱時，從對話歷史記錄自動產生名稱。{/* min-version: 2.1.205 */}也可在非互動模式（`-p`）中使用；需要 Claude Code v2.1.205 或更新版本 |

120| `/review [PR]` | 使用與 `/code-review` 相同的審閱引擎按編號審閱 GitHub pull request。不帶引數時，列出開放的 PR 以供選擇。如需雲端審閱，請參閱 [`/code-review ultra`](/zh-TW/ultrareview) |120| `/review [PR]` | {/* min-version: 2.1.202 */}按編號執行 GitHub pull request 的快速單次通過、唯讀審閱。不帶引數時，列出開放的 PR 以供選擇；PR 編號後的文字成為額外的審閱指示。從 v2.1.186 到 v2.1.201，`/review` 改為運行與 `/code-review medium` 相同的多 agent 引擎。如需選定努力程度的多 agent 審閱，請使用 [`/code-review <level> <pr#>`](/zh-TW/code-review#review-a-diff-locally)；如需雲端審閱，請參閱 [`/code-review ultra`](/zh-TW/ultrareview) |

122| `/run` | **[Skill](/zh-TW/skills#bundled-skills).** 啟動並驅動您的專案應用程式以查看在執行中的應用程式中工作的變更，而不僅僅是在測試中。請參閱[運行並驗證您的應用程式](/zh-TW/skills#run-and-verify-your-app)。{/* min-version: 2.1.145 */}需要 Claude Code v2.1.145 或更新版本 |122| `/run` | **[Skill](/zh-TW/skills#bundled-skills).** 啟動並驅動您的專案應用程式以查看在執行中的應用程式中工作的變更，而不僅僅是在測試中。請參閱[運行並驗證您的應用程式](/zh-TW/skills#run-and-verify-your-app)。{/* min-version: 2.1.145 */}需要 Claude Code v2.1.145 或更新版本 |

123| `/run-skill-generator` | **[Skill](/zh-TW/skills#bundled-skills).** 通過從乾淨環境編寫每個專案的 [skill](/zh-TW/skills#run-and-verify-your-app)，教導 `/run` 和 `/verify` 如何構建、啟動和驅動您的專案應用程式。{/* min-version: 2.1.145 */}需要 Claude Code v2.1.145 或更新版本 |123| `/run-skill-generator` | **[Skill](/zh-TW/skills#bundled-skills).** 通過從乾淨環境編寫每個專案的 [skill](/zh-TW/skills#run-and-verify-your-app)，教導 `/run` 和 `/verify` 如何構建、啟動和驅動您的專案應用程式。{/* min-version: 2.1.145 */}需要 Claude Code v2.1.145 或更新版本 |

125| `/schedule [description]` | 建立、更新、列出或執行[例行工作](/zh-TW/routines)，在 Anthropic 管理的雲端基礎設施上執行。Claude 會以對話方式引導您完成設定。別名：`/routines` |125| `/schedule [description]` | 建立、更新、列出或執行[例行工作](/zh-TW/routines)，在 Anthropic 管理的雲端基礎設施上執行。Claude 會以對話方式引導您完成設定。別名：`/routines` |

126| `/scroll-speed` | 以互動方式調整滑鼠滾輪[捲動速度](/zh-TW/fullscreen#mouse-wheel-scrolling)，使用尺標，您可以在對話框開啟時捲動以預覽變更。僅在[全螢幕渲染](/zh-TW/fullscreen)中可用，在 JetBrains IDE 終端機中不可用 |126| `/scroll-speed` | 以互動方式調整滑鼠滾輪[捲動速度](/zh-TW/fullscreen#mouse-wheel-scrolling)，使用尺標，您可以在對話框開啟時捲動以預覽變更。僅在[全螢幕渲染](/zh-TW/fullscreen)中可用，在 JetBrains IDE 終端機中不可用 |

128| `/setup-bedrock` | 通過互動式精靈配置 [Amazon Bedrock](/zh-TW/amazon-bedrock) 驗證、區域和模型釘選。僅在設定 `CLAUDE_CODE_USE_BEDROCK=1` 時可見。首次 Bedrock 使用者也可以從登入螢幕訪問此精靈 |128| `/setup-bedrock` | 通過互動式精靈配置 [Amazon Bedrock](/zh-TW/amazon-bedrock) 驗證、區域和模型釘選。僅在設定 `CLAUDE_CODE_USE_BEDROCK=1` 時可見。首次 Amazon Bedrock 使用者也可以從登入螢幕訪問此精靈 |

129| `/setup-vertex` | 通過互動式精靈配置 [Google Vertex AI](/zh-TW/google-vertex-ai) 驗證、專案、區域和模型釘選。僅在設定 `CLAUDE_CODE_USE_VERTEX=1` 時可見。首次 Vertex AI 使用者也可以從登入螢幕訪問此精靈 |129| `/setup-vertex` | 通過互動式精靈配置 [Google Cloud 的 Agent Platform](/zh-TW/google-vertex-ai) 驗證、專案、區域和模型釘選。僅在設定 `CLAUDE_CODE_USE_VERTEX=1` 時可見。首次 Google Cloud 的 Agent Platform 使用者也可以從登入螢幕訪問此精靈 |

130| `/simplify [target]` | {/* min-version: 2.1.154 */}**[Skill](/zh-TW/skills#bundled-skills).** 審閱變更的程式碼以查找清理機會並應用修復。四個審閱 [agents](/zh-TW/sub-agents) 並行運行，涵蓋現有幫助程式的重用、簡化、效率和變更是否位於正確的抽象層級。從 v2.1.154 開始，審閱不尋找正確性錯誤。使用 `/code-review` 查找錯誤。在較早的版本上，`/simplify` 等同於 `/code-review --fix`。傳遞路徑或 PR 參考以審閱特定目標 |130| `/simplify [target]` | {/* min-version: 2.1.154 */}**[Skill](/zh-TW/skills#bundled-skills).** 審閱變更的程式碼以查找清理機會並應用修復。四個審閱 [agents](/zh-TW/sub-agents) 並行運行，涵蓋現有幫助程式的重用、簡化、效率和變更是否位於正確的抽象層級。從 v2.1.154 開始，審閱不尋找正確性錯誤。使用 `/code-review` 查找錯誤。在較早的版本上，`/simplify` 等同於 `/code-review --fix`。傳遞路徑或 PR 參考以審閱特定目標 |

131| `/skills` | 列出可用的 [skills](/zh-TW/skills)。{/* min-version: 2.1.121 */}自 v2.1.121 起，輸入以按名稱篩選清單。按 `t` 按 token 計數排序。按 `Space` 以[從 Claude 或 `/` 選單隱藏 skill](/zh-TW/skills#override-skill-visibility-from-settings)，然後按 `Enter` 以儲存 |131| `/skills` | 列出可用的 [skills](/zh-TW/skills)。{/* min-version: 2.1.121 */}自 v2.1.121 起，輸入以按名稱篩選清單。按 `t` 按 token 計數排序。按 `Space` 以[從 Claude 或 `/` 選單隱藏 skill](/zh-TW/skills#override-skill-visibility-from-settings)，然後按 `Enter` 以儲存 |

144| `/ultrareview [PR]` | 在雲端沙箱中使用 [ultrareview](/zh-TW/ultrareview) 運行深度、多 agent 程式碼審閱。首選的調用現在是 `/code-review ultra`，`/ultrareview` 保留為別名。Pro 和 Max 上包括 3 次免費執行，然後需要[使用額度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |144| `/ultrareview [PR]` | 在雲端沙箱中使用 [ultrareview](/zh-TW/ultrareview) 運行深度、多 agent 程式碼審閱。首選的調用現在是 `/code-review ultra`，`/ultrareview` 保留為別名。Pro 和 Max 上包括 3 次免費執行，然後需要[使用額度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |

146| `/usage` | 顯示工作階段成本、方案使用限制和活動統計資訊。在 Pro、Max、Team 或 Enterprise 方案上，包括按 skill、subagent、plugin 和 MCP 伺服器的使用情況分解。請參閱[成本追蹤指南](/zh-TW/costs#using-the-%2Fusage-command)以了解詳細資訊。`/cost` 和 `/stats` 是別名 |146| `/usage` | 顯示工作階段成本、方案使用限制和活動統計資訊。在 Pro、Max、Team 或 Enterprise 方案上，包括按 skill、subagent、plugin 和 MCP 伺服器的使用情況分解。請參閱[成本追蹤指南](/zh-TW/costs#using-the-%2Fusage-command)以了解詳細資訊。`/cost` 和 `/stats` 是別名 |

147| `/usage-credits` | 配置使用量額度以在達到限制時繼續工作。先前為 `/extra-usage` |147| `/usage-credits` | 配置使用量額度以在達到限制時繼續工作。開啟使用量額度計費頁面在您的瀏覽器中。{/* min-version: 2.1.205 */}當沒有瀏覽器可以開啟時，例如透過 SSH，命令改為列印要訪問的 URL；這需要 Claude Code v2.1.205 或更新版本，較早的版本在該情況下顯示任何內容。先前為 `/extra-usage` |

148| `/verify` | **[Skill](/zh-TW/skills#bundled-skills).** 通過構建您的專案應用程式、運行它並觀察結果來確認程式碼變更是否執行了應該執行的操作，而不是依賴測試或類型檢查。請參閱[運行並驗證您的應用程式](/zh-TW/skills#run-and-verify-your-app)。{/* min-version: 2.1.145 */}需要 Claude Code v2.1.145 或更新版本 |148| `/verify` | **[Skill](/zh-TW/skills#bundled-skills).** 通過構建您的專案應用程式、運行它並觀察結果來確認程式碼變更是否執行了應該執行的操作，而不是依賴測試或類型檢查。請參閱[運行並驗證您的應用程式](/zh-TW/skills#run-and-verify-your-app)。{/* min-version: 2.1.145 */}需要 Claude Code v2.1.145 或更新版本 |

149| `/vim` | {/* max-version: 2.1.91 */}在 v2.1.92 中移除。若要在 Vim 和一般編輯模式之間切換，請使用 `/config` → Editor mode |149| `/vim` | {/* max-version: 2.1.91 */}在 v2.1.92 中移除。若要在 Vim 和一般編輯模式之間切換，請使用 `/config` → Editor mode |

150| `/voice [hold\|tap\|off]` | 切換[語音聽寫](/zh-TW/voice-dictation)，或在特定模式下啟用它。需要 Claude.ai 帳戶 |150| `/voice [hold\|tap\|off]` | 切換[語音聽寫](/zh-TW/voice-dictation)，或在特定模式下啟用它。需要 Claude.ai 帳戶 |

common-workflows.md +1 −1

Details

255 </Step>255 </Step>

256</Steps>256</Steps>

257 257

258當您使用 `gh pr create` 建立 PR 時，會話會自動連結到該 PR。要稍後返回它，請執行 `claude --from-pr <number>` 或將 PR URL 貼到[`/resume` 選擇器](/zh-TW/sessions#use-the-session-picker)搜尋中。258當您使用 `gh pr create` 建立 PR 時，會話會自動連結到該 PR。要稍後返回它，請執行 `claude --from-pr 123`，將 123 替換為 PR 編號，或將 PR URL 貼到[`/resume` 選擇器](/zh-TW/sessions#use-the-session-picker)搜尋中。

259 259

260<Tip>260<Tip>

261 在提交前檢查 Claude 產生的 PR，並要求 Claude 突出顯示潛在的風險或考慮事項。261 在提交前檢查 Claude 產生的 PR，並要求 Claude 突出顯示潛在的風險或考慮事項。

communications-kit.md +2 −3

Details

277 277

278有時您希望 Claude 在每次編輯前請求許可。有時您只是希望它發貨。您不應該永遠選擇一個。278有時您希望 Claude 在每次編輯前請求許可。有時您只是希望它發貨。您不應該永遠選擇一個。

279 279

280*Shift+Tab* 循環通過 Claude 獲得多少自由度：*default* 在風險操作前請求，*acceptEdits* 讓檔案編輯和常見檔案系統命令流通，同時仍在其他 shell 命令前檢查，*plan* 在觸及任何東西前為您的批准提議變更。Plan 模式是信任建立者，因此對於觸及多個檔案的任何事情，從那裡開始。280*Shift+Tab* 循環通過 Claude 可以做多少而不需要詢問：*Manual*（`default` 設定值）在每個動作前詢問，*acceptEdits* 讓檔案編輯和常見檔案系統命令流通，同時仍在其他 shell 命令前檢查，*plan* 在觸及任何東西前為您的批准提議變更。Plan 模式是信任建立者，因此對於觸及多個檔案的任何事情，從那裡開始。

281 281

282*現在嘗試：* 在您的下一個重構上，按 Shift+Tab 直到您看到「plan」，282*現在嘗試：* 在您的下一個重構上，按 Shift+Tab 直到您看到「plan」，然後描述變更。您將在單個檔案移動前獲得完整提案。

283然後描述變更。您將在單個檔案移動前獲得完整提案。

284 283

285📖 Permission modes → https://code.claude.com/docs/zh-TW/permissions284📖 Permission modes → https://code.claude.com/docs/zh-TW/permissions

286```285```

computer-use.md +1 −1

Details

239* 您在 macOS 上。Computer use 在 CLI 中不適用於 Linux 或 Windows。在 Windows 上，請改用 [Desktop 中的 computer use](/zh-TW/desktop#let-claude-use-your-computer)。239* 您在 macOS 上。Computer use 在 CLI 中不適用於 Linux 或 Windows。在 Windows 上，請改用 [Desktop 中的 computer use](/zh-TW/desktop#let-claude-use-your-computer)。

240* 您執行的是 Claude Code v2.1.85 或更新版本。執行 `claude --version` 以檢查。240* 您執行的是 Claude Code v2.1.85 或更新版本。執行 `claude --version` 以檢查。

241* 您在 Pro 或 Max 方案上。執行 `/status` 以確認您的訂閱。241* 您在 Pro 或 Max 方案上。執行 `/status` 以確認您的訂閱。

242* 您透過 claude.ai 進行身份驗證。Computer use 不適用於 Amazon Bedrock、Google Cloud Vertex AI 或 Microsoft Foundry 等第三方提供者。如果您完全透過第三方提供者存取 Claude，您需要單獨的 claude.ai 帳戶才能使用此功能。242* 您透過 claude.ai 進行身份驗證。Computer use 不適用於 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 等第三方提供者。如果您完全透過第三方提供者存取 Claude，您需要單獨的 claude.ai 帳戶才能使用此功能。

243* 您在互動式工作階段中。Computer use 在使用 `-p` 旗標的非互動式模式中不可用。243* 您在互動式工作階段中。Computer use 在使用 `-p` 旗標的非互動式模式中不可用。

244 244

245<h2 id="see-also">245<h2 id="see-also">

costs.md +1 −1

Details

51 對於具有自訂速率限制的組織，此工作區中的 Claude Code 流量計入您的組織整體 API 速率限制。您可以在 Claude Console 的此工作區的「限制」頁面上設定[工作區速率限制](https://platform.claude.com/docs/zh-TW/api/rate-limits#setting-lower-limits-for-workspaces)，以限制 Claude Code 的份額並保護其他生產工作負載。51 對於具有自訂速率限制的組織，此工作區中的 Claude Code 流量計入您的組織整體 API 速率限制。您可以在 Claude Console 的此工作區的「限制」頁面上設定[工作區速率限制](https://platform.claude.com/docs/zh-TW/api/rate-limits#setting-lower-limits-for-workspaces)，以限制 Claude Code 的份額並保護其他生產工作負載。

52</Note>52</Note>

53 53

54在 Bedrock、Vertex 和 Foundry 上，Claude Code 不會從您的雲端傳送指標。自託管的 [Claude apps gateway](/zh-TW/claude-apps-gateway) 提供每位使用者的使用情況歸因、包含 token 計數的 OTLP 指標，以及這些提供者上的[每位使用者支出限制](/zh-TW/claude-apps-gateway-spend-limits)。透過不同 [LLM gateway](/zh-TW/llm-gateway) 路由 Claude Code 的組織可以改為在 gateway 追蹤支出，因為它會看到每個請求。54在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，Claude Code 不會從您的雲端傳送指標。自託管的 [Claude apps gateway](/zh-TW/claude-apps-gateway) 提供每位使用者的使用情況歸因、包含 token 計數的 OTLP 指標，以及這些提供者上的[每位使用者支出限制](/zh-TW/claude-apps-gateway-spend-limits)。透過不同 [LLM gateway](/zh-TW/llm-gateway) 路由 Claude Code 的組織可以改為在 gateway 追蹤支出，因為它會看到每個請求。

55 55

56<h3 id="rate-limit-recommendations">56<h3 id="rate-limit-recommendations">

57 速率限制建議57 速率限制建議

data-usage.md +8 −8

Details

23 開發者合作夥伴計畫23 開發者合作夥伴計畫

24</h3>24</h3>

25 25

26如果您明確選擇加入向我們提供訓練材料的方法，例如透過[開發者合作夥伴計畫](https://support.claude.com/en/articles/11174108-about-the-development-partner-program)，我們可能會使用所提供的材料來訓練我們的模型。組織管理員可以明確選擇為其組織加入開發者合作夥伴計畫。請注意，此計畫僅適用於 Anthropic 第一方 API，不適用於 Bedrock 或 Vertex 使用者。26如果您明確選擇加入向我們提供訓練材料的方法，例如透過[開發者合作夥伴計畫](https://support.claude.com/en/articles/11174108-about-the-development-partner-program)，我們可能會使用所提供的材料來訓練我們的模型。組織管理員可以明確選擇為其組織加入開發者合作夥伴計畫。請注意，此計畫僅適用於 Anthropic 第一方 API，不適用於 Amazon Bedrock 或 Google Cloud 的 Agent Platform 使用者。

27 27

28<h3 id="feedback-using-the-/feedback-command">28<h3 id="feedback-using-the-/feedback-command">

29 使用 `/feedback` 命令的回饋29 使用 `/feedback` 命令的回饋

39 39

40在評分提示之後，您可能會看到一個單獨的後續提問「Anthropic 可以查看您的工作階段文字記錄以幫助我們改進 Claude Code 嗎？」。這是一個與評分不同的可選第二步：40在評分提示之後，您可能會看到一個單獨的後續提問「Anthropic 可以查看您的工作階段文字記錄以幫助我們改進 Claude Code 嗎？」。這是一個與評分不同的可選第二步：

41 41

42* **是**：將您的對話文字記錄、任何子代理文字記錄和磁碟中的原始工作階段日誌檔案上傳至 Anthropic。已知的 API 金鑰和權杖模式在上傳前會被編輯。原始程式碼、檔案內容和其他對話內容會按原樣上傳。共享的文字記錄會保留最多 6 個月。在 Bedrock、Vertex AI、Foundry 和已登入的 [Claude apps gateway](/zh-TW/claude-apps-gateway) 工作階段上，是會將相同的承載寫入 `~/.claude/feedback-bundles/` 下的本機封存，而不是上傳；在您轉發該檔案之前，沒有任何內容會離開您的機器。42* **是**：將您的對話文字記錄、任何子代理文字記錄和磁碟中的原始工作階段日誌檔案上傳至 Anthropic。已知的 API 金鑰和權杖模式在上傳前會被編輯。原始程式碼、檔案內容和其他對話內容會按原樣上傳。共享的文字記錄會保留最多 6 個月。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和已登入的 [Claude apps gateway](/zh-TW/claude-apps-gateway) 工作階段上，是會將相同的承載寫入 `~/.claude/feedback-bundles/` 下的本機封存，而不是上傳；在您轉發該檔案之前，沒有任何內容會離開您的機器。

43* **否**：拒絕而不發送任何內容43* **否**：拒絕而不發送任何內容

44* **不再詢問**：拒絕並停止此後續提問在未來工作階段中出現44* **不再詢問**：拒絕並停止此後續提問在未來工作階段中出現

45 45

90靜止時的加密取決於您的模型提供者：90靜止時的加密取決於您的模型提供者：

91 91

92| 提供者 | 靜止時加密 |92| 提供者 | 靜止時加密 |

~~93| ---------------------- | --------------------------------------------------------------------- |~~93| ----------------------------- | --------------------------------------------------------------------- |

94| Anthropic API | 基礎設施層級磁碟加密 (AES-256)。啟用[零資料保留](/zh-TW/zero-data-retention)以避免伺服器端持久化。 |94| Anthropic API | 基礎設施層級磁碟加密 (AES-256)。啟用[零資料保留](/zh-TW/zero-data-retention)以避免伺服器端持久化。 |

95| Amazon Bedrock | AES-256 搭配 AWS 管理的金鑰。客戶管理的金鑰可透過 AWS KMS 取得。 |95| Amazon Bedrock | AES-256 搭配 AWS 管理的金鑰。客戶管理的金鑰可透過 AWS KMS 取得。 |

~~96| Google Cloud Vertex AI | Google 管理的加密金鑰。CMEK 可用。 |~~96| Google Cloud 的 Agent Platform | Google 管理的加密金鑰。CMEK 可用。 |

97| Microsoft Foundry | 請求路由到 Anthropic 基礎設施，具有 AES-256 磁碟加密。 |97| Microsoft Foundry | 請求路由到 Anthropic 基礎設施，具有 AES-256 磁碟加密。 |

98 98

99Claude Code 建立在 Anthropic 的 API 上。有關 API 安全控制的詳細資訊，包括 API 記錄程序，請參閱 [Anthropic 信任中心](https://trust.anthropic.com)中的合規性文件。99Claude Code 建立在 Anthropic 的 API 上。有關 API 安全控制的詳細資訊，包括 API 記錄程序，請參閱 [Anthropic 信任中心](https://trust.anthropic.com)中的合規性文件。

121 121

122當使用者執行 `/feedback` 命令時，他們的完整對話歷史記錄（包括程式碼）的副本會發送到 Anthropic。在提交前，使用者可以選擇要包含多少歷史記錄：僅限目前工作階段（預設值），或也包括同一專案在過去 24 小時或 7 天內的其他工作階段。資料在傳輸中使用 TLS 加密，並儲存在 Google Cloud Storage 中，預設情況下會加密靜止的資料。可選地，在公開儲存庫中建立 GitHub 問題。若要選擇退出，請設定 `DISABLE_FEEDBACK_COMMAND` 環境變數為 `1`。122當使用者執行 `/feedback` 命令時，他們的完整對話歷史記錄（包括程式碼）的副本會發送到 Anthropic。在提交前，使用者可以選擇要包含多少歷史記錄：僅限目前工作階段（預設值），或也包括同一專案在過去 24 小時或 7 天內的其他工作階段。資料在傳輸中使用 TLS 加密，並儲存在 Google Cloud Storage 中，預設情況下會加密靜止的資料。可選地，在公開儲存庫中建立 GitHub 問題。若要選擇退出，請設定 `DISABLE_FEEDBACK_COMMAND` 環境變數為 `1`。

123 123

124當使用者使用第三方提供者（例如 Bedrock 或 Vertex）或未設定 Anthropic 認證時，`/feedback` 會將報告寫入 `~/.claude/feedback-bundles/` 下的本機封存，而不是將其發送到 Anthropic。已知的 API 金鑰和權杖模式在寫入封存前會被編輯。在使用者將該檔案發送給 Anthropic 帳戶代表或將其附加到支援請求之前，任何內容都不會離開使用者的機器。124當使用者使用第三方提供者（例如 Amazon Bedrock 或 Google Cloud 的 Agent Platform）或未設定 Anthropic 認證時，`/feedback` 會將報告寫入 `~/.claude/feedback-bundles/` 下的本機封存，而不是將其發送到 Anthropic。已知的 API 金鑰和權杖模式在寫入封存前會被編輯。在使用者將該檔案發送給 Anthropic 帳戶代表或將其附加到支援請求之前，任何內容都不會離開使用者的機器。

125 125

126<h2 id="default-behaviors-by-api-provider">126<h2 id="default-behaviors-by-api-provider">

127 按 API 提供者的預設行為127 按 API 提供者的預設行為

128</h2>128</h2>

129 129

130根據預設，當使用 Bedrock、Vertex、Foundry 或 Claude Platform on AWS 時，錯誤報告、遙測和錯誤報告會停用。工作階段品質調查和 WebFetch 網域安全檢查是例外，無論提供者為何都會執行。在已登入的 [Claude apps gateway](/zh-TW/claude-apps-gateway) 工作階段上，使用分析、錯誤報告和對 Anthropic 的調查評分會由閘道認證本身停用，沒有重新啟用的設定。您可以透過設定 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 一次選擇退出所有非必要流量，包括調查。此變數不會影響 WebFetch 檢查，該檢查有其自己的選擇退出。以下是完整的預設行為：130根據預設，當使用 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 Claude Platform on AWS 時，錯誤報告、遙測和錯誤報告會停用。工作階段品質調查和 WebFetch 網域安全檢查是例外，無論提供者為何都會執行。在已登入的 [Claude apps gateway](/zh-TW/claude-apps-gateway) 工作階段上，使用分析、錯誤報告和對 Anthropic 的調查評分會由閘道認證本身停用，沒有重新啟用的設定。您可以透過設定 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 一次選擇退出所有非必要流量，包括調查。此變數不會影響 WebFetch 檢查，該檢查有其自己的選擇退出。以下是完整的預設行為：

131 131

133| ------------------------------ | --------------------------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------- |133| ------------------------------ | --------------------------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------- |

139 139

140所有環境變數都可以簽入 `settings.json`（請參閱[設定參考](/zh-TW/settings)）。140所有環境變數都可以簽入 `settings.json`（請參閱[設定參考](/zh-TW/settings)）。

141 141

142自 v2.1.126 起，當主機平台設定 `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` 時，Vertex、Bedrock 和 Foundry 上的指標預設為開啟，並遵循標準 `DISABLE_TELEMETRY` 選擇退出。Sentry 錯誤報告和 `/feedback` 報告在這些提供者上仍預設為關閉。142自 v2.1.126 起，當主機平台設定 `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` 時，Google Cloud 的 Agent Platform、Amazon Bedrock 和 Microsoft Foundry 上的指標預設為開啟，並遵循標準 `DISABLE_TELEMETRY` 選擇退出。Sentry 錯誤報告和 `/feedback` 報告在這些提供者上仍預設為關閉。

143 143

144<h3 id="webfetch-domain-safety-check">144<h3 id="webfetch-domain-safety-check">

145 WebFetch 網域安全檢查145 WebFetch 網域安全檢查

debug-your-config.md +11 −5

Details

19如需特定類別的詳細資訊，請使用專用命令進行後續操作：19如需特定類別的詳細資訊，請使用專用命令進行後續操作：

20 20

21| 命令 | 顯示 |21| 命令 | 顯示 |

~~22| :--------------- | :------------------------------------------------------------------------------------------------------------------------------- |~~22| :--------------- | :------------------------------------------------------------------------------- |

23| `/memory` | 載入了哪些 `CLAUDE.md` 和規則檔案，加上自動記憶項目 |23| `/memory` | 載入了哪些 `CLAUDE.md` 和規則檔案，加上自動記憶項目 |

24| `/skills` | 來自專案、使用者和外掛程式來源的可用 skills |24| `/skills` | 來自專案、使用者和外掛程式來源的可用 skills |

25| `/hooks` | 作用中的 hook 設定 |25| `/hooks` | 作用中的 hook 設定 |

26| `/mcp` | 已連線的 MCP servers 及其狀態 |26| `/mcp` | 已連線的 MCP servers 及其狀態 |

27| `/permissions` | 目前生效的已解析允許和拒絕規則 |27| `/permissions` | 目前生效的已解析允許和拒絕規則 |

28| `/doctor` | 設定診斷：無效的鍵、schema 錯誤、安裝健康狀況。{/* min-version: 2.1.196 */}自 v2.1.196 起，也會報告在同一範圍內定義的重複 [subagent](/zh-TW/sub-agents) 名稱，並標記哪一個是作用中的 |28| `/doctor` | 設定檢查：安裝健康狀況、無效的設定檔案、未使用的擴充功能，以及同一目錄中重複的 [subagent](/zh-TW/sub-agents) 名稱，並提出修復建議 |

29| `/debug [issue]` | 啟用工作階段的偵錯日誌記錄，並提示 Claude 使用日誌輸出和設定路徑進行診斷 |29| `/debug [issue]` | 啟用工作階段的偵錯日誌記錄，並提示 Claude 使用日誌輸出和設定路徑進行診斷 |

30| `/status` | 作用中的設定來源，包括是否啟用了受管設定 |30| `/status` | 作用中的設定來源，包括是否啟用了受管設定 |

31 31

45 45

46設定在受管、使用者、專案和本機範圍之間合併。受管設定在存在時始終優先。在其餘的設定中，較近的範圍會按本機、專案、使用者的順序覆蓋較廣的範圍。某些設定也可以由命令列旗標或 [環境變數](/zh-TW/env-vars) 設定，這些變數充當另一個覆蓋層。當設定似乎不適用時，您設定的值通常被另一個範圍或環境變數覆蓋。46設定在受管、使用者、專案和本機範圍之間合併。受管設定在存在時始終優先。在其餘的設定中，較近的範圍會按本機、專案、使用者的順序覆蓋較廣的範圍。某些設定也可以由命令列旗標或 [環境變數](/zh-TW/env-vars) 設定，這些變數充當另一個覆蓋層。當設定似乎不適用時，您設定的值通常被另一個範圍或環境變數覆蓋。

47 47

~~48執行 `/doctor` 以驗證您的設定檔案並顯示無效的鍵或 schema 錯誤。當 `/doctor` 報告問題時，按 `f` 將診斷報告傳送給 Claude，讓它與您一起逐步進行修正。~~48執行 `/doctor` 以檢查您的設定和安裝。它會報告它發現的內容，包括無效的設定檔案、重複的安裝和未使用的擴充功能，然後提議它在您確認後才會套用的修正。在 v2.1.205 之前，`/doctor` 會開啟唯讀診斷畫面，按 `f` 會將報告傳送給 Claude 以進行修正。

50從終端機，`claude doctor` 會列印唯讀的安裝和設定診斷，而不會啟動工作階段。

49 51

50執行 `/status` 以查看哪些設定來源處於作用中，包括是否啟用了受管設定。若要瞭解給定鍵的哪個範圍優先，請參閱 [範圍如何互動](/zh-TW/settings#how-scopes-interact)。52執行 `/status` 以查看哪些設定來源處於作用中，包括是否啟用了受管設定。若要瞭解給定鍵的哪個範圍優先，請參閱 [範圍如何互動](/zh-TW/settings#how-scopes-interact)。

51 53

67 69

68執行 `/hooks` 以列出為目前工作階段註冊的每個 hook，按事件分組。如果您定義的 hook 沒有出現，則它未被讀取：hooks 位於設定檔案中的 `"hooks"` 鍵下，而不是在獨立檔案中。70執行 `/hooks` 以列出為目前工作階段註冊的每個 hook，按事件分組。如果您定義的 hook 沒有出現，則它未被讀取：hooks 位於設定檔案中的 `"hooks"` 鍵下，而不是在獨立檔案中。

69 71

70如果 hook 出現但不觸發，通常是 matcher 的問題。`matcher` 欄位是一個使用 `|` 匹配多個 tool 名稱的單一字串，例如 `"Edit|Write"`。{/* min-version: 2.1.191 */}在 Claude Code v2.1.191 或更新版本上，`,` 也可作為分隔符，因此 `"Edit,Write"` 等同於 `"Edit|Write"`。在較早的版本上，逗號會進入正規表達式評估，matcher 永遠不會匹配，因此如果您不在 v2.1.191 版本上，請使用 `|`。拼寫錯誤的 tool 名稱會無聲地失敗，原因相同。陣列值是 schema 錯誤：Claude Code 顯示設定錯誤通知，`/doctor` 報告驗證失敗，hook 項目被刪除，因此不會出現在 `/hooks` 中。72如果 hook 出現但不觸發，通常是 matcher 的問題。檢查它是否有這些錯誤：

74* `matcher` 欄位是一個使用 `|` 匹配多個 tool 名稱的單一字串，例如 `"Edit|Write"`。{/* min-version: 2.1.191 */}`,` 分隔符是等效的，因此 `"Edit,Write"` 匹配相同的 tools。在 v2.1.191 之前，逗號會進入正規表達式評估，matcher 永遠不會匹配，因此如果您不在 v2.1.191 版本上，請使用 `|`。

75* 拼寫錯誤的 tool 名稱會產生一個不匹配任何內容的 matcher，因此 hook 會無聲地失敗。

76* 陣列值是 schema 錯誤：Claude Code 顯示設定錯誤通知並拒絕整個使用者、專案或本機設定檔案，`claude doctor` 報告驗證失敗，該檔案中的任何 hook 都不會出現在 `/hooks` 中。在[受管設定](/zh-TW/settings#settings-files)中，只有無效項目被刪除，檔案的其他 hooks 仍然適用。

71 77

72對 `settings.json` 的編輯在短暫的檔案穩定延遲後在執行中的工作階段中生效。您不需要重新啟動。如果在保存後幾秒鐘 `/hooks` 仍顯示舊定義，請再次執行 `/hooks` 以重新整理檢視。78對 `settings.json` 的編輯在短暫的檔案穩定延遲後在執行中的工作階段中生效。您不需要重新啟動。如果在保存後幾秒鐘 `/hooks` 仍顯示舊定義，請再次執行 `/hooks` 以重新整理檢視。

73 79

77 針對乾淨的設定進行測試83 針對乾淨的設定進行測試

78</h2>84</h2>

79 85

80{/* min-version: 2.1.169 */}使用 [`claude --safe-mode`](/zh-TW/cli-reference#cli-flags) 開始，它會啟動一個工作階段，其中所有自訂項目都被停用，包括 `CLAUDE.md`、skills、plugins、hooks、MCP servers 和自訂命令與代理程式。驗證、模型選擇、內建工具和權限正常運作。如果問題在安全模式中消失，則其中一個表面是原因；使用上面的目標檢查來找出是哪一個。由您的組織部署的受管設定仍然部分適用，因此原則配置的 hooks 和狀態列即使在安全模式中也會執行。86{/* min-version: 2.1.169 */}使用 [`claude --safe-mode`](/zh-TW/cli-reference#cli-flags) 開始，它會啟動一個工作階段，其中所有自訂項目都被停用，包括 `CLAUDE.md`、skills、plugins、hooks、MCP servers 和自訂命令與代理程式。驗證、模型選擇、內建工具和權限正常運作。如果問題在安全模式中消失，則其中一個表面是原因；使用上面的目標檢查來找出是哪一個。安全模式仍然會套用來自您組織的受管 hooks 和設定原則。受管 plugins、skills、`CLAUDE.md` 和 MCP servers 會被關閉。

81 87

82如果問題在安全模式中持續存在，或您的設定本身令人懷疑，請與不從您常用設定載入任何內容的工作階段進行比較。將 [`CLAUDE_CONFIG_DIR`](/zh-TW/env-vars) 指向空目錄以略過 `~/.claude` 下的所有內容，並從沒有 `.claude` 資料夾、`.mcp.json` 或 `CLAUDE.md` 的目錄啟動，以便也跳過專案設定。88如果問題在安全模式中持續存在，或您的設定本身令人懷疑，請與不從您常用設定載入任何內容的工作階段進行比較。將 [`CLAUDE_CONFIG_DIR`](/zh-TW/env-vars) 指向空目錄以略過 `~/.claude` 下的所有內容，並從沒有 `.claude` 資料夾、`.mcp.json` 或 `CLAUDE.md` 的目錄啟動，以便也跳過專案設定。

83 89

desktop.md +70 −36

Details

29在 Code 標籤中，每個對話都是一個**會話**：它有自己的聊天歷史記錄、專案資料夾和程式碼變更，獨立於任何其他會話。側邊欄列出您的會話，並讓您並行執行多個會話。在會話中，您可以：29在 Code 標籤中，每個對話都是一個**會話**：它有自己的聊天歷史記錄、專案資料夾和程式碼變更，獨立於任何其他會話。側邊欄列出您的會話，並讓您並行執行多個會話。在會話中，您可以：

30 30

31* [使用差異檢查檢查和評論變更](#review-changes-with-diff-view)，然後[透過 CI 監控產生的 PR](#monitor-pull-request-status)31* [使用差異檢查檢查和評論變更](#review-changes-with-diff-view)，然後[透過 CI 監控產生的 PR](#monitor-pull-request-status)

~~32* [在嵌入式瀏覽器中預覽您執行的應用程式](#preview-your-app)，同時 Claude 驗證其自己的變更~~32* [在瀏覽器窗格中預覽您執行的應用程式](#preview-your-app)，同時 Claude 驗證其自己的變更，並[在其旁邊開啟外部網站](#browse-external-sites)

~~33* [排列窗格](#arrange-your-workspace)，將聊天、差異、預覽、終端機和檔案編輯器並排放置~~33* [排列窗格](#arrange-your-workspace)，將聊天、差異、瀏覽器、終端機和檔案編輯器並排放置

34* 提出[側邊問題](#ask-a-side-question-without-derailing-the-session)，使用會話的內容而不會偏離主題34* 提出[側邊問題](#ask-a-side-question-without-derailing-the-session)，使用會話的內容而不會偏離主題

35* [連接外部工具](#connect-external-tools)，例如 GitHub、Slack 和 Linear35* [連接外部工具](#connect-external-tools)，例如 GitHub、Slack 和 Linear

36* 讓 Claude [開啟應用程式並控制您的螢幕](#let-claude-use-your-computer)36* 讓 Claude [開啟應用程式並控制您的螢幕](#let-claude-use-your-computer)

78 選擇權限模式78 選擇權限模式

79</h3>79</h3>

80 80

81權限模式控制 Claude 在會話期間擁有多少自主權：它是否在編輯檔案、執行命令或兩者之前詢問。您可以隨時使用傳送按鈕旁的模式選擇器切換模式。從「詢問權限」開始，以查看 Claude 確切執行的操作，然後隨著您變得更加熟悉，移至「自動接受編輯」或 Plan mode。81權限模式控制 Claude 在會話期間擁有多少自主權：它是否在編輯檔案、執行命令或兩者之前詢問。您可以隨時使用傳送按鈕旁的模式選擇器切換模式。從「Manual」開始，以查看 Claude 確切執行的操作，然後隨著您變得更加熟悉，移至「Accept edits」或「Plan」。

82 82

83| 模式 | 設定金鑰 | 行為 |83| 模式 | 設定金鑰 | 行為 |

~~84| ------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------- |~~84| ---------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

89| **略過權限** | `bypassPermissions` | Claude 執行時不會有任何權限提示，相當於 CLI 中的 `--dangerously-skip-permissions`。在「設定」→「Claude Code」下的「允許略過權限模式」中啟用。僅在沙箱容器或虛擬機器中使用。企業管理員可以停用此選項。 |89| **Bypass permissions** | `bypassPermissions` | Claude 執行時不會有任何權限提示，除了由明確的[詢問規則](/zh-TW/permissions#manage-permissions)強制執行的提示或當 Claude [在外部網站上執行操作](#browse-external-sites)時由安全分類器強制執行的提示；相當於 CLI 中的 `--dangerously-skip-permissions`。在「設定」→「Claude Code」下的「Allow bypass permissions mode」中啟用。僅在沙箱容器或虛擬機器中使用。企業管理員可以停用此選項。 |

91較早版本的 Code 標籤將這些模式標記為 Ask permissions、Auto accept edits 和 Plan mode。

90 92

91`dontAsk` 權限模式僅在 [CLI](/zh-TW/permission-modes#allow-only-pre-approved-tools-with-dontask-mode) 中可用。93`dontAsk` 權限模式僅在 [CLI](/zh-TW/permission-modes#allow-only-pre-approved-tools-with-dontask-mode) 中可用。

92 94

93<span id="auto-mode-availability" />95<span id="auto-mode-availability" />

94 96

95Auto mode 是在 Anthropic API 上提供給所有使用者的研究預覽版。它需要 Claude Opus 4.6 或更新版本，或 Sonnet 4.6 或更新版本。在路由 Desktop 至 Google Cloud Vertex AI 的企業部署中，Auto mode 預設為關閉，直到您[設定 `CLAUDE_CODE_ENABLE_AUTO_MODE`](/zh-TW/permission-modes#enable-auto-mode-on-bedrock-vertex-ai-or-foundry)，且僅支援 Claude Sonnet 5、Opus 4.7 和 Opus 4.8。97Auto mode 是在 Anthropic API 上提供給所有使用者的研究預覽版，需要 Claude Opus 4.6 或更新版本，或 Sonnet 4.6 或更新版本。在路由 Desktop 至 Google Cloud 的 Agent Platform 的企業部署中，Auto mode 預設為關閉，直到您[設定 `CLAUDE_CODE_ENABLE_AUTO_MODE`](/zh-TW/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)，且僅支援 Claude Sonnet 5、Opus 4.7 和 Opus 4.8。

96 98

97<Tip title="最佳實踐">99<Tip title="最佳實踐">

98 在 Plan mode 中開始複雜任務，以便 Claude 在進行變更之前規劃方法。一旦您批准計畫，切換到'自動接受編輯'或'詢問權限'以執行它。有關此工作流程的更多資訊，請參閱[先探索，然後計畫，然後編碼](/zh-TW/best-practices#explore-first-then-plan-then-code)。100 在 Plan 中開始複雜任務，以便 Claude 在進行變更之前規劃方法。一旦您批准計畫，切換到「Accept edits」或「Manual」以執行它。有關此工作流程的更多資訊，請參閱[先探索，然後計畫，然後編碼](/zh-TW/best-practices#explore-first-then-plan-then-code)。

99</Tip>101</Tip>

100 102

101雲端會話支援'自動接受編輯'、Plan mode 和 Auto mode。'自動接受編輯'對應於 `default` 模式：雲端會話預先批准檔案編輯，因此選擇器顯示'自動接受編輯'而不是'詢問權限'。'略過權限'不可用，因為雲端環境已經是沙箱化的。103雲端會話支援「Accept edits」、「Plan」和「Auto」。「Accept edits」對應於 `default` 模式：雲端會話預先批准檔案編輯，因此選擇器顯示「Accept edits」而不是「Manual」。「Bypass permissions」不可用，因為雲端環境已經是沙箱化的。

102 104

103企業管理員可以限制哪些權限模式可用。有關詳細資訊，請參閱[企業配置](#enterprise-configuration)。105企業管理員可以限制哪些權限模式可用。有關詳細資訊，請參閱[企業配置](#enterprise-configuration)。

104 106

106 預覽您的應用程式108 預覽您的應用程式

107</h3>109</h3>

108 110

109Claude 可以啟動開發伺服器並開啟嵌入式瀏覽器來驗證其變更。這適用於前端網路應用程式以及後端伺服器：Claude 可以測試 API 端點、檢視伺服器日誌，並對其發現的問題進行迭代。在大多數情況下，Claude 在編輯專案檔案後會自動啟動伺服器。您也可以隨時要求 Claude 進行預覽。預設情況下，Claude [自動驗證](#auto-verify-changes)每次編輯後的變更。111Claude 可以啟動開發伺服器並在「Browser」窗格中開啟它以驗證其變更。這適用於前端網路應用程式以及後端伺服器：Claude 可以測試 API 端點、檢視伺服器日誌，並對其發現的問題進行迭代。在大多數情況下，Claude 在編輯專案檔案後會自動啟動伺服器。您也可以隨時要求 Claude 進行預覽。預設情況下，Claude [自動驗證](#auto-verify-changes)每次編輯後的變更。

110 112

111預覽窗格也可以開啟您專案中的靜態 HTML 檔案、PDF、影像和影片。點擊聊天中的 HTML、PDF、影像或影片路徑以在預覽中開啟它。113「Browser」窗格也可以開啟您專案中的靜態 HTML 檔案、PDF、影像和影片。點擊聊天中的 HTML、PDF、影像或影片路徑以在其中開啟它。

112 114

113從預覽窗格，您可以：115從「Browser」窗格，您可以：

114 116

115* 直接在嵌入式瀏覽器中與執行中的應用程式互動117* 直接在「Browser」窗格中與執行中的應用程式互動

116* 觀看 Claude 自動驗證自己的變更：它會擷取螢幕截圖、檢查 DOM、點擊元素、填寫表單，並修復它發現的問題118* 觀看 Claude 自動驗證自己的變更：它會擷取螢幕截圖、檢查 DOM、點擊元素、填寫表單，並修復它發現的問題

117* 從會話工具列中的 **Preview** 下拉式選單啟動或停止伺服器119* 從會話工具列中的伺服器下拉式選單啟動或停止伺服器

118* 透過在下拉式選單中選擇 **Persist sessions**，在伺服器重新啟動時保留 Cookie 和本機儲存，這樣您就不必在開發期間重新登入120* 透過在下拉式選單中選擇 **Persist sessions**，在伺服器重新啟動時保留 Cookie 和本機儲存，這樣您就不必在開發期間重新登入

119* 編輯伺服器配置或一次停止所有伺服器121* 編輯伺服器配置或一次停止所有伺服器

120 122

121Claude 根據您的專案建立初始伺服器配置。如果您的應用程式使用自訂開發命令，請編輯 `.claude/launch.json` 以符合您的設定。有關完整參考，請參閱[配置預覽伺服器](#configure-preview-servers)。123Claude 根據您的專案建立初始伺服器配置。如果您的應用程式使用自訂開發命令，請編輯 `.claude/launch.json` 以符合您的設定。有關完整參考，請參閱[配置預覽伺服器](#configure-preview-servers)。

122 124

123若要清除已儲存的會話資料，請在'設定'→'Claude Code'中切換 **Persist preview sessions** 關閉。若要完全停用預覽，請在'設定'→'Claude Code'中切換 **Preview** 關閉。125若要清除已儲存的會話資料，或完全關閉「Browser」，請使用「設定」→「Claude Code」中的切換開關。

126

127<h3 id="browse-external-sites">

128 瀏覽外部網站

129</h3>

130

131「Browser」窗格是一個分頁瀏覽器，因此您可以在執行中的應用程式旁邊開啟文件、問題追蹤器或任何其他網站。若要開啟「Browser」，請在 macOS 上按 **Cmd+Shift+B** 或在 Windows 上按 **Ctrl+Shift+B**，或從 **Views** 選單中選擇它。當您點擊聊天中的外部連結時，選擇器會提供 **Open in app** 以使用「Browser」窗格或 **Default browser** 以使用您自己的瀏覽器；在 macOS 上按 **Cmd** 點擊或在 Windows 上按 **Ctrl** 點擊會直接在您的系統瀏覽器中開啟連結。您可以登入窗格中的網站，包括彈出式登入流程，例如 Google OAuth。

132

133Claude 可以使用與[驗證您的應用程式](#preview-your-app)相同的工具來讀取和互動外部頁面，並有兩項額外的安全檢查：

134

135* 安全分類器在每個權限模式中檢查 Claude 在外部頁面上的寫入操作，例如點擊和輸入。這些是與[自動模式](#choose-a-permission-mode)相同的分類器，當它們標記操作時，您會收到權限提示，無論模式如何。

136* 在「Auto」和「Bypass permissions」以外的權限模式中，在 Claude 導航到新網站之前，也會應用網域允許清單檢查。

137

138<h4 id="approve-claude’s-actions-on-a-site">

139 批准 Claude 在網站上的操作

140</h4>

141

142Claude 第一次在外部網站上執行操作時，會出現一張權限卡，Claude 會等待您的選擇：**Allow once**、**Always allow** 或 **Deny**。**Allow once** 批准操作而不保存任何內容。**Always allow** 在您的裝置上保存該網站的批准，您可以在「設定」中撤銷它。每個網站都需要自己的批准，包括子網域。您的本機開發伺服器和專案檔案不需要批准，因此[自動驗證](#auto-verify-changes)可以繼續進行而不會出現提示。

143

144即使在已批准的網站上，Claude 也不會在沒有您的輸入的情況下購買商品、建立帳戶或繞過 CAPTCHA。在「Browser」窗格中瀏覽使用與 [Chrome 中的 Claude 擴充功能](/zh-TW/chrome)相同的安全模型。有關 Claude 如何處理敏感網站和危險操作的資訊，請參閱[安全地使用 Chrome 中的 Claude](https://support.claude.com/en/articles/12902428-using-claude-in-chrome-safely)。

145

146<h4 id="choose-between-the-browser-and-the-chrome-extension">

147 在「Browser」和 Chrome 擴充功能之間選擇

148</h4>

149

150「Browser」窗格使用乾淨的瀏覽器設定檔，與您的個人瀏覽器分開，沒有您保存的登入或歷史記錄。使用它來建立和測試您的應用程式，以及不需要您身份的網站。當您想讓 Claude 在您的已登入會話中充當您時，請改用 [Chrome 中的 Claude 擴充功能](/zh-TW/chrome)，它會共享您瀏覽器的登入狀態。

151

152<h4 id="restrict-external-browsing-for-your-organization">

153 限制您的組織的外部瀏覽

154</h4>

155

156「Browser」遵循與 [Chrome 中的 Claude 擴充功能](https://support.claude.com/en/articles/13065128-claude-in-chrome-admin-controls)相同的[網站允許清單和封鎖清單控制](https://support.claude.com/en/articles/13065128-claude-in-chrome-admin-controls)。如果您的組織已經為擴充功能配置了這些清單，「Browser」會自動尊重它們。管理員也可以使用 [`browserExternalPageTools` 受管設定](#managed-settings)關閉外部頁面上的 Claude 工具。停用工具後，使用者仍然可以導航到外部網站；Claude 的工具無法讀取或對其進行操作。

124 157

125<h3 id="review-changes-with-diff-view">158<h3 id="review-changes-with-diff-view">

126 使用差異檢查檢查變更159 使用差異檢視檢查變更

127</h3>160</h3>

128 161

129Claude 對您的程式碼進行變更後，差異檢查可讓您在建立提取請求之前逐個檔案檢查修改。162Claude 對您的程式碼進行變更後，差異檢視可讓您在建立提取請求之前逐個檔案檢查修改。

130 163

131當 Claude 變更檔案時，會出現一個差異統計指示器，顯示新增和移除的行數，例如 `+12 -1`。點擊此指示器以開啟差異檢視器，它在左側顯示檔案清單，在右側顯示每個檔案的變更。164當 Claude 變更檔案時，會出現一個差異統計指示器，顯示新增和移除的行數，例如 `+12 -1`。點擊此指示器以開啟差異檢視器，它在左側顯示檔案清單，在右側顯示每個檔案的變更。

132 165

141 檢查您的程式碼174 檢查您的程式碼

142</h3>175</h3>

143 176

144在差異檢查中，點擊右上角工具列中的 **Review code**，要求 Claude 在您提交之前評估變更。Claude 會檢查目前的差異，並直接在差異檢查中留下註解。您可以回應任何註解或要求 Claude 進行修訂。177在差異檢視中，點擊右上角工具列中的 **Review code**，要求 Claude 在您提交之前評估變更。Claude 會檢查目前的差異，並直接在差異檢視中留下註解。您可以回應任何註解或要求 Claude 進行修訂。

145 178

146檢查著重於高信號問題：編譯錯誤、明確的邏輯錯誤、安全漏洞和明顯的錯誤。它不會標記樣式、格式、預先存在的問題或任何 linter 會捕捉的內容。179檢查著重於高信號問題：編譯錯誤、明確的邏輯錯誤、安全漏洞和明顯的錯誤。它不會標記樣式、格式、預先存在的問題或任何 linter 會捕捉的內容。

147 180

154* **自動修復**：啟用後，Claude 會透過讀取失敗輸出並進行迭代，自動嘗試修復失敗的 CI 檢查。187* **自動修復**：啟用後，Claude 會透過讀取失敗輸出並進行迭代，自動嘗試修復失敗的 CI 檢查。

155* **自動合併**：啟用後，Claude 會在所有檢查通過後合併 PR。合併方法是壓縮。自動合併必須在您的 GitHub 儲存庫設定中[啟用](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository)才能運作。188* **自動合併**：啟用後，Claude 會在所有檢查通過後合併 PR。合併方法是壓縮。自動合併必須在您的 GitHub 儲存庫設定中[啟用](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository)才能運作。

156 189

157使用 CI 狀態列中的 **Auto-fix** 和 **Auto-merge** 切換來啟用任一選項。Claude Code 也會在 CI 完成時傳送桌面通知。若要在 PR 合併或關閉後自動存檔會話，請在'設定'→'Claude Code'中開啟[自動存檔](#work-in-parallel-with-sessions)。190使用 CI 狀態列中的 **Auto-fix** 和 **Auto-merge** 切換來啟用任一選項。Claude Code 也會在 CI 完成時傳送桌面通知。若要在 PR 合併或關閉後自動存檔會話，請在「設定」→「Claude Code」中開啟[自動存檔](#work-in-parallel-with-sessions)。

158 191

159<Note>192<Note>

160 PR 監控需要在您的機器上安裝並驗證 [GitHub CLI (`gh`)](https://cli.github.com/)。如果未安裝 `gh`，Desktop 會在您第一次嘗試建立 PR 時提示您安裝它。193 PR 監控需要在您的機器上安裝並驗證 [GitHub CLI (`gh`)](https://cli.github.com/)。如果未安裝 `gh`，Desktop 會在您第一次嘗試建立 PR 時提示您安裝它。

164 安排您的工作區197 安排您的工作區

165</h2>198</h2>

166 199

167Code 標籤是圍繞您可以以任何佈局排列的窗格構建的：聊天、差異、預覽、終端機、檔案、plan、tasks 和 subagent。透過其標題拖動窗格以重新定位它，或拖動窗格邊緣以調整其大小。在 macOS 上按 **Cmd+\\** 或在 Windows 上按 **Ctrl+\\** 以關閉焦點窗格。從會話工具列中的 **Views** 選單開啟其他窗格。200Code 標籤是圍繞您可以以任何佈局排列的窗格構建的：聊天、差異、瀏覽器、終端機、檔案、plan、tasks 和 subagent。透過其標題拖動窗格以重新定位它，或拖動窗格邊緣以調整其大小。在 macOS 上按 **Cmd+\\** 或在 Windows 上按 **Ctrl+\\** 以關閉焦點窗格。從會話工具列中的 **Views** 選單開啟其他窗格。

168 201

169<Note>202<Note>

170 本節中的窗格佈局、終端機、檔案編輯器和檢視模式需要 Claude Desktop v1.2581.0 或更新版本。在 macOS 上開啟 **Claude → Check for Updates** 或在 Windows 上開啟 **Help → Check for Updates** 以更新。203 本節中的窗格佈局、終端機、檔案編輯器和檢視模式需要 Claude Desktop v1.2581.0 或更新版本。在 macOS 上開啟 **Claude → Check for Updates** 或在 Windows 上開啟 **Help → Check for Updates** 以更新。

180 開啟和編輯檔案213 開啟和編輯檔案

181</h3>214</h3>

182 215

183點擊聊天或差異檢視器中的檔案路徑以在檔案窗格中開啟它。HTML、PDF、影像和影片路徑改為在[預覽窗格](#preview-your-app)中開啟。進行現場編輯並點擊 **Save** 以寫回。如果自您開啟檔案以來檔案在磁碟上已變更，窗格會警告您並讓您覆蓋或放棄。點擊 **Discard** 以還原您的編輯，或點擊窗格標題中的路徑以複製絕對路徑。216點擊聊天或差異檢視器中的檔案路徑以在檔案窗格中開啟它。HTML、PDF、影像和影片路徑改為在[瀏覽器窗格](#preview-your-app)中開啟。進行現場編輯並點擊 **Save** 以寫回。如果自您開啟檔案以來檔案在磁碟上已變更，窗格會警告您並讓您覆蓋或放棄。點擊 **Discard** 以還原您的編輯，或點擊窗格標題中的路徑以複製絕對路徑。

184 217

185檔案窗格在本機和 SSH 會話中可用。對於遠端會話，要求 Claude 進行變更。218檔案窗格在本機和 SSH 會話中可用。對於雲端會話，要求 Claude 進行變更。

186 219

187<h3 id="open-files-in-other-apps">220<h3 id="open-files-in-other-apps">

188 在其他應用程式中開啟檔案221 在其他應用程式中開啟檔案

225| `Esc` | 停止 Claude 的回應 |258| `Esc` | 停止 Claude 的回應 |

230| `Cmd` `\` | 關閉焦點窗格 |263| `Cmd` `\` | 關閉焦點窗格 |

231| `Cmd` `;` | 開啟側邊聊天 |264| `Cmd` `;` | 開啟側邊聊天 |

437 470

438Claude 會自動偵測您的開發伺服器設定，並將配置儲存在您開始會話時選擇的資料夾根目錄中的 `.claude/launch.json`。Preview 使用此資料夾作為其工作目錄，因此如果您選擇了父資料夾，具有自己開發伺服器的子資料夾將不會自動偵測。若要使用子資料夾的伺服器，請直接在該資料夾中開始會話，或手動新增配置。471Claude 會自動偵測您的開發伺服器設定，並將配置儲存在您開始會話時選擇的資料夾根目錄中的 `.claude/launch.json`。Preview 使用此資料夾作為其工作目錄，因此如果您選擇了父資料夾，具有自己開發伺服器的子資料夾將不會自動偵測。若要使用子資料夾的伺服器，請直接在該資料夾中開始會話，或手動新增配置。

439 472

440若要自訂伺服器的啟動方式，例如使用 `yarn dev` 而不是 `npm run dev` 或變更連接埠，請手動編輯檔案或點擊 Preview 下拉式選單中的 **Edit configuration** 以在您的程式碼編輯器中開啟它。該檔案支援帶註解的 JSON。473若要自訂伺服器的啟動方式，例如使用 `yarn dev` 而不是 `npm run dev` 或變更連接埠，請手動編輯檔案或點擊伺服器下拉式選單中的 **Edit configuration** 以在您的程式碼編輯器中開啟它。該檔案支援帶註解的 JSON。

441 474

442```json theme={null}475```json theme={null}

443{476{

461 494

462啟用 `autoVerify` 時，Claude 會在編輯檔案後自動驗證程式碼變更。它會擷取螢幕截圖、檢查錯誤，並在完成回應之前確認變更有效。495啟用 `autoVerify` 時，Claude 會在編輯檔案後自動驗證程式碼變更。它會擷取螢幕截圖、檢查錯誤，並在完成回應之前確認變更有效。

463 496

464自動驗證預設為開啟。透過將 `"autoVerify": false` 新增到 `.claude/launch.json`，或從 **Preview** 下拉式選單切換它，按專案停用它。497自動驗證預設為開啟。透過將 `"autoVerify": false` 新增到 `.claude/launch.json`，或從伺服器下拉式選單切換它，按專案停用它。

465 498

466```json theme={null}499```json theme={null}

467{500{

703| `disableAutoMode` | 設定為 `"disable"` 以防止使用者啟用 [Auto](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 模式。從模式選擇器中移除 Auto。也在 `permissions` 下接受。 |736| `disableAutoMode` | 設定為 `"disable"` 以防止使用者啟用 [Auto](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 模式。從模式選擇器中移除 Auto。也在 `permissions` 下接受。 |

738| `browserExternalPageTools` | 設定為 `"disabled"` 以防止 Claude 使用工具來讀取或作用於[瀏覽器窗格](#browse-external-sites)中的外部頁面。使用者仍然可以自行瀏覽外部網站，本機開發伺服器預覽不受影響。 |

706| `sshHostAllowlist` | 限制 [SSH 會話](#restrict-which-ssh-hosts-users-can-connect-to)連線到已解析主機名稱符合這些模式之一的主機。空陣列會停用 SSH 會話。僅從受管設定讀取。 |740| `sshHostAllowlist` | 限制 [SSH 會話](#restrict-which-ssh-hosts-users-can-connect-to)連線到已解析主機名稱符合這些模式之一的主機。空陣列會停用 SSH 會話。僅從受管設定讀取。 |

707| `managedMcpServers` | 將 MCP 伺服器配置推送到第三方部署中的所有使用者。每個項目指定 `"http"`、`"sse"` 或 `"stdio"` 的傳輸、連線詳細資訊，以及可選的 `toolPolicy` 對應，限制該伺服器中使用者可以叫用的工具。僅在第三方 (3P) Desktop 部署中可用。透過受管設定檔案或 MDM 傳遞此金鑰，因為第三方部署不會收到管理員主控台設定。 |741| `managedMcpServers` | 將 MCP 伺服器配置推送到第三方部署中的所有使用者。每個項目指定 `"http"`、`"sse"` 或 `"stdio"` 的傳輸、連線詳細資訊，以及可選的 `toolPolicy` 對應，限制該伺服器中使用者可以叫用的工具。僅在第三方 (3P) Desktop 部署中可用。透過受管設定檔案或 MDM 傳遞此金鑰，因為第三方部署不會收到管理員主控台設定。 |

754 788

755如果您已經使用 Claude Code CLI，Desktop 執行相同的基礎引擎，具有圖形介面。您可以在同一機器上同時執行兩者，甚至在同一專案上執行。每個都維護單獨的會話歷史記錄，但它們透過 CLAUDE.md 檔案共用配置和專案記憶。789如果您已經使用 Claude Code CLI，Desktop 執行相同的基礎引擎，具有圖形介面。您可以在同一機器上同時執行兩者，甚至在同一專案上執行。每個都維護單獨的會話歷史記錄，但它們透過 CLAUDE.md 檔案共用配置和專案記憶。

756 790

757若要將 CLI 會話移至 Desktop，請在終端機中執行 `/desktop`。Claude 儲存您的會話並在桌面應用程式中開啟它，然後退出 CLI。此命令在 macOS 和 Windows 上可用，當您使用 Claude 訂閱登入時。它不適用於 API 金鑰驗證或 Bedrock、Vertex 或 Foundry。791若要將 CLI 會話移至 Desktop，請在終端機中執行 `/desktop`。Claude 儲存您的會話並在桌面應用程式中開啟它，然後退出 CLI。此命令在 macOS 和 Windows 上可用，當您使用 Claude 訂閱登入時。它不適用於 API 金鑰驗證或 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry。

758 792

759<Tip>793<Tip>

760 何時使用 Desktop 與 CLI：當您想要在一個視窗中管理並行會話、並排排列窗格或視覺化檢查變更時，使用 Desktop。當您需要指令碼、自動化或偏好終端機工作流程時，使用 CLI。794 何時使用 Desktop 與 CLI：當您想要在一個視窗中管理並行會話、並排排列窗格或視覺化檢查變更時，使用 Desktop。當您需要指令碼、自動化或偏好終端機工作流程時，使用 CLI。

804此表比較 CLI 和 Desktop 之間的核心功能。有關 CLI 標誌的完整清單，請參閱 [CLI 參考](/zh-TW/cli-reference)。838此表比較 CLI 和 Desktop 之間的核心功能。有關 CLI 標誌的完整清單，請參閱 [CLI 參考](/zh-TW/cli-reference)。

805 839

806| 功能 | CLI | Desktop |840| 功能 | CLI | Desktop |

807| ----------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |841| ----------------------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

810| [第三方提供者](/zh-TW/third-party-integrations) | Bedrock、Vertex AI、Foundry | Anthropic 的 API 預設。企業部署可以配置 Vertex AI 和閘道提供者。請參閱[企業配置指南](https://support.claude.com/en/articles/12622667-enterprise-configuration)。若要在 Bedrock、Vertex AI、Foundry 或自託管 LLM 閘道上執行 Code 標籤，請參閱 [Cowork on 3P research preview](https://claude.com/docs/cowork/3p/overview)。 |844| [第三方提供者](/zh-TW/third-party-integrations) | Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry | Anthropic 的 API 預設。企業部署可以配置 Google Cloud 的 Agent Platform 和閘道提供者。請參閱[企業配置指南](https://support.claude.com/en/articles/12622667-enterprise-configuration)。若要在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或自託管 LLM 閘道上執行 Code 標籤，請參閱 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)。 |

813| @mention 檔案 | 文字型 | 具有自動完成；本機和 SSH 會話僅 |847| @mention 檔案 | 文字型 | 具有自動完成；本機和 SSH 會話僅 |

825 859

826以下功能僅在 CLI 或 VS Code 擴充功能中可用，除非另有說明：860以下功能僅在 CLI 或 VS Code 擴充功能中可用，除非另有說明：

827 861

828* **第三方提供者**：Desktop 預設連接到 Anthropic 的 API。企業部署可以透過[受管設定](https://support.claude.com/en/articles/12622667-enterprise-configuration)配置 Vertex AI 和閘道提供者。對於 Bedrock 或 Foundry，請參閱 [quickstart](/zh-TW/quickstart)。作為上述部分的例外，[Cowork on 3P research preview](https://claude.com/docs/cowork/3p/overview) 在 Bedrock、Vertex AI、Foundry 或自託管 LLM 閘道上執行 Code 標籤。862* **第三方提供者**：Desktop 預設連接到 Anthropic 的 API。企業部署可以透過[受管設定](https://support.claude.com/en/articles/12622667-enterprise-configuration)配置 Google Cloud 的 Agent Platform 和閘道提供者。對於 Amazon Bedrock 或 Microsoft Foundry，請參閱 [quickstart](/zh-TW/quickstart)。作為上述部分的例外，[Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview) 在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或自託管 LLM 閘道上執行 Code 標籤。

829* **Linux (beta)**：Linux 桌面應用程式中尚未提供電腦使用。請參閱 [Claude Desktop on Linux](/zh-TW/desktop-linux)。863* **Linux (beta)**：Linux 桌面應用程式中尚未提供電腦使用。請參閱 [Claude Desktop on Linux](/zh-TW/desktop-linux)。

830* **內嵌程式碼建議**：Desktop 不提供自動完成樣式的建議。它透過對話提示和明確的程式碼變更進行工作。864* **內嵌程式碼建議**：Desktop 不提供自動完成樣式的建議。它透過對話提示和明確的程式碼變更進行工作。

831* **Agent teams**：平行 Claude Code 會話相互傳遞訊息，可在 [CLI](/zh-TW/agent-teams) 中使用，不在 Desktop 中。若要在一個會話內進行多代理工作，請使用 [dynamic workflows](/zh-TW/workflows)，它們在 Desktop 中執行。865* **Agent teams**：平行 Claude Code 會話相互傳遞訊息，可在 [CLI](/zh-TW/agent-teams) 中使用，不在 Desktop 中。若要在一個會話內進行多代理工作，請使用 [dynamic workflows](/zh-TW/workflows)，它們在 Desktop 中執行。

832* **Terminal-dialog 命令**：在終端機中開啟互動式面板的內建命令，例如 `/permissions`、`/config` 和 `/doctor`，在 Code 標籤中不可用，並回覆 `isn't available in this environment`。直接編輯[設定檔案](/zh-TW/settings)以管理權限規則和配置，或從獨立 CLI 執行命令。866* **Terminal-dialog 命令**：在終端機中開啟互動式面板的內建命令，例如 `/permissions` 和 `/config`，在 Code 標籤中不可用，並回覆 `isn't available in this environment`。`/config` 在您傳遞 `key=value` 時設定設定，例如 `/config theme=dark`；只有其選擇器形式不可用。直接編輯[設定檔案](/zh-TW/settings)以管理權限規則和配置，或從獨立 CLI 執行命令。

833 867

834<h2 id="troubleshooting">868<h2 id="troubleshooting">

835 疑難排解869 疑難排解

desktop-linux.md +26 −2

Details

25 安裝25 安裝

26</h2>26</h2>

27 27

~~28從 Anthropic 的 apt 儲存庫安裝，以便更新透過您系統的定期套件更新到達。~~28從 Anthropic 的 apt 儲存庫安裝，以便更新透過您系統的定期套件更新到達。開啟終端機並執行每個步驟中的命令。

29 29

30<Steps>30<Steps>

31 <Step title="新增 Anthropic 的 apt 儲存庫">31 <Step title="新增 Anthropic 的 apt 儲存庫">

32 此步驟使用 `curl` 下載簽署金鑰，新鮮的 Debian 和 Ubuntu 安裝可能不包含此工具。如果下載命令失敗並顯示 `sudo: curl: command not found`，請先安裝 curl：

34 ```bash theme={null}

35 sudo apt install curl

36 ```

32 下載 Anthropic 的簽署金鑰：38 下載 Anthropic 的簽署金鑰：

33 39

34 ```bash theme={null}40 ```bash theme={null}

69 從下載的檔案安裝75 從下載的檔案安裝

70</h3>76</h3>

71 77

72如果您無法使用 apt 儲存庫，請從 [claude.com/download](https://claude.com/download) 下載適用於您的架構（x64 或 arm64）的 `.deb` 套件，然後使用您的軟體安裝程式開啟它，或從您的下載目錄執行：78如果您無法使用 apt 儲存庫，請先從 [claude.com/download](https://claude.com/download) 下載適用於您的架構（x64 或 arm64）的 `.deb` 套件，然後使用您的軟體安裝程式開啟下載的檔案，或從包含下載檔案的目錄使用 apt 安裝它：

73 79

74```bash theme={null}80```bash theme={null}

75sudo apt install ./claude-desktop_*.deb81sudo apt install ./claude-desktop_*.deb

76```82```

77 83

84如果 apt 報告 `E: Unsupported file ./claude-desktop_*.deb given on commandline`，表示該模式與目前目錄中的 `.deb` 檔案不符。確認下載已完成，然後從包含該檔案的目錄再次執行命令。

78以這種方式安裝的 `.deb` 不會接收更新。若要透過 apt 取得更新，請如上所示新增儲存庫，或取消註解套件寫入 `/etc/apt/sources.list.d/claude-desktop.list` 的預留位置項目中的 `deb` 行。86以這種方式安裝的 `.deb` 不會接收更新。若要透過 apt 取得更新，請如上所示新增儲存庫，或取消註解套件寫入 `/etc/apt/sources.list.d/claude-desktop.list` 的預留位置項目中的 `deb` 行。

79 87

80<h2 id="update">88<h2 id="update">

103sudo rm /etc/apt/sources.list.d/claude-desktop.list111sudo rm /etc/apt/sources.list.d/claude-desktop.list

104```112```

105 113

114<h2 id="troubleshoot">

115 疑難排解

116</h2>

117

118<h3 id="unable-to-locate-package-claude-desktop">

119 無法找到 claude-desktop 套件

120</h3>

121

122如果 `sudo apt install claude-desktop` 失敗並顯示 `E: Unable to locate package claude-desktop`，表示 apt 找不到您新增的儲存庫。請檢查以下項目：

123

124* 確認儲存庫項目已寫入。`cat /etc/apt/sources.list.d/claude-desktop.list` 應該顯示來自[新增 Anthropic 的 apt 儲存庫](#install)步驟的 `deb` 行。如果檔案為空或遺失，請再次執行該步驟。

125* 確認您的架構受支援。`dpkg --print-architecture` 應該列印 `amd64` 或 `arm64`。儲存庫不會為其他架構發佈套件。

126* 再次執行 `sudo apt update` 並檢查其輸出中是否有與 `downloads.claude.ai` 相關的錯誤。該處的網路或金鑰錯誤表示儲存庫已新增但無法連線或驗證。

127

128如果儲存庫已就位且可連線，但仍找不到套件，請改為[從下載的檔案安裝](#install-from-a-downloaded-file)。

129

106<h2 id="what’s-not-in-the-linux-beta-yet">130<h2 id="what’s-not-in-the-linux-beta-yet">

107 Linux 測試版中尚未提供的功能131 Linux 測試版中尚未提供的功能

108</h2>132</h2>

desktop-quickstart.md +8 −4

Details

89 </Step>89 </Step>

90 90

91 <Step title="檢查並接受變更">91 <Step title="檢查並接受變更">

~~92 預設情況下，Code 標籤以 [詢問權限模式](/zh-TW/desktop#choose-a-permission-mode) 啟動，其中 Claude 提出變更並等待您的批准才能應用它們。您將看到：~~92 預設情況下，Code 標籤以 [Manual mode](/zh-TW/desktop#choose-a-permission-mode) 啟動，其中 Claude 提出變更並等待您的批准才能應用它們。您將看到：

93 93

94 1. [差異檢視](/zh-TW/desktop#review-changes-with-diff-view) 顯示每個檔案中將發生的確切變更94 1. [差異檢視](/zh-TW/desktop#review-changes-with-diff-view) 顯示每個檔案中將發生的確切變更

95 2. 接受/拒絕按鈕以批准或拒絕每項變更95 2. 接受/拒絕按鈕以批准或拒絕每項變更

113 113

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

115 115

116**調整您擁有的控制量。** 您的 [權限模式](/zh-TW/desktop#choose-a-permission-mode) 控制平衡。詢問權限（預設）在每次編輯前需要批准。自動接受編輯會自動接受檔案編輯以加快迭代。Plan Mode 讓 Claude 在不觸及任何檔案的情況下規劃方法，這在大型重構前很有用。116**調整您擁有的控制量。** 您的 [權限模式](/zh-TW/desktop#choose-a-permission-mode) 設定 Claude 在不詢問批准的情況下可以執行的操作：

117

118* **Manual**：預設值。Claude 在編輯檔案或執行命令前會詢問。

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

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

117 121

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

119 123

120**排列您的工作區。** 將聊天、差異、終端機、檔案和預覽窗格拖放到您想要的任何佈局中。使用 **Ctrl+\`** 開啟終端機以在您的會話旁執行命令，或點擊檔案路徑以在檔案窗格中開啟它。請參閱 [排列您的工作區](/zh-TW/desktop#arrange-your-workspace)。124**排列您的工作區。** 將聊天、差異、終端機、檔案和瀏覽器窗格拖放到您想要的任何佈局中。使用 **Ctrl+\`** 開啟終端機以在您的會話旁執行命令，或點擊檔案路徑以在檔案窗格中開啟它。請參閱 [排列您的工作區](/zh-TW/desktop#arrange-your-workspace)。

121 125

122**預覽您的應用程式。** 點擊 **Preview** 下拉式選單以直接在桌面中執行您的開發伺服器。Claude 可以檢視執行中的應用程式、測試端點、檢查日誌並對其看到的內容進行迭代。請參閱 [預覽您的應用程式](/zh-TW/desktop#preview-your-app)。126**預覽您的應用程式。** 當您在桌面中執行開發伺服器時，您的應用程式會在瀏覽器窗格中開啟，該窗格也可以 [開啟外部網站](/zh-TW/desktop#browse-external-sites)。Claude 可以檢視執行中的應用程式、測試端點、檢查日誌並對其看到的內容進行迭代。請參閱 [預覽您的應用程式](/zh-TW/desktop#preview-your-app)。

123 127

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

125 129

devcontainer.md +2 −2

Details

75您在身份驗證提示中看到的內容取決於您的提供者：75您在身份驗證提示中看到的內容取決於您的提供者：

76 76

77* **Anthropic**：透過瀏覽器使用您的 Claude 或 Anthropic Console 帳戶登入77* **Anthropic**：透過瀏覽器使用您的 Claude 或 Anthropic Console 帳戶登入

~~78* **[Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry](/zh-TW/third-party-integrations)**：Claude Code 使用您的雲端提供者認證，無需瀏覽器提示~~78* **[Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry](/zh-TW/third-party-integrations)**：Claude Code 使用您的雲端提供者認證，無需瀏覽器提示

79 79

80對於雲端提供者，透過 `containerEnv`、Codespaces 祕密或您的雲端的工作負載身份（而不是從主機掛載認證檔案）將認證傳遞到容器中。請參閱 [Amazon Bedrock](/zh-TW/amazon-bedrock)、[Google Vertex AI](/zh-TW/google-vertex-ai) 或 [Microsoft Foundry](/zh-TW/microsoft-foundry) 以了解 Claude Code 讀取的認證鏈。80對於雲端提供者，透過 `containerEnv`、Codespaces 祕密或您的雲端的工作負載身份（而不是從主機掛載認證檔案）將認證傳遞到容器中。請參閱 [Amazon Bedrock](/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/zh-TW/google-vertex-ai) 或 [Microsoft Foundry](/zh-TW/microsoft-foundry) 以了解 Claude Code 讀取的認證鏈。

81 81

82請參閱[選擇您的 API 提供者](/zh-TW/admin-setup#choose-your-api-provider)以決定哪條路徑適合您的組織。82請參閱[選擇您的 API 提供者](/zh-TW/admin-setup#choose-your-api-provider)以決定哪條路徑適合您的組織。

83 83

discover-plugins.md +11 −2

Details

332* 輸入以按外掛程式名稱或描述篩選332* 輸入以按外掛程式名稱或描述篩選

333* 按 Enter 以開啟外掛程式的詳細檢視並啟用、停用或解除安裝它333* 按 Enter 以開啟外掛程式的詳細檢視並啟用、停用或解除安裝它

334 334

335解除安裝專案的 `.claude/settings.json` 啟用的外掛程式會詢問您指的是哪個範圍：僅為您停用它，這會將覆寫寫入您的 `.claude/settings.local.json` 並為專案保留已安裝的外掛程式，或為所有人解除安裝它，這會將其從共用的 `.claude/settings.json` 中移除。需要 Claude Code v2.1.203 或更新版本。在 v2.1.203 之前，對話框僅提供本機停用選項。

336

335詳細檢視會顯示外掛程式貢獻的元件：commands、skills、agents、hooks、MCP servers 和 LSP servers。相同的清單也可從命令列透過 `claude plugin details` 取得。337詳細檢視會顯示外掛程式貢獻的元件：commands、skills、agents、hooks、MCP servers 和 LSP servers。相同的清單也可從命令列透過 `claude plugin details` 取得。

336 338

337在 Claude Code v2.1.187 及更新版本中，Installed 標籤新增了 **Not used recently** 群組，用於您自己安裝但至少兩週內未叫用且跨越至少 10 個工作階段的 marketplace 外掛程式，詳細檢視會為每個外掛程式顯示 **Last used** 行。使用這些功能來找出您不再使用但仍在增加啟動和內容成本的外掛程式，然後停用或解除安裝它們。339**Installed** 標籤也會收集您自己安裝但至少兩週內未使用且跨越至少 10 個工作階段的 marketplace 外掛程式，位於 **Not used recently** 標題下。詳細檢視會為每個外掛程式顯示 **Last used** 行。使用這些功能來找出您不再使用但仍在增加啟動和內容成本的外掛程式，然後停用或解除安裝它們。需要 Claude Code v2.1.187 或更新版本。

340

341兩種外掛程式永遠不會列為未使用：

342

343* 您的組織管理的外掛程式或您使用 `--plugin-dir` 載入的外掛程式

344* 貢獻 theme、output style、monitor 或 workflow 的外掛程式，因為這些外掛程式提供價值而無需追蹤叫用

345

346當您的組織使用 [`strictKnownMarketplaces`](/zh-TW/settings#strictknownmarketplaces) 限制 marketplaces 時，**Not used recently** 標題和 **Last used** 行都會隱藏。

338 347

339您的組織管理的外掛程式或您使用 `--plugin-dir` 載入的外掛程式永遠不會列為未使用，貢獻 LSP server、theme、output style、monitor 或 workflow 的外掛程式也永遠不會列出，因為這些外掛程式提供價值而無需追蹤叫用。群組和 **Last used** 行在您的組織使用 [`strictKnownMarketplaces`](/zh-TW/settings#strictknownmarketplaces) 限制 marketplaces 時都會隱藏。348外掛程式的 [language server](/zh-TW/plugins#add-lsp-servers-to-your-plugin) 在提供診斷或回答程式碼導覽請求時計為已使用，因此其伺服器在您的工作階段中處於活動狀態的 LSP 外掛程式不會列為未使用。在 v2.1.203 之前，無法將語言伺服器活動計為使用，因此貢獻 LSP 伺服器的外掛程式完全豁免於該群組，與 theme 和 output style 外掛程式的方式相同。

340 349

341當您安裝聲明依賴項的外掛程式時，安裝輸出會列出哪些依賴項與其一起自動安裝。350當您安裝聲明依賴項的外掛程式時，安裝輸出會列出哪些依賴項與其一起自動安裝。

342 351

env-vars.md +52 −50

Details

96</h2>96</h2>

97 97

98| 變數 | 用途 |98| 變數 | 用途 |

99| :------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |99| :------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

100| `ANTHROPIC_API_KEY` | 作為 `X-Api-Key` 標頭發送的 API 金鑰。設定時，即使您已登入，此金鑰也會用於代替您的 Claude Pro、Max、Team 或 Enterprise 訂閱。在非互動式模式（`-p`）中，金鑰存在時始終使用。在互動式模式中，系統會提示您在金鑰覆蓋您的訂閱之前批准一次。若要改用您的訂閱，請執行 `unset ANTHROPIC_API_KEY` |100| `ANTHROPIC_API_KEY` | 作為 `X-Api-Key` 標頭發送的 API 金鑰。設定時，即使您已登入，此金鑰也會用於代替您的 Claude Pro、Max、Team 或 Enterprise 訂閱。在非互動式模式（`-p`）中，金鑰存在時始終使用。在互動式模式中，系統會提示您在金鑰覆蓋您的訂閱之前批准一次。若要改用您的訂閱，請執行 `unset ANTHROPIC_API_KEY` |

102| `ANTHROPIC_AWS_API_KEY` | [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 的工作區 API 金鑰，在 AWS 主控台中產生。作為 `x-api-key` 發送，優先於 AWS SigV4 |102| `ANTHROPIC_AWS_API_KEY` | [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 的工作區 API 金鑰，在 AWS 主控台中產生。作為 `x-api-key` 發送，優先於 AWS SigV4 |

103| `ANTHROPIC_AWS_BASE_URL` | 覆蓋 [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 端點 URL。用於自訂區域或透過 [LLM gateway](/zh-TW/llm-gateway) 路由。預設為 `https://aws-external-anthropic.{AWS_REGION}.api.aws` |103| `ANTHROPIC_AWS_BASE_URL` | 覆蓋 [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 端點 URL。用於自訂區域或透過 [LLM gateway](/zh-TW/llm-gateway) 路由。預設為 `https://aws-external-anthropic.{AWS_REGION}.api.aws` |

104| `ANTHROPIC_AWS_WORKSPACE_ID` | [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 所需。在每個請求上作為 `anthropic-workspace-id` 標頭發送 |104| `ANTHROPIC_AWS_WORKSPACE_ID` | [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 所需。在每個請求上作為 `anthropic-workspace-id` 標頭發送 |

105| `ANTHROPIC_BASE_URL` | 覆蓋 API 端點以透過代理或閘道路由請求。設定為非第一方主機時，[MCP tool search](/zh-TW/mcp#scale-with-mcp-tool-search) 預設停用。如果您的代理轉發 `tool_reference` 區塊，請設定 `ENABLE_TOOL_SEARCH=true`。{/* min-version: 2.1.196 */}自 v2.1.196 起，當此項指向 `api.anthropic.com` 以外的主機時，[Remote Control](/zh-TW/remote-control#requirements) 會停用，符合其在 Bedrock、Vertex AI 和 Foundry 上的行為 |105| `ANTHROPIC_BASE_URL` | 覆蓋 API 端點以透過代理或閘道路由請求。設定為非第一方主機時，[MCP tool search](/zh-TW/mcp#scale-with-mcp-tool-search) 預設停用。如果您的代理轉發 `tool_reference` 區塊，請設定 `ENABLE_TOOL_SEARCH=true`。{/* min-version: 2.1.196 */}自 v2.1.196 起，當此項指向 `api.anthropic.com` 以外的主機時，[Remote Control](/zh-TW/remote-control#requirements) 會停用，符合其在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上的行為 |

106| `ANTHROPIC_BEDROCK_BASE_URL` | 覆蓋 Bedrock 端點 URL。用於自訂 Bedrock 端點或透過 [LLM gateway](/zh-TW/llm-gateway) 路由。請參閱 [Amazon Bedrock](/zh-TW/amazon-bedrock) |106| `ANTHROPIC_BEDROCK_BASE_URL` | 覆蓋 Amazon Bedrock 端點 URL。用於自訂 Amazon Bedrock 端點或透過 [LLM gateway](/zh-TW/llm-gateway) 路由。請參閱 [Amazon Bedrock](/zh-TW/amazon-bedrock) |

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

108| `ANTHROPIC_BEDROCK_SERVICE_TIER` | Bedrock [service tier](https://docs.aws.amazon.com/bedrock/latest/userguide/service-tiers-inference.html)（`default`、`flex` 或 `priority`）。作為 `X-Amzn-Bedrock-Service-Tier` 標頭發送。請參閱 [Amazon Bedrock](/zh-TW/amazon-bedrock#service-tiers) |108| `ANTHROPIC_BEDROCK_SERVICE_TIER` | Amazon Bedrock [service tier](https://docs.aws.amazon.com/bedrock/latest/userguide/service-tiers-inference.html)（`default`、`flex` 或 `priority`）。作為 `X-Amzn-Bedrock-Service-Tier` 標頭發送。請參閱 [Amazon Bedrock](/zh-TW/amazon-bedrock#service-tiers) |

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

111| `ANTHROPIC_CUSTOM_MODEL_OPTION` | 要在 `/model` 選擇器中新增為自訂項目的模型 ID。使用此選項可使非標準或閘道特定的模型可選擇，而無需替換內建別名。請參閱 [Model configuration](/zh-TW/model-config#add-a-custom-model-option) |111| `ANTHROPIC_CUSTOM_MODEL_OPTION` | 要在 `/model` 選擇器中新增為自訂項目的模型 ID。使用此選項可使非標準或閘道特定的模型可選擇，而無需替換內建別名。請參閱 [Model configuration](/zh-TW/model-config#add-a-custom-model-option) |

129| `ANTHROPIC_DEFAULT_SONNET_MODEL_NAME` | 請參閱 [Model configuration](/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |129| `ANTHROPIC_DEFAULT_SONNET_MODEL_NAME` | 請參閱 [Model configuration](/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

130| `ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES` | 請參閱 [Model configuration](/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |130| `ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES` | 請參閱 [Model configuration](/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

132| `ANTHROPIC_FOUNDRY_BASE_URL` | Foundry 資源的完整基礎 URL（例如，`https://my-resource.services.ai.azure.com/anthropic`）。`ANTHROPIC_FOUNDRY_RESOURCE` 的替代方案（請參閱 [Microsoft Foundry](/zh-TW/microsoft-foundry)） |132| `ANTHROPIC_FOUNDRY_AUTH_TOKEN` | {/* min-version: 2.1.203 */}Microsoft Foundry 驗證的 Bearer 權杖，例如 Microsoft Entra 存取權杖。Claude Code 將其作為 `Authorization: Bearer` 標頭發送。優先於 `ANTHROPIC_FOUNDRY_API_KEY` 和 Azure 預設認證鏈。請參閱 [Microsoft Foundry](/zh-TW/microsoft-foundry)。需要 Claude Code v2.1.203 或更新版本 |

133| `ANTHROPIC_FOUNDRY_RESOURCE` | Foundry 資源名稱（例如，`my-resource`）。如果未設定 `ANTHROPIC_FOUNDRY_BASE_URL`，則為必需（請參閱 [Microsoft Foundry](/zh-TW/microsoft-foundry)） |133| `ANTHROPIC_FOUNDRY_BASE_URL` | Microsoft Foundry 資源的完整基礎 URL（例如，`https://my-resource.services.ai.azure.com/anthropic`）。`ANTHROPIC_FOUNDRY_RESOURCE` 的替代方案（請參閱 [Microsoft Foundry](/zh-TW/microsoft-foundry)） |

134| `ANTHROPIC_FOUNDRY_RESOURCE` | Microsoft Foundry 資源名稱（例如，`my-resource`）。如果未設定 `ANTHROPIC_FOUNDRY_BASE_URL`，則為必需（請參閱 [Microsoft Foundry](/zh-TW/microsoft-foundry)） |

136| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | 使用 Bedrock 或 Bedrock Mantle 時覆蓋 Haiku 級別模型的 AWS 區域。在 Bedrock 上，僅當同時設定 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 或已棄用的 `ANTHROPIC_SMALL_FAST_MODEL` 時才生效，因為 Bedrock 否則會為背景任務使用主要模型 |137| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | 使用 Amazon Bedrock 或 Amazon Bedrock Mantle 時覆蓋 Haiku 級別模型的 AWS 區域。在 Amazon Bedrock 上，僅當同時設定 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 或已棄用的 `ANTHROPIC_SMALL_FAST_MODEL` 時才生效，因為 Amazon Bedrock 否則會為背景任務使用主要模型 |

137| `ANTHROPIC_VERTEX_BASE_URL` | 覆蓋 Vertex AI 端點 URL。用於自訂 Vertex 端點或透過 [LLM gateway](/zh-TW/llm-gateway) 路由。請參閱 [Google Vertex AI](/zh-TW/google-vertex-ai) |138| `ANTHROPIC_VERTEX_BASE_URL` | 覆蓋 Google Cloud's Agent Platform 端點 URL。用於自訂 Google Cloud's Agent Platform 端點或透過 [LLM gateway](/zh-TW/llm-gateway) 路由。請參閱 [Google Cloud's Agent Platform](/zh-TW/google-vertex-ai) |

138| `ANTHROPIC_VERTEX_PROJECT_ID` | Vertex AI 的 GCP 專案 ID。被 `GCLOUD_PROJECT`、`GOOGLE_CLOUD_PROJECT` 或您的 `GOOGLE_APPLICATION_CREDENTIALS` 認證檔案中的專案覆蓋。請參閱 [Google Vertex AI](/zh-TW/google-vertex-ai) |139| `ANTHROPIC_VERTEX_PROJECT_ID` | Google Cloud's Agent Platform 的 GCP 專案 ID。被 `GCLOUD_PROJECT`、`GOOGLE_CLOUD_PROJECT` 或您的 `GOOGLE_APPLICATION_CREDENTIALS` 認證檔案中的專案覆蓋。請參閱 [Google Cloud's Agent Platform](/zh-TW/google-vertex-ai) |

139| `ANTHROPIC_WORKSPACE_ID` | [workload identity federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的工作區 ID。當您的聯盟規則的範圍涵蓋多個工作區時設定此項，以便權杖交換知道要針對哪個工作區 |140| `ANTHROPIC_WORKSPACE_ID` | [workload identity federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的工作區 ID。當您的聯盟規則的範圍涵蓋多個工作區時設定此項，以便權杖交換知道要針對哪個工作區 |

140| `API_FORCE_IDLE_TIMEOUT` | {/* min-version: 2.1.169 */}覆蓋 5 分鐘的閒置逾時，該逾時會在沒有位元組到達時中止串流模型回應。設定為 `0` 以停用逾時，例如當緩慢的 [gateway](/zh-TW/llm-gateway) 或本機模型在區塊之間暫停超過 5 分鐘時。設定為 `1` 以在每個提供者上保持逾時。未設定時，逾時在直接 Anthropic API 和 [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 連線上無效，其中 Claude Code 自己的位元組級串流監視程式執行，在每個其他提供者上有效，包括 [Vertex AI](/zh-TW/google-vertex-ai)、[Foundry](/zh-TW/microsoft-foundry)、[Mantle](/zh-TW/amazon-bedrock#use-the-mantle-endpoint)、[Bedrock](/zh-TW/amazon-bedrock) 和閘道連線，因此停滯的串流會中止而不是掛起。自 v2.1.169 起 |141| `API_FORCE_IDLE_TIMEOUT` | {/* min-version: 2.1.169 */}覆蓋 5 分鐘的閒置逾時，該逾時會在沒有位元組到達時中止串流模型回應。設定為 `0` 以停用逾時，例如當緩慢的 [gateway](/zh-TW/llm-gateway) 或本機模型在區塊之間暫停超過 5 分鐘時。設定為 `1` 以在每個提供者上保持逾時。未設定時，逾時在直接 Anthropic API 和 [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 連線上無效，其中 Claude Code 自己的位元組級串流監視程式執行，在每個其他提供者上有效，包括 [Google Cloud's Agent Platform](/zh-TW/google-vertex-ai)、[Microsoft Foundry](/zh-TW/microsoft-foundry)、[Mantle](/zh-TW/amazon-bedrock#use-the-mantle-endpoint)、[Amazon Bedrock](/zh-TW/amazon-bedrock) 和閘道連線，因此停滯的串流會中止而不是掛起。自 v2.1.169 起 |

141| `API_TIMEOUT_MS` | API 請求的逾時（以毫秒為單位）（預設值：600000，或 10 分鐘；最大值：2147483647）。在緩慢網路上請求逾時或透過代理路由時增加此值。超過最大值的值會導致基礎計時器溢位，並導致請求立即失敗 |142| `API_TIMEOUT_MS` | API 請求的逾時（以毫秒為單位）（預設值：600000，或 10 分鐘；最大值：2147483647）。在緩慢網路上請求逾時或透過代理路由時增加此值。超過最大值的值會導致基礎計時器溢位，並導致請求立即失敗 |

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

144| `BASH_MAX_OUTPUT_LENGTH` | bash 輸出中的最大字元數，超過此數量後完整輸出會儲存到檔案，Claude 會收到路徑加上簡短預覽。請參閱 [Bash tool behavior](/zh-TW/tools-reference#bash-tool-behavior) |145| `BASH_MAX_OUTPUT_LENGTH` | bash 輸出中的最大字元數，超過此數量後完整輸出會儲存到檔案，Claude 會收到路徑加上簡短預覽。請參閱 [Bash tool behavior](/zh-TW/tools-reference#bash-tool-behavior) |

146| `CCR_FORCE_BUNDLE` | 設定為 `1` 以強制 [`claude --remote`](/zh-TW/claude-code-on-the-web#send-local-repositories-without-github) 在 GitHub 存取可用時也要捆綁並上傳您的本機儲存庫 |147| `CCR_FORCE_BUNDLE` | 設定為 `1` 以強制 [`claude --cloud`](/zh-TW/claude-code-on-the-web#send-local-repositories-without-github) 在 GitHub 存取可用時也要捆綁並上傳您的本機儲存庫 |

147| `CLAUDECODE` | 在 Claude Code 生成的子程序中設定為 `1`（Bash 和 PowerShell 工具、tmux 工作階段、[hook](/zh-TW/hooks) 命令、[status line](/zh-TW/statusline) 命令、stdio [MCP server](/zh-TW/mcp) 子程序）。IDE 擴充功能也在其整合終端中設定此項。用於偵測指令碼何時在 Claude Code 生成的子程序內執行。若要檢查目前程序是否由工具呼叫或 hook 直接生成，而不是在 Claude Code 啟動的 stdio MCP 伺服器內，請改用 `CLAUDE_CODE_CHILD_SESSION` |148| `CLAUDECODE` | 在 Claude Code 生成的子程序中設定為 `1`（Bash 和 PowerShell 工具、tmux 工作階段、[hook](/zh-TW/hooks) 命令、[status line](/zh-TW/statusline) 命令、stdio [MCP server](/zh-TW/mcp) 子程序）。IDE 擴充功能也在其整合終端中設定此項。用於偵測指令碼何時在 Claude Code 生成的子程序內執行。若要檢查目前程序是否由工具呼叫或 hook 直接生成，而不是在 Claude Code 啟動的 stdio MCP 伺服器內，請改用 `CLAUDE_CODE_CHILD_SESSION` |

148| `CLAUDE_AFK_COUNTDOWN_MS` | {/* min-version: 2.1.198 */}在未回答的 `AskUserQuestion` 對話框上自動繼續前，螢幕上倒數計時出現前的毫秒數。預設 `20000`（20 秒）。請參閱 `CLAUDE_AFK_TIMEOUT_MS`。需要 Claude Code v2.1.198 或更新版本 |149| `CLAUDE_AFK_COUNTDOWN_MS` | {/* min-version: 2.1.198 */}在未回答的 [`AskUserQuestion`](/zh-TW/tools-reference) 對話框上自動繼續前，螢幕上倒數計時出現前的毫秒數。預設 `20000`（20 秒），上限為自動繼續逾時。除非自動繼續開啟，否則無效；請參閱 [`askUserQuestionTimeout`](/zh-TW/settings#available-settings) 設定和 `CLAUDE_AFK_TIMEOUT_MS`。需要 Claude Code v2.1.198 或更新版本 |

149| `CLAUDE_AFK_TIMEOUT_MS` | {/* min-version: 2.1.198 */}在未回答的 [`AskUserQuestion`](/zh-TW/tools-reference) 對話框自動繼續前的閒置時間（以毫秒為單位）。預設 `60000`（60 秒）。若要在您離開時保持問題開啟，請設定大值，例如 `86400000`（24 小時）。設定 `0` 不會關閉逾時；它會立即關閉對話框。需要 Claude Code v2.1.198 或更新版本 |150| `CLAUDE_AFK_TIMEOUT_MS` | {/* min-version: 2.1.198 */}在未回答的 [`AskUserQuestion`](/zh-TW/tools-reference) 對話框自動繼續前的閒置時間（以毫秒為單位）。{/* min-version: 2.1.200 */}自動繼續預設關閉；使用 [`askUserQuestionTimeout`](/zh-TW/settings#available-settings) 設定選擇加入。此變數是演示和自動化測試的覆蓋：設定時，它優先於該設定並開啟自動繼續，即使設定未設定或為 `never`。設定 `0` 不會關閉逾時；它會立即關閉對話框。在 v2.1.198 和 v2.1.199 中，自動繼續預設開啟，逾時為 `60000`（60 秒）。需要 Claude Code v2.1.198 或更新版本 |

150| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 設定為 `1` 以停用所有內建 [subagent](/zh-TW/sub-agents) 類型，例如 Explore 和 Plan。僅適用於非互動式模式（`-p` 旗標）。對於想要空白狀態的 SDK 使用者很有用 |151| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 設定為 `1` 以停用所有內建 [subagent](/zh-TW/sub-agents) 類型，例如 Explore 和 Plan。僅適用於非互動式模式（`-p` 旗標）。對於想要空白狀態的 SDK 使用者很有用 |

152| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | 背景 subagents 的停滯逾時（以毫秒為單位）。預設 `600000`（10 分鐘）。計時器在每個串流進度事件時重設；如果在視窗內沒有進度到達，subagent 會被中止，任務會標記為失敗，將任何部分結果呈現給父級 |153| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | 背景 subagents 的停滯逾時（以毫秒為單位）。預設 `600000`（10 分鐘）。計時器在每個串流進度事件時重設；如果在視窗內沒有進度到達，subagent 會被中止，任務會標記為失敗，將任何部分結果呈現給父級 |

163| `CLAUDE_CODE_ARTIFACT_AUTO_OPEN` | 設定為 `0` 以停止 Claude Code 在發佈新 [artifact](/zh-TW/artifacts) 時自動開啟瀏覽器。重新發佈現有 artifact 無論此設定如何都不會開啟瀏覽器 |164| `CLAUDE_CODE_ARTIFACT_AUTO_OPEN` | 設定為 `0` 以停止 Claude Code 在發佈新 [artifact](/zh-TW/artifacts) 時自動開啟瀏覽器。重新發佈現有 artifact 無論此設定如何都不會開啟瀏覽器 |

164| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 設定為 `0` 以省略系統提示開始處的歸屬區塊（用戶端版本和提示指紋）。停用它會改善透過 [LLM gateway](/zh-TW/llm-gateway) 路由時的提示快取命中率。Anthropic API 快取不受影響 |165| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 設定為 `0` 以省略系統提示開始處的歸屬區塊（用戶端版本和提示指紋）。停用它會改善透過 [LLM gateway](/zh-TW/llm-gateway) 路由時的提示快取命中率。Anthropic API 快取不受影響 |

165| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 設定用於自動壓縮計算的上下文容量（以 token 為單位）。預設為模型的上下文視窗：標準模型為 200K 或 [extended context](/zh-TW/model-config#extended-context) 模型為 1M。在 1M 模型上使用較低的值（如 `500000`）以將視窗視為 500K 用於壓縮目的。該值上限為模型的實際上下文視窗。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 作為此值的百分比應用。設定此變數會將壓縮閾值與狀態行的 `used_percentage` 解耦，後者始終使用模型的完整上下文視窗 |166| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 設定用於自動壓縮計算的上下文容量（以 token 為單位）。預設為模型的上下文視窗：標準模型為 200K 或 [extended context](/zh-TW/model-config#extended-context) 模型為 1M，除了 Sonnet 5，其具有自己的 [default threshold](/zh-TW/model-config#sonnet-5-context-window)。在 1M 模型上使用較低的值（如 `500000`）以將視窗視為 500K 用於壓縮目的。該值上限為模型的實際上下文視窗。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 作為此值的百分比應用。設定此變數會將壓縮閾值與狀態行的 `used_percentage` 解耦，後者始終使用模型的完整上下文視窗 |

166| `CLAUDE_CODE_AUTO_CONNECT_IDE` | 覆蓋自動 [IDE connection](/zh-TW/vs-code)。預設情況下，在支援的 IDE 的整合終端內啟動時，Claude Code 會自動連線。設定為 `false` 以防止此情況。設定為 `true` 以在自動偵測失敗時強制連線嘗試，例如當 tmux 遮蔽父終端時。優先於 [`autoConnectIde`](/zh-TW/settings#global-config-settings) 全域配置設定 |167| `CLAUDE_CODE_AUTO_CONNECT_IDE` | 覆蓋自動 [IDE connection](/zh-TW/vs-code)。預設情況下，在支援的 IDE 的整合終端內啟動時，Claude Code 會自動連線。設定為 `false` 以防止此情況。設定為 `true` 以在自動偵測失敗時強制連線嘗試，例如當 tmux 遮蔽父終端時。優先於 [`autoConnectIde`](/zh-TW/settings#global-config-settings) 全域配置設定 |

167| `CLAUDE_CODE_BRIDGE_SESSION_ID` | {/* min-version: 2.1.199 */}在工作階段具有作用中 [Remote Control](/zh-TW/remote-control) 連線時在 Bash 工具和 [hook command](/zh-TW/hooks) 子程序中自動設定，並在連線結束時移除。該值是工作階段的 ID，格式為 `session_`，與出現在工作階段 `claude.ai/code` URL 中的識別碼相同，因此指令碼可以連結回執行它的工作階段。需要 Claude Code v2.1.199 或更新版本。在 [cloud sessions](/zh-TW/claude-code-on-the-web) 中，改為讀取 `CLAUDE_CODE_REMOTE_SESSION_ID` |168| `CLAUDE_CODE_BRIDGE_SESSION_ID` | {/* min-version: 2.1.199 */}在工作階段具有作用中 [Remote Control](/zh-TW/remote-control) 連線時在 Bash 工具和 [hook command](/zh-TW/hooks) 子程序中自動設定，並在連線結束時移除。該值是工作階段的 ID，格式為 `session_`，與出現在工作階段 `claude.ai/code` URL 中的識別碼相同，因此指令碼可以連結回執行它的工作階段。需要 Claude Code v2.1.199 或更新版本。在 [cloud sessions](/zh-TW/claude-code-on-the-web) 中，改為讀取 `CLAUDE_CODE_REMOTE_SESSION_ID` |

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

193| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | 設定為 `1` 以停用「Claude 表現如何？」工作階段品質調查。在設定 `DISABLE_TELEMETRY`、`DO_NOT_TRACK` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 時也會停用調查，除非 `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` 選擇加入。若要改為設定樣本速率，請使用 [`feedbackSurveyRate`](/zh-TW/settings#available-settings) 設定。請參閱 [Session quality surveys](/zh-TW/data-usage#session-quality-surveys) |194| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | 設定為 `1` 以停用「Claude 表現如何？」工作階段品質調查。在設定 `DISABLE_TELEMETRY`、`DO_NOT_TRACK` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 時也會停用調查，除非 `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` 選擇加入。若要改為設定樣本速率，請使用 [`feedbackSurveyRate`](/zh-TW/settings#available-settings) 設定。請參閱 [Session quality surveys](/zh-TW/data-usage#session-quality-surveys) |

195| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | 設定為 `1` 以從 Claude 的系統提示中移除內建的提交和 PR 工作流程指令以及 git 狀態快照。在使用您自己的 git 工作流程 skills 時很有用。設定時優先於 [`includeGitInstructions`](/zh-TW/settings#available-settings) 設定 |196| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | 設定為 `1` 以從 Claude 的系統提示中移除內建的提交和 PR 工作流程指令以及 git 狀態快照。在使用您自己的 git 工作流程 skills 時很有用。設定時優先於 [`includeGitInstructions`](/zh-TW/settings#available-settings) 設定 |

196| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | 設定為 `1` 以防止在 Anthropic API 上自動重新對應 Opus 4.0 和 4.1 至目前的 Opus 版本。在您想要刻意固定較舊模型時使用。重新對應不在 Bedrock、Vertex 或 Foundry 上執行 |197| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | 設定為 `1` 以防止在 Anthropic API 上自動重新對應 Opus 4.0 和 4.1 至目前的 Opus 版本。在您想要刻意固定較舊模型時使用。重新對應不在 Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry 上執行 |

197| `CLAUDE_CODE_DISABLE_MOUSE` | 設定為 `1` 以停用 [fullscreen rendering](/zh-TW/fullscreen) 中的滑鼠追蹤。使用 `PgUp` 和 `PgDn` 的鍵盤捲動仍然有效。使用此選項可保留您終端的原生選擇複製行為 |198| `CLAUDE_CODE_DISABLE_MOUSE` | 設定為 `1` 以停用 [fullscreen rendering](/zh-TW/fullscreen) 中的滑鼠追蹤。使用 `PgUp` 和 `PgDn` 的鍵盤捲動仍然有效。使用此選項可保留您終端的原生選擇複製行為 |

198| `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` | {/* min-version: 2.1.195 */}設定為 `1` 以停用 [fullscreen rendering](/zh-TW/fullscreen) 中的點擊、拖曳和懸停處理，同時保留滑鼠滾輪捲動。當您想要滾輪捲動在 Claude Code 內工作但不想要點擊來定位游標、展開工具輸出或開啟連結時使用。當兩者都設定時，`CLAUDE_CODE_DISABLE_MOUSE` 優先。需要 Claude Code v2.1.195 或更新版本 |199| `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` | {/* min-version: 2.1.195 */}設定為 `1` 以停用 [fullscreen rendering](/zh-TW/fullscreen) 中的點擊、拖曳和懸停處理，同時保留滑鼠滾輪捲動。當您想要滾輪捲動在 Claude Code 內工作但不想要點擊來定位游標、展開工具輸出或開啟連結時使用。當兩者都設定時，`CLAUDE_CODE_DISABLE_MOUSE` 優先。需要 Claude Code v2.1.195 或更新版本 |

199| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 相當於設定 `DISABLE_AUTOUPDATER`、`DISABLE_FEEDBACK_COMMAND`、`DISABLE_ERROR_REPORTING` 和 `DISABLE_TELEMETRY` |200| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 相當於設定 `DISABLE_AUTOUPDATER`、`DISABLE_FEEDBACK_COMMAND`、`DISABLE_ERROR_REPORTING` 和 `DISABLE_TELEMETRY` |

206| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | 設定為 `1` 以停用 [fullscreen rendering](/zh-TW/fullscreen) 中的虛擬捲動，並呈現文字記錄中的每條訊息。如果全螢幕模式中的捲動顯示應該出現訊息的空白區域，請使用此選項 |207| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | 設定為 `1` 以停用 [fullscreen rendering](/zh-TW/fullscreen) 中的虛擬捲動，並呈現文字記錄中的每條訊息。如果全螢幕模式中的捲動顯示應該出現訊息的空白區域，請使用此選項 |

207| `CLAUDE_CODE_DISABLE_WORKFLOWS` | 設定為 `1` 以停用 [workflows](/zh-TW/workflows#turn-workflows-off)。相當於 [`disableWorkflows`](/zh-TW/settings#available-settings) 設定 |208| `CLAUDE_CODE_DISABLE_WORKFLOWS` | 設定為 `1` 以停用 [workflows](/zh-TW/workflows#turn-workflows-off)。相當於 [`disableWorkflows`](/zh-TW/settings#available-settings) 設定 |

208| `CLAUDE_CODE_EFFORT_LEVEL` | 為支援的模型設定努力級別。值：`low`、`medium`、`high`、`xhigh`、`max` 或 `auto` 以使用模型預設值。可用級別取決於模型。優先於 `/effort` 和 `effortLevel` 設定。請參閱 [Adjust effort level](/zh-TW/model-config#adjust-effort-level) |209| `CLAUDE_CODE_EFFORT_LEVEL` | 為支援的模型設定努力級別。值：`low`、`medium`、`high`、`xhigh`、`max` 或 `auto` 以使用模型預設值。可用級別取決於模型。優先於 `/effort` 和 `effortLevel` 設定。請參閱 [Adjust effort level](/zh-TW/model-config#adjust-effort-level) |

209| `CLAUDE_CODE_ENABLE_AUTO_MODE` | {/* min-version: 2.1.158 */}設定為 `1` 以在 Amazon Bedrock、Google Cloud Vertex AI 和 Microsoft Foundry 上啟用 [auto mode](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)。需要 Claude Code v2.1.158 或更新版本。對 Anthropic API 無效，其中 auto mode 預設可用。請參閱 [在 Bedrock、Vertex AI 或 Foundry 上啟用自動模式](/zh-TW/permission-modes#enable-auto-mode-on-bedrock-vertex-ai-or-foundry) |210| `CLAUDE_CODE_ENABLE_APPEND_SUBAGENT_PROMPT` | {/* min-version: 2.1.205 */}設定為 `1` 以啟用將額外文字附加到每個 [subagent](/zh-TW/sub-agents) 系統提示的末尾。[`--append-subagent-system-prompt`](/zh-TW/cli-reference#cli-flags) 旗標提供附加的文字並自動設定此變數，因此您不需要自己設定它。需要 Claude Code v2.1.205 或更新版本 |

211| `CLAUDE_CODE_ENABLE_AUTO_MODE` | {/* min-version: 2.1.158 */}設定為 `1` 以在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上啟用 [auto mode](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)。需要 Claude Code v2.1.158 或更新版本。對 Anthropic API 無效，其中 auto mode 預設可用。請參閱 [Enable auto mode on Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry](/zh-TW/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry) |

210| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | 覆蓋 [session recap](/zh-TW/interactive-mode#session-recap) 可用性。設定為 `0` 以強制關閉摘要，無論 `/config` 切換如何。設定為 `1` 以在 [`awaySummaryEnabled`](/zh-TW/settings#available-settings) 為 `false` 時強制啟用摘要。優先於設定和 `/config` 切換 |212| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | 覆蓋 [session recap](/zh-TW/interactive-mode#session-recap) 可用性。設定為 `0` 以強制關閉摘要，無論 `/config` 切換如何。設定為 `1` 以在 [`awaySummaryEnabled`](/zh-TW/settings#available-settings) 為 `false` 時強制啟用摘要。優先於設定和 `/config` 切換 |

211| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 設定為 `1` 以在 [non-interactive mode](/zh-TW/headless) 中背景安裝完成後在回合邊界處刷新外掛程式狀態。預設關閉，因為刷新會在工作階段中途更改系統提示，這會使該回合的 [prompt caching](/zh-TW/prompt-caching) 失效 |213| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 設定為 `1` 以在 [non-interactive mode](/zh-TW/headless) 中背景安裝完成後在回合邊界處刷新外掛程式狀態。預設關閉，因為刷新會在工作階段中途更改系統提示，這會使該回合的 [prompt caching](/zh-TW/prompt-caching) 失效 |

212| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | 設定為 `1` 以在 Anthropic 綁定的非必要流量被阻止時將「Claude 表現如何？」工作階段品質調查路由到您自己的 [OpenTelemetry collector](/zh-TW/monitoring-usage)。調查評分僅作為 OTEL 事件發出到您配置的收集器。在此模式下，沒有調查資料發送到 Anthropic。在設定 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`、`DISABLE_TELEMETRY` 或 `DO_NOT_TRACK` 時適用，否則無效。`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` 和組織產品反饋政策優先 |214| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | 設定為 `1` 以在 Anthropic 綁定的非必要流量被阻止時將「Claude 表現如何？」工作階段品質調查路由到您自己的 [OpenTelemetry collector](/zh-TW/monitoring-usage)。調查評分僅作為 OTEL 事件發出到您配置的收集器。在此模式下，沒有調查資料發送到 Anthropic。在設定 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`、`DISABLE_TELEMETRY` 或 `DO_NOT_TRACK` 時適用，否則無效。`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` 和組織產品反饋政策優先 |

213| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 控制工具呼叫輸入是否在 Claude 生成時從 API 串流。關閉此選項時，大型工具輸入（例如長檔案寫入）僅在 Claude 完成生成後才到達，這可能看起來像是掛起。在 Anthropic API 上預設啟用。在 Bedrock 和 Vertex 上，按模型啟用，其中已部署的容器支援它。設定為 `0` 以選擇退出。設定為 `1` 以在透過 `ANTHROPIC_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_BEDROCK_BASE_URL` 路由時強制啟用。在 Foundry 和 [gateway](/zh-TW/llm-gateway) 連線上預設關閉 |215| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 控制工具呼叫輸入是否在 Claude 生成時從 API 串流。關閉此選項時，大型工具輸入（例如長檔案寫入）僅在 Claude 完成生成後才到達，這可能看起來像是掛起。在 Anthropic API 上預設啟用。在 Amazon Bedrock 和 Google Cloud's Agent Platform 上，按模型啟用，其中已部署的容器支援它。設定為 `0` 以選擇退出。設定為 `1` 以在透過 `ANTHROPIC_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_BEDROCK_BASE_URL` 路由時強制啟用。在 Microsoft Foundry 和 [gateway](/zh-TW/llm-gateway) 連線上預設關閉 |

214| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 設定為 `1` 以在 `ANTHROPIC_BASE_URL` 指向 Anthropic 相容閘道（例如 LiteLLM、Kong 或內部代理）時從您的閘道的 `/v1/models` 端點填充 `/model` 選擇器。預設關閉，因為由共享 API 金鑰支援的閘道會以其他方式向每個使用者顯示該金鑰可以存取的每個模型。探索的模型仍由 [`availableModels`](/zh-TW/settings#available-settings) 允許清單篩選，工作階段接收；由於 [server-managed delivery is not available on gateway configurations](/zh-TW/server-managed-settings#platform-availability)，透過 MDM 或受管設定檔案傳遞清單 |216| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 設定為 `1` 以在 `ANTHROPIC_BASE_URL` 指向 Anthropic 相容閘道（例如 LiteLLM、Kong 或內部代理）時從您的閘道的 `/v1/models` 端點填充 `/model` 選擇器。預設關閉，因為由共享 API 金鑰支援的閘道會以其他方式向每個使用者顯示該金鑰可以存取的每個模型。探索的模型仍由 [`availableModels`](/zh-TW/settings#available-settings) 允許清單篩選，工作階段接收；由於 [server-managed delivery is not available on gateway configurations](/zh-TW/server-managed-settings#platform-availability)，透過 MDM 或受管設定檔案傳遞清單 |

215| `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE` | {/* max-version: 2.1.141 */}在 v2.1.142 中移除，當 [fast mode](/zh-TW/fast-mode) 預設從 Opus 4.6 移至 Opus 4.7 時 |217| `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE` | {/* max-version: 2.1.141 */}在 v2.1.142 中移除，當 [fast mode](/zh-TW/fast-mode) 預設從 Opus 4.6 移至 Opus 4.7 時 |

216| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 設定為 `false` 以停用提示建議（`/config` 中的「提示建議」切換）。這些是在 Claude 回應後出現在您的提示輸入中的灰顯預測。請參閱 [Prompt suggestions](/zh-TW/interactive-mode#prompt-suggestions) |218| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 設定為 `false` 以停用提示建議（`/config` 中的「提示建議」切換）。這些是在 Claude 回應後出現在您的提示輸入中的灰顯預測。請參閱 [Prompt suggestions](/zh-TW/interactive-mode#prompt-suggestions) |

239| `CLAUDE_CODE_MAX_TURNS` | 當未傳遞明確限制時，限制代理回合的數量。相當於傳遞 [`--max-turns`](/zh-TW/cli-reference#cli-flags)，當兩者都設定時優先。不是正整數的值在啟動時會被拒絕並出現錯誤，而不是被視為無限制 |241| `CLAUDE_CODE_MAX_TURNS` | 當未傳遞明確限制時，限制代理回合的數量。相當於傳遞 [`--max-turns`](/zh-TW/cli-reference#cli-flags)，當兩者都設定時優先。不是正整數的值在啟動時會被拒絕並出現錯誤，而不是被視為無限制 |

241| `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` | {/* min-version: 2.1.187 */}遠端 MCP 工具呼叫的閒置逾時（以毫秒為單位）（預設值：300000，或 5 分鐘）。當 HTTP、SSE、WebSocket 或 [claude.ai connector](/zh-TW/mcp#use-mcp-servers-from-claude-ai) MCP 伺服器在此期間內沒有發送回應和進度通知時，工具呼叫會中止並出現錯誤，而不是等待牆上時鐘 `MCP_TOOL_TIMEOUT`。設定為 `0` 以停用閒置檢查。低於 1000 的值會提高到 1 秒，該值上限為有效的 `MCP_TOOL_TIMEOUT`。不適用於 stdio 或 IDE 伺服器。需要 Claude Code v2.1.187 或更新版本 |243| `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` | {/* min-version: 2.1.187 */}MCP 工具呼叫的閒置逾時（以毫秒為單位）。當 stdio、HTTP、SSE、WebSocket 或 [claude.ai connector](/zh-TW/mcp#use-mcp-servers-from-claude-ai) MCP 伺服器在此期間內沒有發送回應和進度通知時，工具呼叫會中止並出現錯誤，而不是等待整體 `MCP_TOOL_TIMEOUT`。覆蓋網路伺服器的每個傳輸預設值 300000（5 分鐘）和 stdio 伺服器的 1800000（30 分鐘）。設定為 `0` 以停用閒置檢查。低於 1000 的值會提高到 1 秒，該值上限為有效的 `MCP_TOOL_TIMEOUT`。`.mcp.json` 中的每個伺服器 `timeout` 至少 1000 會將該伺服器的閒置視窗提高到至少 `timeout` 值。不適用於 IDE 伺服器或 SDK 進程內伺服器。需要 Claude Code v2.1.187 或更新版本。{/* min-version: 2.1.203 */}在 v2.1.203 之前，stdio 伺服器不受閒置逾時限制 |

243| `CLAUDE_CODE_NEW_INIT` | 設定為 `1` 以使 `/init` 執行互動式設定流程。流程會詢問要產生哪些檔案，包括 CLAUDE.md、skills 和 hooks，然後再探索程式碼庫並寫入它們。沒有此變數，`/init` 會自動產生 CLAUDE.md 而不提示 |245| `CLAUDE_CODE_NEW_INIT` | 設定為 `1` 以使 `/init` 執行互動式設定流程。流程會詢問要產生哪些檔案，包括 CLAUDE.md、skills 和 hooks，然後再探索程式碼庫並寫入它們。沒有此變數，`/init` 會自動產生 CLAUDE.md 而不提示 |

244| `CLAUDE_CODE_NO_FLICKER` | 設定為 `1` 以啟用 [fullscreen rendering](/zh-TW/fullscreen)，一項研究預覽，可減少閃爍並在長對話中保持記憶體平坦。相當於 [`tui`](/zh-TW/settings#available-settings) 設定；您也可以使用 `/tui fullscreen` 切換 |246| `CLAUDE_CODE_NO_FLICKER` | 設定為 `1` 以啟用 [fullscreen rendering](/zh-TW/fullscreen)，一項研究預覽，可減少閃爍並在長對話中保持記憶體平坦。相當於 [`tui`](/zh-TW/settings#available-settings) 設定；您也可以使用 `/tui fullscreen` 切換 |

260| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | 設定為 `1` 以停止 Claude Code 在生成 PowerShell 以進行工具呼叫、hooks 和狀態行命令時傳遞 `-ExecutionPolicy Bypass`，並改為尊重機器的有效執行政策。預設情況下，Claude Code 在程序範圍內繞過執行政策，以便 `.ps1` 指令碼和模組匯入在預設受限的 Windows 安裝上工作。無論此設定如何，程序範圍繞過永遠不會覆蓋群組原則 `MachinePolicy` 或 `UserPolicy` |262| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | 設定為 `1` 以停止 Claude Code 在生成 PowerShell 以進行工具呼叫、hooks 和狀態行命令時傳遞 `-ExecutionPolicy Bypass`，並改為尊重機器的有效執行政策。預設情況下，Claude Code 在程序範圍內繞過執行政策，以便 `.ps1` 指令碼和模組匯入在預設受限的 Windows 安裝上工作。無論此設定如何，程序範圍繞過永遠不會覆蓋群組原則 `MachinePolicy` 或 `UserPolicy` |

261| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | {/* min-version: 2.1.182 */}[非互動式模式](/zh-TW/headless#background-tasks-at-exit)使用 `-p` 旗標在最終回合後等待的最大時間（以毫秒為單位），用於背景 subagents 和工作流程，其結果是輸出的一部分。預設值：`600000`，或 10 分鐘。超過上限時，剩餘背景任務會被終止，程序會退出。設定為 `0` 以無限期等待。此上限與適用於純背景 shells 的 5 秒寬限期分開 |263| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | {/* min-version: 2.1.182 */}[非互動式模式](/zh-TW/headless#background-tasks-at-exit)使用 `-p` 旗標在最終回合後等待的最大時間（以毫秒為單位），用於背景 subagents 和工作流程，其結果是輸出的一部分。預設值：`600000`，或 10 分鐘。超過上限時，剩餘背景任務會被終止，程序會退出。設定為 `0` 以無限期等待。此上限與適用於純背景 shells 的 5 秒寬限期分開 |

262| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | {/* min-version: 2.1.152 */}設定為 `1` 以在 `ANTHROPIC_BASE_URL` 指向自訂代理時傳播 W3C 追蹤上下文。傳播涵蓋模型和 HTTP MCP 請求上的 `traceparent` 標頭以及 Bash、PowerShell 和 hook 子程序的 `TRACEPARENT` 環境變數。預設情況下，傳播僅在直接連線到 Anthropic API 時啟用。在 v2.1.152 中新增。請參閱 [Traces (beta)](/zh-TW/monitoring-usage#traces-beta) |264| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | {/* min-version: 2.1.152 */}設定為 `1` 以在 `ANTHROPIC_BASE_URL` 指向自訂代理時傳播 W3C 追蹤上下文。傳播涵蓋模型和 HTTP MCP 請求上的 `traceparent` 標頭以及 Bash、PowerShell 和 hook 子程序的 `TRACEPARENT` 環境變數。預設情況下，傳播僅在直接連線到 Anthropic API 時啟用。在 v2.1.152 中新增。請參閱 [Traces (beta)](/zh-TW/monitoring-usage#traces-beta) |

263| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | 由嵌入 Claude Code 並代表其管理模型提供者路由的主機平台設定。設定時，提供者選擇、端點和驗證變數（例如 `CLAUDE_CODE_USE_BEDROCK`、`ANTHROPIC_BASE_URL` 和 `ANTHROPIC_API_KEY`）在設定檔案中被忽略，以便使用者設定無法覆蓋主機的路由。Bedrock、Vertex 和 Foundry 的自動遙測選擇退出也會被跳過，因此遙測遵循標準 `DISABLE_TELEMETRY` 選擇退出。請參閱 [Default behaviors by API provider](/zh-TW/data-usage#default-behaviors-by-api-provider) |265| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | 由嵌入 Claude Code 並代表其管理模型提供者路由的主機平台設定。設定時，提供者選擇、端點和驗證變數（例如 `CLAUDE_CODE_USE_BEDROCK`、`ANTHROPIC_BASE_URL` 和 `ANTHROPIC_API_KEY`）在設定檔案中被忽略，以便使用者設定無法覆蓋主機的路由。Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 的自動遙測選擇退出也會被跳過，因此遙測遵循標準 `DISABLE_TELEMETRY` 選擇退出。請參閱 [Default behaviors by API provider](/zh-TW/data-usage#default-behaviors-by-api-provider) |

265| `CLAUDE_CODE_REMOTE` | 當 Claude Code 作為 [cloud session](/zh-TW/claude-code-on-the-web) 執行時自動設定為 `true`。從 hook 或設定指令碼讀取此項以偵測您是否在雲端環境中 |267| `CLAUDE_CODE_REMOTE` | 當 Claude Code 作為 [cloud session](/zh-TW/claude-code-on-the-web) 執行時自動設定為 `true`。從 hook 或設定指令碼讀取此項以偵測您是否在雲端環境中 |

266| `CLAUDE_CODE_REMOTE_SESSION_ID` | 在 [cloud sessions](/zh-TW/claude-code-on-the-web) 中自動設定為目前工作階段的 ID。讀取此項以構造回到工作階段文字記錄的連結。請參閱 [Link output back to the session](/zh-TW/claude-code-on-the-web#link-output-back-to-the-session) |268| `CLAUDE_CODE_REMOTE_SESSION_ID` | 在 [cloud sessions](/zh-TW/claude-code-on-the-web) 中自動設定為目前工作階段的 ID。讀取此項以構造回到工作階段文字記錄的連結。請參閱 [Link output back to the session](/zh-TW/claude-code-on-the-web#link-output-back-to-the-session) |

277| `CLAUDE_CODE_SIMPLE` | 設定為 `1` 以使用最小系統提示和僅 Bash、檔案讀取和檔案編輯工具執行。來自 `--mcp-config` 的 MCP 工具仍然可用。停用 hooks、skills、plugins、MCP 伺服器、自動記憶體和 CLAUDE.md 的自動探索。OAuth 權杖和鑰匙圈認證不會被讀取，因此 Anthropic 驗證必須來自 `ANTHROPIC_API_KEY` 或 `--settings` 中的 `apiKeyHelper`。相當於傳遞 [`--bare`](/zh-TW/headless#start-faster-with-bare-mode) |279| `CLAUDE_CODE_SIMPLE` | 設定為 `1` 以使用最小系統提示和僅 Bash、檔案讀取和檔案編輯工具執行。來自 `--mcp-config` 的 MCP 工具仍然可用。停用 hooks、skills、plugins、MCP 伺服器、自動記憶體和 CLAUDE.md 的自動探索。OAuth 權杖和鑰匙圈認證不會被讀取，因此 Anthropic 驗證必須來自 `ANTHROPIC_API_KEY` 或 `--settings` 中的 `apiKeyHelper`。相當於傳遞 [`--bare`](/zh-TW/headless#start-faster-with-bare-mode) |

278| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 設定為 `1` 以在任何模型上使用較短的系統提示和縮寫工具描述。設定為 `0`、`false`、`no` 或 `off` 以選擇退出，即使實驗或伺服器配置會以其他方式啟用它。完整工具集、hooks、MCP 伺服器和 CLAUDE.md 探索保持啟用 |280| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 設定為 `1` 以在任何模型上使用較短的系統提示和縮寫工具描述。設定為 `0`、`false`、`no` 或 `off` 以選擇退出，即使實驗或伺服器配置會以其他方式啟用它。完整工具集、hooks、MCP 伺服器和 CLAUDE.md 探索保持啟用 |

281| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | 跳過 Microsoft Foundry 的 Azure 驗證。對於閘道，請改為在 `ANTHROPIC_FOUNDRY_API_KEY` 中設定認證；沒有 API 金鑰，此變數會使 Foundry 用戶端無法發送請求 |283| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | 跳過 Microsoft Foundry 的 Azure 驗證，用於代理或閘道，該代理或閘道注入其自己的 `Authorization` 標頭。Claude Code 發送沒有 Azure 認證的請求，並保留您提供的 `Authorization` 標頭，例如透過 `ANTHROPIC_CUSTOM_HEADERS`。當設定 `ANTHROPIC_FOUNDRY_API_KEY` 或 `ANTHROPIC_FOUNDRY_AUTH_TOKEN` 時被忽略。{/* min-version: 2.1.203 */}在 v2.1.203 之前，此變數使 Microsoft Foundry 用戶端無法發送請求，除非同時設定了 API 金鑰 |

283| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 設定為 `1` 以跳過將提示歷史記錄和工作階段文字記錄寫入磁碟。使用此變數啟動的工作階段不會出現在 `--resume`、`--continue` 或向上箭頭歷史記錄中。對於臨時指令碼化工作階段很有用 |285| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 設定為 `1` 以跳過將提示歷史記錄和工作階段文字記錄寫入磁碟。使用此變數啟動的工作階段不會出現在 `--resume`、`--continue` 或向上箭頭歷史記錄中。對於臨時指令碼化工作階段很有用 |

285| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | [Stop](/zh-TW/hooks#stop) 或 [SubagentStop](/zh-TW/hooks#subagentstop) hook 可能連續阻止回合結束的最大次數，然後 Claude Code 覆蓋它並無論如何結束回合（預設值：8）。設定為 `0` 以停用上限。如果您的 hook 合法需要更多迭代來解決，請提高此值 |287| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | [Stop](/zh-TW/hooks#stop) 或 [SubagentStop](/zh-TW/hooks#subagentstop) hook 可能連續阻止回合結束的最大次數，然後 Claude Code 覆蓋它並無論如何結束回合（預設值：8）。設定為 `0` 以停用上限。如果您的 hook 合法需要更多迭代來解決，請提高此值 |

286| `CLAUDE_CODE_SUBAGENT_MODEL` | 請參閱 [Model configuration](/zh-TW/model-config)。{/* min-version: 2.1.196 */}自 v2.1.196 起，將其設定為 `inherit` 與不設定相同；較早版本將 `inherit` 視為覆蓋，強制每個 subagent 進入主對話的模型 |288| `CLAUDE_CODE_SUBAGENT_MODEL` | 請參閱 [Model configuration](/zh-TW/model-config)。{/* min-version: 2.1.196 */}自 v2.1.196 起，將其設定為 `inherit` 與不設定相同；較早版本將 `inherit` 視為覆蓋，強制每個 subagent 進入主對話的模型 |

287| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | 設定為 `1` 以從子程序環境中移除 Anthropic 和雲端提供者認證（Bash 工具、hooks、MCP stdio 伺服器）。父 Claude 程序保留這些認證以進行 API 呼叫，但子程序無法讀取它們，減少了嘗試透過 shell 擴展來竊取機密的提示注入攻擊的暴露。在 Linux 上，這也會在隔離的 PID 命名空間中執行 Bash 子程序，以便它們無法透過 `/proc` 讀取主機程序環境；作為副作用，`ps`、`pgrep` 和 `kill` 無法看到或發信號給主機程序。配置 `allowed_non_write_users` 時，`claude-code-action` 會自動設定此項 |289| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | 設定為 `1` 以從子程序環境中移除 Anthropic 和雲端提供者認證（Bash 工具、hooks、MCP stdio 伺服器）。父 Claude 程序保留這些認證以進行 API 呼叫，但子程序無法讀取它們，減少了嘗試透過 shell 擴展來竊取機密的提示注入攻擊的暴露。在 Linux 上，這也會在隔離的 PID 命名空間中執行 Bash 子程序，以便它們無法透過 `/proc` 讀取主機程序環境；作為副作用，`ps`、`pgrep` 和 `kill` 無法看到或發信號給主機程序。配置 `allowed_non_write_users` 時，`claude-code-action` 會自動設定此項 |

296| `CLAUDE_CODE_TMPDIR` | 覆蓋用於內部臨時檔案的臨時目錄。Claude Code 將 `/claude-{uid}/`（Unix）或 `/claude/`（Windows）附加到此路徑。預設值：macOS 上的 `/tmp`、Linux/Windows 上的 `os.tmpdir()`。{/* min-version: 2.1.161 */}自 v2.1.161 起，在 macOS 和 Linux 上，當您的覆蓋是長路徑時，[sandboxed](/zh-TW/sandboxing) Bash 子程序會在系統預設下收到簡短的回退 `$TMPDIR`，因為某些工具在臨時路徑變得太長時會失敗。未沙箱化的 Bash 命令繼承您的 shell 的 `$TMPDIR` 不變。Claude Code 自己的臨時檔案始終使用您的覆蓋 |298| `CLAUDE_CODE_TMPDIR` | 覆蓋用於內部臨時檔案的臨時目錄。Claude Code 將 `/claude-{uid}/`（Unix）或 `/claude/`（Windows）附加到此路徑。預設值：macOS 上的 `/tmp`、Linux/Windows 上的 `os.tmpdir()`。{/* min-version: 2.1.161 */}自 v2.1.161 起，在 macOS 和 Linux 上，當您的覆蓋是長路徑時，[sandboxed](/zh-TW/sandboxing) Bash 子程序會在系統預設下收到簡短的回退 `$TMPDIR`，因為某些工具在臨時路徑變得太長時會失敗。未沙箱化的 Bash 命令繼承您的 shell 的 `$TMPDIR` 不變。Claude Code 自己的臨時檔案始終使用您的覆蓋 |

297| `CLAUDE_CODE_TMUX_TRUECOLOR` | 設定為 `1` 以允許 tmux 內的 24 位真彩色輸出。預設情況下，當設定 `$TMUX` 時，Claude Code 會限制為 256 色，因為 tmux 不會通過真彩色逃逸序列，除非配置為這樣做。在將 `set -ga terminal-overrides ',*:Tc'` 新增到您的 `~/.tmux.conf` 後設定此項。請參閱 [Terminal configuration](/zh-TW/terminal-config) 以取得其他 tmux 設定 |299| `CLAUDE_CODE_TMUX_TRUECOLOR` | 設定為 `1` 以允許 tmux 內的 24 位真彩色輸出。預設情況下，當設定 `$TMUX` 時，Claude Code 會限制為 256 色，因為 tmux 不會通過真彩色逃逸序列，除非配置為這樣做。在將 `set -ga terminal-overrides ',*:Tc'` 新增到您的 `~/.tmux.conf` 後設定此項。請參閱 [Terminal configuration](/zh-TW/terminal-config) 以取得其他 tmux 設定 |

302| `CLAUDE_CODE_USE_NATIVE_FILE_SEARCH` | 設定為 `1` 以使用 Node.js 檔案 API 而不是 ripgrep 來探索自訂命令、subagents 和輸出樣式。如果捆綁的 ripgrep 二進位檔案在您的環境中不可用或被阻止，請設定此項。不影響 Grep 或檔案搜尋工具 |304| `CLAUDE_CODE_USE_NATIVE_FILE_SEARCH` | 設定為 `1` 以使用 Node.js 檔案 API 而不是 ripgrep 來探索自訂命令、subagents 和輸出樣式。如果捆綁的 ripgrep 二進位檔案在您的環境中不可用或被阻止，請設定此項。不影響 Grep 或檔案搜尋工具 |

303| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | 控制 PowerShell 工具。在沒有 Git Bash 的 Windows 上，工具會自動啟用；設定為 `0` 以停用它。在安裝了 Git Bash 的 Windows 上，工具正在逐步推出：設定為 `1` 以選擇加入或 `0` 以選擇退出。在 Linux、macOS 和 WSL 上，設定為 `1` 以啟用它，這需要您的 `PATH` 上有 `pwsh`。在 Windows 上啟用時，Claude 可以原生執行 PowerShell 命令，而不是透過 Git Bash 路由。請參閱 [PowerShell tool](/zh-TW/tools-reference#powershell-tool) |305| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | 控制 PowerShell 工具。在沒有 Git Bash 的 Windows 上，工具會自動啟用；設定為 `0` 以停用它。在安裝了 Git Bash 的 Windows 上，工具正在逐步推出：設定為 `1` 以選擇加入或 `0` 以選擇退出。在 Linux、macOS 和 WSL 上，設定為 `1` 以啟用它，這需要您的 `PATH` 上有 `pwsh`。在 Windows 上啟用時，Claude 可以原生執行 PowerShell 命令，而不是透過 Git Bash 路由。請參閱 [PowerShell tool](/zh-TW/tools-reference#powershell-tool) |

305| `CLAUDE_CONFIG_DIR` | 覆蓋配置目錄（預設值：`~/.claude`）。所有設定、認證、工作階段歷史記錄和外掛程式都儲存在此路徑下。對於並排執行多個帳戶很有用：例如，`alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'` |307| `CLAUDE_CONFIG_DIR` | 覆蓋配置目錄（預設值：`~/.claude`）。所有設定、認證、工作階段歷史記錄和外掛程式都儲存在此路徑下。對於並排執行多個帳戶很有用：例如，`alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'` |

306| `CLAUDE_DISABLE_ADOPT` | {/* min-version: 2.1.195 */}設定為 `1` 以停止進行中的背景工作，而不是在您按 `←` 或使用 [`/background`](/zh-TW/agent-view#from-inside-a-session) 將工作階段背景化時帶入它。Claude Code 會要求您在背景化前確認，然後停止會以其他方式帶入的任務。需要 Claude Code v2.1.195 或更新版本 |308| `CLAUDE_DISABLE_ADOPT` | {/* min-version: 2.1.195 */}設定為 `1` 以停止進行中的背景工作，而不是在您按 `←` 或使用 [`/background`](/zh-TW/agent-view#from-inside-a-session) 將工作階段背景化時帶入它。Claude Code 會要求您在背景化前確認，然後停止會以其他方式帶入的任務。需要 Claude Code v2.1.195 或更新版本 |

307| `CLAUDE_EFFORT` | 在 Bash 工具子程序和 hook 命令中自動設定為該回合的作用中 [effort level](/zh-TW/model-config#adjust-effort-level)：`low`、`medium`、`high`、`xhigh` 或 `max`。Ultracode 不是一個不同的級別，報告為 `xhigh`。符合傳遞給 [hooks](/zh-TW/hooks) 的 `effort.level` 欄位。僅在目前模型支援努力參數時設定 |309| `CLAUDE_EFFORT` | 在 Bash 工具子程序和 hook 命令中自動設定為該回合的作用中 [effort level](/zh-TW/model-config#adjust-effort-level)：`low`、`medium`、`high`、`xhigh` 或 `max`。Ultracode 不是一個不同的級別，報告為 `xhigh`。符合傳遞給 [hooks](/zh-TW/hooks) 的 `effort.level` 欄位。僅在目前模型支援努力參數時設定 |

308| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 設定為 `1` 以強制啟用位元級串流閒置監視程式，或設定為 `0` 以強制停用它。未設定時，監視程式預設對 Anthropic API 和 [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 連線啟用。位元監視程式會在 180 秒內沒有位元組到達線路時中止連線（直接 Anthropic API 連線上預設為 180 秒，Claude Platform on AWS 和其他提供者上為 300 秒），或在設定 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 時為該值，該值被限制為最少 5 分鐘，獨立於事件級監視程式 |310| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 設定為 `1` 以強制啟用位元級串流閒置監視程式，或設定為 `0` 以強制停用它。未設定時，監視程式預設對 Anthropic API 和 [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 連線啟用。位元監視程式會在 180 秒內沒有位元組到達線路時中止連線（直接 Anthropic API 連線上預設為 180 秒，Claude Platform on AWS 和其他提供者上為 300 秒），或在設定 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 時為該值，該值被限制為最少 5 分鐘，獨立於事件級監視程式 |

309| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | 設定為 `1` 以在 Amazon Bedrock `vnd.amazon.eventstream` 回應上啟用位元級串流閒置監視程式。預設關閉。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置逾時 |311| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | 設定為 `1` 以在 Amazon Bedrock `vnd.amazon.eventstream` 回應上啟用位元級串流閒置監視程式。預設關閉。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置逾時 |

310| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 設定為 `1` 以強制啟用事件級串流閒置監視程式，或設定為 `0` 以強制停用它。{/* min-version: 2.1.196 */}未設定時，監視程式預設對所有提供者啟用。在 v2.1.196 之前，未設定的預設值由伺服器在直接 Anthropic API 上控制，在其他提供者上關閉。{/* min-version: 2.1.169 */}自 v2.1.169 起，直接 Anthropic API 和 Claude Platform on AWS 以外的提供者也有預設開啟的 5 分鐘主體閒置逾時，獨立於此變數；請參閱 `API_FORCE_IDLE_TIMEOUT`。在 Bedrock 上，您也可以使用 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` 啟用獨立的位元級監視程式；當兩者都設定時，它們一起執行。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置逾時 |312| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 設定為 `1` 以強制啟用事件級串流閒置監視程式，或設定為 `0` 以強制停用它。{/* min-version: 2.1.196 */}未設定時，監視程式預設對所有提供者啟用。在 v2.1.196 之前，未設定的預設值由伺服器在直接 Anthropic API 上控制，在其他提供者上關閉。{/* min-version: 2.1.169 */}自 v2.1.169 起，直接 Anthropic API 和 Claude Platform on AWS 以外的提供者也有預設開啟的 5 分鐘主體閒置逾時，獨立於此變數；請參閱 `API_FORCE_IDLE_TIMEOUT`。在 Amazon Bedrock 上，您也可以使用 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` 啟用獨立的位元級監視程式；當兩者都設定時，它們一起執行。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置逾時 |

311| `CLAUDE_ENV_FILE` | Claude Code 在每個 Bash 命令之前在同一 shell 程序中執行的 shell 指令碼的路徑，因此檔案中的匯出對命令可見。用於在命令之間保持 virtualenv 或 conda 啟用。也由 [SessionStart](/zh-TW/hooks#persist-environment-variables)、[Setup](/zh-TW/hooks#setup)、[CwdChanged](/zh-TW/hooks#cwdchanged) 和 [FileChanged](/zh-TW/hooks#filechanged) hooks 動態填充 |313| `CLAUDE_ENV_FILE` | Claude Code 在每個 Bash 命令之前在同一 shell 程序中執行的 shell 指令碼的路徑，因此檔案中的匯出對命令可見。用於在命令之間保持 virtualenv 或 conda 啟用。也由 [SessionStart](/zh-TW/hooks#persist-environment-variables)、[Setup](/zh-TW/hooks#setup)、[CwdChanged](/zh-TW/hooks#cwdchanged) 和 [FileChanged](/zh-TW/hooks#filechanged) hooks 動態填充 |

312| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | 當未提供明確名稱時，自動產生的 [Remote Control](/zh-TW/remote-control) 工作階段名稱的前綴。預設為您的機器主機名稱，產生名稱如 `myhost-graceful-unicorn`。`--remote-control-session-name-prefix` CLI 旗標為單一呼叫設定相同的值 |314| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | 當未提供明確名稱時，自動產生的 [Remote Control](/zh-TW/remote-control) 工作階段名稱的前綴。預設為您的機器主機名稱，產生名稱如 `myhost-graceful-unicorn`。`--remote-control-session-name-prefix` CLI 旗標為單一呼叫設定相同的值 |

313| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 串流閒置監視程式在關閉停滯連線之前的逾時（以毫秒為單位）。當您明確設定此變數時，最小值為 `300000`（5 分鐘）；較低的值會無聲地限制以吸收延伸思考暫停和代理緩衝。未設定時，事件級監視程式預設為 300 秒，位元級監視程式在直接 Anthropic API 連線上預設為 180 秒（Claude Platform on AWS 和其他提供者上為 300 秒）。未設定的 180 秒位元監視程式預設是一個單獨的值，不受 5 分鐘限制。`API_FORCE_IDLE_TIMEOUT` 下描述的主體閒置逾時獨立適用。在 Bedrock 上，也適用於 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1` |315| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 串流閒置監視程式在關閉停滯連線之前的逾時（以毫秒為單位）。當您明確設定此變數時，最小值為 `300000`（5 分鐘）；較低的值會無聲地限制以吸收延伸思考暫停和代理緩衝。未設定時，事件級監視程式預設為 300 秒，位元級監視程式在直接 Anthropic API 連線上預設為 180 秒（Claude Platform on AWS 和其他提供者上為 300 秒）。未設定的 180 秒位元監視程式預設是一個單獨的值，不受 5 分鐘限制。`API_FORCE_IDLE_TIMEOUT` 下描述的主體閒置逾時獨立適用。在 Amazon Bedrock 上，也適用於 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1` |

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

319| `DISABLE_DOCTOR_COMMAND` | 設定為 `1` 以隱藏 `/doctor` 命令。對於使用者不應執行安裝診斷的受管部署很有用 |321| `DISABLE_DOCTOR_COMMAND` | 設定為 `1` 以隱藏 [`/doctor`](/zh-TW/commands#all-commands) 設定檢查 skill 及其 `/checkup` 別名。對於使用者不應執行安裝診斷的受管部署很有用。不影響 `claude doctor` 終端命令。{/* min-version: 2.1.205 */}在 v2.1.205 之前，此變數隱藏了 `/doctor` 診斷螢幕命令 |

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

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

338| `ENABLE_CLAUDEAI_MCP_SERVERS` | 設定為 `false` 以停用 Claude Code 中的 [claude.ai MCP servers](/zh-TW/mcp#use-mcp-servers-from-claude-ai)。對於已登入的使用者預設啟用。若要按專案或按組織停用，請改為在設定中設定 [`disableClaudeAiConnectors`](/zh-TW/settings#available-settings) |340| `ENABLE_CLAUDEAI_MCP_SERVERS` | 設定為 `false` 以停用 Claude Code 中的 [claude.ai MCP servers](/zh-TW/mcp#use-mcp-servers-from-claude-ai)。對於已登入的使用者預設啟用。若要按專案或按組織停用，請改為在設定中設定 [`disableClaudeAiConnectors`](/zh-TW/settings#available-settings) |

339| `ENABLE_PROMPT_CACHING_1H` | 設定為 `1` 以要求 1 小時的提示快取 TTL，而不是預設的 5 分鐘。適用於 API 金鑰、[Bedrock](/zh-TW/amazon-bedrock)、[Vertex](/zh-TW/google-vertex-ai)、[Foundry](/zh-TW/microsoft-foundry) 和 [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 使用者。訂閱使用者自動接收 1 小時 TTL。1 小時快取寫入以更高的速率計費 |341| `ENABLE_PROMPT_CACHING_1H` | 設定為 `1` 以要求 1 小時的提示快取 TTL，而不是預設的 5 分鐘。適用於 API 金鑰、[Amazon Bedrock](/zh-TW/amazon-bedrock)、[Google Cloud's Agent Platform](/zh-TW/google-vertex-ai)、[Microsoft Foundry](/zh-TW/microsoft-foundry) 和 [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 使用者。訂閱使用者自動接收 1 小時 TTL。1 小時快取寫入以更高的速率計費 |

341| `ENABLE_TOOL_SEARCH` | 控制 [MCP tool search](/zh-TW/mcp#scale-with-mcp-tool-search)。未設定：預設所有 MCP 工具延遲，但在 Vertex AI 上或當 `ANTHROPIC_BASE_URL` 指向非第一方主機時提前載入。值：`true`（始終延遲並發送 beta 標頭，在 Vertex AI 或不支援 `tool_reference` 的代理上請求失敗）、`auto`（閾值模式：如果工具符合上下文的 10% 內則提前載入）、`auto:N`（自訂閾值，例如 `auto:5` 表示 5%）、`false`（提前載入全部） |343| `ENABLE_TOOL_SEARCH` | 控制 [MCP tool search](/zh-TW/mcp#scale-with-mcp-tool-search)。未設定：預設所有 MCP 工具延遲，但在 Google Cloud's Agent Platform 上或當 `ANTHROPIC_BASE_URL` 指向非第一方主機時提前載入。值：`true`（始終延遲並發送 beta 標頭，在 Google Cloud's Agent Platform 或不支援 `tool_reference` 的代理上請求失敗）、`auto`（閾值模式：如果工具符合上下文的 10% 內則提前載入）、`auto:N`（自訂閾值，例如 `auto:5` 表示 5%）、`false`（提前載入全部） |

342| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | 設定為任何非空值以在任何主要模型上重複過載錯誤後觸發回退。{/* min-version: 2.1.160 */}自 v2.1.160 起，配置的 [fallback model chain](/zh-TW/model-config#fallback-model-chains) 會在任何主要模型的重複過載錯誤時觸發，因此此變數不影響切換到回退模型 |344| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | 設定為任何非空值以在任何主要模型上重複過載錯誤後觸發回退。{/* min-version: 2.1.160 */}自 v2.1.160 起，配置的 [fallback model chain](/zh-TW/model-config#fallback-model-chains) 會在任何主要模型的重複過載錯誤時觸發，因此此變數不影響切換到回退模型 |

358| `MCP_TOOL_TIMEOUT` | MCP 工具執行的逾時（以毫秒為單位）（預設值：100000000，約 28 小時）。`.mcp.json` 中的每個伺服器 `timeout` 欄位會覆蓋該伺服器的此值。對於環境變數，低於 1000 的值會下限為 1 秒；對於每個伺服器欄位，低於 1000 的值會被忽略 |360| `MCP_TOOL_TIMEOUT` | MCP 工具執行的逾時（以毫秒為單位）（預設值：100000000，約 28 小時）。`.mcp.json` 中的每個伺服器 `timeout` 欄位會覆蓋該伺服器的此值。{/* min-version: 2.1.203 */}每個伺服器 `timeout` 至少 1000 也會設定該伺服器的工具呼叫的最小閒置視窗，因此 `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` 永遠不會更早中止它們；此下限需要 Claude Code v2.1.203 或更新版本。對於環境變數，低於 1000 的值會下限為 1 秒；對於每個伺服器欄位，低於 1000 的值會被忽略 |

360| `OTEL_LOG_ASSISTANT_RESPONSES` | {/* min-version: 2.1.193 */}設定為 `1` 以在 `assistant_response` OpenTelemetry 日誌事件上包含模型的回應文字。未設定時，使用 `OTEL_LOG_USER_PROMPTS` 的值。設定為 `0` 以保持回應編輯，即使設定 `OTEL_LOG_USER_PROMPTS`。需要 Claude Code v2.1.193 或更新版本。請參閱 [Monitoring](/zh-TW/monitoring-usage#assistant-response-event) |362| `OTEL_LOG_ASSISTANT_RESPONSES` | {/* min-version: 2.1.193 */}設定為 `1` 以在 `assistant_response` OpenTelemetry 日誌事件上包含模型的回應文字。未設定時，使用 `OTEL_LOG_USER_PROMPTS` 的值。設定為 `0` 以保持回應編輯，即使設定 `OTEL_LOG_USER_PROMPTS`。需要 Claude Code v2.1.193 或更新版本。請參閱 [Monitoring](/zh-TW/monitoring-usage#assistant-response-event) |

361| `OTEL_LOG_RAW_API_BODIES` | 設定為 `1` 以將完整的 Anthropic Messages API 請求和回應 JSON 作為 `api_request_body` / `api_response_body` 日誌事件發出（在 60 KB 處截斷），或 `file:<dir>` 以將未截斷的主體寫入磁碟並發出 `body_ref` 路徑。預設停用；主體包括整個對話歷史記錄。請參閱 [Monitoring](/zh-TW/monitoring-usage#api-request-body-event) |363| `OTEL_LOG_RAW_API_BODIES` | 設定為 `1` 以將完整的 Anthropic Messages API 請求和回應 JSON 作為 `api_request_body` / `api_response_body` 日誌事件發出（在 60 KB 處截斷），或 `file:<dir>` 以將未截斷的主體寫入磁碟並發出 `body_ref` 路徑。預設停用；主體包括整個對話歷史記錄。請參閱 [Monitoring](/zh-TW/monitoring-usage#api-request-body-event) |

370| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | 覆蓋顯示給 [Skill tool](/zh-TW/skills#control-who-invokes-a-skill) 的 skill 中繼資料的字元預算。預算在上下文視窗的 1% 處動態縮放，回退為 8,000 個字元。為了向後相容性保留舊名稱 |372| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | 覆蓋顯示給 [Skill tool](/zh-TW/skills#control-who-invokes-a-skill) 的 skill 中繼資料的字元預算。預算在上下文視窗的 1% 處動態縮放，回退為 8,000 個字元。為了向後相容性保留舊名稱 |

371| `TASK_MAX_OUTPUT_LENGTH` | [subagent](/zh-TW/sub-agents) 輸出在截斷前的最大字元數（預設值：32000，最大值：160000）。截斷時，完整輸出會儲存到磁碟，路徑會包含在截斷的回應中 |373| `TASK_MAX_OUTPUT_LENGTH` | [subagent](/zh-TW/sub-agents) 輸出在截斷前的最大字元數（預設值：32000，最大值：160000）。截斷時，完整輸出會儲存到磁碟，路徑會包含在截斷的回應中 |

383| `VERTEX_REGION_CLAUDE_4_7_OPUS` | {/* min-version: 2.1.111 */}使用 Vertex AI 時覆蓋 Claude Opus 4.7 的區域。在 v2.1.111 中新增 |385| `VERTEX_REGION_CLAUDE_4_7_OPUS` | {/* min-version: 2.1.111 */}使用 Google Cloud's Agent Platform 時覆蓋 Claude Opus 4.7 的區域。在 v2.1.111 中新增 |

384| `VERTEX_REGION_CLAUDE_4_8_OPUS` | {/* min-version: 2.1.154 */}使用 Vertex AI 時覆蓋 Claude Opus 4.8 的區域。在 v2.1.154 中新增 |386| `VERTEX_REGION_CLAUDE_4_8_OPUS` | {/* min-version: 2.1.154 */}使用 Google Cloud's Agent Platform 時覆蓋 Claude Opus 4.8 的區域。在 v2.1.154 中新增 |

385| `VERTEX_REGION_CLAUDE_5_SONNET` | {/* min-version: 2.1.197 */}使用 Vertex AI 時覆蓋 Claude Sonnet 5 的區域。在 v2.1.197 中新增 |387| `VERTEX_REGION_CLAUDE_5_SONNET` | {/* min-version: 2.1.197 */}}使用 Google Cloud's Agent Platform 時覆蓋 Claude Sonnet 5 的區域。在 v2.1.197 中新增 |

386| `VERTEX_REGION_CLAUDE_FABLE_5` | {/* min-version: 2.1.170 */}使用 Vertex AI 時覆蓋 Claude Fable 5 的區域。在 v2.1.170 中新增 |388| `VERTEX_REGION_CLAUDE_FABLE_5` | {{/* min-version: 2.1.170 */}}使用 Google Cloud's Agent Platform 時覆蓋 Claude Fable 5 的區域。在 v2.1.170 中新增 |

388 390

389標準 OpenTelemetry 匯出器變數（`OTEL_METRICS_EXPORTER`、`OTEL_LOGS_EXPORTER`、`OTEL_EXPORTER_OTLP_ENDPOINT`、`OTEL_EXPORTER_OTLP_PROTOCOL`、`OTEL_EXPORTER_OTLP_HEADERS`、`OTEL_METRIC_EXPORT_INTERVAL`、`OTEL_RESOURCE_ATTRIBUTES` 和信號特定變體）也受支援。請參閱 [Monitoring](/zh-TW/monitoring-usage) 以取得配置詳細資訊。391標準 OpenTelemetry 匯出器變數（`OTEL_METRICS_EXPORTER`、`OTEL_LOGS_EXPORTER`、`OTEL_EXPORTER_OTLP_ENDPOINT`、`OTEL_EXPORTER_OTLP_PROTOCOL`、`OTEL_EXPORTER_OTLP_HEADERS`、`OTEL_METRIC_EXPORT_INTERVAL`、`OTEL_RESOURCE_ATTRIBUTES` 和信號特定變體）也受支援。請參閱 [Monitoring](/zh-TW/monitoring-usage) 以取得配置詳細資訊。

390 392

errors.md +526 −301

Details

53| `SSL certificate verification failed` | [Network](#ssl-certificate-errors) |53| `SSL certificate verification failed` | [Network](#ssl-certificate-errors) |

54| `SSL certificate error (...)` during login or startup | [Network](#ssl-certificate-errors) |54| `SSL certificate error (...)` during login or startup | [Network](#ssl-certificate-errors) |

55| `403` with `x-deny-reason: host_not_allowed` in a cloud or routine session | [Network](#host-not-allowed-in-a-cloud-session) |55| `403` with `x-deny-reason: host_not_allowed` in a cloud or routine session | [Network](#host-not-allowed-in-a-cloud-session) |

56| `Couldn't reconnect to your Remote Control session` | [Network](#couldn%E2%80%99t-reconnect-to-your-remote-control-session) |

56| `Prompt is too long` | [Request errors](#prompt-is-too-long) |57| `Prompt is too long` | [Request errors](#prompt-is-too-long) |

57| `Error during compaction: Conversation too long` | [Request errors](#error-during-compaction-conversation-too-long) |58| `Error during compaction: Conversation too long` | [Request errors](#error-during-compaction-conversation-too-long) |

58| `Request too large` | [Request errors](#request-too-large) |59| `Request too large` | [Request errors](#request-too-large) |

61| `PDF too large` / `PDF is password protected` | [Request errors](#pdf-errors) |62| `PDF too large` / `PDF is password protected` | [Request errors](#pdf-errors) |

62| `Extra inputs are not permitted` | [Request errors](#extra-inputs-are-not-permitted) |63| `Extra inputs are not permitted` | [Request errors](#extra-inputs-are-not-permitted) |

63| `There's an issue with the selected model` | [Request errors](#there%E2%80%99s-an-issue-with-the-selected-model) |64| `There's an issue with the selected model` | [Request errors](#there%E2%80%99s-an-issue-with-the-selected-model) |

65| `Model ... is not a recognized model id` | [Request errors](#model-is-not-a-recognized-model-id) |

64| `Claude Opus is not available with the Claude Pro plan` | [Request errors](#claude-opus-is-not-available-with-the-claude-pro-plan) |66| `Claude Opus is not available with the Claude Pro plan` | [Request errors](#claude-opus-is-not-available-with-the-claude-pro-plan) |

65| `Model ... is restricted by your organization's settings` | [Request errors](#model-is-restricted-by-your-organization%E2%80%99s-settings) |67| `Model ... is restricted by your organization's settings` | [Request errors](#model-is-restricted-by-your-organization%E2%80%99s-settings) |

66| `thinking.type.enabled is not supported for this model` | [Request errors](#thinking-type-enabled-is-not-supported-for-this-model) |68| `thinking.type.enabled is not supported for this model` | [Request errors](#thinking-type-enabled-is-not-supported-for-this-model) |

67| `max_tokens must be greater than thinking.budget_tokens` | [Request errors](#thinking-budget-exceeds-output-limit) |69| `max_tokens must be greater than thinking.budget_tokens` | [Request errors](#thinking-budget-exceeds-output-limit) |

68| `API Error: 400 due to tool use concurrency issues` | [Request errors](#tool-use-or-thinking-block-mismatch) |70| `API Error: 400 due to tool use concurrency issues` | [Request errors](#tool-use-or-thinking-block-mismatch) |

69| `Claude Code is unable to respond to this request, which appears to violate our Usage Policy` | [Request errors](#usage-policy-refusal) |71| `Claude Code is unable to respond to this request, which appears to violate our Usage Policy` | [Request errors](#usage-policy-refusal) |

72| `<model> has safety measures that flagged this message for a cybersecurity topic` | [Request errors](#safety-measures-flagged-a-cybersecurity-topic) |

73| `Installation was killed before it could finish (exit code 137)` | [Installation errors](#installation-was-killed-before-it-could-finish) |

74| `The connection dropped while downloading the update` | [Installation errors](#the-connection-dropped-while-downloading-the-update) |

75| `Download timed out: exceeded the total deadline` | [Installation errors](#the-connection-dropped-while-downloading-the-update) |

70| `--bg and --print conflict` | [Command-line errors](#command-line-errors) |76| `--bg and --print conflict` | [Command-line errors](#command-line-errors) |

77| `Error: --json-schema is not a valid JSON Schema` | [Command-line errors](#command-line-errors) |

78| `Could not import <server>: <reason>` | [Command-line errors](#could-not-import-a-server-from-claude-desktop) |

79| `Marketplace "<name>" is registered from an untrusted source` | [Plugin errors](#marketplace-is-registered-from-an-untrusted-source) |

80| `Ignoring N permissions.allow entries from ... this workspace has not been trusted` | [Configuration warnings](#workspace-has-not-been-trusted) |

71| 回應品質似乎低於平常 | [Response quality](#responses-seem-lower-quality-than-usual) |81| 回應品質似乎低於平常 | [Response quality](#responses-seem-lower-quality-than-usual) |

72 82

73<h2 id="automatic-retries">83<h2 id="automatic-retries">

99 伺服器錯誤109 伺服器錯誤

100</h2>110</h2>

101 111

102這些錯誤來自推論提供者，而不是您的帳戶或請求。在 Anthropic API 上，這表示 Anthropic 基礎設施。在 Bedrock、Vertex AI、Foundry 或自訂閘道上，這表示該提供者的基礎設施。112這些錯誤來自推論提供者，而非您的帳戶或請求。在 Anthropic API 上，這表示 Anthropic 基礎設施。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或自訂閘道上，這表示該提供者的基礎設施。

103 113

104<h3 id="api-error-500-internal-server-error">114<h3 id="api-error-500-internal-server-error">

105 API Error: 500 Internal server error115 API 錯誤：500 內部伺服器錯誤

106</h3>116</h3>

107 117

108Claude Code 為任何 5xx 回應顯示狀態碼和 API 的錯誤訊息。下面的範例顯示 Anthropic API 上的 500 回應：118Claude Code 會顯示任何 5xx 回應的狀態碼和 API 的錯誤訊息。下面的範例顯示 Anthropic API 上的 500 回應：

109 119

110```text theme={null}120```text theme={null}

111API Error: 500 Internal server error. This is a server-side issue, usually temporary — try again in a moment. If it persists, check https://status.claude.com.121API Error: 500 Internal server error. This is a server-side issue, usually temporary — try again in a moment. If it persists, check https://status.claude.com.

112```122```

113 123

114尾部句子命名檢查服務健康狀況的位置，並因提供者而異。Bedrock、Vertex AI 和 Foundry 配置命名該提供者的服務狀態。自訂 `ANTHROPIC_BASE_URL` 命名閘道主機。124結尾的句子會指出要檢查服務健康狀態的位置，並因提供者而異。Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 配置會指出該提供者的服務狀態。自訂 `ANTHROPIC_BASE_URL` 會指出閘道主機。

115 125

116這表示 API 內部發生意外失敗。它不是由您的提示、設定或帳戶引起的。126這表示 API 內部發生了意外故障。它不是由您的提示、設定或帳戶造成的。

117 127

118**要做什麼：**128**該怎麼做：**

119 129

120* 檢查 [status.claude.com](https://status.claude.com) 或訊息中命名的提供者狀態頁面，以了解活躍的事件130* 檢查 [status.claude.com](https://status.claude.com) 或訊息中指名的提供者狀態頁面，查看是否有活躍的事件

121* 等待一分鐘，然後再次傳送您的訊息。您的原始訊息仍在對話中，因此對於長提示，您可以輸入 `try again` 而不是貼上整個內容。131* 等待一分鐘，然後再次傳送您的訊息。您的原始訊息仍在對話中，所以對於較長的提示，您可以輸入 `try again` 而不是貼上整個內容。

122* 如果錯誤持續存在且沒有發佈的事件，請執行 `/feedback` 以便 Anthropic 可以使用您的請求詳細資訊進行調查。如果您的環境中 `/feedback` 不可用，請參閱 [Report an error](#report-an-error)。132* 如果錯誤持續出現且沒有發佈的事件，請執行 `/feedback` 以便 Anthropic 可以使用您的請求詳細資訊進行調查。如果您的環境中無法使用 `/feedback`，請參閱[報告錯誤](#report-an-error)。

123 133

124<h3 id="api-error-repeated-529-overloaded-errors">134<h3 id="api-error-repeated-529-overloaded-errors">

125 API Error: Repeated 529 Overloaded errors135 API 錯誤：重複的 529 超載錯誤

126</h3>136</h3>

127 137

128API 在所有使用者中暫時達到容量。Claude Code 在顯示此訊息之前已經重試了多次：138API 在所有使用者中暫時達到容量上限。Claude Code 在顯示此訊息之前已經重試了多次：

129 139

130```text theme={null}140```text theme={null}

131API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. Try again in a moment. If it persists, check https://status.claude.com.141API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. Try again in a moment. If it persists, check https://status.claude.com.

132```142```

133 143

134尾部句子因提供者而異，方式與上面的 500 錯誤相同。529 不是您的使用限制，也不會計入您的配額。144結尾的句子因提供者而異，方式與上面的 500 錯誤相同。

135 145

136**要做什麼：**146529 不是您的使用限制，也不會計入您的配額。

137 147

138* 檢查 [status.claude.com](https://status.claude.com) 或訊息中命名的提供者狀態頁面，以了解容量通知148**該怎麼做：**

149

150* 檢查 [status.claude.com](https://status.claude.com) 或訊息中指名的提供者狀態頁面，查看是否有容量通知

139* 幾分鐘後再試一次151* 幾分鐘後再試一次

140* 執行 `/model` 並切換到不同的模型以繼續工作，因為容量是按模型追蹤的。當一個模型負載特別高時，Claude Code 會提示您執行此操作，例如 `Opus is experiencing high load, please use /model to switch to Sonnet`。152* 執行 `/model` 並切換到不同的模型以繼續工作，因為容量是按模型追蹤的。當某個模型負載特別高時，Claude Code 會提示您執行此操作，例如 `Opus is experiencing high load, please use /model to switch to Sonnet`。

141 153

142<h3 id="request-timed-out">154<h3 id="request-timed-out">

143 Request timed out155 請求逾時

144</h3>156</h3>

145 157

146API 在連線截止時間之前沒有回應。158API 在連線截止期限之前沒有回應。

147 159

148```text theme={null}160```text theme={null}

149Request timed out161Request timed out

150```162```

151 163

152這可能在高負載期間或生成非常大的回應時發生。預設請求逾時為 10 分鐘。164這可能在高負載期間或模型生成非常大的回應時發生。預設請求逾時為 10 分鐘。

153 165

154**要做什麼：**166**該怎麼做：**

155 167

156* 重試請求168* 重試請求

157* 對於長時間執行的任務，將工作分解為較小的提示169* 對於長時間執行的任務，將工作分解為較小的提示

158* 如果原因是慢速網路或代理，請按照 [Automatic retries](#automatic-retries) 中的說明提高 `API_TIMEOUT_MS`170* 如果是緩慢的網路或代理造成的，請按照[自動重試](#automatic-retries)中的說明提高 `API_TIMEOUT_MS`

159* 如果逾時頻繁且您的網路在其他方面是健康的，請參閱下面的 [Network and connection errors](#network-and-connection-errors)171* 如果逾時頻繁且您的網路狀況良好，請參閱下面的[網路和連線錯誤](#network-and-connection-errors)

160 172

161<h3 id="the-response-above-may-be-incomplete">173<h3 id="the-response-above-may-be-incomplete">

162 The response above may be incomplete174 上面的回應可能不完整

163</h3>175</h3>

164 176

165串流回應在 Claude 已經產生可見輸出後失敗。重新傳送請求可能會執行相同的工具呼叫兩次，因此 Claude Code 會保留已經串流的內容並附加此通知，而不是捨棄轉向。您看到的變體命名原因：177串流回應在 Claude 已經產生可見輸出後失敗。重新傳送請求可能會執行相同的工具呼叫兩次，所以 Claude Code 會保留已經串流的內容，並改為附加此通知，而不是捨棄該輪次。您看到的變體會指出原因：

166 178

167```text theme={null}179```text theme={null}

168API Error: Server error mid-response. The response above may be incomplete.180API Error: Server error mid-response. The response above may be incomplete.

170API Error: Response stalled mid-stream. The response above may be incomplete.182API Error: Response stalled mid-stream. The response above may be incomplete.

171```183```

172 184

173* {/* min-version: 2.1.199 */}}`Server error mid-response`：中途過載或 5xx 伺服器錯誤。此變體需要 Claude Code v2.1.199 或更新版本；在此之前，該情況會捨棄部分輸出並將整個轉向報告為錯誤。185* {/* min-version: 2.1.199 */}}`Server error mid-response`：中途串流超載或 5xx 伺服器錯誤。此變體需要 Claude Code v2.1.199 或更新版本；在此之前，該情況會捨棄部分輸出並將整個輪次報告為錯誤。

174* `Connection closed mid-response`：連線已中斷。186* `Connection closed mid-response`：連線中斷。

175* `Response stalled mid-stream`：串流停止傳送資料。187* `Response stalled mid-stream`：串流停止傳送資料。

176 188

177**要做什麼：**189**該怎麼做：**

178 190

179* 閱讀串流的回應。沒有任何內容遺失，但最後的句子或工具呼叫可能會遺失。191* 閱讀已串流的回應。沒有任何內容遺失，但最後的句子或工具呼叫可能缺失。

180* 回覆 `continue` 以讓 Claude 從停止的地方繼續192* 回覆 `continue` 以讓 Claude 從停止的地方繼續

181* 如果相同的錯誤在任何可見輸出之前出現，Claude Code 會重試請求，而不是完成它。請參閱 [Automatic retries](#automatic-retries)。193* 如果相同的錯誤在任何可見輸出之前出現，Claude Code 會重試請求而不是完成它。請參閱[自動重試](#automatic-retries)。

182 194

183<h3 id="auto-mode-cannot-determine-the-safety-of-an-action">195<h3 id="auto-mode-cannot-determine-the-safety-of-an-action">

184 Auto mode cannot determine the safety of an action196 自動模式無法判斷動作的安全性

185</h3>197</h3>

186 198

187用來 [auto mode](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 分類動作的模型無法產生決定，因此 auto mode 沒有自動批准該動作。您看到的訊息取決於分類器失敗的原因。199[自動模式](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)用來分類動作的模型無法做出決定，所以自動模式沒有自動批准該動作。您看到的訊息取決於分類器失敗的原因。

188 200

189在您的工作目錄內的讀取、搜尋和編輯會跳過分類器，因此它們在所有這些情況下都能繼續工作。201在您的工作目錄內的讀取、搜尋和編輯會跳過分類器，所以它們在所有這些情況下都能繼續工作。

190 202

191當分類器模型過載時：203當分類器模型超載時：

192 204

193```text theme={null}205```text theme={null}

194<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool> right now. Wait briefly and then try this action again.206<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool> right now. Wait briefly and then try this action again.

195```207```

196 208

197**要做什麼：**209**該怎麼做：**

198 210

199* 幾秒鐘後重試；Claude 看到相同的訊息，通常會自動重試211* 幾秒鐘後重試；Claude 會看到相同的訊息，通常會自動重試

200* 如果重試持續失敗，繼續進行唯讀任務，稍後再回到被阻止的動作212* 如果重試持續失敗，請繼續執行唯讀任務，稍後再回到被阻止的動作

201* 這是暫時的，與 [auto mode eligibility](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 無關；您不需要更改設定213* 這是暫時的，與[自動模式資格](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)無關；您不需要變更設定

202 214

203當分類器傳回無法解析的回應時：215當分類器傳回無法解析的回應時：

204 216

206Auto mode could not evaluate this action and is blocking it for safety — run with --debug for details218Auto mode could not evaluate this action and is blocking it for safety — run with --debug for details

207```219```

208 220

209**要做什麼：**221**該怎麼做：**

210 222

211* 重試該動作；這通常在下一次嘗試時成功223* 重試該動作；這通常在下一次嘗試時成功

212* 執行 `claude --debug` 並重複該動作以在偵錯日誌中查看基礎分類器回應224* 執行 `claude --debug` 並重複該動作以在偵錯日誌中查看基礎分類器回應

213 225

214當對話已增長到超過分類器的上下文視窗時：226當單獨的 API 安全檢查因為較早的對話內容而阻止了分類器請求時：

227

228```text theme={null}

229Auto mode could not evaluate this action and is blocking it for safety — a safety check separate from auto mode blocked this request because of earlier conversation content — it isn't about the action itself — run with --debug for details

230```

231

232**該怎麼做：**

233

234* 這不是關於您的動作的決定。您對話中已有的內容在自動模式將對話傳送給分類器時觸發了 API 上的安全篩選器

235* 重試無法幫助；相同的對話內容會再次觸發篩選器

236* 切換到不同的[權限模式](/zh-TW/permission-modes)，以便在出現提示時批准該動作，或開始一個沒有觸發內容的新對話

237

238當對話大小超過分類器的上下文視窗時：

215 239

216```text theme={null}240```text theme={null}

217Auto mode classifier transcript exceeded context window — falling back to manual approval (try /compact to reduce conversation size)241Auto mode classifier transcript exceeded context window — falling back to manual approval (try /compact to reduce conversation size)

218```242```

219 243

220在互動式工作階段中，auto mode 會針對該動作回退到正常的權限提示，以便您可以手動批准或拒絕它。在 [非互動式模式](/zh-TW/headless) 中，執行會中止，因為文字記錄只會增長，重試無法成功。244在互動式工作階段中，自動模式會為該動作回退到正常的權限提示，以便您可以手動批准或拒絕它。在[非互動式模式](/zh-TW/headless)中，執行會中止，因為文字記錄只會增長，重試無法成功。

221 245

222**要做什麼：**246**該怎麼做：**

223 247

224* 在出現的提示中批准或拒絕該動作248* 在出現的提示中批准或拒絕該動作

225* 執行 `/compact` 以減少對話大小，以便後續動作再次適應分類器視窗內249* 執行 `/compact` 以減少對話大小，以便後續動作再次適應分類器視窗

226 250

227<h3 id="agent-terminated-early-due-to-an-api-error">251<h3 id="agent-terminated-early-due-to-an-api-error">

228 Agent terminated early due to an API error252 代理因 API 錯誤而提前終止

229</h3>253</h3>

230 254

231{/* min-version: 2.1.199 */}[subagent](/zh-TW/sub-agents) 的 API 請求終止失敗，例如因為達到使用限制或伺服器錯誤的重試用盡，因此子代理在完成其任務之前停止。此訊息需要 Claude Code v2.1.199 或更新版本；在此之前，API 錯誤文字被傳回給 Claude，就像它是子代理的結果一樣。255{/* min-version: 2.1.199 */}[子代理](/zh-TW/sub-agents)的 API 請求終止失敗，例如因為達到使用限制或伺服器錯誤的重試用盡，所以子代理在完成其任務之前停止。此訊息需要 Claude Code v2.1.199 或更新版本；在此之前，API 錯誤文字被傳回給 Claude，就像它是子代理的結果一樣。

232 256

233```text theme={null}257```text theme={null}

234Agent terminated early due to an API error: <error detail>258Agent terminated early due to an API error: <error detail>

235```259```

236 260

237**要做什麼：**261**該怎麼做：**

238 262

239* 將冒號後的錯誤詳細資訊與本頁上的其自己的部分相符，例如 [Usage limits](#usage-limits) 或 [Server errors](#server-errors)，並遵循該部分的步驟263* 將冒號後的錯誤詳細資訊與此頁面上的自己的部分相符，例如[使用限制](#usage-limits)或[伺服器錯誤](#server-errors)，並遵循該部分的步驟

240* 一旦基礎錯誤清除，要求 Claude 重試任務或 [resume the subagent](/zh-TW/sub-agents#resume-subagents)264* 一旦基礎錯誤清除，請要求 Claude 重試任務或[恢復子代理](/zh-TW/sub-agents#resume-subagents)

241 265

242當速率限制、過載或伺服器錯誤中斷已經產生輸出的前景子代理時，Claude 會收到該部分輸出標記為不完整，而不是此錯誤。請參閱 [API errors in subagents](/zh-TW/sub-agents#api-errors-in-subagents)。266當速率限制、超載或伺服器錯誤中斷已經產生文字輸出的前景子代理時，Claude 會收到該部分輸出標記為不完整，而不是此錯誤。{/* min-version: 2.1.200 */}只有工具呼叫輸出的子代理也會收到此錯誤；在 v2.1.199 中，該形狀改為傳回空的部分結果。請參閱[子代理中的 API 錯誤](/zh-TW/sub-agents#api-errors-in-subagents)。

243 267

244<h2 id="usage-limits">268<h2 id="usage-limits">

245 使用限制269 使用限制

246</h2>270</h2>

247 271

248這些錯誤表示與您的帳戶或計畫相關的配額已達到。它們與影響所有人的 [server errors](#server-errors) 不同。272這些錯誤表示與您的帳戶或方案相關的配額已達到。它們與[伺服器錯誤](#server-errors)不同，伺服器錯誤會影響所有人。

249 273

250<h3 id="you’ve-hit-your-session-limit">274<h3 id="you’ve-hit-your-session-limit">

251 You've hit your session limit275 您已達到工作階段限制

252</h3>276</h3>

253 277

254訂閱計畫包括滾動使用額度。當它用完時，您會看到以下訊息之一：278訂閱方案包括滾動使用額度。當額度用完時，您會看到以下其中一條訊息：

255 279

256```text theme={null}280```text theme={null}

257You've hit your session limit · resets 3:45pm281You've hit your session limit · resets 3:45pm

261 285

262Claude Code 會阻止進一步的請求，直到訊息中顯示的重設時間。286Claude Code 會阻止進一步的請求，直到訊息中顯示的重設時間。

263 287

264**要做什麼：**288**該怎麼做：**

265 289

266* 等待錯誤中顯示的重設時間290* 等待錯誤訊息中顯示的重設時間

267* 執行 `/usage` 以查看您的計畫限制及其重設時間291* 執行 `/usage` 以查看您的方案限制及其重設時間

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

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

270 294

271若要在達到限制之前監視您的剩餘額度，請將 `rate_limits` 欄位新增到 [custom status line](/zh-TW/statusline#rate-limit-usage)，或在 Desktop app 中按一下模型選擇器旁邊的 [usage ring](/zh-TW/desktop#check-usage)。295若要在達到限制之前監控您的剩餘額度，請將 `rate_limits` 欄位新增至[自訂狀態列](/zh-TW/statusline#rate-limit-usage)，或在桌面應用程式中按一下模型選擇器旁的[使用量環](/zh-TW/desktop#check-usage)。

272 296

273<h3 id="usage-credits-required-for-1m-context">297<h3 id="usage-credits-required-for-1m-context">

274 Usage credits required for 1M context298 1M 上下文需要使用額度

275</h3>299</h3>

276 300

277所選模型使用 1M 令牌擴展上下文視窗，而您的計畫僅透過使用額度包括它。301選定的模型使用 1M 令牌擴展上下文視窗，而您的方案僅透過使用額度包含它。

278 302

279```text theme={null}303```text theme={null}

280API Error: Usage credits required for 1M context · run /usage-credits to turn them on, or /model to switch to standard context304API Error: Usage credits required for 1M context · run /usage-credits to turn them on, or /model to switch to standard context

281```305```

282 306

283這是一項權利檢查，而不是配額耗盡。即使您的工作階段和每週額度仍有容量，它也會觸發。請參閱 [Extended context](/zh-TW/model-config#extended-context) 以了解哪些計畫直接包括 1M 上下文，哪些需要使用額度。307這是一項權利檢查，而不是配額耗盡。即使您的工作階段和每週額度仍有容量，它也會觸發。請參閱[擴展上下文](/zh-TW/model-config#extended-context)以了解哪些方案直接包含 1M 上下文，哪些需要使用額度。

284 308

285{/* min-version: 2.1.172 */}當此錯誤在對話中途出現，因為上下文增長超過 200K 令牌時，Claude Code 會自動將對話壓縮回標準上下文限制以下，並在之後將工作階段保持在該限制，因此無需採取任何行動。在 v2.1.172 之前的版本上，錯誤會在每個後續請求（包括 `/compact`）上重複出現；在這些版本上執行 `/clear` 以恢復。以下步驟適用於您明確選擇 `[1m]` 模型的情況。309{/* min-version: 2.1.172 */}當此錯誤在對話中途出現，因為上下文增長超過 200K 令牌時，Claude Code 會自動將對話壓縮回標準上下文限制以下，並在之後將工作階段保持在該限制，因此無需採取任何行動。在 v2.1.172 之前的版本上，錯誤會在每個後續請求（包括 `/compact`）上重複出現；在這些版本上執行 `/clear` 以恢復。以下步驟適用於您明確選擇 `[1m]` 模型的情況。

286 310

287**要做什麼：**311**該怎麼做：**

288 312

289* 執行 `/model` 並選擇不帶 `[1m]` 後綴的變體以回退到標準上下文視窗313* 執行 `/model` 並選擇不帶 `[1m]` 後綴的變體以回退到標準上下文視窗

290* 執行 `/usage-credits` 以在 Pro 和 Max 上開啟 1M 變體的計量計費，或在 Team 和 Enterprise 上向您的管理員請求314* 執行 `/usage-credits` 以在 Pro 和 Max 上開啟 1M 變體的計量計費，或在 Team 和 Enterprise 上向您的管理員請求

291* 如果執行 `/model` 後錯誤仍然存在，1M 模型 ID 可能在其他地方設定。請參閱 [There's an issue with the selected model](#there%E2%80%99s-an-issue-with-the-selected-model) 以了解要按優先順序檢查的配置位置。315* 如果 `/model` 後錯誤仍然存在，1M 模型 ID 可能在其他地方設定。請參閱[選定的模型有問題](#there%E2%80%99s-an-issue-with-the-selected-model)以按優先順序檢查配置位置。

292* 若要從模型選擇器中完全移除 1M 變體，請設定 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/zh-TW/env-vars)316* 若要從模型選擇器中完全移除 1M 變體，請設定 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/zh-TW/env-vars)

293 317

294<h3 id="server-is-temporarily-limiting-requests">318<h3 id="server-is-temporarily-limiting-requests">

295 Server is temporarily limiting requests319 伺服器暫時限制請求

296</h3>320</h3>

297 321

298API 應用了與您的計畫配額無關的短期節流。322API 應用了與您的方案配額無關的短期節流。

299 323

300```text theme={null}324```text theme={null}

301API Error: Server is temporarily limiting requests (not your usage limit)325API Error: Server is temporarily limiting requests (not your usage limit)

302```326```

303 327

304Claude Code 透過缺少真實限制回應所帶的統一配額標頭來區分這些。{/* min-version: 2.1.199 */}自 v2.1.199 起，這會 [自動重試](#automatic-retries)，無論您如何認證。在較早的版本上，使用 claude.ai 訂閱登入的工作階段在第一次出現時失敗轉向；只有 API 金鑰和 Enterprise 登入重試它。328Claude Code 透過真實限制回應所攜帶的統一配額標頭的缺失來區分這些與您的方案限制。{/* min-version: 2.1.199 */}自 v2.1.199 起，無論您如何驗證，這都會[自動重試](#automatic-retries)並進行退避，然後才會顯示。在較早的版本上，使用 claude.ai 訂閱登入的工作階段在第一次出現時失敗；只有 API 金鑰和 Enterprise 登入會重試它。

305 329

306**要做什麼：**330**該怎麼做：**

307 331

308* 稍等片刻，然後再試一次332* 稍等片刻後重試

309* 如果持續存在，請檢查 [status.claude.com](https://status.claude.com)333* 如果問題持續，請檢查 [status.claude.com](https://status.claude.com)

310 334

311<h3 id="request-rejected-429">335<h3 id="request-rejected-429">

312 Request rejected (429)336 請求被拒絕 (429)

313</h3>337</h3>

314 338

315您已達到為您的 API 金鑰、Amazon Bedrock 專案或 Google Vertex AI 專案配置的速率限制。339您已達到為 API 金鑰、Amazon Bedrock 專案或 Google Cloud 專案配置的速率限制。

316 340

317```text theme={null}341```text theme={null}

318API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com.342API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com.

319```343```

320 344

321尾部句子命名了檢查服務健康狀況的位置，並因提供者而異。Bedrock、Vertex AI 和 Foundry 配置會命名該提供者的服務狀態，而不是 Anthropic 狀態頁面。自訂 `ANTHROPIC_BASE_URL` 會命名閘道主機。345尾部句子命名檢查服務健康狀況的位置，並因提供者而異。Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 配置會命名該提供者的服務狀態，而不是 Anthropic 狀態頁面。自訂 `ANTHROPIC_BASE_URL` 會命名閘道主機。

322 346

323**要做什麼：**347**該怎麼做：**

324 348

325* 執行 `/status` 並確認活躍的認證是您期望的。環境中的流浪 `ANTHROPIC_API_KEY` 可能會透過低階金鑰而不是您的訂閱路由請求。349* 執行 `/status` 並確認作用中的認證是您預期的認證。環境中的流浪 `ANTHROPIC_API_KEY` 可能會透過低階金鑰而不是您的訂閱來路由請求。

326* 檢查您的提供者主控台以了解活躍的限制，並在需要時請求更高的層級350* 檢查您的提供者主控台以了解作用中的限制，並在需要時請求更高的層級

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

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

329 353

330<h3 id="credit-balance-is-too-low">354<h3 id="credit-balance-is-too-low">

331 Credit balance is too low355 信用額度餘額過低

332</h3>356</h3>

333 357

334您的 Console 組織已用完預付額度。358您的 Console 組織已用完預付信用額度。

335 359

336```text theme={null}360```text theme={null}

337Credit balance is too low361Credit balance is too low

338```362```

339 363

340**要做什麼：**364**該怎麼做：**

341 365

342* 在 [platform.claude.com/settings/billing](https://platform.claude.com/settings/billing) 新增額度，並考慮在那裡啟用自動重新載入，以便在達到零之前重新填充餘額366* 在 [platform.claude.com/settings/billing](https://platform.claude.com/settings/billing) 新增信用額度，並考慮在那裡啟用自動重新載入，以便在餘額達到零之前進行補充

343* 如果您有 Pro、Max、Team 或 Enterprise 計畫，請使用 `/login` 切換到訂閱認證367* 如果您有 Pro、Max、Team 或 Enterprise 方案，請使用 `/login` 切換到訂閱驗證

344* 在 Console 中設定每個工作區的支出上限，以防止單個專案耗盡組織餘額。請參閱 [Manage costs effectively](/zh-TW/costs)。368* 在 Console 中設定每個工作區的支出上限，以防止單一專案耗盡組織餘額。請參閱[有效管理成本](/zh-TW/costs)。

345 369

346<h2 id="authentication-errors">370<h2 id="authentication-errors">

347 認證錯誤371 驗證錯誤

348</h2>372</h2>

349 373

350這些錯誤表示 Claude Code 無法向 API 證明您的身份。隨時執行 `/status` 以查看目前活躍的認證。374這些錯誤表示 Claude Code 無法向 API 證明您的身份。隨時執行 `/status` 以查看目前使用的認證方式。

351 375

352<h3 id="not-logged-in">376<h3 id="not-logged-in">

353 Not logged in377 未登入

354</h3>378</h3>

355 379

356此工作階段沒有有效的認證可用。380此工作階段沒有有效的認證方式可用。

357 381

358```text theme={null}382```text theme={null}

359Not logged in · Please run /login383Not logged in · Please run /login

360```384```

361 385

362**要做什麼：**386**應該怎麼做：**

363 387

364* 執行 `/login` 以使用您的 Claude 訂閱或 Console 帳戶進行認證388* 執行 `/login` 以使用您的 Claude 訂閱或 Console 帳戶進行驗證

365* 如果您期望環境變數對您進行認證，請確認 `ANTHROPIC_API_KEY` 已在您啟動 `claude` 的 shell 中設定並匯出389* 如果您預期使用環境變數進行驗證，請確認 `ANTHROPIC_API_KEY` 已在啟動 `claude` 的 shell 中設定並匯出

366* 對於無法進行互動式登入的 CI 或自動化，請配置一個 [`apiKeyHelper`](/zh-TW/settings#available-settings) 指令碼，在啟動時擷取金鑰390* 對於無法進行互動式登入的 CI 或自動化環境，請設定一個 [`apiKeyHelper`](/zh-TW/settings#available-settings) 指令碼，在啟動時取得金鑰

367* 請參閱 [Authentication precedence](/zh-TW/authentication#authentication-precedence) 以了解當存在多個認證時哪個會獲勝391* 請參閱[驗證優先順序](/zh-TW/authentication#authentication-precedence)以了解當存在多個認證方式時，Claude Code 使用哪一個

368 392

369如果系統提示您重複登入，請參閱 [Not logged in or token expired](/zh-TW/troubleshoot-install#not-logged-in-or-token-expired) 以了解系統時鐘和 macOS Keychain 修復。393如果系統反覆提示您登入，請參閱[未登入或權杖已過期](/zh-TW/troubleshoot-install#not-logged-in-or-token-expired)以取得系統時鐘和 macOS Keychain 的修復方法。

370 394

371<h3 id="could-not-resolve-authentication-method">395<h3 id="could-not-resolve-authentication-method">

372 Could not resolve authentication method396 無法解析驗證方法

373</h3>397</h3>

374 398

375工作階段到達 API 用戶端時沒有任何認證。這會出現在[背景工作階段](/zh-TW/agent-view)、雲端工作階段和 Agent SDK 環境中，其中互動式登入檢查在第一個請求之前不會執行。399工作階段到達 API 用戶端時沒有任何認證方式。這會出現在[背景工作階段](/zh-TW/agent-view)、雲端工作階段和 Agent SDK 環境中，其中互動式登入檢查在第一個請求之前不會執行。

376 400

377```text theme={null}401```text theme={null}

378Could not resolve authentication method. Expected one of apiKey, authToken, credentials, config, or profile to be set. Or for one of the "X-Api-Key" or "Authorization" headers to be explicitly omitted402Could not resolve authentication method. Expected one of apiKey, authToken, credentials, config, or profile to be set. Or for one of the "X-Api-Key" or "Authorization" headers to be explicitly omitted

379```403```

380 404

381{/* min-version: 2.1.174 */}在 v2.1.174 之前，分配給閒置預初始化背景工作程序的背景或雲端工作階段即使配置了有效認證也可能以這種方式失敗。升級以恢復。在目前版本中，此錯誤表示沒有認證可用於背景工作程序。405{/* min-version: 2.1.174 */}在 v2.1.174 之前，指派給閒置預初始化背景工作程序的背景或雲端工作階段即使已設定有效認證方式也可能以此方式失敗。請升級以恢復。在目前版本中，此錯誤表示背景工作程序沒有可用的認證方式。

382 406

383**要做什麼：**407**應該怎麼做：**

384 408

385* 如果這出現在背景或雲端工作階段中且您的認證已配置，請升級到 v2.1.174 或更新版本409* 如果此錯誤出現在背景或雲端工作階段中且您的認證方式已設定，請升級至 v2.1.174 或更新版本

386* 確認 `ANTHROPIC_API_KEY`、`CLAUDE_CODE_OAUTH_TOKEN` 或您的雲端提供者認證已在啟動背景工作程序的環境中設定，而不僅在您的互動式 shell 中410* 確認 `ANTHROPIC_API_KEY`、`CLAUDE_CODE_OAUTH_TOKEN` 或您的雲端提供者認證方式已在啟動背景工作程序的環境中設定，而不僅在您的互動式 shell 中

387* 對於 Agent SDK，請參閱[認證設定](/zh-TW/agent-sdk/overview#get-started)411* 對於 Agent SDK，請參閱[驗證設定](/zh-TW/agent-sdk/overview#get-started)

388* 在相同環境中的互動式工作階段中執行 `/status` 以確認哪個認證來源會解析412* 在相同環境中的互動式工作階段中執行 `/status` 以確認哪個認證方式來源可以解析

389 413

390<h3 id="invalid-api-key">414<h3 id="invalid-api-key">

391 Invalid API key415 無效的 API 金鑰

392</h3>416</h3>

393 417

394`ANTHROPIC_API_KEY` 環境變數或 `apiKeyHelper` 指令碼傳回的金鑰被 API 拒絕。418`ANTHROPIC_API_KEY` 環境變數或 `apiKeyHelper` 指令碼傳回的金鑰被 API 拒絕。

397Invalid API key · Fix external API key421Invalid API key · Fix external API key

398```422```

399 423

400**要做什麼：**424**應該怎麼做：**

401 425

402* 檢查拼寫錯誤，並確認金鑰未在 [Console](https://platform.claude.com/settings/keys) 中被撤銷426* 檢查是否有拼寫錯誤，並確認該金鑰未在 [Console](https://platform.claude.com/settings/keys) 中被撤銷

403* 在同一個 shell 中執行 `env | grep ANTHROPIC`。direnv、dotenv shell 外掛程式和 IDE 終端等工具可以從您的專案中的 `.env` 檔案載入過時的金鑰，而無需您明確設定它。427* 在相同的 shell 中執行 `env | grep ANTHROPIC`。direnv、dotenv shell 外掛程式和 IDE 終端等工具可能會從您專案中的 `.env` 檔案載入過時的金鑰，而您並未明確設定它

404* 取消設定 `ANTHROPIC_API_KEY` 並執行 `/login` 以改用訂閱認證428* 取消設定 `ANTHROPIC_API_KEY` 並執行 `/login` 以改用訂閱驗證

405* 如果金鑰來自 [`apiKeyHelper`](/zh-TW/settings#available-settings) 指令碼，請直接執行指令碼以確認它在 stdout 上列印有效的金鑰429* 如果金鑰來自 [`apiKeyHelper`](/zh-TW/settings#available-settings) 指令碼，請直接執行該指令碼以確認它在 stdout 上列印有效的金鑰

406* 執行 `/status` 以確認 Claude Code 實際使用的認證來源430* 執行 `/status` 以確認 Claude Code 實際使用的認證方式來源

407 431

408<h3 id="this-organization-has-been-disabled">432<h3 id="this-organization-has-been-disabled">

409 This organization has been disabled433 此組織已被停用

410</h3>434</h3>

411 435

412來自已停用 Console 組織的過時 `ANTHROPIC_API_KEY` 正在覆蓋您的訂閱登入。436來自已停用 Console 組織的過時 `ANTHROPIC_API_KEY` 正在覆蓋您的訂閱登入。

416API Error: 400 ... This organization has been disabled.440API Error: 400 ... This organization has been disabled.

417```441```

418 442

419環境變數優先於 `/login`，因此在您的 shell 設定檔中匯出或從 `.env` 檔案載入的金鑰即使您有有效的 Pro 或 Max 訂閱也會被使用。在非互動式模式 (`-p`) 中，當存在金鑰時總是使用該金鑰。443環境變數優先於 `/login`，因此即使您有有效的 Pro 或 Max 訂閱，在 shell 設定檔中匯出或從 `.env` 檔案載入的金鑰也會被使用。在非互動模式 (`-p`) 中，當金鑰存在時總是使用該金鑰。

420 444

421**要做什麼：**445**應該怎麼做：**

422 446

423* 在目前的 shell 中取消設定 `ANTHROPIC_API_KEY` 並從您的 shell 設定檔中移除它，然後重新啟動 `claude`447* 在目前 shell 中取消設定 `ANTHROPIC_API_KEY` 並從您的 shell 設定檔中移除它，然後重新啟動 `claude`

424* 之後執行 `/status` 以確認活躍的認證是您的訂閱448* 之後執行 `/status` 以確認使用中的認證方式是您的訂閱

425* 如果未設定環境變數且錯誤持續存在，則已停用的組織是與您的 `/login` 相關聯的組織。聯絡支援或使用不同的帳戶登入。449* 如果未設定環境變數且錯誤仍然存在，則已停用的組織是與您的 `/login` 相關聯的組織。請聯絡支援或使用不同的帳戶登入。

426 450

427<h3 id="your-organization-has-disabled-api-key-authentication">451<h3 id="your-organization-has-disabled-api-key-authentication">

428 Your organization has disabled API key authentication452 您的組織已停用 API 金鑰驗證

429</h3>453</h3>

430 454

431此訊息需要 Claude Code v2.1.169 或更新版本。您的 Console 組織管理員已關閉 API 金鑰認證，因此 API 拒絕了 Claude Code 正在傳送的金鑰。`·` 之後的復原提示會根據金鑰的來源而異：455此訊息需要 Claude Code v2.1.169 或更新版本。您的 Console 組織管理員已關閉 API 金鑰驗證，因此 API 拒絕了 Claude Code 正在傳送的金鑰。`·` 之後的恢復提示會根據金鑰的來源而有所不同：

432 456

433```text theme={null}457```text theme={null}

434Your organization has disabled API key authentication · Run /login to sign in with your claude.ai account458Your organization has disabled API key authentication · Run /login to sign in with your claude.ai account

437Your organization has disabled API key authentication · Unset the apiKeyHelper setting and run /login to sign in with your claude.ai account461Your organization has disabled API key authentication · Unset the apiKeyHelper setting and run /login to sign in with your claude.ai account

438```462```

439 463

440環境變數和 `apiKeyHelper` 優先於 `/login`，因此在任一仍在提供金鑰時單獨執行 `/login` 無法幫助。請參閱 [Authentication precedence](/zh-TW/authentication#authentication-precedence)。464環境變數和 `apiKeyHelper` 優先於 `/login`，因此當其中任一個仍在提供金鑰時，單獨執行 `/login` 無法幫助。請參閱[驗證優先順序](/zh-TW/authentication#authentication-precedence)。

441 465

442**要做什麼：**466**應該怎麼做：**

443 467

444* 如果訊息提及 `ANTHROPIC_API_KEY`，請在目前的 shell 中取消設定它，並從您的 shell 設定檔或 `.env` 檔案中移除它，然後重新啟動 `claude`468* 如果訊息提及 `ANTHROPIC_API_KEY`，請在目前 shell 中取消設定它，並從您的 shell 設定檔或 `.env` 檔案中移除它，然後重新啟動 `claude`

445* 如果訊息提及 `apiKeyHelper`，請從您的 `settings.json` 中移除 [`apiKeyHelper`](/zh-TW/settings#available-settings) 設定469* 如果訊息提及 `apiKeyHelper`，請從您的 `settings.json` 中移除 [`apiKeyHelper`](/zh-TW/settings#available-settings) 設定

446* 執行 `/login` 以使用您的 claude.ai 帳戶登入470* 執行 `/login` 以使用您的 claude.ai 帳戶登入

447* 之後執行 `/status` 以確認活躍的認證是您的訂閱而不是 API 金鑰471* 之後執行 `/status` 以確認使用中的認證方式是您的訂閱而不是 API 金鑰

448* 如果您需要 API 金鑰認證進行自動化，請要求您的組織管理員在 Console 中重新啟用它472* 如果您需要 API 金鑰驗證進行自動化，請要求您的組織管理員在 Console 中重新啟用它

449 473

450<h3 id="your-organization-has-disabled-claude-subscription-access">474<h3 id="your-organization-has-disabled-claude-subscription-access">

451 Your organization has disabled Claude subscription access475 您的組織已停用 Claude 訂閱存取

452</h3>476</h3>

453 477

454您的 Claude 組織不允許使用訂閱登入來登入 Claude Code。使用相同帳戶再次執行 `/login` 會傳回相同的錯誤。478您的 Claude 組織不允許使用訂閱登入來登入 Claude Code。使用相同帳戶再次執行 `/login` 會傳回相同的錯誤。

457Your organization has disabled Claude subscription access for Claude Code · Use an Anthropic API key instead, or ask your admin to enable access481Your organization has disabled Claude subscription access for Claude Code · Use an Anthropic API key instead, or ask your admin to enable access

458```482```

459 483

460這是一個伺服器端組織設定，因此無法從本機設定、環境變數或 CLI 旗標覆蓋。Agent SDK 和 `-p` 非互動式模式將此呈現為 `oauth_org_not_allowed` 錯誤代碼。484這是伺服器端組織設定，因此無法從本機設定、環境變數或 CLI 旗標覆蓋。

461 485

462**要做什麼：**486Agent SDK 和 `-p` 非互動模式將此顯示為 `oauth_org_not_allowed` 錯誤代碼。

487

488**應該怎麼做：**

463 489

464* 要求您的管理員為您的組織啟用 Claude Code 存取490* 要求您的管理員為您的組織啟用 Claude Code 存取

465* 改用 Console API 金鑰進行認證，而不是您的訂閱。請參閱 [Claude Console authentication](/zh-TW/authentication#claude-console-authentication) 以了解設定。491* 使用 Console API 金鑰而不是您的訂閱進行驗證。請參閱 [Claude Console 驗證](/zh-TW/authentication#claude-console-authentication)以進行設定。

466* 如果您是管理員且看不到啟用存取的選項，請聯絡 [Anthropic support](https://support.claude.com)492* 如果您是管理員且看不到啟用存取的選項，請聯絡 [Anthropic 支援](https://support.claude.com)

467 493

468<h3 id="routines-are-disabled-by-your-organization’s-policy">494<h3 id="routines-are-disabled-by-your-organization’s-policy">

469 Routines are disabled by your organization's policy495 您的組織政策已停用例行工作

470</h3>496</h3>

471 497

472您的 Team 或 Enterprise 管理員已在組織層級關閉了例程。當您嘗試建立或執行例程時會出現此錯誤，包括從 `/schedule` 和 claude.ai/code 上的 [Routines](/zh-TW/routines) UI。498您的 Team 或 Enterprise 組織中的擁有者已在組織層級關閉例行工作。當您嘗試建立或執行例行工作時（包括從 `/schedule` 和 claude.ai/code 上的[例行工作](/zh-TW/routines) UI），會出現此錯誤。

473 499

474```text theme={null}500```text theme={null}

475Routines are disabled by your organization's policy.501Routines are disabled by your organization's policy.

476```502```

477 503

478這是一個伺服器端設定，因此無法從本機設定、環境變數或 CLI 旗標覆蓋。504這是伺服器端設定，因此無法從本機設定、環境變數或 CLI 旗標覆蓋。

479 505

480**要做什麼：**506**應該怎麼做：**

481 507

482* 要求您的管理員在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 啟用 **Routines** 切換508* 要求您的組織中的擁有者在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 啟用**例行工作**切換

483* 對於不需要組織層級例程的一次性排程工作，請參閱 [scheduled tasks](/zh-TW/scheduled-tasks)509* 對於不需要組織層級例行工作的一次性排程工作，請參閱[排程工作](/zh-TW/scheduled-tasks)

484 510

485<h3 id="remote-control-requires-the-anthropic-api">511<h3 id="remote-control-requires-the-anthropic-api">

486 Remote Control requires the Anthropic API512 Remote Control 需要 Anthropic API

487</h3>513</h3>

488 514

489此工作階段不是直接與 Anthropic API 通訊，因此沒有 claude.ai 後端供 [Remote Control](/zh-TW/remote-control) 配對。515工作階段未直接與 Anthropic API 通訊，因此沒有 claude.ai 後端供 [Remote Control](/zh-TW/remote-control) 配對。

490 516

491```text theme={null}517```text theme={null}

492Remote Control is only available when using Claude via api.anthropic.com.518Remote Control is only available when using Claude via api.anthropic.com.

493```519```

494 520

495這會出現在 Amazon Bedrock、Google Vertex AI 和 Microsoft Foundry 上。{/* min-version: 2.1.196 */}自 v2.1.196 開始，當 [`ANTHROPIC_BASE_URL`](/zh-TW/env-vars) 指向 `api.anthropic.com` 以外的主機時，例如 [LLM gateway](/zh-TW/llm-gateway) 或代理，即使您使用 claude.ai 登入，它也會出現。521這會出現在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上。{/* min-version: 2.1.196 */}從 v2.1.196 開始，當 [`ANTHROPIC_BASE_URL`](/zh-TW/env-vars) 指向 `api.anthropic.com` 以外的主機（例如 [LLM 閘道](/zh-TW/llm-gateway)或代理）時，即使您使用 claude.ai 登入，也會出現此訊息。

496 522

497**要做什麼：**523**應該怎麼做：**

498 524

499* 取消設定 `ANTHROPIC_BASE_URL` 並重新啟動工作階段，或從直接與 Anthropic API 通訊的工作階段啟動 Remote Control525* 取消設定 `ANTHROPIC_BASE_URL` 並重新啟動工作階段，或從直接與 Anthropic API 通訊的工作階段啟動 Remote Control

500* 對於此錯誤和其他 Remote Control 啟動訊息，請參閱 [Troubleshoot Remote Control](/zh-TW/remote-control#troubleshooting)526* 對於此訊息和其他 Remote Control 啟動訊息，請參閱[疑難排解 Remote Control](/zh-TW/remote-control#troubleshooting)

501 527

502<h3 id="oauth-token-revoked-or-expired">528<h3 id="oauth-token-revoked-or-expired">

503 OAuth token revoked or expired529 OAuth 權杖已撤銷或已過期

504</h3>530</h3>

505 531

506您的已儲存登入不再有效。撤銷的令牌表示您在任何地方登出或管理員移除了存取權；過期的令牌表示自動重新整理在工作階段中途失敗。532您儲存的登入不再有效。撤銷的權杖表示您已在所有地方登出或管理員移除了存取；過期的權杖表示自動重新整理在工作階段中途失敗。

507 533

508```text theme={null}534```text theme={null}

509OAuth token revoked · Please run /login535OAuth token revoked · Please run /login

511API Error: 401 ... authentication_error537API Error: 401 ... authentication_error

512```538```

513 539

514**要做什麼：**540**應該怎麼做：**

515 541

516* 執行 `/login` 以再次登入542* 執行 `/login` 以重新登入

517* 如果在同一工作階段中重新認證後錯誤返回，請先執行 `/logout` 以完全清除儲存的令牌，然後執行 `/login`543* 如果在同一工作階段中重新驗證後錯誤仍然出現，請先執行 `/logout` 以完全清除儲存的權杖，然後執行 `/login`

518* 對於跨啟動的重複登入提示，請參閱 [Troubleshooting](/zh-TW/troubleshoot-install#not-logged-in-or-token-expired) 中的系統時鐘和 macOS Keychain 檢查544* 對於跨啟動的重複登入提示，請參閱[疑難排解](/zh-TW/troubleshoot-install#not-logged-in-or-token-expired)中的系統時鐘和 macOS Keychain 檢查

519* 對於其他失敗（包括 `403 Forbidden` 和 OAuth 瀏覽器問題），請參閱 [Login and authentication](/zh-TW/troubleshoot-install#login-and-authentication)545* 對於其他失敗（包括 `403 Forbidden` 和 OAuth 瀏覽器問題），請參閱[登入和驗證](/zh-TW/troubleshoot-install#login-and-authentication)

520 546

521<h3 id="oauth-scope-requirement">547<h3 id="oauth-scope-requirement">

522 OAuth scope requirement548 OAuth 範圍要求

523</h3>549</h3>

524 550

525儲存的令牌早於較新功能所需的權限範圍。您最常從 `/usage` 和狀態行使用指標看到這一點：551儲存的權杖早於較新功能所需的權限範圍。您最常從 `/usage` 和狀態列使用量指示器看到此訊息：

526 552

527```text theme={null}553```text theme={null}

528OAuth token does not meet scope requirement: user:profile554OAuth token does not meet scope requirement: user:profile

529```555```

530 556

531**要做什麼：**557**應該怎麼做：**

532 558

533* 執行 `/login` 以使用目前的範圍鑄造新令牌。您不需要先登出。559* 執行 `/login` 以取得具有目前範圍的新權杖。您不需要先登出。

534 560

535<h3 id="aws-credentials-expired-or-invalid">561<h3 id="aws-credentials-expired-or-invalid">

536 AWS credentials expired or invalid562 AWS 認證方式已過期或無效

537</h3>563</h3>

538 564

539{/* min-version: 2.1.198 */}此訊息需要 Claude Code v2.1.198 或更新版本，且僅在 [`awsAuthRefresh`](/zh-TW/amazon-bedrock#advanced-credential-configuration) 在您的設定檔案中設定時出現。您的 AWS 工作階段令牌過期或被拒絕，而 Claude Code 已經執行的自動重新整理沒有產生 API 接受的認證。它出現在來自 [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 或 [Mantle endpoint](/zh-TW/amazon-bedrock#use-the-mantle-endpoint) 的 401，這是這些提供者報告過期安全令牌的方式。565{/* min-version: 2.1.198 */}此訊息需要 Claude Code v2.1.198 或更新版本，且僅在您的設定檔中設定了 [`awsAuthRefresh`](/zh-TW/amazon-bedrock#advanced-credential-configuration) 時出現。您的 AWS 工作階段權杖已過期或被拒絕，Claude Code 已執行的自動重新整理未產生 API 接受的認證方式。它會出現在來自 [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 或 [Mantle 端點](/zh-TW/amazon-bedrock#use-the-mantle-endpoint) 的 401 上，這是這些提供者報告過期安全權杖的方式。

540 566

541中間的動作提示命名您設定中的 `awsAuthRefresh` 命令，因此它會有所不同。穩定的部分是前導 `AWS credentials expired or invalid`：567中間的動作提示會命名您設定中的 `awsAuthRefresh` 命令，因此會有所不同。穩定的部分是前導的 `AWS credentials expired or invalid`：

542 568

543```text theme={null}569```text theme={null}

544AWS credentials expired or invalid · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · API Error: 401 ...570AWS credentials expired or invalid · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · API Error: 401 ...

545```571```

546 572

547如果未配置 `awsAuthRefresh`，相同的 401 會改為顯示通用 `Please run /login` 訊息，無法重新整理 AWS 認證。573如果未設定 `awsAuthRefresh`，相同的 401 會改為顯示通用的 `Please run /login` 訊息，該訊息無法重新整理 AWS 認證方式。

548 574

549**要做什麼：**575**應該怎麼做：**

550 576

551* 在另一個終端中執行訊息中命名的 `awsAuthRefresh` 命令（例如 `aws sso login --profile myprofile`）並完成瀏覽器登入，然後重試577* 在另一個終端中執行訊息中命名的 `awsAuthRefresh` 命令（例如 `aws sso login --profile myprofile`）並完成瀏覽器登入，然後重試

552* 在互動式工作階段中，執行 `/login`，選擇 **3rd-party platform**，然後在 **Using 3rd-party platforms** 下選擇 **Claude Platform on AWS · refresh credentials** 以執行相同的命令而無需重新啟動 Claude Code。請參閱 [Configure AWS credentials](/zh-TW/claude-platform-on-aws#1-configure-aws-credentials)578* 在互動式工作階段中，執行 `/login`，選擇 **3rd-party platform**，然後在 **Using 3rd-party platforms** 下選擇 **Claude Platform on AWS · refresh credentials** 以執行相同的命令而無需重新啟動 Claude Code。請參閱[設定 AWS 認證方式](/zh-TW/claude-platform-on-aws#1-configure-aws-credentials)

553* 如果重新整理命令成功後錯誤重複出現，請在同一 shell 和設定檔中使用 `aws sts get-caller-identity` 確認身份在 Claude Code 外有效579* 如果重新整理命令成功後錯誤仍然重複出現，請在相同的 shell 和設定檔中使用 `aws sts get-caller-identity` 確認身份在 Claude Code 外部有效

554 580

555<h3 id="aws-authentication-failed">581<h3 id="aws-authentication-failed">

556 AWS authentication failed582 AWS 驗證失敗

557</h3>583</h3>

558 584

559{/* min-version: 2.1.198 */}此訊息需要 Claude Code v2.1.198 或更新版本，且僅在 [`awsAuthRefresh`](/zh-TW/amazon-bedrock#advanced-credential-configuration) 在您的設定檔案中設定時出現。您的 AWS 提供者傳回 403，或 [Amazon Bedrock](/zh-TW/amazon-bedrock) 傳回 401。585{/* min-version: 2.1.198 */}此訊息需要 Claude Code v2.1.198 或更新版本，且僅在您的設定檔中設定了 [`awsAuthRefresh`](/zh-TW/amazon-bedrock#advanced-credential-configuration) 時出現。您的 AWS 提供者傳回了 403，或 [Amazon Bedrock](/zh-TW/amazon-bedrock) 傳回了 401。

560 586

561Claude Code 無法判斷您遇到的是哪個原因。Amazon Bedrock 將過期的安全令牌報告為 403，但 403 也是它報告授權拒絕的方式，例如來自遺失 IAM 權限或未為您的帳戶啟用的模型的 `AccessDeniedException`。587Claude Code 無法判斷您遇到了哪個原因。Amazon Bedrock 將過期的安全權杖報告為 403，但 403 也是它報告授權拒絕的方式，例如來自遺失 IAM 權限或未為您的帳戶啟用的模型的 `AccessDeniedException`。

562 588

563來自 Amazon Bedrock 的 401 也會落在這裡，而不是在 [AWS credentials expired or invalid](#aws-credentials-expired-or-invalid) 下，因為 Bedrock 不會將過期令牌報告為 401。來自該端點的 401 通常來自請求路徑中的其他內容，例如公司代理。589來自 Amazon Bedrock 的 401 也會落在此處而不是在 [AWS 認證方式已過期或無效](#aws-credentials-expired-or-invalid) 下，因為 Amazon Bedrock 不會將過期的權杖報告為 401。來自該端點的 401 通常來自請求路徑中的其他內容，例如公司代理。

564 590

565認證重新整理可以修復過期令牌，無法修復其他原因，因此訊息提供兩者：591認證方式重新整理可以修復過期的權杖，無法修復其他原因，因此訊息提供了兩者：

566 592

567```text theme={null}593```text theme={null}

568AWS authentication failed · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · if credentials are current, check AWS permissions and model access · API Error: 403 ...594AWS authentication failed · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · if credentials are current, check AWS permissions and model access · API Error: 403 ...

569```595```

570 596

571中間的動作提示命名您設定中的 `awsAuthRefresh` 命令，因此它會有所不同。穩定的部分是前導 `AWS authentication failed`。597中間的動作提示會命名您設定中的 `awsAuthRefresh` 命令，因此會有所不同。穩定的部分是前導的 `AWS authentication failed`。

572 598

573**要做什麼：**599**應該怎麼做：**

574 600

575* 執行訊息中命名的 `awsAuthRefresh` 命令或 `aws sso login`，以防過期認證是原因601* 執行訊息中命名的 `awsAuthRefresh` 命令或 `aws sso login`，以防過期的認證方式是原因

576* 如果您的認證是最新的，請確認 [IAM configuration](/zh-TW/amazon-bedrock#iam-configuration) 中的 IAM 權限已附加到您使用的身份，並且所選模型已為您的帳戶和區域啟用602* 如果您的認證方式是最新的，請確認 [IAM 配置](/zh-TW/amazon-bedrock#iam-configuration) 中的 IAM 權限已附加到您使用的身份，且所選模型已為您的帳戶和區域啟用

577* 執行 `aws sts get-caller-identity` 以確認您的請求使用哪個身份；過時的 `AWS_PROFILE` 或預設設定檔是權限不匹配的常見原因603* 執行 `aws sts get-caller-identity` 以確認您的請求使用哪個身份；過時的 `AWS_PROFILE` 或預設設定檔是權限不匹配的常見原因

578 604

579<h2 id="network-and-connection-errors">605<h2 id="network-and-connection-errors">

580 網路和連線錯誤606 網路和連線錯誤

581</h2>607</h2>

582 608

583這些錯誤表示 Claude Code 的網路請求無法到達其目的地。它們通常源於您的本地網路、代理或防火牆，或雲端環境的網路政策。609這些錯誤表示來自 Claude Code 的網路請求無法到達其目的地。它們通常源自您的本機網路、代理伺服器或防火牆，或雲端環境的網路政策。

584 610

585<h3 id="unable-to-connect-to-api">611<h3 id="unable-to-connect-to-api">

586 Unable to connect to API612 無法連線到 API

587</h3>613</h3>

588 614

589到 API 的 TCP 連線失敗或從未完成。615與 API 的 TCP 連線失敗或從未完成。

590 616

591```text theme={null}617```text theme={null}

592Unable to connect to API. Check your internet connection618Unable to connect to API. Check your internet connection

597Request timed out. Check your internet connection and proxy settings623Request timed out. Check your internet connection and proxy settings

598```624```

599 625

600常見原因包括沒有網際網路存取、阻止 `api.anthropic.com` 的 VPN 或未配置的必需公司代理。626常見原因包括沒有網際網路存取、阻止 `api.anthropic.com` 的 VPN，或未設定的必要公司代理伺服器。

601 627

602**要做什麼：**628**該怎麼做：**

603 629

604* 透過從同一個 shell 執行 `curl -I https://api.anthropic.com` 來確認您可以到達 API 主機。在 Windows PowerShell 上使用 `curl.exe -I https://api.anthropic.com` 以便不使用內建的 `Invoke-WebRequest` 別名。630* 透過在同一個 shell 中執行 `curl -I https://api.anthropic.com` 來確認您可以到達 API 主機。在 Windows PowerShell 上使用 `curl.exe -I https://api.anthropic.com`，以免使用內建的 `Invoke-WebRequest` 別名。

605* 如果您在公司代理後面，請在啟動 Claude Code 之前設定 `HTTPS_PROXY` 並參閱 [Network configuration](/zh-TW/network-config)631* 如果您在公司代理伺服器後面，請在啟動 Claude Code 前設定 `HTTPS_PROXY`，並參閱[網路設定](/zh-TW/network-config)

606* 如果您透過 LLM 閘道或中繼路由，請將 [`ANTHROPIC_BASE_URL`](/zh-TW/env-vars) 設定為其位址。請參閱 [Connect Claude Code to an LLM gateway](/zh-TW/llm-gateway-connect) 以了解設定。632* 如果您透過 LLM 閘道或中繼站路由，請將 [`ANTHROPIC_BASE_URL`](/zh-TW/env-vars) 設定為其位址。請參閱[將 Claude Code 連線到 LLM 閘道](/zh-TW/llm-gateway-connect)以取得設定說明。

607* 確保您的防火牆允許 [Network access requirements](/zh-TW/network-config#network-access-requirements) 中列出的主機633* 確保您的防火牆允許[網路存取需求](/zh-TW/network-config#network-access-requirements)中列出的主機

608* 間歇性失敗會 [自動重試](#automatic-retries)；持續失敗指向本地網路問題634* 間歇性故障會[自動重試](#automatic-retries)；持續性故障指向本機網路問題

609 635

610如果 `curl` 成功但 Claude Code 仍然失敗，原因通常是執行時和網路之間的某些東西，而不是網路本身：636如果 `curl` 成功但 Claude Code 仍然失敗，原因通常是執行時間和網路之間的某些東西，而不是網路本身：

611 637

612* 在 Linux 和 WSL 上，檢查 `/etc/resolv.conf` 是否有無法到達的名稱伺服器。WSL 特別可以從主機繼承損壞的解析器。638* 在 Linux 和 WSL 上，檢查 `/etc/resolv.conf` 是否有無法到達的名稱伺服器。特別是 WSL 可能會從主機繼承損壞的解析器。

613* 在 macOS 上，已斷開連線或卸載的 VPN 用戶端可能會留下隧道介面或路由規則。檢查 `ifconfig` 以了解過時的 `utun` 介面，並在系統設定中移除 VPN 的網路擴充功能。639* 在 macOS 上，已斷開連線或卸載的 VPN 用戶端可能會留下隧道介面或路由規則。檢查 `ifconfig` 是否有過時的 `utun` 介面，並在系統設定中移除 VPN 的網路擴充功能。

614* Docker Desktop 和類似的容器執行時可以攔截出站流量。退出它們並重試以排除這一點。640* Docker Desktop 和類似的容器執行時間可能會攔截出站流量。結束它們並重試以排除此可能性。

615 641

616<h3 id="ssl-certificate-errors">642<h3 id="ssl-certificate-errors">

617 SSL certificate errors643 SSL 憑證錯誤

618</h3>644</h3>

619 645

620您網路上的代理或安全設備正在使用其自己的憑證攔截 TLS 流量，而 Claude Code 不信任它。646您網路上的代理伺服器或安全設備正在用其自己的憑證攔截 TLS 流量，而 Claude Code 不信任它。

621 647

622```text theme={null}648```text theme={null}

623Unable to connect to API: SSL certificate verification failed. Check your proxy or corporate SSL certificates649Unable to connect to API: SSL certificate verification failed. Check your proxy or corporate SSL certificates

624Unable to connect to API: Self-signed certificate detected650Unable to connect to API: Self-signed certificate detected

625```651```

626 652

627{/* min-version: 2.1.199 */}自 v2.1.199 起，憑證驗證失敗不會重試，因此此錯誤會在第一次嘗試時出現，而不是在完整 [retry budget](#automatic-retries) 之後。較早的版本會在顯示之前重試幾分鐘。暫時性 TLS 條件（例如握手逾時）仍會重試。653{/* min-version: 2.1.199 */}自 v2.1.199 起，憑證驗證失敗不會重試，因此此錯誤會在第一次嘗試時出現，而不是在完整[重試預算](#automatic-retries)後出現。較早的版本在顯示它之前會花費幾分鐘重試。暫時性 TLS 條件（例如握手逾時）仍會重試。

628 654

629在 `/login` 和啟動連線檢查期間，相同的失敗會以 OpenSSL 代碼和內聯修復報告：655在 `/login` 和啟動連線檢查期間，同樣的失敗會以 OpenSSL 代碼和內聯修復報告：

630 656

631```text theme={null}657```text theme={null}

632SSL certificate error (UNABLE_TO_GET_ISSUER_CERT_LOCALLY). If you are behind a corporate proxy or TLS-intercepting firewall, set NODE_EXTRA_CA_CERTS to your CA bundle path, or ask IT to allowlist *.anthropic.com. Run /doctor for details.658SSL certificate error (UNABLE_TO_GET_ISSUER_CERT_LOCALLY). If you are behind a corporate proxy or TLS-intercepting firewall, set NODE_EXTRA_CA_CERTS to your CA bundle path, or ask IT to allowlist *.anthropic.com. Run `claude doctor` for details.

633```659```

634 660

635**要做什麼：**661**該怎麼做：**

636 662

637* 匯出您組織的 CA 套件，並使用 `NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem` 指向 Claude Code663* 匯出您組織的 CA 套件，並使用 `NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem` 將 Claude Code 指向它

638* 請參閱 [Network configuration](/zh-TW/network-config#custom-ca-certificates) 以了解完整的設定說明664* 請參閱[網路設定](/zh-TW/network-config#custom-ca-certificates)以取得完整設定說明

639* 不要設定 `NODE_TLS_REJECT_UNAUTHORIZED=0`，這會完全停用憑證驗證665* 不要設定 `NODE_TLS_REJECT_UNAUTHORIZED=0`，這會完全停用憑證驗證

640 666

641<h3 id="host-not-allowed-in-a-cloud-session">667<h3 id="host-not-allowed-in-a-cloud-session">

642 Host not allowed in a cloud session668 雲端工作階段中不允許的主機

643</h3>669</h3>

644 670

645來自雲端工作階段或例行程序的出站 HTTP 請求被環境的網路政策阻止。671來自雲端工作階段或例行程序的出站 HTTP 請求被環境的網路政策阻止。

649x-deny-reason: host_not_allowed675x-deny-reason: host_not_allowed

650```676```

651 677

652您也可能看到與目的地實際憑證不符的 TLS 憑證。雲端環境透過代理路由出站流量以強制執行網路政策，因此不符的憑證表示代理終止了連線，而不是目的地。678您也可能看到與目的地實際憑證不符的 TLS 憑證。雲端環境透過代理伺服器路由出站流量以強制執行網路政策，因此不符的憑證表示代理伺服器終止了連線，而不是目的地。

679

680這不是用戶端網路問題。雲端工作階段和[例行程序](/zh-TW/routines)在沙箱環境內執行，其出站流量被篩選到環境的允許清單。**預設**環境使用**信任**存取，允許[預設允許清單](/zh-TW/claude-code-on-the-web#default-allowed-domains)的套件登錄、雲端提供者 API、容器登錄和常見開發網域，但阻止其他所有內容。

653 681

654這不是用戶端網路問題。雲端工作階段和 [routines](/zh-TW/routines) 在沙箱環境內執行，其出站流量被篩選到環境的允許清單。**Default** 環境使用 **Trusted** 存取，允許 [預設允許清單](/zh-TW/claude-code-on-the-web#default-allowed-domains) 的套件登錄、雲端提供者 API、容器登錄和常見開發網域，但阻止其他所有內容。682**該怎麼做：**

655 683

656**要做什麼：**684* 開啟例行程序進行編輯，或啟動雲端工作階段。選擇顯示您環境名稱（例如**預設**）的雲端圖示以開啟選擇器。將滑鼠懸停在您的環境上，然後按一下設定圖示。

685* 在**更新雲端環境**對話方塊中，將**網路存取**從**信任**變更為**自訂**，然後將被阻止的網域新增到**允許的網域**。每行輸入一個網域。勾選**也包含常見套件管理員的預設清單**以在自訂網域旁保留[預設允許清單](/zh-TW/claude-code-on-the-web#default-allowed-domains)。如果您想要不受限制的存取，請改為選擇**完整**。

686* 按一下**儲存變更**。下一次執行會使用更新的允許清單。

657 687

658* 開啟例行程序進行編輯，或啟動雲端工作階段。選擇顯示您環境名稱的雲端圖示，例如 **Default**，以開啟選擇器。將滑鼠懸停在您的環境上，然後按一下設定圖示。688請參閱[網路存取](/zh-TW/claude-code-on-the-web#network-access)以取得存取層級和預設允許清單。本機 CLI 工作階段不受此政策影響。

659* 在 **Update cloud environment** 對話方塊中，將 **Network access** 從 **Trusted** 變更為 **Custom**，然後將被阻止的網域新增至 **Allowed domains**。每行輸入一個網域。勾選 **Also include default list of common package managers** 以在自訂網域旁保留 [預設允許清單](/zh-TW/claude-code-on-the-web#default-allowed-domains)。如果您想要不受限制的存取，請改為選擇 **Full**。689

660* 按一下 **Save changes**。下一次執行使用更新的允許清單。690<h3 id="couldn’t-reconnect-to-your-remote-control-session">

691 無法重新連線到您的遠端控制工作階段

692</h3>

693

694```text theme={null}

695Couldn't reconnect to your Remote Control session. Retry, or start a fresh session without --resume.

696```

661 697

662請參閱 [Network access](/zh-TW/claude-code-on-the-web#network-access) 以了解存取層級和預設允許清單。本地 CLI 工作階段不受此政策影響。698使用 `claude --resume` 或 `claude --continue` 恢復會重新連線到該對話中記錄的[遠端控制](/zh-TW/remote-control)工作階段。此訊息表示重新連線因可能是暫時性的原因（例如網路中斷或伺服器錯誤）而失敗，因此 Claude Code 無法確認遠端工作階段是否仍然存在。您的本機工作階段會繼續執行，但不使用遠端控制。

699

700**該怎麼做：**

701

702* 執行 `/remote-control` 以重試連線

703* 啟動 Claude Code 時不使用 `--resume` 以建立新的遠端控制工作階段

704* 如需其他遠端控制啟動訊息，請參閱[遠端控制疑難排解](/zh-TW/remote-control#troubleshooting)

705

706當伺服器確認前一個工作階段不再存在時，您不會看到此訊息；Claude Code 在這種情況下會建立一個新的工作階段。{/* min-version: 2.1.200 */}在 v2.1.200 之前，任何重新連線失敗都會建立新的遠端控制工作階段，這在 claude.ai/code 的工作階段清單中留下額外的工作階段。

663 707

664<h2 id="request-errors">708<h2 id="request-errors">

665 請求錯誤709 請求錯誤

666</h2>710</h2>

667 711

668這些錯誤表示 API 收到了您的請求但拒絕了其內容。712這些錯誤與您的請求內容有關。大多數來自 API 在拒絕請求後的回應；少數是由 Claude Code 在發送任何請求之前在本地產生的。

669 713

670<h3 id="prompt-is-too-long">714<h3 id="prompt-is-too-long">

671 Prompt is too long715 提示詞過長

672</h3>716</h3>

673 717

674對話加上附加檔案超過了模型的上下文視窗。718對話加上附加檔案超過了模型的上下文視窗。

677Prompt is too long721Prompt is too long

678```722```

679 723

680**要做什麼：**724**該怎麼做：**

681 725

682* 執行 `/compact` 以總結較早的轉向並釋放空間，或執行 `/clear` 以重新開始726* 執行 `/compact` 來總結早期的回合並釋放空間，或執行 `/clear` 來重新開始

683* 執行 `/context` 以查看消耗視窗的內容的細目：系統提示、工具、記憶檔案和訊息727* 執行 `/context` 來查看視窗消耗的詳細分解：系統提示詞、工具、記憶檔案和訊息

684* 使用 `/mcp disable <name>` 停用您未使用的 MCP 伺服器，以從上下文中移除其工具定義728* 使用 `/mcp disable <name>` 停用您未使用的 MCP 伺服器，以從上下文中移除其工具定義

685* 修剪大型 `CLAUDE.md` 記憶檔案，或將說明移至 [path-scoped rules](/zh-TW/memory#path-specific-rules)，這些規則僅在相關時載入729* 修剪大型 `CLAUDE.md` 記憶檔案，或將指令移至[路徑範圍規則](/zh-TW/memory#path-specific-rules)，這些規則只在相關時載入

686* 子代理從父工作階段繼承每個 MCP 工具定義，這可能會在第一個轉向之前填滿其上下文視窗。在生成子代理之前停用您未使用的 MCP 伺服器。730* 子代理繼承父工作階段中的每個 MCP 工具定義，這可能會在第一個回合之前填滿其上下文視窗。在生成子代理之前停用您未使用的 MCP 伺服器。

687* 自動壓縮預設為開啟，通常可防止此錯誤。如果您已設定 [`DISABLE_AUTO_COMPACT`](/zh-TW/env-vars)，請重新啟用它或在視窗填滿之前手動執行 `/compact`。731* 自動壓縮預設為開啟，通常可防止此錯誤。如果您已設定 [`DISABLE_AUTO_COMPACT`](/zh-TW/env-vars)，請重新啟用它或在視窗填滿之前手動執行 `/compact`。

688 732

689請參閱 [Explore the context window](/zh-TW/context-window) 以取得上下文如何填滿的互動式檢視。733請參閱[探索上下文視窗](/zh-TW/context-window)以取得上下文如何填滿的互動式檢視。

690 734

691<h3 id="error-during-compaction-conversation-too-long">735<h3 id="error-during-compaction-conversation-too-long">

692 Error during compaction: Conversation too long736 壓縮期間出錯：對話過長

693</h3>737</h3>

694 738

695`/compact` 本身失敗，因為沒有足夠的可用上下文來保存它產生的摘要。739`/compact` 本身失敗，因為沒有足夠的可用上下文來保存它產生的摘要。

698Error during compaction: Conversation too long. Press esc twice to go up a few messages and try again.742Error during compaction: Conversation too long. Press esc twice to go up a few messages and try again.

699```743```

700 744

701當視窗在自動壓縮觸發時已經滿了，或當您在看到 `Prompt is too long` 後執行 `/compact` 時，可能會發生這種情況。745當視窗在自動壓縮觸發時已滿，或當您在看到 `Prompt is too long` 後執行 `/compact` 時，可能會發生這種情況。

702 746

703**要做什麼：**747**該怎麼做：**

704 748

705* 按 Esc 兩次以開啟訊息清單並回退幾個轉向。這會從上下文中刪除最近的訊息。然後再次執行 `/compact`。749* 按 Esc 兩次以開啟訊息清單並回溯幾個回合。這會從上下文中移除最近的訊息。然後再次執行 `/compact`。

706* 如果回退沒有釋放足夠的空間，請執行 `/clear` 以啟動新的工作階段。您之前的對話已保留，可以使用 `/resume` 重新開啟。750* 如果回溯沒有釋放足夠的空間，執行 `/clear` 以開始新的工作階段。您之前的對話會被保留，可以使用 `/resume` 重新開啟。

707 751

708<h3 id="request-too-large">752<h3 id="request-too-large">

709 Request too large753 請求過大

710</h3>754</h3>

711 755

712原始請求主體在標記化之前超過了 API 的位元組限制，通常是因為貼上的大型檔案或附件。756原始請求主體在標記化之前超過了 API 的位元組限制，通常是因為貼上了大型檔案或附件。

713 757

714```text theme={null}758```text theme={null}

715Request too large (max 30 MB). Double press esc to go back and remove or shrink the attached content.759Request too large (max 30 MB). Double press esc to go back and remove or shrink the attached content.

716```760```

717 761

718這是 HTTP 請求的大小限制，與 [context window limit](#prompt-is-too-long) 分開。762這是 HTTP 請求的大小限制，與[上下文視窗限制](#prompt-is-too-long)分開。

719 763

720**要做什麼：**764**該怎麼做：**

721 765

722* 按 Esc 兩次並回退到新增超大內容的轉向之前766* 按 Esc 兩次並回溯到添加超大內容的回合之前

723* 按路徑參考大型檔案而不是貼上其內容，以便 Claude 可以分塊讀取它們767* 按路徑參考大型檔案而不是貼上其內容，以便 Claude 可以分塊讀取它們

724* 對於影像，請參閱下面的 [Image was too large](#image-was-too-large)768* 對於影像，請參閱下面的[影像過大](#image-was-too-large)

725 769

726<h3 id="image-was-too-large">770<h3 id="image-was-too-large">

727 Image was too large771 影像過大

728</h3>772</h3>

729 773

730貼上或附加的影像超過了 API 的大小或尺寸限制。774貼上或附加的影像超過了 API 的大小或尺寸限制。

734API Error: 400 ... image dimensions exceed max allowed size778API Error: 400 ... image dimensions exceed max allowed size

735```779```

736 780

737{/* min-version: 2.1.142 */}Claude Code 會將無法處理的影像替換為文字預留位置並重試，因此後續訊息會成功。在 2.1.142 之前的版本上，貼上的影像可能會保留在對話中，並在每個後續訊息上重複相同的錯誤。若要在這些版本上恢復，請按 Esc 兩次並回退到新增影像的轉向之前。781{/* min-version: 2.1.142 */}Claude Code 將無法處理的影像替換為文字佔位符並重試，因此後續訊息會成功。在 2.1.142 之前的版本上，貼上的影像可能會保留在對話中，並在每個後續訊息上重複相同的錯誤。若要在這些版本上恢復，請按 Esc 兩次並回溯到添加影像的回合之前。

738 782

739**要做什麼：**783**該怎麼做：**

740 784

741* 在貼上之前調整影像大小。API 接受單個影像最長邊最多 8000 像素的影像，或當許多影像在上下文中時為 2000 像素。785* 在貼上之前調整影像大小。API 接受單個影像最長邊最多 8000 像素的影像，或當許多影像在上下文中時為 2000 像素。

742* 拍攝相關區域的更緊密螢幕截圖，而不是整個螢幕786* 拍攝相關區域的更緊密螢幕截圖，而不是整個螢幕

743 787

744<h3 id="unable-to-resize-image">788<h3 id="unable-to-resize-image">

745 Unable to resize image789 無法調整影像大小

746</h3>790</h3>

747 791

748Claude Code 無法在將附加影像傳送到 API 之前將其縮小。792Claude Code 無法在將附加影像發送到 API 之前將其縮小。

749 793

750```text theme={null}794```text theme={null}

751Unable to resize image — image processing is unavailable and dimensions could not be read from the file header. Please convert the image to PNG, JPEG, GIF, or WebP.795Unable to resize image — image processing is unavailable and dimensions could not be read from the file header. Please convert the image to PNG, JPEG, GIF, or WebP.

754Unable to resize image — could not verify image dimensions are within the 2000x2000px API limit.798Unable to resize image — could not verify image dimensions are within the 2000x2000px API limit.

755```799```

756 800

757Claude Code 通常會自動調整大型影像的大小。這些錯誤表示原生影像處理器無法載入或傳回錯誤，因此影像無法調整大小以符合 API 限制。801Claude Code 通常會自動調整大型影像的大小。這些錯誤意味著原生影像處理器無法載入或返回錯誤，因此無法調整影像大小以符合 API 限制。

758 802

759**要做什麼：**803**該怎麼做：**

760 804

761* 如果訊息要求您轉換影像，請將其轉換為 PNG、JPEG、GIF 或 WebP，然後再次附加。Claude Code 可以驗證這些格式的尺寸，而無需影像處理器。805* 如果訊息要求您轉換影像，請將其轉換為 PNG、JPEG、GIF 或 WebP，然後再次附加。Claude Code 可以驗證這些格式的尺寸，無需影像處理器。

762* 如果訊息報告尺寸或大小限制，請在附加之前將影像調整大小或重新壓縮到該限制以下。806* 如果訊息報告尺寸或大小限制，請在附加之前將影像調整或重新壓縮到該限制以下。

763 807

764<h3 id="pdf-errors">808<h3 id="pdf-errors">

765 PDF errors809 PDF 錯誤

766</h3>810</h3>

767 811

768您附加的 PDF 無法處理。812您附加的 PDF 無法處理。

773The PDF file was not valid. Try converting to a different format first.817The PDF file was not valid. Try converting to a different format first.

774```818```

775 819

776**要做什麼：**820**該怎麼做：**

777 821

778* 對於超大 PDF，請要求 Claude 使用 Read 工具讀取頁面範圍，而不是附加整個檔案，或使用 `pdftotext` 等工具提取文字並按路徑參考輸出檔案822* 對於超大 PDF，請要求 Claude 使用 Read 工具讀取頁面範圍，而不是附加整個檔案，或使用 `pdftotext` 之類的工具提取文字並按路徑參考輸出檔案

779* 對於受保護或無效的 PDF，移除密碼或從其來源應用程式重新匯出檔案，然後再試一次823* 對於受保護或無效的 PDF，移除密碼或從其源應用程式重新匯出檔案，然後重試

780 824

781<h3 id="extra-inputs-are-not-permitted">825<h3 id="extra-inputs-are-not-permitted">

782 Extra inputs are not permitted826 不允許額外輸入

783</h3>827</h3>

784 828

785Claude Code 和 API 之間的代理或 LLM 閘道剝離了 `anthropic-beta` 請求標頭，因此 API 拒絕了依賴它的欄位。829Claude Code 和 API 之間的代理或 LLM 閘道移除了 `anthropic-beta` 請求標頭，因此 API 拒絕了依賴它的欄位。

786 830

787```text theme={null}831```text theme={null}

788API Error: 400 ... Extra inputs are not permitted ... context_management832API Error: 400 ... Extra inputs are not permitted ... context_management

790API Error: 400 ... Unexpected value(s) for the `anthropic-beta` header834API Error: 400 ... Unexpected value(s) for the `anthropic-beta` header

791```835```

792 836

793Claude Code 傳送僅限測試版的欄位（例如 `context_management`、`effort` 和工具 `input_examples`）以及啟用它們的 `anthropic-beta` 標頭。當閘道轉發主體但刪除標頭時，API 會看到它不識別的欄位。837Claude Code 發送測試版專用欄位，例如 `context_management`、`effort` 和工具 `input_examples`，以及啟用它們的 `anthropic-beta` 標頭。當閘道轉發主體但移除標頭時，API 會看到它不認識的欄位。

794 838

795**要做什麼：**839**該怎麼做：**

796 840

797* 配置您的閘道以轉發 `anthropic-beta` 標頭。請參閱 [feature pass-through](/zh-TW/llm-gateway-protocol#feature-pass-through) 以了解閘道必須轉發的內容。841* 配置您的閘道以轉發 `anthropic-beta` 標頭。請參閱[功能傳遞](/zh-TW/llm-gateway-protocol#feature-pass-through)以了解閘道必須轉發的內容。

798* 作為後備，在啟動之前設定 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/zh-TW/env-vars)。這會停用需要測試版標頭的功能，以便請求透過無法轉發它的閘道成功。842* 作為備選方案，在啟動前設定 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/zh-TW/env-vars)。這會停用需要測試版標頭的功能，以便請求通過無法轉發它的閘道成功。

799 843

800<h3 id="there’s-an-issue-with-the-selected-model">844<h3 id="there’s-an-issue-with-the-selected-model">

801 There's an issue with the selected model845 選定的模型有問題

802</h3>846</h3>

803 847

804配置的模型名稱未被識別，或您的帳戶缺乏對其的存取權。自 v2.1.160 起，尾部提示（如此處以其互動形式所示）因表面而異。848配置的模型名稱未被識別，或您的帳戶缺乏對其的存取權限。從 v2.1.160 開始，尾部提示（此處以其互動形式顯示）因表面而異。

805 849

806```text theme={null}850```text theme={null}

807There's an issue with the selected model (claude-...). It may not exist or you may not have access to it. Run /model to pick a different model.851There's an issue with the selected model (claude-...). It may not exist or you may not have access to it. Run /model to pick a different model.

808```852```

809 853

810**要做什麼：**854**該怎麼做：**

811 855

812* **互動式 CLI**：執行 `/model` 以從您帳戶可用的模型中選擇。856* **互動式 CLI**：執行 `/model` 以從您帳戶可用的模型中選擇。

813* **非互動式模式（`-p`）**：使用有效的別名或 ID 傳遞 `--model`，或設定 [`ANTHROPIC_MODEL`](/zh-TW/env-vars)。錯誤文字在此表面上顯示 `Run --model`。857* **非互動模式 (`-p`)**：使用有效的別名或 ID 傳遞 `--model`，或設定 [`ANTHROPIC_MODEL`](/zh-TW/env-vars)。錯誤文字在此表面上顯示 `Run --model`。

814* **Agent SDK**：錯誤文字省略提示，因為模型是以程式設計方式設定的。在 TypeScript 中的 [`Options`](/zh-TW/agent-sdk/typescript#options) 上設定 [`model`](/zh-TW/agent-sdk/typescript#options)，或在 Python 中設定 [`ClaudeAgentOptions(model=...)`](/zh-TW/agent-sdk/python#claudeagentoptions)，並處理結構化的 `model_not_found` 錯誤以呈現您自己的重試或模型選擇器。858* **Agent SDK**：錯誤文字省略提示，因為模型是以程式設計方式設定的。在 TypeScript 中設定 [`Options` 上的 `model`](/zh-TW/agent-sdk/typescript#options)，或在 Python 中設定 [`ClaudeAgentOptions(model=...)`](/zh-TW/agent-sdk/python#claudeagentoptions)，並處理結構化的 `model_not_found` 錯誤以呈現您自己的重試或模型選擇器。

815* 使用別名（例如 `sonnet` 或 `opus`）而不是完整的版本化 ID。別名追蹤最新版本，因此它們不會過時。請參閱 [Model configuration](/zh-TW/model-config)。859* 使用別名（例如 `sonnet` 或 `opus`）而不是完整的版本化 ID。別名解析為維護的預設值，因此不會過時。請參閱[模型配置](/zh-TW/model-config)。

816* 如果錯誤的模型一直出現在 CLI 中，則某處設定了過時的 ID。按 [優先順序](/zh-TW/model-config#setting-your-model) 檢查：`--model` 旗標、`ANTHROPIC_MODEL` 環境變數，然後是 `.claude/settings.local.json` 中的 `model` 欄位、您專案的 `.claude/settings.json` 和 `~/.claude/settings.json`。移除過時的值，Claude Code 會回退到您的帳戶預設值。860* 如果 CLI 中一直出現錯誤的模型，則某處設定了過時的 ID。按[優先順序](/zh-TW/model-config#setting-your-model)檢查：`--model` 標誌、`ANTHROPIC_MODEL` 環境變數，然後是 `.claude/settings.local.json` 中的 `model` 欄位、您專案的 `.claude/settings.json` 和 `~/.claude/settings.json`。移除過時的值，Claude Code 會回退到您的帳戶預設值。

817* 對於 Vertex AI 部署，請參閱 [Vertex AI troubleshooting](/zh-TW/google-vertex-ai#troubleshooting)。861* 對於 Google Cloud 的 Agent Platform 部署，請參閱 [Google Cloud 的 Agent Platform 故障排除](/zh-TW/google-vertex-ai#troubleshooting)。

862

863<h3 id="model-is-not-a-recognized-model-id">

864 模型不是公認的模型 ID

865</h3>

866

867您傳遞給模型切換的模型字串不是模型別名、此 Claude Code 版本知道的模型 ID，也不是以 `claude-` 開頭的 ID。常見原因是 ID 中的拼寫錯誤、顯示名稱（例如 `Sonnet 5`，其中需要 ID `claude-sonnet-5`），或只有較新 Claude Code 版本識別的別名。Claude Code 立即拒絕切換。在 v2.1.200 之前，Claude Code 會儲存字串並在下一個請求時失敗，出現[選定的模型有問題](#there%E2%80%99s-an-issue-with-the-selected-model)。

868

869```text theme={null}

870Model "claud-sonnet-5" is not a recognized model id. Did you mean 'claude-sonnet-5'?

871```

872

873尾部提示命名最接近的匹配別名或模型 ID。當沒有足夠接近的內容時，它會改為讀取 `Run /model to see available models.`。

874

875Claude Code 在請求切換時在本地產生此錯誤，在發出任何 API 請求之前。它適用於通過 [Agent SDK](/zh-TW/agent-sdk/typescript) `setModel()` 方法或為您執行 Claude Code CLI 的應用程式（例如 [Desktop 應用程式](/zh-TW/desktop)）設定模型的情況。

876

877**該怎麼做：**

878

879* 執行不帶引數的 `/model` 以開啟選擇器並從您帳戶可用的模型中選擇，然後傳遞那裡顯示的別名或 ID

880* 如果您使用了較新 Claude Code 版本支援的別名，請執行 `claude update`。以 `claude-` 開頭的完整 ID 即使模型比您的 Claude Code 版本更新，也會通過此檢查，因此不需要升級。

881* v2.1.200 之前儲存的模型不會被此檢查修復。如果過時的值一直出現，請從[選定的模型有問題](#there%E2%80%99s-an-issue-with-the-selected-model)下列出的位置移除它。

882* 檢查僅在 Anthropic API 上執行。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry、[AWS 上的 Claude Platform](/zh-TW/claude-platform-on-aws) 和 [LLM 閘道](/zh-TW/llm-gateway)後面或自訂 `ANTHROPIC_BASE_URL`，您的提供者或閘道定義模型名稱，因此 Claude Code 接受任何字串並將其傳遞。

818 883

819<h3 id="claude-opus-is-not-available-with-the-claude-pro-plan">884<h3 id="claude-opus-is-not-available-with-the-claude-pro-plan">

820 Claude Opus is not available with the Claude Pro plan885 Claude Opus 不適用於 Claude Pro 方案

821</h3>886</h3>

822 887

823您的活躍訂閱計畫不包括您選擇的模型。888您的有效訂閱方案不包括您選擇的模型。

824 889

825```text theme={null}890```text theme={null}

826Claude Opus is not available with the Claude Pro plan · Select a different model in /model891Claude Opus is not available with the Claude Pro plan · Select a different model in /model

827```892```

828 893

829**要做什麼：**894**該怎麼做：**

830 895

831* 執行 `/model` 並選擇您的計畫包括的模型896* 執行 `/model` 並選擇您的方案包括的模型

832* 如果您最近升級了計畫但仍然看到這個，請執行 `/logout` 然後 `/login`。儲存的令牌反映您登入時的計畫，因此在現有工作階段中升級網路不會生效，直到您重新認證。897* 如果您最近升級了方案但仍然看到此訊息，請執行 `/logout` 然後 `/login`。儲存的令牌反映您登入時的方案，因此在現有工作階段中在網路上升級不會生效，直到您重新驗證。

833* 請參閱 [claude.com/pricing](https://claude.com/pricing) 以了解每個計畫包括哪些模型898* 請參閱 [claude.com/pricing](https://claude.com/pricing) 以了解每個方案包括哪些模型

834 899

835<h3 id="model-is-restricted-by-your-organization’s-settings">900<h3 id="model-is-restricted-by-your-organization’s-settings">

836 Model is restricted by your organization's settings901 模型受您組織的設定限制

837</h3>902</h3>

838 903

839您的組織管理員已在 Claude Console 中停用此模型，或它被受管設定中的 [`availableModels`](/zh-TW/model-config#restrict-model-selection) 允許清單排除。當受限制的模型使用 `--model`、`ANTHROPIC_MODEL` 或 `model` 設定設定時，Claude Code 會替換為允許的模型並繼續。為受限制的模型輸入 `/model <name>` 會被拒絕，並顯示 `Run /model to choose a different model.`，工作階段保持其目前的模型。904您的組織管理員已在 claude.ai 管理控制台中停用此模型，或它被託管設定中的 [`availableModels`](/zh-TW/model-config#restrict-model-selection) 允許清單排除。當使用 `--model`、`ANTHROPIC_MODEL` 或 `model` 設定設定受限制的模型時，Claude Code 會替換為允許的模型並繼續。為受限制的模型鍵入 `/model <name>` 會被拒絕，顯示 `Run /model to choose a different model.`，工作階段保持其目前模型。

840 905

841```text theme={null}906```text theme={null}

842Model "claude-opus-4-8" is restricted by your organization's settings. Using claude-sonnet-4-6 instead.907Model "claude-opus-4-8" is restricted by your organization's settings. Using claude-sonnet-4-6 instead.

843```908```

844 909

845**要做什麼：**910Claude Code 將模型系列別名（`opus`、`sonnet`、`haiku` 或 `fable` 之一）視為對該系列的請求，而不是對其最新版本的請求。在 Anthropic API 和 [AWS 上的 Claude Platform](/zh-TW/claude-platform-on-aws) 上，受限制的系列別名解析為您的組織和 `availableModels` 允許清單允許的系列的最新版本，替換通知命名該版本。Claude Code 僅在系列的每個版本都受限制時才拒絕 `/model <alias>`。在 v2.1.205 之前，系列別名是根據其最新版本單獨替換或拒絕的，即使同一系列的較舊版本被允許。

911

912**該怎麼做：**

846 913

847* 執行 `/model` 以從您的組織允許的模型中選擇。受限制的模型在選擇器中被隱藏。914* 執行 `/model` 以從您的組織允許的模型中選擇。受限制的模型在選擇器中隱藏。

848* 如果受限制的模型在 `--model`、`ANTHROPIC_MODEL` 或設定檔案的 `model` 欄位中設定，請移除或更新該值，以便通知不會在每次啟動時重複出現915* 如果受限制的模型是在 `--model`、`ANTHROPIC_MODEL` 或設定檔案的 `model` 欄位中設定的，請移除或更新該值，以便通知不會在每次啟動時重複出現

849* 如果您需要存取受限制的模型，請要求您的組織管理員啟用它。請參閱 [Organization model restrictions](/zh-TW/model-config#organization-model-restrictions)。916* 如果您需要存取受限制的模型，請要求您的組織管理員啟用它。請參閱[組織模型限制](/zh-TW/model-config#organization-model-restrictions)。

850 917

851<h3 id="thinking-type-enabled-is-not-supported-for-this-model">918<h3 id="thinking-type-enabled-is-not-supported-for-this-model">

852 thinking.type.enabled is not supported for this model919 此模型不支援 thinking.type.enabled

853</h3>920</h3>

854 921

855您的 Claude Code 版本早於 Sonnet 5、Opus 4.8 或 Opus 4.7 的最低版本。CLI 傳送了模型不再接受的思考配置。922您的 Claude Code 版本比 Sonnet 5、Opus 4.8 或 Opus 4.7 的最低版本更舊。CLI 發送了模型不再接受的思考配置。

856 923

857```text theme={null}924```text theme={null}

858API Error: 400 ... "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.925API Error: 400 ... "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

859```926```

860 927

861**要做什麼：**928**該怎麼做：**

862 929

863* 執行 `claude update` 並重新啟動 Claude Code。Opus 4.7 需要 v2.1.111 或更新版本。Opus 4.8 需要 v2.1.154 或更新版本。Sonnet 5 需要 v2.1.197 或更新版本930* 執行 `claude update` 並重新啟動 Claude Code。Opus 4.7 需要 v2.1.111 或更新版本。Opus 4.8 需要 v2.1.154 或更新版本。Sonnet 5 需要 v2.1.197 或更新版本

864* 如果您無法升級，請執行 `/model` 並選擇 Opus 4.6 或 Sonnet 4.6 代替931* 如果您無法升級，請執行 `/model` 並改為選擇 Opus 4.6 或 Sonnet 4.6

865* {/* min-version: agent-sdk@0.3.197 */}如果您在 [Agent SDK](/zh-TW/agent-sdk/overview) 中遇到這個，請升級 SDK 套件。Opus 4.8 需要 TypeScript SDK v0.3.154 或更新版本和 Python SDK v0.2.88 或更新版本。Sonnet 5 需要 TypeScript SDK v0.3.197 或更新版本932* {/* min-version: agent-sdk@0.3.197 */}如果您在 [Agent SDK](/zh-TW/agent-sdk/overview) 中遇到此問題，請改為升級 SDK 套件。Opus 4.8 需要 TypeScript SDK v0.3.154 或更新版本和 Python SDK v0.2.88 或更新版本。Sonnet 5 需要 TypeScript SDK v0.3.197 或更新版本

866 933

867<h3 id="thinking-budget-exceeds-output-limit">934<h3 id="thinking-budget-exceeds-output-limit">

868 Thinking budget exceeds output limit935 思考預算超過輸出限制

869</h3>936</h3>

870 937

871配置的擴展思考預算超過最大回應長度，因此實際答案沒有剩餘空間。938配置的擴展思考預算超過最大回應長度，因此沒有空間留給實際答案。

872 939

873```text theme={null}940```text theme={null}

874API Error: 400 ... max_tokens must be greater than thinking.budget_tokens941API Error: 400 ... max_tokens must be greater than thinking.budget_tokens

875```942```

876 943

877Claude Code 在 Anthropic API 上自動調整這些值。當 [`MAX_THINKING_TOKENS`](/zh-TW/env-vars) 設定高於提供者的輸出限制時，或當計畫模式提高思考預算時，您通常會在 Amazon Bedrock 或 Google Vertex AI 上看到此錯誤。944Claude Code 在 Anthropic API 上自動調整這些值。當 [`MAX_THINKING_TOKENS`](/zh-TW/env-vars) 設定高於提供者的輸出限制時，或當計畫模式提高思考預算時，您通常會在 Amazon Bedrock 或 Google Cloud 的 Agent Platform 上看到此錯誤。

878 945

879**要做什麼：**946**該怎麼做：**

880 947

881* 降低 `MAX_THINKING_TOKENS`，或將 [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/zh-TW/env-vars) 提高到思考預算之上948* 降低 `MAX_THINKING_TOKENS`，或將 [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/zh-TW/env-vars) 提高到思考預算之上

882* 請參閱 [Extended thinking](/zh-TW/model-config#extended-thinking) 以了解預算如何與輸出長度互動949* 請參閱[擴展思考](/zh-TW/model-config#extended-thinking)以了解預算如何與輸出長度互動

883 950

884<h3 id="tool-use-or-thinking-block-mismatch">951<h3 id="tool-use-or-thinking-block-mismatch">

885 Tool use or thinking block mismatch952 工具使用或思考區塊不匹配

886</h3>953</h3>

887 954

888對話歷史記錄以不一致的狀態到達 API，通常是在工具呼叫被中斷或轉向在流中途被編輯後。955對話歷史以不一致的狀態到達 API，通常是在工具呼叫被中斷或回合在中途被編輯後。

889 956

890```text theme={null}957```text theme={null}

891API Error: 400 due to tool use concurrency issues. Run /rewind to recover the conversation.958API Error: 400 due to tool use concurrency issues. Run /rewind to recover the conversation.

893API Error: 400 ... thinking blocks ... cannot be modified960API Error: 400 ... thinking blocks ... cannot be modified

894```961```

895 962

896所有三個變體都表示相同的事情：歷史記錄中 `tool_use`、`tool_result` 和 `thinking` 區塊的序列不再與 API 期望的相符。963所有三個變體都意味著同一件事：歷史中 `tool_use`、`tool_result` 和 `thinking` 區塊的序列不再與 API 期望的相符。

897 964

898**要做什麼：**965**該怎麼做：**

899 966

900* {/* max-version: 2.1.155 */}如果您使用的是 Opus 4.7 或 Opus 4.8，請先執行 `claude update`。v2.1.156 之前的版本可能在正常工具使用期間觸發此錯誤，而 `/rewind` 無法清除它。967* {/* max-version: 2.1.155 */}如果您使用的是 Opus 4.7 或 Opus 4.8，請先執行 `claude update`。v2.1.156 之前的版本可能在正常工具使用期間觸發此錯誤，而 `/rewind` 不會清除它。

901* 執行 `/rewind`，或按 Esc 兩次，以回退到損壞轉向之前的檢查點並從那裡繼續。請參閱 [Checkpointing](/zh-TW/checkpointing) 以了解如何建立和恢復檢查點。968* 執行 `/rewind` 或按 Esc 兩次，以回溯到損壞回合之前的檢查點並從那裡繼續。請參閱[檢查點](/zh-TW/checkpointing)以了解如何建立和恢復檢查點。

902 969

903<h3 id="usage-policy-refusal">970<h3 id="usage-policy-refusal">

904 Usage Policy refusal971 使用政策拒絕

905</h3>972</h3>

906 973

907API 拒絕回應，因為對話中的內容觸發了 [Usage Policy](https://www.anthropic.com/legal/aup) 檢查。訊息包括一個請求 ID，如果您認為拒絕不正確，可以引用該 ID 與支援部門聯繫。974API 拒絕回應，因為對話中的內容觸發了[使用政策](https://www.anthropic.com/legal/aup)檢查。訊息包括您可以引用給支援的請求 ID，如果您認為拒絕不正確。

908 975

909```text theme={null}976```text theme={null}

910API Error: Claude Code is unable to respond to this request, which appears to violate our Usage Policy (https://www.anthropic.com/legal/aup). Please double press esc to edit your last message or start a new session for Claude Code to assist with a different task.977API Error: Claude Code is unable to respond to this request, which appears to violate our Usage Policy (https://www.anthropic.com/legal/aup). Please double press esc to edit your last message or start a new session for Claude Code to assist with a different task.

911```978```

912 979

913檢查評估整個對話，而不僅僅是您的最新提示，因此在同一工作階段中傳送新訊息通常會重新觸發相同的拒絕。在使用 `--continue` 或 `--resume` 退出並重新開啟工作階段後也是如此，因為磁碟上的文字記錄仍然包含觸發內容。980檢查評估完整對話，而不僅是您的最新提示，因此在同一工作階段中發送新訊息通常會重新觸發相同的拒絕。在使用 `--continue` 或 `--resume` 退出並重新開啟工作階段後也是如此，因為磁碟上的文字記錄仍然包含觸發內容。在 [Amazon Bedrock](/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/zh-TW/google-vertex-ai) 和 [Microsoft Foundry](/zh-TW/microsoft-foundry) 上，此訊息也涵蓋模型的安全措施標記為網路安全主題的請求。請參閱[安全措施標記了網路安全主題](#safety-measures-flagged-a-cybersecurity-topic)。

914 981

915**要做什麼：**982**該怎麼做：**

916 983

917* 按 Esc 兩次或執行 `/rewind` 以回退到觸發拒絕的轉向之前的檢查點，然後重新表述或採取不同的方法。請參閱 [Checkpointing](/zh-TW/checkpointing)。984* 按 Esc 兩次或執行 `/rewind` 以回溯到觸發拒絕的回合之前的檢查點，然後重新表述或採取不同的方法。請參閱[檢查點](/zh-TW/checkpointing)。

918* 如果您無法識別哪個轉向導致了它，請執行 `/clear` 以在同一專案中啟動新的對話。您之前的對話已保留在磁碟上，並在 `/resume` 中保持可用。985* 如果您無法識別哪個回合導致了它，請執行 `/clear` 以在同一專案中開始新的對話。您之前的對話會保留在磁碟上，並在 `/resume` 中保持可用。

919* 在 [non-interactive mode](/zh-TW/headless)（`-p`）中，其中無法使用 rewind，請使用重新表述的提示重試或啟動新的工作階段而不使用 `--continue`。政策檢查因模型而異，因此使用 `--model` 切換到不同的模型也可能在某些情況下解決拒絕。986* 在[非互動模式](/zh-TW/headless)(`-p`) 中，其中無法進行倒帶，請在沒有 `--continue` 的新工作階段中使用重新表述的提示重試。政策檢查因模型而異，因此使用 `--model` 切換到不同的模型也可能在某些情況下解決拒絕。

987

988<h3 id="safety-measures-flagged-a-cybersecurity-topic">

989 安全措施標記了網路安全主題

990</h3>

991

992模型的安全措施將對話中的內容標記為網路安全主題。訊息命名標記請求的模型：

993

994```text theme={null}

995API Error: Opus 4.8 has safety measures that flagged this message for a cybersecurity topic. To learn about the Cyber Verification Program and apply for access, visit our help center: https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude.

996

997If you were not engaging in a cybersecurity topic, please send feedback via /feedback.

998```

999

1000訊息連結到[網路安全驗證計畫](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)，該計畫為合法網路安全工作授予存取權限。保護措施本身是伺服器端的，早於 v2.1.203；此版本僅更改了訊息的措辭和它連結到的頁面。

1001

1002您看到的內容取決於您的提供者和模式：

1003

1004* 在 [Amazon Bedrock](/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/zh-TW/google-vertex-ai) 和 [Microsoft Foundry](/zh-TW/microsoft-foundry) 上，網路安全標記會產生[使用政策拒絕](#usage-policy-refusal)訊息。

1005* [非互動模式](/zh-TW/headless)省略 `/feedback` 句子。

1006

1007{/* max-version: 2.1.202 */}在 v2.1.203 之前，訊息讀取 `<model>'s safeguards flagged this message for a cybersecurity topic. If your work requires this access, you can apply for an exemption:` 後跟豁免表單連結。

1008

1009**該怎麼做：**

1010

1011* 如果您的工作需要此內容，請通過[網路安全驗證計畫](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)申請存取權限

1012* 如果您的請求不是關於網路安全主題，請執行 `/feedback` 以報告誤報

1013* 若要在同一工作階段中繼續工作，請按 Esc 兩次或執行 `/rewind` 以回溯到觸發標記的回合之前的檢查點，然後採取不同的方法。請參閱[檢查點](/zh-TW/checkpointing)。

1014

1015<h2 id="installation-errors">

1016 安裝錯誤

1017</h2>

1018

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

1020

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

1022 安裝在完成前被中止

1023</h3>

1024

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

1026

1027```text theme={null}

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

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

1030```

1031

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

1033

1034**該怎麼做：**

1035

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

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

1038

1039<h3 id="the-connection-dropped-while-downloading-the-update">

1040 下載更新時連線中斷

1041</h3>

1042

1043當 `claude install`、`claude update` 或 [自動更新程式](/zh-TW/setup#auto-updates) 正在擷取 Claude Code 二進位檔案時，與下載伺服器的連線已關閉，且重試未能恢復。當連線中斷、傳輸停滯或下載的檔案未通過校驗和時，Claude Code 會重試下載，最多嘗試三次。已完成的 HTTP 錯誤（例如 404）不會重試，因為伺服器已經回應。{/* min-version: 2.1.202 */}在 v2.1.202 之前，單一連線中斷會立即導致下載失敗，並顯示裸錯誤 `aborted`，而不是重試。

1044

1045```text theme={null}

1046The connection dropped while downloading the update (attempt 3/3: aborted). Check your network — proxies sometimes cut off large downloads.

1047```

1048

1049括號中的文字命名失敗的嘗試和基礎網路錯誤。`claude update` 在 stderr 上以 `Error: Failed to install native update` 開頭該訊息。

1050

1051保持連線但在 10 分鐘內未完成的下載會失敗，並顯示 `Download timed out: exceeded the total deadline`。Claude Code 不會重試逾時的下載，因為連線速度太慢而無法在期限內完成，在立即重試時也不會完成。下面的步驟適用於兩個訊息。在 v2.1.205 之前，相同的 10 分鐘期限被報告為 HTTP 用戶端的通用 `timeout of 600000ms exceeded`。

1052

1053通常的原因是代理或閘道在傳輸完成前關閉長傳輸。Claude Code 二進位檔案是大型下載，因此永遠不會影響正常 API 流量的代理連線限制仍然可能中斷它。

1054

1055**該怎麼做：**

1056

1057* 再次執行 `claude update`。在網路狀況良好的情況下，下載通常在下次執行時成功。對於逾時訊息，請從更快或限制較少的網路重新執行。

1058* 如果您的網路需要代理，請在執行安裝程式或 `claude update` 之前設定 `HTTPS_PROXY`。請參閱 [檢查網路連線](/zh-TW/troubleshoot-install#check-network-connectivity)。

1059* 如果公司代理持續關閉傳輸，請要求您的網路團隊允許從 `downloads.claude.ai` 進行完整下載。請參閱 [網路存取需求](/zh-TW/network-config#network-access-requirements)。

1060* 從您的 shell 執行 `claude doctor` 以進行安裝診斷

920 1061

921<h2 id="command-line-errors">1062<h2 id="command-line-errors">

922 命令列錯誤1063 命令列錯誤

923</h2>1064</h2>

924 1065

925這些錯誤來自 Claude Code 自己對 `claude` 命令列的驗證。Claude Code 會立即列印它們，在建立工作階段或傳送任何 API 請求之前。1066這些錯誤來自 `claude` 命令列及其子命令。Claude Code 在執行您的提示或傳送任何 API 請求之前會列印這些錯誤。

926 1067

927<h3 id="conflict-between-bg-and-print">1068<h3 id="conflict-between-bg-and-print">

928 Conflict between --bg and --print1069 \--bg 和 --print 之間的衝突

1070</h3>

1071

1072此訊息需要 Claude Code v2.1.198 或更新版本。您在同一個 `claude` 呼叫中結合了 `--bg` 與 `-p` 或 `--print`。`--bg` 啟動一個[背景工作階段](/zh-TW/agent-view#from-your-shell)，您稍後可以使用 `claude agents` 附加到該工作階段，而 `--print` 以[非互動模式](/zh-TW/headless)執行，永遠不會啟動 `claude agents` 附加到的互動工作階段。在 v2.1.198 之前，此組合會無聲地建立一個永遠無法附加的背景工作。

1073

1074```text theme={null}

1075--bg 和 --print 衝突：--print 永遠不會啟動 `claude agents` 附加到的互動工作階段，因此工作將無法附加。提示是位置引數 — 移除 --print：`claude --bg '<task>'`。

1076```

1077

1078**該怎麼做：**

1079

1080* 移除 `-p` 或 `--print`。`--bg` 將提示作為其位置引數，所以 `claude --bg "<task>"` 是完整的命令。請參閱[從您的 shell 分派新代理](/zh-TW/agent-view#from-your-shell)。

1081* 若要以非互動模式執行提示並列印結果而不是建立背景工作階段，請移除 `--bg` 並執行 `claude -p "<task>"`

1082

1083<h3 id="the-json-schema-value-is-not-a-valid-json-schema">

1084 \--json-schema 值不是有效的 JSON Schema

1085</h3>

1086

1087您傳遞給[`--json-schema`](/zh-TW/cli-reference#cli-flags) 的結構描述在[非互動模式](/zh-TW/headless#get-structured-output)中未能通過 JSON Schema 編譯，因此 `claude` 以代碼 1 結束而不是執行提示。在 v2.1.205 之前，無效的結構描述會產生無結構的輸出且沒有錯誤，任何使用 `format` 關鍵字的結構描述都被視為無效。

1088

1089```text theme={null}

1090Error: --json-schema is not a valid JSON Schema: data/type must be equal to one of the allowed values

1091```

1092

1093第二個冒號之後的文字是驗證器的診斷，並命名失敗的關鍵字或位置。使用 `format` 關鍵字的結構描述（例如 `"format": "email"`）是有效的：Claude Code 接受 `format` 作為註解，不強制執行它。

1094

1095Claude Code 在結構描述編譯之前執行兩項檢查：它拒絕不可解析的 JSON 值，並顯示 `Error: --json-schema is not valid JSON`，以及有效但不是物件的 JSON，並顯示 `Error: --json-schema must be a JSON object`。

1096

1097**該怎麼做：**

1098

1099* 修復診斷命名的結構描述部分，然後重新執行命令

1100* 如果診斷是 `schema too large`，請減少結構描述的巢狀和 `$ref` 重複使用

1101* 請參閱[取得結構化輸出](/zh-TW/headless#get-structured-output)以取得有效的結構描述和命令

1102

1103<h3 id="could-not-import-a-server-from-claude-desktop">

1104 無法從 Claude Desktop 匯入伺服器

1105</h3>

1106

1107Claude Code 無法新增您在 `claude mcp add-from-claude-desktop` 中選擇的其中一個伺服器。該命令仍會匯入其他選定的伺服器，並為每個無法新增的伺服器列印一行。在 v2.1.205 之前，第一個失敗的伺服器會停止匯入，且所有選定的伺服器都不會被新增。

1108

1109```text theme={null}

1110Could not import my server: Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.

1111```

1112

1113伺服器名稱之後的文字是原因。最常見的是名稱檢查：Claude Desktop 允許伺服器名稱中的字元（例如空格和句號），而 `claude mcp` 限制為字母、數字、連字號和底線。其他原因包括未通過驗證的伺服器配置，以及被您組織的 [MCP 政策](/zh-TW/managed-mcp)阻止的伺服器。

1114

1115**該怎麼做：**

1116

1117* 在 `claude_desktop_config.json` 中重新命名伺服器，僅使用字母、數字、連字號和底線，然後再次執行 `claude mcp add-from-claude-desktop`

1118* 使用 `claude mcp add` 或 `claude mcp add-json` 在有效名稱下直接新增該伺服器。請參閱[從 Claude Desktop 匯入 MCP 伺服器](/zh-TW/mcp#import-mcp-servers-from-claude-desktop)。

1119

1120<h2 id="plugin-errors">

1121 外掛程式錯誤

1122</h2>

1123

1124這些錯誤來自 [外掛程式](/zh-TW/plugins) 和 [marketplace](/zh-TW/plugin-marketplaces) 設定。對於不會產生此頁面上其中一則訊息的外掛程式問題，例如無法載入的 marketplace URL 或已安裝但未出現的外掛程式，請參閱 [外掛程式疑難排解](/zh-TW/discover-plugins#troubleshooting)。

1125

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

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

929</h3>1128</h3>

930 1129

931此訊息需要 Claude Code v2.1.198 或更新版本。您在同一個 `claude` 呼叫中結合了 `--bg` 與 `-p` 或 `--print`。`--bg` 啟動 [background session](/zh-TW/agent-view#from-your-shell)，您稍後使用 `claude agents` 附加到，而 `--print` 執行 [non-interactively](/zh-TW/headless) 並從不啟動 `claude agents` 附加到的互動式工作階段。在 v2.1.198 之前，此組合無聲地建立了一個無法附加到的背景工作。1130Marketplace 是以 [為官方 Anthropic marketplace 保留的名稱](/zh-TW/plugin-marketplaces#marketplace-schema) 註冊的，但其註冊的來源不是 `anthropics` GitHub 儲存庫。Claude Code 每次載入或重新整理 marketplace 時都會重新檢查保留的名稱，因此 marketplace 和從中安裝的外掛程式會停止載入。在 v2.1.205 之前，名稱只在新增 marketplace 時檢查，因此在其名稱變成保留名稱之前註冊的項目會繼續載入。

932 1131

933```text theme={null}1132```text theme={null}

1133Marketplace "claude-community" is registered from an untrusted source: The name 'claude-community' is reserved for official Anthropic marketplaces. Only repositories from 'github.com/anthropics/' can use this name. To fix it, remove the marketplace and re-add it from the official source.

934```1134```

935 1135

936**要做什麼：**1136**該怎麼做：**

1137

1138* 執行 `claude plugin marketplace remove <name>`，然後從官方 `github.com/anthropics` 儲存庫重新新增 marketplace

1139* 如果您發佈了在名稱變成保留名稱之前使用該名稱的第三方 marketplace，請重新命名它並要求使用者從您的來源重新新增它

1140* 請參閱 [Marketplace schema](/zh-TW/plugin-marketplaces#marketplace-schema) 下的保留名稱清單

1141

1142<h2 id="configuration-warnings">

1143 設定警告

1144</h2>

1145

1146Claude Code 在啟動時將這些訊息寫入 stderr，而不是在對話中顯示錯誤。它們報告 Claude Code 讀取但未應用的設定。

1147

1148<h3 id="workspace-has-not-been-trusted">

1149 工作區尚未受信任

1150</h3>

937 1151

938* 放棄 `-p` 或 `--print`。`--bg` 將提示作為其位置引數，因此 `claude --bg "<task>"` 是完整的命令。請參閱 [Dispatch new agents from your shell](/zh-TW/agent-view#from-your-shell)。1152Claude Code 在專案的 `.claude/settings.json` 或 `.claude/settings.local.json` 中找到 `permissions.allow` 規則或 `permissions.additionalDirectories` 項目，但未應用它們，因為[來自專案設定的允許規則需要工作區信任](/zh-TW/permissions#project-allow-rules-and-workspace-trust)。訊息中的計數、設定名稱和檔案名稱會根據您的設定而異。`deny` 和 `ask` 規則不受影響。

939* 若要非互動式執行提示並列印結果而不是建立背景工作階段，請放棄 `--bg` 並執行 `claude -p "<task>"`1153

1154```text theme={null}

1155Ignoring 2 permissions.allow entries from .claude/settings.local.json: this workspace has not been trusted. Run Claude Code interactively here once and accept the trust dialog, or set projects["/Users/you/project"].hasTrustDialogAccepted: true in /Users/you/.claude.json.

1156```

1157

1158**該怎麼做：**

1159

1160* 在目錄中執行 `claude` 並接受信任對話框。{/* min-version: 2.1.200 */}即使父目錄已受信任，對話框仍會出現，列出被保留的規則，並讓您拒絕並繼續工作而不使用它們。在 v2.1.200 之前，在該情況下不會出現對話框，因此無法在那裡完成此步驟。

1161* 在[非互動模式](/zh-TW/headless)中使用 `-p` 不會顯示對話框。使用訊息列印的確切 `projects` 金鑰在 `~/.claude.json` 中設定 `hasTrustDialogAccepted` 項目。

1162* {/* min-version: 2.1.200 */}如果訊息命名 `.claude/settings.local.json` 且您在 git 儲存庫外或主目錄中啟動 Claude Code，請更新至 v2.1.200 或更新版本。版本 2.1.196 至 2.1.199 在這些工作區中將您自己的 `.claude/settings.local.json` 視為儲存庫提供的。請參閱[專案允許規則和工作區信任](/zh-TW/permissions#project-allow-rules-and-workspace-trust)。

940 1163

941<h2 id="responses-seem-lower-quality-than-usual">1164<h2 id="responses-seem-lower-quality-than-usual">

942 回應品質似乎低於平常1165 回應品質似乎低於預期

943</h2>1166</h2>

944 1167

945如果 Claude 的答案似乎不如您預期的那樣有能力，但沒有顯示錯誤，原因通常是對話狀態而不是模型本身。Claude Code 不會無聲地更改模型版本。它可以在三個特定情況下切換到後備模型：1168如果 Claude 的回答似乎不如預期那樣有能力，但沒有顯示錯誤，原因通常是對話狀態而非模型本身。Claude Code 不會無聲地更改模型版本。它只能在三種特定情況下切換到備用模型：

1169

1170* 配置的 [`--fallback-model`](/zh-TW/cli-reference#cli-flags) 在可用性錯誤後接管該輪次，並在文字記錄中顯示通知

1171* Amazon Bedrock 或 Google Cloud 的 Agent Platform 啟動檢查發現您的預設模型不可用

1172* [自動模型備用](/zh-TW/model-config#automatic-model-fallback)在 Fable 5 上將工作階段移至預設 Opus 模型，並在文字記錄中顯示通知

946 1173

947* 配置的 [`--fallback-model`](/zh-TW/cli-reference#cli-flags) 在可用性錯誤後接管該轉向，並在記錄中顯示通知1174下面的模型選擇檢查會捕捉第二和第三種情況；第一種情況會顯示為文字記錄通知而非 `/model` 變更。[模型配置](/zh-TW/model-config)說明每種備用何時適用。

948* Bedrock 或 Vertex AI 啟動檢查發現您的預設模型不可用

949* [自動模型後備](/zh-TW/model-config#automatic-model-fallback)在 Fable 5 上將工作階段移至預設 Opus 模型，並在記錄中顯示通知

950 1175

951下面的模型選擇檢查會捕獲第二和第三種情況；第一種情況顯示為記錄通知而不是 `/model` 變更。[Model configuration](/zh-TW/model-config) 解釋何時應用每個後備。1176首先檢查這些項目：

952 1177

953首先檢查這些：1178* **模型選擇**：執行 `/model` 以確認您使用的是預期的模型。先前的 `/model` 選擇或 `ANTHROPIC_MODEL` 環境變數可能會讓您使用比預期更小的模型。

1179* **努力程度**：執行 `/effort` 以檢查目前的推理程度，並針對困難的除錯或設計工作提高它。預設值因模型而異，因此在假設您低於最大值之前請先檢查。請參閱[調整努力程度](/zh-TW/model-config#adjust-effort-level)以了解各模型的預設值和 `ultrathink` 快捷方式。

1180* **上下文壓力**：執行 `/context` 以查看視窗的滿度。如果接近容量，請在自然中斷點執行 `/compact` 或執行 `/clear` 以重新開始。請參閱[探索上下文視窗](/zh-TW/context-window)以了解自動壓縮如何影響較早的輪次。

1181* **過時的指示**：大型或過時的 `CLAUDE.md` 檔案和 MCP 工具定義會消耗上下文，並可能引導回應。{/* min-version: 2.1.205 */}`/doctor` 檢查會標記超大的記憶體檔案和未使用的擴充功能，`/context` 會顯示 MCP 工具的權杖使用情況。在 v2.1.205 之前，`/doctor` 會開啟診斷畫面，標記超大的記憶體檔案和子代理定義。

954 1182

955* **模型選擇**：執行 `/model` 以確認您在您期望的模型上。之前的 `/model` 選擇或 `ANTHROPIC_MODEL` 環境變數可能會讓您使用比您想要的更小的模型。1183當回應出錯時，通常比用更正回覆更有效的做法是回溯。按 Esc 兩次或執行 `/rewind` 以回到不良輪次之前，然後用更具體的內容重新表述提示。在執行緒中更正會將錯誤的嘗試保留在上下文中，這可能會將後續答案錨定到它。請參閱[檢查點](/zh-TW/checkpointing)。

956* **努力級別**：執行 `/effort` 以檢查目前的推理級別，並為困難的除錯或設計工作提高它。預設值因模型而異，因此在假設您低於最大值之前請檢查。請參閱 [Adjust effort level](/zh-TW/model-config#adjust-effort-level) 以了解每個模型的預設值和 `ultrathink` 快捷方式。

957* **上下文壓力**：執行 `/context` 以查看視窗的滿度。如果接近容量，請在自然斷點執行 `/compact` 或執行 `/clear` 以重新開始。請參閱 [Explore the context window](/zh-TW/context-window) 以了解自動壓縮如何影響較早的轉向。

958* **過時的說明**：大型或過時的 `CLAUDE.md` 檔案和 MCP 工具定義消耗上下文，可能會引導回應。`/doctor` 標記超大記憶檔案和子代理定義；`/context` 顯示 MCP 工具令牌使用。

959 1184

960當回應出錯時，回退通常比用更正回覆效果更好。按 Esc 兩次或執行 `/rewind` 以回退到不良轉向之前，然後用更多細節重新表述提示。在執行緒中更正會將錯誤的嘗試保留在上下文中，這可能會將後來的答案錨定到它。請參閱 [Checkpointing](/zh-TW/checkpointing)。1185如果在檢查上述項目後品質仍然似乎不對，請執行 `/feedback` 並描述您預期的內容與實際得到的內容。以這種方式提交的回饋包括對話文字記錄，這是 Anthropic 診斷真實迴歸的最快方式。如果 `/feedback` 在您的環境中不可用，請參閱[報告錯誤](#report-an-error)。

961 1186

962如果在檢查上述內容後品質仍然似乎有問題，請執行 `/feedback` 並描述您期望的內容與您得到的內容。以這種方式提交的反饋包括對話記錄，這是 Anthropic 診斷真實回歸的最快方式。如果您的環境上 `/feedback` 不可用，請參閱 [Report an error](#report-an-error)。1187{/* min-version: 2.1.201 */}如果 Sonnet 5 拒絕請求並在 Claude Code v2.1.200 或更早版本上引用可疑的提示注入，請執行 `claude update` 以取得 v2.1.201 修正。

963 1188

964<h2 id="report-an-error">1189<h2 id="report-an-error">

965 報告錯誤1190 回報錯誤

966</h2>1191</h2>

967 1192

968對於此頁面未涵蓋的元件的錯誤，請參閱相關指南：1193如需了解此頁面未涵蓋的元件錯誤，請參閱相關指南：

969 1194

970* MCP 伺服器無法連線或認證：[MCP](/zh-TW/mcp)1195* MCP 伺服器連線或驗證失敗：[MCP](/zh-TW/mcp)

971* Hook 指令碼失敗或阻止工具：[Debug hooks](/zh-TW/hooks#debug-hooks)1196* Hook 指令碼失敗或阻止了工具：[Debug hooks](/zh-TW/hooks#debug-hooks)

972* 安裝期間權限被拒絕或檔案系統錯誤：[Troubleshoot installation and login](/zh-TW/troubleshoot-install)1197* 安裝期間權限被拒或檔案系統錯誤：[Troubleshoot installation and login](/zh-TW/troubleshoot-install)

973 1198

974如果此處未列出錯誤或建議的修復無法幫助：1199如果此處未列出錯誤或建議的修正方法無法幫助：

975 1200

976* 在 Claude Code 內執行 `/feedback` 以將記錄和描述傳送給 Anthropic。該命令還提供開啟預填充 GitHub 問題的選項。在 Bedrock、Vertex AI、Foundry 和其他第三方提供商上，`/feedback` 會儲存本地封存，您可以將其傳送給您的 Anthropic 帳戶代表。1201* 在 Claude Code 內執行 `/feedback` 以將文字記錄和說明傳送給 Anthropic。該命令也提供開啟預先填入的 GitHub issue 的選項。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和其他第三方提供者上，`/feedback` 會儲存本機封存，您可以將其傳送給您的 Anthropic 帳戶代表。

977* 執行 `/doctor` 以檢查本地配置問題1202* 從您的 shell 執行 `claude doctor` 以進行安裝的唯讀診斷，或在 Claude Code 內執行 `/doctor` 檢查以尋找並修正設定問題

978* 檢查 [status.claude.com](https://status.claude.com) 以了解活躍的事件1203* 檢查 [status.claude.com](https://status.claude.com) 以了解活躍的事件

979* 在 GitHub 上搜尋 [existing issues](https://github.com/anthropics/claude-code/issues)1204* 在 GitHub 上搜尋[現有 issue](https://github.com/anthropics/claude-code/issues)

fast-mode.md +2 −2

Details

38* 輸入 `/fast` 並按 Tab 鍵切換開啟或關閉38* 輸入 `/fast` 並按 Tab 鍵切換開啟或關閉

39* 在您的[使用者設定檔案](/zh-TW/settings)中設定 `"fastMode": true`39* 在您的[使用者設定檔案](/zh-TW/settings)中設定 `"fastMode": true`

40 40

41預設情況下，快速模式在工作階段之間保持。管理員可以配置快速模式在每個工作階段重設。詳見[要求每個工作階段選擇加入](#require-per-session-opt-in)以了解詳情。41預設情況下，在互動式工作階段中開啟的快速模式會在工作階段之間保持。{/* min-version: 2.1.205 */}在[非互動式模式](/zh-TW/headless)中，使用 `-p` 旗標時，`/fast` 僅在使用快速模式在其 [`--settings`](/zh-TW/cli-reference#cli-flags) 值中啟動的工作階段中運作，例如 `claude -p --settings '{"fastMode": true}'`；切換則僅適用於該工作階段，不會儲存為您的預設值，在任何其他非互動式工作階段中，該命令會報告快速模式不可用。管理員可以配置快速模式在每個工作階段重設。詳見[要求每個工作階段選擇加入](#require-per-session-opt-in)以了解詳情。

42 42

43為了獲得最佳成本效率，在工作階段開始時啟用快速模式，而不是在對話中途切換。詳見[了解成本權衡](#understand-the-cost-tradeoff)以了解詳情。43為了獲得最佳成本效率，在工作階段開始時啟用快速模式，而不是在對話中途切換。詳見[了解成本權衡](#understand-the-cost-tradeoff)以了解詳情。

44 44

103 103

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

105 105

106* **僅限 Anthropic API 或訂閱**：快速模式可透過 Anthropic Console API 和使用額度的 Claude 訂閱方案取得。它在 Amazon Bedrock、Google Vertex AI、Microsoft Azure Foundry 或 AWS 上的 Claude Platform 上不可用。106* **僅限 Anthropic API 或訂閱**：快速模式可透過 Anthropic Console API 和使用額度的 Claude 訂閱方案取得。它在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 AWS 上的 Claude Platform 上不可用。

107* **啟用使用額度**：您的帳戶必須啟用使用額度，這允許超出您方案包含使用量的計費。對於個人帳戶，在您的 [Console 計費設定](https://platform.claude.com/settings/organization/billing)中啟用此功能。對於 Team 和 Enterprise，管理員必須為組織啟用使用額度。107* **啟用使用額度**：您的帳戶必須啟用使用額度，這允許超出您方案包含使用量的計費。對於個人帳戶，在您的 [Console 計費設定](https://platform.claude.com/settings/organization/billing)中啟用此功能。對於 Team 和 Enterprise，管理員必須為組織啟用使用額度。

108 108

109<Note>109<Note>

feature-availability.md +17 −17

Details

4 4

5# 功能可用性5# 功能可用性

6 6

~~7> 比較 Claude Code 功能在 Anthropic 訂閱計畫、Anthropic Console、Amazon Bedrock、AWS 上的 Claude Platform、Google Vertex AI 和 Microsoft Foundry 中的可用性。~~7> 比較 Claude Code 功能在 Anthropic 訂閱計畫、Anthropic Console、Amazon Bedrock、AWS 上的 Claude Platform、Google Cloud 的 Agent Platform 和 Microsoft Foundry 中的可用性。

8 8

9Claude Code CLI 和所有在本地執行的功能在每個提供者上的運作方式完全相同。如需每個提供者的設定說明，請參閱[企業部署概述](/zh-TW/third-party-integrations)。若要直接跳到您的提供者上缺少的功能，請參閱[按提供者摘要](#summary-by-provider)標籤。9Claude Code CLI 和所有在本地執行的功能在每個提供者上的運作方式完全相同。如需每個提供者的設定說明，請參閱[企業部署概述](/zh-TW/third-party-integrations)。若要直接跳到您的提供者上缺少的功能，請參閱[按提供者摘要](#summary-by-provider)標籤。

10 10

18 18

19* **Claude 訂閱**：您使用 claude.ai 帳戶登入 Pro、Max、Team 或 Enterprise 計畫19* **Claude 訂閱**：您使用 claude.ai 帳戶登入 Pro、Max、Team 或 Enterprise 計畫

20* **Anthropic Console**：您使用 Anthropic API 金鑰進行驗證20* **Anthropic Console**：您使用 Anthropic API 金鑰進行驗證

21* **Amazon Bedrock**：您使用 Bedrock 模型目錄中的 Claude 模型並設定 `CLAUDE_CODE_USE_BEDROCK`。[Mantle 端點](/zh-TW/amazon-bedrock#use-the-mantle-endpoint)（`CLAUDE_CODE_USE_MANTLE`）由此欄涵蓋21* **Amazon Bedrock**：您使用 Amazon Bedrock 模型目錄中的 Claude 模型並設定 `CLAUDE_CODE_USE_BEDROCK`。[Mantle 端點](/zh-TW/amazon-bedrock#use-the-mantle-endpoint)（`CLAUDE_CODE_USE_MANTLE`）由此欄涵蓋

22* **AWS 上的 Claude Platform**：您透過 AWS Marketplace 購買了 Claude，但呼叫 Anthropic API，並設定 `CLAUDE_CODE_USE_ANTHROPIC_AWS`22* **AWS 上的 Claude Platform**：您透過 AWS Marketplace 購買了 Claude，但呼叫 Anthropic API，並設定 `CLAUDE_CODE_USE_ANTHROPIC_AWS`

~~23* **Google Vertex AI**：由 Google 營運；您設定 `CLAUDE_CODE_USE_VERTEX`~~23* **Google Cloud's Agent Platform**：由 Google 營運；您設定 `CLAUDE_CODE_USE_VERTEX`

24* **Microsoft Foundry**：由 Anthropic 在 Azure 上營運；您設定 `CLAUDE_CODE_USE_FOUNDRY`24* **Microsoft Foundry**：由 Anthropic 在 Azure 上營運；您設定 `CLAUDE_CODE_USE_FOUNDRY`

25 25

26<h3 id="features-available-on-every-provider">26<h3 id="features-available-on-every-provider">

53* [Artifacts](/zh-TW/artifacts)：Pro、Max、Team 和 Enterprise 計畫53* [Artifacts](/zh-TW/artifacts)：Pro、Max、Team 和 Enterprise 計畫

54* [Voice dictation](/zh-TW/voice-dictation)54* [Voice dictation](/zh-TW/voice-dictation)

55 55

56Desktop 是部分例外：Enterprise 部署可以透過[受管設定](https://support.claude.com/en/articles/12622667-enterprise-configuration)將 Desktop 路由到 Vertex AI 或閘道提供者，而[在 3P 研究預覽上協作](https://claude.com/docs/cowork/3p/overview)在 Bedrock、Vertex AI、Foundry 或自託管 LLM 閘道上執行 Code 標籤。如需這些功能的按計畫可用性，請參閱[按訂閱計畫的可用性](#availability-by-subscription-plan)。56Desktop 是部分例外：Enterprise 部署可以透過[受管設定](https://support.claude.com/en/articles/12622667-enterprise-configuration)將 Desktop 路由到 Google Cloud's Agent Platform 或閘道提供者，而[在 3P 上的 Claude Desktop](https://claude.com/docs/third-party/claude-desktop/overview)在 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 或自託管 LLM 閘道上執行 Code 標籤。如需這些功能的按計畫可用性，請參閱[按訂閱計畫的可用性](#availability-by-subscription-plan)。

57 57

58<h3 id="cli-capabilities-that-vary-by-provider">58<h3 id="cli-capabilities-that-vary-by-provider">

59 按提供者變化的 CLI 功能59 按提供者變化的 CLI 功能

69 <th>Anthropic Console</th>69 <th>Anthropic Console</th>

70 <th>Amazon Bedrock</th>70 <th>Amazon Bedrock</th>

71 <th>AWS 上的 Claude Platform</th>71 <th>AWS 上的 Claude Platform</th>

~~72 <th>Google Vertex AI</th>~~72 <th>Google Cloud's Agent Platform</th>

73 <th>Microsoft Foundry</th>73 <th>Microsoft Foundry</th>

74 </tr>74 </tr>

75 </thead>75 </thead>

126 </tr>126 </tr>

127 127

128 <tr>128 <tr>

129 <td>[`/loop` scheduled tasks](/zh-TW/scheduled-tasks)</td>129 <td>[`/loop` 排程任務](/zh-TW/scheduled-tasks)</td>

130 <td>✓</td>130 <td>✓</td>

131 <td>✓</td>131 <td>✓</td>

132 <td>請參閱備註 <sup><a href="#fn3">3</a></sup></td>132 <td>請參閱備註 <sup><a href="#fn3">3</a></sup></td>

161 <th>Anthropic Console</th>161 <th>Anthropic Console</th>

162 <th>Amazon Bedrock</th>162 <th>Amazon Bedrock</th>

163 <th>AWS 上的 Claude Platform</th>163 <th>AWS 上的 Claude Platform</th>

164 <th>Google Vertex AI</th>164 <th>Google Cloud's Agent Platform</th>

165 <th>Microsoft Foundry</th>165 <th>Microsoft Foundry</th>

166 </tr>166 </tr>

167 </thead>167 </thead>

199 </tbody>199 </tbody>

200</table>200</table>

201 201

202<span id="fn1" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>1</sup> 在 Vertex AI 上，web search 適用於 Claude 4 模型及更新版本。<br />202<span id="fn1" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>1</sup> 在 Google Cloud's Agent Platform 上，web search 適用於 Claude 4 模型及更新版本。<br />

203<span id="fn2" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>2</sup> 需要 `CLAUDE_CODE_ENABLE_AUTO_MODE`。請參閱 [Auto mode 配置](/zh-TW/auto-mode-config)。<br />203<span id="fn2" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>2</sup> 需要 `CLAUDE_CODE_ENABLE_AUTO_MODE`。請參閱 [Auto mode 配置](/zh-TW/auto-mode-config)。<br />

204<span id="fn3" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>3</sup> 明確的間隔（例如 `/loop every 2 hours`）在每個提供者上都有效。在 Bedrock、Vertex AI 和 Foundry 上，`/loop` 無法選擇自己的間隔或提供預設維護提示，因此沒有間隔的提示每 10 分鐘執行一次，沒有引數的 `/loop` 顯示使用訊息。請參閱[排程任務](/zh-TW/scheduled-tasks)。<br />204<span id="fn3" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>3</sup> 明確的間隔（例如 `/loop every 2 hours`）在每個提供者上都有效。在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上，`/loop` 無法選擇自己的間隔或提供預設維護提示，因此沒有間隔的提示每 10 分鐘執行一次，沒有引數的 `/loop` 顯示使用訊息。請參閱[排程任務](/zh-TW/scheduled-tasks)。<br />

205<span id="fn4" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>4</sup> 受您與雲端提供者的協議約束。<br />205<span id="fn4" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>4</sup> 受您與雲端提供者的協議約束。<br />

206<span id="fn5" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>5</sup> 僅限儀表板和 API。[貢獻指標](/zh-TW/analytics#enable-contribution-metrics)需要 claude.ai Team 或 Enterprise 組織。206<span id="fn5" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>5</sup> 僅限儀表板和 API。[貢獻指標](/zh-TW/analytics#enable-contribution-metrics)需要 claude.ai Team 或 Enterprise 組織。

207 207

213 按提供者摘要213 按提供者摘要

214</h3>214</h3>

215 215

216每個標籤列出該提供者上不可用或部分支援的功能，以及存在替代方案的地方。未列出的所有功能在 Claude 訂閱上的運作方式相同。在 Bedrock、Vertex AI、Foundry 和 AWS 上的 Claude Platform 上，向 Anthropic 的錯誤報告和遙測預設為關閉。請參閱[按 API 提供者的預設行為](/zh-TW/data-usage#default-behaviors-by-api-provider)，了解哪些流量仍會到達 Anthropic 以及如何選擇退出。216每個標籤列出該提供者上不可用或部分支援的功能，以及存在替代方案的地方。未列出的所有功能在 Claude 訂閱上的運作方式相同。在 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 和 AWS 上的 Claude Platform 上，向 Anthropic 的錯誤報告和遙測預設為關閉。請參閱[按 API 提供者的預設行為](/zh-TW/data-usage#default-behaviors-by-api-provider)，了解哪些流量仍會到達 Anthropic 以及如何選擇退出。

217 217

218<Tabs>218<Tabs>

219 <Tab title="Amazon Bedrock">219 <Tab title="Amazon Bedrock">

221 221

222 **部分支援：**222 **部分支援：**

223 223

224 * [Desktop](/zh-TW/desktop)：僅透過[在 3P 研究預覽上協作](https://claude.com/docs/cowork/3p/overview)224 * [Desktop](/zh-TW/desktop)：僅透過[在 3P 上的 Claude Desktop](https://claude.com/docs/third-party/claude-desktop/overview)

225 * [Auto mode](/zh-TW/auto-mode-config)：設定 `CLAUDE_CODE_ENABLE_AUTO_MODE`225 * [Auto mode](/zh-TW/auto-mode-config)：設定 `CLAUDE_CODE_ENABLE_AUTO_MODE`

226 * [`/loop`](/zh-TW/scheduled-tasks)：僅限明確間隔226 * [`/loop`](/zh-TW/scheduled-tasks)：僅限明確間隔

227 * [Zero Data Retention](/zh-TW/zero-data-retention)：受您的 AWS 協議約束227 * [Zero Data Retention](/zh-TW/zero-data-retention)：受您的 AWS 協議約束

237 **替代方案：** 對於排程，使用 [`/loop`](/zh-TW/scheduled-tasks) 而不是 `/schedule`。對於雲端工作階段，使用 [GitHub Actions](/zh-TW/github-actions) 或 [GitLab CI/CD](/zh-TW/gitlab-ci-cd)。237 **替代方案：** 對於排程，使用 [`/loop`](/zh-TW/scheduled-tasks) 而不是 `/schedule`。對於雲端工作階段，使用 [GitHub Actions](/zh-TW/github-actions) 或 [GitLab CI/CD](/zh-TW/gitlab-ci-cd)。

238 </Tab>238 </Tab>

239 239

240 <Tab title="Google Vertex AI">240 <Tab title="Google Cloud's Agent Platform">

241 **不可用：** 所有[需要 Claude 訂閱的功能](#features-that-require-a-claude-subscription)，加上 [fast mode](/zh-TW/fast-mode)、[Advisor](/zh-TW/advisor)、[Channels](/zh-TW/channels)、[分析儀表板](/zh-TW/analytics)和[伺服器管理的設定](/zh-TW/server-managed-settings)。241 **不可用：** 所有[需要 Claude 訂閱的功能](#features-that-require-a-claude-subscription)，加上 [fast mode](/zh-TW/fast-mode)、[Advisor](/zh-TW/advisor)、[Channels](/zh-TW/channels)、[分析儀表板](/zh-TW/analytics)和[伺服器管理的設定](/zh-TW/server-managed-settings)。

242 242

243 **部分支援：**243 **部分支援：**

244 244

245 * [Desktop](/zh-TW/desktop)：透過[受管設定](https://support.claude.com/en/articles/12622667-enterprise-configuration)或[在 3P 研究預覽上協作](https://claude.com/docs/cowork/3p/overview)245 * [Desktop](/zh-TW/desktop)：透過[受管設定](https://support.claude.com/en/articles/12622667-enterprise-configuration)或[在 3P 上的 Claude Desktop](https://claude.com/docs/third-party/claude-desktop/overview)

246 * [Web search](/zh-TW/tools-reference#websearch-tool-behavior)：Claude 4 模型及更新版本246 * [Web search](/zh-TW/tools-reference#websearch-tool-behavior)：Claude 4 模型及更新版本

247 * [Auto mode](/zh-TW/auto-mode-config)：設定 `CLAUDE_CODE_ENABLE_AUTO_MODE`247 * [Auto mode](/zh-TW/auto-mode-config)：設定 `CLAUDE_CODE_ENABLE_AUTO_MODE`

248 * [`/loop`](/zh-TW/scheduled-tasks)：僅限明確間隔248 * [`/loop`](/zh-TW/scheduled-tasks)：僅限明確間隔

256 256

257 **部分支援：**257 **部分支援：**

258 258

259 * [Desktop](/zh-TW/desktop)：僅透過[在 3P 研究預覽上協作](https://claude.com/docs/cowork/3p/overview)259 * [Desktop](/zh-TW/desktop)：僅透過[在 3P 上的 Claude Desktop](https://claude.com/docs/third-party/claude-desktop/overview)

260 * [Auto mode](/zh-TW/auto-mode-config)：設定 `CLAUDE_CODE_ENABLE_AUTO_MODE`260 * [Auto mode](/zh-TW/auto-mode-config)：設定 `CLAUDE_CODE_ENABLE_AUTO_MODE`

261 * [`/loop`](/zh-TW/scheduled-tasks)：僅限明確間隔261 * [`/loop`](/zh-TW/scheduled-tasks)：僅限明確間隔

262 * [Zero Data Retention](/zh-TW/zero-data-retention)：受您的 Azure 協議約束262 * [Zero Data Retention](/zh-TW/zero-data-retention)：受您的 Azure 協議約束

275 按訂閱計畫的可用性275 按訂閱計畫的可用性

276</h2>276</h2>

277 277

278如果您透過 Bedrock、Vertex AI、Foundry 或 Anthropic Console API 金鑰進行驗證，本節不適用於您。當您使用 claude.ai 帳戶登入時，您的計畫決定了下列功能中哪些可用。278如果您透過 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 Anthropic Console API 金鑰進行驗證，本節不適用於您。當您使用 claude.ai 帳戶登入時，您的計畫決定了下列功能中哪些可用。

279 279

280| 功能 | Pro | Max | Team | Enterprise |280| 功能 | Pro | Max | Team | Enterprise |

281| :-------------------------------------------------------------------------------------- | :-- | :-- | :---- | :-------------------------------- |281| :-------------------------------------------------------------------------------------- | :-- | :-- | :---- | :-------------------------------- |

303 模型可用性303 模型可用性

304</h2>304</h2>

305 305

306如需每個提供者和地區可用的 Claude 模型和內容視窗大小，請參閱[模型配置](/zh-TW/model-config)和[模型概述](https://platform.claude.com/docs/en/about-claude/models/overview)。Vision、PDF 輸入和擴展思考是模型功能而非 Claude Code 功能，在提供該模型的每個提供者上都有效。[Prompt caching](/zh-TW/prompt-caching) 在大多數提供者上的運作方式相同；在 Bedrock 上，支援因模型而異。306如需每個提供者和地區可用的 Claude 模型和內容視窗大小，請參閱[模型配置](/zh-TW/model-config)和[模型概述](https://platform.claude.com/docs/en/about-claude/models/overview)。Vision、PDF 輸入和擴展思考是模型功能而非 Claude Code 功能，在提供該模型的每個提供者上都有效。[Prompt caching](/zh-TW/prompt-caching) 在大多數提供者上的運作方式相同；在 Amazon Bedrock 上，支援因模型而異。

307 307

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

309 相關資源309 相關資源

310</h2>310</h2>

311 311

312* [企業部署概述](/zh-TW/third-party-integrations)：比較提供者之間的驗證、計費和地區312* [企業部署概述](/zh-TW/third-party-integrations)：比較提供者之間的驗證、計費和地區

313* 提供者設定指南：[Amazon Bedrock](/zh-TW/amazon-bedrock)、[AWS 上的 Claude Platform](/zh-TW/claude-platform-on-aws)、[Google Vertex AI](/zh-TW/google-vertex-ai)、[Microsoft Foundry](/zh-TW/microsoft-foundry)313* 提供者設定指南：[Amazon Bedrock](/zh-TW/amazon-bedrock)、[AWS 上的 Claude Platform](/zh-TW/claude-platform-on-aws)、[Google Cloud 的 Agent Platform](/zh-TW/google-vertex-ai)、[Microsoft Foundry](/zh-TW/microsoft-foundry)

314* [平台和整合](/zh-TW/platforms)：Claude Code 執行的位置，包括 CLI、Desktop、IDE 擴充功能、網頁、行動和 CI/CD314* [平台和整合](/zh-TW/platforms)：Claude Code 執行的位置，包括 CLI、Desktop、IDE 擴充功能、網頁、行動和 CI/CD

fullscreen.md +3 −1

Details

170 170

171全螢幕渲染與 iTerm2 的 tmux 整合模式不相容，這是您使用 `tmux -CC` 進入的模式。在整合模式中，iTerm2 將每個 tmux 窗格渲染為原生分割，而不是讓 tmux 繪製到終端。替代螢幕緩衝區和滑鼠追蹤在那裡無法正確運作：滑鼠滾輪無法執行任何操作，雙擊可能會損壞終端狀態。不要在 `tmux -CC` 工作階段中啟用全螢幕渲染。在 iTerm2 內的常規 tmux（沒有 `-CC`）運作良好。171全螢幕渲染與 iTerm2 的 tmux 整合模式不相容，這是您使用 `tmux -CC` 進入的模式。在整合模式中，iTerm2 將每個 tmux 窗格渲染為原生分割，而不是讓 tmux 繪製到終端。替代螢幕緩衝區和滑鼠追蹤在那裡無法正確運作：滑鼠滾輪無法執行任何操作，雙擊可能會損壞終端狀態。不要在 `tmux -CC` 工作階段中啟用全螢幕渲染。在 iTerm2 內的常規 tmux（沒有 `-CC`）運作良好。

172 172

173tmux 不支援同步輸出，因此在重繪期間您可能會看到比直接在終端中執行 Claude Code 時更多的閃爍。如果閃爍明顯，特別是在 SSH 上，請在 tmux 外的自己的終端標籤中執行 Claude Code。173並非每個 tmux 版本都會套用應用程式的同步輸出，因此在 tmux 下重繪期間您可能會看到比直接在終端中執行 Claude Code 時更多的閃爍。如果閃爍明顯，特別是在 SSH 上，請升級到最新的 tmux 或在 tmux 外的自己的終端標籤中執行 Claude Code。使用 `tmux -V` 檢查您的 tmux 版本。

174

175{/* min-version: 2.1.200 */}Claude Code 在偵測到來自 `TERM_PROGRAM_VERSION` 變數的 tmux 3.4 或更新版本時會自動開啟同步輸出，當無法判斷版本時會回退到直接查詢終端以取得同步輸出支援。重繪是否實際上變成原子操作取決於您的 tmux 版本是否遵守同步輸出；如果您在 tmux 3.4 或更新版本下仍然看到閃爍，請升級到最新的 tmux。此偵測需要 Claude Code v2.1.200 或更新版本。

174 176

175<h2 id="keep-native-text-selection">177<h2 id="keep-native-text-selection">

176 保持原生文字選擇178 保持原生文字選擇

github-actions.md +25 −25

Details

51<Note>51<Note>

52 * 您必須是儲存庫管理員才能安裝 GitHub app 並新增密鑰52 * 您必須是儲存庫管理員才能安裝 GitHub app 並新增密鑰

53 * GitHub app 將要求對內容、議題和 Pull request 的讀取和寫入權限53 * GitHub app 將要求對內容、議題和 Pull request 的讀取和寫入權限

54 * 此快速入門方法僅適用於直接 Claude API 使用者。如果您使用 Amazon Bedrock 或 Google Vertex AI，請參閱 [使用 Amazon Bedrock 和 Google Vertex AI](#using-with-amazon-bedrock-%26-google-vertex-ai) 部分。54 * 此快速入門方法僅適用於直接 Claude API 使用者。如果您使用 Amazon Bedrock 或 Google Cloud 的 Agent Platform，請參閱 [使用 Amazon Bedrock 和 Google Cloud](#using-with-amazon-bedrock-and-google-cloud) 部分。

55</Note>55</Note>

56 56

57<h2 id="manual-setup">57<h2 id="manual-setup">

320 當回應議題或 PR 評論時，Claude 會自動回應 @claude 提及。對於其他事件，使用 `prompt` 參數來提供指令。320 當回應議題或 PR 評論時，Claude 會自動回應 @claude 提及。對於其他事件，使用 `prompt` 參數來提供指令。

321</Tip>321</Tip>

322 322

323<h2 id="using-with-amazon-bedrock--google-vertex-ai">323<h2 id="using-with-amazon-bedrock-and-google-cloud">

324 使用 Amazon Bedrock 和 Google Vertex AI324 使用 Amazon Bedrock 和 Google Cloud

325</h2>325</h2>

326 326

327對於企業環境，您可以使用 Claude Code GitHub Actions 搭配您自己的雲端基礎設施。此方法讓您可以控制資料駐留和計費，同時保持相同的功能。327對於企業環境，您可以使用 Claude Code GitHub Actions 搭配您自己的雲端基礎設施。此方法讓您可以控制資料駐留和計費，同時保持相同的功能。

332 332

333在使用雲端提供者設定 Claude Code GitHub Actions 之前，您需要：333在使用雲端提供者設定 Claude Code GitHub Actions 之前，您需要：

334 334

335<h4 id="for-google-cloud-vertex-ai">335<h4 id="for-google-cloud’s-agent-platform">

336 對於 Google Cloud Vertex AI：336 對於 Google Cloud 的 Agent Platform：

337</h4>337</h4>

338 338

3391. 啟用了 Vertex AI 的 Google Cloud 專案3391. 啟用了 Google Cloud 的 Agent Platform 的 Google Cloud 專案

3402. 為 GitHub Actions 設定的工作負載身份聯盟3402. 為 GitHub Actions 設定的工作負載身份聯盟

3413. 具有所需權限的服務帳戶3413. 具有所需權限的服務帳戶

3424. GitHub App（建議）或使用預設 GITHUB\_TOKEN3424. GitHub App（建議）或使用預設 GITHUB\_TOKEN

347 347

3481. 啟用了 Amazon Bedrock 的 AWS 帳戶3481. 啟用了 Amazon Bedrock 的 AWS 帳戶

3492. 在 AWS 中設定的 GitHub OIDC 身份提供者3492. 在 AWS 中設定的 GitHub OIDC 身份提供者

3503. 具有 Bedrock 權限的 IAM 角色3503. 具有 Amazon Bedrock 權限的 IAM 角色

3514. GitHub App（建議）或使用預設 GITHUB\_TOKEN3514. GitHub App（建議）或使用預設 GITHUB\_TOKEN

352 352

353<Steps>353<Steps>

354 <Step title="建立自訂 GitHub App（建議用於第三方提供者）">354 <Step title="建立自訂 GitHub App（建議用於第三方提供者）">

355 為了在使用 Vertex AI 或 Bedrock 等第三方提供者時獲得最佳控制和安全性，我們建議建立您自己的 GitHub App：355 為了在使用 Google Cloud 的 Agent Platform 或 Amazon Bedrock 等第三方提供者時獲得最佳控制和安全性，我們建議建立您自己的 GitHub App：

356 356

357 1. 前往 [https://github.com/settings/apps/new](https://github.com/settings/apps/new)357 1. 前往 [https://github.com/settings/apps/new](https://github.com/settings/apps/new)

358 2. 填寫基本資訊：358 2. 填寫基本資訊：

428 請參閱 [AWS 文件](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html)以取得詳細的 OIDC 設定說明。428 請參閱 [AWS 文件](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html)以取得詳細的 OIDC 設定說明。

429 </Accordion>429 </Accordion>

430 430

431 <Accordion title="Google Vertex AI">431 <Accordion title="Google Cloud 的 Agent Platform">

432 **設定 Google Cloud 以允許 GitHub Actions 安全地進行身份驗證，而無需儲存認證。**432 **設定 Google Cloud 以允許 GitHub Actions 安全地進行身份驗證，而無需儲存認證。**

433 433

434 > **安全性注意**：使用儲存庫特定的設定並僅授予最少所需的權限。434 > **安全性注意**：使用儲存庫特定的設定並僅授予最少所需的權限。

438 1. **在您的 Google Cloud 專案中啟用 API**：438 1. **在您的 Google Cloud 專案中啟用 API**：

439 * IAM Credentials API439 * IAM Credentials API

440 * Security Token Service (STS) API440 * Security Token Service (STS) API

441 * Vertex AI API441 * Google Cloud 的 Agent Platform API

442 442

443 2. **建立工作負載身份聯盟資源**：443 2. **建立工作負載身份聯盟資源**：

444 * 建立工作負載身份池444 * 建立工作負載身份池

483 * `APP_ID`：您的 GitHub App 的 ID483 * `APP_ID`：您的 GitHub App 的 ID

484 * `APP_PRIVATE_KEY`：私鑰 (.pem) 內容484 * `APP_PRIVATE_KEY`：私鑰 (.pem) 內容

485 485

486 #### 對於 Google Cloud Vertex AI486 #### 對於 Google Cloud 的 Agent Platform

487 487

488 1. **對於 GCP 身份驗證**：488 1. **對於 GCP 身份驗證**：

489 * `GCP_WORKLOAD_IDENTITY_PROVIDER`489 * `GCP_WORKLOAD_IDENTITY_PROVIDER`

504 </Step>504 </Step>

505 505

506 <Step title="建立工作流程檔案">506 <Step title="建立工作流程檔案">

507 建立與您的雲端提供者整合的 GitHub Actions 工作流程檔案。以下範例顯示了 Amazon Bedrock 和 Google Vertex AI 的完整設定：507 建立與您的雲端提供者整合的 GitHub Actions 工作流程檔案。以下範例顯示了 Amazon Bedrock 和 Google Cloud 的 Agent Platform 的完整設定：

508 508

509 <AccordionGroup>509 <AccordionGroup>

510 <Accordion title="Amazon Bedrock 工作流程">510 <Accordion title="Amazon Bedrock 工作流程">

512 512

513 * 啟用了 Amazon Bedrock 存取且具有 Claude 模型權限513 * 啟用了 Amazon Bedrock 存取且具有 Claude 模型權限

514 * GitHub 在 AWS 中設定為 OIDC 身份提供者514 * GitHub 在 AWS 中設定為 OIDC 身份提供者

515 * 具有 Bedrock 權限且信任 GitHub Actions 的 IAM 角色515 * 具有 Amazon Bedrock 權限且信任 GitHub Actions 的 IAM 角色

516 516

517 **必需的 GitHub 密鑰：**517 **必需的 GitHub 密鑰：**

518 518

519 | 密鑰名稱 | 描述 |519 | 密鑰名稱 | 描述 |

520 | -------------------- | --------------------------- |520 | -------------------- | ------------------------------ |

524 524

573 ```573 ```

574 574

575 <Tip>575 <Tip>

576 Bedrock 的模型 ID 格式包括區域前綴（例如 `us.anthropic.claude-sonnet-4-6`）。576 Amazon Bedrock 的模型 ID 格式包括區域前綴（例如 `us.anthropic.claude-sonnet-4-6`）。

577 </Tip>577 </Tip>

578 </Accordion>578 </Accordion>

579 579

580 <Accordion title="Google Vertex AI 工作流程">580 <Accordion title="Google Cloud 的 Agent Platform 工作流程">

581 **先決條件：**581 **先決條件：**

582 582

583 * 在您的 GCP 專案中啟用了 Vertex AI API583 * 在您的 GCP 專案中啟用了 Google Cloud 的 Agent Platform API

584 * 為 GitHub 設定的工作負載身份聯盟584 * 為 GitHub 設定的工作負載身份聯盟

585 * 具有 Vertex AI 權限的服務帳戶585 * 具有 Google Cloud 的 Agent Platform 權限的服務帳戶

586 586

587 **必需的 GitHub 密鑰：**587 **必需的 GitHub 密鑰：**

588 588

589 | 密鑰名稱 | 描述 |589 | 密鑰名稱 | 描述 |

590 | -------------------------------- | --------------------------- |590 | -------------------------------- | ---------------------------------------------- |

595 595

675 身份驗證錯誤675 身份驗證錯誤

676</h3>676</h3>

677 677

678確認 API 金鑰有效且具有足夠的權限。對於 Bedrock/Vertex，檢查認證設定並確保密鑰在工作流程中命名正確。678確認 API 金鑰有效且具有足夠的權限。對於 Amazon Bedrock 或 Google Cloud 的 Agent Platform，檢查認證設定並確保密鑰在工作流程中命名正確。

679 679

680<h2 id="advanced-configuration">680<h2 id="advanced-configuration">

681 進階設定681 進階設定

688Claude Code Action v1 使用簡化的設定：688Claude Code Action v1 使用簡化的設定：

689 689

690| 參數 | 描述 | 必需 |690| 參數 | 描述 | 必需 |

691| --------------------- | ------------------------------------------ | ----- |691| --------------------- | ----------------------------------------------- | ----- |

692| `prompt` | Claude 的指令（純文字或 [skill](/zh-TW/skills) 名稱） | 否\* |692| `prompt` | Claude 的指令（純文字或 [skill](/zh-TW/skills) 名稱） | 否\* |

693| `claude_args` | 傳遞給 Claude Code 的 CLI 引數 | 否 |693| `claude_args` | 傳遞給 Claude Code 的 CLI 引數 | 否 |

694| `plugin_marketplaces` | 以換行符分隔的 plugin marketplace Git URL 清單 | 否 |694| `plugin_marketplaces` | 以換行符分隔的 plugin marketplace Git URL 清單 | 否 |

697| `github_token` | 用於 API 存取的 GitHub 令牌 | 否 |697| `github_token` | 用於 API 存取的 GitHub 令牌 | 否 |

698| `trigger_phrase` | 自訂觸發短語（預設：「@claude」） | 否 |698| `trigger_phrase` | 自訂觸發短語（預設：「@claude」） | 否 |

699| `use_bedrock` | 使用 Amazon Bedrock 而不是 Claude API | 否 |699| `use_bedrock` | 使用 Amazon Bedrock 而不是 Claude API | 否 |

700| `use_vertex` | 使用 Google Vertex AI 而不是 Claude API | 否 |700| `use_vertex` | 使用 Google Cloud 的 Agent Platform 而不是 Claude API | 否 |

701 701

702\*提示是可選的 - 當在議題/PR 評論中省略時，Claude 回應觸發短語\702\*提示是可選的 - 當在議題/PR 評論中省略時，Claude 回應觸發短語\

703\*\*對於直接 Claude API 是必需的，對於 Bedrock/Vertex 不是必需的703\*\*對於直接 Claude API 是必需的，對於 Amazon Bedrock 或 Google Cloud 的 Agent Platform 不是必需的

704 704

705<h4 id="pass-cli-arguments">705<h4 id="pass-cli-arguments">

706 傳遞 CLI 引數706 傳遞 CLI 引數

github-enterprise-server.md +61 −26

Details

10 GitHub Enterprise Server 支持適用於 Team 和 Enterprise 計劃。10 GitHub Enterprise Server 支持適用於 Team 和 Enterprise 計劃。

11</Note>11</Note>

12 12

13GitHub Enterprise Server (GHES) 支持讓您的組織使用 Claude Code 與託管在自管理 GitHub 實例上的存儲庫，而不是 github.com。一旦 Owner 連接您的 GHES 實例，開發人員可以運行網頁會話、獲得自動化代碼審查，並從內部市場安裝插件，無需任何按存儲庫的配置。13GitHub Enterprise Server (GHES) 支持讓您的組織使用 Claude Code 與託管在自管理 GitHub 實例上的存儲庫，而不是 github.com。一旦 Owner 連接您的 GHES 實例，開發人員可以運行網頁會話和獲得自動化代碼審查，無需任何按存儲庫的配置。您實例上託管的插件市場也受支持；憑證要求因表面而異，如 [GHES 上的插件市場](#plugin-marketplaces-on-ghes) 中所述。

14 14

15對於 github.com 上的存儲庫，請參閱 [Claude Code on the web](/zh-TW/claude-code-on-the-web) 和 [Code Review](/zh-TW/code-review)。要在您自己的 CI 基礎設施中運行 Claude，請參閱 [GitHub Actions](/zh-TW/github-actions)。15對於 github.com 上的存儲庫，請參閱 [Claude Code on the web](/zh-TW/claude-code-on-the-web) 和 [Code Review](/zh-TW/code-review)。要在您自己的 CI 基礎設施中運行 Claude，請參閱 [GitHub Actions](/zh-TW/github-actions)。

16 16

21下表顯示了 Claude Code 的哪些功能支持 GHES，以及與 github.com 行為的任何差異。21下表顯示了 Claude Code 的哪些功能支持 GHES，以及與 github.com 行為的任何差異。

22 22

23| 功能 | GHES 支持 | 備註 |23| 功能 | GHES 支持 | 備註 |

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

~~25| Claude Code on the web | ✅ 支持 | 管理員連接 GHES 實例一次；開發人員像往常一樣使用 `claude --remote` 或 [claude.ai/code](https://claude.ai/code) |~~25| Claude Code on the web | ✅ 支持 | 管理員連接 GHES 實例一次；開發人員像往常一樣使用 `claude --cloud` 或 [claude.ai/code](https://claude.ai/code) |

26| Code Review | ✅ 支持 | 與 github.com 相同的自動化 PR 審查 |26| Code Review | ✅ 支持 | 與 github.com 相同的自動化 PR 審查 |

27| Claude Security | ✅ 支持 | 在 Enterprise 計劃的公開測試版中提供，位於 [claude.ai/security](https://claude.ai/security) |27| Claude Security | ✅ 支持 | 在 Enterprise 計劃的公開測試版中提供，位於 [claude.ai/security](https://claude.ai/security) |

28| Teleport sessions | ✅ 支持 | 使用 `--teleport` 在網頁和終端之間移動會話 |28| Teleport sessions | ✅ 支持 | 使用 `--teleport` 在網頁和終端之間移動會話 |

~~29| Plugin marketplaces | ✅ 支持 | 使用完整的 git URL 而不是 `owner/repo` 簡寫 |~~29| Plugin marketplaces | ✅ 支持 | 認證要求因介面而異。請參閱 [GHES 上的 Plugin marketplaces](#plugin-marketplaces-on-ghes) |

30| Contribution metrics | ✅ 支持 | 通過 webhooks 傳遞到 [analytics dashboard](/zh-TW/analytics) |30| Contribution metrics | ✅ 支持 | 通過 webhooks 傳遞到 [analytics dashboard](/zh-TW/analytics) |

31| GitHub Actions | ✅ 支持 | 需要手動工作流設置；`/install-github-app` 僅適用於 github.com |31| GitHub Actions | ✅ 支持 | 需要手動工作流設置；`/install-github-app` 僅適用於 github.com |

32| GitHub MCP server | ❌ 不支持 | GitHub MCP server 不適用於 GHES 實例 |32| GitHub MCP server | ❌ 不支持 | GitHub MCP server 不適用於 GHES 實例 |

107然後開始網頁會話。Claude 從您的 git 遠程檢測 GHES 主機，並通過您組織的配置實例路由會話：107然後開始網頁會話。Claude 從您的 git 遠程檢測 GHES 主機，並通過您組織的配置實例路由會話：

108 108

109```bash theme={null}109```bash theme={null}

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

111```111```

112 112

113會話在 Anthropic 基礎設施上運行，從 GHES 克隆您的存儲庫，並將更改推送回分支。使用 `/tasks` 或在 [claude.ai/code](https://claude.ai/code) 監控進度。有關完整的遠程會話工作流（包括 diff 審查、自動修復和例程），請參閱 [Claude Code on the web](/zh-TW/claude-code-on-the-web)。113會話在 Anthropic 基礎設施上運行，從 GHES 克隆您的存儲庫，並將更改推送回分支。使用 `/tasks` 或在 [claude.ai/code](https://claude.ai/code) 監控進度。有關完整的遠程會話工作流（包括 diff 審查、自動修復和例程），請參閱 [Claude Code on the web](/zh-TW/claude-code-on-the-web)。

122 GHES 上的插件市場122 GHES 上的插件市場

123</h2>123</h2>

124 124

125在您的 GHES 實例上託管插件市場，以在您的組織中分發內部工具。市場結構與 github.com 託管的市場相同；唯一的區別是您如何引用它們。125在您的 GHES 實例上託管插件市場，以在您的組織中分發內部工具。市場結構與 github.com 託管的市場相同，但安裝方式取決於您在何處新增市場，且認證在不同介面上有所不同：

126

127| 介面 | 安裝方式 | 每個使用者需要什麼 |

128| :------------------------------ | :------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------- |

129| Claude Code CLI 和桌面應用 | Claude Code 使用機器現有的 git 認證複製市場存儲庫 | 從其機器對您的 GHES 主機的 Git 存取權 |

130| 託管設定 (`extraKnownMarketplaces`) | Claude Code 註冊該項目並使用機器現有的 git 認證複製存儲庫 | 從其機器對您的 GHES 主機的 Git 存取權 |

131| claude.ai 組織插件設定 | 擁有者選擇 GHES 實例作為來源；Anthropic 的後端使用來自 [管理員設定](#admin-setup) 的 GitHub App 擷取並同步存儲庫 | 新增後每個使用者無需任何操作。新增它的擁有者需要連接自己的 GitHub Enterprise 帳戶作為存取檢查，且 GitHub App 必須安裝在市場存儲庫上 |

132| claude.ai 使用者設定 | Anthropic 的後端使用提交使用者的 GitHub Enterprise 連接擷取存儲庫 | 連接到 Claude 的自己的 GitHub Enterprise 帳戶 |

133| Claude Code 網頁版 | 雲端工作階段在工作階段沙箱內複製市場。沙箱只有在工作階段的存儲庫位於同一實例上時，才能到達您的 GHES 實例，且其 git 認證的範圍限於工作階段的存儲庫 | 對於 GHES 託管的市場不可靠：與工作階段存儲庫不同的主機無法到達，即使是同一實例的安裝也可能失敗。請改用 CLI、託管設定或 claude.ai |

134

135<Warning>

136 當從使用者設定新增市場時，claude.ai 上的 GitHub Enterprise 連接是按使用者的。[管理員設定](#admin-setup) 將您的 GHES 實例連接到您的組織，但它不連接個別使用者帳戶：每個從自己的設定新增 GHES 市場的使用者必須先連接自己的 GitHub Enterprise 帳戶，且一個使用者的連接（包括擁有者的）不涵蓋任何其他人。由擁有者在組織插件設定中新增的市場不會對使用者施加此要求，因為持續的擷取使用組織的 GitHub App。新增市場的擁有者仍然需要在新增時連接自己的 GitHub Enterprise 帳戶。

137</Warning>

126 138

127<h3 id="add-a-ghes-marketplace">139<h3 id="add-a-ghes-marketplace">

128 添加 GHES 市場140 添加 GHES 市場

129</h3>141</h3>

130 142

131`owner/repo` 簡寫始終解析為 github.com。對於 GHES 託管的市場，使用完整的 git URL：143`owner/repo` 簡寫始終解析為 github.com。對於 GHES 託管的市場，請使用完整的 git URL。建議使用 HTTPS URL：

132 144

133```bash theme={null}145```bash theme={null}

134/plugin marketplace add git@github.example.com:platform/claude-plugins.git146/plugin marketplace add https://github.example.com/platform/claude-plugins.git

135```147```

136 148

137HTTPS URL 也可以工作：149如果機器已經信任您的 GHES 主機，SSH URL 也可以工作：

138 150

139```bash theme={null}151```bash theme={null}

140/plugin marketplace add https://github.example.com/platform/claude-plugins.git152/plugin marketplace add git@github.example.com:platform/claude-plugins.git

141```153```

142 154

155Claude Code 以非互動方式執行 git，並拒絕連接到不在機器 `known_hosts` 檔案中的主機的 SSH 連接。帶有 git 認證幫助程式的 HTTPS URL 可以避免 `known_hosts` 要求。

156

143有關構建市場的完整指南，請參閱 [Create and distribute a plugin marketplace](/zh-TW/plugin-marketplaces)。157有關構建市場的完整指南，請參閱 [Create and distribute a plugin marketplace](/zh-TW/plugin-marketplaces)。

144 158

159<h3 id="pre-register-ghes-marketplaces-with-managed-settings">

160 使用託管設定預先註冊 GHES 市場

161</h3>

162

163`extraKnownMarketplaces` 設定預先註冊市場，以便開發人員無需手動設定即可獲得它。它可以從 [任何設定檔案](/zh-TW/settings#extraknownmarketplaces) 工作，包括存儲庫的 `.claude/settings.json`；託管設定可以組織範圍內傳遞它：

164

165```json theme={null}

166{

167 "extraKnownMarketplaces": {

168 "internal-tools": {

169 "source": {

170 "source": "git",

171 "url": "https://github.example.com/platform/claude-plugins.git"

172 }

173 }

174 }

175}

176```

177

178Claude Code 在本地安裝這些市場：它註冊每個項目並使用機器現有的 git 認證複製存儲庫。此路徑不經過 claude.ai，因此不需要按使用者的 GitHub Enterprise 連接。為了成功推出：

179

180* **使用完整的 git URL。** `owner/repo` 簡寫始終解析為 github.com，無法參考 GHES 主機。

181* **偏好 HTTPS URL。** SSH 複製在不已信任您的 GHES 主機金鑰的機器上失敗。帶有您組織標準 git 認證幫助程式的 HTTPS URL 可在任何配置了認證的機器上工作。

182* **確認每台機器都可以從您的 GHES 主機複製。** 如果機器缺少認證，市場已註冊但永遠不會安裝，其插件報告為未找到而不是提示輸入認證。

183* **確認設定到達每台機器。** 託管設定檔案只對部署到的機器生效，例如透過您的裝置管理系統。有關檔案位置，請參閱 [託管設定](/zh-TW/settings#settings-files)。

184

145<h3 id="allowlist-ghes-marketplaces-in-managed-settings">185<h3 id="allowlist-ghes-marketplaces-in-managed-settings">

146 在託管設定中將 GHES 市場列入白名單186 在託管設定中將 GHES 市場列入白名單

147</h3>187</h3>

159}199}

160```200```

161 201

162您也可以為開發人員預先註冊市場，以便它們無需手動設定即可顯示。此示例使內部工具市場在整個組織中可用：

~~163~~

164```json theme={null}

165{

166 "extraKnownMarketplaces": {

167 "internal-tools": {

168 "source": {

169 "source": "git",

170 "url": "git@github.example.com:platform/claude-plugins.git"

171 }

172 }

173 }

174}

175```

~~176~~

177有關完整的架構，請參閱 [strictKnownMarketplaces](/zh-TW/settings#strictknownmarketplaces) 和 [extraKnownMarketplaces](/zh-TW/settings#extraknownmarketplaces) 設定參考。202有關完整的架構，請參閱 [strictKnownMarketplaces](/zh-TW/settings#strictknownmarketplaces) 和 [extraKnownMarketplaces](/zh-TW/settings#extraknownmarketplaces) 設定參考。

178 203

179<h2 id="limitations">204<h2 id="limitations">

193 網頁會話無法克隆存儲庫218 網頁會話無法克隆存儲庫

194</h3>219</h3>

195 220

196如果 `claude --remote` 因克隆錯誤而失敗，請驗證 Owner 已完成您的 GHES 實例的設置，並且 GitHub App 已安裝在您正在使用的存儲庫上。與連接該實例的 Owner 確認在 Claude 設置中註冊的主機名與您的 git 遠端中的主機名匹配。221如果 `claude --cloud` 因克隆錯誤而失敗，請驗證 Owner 已完成您的 GHES 實例的設置，並且 GitHub App 已安裝在您正在使用的存儲庫上。與連接該實例的 Owner 確認在 Claude 設置中註冊的主機名與您的 git 遠端中的主機名匹配。

197 222

198<h3 id="marketplace-add-fails-with-a-policy-error">223<h3 id="marketplace-add-fails-with-a-policy-error">

199 市場添加因策略錯誤而失敗224 市場添加因策略錯誤而失敗

201 226

202如果 `/plugin marketplace add` 因您的 GHES URL 而被阻止，您的組織已限制市場源。要求您的管理員在 [託管設置](#allowlist-ghes-marketplaces-in-managed-settings) 中為您的 GHES 主機名添加 `hostPattern` 條目。227如果 `/plugin marketplace add` 因您的 GHES URL 而被阻止，您的組織已限制市場源。要求您的管理員在 [託管設置](#allowlist-ghes-marketplaces-in-managed-settings) 中為您的 GHES 主機名添加 `hostPattern` 條目。

203 228

229<h3 id="marketplace-add-on-claude-ai-fails-with-a-github-access-error">

230 claude.ai 上的市場添加因 GitHub 存取錯誤而失敗

231</h3>

232

233如果從您的使用者設置添加 GHES 市場失敗並出現通用錯誤（例如「無法添加市場」），請先檢查您的 GitHub Enterprise 連接。這是當您自己的 GitHub Enterprise 帳戶未連接到 Claude 時出現的情況，即使您的組織的 GHES 實例已配置且其他使用者已連接。該對話框不會指向 GitHub Enterprise 連接流程，而「瀏覽」標籤上的「連接到 GitHub」選項會登入 github.com，這不會授予對 GHES 存儲庫的存取權限。

234

235要連接您的 GitHub Enterprise 帳戶：[claude.ai/code](https://claude.ai/code) 上的存儲庫選擇器為每個已配置的 GHES 實例提供連接選項，Owner 也可以從 [Claude Code 管理員設置](https://claude.ai/admin-settings/claude-code) 的 GitHub Enterprise 部分進行連接。然後再次添加市場。或者，要求 Owner 在組織外掛程式設置中添加市場，這樣可以消除每個使用者的連接要求。

236

237在其他 claude.ai 表面上，GHES 市場上的「找不到存儲庫。如果是私有的，需要 GitHub 存取」錯誤通常表示相同的缺失連接。通過上述路徑之一連接您的 GitHub Enterprise 帳戶，然後重試。

238

204<h3 id="ghes-instance-not-reachable">239<h3 id="ghes-instance-not-reachable">

205 GHES 實例無法訪問240 GHES 實例無法訪問

206</h3>241</h3>

gitlab-ci-cd.md +30 −30

Details

24* **自動化實現**：使用單一命令或提及將問題轉變為可運作的程式碼24* **自動化實現**：使用單一命令或提及將問題轉變為可運作的程式碼

25* **專案感知**：Claude 遵循您的 `CLAUDE.md` 指南和現有程式碼模式25* **專案感知**：Claude 遵循您的 `CLAUDE.md` 指南和現有程式碼模式

26* **簡單設定**：在 `.gitlab-ci.yml` 中新增一個工作和一個遮罩 CI/CD 變數26* **簡單設定**：在 `.gitlab-ci.yml` 中新增一個工作和一個遮罩 CI/CD 變數

~~27* **企業就緒**：選擇 Claude API、Amazon Bedrock 或 Google Vertex AI 以滿足資料駐留和採購需求~~27* **企業就緒**：選擇 Claude API、Amazon Bedrock 或 Google Cloud 的 Agent Platform 以滿足資料駐留和採購需求

28* **預設安全**：在您的 GitLab runners 中執行，具有您的分支保護和核准28* **預設安全**：在您的 GitLab runners 中執行，具有您的分支保護和核准

29 29

30<h2 id="how-it-works">30<h2 id="how-it-works">

382. **提供者抽象化**：使用適合您環境的提供者：382. **提供者抽象化**：使用適合您環境的提供者：

39 * Claude API (SaaS)39 * Claude API (SaaS)

40 * Amazon Bedrock (基於 IAM 的存取、跨區域選項)40 * Amazon Bedrock (基於 IAM 的存取、跨區域選項)

~~41 * Google Vertex AI (GCP 原生、Workload Identity Federation)~~41 * Google Cloud 的 Agent Platform (GCP 原生、Workload Identity Federation)

42 42

433. **沙箱執行**：每次互動都在具有嚴格網路和檔案系統規則的容器中執行。Claude Code 強制執行工作區範圍的權限以限制寫入。每項變更都透過 MR 流動，以便審查者看到差異並且核准仍然適用。433. **沙箱執行**：每次互動都在具有嚴格網路和檔案系統規則的容器中執行。Claude Code 強制執行工作區範圍的權限以限制寫入。每項變更都透過 MR 流動，以便審查者看到差異並且核准仍然適用。

44 44

108新增工作和您的 `ANTHROPIC_API_KEY` 變數後，透過 **CI/CD** → **Pipelines** 手動執行工作進行測試，或從 MR 觸發它，讓 Claude 在分支中提出更新並在需要時開啟 MR。108新增工作和您的 `ANTHROPIC_API_KEY` 變數後，透過 **CI/CD** → **Pipelines** 手動執行工作進行測試，或從 MR 觸發它，讓 Claude 在分支中提出更新並在需要時開啟 MR。

109 109

110<Note>110<Note>

111 若要改為在 Amazon Bedrock 或 Google Vertex AI 上執行而不是 Claude API，請參閱下方的 [Using with Amazon Bedrock & Google Vertex AI](#using-with-amazon-bedrock-%26-google-vertex-ai) 部分，了解驗證和環境設定。111 若要改為在 Amazon Bedrock 或 Google Cloud 的 Agent Platform 上執行而不是 Claude API，請參閱下方的 [Using with Amazon Bedrock and Google Cloud](#using-with-amazon-bedrock-and-google-cloud) 部分，了解驗證和環境設定。

112</Note>112</Note>

113 113

114<h3 id="manual-setup-recommended-for-production">114<h3 id="manual-setup-recommended-for-production">

119 119

1201. **設定提供者存取**：1201. **設定提供者存取**：

121 * **Claude API**：建立並將 `ANTHROPIC_API_KEY` 儲存為遮罩 CI/CD 變數121 * **Claude API**：建立並將 `ANTHROPIC_API_KEY` 儲存為遮罩 CI/CD 變數

122 * **Amazon Bedrock**：**Configure GitLab** → **AWS OIDC** 並為 Bedrock 建立 IAM 角色122 * **Amazon Bedrock**：**Configure GitLab** → **AWS OIDC** 並為 Amazon Bedrock 建立 IAM 角色

123 * **Google Vertex AI**：**Configure Workload Identity Federation for GitLab** → **GCP**123 * **Google Cloud 的 Agent Platform**：**Configure Workload Identity Federation for GitLab** → **GCP**

124 124

1252. **為 GitLab API 操作新增專案認證**：1252. **為 GitLab API 操作新增專案認證**：

126 * 預設使用 `CI_JOB_TOKEN`，或建立具有 `api` 範圍的專案存取令牌126 * 預設使用 `CI_JOB_TOKEN`，或建立具有 `api` 範圍的專案存取令牌

172 172

173Claude 定位錯誤，實現修復，並更新分支或開啟新的 MR。173Claude 定位錯誤，實現修復，並更新分支或開啟新的 MR。

174 174

175<h2 id="using-with-amazon-bedrock--google-vertex-ai">175<h2 id="using-with-amazon-bedrock-and-google-cloud">

176 使用 Amazon Bedrock 和 Google Vertex AI176 使用 Amazon Bedrock 和 Google Cloud

177</h2>177</h2>

178 178

179對於企業環境，您可以在您的雲端基礎設施上完全執行 Claude Code，具有相同的開發人員體驗。179對於企業環境，您可以在您的雲端基礎設施上完全執行 Claude Code，具有相同的開發人員體驗。

186 186

187 1. 具有 Amazon Bedrock 存取權限的 AWS 帳戶，可存取所需的 Claude 模型187 1. 具有 Amazon Bedrock 存取權限的 AWS 帳戶，可存取所需的 Claude 模型

188 2. 在 AWS IAM 中設定為 OIDC 身份提供者的 GitLab188 2. 在 AWS IAM 中設定為 OIDC 身份提供者的 GitLab

189 3. 具有 Bedrock 權限和信任政策的 IAM 角色，限制於您的 GitLab 專案/refs189 3. 具有 Amazon Bedrock 權限和信任政策的 IAM 角色，限制於您的 GitLab 專案/refs

190 4. 用於角色假設的 GitLab CI/CD 變數：190 4. 用於角色假設的 GitLab CI/CD 變數：

191 * `AWS_ROLE_TO_ASSUME`（角色 ARN）191 * `AWS_ROLE_TO_ASSUME`（角色 ARN）

192 * `AWS_REGION`（Bedrock 區域）192 * `AWS_REGION`（Amazon Bedrock 區域）

193 193

194 ### 設定說明194 ### 設定說明

195 195

200 1. 啟用 Amazon Bedrock 並請求存取您的目標 Claude 模型200 1. 啟用 Amazon Bedrock 並請求存取您的目標 Claude 模型

201 2. 為 GitLab 建立 IAM OIDC 提供者（如果尚未存在）201 2. 為 GitLab 建立 IAM OIDC 提供者（如果尚未存在）

202 3. 建立由 GitLab OIDC 提供者信任的 IAM 角色，限制於您的專案和受保護的 refs202 3. 建立由 GitLab OIDC 提供者信任的 IAM 角色，限制於您的專案和受保護的 refs

203 4. 為 Bedrock invoke API 附加最小權限203 4. 為 Amazon Bedrock invoke API 附加最小權限

204 204

205 **要儲存在 CI/CD 變數中的必需值：**205 **要儲存在 CI/CD 變數中的必需值：**

206 206

218 使用上面的 Amazon Bedrock 工作範例在執行時交換 GitLab 工作令牌以取得臨時 AWS 認證。218 使用上面的 Amazon Bedrock 工作範例在執行時交換 GitLab 工作令牌以取得臨時 AWS 認證。

219 </Tab>219 </Tab>

220 220

221 <Tab title="Google Vertex AI">221 <Tab title="Google Cloud's Agent Platform">

222 ### 先決條件222 ### 先決條件

223 223

224 在使用 Google Vertex AI 設定 Claude Code 之前，您需要：224 在使用 Google Cloud's Agent Platform 設定 Claude Code 之前，您需要：

225 225

226 1. 具有以下內容的 Google Cloud 專案：226 1. 具有以下內容的 Google Cloud 專案：

227 * 啟用 Vertex AI API227 * 啟用 Google Cloud's Agent Platform API

228 * 設定 Workload Identity Federation 以信任 GitLab OIDC228 * 設定 Workload Identity Federation 以信任 GitLab OIDC

229 2. 僅具有所需 Vertex AI 角色的專用服務帳戶229 2. 僅具有所需 Google Cloud's Agent Platform 角色的專用服務帳戶

230 3. 用於 WIF 的 GitLab CI/CD 變數：230 3. 用於 WIF 的 GitLab CI/CD 變數：

231 * `GCP_WORKLOAD_IDENTITY_PROVIDER`（完整資源名稱）231 * `GCP_WORKLOAD_IDENTITY_PROVIDER`（完整資源名稱）

232 * `GCP_SERVICE_ACCOUNT`（服務帳戶電子郵件）232 * `GCP_SERVICE_ACCOUNT`（服務帳戶電子郵件）

237 237

238 **必需的設定：**238 **必需的設定：**

239 239

240 1. 啟用 IAM Credentials API、STS API 和 Vertex AI API240 1. 啟用 IAM Credentials API、STS API 和 Google Cloud's Agent Platform API

241 2. 為 GitLab OIDC 建立 Workload Identity Pool 和提供者241 2. 為 GitLab OIDC 建立 Workload Identity Pool 和提供者

242 3. 建立具有 Vertex AI 角色的專用服務帳戶242 3. 建立具有 Google Cloud's Agent Platform 角色的專用服務帳戶

243 4. 授予 WIF 主體權限以模擬服務帳戶243 4. 授予 WIF 主體權限以模擬服務帳戶

244 244

245 **要儲存在 CI/CD 變數中的必需值：**245 **要儲存在 CI/CD 變數中的必需值：**

250 在 Settings → CI/CD → Variables 中新增變數：250 在 Settings → CI/CD → Variables 中新增變數：

251 251

252 ```yaml theme={null}252 ```yaml theme={null}

253 # 對於 Google Vertex AI：253 # 對於 Google Cloud's Agent Platform：

254 - GCP_WORKLOAD_IDENTITY_PROVIDER254 - GCP_WORKLOAD_IDENTITY_PROVIDER

255 - GCP_SERVICE_ACCOUNT255 - GCP_SERVICE_ACCOUNT

256 - CLOUD_ML_REGION (例如，us-east5)256 - CLOUD_ML_REGION (例如，us-east5)

257 ```257 ```

258 258

259 使用上面的 Google Vertex AI 工作範例在不儲存金鑰的情況下進行驗證。259 使用上面的 Google Cloud's Agent Platform 工作範例在不儲存金鑰的情況下進行驗證。

260 </Tab>260 </Tab>

261</Tabs>261</Tabs>

262 262

305 305

306* 啟用 Amazon Bedrock 並存取您選擇的 Claude 模型306* 啟用 Amazon Bedrock 並存取您選擇的 Claude 模型

307* 在 AWS 中設定 GitLab OIDC，具有信任您的 GitLab 專案和 refs 的角色307* 在 AWS 中設定 GitLab OIDC，具有信任您的 GitLab 專案和 refs 的角色

308* 具有 Bedrock 權限的 IAM 角色（建議最小權限）308* 具有 Amazon Bedrock 權限的 IAM 角色（建議最小權限）

309 309

310**必需的 CI/CD 變數：**310**必需的 CI/CD 變數：**

311 311

312* `AWS_ROLE_TO_ASSUME`：Bedrock 存取的 IAM 角色的 ARN312* `AWS_ROLE_TO_ASSUME`：Amazon Bedrock 存取的 IAM 角色的 ARN

313* `AWS_REGION`：Bedrock 區域（例如，`us-west-2`）313* `AWS_REGION`：Amazon Bedrock 區域（例如，`us-west-2`）

314 314

315```yaml theme={null}315```yaml theme={null}

316claude-bedrock:316claude-bedrock:

347```347```

348 348

349<Note>349<Note>

350 Bedrock 的模型 ID 包括區域特定的前綴（例如，`us.anthropic.claude-sonnet-4-6`）。如果您的工作流程支援，透過您的工作設定或提示傳遞所需的模型。350 Amazon Bedrock 的模型 ID 包括區域特定的前綴（例如，`us.anthropic.claude-sonnet-4-6`）。如果您的工作流程支援，透過您的工作設定或提示傳遞所需的模型。

351</Note>351</Note>

352 352

353<h3 id="google-vertex-ai-job-example-workload-identity-federation">353<h3 id="agent-platform-job-example-workload-identity-federation">

354 Google Vertex AI 工作範例 (Workload Identity Federation)354 Agent Platform 工作範例 (Workload Identity Federation)

355</h3>355</h3>

356 356

357**先決條件：**357**先決條件：**

358 358

359* 在您的 GCP 專案中啟用 Vertex AI API359* 在您的 GCP 專案中啟用 Google Cloud 的 Agent Platform API

360* 設定 Workload Identity Federation 以信任 GitLab OIDC360* 設定 Workload Identity Federation 以信任 GitLab OIDC

361* 具有 Vertex AI 權限的服務帳戶361* 具有 Google Cloud 的 Agent Platform 權限的服務帳戶

362 362

363**必需的 CI/CD 變數：**363**必需的 CI/CD 變數：**

364 364

365* `GCP_WORKLOAD_IDENTITY_PROVIDER`：完整提供者資源名稱365* `GCP_WORKLOAD_IDENTITY_PROVIDER`：完整提供者資源名稱

366* `GCP_SERVICE_ACCOUNT`：服務帳戶電子郵件366* `GCP_SERVICE_ACCOUNT`：服務帳戶電子郵件

367* `CLOUD_ML_REGION`：Vertex 區域（例如，`us-east5`）367* `CLOUD_ML_REGION`：Google Cloud 的 Agent Platform 區域（例如，`us-east5`）

368 368

369```yaml theme={null}369```yaml theme={null}

370claude-vertex:370claude-vertex:

490</h3>490</h3>

491 491

492* **對於 Claude API**：確認 `ANTHROPIC_API_KEY` 有效且未過期492* **對於 Claude API**：確認 `ANTHROPIC_API_KEY` 有效且未過期

493* **對於 Bedrock/Vertex**：驗證 OIDC/WIF 設定、角色模擬和祕密名稱；確認區域和模型可用性493* **對於 Amazon Bedrock 或 Google Cloud 的 Agent Platform**：驗證 OIDC/WIF 設定、角色模擬和祕密名稱；確認區域和模型可用性

494 494

495<h2 id="advanced-configuration">495<h2 id="advanced-configuration">

496 進階設定496 進階設定

505* `prompt` / `prompt_file`：內聯提供說明（`-p`）或透過檔案505* `prompt` / `prompt_file`：內聯提供說明（`-p`）或透過檔案

506* `max_turns`：限制來回反覆的次數506* `max_turns`：限制來回反覆的次數

507* `timeout_minutes`：限制總執行時間507* `timeout_minutes`：限制總執行時間

508* `ANTHROPIC_API_KEY`：Claude API 所需（不用於 Bedrock/Vertex）508* `ANTHROPIC_API_KEY`：Claude API 所需（不用於 Amazon Bedrock 或 Google Cloud 的 Agent Platform）

509* 提供者特定環境：`AWS_REGION`、Vertex 的專案/區域變數509* 提供者特定環境：`AWS_REGION`、Google Cloud 的 Agent Platform 的專案/區域變數

510 510

511<Note>511<Note>

512 確切的旗標和參數可能因 `@anthropic-ai/claude-code` 的版本而異。在您的工作中執行 `claude --help` 以查看支援的選項。512 確切的旗標和參數可能因 `@anthropic-ai/claude-code` 的版本而異。在您的工作中執行 `claude --help` 以查看支援的選項。

glossary.md +3 −1

Details

262 262

263會話的基線批准行為。在 CLI 中使用 `Shift+Tab` 循環或在 VS Code、Desktop 和 claude.ai 中使用模式選擇器。可用的模式是 `default`、`acceptEdits`、`plan`、`auto`、`dontAsk` 和 `bypassPermissions`。263會話的基線批准行為。在 CLI 中使用 `Shift+Tab` 循環或在 VS Code、Desktop 和 claude.ai 中使用模式選擇器。可用的模式是 `default`、`acceptEdits`、`plan`、`auto`、`dontAsk` 和 `bypassPermissions`。

264 264

265`default` 模式在 CLI 和 VS Code 及 JetBrains 擴充功能中標記為 Manual，Claude Code 接受 `manual` 作為該值的別名。

266

265了解更多：[選擇權限模式](/zh-TW/permission-modes)267了解更多：[選擇權限模式](/zh-TW/permission-modes)

266 268

267<h3 id="permission-rule">269<h3 id="permission-rule">

388 Teleport390 Teleport

389</h3>391</h3>

390 392

391一個命令 `/teleport`，它將雲 Claude Code 會話拉入您的本地終端。Claude 獲取分支、載入對話歷史並從 web 會話的最後狀態恢復。反向方向是 `--remote`，它將本地任務發送到 web 上執行。393一個命令 `/teleport`，它將雲 Claude Code 會話拉入您的本地終端。Claude 獲取分支、載入對話歷史並從 web 會話的最後狀態恢復。反向方向是 `--cloud`，它將本地任務發送到 web 上執行。

392 394

393了解更多：[From web to terminal](/zh-TW/claude-code-on-the-web#from-web-to-terminal)395了解更多：[From web to terminal](/zh-TW/claude-code-on-the-web#from-web-to-terminal)

394 396

google-vertex-ai.md +38 −38

Details

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.3> Use this file to discover all available pages before exploring further.

4 4

~~5# Google Vertex AI 上的 Claude Code~~5# Google Cloud 的 Agent Platform 上的 Claude Code

6 6

~~7> 了解如何透過 Google Vertex AI 設定 Claude Code，包括設定、IAM 設定和故障排除。~~7> 了解如何透過 Google Cloud 的 Agent Platform（前身為 Vertex AI）設定 Claude Code，包括設定、IAM 設定和故障排除。

8 8

9export const ContactSalesCard = ({surface}) => {9export const ContactSalesCard = ({surface}) => {

10 const utm = content => `utm_source=claude_code&utm_medium=docs&utm_content=${surface}_${content}`;10 const utm = content => `utm_source=claude_code&utm_medium=docs&utm_content=${surface}_${content}`;

82 先決條件82 先決條件

83</h2>83</h2>

84 84

~~85在使用 Vertex AI 設定 Claude Code 之前，請確保您具有：~~85在使用 Google Cloud 的 Agent Platform（前身為 Vertex AI）設定 Claude Code 之前，請確保您具有：

86 86

87* 已啟用計費的 Google Cloud Platform (GCP) 帳戶87* 已啟用計費的 Google Cloud Platform (GCP) 帳戶

~~88* 已啟用 Vertex AI API 的 GCP 專案~~88* 已啟用 Google Cloud 的 Agent Platform API 的 GCP 專案

89* 存取所需的 Claude 模型（例如 Claude Sonnet 4.6）89* 存取所需的 Claude 模型（例如 Claude Sonnet 4.6）

90* 已安裝並設定 Google Cloud SDK (`gcloud`)90* 已安裝並設定 Google Cloud SDK (`gcloud`)

91* 在所需的 GCP 區域中分配的配額91* 在所需的 GCP 區域中分配的配額

92 92

93若要使用您自己的 Vertex AI 認證登入，請遵循下方的[使用 Vertex AI 登入](#sign-in-with-vertex-ai)。若要在整個團隊中部署 Claude Code，請使用[手動設定](#set-up-manually)步驟並在推出前[固定您的模型版本](#5-pin-model-versions)。93若要使用您自己的 Google Cloud 的 Agent Platform 認證登入，請遵循下方的[使用 Google Cloud 的 Agent Platform 登入](#sign-in-with-agent-platform)。若要在整個團隊中部署 Claude Code，請使用[手動設定](#set-up-manually)步驟並在推出前[固定您的模型版本](#5-pin-model-versions)。

94 94

~~95<h2 id="sign-in-with-vertex-ai">~~95<h2 id="sign-in-with-agent-platform">

~~96 使用 Vertex AI 登入~~96 使用 Agent Platform 登入

97</h2>97</h2>

98 98

99如果您有 Google Cloud 認證並想開始透過 Vertex AI 使用 Claude Code，登入精靈會引導您完成整個過程。您只需在每個專案中完成一次 GCP 端的先決條件；精靈會處理 Claude Code 端的設定。99如果您有 Google Cloud 認證並想開始透過 Google Cloud 的 Agent Platform 使用 Claude Code，登入精靈會引導您完成整個過程。您只需在每個專案中完成一次 GCP 端的先決條件；精靈會處理 Claude Code 端的設定。

100 100

101<Note>101<Note>

102 Vertex AI 設定精靈需要 Claude Code v2.1.98 或更新版本。執行 `claude --version` 以檢查。102 Google Cloud 的 Agent Platform 設定精靈需要 Claude Code v2.1.98 或更新版本。執行 `claude --version` 以檢查。

103</Note>103</Note>

104 104

105<Steps>105<Steps>

106 <Step title="在您的 GCP 專案中啟用 Claude 模型">106 <Step title="在您的 GCP 專案中啟用 Claude 模型">

107 為您的專案[啟用 Vertex AI API](#1-enable-vertex-ai-api)，然後在 [Vertex AI Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) 中要求存取您想要的 Claude 模型。請參閱 [IAM 設定](#iam-configuration)以了解您的帳戶需要的權限。107 為您的專案[啟用 Google Cloud 的 Agent Platform API](#1-enable-agent-platform-api)，然後在 [Google Cloud 的 Agent Platform Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) 中要求存取您想要的 Claude 模型。請參閱 [IAM 設定](#iam-configuration)以了解您的帳戶需要的權限。

108 </Step>108 </Step>

109 109

110 <Step title="啟動 Claude Code 並選擇 Vertex AI">110 <Step title="啟動 Claude Code 並選擇 Google Cloud 的 Agent Platform">

111 執行 `claude`。在登入提示處，選擇**第三方平台**，然後選擇 **Google Vertex AI**。111 執行 `claude`。在登入提示處，選擇**第三方平台**，然後選擇 **Google Vertex AI**，這是登入提示仍然用於 Google Cloud 的 Agent Platform 的標籤。

112 </Step>112 </Step>

113 113

114 <Step title="遵循精靈提示">114 <Step title="遵循精靈提示">

122 區域設定122 區域設定

123</h2>123</h2>

124 124

125Claude Code 支援 Vertex AI [全球](https://cloud.google.com/blog/products/ai-machine-learning/global-endpoint-for-claude-models-generally-available-on-vertex-ai)、多區域和區域端點。將 `CLOUD_ML_REGION` 設定為 `global`、多區域位置（例如 `eu` 或 `us`）或特定區域（例如 `us-east5`）。Claude Code 為每種形式選擇正確的 Vertex AI 主機名稱，包括多區域位置的 `aiplatform.eu.rep.googleapis.com` 和 `aiplatform.us.rep.googleapis.com` 主機。125Claude Code 支援 Google Cloud 的 Agent Platform [全球](https://cloud.google.com/blog/products/ai-machine-learning/global-endpoint-for-claude-models-generally-available-on-vertex-ai)、多區域和區域端點。將 `CLOUD_ML_REGION` 設定為 `global`、多區域位置（例如 `eu` 或 `us`）或特定區域（例如 `us-east5`）。Claude Code 為每種形式選擇正確的 Google Cloud 的 Agent Platform 主機名稱，包括多區域位置的 `aiplatform.eu.rep.googleapis.com` 和 `aiplatform.us.rep.googleapis.com` 主機。

126 126

127<Note>127<Note>

128 Vertex AI 可能不支援每個端點類型上的 Claude Code 預設模型。模型可用性在[特定區域](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations#genai-partner-models)、多區域位置和[全球端點](https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/use-partner-models#supported_models)之間有所不同。您可能需要切換到支援的位置或指定支援的模型。128 Google Cloud 的 Agent Platform 可能不支援每個端點類型上的 Claude Code 預設模型。模型可用性在[特定區域](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations#genai-partner-models)、多區域位置和[全球端點](https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/use-partner-models#supported_models)之間有所不同。您可能需要切換到支援的位置或指定支援的模型。

129</Note>129</Note>

130 130

131<h2 id="set-up-manually">131<h2 id="set-up-manually">

132 手動設定132 手動設定

133</h2>133</h2>

134 134

135若要透過環境變數而不是精靈來設定 Vertex AI，例如在 CI 或指令碼化企業推出中，請遵循下列步驟。135若要透過環境變數而不是精靈來設定 Google Cloud 的 Agent Platform，例如在 CI 或指令碼化企業推出中，請遵循下列步驟。

136 136

137<h3 id="1-enable-vertex-ai-api">137<h3 id="1-enable-agent-platform-api">

138 1. 啟用 Vertex AI API138 1. 啟用 Agent Platform API

139</h3>139</h3>

140 140

141在您的 GCP 專案中啟用 Vertex AI API：141在您的 GCP 專案中啟用 Google Cloud 的 Agent Platform API：

142 142

143```bash theme={null}143```bash theme={null}

144# 設定您的專案 ID144# 設定您的專案 ID

145gcloud config set project YOUR-PROJECT-ID145gcloud config set project YOUR-PROJECT-ID

146 146

147# 啟用 Vertex AI API147# 啟用 Agent Platform API

148gcloud services enable aiplatform.googleapis.com148gcloud services enable aiplatform.googleapis.com

149```149```

150 150

152 2. 要求模型存取152 2. 要求模型存取

153</h3>153</h3>

154 154

155在 Vertex AI 中要求存取 Claude 模型：155在 Google Cloud 的 Agent Platform 中要求存取 Claude 模型：

156 156

1571. 導覽至 [Vertex AI Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)1571. 導覽至 [Google Cloud 的 Agent Platform Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)

1582. 搜尋'Claude'模型1582. 搜尋'Claude'模型

1593. 要求存取所需的 Claude 模型（例如 Claude Sonnet 4.6）1593. 要求存取所需的 Claude 模型（例如 Claude Sonnet 4.6）

1604. 等待核准（可能需要 24-48 小時）1604. 等待核准（可能需要 24-48 小時）

170Claude Code v2.1.121 或更新版本透過相同的 Application Default Credentials 鏈支援 [X.509 憑證型 Workload Identity Federation](https://cloud.google.com/iam/docs/workload-identity-federation-with-x509-certificates)。將 `GOOGLE_APPLICATION_CREDENTIALS` 設定為您的認證設定檔案路徑。170Claude Code v2.1.121 或更新版本透過相同的 Application Default Credentials 鏈支援 [X.509 憑證型 Workload Identity Federation](https://cloud.google.com/iam/docs/workload-identity-federation-with-x509-certificates)。將 `GOOGLE_APPLICATION_CREDENTIALS` 設定為您的認證設定檔案路徑。

171 171

172<Note>172<Note>

173 Claude Code 使用 `ANTHROPIC_VERTEX_PROJECT_ID` 作為 Vertex AI 要求的專案 ID。`GCLOUD_PROJECT` 和 `GOOGLE_CLOUD_PROJECT` 環境變數以及 `GOOGLE_APPLICATION_CREDENTIALS` 參考的認證檔案優先於它。如果這些都未設定，專案 ID 會從您的 `gcloud` 設定或附加的服務帳戶解析。173 Claude Code 使用 `ANTHROPIC_VERTEX_PROJECT_ID` 作為 Google Cloud 的 Agent Platform 要求的專案 ID。`GCLOUD_PROJECT` 和 `GOOGLE_CLOUD_PROJECT` 環境變數以及 `GOOGLE_APPLICATION_CREDENTIALS` 參考的認證檔案優先於它。如果這些都未設定，專案 ID 會從您的 `gcloud` 設定或附加的服務帳戶解析。

174</Note>174</Note>

175 175

176<h4 id="advanced-credential-configuration">176<h4 id="advanced-credential-configuration">

197設定下列環境變數：197設定下列環境變數：

198 198

199```bash theme={null}199```bash theme={null}

200# 啟用 Vertex AI 整合200# 啟用 Agent Platform 整合

201export CLAUDE_CODE_USE_VERTEX=1201export CLAUDE_CODE_USE_VERTEX=1

202export CLOUD_ML_REGION=global202export CLOUD_ML_REGION=global

203export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID203export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

204 204

205# 選用：覆寫 Vertex 端點 URL 以用於自訂端點或閘道205# 選用：覆寫 Agent Platform 端點 URL 以用於自訂端點或閘道

206# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com206# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com

207 207

208# 選用：如需要，停用 prompt caching208# 選用：如需要，停用 prompt caching

216export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1216export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1

217```217```

218 218

219大多數模型版本都有對應的 `VERTEX_REGION_CLAUDE_*` 變數。如需完整清單，請參閱[環境變數參考](/zh-TW/env-vars)。檢查 [Vertex Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) 以確定哪些模型支援全球端點與僅限區域端點。219大多數模型版本都有對應的 `VERTEX_REGION_CLAUDE_*` 變數。如需完整清單，請參閱[環境變數參考](/zh-TW/env-vars)。檢查 [Google Cloud 的 Agent Platform Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) 以確定哪些模型支援全球端點與僅限區域端點。

220 220

221[Prompt caching](/zh-TW/prompt-caching) 會自動啟用。若要停用它，請設定 `DISABLE_PROMPT_CACHING=1`。若要要求 1 小時 cache TTL 而不是 5 分鐘預設值，請設定 `ENABLE_PROMPT_CACHING_1H=1`；具有 1 小時 TTL 的 cache 寫入會以更高費率計費。如需提高速率限制，請聯絡 Google Cloud 支援。使用 Vertex AI 時，`/logout` 命令會被停用，因為驗證是透過 Google Cloud 認證處理的。221[Prompt caching](/zh-TW/prompt-caching) 會自動啟用。若要停用它，請設定 `DISABLE_PROMPT_CACHING=1`。若要要求 1 小時 cache TTL 而不是 5 分鐘預設值，請設定 `ENABLE_PROMPT_CACHING_1H=1`；具有 1 小時 TTL 的 cache 寫入會以更高費率計費。如需提高速率限制，請聯絡 Google Cloud 支援。使用 Google Cloud 的 Agent Platform 時，`/logout` 命令會被停用，因為驗證是透過 Google Cloud 認證處理的。

222 222

223Claude Code 在 Vertex AI 上預設停用 [MCP tool search](/zh-TW/mcp#scale-with-mcp-tool-search)，因此 MCP 工具定義會預先載入。Vertex AI 支援 Claude Sonnet 4.5 及更新版本以及 Claude Opus 4.5 及更新版本的工具搜尋。設定 `ENABLE_TOOL_SEARCH=true` 以在這些模型上啟用它。Vertex AI 上的較早模型不接受所需的 beta 標頭，如果您使用它們啟用工具搜尋，要求會失敗。223Claude Code 在 Google Cloud 的 Agent Platform 上預設停用 [MCP tool search](/zh-TW/mcp#scale-with-mcp-tool-search)，因此 MCP 工具定義會預先載入。Google Cloud 的 Agent Platform 支援 Claude Sonnet 4.5 及更新版本以及 Claude Opus 4.5 及更新版本的工具搜尋。設定 `ENABLE_TOOL_SEARCH=true` 以在這些模型上啟用它。Google Cloud 的 Agent Platform 上的較早模型不接受所需的 beta 標頭，如果您使用它們啟用工具搜尋，要求會失敗。

224 224

225<h3 id="5-pin-model-versions">225<h3 id="5-pin-model-versions">

226 5. 固定模型版本226 5. 固定模型版本

227</h3>227</h3>

228 228

229<Warning>229<Warning>

230 在部署到多個使用者時固定特定模型版本。如果不固定，模型別名（例如 `sonnet` 和 `opus`）會解析為 Claude Code 針對 Vertex AI 的內建預設值，該預設值可能落後於最新版本，且可能尚未在您的專案中啟用。Claude Code 在啟動時會在預設值無法使用時[回退](#startup-model-checks)到先前版本，但固定可讓您控制使用者何時移至新模型。230 在部署到多個使用者時固定特定模型版本。如果不固定，模型別名（例如 `sonnet` 和 `opus`）會解析為 Claude Code 針對 Google Cloud 的 Agent Platform 的內建預設值，該預設值可能落後於最新版本，且可能尚未在您的專案中啟用。Claude Code 在啟動時會在預設值無法使用時[回退](#startup-model-checks)到先前版本，但固定可讓您控制使用者何時移至新模型。

231</Warning>231</Warning>

232 232

233將這些環境變數設定為特定的 Vertex AI 模型 ID。233將這些環境變數設定為特定的 Google Cloud 的 Agent Platform 模型 ID。

234 234

235如果沒有 `ANTHROPIC_DEFAULT_OPUS_MODEL`，Vertex 上的 `opus` 別名會解析為 Opus 4.6。將其設定為 Opus 4.8 ID 以使用最新模型：235如果沒有 `ANTHROPIC_DEFAULT_OPUS_MODEL`，Google Cloud 的 Agent Platform 上的 `opus` 別名會解析為 Opus 4.6。將其設定為 Opus 4.8 ID 以使用最新模型：

236 236

237```bash theme={null}237```bash theme={null}

238export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'238export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'

250| 小型/快速模型 | 與主要模型相同 |250| 小型/快速模型 | 與主要模型相同 |

251 251

252背景工作（例如工作階段標題產生）使用小型/快速模型，通常是 Haiku 級模型。在 Vertex AI 上，Claude Code 預設為主要模型，因為 Haiku 可能不會在每個專案或區域中啟用。若要使用 Haiku 進行背景工作，請將 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 設定為您專案中可用的模型 ID。252背景工作（例如工作階段標題產生）使用小型/快速模型，通常是 Haiku 級模型。在 Google Cloud 的 Agent Platform 上，Claude Code 預設為主要模型，因為 Haiku 可能不會在每個專案或區域中啟用。若要使用 Haiku 進行背景工作，請將 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 設定為您專案中可用的模型 ID。

253 253

254若要進一步自訂模型：254若要進一步自訂模型：

255 255

262 啟動模型檢查262 啟動模型檢查

263</h2>263</h2>

264 264

265當 Claude Code 以設定的 Vertex AI 啟動時，它會驗證它打算使用的模型在您的專案中是否可存取。此檢查需要 Claude Code v2.1.98 或更新版本。265當 Claude Code 以 Google Cloud 的 Agent Platform 設定啟動時，它會驗證它打算使用的模型在您的專案中是否可存取。此檢查需要 Claude Code v2.1.98 或更新版本。

266 266

267如果您已固定的模型版本比目前 Claude Code 預設值更舊，且您的專案可以呼叫較新版本，Claude Code 會提示您更新固定。接受會將新模型 ID 寫入您的[使用者設定檔](/zh-TW/settings)並重新啟動 Claude Code。拒絕會被記住，直到下一次預設版本變更。267如果您已固定的模型版本比目前 Claude Code 預設值更舊，且您的專案可以呼叫較新版本，Claude Code 會提示您更新固定。接受會將新模型 ID 寫入您的[使用者設定檔](/zh-TW/settings)並重新啟動 Claude Code。拒絕會被記住，直到下一次預設版本變更。

268 268

280 280

281如需更嚴格的權限，請建立只包含上述權限的自訂角色。281如需更嚴格的權限，請建立只包含上述權限的自訂角色。

282 282

283如需詳細資訊，請參閱 [Vertex IAM 文件](https://cloud.google.com/vertex-ai/docs/general/access-control)。283如需詳細資訊，請參閱 [Google Cloud 的 Agent Platform IAM 文件](https://cloud.google.com/vertex-ai/docs/general/access-control)。

284 284

285<Note>285<Note>

286 為 Claude Code 建立專用的 GCP 專案，以簡化成本追蹤和存取控制。286 為 Claude Code 建立專用的 GCP 專案，以簡化成本追蹤和存取控制。

290 1M token context window290 1M token context window

291</h2>291</h2>

292 292

293Claude Sonnet 5、Opus 4.6 及更新版本，以及 Sonnet 4.6，在 Vertex AI 上支援 [1M token context window](https://platform.claude.com/docs/zh-TW/build-with-claude/context-windows#1m-token-context-window)。Sonnet 5 始終以 1M 視窗執行，沒有 `[1m]` 變體可選擇。對於其他模型，Claude Code 會在您選擇 1M 模型變體時自動啟用擴展 context window。293Claude Sonnet 5、Opus 4.6 及更新版本，以及 Sonnet 4.6，在 Google Cloud 的 Agent Platform 上支援 [1M token context window](https://platform.claude.com/docs/zh-TW/build-with-claude/context-windows#1m-token-context-window)。Sonnet 5 始終以 1M 視窗執行，沒有 `[1m]` 變體可選擇。對於其他模型，Claude Code 會在您選擇 1M 模型變體時自動啟用擴展 context window。

294 294

295[設定精靈](#sign-in-with-vertex-ai)在固定模型時提供 1M context 選項。若要為手動固定的模型啟用它，請在模型 ID 後附加 `[1m]`。如需詳細資訊，請參閱[為第三方部署固定模型](/zh-TW/model-config#pin-models-for-third-party-deployments)。295[設定精靈](#sign-in-with-agent-platform)在固定模型時提供 1M context 選項。若要為手動固定的模型啟用它，請在模型 ID 後附加 `[1m]`。如需詳細資訊，請參閱[為第三方部署固定模型](/zh-TW/model-config#pin-models-for-third-party-deployments)。

296 296

297<h2 id="troubleshooting">297<h2 id="troubleshooting">

298 故障排除298 故障排除

325 其他資源325 其他資源

326</h2>326</h2>

327 327

328* [Vertex AI 文件](https://cloud.google.com/vertex-ai/docs)328* [Google Cloud 的 Agent Platform 文件](https://cloud.google.com/vertex-ai/docs)

329* [Vertex AI 定價](https://cloud.google.com/vertex-ai/pricing)329* [Google Cloud 的 Agent Platform 定價](https://cloud.google.com/vertex-ai/pricing)

330* [Vertex AI 配額和限制](https://cloud.google.com/vertex-ai/docs/quotas)330* [Google Cloud 的 Agent Platform 配額和限制](https://cloud.google.com/vertex-ai/docs/quotas)

headless.md +9 −3

Details

56| 自訂 agents | `--agents <json>` |56| 自訂 agents | `--agents <json>` |

57| 外掛程式 | `--plugin-dir <path>`, `--plugin-url <url>` |57| 外掛程式 | `--plugin-dir <path>`, `--plugin-url <url>` |

58 58

59裸機模式跳過 OAuth 和鑰匙圈讀取。Anthropic 驗證必須來自 `ANTHROPIC_API_KEY` 或傳遞給 `--settings` 的 JSON 中的 `apiKeyHelper`。Bedrock、Vertex 和 Foundry 使用其通常的提供者認證。59裸機模式跳過 OAuth 和鑰匙圈讀取。Anthropic 驗證必須來自 `ANTHROPIC_API_KEY` 或傳遞給 `--settings` 的 JSON 中的 `apiKeyHelper`。Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 使用其通常的提供者認證。

60 60

61<Note>61<Note>

62 `--bare` 是指令碼和 SDK 呼叫的建議模式，將在未來版本中成為 `-p` 的預設值。62 `--bare` 是指令碼和 SDK 呼叫的建議模式，將在未來版本中成為 `-p` 的預設值。

136 --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'136 --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'

137```137```

138 138

139如果值不是有效的 JSON Schema，`claude` 會以 `Error: --json-schema is not a valid JSON Schema` 退出，後面跟著驗證器的診斷。Claude Code 接受使用 `format` 關鍵字的結構描述，例如 `"format": "email"`，但將 `format` 視為註解，不強制執行它。在 v2.1.205 之前，Claude Code 會以無聲方式忽略無效的結構描述並傳回非結構化文字，並將任何包含 `format` 的結構描述視為無效。

140

139<Tip>141<Tip>

140 使用 [jq](https://jqlang.github.io/jq/) 之類的工具來解析回應並提取特定欄位：142 使用 [jq](https://jqlang.github.io/jq/) 之類的工具來解析回應並提取特定欄位：

141 143

182| `uuid` | 字串 | 唯一事件識別碼 |184| `uuid` | 字串 | 唯一事件識別碼 |

183| `session_id` | 字串 | 事件所屬的工作階段 |185| `session_id` | 字串 | 事件所屬的工作階段 |

184 186

185`system/init` 事件報告工作階段中繼資料，包括模型、工具、MCP 伺服器和載入的外掛程式。除非設定了 [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/zh-TW/env-vars)，否則它是串流中的第一個事件，在這種情況下 `plugin_install` 事件在其之前。使用外掛程式欄位在外掛程式未載入時使 CI 失敗：187`system/init` 事件報告工作階段中繼資料，包括模型、工具、MCP 伺服器和載入的外掛程式。除非設定了 [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/zh-TW/env-vars)，否則它是串流中的第一個事件，在這種情況下 `plugin_install` 事件在其之前。

188

189該事件也包含一個選用的 `capabilities` 字串陣列，命名此 Claude Code 版本實施的協定行為，例如 `interrupt_receipt_v1`。檢查它以進行功能偵測，而不是比較版本字串，並忽略您不認識的值。該欄位需要 Claude Code v2.1.205 或更新版本，在較早版本中不存在。請參閱 [`SDKSystemMessage`](/zh-TW/agent-sdk/typescript#sdksystemmessage) 以取得功能清單。

190

191使用外掛程式欄位在外掛程式未載入時使 CI 失敗：

186 192

187| 欄位 | 類型 | 描述 |193| 欄位 | 類型 | 描述 |

188| --------------- | -- | ----------------------------------------------------------------------------------------------------------------------------------- |194| --------------- | -- | ----------------------------------------------------------------------------------------------------------------------------------- |

234`--allowedTools` 旗標使用 [權限規則語法](/zh-TW/settings#permission-rule-syntax)。尾部的 ` *` 啟用前綴匹配，因此 `Bash(git diff *)` 允許任何以 `git diff` 開頭的命令。空格在 `*` 之前很重要：沒有它，`Bash(git diff*)` 也會符合 `git diff-index`。240`--allowedTools` 旗標使用 [權限規則語法](/zh-TW/settings#permission-rule-syntax)。尾部的 ` *` 啟用前綴匹配，因此 `Bash(git diff *)` 允許任何以 `git diff` 開頭的命令。空格在 `*` 之前很重要：沒有它，`Bash(git diff*)` 也會符合 `git diff-index`。

235 241

236<Note>242<Note>

237 使用者叫用的 [skills](/zh-TW/skills) 和自訂命令在 `-p` 模式中運作：在提示字串中包含 `/skill-name`，Claude Code 會在執行前展開它。開啟互動對話的內建命令，例如 `/login`，在 `-p` 模式中不可用。{/* min-version: 2.1.181 */}若要從 `-p` 叫用變更設定，請將 `key=value` 傳遞至 `/config`，例如 `/config thinking=false`。243 使用者叫用的 [skills](/zh-TW/skills) 和自訂命令在 `-p` 模式中運作：在提示字串中包含 `/skill-name`，Claude Code 會在執行前展開它。開啟互動對話的內建命令，例如 `/login`，在 `-p` 模式中不可用。{/* min-version: 2.1.205 */}`/model`、`/effort`、`/fast`、`/color` 和 `/rename` 接受值作為引數，例如 `/model sonnet`，`/mcp` 不帶引數會列印伺服器狀態的文字摘要；這些形式需要 Claude Code v2.1.205 或更新版本，並遵循每個命令的 [可用性注意事項](/zh-TW/commands#all-commands)。{/* min-version: 2.1.181 */}若要從 `-p` 叫用變更設定，請將 `key=value` 傳遞至 `/config`，例如 `/config thinking=false`。

238</Note>244</Note>

239 245

240<h3 id="customize-the-system-prompt">246<h3 id="customize-the-system-prompt">

hooks.md +20 −14

Details

164Hooks 在 JSON 設定檔中定義。配置有三個嵌套層級：164Hooks 在 JSON 設定檔中定義。配置有三個嵌套層級：

165 165

1661. 選擇要回應的 [hook 事件](#hook-events)，例如 `PreToolUse` 或 `Stop`1661. 選擇要回應的 [hook 事件](#hook-events)，例如 `PreToolUse` 或 `Stop`

1672. 新增 [匹配器群組](#matcher-patterns) 以篩選何時觸發，例如'僅針對 Bash 工具'1672. 新增 [匹配器群組](#matcher-patterns) 以篩選何時觸發，例如「僅針對 Bash 工具」

1683. 定義一個或多個 [hook 處理程式](#hook-handler-fields) 以在匹配時執行1683. 定義一個或多個 [hook 處理程式](#hook-handler-fields) 以在匹配時執行

169 169

170有關完整的逐步說明和註解範例，請參閱上面的 [Hook 如何解析](#how-a-hook-resolves)。170有關完整的逐步說明和註解範例，請參閱上面的 [Hook 如何解析](#how-a-hook-resolves)。

280 280

281精確匹配集中的連字號需要 Claude Code v2.1.195 或更新版本。在較早的版本上，像 `mcp__brave-search` 這樣的裸連字號前綴被評估為未錨定的正規表達式，並匹配來自該伺服器的每個工具。`mcp__brave-search__.*` 形式在每個版本上都有效。281精確匹配集中的連字號需要 Claude Code v2.1.195 或更新版本。在較早的版本上，像 `mcp__brave-search` 這樣的裸連字號前綴被評估為未錨定的正規表達式，並匹配來自該伺服器的每個工具。`mcp__brave-search__.*` 形式在每個版本上都有效。

282 282

283來自 [plugin-bundled MCP server](/zh-TW/mcp#plugin-provided-mcp-servers) 的工具使用包含外掛程式名稱的範圍伺服器段：`mcp__plugin_<plugin-name>_<server-name>__<tool>`。針對裸伺服器金鑰編寫的匹配器永遠不會針對這些工具觸發。對於名為 `my-plugin` 的外掛程式，在金鑰 `db` 下打包伺服器，`query` 工具顯示為 `mcp__plugin_my-plugin_db__query`，因此來自該伺服器的每個工具的匹配器是 `mcp__plugin_my-plugin_db__.*`。在處理程式的 [`if` 欄位](#common-fields) 中使用相同的範圍工具名稱。請參閱 [Plugin-provided MCP servers](/zh-TW/mcp#plugin-provided-mcp-servers) 以了解如何建立範圍名稱。

284

283此範例記錄所有 memory 伺服器操作並驗證來自任何 MCP 伺服器的寫入操作：285此範例記錄所有 memory 伺服器操作並驗證來自任何 MCP 伺服器的寫入操作：

284 286

285```json theme={null}287```json theme={null}

456除了 [通用欄位](#common-fields) 外，MCP 工具 hooks 還接受這些欄位：458除了 [通用欄位](#common-fields) 外，MCP 工具 hooks 還接受這些欄位：

457 459

458| 欄位 | 必需 | 描述 |460| 欄位 | 必需 | 描述 |

459| :------- | :- | :------------------------------------------------------------------------------------------------------ |461| :------- | :- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

460| `server` | 是 | 已配置的 MCP 伺服器的名稱。伺服器必須已連接；hook 永遠不會觸發 OAuth 或連接流程 |462| `server` | 是 | 已配置的 MCP 伺服器的名稱。對於 [plugin-bundled server](/zh-TW/mcp#plugin-provided-mcp-servers)，這是範圍名稱 `plugin:<plugin-name>:<server-name>`，例如 `plugin:my-plugin:db`，而不是裸伺服器金鑰。伺服器必須已連接；hook 永遠不會觸發 OAuth 或連接流程 |

461| `tool` | 是 | 該伺服器上要呼叫的工具名稱 |463| `tool` | 是 | 該伺服器上要呼叫的工具名稱 |

462| `input` | 否 | 傳遞給工具的參數。字串值支援來自 hook 的 [JSON 輸入](#hook-input-and-output) 的 `${path}` 替換，例如 `"${tool_input.file_path}"` |464| `input` | 否 | 傳遞給工具的參數。字串值支援來自 hook 的 [JSON 輸入](#hook-input-and-output) 的 `${path}` 替換，例如 `"${tool_input.file_path}"` |

463 465

638| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |640| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

640| `prompt_id` | UUID 識別目前正在處理的使用者提示。與 [OpenTelemetry 事件上的 `prompt.id` 屬性](/zh-TW/monitoring-usage#event-correlation-attributes) 相符，因此您可以將 hook 輸出與單一提示的遙測相關聯。在第一個使用者輸入之前不存在。{/* min-version: 2.1.196 */}需要 Claude Code v2.1.196 或更新版本 |642| `prompt_id` | UUID 識別目前正在處理的使用者提示。與 [OpenTelemetry 事件上的 `prompt.id` 屬性](/zh-TW/monitoring-usage#event-correlation-attributes) 相符，因此您可以將 hook 輸出與單一提示的遙測相關聯。在第一個使用者輸入之前不存在。{/* min-version: 2.1.196 */}需要 Claude Code v2.1.196 或更新版本 |

642| `cwd` | 叫用 hook 時的目前工作目錄 |644| `cwd` | 叫用 hook 時的目前工作目錄 |

643| `permission_mode` | 目前 [權限模式](/zh-TW/permissions#permission-modes)：`"default"`、`"plan"`、`"acceptEdits"`、`"auto"`、`"dontAsk"` 或 `"bypassPermissions"`。並非所有事件都接收此欄位：請參閱下面每個事件的 JSON 範例以檢查 |645| `permission_mode` | 目前 [權限模式](/zh-TW/permissions#permission-modes)：`"default"`、`"plan"`、`"acceptEdits"`、`"auto"`、`"dontAsk"` 或 `"bypassPermissions"`。標記為**手動**的模式以 `"default"` 到達，永遠不會以 `"manual"` 到達，因此匹配 `"default"` 的指令碼繼續工作。並非所有事件都接收此欄位。檢查每個 [hook 事件](#hook-events) 部分中的 JSON 範例 |

644| `effort` | 物件，其 `level` 欄位保存該回合的活躍 [努力等級](/zh-TW/model-config#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。如果請求的模型努力等級超過目前模型支援的等級，這是模型實際使用的降級等級。Ultracode 不是一個不同的等級，報告為 `"xhigh"`。該物件與 [狀態行](/zh-TW/statusline#available-data) `effort` 欄位相符。存在於在工具使用上下文中觸發的事件，例如 `PreToolUse`、`PostToolUse`、`Stop` 和 `SubagentStop`，當目前模型支援努力參數時。該等級也可作為 `$CLAUDE_EFFORT` 環境變數提供給 hook 命令和 Bash 工具。 |646| `effort` | 物件，其 `level` 欄位保存該回合的活躍 [努力等級](/zh-TW/model-config#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。如果請求的模型努力等級超過目前模型支援的等級，這是模型實際使用的降級等級。Ultracode 不是一個不同的等級，報告為 `"xhigh"`。該物件與 [狀態行](/zh-TW/statusline#available-data) `effort` 欄位相符。存在於在工具使用上下文中觸發的事件，例如 `PreToolUse`、`PostToolUse`、`Stop` 和 `SubagentStop`，當目前模型支援努力參數時。該等級也可作為 `$CLAUDE_EFFORT` 環境變數提供給 hook 命令和 Bash 工具。 |

646 648

1079 Setup1081 Setup

1080</h3>1082</h3>

1081 1083

1082僅當您使用 `--init-only` 啟動 Claude Code，或在列印模式（`-p`）中使用 `--init` 或 `--maintenance` 時觸發。它在正常啟動時不觸發。使用它進行一次性依賴項安裝或您從 CI 或指令碼明確觸發的計劃清理，與正常工作階段啟動分開。對於每個工作階段的初始化，請改用 [SessionStart](#sessionstart)。1084僅當您使用 `--init-only` 啟動 Claude Code，或在非互動模式（`-p`）中使用 `--init` 或 `--maintenance` 時觸發。它在正常啟動時不觸發。使用它進行一次性依賴項安裝或您從 CI 或指令碼明確觸發的計劃清理，與正常工作階段啟動分開。對於每個工作階段的初始化，請改用 [SessionStart](#sessionstart)。

1083 1085

1084匹配器值對應於觸發 hook 的 CLI 標誌：1086匹配器值對應於觸發 hook 的 CLI 標誌：

1085 1087

1090 1092

1091`--init-only` 執行 Setup hooks 和 SessionStart hooks（帶有 `startup` 匹配器），然後退出而不啟動對話。`--init` 和 `--maintenance` 僅在與 `-p`（列印模式）結合時觸發 Setup hooks；在互動式工作階段中，這兩個標誌目前不觸發 Setup hooks。1093`--init-only` 執行 Setup hooks 和 SessionStart hooks（帶有 `startup` 匹配器），然後退出而不啟動對話。`--init` 和 `--maintenance` 僅在與 `-p` 結合時觸發 Setup hooks；在互動式工作階段中，這兩個標誌目前不觸發 Setup hooks。

1092 1094

1093因為 Setup 不在每次啟動時觸發，需要安裝依賴項的外掛程式無法僅依賴 Setup。實際的模式是在首次使用時檢查依賴項，如果缺失則安裝，例如測試 `${CLAUDE_PLUGIN_DATA}/node_modules` 的 hook 或 skill，如果不存在則執行 `npm install`。請參閱 [持久資料目錄](/zh-TW/plugins-reference#persistent-data-directory) 以了解在何處儲存已安裝的依賴項。1095因為 Setup 不在每次啟動時觸發，需要安裝依賴項的外掛程式無法僅依賴 Setup。實際的模式是在首次使用時檢查依賴項，如果缺失則安裝，例如測試 `${CLAUDE_PLUGIN_DATA}/node_modules` 的 hook 或 skill，如果不存在則執行 `npm install`。請參閱 [持久資料目錄](/zh-TW/plugins-reference#persistent-data-directory) 以了解在何處儲存已安裝的依賴項。

1094 1096

1591 ExitPlanMode1593 ExitPlanMode

1592</h5>1594</h5>

1593 1595

1594呈現一個計劃並要求使用者在 Claude 離開 [plan mode](/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 之前批准它。Claude 在呼叫工具之前將計劃寫入磁碟上的檔案，因此模型的字面 `tool_input` 僅攜帶 `allowedPrompts`。Claude Code 在將輸入傳遞給 hooks 之前注入計劃內容和檔案路徑。1596呈現一個計劃並要求使用者在 Claude 離開 [plan mode](/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 之前批准它。Claude 在呼叫工具之前將計劃寫入磁碟上的檔案，因此模型的字面 `tool_input` 通常為空。Claude Code 在將輸入傳遞給 hooks 之前注入計劃內容和檔案路徑。

1595 1597

1596| 欄位 | 類型 | 範例 | 描述 |1598| 欄位 | 類型 | 範例 | 描述 |

1597| :--------------- | :- | :------------------------------------------ | :------------------------------------------------------- |1599| :--------------- | :- | :------------------------------------------ | :-------------------------------------------------------------------------------------------- |

1600| `allowedPrompts` | 陣列 | `[{"tool": "Bash", "prompt": "run tests"}]` | 可選。Claude 要求實施計劃的基於提示的權限，每個都有 `tool` 名稱和描述操作類別的 `prompt` |1602| `allowedPrompts` | 陣列 | `[{"tool": "Bash", "prompt": "run tests"}]` | {/* min-version: 2.1.205 */}已棄用。Claude Code 接受該欄位但忽略它。在 v2.1.205 之前，它攜帶 Claude 要求實施計劃的基於提示的權限 |

1601 1603

1602在 `PostToolUse` 中，`tool_response` 是一個物件，其中包含 `plan` 和 `filePath` 欄位，保存批准的計劃，加上內部狀態標誌。讀取 `tool_response.plan` 以獲取計劃內容，而不是從磁碟重新讀取檔案。1604在 `PostToolUse` 中，`tool_response` 是一個物件，其中包含 `plan` 和 `filePath` 欄位，保存批准的計劃，加上內部狀態標誌。讀取 `tool_response.plan` 以獲取計劃內容，而不是從磁碟重新讀取檔案。

1603 1605

1756`updatedPermissions` 輸出欄位和 [`permission_suggestions` 輸入欄位](#permissionrequest-input) 都使用相同的項目物件陣列。每個項目都有一個 `type` 決定其他欄位，以及一個 `destination` 控制變更寫入位置。1758`updatedPermissions` 輸出欄位和 [`permission_suggestions` 輸入欄位](#permissionrequest-input) 都使用相同的項目物件陣列。每個項目都有一個 `type` 決定其他欄位，以及一個 `destination` 控制變更寫入位置。

1757 1759

1758| `type` | 欄位 | 效果 |1760| `type` | 欄位 | 效果 |

1759| :------------------ | :------------------------------- | :------------------------------------------------------------------------------------------------------------------- |1761| :------------------ | :------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1760| `addRules` | `rules`、`behavior`、`destination` | 新增權限規則。`rules` 是 `{toolName, ruleContent?}` 物件的陣列。省略 `ruleContent` 以匹配整個工具。`behavior` 是 `"allow"`、`"deny"` 或 `"ask"` |1762| `addRules` | `rules`、`behavior`、`destination` | 新增權限規則。`rules` 是 `{toolName, ruleContent?}` 物件的陣列。省略 `ruleContent` 以匹配整個工具。`behavior` 是 `"allow"`、`"deny"` 或 `"ask"` |

1763| `setMode` | `mode`、`destination` | 變更權限模式。有效模式為 `default`、`auto`、`acceptEdits`、`dontAsk`、`bypassPermissions` 和 `plan` |1765| `setMode` | `mode`、`destination` | 變更權限模式。有效模式為 `default`、`auto`、`acceptEdits`、`dontAsk`、`bypassPermissions`、`plan` 和 {/* min-version: 2.1.200 */}`manual` 作為 `default` 的別名。`manual` 別名需要 Claude Code v2.1.200 或更高版本 |

1766 1768

2648 2650

2649因為 hook 完全替換預設行為，[`.worktreeinclude`](/zh-TW/worktrees#copy-gitignored-files-into-worktrees) 不被處理。如果您需要將本機配置檔案（如 `.env`）複製到新 worktree，請在您的 hook 指令碼內執行。2651因為 hook 完全替換預設行為，[`.worktreeinclude`](/zh-TW/worktrees#copy-gitignored-files-into-worktrees) 不被處理。如果您需要將本機配置檔案（如 `.env`）複製到新 worktree，請在您的 hook 指令碼內執行。

2650 2652

2651Hook 必須返回建立的 worktree 目錄的絕對路徑。Claude Code 使用此路徑作為隔離工作階段的工作目錄。命令 hooks 在 stdout 上列印它；HTTP hooks 通過 `hookSpecificOutput.worktreePath` 返回它。2653Hook 必須返回建立的 worktree 目錄的絕對路徑。Claude Code 使用此路徑作為隔離工作階段的工作目錄。請參閱 [WorktreeCreate 輸出](#worktreecreate-output) 以了解每個 hook 類型如何返回路徑。

2652 2654

2653此範例建立 SVN 工作副本並列印路徑供 Claude Code 使用。將儲存庫 URL 替換為您自己的：2655此範例建立 SVN 工作副本並列印路徑供 Claude Code 使用。將儲存庫 URL 替換為您自己的：

2654 2656

2693 2695

2694WorktreeCreate hooks 不使用標準的允許/阻止決定模型。相反，hook 的成功或失敗決定結果。Hook 必須返回建立的 worktree 目錄的絕對路徑：2696WorktreeCreate hooks 不使用標準的允許/阻止決定模型。相反，hook 的成功或失敗決定結果。Hook 必須返回建立的 worktree 目錄的絕對路徑：

2695 2697

2696* **命令 hooks**（`type: "command"`）：在 stdout 上列印路徑。2698* **命令 hooks**（`type: "command"`）：在 stdout 上列印路徑。Claude Code 在讀取該行之前去除 ANSI 逃逸代碼，因此在您的 `echo` 之前列印的 shell 啟動橫幅被忽略。將任何其他 hook 輸出重定向到 stderr。

2697* **HTTP hooks**（`type: "http"`）：在回應正文中返回 `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }`。2699* **HTTP hooks**（`type: "http"`）：在回應正文中返回 `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }`。

2698 2700

2699如果 hook 失敗或不產生路徑，worktree 建立失敗並出現錯誤。2701如果 hook 失敗或不產生路徑，worktree 建立失敗並出現錯誤。

2700 2702

2703Claude Code 根據 hook 執行的目錄解析相對路徑。如果結果路徑不是 Claude Code 可以進入的目錄，工作階段列印一個命名路徑的錯誤並以代碼 1 退出。在 v2.1.205 之前，相對路徑或磁碟上不存在的路徑會在啟動時使工作階段崩潰，使用 `-p` 時會停滯約 30 秒，然後以代碼 0 退出。

2704

2701<h3 id="worktreeremove">2705<h3 id="worktreeremove">

2702 WorktreeRemove2706 WorktreeRemove

2703</h3>2707</h3>

3217 3221

3218背景程序退出後，如果 hook 產生了帶有 `additionalContext` 欄位的 JSON 回應，該內容會在下一個對話輪次上作為上下文傳遞給 Claude。`systemMessage` 欄位會顯示給你，而不是 Claude。3222背景程序退出後，如果 hook 產生了帶有 `additionalContext` 欄位的 JSON 回應，該內容會在下一個對話輪次上作為上下文傳遞給 Claude。`systemMessage` 欄位會顯示給你，而不是 Claude。

3219 3223

3224Claude Code 驗證該 JSON 回應是否符合與同步 hooks 相同的[輸出結構](#json-output)，並捨棄任何值類型錯誤的欄位，例如不是字串的 `systemMessage`，而不是傳遞它。使用 `--debug` 執行以查看命名每個捨棄欄位的警告。在 v2.1.202 之前，來自非同步 hook 的格式不正確的 JSON 輸出可能會導致工作階段崩潰，每次恢復工作階段時都會重複發生崩潰。

3225

3220非同步 hook 完成通知預設被抑制。要查看它們，請使用 `Ctrl+O` 啟用詳細模式或使用 `--verbose` 啟動 Claude Code。3226非同步 hook 完成通知預設被抑制。要查看它們，請使用 `Ctrl+O` 啟用詳細模式或使用 `--verbose` 啟動 Claude Code。

3221 3227

3222<h3 id="run-tests-after-file-changes">3228<h3 id="run-tests-after-file-changes">

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

Details

186 186

187按 `Shift+Tab` 循環通過許可模式：187按 `Shift+Tab` 循環通過許可模式：

188 188

189* **預設**：Claude 在檔案編輯和 shell 命令之前詢問189* **Manual**：Claude 在檔案編輯和 shell 命令之前詢問

190* **自動接受編輯**：Claude 編輯檔案並執行常見的檔案系統命令（如 `mkdir` 和 `mv`）而不詢問，仍然詢問其他命令190* **Accept edits**：Claude 編輯檔案並執行常見的檔案系統命令（如 `mkdir` 和 `mv`）而不詢問，仍然詢問其他命令

191* **Plan Mode**：Claude 探索並提出計畫而不編輯您的原始檔案；許可提示仍然如預設模式一樣適用191* **Plan**：Claude 探索並提出計畫而不編輯您的原始檔案；許可提示仍然如 Manual 模式一樣適用

192* **Auto mode**：Claude 使用背景安全檢查評估所有操作。目前是研究預覽192* **Auto**：Claude 使用背景安全檢查評估所有操作。目前是研究預覽

193 193

194您也可以在 `.claude/settings.json` 中允許特定命令，以便 Claude 不會每次都詢問。這對於受信任的命令（如 `npm test` 或 `git status`）很有用。設定可以從組織範圍的政策範圍到個人偏好。請參閱[許可](/zh-TW/permissions)以取得詳細資訊。194您也可以在 `.claude/settings.json` 中允許特定命令，以便 Claude 不會每次都詢問。這對於受信任的命令（如 `npm test` 或 `git status`）很有用。設定可以從組織範圍的政策範圍到個人偏好。請參閱[許可](/zh-TW/permissions)以取得詳細資訊。

195 195

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

211 211

212* `/init` 引導您為您的專案建立 CLAUDE.md212* `/init` 引導您為您的專案建立 CLAUDE.md

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

214 214

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

216 這是一個對話216 這是一個對話

interactive-mode.md +5 −3

Details

27</h3>27</h3>

28 28

29| 快捷鍵 | 說明 | 上下文 |29| 快捷鍵 | 說明 | 上下文 |

30| :------------------------------------------------- | :-------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------- |30| :------------------------------------------------- | :-------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- |

42| `Up/Down arrows` 或 `Ctrl+P`/`Ctrl+N` | 移動游標或導航命令歷史 | 當輸入跨越多個視覺行時，無論是換行還是多行，首先在提示內移動游標。一旦游標已在第一個或最後一個視覺行，再次按下會導航命令歷史。{/* min-version: 2.1.169 */}自 v2.1.169 起，換行的單行輸入行為與多行相同 |42| `Up/Down arrows` 或 `Ctrl+P`/`Ctrl+N` | 移動游標或導航命令歷史 | 當輸入跨越多個視覺行時，無論是換行還是多行，首先在提示內移動游標。一旦游標已在第一個或最後一個視覺行，再次按下會導航命令歷史。{/* min-version: 2.1.169 */}自 v2.1.169 起，換行的單行輸入行為與多行相同 |

43| `Esc` | 中斷 Claude | 停止目前回應或工具呼叫中途，以便您可以重新導向。Claude 會保留迄今為止完成的工作 |43| `Esc` | 中斷 Claude，或關閉對話框 | 停止目前回應或工具呼叫中途，以便您可以重新導向。Claude 會保留迄今為止完成的工作。當對話框（例如權限提示）開啟時，`Esc` 會關閉對話框，而不是中斷 Claude。{/* min-version: 2.1.202 */}在 v2.1.202 之前，某些對話框上的 `Esc` 會中斷 Claude 並保持對話框開啟 |

47| `Option+T`（macOS）或 `Alt+T`（Windows/Linux） | 切換擴展思考 | 啟用或停用擴展思考模式。在 Fable 5 上無效，其始終使用擴展思考。{/* min-version: 2.1.132 */}自 v2.1.132 起，此快捷鍵在 macOS 上無需配置 Option 為 Meta 即可運作 |47| `Option+T`（macOS）或 `Alt+T`（Windows/Linux） | 切換擴展思考 | 啟用或停用擴展思考模式。在 Fable 5 上無效，其始終使用擴展思考。{/* min-version: 2.1.132 */}自 v2.1.132 起，此快捷鍵在 macOS 上無需配置 Option 為 Meta 即可運作 |

270 270

271搜尋會載入所選範圍中最近的 100 個唯一提示，重複項目會摺疊至最新出現。匹配的提示會顯示醒目提示的搜尋詞，因此您可以找到並重複使用先前的輸入。271搜尋會載入所選範圍中最近的 100 個唯一提示，重複項目會摺疊至最新出現。匹配的提示會顯示醒目提示的搜尋詞，因此您可以找到並重複使用先前的輸入。

272 272

273接受匹配項或取消搜尋會立即生效，即使 Claude Code 仍在載入歷史時也是如此。在 v2.1.202 之前，在該載入期間接受或取消可能會報告內部錯誤。

274

273<h2 id="background-bash-commands">275<h2 id="background-bash-commands">

274 背景 Bash 命令276 背景 Bash 命令

275</h2>277</h2>

keybindings.md +12 −13

Details

71| `Select` | 通用選擇/清單元件 |71| `Select` | 通用選擇/清單元件 |

72| `Plugin` | Plugin 對話框（瀏覽、探索、管理） |72| `Plugin` | Plugin 對話框（瀏覽、探索、管理） |

73| `Scroll` | 對話滾動和全螢幕模式中的文字選擇 |73| `Scroll` | 對話滾動和全螢幕模式中的文字選擇 |

~~74| `Doctor` | `/doctor` 診斷螢幕 |~~74

75{/* max-version: 2.1.204 */}在 v2.1.205 之前，`/doctor` 診斷螢幕存在 `Doctor` 上下文和 `doctor:fix` 動作。

75 76

76<h2 id="available-actions">77<h2 id="available-actions">

77 可用動作78 可用動作

358 359

359<h3 id="doctor-actions">

360 Doctor 動作

361</h3>

~~362~~

363在 `Doctor` 上下文中可用的動作：

~~364~~

365| 動作 | 預設值 | 說明 |

366| :----------- | :-- | :--------------------------------- |

367| `doctor:fix` | F | 將診斷報告傳送給 Claude 以修復報告的問題。僅在發現問題時有效 |

~~368~~

369<h3 id="voice-actions">360<h3 id="voice-actions">

370 語音動作361 語音動作

371</h3>362</h3>

477}468}

478```469```

479 470

480這也適用於和弦繫結。取消繫結共享前綴的每個和弦會釋放該前綴以用作單一鍵繫結：471這也適用於和弦繫結。取消繫結共享前綴的每個和弦會釋放該前綴以用作單一鍵繫結。任何作用中的內容中的和弦會保留其前綴的保留狀態，因此您必須在定義該和弦的內容中取消繫結每個和弦。

472

473預設的 `Ctrl+X` 系列跨越兩個內容：`Chat` 中的 `ctrl+x ctrl+k` 和 `ctrl+x ctrl+e`，以及 `Task` 中的 `ctrl+x ctrl+b`。若要將 `ctrl+x` 本身回收為單一鍵繫結，請取消繫結所有這些：

481 474

482```json theme={null}475```json theme={null}

483{476{

484 "bindings": [477 "bindings": [

478 {

479 "context": "Task",

480 "bindings": {

481 "ctrl+x ctrl+b": null

482 }

483 },

485 {484 {

486 "context": "Chat",485 "context": "Chat",

487 "bindings": {486 "bindings": {

546* 終端機多工器衝突545* 終端機多工器衝突

547* 同一上下文中的重複繫結546* 同一上下文中的重複繫結

548 547

549執行 `/doctor` 以查看任何快捷鍵警告。548Claude Code 在檔案載入時報告警告，並將每個警告寫入偵錯日誌。使用 [`--debug`](/zh-TW/cli-reference#cli-flags) 啟動 Claude Code 以查看詳細資訊。

legal-and-compliance.md +1 −1

Details

23 商業協議23 商業協議

24</h3>24</h3>

25 25

26無論您是直接使用 Claude API（1P）還是通過 Amazon Bedrock 或 Google Vertex（3P）存取，您現有的商業協議將適用於 Claude Code 使用，除非我們已相互同意另行安排。26無論您是直接使用 Claude API（1P）還是通過 Amazon Bedrock 或 Google Cloud 的 Agent Platform（3P）存取，您現有的商業協議將適用於 Claude Code 使用，除非我們已相互同意另行安排。

27 27

28<h2 id="compliance">28<h2 id="compliance">

29 合規29 合規

llm-gateway-connect.md +8 −6

Details

209 桌面應用程式209 桌面應用程式

210</h3>210</h3>

211 211

212桌面應用程式從[管理員分發的配置](https://claude.com/docs/cowork/3p/gateway)讀取閘道路由，而不是從 `ANTHROPIC_BASE_URL` 或 `settings.json`。如果您的組織已分發它，桌面應用程式通過閘道路由，無需您進行任何設定；如果沒有，請使用終端 CLI 或 VS Code 擴充功能進行閘道會話。管理員按照[組織推出](/zh-TW/llm-gateway-rollout#distribute-through-managed-settings)中所述分發配置。212桌面應用程式從[管理員分發的配置](https://claude.com/docs/third-party/claude-desktop/gateway)讀取閘道路由，而不是從 `ANTHROPIC_BASE_URL` 或 `settings.json`。如果您的組織已分發它，桌面應用程式通過閘道路由，無需您進行任何設定；如果沒有，請使用終端 CLI 或 VS Code 擴充功能進行閘道會話。管理員按照[組織推出](/zh-TW/llm-gateway-rollout#distribute-through-managed-settings)中所述分發配置。

213 213

214如果桌面應用程式顯示 `Gateway was unreachable`，應用程式在啟動時無法到達配置的基礎 URL；使用上面的 [curl 測試](#verify-the-connection)檢查 URL 和網路路徑。214如果桌面應用程式顯示 `Gateway was unreachable`，應用程式在啟動時無法到達配置的基礎 URL；使用上面的 [curl 測試](#verify-the-connection)檢查 URL 和網路路徑。

215 215

287 287

288[遠端控制](/zh-TW/remote-control)和[語音聽寫](/zh-TW/voice-dictation)都依賴於 claude.ai 身份：遠端控制將實時會話與您的帳戶配對，語音聽寫到達 claude.ai 轉錄端點。當 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 處於活動狀態時，它們不可用。{/* min-version: 2.1.196 */}自 v2.1.196 起，當 `ANTHROPIC_BASE_URL` 指向非 Anthropic 主機時，遠端控制也被禁用，因此僅使用 claude.ai 登入本身是不夠的。288[遠端控制](/zh-TW/remote-control)和[語音聽寫](/zh-TW/voice-dictation)都依賴於 claude.ai 身份：遠端控制將實時會話與您的帳戶配對，語音聽寫到達 claude.ai 轉錄端點。當 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 處於活動狀態時，它們不可用。{/* min-version: 2.1.196 */}自 v2.1.196 起，當 `ANTHROPIC_BASE_URL` 指向非 Anthropic 主機時，遠端控制也被禁用，因此僅使用 claude.ai 登入本身是不夠的。

289 289

290若要還原任一功能，請使用 claude.ai 登入並取消設定它檢查的閘道變數。`/doctor` 命名要取消設定的認證變數。290若要還原任一功能，請使用 claude.ai 登入並取消設定它檢查的閘道變數。`claude doctor` 的遠端控制部分命名要取消設定的認證變數。

291 291

292* 語音聽寫：取消設定閘道認證292* 語音聽寫：取消設定閘道認證

293* 遠端控制：取消設定閘道認證和 `ANTHROPIC_BASE_URL`293* 遠端控制：取消設定閘道認證和 `ANTHROPIC_BASE_URL`

393 通過閘道路由到雲端提供者393 通過閘道路由到雲端提供者

394</h3>394</h3>

395 395

396這些配置使用提供者特定的基礎 URL 變數代替 `ANTHROPIC_BASE_URL` 將 Claude Code 指向通過閘道的雲端提供者。Bedrock 和 Agent Platform 閘道接受這些提供者的本機請求格式；Foundry 和 AWS 上的 Claude Platform 閘道接受 Anthropic Messages 格式，僅在哪個基礎 URL 變數到達它們方面有所不同。396這些配置使用提供者特定的基礎 URL 變數代替 `ANTHROPIC_BASE_URL` 將 Claude Code 指向通過閘道的雲端提供者。Amazon Bedrock 和 Google Cloud 的 Agent Platform 閘道接受這些提供者的本機請求格式；Microsoft Foundry 和 AWS 上的 Claude Platform 閘道接受 Anthropic Messages 格式，僅在哪個基礎 URL 變數到達它們方面有所不同。

397 397

398僅在您的閘道團隊特別命名 Bedrock、Agent Platform、Foundry 或 AWS 上的 Claude Platform 時使用一個。如果上面的[驗證請求](#verify-the-connection)返回 JSON，您可以跳過本部分。398僅在您的閘道團隊特別命名 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 AWS 上的 Claude Platform 時使用一個。如果上面的[驗證請求](#verify-the-connection)返回 JSON，您可以跳過本部分。

399 399

400為您的閘道團隊命名的提供者設定區塊。跳過身份驗證變數告訴 Claude Code 不要使用提供者認證簽署請求，因為閘道持有這些。如果閘道需要自己的令牌，請在區塊後添加 `ANTHROPIC_AUTH_TOKEN`，除了 Foundry，它使用 `ANTHROPIC_FOUNDRY_API_KEY`，如所示。400為您的閘道團隊命名的提供者設定區塊。跳過身份驗證變數告訴 Claude Code 不要使用提供者認證簽署請求，因為閘道持有這些。如果閘道需要自己的令牌，請在區塊後添加 `ANTHROPIC_AUTH_TOKEN`，除了 Microsoft Foundry，它使用 `ANTHROPIC_FOUNDRY_API_KEY`，如所示。{/* min-version: 2.1.203 */}期望持有人令牌的 Microsoft Foundry 閘道可以改用 [`ANTHROPIC_FOUNDRY_AUTH_TOKEN`](/zh-TW/env-vars)；當兩者都設定時，它優先於 `ANTHROPIC_FOUNDRY_API_KEY`。`ANTHROPIC_FOUNDRY_AUTH_TOKEN` 需要 Claude Code v2.1.203 或更高版本。

401 401

402<h4 id="amazon-bedrock">402<h4 id="amazon-bedrock">

403 Amazon Bedrock403 Amazon Bedrock

451 Microsoft Foundry451 Microsoft Foundry

452</h4>452</h4>

453 453

454將閘道的認證放在 `ANTHROPIC_FOUNDRY_API_KEY` 中；它作為 `x-api-key` 標頭發送到閘道。`CLAUDE_CODE_SKIP_FOUNDRY_AUTH` 在這裡不適用：沒有 API 金鑰，Foundry 客戶端在它離開機器之前會使每個請求失敗。454將閘道的認證放在 `ANTHROPIC_FOUNDRY_API_KEY` 中；它作為 `x-api-key` 標頭發送到閘道。{/* min-version: 2.1.203 */}期望持有人令牌的閘道可以改用 [`ANTHROPIC_FOUNDRY_AUTH_TOKEN`](/zh-TW/env-vars)。Claude Code 將該值作為 `Authorization: Bearer` 標頭發送，當兩者都設定時，它優先於 `ANTHROPIC_FOUNDRY_API_KEY`。需要 Claude Code v2.1.203 或更高版本。

455

456對於注入自己的 `Authorization` 標頭的閘道，設定 `CLAUDE_CODE_SKIP_FOUNDRY_AUTH=1` 並將兩個認證變數都保留為未設定。Claude Code 然後發送沒有 Azure 認證的請求，並保留您提供的 `Authorization` 標頭，例如通過 `ANTHROPIC_CUSTOM_HEADERS`。{/* min-version: 2.1.203 */}在 v2.1.203 之前，`CLAUDE_CODE_SKIP_FOUNDRY_AUTH` 沒有 API 金鑰使 Microsoft Foundry 客戶端無法發送請求。

455 457

456<Tabs>458<Tabs>

457 <Tab title="Bash or Zsh">459 <Tab title="Bash or Zsh">

llm-gateway-protocol.md +13 −13

Details

34 API 格式34 API 格式

35</h2>35</h2>

36 36

37Gateway 必須向 Claude Code 用戶端公開以下至少一種 API 格式。Claude Code 使用哪種格式由用戶端的配置決定：下表「選擇者」欄中的變數指向您的 gateway 使用該格式。Agent Platform 是 Google Cloud 的 Claude 端點，前身為 Vertex AI；其變數名稱保留 `VERTEX` 拼寫。37Gateway 必須向 Claude Code 用戶端公開以下至少一種 API 格式。Claude Code 使用哪種格式由用戶端的配置決定：下表「選擇者」欄中的變數指向您的 gateway 使用該格式。Google Cloud 的 Agent Platform 是 Google Cloud 的 Claude 端點，前身為 Vertex AI；其變數名稱保留 `VERTEX` 拼寫。

38 38

39| 格式 | 選擇者 | 端點 | 轉發不變 |39| 格式 | 選擇者 | 端點 | 轉發不變 |

40| :------------------------ | :---------------------------------------------------------- | :------------------------------------------------------------------- | :----------------------------------------------------------------------- |40| :--------------------------------------- | :---------------------------------------------------------- | :------------------------------------------------------------------- | :----------------------------------------------------------------------- |

42| Bedrock InvokeModel | `ANTHROPIC_BEDROCK_BASE_URL` 搭配 `CLAUDE_CODE_USE_BEDROCK=1` | `/model/{model}/invoke`、`/model/{model}/invoke-with-response-stream` | `anthropic_beta` 和 `anthropic_version` 請求體欄位 |42| Amazon Bedrock InvokeModel | `ANTHROPIC_BEDROCK_BASE_URL` 搭配 `CLAUDE_CODE_USE_BEDROCK=1` | `/model/{model}/invoke`、`/model/{model}/invoke-with-response-stream` | `anthropic_beta` 和 `anthropic_version` 請求體欄位 |

43| Agent Platform rawPredict | `ANTHROPIC_VERTEX_BASE_URL` 搭配 `CLAUDE_CODE_USE_VERTEX=1` | `:rawPredict`、`:streamRawPredict`、`count-tokens:rawPredict`（可選） | `anthropic-beta` 和 `anthropic-version` 請求標頭，以及 `anthropic_version` 請求體欄位 |43| Google Cloud 的 Agent Platform rawPredict | `ANTHROPIC_VERTEX_BASE_URL` 搭配 `CLAUDE_CODE_USE_VERTEX=1` | `:rawPredict`、`:streamRawPredict`、`count-tokens:rawPredict`（可選） | `anthropic-beta` 和 `anthropic-version` 請求標頭，以及 `anthropic_version` 請求體欄位 |

44 44

45<h3 id="foundry-and-claude-platform-on-aws">45<h3 id="foundry-and-claude-platform-on-aws">

46 Foundry 和 AWS 上的 Claude Platform46 Foundry 和 AWS 上的 Claude Platform

52 可選端點和啟動流量52 可選端點和啟動流量

53</h3>53</h3>

54 54

55令牌計數端點是唯一可選的：當它們不存在時，Claude Code 會在本地估計上下文使用情況。推理請求發佈到 `/v1/messages?beta=true`，因此請匹配路徑，而不是完整 URL。Agent Platform 方法後綴附加到發佈者模型路徑，如 `/projects/{project}/locations/{location}/publishers/anthropic/models/{model}:streamRawPredict`。55令牌計數端點是唯一可選的：當它們不存在時，Claude Code 會在本地估計上下文使用情況。推理請求發佈到 `/v1/messages?beta=true`，因此請匹配路徑，而不是完整 URL。Google Cloud 的 Agent Platform 方法後綴附加到發佈者模型路徑，如 `/projects/{project}/locations/{location}/publishers/anthropic/models/{model}:streamRawPredict`。

56 56

57Gateway 也會看到最佳努力的啟動流量，它可以拒絕而不會破壞任何東西：一個 `HEAD /` 連接探測，以及在 Bedrock 格式 gateway 上的 `GET /inference-profiles?type=SYSTEM_DEFINED` 請求。57Gateway 也會看到最佳努力的啟動流量，它可以拒絕而不會破壞任何東西：一個 `HEAD /` 連接探測，以及在 Amazon Bedrock 格式 gateway 上的 `GET /inference-profiles?type=SYSTEM_DEFINED` 請求。

58 58

59<h3 id="streaming">59<h3 id="streaming">

60 串流60 串流

68 68

69用戶端使用的格式決定了您的 gateway 接收的內容。常見的失敗模式是用戶端發送給您的 gateway 的格式與其後面的上游提供者接受的格式不匹配。69用戶端使用的格式決定了您的 gateway 接收的內容。常見的失敗模式是用戶端發送給您的 gateway 的格式與其後面的上游提供者接受的格式不匹配。

70 70

~~71* 當用戶端使用 Bedrock 或 Agent Platform 格式時，Claude Code 只發送那些提供者接受的完整功能集的子集~~71* 當用戶端使用 Amazon Bedrock 或 Google Cloud 的 Agent Platform 格式時，Claude Code 只發送那些提供者接受的完整功能集的子集

~~72* 當用戶端使用 Anthropic Messages 格式時，Claude Code 發送完整集合，即使您的 gateway 轉發到 Bedrock 或 Agent Platform 上游~~72* 當用戶端使用 Anthropic Messages 格式時，Claude Code 發送完整集合，即使您的 gateway 轉發到 Amazon Bedrock 或 Google Cloud 的 Agent Platform 上游

73 73

74橋接該差異是您的 gateway 的工作。[功能傳遞](#feature-pass-through)描述了當它不這樣做時會發生什麼。74橋接該差異是您的 gateway 的工作。[功能傳遞](#feature-pass-through)描述了當它不這樣做時會發生什麼。

75 75

82| 標頭 | 描述 |82| 標頭 | 描述 |

83| :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |83| :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

84| `Authorization`、`x-api-key` | 開發人員的 gateway 認證，根據他們設定的[認證變數](/zh-TW/llm-gateway-connect#set-the-credential-variable)在一個或兩個標頭中 |84| `Authorization`、`x-api-key` | 開發人員的 gateway 認證，根據他們設定的[認證變數](/zh-TW/llm-gateway-connect#set-the-credential-variable)在一個或兩個標頭中 |

85| `anthropic-version` | API 版本，目前為 `2023-06-01`。Bedrock 和 Agent Platform 格式請求也攜帶 `anthropic_version` 請求體欄位，其值是提供者方言字串，而不是此標頭的值 |85| `anthropic-version` | API 版本，目前為 `2023-06-01`。Amazon Bedrock 和 Google Cloud 的 Agent Platform 格式請求也攜帶 `anthropic_version` 請求體欄位，其值是提供者方言字串，而不是此標頭的值 |

86| `anthropic-beta` | 請求的逗號分隔功能值。逐字轉發標頭；不要將個別值列入允許清單，因為該集合隨 Claude Code 版本而變化。當開發人員使用 claude.ai 登入進行驗證時（當設定 `ANTHROPIC_BASE_URL` 而沒有 gateway 認證變數時可能），此標頭也會攜帶上游需要的 OAuth 功能，移除它會導致這些請求失敗並出現 `401` |86| `anthropic-beta` | 請求的逗號分隔功能值。逐字轉發標頭；不要將個別值列入允許清單，因為該集合隨 Claude Code 版本而變化。當開發人員使用 claude.ai 登入進行驗證時（當設定 `ANTHROPIC_BASE_URL` 而沒有 gateway 認證變數時可能），此標頭也會攜帶上游需要的 OAuth 功能，移除它會導致這些請求失敗並出現 `401` |

100 100

101轉發到 Anthropic 格式上游時，傳遞 `anthropic-*` 請求標頭和請求體欄位不變，而不是將您今天看到的列入允許清單。固定到觀察清單的 gateway 會移除下一個功能的標頭或欄位，並在引入它的版本上破壞它。101轉發到 Anthropic 格式上游時，傳遞 `anthropic-*` 請求標頭和請求體欄位不變，而不是將您今天看到的列入允許清單。固定到觀察清單的 gateway 會移除下一個功能的標頭或欄位，並在引入它的版本上破壞它。

102 102

103例外是非 Anthropic 上游（如 Bedrock 或 Agent Platform），其中橋接架構差異是 gateway 的工作；請參閱[功能傳遞](#feature-pass-through)。103例外是非 Anthropic 上游（如 Amazon Bedrock 或 Google Cloud 的 Agent Platform），其中橋接架構差異是 gateway 的工作；請參閱[功能傳遞](#feature-pass-through)。

104 104

105<h2 id="system-prompt-attribution-block">105<h2 id="system-prompt-attribution-block">

106 系統提示歸屬區塊106 系統提示歸屬區塊

129細粒度工具串流是直接連接預設值之一：每當請求通過自訂基礎 URL 路由時，它預設為關閉，當開發人員設定 [`CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING=1`](/zh-TW/env-vars) 時，gateway 會接收它。129細粒度工具串流是直接連接預設值之一：每當請求通過自訂基礎 URL 路由時，它預設為關閉，當開發人員設定 [`CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING=1`](/zh-TW/env-vars) 時，gateway 會接收它。

130 130

131| 功能 | 標頭和請求體對 | 破壞時的症狀 | 補救 |131| 功能 | 標頭和請求體對 | 破壞時的症狀 | 補救 |

132| :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------- |132| :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------- |

133| [自適應推理](/zh-TW/model-config#adjust-effort-level) | 無測試版標頭。Claude Code 為 Claude 4.6 及更新版本發送 `thinking: {"type": "adaptive"}`，並將它不識別的模型名稱（如 gateway 別名）視為接收該欄位的目前模型 | 當上游模型組建不接受它時，命名 `thinking` 欄位或 `adaptive` 標籤的 `400` | 升級上游。在 Opus 4.6 和 Sonnet 4.6 上，開發人員可以改為設定 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` |133| [自適應推理](/zh-TW/model-config#adjust-effort-level) | 無測試版標頭。Claude Code 為 Claude 4.6 及更新版本發送 `thinking: {"type": "adaptive"}`，並將它不識別的模型名稱（如 gateway 別名）視為接收該欄位的目前模型 | 當上游模型組建不接受它時，命名 `thinking` 欄位或 `adaptive` 標籤的 `400` | 升級上游。在 Opus 4.6 和 Sonnet 4.6 上，開發人員可以改為設定 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` |

134| [上下文管理](https://platform.claude.com/docs/en/build-with-claude/context-management) | 上下文管理測試版標頭與 `context_management` 請求體欄位配對 | `400` 搭配 `Extra inputs are not permitted`。常見於 gateway 接受 Anthropic 格式請求但將其轉發到 Bedrock 時 | 轉發兩者，或 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/zh-TW/env-vars) |134| [上下文管理](https://platform.claude.com/docs/en/build-with-claude/context-management) | 上下文管理測試版標頭與 `context_management` 請求體欄位配對 | `400` 搭配 `Extra inputs are not permitted`。常見於 gateway 接受 Anthropic 格式請求但將其轉發到 Amazon Bedrock 時 | 轉發兩者，或 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/zh-TW/env-vars) |

135| [擴展上下文](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window)和[交錯思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking) | 僅測試版標頭，無請求體欄位 | 當標頭被移除時無聲地不可用；上游永遠不會看到功能請求 | 逐字轉發 `anthropic-beta` |135| [擴展上下文](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window)和[交錯思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking) | 僅測試版標頭，無請求體欄位 | 當標頭被移除時無聲地不可用；上游永遠不會看到功能請求 | 逐字轉發 `anthropic-beta` |

136| 測試版[工具欄位](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) | 工具相關的測試版標頭與工具架構欄位（如 `strict` 和 `defer_loading`）配對 | 當請求體在沒有其標頭的情況下通過時，命名無法識別的工具架構欄位的 `400` | 轉發兩者，或 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` |136| 測試版[工具欄位](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) | 工具相關的測試版標頭與工具架構欄位（如 `strict` 和 `defer_loading`）配對 | 當請求體在沒有其標頭的情況下通過時，命名無法識別的工具架構欄位的 `400` | 轉發兩者，或 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` |

137| [努力](https://platform.claude.com/docs/en/build-with-claude/effort)和[結構化輸出](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) | `output_config` 請求體欄位攜帶努力、結構化輸出格式和任務預算設定；每個都與其自己的測試版標頭配對 | 在 Bedrock 和 Agent Platform 上游上命名 `output_config` 的 `400`，通常是 `Extra inputs are not permitted` | 一起轉發欄位及其標頭 |137| [努力](https://platform.claude.com/docs/en/build-with-claude/effort)和[結構化輸出](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) | `output_config` 請求體欄位攜帶努力、結構化輸出格式和任務預算設定；每個都與其自己的測試版標頭配對 | 在 Amazon Bedrock 和 Google Cloud 的 Agent Platform 上游上命名 `output_config` 的 `400`，通常是 `Extra inputs are not permitted` | 一起轉發欄位及其標頭 |

139 139

140`ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES` [變數](/zh-TW/model-config)僅在提供者配置中聲明模型功能：`CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_VERTEX`、`CLAUDE_CODE_USE_FOUNDRY` 和 [`CLAUDE_CODE_USE_MANTLE`](/zh-TW/amazon-bedrock#use-the-mantle-endpoint)。它們在 `ANTHROPIC_BASE_URL` gateway 後面沒有效果。140`ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES` [變數](/zh-TW/model-config)僅在提供者配置中聲明模型功能：`CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_VERTEX`、`CLAUDE_CODE_USE_FOUNDRY` 和 [`CLAUDE_CODE_USE_MANTLE`](/zh-TW/amazon-bedrock#use-the-mantle-endpoint)。它們在 `ANTHROPIC_BASE_URL` gateway 後面沒有效果。

llm-gateway-rollout.md +4 −4

Details

180無論您選擇哪條路徑，相同的變數集都適用。大多數推出只需要 `ANTHROPIC_BASE_URL` 和認證；當您的閘道設定需要時，包括條件列。180無論您選擇哪條路徑，相同的變數集都適用。大多數推出只需要 `ANTHROPIC_BASE_URL` 和認證；當您的閘道設定需要時，包括條件列。

181 181

183| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |183| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

184| `ANTHROPIC_BASE_URL` | 將 Claude Code 的 API 請求發送到閘道，而不是 `api.anthropic.com` | 總是 |184| `ANTHROPIC_BASE_URL` | 將 Claude Code 的 API 請求發送到閘道，而不是 `api.anthropic.com` | 總是 |

189| `ANTHROPIC_MODEL` 或 [`ANTHROPIC_DEFAULT_HAIKU_MODEL`](/zh-TW/model-config) | 設定 Claude Code 為主工作階段和背景流量請求的模型名稱 | 您的閘道路由與 Claude Code 預設值不符的模型名稱，或您將[背景功能](/zh-TW/costs#background-token-usage)路由到不同的模型。在閘道上路由覆蓋名稱和 Claude Code 的預設名稱，因為某些子呼叫可以請求預設名稱，無論覆蓋如何；[模型配置](/zh-TW/model-config)涵蓋工作階段的每個部分使用哪個模型 |189| `ANTHROPIC_MODEL` 或 [`ANTHROPIC_DEFAULT_HAIKU_MODEL`](/zh-TW/model-config) | 設定 Claude Code 為主工作階段和背景流量請求的模型名稱 | 您的閘道路由與 Claude Code 預設值不符的模型名稱，或您將[背景功能](/zh-TW/costs#background-token-usage)路由到不同的模型。在閘道上路由覆蓋名稱和 Claude Code 的預設名稱，因為某些子呼叫可以請求預設名稱，無論覆蓋如何；[模型配置](/zh-TW/model-config)涵蓋工作階段的每個部分使用哪個模型 |

190| `ANTHROPIC_BEDROCK_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL`、`ANTHROPIC_FOUNDRY_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 以及[該提供者的變數](/zh-TW/llm-gateway-connect#route-to-a-cloud-provider-through-a-gateway) | 透過提供者特定的基本 URL 將 Claude Code 指向閘道。Bedrock 和 Agent Platform 也切換到這些提供者的原生請求格式 | 您的閘道前置 Bedrock、Agent Platform、Foundry 或 AWS 上的 Claude 平台；請參閱 [API 格式](/zh-TW/llm-gateway-protocol#api-formats) |190| `ANTHROPIC_BEDROCK_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL`、`ANTHROPIC_FOUNDRY_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 以及[該提供者的變數](/zh-TW/llm-gateway-connect#route-to-a-cloud-provider-through-a-gateway) | 透過提供者特定的基本 URL 將 Claude Code 指向閘道。Amazon Bedrock 和 Google Cloud 的 Agent Platform 也切換到這些提供者的原生請求格式 | 您的閘道前置 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 AWS 上的 Claude 平台；請參閱 [API 格式](/zh-TW/llm-gateway-protocol#api-formats) |

191 191

192<h4 id="distribute-through-managed-settings">192<h4 id="distribute-through-managed-settings">

193 透過受管設定分發193 透過受管設定分發

214 214

215某些環境需要單獨的傳遞：215某些環境需要單獨的傳遞：

216 216

217* 桌面應用程式僅從其 MDM 傳遞的第三方推理配置讀取閘道路由；部署該檔案以及受管設定，以便桌面工作階段也透過閘道路由。請參閱[桌面第三方配置文件](https://claude.com/docs/cowork/3p/configuration)和[桌面閘道文件](https://claude.com/docs/cowork/3p/gateway)217* 桌面應用程式僅從其 MDM 傳遞的第三方推理配置讀取閘道路由；部署該檔案以及受管設定，以便桌面工作階段也透過閘道路由。請參閱[桌面第三方配置文件](https://claude.com/docs/third-party/claude-desktop/configuration)和[桌面閘道文件](https://claude.com/docs/third-party/claude-desktop/gateway)

218* CI 執行器需要在[執行器的環境](/zh-TW/llm-gateway-connect#configure-each-surface)中設定 `ANTHROPIC_BASE_URL` 和認證218* CI 執行器需要在[執行器的環境](/zh-TW/llm-gateway-connect#configure-each-surface)中設定 `ANTHROPIC_BASE_URL` 和認證

219* 受管 Windows 機器上的 WSL 僅在 [`wslInheritsWindowsSettings`](/zh-TW/settings#available-settings) 為 `true` 時讀取 Windows 受管設定219* 受管 Windows 機器上的 WSL 僅在 [`wslInheritsWindowsSettings`](/zh-TW/settings#available-settings) 為 `true` 時讀取 Windows 受管設定

220 220

mcp.md +34 −17

Details

85 85

86當透過 `.mcp.json`、`~/.claude.json` 或 `claude mcp add-json` 中的 JSON 配置 MCP servers 時，`type` 欄位接受 `streamable-http` 作為 `http` 的別名。MCP 規範使用名稱 `streamable-http` 作為此傳輸，因此從 server 文件複製的配置無需修改即可運作。86當透過 `.mcp.json`、`~/.claude.json` 或 `claude mcp add-json` 中的 JSON 配置 MCP servers 時，`type` 欄位接受 `streamable-http` 作為 `http` 的別名。MCP 規範使用名稱 `streamable-http` 作為此傳輸，因此從 server 文件複製的配置無需修改即可運作。

87 87

88沒有 `type` 但有 `url` 的 JSON 項目是配置錯誤，因為 Claude Code 將沒有 `type` 的項目讀取為 stdio server。Claude Code 會跳過該 server 並報告 `MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry`。在 v2.1.202 之前，Claude Code 將此配置錯誤報告為 `command: expected string, received undefined`。

88<h3 id="option-2-add-a-remote-sse-server">90<h3 id="option-2-add-a-remote-sse-server">

89 選項 2：新增遠端 SSE server91 選項 2：新增遠端 SSE server

90</h3>92</h3>

111 113

112Stdio servers 在您的機器上作為本機程序執行。它們非常適合需要直接系統存取或自訂指令碼的工具。114Stdio servers 在您的機器上作為本機程序執行。它們非常適合需要直接系統存取或自訂指令碼的工具。

113 115

114Claude Code 在生成的 server 環境中設定 `CLAUDE_PROJECT_DIR`，以指向專案根目錄，因此您的 server 可以解析專案相對路徑，而無需依賴工作目錄。這與 hooks 在其 `CLAUDE_PROJECT_DIR` 變數中接收的目錄相同。從您的 server 程序內部讀取它，例如 Node 中的 `process.env.CLAUDE_PROJECT_DIR` 或 Python 中的 `os.environ["CLAUDE_PROJECT_DIR"]`。116Claude Code 在生成的 server 環境中設定 `CLAUDE_PROJECT_DIR` 為專案根目錄，因此您的 server 可以解析專案相對路徑，而無需依賴工作目錄。這與 hooks 在其 `CLAUDE_PROJECT_DIR` 變數中接收的目錄相同。從您的 server 程序內部讀取它，例如 Node 中的 `process.env.CLAUDE_PROJECT_DIR` 或 Python 中的 `os.environ["CLAUDE_PROJECT_DIR"]`。

115 117

116您的 server 也可以呼叫 MCP `roots/list` 請求，該請求會傳回啟動 Claude Code 的目錄。118`CLAUDE_PROJECT_DIR` 是穩定的專案根目錄，在 session 中途新增或移除工作目錄時不會變更。限制自身檔案系統存取到一組允許目錄的 server 應該改為實作 MCP `roots/list` 請求。Claude Code 使用 session 的啟動目錄加上您透過 `--add-dir`、`/add-dir` 或 `additionalDirectories` 設定授予的每個[額外工作目錄](/zh-TW/permissions#working-directories)來回答 `roots/list`。當該集合變更時，Claude Code 會傳送 `notifications/roots/list_changed`。在 v2.1.203 之前，`roots/list` 只傳回啟動目錄，Claude Code 不會傳送 `notifications/roots/list_changed`。

117 119

118此變數在 server 的環境中設定，而不是在 Claude Code 自己的環境中，因此在專案或使用者範圍的 `.mcp.json` `command` 或 `args` 中透過 `${VAR}` 擴展參考它需要預設值，例如 `${CLAUDE_PROJECT_DIR:-.}`。Plugin 提供的 MCP 配置直接替換 `${CLAUDE_PROJECT_DIR}`，不需要預設值。120此變數在 server 的環境中設定，而不是在 Claude Code 自己的環境中，因此在專案或使用者範圍的 `.mcp.json` `command` 或 `args` 中透過 `${VAR}` 擴展參考它需要預設值，例如 `${CLAUDE_PROJECT_DIR:-.}`。Plugin 提供的 MCP 配置直接替換 `${CLAUDE_PROJECT_DIR}`，不需要預設值。

119 121

191 193

192`/mcp` 面板會在每個已連接的 server 旁邊顯示工具計數，並標記宣告工具功能但未公開任何工具的 servers。194`/mcp` 面板會在每個已連接的 server 旁邊顯示工具計數，並標記宣告工具功能但未公開任何工具的 servers。

193 195

194如果您的請求需要來自仍在背景連接的 server 的工具，Claude 會在繼續之前等待該 server。啟用 [tool search](#scale-with-mcp-tool-search)（預設啟用）後，等待會在 `ToolSearch` 呼叫內進行。在沒有工具搜尋的配置中，例如 Vertex AI、自訂 `ANTHROPIC_BASE_URL` 或 `ENABLE_TOOL_SEARCH=false`，Claude 會改用 `WaitForMcpServers` 工具。196如果您的請求需要來自仍在背景連接的 server 的工具，Claude 會在繼續之前等待該 server。啟用 [tool search](#scale-with-mcp-tool-search)（預設啟用）後，等待會在 `ToolSearch` 呼叫內進行。在沒有工具搜尋的配置中，例如 Google Cloud 的 Agent Platform、自訂 `ANTHROPIC_BASE_URL` 或 `ENABLE_TOOL_SEARCH=false`，Claude 會改用 `WaitForMcpServers` 工具。

197

198某些 server 名稱保留供 Claude Code 的內建 servers 使用：`workspace`、`claude-in-chrome`、`computer-use`、`Claude Preview` 和 `Claude Browser`。如果您的配置定義了具有保留名稱的 server，Claude Code 會在載入時跳過它，並顯示警告要求您重新命名它。`claude mcp add` 會以錯誤拒絕保留名稱。

195 199

196server 名稱 `workspace` 保留供內部使用。如果您的配置定義了具有該名稱的 server，Claude Code 會在載入時跳過它，並顯示警告要求您重新命名它。200`Claude Preview` 和 `Claude Browser` 都命名了 [Claude Code 桌面應用程式的預覽窗格](/zh-TW/desktop#preview-your-app)使用的內建 server。在 v2.1.205 之前，`Claude Browser` 未被保留，因此使用者配置的 server 可以在該名稱下註冊。

197 201

198<h3 id="dynamic-tool-updates">202<h3 id="dynamic-tool-updates">

199 動態工具更新203 動態工具更新

209 213

210相同的退避策略適用於 HTTP 或 SSE server 在啟動時初始連接失敗的情況。自 v2.1.121 起，Claude Code 在暫時性錯誤（例如 5xx 回應、連接被拒絕或逾時）上最多重試初始連接三次，如果仍無法連接，則將 server 標記為失敗。驗證和找不到錯誤不會重試，因為它們需要配置變更才能解決。214相同的退避策略適用於 HTTP 或 SSE server 在啟動時初始連接失敗的情況。自 v2.1.121 起，Claude Code 在暫時性錯誤（例如 5xx 回應、連接被拒絕或逾時）上最多重試初始連接三次，如果仍無法連接，則將 server 標記為失敗。驗證和找不到錯誤不會重試，因為它們需要配置變更才能解決。

211 215

216當配置的 server 無法連接時，Claude Code 會告訴 Claude 哪個 server 失敗及其連接錯誤，包括在找不到匹配工具的 `ToolSearch` 結果中，因此 Claude 會在其回應中報告連接失敗。需要 [tool search](#scale-with-mcp-tool-search)，預設啟用。在沒有工具搜尋的配置中，例如自訂 `ANTHROPIC_BASE_URL`、`ENABLE_TOOL_SEARCH=false` 或 Haiku 模型，以及在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，Claude Code 不會向 Claude 報告失敗的 server 連接。在 v2.1.205 之前，Claude Code 不會將連接錯誤傳遞給 Claude，Claude 可能會回應，就像失敗的 server 的工具從未被配置一樣。

217

212自 v2.1.191 起，在成功連接後執行的功能探索請求（例如 `tools/list`、`prompts/list` 和 `resources/list`）也會在短退避的情況下重試暫時性網路和 server 錯誤最多三次。驗證錯誤、4xx 回應和請求逾時不會重試。218自 v2.1.191 起，在成功連接後執行的功能探索請求（例如 `tools/list`、`prompts/list` 和 `resources/list`）也會在短退避的情況下重試暫時性網路和 server 錯誤最多三次。驗證錯誤、4xx 回應和請求逾時不會重試。

213 219

214<h3 id="push-messages-with-channels">220<h3 id="push-messages-with-channels">

220<Tip>226<Tip>

221 提示：227 提示：

222 228

223 * 使用 `--scope` 旗標指定配置的儲存位置：229 * 使用 `-s` 或 `--scope` 旗標指定配置的儲存位置：

224 * `local` (預設)：僅在目前專案中對您可用。較舊版本稱此範圍為 `project`230 * `local` (預設)：僅在目前專案中對您可用。較舊版本稱此範圍為 `project`

225 * `project`：透過 `.mcp.json` 檔案與專案中的所有人共享231 * `project`：透過 `.mcp.json` 檔案與專案中的所有人共享

226 * `user`：在所有專案中對您可用。較舊版本稱此範圍為 `global`232 * `user`：在所有專案中對您可用。較舊版本稱此範圍為 `global`

227 * 使用 `--env` 旗標設定環境變數 (例如，`--env KEY=value`)233 * 使用 `-e` 或 `--env` 旗標設定環境變數 (例如，`-e KEY=value`)

234 * `--transport` 和 `--header` 旗標也接受 `-t` 和 `-H` 短形式

228 * 使用 `MCP_TIMEOUT` 環境變數配置 MCP server 啟動逾時 (例如，`MCP_TIMEOUT=10000 claude` 設定 10 秒逾時)235 * 使用 `MCP_TIMEOUT` 環境變數配置 MCP server 啟動逾時 (例如，`MCP_TIMEOUT=10000 claude` 設定 10 秒逾時)

229 * 透過在該 server 的 `.mcp.json` 項目中新增 `timeout` 欄位（以毫秒為單位）來設定每個 server 的工具執行逾時，例如 `"timeout": 600000` 表示十分鐘。這只會覆寫該 server 的 `MCP_TOOL_TIMEOUT` 環境變數236 * 透過在該 server 的 `.mcp.json` 項目中新增 `timeout` 欄位（以毫秒為單位）來設定每個 server 的工具執行逾時，例如 `"timeout": 600000` 表示十分鐘。這只會覆寫該 server 的 `MCP_TOOL_TIMEOUT` 環境變數

230 * 當 MCP 工具輸出超過 10,000 個 tokens 時，Claude Code 會顯示警告。若要增加此限制，請設定 `MAX_MCP_OUTPUT_TOKENS` 環境變數 (例如，`MAX_MCP_OUTPUT_TOKENS=50000`)237 * 當 MCP 工具輸出超過 10,000 個 tokens 時，Claude Code 會顯示警告。若要增加此限制，請設定 `MAX_MCP_OUTPUT_TOKENS` 環境變數 (例如，`MAX_MCP_OUTPUT_TOKENS=50000`)

231 * 使用 `/mcp` 向需要 OAuth 2.0 驗證的遠端 servers 進行驗證238 * 使用 `/mcp` 向需要 OAuth 2.0 驗證的遠端 servers 進行驗證

232</Tip>239</Tip>

233 240

234每個 server 的 `timeout` 是每個工具呼叫的硬牆鐘限制，來自 server 的進度通知不會延長它。低於 1000 的值會被忽略並落回到 `MCP_TOOL_TIMEOUT`，或在該變數未設定時落回到其預設值約 28 小時。{/* min-version: 2.1.162 */}在 v2.1.162 之前，低於 1000 的值被調整為一秒。對於 HTTP 和 SSE servers，每個請求的 fetch 首位元組預算有 60 秒的最小值。241每個 server 的 `timeout` 是每個工具呼叫的硬牆鐘限制，來自 server 的進度通知不會延長它。低於 1000 的值會被忽略並落回到 `MCP_TOOL_TIMEOUT`，或在該變數未設定時落回到其預設值約 28 小時。{/* min-version: 2.1.162 */}在 v2.1.162 之前，低於 1000 的值被調整為一秒。

242

243每個 server 至少 1000 的 `timeout` 也會作為下面所述的閒置逾時的下限：Claude Code 永遠不會因為閒置而在每個 server 的 `timeout` 之前中止該 server 的工具呼叫。需要 Claude Code v2.1.203 或更新版本。

235 244

236自 v2.1.187 起，對遠端 HTTP、SSE、WebSocket 或 [claude.ai connector](#use-mcp-servers-from-claude-ai) server 的工具呼叫如果 5 分鐘內沒有傳送回應和進度通知，會以錯誤中止，而不是等待牆鐘限制。在毫秒中設定 [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](/zh-TW/env-vars) 環境變數以變更閒置視窗，或將其設定為 `0` 以停用檢查。Stdio servers 是本機程序，不受閒置逾時限制。245對於 HTTP 和 SSE servers，每個請求的 fetch 首位元組預算有 60 秒的最小值。

246

247對遠端 MCP server 的工具呼叫如果在閒置視窗內沒有傳送回應和進度通知，會以錯誤中止，而不是等待牆鐘限制。閒置逾時需要 Claude Code v2.1.187 或更新版本。{/* min-version: 2.1.203 */}它適用於除 IDE servers 和 SDK 進程內 servers 之外的每種 server 類型。HTTP、SSE、WebSocket 和 [claude.ai connector](#use-mcp-servers-from-claude-ai) servers 的閒置視窗預設為五分鐘，stdio servers 的預設為 30 分鐘。在 v2.1.203 之前，stdio servers 不受閒置逾時限制。

248

249在毫秒中設定 [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](/zh-TW/env-vars) 環境變數以變更閒置視窗，或將其設定為 `0` 以停用檢查。

237 250

238<h3 id="plugin-provided-mcp-servers">251<h3 id="plugin-provided-mcp-servers">

239 Plugin 提供的 MCP servers252 Plugin 提供的 MCP servers

304mcp__plugin_my-plugin_database-tools__query317mcp__plugin_my-plugin_database-tools__query

305```318```

306 319

307在 [permission rules](/zh-TW/permissions)、skill 的 `allowed-tools` 列表或 [subagent 的 `tools` 欄位](/zh-TW/sub-agents#available-tools) 中參考工具時，請使用此完整名稱。320在 [permission rules](/zh-TW/permissions)、skill 的 `allowed-tools` 列表、[subagent 的 `tools` 欄位](/zh-TW/sub-agents#available-tools) 或 [hook matcher](/zh-TW/hooks#match-mcp-tools) 中參考工具時，請使用此完整名稱。針對裸 server 金鑰（例如 `mcp__database-tools__.*`）編寫的 hook matcher 永遠不會針對 plugin 捆綁的 server 觸發。

321

322server 本身在範圍名稱 `plugin:<plugin-name>:<server-name>` 下註冊，例如 `plugin:my-plugin:database-tools`。在需要配置的 server 名稱的地方使用該名稱，例如 [`mcp_tool` hook 的 `server` 欄位](/zh-TW/hooks#mcp-tool-hook-fields)。

308 323

309**Plugin MCP servers 的優點**：324**Plugin MCP servers 的優點**：

310 325

858 </Step>873 </Step>

859</Steps>874</Steps>

860 875

876透過 `claude mcp` 命令新增的伺服器名稱只能包含字母、數字、連字號和底線。Claude Desktop 不會套用該限制，因此名稱包含任何其他字元（例如空格）的 Claude Desktop 伺服器無法匯入。匯入會報告它拒絕的每個名稱，並仍會匯入您選擇的其他伺服器。在 v2.1.205 之前，第一個無效名稱會停止匯入，且不會新增任何選定的伺服器。

877

861<Tip>878<Tip>

862 提示：879 提示：

863 880

864 * 此功能僅適用於 macOS 和 Windows Subsystem for Linux (WSL)881 * 此功能僅適用於 macOS 和 Windows Subsystem for Linux (WSL)

865 * 它從這些平台上的標準位置讀取 Claude Desktop 配置檔案882 * 它從這些平台上的標準位置讀取 Claude Desktop 配置檔案

866 * 使用 `--scope user` 旗標將 servers 新增到您的使用者配置883 * 使用 `--scope user` 旗標將 servers 新增到您的使用者配置

867 * 匯入的 servers 將具有與 Claude Desktop 中相同的名稱884 * 匯入的 servers 將具有與 Claude Desktop 中相同的名稱（當名稱只包含字母、數字、連字號和底線時）。Claude Code 會報告名稱包含任何其他字元的伺服器並跳過它

868 * 如果已存在相同名稱的 servers，它們將獲得數字尾碼 (例如，`server_1`)885 * 如果已存在相同名稱的 servers，它們將獲得數字尾碼（例如，`server_1`）

869</Tip>886</Tip>

870 887

871<h2 id="use-mcp-servers-from-claude-ai">888<h2 id="use-mcp-servers-from-claude-ai">

896 913

897從 v2.1.161 開始，您從未登入過的 connectors 會在 claude.ai 部分末尾的 `Show unused connectors` 列後面摺疊，因此組織佈建的列表不會填滿面板。選擇該列以展開它們。您之前登入過的 connector 即使目前需要重新驗證，也會保持可見。914從 v2.1.161 開始，您從未登入過的 connectors 會在 claude.ai 部分末尾的 `Show unused connectors` 列後面摺疊，因此組織佈建的列表不會填滿面板。選擇該列以展開它們。您之前登入過的 connector 即使目前需要重新驗證，也會保持可見。

898 915

899Claude.ai connectors 只有在您的活躍[驗證方法](/zh-TW/authentication#authentication-precedence)是您的 Claude.ai 訂閱時才會被取得。當 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN`、`apiKeyHelper` 或第三方提供者（例如 Bedrock 或 Vertex）處於活躍狀態時，它們不會被載入，即使您之前執行過 `/login`。如果 `/mcp` 沒有列出您新增的 connector，請執行 `/status` 以確認哪個驗證方法處於活躍狀態，取消設定該環境變數或移除 `apiKeyHelper` 設定，然後執行 `/login` 以選擇您的 claude.ai 帳戶。916Claude.ai connectors 只有在您的活躍[驗證方法](/zh-TW/authentication#authentication-precedence)是您的 Claude.ai 訂閱時才會被取得。當 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN`、`apiKeyHelper` 或第三方提供者（例如 Amazon Bedrock 或 Google Cloud 的 Agent Platform）處於活躍狀態時，它們不會被載入，即使您之前執行過 `/login`。如果 `/mcp` 沒有列出您新增的 connector，請執行 `/status` 以確認哪個驗證方法處於活躍狀態，取消設定該環境變數或移除 `apiKeyHelper` 設定，然後執行 `/login` 以選擇您的 claude.ai 帳戶。

900 917

901您在 Claude Code 中新增的 server 優先於指向相同 URL 的 claude.ai connector。發生這種情況時，`/mcp` 會將 connector 列為隱藏，並顯示如何移除重複項（如果您寧願使用 connector）。918您在 Claude Code 中新增的 server 優先於指向相同 URL 的 claude.ai connector。發生這種情況時，`/mcp` 會將 connector 列為隱藏，並顯示如何移除重複項（如果您寧願使用 connector）。

902 919

1172 配置 tool search1189 配置 tool search

1173</h3>1190</h3>

1174 1191

1175Tool search 預設啟用：MCP 工具被延遲並按需探索。Claude Code 在 Vertex AI 上預設停用它。當 `ANTHROPIC_BASE_URL` 指向非第一方主機時，它也被停用，因為大多數代理不轉發 `tool_reference` 區塊。設定 `ENABLE_TOOL_SEARCH` 明確以覆蓋任一回退。1192Tool search 預設啟用：MCP 工具被延遲並按需探索。Claude Code 在 Google Cloud 的 Agent Platform 上預設停用它。當 `ANTHROPIC_BASE_URL` 指向非第一方主機時，它也被停用，因為大多數代理不轉發 `tool_reference` 區塊。設定 `ENABLE_TOOL_SEARCH` 明確以覆蓋任一回退。

1176 1193

1177Tool search 需要支援 `tool_reference` 區塊的模型。Haiku 模型不支援它。在 Vertex AI 上，tool search 支援 Claude Sonnet 4.5 及更新版本和 Claude Opus 4.5 及更新版本。1194Tool search 需要支援 `tool_reference` 區塊的模型。Haiku 模型不支援它。在 Google Cloud 的 Agent Platform 上，tool search 支援 Claude Sonnet 4.5 及更新版本和 Claude Opus 4.5 及更新版本。

1178 1195

1179使用 `ENABLE_TOOL_SEARCH` 環境變數控制 tool search 行為：1196使用 `ENABLE_TOOL_SEARCH` 環境變數控制 tool search 行為：

1180 1197

1181| 值 | 行為 |1198| 值 | 行為 |

1182| :------- | :------------------------------------------------------------------------------------------------------------------------------------- |1199| :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1183| (未設定) | 所有 MCP 工具被延遲並按需載入。在 Vertex AI 上或當 `ANTHROPIC_BASE_URL` 是非第一方主機時回退到預先載入 |1200| (未設定) | 所有 MCP 工具被延遲並按需載入。在 Google Cloud 的 Agent Platform 上或當 `ANTHROPIC_BASE_URL` 是非第一方主機時回退到預先載入 |

1184| `true` | 所有 MCP 工具被延遲。Claude Code 即使在 Vertex AI 上和透過代理也會傳送 beta 標頭。在 Vertex AI 模型早於 Sonnet 4.5 或 Opus 4.5 上，或在不支援 `tool_reference` 區塊的代理上，請求會失敗 |1201| `true` | 所有 MCP 工具被延遲。Claude Code 即使在 Google Cloud 的 Agent Platform 上和透過代理也會傳送 beta 標頭。在 Google Cloud 的 Agent Platform 模型早於 Sonnet 4.5 或 Opus 4.5 上，或在不支援 `tool_reference` 區塊的代理上，請求會失敗 |

mcp-quickstart.md +1 −1

Details

315 Claude Code 未找到目前目錄的任何伺服器。最常見的原因：315 Claude Code 未找到目前目錄的任何伺服器。最常見的原因：

316 316

317 * 您從不同的專案執行了 `claude mcp add`。本機範圍伺服器與您新增它們的專案相關聯：儲存庫根目錄，或如果您不在 git 儲存庫中，則為確切目錄。從您現在所在的專案重新新增伺服器，或使用 `--scope user` 新增它，使其不與專案相關聯。317 * 您從不同的專案執行了 `claude mcp add`。本機範圍伺服器與您新增它們的專案相關聯：儲存庫根目錄，或如果您不在 git 儲存庫中，則為確切目錄。從您現在所在的專案重新新增伺服器，或使用 `--scope user` 新增它，使其不與專案相關聯。

318 * 您在錯誤的路徑編輯了設定檔。正確的檔案是 `~/.claude.json` 和 `<project>/.mcp.json`。Claude Code 不讀取 `~/.claude/config/mcp.json`、`~/.claude/mcp.json` 或 `%APPDATA%\Claude\mcp.json` 等路徑。318 * 您在錯誤的路徑編輯了設定檔。正確的檔案是 `~/.claude.json` 和 `<project>/.mcp.json`。Claude Code 不讀取 `~/.claude/.mcp.json`、`~/.claude/config/mcp.json`、`~/.claude/mcp.json` 或 `%APPDATA%\Claude\mcp.json` 等路徑。對於使用者範圍伺服器，執行 `claude mcp add --scope user`，它會寫入 `~/.claude.json` 中的 `mcpServers` 金鑰；對於專案範圍伺服器，編輯專案根目錄的 `.mcp.json`。

319 </Accordion>319 </Accordion>

320 320

321 <Accordion title="狀態顯示 Failed to connect 或 Connection error">321 <Accordion title="狀態顯示 Failed to connect 或 Connection error">

microsoft-foundry.md +18 −6

Details

113 2) 配置 Azure 認證113 2) 配置 Azure 認證

114</h3>114</h3>

115 115

116Claude Code 支援 Microsoft Foundry 的兩種驗證方法。選擇最適合您安全性要求的方法。116Claude Code 支援 Microsoft Foundry 的三種驗證方法。選擇最適合您安全性要求的方法。

117 117

118**選項 A：API 金鑰驗證**118**選項 A：API 金鑰驗證**

119 119

128 128

129**選項 B：Microsoft Entra ID 驗證**129**選項 B：Microsoft Entra ID 驗證**

130 130

131當未設定 `ANTHROPIC_FOUNDRY_API_KEY` 時，Claude Code 會自動使用 Azure SDK [預設認證鏈](https://learn.microsoft.com/en-us/azure/developer/javascript/sdk/authentication/credential-chains#defaultazurecredential-overview)。131當未設定 `ANTHROPIC_FOUNDRY_API_KEY` 和 `ANTHROPIC_FOUNDRY_AUTH_TOKEN` 時，Claude Code 會自動使用 Azure SDK [預設認證鏈](https://learn.microsoft.com/en-us/azure/developer/javascript/sdk/authentication/credential-chains#defaultazurecredential-overview)。

132這支援多種方法來驗證本機和遠端工作負載。132這支援多種方法來驗證本機和遠端工作負載。

133 133

134在本機環境中，您通常可以使用 Azure CLI：134在本機環境中，您通常可以使用 Azure CLI：

137az login137az login

138```138```

139 139

140**選項 C：Bearer 權杖驗證**

141

142{/* min-version: 2.1.203 */}Claude Code 在每個請求上將 `ANTHROPIC_FOUNDRY_AUTH_TOKEN` 的值作為 `Authorization: Bearer` 標頭傳送。當另一個程序（例如主應用程式或登入指令碼）已為您取得存取權杖時，請使用此選項。需要 Claude Code v2.1.203 或更新版本。

143

144將變數設定為 Microsoft Entra ID 為您的資源簽發的 Bearer 權杖：

145

146```bash theme={null}

147export ANTHROPIC_FOUNDRY_AUTH_TOKEN=your-entra-access-token

148```

149

150`ANTHROPIC_FOUNDRY_AUTH_TOKEN` 優先於 `ANTHROPIC_FOUNDRY_API_KEY` 和預設認證鏈。

151

140<Note>152<Note>

141 使用 Microsoft Foundry 時，`/logout` 命令無法使用，因為驗證是透過 Azure 認證處理的。153 使用 Microsoft Foundry 時，`/logout` 命令無法使用，因為驗證是透過 Azure 認證處理的。

142</Note>154</Note>

162</h3>174</h3>

163 175

164<Warning>176<Warning>

165 為每個部署固定特定的模型版本。如果您使用模型別名（例如 `sonnet` 和 `opus`）而不固定版本，Claude Code 的 Foundry 內建預設值可能會落後最新版本，且可能尚未在您的帳戶中提供。Foundry 沒有啟動模型檢查，因此當預設值無法使用時，請求會失敗。建立 Azure 部署時，請選擇特定的模型版本，而不是「自動更新至最新版本」。177 為每個部署固定特定的模型版本。如果不固定版本，模型別名（例如 `sonnet` 和 `opus`）會解析為 Claude Code 針對 Microsoft Foundry 的內建預設值，這可能會落後最新版本，且可能尚未在您的帳戶中提供。Microsoft Foundry 沒有啟動模型檢查，因此當預設值無法使用時，請求會失敗。建立 Azure 部署時，請選擇特定的模型版本，而不是「自動更新至最新版本」。

166</Warning>178</Warning>

167 179

168設定模型變數以符合您在步驟 1 中建立的部署名稱。180設定模型變數以符合您在步驟 1 中建立的部署名稱。

169 181

170如果沒有 `ANTHROPIC_DEFAULT_OPUS_MODEL`，Foundry 上的 `opus` 別名會解析為 Opus 4.6。將其設定為 Opus 4.8 ID 以使用最新模型：182如果沒有 `ANTHROPIC_DEFAULT_OPUS_MODEL`，Microsoft Foundry 上的 `opus` 別名會解析為 Opus 4.6。將其設定為 Opus 4.8 ID 以使用最新模型：

171 183

172```bash theme={null}184```bash theme={null}

173export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'185export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'

175export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5'187export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5'

176```188```

177 189

178背景工作（例如工作階段標題生成）使用小型/快速模型，通常是 Haiku 級別的模型。在 Foundry 上，Claude Code 預設使用主要模型，因為並非每個帳戶都有 Haiku 部署。若要為背景工作使用 Haiku，請將 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 設定為您帳戶中可用的 Haiku 部署，如上所示。190背景工作（例如工作階段標題生成）使用小型/快速模型，通常是 Haiku 級別的模型。在 Microsoft Foundry 上，Claude Code 預設使用主要模型，因為並非每個帳戶都有 Haiku 部署。若要為背景工作使用 Haiku，請將 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 設定為您帳戶中可用的 Haiku 部署，如上所示。

179 191

180如需目前和舊版模型 ID，請參閱[模型概覽](https://platform.claude.com/docs/en/about-claude/models/overview)。如需完整的環境變數清單，請參閱[模型配置](/zh-TW/model-config#pin-models-for-third-party-deployments)。192如需目前和舊版模型 ID，請參閱[模型概覽](https://platform.claude.com/docs/en/about-claude/models/overview)。如需完整的環境變數清單，請參閱[模型配置](/zh-TW/model-config#pin-models-for-third-party-deployments)。

181 193

195claude207claude

196```208```

197 209

198Claude Code 從環境中讀取 `CLAUDE_CODE_USE_FOUNDRY` 和其他 Foundry 變數，並在第一個提示時連接到您的 Azure 資源。與 Bedrock 和 Vertex AI 不同，Foundry 沒有互動式設定精靈，因此步驟 3 和 4 中的環境變數是唯一的配置路徑。210Claude Code 從環境中讀取 `CLAUDE_CODE_USE_FOUNDRY` 和其他 Microsoft Foundry 變數，並在第一個提示時連接到您的 Azure 資源。與 Amazon Bedrock 和 Google Cloud 的 Agent Platform 不同，Microsoft Foundry 沒有互動式設定精靈，因此步驟 3 和 4 中的環境變數是唯一的配置路徑。

199 211

200<h2 id="azure-rbac-configuration">212<h2 id="azure-rbac-configuration">

201 Azure RBAC 配置213 Azure RBAC 配置

model-config.md +76 −30

Details

15* 一個**模型別名**15* 一個**模型別名**

16* 一個**模型名稱**16* 一個**模型名稱**

17 * Anthropic API：完整的\*\*[模型名稱](https://platform.claude.com/docs/zh-TW/about-claude/models/overview)\*\*17 * Anthropic API：完整的\*\*[模型名稱](https://platform.claude.com/docs/zh-TW/about-claude/models/overview)\*\*

~~18 * Bedrock：推論設定檔 ARN~~18 * Amazon Bedrock：推論設定檔 ARN

~~19 * Foundry：部署名稱~~19 * Microsoft Foundry：部署名稱

~~20 * Vertex：版本名稱~~20 * Google Cloud 的 Agent Platform：版本名稱

21 21

22<Note>22<Note>

23 `ANTHROPIC_BASE_URL` 改變請求的發送位置，而不是哪個模型回答它們。若要透過 LLM 閘道路由 Claude，請參閱 [LLM 閘道](/zh-TW/llm-gateway)。23 `ANTHROPIC_BASE_URL` 改變請求的發送位置，而不是哪個模型回答它們。若要透過 LLM 閘道路由 Claude，請參閱 [LLM 閘道](/zh-TW/llm-gateway)。

41| **`opus[1m]`** | 使用 Opus 搭配[100 萬個 token 的 context window](https://platform.claude.com/docs/zh-TW/build-with-claude/context-windows#1m-token-context-window)進行長時間會話 |41| **`opus[1m]`** | 使用 Opus 搭配[100 萬個 token 的 context window](https://platform.claude.com/docs/zh-TW/build-with-claude/context-windows#1m-token-context-window)進行長時間會話 |

43 43

44在 Anthropic API 上，`opus` 解析為 Opus 4.8，`sonnet` 解析為 Sonnet 5。在 [AWS 上的 Claude Platform](/zh-TW/claude-platform-on-aws) 上，`opus` 解析為 Opus 4.7，`sonnet` 解析為 Sonnet 4.6。在 Bedrock、Vertex 和 Foundry 上，`opus` 解析為 Opus 4.6，`sonnet` 解析為 Sonnet 4.5；透過明確選擇完整模型名稱或設定 `ANTHROPIC_DEFAULT_OPUS_MODEL` 或 `ANTHROPIC_DEFAULT_SONNET_MODEL`，這些提供者上可以使用更新的模型。44在 Anthropic API 上，`opus` 解析為 Opus 4.8，`sonnet` 解析為 Sonnet 5。在 [AWS 上的 Claude Platform](/zh-TW/claude-platform-on-aws) 上，`opus` 解析為 Opus 4.7，`sonnet` 解析為 Sonnet 4.6。在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，`opus` 解析為 Opus 4.6，`sonnet` 解析為 Sonnet 4.5；透過明確選擇完整模型名稱或設定 `ANTHROPIC_DEFAULT_OPUS_MODEL` 或 `ANTHROPIC_DEFAULT_SONNET_MODEL`，這些提供者上可以使用更新的模型。

45 45

46別名指向您提供者的推薦版本，並隨著時間推移而更新。若要固定到特定版本，請使用完整模型名稱（例如 `claude-opus-4-8`）或設定相應的環境變數，如 `ANTHROPIC_DEFAULT_OPUS_MODEL`。46別名指向您提供者的推薦版本，並隨著時間推移而更新。若要固定到特定版本，請使用完整模型名稱（例如 `claude-opus-4-8`）或設定相應的環境變數，如 `ANTHROPIC_DEFAULT_OPUS_MODEL`。

47 47

84* `Enter`：切換模型並儲存為您的預設值84* `Enter`：切換模型並儲存為您的預設值

85* `s`：僅針對此會話切換模型85* `s`：僅針對此會話切換模型

86 86

87直接輸入 `/model <name>` 的行為類似於 `Enter`。專案和受管設定仍然優先，並在下次啟動時重新應用。{/* min-version: 2.1.196 */}您的管理員配置的[組織預設模型](#organization-default-model)也會在下次啟動時重新應用。87直接輸入 `/model <name>` 的行為類似於 `Enter`。{/* min-version: 2.1.205 */}在[非互動模式](/zh-TW/headless)中使用 `/model` 設定的模型，搭配 `-p` 旗標，僅適用於目前會話，不會儲存為您的預設值。專案和受管設定仍然優先，並在下次啟動時重新應用。{/* min-version: 2.1.196 */}您的管理員配置的[組織預設模型](#organization-default-model)也會在下次啟動時重新應用。

88 88

89在 v2.1.144 至 v2.1.152 中，`/model` 僅適用於目前會話，選擇器中的 `d` 儲存預設值。89在 v2.1.144 至 v2.1.152 中，`/model` 僅適用於目前會話，選擇器中的 `d` 儲存預設值。

90 90

94 94

95當啟動時的活動模型來自專案或受管設定而非您自己的選擇時，啟動標題會顯示哪個設定檔設定了它。執行 `/model` 以覆蓋；專案或受管設定會在下次啟動時重新應用。95當啟動時的活動模型來自專案或受管設定而非您自己的選擇時，啟動標題會顯示哪個設定檔設定了它。執行 `/model` 以覆蓋；專案或受管設定會在下次啟動時重新應用。

96 96

97當透過 [Agent SDK](/zh-TW/agent-sdk/overview) `setModel()` 方法或由執行 Claude Code CLI 的應用程式（例如 [Desktop app](/zh-TW/desktop)）要求模型切換時，Claude Code 會檢查該字串是否為它識別的字串，然後再儲存它。此檢查需要 Claude Code v2.1.200 或更新版本。在 Anthropic API 上，Claude Code 識別：

99* 一個模型別名

100* 來自 `/model` 選擇器的項目

101* 任何以 `claude-` 開頭的名稱

102* 您自己配置為[自訂模型選項](#add-a-custom-model-option)或在 [`modelOverrides`](#override-model-ids-per-version) 中的值

103

104Claude Code 會以 `Model "<name>" is not a recognized model id.` 拒絕無法識別的字串，會話會保持其目前的模型，而不是儲存該字串並在下一個請求時失敗。請參閱[錯誤參考](/zh-TW/errors#model-is-not-a-recognized-model-id)以了解復原步驟。

105

106檢查僅在 Anthropic API 上執行。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry、[AWS 上的 Claude Platform](/zh-TW/claude-platform-on-aws) 和 [LLM 閘道](/zh-TW/llm-gateway)後方或自訂 `ANTHROPIC_BASE_URL` 後方，您的提供者或閘道定義模型名稱，所以 Claude Code 會不檢查地傳遞任何字串。檢查也不涵蓋 `--model` 旗標、`ANTHROPIC_MODEL` 環境變數或 `model` 設定；在那裡輸入錯誤的值會在第一個請求時產生[所選模型有問題](/zh-TW/errors#there%E2%80%99s-an-issue-with-the-selected-model)。

107

97當請求的模型有排定的淘汰日期或自動重新對應到較新版本時，Claude Code 會顯示一個警告，其中命名了請求的模型。互動式會話會將其顯示為啟動通知。從 v2.1.182 起，當使用預設文字輸出格式時，相同的警告會在[非互動模式](/zh-TW/headless)中寫入 stderr。檢查也涵蓋在[子代理 frontmatter](/zh-TW/sub-agents) 中設定的 `model`。對於 `--output-format json` 和 `stream-json`，stderr 警告會被抑制；改為從[結果訊息](/zh-TW/headless#get-structured-output)的 `modelUsage` 欄位讀取實際模型。108當請求的模型有排定的淘汰日期或自動重新對應到較新版本時，Claude Code 會顯示一個警告，其中命名了請求的模型。互動式會話會將其顯示為啟動通知。從 v2.1.182 起，當使用預設文字輸出格式時，相同的警告會在[非互動模式](/zh-TW/headless)中寫入 stderr。檢查也涵蓋在[子代理 frontmatter](/zh-TW/sub-agents) 中設定的 `model`。對於 `--output-format json` 和 `stream-json`，stderr 警告會被抑制；改為從[結果訊息](/zh-TW/headless#get-structured-output)的 `modelUsage` 欄位讀取實際模型。

98 109

99使用範例：110使用範例：

133* **顧問模型**：已設定的 [`advisorModel`](/zh-TW/advisor) 設定和 `--advisor` 旗標144* **顧問模型**：已設定的 [`advisorModel`](/zh-TW/advisor) 設定和 `--advisor` 旗標

134* **背景代理模型**：在[分派選擇器](/zh-TW/agent-view)中選擇的模型145* **背景代理模型**：在[分派選擇器](/zh-TW/agent-view)中選擇的模型

135 146

136使用 `/model` 切換到被阻止的模型會被拒絕並出現錯誤，而被阻止的 `--model` 旗標、`ANTHROPIC_MODEL` 或 `model` 設定值在啟動時會被替換為警告，命名所要求和替代的模型，會話會在預設模型上啟動。被阻止的子代理、技能或命令覆蓋會回退到繼承或預設模型，而不是使請求失敗；被阻止的 `advisorModel` 設定會停用該會話的顧問，而被阻止的 `--advisor` 旗標值會在啟動時以錯誤退出。排除的模型會從 `/model` 選擇器中隱藏。{/* min-version: 2.1.199 */}自 v2.1.199 起，清單中沒有內建選擇器列的完整模型 ID（例如清單固定的較舊版本）會在 `/model` 選擇器中顯示為其自己的標記列。在較早版本上，此類 ID 只能透過輸入 `/model <id>` 選擇。147在 Anthropic API 和 [AWS 上的 Claude Platform](/zh-TW/claude-platform-on-aws) 上，模型系列別名 `opus`、`sonnet`、`haiku` 或 `fable` 解析為允許清單允許的其系列的最新版本。當允許清單固定特定版本時，例如 `["sonnet", "claude-opus-4-6"]`，`/model opus` 和 `--model opus` 都會選擇 Claude Opus 4.6（最新允許的 Opus），並顯示一個通知，命名所要求和替代的模型。在 v2.1.205 之前，其最新發佈版本在清單外的別名會被拒絕或替換，就像任何其他被阻止的選擇一樣，即使清單允許較舊版本。

148

149Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 [Mantle](/zh-TW/amazon-bedrock#use-the-mantle-endpoint) 使用提供者特定的部署 ID 而不是 Anthropic 模型 ID，因此被阻止的別名在那裡遵循下面的拒絕和替換行為。

150

151Claude Code 根據模型的設定位置處理任何其他被阻止的選擇：

152

153* **`/model`**：切換被拒絕並出現錯誤

154* **`--model` 旗標、`ANTHROPIC_MODEL` 或 `model` 設定**：該值在啟動時被替換為警告，命名所要求和替代的模型，會話會在預設模型上啟動

155* **子代理、技能或命令覆蓋**：覆蓋會回退到繼承或預設模型，而不是使請求失敗

156* **`advisorModel` 設定**：該會話的顧問被停用

157* **`--advisor` 旗標**：Claude Code 在啟動時以錯誤退出

158

159排除的模型會從 `/model` 選擇器中隱藏。{/* min-version: 2.1.199 */}清單中沒有內建選擇器列的完整模型 ID（例如清單固定的較舊版本）會在 `/model` 選擇器中顯示為其自己的標記列。在 v2.1.199 之前，此類 ID 只能透過輸入 `/model <id>` 選擇。

160

161Claude Code 代表您進行的模型變更會以相同方式檢查：

137 162

138自動模型變更的檢查方式相同：[後備模型鏈](#fallback-model-chains)中清單外的元素會被捨棄，計畫模式升級（例如 [`opusplan`](#opusplan-model-setting)）到排除的模型會被跳過，以便計畫在會話的模型上繼續進行，而[自動模型後備](#automatic-model-fallback)的目標被排除時不會執行，因此標記的請求會以拒絕結束。當會話之後執行的模型在允許清單外時，啟用[快速模式](/zh-TW/fast-mode)會被拒絕。163* **[後備模型鏈](#fallback-model-chains)**：清單外的元素會被捨棄

164* **Plan Mode 升級**：在 Anthropic API 和 AWS 上的 Claude Platform 上，升級（例如 [`opusplan`](#opusplan-model-setting)）到排除的模型會使用升級系列的最新允許版本。在具有提供者特定模型 ID 的提供者上，以及當沒有版本被允許時，升級會被跳過，計畫會在會話的模型上繼續

165* **[自動模型後備](#automatic-model-fallback)**：目標被排除的後備不會執行，因此標記的請求會以拒絕結束

166* **[快速模式](/zh-TW/fast-mode)**：當會話之後執行的模型在允許清單外時，啟用快速模式會被拒絕

139 167

140```json theme={null}168```json theme={null}

141{169{

156 184

157* 雲端會話在[網路上的 Claude Code](/zh-TW/claude-code-on-the-web) 或桌面應用程式中執行，在 Anthropic 管理的 VM 上執行：部署到您的裝置的設定無法到達它們，因此請透過伺服器管理設定傳遞允許清單。雲端會話中的中途會話模型切換在要求的模型被允許清單排除時被拒絕。會話建立時的伺服器端拒絕適用於[組織模型限制](#organization-model-restrictions)，而不是 `availableModels` 設定鍵。185* 雲端會話在[網路上的 Claude Code](/zh-TW/claude-code-on-the-web) 或桌面應用程式中執行，在 Anthropic 管理的 VM 上執行：部署到您的裝置的設定無法到達它們，因此請透過伺服器管理設定傳遞允許清單。雲端會話中的中途會話模型切換在要求的模型被允許清單排除時被拒絕。會話建立時的伺服器端拒絕適用於[組織模型限制](#organization-model-restrictions)，而不是 `availableModels` 設定鍵。

158* Cowork 是 Claude 桌面應用程式中的代理工作標籤，不是 Claude Code 表面，根據設計不接收伺服器管理設定。受管理設定檔在會話執行的位置存在時適用於 Cowork 會話；遠端 Cowork 會話在 Anthropic 管理的 VM 上執行，其中不存在裝置部署的檔案。186* Cowork 是 Claude 桌面應用程式中的代理工作標籤，不是 Claude Code 表面，根據設計不接收伺服器管理設定。受管理設定檔在會話執行的位置存在時適用於 Cowork 會話；遠端 Cowork 會話在 Anthropic 管理的 VM 上執行，其中不存在裝置部署的檔案。

159* [第三方提供者](/zh-TW/server-managed-settings#platform-availability)（例如 Bedrock、Vertex AI、Foundry 和 [AWS 上的 Claude Platform](/zh-TW/claude-platform-on-aws)）上的會話不接收伺服器管理設定，因此請在那裡透過 MDM 或受管理設定檔傳遞允許清單。187* [第三方提供者](/zh-TW/server-managed-settings#platform-availability)（例如 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 [AWS 上的 Claude Platform](/zh-TW/claude-platform-on-aws)）上的會話不接收伺服器管理設定，因此請在那裡透過 MDM 或受管理設定檔傳遞允許清單。

160* 伺服器管理傳遞也需要會話使用組織登入或直接設定的 API 金鑰進行驗證。只透過 [`apiKeyHelper`](/zh-TW/settings#available-settings) 指令碼產生金鑰的艦隊應透過 MDM 或受管理設定檔傳遞允許清單。188* 伺服器管理傳遞也需要會話使用組織登入或直接設定的 API 金鑰進行驗證。只透過 [`apiKeyHelper`](/zh-TW/settings#available-settings) 指令碼產生金鑰的艦隊應透過 MDM 或受管理設定檔傳遞允許清單。

161* 桌面代碼標籤也裝載 [SSH 會話](/zh-TW/desktop#ssh-sessions)，它們從執行所在的遠端主機讀取受管理設定檔。請參閱[桌面受管理設定](/zh-TW/desktop#managed-settings)。189* 桌面代碼標籤也裝載 [SSH 會話](/zh-TW/desktop#ssh-sessions)，它們從執行所在的遠端主機讀取受管理設定檔。請參閱[桌面受管理設定](/zh-TW/desktop#managed-settings)。

162* claude.ai 和桌面應用程式中的模型選擇器會隱藏或灰顯您組織的允許清單排除的模型。選擇器狀態是使用者的便利；強制執行發生在會話中。190* claude.ai 和桌面應用程式中的模型選擇器會隱藏或灰顯您組織的允許清單排除的模型。選擇器狀態是使用者的便利；強制執行發生在會話中。

228 Mantle 模型 ID256 Mantle 模型 ID

229</h3>257</h3>

230 258

231當[Bedrock Mantle 端點](/zh-TW/amazon-bedrock#use-the-mantle-endpoint)啟用時，`availableModels` 中以 `anthropic.` 開頭的項目會作為自訂選項新增到 `/model` 選擇器，並路由到 Mantle 端點。這是[為第三方部署固定模型](#pin-models-for-third-party-deployments)中描述的別名符合的例外。該設定仍然將選擇器限制為列出的項目，而 Mantle ID 嵌入系列名稱，因此它計為特定項目並停用該系列的萬用字元：在任何 Mantle ID 旁邊，列出您想要保持可選擇的版本前綴或完整 ID。請參閱[合併行為](#merge-behavior)。259當[Amazon Bedrock Mantle 端點](/zh-TW/amazon-bedrock#use-the-mantle-endpoint)啟用時，`availableModels` 中以 `anthropic.` 開頭的項目會作為自訂選項新增到 `/model` 選擇器，並路由到 Mantle 端點。這是[為第三方部署固定模型](#pin-models-for-third-party-deployments)中描述的別名符合的例外。該設定仍然將選擇器限制為列出的項目，而 Mantle ID 嵌入系列名稱，因此它計為特定項目並停用該系列的萬用字元：在任何 Mantle ID 旁邊，列出您想要保持可選擇的版本前綴或完整 ID。請參閱[合併行為](#merge-behavior)。

232 260

233<h3 id="organization-model-restrictions">261<h3 id="organization-model-restrictions">

234 組織模型限制262 組織模型限制

242 270

243受限制的模型會從 `/model` 選擇器中隱藏。使用 `--model`、`ANTHROPIC_MODEL` 環境變數或 `model` 設定按名稱選擇它會顯示通知 `Model "<name>" is restricted by your organization's settings. Using <model> instead.`，會話會在允許的模型上啟動。為受限制的模型輸入 `/model <name>` 會被拒絕，並顯示 `Model '<name>' is restricted by your organization's settings. Run /model to choose a different model.`，會話會保持其目前模型。271受限制的模型會從 `/model` 選擇器中隱藏。使用 `--model`、`ANTHROPIC_MODEL` 環境變數或 `model` 設定按名稱選擇它會顯示通知 `Model "<name>" is restricted by your organization's settings. Using <model> instead.`，會話會在允許的模型上啟動。為受限制的模型輸入 `/model <name>` 會被拒絕，並顯示 `Model '<name>' is restricted by your organization's settings. Run /model to choose a different model.`，會話會保持其目前模型。

244 272

273[模型系列別名](#restrict-model-selection)（例如 `opus`）解析為組織允許的其系列的最新版本，具有相同的替代通知。`/model <alias>` 只有在其系列的每個版本都被限制時才會被拒絕；使用 `--model`、`ANTHROPIC_MODEL` 或 `model` 設定設定的別名在該情況下仍在啟動時被替換。在 v2.1.205 之前，系列別名是根據其最新發佈版本單獨進行替代或拒絕的，即使允許了較舊版本。

274

245限制適用於組織範圍或按角色：275限制適用於組織範圍或按角色：

246 276

247* 在組織層級停用模型會將其移除給每個成員。277* 在組織層級停用模型會將其移除給每個成員。

249* Haiku 模型始終可用，無法停用，因此每個成員至少保留一個可用模型。279* Haiku 模型始終可用，無法停用，因此每個成員至少保留一個可用模型。

250* 存取變更在約一分鐘內對新請求生效；`/model` 選擇器在下次會話啟動時反映它。280* 存取變更在約一分鐘內對新請求生效；`/model` 選擇器在下次會話啟動時反映它。

251 281

252這兩個限制組合：只有當模型被 `availableModels` 允許且未被組織限制時，它才可選擇。組織限制會傳遞到 Anthropic API 和 [LLM 閘道](/zh-TW/llm-gateway)部署上的會話。Bedrock、Vertex AI、Foundry 和 AWS 上的 Claude Platform 上的會話不接收它們，因此請改為在這些提供者上使用 `availableModels`。282這兩個限制組合：只有當模型被 `availableModels` 允許且未被組織限制時，它才可選擇。組織限制會傳遞到 Anthropic API 和 [LLM 閘道](/zh-TW/llm-gateway)部署上的會話。Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 AWS 上的 Claude Platform 上的會話不接收它們，因此請改為在這些提供者上使用 `availableModels`。

253 283

254<h2 id="organization-default-model">284<h2 id="organization-default-model">

255 組織預設模型285 組織預設模型

308* **Max、Team Premium、Enterprise 隨用隨付和 Anthropic API**：預設為 Opus 4.8338* **Max、Team Premium、Enterprise 隨用隨付和 Anthropic API**：預設為 Opus 4.8

309* **AWS 上的 Claude Platform**：預設為 Opus 4.7339* **AWS 上的 Claude Platform**：預設為 Opus 4.7

310* **Pro、Team Standard 和 Enterprise 訂閱席位**：預設為 Sonnet 5340* **Pro、Team Standard 和 Enterprise 訂閱席位**：預設為 Sonnet 5

311* **Bedrock、Vertex 和 Foundry**：預設為 Sonnet 4.5341* **Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry**：預設為 Sonnet 4.5

312 342

313Enterprise 隨用隨付是指按使用量計費而非按訂閱席位計費的 Enterprise 組織。343Enterprise 隨用隨付是指按使用量計費而非按訂閱席位計費的 Enterprise 組織。

314 344

331 361

332Plan Mode Opus 階段使用與 `opus` 模型設定相同的 context window。在訂閱層級上，Opus 會[自動升級到 1M context](#extended-context)，`opusplan` 在 Plan Mode 中也會獲得升級。若要在您不在自動升級層級上時強制兩個階段都使用 1M context，請將模型設定為 `opusplan[1m]`。362Plan Mode Opus 階段使用與 `opus` 模型設定相同的 context window。在訂閱層級上，Opus 會[自動升級到 1M context](#extended-context)，`opusplan` 在 Plan Mode 中也會獲得升級。若要在您不在自動升級層級上時強制兩個階段都使用 1M context，請將模型設定為 `opusplan[1m]`。

333 363

334當 [`availableModels`](#restrict-model-selection) 排除 Opus 時，`opusplan` 在 Plan Mode 中保持在 Sonnet 上，而不是切換。同樣地，隱含的 Haiku 到 Sonnet Plan Mode 升級在 Sonnet 被排除時也適用相同情況。364當 [`availableModels`](#restrict-model-selection) 排除最新的 Opus 但允許較舊版本時，例如 `["sonnet", "claude-opus-4-6"]`，`opusplan` 會為計畫使用最新允許的 Opus，並且僅在排除每個 Opus 時才保持在 Sonnet 上。通常會在 Plan Mode 中升級到 Sonnet 的 Haiku 會話同樣會使用最新允許的 Sonnet，並且僅在排除每個 Sonnet 時才保持在 Haiku 上。在 v2.1.205 之前，當排除升級系列的最新版本時，Plan Mode 會保持在會話的模型上，即使允許清單允許較舊版本。

365

366較舊允許版本的替換適用於 Anthropic API 和 [Claude Platform on AWS](/zh-TW/claude-platform-on-aws)。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 Mantle 上，其部署使用提供者特定的模型 ID，當升級模型被排除時，Plan Mode 會保持在會話的模型上。

335 367

336如需混合方法，其中 Claude 在任務中途決定何時諮詢第二個模型，而不是在計畫邊界處切換，請參閱 [advisor tool](/zh-TW/advisor)。368如需混合方法，其中 Claude 在任務中途決定何時諮詢第二個模型，而不是在計畫邊界處切換，請參閱 [advisor tool](/zh-TW/advisor)。

337 369

397* 在 [non-interactive mode](/zh-TW/cli-reference#cli-flags) 和無法顯示提示的 SDK 整合中，標記的請求以拒絕結束輪次。429* 在 [non-interactive mode](/zh-TW/cli-reference#cli-flags) 和無法顯示提示的 SDK 整合中，標記的請求以拒絕結束輪次。

398* 當回退目標被 [`availableModels`](#restrict-model-selection) 阻止時，不會顯示提示。標記的請求以拒絕結束，與目標被阻止時的自動回退相同。430* 當回退目標被 [`availableModels`](#restrict-model-selection) 阻止時，不會顯示提示。標記的請求以拒絕結束，與目標被阻止時的自動回退相同。

399 431

400<h4 id="enable-fallback-on-bedrock-vertex-ai-and-foundry">432<h4 id="enable-fallback-on-bedrock-agent-platform-and-foundry">

401 在 Bedrock、Vertex AI 和 Foundry 上啟用回退433 在 Bedrock、Agent Platform 和 Foundry 上啟用回退

402</h4>434</h4>

403 435

404在 [Amazon Bedrock](/zh-TW/amazon-bedrock)、[Google Vertex AI](/zh-TW/google-vertex-ai) 和 [Microsoft Foundry](/zh-TW/microsoft-foundry) 上，模型 ID 是提供者特定的，因此自動回退僅在 Claude Code 可以識別涉及的兩個模型時運作：436在 [Amazon Bedrock](/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/zh-TW/google-vertex-ai) 和 [Microsoft Foundry](/zh-TW/microsoft-foundry) 上，模型 ID 是提供者特定的，因此自動回退僅在 Claude Code 可以識別涉及的兩個模型時運作：

405 437

406* Claude Code 必須將目前模型識別為 Fable 5：模型 ID 包含 `claude-fable-5`、符合 `ANTHROPIC_DEFAULT_FABLE_MODEL` 的值，或使用 [`modelOverrides`](#override-model-ids-per-version) 對應。438* Claude Code 必須將目前模型識別為 Fable 5：模型 ID 包含 `claude-fable-5`、符合 `ANTHROPIC_DEFAULT_FABLE_MODEL` 的值，或使用 [`modelOverrides`](#override-model-ids-per-version) 對應。

407* 回退目標必須解析為 Opus 模型：`ANTHROPIC_DEFAULT_OPUS_MODEL` 的值（如果設定），否則提供者模型清單中的 Opus 4.8 項目。439* 回退目標必須解析為 Opus 模型：`ANTHROPIC_DEFAULT_OPUS_MODEL` 的值（如果設定），否則提供者模型清單中的 Opus 4.8 項目。

434 466

435Fable 5、Sonnet 5、Opus 4.8、Opus 4.6 和 Sonnet 4.6 上的預設努力為 `high`，Opus 4.7 上的預設努力為 `xhigh`。467Fable 5、Sonnet 5、Opus 4.8、Opus 4.6 和 Sonnet 4.6 上的預設努力為 `high`，Opus 4.7 上的預設努力為 `xhigh`。

436 468

437當您首次執行 Fable 5、Opus 4.8 或 Opus 4.7 時，Claude Code 會應用該模型的預設努力，即使您之前為另一個模型設定了不同的等級：Fable 5 和 Opus 4.8 上的 `high`，以及 Opus 4.7 上的 `xhigh`。執行 `/effort` 以在切換後選擇不同的等級。469當您首次執行 Fable 5、Opus 4.8 或 Opus 4.7 時，Claude Code 會應用該模型的預設努力，即使您之前為另一個模型設定了不同的等級：Fable 5 和 Opus 4.8 上的 `high`，以及 Opus 4.7 上的 `xhigh`。執行 `/effort` 以在切換後選擇不同的等級。該預設值在會話間保持，直到您進行明確的努力選擇，例如在互動式會話中執行 `/effort` 或使用 `--effort` 啟動。{/* min-version: 2.1.205 */}在 [non-interactive mode](/zh-TW/headless) 中使用 `/effort` 設定的等級，使用 `-p` 旗標，僅適用於目前會話，不會儲存為您的預設值。非互動式 `/effort` 也無法釋放上述模型預設值保持：在 Fable 5、Opus 4.8 和 Opus 4.7 上，它報告 `Not applied`，會話保持在模型的預設努力，因此改為在啟動時傳遞 `--effort`。`max` 提供最深入的推理，對 token 支出沒有限制，並且僅適用於目前會話，除非透過 `CLAUDE_CODE_EFFORT_LEVEL` 環境變數設定。

470

471`/effort` 選單也提供 `ultracode`。Ultracode 是 Claude Code 設定而非模型努力等級：它向模型發送 `xhigh`，並額外讓 Claude 為實質性任務協調[動態工作流程](/zh-TW/workflows)。它僅適用於目前會話。

472

473您可以透過以下任何方式開啟 ultracode：

438 474

439`low`、`medium`、`high` 和 `xhigh` 在會話間持續存在。`max` 提供最深入的推理，對 token 支出沒有限制，並且僅適用於目前會話，除非透過 `CLAUDE_CODE_EFFORT_LEVEL` 環境變數設定。475* **`/effort`**：執行 `/effort ultracode`，或從選單中選擇它

476* **`--effort` 旗標**：使用 `claude --effort ultracode` 啟動，這會以 `xhigh` 努力和 ultracode 開啟會話

477* **`--settings` 或 Agent SDK 控制請求**：傳遞 `"ultracode": true`。[`applyFlagSettings()`](/zh-TW/agent-sdk/typescript#applyflagsettings) 請求也接受 `effortLevel: "ultracode"`

440 478

441`/effort` 選單也提供 `ultracode`。Ultracode 是 Claude Code 設定而非模型努力等級：它向模型發送 `xhigh`，並額外讓 Claude 為實質性任務協調[動態工作流程](/zh-TW/workflows)。它僅適用於目前會話。透過 `/effort` 設定，或透過 `--settings` 或 Agent SDK 控制請求傳遞 `"ultracode": true`。它不是 `effortLevel` 設定、`--effort` 旗標或 `CLAUDE_CODE_EFFORT_LEVEL` 的一部分。479將 `ultracode` 傳遞給 `--effort` 旗標或 Agent SDK `effortLevel` 值需要 Claude Code v2.1.203 或更新版本。在 v2.1.203 之前，`--effort ultracode` 列印 `Unknown --effort value 'ultracode'`，會話以預設努力啟動。

480

481持續的 `effortLevel` 設定和 `CLAUDE_CODE_EFFORT_LEVEL` 環境變數不接受 `ultracode`。

482

483當 ultracode 不可用時，例如當[工作流程被關閉](/zh-TW/workflows#turn-workflows-off)時，`--effort ultracode` 僅設定 `xhigh` 努力。

442 484

443<h4 id="choose-an-effort-level">485<h4 id="choose-an-effort-level">

444 選擇努力等級486 選擇努力等級

595 為第三方部署固定模型637 為第三方部署固定模型

596</h3>638</h3>

597 639

598當透過 [Bedrock](/zh-TW/amazon-bedrock)、[Vertex AI](/zh-TW/google-vertex-ai)、[Foundry](/zh-TW/microsoft-foundry) 或 [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 部署 Claude Code 時，在向使用者推出前固定模型版本。640當透過 [Amazon Bedrock](/zh-TW/amazon-bedrock)、[Google Cloud's Agent Platform](/zh-TW/google-vertex-ai)、[Microsoft Foundry](/zh-TW/microsoft-foundry) 或 [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 部署 Claude Code 時，在向使用者推出前固定模型版本。

599 641

600不固定模型時，Claude Code 使用模型別名（例如 `fable`、`opus`、`sonnet` 和 `haiku`），這些別名會解析為每個提供者的內建預設模型 ID。該預設值可能落後於最新的 Anthropic 版本，而且它指向的模型可能尚未在使用者的帳戶中啟用。當預設值不可用時，Bedrock 和 Vertex AI 使用者會看到通知並回退到該會話的先前版本，而 Foundry 使用者會看到錯誤，因為 Foundry 沒有等效的啟動檢查。642不固定模型時，Claude Code 使用模型別名（例如 `fable`、`opus`、`sonnet` 和 `haiku`），這些別名會解析為每個提供者的內建預設模型 ID。該預設值可能落後於最新的 Anthropic 版本，而且它指向的模型可能尚未在使用者的帳戶中啟用。當預設值不可用時，Amazon Bedrock 和 Google Cloud's Agent Platform 使用者會看到通知並回退到該會話的先前版本，而 Microsoft Foundry 使用者會看到錯誤，因為 Microsoft Foundry 沒有等效的啟動檢查。

601 643

602<Warning>644<Warning>

603 在初始設定中將模型環境變數設定為特定版本 ID。固定讓您控制使用者何時移動到新模型。645 在初始設定中將模型環境變數設定為特定版本 ID。固定讓您控制使用者何時移動到新模型。

606使用以下環境變數搭配您提供者的版本特定模型 ID：648使用以下環境變數搭配您提供者的版本特定模型 ID：

607 649

608| 提供者 | 範例 |650| 提供者 | 範例 |

609| :-------- | :------------------------------------------------------------------- |651| :---------------------------- | :------------------------------------------------------------------- |

613 655

614對 `ANTHROPIC_DEFAULT_FABLE_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 應用相同的模式。有關所有提供者的目前和舊版模型 ID，請參閱[模型概述](https://platform.claude.com/docs/en/about-claude/models/overview)。若要將使用者升級到新模型版本，請更新這些環境變數並重新部署。656對 `ANTHROPIC_DEFAULT_FABLE_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 應用相同的模式。有關所有提供者的目前和舊版模型 ID，請參閱[模型概述](https://platform.claude.com/docs/en/about-claude/models/overview)。若要將使用者升級到新模型版本，請更新這些環境變數並重新部署。

615 657

623 665

624* Claude Code 在將模型 ID 發送到您的提供者之前會移除該後綴。666* Claude Code 在將模型 ID 發送到您的提供者之前會移除該後綴。

625* 只有當基礎模型[支援 1M context](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window) 時，才附加 `[1m]`。667* 只有當基礎模型[支援 1M context](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window) 時，才附加 `[1m]`。

626* 後綴是按變數讀取的，而不是按模型讀取的。在 Bedrock、Vertex 和 Foundry 上，一個變數中沒有 `[1m]` 的模型 ID 會使用 200K context，即使另一個變數設定相同的模型並帶有後綴。Sonnet 5 在這些提供者上始終以 1M window 執行，永遠不需要後綴。668* 後綴是按變數讀取的，而不是按模型讀取的。在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上，一個變數中沒有 `[1m]` 的模型 ID 會使用 200K context，即使另一個變數設定相同的模型並帶有後綴。Sonnet 5 在這些提供者上始終以 1M window 執行，永遠不需要後綴。

627 669

628<Note>670<Note>

629 使用第三方提供者時，透過 [MDM 或受管設定檔](/zh-TW/settings#settings-files) 傳遞的 `availableModels` 允許清單仍然適用；[伺服器管理的設定不會在那裡傳遞](/zh-TW/server-managed-settings#platform-availability)。篩選會根據模型別名（例如 `opus`）、版本前綴（例如 `claude-opus-4-8`）或完整提供者形式模型 ID 進行匹配。提供者特定的前綴（例如 `us.anthropic.`）不會被移除，因此若要允許特定模型，請列出選擇器顯示的相同提供者形式 ID，或透過 [`modelOverrides`](#override-model-ids-per-version) 對應它。任何 `[1m]` 後綴會從允許清單項目和請求的模型中移除，然後進行匹配。671 使用第三方提供者時，透過 [MDM 或受管設定檔](/zh-TW/settings#settings-files) 傳遞的 `availableModels` 允許清單仍然適用；[伺服器管理的設定不會在那裡傳遞](/zh-TW/server-managed-settings#platform-availability)。篩選會根據模型別名（例如 `opus`）、版本前綴（例如 `claude-opus-4-8`）或完整提供者形式模型 ID 進行匹配。提供者特定的前綴（例如 `us.anthropic.`）不會被移除，因此若要允許特定模型，請列出選擇器顯示的相同提供者形式 ID，或透過 [`modelOverrides`](#override-model-ids-per-version) 對應它。任何 `[1m]` 後綴會從允許清單項目和請求的模型中移除，然後進行匹配。

635 677

636當您在第三方提供者上固定模型時，提供者特定的 ID 會按原樣出現在 `/model` 選擇器中，Claude Code 可能無法識別模型支援的功能。您可以使用每個固定模型的伴隨環境變數覆蓋顯示名稱並宣告能力。678當您在第三方提供者上固定模型時，提供者特定的 ID 會按原樣出現在 `/model` 選擇器中，Claude Code 可能無法識別模型支援的功能。您可以使用每個固定模型的伴隨環境變數覆蓋顯示名稱並宣告能力。

637 679

638這些變數在 Bedrock、Vertex AI 和 Foundry 等第三方提供者上生效。`_NAME` 和 `_DESCRIPTION` 變數在 `ANTHROPIC_BASE_URL` 指向 [LLM gateway](/zh-TW/llm-gateway) 時也會生效。當直接連接到 `api.anthropic.com` 時無效。680這些變數在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 等第三方提供者上生效。`_NAME` 和 `_DESCRIPTION` 變數在 `ANTHROPIC_BASE_URL` 指向 [LLM gateway](/zh-TW/llm-gateway) 時也會生效。當直接連接到 `api.anthropic.com` 時無效。

639 681

640| 環境變數 | 描述 |682| 環境變數 | 描述 |

641| ----------------------------------------------------- | -------------------------------------------------------- |683| ----------------------------------------------------- | -------------------------------------------------------- |

645 687

646相同的 `_NAME`、`_DESCRIPTION` 和 `_SUPPORTED_CAPABILITIES` 後綴可用於 `ANTHROPIC_DEFAULT_SONNET_MODEL`、`ANTHROPIC_DEFAULT_HAIKU_MODEL`、`ANTHROPIC_DEFAULT_FABLE_MODEL` 和 `ANTHROPIC_CUSTOM_MODEL_OPTION`。688相同的 `_NAME`、`_DESCRIPTION` 和 `_SUPPORTED_CAPABILITIES` 後綴可用於 `ANTHROPIC_DEFAULT_SONNET_MODEL`、`ANTHROPIC_DEFAULT_HAIKU_MODEL`、`ANTHROPIC_DEFAULT_FABLE_MODEL` 和 `ANTHROPIC_CUSTOM_MODEL_OPTION`。

647 689

648Claude Code 透過將模型 ID 與已知模式進行匹配來啟用[努力等級](#adjust-effort-level)和[擴展思考](#extended-thinking)等功能。提供者特定的 ID（例如 Bedrock ARN 或自訂部署名稱）通常不符合這些模式，導致支援的功能被禁用。設定 `_SUPPORTED_CAPABILITIES` 以告訴 Claude Code 模型實際支援的功能：690Claude Code 透過將模型 ID 與已知模式進行匹配來啟用[努力等級](#adjust-effort-level)和[擴展思考](#extended-thinking)等功能。提供者特定的 ID（例如 Amazon Bedrock ARN 或自訂部署名稱）通常不符合這些模式，導致支援的功能被禁用。設定 `_SUPPORTED_CAPABILITIES` 以告訴 Claude Code 模型實際支援的功能：

649 691

650| 能力值 | 啟用 |692| 能力值 | 啟用 |

651| ---------------------- | ------------------------------------------ |693| ---------------------- | ------------------------------------------ |

658 700

659當設定 `_SUPPORTED_CAPABILITIES` 時，列出的能力會為匹配的固定模型啟用，未列出的能力會被禁用。當變數未設定時，Claude Code 會回退到基於模型 ID 的內建檢測。701當設定 `_SUPPORTED_CAPABILITIES` 時，列出的能力會為匹配的固定模型啟用，未列出的能力會被禁用。當變數未設定時，Claude Code 會回退到基於模型 ID 的內建檢測。

660 702

661此範例將 Opus 固定到 Bedrock 自訂模型 ARN，設定友善名稱，並宣告其能力：703此範例將 Opus 固定到 Amazon Bedrock 自訂模型 ARN，設定友善名稱，並宣告其能力：

662 704

663```bash theme={null}705```bash theme={null}

664export ANTHROPIC_DEFAULT_OPUS_MODEL='arn:aws:bedrock:us-east-1:123456789012:custom-model/abc'706export ANTHROPIC_DEFAULT_OPUS_MODEL='arn:aws:bedrock:us-east-1:123456789012:custom-model/abc'

675 717

676`modelOverrides` 將個別 Anthropic 模型 ID 對應到 Claude Code 發送到您提供者 API 的提供者特定字串。當使用者在 `/model` 選擇器中選擇對應的模型時，Claude Code 會使用您配置的值而不是內建預設值。718`modelOverrides` 將個別 Anthropic 模型 ID 對應到 Claude Code 發送到您提供者 API 的提供者特定字串。當使用者在 `/model` 選擇器中選擇對應的模型時，Claude Code 會使用您配置的值而不是內建預設值。

677 719

678這讓企業管理員可以將每個模型版本路由到特定的 Bedrock 推論設定檔 ARN、Vertex AI 版本名稱或 Foundry 部署名稱，以進行治理、成本分配或區域路由。720這讓企業管理員可以將每個模型版本路由到特定的 Amazon Bedrock 推論設定檔 ARN、Google Cloud's Agent Platform 版本名稱或 Microsoft Foundry 部署名稱，以進行治理、成本分配或區域路由。

679 721

680在您的[設定檔](/zh-TW/settings#settings-files)中設定 `modelOverrides`：722在您的[設定檔](/zh-TW/settings#settings-files)中設定 `modelOverrides`：

681 723

691 733

692鍵必須是[模型概述](https://platform.claude.com/docs/en/about-claude/models/overview)中列出的 Anthropic 模型 ID。對於日期模型 ID，請包含日期後綴，完全如其所示。未知的鍵會被忽略。734鍵必須是[模型概述](https://platform.claude.com/docs/en/about-claude/models/overview)中列出的 Anthropic 模型 ID。對於日期模型 ID，請包含日期後綴，完全如其所示。未知的鍵會被忽略。

693 735

694覆蓋會取代支援 `/model` 選擇器中每個項目的內建模型 ID。在 Bedrock 上，覆蓋優先於 Claude Code 在啟動時自動發現的任何推論設定檔。您直接透過 `ANTHROPIC_MODEL`、`--model` 或 `ANTHROPIC_DEFAULT_*_MODEL` 環境變數提供的值會按原樣傳遞給提供者，不會由 `modelOverrides` 轉換。736覆蓋會取代支援 `/model` 選擇器中每個項目的內建模型 ID。在 Amazon Bedrock 上，`modelOverrides` 項目優先於 Claude Code 在啟動時自動發現的任何推論設定檔。Claude Code 會將已經是提供者原生的值（例如 Amazon Bedrock 推論設定檔 ARN 或 Microsoft Foundry 部署名稱）按原樣傳遞給提供者。

737

738{/* min-version: 2.1.200 */}當您直接透過 `--model`、`ANTHROPIC_MODEL` 環境變數或 `ANTHROPIC_DEFAULT_*_MODEL` 環境變數傳遞 Anthropic 模型 ID 時，覆蓋也會適用。在 Amazon Bedrock、Google Cloud's Agent Platform 和 [Mantle](/zh-TW/amazon-bedrock#use-the-mantle-endpoint) 上，沒有 `modelOverrides` 項目的 Anthropic 模型 ID 會解析為與該版本的 `/model` 選擇器列相同的提供者特定 ID（當提供者支援該版本時）。Mantle 支援版本的子集。對於該子集之外的 Anthropic 模型 ID，Claude Code 會將原始 ID 發送到 Mantle 而不進行對應，除非 `modelOverrides` 項目涵蓋它。在 v2.1.200 之前，`--model` 和環境變數值會按原樣到達提供者，不會通過覆蓋對應。

695 739

696`modelOverrides` 與 `availableModels` 一起運作。允許清單會根據 Anthropic 模型 ID 進行評估，而不是覆蓋值，因此 `availableModels` 中的項目（如 `"opus"`）即使 Opus 版本對應到 ARN 時仍會繼續匹配。當在受管設定中設定 `enforceAvailableModels` 時，強制執行的預設值會從[最高優先順序受管來源](/zh-TW/server-managed-settings#settings-precedence)透過 `modelOverrides` 解析。管理員的對應（例如固定到推論設定檔 ARN 的版本）會在強制執行的預設值中受到尊重。來自使用者或專案設定的覆蓋不會影響它。740`modelOverrides` 與 `availableModels` 一起運作。允許清單會根據 Anthropic 模型 ID 進行評估，而不是覆蓋值，因此 `availableModels` 中的項目（如 `"opus"`）即使 Opus 版本對應到 ARN 時仍會繼續匹配。當在受管設定中設定 `enforceAvailableModels` 時，強制執行的預設值會從[最高優先順序受管來源](/zh-TW/server-managed-settings#settings-precedence)透過 `modelOverrides` 解析。管理員的對應（例如固定到推論設定檔 ARN 的版本）會在強制執行的預設值中受到尊重。來自使用者或專案設定的覆蓋不會影響它。

697 741

742{/* min-version: 2.1.200 */}當 `availableModels` 在[受管設定](/zh-TW/settings#settings-files)中設定時，只有來自該受管來源的 `modelOverrides` 適用於直接透過 `--model` 或上述環境變數傳遞的 Anthropic 模型 ID。Claude Code 會忽略來自使用者或專案設定的這些 ID 的覆蓋，並且永遠不會透過來自任何設定來源的 `modelOverrides` 解析受管清單排除的 ID。此受管來源限制需要 Claude Code v2.1.200 或更新版本。請參閱[限制模型選擇](#restrict-model-selection)以瞭解如何處理被阻止的 ID。

743

698<h3 id="prompt-caching-configuration">744<h3 id="prompt-caching-configuration">

699 Prompt caching 配置745 Prompt caching 配置

700</h3>746</h3>

monitoring-usage.md +13 −7

Details

94| `OTEL_LOGS_EXPORT_INTERVAL` | 日誌匯出間隔（毫秒）（預設：5000） | `1000`、`10000` |94| `OTEL_LOGS_EXPORT_INTERVAL` | 日誌匯出間隔（毫秒）（預設：5000） | `1000`、`10000` |

95| `OTEL_LOG_USER_PROMPTS` | 啟用使用者提示內容的日誌記錄（預設：停用） | `1` 以啟用 |95| `OTEL_LOG_USER_PROMPTS` | 啟用使用者提示內容的日誌記錄（預設：停用） | `1` 以啟用 |

96| `OTEL_LOG_ASSISTANT_RESPONSES` | 啟用在 `assistant_response` 事件上記錄助手回應文字的日誌（預設：停用）。未設定時，會回退到 `OTEL_LOG_USER_PROMPTS` 的值。{/* min-version: 2.1.193 */}需要 Claude Code v2.1.193 或更新版本 | `1` 以啟用，`0` 以保持編輯 |96| `OTEL_LOG_ASSISTANT_RESPONSES` | 啟用在 `assistant_response` 事件上記錄助手回應文字的日誌（預設：停用）。未設定時，會回退到 `OTEL_LOG_USER_PROMPTS` 的值。{/* min-version: 2.1.193 */}需要 Claude Code v2.1.193 或更新版本 | `1` 以啟用，`0` 以保持編輯 |

97| `OTEL_LOG_TOOL_DETAILS` | 啟用在工具事件和追蹤跨度屬性中記錄工具參數和輸入引數的日誌：Bash 命令、MCP 伺服器和工具名稱、Skill 名稱和工具輸入。也在 `user_prompt` 事件上啟用自訂、plugin 和 MCP 命令名稱（預設：停用） | `1` 以啟用 |97| `OTEL_LOG_TOOL_DETAILS` | 啟用在工具事件和追蹤跨度屬性中記錄工具參數和輸入引數的日誌：Bash 命令、MCP 伺服器和工具名稱、Skill 名稱、使用者撰寫的工作流程名稱和工具輸入。也在 `user_prompt` 事件上啟用自訂、plugin 和 MCP 命令名稱（預設：停用） | `1` 以啟用 |

98| `OTEL_LOG_TOOL_CONTENT` | 啟用在跨度事件中記錄工具輸入和輸出內容的日誌（預設：停用）。需要[追蹤](#traces-beta)。內容在 60 KB 處截斷 | `1` 以啟用 |98| `OTEL_LOG_TOOL_CONTENT` | 啟用在跨度事件中記錄工具輸入和輸出內容的日誌（預設：停用）。需要[追蹤](#traces-beta)。內容在 60 KB 處截斷 | `1` 以啟用 |

99| `OTEL_LOG_RAW_API_BODIES` | 將完整的 Anthropic Messages API 請求和回應 JSON 作為 `api_request_body` / `api_response_body` 日誌事件發出（預設：停用）。主體包括整個對話歷史記錄。啟用此選項意味著同意 `OTEL_LOG_USER_PROMPTS`、`OTEL_LOG_TOOL_DETAILS` 和 `OTEL_LOG_TOOL_CONTENT` 會揭露的所有內容 | `1` 用於在 60 KB 處截斷的內聯主體，或 `file:<dir>` 用於磁碟上未截斷的主體，事件中有 `body_ref` 指標 |99| `OTEL_LOG_RAW_API_BODIES` | 將完整的 Anthropic Messages API 請求和回應 JSON 作為 `api_request_body` / `api_response_body` 日誌事件發出（預設：停用）。主體包括整個對話歷史記錄。啟用此選項意味著同意 `OTEL_LOG_USER_PROMPTS`、`OTEL_LOG_TOOL_DETAILS` 和 `OTEL_LOG_TOOL_CONTENT` 會揭露的所有內容 | `1` 用於在 60 KB 處截斷的內聯主體，或 `file:<dir>` 用於磁碟上未截斷的主體，事件中有 `body_ref` 指標 |

191**`claude_code.llm_request`**191**`claude_code.llm_request`**

192 192

193| 屬性 | 描述 | 由以下控制 |193| 屬性 | 描述 | 由以下控制 |

194| -------------------------------- | --------------------------------------------------------------------------------------------------- | ----- |194| -------------------------------- | --------------------------------------------------------------------------------------------------- | ----------------------- |

201| `workflow.run_id` | [Workflow](/zh-TW/workflows) 工具執行的執行識別碼，前綴為 `wf_`，該執行產生了此代理。對於不是由工作流程產生的代理不存在 | |

202| `workflow.name` | 產生此代理的工作流程名稱。使用者撰寫的名稱會被替換為 `custom`，除非設定了閘道 | `OTEL_LOG_TOOL_DETAILS` |

233| `workflow.run_id` | 產生此代理的 Workflow 工具執行的執行識別碼，前綴為 `wf_`。對於不是由工作流程產生的代理不存在 | |

234| `workflow.name` | 產生此代理的工作流程名稱。使用者撰寫的名稱會被替換為 `custom`，除非設定了閘道 | `OTEL_LOG_TOOL_DETAILS` |

231| `tool_use_id` | 此呼叫的模型 `tool_use` 區塊 id。符合[工具結果](#tool-result-event)和[工具決定](#tool-decision-event)事件上的 `tool_use_id` 以及 hook 承載中的 `tool_use_id`，因此您可以將跨度連結到這些記錄 | |235| `tool_use_id` | 此呼叫的模型 `tool_use` 區塊 id。符合[工具結果](#tool-result-event)和[工具決定](#tool-decision-event)事件上的 `tool_use_id` 以及 hook 承載中的 `tool_use_id`，因此您可以將跨度連結到這些記錄 | |

309 313

310如果協助程式失敗或列印不符合這些要求的輸出，Claude Code 會在以下位置報告錯誤：314如果協助程式失敗或列印不符合這些要求的輸出，Claude Code 會在以下位置報告錯誤：

311 315

312* `/doctor` 輸出316* `/status` 輸出

313* 使用 [`--debug`](/zh-TW/cli-reference#cli-flags) 執行或在工作階段中執行 `/debug` 後的除錯日誌317* 使用 [`--debug`](/zh-TW/cli-reference#cli-flags) 執行或在工作階段中執行 `/debug` 後的除錯日誌

314* stderr，在以 `-p` 啟動的非互動式工作階段中318* stderr，在以 `-p` 啟動的非互動式工作階段中

315 319

443 447

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

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

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

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

446 452

447<h3 id="metrics">453<h3 id="metrics">

448 指標454 指標

884 內部錯誤事件890 內部錯誤事件

885</h4>891</h4>

886 892

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

888 894

889**事件名稱**：`claude_code.internal_error`895**事件名稱**：`claude_code.internal_error`

890 896

1163* 透過 `skill.name`、`plugin.name` 和 `agent.name` 屬性將支出歸因於特定技能、外掛程式或子代理類型1169* 透過 `skill.name`、`plugin.name` 和 `agent.name` 屬性將支出歸因於特定技能、外掛程式或子代理類型

1164 1170

1165<Note>1171<Note>

1166 成本指標是近似值。如需官方帳單資料，請參閱您的 API 提供者（Claude Console、Amazon Bedrock 或 Google Cloud Vertex）。1172 成本指標是近似值。如需官方帳單資料，請參閱您的 API 提供者（Claude Console、Amazon Bedrock 或 Google Cloud 的 Agent Platform）。

1167</Note>1173</Note>

1168 1174

1169<h3 id="alerting-and-segmentation">1175<h3 id="alerting-and-segmentation">

1217 1223

1218MCP 工具呼叫、Bash 命令和檔案編輯因此歸因於啟動工作階段的開發人員。Claude Code 不在單獨的服務帳戶下運作；每個事件上記錄的身份是開發人員自己的 Claude 帳戶，或開發人員在 [Claude apps gateway](/zh-TW/claude-apps-gateway) 工作階段上的 IdP 身份。1224MCP 工具呼叫、Bash 命令和檔案編輯因此歸因於啟動工作階段的開發人員。Claude Code 不在單獨的服務帳戶下運作；每個事件上記錄的身份是開發人員自己的 Claude 帳戶，或開發人員在 [Claude apps gateway](/zh-TW/claude-apps-gateway) 工作階段上的 IdP 身份。

1219 1225

1220當 Claude Code 使用直接 API 金鑰進行身份驗證，或針對 Bedrock、Vertex AI 或 Microsoft Foundry 進行身份驗證時，工作階段中沒有 Claude 帳戶，僅填充 `user.id` 和 `session.id`。在這些部署中，使用 `OTEL_RESOURCE_ATTRIBUTES` 自行附加使用者身份，透過[受管設定](#administrator-configuration)檔案或啟動包裝器按使用者設定。Claude apps gateway 工作階段不需要任何這些：CLI 會自動標記 IdP 身份，如[標準屬性](#standard-attributes)中所述。1226當 Claude Code 使用直接 API 金鑰進行身份驗證，或針對 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 進行身份驗證時，工作階段中沒有 Claude 帳戶，僅填充 `user.id` 和 `session.id`。在這些部署中，使用 `OTEL_RESOURCE_ATTRIBUTES` 自行附加使用者身份，透過[受管設定](#administrator-configuration)檔案或啟動包裝器按使用者設定。Claude apps gateway 工作階段不需要任何這些：CLI 會自動標記 IdP 身份，如[標準屬性](#standard-attributes)中所述。

1221 1227

1222```bash theme={null}1228```bash theme={null}

1223export OTEL_RESOURCE_ATTRIBUTES="enduser.id=jdoe@example.com,enduser.directory_id=S-1-5-21-..."1229export OTEL_RESOURCE_ATTRIBUTES="enduser.id=jdoe@example.com,enduser.directory_id=S-1-5-21-..."

1352 在 Amazon Bedrock 上監控 Claude Code1358 在 Amazon Bedrock 上監控 Claude Code

1353</h2>1359</h2>

1354 1360

1355如需 Amazon Bedrock 上 Claude Code 使用情況監控的詳細指南，請參閱 [Claude Code 監控實作 (Bedrock)](https://github.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock/blob/main/assets/docs/MONITORING.md)。1361如需 Amazon Bedrock 上 Claude Code 使用情況監控的詳細指南，請參閱 [Claude Code 監控實作 (Amazon Bedrock)](https://github.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock/blob/main/assets/docs/MONITORING.md)。

network-config.md +3 −1

Details

110export CLAUDE_CODE_CLIENT_KEY_PASSPHRASE="your-passphrase"110export CLAUDE_CODE_CLIENT_KEY_PASSPHRASE="your-passphrase"

111```111```

112 112

113Claude Code 在啟動時讀取憑證和金鑰檔案，並在每次套用設定時重新讀取它們，包括在工作階段期間設定變更時。若要輪換憑證和金鑰，請取代相同路徑上的檔案。

114

113<h2 id="network-access-requirements">115<h2 id="network-access-requirements">

114 網路存取需求116 網路存取需求

115</h2>117</h2>

131 133

132Claude Code 預設也會傳送選用的操作遙測，您可以使用環境變數停用此功能。請參閱[遙測服務](/zh-TW/data-usage#telemetry-services)以了解如何在完成允許清單之前停用它。134Claude Code 預設也會傳送選用的操作遙測，您可以使用環境變數停用此功能。請參閱[遙測服務](/zh-TW/data-usage#telemetry-services)以了解如何在完成允許清單之前停用它。

133 135

134使用 [Amazon Bedrock](/zh-TW/amazon-bedrock)、[Google Vertex AI](/zh-TW/google-vertex-ai)、[Microsoft Foundry](/zh-TW/microsoft-foundry) 或已登入的 [Claude 應用程式閘道](/zh-TW/claude-apps-gateway)工作階段時，模型流量和驗證會傳送到您的提供者或閘道，而不是 `api.anthropic.com`、`claude.ai` 或 `platform.claude.com`。WebFetch 工具仍會呼叫 `api.anthropic.com` 進行其[網域安全檢查](/zh-TW/data-usage#webfetch-domain-safety-check)，除非您在[設定](/zh-TW/settings)中設定 `skipWebFetchPreflight: true`。136使用 [Amazon Bedrock](/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/zh-TW/google-vertex-ai)、[Microsoft Foundry](/zh-TW/microsoft-foundry) 或已登入的 [Claude 應用程式閘道](/zh-TW/claude-apps-gateway)工作階段時，模型流量和驗證會傳送到您的提供者或閘道，而不是 `api.anthropic.com`、`claude.ai` 或 `platform.claude.com`。WebFetch 工具仍會呼叫 `api.anthropic.com` 進行其[網域安全檢查](/zh-TW/data-usage#webfetch-domain-safety-check)，除非您在[設定](/zh-TW/settings)中設定 `skipWebFetchPreflight: true`。

135 137

136[Claude Code on the web](/zh-TW/claude-code-on-the-web) 和 [Code Review](/zh-TW/code-review) 從 Anthropic 管理的基礎設施連線到您的儲存庫。如果您的 GitHub Enterprise Cloud 組織按 IP 位址限制存取，請啟用[已安裝 GitHub Apps 的 IP 允許清單繼承](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization#allowing-access-by-github-apps)。Claude GitHub App 會註冊其 IP 範圍，因此啟用此設定可允許存取而無需手動設定。若要[手動將範圍新增到允許清單](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization#adding-an-allowed-ip-address)，或設定其他防火牆，請參閱 [Anthropic API IP 位址](https://platform.claude.com/docs/en/api/ip-addresses)。138[Claude Code on the web](/zh-TW/claude-code-on-the-web) 和 [Code Review](/zh-TW/code-review) 從 Anthropic 管理的基礎設施連線到您的儲存庫。如果您的 GitHub Enterprise Cloud 組織按 IP 位址限制存取，請啟用[已安裝 GitHub Apps 的 IP 允許清單繼承](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization#allowing-access-by-github-apps)。Claude GitHub App 會註冊其 IP 範圍，因此啟用此設定可允許存取而無需手動設定。若要[手動將範圍新增到允許清單](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization#adding-an-allowed-ip-address)，或設定其他防火牆，請參閱 [Anthropic API IP 位址](https://platform.claude.com/docs/en/api/ip-addresses)。

137 139

overview.md +2 −2

Details

12 開始使用12 開始使用

13</h2>13</h2>

14 14

15選擇您的環境以開始使用。大多數介面需要 [Claude 訂閱](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=overview_pricing)或 [Anthropic Console](https://console.anthropic.com/) 帳戶。終端機 CLI 和 VS Code 也支援[第三方提供商](/zh-TW/third-party-integrations)。15Claude Code 在多個平台上執行：終端機、IDE 擴充功能、桌面應用程式和網頁。從下方的標籤中選擇一個以開始使用。大多數平台需要 [Claude 訂閱](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=overview_pricing)或 [Anthropic Console](https://console.anthropic.com/) 帳戶。終端機 CLI 和 VS Code 也支援[第三方提供商](/zh-TW/third-party-integrations)。

16 16

17<Tabs>17<Tabs>

18 <Tab title="終端機">18 <Tab title="終端機">

221 在任何地方使用 Claude Code221 在任何地方使用 Claude Code

222</h2>222</h2>

223 223

224每個介面都連接到相同的基礎 Claude Code 引擎，因此您的 CLAUDE.md 檔案、設定和 MCP servers 可在所有介面中工作。224每個[介面](/zh-TW/glossary#surface)都連接到相同的基礎 Claude Code 引擎，因此您的 CLAUDE.md 檔案、設定和 MCP servers 可在所有介面中工作。

225 225

226除了上述[終端機](/zh-TW/quickstart)、[VS Code](/zh-TW/vs-code)、[JetBrains](/zh-TW/jetbrains)、[桌面](/zh-TW/desktop)和[網頁](/zh-TW/claude-code-on-the-web)環境外，Claude Code 還與 CI/CD、聊天和瀏覽器工作流程整合：226除了上述[終端機](/zh-TW/quickstart)、[VS Code](/zh-TW/vs-code)、[JetBrains](/zh-TW/jetbrains)、[桌面](/zh-TW/desktop)和[網頁](/zh-TW/claude-code-on-the-web)環境外，Claude Code 還與 CI/CD、聊天和瀏覽器工作流程整合：

227 227

permission-modes.md +45 −20

Details

6 6

7> 控制 Claude 是否在編輯檔案或執行命令前詢問。在 CLI 中使用 Shift+Tab 循環模式，或在 VS Code、Desktop 和 claude.ai 中使用模式選擇器。7> 控制 Claude 是否在編輯檔案或執行命令前詢問。在 CLI 中使用 Shift+Tab 循環模式，或在 VS Code、Desktop 和 claude.ai 中使用模式選擇器。

8 8

9當 Claude 想要編輯檔案、執行 shell 命令或進行網路請求時，它會暫停並要求您批准該操作。權限模式控制該暫停發生的頻率。您選擇的模式塑造了會話的流程：預設模式讓您在操作進行時審查每個操作，而較寬鬆的模式讓 Claude 在較長的不間斷時間內工作並在完成時報告。對敏感工作選擇更多監督，或在您信任方向時選擇較少中斷。9當 Claude 想要編輯檔案、執行 shell 命令或進行網路請求時，它會暫停並要求您批准該操作。權限模式控制該暫停發生的頻率。您選擇的模式塑造了會話的流程：Manual mode 讓您在操作進行時審查每個操作，而較寬鬆的模式讓 Claude 在較長的不間斷時間內工作並在完成時報告。對敏感工作選擇更多監督，或在您信任方向時選擇較少中斷。

10 10

11<h2 id="available-modes">11<h2 id="available-modes">

12 可用模式12 可用模式

16 16

17| 模式 | 無需詢問即可執行的操作 | 最適合 |17| 模式 | 無需詢問即可執行的操作 | 最適合 |

18| :------------------------------------------------------------------ | :-------------------------------------------- | :-------------- |18| :------------------------------------------------------------------ | :-------------------------------------------- | :-------------- |

21| [`plan`](#analyze-before-you-edit-with-plan-mode) | 僅讀取 | 在變更前探索程式碼庫 |21| [`plan`](#analyze-before-you-edit-with-plan-mode) | 僅讀取 | 在變更前探索程式碼庫 |

25 25

26在 CLI、`claude --help` 中以及 VS Code 和 JetBrains 擴充功能中，審查每個操作的模式名為 **Manual**。其配置值為 `default`，這是 hooks 和 SDK 整合使用的值。CLI 在您輸入值的任何地方接受 `manual` 作為別名，例如 `claude --permission-mode manual` 或 `"defaultMode": "manual"`。Manual 標籤和 `manual` 別名需要 Claude Code v2.1.200 或更新版本。

26在除 `bypassPermissions` 外的每種模式中，寫入[受保護路徑](#protected-paths)永遠不會自動批准，保護倉庫狀態和 Claude 自己的配置免受意外損壞。28在除 `bypassPermissions` 外的每種模式中，寫入[受保護路徑](#protected-paths)永遠不會自動批准，保護倉庫狀態和 Claude 自己的配置免受意外損壞。

27 29

28模式設定基線。在頂部分層[權限規則](/zh-TW/permissions#manage-permissions)以預先批准或阻止特定工具。拒絕規則和明確詢問規則適用於每種模式，包括 `bypassPermissions`。允許規則在該模式中無效，因為其他所有操作都已經被批准。30模式設定基線。在頂部分層[權限規則](/zh-TW/permissions#manage-permissions)以預先批准或阻止特定工具。拒絕規則和明確詢問規則適用於每種模式，包括 `bypassPermissions`。允許規則在該模式中無效，因為其他所有操作都已經被批准。

35 37

36<Tabs>38<Tabs>

37 <Tab title="CLI">39 <Tab title="CLI">

~~38 **在會話期間**：按 `Shift+Tab` 循環 `default` → `acceptEdits` → `plan`。目前模式出現在狀態欄中。並非每種模式都在預設循環中：~~40 **在會話期間**：按 `Shift+Tab` 循環 `default` → `acceptEdits` → `plan`。目前模式出現在狀態欄中。{/* min-version: 2.1.203 */}手動模式（該循環中的 `default`）顯示灰色的 `⏸ manual mode on` 徽章。在 v2.1.203 之前，狀態欄在手動模式中不顯示徽章。

42 並非每種模式都在預設循環中：

39 43

40 * `auto`：當您的帳戶符合 [auto 模式要求](#eliminate-prompts-with-auto-mode)時出現；循環到它會在不確認提示的情況下切換模式44 * `auto`：當您的帳戶符合 [auto 模式要求](#eliminate-prompts-with-auto-mode)時出現；循環到它會在不確認提示的情況下切換模式

41 * `bypassPermissions`：在您使用 `--permission-mode bypassPermissions`、`--dangerously-skip-permissions` 或 `--allow-dangerously-skip-permissions` 啟動後出現；`--allow-` 變體將模式添加到循環中而不啟動它45 * `bypassPermissions`：在您使用 `--permission-mode bypassPermissions`、`--dangerously-skip-permissions` 或 `--allow-dangerously-skip-permissions` 啟動後出現；`--allow-` 變體將模式添加到循環中而不啟動它

70 模式指示器顯示這些標籤，對應於每個標籤適用的模式：74 模式指示器顯示這些標籤，對應於每個標籤適用的模式：

71 75

72 | UI 標籤 | 模式 |76 | UI 標籤 | 模式 |

~~73 | :-------- | :------------------ |~~77 | :---- | :------------------ |

~~74 | 編輯前詢問 | `default` |~~78 | 手動 | `default` |

75 | 自動編輯 | `acceptEdits` |79 | 自動編輯 | `acceptEdits` |

78 | 繞過權限 | `bypassPermissions` |82 | 繞過權限 | `bypassPermissions` |

79 83

84 在 v2.1.205 之前，擴充將 `plan` 標記為 Plan mode，將 `auto` 標記為 Auto mode。

80 Auto mode 在您的帳戶符合 [auto 模式部分](#eliminate-prompts-with-auto-mode)中列出的每項要求時出現在模式指示器中。`claudeCode.initialPermissionMode` 設定不接受 `auto`。要預設啟動 auto mode，請改為在您的[使用者設定](/zh-TW/settings#settings-files)中設定 `defaultMode`。Claude Code 忽略專案和本機設定中的 `defaultMode: "auto"`。86 Auto mode 在您的帳戶符合 [auto 模式部分](#eliminate-prompts-with-auto-mode)中列出的每項要求時出現在模式指示器中。`claudeCode.initialPermissionMode` 設定不接受 `auto`。要預設啟動 auto mode，請改為在您的[使用者設定](/zh-TW/settings#settings-files)中設定 `defaultMode`。Claude Code 忽略專案和本機設定中的 `defaultMode: "auto"`。

81 87

82 繞過權限需要擴充設定中的**允許危險跳過權限**切換，然後才會在模式指示器中出現。88 繞過權限需要擴充設定中的**允許危險跳過權限**切換，然後才會在模式指示器中出現。

95 <Tab title="Web and mobile">101 <Tab title="Web and mobile">

96 在 [claude.ai/code](https://claude.ai/code) 或行動應用中使用提示框旁邊的模式下拉菜單。權限提示出現在 claude.ai 中以供批准。哪些模式出現取決於會話執行的位置：102 在 [claude.ai/code](https://claude.ai/code) 或行動應用中使用提示框旁邊的模式下拉菜單。權限提示出現在 claude.ai 中以供批准。哪些模式出現取決於會話執行的位置：

97 103

98 * **雲端會話**在 [Claude Code on the web](/zh-TW/claude-code-on-the-web)：Accept edits、Plan mode 和 Auto mode。Accept edits 對應於 `default` 模式：雲端環境預先批准檔案編輯，無論模式如何，因此下拉菜單顯示 Accept edits 而不是 Ask permissions。來自設定的 `defaultMode: "acceptEdits"` 仍然被遵守。Auto mode 僅在您的組織允許且選定的模型支援時出現。Bypass permissions 不可用。104 * **雲端會話**在 [Claude Code on the web](/zh-TW/claude-code-on-the-web)：Accept edits、Plan 和 Auto。Accept edits 對應於 `default` 模式：雲端環境預先批准檔案編輯，無論模式如何，因此下拉菜單顯示 Accept edits 而不是 Manual。來自設定的 `defaultMode: "acceptEdits"` 仍然被遵守。Auto mode 僅在您的組織允許且選定的模型支援時出現。Bypass permissions 不可用。

~~99 * **[Remote Control](/zh-TW/remote-control) 會話**在您的本機上：Ask permissions、Auto accept edits 和 Plan mode。Auto 和 Bypass permissions 不可用。~~105 * **[Remote Control](/zh-TW/remote-control) 會話**在您的本機上：Manual、Accept edits 和 Plan。您無法從應用中選擇 Auto 或 Bypass permissions。{/* min-version: 2.1.202 */}下拉菜單顯示本機會話所在的模式，包括從終端設定的模式，並在應用或終端中模式變更時更新。唯一的例外是 Bypass permissions：會話永遠不會向 claude.ai 報告該模式，因此從終端切換到它不會改變下拉菜單顯示的內容。在 v2.1.202 之前，使用 `/remote-control` 或 `claude --remote-control` 連接的會話根本不報告其模式，因此 claude.ai 和行動應用可能顯示會話不在的模式。不匹配僅影響標籤：Claude Code 從會話的實際模式生成權限提示，仍然出現在應用中以供批准。

100 106

101 對於 Remote Control，您也可以在啟動主機時設定啟動模式：107 對於 Remote Control，您也可以在啟動主機時設定啟動模式：

102 108

116 122

117當啟用 [PowerShell tool](/zh-TW/tools-reference#powershell-tool) 時，`acceptEdits` 模式也會自動批准 `Set-Content`、`Add-Content`、`Clear-Content` 和 `Remove-Item` 在範圍內的路徑上，以及它們的常見別名。相同的範圍和受保護路徑規則適用。123當啟用 [PowerShell tool](/zh-TW/tools-reference#powershell-tool) 時，`acceptEdits` 模式也會自動批准 `Set-Content`、`Add-Content`、`Clear-Content` 和 `Remove-Item` 在範圍內的路徑上，以及它們的常見別名。相同的範圍和受保護路徑規則適用。

118 124

119當您想在編輯器中或通過 `git diff` 之後審查變更而不是在線批准每個編輯時，使用 `acceptEdits`。從預設模式按 `Shift+Tab` 一次進入它，或直接啟動它：125當您想在編輯器中或通過 `git diff` 之後審查變更而不是在線批准每個編輯時，使用 `acceptEdits`。從手動模式按 `Shift+Tab` 一次進入它，或直接啟動它：

120 126

121```bash theme={null}127```bash theme={null}

122claude --permission-mode acceptEdits128claude --permission-mode acceptEdits

126 使用 plan mode 在編輯前分析132 使用 plan mode 在編輯前分析

127</h2>133</h2>

128 134

129Plan mode 告訴 Claude 研究和提議變更而不進行變更。Claude 讀取檔案、執行 shell 命令進行探索，並寫入計劃，但不編輯您的原始程式碼。權限提示的應用方式與預設模式相同。135Plan mode 告訴 Claude 研究和提議變更而不進行變更。Claude 讀取檔案、執行 shell 命令進行探索，並寫入計劃，但不編輯您的原始程式碼。權限提示的應用方式與手動模式相同。

130 136

131通過按 `Shift+Tab` 或在單個提示前加上 `/plan` 進入 plan mode。您也可以從 CLI 啟動 plan mode：137通過按 `Shift+Tab` 或在單個提示前加上 `/plan` 進入 plan mode。您也可以從 CLI 啟動 plan mode：

132 138

188 194

189* **計劃**：所有計劃。195* **計劃**：所有計劃。

190* **擁有者**：在 Team 和 Enterprise 上，擁有者必須在 [Claude Code 管理設定](https://claude.ai/admin-settings/claude-code)中啟用它，使用者才能打開它。管理員也可以通過在[受管設定](/zh-TW/permissions#managed-settings)中將 `permissions.disableAutoMode` 設定為 `"disable"` 來鎖定它。196* **擁有者**：在 Team 和 Enterprise 上，擁有者必須在 [Claude Code 管理設定](https://claude.ai/admin-settings/claude-code)中啟用它，使用者才能打開它。管理員也可以通過在[受管設定](/zh-TW/permissions#managed-settings)中將 `permissions.disableAutoMode` 設定為 `"disable"` 來鎖定它。

191* **模型**：在 Anthropic API 上，Claude Opus 4.6 或更新版本，或 Sonnet 4.6 或更新版本。在 Amazon Bedrock、Google Cloud Vertex AI、Microsoft Foundry 和已登入的 [Claude apps gateway](/zh-TW/claude-apps-gateway) 會話上，僅支援 Claude Sonnet 5、Opus 4.7 和 Opus 4.8。不支援較舊的模型，包括 Sonnet 4.5、Opus 4.5、Haiku 和 claude-3 模型，在任何提供商上都不支援。197* **模型**：在 Anthropic API 上，Claude Opus 4.6 或更新版本，或 Sonnet 4.6 或更新版本。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和已登入的 [Claude apps gateway](/zh-TW/claude-apps-gateway) 會話上，僅支援 Claude Sonnet 5、Opus 4.7 和 Opus 4.8。不支援較舊的模型，包括 Sonnet 4.5、Opus 4.5、Haiku 和 claude-3 模型，在任何提供商上都不支援。

192* **提供商**：在 Anthropic API 上預設可用。在 Amazon Bedrock、Google Cloud Vertex AI、Microsoft Foundry 和已登入的 Claude apps gateway 會話上，auto mode 關閉，直到您[設定 `CLAUDE_CODE_ENABLE_AUTO_MODE`](#enable-auto-mode-on-bedrock-vertex-ai-or-foundry)。198* **提供商**：在 Anthropic API 上預設可用。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和已登入的 Claude apps gateway 會話上，auto mode 關閉，直到您[設定 `CLAUDE_CODE_ENABLE_AUTO_MODE`](#enable-auto-mode-on-bedrock-agent-platform-or-foundry)。

193 199

194如果 Claude Code 報告 auto mode 不可用，其中一項要求未滿足；這不是暫時性中斷。單獨的訊息命名模型並說 auto mode「無法確定」操作的安全性是暫時性分類器中斷；請參閱[錯誤參考](/zh-TW/errors#auto-mode-cannot-determine-the-safety-of-an-action)。200如果 Claude Code 報告 auto mode 不可用，其中一項要求未滿足；這不是暫時性中斷。單獨的訊息命名模型並說 auto mode「無法確定」操作的安全性是暫時性分類器中斷；請參閱[錯誤參考](/zh-TW/errors#auto-mode-cannot-determine-the-safety-of-an-action)。

195 201

196如果您在[設定](/zh-TW/settings#available-settings)中設定 `defaultMode: "auto"` 並且會話以 `default` 模式啟動且沒有錯誤，該設定可能在 `.claude/settings.json` 或 `.claude/settings.local.json` 中。Claude Code v2.1.142 及更新版本忽略來自這些檔案的 `auto`，因此倉庫無法授予自己 auto mode。將其移至 `~/.claude/settings.json`。202如果您在[設定](/zh-TW/settings#available-settings)中設定 `defaultMode: "auto"` 並且會話以 `default` 模式啟動且沒有錯誤，該設定可能在 `.claude/settings.json` 或 `.claude/settings.local.json` 中。Claude Code v2.1.142 及更新版本忽略來自這些檔案的 `auto`，因此倉庫無法授予自己 auto mode。將其移至 `~/.claude/settings.json`。

197 203

198<h3 id="enable-auto-mode-on-bedrock-vertex-ai-or-foundry">204<h3 id="enable-auto-mode-on-bedrock-agent-platform-or-foundry">

199 在 Bedrock、Vertex AI 或 Foundry 上啟用 auto mode205 在 Bedrock、Agent Platform 或 Foundry 上啟用 auto mode

200</h3>206</h3>

201 207

202在 [Amazon Bedrock](/zh-TW/amazon-bedrock)、[Google Cloud Vertex AI](/zh-TW/google-vertex-ai)、[Microsoft Foundry](/zh-TW/microsoft-foundry) 和已登入的 [Claude apps gateway](/zh-TW/claude-apps-gateway) 會話上，auto mode 不會出現在 `Shift+Tab` 循環中，直到 `CLAUDE_CODE_ENABLE_AUTO_MODE` 設定為 `1`。該變數在 Claude Code v2.1.158 及更新版本中有效。這些提供商上僅支援 Claude Sonnet 5、Opus 4.7 和 Opus 4.8。208在 [Amazon Bedrock](/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/zh-TW/google-vertex-ai)、[Microsoft Foundry](/zh-TW/microsoft-foundry) 和已登入的 [Claude apps gateway](/zh-TW/claude-apps-gateway) 會話上，auto mode 不會出現在 `Shift+Tab` 循環中，直到 `CLAUDE_CODE_ENABLE_AUTO_MODE` 設定為 `1`。該變數在 Claude Code v2.1.158 及更新版本中有效。這些提供商上僅支援 Claude Sonnet 5、Opus 4.7 和 Opus 4.8。

203 209

204若要為一個開發人員啟用它，請將變數添加到 `~/.claude/settings.json` 中的 `env` 區塊：210若要為一個開發人員啟用它，請將變數添加到 `~/.claude/settings.json` 中的 `env` 區塊：

205 211

223 分類器預設阻止的內容229 分類器預設阻止的內容

224</h3>230</h3>

225 231

226分類器信任您的工作目錄和您的倉庫配置的遠端。其他所有內容都被視為外部，直到您[配置受信任的基礎設施](/zh-TW/auto-mode-config)。232分類器信任您的工作目錄和會話啟動時為其配置的遠端。使用 `git remote add` 或 `git remote set-url` 在會話期間添加或重新指向的遠端不受信任，其他所有內容都被視為外部，直到您[配置受信任的基礎設施](/zh-TW/auto-mode-config)。在 v2.1.200 之前，會話中期添加的遠端也受信任。

227 233

228**預設阻止**：234**預設阻止**：

229 235

234* 授予 IAM 或倉庫權限240* 授予 IAM 或倉庫權限

235* 修改共享基礎設施241* 修改共享基礎設施

236* 不可逆轉地銷毀會話開始前存在的檔案242* 不可逆轉地銷毀會話開始前存在的檔案

237* 強制推送或直接推送到 `main`243* 強制推送

238* {/* min-version: 2.1.182 */}`git reset --hard`、`git checkout -- .`、`git restore .`、`git clean -fd`、`git stash drop` 或 `git stash clear`，分類器推測這些會捨棄未提交的變更244* {/* min-version: 2.1.203 */}當推送攜帶敏感內容（如密鑰或個人或受信任的資料）、攜帶相對於您要求的隱藏或誤述的變更、攜帶從倉庫外部移植或首次讀取的內容，或繞過您要求的拉取請求、審查或檢查時，推送到倉庫的預設分支。純粹推送到預設分支本身不被阻止，清除標記的推送需要命名標記的內容或被繞過的審查，而不僅僅是推送。分類器是一層：[`permissions.deny` 規則](/zh-TW/permissions#manage-permissions)在每種模式中應用，可以完全阻止推送到預設分支，遠端自己的分支保護仍然適用。在 v2.1.203 之前，任何直接推送到預設分支都被阻止

245* {/* min-version: 2.1.182 */}}`git reset --hard`、`git checkout -- .`、`git restore .`、`git clean -fd`、`git stash drop` 或 `git stash clear`，分類器推測這些會捨棄未提交的變更

239* `git commit --amend`，當 HEAD 的提交不是在此會話中建立的246* `git commit --amend`，當 HEAD 的提交不是在此會話中建立的

240* {/* min-version: 2.1.198 */}}從 v2.1.198 開始，`git commit --amend` 當 HEAD 的提交已經被推送時。僅訊息重新措辭不被阻止：`--amend -m` 沒有新暫存的內容，在 Claude 在此會話中建立的提交上247* {/* min-version: 2.1.198 */}}從 v2.1.198 開始，`git commit --amend` 當 HEAD 的提交已經被推送時。僅訊息重新措辭不被阻止：`--amend -m` 沒有新暫存的內容，在 Claude 在此會話中建立的提交上

241* `terraform destroy`、`pulumi destroy`、`cdk destroy` 或 `terragrunt destroy`，以及應用會銷毀資源的計劃248* `terraform destroy`、`pulumi destroy`、`cdk destroy` 或 `terragrunt destroy`，以及應用會銷毀資源的計劃

261Claude Code v2.1.198 及更新版本也預設阻止這些：268Claude Code v2.1.198 及更新版本也預設阻止這些：

262 269

263* 通過通配符、glob 或年齡篩選器而不是特定命名路徑刪除 `/tmp`、`$TMPDIR` 或另一個共享暫存或快取目錄中的檔案270* 通過通配符、glob 或年齡篩選器而不是特定命名路徑刪除 `/tmp`、`$TMPDIR` 或另一個共享暫存或快取目錄中的檔案

264* 在發送、上傳、發佈或寫入其他人或共享系統的內容中包含敏感詳細資訊，當您自己的訊息沒有授權這些詳細資訊給該收件人時271* 在發送、上傳、發佈或寫入其他人或共享系統的內容中包含敏感詳細資訊，當您自己的訊息沒有授權這些詳細資訊給該收件人時。{/* min-version: 2.1.200 */}PR 和問題本文、提交訊息和評論在倉庫在信任邊界外或公開時計為此類出站內容，包括您組織自己的公開倉庫；內部檔案路徑、代碼名稱、即時 API 回應資料（如電子郵件或帳戶識別碼）和基礎設施識別碼計為敏感詳細資訊。PR、問題和提交訊息範圍需要 Claude Code v2.1.200 或更新版本。{/* min-version: 2.1.203 */}}PR 或問題本文中的即時個人資料（如電子郵件地址、帳戶或組織識別碼或使用指標）需要您命名這些詳細資訊和收件人，無論倉庫的可見性或信任邊界如何。該檢查需要 Claude Code v2.1.203 或更新版本

265* 將按鍵發送到 Claude Code 自己的 tmux 窗格以驅動其自己的介面，分類器將其視為 Claude 改變自己的權限或監督272* 將按鍵發送到 Claude Code 自己的 tmux 窗格以驅動其自己的介面，分類器將其視為 Claude 改變自己的權限或監督

266 273

274Claude Code v2.1.200 及更新版本也預設阻止這些：

275

276* 註釋掉、刪除或強制通過保護安全行為的測試或斷言，例如身份驗證、存取控制、輸入驗證或沙箱

277* 刪除或拆除 Claude 在會話中未建立的有狀態資源，當沒有更具體的刪除規則適用且您沒有命名該資源時

278* 將 API 基礎 URL、代理端點、webhook 接收器或登錄鏡像重新指向不適合任務的第三方主機，包括在 `.env.example` 等範例檔案中

279* 使用 `git remote set-url` 或 `git remote add` 改變推送去向，除非您命名了新遠端

280* 推送密鑰或個人或受信任的資料到已知為公開的倉庫，或推送其他機密材料到那裡，這些不是該倉庫自己工作的一部分。{/* min-version: 2.1.203 */}}dotfiles 倉庫自己的主題是個人或受信任資料的唯一例外，來自私人倉庫到任何公開表面的內容以相同方式被阻止；兩項改進都需要 Claude Code v2.1.203 或更新版本。在 v2.1.203 之前，個人資料與機密材料分組，僅在不是該倉庫自己工作的一部分時被阻止。當倉庫的可見性未確定時，分類器不會單獨在此阻止；它改為根據其他規則判斷內容

281* 針對不同的倉庫或組織開啟拉取請求、使用 `gh repo fork` 進行分叉，或推送到第三方倉庫，除非您命名了該外部目標

282

283Claude Code v2.1.203 及更新版本也預設阻止這些：

284

285* 來自敏感本地存儲或檔案名稱、路徑或類型標記為敏感的檔案的內容進入提交、推送、PR 或問題文本、gist 或貼上或套件發佈，除非您命名了來源和目的地。會話記錄和對話日誌、認證和配置點資料夾（如 SSH 金鑰、雲端認證、瀏覽器設定檔和 shell 歷史記錄）以及使用者資料匯出都計為此類，倉庫是私人的不會清除它

286

287Claude Code v2.1.205 及更新版本也預設阻止這些：

288

289* 寫入 Claude Code 會話記錄、`~/.claude/projects/` 下的 `.jsonl` 歷史檔案或您配置的配置目錄，無論是直接還是通過 shell 命令。該規則也涵蓋 Claude Code 為其自己的檢查附加到每個記錄項目的中繼資料行。記錄是 Claude Code 寫入的會話狀態，而不是工作檔案，篡改的項目在您恢復會話後到達每個稍後的檢查，因此 auto mode 作為深度防禦阻止這些寫入。讀取記錄不被阻止

290* 遞迴強制刪除，例如 `rm -rf "$VAR"` 或 `Remove-Item -Recurse -Force $dir`，其目標是分類器看到的對話中任何地方都未指派的 shell 變數，或以一個為根的 glob。該值僅來自較早的命令輸出，分類器永遠不會收到，因此分類器無法根據其他刪除規則驗證刪除目標。分類器根據設計讀取對話而不是命令輸出，因此它阻止呼叫而不是猜測目標。當您命名被刪除的確切路徑，或當 Claude 使用寫入命令的已解析文字路徑重新執行刪除時，該阻止清除。其目標分類器可以解析的刪除不受影響

291

267**預設允許**：292**預設允許**：

268 293

269* 工作目錄中的本地檔案操作294* 工作目錄中的本地檔案操作

permissions.md +27 −3

Details

47Claude Code 支援多種權限模式來控制工具的批准方式。請參閱 [Permission modes](/zh-TW/permission-modes) 以了解何時使用每一種。在您的 [settings files](/zh-TW/settings#settings-files) 中設定 `defaultMode`：47Claude Code 支援多種權限模式來控制工具的批准方式。請參閱 [Permission modes](/zh-TW/permission-modes) 以了解何時使用每一種。在您的 [settings files](/zh-TW/settings#settings-files) 中設定 `defaultMode`：

48 48

49| 模式 | 描述 |49| 模式 | 描述 |

~~50| :------------------ | :------------------------------------------------------------------------------- |~~50| :------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |

~~51| `default` | 標準行為：在首次使用每個工具時提示權限 |~~51| `default` | 標準行為：在首次使用每個工具時提示權限。{/* min-version: 2.1.200 */}在 CLI 和 VS Code 及 JetBrains 擴充功能中標示為 Manual，Claude Code 接受 `manual` 作為別名。標籤和別名需要 Claude Code v2.1.200 或更新版本 |

505 505

506嵌入主機可以在 [`parentSettingsBehavior`](/zh-TW/settings#settings-precedence) 設定為 `"merge"` 時，透過 SDK `managedSettings` 選項提供額外的受管理原則；嵌入器值可以收緊原則但不能放寬它。506嵌入主機可以在 [`parentSettingsBehavior`](/zh-TW/settings#settings-precedence) 設定為 `"merge"` 時，透過 SDK `managedSettings` 選項提供額外的受管理原則；嵌入器值可以收緊原則但不能放寬它。

507 507

508<h2 id="project-allow-rules-and-workspace-trust">

509 專案允許規則和工作區信任

510</h2>

511

512`permissions.allow` 規則和專案 `.claude/settings.json` 中的 `permissions.additionalDirectories` 項目會授予功能，因此 Claude Code 只有在您接受該工作區的[工作區信任對話框](/zh-TW/security#additional-safeguards)後才會套用這些規則。在此之前，Claude Code 會讀取規則但不會套用它們。信任對話框會列出資料夾將授予的允許規則和其他目錄，以便您在接受前進行檢查。`deny` 和 `ask` 規則不受影響，因為它們只會限制。

513

514Claude Code 按工作區儲存信任，以 git 儲存庫根目錄為鍵，或在儲存庫外，以您啟動 Claude Code 的目錄為鍵。當您在主目錄中啟動時，信任僅在目前工作階段內保持，不會寫入磁碟；請參閱[額外保護措施](/zh-TW/security#additional-safeguards)說明。信任父目錄不會套用巢狀專案的允許規則。

515

516`.claude/settings.local.json` 是您自己的檔案，因此工作區信任檢查通常不適用於它。當儲存庫可能已提供該檔案時，例如當它被提交到 git 或 `.claude` 是符號連結時，其允許規則和其他目錄會經過信任檢查，就像專案設定一樣。

517

518`.claude/settings.local.json` 中的允許規則和其他目錄在兩種情況下也可以在沒有工作區信任的情況下套用：

519

520* 您啟動 Claude Code 的目錄不在 git 儲存庫內。

521* 工作階段在您自己的設定主目錄中執行：您的主目錄或任何您已設定為 [`CLAUDE_CONFIG_DIR`](/zh-TW/env-vars) 的 `.claude` 子目錄。

522

523在這兩種情況下，該檔案都是您建立的，而不是儲存庫可能提供的檔案，而儲存庫提交的 `.claude/settings.local.json` 仍然需要工作區信任。版本 2.1.196 至 2.1.199 在這些工作區中將該檔案視為儲存庫提供的檔案，忽略其允許規則，並向 stderr 列印[`this workspace has not been trusted`](/zh-TW/errors#workspace-has-not-been-trusted)警告。上述兩個例外與 v2.1.195 及更早版本相符，並在 v2.1.200 中恢復。

524

525同樣從 v2.1.200 開始，工作區的允許規則或其他目錄仍未被套用，但由於父目錄已被信任而從未顯示信任對話框，在您下次以互動方式在該處啟動 Claude Code 時會顯示對話框。對話框提供兩個選擇：

526

527* **Yes, I trust this folder**：儲存該工作區的信任並在同一工作階段中套用規則。

528* **No, continue without these permissions**：繼續工作，忽略這些規則。對話框將在下一個工作階段中再次出現。

529

530在[非互動模式](/zh-TW/headless)中使用 `-p`，不會出現對話框，規則保持被忽略。

531

508<h2 id="example-configurations">532<h2 id="example-configurations">

509 範例設定533 範例設定

510</h2>534</h2>

platforms.md +1 −1

Details

25 25

26CLI 是終端原生工作的最完整介面：指令碼和 Agent SDK 僅限 CLI。第三方提供商也可在 [VS Code](/zh-TW/vs-code#use-third-party-providers) 中使用。企業 [Desktop](/zh-TW/desktop) 部署支援 Vertex AI 和閘道提供商；對於 Bedrock 或 Foundry，請改用 CLI 或 VS Code，或 [Cowork on 3P research preview](https://claude.com/docs/cowork/3p/overview)，其在這些提供商上執行 Code 標籤。Desktop 和 IDE 擴充功能用視覺審查和更緊密的編輯器整合來交換一些僅限 CLI 的功能。Web 在 Anthropic 的雲端中執行，因此任務在您斷開連接後會繼續進行。Mobile 是進入這些相同雲端會話或透過 Remote Control 進入本地會話的瘦用戶端，並可以透過 Dispatch 將任務發送到 Desktop。26CLI 是終端原生工作的最完整介面：指令碼和 Agent SDK 僅限 CLI。第三方提供商也可在 [VS Code](/zh-TW/vs-code#use-third-party-providers) 中使用。企業 [Desktop](/zh-TW/desktop) 部署支援 Google Cloud 的 Agent Platform 和閘道提供商；對於 Amazon Bedrock 或 Microsoft Foundry，請改用 CLI 或 VS Code，或 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)，其在這些提供商上執行 Code 標籤。Desktop 和 IDE 擴充功能用視覺審查和更緊密的編輯器整合來交換一些僅限 CLI 的功能。Web 在 Anthropic 的雲端中執行，因此任務在您斷開連接後會繼續進行。Mobile 是進入這些相同雲端會話或透過 Remote Control 進入本地會話的瘦用戶端，並可以透過 Dispatch 將任務發送到 Desktop。

27 27

28您可以在同一專案上混合使用介面。配置、專案記憶體和 MCP 伺服器在本地介面之間共享。28您可以在同一專案上混合使用介面。配置、專案記憶體和 MCP 伺服器在本地介面之間共享。

29 29

plugin-dependencies.md +2 −2

Details

125| `~2.1` | `~3.0` | Plugin B 的安裝失敗，出現 `range-conflict` 錯誤。Plugin A 和依賴保持原樣。 |125| `~2.1` | `~3.0` | Plugin B 的安裝失敗，出現 `range-conflict` 錯誤。Plugin A 和依賴保持原樣。 |

126| `=2.1.0` | 無 | 依賴保持在 `2.1.0`。在安裝了 Plugin A 時，自動更新會跳過較新版本。 |126| `=2.1.0` | 無 | 依賴保持在 `2.1.0`。在安裝了 Plugin A 時，自動更新會跳過較新版本。 |

127 127

128自動更新會在滿足每個已安裝 plugin 範圍的最高 git 標籤處取得受約束的依賴，而不是在 marketplace 的最新版本處，因此依賴會在其允許的範圍內繼續接收更新。如果沒有標籤滿足所有範圍，更新將被跳過，跳過訊息會出現在 `/doctor` 和 `/plugin` 錯誤標籤中，並命名限制 plugin。128自動更新會在滿足每個已安裝 plugin 範圍的最高 git 標籤處取得受約束的依賴，而不是在 marketplace 的最新版本處，因此依賴會在其允許的範圍內繼續接收更新。如果沒有標籤滿足所有範圍，自動更新會跳過該依賴，並在 `/plugin` 錯誤標籤中列出跳過，並命名限制 plugin。

129 129

130當您卸載最後一個限制依賴的 plugin 時，依賴不再被保持，並在下次更新時恢復追蹤其 marketplace 條目。130當您卸載最後一個限制依賴的 plugin 時，依賴不再被保持，並在下次更新時恢復追蹤其 marketplace 條目。

131 131

181 解析依賴錯誤181 解析依賴錯誤

182</h2>182</h2>

183 183

184依賴問題會在 `claude plugin list`、`/plugin` 介面和 `/doctor` 中出現。受影響的 plugin 將被禁用，直到您解析錯誤。最常見的錯誤及其修復方法列在下表中。184依賴問題會在 `claude plugin list` 和 `/plugin` 介面中出現。Claude Code 會禁用受影響的 plugin，直到您解析錯誤。下表列出最常見的錯誤及其解決方法。

185 185

186| 錯誤 | 含義 | 如何解析 |186| 錯誤 | 含義 | 如何解析 |

187| :------------------------------- | :---------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------- |187| :------------------------------- | :---------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------- |

plugin-marketplaces.md +3 −1

Details

171 171

172<Note>172<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`。模仿官方 marketplace 的名稱（如 `official-claude-plugins` 或 `anthropic-tools-v2`）也被阻止。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 發佈的來源。

174

175 Claude Code 每次載入 marketplace 時都會重新檢查保留名稱，而不僅在您新增 marketplace 時檢查。在名稱成為保留名稱之前以其中一個名稱註冊的 marketplace 會停止載入，並報告它是[從不受信任的來源註冊](/zh-TW/errors#marketplace-is-registered-from-an-untrusted-source)。移除該 marketplace，並從官方 Anthropic 來源重新新增它。受新保留名稱影響的第三方 marketplace 在您以不同名稱重新新增它後立即再次載入。在 v2.1.205 之前，`first-party-plugins` 和 `healthcare` 未被保留，已在保留名稱下註冊的 marketplace 繼續載入。

174</Note>176</Note>

175 177

176<h3 id="owner-fields">178<h3 id="owner-fields">

plugins.md +2 −0

Details

203 203

204<Warning>204<Warning>

205 **常見錯誤**：不要將 `commands/`、`agents/`、`skills/` 或 `hooks/` 放在 `.claude-plugin/` 目錄內。只有 `plugin.json` 應該在 `.claude-plugin/` 內。所有其他目錄必須位於 plugin 根目錄級別。205 **常見錯誤**：不要將 `commands/`、`agents/`、`skills/` 或 `hooks/` 放在 `.claude-plugin/` 目錄內。只有 `plugin.json` 應該在 `.claude-plugin/` 內。所有其他目錄必須位於 plugin 根目錄級別。

206

207 plugin 根目錄是個別 plugin 自己的目錄：包含 `.claude-plugin/plugin.json` 的目錄。它永遠不是 `~/.claude/`。例如，Claude Code 不會讀取放在 `~/.claude/.mcp.json` 的 `.mcp.json`。

206</Warning>208</Warning>

207 209

208| 目錄 | 位置 | 用途 |210| 目錄 | 位置 | 用途 |

plugins-reference.md +16 −2

Details

159* `prompt`：使用 LLM 評估提示（使用 `$ARGUMENTS` 佔位符表示上下文）159* `prompt`：使用 LLM 評估提示（使用 `$ARGUMENTS` 佔位符表示上下文）

160* `agent`：執行具有工具的 agentic 驗證器以進行複雜驗證任務160* `agent`：執行具有工具的 agentic 驗證器以進行複雜驗證任務

161 161

162針對 plugin 自己的 [bundled MCP server](#mcp-servers) 的 Hooks 必須使用其範圍名稱。工具匹配器和 `if` 欄位採用範圍工具名稱 `mcp__plugin_<plugin-name>_<server-name>__<tool>`，而 `mcp_tool` hook 的 `server` 欄位採用 `plugin:<plugin-name>:<server-name>`。針對裸伺服器金鑰撰寫的匹配器永遠不會觸發。請參閱 [Match MCP tools](/zh-TW/hooks#match-mcp-tools) 和 [Plugin-provided MCP servers](/zh-TW/mcp#plugin-provided-mcp-servers)。

163

162<h3 id="mcp-servers">164<h3 id="mcp-servers">

163 MCP servers165 MCP servers

164</h3>166</h3>

271| `shutdownTimeout` | 等待正常關閉的最長時間（毫秒）。當逾時時間過去時，Claude Code 會終止 server 程序。未設定時，不適用逾時 |

272| `restartOnCrash` | server 崩潰後是否重新啟動。預設為 `true`。設定為 `false` 以保持崩潰的 server 停止而不是重新啟動它 |

271 275

276`restartOnCrash` 和 `shutdownTimeout` 需要 Claude Code v2.1.205 或更新版本。在 v2.1.205 之前，設定架構接受兩個選項，但設定其中任一個會導致 Claude Code 在啟動時完全跳過該 LSP server，原因僅在 `claude --debug` 輸出中可見。

277

278**相同副檔名的多個 servers**：當多個已啟用的 LSP servers 在 `extensionToLanguage` 中宣告相同的檔案副檔名時，無論 servers 來自一個 plugin 還是來自不同的 plugins，第一個註冊的 server 會處理具有該副檔名的檔案，其他的永遠不會啟動。`/plugin` 介面會顯示一個警告，命名其 server 為作用中的 plugin。

279

280**無法初始化的 Servers**：Claude Code 會跳過設定無效的 server，例如缺少 `command` 或 `extensionToLanguage` 的 server，其他已設定的 servers 仍會啟動。執行 `claude --debug` 以查看為什麼 server 被跳過。

281

282被跳過的 server 不會聲稱其檔案副檔名，因此另一個宣告相同副檔名的有效 server（來自相同或不同的 plugin）仍會處理這些檔案。在 v2.1.205 之前，無法初始化的 server 仍會聲稱其副檔名並阻止另一個有效的 server 使用相同的副檔名。

283

272<Warning>284<Warning>

273 **您必須單獨安裝語言伺服器二進位檔。** LSP plugins 設定 Claude Code 如何連接到語言伺服器，但它們不包括伺服器本身。如果您在 `/plugin` Errors 標籤中看到 `Executable not found in $PATH`，請為您的語言安裝所需的二進位檔。285 **您必須單獨安裝語言伺服器二進位檔。** LSP plugins 設定 Claude Code 如何連接到語言伺服器，但它們不包括伺服器本身。如果您在 `/plugin` Errors 標籤中看到 `Executable not found in $PATH`，請為您的語言安裝所需的二進位檔。

274</Warning>286</Warning>

635* **新增到預設值**：`skills`。預設 `skills/` 目錄始終被掃描，`skills` 中列出的目錄與其一起載入。例外：對於[其 `source` 解析為 marketplace 根目錄的 marketplace 項目](/zh-TW/plugin-marketplaces#advanced-plugin-entries)，宣告特定子目錄會取代掃描647* **新增到預設值**：`skills`。預設 `skills/` 目錄始終被掃描，`skills` 中列出的目錄與其一起載入。例外：對於[其 `source` 解析為 marketplace 根目錄的 marketplace 項目](/zh-TW/plugin-marketplaces#advanced-plugin-entries)，宣告特定子目錄會取代掃描

636* **自有合併規則**：[hooks](#hooks)、[MCP servers](#mcp-servers) 和 [LSP servers](#lsp-servers)。請參閱每個部分以了解多個來源如何組合648* **自有合併規則**：[hooks](#hooks)、[MCP servers](#mcp-servers) 和 [LSP servers](#lsp-servers)。請參閱每個部分以了解多個來源如何組合

637 649

638當 plugin 同時具有預設資料夾和相符的 manifest 金鑰時，Claude Code v2.1.140 及更新版本會在 `/doctor`、`claude plugin list` 和 `/plugin` 詳細檢視中標記被忽略的資料夾。plugin 仍會使用 manifest 路徑載入。當 manifest 金鑰指向預設資料夾時不會顯示警告，例如 `"commands": ["./commands/deploy.md"]`，因為在這種情況下資料夾是明確定址的。650當 plugin 同時具有預設資料夾和相符的 manifest 金鑰時，Claude Code v2.1.140 及更新版本會在 `claude plugin list` 和 `/plugin` 詳細檢視中標記被忽略的資料夾。plugin 仍會使用 manifest 路徑載入。當 manifest 金鑰指向預設資料夾時不會顯示警告，例如 `"commands": ["./commands/deploy.md"]`，因為在這種情況下資料夾是明確定址的。

639 651

640對於所有路徑欄位：652對於所有路徑欄位：

641 653

673 685

674**`${CLAUDE_PLUGIN_DATA}`**：用於在更新後保留的 plugin 狀態的持久目錄。使用此方法用於已安裝的依賴項，例如 `node_modules` 或 Python 虛擬環境、生成的程式碼、快取和任何應在 plugin 版本之間保留的其他檔案。首次參考此變數時會自動建立目錄。686**`${CLAUDE_PLUGIN_DATA}`**：用於在更新後保留的 plugin 狀態的持久目錄。使用此方法用於已安裝的依賴項，例如 `node_modules` 或 Python 虛擬環境、生成的程式碼、快取和任何應在 plugin 版本之間保留的其他檔案。首次參考此變數時會自動建立目錄。

675 687

676**`${CLAUDE_PROJECT_DIR}`**：專案根目錄。這是 hooks 在其 `CLAUDE_PROJECT_DIR` 變數中接收的相同目錄。使用此方法參考專案本地指令碼或設定檔。包裝在引號中以處理包含空格的路徑，例如 `"${CLAUDE_PROJECT_DIR}/scripts/server.sh"`。MCP servers 也可以呼叫 MCP `roots/list` 請求，該請求會傳回啟動 Claude Code 的目錄。688**`${CLAUDE_PROJECT_DIR}`**：專案根目錄。這是 hooks 在其 `CLAUDE_PROJECT_DIR` 變數中接收的相同目錄。使用此方法參考專案本地指令碼或設定檔。包裝在引號中以處理包含空格的路徑，例如 `"${CLAUDE_PROJECT_DIR}/scripts/server.sh"`。

689

690MCP servers 也可以呼叫 `roots/list` 請求以在執行時讀取工作階段的工作目錄。請參閱[`roots/list` 傳回的內容以及 Claude Code 何時通知伺服器變更](/zh-TW/mcp#option-3-add-a-local-stdio-server)。

677 691

678```json theme={null}692```json theme={null}

679{693{

prompt-caching.md +5 −5

Details

50快取發生在伺服器端，在提供您的模型的任何基礎設施中。位置取決於您如何進行身份驗證：50快取發生在伺服器端，在提供您的模型的任何基礎設施中。位置取決於您如何進行身份驗證：

51 51

52* **API 金鑰、Claude 訂閱或 [Claude Platform on AWS](/zh-TW/claude-platform-on-aws)**：快取位於 Anthropic 的基礎設施中，通過 [Claude API](https://platform.claude.com/docs) 訪問52* **API 金鑰、Claude 訂閱或 [Claude Platform on AWS](/zh-TW/claude-platform-on-aws)**：快取位於 Anthropic 的基礎設施中，通過 [Claude API](https://platform.claude.com/docs) 訪問

~~53* **Bedrock 或 Vertex AI**：快取位於您的雲端提供商的服務基礎設施中~~53* **Amazon Bedrock 或 Google Cloud 的 Agent Platform**：快取位於您的雲端提供商的服務基礎設施中

~~54* **Foundry**：請求路由到 Anthropic 的基礎設施~~54* **Microsoft Foundry**：請求路由到 Anthropic 的基礎設施

55* **自訂 `ANTHROPIC_BASE_URL` 或 [LLM gateway](/zh-TW/llm-gateway)**：快取位於您的請求轉發到的位置，快取是否工作取決於閘道55* **自訂 `ANTHROPIC_BASE_URL` 或 [LLM gateway](/zh-TW/llm-gateway)**：快取位於您的請求轉發到的位置，快取是否工作取決於閘道

56 56

57有關每個提供商存儲和處理的內容，請參閱[資料使用](/zh-TW/data-usage)。無論快取位於何處，條目在一段時間不活動後過期，[下面的快取生命週期](#cache-lifetime)涵蓋 TTL 以及如何延長它。57有關每個提供商存儲和處理的內容，請參閱[資料使用](/zh-TW/data-usage)。無論快取位於何處，條目在一段時間不活動後過期，[下面的快取生命週期](#cache-lifetime)涵蓋 TTL 以及如何延長它。

106工具定義位於系統提示層中，因此當請求之間的工具定義集合變更時，快取會失效。切換[顧問工具](/zh-TW/advisor)是例外：其定義位於快取中斷點之後，因此啟用或停用 `/advisor` 會保持快取的前綴完整。[MCP 伺服器](/zh-TW/mcp)變更是否執行此操作取決於其工具是否由[工具搜尋](/zh-TW/mcp#scale-with-mcp-tool-search)延遲或載入到前綴中：106工具定義位於系統提示層中，因此當請求之間的工具定義集合變更時，快取會失效。切換[顧問工具](/zh-TW/advisor)是例外：其定義位於快取中斷點之後，因此啟用或停用 `/advisor` 會保持快取的前綴完整。[MCP 伺服器](/zh-TW/mcp)變更是否執行此操作取決於其工具是否由[工具搜尋](/zh-TW/mcp#scale-with-mcp-tool-search)延遲或載入到前綴中：

107 107

108* **延遲工具**，在支援的模型上為預設值：伺服器連接、斷開連接或變更其工具列表只會附加新內容，不會擾亂已快取的任何內容。108* **延遲工具**，在支援的模型上為預設值：伺服器連接、斷開連接或變更其工具列表只會附加新內容，不會擾亂已快取的任何內容。

109* **載入到前綴中的工具**：對它們的任何變更都會使快取失效。這發生在[工具搜尋不可用或已停用](/zh-TW/mcp#configure-tool-search)時，例如在 Haiku 模型上、在 Vertex AI 上，或使用自訂 `ANTHROPIC_BASE_URL` 閘道時。它也發生在標記為 [`alwaysLoad`](/zh-TW/mcp#exempt-a-server-from-deferral) 的伺服器或工具上，以及由[基於閾值的載入](/zh-TW/mcp#configure-tool-search)保持在前面的定義上。109* **載入到前綴中的工具**：對它們的任何變更都會使快取失效。這發生在[工具搜尋不可用或已停用](/zh-TW/mcp#configure-tool-search)時，例如在 Haiku 模型上、在 Google Cloud 的 Agent Platform 上，或使用自訂 `ANTHROPIC_BASE_URL` 閘道時。它也發生在標記為 [`alwaysLoad`](/zh-TW/mcp#exempt-a-server-from-deferral) 的伺服器或工具上，以及由[基於閾值的載入](/zh-TW/mcp#configure-tool-search)保持在前面的定義上。

110 110

111當工具載入到前綴中時，失效的最常見原因是伺服器在會話中期連接或斷開連接，這可能在沒有您採取任何操作的情況下發生：stdio 伺服器的進程退出、HTTP 會話過期，或伺服器[在暫時性故障後自動重新連接](/zh-TW/mcp#automatic-reconnection)。連接的伺服器也可以推送[動態工具更新](/zh-TW/mcp#dynamic-tool-updates)來變更其工具列表。111當工具載入到前綴中時，失效的最常見原因是伺服器在會話中期連接或斷開連接，這可能在沒有您採取任何操作的情況下發生：stdio 伺服器的進程退出、HTTP 會話過期，或伺服器[在暫時性故障後自動重新連接](/zh-TW/mcp#automatic-reconnection)。連接的伺服器也可以推送[動態工具更新](/zh-TW/mcp#dynamic-tool-updates)來變更其工具列表。

112 112

235 在 API 金鑰或第三方提供商上235 在 API 金鑰或第三方提供商上

236</h3>236</h3>

237 237

238在 API 金鑰、Bedrock、Vertex、Foundry 或 Claude Platform on AWS 上，您支付按令牌費率，因此 TTL 預設保持在更便宜的五分鐘。要選擇加入[一小時 TTL](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-caching#1-hour-cache-duration)，設定 `ENABLE_PROMPT_CACHING_1H=1`。238在 API 金鑰、Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 Claude Platform on AWS 上，您支付按令牌費率，因此 TTL 預設保持在更便宜的五分鐘。要選擇加入[一小時 TTL](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-caching#1-hour-cache-duration)，設定 `ENABLE_PROMPT_CACHING_1H=1`。

239 239

240在 Bedrock 上，prompt caching 支援、最小可快取前綴長度和一小時 TTL 可用性都因模型而異。如果快取令牌計數保持為零，請檢查 Bedrock 文件中的[支援的模型、區域和限制](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html#prompt-caching-models)。240在 Amazon Bedrock 上，prompt caching 支援、最小可快取前綴長度和一小時 TTL 可用性都因模型而異。如果快取令牌計數保持為零，請檢查 Amazon Bedrock 文件中的[支援的模型、區域和限制](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html#prompt-caching-models)。

241 241

242<h3 id="override-the-ttl">242<h3 id="override-the-ttl">

243 覆蓋 TTL243 覆蓋 TTL

quickstart.md +1 −1

Details

105 105

106* [Claude Pro、Max、Team 或 Enterprise](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=quickstart_login)（推薦）106* [Claude Pro、Max、Team 或 Enterprise](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=quickstart_login)（推薦）

107* [Claude Console](https://console.anthropic.com/)（具有預付額度的 API 存取）。首次登入時，Console 中會自動建立「Claude Code」工作區以進行集中成本追蹤。107* [Claude Console](https://console.anthropic.com/)（具有預付額度的 API 存取）。首次登入時，Console 中會自動建立「Claude Code」工作區以進行集中成本追蹤。

108* [Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry](/zh-TW/third-party-integrations)（企業雲端提供商）108* [Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry](/zh-TW/third-party-integrations)（企業雲端提供商）

109* 自行託管的 [Claude 應用程式閘道](/zh-TW/claude-apps-gateway)（如果您的組織執行一個的話）：您的管理員會預先設定閘道 URL，`/login` 會直接在 **Cloud gateway** 畫面上開啟，供您使用公司 SSO 登入109* 自行託管的 [Claude 應用程式閘道](/zh-TW/claude-apps-gateway)（如果您的組織執行一個的話）：您的管理員會預先設定閘道 URL，`/login` 會直接在 **Cloud gateway** 畫面上開啟，供您使用公司 SSO 登入

110 110

111登入後，您的認證將被儲存，您無需再次登入。111登入後，您的認證將被儲存，您無需再次登入。

remote-control.md +20 −5

Details

16 16

17* **遠端使用您的完整本地環境**：您的檔案系統、[MCP servers](/zh-TW/mcp)、工具和專案配置都保持可用，輸入 `@` 會自動完成來自您本地專案的檔案路徑17* **遠端使用您的完整本地環境**：您的檔案系統、[MCP servers](/zh-TW/mcp)、工具和專案配置都保持可用，輸入 `@` 會自動完成來自您本地專案的檔案路徑

18* **同時在兩個介面上工作**：對話在所有連接的裝置上保持同步，因此您可以從終端機、瀏覽器和手機交替發送訊息18* **同時在兩個介面上工作**：對話在所有連接的裝置上保持同步，因此您可以從終端機、瀏覽器和手機交替發送訊息

19* **從您的手機或瀏覽器傳送影像和檔案**：當您在 Claude 應用程式或 claude.ai/code 中新增附件時，Claude Code 會將其下載到您的機器，並將其作為 `@` 檔案參考傳遞給 Claude，可以有或沒有標題。{/* min-version: 2.1.202 */}在 v2.1.202 之前，Claude Code 可能會在沒有標題的附件到達會話之前將其丟棄。

19* **克服中斷**：如果您的筆記型電腦進入睡眠狀態或網路中斷，當您的機器重新上線時，會話會自動重新連接20* **克服中斷**：如果您的筆記型電腦進入睡眠狀態或網路中斷，當您的機器重新上線時，會話會自動重新連接

20 21

21與[網頁版 Claude Code](/zh-TW/claude-code-on-the-web)（在雲端基礎設施上執行）不同，Remote Control 會話直接在您的機器上執行並與您的本地檔案系統互動。網頁和行動介面只是該本地會話的一個窗口。22與[網頁版 Claude Code](/zh-TW/claude-code-on-the-web)（在雲端基礎設施上執行）不同，Remote Control 會話直接在您的機器上執行並與您的本地檔案系統互動。網頁和行動介面只是該本地會話的一個窗口。

34 35

35* **訂閱**：在 Pro、Max、Team 和 Enterprise 方案上可用。不支援 API 金鑰。在 Team 和 Enterprise 上，管理員必須先在 [Claude Code 管理員設定](https://claude.ai/admin-settings/claude-code)中啟用 Remote Control 切換。36* **訂閱**：在 Pro、Max、Team 和 Enterprise 方案上可用。不支援 API 金鑰。在 Team 和 Enterprise 上，管理員必須先在 [Claude Code 管理員設定](https://claude.ai/admin-settings/claude-code)中啟用 Remote Control 切換。

36* **驗證**：執行 `claude` 並使用 `/login` 透過 claude.ai 登入（如果您還沒有登入）。37* **驗證**：執行 `claude` 並使用 `/login` 透過 claude.ai 登入（如果您還沒有登入）。

37* **API 端點**：在 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 上不可用。{/* min-version: 2.1.196 */}自 v2.1.196 起，當 [`ANTHROPIC_BASE_URL`](/zh-TW/env-vars) 指向 `api.anthropic.com` 以外的主機（例如 [LLM 閘道](/zh-TW/llm-gateway)或代理）時，Remote Control 也會被停用。取消設定該變數以使用 Remote Control。38* **API 端點**：在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用。{/* min-version: 2.1.196 */}自 v2.1.196 起，當 [`ANTHROPIC_BASE_URL`](/zh-TW/env-vars) 指向 `api.anthropic.com` 以外的主機（例如 [LLM 閘道](/zh-TW/llm-gateway)或代理）時，Remote Control 也會被停用。取消設定該變數以使用 Remote Control。

38* **工作區信任**：在您的專案目錄中至少執行一次 `claude` 以接受工作區信任對話框。39* **工作區信任**：在您的專案目錄中至少執行一次 `claude` 以接受工作區信任對話框。

39 40

40<h2 id="start-a-remote-control-session">41<h2 id="start-a-remote-control-session">

59 | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |60 | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

61 | `--remote-control-session-name-prefix <prefix>` | 未設定明確名稱時自動生成會話名稱的前綴。預設為您機器的主機名稱，產生類似 `myhost-graceful-unicorn` 的名稱。設定 `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` 以獲得相同效果。 |62 | `--remote-control-session-name-prefix <prefix>` | 未設定明確名稱時自動生成會話名稱的前綴。預設為您機器的主機名稱，產生類似 `myhost-graceful-unicorn` 的名稱。設定 `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` 以獲得相同效果。 |

63 | `-c`, `--continue` | {/* min-version: 2.1.200 */}恢復從此目錄啟動的最近 Remote Control 會話，而不是建立新會話。無法與 `--session-id`、`--spawn`、`--capacity` 或 `--create-session-in-dir` 結合。需要 Claude Code v2.1.200 或更新版本；較早版本會將該旗標拒絕為未知引數。 |

64 | `--session-id <id>` | {/* min-version: 2.1.200 */}按其 ID 恢復特定的 Remote Control 會話。無法與 `--continue`、`--spawn`、`--capacity` 或 `--create-session-in-dir` 結合。需要 Claude Code v2.1.200 或更新版本；較早版本會將該旗標拒絕為未知引數。 |

62 | `--spawn <mode>` | 伺服器如何建立會話。<br />• `same-dir`（預設）：所有會話共享目前的工作目錄，因此如果編輯相同的檔案可能會衝突。<br />• `worktree`：每個按需會話都會獲得自己的 [git worktree](/zh-TW/worktrees)。需要 git 儲存庫。<br />• `session`：單一會話模式。恰好提供一個會話並拒絕其他連接。僅在啟動時設定。<br />在執行時按 `w` 在 `same-dir` 和 `worktree` 之間切換。 |65 | `--spawn <mode>` | 伺服器如何建立會話。<br />• `same-dir`（預設）：所有會話共享目前的工作目錄，因此如果編輯相同的檔案可能會衝突。<br />• `worktree`：每個按需會話都會獲得自己的 [git worktree](/zh-TW/worktrees)。需要 git 儲存庫。<br />• `session`：單一會話模式。恰好提供一個會話並拒絕其他連接。僅在啟動時設定。<br />在執行時按 `w` 在 `same-dir` 和 `worktree` 之間切換。 |

67 | `--[no-]create-session-in-dir` | 伺服器啟動時在目前目錄中預先建立一個會話，以便您有地方立即輸入。在 `worktree` 模式中，此會話保留在目前目錄中，而按需會話會獲得隔離的 worktrees。預設為開啟；傳遞 `--no-create-session-in-dir` 以不建立任何會話啟動。 |

66 </Tab>70 </Tab>

149 為所有會話啟用 Remote Control153 為所有會話啟用 Remote Control

150</h3>154</h3>

151 155

152預設情況下，Remote Control 只在您明確執行 `claude remote-control`、`claude --remote-control` 或 `/remote-control` 時啟動，除非自動連接已開啟。要為每個互動式會話自動啟用它，請在 Claude Code 內執行 `/config` 並將**為所有會話啟用 Remote Control** 設定為 `true`。將其設定為 `false` 以永不自動連接，或保留未設定以遵循您組織的預設值。在桌面應用程式中，您也可以從**設定 → Claude Code → 預設啟用遠端控制**切換此選項。156預設情況下，Remote Control 只在您明確執行 `claude remote-control`、`claude --remote-control` 或 `/remote-control` 時啟動，除非自動連接已開啟。要為每個互動式會話自動啟用它，請在 Claude Code 內執行 `/config` 並將**為所有會話啟用 Remote Control** 設定為 `true`。將其設定為 `false` 以永不自動連接，或保留未設定以遵循您組織的預設值。在桌面應用程式中，您也可以從**設定 → Claude Code → 預設啟用遠端控制**切換此選項。{/* min-version: 2.1.203 */}在 [VS Code 擴充功能](/zh-TW/vs-code#use-the-prompt-box)中，相同的切換會在命令選單的設定部分中顯示為**為所有會話啟用 Remote Control**；需要 Claude Code v2.1.203 或更新版本。

153 157

154啟用此設定後，每個互動式 Claude Code 程序會註冊一個遠端會話。如果您執行多個實例，每個實例都會獲得自己的環境和會話。要從單個程序執行多個並行會話，請改用[伺服器模式](#start-a-remote-control-session)。158啟用此設定後，每個互動式 Claude Code 程序會註冊一個遠端會話。如果您執行多個實例，每個實例都會獲得自己的環境和會話。要從單個程序執行多個並行會話，請改用[伺服器模式](#start-a-remote-control-session)。

155 159

282* **Ultraplan 斷開 Remote Control**：啟動 [ultraplan](/zh-TW/ultraplan) 會話會斷開任何活動的 Remote Control 會話，因為兩個功能都佔據 claude.ai/code 介面，一次只能連接一個。286* **Ultraplan 斷開 Remote Control**：啟動 [ultraplan](/zh-TW/ultraplan) 會話會斷開任何活動的 Remote Control 會話，因為兩個功能都佔據 claude.ai/code 介面，一次只能連接一個。

283* **某些命令僅限本地**：在終端機中開啟互動式選擇器的命令，例如 `/plugin` 或 `/resume`，只能從本地 CLI 使用。以下命令可從行動和網頁使用：287* **某些命令僅限本地**：在終端機中開啟互動式選擇器的命令，例如 `/plugin` 或 `/resume`，只能從本地 CLI 使用。以下命令可從行動和網頁使用：

284 * 文字輸出命令：`/compact`、`/clear`、`/context`、`/usage`、`/exit`、`/usage-credits`、`/recap`、`/reload-plugins`288 * 文字輸出命令：`/compact`、`/clear`、`/context`、`/usage`、`/exit`、`/usage-credits`、`/recap`、`/reload-plugins`

285 * {/* min-version: 2.1.166 */}自 v2.1.166 起，`/mcp`：傳回伺服器狀態的文字摘要而不是開啟選擇器，並接受 `reconnect`、`enable` 和 `disable` [子命令](/zh-TW/commands#all-commands)。與本地 CLI 不同，`/mcp reconnect` 不帶伺服器名稱會重新連接每個已失敗或需要驗證的伺服器。289 * `/model`、`/effort`、`/fast`、`/color` 和 `/rename`：將值作為引數傳遞，例如 `/model sonnet` 或 `/effort high`。從行動和網頁，`/model` 和 `/effort` 在終端機選擇器或滑桿的位置接受引數。

286 * {/* min-version: 2.1.181 */}自 v2.1.181 起，`/config`：傳遞 `key=value` 以設定設定，或不帶引數執行以列出您可以設定的金鑰。290 * {/* min-version: 2.1.166 */}`/mcp`，自 v2.1.166 起：傳回伺服器狀態的文字摘要而不是開啟選擇器，並接受 `reconnect`、`enable` 和 `disable` [子命令](/zh-TW/commands#all-commands)。與本地 CLI 不同，`/mcp reconnect` 不帶伺服器名稱會重新連接每個已失敗或需要驗證的伺服器。

291 * {/* min-version: 2.1.181 */}`/config`，自 v2.1.181 起：傳遞 `key=value` 以設定設定，或不帶引數執行以列出您可以設定的金鑰。

287 292

288<h2 id="troubleshooting">293<h2 id="troubleshooting">

289 疑難排解294 疑難排解

323 「Remote Control 僅在透過 api.anthropic.com 使用 Claude 時可用」328 「Remote Control 僅在透過 api.anthropic.com 使用 Claude 時可用」

324</h3>329</h3>

325 330

326會話未直接與 Anthropic API 通訊，因此沒有 claude.ai 後端可配對。這發生在 Amazon Bedrock、Google Vertex AI 和 Microsoft Foundry 上。{/* min-version: 2.1.196 */}自 v2.1.196 起，當 [`ANTHROPIC_BASE_URL`](/zh-TW/env-vars) 指向 `api.anthropic.com` 以外的主機時，例如 [LLM 閘道](/zh-TW/llm-gateway)或代理，即使您使用 claude.ai 登入，也會發生這種情況。取消設定 `ANTHROPIC_BASE_URL` 並重新啟動會話以使用 Remote Control。331會話未直接與 Anthropic API 通訊，因此沒有 claude.ai 後端可配對。這發生在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上。{/* min-version: 2.1.196 */}自 v2.1.196 起，當 [`ANTHROPIC_BASE_URL`](/zh-TW/env-vars) 指向 `api.anthropic.com` 以外的主機時，例如 [LLM 閘道](/zh-TW/llm-gateway)或代理，即使您使用 claude.ai 登入，也會發生這種情況。取消設定 `ANTHROPIC_BASE_URL` 並重新啟動會話以使用 Remote Control。

327 332

328<h3 id="remote-control-is-disabled-by-your-organization’s-policy">333<h3 id="remote-control-is-disabled-by-your-organization’s-policy">

329 「Remote Control 已被您的組織政策停用」334 「Remote Control 已被您的組織政策停用」

352* 網路或代理問題：防火牆或代理可能阻止出站 HTTPS 請求。Remote Control 需要存取埠 443 上的 Anthropic API。357* 網路或代理問題：防火牆或代理可能阻止出站 HTTPS 請求。Remote Control 需要存取埠 443 上的 Anthropic API。

353* 會話建立失敗：如果您也看到 `Session creation failed — see debug log`，失敗發生在設定的早期。檢查您的訂閱是否有效。358* 會話建立失敗：如果您也看到 `Session creation failed — see debug log`，失敗發生在設定的早期。檢查您的訂閱是否有效。

354 359

360<h3 id="couldn’t-reconnect-to-your-remote-control-session">

361 「無法重新連接到您的 Remote Control 會話」

362</h3>

363

364當您使用 `claude --resume` 或 `claude --continue` 繼續對話時，Claude Code 會重新連接到該對話中記錄的 Remote Control 會話。此訊息表示重新連接因可能是暫時性的原因（例如網路中斷或伺服器錯誤）而失敗，因此 Claude Code 無法確認遠端會話是否仍然存在。當伺服器確認先前的會話不再存在時，Claude Code 會建立新的 Remote Control 會話，而不顯示此訊息。

365

366您的本機會話在沒有 Remote Control 的情況下繼續執行。執行 `/remote-control` 以重試連接，或在不使用 `--resume` 的情況下啟動 Claude Code 以建立新的 Remote Control 會話。

367

368{/* min-version: 2.1.200 */}在 v2.1.200 之前，重新連接失敗會建立新的 Remote Control 會話，而不是顯示此訊息，這在 claude.ai/code 的會話清單中留下了額外的會話。

369

355<h3 id="your-organization-requires-trusted-devices-for-remote-control-but-this-device-is-not-enrolled">370<h3 id="your-organization-requires-trusted-devices-for-remote-control-but-this-device-is-not-enrolled">

356 「您的組織需要受信任的裝置進行 Remote Control，但此裝置未註冊」371 「您的組織需要受信任的裝置進行 Remote Control，但此裝置未註冊」

357</h3>372</h3>

routines.md +1 −1

Details

416 416

417當不滿足其中一項要求時，CLI 會隱藏 `/schedule`，因此命令菜單在您輸入時會顯示 `No commands match "/schedule"`，提交時會返回 `Unknown command: /schedule`。原因通常是以下之一：417當不滿足其中一項要求時，CLI 會隱藏 `/schedule`，因此命令菜單在您輸入時會顯示 `No commands match "/schedule"`，提交時會返回 `Unknown command: /schedule`。原因通常是以下之一：

418 418

419* 您使用 Console API 金鑰或雲端提供商（例如 Bedrock、Vertex 或 Foundry）進行身份驗證。`/schedule` 需要 claude.ai 訂閱登入。如果在您的 shell 中設定了 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN`，或在 `settings.json` 中設定了 `apiKeyHelper`，請先移除它，因為這些設定優先於 claude.ai 登入419* 您使用 Console API 金鑰或雲端提供商（例如 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry）進行身份驗證。`/schedule` 需要 claude.ai 訂閱登入。如果在您的 shell 中設定了 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN`，或在 `settings.json` 中設定了 `apiKeyHelper`，請先移除它，因為這些設定優先於 claude.ai 登入

420* `DISABLE_TELEMETRY`、`DO_NOT_TRACK`、`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 或 `DISABLE_GROWTHBOOK` 在您的 shell 環境或 [`settings.json` 檔案](/zh-TW/settings#available-settings)的 `env` 區塊中設定。這些會停用功能旗標擷取，而 `/schedule` 依賴於此功能420* `DISABLE_TELEMETRY`、`DO_NOT_TRACK`、`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 或 `DISABLE_GROWTHBOOK` 在您的 shell 環境或 [`settings.json` 檔案](/zh-TW/settings#available-settings)的 `env` 區塊中設定。這些會停用功能旗標擷取，而 `/schedule` 依賴於此功能

421* 您在 Claude Code 網頁工作階段中。改為從 [web UI](https://claude.ai/code/routines) 管理例行程序421* 您在 Claude Code 網頁工作階段中。改為從 [web UI](https://claude.ai/code/routines) 管理例行程序

422* {/* min-version: 2.1.81 */}您的 CLI 版本早於 v2.1.81。執行 `claude update`422* {/* min-version: 2.1.81 */}您的 CLI 版本早於 v2.1.81。執行 `claude update`

sandboxing.md +1 −1

Details

237 237

238使用 `mask`，沙箱化命令看到的是每個工作階段的哨兵值而不是真實值。當請求離開沙箱前往認證的 `injectHosts` 之一時，[sandbox proxy](#network-isolation) 將哨兵值替換為真實值。命令和它記錄的任何內容都不會持有真實認證，但其請求仍然進行身份驗證。238使用 `mask`，沙箱化命令看到的是每個工作階段的哨兵值而不是真實值。當請求離開沙箱前往認證的 `injectHosts` 之一時，[sandbox proxy](#network-isolation) 將哨兵值替換為真實值。命令和它記錄的任何內容都不會持有真實認證，但其請求仍然進行身份驗證。

239 239

240代理在請求內容中替換認證，因此它必須看到它們。設定 [`network.tlsTerminate`](/zh-TW/settings#sandbox-settings) 以便代理自己終止 HTTPS。沒有它，遮罩會失敗關閉：命令仍然只看到哨兵值，但哨兵值不變地到達伺服器，身份驗證失敗。Claude Code 在啟動時和 `/doctor` 中報告此配置錯誤。240代理在請求內容中替換認證，因此它必須看到它們。設定 [`network.tlsTerminate`](/zh-TW/settings#sandbox-settings) 以便代理自己終止 TLS。沒有它，遮罩會失敗關閉：命令仍然只看到哨兵值，但哨兵值不變地到達伺服器，身份驗證失敗。Claude Code 在啟動時報告此配置錯誤。

241 241

242下面的範例遮罩兩個令牌。`GH_TOKEN` 僅在對 `api.github.com` 的請求上被替換，而 `NPM_TOKEN` 沒有 `injectHosts` 並在對 `network.allowedDomains` 中每個主機的請求上被替換。每個 `injectHosts` 項目本身必須被 `network.allowedDomains` 覆蓋。242下面的範例遮罩兩個令牌。`GH_TOKEN` 僅在對 `api.github.com` 的請求上被替換，而 `NPM_TOKEN` 沒有 `injectHosts` 並在對 `network.allowedDomains` 中每個主機的請求上被替換。每個 `injectHosts` 項目本身必須被 `network.allowedDomains` 覆蓋。

243 243

scheduled-tasks.md +6 −4

Details

86動態排程的迴圈會像任何其他任務一樣出現在您的[排程任務清單](#manage-scheduled-tasks)中，因此您可以以相同的方式列出或取消它。[抖動規則](#jitter)不適用於它，但[七天過期](#seven-day-expiry)適用：迴圈在您啟動它七天後自動結束。86動態排程的迴圈會像任何其他任務一樣出現在您的[排程任務清單](#manage-scheduled-tasks)中，因此您可以以相同的方式列出或取消它。[抖動規則](#jitter)不適用於它，但[七天過期](#seven-day-expiry)適用：迴圈在您啟動它七天後自動結束。

87 87

88<Note>88<Note>

~~89 在 Bedrock、Vertex AI 和 Microsoft Foundry 上，沒有間隔的提示會改為在固定的 10 分鐘排程上執行。~~89 在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，沒有間隔的提示會改為在固定的 10 分鐘排程上執行。

90</Note>90</Note>

91 91

92<h3 id="run-the-built-in-maintenance-prompt">92<h3 id="run-the-built-in-maintenance-prompt">

108裸 `/loop` 在[動態選擇的間隔](#let-claude-choose-the-interval)上執行此提示。新增間隔（例如 `/loop 15m`）以改為在固定排程上執行它。若要用您自己的預設值替換內建提示，請參閱[使用 loop.md 自訂預設提示](#customize-the-default-prompt-with-loop-md)。108裸 `/loop` 在[動態選擇的間隔](#let-claude-choose-the-interval)上執行此提示。新增間隔（例如 `/loop 15m`）以改為在固定排程上執行它。若要用您自己的預設值替換內建提示，請參閱[使用 loop.md 自訂預設提示](#customize-the-default-prompt-with-loop-md)。

109 109

110<Note>110<Note>

111 在 Bedrock、Vertex AI 和 Microsoft Foundry 上，沒有提示的 `/loop` 會列印使用訊息而不是執行維護提示。111 在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，沒有提示的 `/loop` 會列印使用訊息而不是執行維護提示。

112</Note>112</Note>

113 113

114<h3 id="customize-the-default-prompt-with-loop-md">114<h3 id="customize-the-default-prompt-with-loop-md">

136對 `loop.md` 的編輯在下次迭代時生效，因此您可以在迴圈執行時精煉指示。當任一位置都不存在 `loop.md` 時，迴圈會回退到內建維護提示。保持檔案簡潔：超過 25,000 位元組的內容會被截斷。136對 `loop.md` 的編輯在下次迭代時生效，因此您可以在迴圈執行時精煉指示。當任一位置都不存在 `loop.md` 時，迴圈會回退到內建維護提示。保持檔案簡潔：超過 25,000 位元組的內容會被截斷。

137 137

138<Note>138<Note>

139 在 Bedrock、Vertex AI 和 Microsoft Foundry 上，`loop.md` 不會被讀取，沒有提示的 `/loop` 會列印使用訊息。139 在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，`loop.md` 不會被讀取，沒有提示的 `/loop` 會列印使用訊息。

140</Note>140</Note>

141 141

142<h3 id="stop-a-loop">142<h3 id="stop-a-loop">

145 145

146若要在 `/loop` 等待下一次迭代時停止它，請按 `Esc`。這會清除待處理的喚醒，使迴圈不會再次執行。您透過[直接要求 Claude](#manage-scheduled-tasks) 排程的任務不受 `Esc` 影響，會保留在原位，直到您刪除它們。146若要在 `/loop` 等待下一次迭代時停止它，請按 `Esc`。這會清除待處理的喚醒，使迴圈不會再次執行。您透過[直接要求 Claude](#manage-scheduled-tasks) 排程的任務不受 `Esc` 影響，會保留在原位，直到您刪除它們。

147 147

148在[自我調整模式](#let-claude-choose-the-interval)中，Claude 也可以在任務可證明完成後不排程下一次喚醒來自行結束迴圈。固定間隔上的迴圈會持續執行，直到您停止它們或[七天過去](#seven-day-expiry)。148在[自我調整模式](#let-claude-choose-the-interval)中，Claude 也可以在任務完成後自行結束迴圈。Claude 呼叫 [`ScheduleWakeup` tool](/zh-TW/tools-reference)，其中 `stop: true`，這會立即取消待處理的喚醒。如果迭代結束時既未重新排程也未停止，Claude Code 會排程一個大約 20 分鐘後的備用喚醒，並在該迭代也不重新排程時結束迴圈。在 v2.1.202 之前，不重新排程是 Claude 自行結束迴圈的唯一方式。

149

150固定間隔上的迴圈會持續執行，直到您停止它們或[七天過去](#seven-day-expiry)。

149 151

150<h2 id="set-a-one-time-reminder">152<h2 id="set-a-one-time-reminder">

151 設定一次性提醒153 設定一次性提醒

security-guidance.md +1 −1

Details

219/plugin uninstall security-guidance@claude-plugins-official219/plugin uninstall security-guidance@claude-plugins-official

220```220```

221 221

222如果外掛程式通過專案的 `.claude/settings.json` 啟用，從 `/plugin` 禁用它會將覆蓋寫入您的 `.claude/settings.local.json`，而不是編輯簽入的檔案，因此外掛程式對您保持關閉，而不影響隊友。如果它通過 [受管設定](/zh-TW/admin-setup) 啟用，只有管理員可以禁用它。222如果外掛程式通過專案的 `.claude/settings.json` 啟用，從 `/plugin` 禁用它會將覆蓋寫入您的 `.claude/settings.local.json`，而不是編輯簽入的檔案，因此外掛程式對您保持關閉，而不影響隊友。{/* min-version: 2.1.203 */}同一對話框也提供選項以移除外掛程式供所有人使用，方法是從共享的 `.claude/settings.json` 中移除它；該選項需要 Claude Code v2.1.203 或更新版本。如果它通過 [受管設定](/zh-TW/admin-setup) 啟用，只有管理員可以禁用它。

223 223

224<h2 id="how-the-plugin-integrates-with-claude-code">224<h2 id="how-the-plugin-integrates-with-claude-code">

225 外掛程式如何與 Claude Code 整合225 外掛程式如何與 Claude Code 整合

server-managed-settings.md +2 −2

Details

255在使用第三方模型提供者時，伺服器管理的設定無法使用：255在使用第三方模型提供者時，伺服器管理的設定無法使用：

256 256

257* Amazon Bedrock257* Amazon Bedrock

258* Google Vertex AI258* Google Cloud 的 Agent Platform

259* Microsoft Foundry259* Microsoft Foundry

260* [Claude Platform on AWS](/zh-TW/claude-platform-on-aws)260* [Claude Platform on AWS](/zh-TW/claude-platform-on-aws)

261* 透過 `ANTHROPIC_BASE_URL` 或第三方 [LLM 閘道](/zh-TW/llm-gateway) 的自訂 API 端點261* 透過 `ANTHROPIC_BASE_URL` 或第三方 [LLM 閘道](/zh-TW/llm-gateway) 的自訂 API 端點

262 262

263對於 Bedrock、Vertex AI 和 Foundry 部署，自託管的 [Claude 應用程式閘道](/zh-TW/claude-apps-gateway) 提供等效的遠端管理設定傳遞：閘道登入的用戶端從閘道而不是 `api.anthropic.com` 擷取管理設定。啟動時的失敗語義不同：無法到達閘道的閘道用戶端會以錯誤結束，而不是回退到快取的設定，而每小時的背景重新整理在兩個通道上都是開放失敗的。263對於 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 部署，自託管的 [Claude 應用程式閘道](/zh-TW/claude-apps-gateway) 提供等效的遠端管理設定傳遞：閘道登入的用戶端從閘道而不是 `api.anthropic.com` 擷取管理設定。啟動時的失敗語義不同：無法到達閘道的閘道用戶端會以錯誤結束，而不是回退到快取的設定，而每小時的背景重新整理在兩個通道上都是開放失敗的。

264 264

265<h2 id="audit-logging">265<h2 id="audit-logging">

266 稽核記錄266 稽核記錄

settings.md +35 −20

Details

95* **專案設定**儲存在您的專案目錄中：95* **專案設定**儲存在您的專案目錄中：

96 * `.claude/settings.json` 用於簽入原始碼控制並與您的團隊共享的設定96 * `.claude/settings.json` 用於簽入原始碼控制並與您的團隊共享的設定

97 * `.claude/settings.local.json` 用於未簽入的設定，適用於個人偏好和實驗。Claude Code 建立 `.claude/settings.local.json` 時，會設定 git 以忽略該檔案。如果您自己建立該檔案，請手動將其新增到 gitignore。97 * `.claude/settings.local.json` 用於未簽入的設定，適用於個人偏好和實驗。Claude Code 建立 `.claude/settings.local.json` 時，會設定 git 以忽略該檔案。如果您自己建立該檔案，請手動將其新增到 gitignore。

99 因為此檔案是您的而不是儲存庫的，其權限 `allow` 規則會生效，無需 `.claude/settings.json` allow 規則所需的[工作區信任](/zh-TW/permissions#project-allow-rules-and-workspace-trust)步驟。如果儲存庫提供該檔案，例如透過提交它，工作區信任仍然適用。

98* **Managed 設定**：對於需要集中控制的組織，Claude Code 支援多種 managed 設定的傳遞機制。所有機制都使用相同的 JSON 格式，無法被使用者或專案設定覆蓋：100* **Managed 設定**：對於需要集中控制的組織，Claude Code 支援多種 managed 設定的傳遞機制。所有機制都使用相同的 JSON 格式，無法被使用者或專案設定覆蓋：

99 101

100 * **伺服器管理的設定**：透過 Anthropic 的伺服器或自託管的 [Claude apps gateway](/zh-TW/claude-apps-gateway) 在登入時遠端傳遞，可從 claude.ai 管理員主控台或自託管 Claude apps gateway 傳遞。請參閱[伺服器管理的設定](/zh-TW/server-managed-settings)。102 * **伺服器管理的設定**：透過 Anthropic 的伺服器或自託管的 [Claude apps gateway](/zh-TW/claude-apps-gateway) 在登入時遠端傳遞，可從 claude.ai 管理員主控台或自託管 Claude apps gateway 傳遞。請參閱[伺服器管理的設定](/zh-TW/server-managed-settings)。

211`settings.json` 支援多個選項：213`settings.json` 支援多個選項：

212 214

213| 金鑰 | 說明 | 範例 |215| 金鑰 | 說明 | 範例 |

214| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------ |216| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ |

215| `advisorModel` | {/* min-version: 2.1.98 */}伺服器端 [advisor tool](/zh-TW/advisor) 的模型。接受模型別名，例如 `"opus"`、`"sonnet"` 或 `"fable"`（{/* min-version: 2.1.170 */}v2.1.170+），或完整模型 ID。當您執行 `/advisor` 時自動寫入。取消設定以停用 advisor。需要 Claude Code v2.1.98 或更新版本 | `"opus"` |217| `advisorModel` | {/* min-version: 2.1.98 */}伺服器端 [advisor tool](/zh-TW/advisor) 的模型。接受模型別名，例如 `"opus"`、`"sonnet"` 或 `"fable"`（{/* min-version: 2.1.170 */}v2.1.170+），或完整模型 ID。當您執行 `/advisor` 時自動寫入。取消設定以停用 advisor。需要 Claude Code v2.1.98 或更新版本 | `"opus"` |

216| `agent` | 將主執行緒作為命名 subagent 執行，並為從 `claude agents` 分派的工作階段設定預設 agent。應用該 subagent 的系統提示、工具限制和模型。請參閱[明確叫用 subagents](/zh-TW/sub-agents#invoke-subagents-explicitly) | `"code-reviewer"` |218| `agent` | 將主執行緒作為命名 subagent 執行，並為從 `claude agents` 分派的工作階段設定預設 agent。應用該 subagent 的系統提示、工具限制和模型。請參閱[明確叫用 subagents](/zh-TW/sub-agents#invoke-subagents-explicitly) | `"code-reviewer"` |

217| `agentPushNotifEnabled` | {/* min-version: 2.1.119 */}**預設**：`false`。當[遠端控制](/zh-TW/remote-control)已連線時，允許 Claude 主動傳送推播通知到您的手機，例如當長時間工作完成時。在 `/config` 中顯示為**Claude 決定時推播**。請參閱[行動推播通知](/zh-TW/remote-control#mobile-push-notifications)。需要 Claude Code v2.1.119 或更新版本 | `true` |219| `agentPushNotifEnabled` | {/* min-version: 2.1.119 */}**預設**：`false`。當[遠端控制](/zh-TW/remote-control)已連線時，允許 Claude 主動傳送推播通知到您的手機，例如當長時間工作完成時。在 `/config` 中顯示為**Claude 決定時推播**。請參閱[行動推播通知](/zh-TW/remote-control#mobile-push-notifications)。需要 Claude Code v2.1.119 或更新版本 | `true` |

224| `allowManagedPermissionRulesOnly` | （Managed 設定僅限）防止使用者和專案設定定義 `allow`、`ask` 或 `deny` 權限規則。僅適用 managed 設定中的規則。請參閱 [Managed 專用設定](/zh-TW/permissions#managed-only-settings) | `true` |226| `allowManagedPermissionRulesOnly` | （Managed 設定僅限）防止使用者和專案設定定義 `allow`、`ask` 或 `deny` 權限規則。僅適用 managed 設定中的規則。請參閱 [Managed 專用設定](/zh-TW/permissions#managed-only-settings) | `true` |

225| `alwaysThinkingEnabled` | 為所有工作階段預設啟用[擴展思考](/zh-TW/model-config#extended-thinking)。通常透過 `/config` 命令而不是直接編輯來設定。若要強制思考關閉，無論此設定如何，請在 `env` 中設定 [`MAX_THINKING_TOKENS=0`](/zh-TW/env-vars)，這會停用 Anthropic API 上的思考，除了 Fable 5，無法關閉思考。在[第三方提供者](/zh-TW/third-party-integrations)上，這會改為省略 `thinking` 參數，自適應推理模型仍可能思考 | `true` |227| `alwaysThinkingEnabled` | 為所有工作階段預設啟用[擴展思考](/zh-TW/model-config#extended-thinking)。通常透過 `/config` 命令而不是直接編輯來設定。若要強制思考關閉，無論此設定如何，請在 `env` 中設定 [`MAX_THINKING_TOKENS=0`](/zh-TW/env-vars)，這會停用 Anthropic API 上的思考，除了 Fable 5，無法關閉思考。在[第三方提供者](/zh-TW/third-party-integrations)上，這會改為省略 `thinking` 參數，自適應推理模型仍可能思考 | `true` |

226| `apiKeyHelper` | 自訂指令碼，在系統 shell（macOS 和 Linux 上為 `/bin/sh`，Windows 上為 `cmd`）中執行，以產生驗證值。此值將作為 `X-Api-Key` 和 `Authorization: Bearer` 標頭傳送以進行模型請求。使用 [`CLAUDE_CODE_API_KEY_HELPER_TTL_MS`](/zh-TW/env-vars) 設定重新整理間隔 | `/bin/generate_temp_api_key.sh` |228| `apiKeyHelper` | 自訂指令碼，在系統 shell（macOS 和 Linux 上為 `/bin/sh`，Windows 上為 `cmd`）中執行，以產生驗證值。此值將作為 `X-Api-Key` 和 `Authorization: Bearer` 標頭傳送以進行模型請求。使用 [`CLAUDE_CODE_API_KEY_HELPER_TTL_MS`](/zh-TW/env-vars) 設定重新整理間隔 | `/bin/generate_temp_api_key.sh` |

229| `askUserQuestionTimeout` | {/* min-version: 2.1.200 */}**預設**：`"never"`。未回答的 [`AskUserQuestion`](/zh-TW/tools-reference) 對話框在自動繼續前的閒置時間，使用您已選擇的任何選項。接受 `"60s"`、`"5m"`、`"10m"` 或 `"never"`。使用預設值，問題會等待您回答。在 `/config` 中顯示為**問題自動繼續逾時**，會將此金鑰寫入使用者設定。不從專案或本機設定讀取。需要 Claude Code v2.1.200 或更新版本 | `"5m"` |

227| `attribution` | 自訂 git 提交和拉取請求的歸屬。請參閱[歸屬設定](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |230| `attribution` | 自訂 git 提交和拉取請求的歸屬。請參閱[歸屬設定](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |

228| `autoCompactEnabled` | {/* min-version: 2.1.119 */}**預設**：`true`。當內容接近限制時自動壓縮對話。在 `/config` 中顯示為**自動壓縮**。若要透過環境變數停用，請在 `env` 中設定 [`DISABLE_AUTO_COMPACT`](/zh-TW/env-vars) | `false` |231| `autoCompactEnabled` | {/* min-version: 2.1.119 */}**預設**：`true`。當內容接近限制時自動壓縮對話。在 `/config` 中顯示為**自動壓縮**。若要透過環境變數停用，請在 `env` 中設定 [`DISABLE_AUTO_COMPACT`](/zh-TW/env-vars) | `false` |

239| `axScreenReader` | {/* min-version: 2.1.181 */}渲染螢幕閱讀器友善的輸出：沒有裝飾邊框或動畫的平面文字。螢幕閱讀器模式始終使用經典渲染器，因此在其使用中時 `tui` 設定無效。[`CLAUDE_AX_SCREEN_READER`](/zh-TW/env-vars) 環境變數和 [`--ax-screen-reader`](/zh-TW/cli-reference#cli-flags) 旗標優先。需要 Claude Code v2.1.181 或更新版本 | `true` |242| `axScreenReader` | {/* min-version: 2.1.181 */}渲染螢幕閱讀器友善的輸出：沒有裝飾邊框或動畫的平面文字。螢幕閱讀器模式始終使用經典渲染器，因此在其使用中時 `tui` 設定無效。[`CLAUDE_AX_SCREEN_READER`](/zh-TW/env-vars) 環境變數和 [`--ax-screen-reader`](/zh-TW/cli-reference#cli-flags) 旗標優先。需要 Claude Code v2.1.181 或更新版本 | `true` |

240| `blockedMarketplaces` | （Managed 設定僅限）marketplace 來源的黑名單。在 marketplace 新增和 plugin 安裝、更新、重新整理和自動更新時強制執行，因此在設定政策之前新增的 marketplace 無法用於擷取 plugins。在下載前檢查被阻止的來源，因此它們永遠不會接觸檔案系統。請參閱 [Managed marketplace 限制](/zh-TW/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "untrusted/plugins" }]` |243| `blockedMarketplaces` | （Managed 設定僅限）marketplace 來源的黑名單。在 marketplace 新增和 plugin 安裝、更新、重新整理和自動更新時強制執行，因此在設定政策之前新增的 marketplace 無法用於擷取 plugins。在下載前檢查被阻止的來源，因此它們永遠不會接觸檔案系統。請參閱 [Managed marketplace 限制](/zh-TW/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "untrusted/plugins" }]` |

244| `browserExternalPageTools` | （Managed 設定僅限）設定為 `"disabled"` 以防止 Claude 使用工具讀取或作用於桌面應用程式[瀏覽器窗格](/zh-TW/desktop#browse-external-sites)中的外部頁面。使用者仍可自行導覽到外部網站，本機開發伺服器預覽不受影響 | `"disabled"` |

241| `channelsEnabled` | （Managed 設定僅限）允許組織使用[頻道](/zh-TW/channels)。在 claude.ai Team 和 Enterprise 方案上，當此設定未設定或為 `false` 時，頻道會被阻止。對於使用 API 金鑰驗證的 [Anthropic Console](/zh-TW/authentication#claude-console-authentication) 帳戶，除非您的組織部署 managed 設定（在這種情況下此金鑰必須設定為 `true`），否則預設允許頻道 | `true` |245| `channelsEnabled` | （Managed 設定僅限）允許組織使用[頻道](/zh-TW/channels)。在 claude.ai Team 和 Enterprise 方案上，當此設定未設定或為 `false` 時，頻道會被阻止。對於使用 API 金鑰驗證的 [Anthropic Console](/zh-TW/authentication#claude-console-authentication) 帳戶，除非您的組織部署 managed 設定（在這種情況下此金鑰必須設定為 `true`），否則預設允許頻道 | `true` |

242| `claudeMd` | （Managed 設定僅限）CLAUDE.md 樣式的指示，作為組織管理的記憶注入。僅在 managed 或政策設定中設定時受尊重，在使用者、專案和本機設定中被忽略。請參閱[組織範圍的 CLAUDE.md](/zh-TW/memory#deploy-organization-wide-claude-md) | `"Always run make lint before committing."` |246| `claudeMd` | （Managed 設定僅限）CLAUDE.md 樣式的指示，作為組織管理的記憶注入。僅在 managed 或政策設定中設定時受尊重，在使用者、專案和本機設定中被忽略。請參閱[組織範圍的 CLAUDE.md](/zh-TW/memory#deploy-organization-wide-claude-md) | `"Always run make lint before committing."` |

243| `claudeMdExcludes` | 載入[記憶](/zh-TW/memory)時要跳過的 `CLAUDE.md` 檔案的 Glob 模式或絕對路徑。模式與絕對檔案路徑相符。僅適用於使用者、專案和本機記憶；managed 政策檔案無法排除 | `["**/vendor/**/CLAUDE.md"]` |247| `claudeMdExcludes` | 載入[記憶](/zh-TW/memory)時要跳過的 `CLAUDE.md` 檔案的 Glob 模式或絕對路徑。模式與絕對檔案路徑相符。僅適用於使用者、專案和本機記憶；managed 政策檔案無法排除 | `["**/vendor/**/CLAUDE.md"]` |

244| `cleanupPeriodDays` | **預設**：`30` 天，最少 `1`。非使用中超過此期間的工作階段在啟動時刪除。設定為 `0` 會被拒絕並出現驗證錯誤。也控制[孤立 subagent worktrees](/zh-TW/worktrees#clean-up-worktrees) 在啟動時自動移除的年齡截止。若要完全停用文字記錄寫入，請設定 [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/zh-TW/env-vars) 環境變數，或在非互動模式（`-p`）中使用 `--no-session-persistence` 旗標或 `persistSession: false` SDK 選項。 | `20` |248| `cleanupPeriodDays` | **預設**：`30` 天，最少 `1`。Claude Code 刪除[工作階段檔案和其他應用程式資料](/zh-TW/claude-directory#cleaned-up-automatically)超過此期間的檔案在啟動時。設定 `0` 會失敗並出現驗證錯誤。相同的年齡截止也適用於[孤立 worktrees](/zh-TW/worktrees#clean-up-worktrees) 在啟動時的自動移除。{/* min-version: 2.1.203 */}如果 Claude Code 無法讀取或解析設定檔案，它會暫停保留清理掃描並在 `/status` 中顯示警告，直到您修復檔案，除非 [managed 設定](/zh-TW/server-managed-settings)提供 `cleanupPeriodDays`，在這種情況下掃描以 managed 值執行。在 v2.1.203 之前，清理以 30 天預設執行，並可能刪除較長 `cleanupPeriodDays` 打算保留的文字記錄；新於 30 天的檔案永遠不會被移除。若要完全停用文字記錄寫入，請設定 [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/zh-TW/env-vars) 環境變數。在非互動模式中，使用 `--no-session-persistence` 與 `-p` 一起傳遞或在 Agent SDK 中設定 `persistSession: false`。 | `20` |

246| `defaultShell` | **預設**：`"bash"`，或在 Bash 不可用時 Windows 上為 `"powershell"`。輸入框 `!` 命令的預設 shell。接受 `"bash"` 或 `"powershell"`。設定 `"powershell"` 會在 Windows 上透過 PowerShell 路由互動式 `!` 命令。需要 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`。請參閱 [PowerShell tool](/zh-TW/tools-reference#powershell-tool) | `"powershell"` |250| `defaultShell` | **預設**：`"bash"`，或在 Bash 不可用時 Windows 上為 `"powershell"`。輸入框 `!` 命令的預設 shell。接受 `"bash"` 或 `"powershell"`。設定 `"powershell"` 會在 Windows 上透過 PowerShell 路由互動式 `!` 命令。需要 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`。請參閱 [PowerShell tool](/zh-TW/tools-reference#powershell-tool) | `"powershell"` |

247| `deniedMcpServers` | 在 managed-settings.json 中設定時，明確阻止的 MCP servers 拒絕清單。適用於所有範圍，包括 managed servers。拒絕清單優先於白名單。請參閱 [Managed MCP 設定](/zh-TW/managed-mcp) | `[{ "serverName": "filesystem" }]` |251| `deniedMcpServers` | 在 managed-settings.json 中設定時，明確阻止的 MCP servers 拒絕清單。適用於所有範圍，包括 managed servers。拒絕清單優先於白名單。請參閱 [Managed MCP 設定](/zh-TW/managed-mcp) | `[{ "serverName": "filesystem" }]` |

266| `env` | 應用於每個工作階段和 Claude Code 從中產生的子流程的環境變數。{/* min-version: 2.1.143 */}自 v2.1.143 起，此處設定的 `NO_COLOR` 和 `FORCE_COLOR` 會傳遞到子流程，但不會改變 Claude Code 自己的介面顏色。在啟動 `claude` 前在您的 shell 中設定這些以改變介面顏色。{/* min-version: 2.1.195 */}自 v2.1.195 起，Claude Code 的託管環境設定的身份變數（例如 `CLAUDE_CODE_REMOTE` 和 `CLAUDE_CODE_ACCOUNT_UUID`）在此處設定時會被忽略 | `{"FOO": "bar"}` |270| `env` | 應用於每個工作階段和 Claude Code 從中產生的子流程的環境變數。{/* min-version: 2.1.143 */}自 v2.1.143 起，此處設定的 `NO_COLOR` 和 `FORCE_COLOR` 會傳遞到子流程，但不會改變 Claude Code 自己的介面顏色。在啟動 `claude` 前在您的 shell 中設定這些以改變介面顏色。{/* min-version: 2.1.195 */}自 v2.1.195 起，Claude Code 的託管環境設定的身份變數（例如 `CLAUDE_CODE_REMOTE` 和 `CLAUDE_CODE_ACCOUNT_UUID`）在此處設定時會被忽略 | `{"FOO": "bar"}` |

267| `fallbackModel` | 當主模型過載或不可用時按順序嘗試的備用模型。Claude Code 會為該輪的其餘部分切換到鏈中的下一個可用模型並顯示通知。`"default"` 擴展為預設模型。鏈限制為三個模型；額外項目會被忽略。與大多數陣列設定不同，此金鑰不跨設定檔案合併：定義它的最高優先順序檔案提供整個鏈。[`--fallback-model`](/zh-TW/cli-reference#cli-flags) 旗標會覆蓋此設定以進行一個工作階段。請參閱[備用模型鏈](/zh-TW/model-config#fallback-model-chains) | `["claude-sonnet-5", "claude-haiku-4-5"]` |271| `fallbackModel` | 當主模型過載或不可用時按順序嘗試的備用模型。Claude Code 會為該輪的其餘部分切換到鏈中的下一個可用模型並顯示通知。`"default"` 擴展為預設模型。鏈限制為三個模型；額外項目會被忽略。與大多數陣列設定不同，此金鑰不跨設定檔案合併：定義它的最高優先順序檔案提供整個鏈。[`--fallback-model`](/zh-TW/cli-reference#cli-flags) 旗標會覆蓋此設定以進行一個工作階段。請參閱[備用模型鏈](/zh-TW/model-config#fallback-model-chains) | `["claude-sonnet-5", "claude-haiku-4-5"]` |

268| `fastModePerSessionOptIn` | 當為 `true` 時，快速模式不會跨工作階段持久化。每個工作階段都以快速模式關閉開始，需要使用者使用 `/fast` 啟用它。使用者的快速模式偏好仍會儲存。請參閱[需要每個工作階段的選擇加入](/zh-TW/fast-mode#require-per-session-opt-in) | `true` |272| `fastModePerSessionOptIn` | 當為 `true` 時，快速模式不會跨工作階段持久化。每個工作階段都以快速模式關閉開始，需要使用者使用 `/fast` 啟用它。使用者的快速模式偏好仍會儲存。請參閱[需要每個工作階段的選擇加入](/zh-TW/fast-mode#require-per-session-opt-in) | `true` |

269| `feedbackSurveyRate` | [工作階段品質調查](/zh-TW/data-usage#session-quality-surveys)出現時符合條件的機率（0–1）。設定為 `0` 以完全抑制，或設定 [`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY`](/zh-TW/env-vars) 在 `env` 中。在使用 Bedrock、Vertex 或 Foundry 時很有用，其中預設樣本率不適用 | `0.05` |273| `feedbackSurveyRate` | [工作階段品質調查](/zh-TW/data-usage#session-quality-surveys)出現時符合條件的機率（0–1）。設定為 `0` 以完全抑制，或設定 [`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY`](/zh-TW/env-vars) 在 `env` 中。在使用 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 時很有用，其中預設樣本率不適用 | `0.05` |

270| `fileCheckpointingEnabled` | {/* min-version: 2.1.119 */}**預設**：`true`。在每次編輯前快照檔案，以便 [`/rewind`](/zh-TW/checkpointing) 可以還原它們。在 `/config` 中顯示為**倒帶程式碼（檢查點）**。若要透過環境變數停用，請在 `env` 中設定 [`CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING`](/zh-TW/env-vars) | `false` |274| `fileCheckpointingEnabled` | {/* min-version: 2.1.119 */}**預設**：`true`。在每次編輯前快照檔案，以便 [`/rewind`](/zh-TW/checkpointing) 可以還原它們。在 `/config` 中顯示為**倒帶程式碼（檢查點）**。若要透過環境變數停用，請在 `env` 中設定 [`CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING`](/zh-TW/env-vars) | `false` |

271| `fileSuggestion` | 為 `@` 檔案自動完成設定自訂指令碼。請參閱[檔案建議設定](#file-suggestion-settings) | `{"type": "command", "command": "~/.claude/file-suggestion.sh"}` |275| `fileSuggestion` | 為 `@` 檔案自動完成設定自訂指令碼。請參閱[檔案建議設定](#file-suggestion-settings) | `{"type": "command", "command": "~/.claude/file-suggestion.sh"}` |

272| `footerLinksRegexes` | {/* min-version: 2.1.176 */}當 regex 符合輪次輸出時在頁尾中渲染額外的可點擊徽章。每個項目都有一個 `pattern`、一個包含 `{name}` 佔位符的 URL 範本（從命名擷取群組填入），以及一個選用的 `label`。僅從使用者設定、`--settings` 旗標和 managed 設定讀取。請參閱[頁尾連結徽章](#footer-link-badges)以了解 URL 限制、方案白名單和限制。需要 Claude Code v2.1.176 或更新版本 | `[{"type": "regex", "pattern": "\\b(?<key>PROJ-\\d+)\\b", "url": "https://issues.example.com/browse/{key}", "label": "{key}"}]` |276| `footerLinksRegexes` | {/* min-version: 2.1.176 */}當 regex 符合輪次輸出時在頁尾中渲染額外的可點擊徽章。每個項目都有一個 `pattern`、一個包含 `{name}` 佔位符的 URL 範本（從命名擷取群組填入），以及一個選用的 `label`。僅從使用者設定、`--settings` 旗標和 managed 設定讀取。請參閱[頁尾連結徽章](#footer-link-badges)以了解 URL 限制、方案白名單和限制。需要 Claude Code v2.1.176 或更新版本 | `[{"type": "regex", "pattern": "\\b(?<key>PROJ-\\d+)\\b", "url": "https://issues.example.com/browse/{key}", "label": "{key}"}]` |

273| `forceLoginMethod` | 使用 `claudeai` 限制登入到 Claude.ai 帳戶，`console` 限制登入到 Claude Console 帳戶，或 `gateway` 限制登入到雲端閘道；請參閱 [Claude apps gateway](/zh-TW/claude-apps-gateway)。在 managed 設定中設定為任何值時，由 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 驗證的工作階段在啟動時被阻止，因為環境認證無法滿足所需的登入方法。第三方提供者工作階段（例如 Bedrock、Vertex 和 Foundry）不被阻止：它們針對您的雲端提供者而不是 Anthropic 進行驗證 | `claudeai` |277| `forceLoginMethod` | 使用 `claudeai` 限制登入到 Claude.ai 帳戶，`console` 限制登入到 Claude Console 帳戶，或 `gateway` 限制登入到雲端閘道；請參閱 [Claude apps gateway](/zh-TW/claude-apps-gateway)。在 managed 設定中設定為任何值時，由 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 驗證的工作階段在啟動時被阻止，因為環境認證無法滿足所需的登入方法。第三方提供者工作階段（例如 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry）不被阻止：它們針對您的雲端提供者而不是 Anthropic 進行驗證 | `claudeai` |

274| `forceLoginGatewayUrl` | 在 `/login` 雲端閘道畫面上預先填入並鎖定閘道 URL。此金鑰或 `forceLoginMethod: "gateway"` 會顯示該畫面；同時設定兩者以便 URL 被填入。僅在 managed 政策層級受尊重；在使用者和專案設定中被忽略。請參閱 [Claude apps gateway](/zh-TW/claude-apps-gateway#set-the-gateway-url) | `"https://claude-gateway.example.com"` |278| `forceLoginGatewayUrl` | 在 `/login` 雲端閘道畫面上預先填入並鎖定閘道 URL。此金鑰或 `forceLoginMethod: "gateway"` 會顯示該畫面；同時設定兩者以便 URL 被填入。僅在 managed 政策層級受尊重；在使用者和專案設定中被忽略。請參閱 [Claude apps gateway](/zh-TW/claude-apps-gateway#set-the-gateway-url) | `"https://claude-gateway.example.com"` |

275| `forceLoginOrgUUID` | 要求登入屬於特定 Anthropic 組織。接受單一 UUID 字串（也會在登入期間預先選擇該組織），或 UUID 陣列，其中接受任何列出的組織而不預先選擇。在 managed 設定中設定時，如果驗證帳戶不屬於列出的組織，登入會失敗；由 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 驗證的工作階段在啟動時被阻止，因為無法驗證它們的組織成員資格。第三方提供者工作階段（例如 Bedrock、Vertex 和 Foundry）不被阻止：使用您的雲端 IAM 限制可以使用哪些雲端帳戶。空陣列會失敗關閉並使用誤設定訊息阻止登入 | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` 或 `["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"]` |279| `forceLoginOrgUUID` | 要求登入屬於特定 Anthropic 組織。接受單一 UUID 字串（也會在登入期間預先選擇該組織），或 UUID 陣列，其中接受任何列出的組織而不預先選擇。在 managed 設定中設定時，如果驗證帳戶不屬於列出的組織，登入會失敗；由 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 驗證的工作階段在啟動時被阻止，因為無法驗證它們的組織成員資格。第三方提供者工作階段（例如 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry）不被阻止：使用您的雲端 IAM 限制可以使用哪些雲端帳戶。空陣列會失敗關閉並使用誤設定訊息阻止登入 | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` 或 `["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"]` |

276| `forceRemoteSettingsRefresh` | （Managed 設定僅限）阻止 CLI 啟動，直到從伺服器新鮮擷取遠端 managed 設定。如果擷取失敗，CLI 會結束而不是繼續使用快取或無設定。未設定時，啟動會繼續而不等待遠端設定。請參閱[失敗關閉強制執行](/zh-TW/server-managed-settings#enforce-fail-closed-startup) | `true` |280| `forceRemoteSettingsRefresh` | （Managed 設定僅限）阻止 CLI 啟動，直到從伺服器新鮮擷取遠端 managed 設定。如果擷取失敗，CLI 會結束而不是繼續使用快取或無設定。未設定時，啟動會繼續而不等待遠端設定。請參閱[失敗關閉強制執行](/zh-TW/server-managed-settings#enforce-fail-closed-startup) | `true` |

277| `gcpAuthRefresh` | 當 GCP Application Default Credentials 過期或無法載入時重新整理它們的自訂指令碼。請參閱[進階認證設定](/zh-TW/google-vertex-ai#advanced-credential-configuration) | `gcloud auth application-default login` |281| `gcpAuthRefresh` | 當 GCP Application Default Credentials 過期或無法載入時重新整理它們的自訂指令碼。請參閱[進階認證設定](/zh-TW/google-vertex-ai#advanced-credential-configuration) | `gcloud auth application-default login` |

282| `language` | 設定 Claude 的首選回應語言（例如 `"japanese"`、`"spanish"`、`"french"`）。Claude 預設會以此語言回應。也設定[語音聽寫](/zh-TW/voice-dictation#change-the-dictation-language)語言和自動產生的工作階段標題。{/* min-version: 2.1.176 */}自 v2.1.176 起，未設定時，工作階段標題符合您對話的語言 | `"japanese"` |286| `language` | 設定 Claude 的首選回應語言（例如 `"japanese"`、`"spanish"`、`"french"`）。Claude 預設會以此語言回應。也設定[語音聽寫](/zh-TW/voice-dictation#change-the-dictation-language)語言和自動產生的工作階段標題。{/* min-version: 2.1.176 */}自 v2.1.176 起，未設定時，工作階段標題符合您對話的語言 | `"japanese"` |

283| `minimumVersion` | 防止背景自動更新和 `claude update` 安裝低於此版本的版本。當從 `"latest"` 頻道切換到 `"stable"` 時透過 `/config` 提示您保持在目前版本或允許降級。選擇保持設定此值。也適用於[managed 設定](/zh-TW/permissions#managed-settings)以釘選組織範圍的最小值。如需完全阻止啟動的硬底線，請參閱 `requiredMinimumVersion` | `"2.1.100"` |287| `minimumVersion` | 防止背景自動更新和 `claude update` 安裝低於此版本的版本。當從 `"latest"` 頻道切換到 `"stable"` 時透過 `/config` 提示您保持在目前版本或允許降級。選擇保持設定此值。也適用於[managed 設定](/zh-TW/permissions#managed-settings)以釘選組織範圍的最小值。如需完全阻止啟動的硬底線，請參閱 `requiredMinimumVersion` | `"2.1.100"` |

285| `modelOverrides` | 將 Anthropic 模型 ID 對應到提供者特定的模型 ID，例如 Bedrock 推論設定檔 ARN。每個模型選擇器項目在呼叫提供者 API 時使用其對應的值。請參閱[按版本覆蓋模型 ID](/zh-TW/model-config#override-model-ids-per-version) | `{"claude-opus-4-6": "arn:aws:bedrock:..."}` |289| `modelOverrides` | 將 Anthropic 模型 ID 對應到提供者特定的模型 ID，例如 Amazon Bedrock 推論設定檔 ARN。每個模型選擇器項目在呼叫提供者 API 時使用其對應的值。請參閱[按版本覆蓋模型 ID](/zh-TW/model-config#override-model-ids-per-version) | `{"claude-opus-4-6": "arn:aws:bedrock:..."}` |

286| `otelHeadersHelper` | 產生動態 OpenTelemetry 標頭的指令碼。在啟動時和定期執行。使用 [`CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`](/zh-TW/env-vars) 設定重新整理間隔。請參閱[動態標頭](/zh-TW/monitoring-usage#dynamic-headers) | `/bin/generate_otel_headers.sh` |290| `otelHeadersHelper` | 產生動態 OpenTelemetry 標頭的指令碼。在啟動時和定期執行。使用 [`CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`](/zh-TW/env-vars) 設定重新整理間隔。請參閱[動態標頭](/zh-TW/monitoring-usage#dynamic-headers) | `/bin/generate_otel_headers.sh` |

288| `parentSettingsBehavior` | {/* min-version: 2.1.133 */}（Managed 設定僅限）**預設**：`"first-wins"`。控制由嵌入主機流程（例如 Agent SDK 或 IDE 擴充功能）以程式設計方式提供的 managed 設定在同時存在管理員部署的 managed 層級時是否適用。`"first-wins"`：父級提供的設定被丟棄，僅適用管理員層級。`"merge"`：父級提供的設定適用於管理員層級下方，經過篩選以便它們可以收緊 managed 政策但不能放鬆政策。當未部署管理員層級時無效。需要 Claude Code v2.1.133 或更新版本 | `"merge"` |292| `parentSettingsBehavior` | {/* min-version: 2.1.133 */}（Managed 設定僅限）**預設**：`"first-wins"`。控制由嵌入主機流程（例如 Agent SDK 或 IDE 擴充功能）以程式設計方式提供的 managed 設定在同時存在管理員部署的 managed 層級時是否適用。`"first-wins"`：父級提供的設定被丟棄，僅適用管理員層級。`"merge"`：父級提供的設定適用於管理員層級下方，經過篩選以便它們可以收緊 managed 政策但不能放鬆政策。當未部署管理員層級時無效。需要 Claude Code v2.1.133 或更新版本 | `"merge"` |

303| `showThinkingSummaries` | **預設**：`false`。在互動式工作階段中顯示[擴展思考](/zh-TW/model-config#extended-thinking)摘要。未設定或 `false` 時，思考區塊由 API 編輯並顯示為摺疊的存根。編輯只會改變您看到的內容，而不是模型生成的內容：若要減少思考支出，請[降低預算或停用思考](/zh-TW/model-config#extended-thinking)。此設定在非互動模式（`-p`）、Agent SDK 或 IDE 擴充功能（例如 VS Code）中無效 | `true` |307| `showThinkingSummaries` | **預設**：`false`。在互動式工作階段中顯示[擴展思考](/zh-TW/model-config#extended-thinking)摘要。未設定或 `false` 時，思考區塊由 API 編輯並顯示為摺疊的存根。編輯只會改變您看到的內容，而不是模型生成的內容：若要減少思考支出，請[降低預算或停用思考](/zh-TW/model-config#extended-thinking)。此設定在非互動模式（`-p`）、Agent SDK 或 IDE 擴充功能（例如 VS Code）中無效 | `true` |

305| `skillListingBudgetFraction` | {/* min-version: 2.1.105 */}**預設**：`0.01`（1%）。為 Claude 每輪看到的[skill 清單](/zh-TW/skills#skill-descriptions-are-cut-short)保留的模型內容視窗分數。當清單超過預算時，最少使用的 skills 的描述會摺疊為裸名稱，以便 Claude 仍可叫用它們，但不會看到原因。提高以保持更多描述可見，代價是每輪更多內容。`/doctor` 顯示目前的截斷計數和受影響的 skills。需要 Claude Code v2.1.105 或更新版本 | `0.02` |309| `skillListingBudgetFraction` | {/* min-version: 2.1.105 */}**預設**：`0.01`。為 Claude 每輪看到的[skill 清單](/zh-TW/skills#skill-descriptions-are-cut-short)保留的模型內容視窗分數。當清單超過預算時，最少使用的 skills 的描述會摺疊為裸名稱，以便 Claude 仍可叫用它們，但不會看到原因。提高以保持更多描述可見，代價是每輪更多內容。`/doctor` 顯示目前的截斷計數和受影響的 skills。需要 Claude Code v2.1.105 或更新版本 | `0.02` |

306| `skillListingMaxDescChars` | {/* min-version: 2.1.105 */}**預設**：`1536`。[skill 清單](/zh-TW/skills#skill-descriptions-are-cut-short)中每個 skill 的字元上限，Claude 每輪看到的 `description` 和 `when_to_use` 文字的組合。超過此長度的文字會被截斷。提高以保持長描述完整，代價是每輪更多內容；降低以在 [`skillListingBudgetFraction`](#available-settings) 下適應更多 skills。需要 Claude Code v2.1.105 或更新版本 | `2048` |310| `skillListingMaxDescChars` | {/* min-version: 2.1.105 */}**預設**：`1536`。[skill 清單](/zh-TW/skills#skill-descriptions-are-cut-short)中每個 skill 的字元上限，Claude 每輪看到的 `description` 和 `when_to_use` 文字的組合。超過此長度的文字會被截斷。提高以保持長描述完整，代價是每輪更多內容；降低以在 [`skillListingBudgetFraction`](#available-settings) 下適應更多 skills。需要 Claude Code v2.1.105 或更新版本 | `2048` |

307| `skillOverrides` | {/* min-version: 2.1.129 */}按 skill 名稱鍵入的每個 skill 可見性覆蓋。值為 `"on"`、`"name-only"`、`"user-invocable-only"` 或 `"off"`。讓您隱藏或摺疊 skill 而無需編輯其 SKILL.md。不適用於 plugin skills，這些由 `/plugin` 管理。`/skills` 功能表將這些寫入 `.claude/settings.local.json`。請參閱[從設定覆蓋 skill 可見性](/zh-TW/skills#override-skill-visibility-from-settings)。需要 Claude Code v2.1.129 或更新版本 | `{"legacy-context": "name-only", "deploy": "off"}` |311| `skillOverrides` | {/* min-version: 2.1.129 */}按 skill 名稱鍵入的每個 skill 可見性覆蓋。值為 `"on"`、`"name-only"`、`"user-invocable-only"` 或 `"off"`。讓您隱藏或摺疊 skill 而無需編輯其 SKILL.md。不適用於 plugin skills，這些由 `/plugin` 管理。`/skills` 功能表將這些寫入 `.claude/settings.local.json`。請參閱[從設定覆蓋 skill 可見性](/zh-TW/skills#override-skill-visibility-from-settings)。需要 Claude Code v2.1.129 或更新版本 | `{"legacy-context": "name-only", "deploy": "off"}` |

308| `skipWebFetchPreflight` | 跳過[WebFetch 網域安全檢查](/zh-TW/data-usage#webfetch-domain-safety-check)，該檢查在擷取前將每個請求的主機名稱傳送到 `api.anthropic.com`。在阻止流量到 Anthropic 的環境中設定為 `true`，例如 Bedrock、Vertex AI 或 Foundry 部署，具有限制性的出站。跳過時，WebFetch 嘗試任何 URL 而不諮詢黑名單 | `true` |312| `skipWebFetchPreflight` | 跳過[WebFetch 網域安全檢查](/zh-TW/data-usage#webfetch-domain-safety-check)，該檢查在擷取前將每個請求的主機名稱傳送到 `api.anthropic.com`。在阻止流量到 Anthropic 的環境中設定為 `true`，例如 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 部署，具有限制性的出站。跳過時，WebFetch 嘗試任何 URL 而不諮詢黑名單 | `true` |

310| `spinnerTipsOverride` | 使用自訂字串覆蓋微調器提示。`tips`：提示字串陣列。`excludeDefault`：如果為 `true`，僅顯示自訂提示；如果為 `false` 或不存在，自訂提示會與內建提示合併 | `{ "excludeDefault": true, "tips": ["Use our internal tool X"] }` |314| `spinnerTipsOverride` | 使用自訂字串覆蓋微調器提示。`tips`：提示字串陣列。`excludeDefault`：如果為 `true`，僅顯示自訂提示；如果為 `false` 或不存在，自訂提示會與內建提示合併 | `{ "excludeDefault": true, "tips": ["Use our internal tool X"] }` |

311| `spinnerVerbs` | 自訂在微調器中顯示的動作動詞。將 `mode` 設定為 `"replace"` 以僅使用您的動詞，或 `"append"` 以將它們新增到預設值 | `{"mode": "append", "verbs": ["Pondering", "Crafting"]}` |315| `spinnerVerbs` | 自訂在微調器中顯示的動作動詞。將 `mode` 設定為 `"replace"` 以僅使用您的動詞，或 `"append"` 以將它們新增到預設值 | `{"mode": "append", "verbs": ["Pondering", "Crafting"]}` |

319| `theme` | {/* min-version: 2.1.119 */}**預設**：`"dark"`。介面的色彩主題：`"auto"`、`"dark"`、`"light"`、`"dark-daltonized"`、`"light-daltonized"`、`"dark-ansi"`、`"light-ansi"` 或自訂主題參考，例如 `"custom:<slug>"` 或 `"custom:<plugin-name>:<slug>"`。請參閱[建立自訂主題](/zh-TW/terminal-config#create-a-custom-theme)。在 `/config` 中顯示為**主題** | `"dark"` |323| `theme` | {/* min-version: 2.1.119 */}**預設**：`"dark"`。介面的色彩主題：`"auto"`、`"dark"`、`"light"`、`"dark-daltonized"`、`"light-daltonized"`、`"dark-ansi"`、`"light-ansi"` 或自訂主題參考，例如 `"custom:<slug>"` 或 `"custom:<plugin-name>:<slug>"`。請參閱[建立自訂主題](/zh-TW/terminal-config#create-a-custom-theme)。在 `/config` 中顯示為**主題** | `"dark"` |

320| `tui` | 終端機 UI 渲染器。使用 `"fullscreen"` 以取得無閃爍[替代螢幕渲染器](/zh-TW/fullscreen)，具有虛擬化捲軸。使用 `"default"` 以取得經典主螢幕渲染器。透過 `/tui` 設定。您也可以設定 [`CLAUDE_CODE_NO_FLICKER`](/zh-TW/env-vars) 環境變數。背景工作階段從[代理檢視](/zh-TW/agent-view)開啟時，無論此設定如何，始終使用全螢幕渲染器 | `"fullscreen"` |324| `tui` | 終端機 UI 渲染器。使用 `"fullscreen"` 以取得無閃爍[替代螢幕渲染器](/zh-TW/fullscreen)，具有虛擬化捲軸。使用 `"default"` 以取得經典主螢幕渲染器。透過 `/tui` 設定。您也可以設定 [`CLAUDE_CODE_NO_FLICKER`](/zh-TW/env-vars) 環境變數。背景工作階段從[代理檢視](/zh-TW/agent-view)開啟時，無論此設定如何，始終使用全螢幕渲染器 | `"fullscreen"` |

321| `ultracode` | 為工作階段開啟 [ultracode](/zh-TW/workflows#let-claude-decide-with-ultracode)。僅限工作階段，不從 `settings.json` 讀取。透過 `/effort ultracode`、`--settings` 或 Agent SDK 控制請求設定 | `true` |325| `ultracode` | 為工作階段開啟 [ultracode](/zh-TW/workflows#let-claude-decide-with-ultracode)。此金鑰不從 `settings.json` 讀取。透過 `/effort ultracode`、`--settings` 或 Agent SDK 控制請求設定 | `true` |

323| `verbose` | {/* min-version: 2.1.119 */}**預設**：`false`。顯示完整工具輸出而不是截斷摘要。在 `/config` 中顯示為**詳細輸出**。`--verbose` 旗標會覆蓋此設定以進行一個工作階段 | `true` |327| `verbose` | {/* min-version: 2.1.119 */}**預設**：`false`。顯示完整工具輸出而不是截斷摘要。在 `/config` 中顯示為**詳細輸出**。`--verbose` 旗標會覆蓋此設定以進行一個工作階段 | `true` |

339</Note>343</Note>

340 344

341| 金鑰 | 說明 | 範例 |345| 金鑰 | 說明 | 範例 |

342| :------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------- |346| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------- |

343| `autoConnectIde` | **預設**：`false`。當 Claude Code 從外部終端機啟動時自動連線到執行中的 IDE。在 VS Code 或 JetBrains 終端機外執行時在 `/config` 中顯示為**自動連線到 IDE（外部終端機）**。[`CLAUDE_CODE_AUTO_CONNECT_IDE`](/zh-TW/env-vars) 環境變數在設定時會覆蓋此設定 | `true` |347| `autoConnectIde` | **預設**：`false`。當 Claude Code 從外部終端機啟動時自動連線到執行中的 IDE。在 VS Code 或 JetBrains 終端機外執行時在 `/config` 中顯示為**自動連線到 IDE（外部終端機）**。[`CLAUDE_CODE_AUTO_CONNECT_IDE`](/zh-TW/env-vars) 環境變數在設定時會覆蓋此設定 | `true` |

344| `autoInstallIdeExtension` | **預設**：`true`。從 VS Code 終端機執行時自動安裝 Claude Code IDE 擴充功能。在 VS Code 或 JetBrains 終端機內執行時在 `/config` 中顯示為**自動安裝 IDE 擴充功能**。您也可以設定 [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](/zh-TW/env-vars) 環境變數 | `false` |348| `autoInstallIdeExtension` | **預設**：`true`。從 VS Code 終端機執行時自動安裝 Claude Code IDE 擴充功能。在 VS Code 或 JetBrains 終端機內執行時在 `/config` 中顯示為**自動安裝 IDE 擴充功能**。您也可以設定 [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](/zh-TW/env-vars) 環境變數 | `false` |

346| `teammateDefaultModel` | [agent team](/zh-TW/agent-teams) 隊友在生成提示未指定時的預設模型。設定為模型別名（例如 `"sonnet"`），或 `null` 以繼承主管的目前 `/model` 選擇。在 `/config` 中顯示為**預設隊友模型** | `"sonnet"` |350| `teammateDefaultModel` | [agent team](/zh-TW/agent-teams) 隊友在生成提示未指定時的預設模型。設定為模型別名（例如 `"sonnet"`），或 `null` 以繼承主管的目前 `/model` 選擇。在 `/config` 中顯示為**預設隊友模型** | `"sonnet"` |

351| `workflowSizeGuideline` | {/* min-version: 2.1.202 */}**預設**：`unrestricted`，不傳送任何指南。設定 Claude 在其撰寫的動態工作流程中目標的[代理計數](/zh-TW/workflows#set-a-size-guideline)。Claude Code 將值作為建議而不是強制上限傳送給 Claude。接受 `unrestricted`、`small`、`medium` 或 `large`。在 `/config` 中顯示為**動態工作流程大小**。您也可以使用 `/config workflowSizeGuideline=small` 直接設定它。需要 Claude Code v2.1.202 或更新版本。{/* min-version: 2.1.203 */}指南的代理計數也替換[`Large workflow` 警告](/zh-TW/workflows#cost)的預設閾值；該行為需要 Claude Code v2.1.203 或更新版本 | `"small"` |

347 352

348<h3 id="worktree-settings">353<h3 id="worktree-settings">

349 Worktree 設定354 Worktree 設定

352設定 `--worktree` 如何建立和管理 git worktrees。357設定 `--worktree` 如何建立和管理 git worktrees。

353 358

354| 金鑰 | 說明 | 範例 |359| 金鑰 | 說明 | 範例 |

355| :---------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------ |360| :---------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------ |

356| `worktree.baseRef` | 新 worktrees 分支的來源 ref。`"fresh"`（預設）從 `origin/<default-branch>` 分支以取得與遠端相符的乾淨樹。`"head"` 從您目前的本機 `HEAD` 分支，所以未推送的提交和功能分支狀態存在於 worktree 中。適用於 `--worktree`、`EnterWorktree` 工具和 subagent 隔離 | `"head"` |361| `worktree.baseRef` | 新 worktrees 分支的來源 ref。`"fresh"`（預設）從 `origin/<default-branch>` 分支以取得與遠端相符的乾淨樹。`"head"` 從您目前的本機 `HEAD` 分支，所以未推送的提交和功能分支狀態存在於 worktree 中。適用於 `--worktree`、`EnterWorktree` 工具和 subagent 隔離 | `"head"` |

359| `worktree.bgIsolation` | {/* min-version: 2.1.143 */}[背景工作階段](/zh-TW/agent-view#how-file-edits-are-isolated)的隔離模式。`"worktree"`（預設）在呼叫 `EnterWorktree` 之前阻止主簽出中的 `Edit`/`Write`。`"none"` 讓背景工作直接編輯工作副本。需要 Claude Code v2.1.143 或更新版本 | `"none"` |364| `worktree.bgIsolation` | {/* min-version: 2.1.143 */}[背景工作階段](/zh-TW/agent-view#how-file-edits-are-isolated)的隔離模式。`"worktree"`（預設）在呼叫 `EnterWorktree` 之前阻止主簽出中的 `Edit`/`Write`。{/* min-version: 2.1.203 */}在 git 儲存庫外，失敗的 [`WorktreeCreate` hook](/zh-TW/worktrees#non-git-version-control) 會釋放區塊，以便工作階段可以就地編輯工作目錄；需要 Claude Code v2.1.203 或更新版本。`"none"` 讓背景工作直接編輯工作副本。需要 Claude Code v2.1.143 或更新版本 | `"none"` |

360 365

361若要將 gitignored 檔案（如 `.env`）複製到新的 worktrees，請改用專案根目錄中的 [`.worktreeinclude` 檔案](/zh-TW/worktrees#copy-gitignored-files-into-worktrees)，而不是設定。366若要將 gitignored 檔案（如 `.env`）複製到新的 worktrees，請改用專案根目錄中的 [`.worktreeinclude` 檔案](/zh-TW/worktrees#copy-gitignored-files-into-worktrees)，而不是設定。

362 367

365</h3>370</h3>

366 371

367| 金鑰 | 說明 | 範例 |372| 金鑰 | 說明 | 範例 |

368| :---------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------- |373| :---------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------- |

369| `allow` | 允許工具使用的權限規則陣列。工具名稱 globs 僅在字面 `mcp__<server>__` 前綴之後的工具位置支援，例如 `mcp__github__get_*`；server 段必須無 glob。請參閱下面的[權限規則語法](#permission-rule-syntax)以了解模式匹配詳細資訊 | `[ "Bash(git diff *)" ]` |374| `allow` | 允許工具使用的權限規則陣列。工具名稱 globs 僅在字面 `mcp__<server>__` 前綴之後的工具位置支援，例如 `mcp__github__get_*`；server 段必須無 glob。請參閱下面的[權限規則語法](#permission-rule-syntax)以了解模式匹配詳細資訊 | `[ "Bash(git diff *)" ]` |

370| `ask` | 要求在工具使用時確認的權限規則陣列。請參閱下面的[權限規則語法](#permission-rule-syntax) | `[ "Bash(git push *)" ]` |375| `ask` | 要求在工具使用時確認的權限規則陣列。請參閱下面的[權限規則語法](#permission-rule-syntax) | `[ "Bash(git push *)" ]` |

371| `deny` | 拒絕工具使用的權限規則陣列。使用此選項從 Claude Code 存取中排除敏感檔案。工具名稱接受 glob 模式：`"*"` 拒絕每個工具，`"mcp__*"` 拒絕所有 MCP 工具。請參閱[權限規則語法](#permission-rule-syntax)和 [Bash 權限限制](/zh-TW/permissions#tool-specific-permission-rules) | `[ "WebFetch", "Bash(curl *)", "Read(./.env)", "Read(./secrets/**)" ]` |376| `deny` | 拒絕工具使用的權限規則陣列。使用此選項從 Claude Code 存取中排除敏感檔案。工具名稱接受 glob 模式：`"*"` 拒絕每個工具，`"mcp__*"` 拒絕所有 MCP 工具。請參閱[權限規則語法](#permission-rule-syntax)和 [Bash 權限限制](/zh-TW/permissions#tool-specific-permission-rules) | `[ "WebFetch", "Bash(curl *)", "Read(./.env)", "Read(./secrets/**)" ]` |

372| `additionalDirectories` | Claude 有權存取的其他[工作目錄](/zh-TW/permissions#working-directories)。大多數 `.claude/` 設定[未從這些目錄發現](/zh-TW/permissions#additional-directories-grant-file-access-not-configuration) | `[ "../docs/" ]` |377| `additionalDirectories` | Claude 有權存取的其他[工作目錄](/zh-TW/permissions#working-directories)。大多數 `.claude/` 設定[未從這些目錄發現](/zh-TW/permissions#additional-directories-grant-file-access-not-configuration) | `[ "../docs/" ]` |

373| `defaultMode` | 開啟 Claude Code 時的預設[權限模式](/zh-TW/permission-modes)。有效值：`default`、`acceptEdits`、`plan`、`auto`、`dontAsk`、`bypassPermissions`。{/* min-version: 2.1.142 */}自 Claude Code v2.1.142 起，當在專案或本機設定（`.claude/settings.json`、`.claude/settings.local.json`）中設定時，`auto` 會被忽略，因此儲存庫無法授予自己自動模式。改為在 `~/.claude/settings.json` 中設定它。`--permission-mode` CLI 旗標會覆蓋此設定以進行單一工作階段 | `"acceptEdits"` |378| `defaultMode` | 開啟 Claude Code 時的預設[權限模式](/zh-TW/permission-modes)。有效值：`default`、`acceptEdits`、`plan`、`auto`、`dontAsk`、`bypassPermissions` 和 {/* min-version: 2.1.200 */}}`manual` 作為 `default` 的別名，CLI 和 VS Code 和 JetBrains 擴充功能中標記為 Manual 的模式。`manual` 別名需要 Claude Code v2.1.200 或更新版本。{/* min-version: 2.1.142 */}自 Claude Code v2.1.142 起，當在專案或本機設定（`.claude/settings.json`、`.claude/settings.local.json`）中設定時，`auto` 會被忽略，因此儲存庫無法授予自己自動模式。改為在 `~/.claude/settings.json` 中設定它。在 v2.1.142 之前，專案設定可以設定 `auto`。`--permission-mode` CLI 旗標會覆蓋此設定以進行單一工作階段 | `"acceptEdits"` |

374| `disableBypassPermissionsMode` | 設定為 `"disable"` 以防止啟用 `bypassPermissions` 模式。這會停用 `--dangerously-skip-permissions` 旗標。在[managed 設定](/zh-TW/permissions#managed-settings)中最有用，使用者無法覆蓋它 | `"disable"` |379| `disableBypassPermissionsMode` | 設定為 `"disable"` 以防止啟用 `bypassPermissions` 模式。這會停用 `--dangerously-skip-permissions` 旗標。在[managed 設定](/zh-TW/permissions#managed-settings)中最有用，使用者無法覆蓋它 | `"disable"` |

375| `skipDangerousModePermissionPrompt` | 跳過透過 `--dangerously-skip-permissions` 或 `defaultMode: "bypassPermissions"` 進入 bypass permissions 模式之前顯示的確認提示。在專案設定（`.claude/settings.json`）中設定時被忽略，以防止不受信任的儲存庫自動繞過提示 | `true` |380| `skipDangerousModePermissionPrompt` | 跳過透過 `--dangerously-skip-permissions` 或 `defaultMode: "bypassPermissions"` 進入 bypass permissions 模式之前顯示的確認提示。在專案設定（`.claude/settings.json`）中設定時被忽略，以防止不受信任的儲存庫自動繞過提示 | `true` |

376 381

412| `credentials.files` | {/* min-version: 2.1.187 */}Sandboxed 命令無法讀取的認證檔案或目錄。應用與 `filesystem.denyRead` 相同的讀取區塊；單獨的金鑰將認證路徑與 `credentials.envVars` 分組，並與一般檔案系統規則分開。每個項目為 `{ "path": "...", "mode": "deny" }`，僅支援 `deny`。路徑使用與 `filesystem.*` 設定相同的[前綴](#sandbox-path-prefixes)。陣列跨所有設定範圍合併。需要 Claude Code v2.1.187 或更新版本。 | `[{ "path": "~/.aws/credentials", "mode": "deny" }]` |417| `credentials.files` | {/* min-version: 2.1.187 */}Sandboxed 命令無法讀取的認證檔案或目錄。應用與 `filesystem.denyRead` 相同的讀取區塊；單獨的金鑰將認證路徑與 `credentials.envVars` 分組，並與一般檔案系統規則分開。每個項目為 `{ "path": "...", "mode": "deny" }`，僅支援 `deny`。路徑使用與 `filesystem.*` 設定相同的[前綴](#sandbox-path-prefixes)。陣列跨所有設定範圍合併。需要 Claude Code v2.1.187 或更新版本。 | `[{ "path": "~/.aws/credentials", "mode": "deny" }]` |

413| `credentials.envVars` | {/* min-version: 2.1.187 */}環境變數以[保護免受 sandboxed 命令](/zh-TW/sandboxing#protect-credentials)。每個項目有一個 `name` 和一個 `mode`；名稱必須以字母或底線開頭，並僅包含字母、數字和底線。`deny` 從 sandboxed 命令的環境中移除變數。需要 Claude Code v2.1.187 或更新版本。{/* min-version: 2.1.199 */}}`mask` 在 sandbox 內用每個工作階段的 sentinel 值替換變數，而 sandbox 代理在該項目的 `injectHosts` 的出站請求上替換真實值；它需要 `network.tlsTerminate` 和 Claude Code v2.1.199 或更新版本。`mask` 項目僅從使用者、managed 或 CLI `--settings` 設定受尊重，不從 `.claude/settings.json` 或 `.claude/settings.local.json`。陣列跨所有設定範圍合併，當相同變數同時出現兩種模式時 `deny` 優先。 | `[{ "name": "GITHUB_TOKEN", "mode": "deny" }]` |418| `credentials.envVars` | {/* min-version: 2.1.187 */}環境變數以[保護免受 sandboxed 命令](/zh-TW/sandboxing#protect-credentials)。每個項目有一個 `name` 和一個 `mode`；名稱必須以字母或底線開頭，並僅包含字母、數字和底線。`deny` 從 sandboxed 命令的環境中移除變數。需要 Claude Code v2.1.187 或更新版本。{/* min-version: 2.1.199 */}}`mask` 在 sandbox 內用每個工作階段的 sentinel 值替換變數，而 sandbox 代理在該項目的 `injectHosts` 的出站請求上替換真實值；它需要 `network.tlsTerminate` 和 Claude Code v2.1.199 或更新版本。`mask` 項目僅從使用者、managed 或 CLI `--settings` 設定受尊重，不從 `.claude/settings.json` 或 `.claude/settings.local.json`。陣列跨所有設定範圍合併，當相同變數同時出現兩種模式時 `deny` 優先。 | `[{ "name": "GITHUB_TOKEN", "mode": "deny" }]` |

414| `credentials.envVars[].injectHosts` | {{/* min-version: 2.1.199 */}}Sandbox 代理替換 `mask` 項目真實值的主機。每個主機也必須由 `network.allowedDomains` 涵蓋，無論是精確還是通過萬用字元。未設定時，代理在 `network.allowedDomains` 中的每個主機上替換值。當 `mode` 為 `deny` 時被接受但忽略。需要 Claude Code v2.1.199 或更新版本。 | `["api.github.com"]` |419| `credentials.envVars[].injectHosts` | Sandbox 代理替換 `mask` 項目真實值的主機。每個主機也必須由 `network.allowedDomains` 涵蓋，無論是精確還是通過萬用字元。未設定時，代理在 `network.allowedDomains` 中的每個主機上替換值。當 `mode` 為 `deny` 時被接受但忽略。需要 Claude Code v2.1.199 或更新版本。{/* min-version: 2.1.199 */}} | `["api.github.com"]` |

415| `credentials.allowPlaintextInject` | {{/* min-version: 2.1.199 */}}允許 `mask` 替換在純 HTTP 請求以及 TLS 終止的 HTTPS 上。在純 HTTP 上，上游身份未驗證，認證以明文形式傳輸，因此在受信任的測試網路外保持此設定關閉。僅從使用者、managed 或 CLI `--settings` 設定受尊重，不從 `.claude/settings.json` 或 `.claude/settings.local.json`。預設：false。需要 Claude Code v2.1.199 或更新版本。 | `true` |420| `credentials.allowPlaintextInject` | 允許 `mask` 替換在純 HTTP 請求以及 TLS 終止的 HTTPS 上。在純 HTTP 上，上游身份未驗證，認證以明文形式傳輸，因此在受信任的測試網路外保持此設定關閉。僅從使用者、managed 或 CLI `--settings` 設定受尊重，不從 `.claude/settings.json` 或 `.claude/settings.local.json`。預設：false。需要 Claude Code v2.1.199 或更新版本。{/* min-version: 2.1.199 */}} | `true` |

416| `network.allowUnixSockets` | （macOS 僅限）sandbox 中可存取的 Unix socket 路徑。在 Linux 和 WSL2 上被忽略，其中 seccomp 篩選器無法檢查 socket 路徑；改用 `allowAllUnixSockets`。 | `["~/.ssh/agent-socket"]` |421| `network.allowUnixSockets` | （macOS 僅限）sandbox 中可存取的 Unix socket 路徑。在 Linux 和 WSL2 上被忽略，其中 seccomp 篩選器無法檢查 socket 路徑；改用 `allowAllUnixSockets`。 | `["~/.ssh/agent-socket"]` |

417| `network.allowAllUnixSockets` | 允許 sandbox 中的所有 Unix socket 連線。在 Linux 和 WSL2 上，這是允許 Unix sockets 的唯一方式，因為它跳過了 seccomp 篩選器，否則會阻止 `socket(AF_UNIX, ...)` 呼叫。預設：false | `true` |422| `network.allowAllUnixSockets` | 允許 sandbox 中的所有 Unix socket 連線。在 Linux 和 WSL2 上，這是允許 Unix sockets 的唯一方式，因為它跳過了 seccomp 篩選器，否則會阻止 `socket(AF_UNIX, ...)` 呼叫。預設：false | `true` |

422| `network.allowManagedDomainsOnly` | （Managed 設定僅限）僅尊重 managed 設定中的 `allowedDomains` 和 `WebFetch(domain:...)` 允許規則。來自使用者、專案和本機設定的網域會被忽略。非允許的網域會自動阻止，不會提示使用者。拒絕的網域仍從所有來源受尊重。預設：false | `true` |427| `network.allowManagedDomainsOnly` | （Managed 設定僅限）僅尊重 managed 設定中的 `allowedDomains` 和 `WebFetch(domain:...)` 允許規則。來自使用者、專案和本機設定的網域會被忽略。非允許的網域會自動阻止，不會提示使用者。拒絕的網域仍從所有來源受尊重。預設：false | `true` |

423| `network.httpProxyPort` | 如果您想帶上自己的代理，使用的 HTTP 代理連接埠。如果未指定，Claude 將執行自己的代理。 | `8080` |428| `network.httpProxyPort` | 如果您想帶上自己的代理，使用的 HTTP 代理連接埠。如果未指定，Claude 將執行自己的代理。 | `8080` |

424| `network.socksProxyPort` | 如果您想帶上自己的代理，使用的 SOCKS5 代理連接埠。如果未指定，Claude 將執行自己的代理。 | `8081` |429| `network.socksProxyPort` | 如果您想帶上自己的代理，使用的 SOCKS5 代理連接埠。如果未指定，Claude 將執行自己的代理。 | `8081` |

425| `network.tlsTerminate` | {{/* min-version: 2.1.199 */}}實驗性。在 sandbox 代理內終止 TLS，以便它可以讀取 HTTPS 請求的內容。[credential substitution](/zh-TW/sandboxing#protect-credentials) 的 `mask` 需要。設定 `{}` 以為工作階段產生臨時憑證授權單位，或設定 `caCertPath` 和 `caKeyPath` 以使用您自己的。僅從使用者、managed 或 CLI `--settings` 設定受尊重，不從 `.claude/settings.json` 或 `.claude/settings.local.json`。需要 Claude Code v2.1.199 或更新版本。 | `{}` |430| `network.tlsTerminate` | 實驗性。在 sandbox 代理內終止 TLS，以便它可以讀取 HTTPS 請求的內容。[credential substitution](/zh-TW/sandboxing#protect-credentials) 的 `mask` 需要。設定 `{}` 以為工作階段產生臨時憑證授權單位，或設定 `caCertPath` 和 `caKeyPath` 以使用您自己的。僅從使用者、managed 或 CLI `--settings` 設定受尊重，不從 `.claude/settings.json` 或 `.claude/settings.local.json`。需要 Claude Code v2.1.199 或更新版本。{/* min-version: 2.1.199 */}} | `{}` |

427| `enableWeakerNetworkIsolation` | （macOS 僅限）允許在 sandbox 中存取系統 TLS 信任服務（`com.apple.trustd.agent`）。使用 `httpProxyPort` 和自訂 CA 的 MITM 代理時，Go 型工具（如 `gh`、`gcloud` 和 `terraform`）需要驗證 TLS 憑證。**透過開啟潛在的資料外洩路徑降低安全性**。預設：false | `true` |432| `enableWeakerNetworkIsolation` | （macOS 僅限）允許在 sandbox 中存取系統 TLS 信任服務（`com.apple.trustd.agent`）。使用 `httpProxyPort` 和自訂 CA 的 MITM 代理時，Go 型工具（如 `gh`、`gcloud` 和 `terraform`）需要驗證 TLS 憑證。**透過開啟潛在的資料外洩路徑降低安全性**。預設：false | `true` |

428| `allowAppleEvents` | （macOS 僅限）允許 sandboxed 命令傳送 Apple Events。`open`、`osascript` 和在瀏覽器中開啟 URL 的工具需要，否則會失敗並出現錯誤 `-600`。**移除程式碼執行隔離。** Sandboxed 命令可以啟動其他應用程式 unsandboxed，無需使用者提示；它們也可以傳送 AppleScript 命令到執行中的應用程式（例如終端機），受限於每個應用程式的 macOS 自動化同意提示 (TCC)。僅從使用者、managed 或 CLI 設定受尊重，不從專案設定。預設：false | `true` |433| `allowAppleEvents` | （macOS 僅限）允許 sandboxed 命令傳送 Apple Events。`open`、`osascript` 和在瀏覽器中開啟 URL 的工具需要，否則會失敗並出現錯誤 `-600`。**移除程式碼執行隔離。** Sandboxed 命令可以啟動其他應用程式 unsandboxed，無需使用者提示；它們也可以傳送 AppleScript 命令到執行中的應用程式（例如終端機），受限於每個應用程式的 macOS 自動化同意提示 (TCC)。僅從使用者、managed 或 CLI 設定受尊重，不從專案設定。預設：false | `true` |

660 665

661設定按優先順序順序應用。從最高到最低：666設定按優先順序順序應用。從最高到最低：

662 667

6631. **Managed 設定**（[伺服器管理](/zh-TW/server-managed-settings)、[MDM/OS 層級政策](#configuration-scopes)或 [managed 設定](/zh-TW/settings#settings-files)）6681. **Managed 設定**（[伺服器管理](/zh-TW/server-managed-settings)、[MDM/OS 層級政策](#configuration-scopes)或 [managed 設定](#settings-files)）

664 * 由 IT 透過伺服器傳遞、MDM 設定檔案、登錄政策或 managed 設定檔案部署的政策669 * 由 IT 透過伺服器傳遞、MDM 設定檔案、登錄政策或 managed 設定檔案部署的政策

665 * 無法被任何其他層級覆蓋，包括命令列引數670 * 無法被任何其他層級覆蓋，包括命令列引數

666 * 在 managed 層級內，僅使用一個 managed 來源，優先順序為：[`policyHelper`](#compute-managed-settings-with-a-policy-helper) 輸出（當設定時是唯一使用的 managed 來源）> 遠端（claude.ai [伺服器管理](/zh-TW/server-managed-settings)或 [Claude apps gateway](/zh-TW/claude-apps-gateway)傳遞）> MDM/OS 層級政策 > 檔案型（`managed-settings.d/*.json` 和 `managed-settings.json` 合併在一起）> HKCU 登錄（僅限 Windows）。來源不跨層級合併，有一個例外：sandbox 鎖定金鑰 `sandbox.network.allowManagedDomainsOnly` 和 `sandbox.filesystem.allowManagedReadPathsOnly` 及其相關聯的白名單、`allowAllClaudeAiMcps` 和 sandbox 二進位路徑 `sandbox.bwrapPath` 和 `sandbox.socatPath` 在任何管理員控制的 managed 來源設定它們時受尊重；使用者可寫的 HKCU 層級被排除。671 * 在 managed 層級內，僅使用一個 managed 來源，其他來源被忽略而不是合併。優先順序，最高優先：

672 * [`policyHelper`](#compute-managed-settings-with-a-policy-helper) 輸出：當設定時，這是唯一使用的 managed 來源

673 * 遠端（claude.ai [伺服器管理](/zh-TW/server-managed-settings)或 [Claude apps gateway](/zh-TW/claude-apps-gateway)傳遞）

674 * MDM/OS 層級政策

675 * 檔案型（`managed-settings.d/*.json` 和 `managed-settings.json`，合併在一起）

676 * HKCU 登錄（僅限 Windows）

677 * 少數金鑰是例外，在任何管理員控制的 managed 來源設定它們時受尊重，而不是僅由獲勝的來源。使用者可寫的 HKCU 登錄來源被排除。例外金鑰為：

678 * sandbox 鎖定金鑰 `sandbox.network.allowManagedDomainsOnly` 和 `sandbox.filesystem.allowManagedReadPathsOnly`，以及其相關聯的白名單

679 * `allowAllClaudeAiMcps`

680 * sandbox 二進位路徑 `sandbox.bwrapPath` 和 `sandbox.socatPath`

681 * [`forceRemoteSettingsRefresh`](/zh-TW/server-managed-settings)

667 * 嵌入主機（例如 Claude Desktop）可以透過 SDK `managedSettings` 選項提供政策。預設情況下，當任何 admin 部署的 managed 來源存在時，此會被忽略：伺服器管理的設定、MDM 或 OS 層級政策，或 managed 設定檔案。使用者可寫的 HKCU 登錄回退不計為 admin 部署的來源。管理員可以透過設定 [`parentSettingsBehavior`](#available-settings) 為 `"merge"` 來選擇加入。嵌入器的值會被篩選，以便它們可以收緊 managed 政策但不能放鬆政策。682 * 嵌入主機（例如 Claude Desktop）可以透過 SDK `managedSettings` 選項提供政策。預設情況下，當任何 admin 部署的 managed 來源存在時，此會被忽略：伺服器管理的設定、MDM 或 OS 層級政策，或 managed 設定檔案。使用者可寫的 HKCU 登錄回退不計為 admin 部署的來源。管理員可以透過設定 [`parentSettingsBehavior`](#available-settings) 為 `"merge"` 來選擇加入。嵌入器的值會被篩選，以便它們可以收緊 managed 政策但不能放鬆政策。

668 683

6692. **命令列引數**6842. **命令列引數**

695 驗證使用中的設定710 驗證使用中的設定

696</h3>711</h3>

697 712

698在 Claude Code 內執行 `/status` 以查看哪些設定來源是使用中的。在功能表內，**Status** 標籤包含 `Setting sources` 行，列出 Claude Code 為目前工作階段載入的每一層，例如 `User settings` 或 `Project local settings`。當[managed 設定](/zh-TW/admin-setup#decide-how-settings-reach-devices)生效時，項目會在括號中顯示傳遞頻道，例如 `Enterprise managed settings (remote)`、`(plist)`、`(HKLM)`、`(HKCU)` 或 `(file)`。層級僅在該來源以至少一個金鑰載入時才出現在清單中，因此空清單表示未找到任何設定來源。713在 Claude Code 內執行 `/status` 以查看哪些設定來源是使用中的。在功能表內，**Status** 標籤包含 `Setting sources` 行，列出 Claude Code 為目前工作階段載入的每一層，例如 `User settings` 或 `Project local settings`。當[managed 設定](/zh-TW/admin-setup#decide-how-settings-reach-devices)生效時，項目會在括號中顯示傳遞頻道，例如 `Enterprise managed settings (remote)`、`(plist)`、`(HKLM)`、`(HKCU)` 或 `(file)`。`remote` 頻道涵蓋 claude.ai 伺服器管理的設定和 [Claude apps gateway](/zh-TW/claude-apps-gateway)傳遞的政策。層級僅在該來源以至少一個金鑰載入時才出現在清單中，因此空清單表示未找到任何設定來源。

699 714

700`Setting sources` 行確認正在讀取哪些來源。它不顯示哪一層提供了每個個別金鑰。同一對話框中的 **Config** 標籤是固定切換集（例如主題和詳細輸出）的編輯器，而不是您 `settings.json` 內容的檢視。715`Setting sources` 行確認正在讀取哪些來源。它不顯示哪一層提供了每個個別金鑰。同一對話框中的 **Config** 標籤是固定切換集（例如主題和詳細輸出）的編輯器，而不是您 `settings.json` 內容的檢視。

701 716

setup.md +9 −3

Details

188 驗證身份188 驗證身份

189</h2>189</h2>

190 190

191Claude Code 需要 Pro、Max、Team、Enterprise 或 Console 帳戶。免費的 Claude.ai 方案不包括 Claude Code 存取權。您也可以透過第三方 API 提供者（如 [Amazon Bedrock](/zh-TW/amazon-bedrock)、[Google Vertex AI](/zh-TW/google-vertex-ai) 或 [Microsoft Foundry](/zh-TW/microsoft-foundry)）使用 Claude Code。191Claude Code 需要 Pro、Max、Team、Enterprise 或 Console 帳戶。免費的 Claude.ai 方案不包括 Claude Code 存取權。您也可以透過第三方 API 提供者（如 [Amazon Bedrock](/zh-TW/amazon-bedrock)、[Google Cloud's Agent Platform](/zh-TW/google-vertex-ai) 或 [Microsoft Foundry](/zh-TW/microsoft-foundry)）使用 Claude Code。

192 192

193安裝後，執行 `claude` 並按照瀏覽器提示登入。請參閱[驗證](/zh-TW/authentication)以了解所有帳戶類型和團隊設定選項。193安裝後，執行 `claude` 並按照瀏覽器提示登入。請參閱[驗證](/zh-TW/authentication)以了解所有帳戶類型和團隊設定選項。

194 194

376 376

377<Tabs>377<Tabs>

378 <Tab title="apt">378 <Tab title="apt">

379 適用於 Debian 和 Ubuntu。下列命令配置 `stable` 通道：379 適用於 Debian 和 Ubuntu。下列安裝命令使用 `curl` 下載簽署金鑰，新鮮的 Debian 和 Ubuntu 安裝可能不包含此命令。如果下載失敗並出現 `sudo: curl: command not found`，請先安裝 curl：

380

381 ```bash theme={null}

382 sudo apt install curl

383 ```

384

385 下列命令配置 `stable` 通道：

380 386

381 ```bash theme={null}387 ```bash theme={null}

382 sudo install -d -m 0755 /etc/apt/keyrings388 sudo install -d -m 0755 /etc/apt/keyrings

526 </Step>532 </Step>

527 533

528 <Step title="根據資訊清單檢查二進位檔案">534 <Step title="根據資訊清單檢查二進位檔案">

529 將您下載的二進位檔案的 SHA256 校驗和與 `manifest.json` 中 `platforms.<platform>.checksum` 下列出的值進行比較。535 將您下載的二進位檔案的 SHA256 校驗和與 `manifest.json` 中 `platforms.<platform>.checksum` 下列出的值進行比較。下列命令假設目前目錄中有 `claude` 二進位檔案。若要改為驗證已安裝的原生二進位檔案，請針對 `~/.local/share/claude/versions/VERSION` 執行命令，將 VERSION 替換為您在步驟 2 中設定的發佈。

530 536

531 <Tabs>537 <Tabs>

532 <Tab title="Linux">538 <Tab title="Linux">

skills.md +11 −3

Details

22 捆綁的 skills22 捆綁的 skills

23</h2>23</h2>

24 24

25Claude Code 包含一組捆綁的 skills，在每個工作階段中都可用，除非使用 [`disableBundledSkills`](/zh-TW/settings#available-settings) 設定停用，包括 `/code-review`、`/batch`、`/debug`、`/loop` 和 `/claude-api`。與大多數內建命令不同，內建命令直接執行固定邏輯，捆綁的 skills 是基於提示的：它們為 Claude 提供詳細的劇本，並讓它使用其工具來協調工作。您叫用它們的方式與任何其他 skill 相同，輸入 `/` 後跟 skill 名稱。25Claude Code 包含一組捆綁的 skills，在每個工作階段中都可用，除非使用 [`disableBundledSkills`](/zh-TW/settings#available-settings) 設定停用，包括 `/doctor`、`/code-review`、`/batch`、`/debug`、`/loop` 和 `/claude-api`。與大多數內建命令不同，內建命令直接執行固定邏輯，捆綁的 skills 是基於提示的：它們為 Claude 提供詳細的劇本，並讓它使用其工具來協調工作。您叫用它們的方式與任何其他 skill 相同，輸入 `/` 後跟 skill 名稱。

27[`/doctor`](/zh-TW/commands#all-commands) 設定檢查是 Claude Code v2.1.205 及更新版本中 `disableBundledSkills` 的一個例外：當設定開啟時，它仍然可以輸入。若要隱藏它，請設定 `DISABLE_DOCTOR_COMMAND` 環境變數或 [`skillOverrides`](#override-skill-visibility-from-settings) 項目 `"doctor": "off"`。在 v2.1.205 之前，`/doctor` 是內建命令而不是捆綁的 skill。

26 28

27捆綁的 skills 在[命令參考](/zh-TW/commands)中與內建命令一起列出，在「目的」欄中標記為 **Skill**。29捆綁的 skills 在[命令參考](/zh-TW/commands)中與內建命令一起列出，在「目的」欄中標記為 **Skill**。

28 30

129 131

130輸入 `/deploy` 執行專案根目錄 skill。輸入限定名稱 `/apps/web:deploy` 以明確執行巢狀變體。132輸入 `/deploy` 執行專案根目錄 skill。輸入限定名稱 `/apps/web:deploy` 以明確執行巢狀變體。

131 133

134當您或 Claude 叫用未限定的名稱時，專案根目錄 skill 會載入，Claude Code 會將目錄限定變體的清單附加到其內容中，並附帶指示以也叫用任何目錄包含 Claude 正在處理的檔案的變體。因此，巢狀 skill 在其目錄中的工作時仍然適用，即使只叫用未限定的名稱。需要 Claude Code v2.1.203 或更新版本。

135

132一個 `<skill-name>` 項目在企業、個人或專案位置可以是磁碟上其他位置的目錄的符號連結。Claude Code 遵循符號連結並從目標目錄讀取 `SKILL.md`，如果相同的目標可從多個位置到達，Claude Code 會載入該 skill 一次。外掛 skills 以不同方式處理符號連結；請參閱[使用符號連結在市集中共享檔案](/zh-TW/plugins-reference#share-files-within-a-marketplace-with-symlinks)。136一個 `<skill-name>` 項目在企業、個人或專案位置可以是磁碟上其他位置的目錄的符號連結。Claude Code 遵循符號連結並從目標目錄讀取 `SKILL.md`，如果相同的目標可從多個位置到達，Claude Code 會載入該 skill 一次。外掛 skills 以不同方式處理符號連結；請參閱[使用符號連結在市集中共享檔案](/zh-TW/plugins-reference#share-files-within-a-marketplace-with-symlinks)。

133 137

134<Note>138<Note>

390 394

391當您或 Claude 叫用 skill 時，呈現的 `SKILL.md` 內容作為單一訊息進入對話，並在工作階段的其餘部分保持在那裡。Claude Code 不會在稍後的回合中重新讀取 skill 檔案，因此應將應該在整個任務中應用的指導寫成常設說明，而不是一次性步驟。395當您或 Claude 叫用 skill 時，呈現的 `SKILL.md` 內容作為單一訊息進入對話，並在工作階段的其餘部分保持在那裡。Claude Code 不會在稍後的回合中重新讀取 skill 檔案，因此應將應該在整個任務中應用的指導寫成常設說明，而不是一次性步驟。

392 396

397當 Claude 重新叫用其呈現內容與已在上下文中的副本相同的 skill 時，Claude Code 會新增一個簡短的註記，表示該 skill 已載入，而不是內容的第二份副本。當呈現內容不同時（因為引數改變或[動態上下文](#inject-dynamic-context)命令產生了新輸出），Claude Code 會附加完整內容。在 v2.1.202 之前，每次重新叫用都會附加 skill 說明的另一份完整副本。

398

393[Auto-compact](/zh-TW/how-claude-code-works#when-context-fills-up) 在令牌預算內轉發叫用的 skills。當對話被摘要以釋放上下文時，Claude Code 在摘要後重新附加每個 skill 的最新叫用，保留每個的前 5,000 個令牌。重新附加的 skills 共享 25,000 個令牌的組合預算。Claude Code 從最近叫用的 skill 開始填充此預算，因此如果您在一個工作階段中叫用了許多 skills，較舊的 skills 可能在 compaction 後完全被丟棄。399[Auto-compact](/zh-TW/how-claude-code-works#when-context-fills-up) 在令牌預算內轉發叫用的 skills。當對話被摘要以釋放上下文時，Claude Code 在摘要後重新附加每個 skill 的最新叫用，保留每個的前 5,000 個令牌。重新附加的 skills 共享 25,000 個令牌的組合預算。Claude Code 從最近叫用的 skill 開始填充此預算，因此如果您在一個工作階段中叫用了許多 skills，較舊的 skills 可能在 compaction 後完全被丟棄。

394 400

395如果 skill 在第一個回應後似乎停止影響行為，內容通常仍然存在，模型正在選擇其他工具或方法。加強 skill 的 `description` 和說明，以便模型繼續偏好它，或使用 [hooks](/zh-TW/hooks) 來確定性地強制行為。如果 skill 很大或您在它之後叫用了其他幾個，請在 compaction 後重新叫用它以恢復完整內容。401如果 skill 在第一個回應後似乎停止影響行為，內容通常仍然存在，模型正在選擇其他工具或方法。加強 skill 的 `description` 和說明，以便模型繼續偏好它，或使用 [hooks](/zh-TW/hooks) 來確定性地強制行為。如果 skill 很大或您在它之後叫用了其他幾個，請在 compaction 後重新叫用它以恢復完整內容。

908 Skill 描述被截斷914 Skill 描述被截斷

909</h3>915</h3>

910 916

911Skill 描述會載入上下文，以便 Claude 知道可用的內容。所有 skill 名稱始終包含在內，但如果您有許多 skills，描述會被縮短以適應字元預算，這可能會去除 Claude 需要匹配您的請求的關鍵字。預算在模型上下文視窗的 1% 處動態縮放。當預算溢出時，您最少叫用的 skills 的描述會首先被捨棄，因此您實際使用的 skills 會保留其完整文字。執行 `/doctor` 以查看有多少 skill 描述被縮短或捨棄，以及哪些 skills 受到影響。917Claude Code 會將 skill 名稱和描述的清單載入上下文，以便 Claude 知道可用的內容。清單始終包含每個 skill 名稱，但如果您有許多 skills，Claude Code 會縮短描述以適應清單的字元預算，這可能會去除 Claude 需要匹配您的請求的關鍵字。預算在模型上下文視窗的 1% 處動態縮放。當清單超出預算時，Claude Code 會從您最少叫用的 skills 開始捨棄描述，因此您使用最多的 skills 會保留其完整文字。

918

919執行 `/doctor` 以估計清單的上下文成本及其最大貢獻者。當清單超出預算時，Claude Code 也會將警告寫入偵錯日誌，可透過 [`--debug`](/zh-TW/cli-reference#cli-flags) 查看。

912 920

913自 v2.1.196 起，`/context` 中的 Skills 列會報告套用預算後的列表大小，因此它與模型接收的內容相符。較早的版本會計算每個描述的完整文字，因此該列可能會顯示一個比預算 `/doctor` 報告的值大幾倍的數值。921`/context` 中的 Skills 列會報告套用預算後的清單大小，因此它與模型接收的內容相符。在 v2.1.196 之前，該列會計算每個描述的完整文字，可能會顯示一個比設定的預算大幾倍的值。

914 922

915若要提高預算，請設定 [`skillListingBudgetFraction`](/zh-TW/settings#available-settings) 設定（例如 `0.02` = 2%）或 `SLASH_COMMAND_TOOL_CHAR_BUDGET` 環境變數為固定字元計數。若要為其他 skills 釋放預算，請在 [`skillOverrides`](#override-skill-visibility-from-settings) 中將低優先順序項目設定為 `"name-only"`，以便它們列出而不顯示描述。您也可以在來源處修剪 `description` 和 `when_to_use` 文字：前置關鍵使用案例，因為每個項目的結合文字無論預算如何都限制在 1,536 個字元。此上限可透過 [`skillListingMaxDescChars`](/zh-TW/settings#available-settings) 進行設定。923若要提高預算，請設定 [`skillListingBudgetFraction`](/zh-TW/settings#available-settings) 設定（例如 `0.02` = 2%）或 `SLASH_COMMAND_TOOL_CHAR_BUDGET` 環境變數為固定字元計數。若要為其他 skills 釋放預算，請在 [`skillOverrides`](#override-skill-visibility-from-settings) 中將低優先順序項目設定為 `"name-only"`，以便它們列出而不顯示描述。您也可以在來源處修剪 `description` 和 `when_to_use` 文字：前置關鍵使用案例，因為每個項目的結合文字無論預算如何都限制在 1,536 個字元。此上限可透過 [`skillListingMaxDescChars`](/zh-TW/settings#available-settings) 進行設定。

916 924

statusline.md +3 −1

Details

1040}1040}

1041```1041```

1042 1042

1043命令在每個重新整理刻度上執行一次，所有可見的子代理行作為單個 JSON 物件在 stdin 上傳遞。輸入包括[基本 hook 欄位](/zh-TW/hooks#common-input-fields)加上 `columns`（可用行寬度）和 `tasks` 陣列，其中每個任務具有 `id`、`name`、`type`、`status`、`description`、`label`、`startTime`、`tokenCount`、`tokenSamples` 和 `cwd`。1043命令在每個重新整理刻度上執行一次，所有可見的子代理行作為單個 JSON 物件在 stdin 上傳遞。輸入包括[基本 hook 欄位](/zh-TW/hooks#common-input-fields)、`columns` 欄位（可用行寬度）和 `tasks` 陣列。每個任務具有 `id`、`name`、`type`、`status`、`description`、`label`、`startTime`、`model`、`contextWindowSize`、`tokenCount`、`tokenSamples` 和 `cwd`。

1044

1045每個任務的 `model` 欄位是任務執行所在的已解析模型 ID。`contextWindowSize` 是該模型的內容視窗（以 token 計），計算方式與主狀態列的 `context_window.context_window_size` 相同，因此您可以從 `tokenCount` 呈現每行百分比。兩個欄位都需要 Claude Code v2.1.205 或更新版本，並且對於模型尚未解析的任務會被省略。

1044 1046

1045將一個 JSON 行寫入 stdout，每行您想要覆蓋，形式為 `{"id": "<task id>", "content": "<row body>"}` 。`content` 字串按原樣呈現，包括 ANSI 顏色和 OSC 8 超連結。省略任務的 `id` 以保持該行的預設呈現；發出空 `content` 字串以隱藏它。1047將一個 JSON 行寫入 stdout，每行您想要覆蓋，形式為 `{"id": "<task id>", "content": "<row body>"}` 。`content` 字串按原樣呈現，包括 ANSI 顏色和 OSC 8 超連結。省略任務的 `id` 以保持該行的預設呈現；發出空 `content` 字串以隱藏它。

1046 1048

sub-agents.md +10 −4

Details

183 183

184Claude Code 會遞迴掃描 `.claude/agents/` 和 `~/.claude/agents/`，因此您可以將定義組織到子資料夾中，例如 `agents/review/` 或 `agents/research/`。子目錄路徑不會影響 subagent 的識別或呼叫方式，因為身份僅來自 `name` frontmatter 欄位。184Claude Code 會遞迴掃描 `.claude/agents/` 和 `~/.claude/agents/`，因此您可以將定義組織到子資料夾中，例如 `agents/review/` 或 `agents/research/`。子目錄路徑不會影響 subagent 的識別或呼叫方式，因為身份僅來自 `name` frontmatter 欄位。

185 185

186在整個樹中保持 `name` 值唯一：如果一個範圍內的兩個檔案宣告相同的名稱，Claude Code 只會載入其中一個。{/* min-version: 2.1.196 */}自 v2.1.196 起，執行 `/doctor` 會報告同範圍的重複代理名稱，並顯示哪個定義處於活動狀態。186在整個樹中保持 `name` 值唯一：如果一個 `.claude/agents/` 目錄下的兩個檔案（包括其子資料夾）宣告相同的名稱，Claude Code 只會載入其中一個，由檔案系統讀取順序選擇，而不是有文件記載的優先級。在巢狀專案目錄中，最接近工作目錄的定義獲勝，如上所述。{/* min-version: 2.1.205 */}[`/doctor`](/zh-TW/commands#all-commands) 設定檢查會報告同一目錄中共享名稱的檔案，並建議重新命名或移除除一個以外的所有檔案。在 v2.1.205 之前，`/doctor` 開啟診斷畫面，列出重複項並顯示哪個定義處於活動狀態。

187 187

188外掛程式 `agents/` 目錄也會遞迴掃描。與專案和使用者範圍不同，外掛程式 `agents/` 目錄內的子資料夾成為 [scoped identifier](#invoke-subagents-explicitly) 的一部分：外掛程式 `my-plugin` 中位於 `agents/review/security.md` 的檔案註冊為 `my-plugin:review:security`。188外掛程式 `agents/` 目錄也會遞迴掃描。與專案和使用者範圍不同，外掛程式 `agents/` 目錄內的子資料夾成為 [scoped identifier](#invoke-subagents-explicitly) 的一部分：外掛程式 `my-plugin` 中位於 `agents/review/security.md` 的檔案註冊為 `my-plugin:review:security`。

189 189

268 268

269Frontmatter 定義 subagent 的中繼資料和配置。主體成為指導 subagent 行為的系統提示。Subagents 只接收此系統提示（加上基本環境詳細資訊，如工作目錄），而不是完整的 Claude Code 系統提示。269Frontmatter 定義 subagent 的中繼資料和配置。主體成為指導 subagent 行為的系統提示。Subagents 只接收此系統提示（加上基本環境詳細資訊，如工作目錄），而不是完整的 Claude Code 系統提示。

270 270

271在 [non-interactive mode](/zh-TW/headless) 中，[`--append-subagent-system-prompt`](/zh-TW/cli-reference#cli-flags) 標誌將您提供的文字附加到每個 subagent 的系統提示末尾，包括巢狀 subagents。需要 Claude Code v2.1.205 或更高版本。

272

271一個 subagent 在主要對話的目前工作目錄中啟動。在 subagent 內，`cd` 命令不會在 Bash 或 PowerShell 工具呼叫之間持續，也不會影響主要對話的工作目錄。若要改為給 subagent 儲存庫的隔離副本，請設定 [`isolation: worktree`](#supported-frontmatter-fields)。273一個 subagent 在主要對話的目前工作目錄中啟動。在 subagent 內，`cd` 命令不會在 Bash 或 PowerShell 工具呼叫之間持續，也不會影響主要對話的工作目錄。若要改為給 subagent 儲存庫的隔離副本，請設定 [`isolation: worktree`](#supported-frontmatter-fields)。

272 274

275{/* min-version: 2.1.203 */}具有 `isolation: worktree` 的 subagent 在其 worktree 內執行其 Bash 和 PowerShell 命令。一個工作目錄解析到您的主要簽出的命令（例如，因為 subagent 執行時 worktree 目錄被移除）會失敗並出現錯誤。在 v2.1.203 之前，此類命令可能在主要簽出中執行。

276

273<h4 id="supported-frontmatter-fields">277<h4 id="supported-frontmatter-fields">

274 支援的 frontmatter 欄位278 支援的 frontmatter 欄位

275</h4>279</h4>

277以下欄位可用於 YAML frontmatter。只有 `name` 和 `description` 是必需的。281以下欄位可用於 YAML frontmatter。只有 `name` 和 `description` 是必需的。

278 282

279| Field | 必需 | Description |283| Field | 必需 | Description |

280| :---------------- | :- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |284| :---------------- | :- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

281| `name` | 是 | 使用小寫字母和連字號的唯一識別碼。[Hooks](/zh-TW/hooks#subagentstart) 將此值作為 `agent_type` 接收。檔案名稱不必相符 |285| `name` | 是 | 使用小寫字母和連字號的唯一識別碼。[Hooks](/zh-TW/hooks#subagentstart) 將此值作為 `agent_type` 接收。檔案名稱不必相符 |

282| `description` | 是 | Claude 何時應委派給此 subagent |286| `description` | 是 | Claude 何時應委派給此 subagent |

283| `tools` | 否 | [Tools](#available-tools) subagent 可以使用。如果省略，繼承所有工具。若要將 Skills 預載入上下文，請使用 `skills` 欄位而不是在此列出 `Skill` |287| `tools` | 否 | [Tools](#available-tools) subagent 可以使用。如果省略，繼承所有工具。若要將 Skills 預載入上下文，請使用 `skills` 欄位而不是在此列出 `Skill` |

284| `disallowedTools` | 否 | 要拒絕的工具，從繼承或指定的清單中移除 |288| `disallowedTools` | 否 | 要拒絕的工具，從繼承或指定的清單中移除 |

285| `model` | 否 | [Model](#choose-a-model) 使用：`sonnet`、`opus`、`haiku`、`fable`、完整模型 ID（例如，`claude-opus-4-8`）或 `inherit`。預設為 `inherit` |289| `model` | 否 | [Model](#choose-a-model) 使用：`sonnet`、`opus`、`haiku`、`fable`、完整模型 ID（例如，`claude-opus-4-8`）或 `inherit`。預設為 `inherit` |

286| `permissionMode` | 否 | [Permission mode](#permission-modes)：`default`、`acceptEdits`、`auto`、`dontAsk`、`bypassPermissions` 或 `plan`。針對 [plugin subagents](#choose-the-subagent-scope) 被忽略 |290| `permissionMode` | 否 | [Permission mode](#permission-modes)：`default`、`acceptEdits`、`auto`、`dontAsk`、`bypassPermissions`、`plan` 或 {/* min-version: 2.1.200 */}`manual` 作為 `default` 的別名。`manual` 別名需要 Claude Code v2.1.200 或更高版本。針對 [plugin subagents](#choose-the-subagent-scope) 被忽略 |

287| `maxTurns` | 否 | subagent 停止前的最大代理轉數 |291| `maxTurns` | 否 | subagent 停止前的最大代理轉數 |

288| `skills` | 否 | [Skills](/zh-TW/skills) 在啟動時預載入到 subagent 的上下文中。注入完整技能內容，而不僅僅是描述。Subagents 仍然可以透過 Skill 工具呼叫未列出的專案、使用者和外掛程式技能 |292| `skills` | 否 | [Skills](/zh-TW/skills) 在啟動時預載入到 subagent 的上下文中。注入完整技能內容，而不僅僅是描述。Subagents 仍然可以透過 Skill 工具呼叫未列出的專案、使用者和外掛程式技能 |

289| `mcpServers` | 否 | [MCP servers](/zh-TW/mcp) 可用於此 subagent。每個條目要麼是參考已配置伺服器的伺服器名稱（例如，`"slack"`），要麼是內聯定義，其中伺服器名稱為鍵，完整 [MCP server config](/zh-TW/mcp#installing-mcp-servers) 為值。針對 [plugin subagents](#choose-the-subagent-scope) 被忽略 |293| `mcpServers` | 否 | [MCP servers](/zh-TW/mcp) 可用於此 subagent。每個條目要麼是參考已配置伺服器的伺服器名稱（例如，`"slack"`），要麼是內聯定義，其中伺服器名稱為鍵，完整 [MCP server config](/zh-TW/mcp#installing-mcp-servers) 為值。針對 [plugin subagents](#choose-the-subagent-scope) 被忽略 |

792 796

793{/* min-version: 2.1.199 */}自 v2.1.199 起，subagent 的執行因 API 錯誤（例如使用限制或重複的伺服器錯誤）而結束時，會將該失敗報告回 Claude，而不是將錯誤文字作為 subagent 的發現返回。Claude 接收的內容取決於 subagent 執行的位置：797{/* min-version: 2.1.199 */}自 v2.1.199 起，subagent 的執行因 API 錯誤（例如使用限制或重複的伺服器錯誤）而結束時，會將該失敗報告回 Claude，而不是將錯誤文字作為 subagent 的發現返回。Claude 接收的內容取決於 subagent 執行的位置：

794 798

795* **前景**：如果速率限制、過載或伺服器錯誤切斷已經產生輸出的 subagent，Agent 工具會返回該部分輸出，並附註 subagent 被切斷且未完成其任務。否則工具呼叫失敗，並顯示 [`Agent terminated early due to an API error`](/zh-TW/errors#agent-terminated-early-due-to-an-api-error)，後跟錯誤詳細資訊。799* **前景**：如果速率限制、過載或伺服器錯誤切斷已經產生輸出的 subagent，Agent 工具會返回該部分輸出，並附註 subagent 被切斷且未完成其任務。{/* min-version: 2.1.200 */}未產生任何內容或其唯一輸出為工具呼叫的 subagent 會失敗，並顯示 [`Agent terminated early due to an API error`](/zh-TW/errors#agent-terminated-early-due-to-an-api-error)，後跟錯誤詳細資訊。在 v2.1.199 中，切斷工具呼叫專用形狀的速率限制、過載或伺服器錯誤返回了只包含切斷注記的空部分結果。

796* **背景**：subagent 被標記為失敗，Claude 在其結束時接收的訊息命名 API 錯誤並包括 subagent 的最後輸出，所以部分工作不會丟失。800* **背景**：subagent 被標記為失敗，Claude 在其結束時接收的訊息命名 API 錯誤並包括 subagent 的最後輸出，所以部分工作不會丟失。

797 801

798一旦基礎 API 錯誤清除，要求 Claude 重試任務或 [恢復 subagent](#resume-subagents)。802一旦基礎 API 錯誤清除，要求 Claude 重試任務或 [恢復 subagent](#resume-subagents)。

924 928

925如果停止的 subagent 接收 `SendMessage`，它會自動在背景中恢復，無需新的 `Agent` 呼叫。929如果停止的 subagent 接收 `SendMessage`，它會自動在背景中恢復，無需新的 `Agent` 呼叫。

926 930

931恢復會在相同 ID 下啟動代理的新執行，所以已經失敗或完成的 subagent 在任務列表和 Agent SDK 的任務事件中再次顯示為執行中。在 v2.1.205 之前，它在恢復的執行工作時保持顯示其較早的失敗或完成狀態。

932

927{/* min-version: 2.1.199 */}自 v2.1.199 起，`SendMessage` 檢查名稱是否仍然指向它在對話中較早時到達的同一代理。如果較新的代理已取得該名稱，例如重新產生的背景代理重複使用了它，Claude Code 會拒絕發送，而不是將其傳遞給錯誤的代理，錯誤會報告該名稱現在到達的代理，以便 Claude 可以重新定位。若要在較早的代理仍在執行時到達它，Claude 會透過其產生結果中的代理 ID 來定址它。檢查的範圍是目前對話，並在 `/clear` 時重置。933{/* min-version: 2.1.199 */}自 v2.1.199 起，`SendMessage` 檢查名稱是否仍然指向它在對話中較早時到達的同一代理。如果較新的代理已取得該名稱，例如重新產生的背景代理重複使用了它，Claude Code 會拒絕發送，而不是將其傳遞給錯誤的代理，錯誤會報告該名稱現在到達的代理，以便 Claude 可以重新定位。若要在較早的代理仍在執行時到達它，Claude 會透過其產生結果中的代理 ID 來定址它。檢查的範圍是目前對話，並在 `/clear` 時重置。

928 934

929{/* min-version: 2.1.198 */}自 v2.1.198 起，subagent 將來自啟動它的代理的訊息視為正常任務方向，包括中途任務課程更正，並在其自己的權限設定內對其進行操作。無論誰發送訊息，兩個限制仍然成立：來自任何代理的任何訊息都不計為您對待處理權限提示的批准，任何代理訊息都無法改變 subagent 的權限設定、`CLAUDE.md` 或配置。只有權限系統或您自己的訊息可以授予批准。935{/* min-version: 2.1.198 */}自 v2.1.198 起，subagent 將來自啟動它的代理的訊息視為正常任務方向，包括中途任務課程更正，並在其自己的權限設定內對其進行操作。無論誰發送訊息，兩個限制仍然成立：來自任何代理的任何訊息都不計為您對待處理權限提示的批准，任何代理訊息都無法改變 subagent 的權限設定、`CLAUDE.md` 或配置。只有權限系統或您自己的訊息可以授予批准。

third-party-integrations.md +14 −14

Details

102 <th>Anthropic Console</th>102 <th>Anthropic Console</th>

103 <th>Amazon Bedrock</th>103 <th>Amazon Bedrock</th>

104 <th>Claude Platform on AWS</th>104 <th>Claude Platform on AWS</th>

105 <th>Google Vertex AI</th>105 <th>Google Cloud's Agent Platform，前身為 Vertex AI</th>

106 <th>Microsoft Foundry</th>106 <th>Microsoft Foundry</th>

107 </tr>107 </tr>

108 </thead>108 </thead>

196 196

197* [Claude for Teams 或 Enterprise](/zh-TW/authentication#claude-for-teams-or-enterprise)197* [Claude for Teams 或 Enterprise](/zh-TW/authentication#claude-for-teams-or-enterprise)

198* [Anthropic Console](/zh-TW/authentication#claude-console-authentication)198* [Anthropic Console](/zh-TW/authentication#claude-console-authentication)

199* [Claude 應用程式閘道](/zh-TW/claude-apps-gateway)，一個自託管閘道，在 Amazon Bedrock、Claude Platform on AWS、Google Vertex AI、Microsoft Foundry 或 Anthropic API 前面添加 IdP 登入199* [Claude 應用程式閘道](/zh-TW/claude-apps-gateway)，一個自託管閘道，在 Amazon Bedrock、Claude Platform on AWS、Google Cloud's Agent Platform、Microsoft Foundry 或 Anthropic API 前面添加 IdP 登入

200* [Amazon Bedrock](/zh-TW/amazon-bedrock)200* [Amazon Bedrock](/zh-TW/amazon-bedrock)

201* [Claude Platform on AWS](/zh-TW/claude-platform-on-aws)201* [Claude Platform on AWS](/zh-TW/claude-platform-on-aws)

202* [Google Vertex AI](/zh-TW/google-vertex-ai)202* [Google Cloud's Agent Platform](/zh-TW/google-vertex-ai)

203* [Microsoft Foundry](/zh-TW/microsoft-foundry)203* [Microsoft Foundry](/zh-TW/microsoft-foundry)

204 204

205<h2 id="configure-proxies-and-gateways">205<h2 id="configure-proxies-and-gateways">

219 219

220<Tabs>220<Tabs>

221 <Tab title="公司代理">221 <Tab title="公司代理">

222 通過設置以下 [環境變數](/zh-TW/env-vars) 將 Bedrock 流量路由通過您的公司代理：222 通過設置以下 [環境變數](/zh-TW/env-vars) 將 Amazon Bedrock 流量路由通過您的公司代理：

223 223

224 ```bash theme={null}224 ```bash theme={null}

225 # 啟用 Bedrock225 # 啟用 Bedrock

232 </Tab>232 </Tab>

233 233

234 <Tab title="LLM 網關">234 <Tab title="LLM 網關">

235 通過設置以下 [環境變數](/zh-TW/env-vars) 將 Bedrock 流量路由通過您的 LLM 網關：235 通過設置以下 [環境變數](/zh-TW/env-vars) 將 Amazon Bedrock 流量路由通過您的 LLM 網關：

236 236

237 ```bash theme={null}237 ```bash theme={null}

238 # 啟用 Bedrock238 # 啟用 Bedrock

251 251

252<Tabs>252<Tabs>

253 <Tab title="公司代理">253 <Tab title="公司代理">

254 通過設置以下 [環境變數](/zh-TW/env-vars) 將 Foundry 流量路由通過您的公司代理：254 通過設置以下 [環境變數](/zh-TW/env-vars) 將 Microsoft Foundry 流量路由通過您的公司代理：

255 255

256 ```bash theme={null}256 ```bash theme={null}

257 # 啟用 Microsoft Foundry257 # 啟用 Microsoft Foundry

265 </Tab>265 </Tab>

266 266

267 <Tab title="LLM 網關">267 <Tab title="LLM 網關">

268 通過設置以下 [環境變數](/zh-TW/env-vars) 將 Foundry 流量路由通過您的 LLM 網關：268 通過設置以下 [環境變數](/zh-TW/env-vars) 將 Microsoft Foundry 流量路由通過您的 LLM 網關：

269 269

270 ```bash theme={null}270 ```bash theme={null}

271 # 啟用 Microsoft Foundry271 # 啟用 Microsoft Foundry

278 </Tab>278 </Tab>

279</Tabs>279</Tabs>

280 280

281<h3 id="google-vertex-ai">281<h3 id="google-cloud’s-agent-platform">

282 Google Vertex AI282 Google Cloud's Agent Platform

283</h3>283</h3>

284 284

285<Tabs>285<Tabs>

286 <Tab title="公司代理">286 <Tab title="公司代理">

287 通過設置以下 [環境變數](/zh-TW/env-vars) 將 Vertex AI 流量路由通過您的公司代理：287 通過設置以下 [環境變數](/zh-TW/env-vars) 將 Google Cloud's Agent Platform 流量路由通過您的公司代理：

288 288

289 ```bash theme={null}289 ```bash theme={null}

290 # 啟用 Vertex290 # 啟用 Agent Platform

291 export CLAUDE_CODE_USE_VERTEX=1291 export CLAUDE_CODE_USE_VERTEX=1

292 export CLOUD_ML_REGION=us-east5292 export CLOUD_ML_REGION=us-east5

293 export ANTHROPIC_VERTEX_PROJECT_ID=your-project-id293 export ANTHROPIC_VERTEX_PROJECT_ID=your-project-id

298 </Tab>298 </Tab>

299 299

300 <Tab title="LLM 網關">300 <Tab title="LLM 網關">

301 通過設置以下 [環境變數](/zh-TW/env-vars) 將 Vertex AI 流量路由通過您的 LLM 網關：301 通過設置以下 [環境變數](/zh-TW/env-vars) 將 Google Cloud's Agent Platform 流量路由通過您的 LLM 網關：

302 302

303 ```bash theme={null}303 ```bash theme={null}

304 # 啟用 Vertex304 # 啟用 Agent Platform

305 export CLAUDE_CODE_USE_VERTEX=1305 export CLAUDE_CODE_USE_VERTEX=1

306 306

307 # 配置 LLM 網關307 # 配置 LLM 網關

348 為雲端提供商固定模型版本348 為雲端提供商固定模型版本

349</h3>349</h3>

350 350

351如果您通過 [Bedrock](/zh-TW/amazon-bedrock)、[Vertex AI](/zh-TW/google-vertex-ai)、[Foundry](/zh-TW/microsoft-foundry) 或 [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 部署，請使用 `ANTHROPIC_DEFAULT_FABLE_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 固定特定模型版本。如果不固定，模型別名會解析為 Claude Code 針對該提供商的內建預設值，這可能會落後於最新版本，且可能尚未在您的帳戶中啟用。固定讓您控制用戶何時移至新模型。有關每個提供商在預設值不可用時的操作，請參閱 [模型配置](/zh-TW/model-config#pin-models-for-third-party-deployments)。351如果您通過 [Amazon Bedrock](/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/zh-TW/google-vertex-ai)、[Microsoft Foundry](/zh-TW/microsoft-foundry) 或 [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 部署，請使用 `ANTHROPIC_DEFAULT_FABLE_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 固定特定模型版本。如果不固定，模型別名會解析為 Claude Code 針對該提供商的內建預設值，這可能會落後於最新版本，且可能尚未在您的帳戶中啟用。固定讓您控制用戶何時移至新模型。有關每個提供商在預設值不可用時的操作，請參閱 [模型配置](/zh-TW/model-config#pin-models-for-third-party-deployments)。

352 352

353<h3 id="configure-security-policies">353<h3 id="configure-security-policies">

354 配置安全策略354 配置安全策略

tools-reference.md +11 −11

Details

11若要新增自訂工具，請連接 [MCP server](/zh-TW/mcp)。若要使用可重複使用的提示型工作流程擴展 Claude，請撰寫 [skill](/zh-TW/skills)，它透過現有的 `Skill` 工具執行，而不是新增工具項目。11若要新增自訂工具，請連接 [MCP server](/zh-TW/mcp)。若要使用可重複使用的提示型工作流程擴展 Claude，請撰寫 [skill](/zh-TW/skills)，它透過現有的 `Skill` 工具執行，而不是新增工具項目。

12 12

13| 工具 | 描述 | 需要權限 |13| 工具 | 描述 | 需要權限 |

14| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--- |14| :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--- |

15| `Agent` | 生成一個具有自己 context window 的 [subagent](/zh-TW/sub-agents)，以處理任務。請參閱 [Agent 工具行為](#agent-tool-behavior) | 否 |15| `Agent` | 生成一個具有自己 context window 的 [subagent](/zh-TW/sub-agents)，以處理任務。請參閱 [Agent 工具行為](#agent-tool-behavior) | 否 |

16| `Artifact` | 將 HTML 或 Markdown 檔案發佈為 [artifact](/zh-TW/artifacts)：一個私人的互動式頁面，在 claude.ai 上。在 Team 和 Enterprise 計畫上，您可以在組織內部分享。{/* plan-availability: feature=artifacts plans=pro,max,team,enterprise providers=anthropic */}需要 Pro、Max、Team 或 Enterprise 計畫和 `/login` 驗證；請參閱 [可用性](/zh-TW/artifacts#availability) | 是 |16| `Artifact` | 將 HTML 或 Markdown 檔案發佈為 [artifact](/zh-TW/artifacts)：一個私人的互動式頁面，在 claude.ai 上。在 Team 和 Enterprise 計畫上，您可以在組織內部分享。{/* plan-availability: feature=artifacts plans=pro,max,team,enterprise providers=anthropic */}需要 Pro、Max、Team 或 Enterprise 計畫和 `/login` 驗證；請參閱 [可用性](/zh-TW/artifacts#availability) | 是 |

17| `AskUserQuestion` | 提出多選題以收集需求或澄清歧義。{/* min-version: 2.1.198 */}自 v2.1.198 起，如果您在 60 秒內未回應，對話框會自動關閉：它會提交您已選擇的任何選項，並告訴 Claude 您可能離開了鍵盤，因此 Claude 會根據自己的判斷進行，稍後可以重新提問。最後 20 秒會出現倒數計時。任何按鍵都會保持對話框開啟，報告焦點的終端機上的焦點視窗也會。設定 [`CLAUDE_AFK_TIMEOUT_MS`](/zh-TW/env-vars#variables) 環境變數以變更 Claude Code 等待的時間，或設定為大值如 `86400000`（24 小時）以在您離開時保持問題開啟。此逾時僅適用於 `AskUserQuestion` 的多選題；權限提示（包括計畫批准）在閒置時永遠不會自動解決 | 否 |17| `AskUserQuestion` | 提出多選題以收集需求或澄清歧義。{/* min-version: 2.1.200 */}問題會保持開啟直到您回答：預設情況下沒有閒置逾時。若要讓閒置對話框自動繼續，請將 [`askUserQuestionTimeout`](/zh-TW/settings#available-settings) 設定設為 `60s`、`5m` 或 `10m`，可在您的使用者 `settings.json` 中或從 `/config` 中的**問題自動繼續逾時**列進行設定。一旦經過所選的閒置時間且沒有輸入，對話框會自動關閉：它會提交您已選擇的任何選項，並告訴 Claude 您可能離開了鍵盤，因此 Claude 會根據自己的判斷進行，稍後可以重新提問。最後 20 秒會出現倒數計時。任何按鍵都會重新啟動計時器，報告焦點的終端機上的焦點視窗也會。逾時僅適用於 `AskUserQuestion` 的多選題；權限提示（包括計畫批准）在閒置時永遠不會自動解決。在 v2.1.198 和 v2.1.199 中，對話框預設在 60 秒閒置後自動繼續，[`CLAUDE_AFK_TIMEOUT_MS`](/zh-TW/env-vars#variables) 是唯一改變該行為的方式 | 否 |

18| `Bash` | 在您的環境中執行 shell 命令。請參閱 [Bash 工具行為](#bash-tool-behavior) | 是 |18| `Bash` | 在您的環境中執行 shell 命令。請參閱 [Bash 工具行為](#bash-tool-behavior) | 是 |

19| `CronCreate` | 在目前工作階段內排程定期或一次性提示。任務的範圍限於工作階段，並在 `--resume` 或 `--continue` 時恢復（如果未過期）。請參閱 [排程任務](/zh-TW/scheduled-tasks) | 否 |19| `CronCreate` | 在目前工作階段內排程定期或一次性提示。任務的範圍限於工作階段，並在 `--resume` 或 `--continue` 時恢復（如果未過期）。請參閱 [排程任務](/zh-TW/scheduled-tasks) | 否 |

20| `CronDelete` | 按 ID 取消排程任務 | 否 |20| `CronDelete` | 按 ID 取消排程任務 | 否 |

21| `CronList` | 列出工作階段中的所有排程任務 | 否 |21| `CronList` | 列出工作階段中的所有排程任務 | 否 |

22| `Edit` | 對特定檔案進行目標編輯。請參閱 [Edit 工具行為](#edit-tool-behavior) | 是 |22| `Edit` | 對特定檔案進行目標編輯。請參閱 [Edit 工具行為](#edit-tool-behavior) | 是 |

23| `EnterPlanMode` | 切換到 Plan Mode 以在編碼前設計方法 | 否 |23| `EnterPlanMode` | 切換到 Plan Mode 以在編碼前設計方法 | 否 |

24| `EnterWorktree` | 建立隔離的 [git worktree](/zh-TW/worktrees) 並切換到其中。傳遞 `path` 以切換到目前儲存庫的現有 worktree，而不是建立新的。從 worktree 工作階段內，或從具有固定工作目錄的 subagent（例如 [`isolation: worktree`](/zh-TW/sub-agents#supported-frontmatter-fields)）中，只有 `path` 形式可用，且目標必須在 `.claude/worktrees/` 下 | 否 |24| `EnterWorktree` | 建立隔離的 [git worktree](/zh-TW/worktrees) 並切換到其中。傳遞 `path` 以切換到現有 worktree，而不是建立新的。{/* min-version: 2.1.203 */}首次進入時，目標可能是目前儲存庫的 worktree，或在多儲存庫工作區中，是其中嵌套的儲存庫的 worktree。在 v2.1.203 之前，嵌套儲存庫的 worktree 會被拒絕。從 worktree 工作階段內，或從具有固定工作目錄的 subagent（例如 [`isolation: worktree`](/zh-TW/sub-agents#supported-frontmatter-fields)）中，只有 `path` 形式可用，且目標必須在工作階段儲存庫的 `.claude/worktrees/` 下 | 否 |

25| `ExitPlanMode` | 提出計畫以供批准並退出 Plan Mode | 是 |25| `ExitPlanMode` | 提出計畫以供批准並退出 Plan Mode | 是 |

26| `ExitWorktree` | 退出 worktree 工作階段並返回原始目錄。不適用於已在自己的工作目錄中執行的 subagents，例如使用 [`isolation: worktree`](/zh-TW/sub-agents#supported-frontmatter-fields) | 否 |26| `ExitWorktree` | 退出 worktree 工作階段並返回原始目錄。不適用於已在自己的工作目錄中執行的 subagents，例如使用 [`isolation: worktree`](/zh-TW/sub-agents#supported-frontmatter-fields) | 否 |

27| `Glob` | 根據模式匹配查找檔案。請參閱 [Glob 工具行為](#glob-tool-behavior) | 否 |27| `Glob` | 根據模式匹配查找檔案。請參閱 [Glob 工具行為](#glob-tool-behavior) | 否 |

31| `Monitor` | 在背景執行命令，並將每個輸出行回饋給 Claude，以便它可以對日誌項目、檔案變更或輪詢狀態做出反應。也可以開啟 WebSocket 並將每個傳入訊息視為事件。請參閱 [Monitor 工具](#monitor-tool) | 是 |31| `Monitor` | 在背景執行命令，並將每個輸出行回饋給 Claude，以便它可以對日誌項目、檔案變更或輪詢狀態做出反應。也可以開啟 WebSocket 並將每個傳入訊息視為事件。請參閱 [Monitor 工具](#monitor-tool) | 是 |

32| `NotebookEdit` | 修改 Jupyter notebook 儲存格。請參閱 [NotebookEdit 工具行為](#notebookedit-tool-behavior) | 是 |32| `NotebookEdit` | 修改 Jupyter notebook 儲存格。請參閱 [NotebookEdit 工具行為](#notebookedit-tool-behavior) | 是 |

33| `PowerShell` | 原生執行 PowerShell 命令。請參閱 [PowerShell 工具](#powershell-tool) 以了解可用性 | 是 |33| `PowerShell` | 原生執行 PowerShell 命令。請參閱 [PowerShell 工具](#powershell-tool) 以了解可用性 | 是 |

34| `PushNotification` | 傳送桌面通知，以及當 [Remote Control](/zh-TW/remote-control) 已連接時傳送手機推播，以便長時間執行的任務或 [排程任務](/zh-TW/scheduled-tasks) 可以在您離開時聯繫您。{/* plan-availability: feature=push-notifications providers=anthropic */}推播傳遞透過 Anthropic 託管的基礎設施執行，無法從 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 存取 | 否 |34| `PushNotification` | 傳送桌面通知，以及當 [Remote Control](/zh-TW/remote-control) 已連接時傳送手機推播，以便長時間執行的任務或 [排程任務](/zh-TW/scheduled-tasks) 可以在您離開時聯繫您。{/* plan-availability: feature=push-notifications providers=anthropic */}推播傳遞透過 Anthropic 託管的基礎設施執行，無法從 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 存取 | 否 |

35| `Read` | 讀取檔案的內容。請參閱 [Read 工具行為](#read-tool-behavior) | 否 |35| `Read` | 讀取檔案的內容。請參閱 [Read 工具行為](#read-tool-behavior) | 否 |

36| `ReadMcpResourceTool` | 按 URI 讀取特定 MCP 資源 | 否 |36| `ReadMcpResourceTool` | 按 URI 讀取特定 MCP 資源 | 否 |

37| `RemoteTrigger` | 在 claude.ai 上建立、更新、執行和列出 [Routines](/zh-TW/routines)。支援 `/schedule` 命令。{/* plan-availability: feature=routines plans=pro,max,team,enterprise providers=anthropic */}Routines 位於 claude.ai 上，需要 Pro、Max、Team 或 Enterprise 計畫，因此此工具無法從 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 存取 | 否 |37| `RemoteTrigger` | 在 claude.ai 上建立、更新、執行和列出 [Routines](/zh-TW/routines)。支援 `/schedule` 命令。{/* plan-availability: feature=routines plans=pro,max,team,enterprise providers=anthropic */}Routines 位於 claude.ai 上，需要 Pro、Max、Team 或 Enterprise 計畫，因此此工具無法從 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 存取 | 否 |

38| `ReportFindings` | 將程式碼審查結果報告為結構化清單，每個結果包含檔案、摘要和失敗情景，以便 Claude Code 可以呈現它們而不是將其列印為文字。當有效的程式碼審查指示告訴它時，Claude 會呼叫它。{/* min-version: 2.1.196 */}需要 Claude Code v2.1.196 或更新版本。{/* min-version: 2.1.199 */}自 v2.1.199 起，結果也可以攜帶選擇性的 `category` slug，例如 `correctness` 或 `test-coverage`，顯示在呈現清單中的檔案位置旁邊 | 否 |38| `ReportFindings` | 將程式碼審查結果報告為結構化清單，每個結果包含檔案、摘要和失敗情景，以便 Claude Code 可以呈現它們而不是將其列印為文字。當有效的程式碼審查指示告訴它時，Claude 會呼叫它。{/* min-version: 2.1.196 */}需要 Claude Code v2.1.196 或更新版本。{/* min-version: 2.1.199 */}自 v2.1.199 起，結果也可以攜帶選擇性的 `category` slug，例如 `correctness` 或 `test-coverage`，顯示在呈現清單中的檔案位置旁邊 | 否 |

39| `ScheduleWakeup` | 重新排程 [自主進行的 `/loop`](/zh-TW/scheduled-tasks#let-claude-choose-the-interval) 的下一次迭代。Claude 在每次迭代結束時呼叫此工具，以選擇下一次執行的時間，範圍在一分鐘到一小時之間；您不需要直接呼叫它。待處理的喚醒會出現在 [Stop hook input](/zh-TW/hooks#stop-input) 的 `session_crons` 中。{/* plan-availability: feature=loop-dynamic providers=anthropic */}在 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 上不可用，其中沒有間隔的 `/loop` 提示會改為按固定時間表執行 | 否 |39| `ScheduleWakeup` | 重新排程 [自主進行的 `/loop`](/zh-TW/scheduled-tasks#let-claude-choose-the-interval) 的下一次迭代。Claude 在每次迭代結束時呼叫此工具，以選擇下一次執行的時間，範圍在一分鐘到一小時之間；您不需要直接呼叫它。若要改為結束迴圈，Claude 會以 `stop: true` 呼叫它，這會取消待處理的喚醒。{/* min-version: 2.1.202 */}`stop` 欄位需要 Claude Code v2.1.202 或更新版本。待處理的喚醒會出現在 [Stop hook input](/zh-TW/hooks#stop-input) 的 `session_crons` 中。{/* plan-availability: feature=loop-dynamic providers=anthropic */}在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用，其中沒有間隔的 `/loop` 提示會改為按固定時間表執行 | 否 |

40| `SendMessage` | 傳送訊息給 [agent team](/zh-TW/agent-teams) 隊友，或按 agent ID 或名稱 [恢復 subagent](/zh-TW/sub-agents#resume-subagents)。已停止的 subagents 會在背景中自動恢復。結構化的團隊協議訊息需要 agent teams。接收者永遠不會將來自另一個 agent 的訊息視為您的同意或批准。{/* min-version: 2.1.198 */}自 v2.1.198 起，subagent 將來自啟動它的 agent 的訊息視為正常任務指示，而不是對等請求。{/* min-version: 2.1.199 */}自 v2.1.199 起，傳送到現在解析為與對話中較早時間不同的 agent 的名稱會被拒絕而不是傳遞；請參閱 [恢復 subagents](/zh-TW/sub-agents#resume-subagents) | 否 |40| `SendMessage` | 傳送訊息給 [agent team](/zh-TW/agent-teams) 隊友，或按 agent ID 或名稱 [恢復 subagent](/zh-TW/sub-agents#resume-subagents)。已停止的 subagents 會在背景中自動恢復。結構化的團隊協議訊息需要 agent teams。接收者永遠不會將來自另一個 agent 的訊息視為您的同意或批准。{/* min-version: 2.1.198 */}自 v2.1.198 起，subagent 將來自啟動它的 agent 的訊息視為正常任務指示，而不是對等請求。{/* min-version: 2.1.199 */}自 v2.1.199 起，傳送到現在解析為與對話中較早時間不同的 agent 的名稱會被拒絕而不是傳遞；請參閱 [恢復 subagents](/zh-TW/sub-agents#resume-subagents) | 否 |

41| `SendUserFile` | 將工作階段中的檔案傳送給您，並附上選擇性標題，以便生成的報告、圖表、螢幕擷取畫面或建置的成品可以到達您的裝置，而不是只在文字記錄中提及。{/* min-version: 2.1.196 */}自 v2.1.196 起，選擇性的 `display` 輸入控制呈現方式：`render` 在用戶端中內聯開啟檔案，`attach` 僅顯示下載卡片，未設定時用戶端會根據檔案類型決定。當連接了 [Remote Control](/zh-TW/remote-control) 用戶端或工作階段在受管雲端環境（例如 [Claude Code on the web](/zh-TW/claude-code-on-the-web)）中執行時可用。傳遞透過 Anthropic 託管的基礎設施執行，因此該工具在 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 上不可用 | 否 |41| `SendUserFile` | 將工作階段中的檔案傳送給您，並附上選擇性標題，以便生成的報告、圖表、螢幕擷取畫面或建置的成品可以到達您的裝置，而不是只在文字記錄中提及。{/* min-version: 2.1.196 */}自 v2.1.196 起，選擇性的 `display` 輸入控制呈現方式：`render` 在用戶端中內聯開啟檔案，`attach` 僅顯示下載卡片，未設定時用戶端會根據檔案類型決定。當連接了 [Remote Control](/zh-TW/remote-control) 用戶端或工作階段在受管雲端環境（例如 [Claude Code on the web](/zh-TW/claude-code-on-the-web)）中執行時可用。傳遞透過 Anthropic 託管的基礎設施執行，因此該工具在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用 | 否 |

42| `ShareOnboardingGuide` | {/* plan-availability: feature=onboarding-guide-share plans=pro,max,team,enterprise providers=anthropic */}上傳 `ONBOARDING.md` 並傳回隊友可以在 Claude Code 中開啟的分享連結。在撰寫指南後從 `/team-onboarding` 呼叫。適用於 Pro、Max、Team 和 Enterprise 計畫上的 claude.ai 訂閱者 | 是 |42| `ShareOnboardingGuide` | {/* plan-availability: feature=onboarding-guide-share plans=pro,max,team,enterprise providers=anthropic */}上傳 `ONBOARDING.md` 並傳回隊友可以在 Claude Code 中開啟的分享連結。在撰寫指南後從 `/team-onboarding` 呼叫。適用於 Pro、Max、Team 和 Enterprise 計畫上的 claude.ai 訂閱者 | 是 |

43| `Skill` | 在主對話中執行 [skill](/zh-TW/skills#control-who-invokes-a-skill) | 是 |43| `Skill` | 在主對話中執行 [skill](/zh-TW/skills#control-who-invokes-a-skill) | 是 |

44| `TaskCreate` | 在任務清單中建立新任務 | 否 |44| `TaskCreate` | 在任務清單中建立新任務 | 否 |

45| `TaskGet` | 檢索特定任務的完整詳細資訊 | 否 |45| `TaskGet` | 檢索特定任務的完整詳細資訊 | 否 |

46| `TaskList` | 列出所有任務及其目前狀態 | 否 |46| `TaskList` | 列出所有任務及其目前狀態 | 否 |

47| `TaskOutput` | （已棄用）檢索背景任務的輸出。建議在任務的輸出檔案路徑上使用 `Read` | 否 |47| `TaskOutput` | 檢索背景任務的輸出。已在任務的輸出檔案路徑上使用 `Read` 取代。{/* min-version: 2.1.203 */}當沒有任務符合 ID 時，錯誤會列出執行中的背景 agents（按 ID 和描述）。在 v2.1.203 之前，錯誤只命名遺失的 ID | 否 |

48| `TaskStop` | 按 ID 終止執行中的背景任務。{/* min-version: 2.1.198 */}自 v2.1.198 起，也接受 [agent-team 隊友](/zh-TW/agent-teams) 或按 agent ID 或名稱的具名背景 agent | 否 |48| `TaskStop` | 按 ID 終止執行中的背景任務。{/* min-version: 2.1.198 */}它也接受 [agent-team 隊友](/zh-TW/agent-teams) 或按 agent ID 或名稱的具名背景 agent。在 v2.1.198 之前，它只接受背景任務 ID。{/* min-version: 2.1.203 */}當沒有任務符合 ID 時，錯誤會列出執行中的背景 agents（按 ID 和描述），包括另一個 agent 生成的 agents。在 v2.1.203 之前，錯誤列出執行中的隊友和具名 agents，但不包括另一個 agent 生成的背景 agents，因此無法從主對話中識別或停止這些 agents | 否 |

49| `TaskUpdate` | 更新任務狀態、依賴項、詳細資訊或刪除任務 | 否 |49| `TaskUpdate` | 更新任務狀態、依賴項、詳細資訊或刪除任務 | 否 |

50| `TodoWrite` | {/* min-version: 2.1.142 */}管理工作階段任務檢查清單。自 v2.1.142 起預設停用，改用 `TaskCreate`、`TaskGet`、`TaskList` 和 `TaskUpdate`。設定 `CLAUDE_CODE_ENABLE_TASKS=0` 以重新啟用 | 否 |50| `TodoWrite` | {/* min-version: 2.1.142 */}管理工作階段任務檢查清單。自 v2.1.142 起預設停用，改用 `TaskCreate`、`TaskGet`、`TaskList` 和 `TaskUpdate`。設定 `CLAUDE_CODE_ENABLE_TASKS=0` 以重新啟用 | 否 |

51| `ToolSearch` | 當啟用 [tool search](/zh-TW/mcp#scale-with-mcp-tool-search) 時，搜尋並載入延遲工具 | 否 |51| `ToolSearch` | 當啟用 [tool search](/zh-TW/mcp#scale-with-mcp-tool-search) 時，搜尋並載入延遲工具 | 否 |

220 220

221當 Monitor 執行命令時，它使用與 [Bash 相同的權限規則](/zh-TW/permissions#tool-specific-permission-rules)，因此您為 Bash 設定的 `allow` 和 `deny` 模式也適用於此處。[WebSocket 來源](#websocket-source)有其自己的核准提示。221當 Monitor 執行命令時，它使用與 [Bash 相同的權限規則](/zh-TW/permissions#tool-specific-permission-rules)，因此您為 Bash 設定的 `allow` 和 `deny` 模式也適用於此處。[WebSocket 來源](#websocket-source)有其自己的核准提示。

222 222

223該工具在 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 上不可用。當設定 `DISABLE_TELEMETRY` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 時，它也不可用。223該工具在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用。當設定 `DISABLE_TELEMETRY` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 時，它也不可用。

224 224

225外掛可以宣告在外掛啟用時自動啟動的監視，而不是要求 Claude 啟動它們。請參閱 [外掛監視](/zh-TW/plugins-reference#monitors)。225外掛可以宣告在外掛啟用時自動啟動的監視，而不是要求 Claude 啟動它們。請參閱 [外掛監視](/zh-TW/plugins-reference#monitors)。

226 226

369WebSearch 權限規則不採用 specifier。`allow` 或 `deny` 中的裸 `WebSearch` 項目是唯一的形式。369WebSearch 權限規則不採用 specifier。`allow` 或 `deny` 中的裸 `WebSearch` 項目是唯一的形式。

370 370

371<Note>371<Note>

372 WebSearch 在 Claude API、[Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 和 Microsoft Foundry 上可用。在 Google Cloud Vertex AI 上，它適用於 Claude 4 及更新版本的模型，包括 Opus、Sonnet 和 Haiku。Amazon Bedrock 不公開伺服器端 web search 工具。372 WebSearch 在 Claude API、[Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 和 Microsoft Foundry 上可用。在 Google Cloud 的 Agent Platform 上，它適用於 Claude 4 及更新版本的模型，包括 Opus、Sonnet 和 Haiku。Amazon Bedrock 不公開伺服器端 web search 工具。

373</Note>373</Note>

374 374

375<h2 id="write-tool-behavior">375<h2 id="write-tool-behavior">

troubleshoot-install.md +17 −14

Details

15將您看到的錯誤訊息或症狀與修復方案相符：15將您看到的錯誤訊息或症狀與修復方案相符：

16 16

17| 您看到的內容 | 解決方案 |17| 您看到的內容 | 解決方案 |

~~18| :----------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------- |~~18| :----------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------- |

22| `curl: (23)` 或 `curl: (56) Failure writing output to destination` | [檢查連線或使用替代安裝程式](#curl-56-failure-writing-output-to-destination) |22| `curl: (23)` 或 `curl: (56) Failure writing output to destination` | [檢查連線或使用替代安裝程式](#curl-56-failure-writing-output-to-destination) |

~~42| `Could not load the default credentials` 或 `Could not load credentials from any providers` | [Bedrock、Vertex 或 Foundry 認證](#bedrock-vertex-or-foundry-credentials-not-loading) |~~42| `Could not load the default credentials` 或 `Could not load credentials from any providers` | [Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 認證](#bedrock-agent-platform-or-foundry-credentials-not-loading) |

~~43| `ChainedTokenCredential authentication failed` 或 `CredentialUnavailableError` | [Bedrock、Vertex 或 Foundry 認證](#bedrock-vertex-or-foundry-credentials-not-loading) |~~43| `ChainedTokenCredential authentication failed` 或 `CredentialUnavailableError` | [Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 認證](#bedrock-agent-platform-or-foundry-credentials-not-loading) |

45 45

46如果您的問題未列出，請執行下面的診斷檢查以縮小原因範圍。46如果您的問題未列出，請執行下面的診斷檢查以縮小原因範圍。

538 低記憶體 Linux 伺服器上安裝被終止538 低記憶體 Linux 伺服器上安裝被終止

539</h3>539</h3>

540 540

541如果您在 VPS 或雲端執行個體上的安裝期間看到 `Killed`：541在安裝期間出現 `Killed` 訊息通常表示 Linux 記憶體不足 (OOM) 殺手終止了 `claude install` 步驟，因為系統用盡了可用記憶體。這在小型 VPS 和雲端執行個體上很常見。安裝指令碼報告原因並以代碼 137 結束：

542 542

543```text theme={null}543```text theme={null}

544Setting up Claude Code...544Setting up Claude Code...

545Installing Claude Code native build latest...

546bash: line 142: 34803 Killed "$binary_path" install ${TARGET:+"$TARGET"}545bash: line 142: 34803 Killed "$binary_path" install ${TARGET:+"$TARGET"}

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

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

547```548```

548 549

549Linux OOM 殺手終止了該程序，因為系統用盡了記憶體。Claude Code 需要至少 4 GB 的可用 RAM。550在 v2.1.200 之前，指令碼僅以 shell 的裸 `Killed` 行結束，沒有說明。

551

552安裝需要大約 512 MB 的可用記憶體，執行 Claude Code 需要更多。請參閱[系統需求](/zh-TW/setup#system-requirements)。

550 553

551**解決方案：**554**解決方案：**

552 555

781`@anthropic-ai/claude-code` npm 套件透過每個平台的可選相依性（如 `@anthropic-ai/claude-code-darwin-arm64`）拉入原生二進位檔。如果安裝後執行 `claude` 列印 `Could not find native binary package "@anthropic-ai/claude-code-<platform>"`，請檢查以下原因：784`@anthropic-ai/claude-code` npm 套件透過每個平台的可選相依性（如 `@anthropic-ai/claude-code-darwin-arm64`）拉入原生二進位檔。如果安裝後執行 `claude` 列印 `Could not find native binary package "@anthropic-ai/claude-code-<platform>"`，請檢查以下原因：

782 785

783* **可選相依性已停用。** 從您的 npm 安裝命令中移除 `--omit=optional`、從 pnpm 移除 `--no-optional` 或從 yarn 移除 `--ignore-optional`，並檢查 `.npmrc` 是否未設定 `optional=false`。然後重新安裝。原生二進位檔僅作為可選相依性提供，因此如果跳過它，沒有 JavaScript 後備。786* **可選相依性已停用。** 從您的 npm 安裝命令中移除 `--omit=optional`、從 pnpm 移除 `--no-optional` 或從 yarn 移除 `--ignore-optional`，並檢查 `.npmrc` 是否未設定 `optional=false`。然後重新安裝。原生二進位檔僅作為可選相依性提供，因此如果跳過它，沒有 JavaScript 後備。

784* **不支援的平台。** 預建二進位檔針對 `darwin-arm64`、`darwin-x64`、`linux-x64`、`linux-arm64`、`linux-x64-musl`、`linux-arm64-musl`、`win32-x64` 和 `win32-arm64` 發佈。Claude Code 不為其他平台提供二進位檔；請參閱[系統需求](/zh-TW/setup#system-requirements)。787* **不支援的平台。** 預建二進位檔針對 `darwin-arm64`、`darwin-x64`、`linux-x64`、`linux-arm64`、`linux-x64-musl`、`linux-arm64-musl`、`win32-x64` 和 `win32-arm64` 發佈。Claude Code 不為其他平台提供二進位檔；請參閱[系統需求](/zh-TW/setup#system-requirements)。{/* min-version: 2.1.205 */}在 FreeBSD 上，安裝程式報告平台為不支援。在 v2.1.205 之前，它將 FreeBSD 視為 Linux 並下載了無法執行的二進位檔。

785* **公司 npm 鏡像缺少平台套件。** 確保您的登錄鏡像除了元套件外，還鏡像所有八個 `@anthropic-ai/claude-code-*` 平台套件。788* **公司 npm 鏡像缺少平台套件。** 確保您的登錄鏡像除了元套件外，還鏡像所有八個 `@anthropic-ai/claude-code-*` 平台套件。

786 789

787使用 `--ignore-scripts` 安裝不會觸發此錯誤。跳過連結二進位檔到位置的 postinstall 步驟，因此 Claude Code 回退到在每次啟動時定位和生成平台二進位檔的包裝器。這有效但啟動速度較慢；使用啟用的指令碼重新安裝以進行直接執行。790使用 `--ignore-scripts` 安裝不會觸發此錯誤。跳過連結二進位檔到位置的 postinstall 步驟，因此 Claude Code 回退到在每次啟動時定位和生成平台二進位檔的包裝器。這有效但啟動速度較慢；使用啟用的指令碼重新安裝以進行直接執行。

876 879

877在 macOS 上，當 Keychain 被鎖定或其密碼與您的帳戶密碼不同步時，登入也可能失敗，這會阻止 Claude Code 儲存認證。執行 `claude doctor` 以檢查 Keychain 存取。要手動解鎖 Keychain，請執行 `security unlock-keychain ~/Library/Keychains/login.keychain-db`。如果解鎖無幫助，請開啟 Keychain Access，選擇 `login` keychain，並選擇「編輯」>「變更 Keychain 'login' 的密碼」以將其與您的帳戶密碼重新同步。880在 macOS 上，當 Keychain 被鎖定或其密碼與您的帳戶密碼不同步時，登入也可能失敗，這會阻止 Claude Code 儲存認證。執行 `claude doctor` 以檢查 Keychain 存取。要手動解鎖 Keychain，請執行 `security unlock-keychain ~/Library/Keychains/login.keychain-db`。如果解鎖無幫助，請開啟 Keychain Access，選擇 `login` keychain，並選擇「編輯」>「變更 Keychain 'login' 的密碼」以將其與您的帳戶密碼重新同步。

878 881

879<h3 id="bedrock-vertex-or-foundry-credentials-not-loading">882<h3 id="bedrock-agent-platform-or-foundry-credentials-not-loading">

880 Bedrock、Vertex 或 Foundry 認證未載入883 Bedrock、Agent Platform 或 Foundry 認證未載入

881</h3>884</h3>

882 885

883如果您設定了 Claude Code 以使用雲端提供者，並在 Bedrock 上看到 `Could not load credentials from any providers`、在 Vertex 上看到 `Could not load the default credentials` 或在 Foundry 上看到 `ChainedTokenCredential authentication failed`，您的雲端提供者 CLI 可能在目前 shell 中未進行身份驗證。886如果您設定了 Claude Code 以使用雲端提供者，並在 Amazon Bedrock 上看到 `Could not load credentials from any providers`、在 Google Cloud 的 Agent Platform 上看到 `Could not load the default credentials` 或在 Microsoft Foundry 上看到 `ChainedTokenCredential authentication failed`，您的雲端提供者 CLI 可能在目前 shell 中未進行身份驗證。

884 887

885對於 Bedrock，確認您的 AWS 認證有效：888對於 Amazon Bedrock，確認您的 AWS 認證有效：

886 889

887```bash theme={null}890```bash theme={null}

888aws sts get-caller-identity891aws sts get-caller-identity

889```892```

890 893

891對於 Vertex AI，確認 `ANTHROPIC_VERTEX_PROJECT_ID` 和 `CLOUD_ML_REGION` 在您的 shell 中設定，然後設定應用程式預設認證：894對於 Google Cloud 的 Agent Platform，確認 `ANTHROPIC_VERTEX_PROJECT_ID` 和 `CLOUD_ML_REGION` 在您的 shell 中設定，然後設定應用程式預設認證：

892 895

893```bash theme={null}896```bash theme={null}

894gcloud auth application-default login897gcloud auth application-default login

902 905

903如果認證在您的終端中有效但在 VS Code 或 JetBrains 擴充功能中無效，IDE 程序可能未繼承您的 shell 環境。在 IDE 自己的設定中設定提供者環境變數，或從已匯出它們的終端啟動 IDE。906如果認證在您的終端中有效但在 VS Code 或 JetBrains 擴充功能中無效，IDE 程序可能未繼承您的 shell 環境。在 IDE 自己的設定中設定提供者環境變數，或從已匯出它們的終端啟動 IDE。

904 907

905請參閱 [Amazon Bedrock](/zh-TW/amazon-bedrock)、[Google Vertex AI](/zh-TW/google-vertex-ai) 或 [Microsoft Foundry](/zh-TW/microsoft-foundry) 以取得完整的提供者設定。908請參閱 [Amazon Bedrock](/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/zh-TW/google-vertex-ai) 或 [Microsoft Foundry](/zh-TW/microsoft-foundry) 以取得完整的提供者設定。

906 909

907<h2 id="still-stuck">910<h2 id="still-stuck">

908 仍然卡住911 仍然卡住

troubleshooting.md +6 −5

Details

9本頁涵蓋 Claude Code 執行後的效能、穩定性和搜尋問題。如需其他問題，請從符合您遇到問題位置的頁面開始：9本頁涵蓋 Claude Code 執行後的效能、穩定性和搜尋問題。如需其他問題，請從符合您遇到問題位置的頁面開始：

10 10

11| 症狀 | 前往 |11| 症狀 | 前往 |

~~12| :-------------------------------------------------------------- | :--------------------------------------------------------------------- |~~12| :-------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------ |

~~14| 登入迴圈、OAuth 錯誤、`403 Forbidden`、「組織已停用」、Bedrock/Vertex/Foundry 認證 | [故障排除安裝和登入](/zh-TW/troubleshoot-install#login-and-authentication) |~~14| 更新或安裝下載失敗，出現 `The connection dropped while downloading the update` 或 `aborted` | [錯誤參考](/zh-TW/errors#the-connection-dropped-while-downloading-the-update) |

15| 登入迴圈、OAuth 錯誤、`403 Forbidden`、「組織已停用」、Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 認證 | [故障排除安裝和登入](/zh-TW/troubleshoot-install#login-and-authentication) |

15| 設定未套用、hooks 未觸發、MCP 伺服器未載入 | [偵錯您的設定](/zh-TW/debug-your-config) |16| 設定未套用、hooks 未觸發、MCP 伺服器未載入 | [偵錯您的設定](/zh-TW/debug-your-config) |

17| `model not found` 或 `you may not have access to it` | [錯誤參考](/zh-TW/errors#there%E2%80%99s-an-issue-with-the-selected-model) |18| `model not found` 或 `you may not have access to it` | [錯誤參考](/zh-TW/errors#there%E2%80%99s-an-issue-with-the-selected-model) |

19| JetBrains 外掛程式或 IDE 未偵測到 | [JetBrains 整合](/zh-TW/jetbrains#troubleshooting) |20| JetBrains 外掛程式或 IDE 未偵測到 | [JetBrains 整合](/zh-TW/jetbrains#troubleshooting) |

20| 高 CPU 或記憶體、回應緩慢、掛起、搜尋找不到檔案 | [效能和穩定性](#performance-and-stability)下方 |21| 高 CPU 或記憶體、回應緩慢、掛起、搜尋找不到檔案 | [效能和穩定性](#performance-and-stability)下方 |

21 22

22如果您不確定哪個適用，請在 Claude Code 內執行 `/doctor` 以自動檢查您的安裝、設定、MCP 伺服器和上下文使用情況。如果 `claude` 根本無法啟動，請改為從您的 shell 執行 `claude doctor`。23如果您不確定哪個適用，請在 Claude Code 內執行 `/doctor` 以自動檢查您的安裝、設定、擴充功能和上下文使用情況；它會提議可以在您確認後套用的修復。如果 `claude` 根本無法啟動，請改為從您的 shell 執行 `claude doctor`。執行 `/mcp` 以檢查 MCP 伺服器狀態。

23 24

24<h2 id="performance-and-stability">25<h2 id="performance-and-stability">

25 效能和穩定性26 效能和穩定性

119在 WSL 上[跨檔案系統工作](https://learn.microsoft.com/en-us/windows/wsl/filesystems)時的磁碟讀取效能損失可能導致在 WSL 上使用 Claude Code 時匹配數少於預期。搜尋仍然有效，但在原生檔案系統上返回的結果較少。120在 WSL 上[跨檔案系統工作](https://learn.microsoft.com/en-us/windows/wsl/filesystems)時的磁碟讀取效能損失可能導致在 WSL 上使用 Claude Code 時匹配數少於預期。搜尋仍然有效，但在原生檔案系統上返回的結果較少。

120 121

121<Note>122<Note>

122 在這種情況下，`/doctor` 將顯示搜尋為正常。123 `claude doctor` 在這種情況下將搜尋顯示為正常。

123</Note>124</Note>

124 125

125**解決方案：**126**解決方案：**

136 137

137如果您遇到此處未涵蓋的問題：138如果您遇到此處未涵蓋的問題：

138 139

1391. 執行 `/doctor` 以一次檢查安裝健康狀況、設定有效性、MCP 設定和上下文使用情況1401. 執行 `/doctor` 進行設定檢查，並執行 `/mcp` 以檢查 MCP 伺服器狀態

1402. 在 Claude Code 內使用 `/feedback` 命令直接向 Anthropic 報告問題1412. 在 Claude Code 內使用 `/feedback` 命令直接向 Anthropic 報告問題

1413. 檢查 [GitHub 存儲庫](https://github.com/anthropics/claude-code)以了解已知問題1423. 檢查 [GitHub 存儲庫](https://github.com/anthropics/claude-code)以了解已知問題

1424. 直接向 Claude 詢問其功能和特性。Claude 內置訪問其文檔。1434. 直接向 Claude 詢問其功能和特性。Claude 內置訪問其文檔。

ultraplan.md +1 −1

Details

18* **無需動手的草擬**：計畫在遠端生成，因此您的終端機可以自由進行其他工作18* **無需動手的草擬**：計畫在遠端生成，因此您的終端機可以自由進行其他工作

19* **靈活的執行**：批准計畫在網路上執行並開啟拉取請求，或將其發送回您的終端機19* **靈活的執行**：批准計畫在網路上執行並開啟拉取請求，或將其發送回您的終端機

20 20

21Ultraplan 需要 [Claude Code on the web](/zh-TW/claude-code-on-the-web) 帳戶和 GitHub 儲存庫。因為它在 Anthropic 的雲端基礎設施上執行，所以在使用 Amazon Bedrock、Google Cloud Vertex AI 或 Microsoft Foundry 時不可用。雲端工作階段在您帳戶的預設 [cloud environment](/zh-TW/claude-code-on-the-web#the-cloud-environment) 中執行。如果您還沒有雲端環境，ultraplan 會在首次啟動時自動建立一個。21Ultraplan 需要 [Claude Code on the web](/zh-TW/claude-code-on-the-web) 帳戶和 GitHub 儲存庫。因為它在 Anthropic 的雲端基礎設施上執行，所以在使用 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 時不可用。雲端工作階段在您帳戶的預設 [cloud environment](/zh-TW/claude-code-on-the-web#the-cloud-environment) 中執行。如果您還沒有雲端環境，ultraplan 會在首次啟動時自動建立一個。

22 22

23<h2 id="launch-ultraplan-from-the-cli">23<h2 id="launch-ultraplan-from-the-cli">

24 從 CLI 啟動 ultraplan24 從 CLI 啟動 ultraplan

ultrareview.md +6 −6

Details

15與本地 `/code-review` 或 `/review` 相比，ultrareview 提供：15與本地 `/code-review` 或 `/review` 相比，ultrareview 提供：

16 16

17* **更高的信號品質**：每個報告的發現都經過獨立重現和驗證，因此結果專注於真實錯誤而非風格建議17* **更高的信號品質**：每個報告的發現都經過獨立重現和驗證，因此結果專注於真實錯誤而非風格建議

~~18* **更廣泛的覆蓋範圍**：許多審查代理程式並行探索變更，這會發現中等規模本地審查可能遺漏的問題~~18* **更廣泛的覆蓋範圍**：許多審查代理程式並行探索變更，這會發現本地審查可能遺漏的問題

19* **無本地資源使用**：審查完全在遠端沙箱中執行，因此您的終端在執行期間保持空閒，可用於其他工作19* **無本地資源使用**：審查完全在遠端沙箱中執行，因此您的終端在執行期間保持空閒，可用於其他工作

20 20

21Ultrareview 需要使用 Claude.ai 帳戶進行身份驗證，因為它在 Claude Code 網路基礎設施上執行。如果您僅使用 API 金鑰登入，請先執行 `/login` 並使用 Claude.ai 進行身份驗證。使用 Amazon Bedrock、Google Cloud Vertex AI 或 Microsoft Foundry 的 Claude Code 時，Ultrareview 不可用，對於已啟用零資料保留的組織也不可用。21Ultrareview 需要使用 Claude.ai 帳戶進行身份驗證，因為它在 Claude Code 網路基礎設施上執行。如果您僅使用 API 金鑰登入，請先執行 `/login` 並使用 Claude.ai 進行身份驗證。使用 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 的 Claude Code 時，Ultrareview 不可用，對於已啟用零資料保留的組織也不可用。

22 22

23<h2 id="run-ultrareview-from-the-cli">23<h2 id="run-ultrareview-from-the-cli">

24 從 CLI 執行 ultrareview24 從 CLI 執行 ultrareview

104這三個命令都審查程式碼，但它們針對工作流程的不同階段。104這三個命令都審查程式碼，但它們針對工作流程的不同階段。

105 105

107| ---- | -------------- | -------------------- | ------------------------------- |107| ---- | -------------- | -------------- | ------------------------------- |

108| 目標 | 您的工作差異 | GitHub 拉取請求 | 您的工作差異或拉取請求 |108| 目標 | 您的工作差異 | GitHub 拉取請求 | 您的工作差異或拉取請求 |

110| 深度 | 隨著努力引數調整 | 中等 `/code-review` 引擎 | 具有獨立驗證的多代理程式艦隊 |110| 深度 | 隨著努力引數調整 | 工作階段努力程度的單次審查 | 具有獨立驗證的多代理程式艦隊 |

112| 成本 | 計入正常使用量 | 計入正常使用量 | 免費執行次數，然後大約 $5 至 $20 每次審查作為使用額度 |112| 成本 | 計入正常使用量 | 計入正常使用量 | 免費執行次數，然後大約 $5 至 $20 每次審查作為使用額度 |

113| 最適合 | 迭代時的快速反饋 | 在批准前審查隊友的拉取請求 | 在實質性變更前合併時的信心 |113| 最適合 | 迭代時的快速反饋 | 在批准前審查隊友的拉取請求 | 在合併實質性變更前時的信心 |

114 114

115使用 `/code-review` 在工作時獲得快速反饋。使用 `/review <pr>` 審查拉取請求，就像您在批准前會做的那樣。在合併實質性變更前使用 `/code-review ultra`，當您想要更深入的審查以捕捉本地審查可能遺漏的問題時。115使用 `/code-review` 在工作時獲得快速反饋。使用 `/review <pr>` 審查拉取請求，就像您在批准前會做的那樣。在合併實質性變更前使用 `/code-review ultra`，當您想要更深入的審查以捕捉本地審查可能遺漏的問題時。

116 116

voice-dictation.md +3 −2

Details

20 20

21語音聽寫會將您錄製的音頻串流傳輸到 Anthropic 的伺服器進行轉錄。音頻不在本地處理。它需要以下所有條件：21語音聽寫會將您錄製的音頻串流傳輸到 Anthropic 的伺服器進行轉錄。音頻不在本地處理。它需要以下所有條件：

22 22

23* **Claude.ai 帳戶**：語音轉文字服務僅在您使用 Claude.ai 帳戶進行身份驗證時可用，當 Claude Code 配置為直接使用 Anthropic API 金鑰、Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 時不可用。23* **Claude.ai 帳戶**：語音轉文字服務僅在您使用 Claude.ai 帳戶進行身份驗證時可用，當 Claude Code 配置為直接使用 Anthropic API 金鑰、Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 時不可用。

24* **未啟用 HIPAA 合規性的組織**：當此限制適用時，`/voice` 會顯示 `Voice mode is disabled by your organization's policy`。24* **未啟用 HIPAA 合規性的組織**：當此限制適用時，`/voice` 會顯示 `Voice mode is disabled by your organization's policy`。

25* **本地麥克風**：語音聽寫在遠端環境中不起作用，例如[網頁上的 Claude Code](/zh-TW/claude-code-on-the-web)或 SSH 工作階段。25* **本地麥克風**：語音聽寫在遠端環境中不起作用，例如[網頁上的 Claude Code](/zh-TW/claude-code-on-the-web)或 SSH 工作階段。

26* **如果您在 WSL 中執行 Claude Code，則需要 WSLg**：WSLg 在從 Microsoft Store 在 Windows 10 或 11 上安裝 WSL2 時包含。如果 WSLg 不可用，例如在 WSL1 上，改為在原生 Windows 中執行 Claude Code。26* **如果您在 WSL 中執行 Claude Code，則需要 WSLg**：WSLg 在從 Microsoft Store 在 Windows 10 或 11 上安裝 WSL2 時包含。如果 WSLg 不可用，例如在 WSL1 上，改為在原生 Windows 中執行 Claude Code。

183* **Linux 上的 `No audio recording tool found`**：原生音頻模組無法載入，且未安裝回退。使用錯誤訊息中顯示的命令安裝 SoX，例如 `sudo apt-get install sox`。183* **Linux 上的 `No audio recording tool found`**：原生音頻模組無法載入，且未安裝回退。使用錯誤訊息中顯示的命令安裝 SoX，例如 `sudo apt-get install sox`。

184* **`Voice mode requires a microphone, but SoX could not open an audio capture device`**：SoX 已安裝，但主機沒有音頻擷取裝置，例如無頭伺服器或容器。在具有麥克風的機器上執行 Claude Code。{/* min-version: 2.1.195 */}自 v2.1.195 起，Linux 上的 Claude Code 在該情況下報告此訊息；較早的版本即使已安裝 SoX 也會要求您安裝它。184* **`Voice mode requires a microphone, but SoX could not open an audio capture device`**：SoX 已安裝，但主機沒有音頻擷取裝置，例如無頭伺服器或容器。在具有麥克風的機器上執行 Claude Code。{/* min-version: 2.1.195 */}自 v2.1.195 起，Linux 上的 Claude Code 在該情況下報告此訊息；較早的版本即使已安裝 SoX 也會要求您安裝它。

185* **`Voice mode could not find a working audio recorder in WSL`**：WSLg 透過 PulseAudio 而非 ALSA 裝置路由音頻，因此 SoX 需要明確安裝其 PulseAudio 後端。執行 `sudo apt install sox libsox-fmt-pulse`。單獨安裝 `sox` 會拉入 ALSA 後端，這在 WSL 上無法錄製，因為沒有 `/dev/snd` 裝置。185* **`Voice mode could not find a working audio recorder in WSL`**：WSLg 透過 PulseAudio 而非 ALSA 裝置路由音頻，因此 SoX 需要明確安裝其 PulseAudio 後端。執行 `sudo apt install sox libsox-fmt-pulse`。單獨安裝 `sox` 會拉入 ALSA 後端，這在 WSL 上無法錄製，因為沒有 `/dev/snd` 裝置。

186* **`Voice input is failing repeatedly and has been paused`**：語音聽寫連續遇到多個啟動失敗，並停止嘗試新的工作階段，直到一個成功。這通常表示此主機上的麥克風或音頻堆疊無法捕獲音頻，例如無頭伺服器、沒有音頻傳遞的遠端 shell 或被拒絕的麥克風權限。確認工作輸入裝置，修復上述項目中的根本原因，然後再次觸發語音。186* **`Voice input is failing repeatedly and has been paused`**：語音聽寫連續遇到多個啟動失敗，並停止嘗試新的工作階段，直到一個成功。失敗計數無論麥克風無法啟動或錄音機啟動後停止而未產生任何音頻。這通常表示此主機上的麥克風或音頻堆疊無法捕獲音頻，例如無頭伺服器、沒有音頻傳遞的遠端 shell 或被拒絕的麥克風權限。確認工作輸入裝置，修復上述項目中的根本原因，然後再次觸發語音。{/* min-version: 2.1.202 */}在 v2.1.202 之前，只有啟動失敗計入暫停。

187* **在按住模式中按住 `Space` 時沒有任何反應**：在按住時監視提示輸入。如果空格不斷累積，語音聽寫可能已關閉；執行 `/voice hold` 啟用它。如果只出現一個或兩個空格然後沒有任何反應，語音聽寫已開啟但按住偵測未觸發。按住偵測需要您的終端機發送按鍵重複事件，因此如果在作業系統層級停用了按鍵重複，它無法偵測按住的鍵。使用 `/voice tap` 切換到點擊模式以避免按鍵重複要求。187* **在按住模式中按住 `Space` 時沒有任何反應**：在按住時監視提示輸入。如果空格不斷累積，語音聽寫可能已關閉；執行 `/voice hold` 啟用它。如果只出現一個或兩個空格然後沒有任何反應，語音聽寫已開啟但按住偵測未觸發。按住偵測需要您的終端機發送按鍵重複事件，因此如果在作業系統層級停用了按鍵重複，它無法偵測按住的鍵。使用 `/voice tap` 切換到點擊模式以避免按鍵重複要求。

188* **在點擊模式中點擊 `Space` 輸入空格而不是錄製**：第一次點擊只在提示輸入為空時開始錄製。先清除輸入，或通過執行 `/voice tap` 檢查您是否處於點擊模式。188* **在點擊模式中點擊 `Space` 輸入空格而不是錄製**：第一次點擊只在提示輸入為空時開始錄製。先清除輸入，或通過執行 `/voice tap` 檢查您是否處於點擊模式。

189* **`No audio detected from microphone`**：錄製已開始但捕獲了無聲。確認正確的輸入裝置設定為系統預設值，其輸入級別未靜音或接近零。在 Windows 上，開啟設定 → 系統 → 聲音 → 輸入並選擇您的麥克風。在 macOS 上，開啟系統設定 → 聲音 → 輸入。189* **`No audio detected from microphone`**：錄製已開始但捕獲了無聲。確認正確的輸入裝置設定為系統預設值，其輸入級別未靜音或接近零。在 Windows 上，開啟設定 → 系統 → 聲音 → 輸入並選擇您的麥克風。在 macOS 上，開啟系統設定 → 聲音 → 輸入。

190* **`Voice connection failed`**：您的錄製因為連線失敗而從未到達轉錄服務。檢查您的網路並重試。{/* min-version: 2.1.200 */}捕獲無音頻的錄製會報告 `No audio detected from microphone` 而不是此訊息。在 v2.1.200 之前，無聲麥克風可能會報告連線失敗，這暗示網路問題，而實際問題是輸入裝置。

190* **`No speech detected`**：音頻到達轉錄服務但未識別任何單詞。靠近麥克風說話，減少背景噪音，並確認您的[聽寫語言](#change-the-dictation-language)與您說話的語言相符。191* **`No speech detected`**：音頻到達轉錄服務但未識別任何單詞。靠近麥克風說話，減少背景噪音，並確認您的[聽寫語言](#change-the-dictation-language)與您說話的語言相符。

191* **轉錄是亂碼或使用了錯誤的語言**：聽寫預設為英文。如果您用另一種語言聽寫，請先在 `/config` 中設定它。請參閱[變更聽寫語言](#change-the-dictation-language)。192* **轉錄是亂碼或使用了錯誤的語言**：聽寫預設為英文。如果您用另一種語言聽寫，請先在 `/config` 中設定它。請參閱[變更聽寫語言](#change-the-dictation-language)。

192 193

vs-code.md +11 −7

Details

19安裝前，請確保您擁有：19安裝前，請確保您擁有：

20 20

21* VS Code 1.98.0 或更高版本21* VS Code 1.98.0 或更高版本

22* Anthropic 帳戶：任何付費 Claude 訂閱（Pro、Max、Team 或 Enterprise）或 Claude Console 帳戶都可以使用，不需要 API 金鑰。首次開啟擴充功能時，您將[使用此帳戶登入](/zh-TW/authentication#log-in-to-claude-code)。如果您透過第三方提供者（如 Amazon Bedrock 或 Google Vertex AI）存取 Claude，請參閱[使用第三方提供者](#use-third-party-providers)以取得設定說明。22* Anthropic 帳戶：任何付費 Claude 訂閱（Pro、Max、Team 或 Enterprise）或 Claude Console 帳戶都可以使用，不需要 API 金鑰。首次開啟擴充功能時，您將[使用此帳戶登入](/zh-TW/authentication#log-in-to-claude-code)。如果您透過第三方提供者（如 Amazon Bedrock 或 Google Cloud 的 Agent Platform）存取 Claude，請參閱[使用第三方提供者](#use-third-party-providers)以取得設定說明。

23 23

24<Tip>24<Tip>

25 此擴充功能包含其自有的 CLI（命令列介面）副本供聊天面板使用。若要在 VS Code 的整合終端機中執行 `claude`，您還需要[獨立 CLI 安裝](/zh-TW/setup)。詳細資訊請參閱 [VS Code 擴充功能與 Claude Code CLI](#vs-code-extension-vs-claude-code-cli)。25 此擴充功能包含其自有的 CLI（命令列介面）副本供聊天面板使用。若要在 VS Code 的整合終端機中執行 `claude`，您還需要[獨立 CLI 安裝](/zh-TW/setup)。詳細資訊請參閱 [VS Code 擴充功能與 Claude Code CLI](#vs-code-extension-vs-claude-code-cli)。

102 102

103提示框支援多項功能：103提示框支援多項功能：

104 104

105* **許可模式**：點擊提示框底部的模式指示器以切換模式。在正常模式下，Claude 在每個操作前要求許可。在 Plan Mode 中，Claude 描述它將做什麼，並在進行變更前等待批准。VS Code 會自動將計畫作為完整 markdown 文件開啟，您可以在其中添加內聯評論以在 Claude 開始前提供反饋。在自動接受模式下，Claude 進行編輯而不詢問。在 VS Code 設定中的 `claudeCode.initialPermissionMode` 下設定預設值。105* **許可模式**：點擊提示框底部的模式指示器以切換模式，或在 VS Code 設定中的 `claudeCode.initialPermissionMode` 下設定預設值。請參閱[許可模式](/zh-TW/permission-modes#switch-permission-modes)以了解指示器提供的每種模式。

106 * **Manual**：Claude 在每個操作前要求許可。

107 * **Plan**：Claude 描述它將做什麼，並在進行變更前等待批准。VS Code 會自動將計畫作為完整 Markdown 文件開啟，您可以在其中添加內聯評論以在 Claude 開始前提供反饋。

108 * **Edit automatically**：Claude 進行編輯而不詢問。

106* **命令菜單**：點擊 `/` 或輸入 `/` 以開啟命令菜單。選項包括附加檔案、切換模型、切換擴展思考、查看計畫使用情況（`/usage`）以及啟動 [Remote Control](/zh-TW/remote-control) 工作階段（`/remote-control`）。自訂部分提供對 MCP servers、hooks、memory、permissions 和 plugins 的存取。帶有終端機圖示的項目在整合終端機中開啟。109* **命令菜單**：點擊 `/` 或輸入 `/` 以開啟命令菜單。選項包括附加檔案、切換模型、切換擴展思考、查看計畫使用情況（`/usage`）以及啟動 [Remote Control](/zh-TW/remote-control) 工作階段（`/remote-control`）。自訂部分提供對 MCP servers、hooks、memory、permissions 和 plugins 的存取。帶有終端機圖示的項目在整合終端機中開啟。

110 * {/* min-version: 2.1.203 */}設定部分包括**為所有工作階段啟用 Remote Control**，它設定 [`remoteControlAtStartup`](/zh-TW/settings#available-settings)，以便[每個新的互動工作階段都自動連接到 Remote Control](/zh-TW/remote-control#enable-remote-control-for-all-sessions)。需要 Claude Code v2.1.203 或更新版本。

107* **上下文指示器**：提示框顯示您使用了多少 Claude 的 context window。Claude 在需要時會自動壓縮，或您可以手動執行 `/compact`。111* **上下文指示器**：提示框顯示您使用了多少 Claude 的 context window。Claude 在需要時會自動壓縮，或您可以手動執行 `/compact`。

108* **擴展思考**：讓 Claude 花更多時間推理複雜問題。透過命令菜單（`/`）切換它。Claude 的推理在對話中顯示為摺疊的區塊：點擊一個區塊以讀取它，或按 `Ctrl+O` 以展開或摺疊工作階段中的每個思考區塊。有關詳細資訊，請參閱 [Extended thinking](/zh-TW/model-config#extended-thinking)。112* **擴展思考**：讓 Claude 花更多時間推理複雜問題。透過命令菜單（`/`）切換它。Claude 的推理在對話中顯示為摺疊的區塊：點擊一個區塊以讀取它，或按 `Ctrl+O` 以展開或摺疊工作階段中的每個思考區塊。有關詳細資訊，請參閱 [Extended thinking](/zh-TW/model-config#extended-thinking)。

109* **多行輸入**：按 `Shift+Enter` 以添加新行而不傳送。這也適用於問題對話框的'其他'自由文字輸入。113* **多行輸入**：按 `Shift+Enter` 以添加新行而不傳送。這也適用於問題對話框的「其他」自由文字輸入。

110 114

111<h3 id="reference-files-and-folders">115<h3 id="reference-files-and-folders">

112 參考檔案和資料夾116 參考檔案和資料夾

356</h3>360</h3>

357 361

358| 設定 | 預設值 | 描述 |362| 設定 | 預設值 | 描述 |

359| ----------------------------------- | --------- | ----------------------------------------------------------------------------------------------------- |363| ----------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

361| `initialPermissionMode` | `default` | 控制新對話的批准提示：`default`、`plan`、`acceptEdits` 或 `bypassPermissions`。請參閱[許可模式](/zh-TW/permission-modes)。 |365| `initialPermissionMode` | `default` | 控制新對話的批准提示：`default`、`plan`、`acceptEdits` 或 `bypassPermissions`。{/* min-version: 2.1.200 */}`manual` 是 `default` 的別名，並選擇模式指示器中標記為**手動**的模式。需要 Claude Code v2.1.200 或更新版本。請參閱[許可模式](/zh-TW/permission-modes)。 |

479 使用第三方提供者483 使用第三方提供者

480</h2>484</h2>

481 485

482預設情況下，Claude Code 直接連接到 Anthropic 的 API。如果您的組織使用 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 來存取 Claude，請配置擴充功能以改為使用您的提供者：486預設情況下，Claude Code 直接連接到 Anthropic 的 API。如果您的組織使用 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 來存取 Claude，請配置擴充功能以改為使用您的提供者：

483 487

484<Steps>488<Steps>

485 <Step title="停用登入提示">489 <Step title="停用登入提示">

492 遵循您的提供者的設定指南：496 遵循您的提供者的設定指南：

493 497

494 * [Amazon Bedrock 上的 Claude Code](/zh-TW/amazon-bedrock)498 * [Amazon Bedrock 上的 Claude Code](/zh-TW/amazon-bedrock)

495 * [Google Vertex AI 上的 Claude Code](/zh-TW/google-vertex-ai)499 * [Google Cloud 的 Agent Platform 上的 Claude Code](/zh-TW/google-vertex-ai)

496 * [Microsoft Foundry 上的 Claude Code](/zh-TW/microsoft-foundry)500 * [Microsoft Foundry 上的 Claude Code](/zh-TW/microsoft-foundry)

497 501

498 這些指南涵蓋在 `~/.claude/settings.json` 中配置您的提供者，這確保您的設定在 VS Code 擴充功能和 CLI 之間共享。502 這些指南涵蓋在 `~/.claude/settings.json` 中配置您的提供者，這確保您的設定在 VS Code 擴充功能和 CLI 之間共享。

web-quickstart.md +7 −7

Details

43Claude Code 在任何地方的行為都相同。改變的是代碼執行的位置以及您的本地配置是否可用。Desktop 應用程式提供本地和雲端會話，因此其下面的答案取決於您選擇的是哪一個：43Claude Code 在任何地方的行為都相同。改變的是代碼執行的位置以及您的本地配置是否可用。Desktop 應用程式提供本地和雲端會話，因此其下面的答案取決於您選擇的是哪一個：

44 44

~~46| :---------------------------------- | :----------------------------------------------------------------------------------------------- | :---------------- | :----------- | :----------- |~~46| :---------------------------------- | :---------------------------------------------------------------------------------------------- | :---------------- | :----------- | :----------- |

49| **使用您的本地配置** | 否，僅儲存庫 | 是 | 是 | 本地為是，雲端為否 |49| **使用您的本地配置** | 否，僅儲存庫 | 是 | 是 | 本地為是，雲端為否 |

50| **需要 GitHub** | 是，或透過 `--remote` [捆綁本地儲存庫](/zh-TW/claude-code-on-the-web#send-local-repositories-without-github) | 否 | 否 | 僅限雲端會話 |50| **需要 GitHub** | 是，或透過 `--cloud` [捆綁本地儲存庫](/zh-TW/claude-code-on-the-web#send-local-repositories-without-github) | 否 | 否 | 僅限雲端會話 |

51| **如果您斷開連接，保持執行** | 是 | 終端保持開啟時 | 否 | 取決於會話類型 |51| **如果您斷開連接，保持執行** | 是 | 終端保持開啟時 | 否 | 取決於會話類型 |

54 54

55請參閱 [terminal quickstart](/zh-TW/quickstart)、[Desktop 應用程式](/zh-TW/desktop) 或 [Remote Control](/zh-TW/remote-control) 文件以設定這些。55請參閱 [terminal quickstart](/zh-TW/quickstart)、[Desktop 應用程式](/zh-TW/desktop) 或 [Remote Control](/zh-TW/remote-control) 文件以設定這些。

113 /web-setup113 /web-setup

114 ```114 ```

115 115

116 這會將您的 `gh` 令牌同步到您的 Claude 帳戶。如果您還沒有雲端環境，`/web-setup` 會建立一個具有 Trusted 網路存取且沒有設定指令碼的環境。您可以[稍後編輯環境或新增變數](/zh-TW/claude-code-on-the-web#configure-your-environment)。一旦 `/web-setup` 完成，您可以使用 [`--remote`](/zh-TW/claude-code-on-the-web#from-terminal-to-web) 從您的終端啟動雲端會話，或使用 [`/schedule`](/zh-TW/routines) 設定定期任務。116 這會將您的 `gh` 令牌同步到您的 Claude 帳戶。如果您還沒有雲端環境，`/web-setup` 會建立一個具有 Trusted 網路存取且沒有設定指令碼的環境。您可以[稍後編輯環境或新增變數](/zh-TW/claude-code-on-the-web#configure-your-environment)。一旦 `/web-setup` 完成，您可以使用 [`--cloud`](/zh-TW/claude-code-on-the-web#from-terminal-to-web) 從您的終端啟動雲端會話，或使用 [`/schedule`](/zh-TW/routines) 設定定期任務。

117 </Step>117 </Step>

118</Steps>118</Steps>

119 119

129 </Step>129 </Step>

130 130

131 <Step title="選擇權限模式">131 <Step title="選擇權限模式">

132 輸入框旁邊的模式下拉菜單預設為**接受編輯**，其中 Claude 進行更改並推送分支而無需停止以獲得批准。如果您希望 Claude 提出方法並在編輯文件前等待您的同意，請切換到 **Plan Mode**。雲端會話不提供詢問權限或繞過權限。請參閱[權限模式](/zh-TW/permission-modes)以了解完整列表。132 輸入框旁邊的模式下拉菜單預設為**接受編輯**，其中 Claude 進行更改並推送分支而無需停止以獲得批准。如果您希望 Claude 提出方法並在編輯文件前等待您的同意，請切換到 **Plan Mode**。雲端會話不提供 Manual 或 Bypass 權限。請參閱[權限模式完整列表](/zh-TW/permission-modes#available-modes)以了解每個模式允許的操作。

133 </Step>133 </Step>

134 134

135 <Step title="描述任務並提交">135 <Step title="描述任務並提交">

216 216

217如果您在 Claude Code 內輸入它並且命令菜單顯示 `No commands match "/web-setup"`，或提交它返回 `Unknown command: /web-setup`，該命令被隱藏是因為未滿足要求。原因通常是您的 CLI 版本早於 v2.1.80，或者您使用 API 金鑰或第三方提供商而不是 claude.ai 訂閱進行驗證。執行 `claude update`，然後執行 `/login` 以使用您的 claude.ai 帳戶登入。217如果您在 Claude Code 內輸入它並且命令菜單顯示 `No commands match "/web-setup"`，或提交它返回 `Unknown command: /web-setup`，該命令被隱藏是因為未滿足要求。原因通常是您的 CLI 版本早於 v2.1.80，或者您使用 API 金鑰或第三方提供商而不是 claude.ai 訂閱進行驗證。執行 `claude update`，然後執行 `/login` 以使用您的 claude.ai 帳戶登入。

218 218

219<h3 id="could-not-create-a-cloud-environment-or-no-cloud-environment-available-when-using-remote-or-ultraplan">219<h3 id="could-not-create-a-cloud-environment-or-no-cloud-environment-available-when-using-cloud-or-ultraplan">

220 使用 `--remote` 或 ultraplan 時出現 "Could not create a cloud environment" 或 "No cloud environment available"220 使用 `--cloud` 或 ultraplan 時出現 "Could not create a cloud environment" 或 "No cloud environment available"

221</h3>221</h3>

222 222

223遠端會話功能會在您沒有雲端環境時自動建立預設雲端環境。如果您看到 "Could not create a cloud environment"，自動建立失敗。{/* max-version: 2.1.100 */}如果您看到 "No cloud environment available"，您的 CLI 早於自動建立。在任何一種情況下，在 Claude Code CLI 中執行 `/web-setup` 以手動建立一個，或訪問 [claude.ai/code](https://claude.ai/code) 並按照上面的**建立您的環境**步驟進行。223遠端會話功能會在您沒有雲端環境時自動建立預設雲端環境。如果您看到 "Could not create a cloud environment"，自動建立失敗。{/* max-version: 2.1.100 */}如果您看到 "No cloud environment available"，您的 CLI 早於自動建立。在任何一種情況下，在 Claude Code CLI 中執行 `/web-setup` 以手動建立一個，或訪問 [claude.ai/code](https://claude.ai/code) 並按照上面的**建立您的環境**步驟進行。

whats-new.md +1 −1

Details

33</Update>33</Update>

34 34

35<Update label="Week 23" description="June 1–5, 2026" tags={["v2.1.158–v2.1.165"]}>35<Update label="Week 23" description="June 1–5, 2026" tags={["v2.1.158–v2.1.165"]}>

~~36 **Bedrock、Vertex 和 Foundry 上的 Auto mode**：auto mode 現在可在第三方提供者上用於 Opus 4.7 和 Opus 4.8，用背景安全檢查取代權限提示。~~36 **Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上的 Auto mode**：auto mode 現在可在第三方提供者上用於 Opus 4.7 和 Opus 4.8，用背景安全檢查取代權限提示。

37 37

38 本週還有：**更安全的自動編輯**在 `acceptEdits` 模式中寫入可執行程式碼的檔案前提示；**`/plugin list`** 內聯列印您安裝的外掛程式；以及**版本需求**讓受管部署要求核准的 Claude Code 版本範圍。38 本週還有：**更安全的自動編輯**在 `acceptEdits` 模式中寫入可執行程式碼的檔案前提示；**`/plugin list`** 內聯列印您安裝的外掛程式；以及**版本需求**讓受管部署要求核准的 Claude Code 版本範圍。

39 39

whats-new/2026-w15.md +2 −2

Details

102 102

103 <div className="digest-wins-grid">103 <div className="digest-wins-grid">

104 <div>焦點檢視：在無閃爍模式中按 <code>Ctrl+O</code> 以將檢視摺疊到您的最後提示、單行工具摘要（含 diffstats）和 Claude 的最終回應</div>104 <div>焦點檢視：在無閃爍模式中按 <code>Ctrl+O</code> 以將檢視摺疊到您的最後提示、單行工具摘要（含 diffstats）和 Claude 的最終回應</div>

105 <div>登入畫面上的引導式 <a href="/zh-TW/docs/amazon-bedrock">Bedrock</a> 和 <a href="/zh-TW/docs/google-vertex-ai">Vertex AI</a> 設定精靈：選擇「第三方平台」以進行逐步驗證、區域、認證檢查和模型固定</div>105 <div>登入畫面上的引導式 <a href="/zh-TW/docs/amazon-bedrock">Amazon Bedrock</a> 和 <a href="/zh-TW/docs/google-vertex-ai">Google Cloud 的 Agent Platform</a> 設定精靈：選擇「第三方平台」以進行逐步驗證、區域、認證檢查和模型固定</div>

106 <div><code>/agents</code> 獲得標籤式版面配置：「執行中」標籤顯示帶有 <code>● N running</code> 計數的即時子代理，加上「執行代理」和「檢視執行中的執行個體」動作在「程式庫」標籤中</div>106 <div><code>/agents</code> 獲得標籤式版面配置：「執行中」標籤顯示帶有 <code>● N running</code> 計數的即時子代理，加上「執行代理」和「檢視執行中的執行個體」動作在「程式庫」標籤中</div>

107 <div>預設工作量級別現在對 API 金鑰、Bedrock、Vertex、Foundry、Team 和 Enterprise 使用者為 <code>high</code>（使用 <code>/effort</code> 控制）</div>107 <div>預設工作量級別現在對 API 金鑰、Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry、Team 和 Enterprise 使用者為 <code>high</code>（使用 <code>/effort</code> 控制）</div>

108 <div><code>/cost</code> 為訂閱使用者顯示每個模型和快取命中的細目分類</div>108 <div><code>/cost</code> 為訂閱使用者顯示每個模型和快取命中的細目分類</div>

109 <div><code>/release-notes</code> 現在是互動式版本選擇器</div>109 <div><code>/release-notes</code> 現在是互動式版本選擇器</div>

110 <div>狀態列：新的 <code>refreshInterval</code> 設定每 N 秒重新執行命令，JSON 輸入中的 <code>workspace.git\_worktree</code></div>110 <div>狀態列：新的 <code>refreshInterval</code> 設定每 N 秒重新執行命令，JSON 輸入中的 <code>workspace.git\_worktree</code></div>

whats-new/2026-w16.md +1 −1

Details

123 <div><code>/fewer-permission-prompts</code> 掃描您的文字記錄以尋找常見的唯讀 Bash 和 MCP 呼叫，並為 <code>.claude/settings.json</code> 提議允許清單</div>123 <div><code>/fewer-permission-prompts</code> 掃描您的文字記錄以尋找常見的唯讀 Bash 和 MCP 呼叫，並為 <code>.claude/settings.json</code> 提議允許清單</div>

124 <div>Claude 現在可以透過 Skill 工具發現並執行內建命令，例如 <code>/init</code>、<code>/review</code> 和 <code>/security-review</code></div>124 <div>Claude 現在可以透過 Skill 工具發現並執行內建命令，例如 <code>/init</code>、<code>/review</code> 和 <code>/security-review</code></div>

125 <div><code>PreCompact</code> hooks 可以透過以代碼 2 結束或傳回 <code>{"{"}"decision":"block"{"}"}</code> 來阻止壓縮</div>125 <div><code>PreCompact</code> hooks 可以透過以代碼 2 結束或傳回 <code>{"{"}"decision":"block"{"}"}</code> 來阻止壓縮</div>

126 <div><code>ENABLE\_PROMPT\_CACHING\_1H</code> 選擇 API 金鑰、Bedrock、Vertex 和 Foundry 使用者進入 1 小時 prompt cache TTL</div>126 <div><code>ENABLE\_PROMPT\_CACHING\_1H</code> 選擇 API 金鑰、Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 使用者進入 1 小時 prompt cache TTL</div>

127 <div><code>sandbox.network.deniedDomains</code> 設定從更廣泛的 <code>allowedDomains</code> 萬用字元中切割特定網域</div>127 <div><code>sandbox.network.deniedDomains</code> 設定從更廣泛的 <code>allowedDomains</code> 萬用字元中切割特定網域</div>

128 <div><code>/undo</code> 現在是 <code>/rewind</code> 的別名，<code>/proactive</code> 是 <code>/loop</code> 的別名</div>128 <div><code>/undo</code> 現在是 <code>/rewind</code> 的別名，<code>/proactive</code> 是 <code>/loop</code> 的別名</div>

129 <div>強化的 Bash 權限：拒絕規則現在透過 <code>env</code>/<code>sudo</code>/<code>watch</code> 包裝器進行比對，<code>Bash(find:\*)</code> 允許規則不再自動核准 <code>-exec</code> 或 <code>-delete</code></div>129 <div>強化的 Bash 權限：拒絕規則現在透過 <code>env</code>/<code>sudo</code>/<code>watch</code> 包裝器進行比對，<code>Bash(find:\*)</code> 允許規則不再自動核准 <code>-exec</code> 或 <code>-delete</code></div>

whats-new/2026-w18.md +2 −2

Details

103 <div><code>--dangerously-skip-permissions</code> 現在繞過對 <code>.claude/</code>、<code>.git/</code>、<code>.vscode/</code>、shell 設定檔和其他先前受保護路徑的寫入提示，同時災難性移除命令仍會提示作為安全網</div>103 <div><code>--dangerously-skip-permissions</code> 現在繞過對 <code>.claude/</code>、<code>.git/</code>、<code>.vscode/</code>、shell 設定檔和其他先前受保護路徑的寫入提示，同時災難性移除命令仍會提示作為安全網</div>

104 <div>當 <code>ANTHROPIC\_BASE\_URL</code> 指向 Anthropic 相容閘道時，<code>/model</code> 選擇器可以列出來自您閘道的 <code>/v1/models</code> 端點的模型；自 v2.1.129 起使用 <code>CLAUDE\_CODE\_ENABLE\_GATEWAY\_MODEL\_DISCOVERY=1</code> 選擇加入</div>104 <div>當 <code>ANTHROPIC\_BASE\_URL</code> 指向 Anthropic 相容閘道時，<code>/model</code> 選擇器可以列出來自您閘道的 <code>/v1/models</code> 端點的模型；自 v2.1.129 起使用 <code>CLAUDE\_CODE\_ENABLE\_GATEWAY\_MODEL\_DISCOVERY=1</code> 選擇加入</div>

105 <div>在啟動期間遇到暫時性錯誤的 MCP 伺服器現在會自動重試最多 3 次，而不是保持斷開連接</div>105 <div>在啟動期間遇到暫時性錯誤的 MCP 伺服器現在會自動重試最多 3 次，而不是保持斷開連接</div>

106 <div><code>ANTHROPIC\_BEDROCK\_SERVICE\_TIER</code> 選擇 Bedrock 服務層：<code>default</code>、<code>flex</code> 或 <code>priority</code></div>106 <div><code>ANTHROPIC\_BEDROCK\_SERVICE\_TIER</code> 選擇 Amazon Bedrock 服務層：<code>default</code>、<code>flex</code> 或 <code>priority</code></div>

107 <div><code>/terminal-setup</code> 啟用 iTerm2 的剪貼簿存取設定，以便 <code>/copy</code> 可以運作，包括從 tmux</div>107 <div><code>/terminal-setup</code> 啟用 iTerm2 的剪貼簿存取設定，以便 <code>/copy</code> 可以運作，包括從 tmux</div>

108 <div>Vertex AI 現在支援 X.509 憑證型工作負載身分識別聯盟 (mTLS ADC)</div>108 <div>Google Cloud 的 Agent Platform 現在支援 X.509 憑證型工作負載身分識別聯盟 (mTLS ADC)</div>

109 <div>重大記憶體洩漏修復：影像繁重的會話、大型文字記錄歷史上的 <code>/usage</code> 以及沒有進度事件的長時間執行工具</div>109 <div>重大記憶體洩漏修復：影像繁重的會話、大型文字記錄歷史上的 <code>/usage</code> 以及沒有進度事件的長時間執行工具</div>

110 </div>110 </div>

111</div>111</div>

whats-new/2026-w21.md +1 −1

Details

37 <div>新的 <a href="/zh-TW/code-review"><code>/code-review</code></a> 命令在選定的努力級別（例如 <code>/code-review high</code>）報告正確性錯誤，<code>--comment</code> 將發現作為內聯 GitHub PR 評論發佈。<code>/simplify</code> 保留為單獨的清理專用檢查。</div>37 <div>新的 <a href="/zh-TW/code-review"><code>/code-review</code></a> 命令在選定的努力級別（例如 <code>/code-review high</code>）報告正確性錯誤，<code>--comment</code> 將發現作為內聯 GitHub PR 評論發佈。<code>/simplify</code> 保留為單獨的清理專用檢查。</div>

38 <div>背景會話現在在 <code>/resume</code> 中與互動式會話一起出現，標記為 <code>bg</code>，並且在 <code>claude agents</code> 中使用 <code>Ctrl+T</code> 固定的會話在空閒時保持活動</div>38 <div>背景會話現在在 <code>/resume</code> 中與互動式會話一起出現，標記為 <code>bg</code>，並且在 <code>claude agents</code> 中使用 <code>Ctrl+T</code> 固定的會話在空閒時保持活動</div>

39 <div><code>claude agents --json</code> 將實時會話列為 JSON 以供指令碼編寫，例如狀態欄和會話選擇器</div>39 <div><code>claude agents --json</code> 將實時會話列為 JSON 以供指令碼編寫，例如狀態欄和會話選擇器</div>

~~40 <div>PowerShell tool 現在在 Windows 上預設為啟用，適用於 Bedrock、Vertex 和 Foundry 使用者；使用 <code>CLAUDE\_CODE\_USE\_POWERSHELL\_TOOL=0</code> 選擇退出</div>~~40 <div>PowerShell tool 現在在 Windows 上預設為啟用，適用於 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 使用者；使用 <code>CLAUDE\_CODE\_USE\_POWERSHELL\_TOOL=0</code> 選擇退出</div>

41 <div><code>claude plugin disable</code> 現在在另一個啟用的 plugin 依賴於目標時拒絕，<code>claude plugin enable</code> 強制啟用傳遞依賴項</div>41 <div><code>claude plugin disable</code> 現在在另一個啟用的 plugin 依賴於目標時拒絕，<code>claude plugin enable</code> 強制啟用傳遞依賴項</div>

42 <div><code>/plugin</code> marketplace 瀏覽窗格顯示預計的上下文成本，Discover 和 Browse 螢幕在安裝前列出 plugin 的命令、agents、skills、hooks 和 MCP/LSP servers</div>42 <div><code>/plugin</code> marketplace 瀏覽窗格顯示預計的上下文成本，Discover 和 Browse 螢幕在安裝前列出 plugin 的命令、agents、skills、hooks 和 MCP/LSP servers</div>

43 <div>新的 <code>worktree.bgIsolation: "none"</code> 設定讓背景會話直接編輯工作副本，無需 <code>EnterWorktree</code>，適用於 worktrees 不實用的儲存庫</div>43 <div>新的 <code>worktree.bgIsolation: "none"</code> 設定讓背景會話直接編輯工作副本，無需 <code>EnterWorktree</code>，適用於 worktrees 不實用的儲存庫</div>

whats-new/2026-w22.md +2 −2

Details

109 <div>Claude Code 現在在找不到主要模型時會切換到您配置的 <code>--fallback-model</code> 以進行工作階段的其餘部分，而不是使每個請求都失敗</div>109 <div>Claude Code 現在在找不到主要模型時會切換到您配置的 <code>--fallback-model</code> 以進行工作階段的其餘部分，而不是使每個請求都失敗</div>

110 <div>外掛程式可以在 <code>plugin.json</code> 或市場項目中宣告 <code>defaultEnabled: false</code>，以便它們安裝而不開啟，直到您啟用它們</div>110 <div>外掛程式可以在 <code>plugin.json</code> 或市場項目中宣告 <code>defaultEnabled: false</code>，以便它們安裝而不開啟，直到您啟用它們</div>

111 <div>Vim 模式：在 NORMAL 模式下按 <code>/</code> 開啟反向歷史搜尋，與 Bash 和 Zsh vi-mode 相符</div>111 <div>Vim 模式：在 NORMAL 模式下按 <code>/</code> 開啟反向歷史搜尋，與 Bash 和 Zsh vi-mode 相符</div>

112 <div>串流工具執行現在始終啟用，包括在禁用遙測和 Bedrock、Vertex 和 Foundry 上</div>112 <div>串流工具執行現在始終啟用，包括在禁用遙測和 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上</div>

113 <div><code>←←</code> 開啟代理檢視現在適用於 Bedrock、Vertex、Foundry 和禁用遙測的情況</div>113 <div><code>←←</code> 開啟代理檢視現在適用於 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和禁用遙測的情況</div>

114 <div>Chrome 中的 Claude：透過 <code>/chrome</code> → "選擇瀏覽器…" 選擇要使用的連接瀏覽器，或在瀏覽器操作執行時在聊天中選擇多個連接的瀏覽器</div>114 <div>Chrome 中的 Claude：透過 <code>/chrome</code> → "選擇瀏覽器…" 選擇要使用的連接瀏覽器，或在瀏覽器操作執行時在聊天中選擇多個連接的瀏覽器</div>

115 <div><code>claude mcp list</code> 和 <code>claude mcp get</code> 現在將未批准的 <code>.mcp.json</code> 伺服器顯示為待批准，而不是在輸出被管道傳輸時自動批准和連接</div>115 <div><code>claude mcp list</code> 和 <code>claude mcp get</code> 現在將未批准的 <code>.mcp.json</code> 伺服器顯示為待批准，而不是在輸出被管道傳輸時自動批准和連接</div>

116 </div>116 </div>

whats-new/2026-w23.md +4 −4

Details

4 4

5# 第 23 週 · 2026 年 6 月 1–5 日5# 第 23 週 · 2026 年 6 月 1–5 日

6 6

7> 在 Bedrock、Vertex 和 Foundry 上執行自動模式，在 acceptEdits 模式下提示寫入可執行程式碼的檔案，使用 /plugin list 列出已安裝的外掛程式，以及為受管部署要求已核准的版本範圍。7> 在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上執行自動模式，在 acceptEdits 模式下提示寫入可執行程式碼的檔案，使用 /plugin list 列出已安裝的外掛程式，以及為受管部署要求已核准的版本範圍。

8 8

9<div className="digest-meta">9<div className="digest-meta">

10 <span>發行版本 <a href="/zh-TW/docs/changelog#2-1-158">v2.1.158 → v2.1.165</a></span>10 <span>發行版本 <a href="/zh-TW/docs/changelog#2-1-158">v2.1.158 → v2.1.165</a></span>

13 13

14<div className="digest-feature">14<div className="digest-feature">

15 <div className="digest-feature-header">15 <div className="digest-feature-header">

~~16 <span className="digest-feature-title">Bedrock、Vertex 和 Foundry 上的自動模式</span>~~16 <span className="digest-feature-title">Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上的自動模式</span>

17 <span className="digest-feature-pill">v2.1.158</span>17 <span className="digest-feature-pill">v2.1.158</span>

18 </div>18 </div>

19 19

20 <p className="digest-feature-lede">自動模式現已在 Bedrock、Vertex 和 Foundry 上提供，適用於 Opus 4.7 和 Opus 4.8，以第三方提供者的背景安全檢查取代權限提示。透過設定 <code>CLAUDE\_CODE\_ENABLE\_AUTO\_MODE=1</code> 來選擇加入。</p>20 <p className="digest-feature-lede">自動模式現已在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上提供，適用於 Opus 4.7 和 Opus 4.8，以第三方提供者的背景安全檢查取代權限提示。透過設定 <code>CLAUDE\_CODE\_ENABLE\_AUTO\_MODE=1</code> 來選擇加入。</p>

21 21

22 <p className="digest-feature-try">在第三方提供者上選擇加入，然後使用 Shift+Tab 切換到自動模式：</p>22 <p className="digest-feature-try">在第三方提供者上選擇加入，然後使用 Shift+Tab 切換到自動模式：</p>

23 23

25 export CLAUDE_CODE_ENABLE_AUTO_MODE=125 export CLAUDE_CODE_ENABLE_AUTO_MODE=1

26 ```26 ```

27 27

~~28 <a className="digest-feature-link" href="/zh-TW/docs/permission-modes#enable-auto-mode-on-bedrock-vertex-ai-or-foundry">在第三方提供者上啟用自動模式</a>~~28 <a className="digest-feature-link" href="/zh-TW/docs/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry">在第三方提供者上啟用自動模式</a>

29</div>29</div>

30 30

31<div className="digest-feature">31<div className="digest-feature">

workflows.md +28 −2

Details

9{/* plan-availability: feature=workflows plans=pro,max,team,enterprise providers=all */}9{/* plan-availability: feature=workflows plans=pro,max,team,enterprise providers=all */}

10 10

11<Note>11<Note>

12 Dynamic workflows 需要 Claude Code v2.1.154 或更新版本，並在所有付費方案上可用，具有 Anthropic API 存取權限，以及在 Amazon Bedrock、Google Cloud Vertex AI 和 Microsoft Foundry 上可用。在 Pro 上，從 `/config` 中的 Dynamic workflows 列啟用它們。12 Dynamic workflows 需要 Claude Code v2.1.154 或更新版本，並在所有付費方案上可用，具有 Anthropic API 存取權限，以及在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上可用。在 Pro 上，從 `/config` 中的 Dynamic workflows 列啟用它們。

13</Note>13</Note>

14 14

15動態工作流程是一個 JavaScript 指令碼，可大規模協調[子代理](/zh-TW/sub-agents)。Claude 為您描述的任務編寫指令碼，執行時期在背景執行它，同時您的工作階段保持回應。15動態工作流程是一個 JavaScript 指令碼，可大規模協調[子代理](/zh-TW/sub-agents)。Claude 為您描述的任務編寫指令碼，執行時期在背景執行它，同時您的工作階段保持回應。

148/effort ultracode148/effort ultracode

149```149```

150 150

151要啟動已啟用 ultracode 的工作階段，請使用 `claude --effort ultracode` 啟動。需要 Claude Code v2.1.203 或更新版本。

152

151啟用 ultracode 後，Claude 決定任務何時值得工作流程。單個請求可以變成一系列工作流程：一個用於理解程式碼，一個用於進行更改，一個用於驗證它。這適用於工作階段中的每項任務，因此每個請求使用更多令牌並花費比較低努力級別更長的時間。153啟用 ultracode 後，Claude 決定任務何時值得工作流程。單個請求可以變成一系列工作流程：一個用於理解程式碼，一個用於進行更改，一個用於驗證它。這適用於工作階段中的每項任務，因此每個請求使用更多令牌並花費比較低努力級別更長的時間。

152 154

153Ultracode 持續當前工作階段，當您啟動新工作階段時重設。當您返回日常工作時，使用 `/effort high` 下降。它在支援 `xhigh` [努力](/zh-TW/model-config#adjust-effort-level)的模型上可用；在其他模型上，`/effort` 功能表不提供它。155Ultracode 持續當前工作階段，當您啟動新工作階段時重設。當您返回日常工作時，使用 `/effort high` 下降。它在支援 `xhigh` [努力](/zh-TW/model-config#adjust-effort-level)的模型上可用；在其他模型上，`/effort` 功能表不提供它。

346 348

347工作流程生成許多代理，因此單次執行可以使用比在對話中完成相同任務更多的令牌。執行計入您的方案使用量和速率限制，如任何其他工作階段。349工作流程生成許多代理，因此單次執行可以使用比在對話中完成相同任務更多的令牌。執行計入您的方案使用量和速率限制，如任何其他工作階段。

348 350

349為了在提交大型任務前評估支出，請先在小片段上執行工作流程：一個目錄而不是整個儲存庫，或一個狹隘的問題而不是廣泛的問題。`/workflows` 檢視顯示每個代理的令牌使用量，隨著執行進行，您可以隨時在那裡停止執行而不會丟失已完成的工作。執行時間的[代理上限](#behavior-and-limits)限制單次執行可以生成多少個代理，這限制了失控指令碼的成本。351為了在提交大型任務前評估支出，請先在小片段上執行工作流程：一個目錄而不是整個儲存庫，或一個狹隘的問題而不是廣泛的問題。`/workflows` 檢視顯示每個代理的令牌使用量，隨著執行進行，您可以隨時在那裡停止執行而不會丟失已完成的工作。執行時間的[代理上限](#behavior-and-limits)限制單次執行可以生成多少個代理，這限制了失控指令碼的成本。要保持每次執行預設較小，請在 `/config` 中[設定大小指南](#set-a-size-guideline)。

352

353Claude Code 也會標記異常增長的執行。當工作流程排程超過 25 個代理，或其預計令牌總數超過 150 萬時，輸入框下方任務面板中的進度線會顯示 `Large workflow` 警告。警告指向您可以停止執行的 [`/workflows`](#watch-the-run)。需要 Claude Code v2.1.203 或更新版本。

354

355警告是建議性的：它不會暫停或限制執行。當您看到它時，有兩個設定會改變：

356

357* 如果您[設定大小指南](#set-a-size-guideline)，指南的代理計數會取代 25 個代理的閾值。

358* 啟用[ultracode](#let-claude-decide-with-ultracode) 的工作階段不會顯示警告，因為啟用 ultracode 已經讓您選擇加入大型執行。

350 359

351工作流程中的每個代理使用您的工作階段模型，除非指令碼將階段路由到不同的模型。要控制模型成本：360工作流程中的每個代理使用您的工作階段模型，除非指令碼將階段路由到不同的模型。要控制模型成本：

352 361

353* 在大型執行前檢查 `/model`，如果您通常為日常工作切換到較小的模型362* 在大型執行前檢查 `/model`，如果您通常為日常工作切換到較小的模型

354* 當您描述任務時，要求 Claude 為不需要最強模型的階段使用較小的模型363* 當您描述任務時，要求 Claude 為不需要最強模型的階段使用較小的模型

355 364

365<h3 id="set-a-size-guideline">

366 設定大小指南

367</h3>

368

369`/config` 中的 Dynamic workflow size 設定保持 Claude 編寫的工作流程預設為較小規模。Claude Code 將設定作為建議發送給 Claude，因此呼叫不同規模的提示仍會覆蓋它。需要 Claude Code v2.1.202 或更新版本。

370

371每個值設定 Claude 在其編寫的指令碼中目標的代理計數。

372

373| 值 | 發送給 Claude 的指南 |

374| :------------- | :------------- |

375| `unrestricted` | 無指南。這是預設值。 |

376| `small` | 目標少於 5 個代理。 |

377| `medium` | 目標少於 15 個代理。 |

378| `large` | 目標少於 50 個代理。 |

379

380變更在下一個提示時生效。[執行時間代理上限](#behavior-and-limits)仍然適用，無論設定如何。

381

356<h3 id="turn-workflows-off">382<h3 id="turn-workflows-off">

357 關閉工作流程383 關閉工作流程

358</h3>384</h3>

worktrees.md +6 −0

Details

40 40

41在第一次在目錄中使用 `--worktree` 之前，請透過在該目錄中執行一次 `claude` 來接受工作區信任對話。如果尚未接受信任，`--worktree` 將以錯誤退出並提示您先在目錄中執行 `claude`。非互動式執行搭配 `-p` 會跳過[信任檢查](/zh-TW/security)，因此 `claude -p --worktree` 會在沒有信任檢查的情況下進行。41在第一次在目錄中使用 `--worktree` 之前，請透過在該目錄中執行一次 `claude` 來接受工作區信任對話。如果尚未接受信任，`--worktree` 將以錯誤退出並提示您先在目錄中執行 `claude`。非互動式執行搭配 `-p` 會跳過[信任檢查](/zh-TW/security)，因此 `claude -p --worktree` 會在沒有信任檢查的情況下進行。

42 42

43如果 Claude Code 在啟動時無法進入 worktree 目錄，例如因為 [`WorktreeCreate` hook](/zh-TW/hooks#worktreecreate) 列印了建立的目錄以外的內容，或因為目錄在設定後被刪除，Claude Code 會列印一個錯誤，命名該路徑並以代碼 1 退出。在 v2.1.205 之前，這會導致會話崩潰，使用 `-p` 時會停滯約 30 秒，然後以代碼 0 退出。

45{/* min-version: 2.1.200 */}在[專案範圍](/zh-TW/plugins-reference#plugin-installation-scopes)從主要檢出安裝的外掛程式也會在同一儲存庫的 worktrees 中載入，因此您不需要為每個 worktree 重新安裝它們。無論您使用 `--worktree` 還是使用 `git worktree add` 建立 worktree，這都適用。需要 Claude Code v2.1.200 或更新版本。

43<Tip>47<Tip>

44 將 `.claude/worktrees/` 新增到您的 `.gitignore`，以便 worktree 內容不會在您的主要檢出中顯示為未追蹤的檔案。48 將 `.claude/worktrees/` 新增到您的 `.gitignore`，以便 worktree 內容不會在您的主要檢出中顯示為未追蹤的檔案。

45</Tip>49</Tip>

106 110

107當代理正在執行時，Claude 會在其 worktree 上執行 `git worktree lock`，以便並行清理無法將其移除。當代理完成時，鎖定會被釋放。若要清理掃描保留的 worktree，請執行 `git worktree remove`，如果 worktree 有未提交的變更或未追蹤的檔案，請新增 `--force`。111當代理正在執行時，Claude 會在其 worktree 上執行 `git worktree lock`，以便並行清理無法將其移除。當代理完成時，鎖定會被釋放。若要清理掃描保留的 worktree，請執行 `git worktree remove`，如果 worktree 有未提交的變更或未追蹤的檔案，請新增 `--force`。

108 112

113在 Windows 上，移除 worktree 之前，Claude Code 會移除其內任何深度的任何 NTFS 連接點或目錄符號連結作為連結項目，以便移除 worktree 不會刪除連結指向的檔案。在 v2.1.205 之前，Claude Code 只移除頂層連結作為連結項目，移除具有嵌套在子目錄中的連接點的 worktree 可能會刪除 worktree 外連結指向的目錄內容。

114

109<h2 id="manage-worktrees-manually">115<h2 id="manage-worktrees-manually">

110 手動管理 worktrees116 手動管理 worktrees

111</h2>117</h2>

zero-data-retention.md +1 −1

Details

19* [服務器管理的設置](/zh-TW/server-managed-settings)19* [服務器管理的設置](/zh-TW/server-managed-settings)

20* 審計日誌20* 審計日誌

21 21

22Claude for Enterprise 上 Claude Code 的 ZDR 僅適用於 Anthropic 的直接平台。對於在 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 上的 Claude 部署，請參考這些平台的數據保留政策。22Claude for Enterprise 上 Claude Code 的 ZDR 僅適用於 Anthropic 的直接平台。對於在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上的 Claude 部署，請參考這些平台的數據保留政策。

23 23

24<h2 id="zdr-scope">24<h2 id="zdr-scope">

25 ZDR 範圍25 ZDR 範圍

Documentation 2026-07-09 23:58 UTC to 2026-07-10 17:00 UTC