Documentation — Spybara

advisor.md +3 −3

Details

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

99 99

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

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

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

108 108

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

110 110

111將顧問設定為 `fable`、`opus` 或 `sonnet`。這些別名解析為 Claude Code 為每個模型系列內建的預設版本，會隨著新的 Claude Code 版本發佈而更新。您也可以傳遞完整的模型 ID，例如 `claude-opus-5`。111將顧問設定為 `fable`、`opus` 或 `sonnet`。這些別名解析為 Claude Code 為每個模型系列內建的預設版本，會隨著新的 Claude Code 版本發佈而更新。您也可以傳遞完整的模型 ID，例如 `claude-opus-5`。

112 112

agent-sdk/agent-loop.md +98 −66

Details

6 6

7> 了解訊息生命週期、工具執行、上下文視窗和支援 SDK 代理程式的架構。7> 了解訊息生命週期、工具執行、上下文視窗和支援 SDK 代理程式的架構。

8 8

9Agent SDK 讓您可以在自己的應用程式中嵌入 Claude Code 的自主代理程式迴圈。SDK 是一個獨立套件，可讓您以程式設計方式控制工具、權限、成本限制和輸出。您不需要安裝 Claude Code CLI 即可使用它。9Agent SDK 讓您可以在自己的應用程式中嵌入 Claude Code 的自主代理程式迴圈。SDK 是一個獨立套件，可讓您以程式設計方式控制工具、權限、成本限制和輸出。

10 10

11當您啟動代理程式時，SDK 會執行與 [Claude Code 相同的執行迴圈](/zh-TW/how-claude-code-works#the-agentic-loop)：Claude 評估您的提示、呼叫工具採取行動、接收結果，並重複直到任務完成。本頁說明該迴圈內發生的情況，以便您可以有效地建立、除錯和最佳化代理程式。11TypeScript 和 Python SDK 都包含原生 Claude Code 二進位檔，因此大多數安裝不需要單獨安裝 Claude Code。請參閱[快速入門的安裝說明](/docs/zh-TW/agent-sdk/quickstart)以了解需要單獨安裝的情況。

13當您啟動代理程式時，SDK 會執行與 [Claude Code 相同的執行迴圈](/docs/zh-TW/how-claude-code-works#the-agentic-loop)：Claude 評估您的提示、呼叫工具採取行動、接收結果，並重複直到任務完成。本頁說明該迴圈內發生的情況，以便您可以有效地建立、除錯和最佳化代理程式。

12 14

13<h2 id="the-loop-at-a-glance">15<h2 id="the-loop-at-a-glance">

14 迴圈概覽16 迴圈概覽

16 18

17每個代理程式工作階段都遵循相同的週期：19每個代理程式工作階段都遵循相同的週期：

18 20

19<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/agent-loop-diagram.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=1c6e8f28d80dba14a7287419656f1237" alt="代理程式迴圈的圖表：您的提示進入代理程式迴圈，Claude 評估並要求工具呼叫（其結果回饋到另一個評估中），或返回最終答案" width="720" height="212" data-path="images/agent-loop-diagram.svg" />21<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/agent-loop-diagram.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=1c6e8f28d80dba14a7287419656f1237" className="dark:hidden" alt="代理程式迴圈的圖表：您的提示進入代理程式迴圈，Claude 評估並要求工具呼叫（其結果回饋到另一個評估中），或返回最終答案" width="720" height="212" data-path="images/agent-loop-diagram.svg" />

23<img src="https://mintcdn.com/claude-code/_xqph1dUOslCOwsj/images/agent-loop-diagram-dark.svg?fit=max&auto=format&n=_xqph1dUOslCOwsj&q=85&s=afe723c52a324d3c61fa72fb02432ab6" className="hidden dark:block" alt="代理程式迴圈的圖表：您的提示進入代理程式迴圈，Claude 評估並要求工具呼叫（其結果回饋到另一個評估中），或返回最終答案" width="720" height="212" data-path="images/agent-loop-diagram-dark.svg" />

20 24

211. **接收提示。** Claude 接收您的提示，以及系統提示、工具定義和對話歷史記錄。SDK 會產生一個 [`SystemMessage`](#message-types)，其子類型為 `"init"`，包含工作階段中繼資料。251. **接收提示。** Claude 接收您的提示，以及系統提示、工具定義和對話歷史記錄。SDK 會產生一個 [`SystemMessage`](#message-types)，其子類型為 `"init"`，包含工作階段中繼資料。

222. **評估並回應。** Claude 評估目前狀態並決定如何進行。它可能會以文字回應、要求一個或多個工具呼叫，或兩者都有。SDK 會產生一個 [`AssistantMessage`](#message-types)，包含文字和任何工具呼叫要求。262. **評估並回應。** Claude 評估目前狀態並決定如何進行。它可能會以文字回應、要求一個或多個工具呼叫，或兩者都有。SDK 會產生一個或多個 [`AssistantMessage`](#message-types) 物件，每個內容區塊（例如文字區塊或工具呼叫要求）各一個。

233. **執行工具。** SDK 執行每個要求的工具並收集結果。每組工具結果都會回饋給 Claude 以進行下一個決定。您可以使用 [hooks](/zh-TW/agent-sdk/hooks) 在工具執行前攔截、修改或阻止工具呼叫。273. **執行工具。** SDK 執行每個要求的工具並收集結果。每組工具結果都會回饋給 Claude 以進行下一個決定。您可以使用 [hooks](/docs/zh-TW/agent-sdk/hooks) 在工具執行前攔截、修改或阻止工具呼叫。

244. **重複。** 步驟 2 和 3 重複為一個週期。每個完整週期是一個回合。Claude 繼續呼叫工具並處理結果，直到它產生沒有工具呼叫的回應。284. **重複。** 步驟 2 和 3 重複為一個週期。每個完整週期是一個回合。Claude 繼續呼叫工具並處理結果，直到它產生沒有工具呼叫的回應。

255. **返回結果。** SDK 會產生最終的 [`AssistantMessage`](#message-types)，包含文字回應（無工具呼叫），然後是 [`ResultMessage`](#message-types)，包含最終文字、代幣使用量、成本和工作階段 ID。295. **返回結果。** SDK 會產生最終的 [`AssistantMessage`](#message-types)，包含文字回應（無工具呼叫），然後是 [`ResultMessage`](#message-types)，包含最終文字、代幣使用量、成本和工作階段 ID。

26 30

37首先，SDK 將您的提示發送給 Claude 並產生一個 [`SystemMessage`](#message-types)，包含工作階段中繼資料。然後迴圈開始：41首先，SDK 將您的提示發送給 Claude 並產生一個 [`SystemMessage`](#message-types)，包含工作階段中繼資料。然後迴圈開始：

38 42

391. **回合 1：** Claude 呼叫 `Bash` 執行 `npm test`。SDK 產生一個 [`AssistantMessage`](#message-types)，包含工具呼叫，執行命令，然後產生一個 [`UserMessage`](#message-types)，包含輸出（三個失敗）。431. **回合 1：** Claude 呼叫 `Bash` 執行 `npm test`。SDK 產生一個 [`AssistantMessage`](#message-types)，包含工具呼叫，執行命令，然後產生一個 [`UserMessage`](#message-types)，包含輸出（三個失敗）。

~~402. **回合 2：** Claude 在 `auth.ts` 和 `auth.test.ts` 上呼叫 `Read`。SDK 返回檔案內容並產生一個 `AssistantMessage`。~~442. **回合 2：** Claude 在 `auth.ts` 和 `auth.test.ts` 上呼叫 `Read`。SDK 產生每個呼叫的 `AssistantMessage` 並返回檔案內容。

~~413. **回合 3：** Claude 呼叫 `Edit` 修復 `auth.ts`，然後呼叫 `Bash` 重新執行 `npm test`。所有三個測試都通過。SDK 產生一個 `AssistantMessage`。~~453. **回合 3：** Claude 呼叫 `Edit` 修復 `auth.ts`，然後呼叫 `Bash` 重新執行 `npm test`。所有三個測試都通過。SDK 產生每個呼叫的 `AssistantMessage`。

424. **最終回合：** Claude 產生一個純文字回應，沒有工具呼叫：「修復了驗證錯誤，所有三個測試現在都通過了。」SDK 產生最終的 `AssistantMessage`，包含此文字，然後是 [`ResultMessage`](#message-types)，包含相同的文字加上成本和使用量。464. **最終回合：** Claude 產生一個純文字回應，沒有工具呼叫：「修復了驗證錯誤，所有三個測試現在都通過了。」SDK 產生最終的 `AssistantMessage`，包含此文字，然後是 [`ResultMessage`](#message-types)，包含相同的文字加上成本和使用量。

43 47

44那是四個回合：三個有工具呼叫，一個最終純文字回應。48那是四個回合：三個有工具呼叫，一個最終純文字回應。

55 59

56* **`SystemMessage`：** 工作階段生命週期事件。`subtype` 欄位區分它們：60* **`SystemMessage`：** 工作階段生命週期事件。`subtype` 欄位區分它們：

57 61

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

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

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

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

62 66

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

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

65* **`UserMessage`：** 在每個工具執行後發出，包含發送回 Claude 的工具結果內容。也針對您在迴圈中期串流的任何使用者輸入發出。69* **`UserMessage`：** 在每個工具執行後發出，包含發送回 Claude 的工具結果內容。也針對您在迴圈中期串流的任何使用者輸入發出。

~~66* **`StreamEvent`：** 僅在啟用部分訊息時發出。包含原始 API 串流事件（文字增量、工具輸入區塊）。請參閱 [串流回應](/zh-TW/agent-sdk/streaming-output)。~~70* **`StreamEvent`：** 僅在啟用部分訊息時發出。包含原始 API 串流事件（文字增量、工具輸入區塊）。請參閱 [串流回應](/docs/zh-TW/agent-sdk/streaming-output)。

67* **`ResultMessage`：** 標記代理程式迴圈的結束。包含最終文字結果、代幣使用量、成本和工作階段 ID。檢查 `subtype` 欄位以確定任務是否成功或達到限制。少數尾隨系統事件（例如 `prompt_suggestion`）可能在其後到達，因此請迭代串流至完成，而不是在結果時中斷。請參閱 [處理結果](#handle-the-result)。71* **`ResultMessage`：** 標記代理程式迴圈的結束。包含最終文字結果、代幣使用量、成本和工作階段 ID。檢查 `subtype` 欄位以確定任務是否成功或達到限制。少數尾隨系統事件（例如 `prompt_suggestion`）可能在其後到達，因此請迭代串流至完成，而不是在結果時中斷。請參閱 [處理結果](#handle-the-result)。

68 72

69這五種類型涵蓋了兩個 SDK 中完整的代理程式迴圈生命週期。TypeScript SDK 還會產生額外的可觀測性事件（hook 事件、工具進度、速率限制、任務通知），提供額外詳細資訊，但不需要驅動迴圈。請參閱 [Python 訊息類型參考](/zh-TW/agent-sdk/python#message-types) 和 [TypeScript 訊息類型參考](/zh-TW/agent-sdk/typescript#message-types) 以了解完整清單。73這五種類型涵蓋了完整的代理程式迴圈生命週期。兩個 SDK 也會產生可觀測性事件，例如速率限制狀態和任務通知，這些事件不需要驅動迴圈。請參閱 [Python 訊息類型參考](/docs/zh-TW/agent-sdk/python#message-types) 和 [TypeScript 訊息類型參考](/docs/zh-TW/agent-sdk/typescript#message-types) 以了解完整清單。

70 74

71<h3 id="handle-messages">75<h3 id="handle-messages">

72 處理訊息76 處理訊息

76 80

77* **僅最終結果：** 處理 `ResultMessage` 以取得輸出、成本以及任務是否成功或達到限制。81* **僅最終結果：** 處理 `ResultMessage` 以取得輸出、成本以及任務是否成功或達到限制。

78* **進度更新：** 處理 `AssistantMessage` 以查看 Claude 在每個回合中做什麼，包括它呼叫了哪些工具。82* **進度更新：** 處理 `AssistantMessage` 以查看 Claude 在每個回合中做什麼，包括它呼叫了哪些工具。

79* **即時串流：** 啟用部分訊息（Python 中的 `include_partial_messages`、TypeScript 中的 `includePartialMessages`）以實時取得 `StreamEvent` 訊息。請參閱 [即時串流回應](/zh-TW/agent-sdk/streaming-output)。83* **即時串流：** 啟用部分訊息（Python 中的 `include_partial_messages`、TypeScript 中的 `includePartialMessages`）以實時取得 `StreamEvent` 訊息。請參閱 [即時串流回應](/docs/zh-TW/agent-sdk/streaming-output)。

80 84

81您檢查訊息類型的方式取決於 SDK：85您檢查訊息類型的方式取決於 SDK：

82 86

87 <CodeGroup>91 <CodeGroup>

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

89 import asyncio93 import asyncio

~~90 from claude_agent_sdk import query, AssistantMessage, ResultMessage~~94 from claude_agent_sdk import query, AssistantMessage, ResultMessage, TextBlock, ToolUseBlock

91 95

92 96

93 async def main():97 async def main():

94 try:98 try:

95 async for message in query(prompt="Summarize this project"):99 async for message in query(prompt="Summarize this project"):

96 if isinstance(message, AssistantMessage):100 if isinstance(message, AssistantMessage):

~~97 print(f"Turn completed: {len(message.content)} content blocks")~~101 # Each AssistantMessage carries one content block

102 for block in message.content:

103 if isinstance(block, TextBlock):

104 print(f"Claude: {block.text}")

105 elif isinstance(block, ToolUseBlock):

106 print(f"Tool call: {block.name}")

98 if isinstance(message, ResultMessage):107 if isinstance(message, ResultMessage):

99 if message.subtype == "success":108 if message.subtype == "success":

100 print(message.result)109 print(message.result)

116 try {125 try {

117 for await (const message of query({ prompt: "Summarize this project" })) {126 for await (const message of query({ prompt: "Summarize this project" })) {

118 if (message.type === "assistant") {127 if (message.type === "assistant") {

119 console.log(`Turn completed: ${message.message.content.length} content blocks`);128 // Each assistant message carries one content block

129 for (const block of message.message.content) {

130 if (block.type === "text") {

131 console.log(`Claude: ${block.text}`);

132 } else if (block.type === "tool_use") {

133 console.log(`Tool call: ${block.name}`);

134 }

135 }

120 }136 }

121 if (message.type === "result") {137 if (message.type === "result") {

122 if (message.subtype === "success") {138 if (message.subtype === "success") {

157| **探索** | `ToolSearch` | 動態查找和按需加載工具，而不是預先加載所有工具 |173| **探索** | `ToolSearch` | 動態查找和按需加載工具，而不是預先加載所有工具 |

158| **協調** | `Agent`、`Skill`、`AskUserQuestion`、`TaskCreate`、`TaskUpdate` | 生成子代理程式、呼叫技能、詢問使用者、追蹤任務 |174| **協調** | `Agent`、`Skill`、`AskUserQuestion`、`TaskCreate`、`TaskUpdate` | 生成子代理程式、呼叫技能、詢問使用者、追蹤任務 |

159 175

176在[不提供任務追蹤工具的模型](/docs/zh-TW/agent-sdk/todo-tracking#model-availability)上，Claude Code 只在您選擇加入時才提供 `TaskCreate` 和 `TaskUpdate`。

177

160除了內建工具，您還可以：178除了內建工具，您還可以：

161 179

162* **使用 [MCP 伺服器](/zh-TW/agent-sdk/mcp) 連接外部服務**（資料庫、瀏覽器、API）180* **使用 [MCP 伺服器](/docs/zh-TW/agent-sdk/mcp) 連接外部服務**（資料庫、瀏覽器、API）

163* **使用 [自訂工具處理程式](/zh-TW/agent-sdk/custom-tools) 定義自訂工具**181* **使用 [自訂工具處理程式](/docs/zh-TW/agent-sdk/custom-tools) 定義自訂工具**

164* **透過 [設定來源](/zh-TW/agent-sdk/claude-code-features) 加載專案技能**以實現可重複使用的工作流程182* **透過 [設定來源](/docs/zh-TW/agent-sdk/claude-code-features) 加載專案技能**以實現可重複使用的工作流程

165 183

166<h3 id="tool-permissions">184<h3 id="tool-permissions">

167 工具權限185 工具權限

169 187

170Claude 根據任務決定呼叫哪些工具，但您控制這些呼叫是否允許執行。您可以自動批准特定工具、完全阻止其他工具，或要求對所有工具進行批准。三個選項一起工作以確定運行的內容：188Claude 根據任務決定呼叫哪些工具，但您控制這些呼叫是否允許執行。您可以自動批准特定工具、完全阻止其他工具，或要求對所有工具進行批准。三個選項一起工作以確定運行的內容：

171 189

172* **`allowed_tools` / `allowedTools`** 自動批准列出的工具。具有 `["Read", "Glob", "Grep"]` 在其允許工具清單中的唯讀代理程式會執行這些工具而不提示。未列出的工具仍然可用，但需要權限。190* **`allowed_tools` / `allowedTools`** 自動批准列出的工具。具有 `["Read", "Glob", "Grep"]` 在其允許工具清單中的唯讀代理程式會執行這些工具而不提示。未列出的工具仍然可用，對它們的呼叫需要批准會根據權限模式和 `canUseTool` 進行處理。

173* **`disallowed_tools` / `disallowedTools`** 阻止列出的工具，無論其他設定如何。請參閱 [權限](/zh-TW/agent-sdk/permissions) 以了解在工具執行前檢查規則的順序。191* **`disallowed_tools` / `disallowedTools`** 阻止列出的工具，無論其他設定如何。請參閱 [權限](/docs/zh-TW/agent-sdk/permissions) 以了解在工具執行前檢查規則的順序。

174* **`permission_mode` / `permissionMode`** 控制對不受允許或拒絕規則涵蓋的工具會發生什麼。請參閱 [權限模式](#permission-mode) 以了解可用的模式。192* **`permission_mode` / `permissionMode`** 控制您想要多少人工監督。SDK 根據固定順序評估活動模式以及您的允許和拒絕規則，詳見[權限如何被評估](/docs/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated)。請參閱[權限模式](#permission-mode)以了解可用的模式。

175 193

176您也可以使用 `"Bash(npm *)"` 之類的規則來限定個別工具，以僅允許特定命令。請參閱 [權限](/zh-TW/agent-sdk/permissions) 以了解完整的規則語法。194您也可以使用 `"Bash(npm *)"` 之類的規則來限定個別工具，以僅允許特定命令。請參閱 [權限](/docs/zh-TW/agent-sdk/permissions) 以了解完整的規則語法。

177 195

178當工具被拒絕時，Claude 會收到一條拒絕訊息作為工具結果，通常會嘗試不同的方法或報告它無法繼續。196當工具被拒絕時，Claude 會收到一條拒絕訊息作為工具結果，通常會嘗試不同的方法或報告它無法繼續。

179 197

183 201

184當 Claude 在單個回合中要求多個工具呼叫時，兩個 SDK 可以根據工具同時或順序執行它們。唯讀工具（如 `Read`、`Glob`、`Grep` 和標記為唯讀的 MCP 工具）可以同時執行。修改狀態的工具（如 `Edit`、`Write` 和 `Bash`）順序執行以避免衝突。202當 Claude 在單個回合中要求多個工具呼叫時，兩個 SDK 可以根據工具同時或順序執行它們。唯讀工具（如 `Read`、`Glob`、`Grep` 和標記為唯讀的 MCP 工具）可以同時執行。修改狀態的工具（如 `Edit`、`Write` 和 `Bash`）順序執行以避免衝突。

185 203

186自訂工具預設為順序執行。要為自訂工具啟用平行執行，請在其註釋中設定 `readOnlyHint`。[TypeScript](/zh-TW/agent-sdk/typescript#tool) 和 [Python](/zh-TW/agent-sdk/python#tool) SDK 都使用 MCP SDK 中的此欄位名稱。204自訂工具預設為順序執行。要為自訂工具啟用平行執行，請在其註釋中設定 `readOnlyHint`。[TypeScript](/docs/zh-TW/agent-sdk/typescript#tool) 和 [Python](/docs/zh-TW/agent-sdk/python#tool) SDK 都使用 MCP SDK 中的此欄位名稱。

187 205

188<h2 id="control-how-the-loop-runs">206<h2 id="control-how-the-loop-runs">

189 控制迴圈如何執行207 控制迴圈如何執行

190</h2>208</h2>

191 209

192您可以限制迴圈執行的回合數、成本、Claude 推理的深度，以及工具是否需要在執行前獲得批准。所有這些都是 [`ClaudeAgentOptions`](/zh-TW/agent-sdk/python#claudeagentoptions)（Python）/ [`Options`](/zh-TW/agent-sdk/typescript#options)（TypeScript）上的欄位。210您可以限制迴圈執行的回合數、成本、Claude 推理的深度，以及工具是否需要在執行前獲得批准。所有這些都是 [`ClaudeAgentOptions`](/docs/zh-TW/agent-sdk/python#claudeagentoptions)（Python）/ [`Options`](/docs/zh-TW/agent-sdk/typescript#options)（TypeScript）上的欄位。

193 211

194<h3 id="turns-and-budget">212<h3 id="turns-and-budget">

195 回合和預算213 回合和預算

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

201| 最大預算（`max_budget_usd` / `maxBudgetUsd`） | 停止前的最大成本 | 無限制 |219| 最大預算（`max_budget_usd` / `maxBudgetUsd`） | 停止前的最大成本 | 無限制 |

202 220

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

222

223預算上限涵蓋 [子代理程式](/docs/zh-TW/agent-sdk/subagents)：它們的支出計入總額。一旦支出達到上限，生成另一個子代理程式會失敗並顯示 `Budget limit reached`，Claude Code 會停止任何仍在執行的背景子代理程式。上限強制行為需要 Claude Code v2.1.217 或更新版本。

204 224

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

206 226

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

208 努力等級228 努力等級

211`effort` 選項控制 Claude 應用多少推理。較低的努力等級每個回合使用更少的代幣並降低成本。並非所有模型都支援努力參數。請參閱 [努力](https://platform.claude.com/docs/en/build-with-claude/effort) 以了解哪些模型支援它。231`effort` 選項控制 Claude 應用多少推理。較低的努力等級每個回合使用更少的代幣並降低成本。並非所有模型都支援努力參數。請參閱 [努力](https://platform.claude.com/docs/en/build-with-claude/effort) 以了解哪些模型支援它。

212 232

213| 等級 | 行為 | 適合 |233| 等級 | 行為 | 適合 |

214| :--------- | :-------- | :------------------------------------------- |234| :--------- | :-------- | :------------------------------------------------------------- |

215| `"low"` | 最少推理、快速回應 | 檔案查找、列出目錄 |235| `"low"` | 最少推理、快速回應 | 檔案查找、列出目錄 |

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

220 240

221如果您不設定 `effort`，兩個 SDK 都會保留參數未設定，並遵循模型的預設行為。241如果您不設定 `effort`，兩個 SDK 都會保留參數未設定，並遵循模型的預設行為。

222 242

223<Note>243<Note>

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

225</Note>245</Note>

226 246

227對於執行簡單、範圍明確的任務（如列出檔案或執行單個 grep）的代理程式，使用較低的努力來降低成本和延遲。在頂級 `query()` 選項中設定 `effort` 以用於整個工作階段，或在 [`AgentDefinition`](/zh-TW/agent-sdk/subagents#agentdefinition-configuration) 上使用 `effort` 欄位以每個子代理程式為基礎覆蓋工作階段等級。247對於執行簡單、範圍明確的任務（如列出檔案或執行單個 grep）的代理程式，使用較低的努力來降低成本和延遲。在頂級 `query()` 選項中設定 `effort` 以用於整個工作階段，或在 [`AgentDefinition`](/docs/zh-TW/agent-sdk/subagents#agentdefinition-configuration) 上使用 `effort` 欄位以每個子代理程式為基礎覆蓋工作階段等級。

228 248

229<h3 id="permission-mode">249<h3 id="permission-mode">

230 權限模式250 權限模式

232 252

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

234 254

235| 模式 | 行為 |255| 模式 | 行為 | 使用案例 |

236| :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |256| :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------- |

240| `"dontAsk"` | 永不提示。由 [權限規則](/zh-TW/settings#permission-settings) 預先批准的工具執行；其他所有工具都被拒絕。`AskUserQuestion`、連接器工具 [您的組織設定為 `ask`](/zh-TW/mcp#organization-controls-on-connector-tools) 和標記為 [`requiresUserInteraction`](/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具即使您已允許它們也會被拒絕 |260| `"dontAsk"` | 永不提示。由 [權限規則](/docs/zh-TW/settings-reference#permission-settings) 預先批准的工具執行，以及在 `default` 模式中不需要批准的呼叫（例如在您的工作目錄內的檔案讀取）；所有其他會提示的呼叫都被拒絕。`AskUserQuestion`、連接器工具 [您的組織設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools) 和標記為 [`requiresUserInteraction`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具即使您已允許它們也會被拒絕 | 您想要為無頭代理程式提供固定、明確的工具表面，並偏好硬拒絕而不是無聲依賴 `canUseTool` 不存在 |

242| `"bypassPermissions"` | 執行所有允許的工具而不詢問，除了由明確的 [`ask` 規則](/zh-TW/settings#permission-settings) 符合的工具、連接器工具 [您的組織設定為 `ask`](/zh-TW/mcp#organization-controls-on-connector-tools) 和需要使用者互動的工具；請參閱 [權限如何被評估](/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated) 以了解優先順序順序。在 Unix 上以 root 身份執行時無法使用。僅在隔離環境中使用，其中代理程式的操作無法影響您關心的系統 |262| `"bypassPermissions"` | 執行所有允許的工具而不詢問，除了由明確的 [`ask` 規則](/docs/zh-TW/settings-reference#permission-settings) 符合的工具、連接器工具 [您的組織設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools) 和需要使用者互動的工具。[跨工作階段訊息安全防護](/docs/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode) 仍然適用。請參閱 [權限如何被評估](/docs/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated) 以了解優先順序順序。在 TypeScript SDK 中，也需要在 `options` 中設定 `allowDangerouslySkipPermissions: true`。在 Unix 上以 root 身份執行時無法使用。僅在隔離環境中使用，其中代理程式的操作無法影響您關心的系統 | CI、容器或其他隔離環境 |

243 263

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

245 265

246<h3 id="model">266<h3 id="model">

247 模型267 模型

253 上下文視窗273 上下文視窗

254</h2>274</h2>

255 275

256上下文視窗是工作階段期間可用於 Claude 的資訊總量。它不會在工作階段內的回合之間重置。所有內容都會累積：系統提示、工具定義、對話歷史記錄、工具輸入和工具輸出。在回合之間保持相同的內容（系統提示、工具定義、CLAUDE.md）會自動進行 [提示快取](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-caching)，這會減少重複前綴的成本和延遲。276上下文視窗是工作階段期間可用於 Claude 的資訊總量。它不會在工作階段內的回合之間重置。所有內容都會累積：系統提示、工具定義、對話歷史記錄、工具輸入和工具輸出。在回合之間保持相同的內容（系統提示、工具定義、CLAUDE.md）會自動進行 [提示快取](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-caching)，這會減少重複前綴的成本和延遲。如需了解自訂系統提示或 `append` 文字如何影響跨工作階段的快取重複使用，請參閱 [修改系統提示](/docs/zh-TW/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines)。

257 277

258<h3 id="what-consumes-context">278<h3 id="what-consumes-context">

259 什麼消耗上下文279 什麼消耗上下文

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

263 283

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

265| :--------------- | :------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |285| :--------------- | :------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

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) 以了解完整矩陣 |288| **工具定義** | 每個請求；MCP 架構預設延遲 | 內建工具架構在每個請求時加載。[工具搜尋](/docs/zh-TW/agent-sdk/mcp#mcp-tool-search) 預設延遲 MCP 工具架構，在不支援的模型和某些平台上回退到預先加載。請參閱 [配置工具搜尋](/docs/zh-TW/agent-sdk/tool-search#configure-tool-search) 以了解完整矩陣 |

271 291

277 297

278當上下文視窗接近其限制時，SDK 會自動壓縮對話：它總結較舊的歷史記錄以釋放空間，保持您最近的交換和關鍵決定完整。SDK 在串流中發出一個 `type: "system"` 和 `subtype: "compact_boundary"` 的訊息（在 Python 中這是一個 `SystemMessage`；在 TypeScript 中它是一個單獨的 `SDKCompactBoundaryMessage` 類型）。298當上下文視窗接近其限制時，SDK 會自動壓縮對話：它總結較舊的歷史記錄以釋放空間，保持您最近的交換和關鍵決定完整。SDK 在串流中發出一個 `type: "system"` 和 `subtype: "compact_boundary"` 的訊息（在 Python 中這是一個 `SystemMessage`；在 TypeScript 中它是一個單獨的 `SDKCompactBoundaryMessage` 類型）。

279 299

280壓縮用摘要替換較舊的訊息，因此對話早期的特定指示可能不會被保留。持久規則應該在 CLAUDE.md 中（透過 [`settingSources`](/zh-TW/agent-sdk/claude-code-features) 加載），而不是在初始提示中，因為 CLAUDE.md 內容在每個請求時重新注入。300壓縮用摘要替換較舊的訊息，因此對話早期的特定指示可能不會被保留。持久規則應該在 CLAUDE.md 中（透過 [`settingSources`](/docs/zh-TW/agent-sdk/claude-code-features) 加載），而不是在初始提示中，因為 CLAUDE.md 內容在每個請求時重新注入。

281 301

282您可以透過多種方式自訂壓縮行為：302您可以透過多種方式自訂壓縮行為：

283 303

284* **CLAUDE.md 中的摘要指示：** 壓縮器像任何其他上下文一樣讀取您的 CLAUDE.md，因此您可以包含一個部分，告訴它在摘要時要保留什麼。部分標題是自由格式的（不是魔法字串）；壓縮器根據意圖匹配。304* **CLAUDE.md 中的摘要指示：** 壓縮器像任何其他上下文一樣讀取您的 CLAUDE.md，因此您可以包含一個部分，告訴它在摘要時要保留什麼。壓縮器根據意圖匹配，因此部分標題是自由格式的。

285* **`PreCompact` hook：** 在壓縮發生前執行自訂邏輯，例如存檔完整成績單。hook 接收一個 `trigger` 欄位（`manual` 或 `auto`）。請參閱 [hooks](/zh-TW/agent-sdk/hooks)。305* **`PreCompact` hook：** 在壓縮發生前執行自訂邏輯，例如存檔完整成績單。hook 接收一個 `trigger` 欄位（`manual` 或 `auto`）。請參閱 [hooks](/docs/zh-TW/agent-sdk/hooks)。

286* **手動壓縮：** 將 `/compact` 作為提示字串發送以按需觸發壓縮。以這種方式發送的命令是 SDK 輸入，而不是僅限 CLI 的快捷方式。請參閱 [SDK 中的命令](/zh-TW/agent-sdk/slash-commands)。306* **手動壓縮：** 將 `/compact` 作為提示字串發送以按需觸發壓縮。以這種方式發送的命令是普通的 SDK 輸入。請參閱 [按名稱分派命令](/docs/zh-TW/agent-sdk/skills#dispatch-commands-by-name)。

287 307

288<Accordion title="範例：CLAUDE.md 中的摘要指示">308<Accordion title="範例：CLAUDE.md 中的摘要指示">

289 將一個部分添加到您的專案的 CLAUDE.md，告訴壓縮器要保留什麼。標題名稱不是特殊的；使用任何清晰的標籤。309 將一個部分添加到您的專案的 CLAUDE.md，告訴壓縮器要保留什麼。標題名稱不是特殊的；使用任何清晰的標籤。

305 325

306長時間執行代理程式的幾個策略：326長時間執行代理程式的幾個策略：

307 327

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

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

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

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

312 332

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

314 334

315<h2 id="sessions-and-continuity">335<h2 id="sessions-and-continuity">

316 工作階段和連續性336 工作階段和連續性

320 340

321當您恢復時，先前回合的完整上下文會被恢復：讀取的檔案、執行的分析和採取的操作。您也可以分叉一個工作階段以分支到不同的方法，而不修改原始工作階段。341當您恢復時，先前回合的完整上下文會被恢復：讀取的檔案、執行的分析和採取的操作。您也可以分叉一個工作階段以分支到不同的方法，而不修改原始工作階段。

322 342

323請參閱 [工作階段管理](/zh-TW/agent-sdk/sessions) 以了解恢復、繼續和分叉模式的完整指南。343請參閱 [工作階段管理](/docs/zh-TW/agent-sdk/sessions) 以了解恢復、繼續和分叉模式的完整指南。若要在無狀態容器或無伺服器主機之間恢復工作階段，請傳遞 [`session_store` / `sessionStore` 配接器](/docs/zh-TW/agent-sdk/session-storage)，以便 SDK 將文字記錄鏡像到您自己的後端，另一個主機可以恢復它們。Claude Code 子程序仍然首先寫入本機磁碟。請參閱 [雙寫入架構](/docs/zh-TW/agent-sdk/session-storage#dual-write-architecture) 以了解哪個副本在新工作階段與從存放區恢復的執行中存活，以及如何保持本機副本為暫時性。

324 344

325<Note>345<Note>

326 在 Python 中，`ClaudeSDKClient` 在多個呼叫中自動處理工作階段 ID。請參閱 [Python SDK 參考](/zh-TW/agent-sdk/python#choosing-between-query-and-claudesdkclient) 以了解詳細資訊。346 在 Python 中，`ClaudeSDKClient` 在多個呼叫中自動處理工作階段 ID。請參閱 [Python SDK 參考](/docs/zh-TW/agent-sdk/python#choosing-between-query-and-claudesdkclient) 以了解詳細資訊。

327</Note>347</Note>

328 348

329<h2 id="handle-the-result">349<h2 id="handle-the-result">

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

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

342 362

343`result` 欄位（最終文字輸出）僅在 `success` 變體上存在，因此在讀取它之前始終檢查子類型。所有結果子類型都帶有 `total_cost_usd`、`usage`、`num_turns` 和 `session_id`，因此您可以追蹤成本並在錯誤後恢復。在 Python 中，`total_cost_usd` 和 `usage` 被類型化為可選的，在某些錯誤路徑上可能是 `None`，因此在格式化它們之前進行保護。請參閱 [追蹤成本和使用量](/zh-TW/agent-sdk/cost-tracking) 以了解有關解釋 `usage` 欄位的詳細資訊。363`result` 欄位保存最終文字輸出，僅在 `success` 變體上存在，因此在讀取它之前始終檢查子類型。

364

365所有結果子類型都帶有 `total_cost_usd`、`usage`、`num_turns` 和 `session_id`，因此您可以追蹤成本並在錯誤後恢復。有兩件事需要防範：

366

367* 在工作階段當機後，最終結果是 `error_during_execution`，其成本欄位可能被清零，其 `stop_reason` 為 `null`，程序在發出它後退出。請參閱 [在工作階段當機後復原總計](/docs/zh-TW/agent-sdk/cost-tracking#recover-totals-after-a-session-crash)。

368* 在 Python 中，`total_cost_usd`、`usage` 和 `model_usage` 被類型化為可選的，因此在讀取它們之前檢查它們不是 `None`。

369

370`usage` 欄位僅涵蓋主要代理迴圈。使用 `modelUsage` 或 Python 中的 `model_usage` 進行整個樹的代幣和成本計算。請參閱 [追蹤成本和使用量](/docs/zh-TW/agent-sdk/cost-tracking) 以了解有關解釋 `usage` 欄位的詳細資訊。

344 371

345<Note>372<Note>

346 當查詢以錯誤結果結束時：373 當查詢以錯誤結果結束時：

347 374

348 * 單次 `query()` 呼叫會產生最終結果訊息，然後引發包含失敗文字的錯誤，例如 `Reached maximum number of turns`。引發是有意的 — 如果您的程式碼需要在其後繼續，請將迴圈包裝在 try 區塊中。底層 Claude Code 程序也會以非零代碼退出。375 * 單次 `query()` 呼叫會產生最終結果訊息，然後引發包含失敗文字的錯誤，例如 `Reached maximum number of turns`。引發是有意的。如果您的程式碼需要在其後繼續，請將迴圈包裝在 try 區塊中。底層 Claude Code 程序也會以非零代碼退出。

349 * 串流輸入工作階段保持活躍，您可以繼續傳送訊息。376 * 串流輸入工作階段保持活躍，您可以繼續傳送訊息，除了在工作階段當機後，它會發出最終 `error_during_execution` 結果並退出程序。

350</Note>377</Note>

351 378

352結果還包括一個 `stop_reason` 欄位（TypeScript 中的 `string | null`、Python 中的 `str | None`），指示模型為什麼在最後一個回合停止生成。常見值是 `end_turn`（模型正常完成）、`max_tokens`（達到輸出代幣限制）和 `refusal`（模型拒絕了請求）。在錯誤結果子類型上，`stop_reason` 帶有迴圈結束前最後一個助手回應的值。要檢測拒絕，請檢查 `stop_reason === "refusal"`（TypeScript）或 `stop_reason == "refusal"`（Python）。請參閱 [`SDKResultMessage`](/zh-TW/agent-sdk/typescript#sdkresultmessage)（TypeScript）或 [`ResultMessage`](/zh-TW/agent-sdk/python#resultmessage)（Python）以了解完整類型。379結果還包括一個 `stop_reason` 欄位（TypeScript 中的 `string | null`、Python 中的 `str | None`），指示模型為什麼在最後一個回合停止生成。常見值是 `end_turn`（模型正常完成）、`max_tokens`（達到輸出代幣限制）和 `refusal`（模型拒絕了請求）。在迴圈產生的錯誤結果上，`stop_reason` 帶有迴圈結束前最後一個助手回應的值；工作階段當機後 Claude Code 合成的結果帶有 `null`。

380

381要檢測拒絕，請檢查 `stop_reason === "refusal"`（TypeScript）或 `stop_reason == "refusal"`（Python）。請參閱 [`SDKResultMessage`](/docs/zh-TW/agent-sdk/typescript#sdkresultmessage)（TypeScript）或 [`ResultMessage`](/docs/zh-TW/agent-sdk/python#resultmessage)（Python）以了解完整類型。

353 382

354<h2 id="hooks">383<h2 id="hooks">

355 Hooks384 Hooks

356</h2>385</h2>

357 386

358[Hooks](/zh-TW/agent-sdk/hooks) 是在迴圈中的特定點觸發的回呼：在工具執行前、執行後、代理程式完成時等。一些常用的 hooks 是：387[Hooks](/docs/zh-TW/agent-sdk/hooks) 是在迴圈中的特定點觸發的回呼：在工具執行前、執行後、代理程式完成時等。一些常用的 hooks 是：

359 388

361| :------------------------------- | :----------- | :------------ |390| :------------------------------- | :----------- | :------------ |

368 397

369Hooks 在您的應用程式進程中執行，而不是在代理程式的上下文視窗內，因此它們不消耗上下文。Hooks 也可以短路迴圈：拒絕工具呼叫的 `PreToolUse` hook 會阻止它執行，Claude 會收到拒絕訊息。398Hooks 在您的應用程式進程中執行，而不是在代理程式的上下文視窗內，因此它們不消耗上下文。Hooks 也可以短路迴圈：拒絕工具呼叫的 `PreToolUse` hook 會阻止它執行，Claude 會收到拒絕訊息。

370 399

371兩個 SDK 都支援上述所有事件。TypeScript SDK 包含 Python 尚不支援的額外事件。請參閱 [使用 hooks 控制執行](/zh-TW/agent-sdk/hooks) 以了解完整的事件清單、每個 SDK 的可用性和完整的回呼 API。400兩個 SDK 都支援上述所有事件。TypeScript SDK 包含 Python 尚不支援的額外事件。請參閱 [使用 hooks 控制執行](/docs/zh-TW/agent-sdk/hooks) 以了解完整的事件清單、每個 SDK 的可用性和完整的回呼 API。

372 401

373<h2 id="put-it-all-together">402<h2 id="put-it-all-together">

374 將其全部整合在一起403 將其全部整合在一起

474 ```503 ```

475</CodeGroup>504</CodeGroup>

476 505

506當代理程式成功完成時，此範例會列印一行 `Done:` 及代理程式對修復的摘要，然後列印一行類似 `Cost: $0.0312` 的內容。

507

477<h2 id="next-steps">508<h2 id="next-steps">

478 後續步驟509 後續步驟

479</h2>510</h2>

480 511

481現在您了解了迴圈，以下是根據您正在建立的內容去往何處：512現在您了解了迴圈，以下是根據您正在建立的內容去往何處：

482 513

483* **還沒有執行代理程式？** 從 [快速入門](/zh-TW/agent-sdk/quickstart) 開始，以安裝 SDK 並查看完整範例端到端執行。514* **還沒有執行代理程式？** 從 [快速入門](/docs/zh-TW/agent-sdk/quickstart) 開始，以安裝 SDK 並查看完整範例端到端執行。

484* **準備好連接到您的專案？** [加載 CLAUDE.md、技能和檔案系統 hooks](/zh-TW/agent-sdk/claude-code-features)，以便代理程式自動遵循您的專案約定。515* **準備好連接到您的專案？** [加載 CLAUDE.md、技能和檔案系統 hooks](/docs/zh-TW/agent-sdk/claude-code-features)，以便代理程式自動遵循您的專案約定。

485* **建立互動式 UI？** 啟用 [串流](/zh-TW/agent-sdk/streaming-output) 以在迴圈執行時顯示即時文字和工具呼叫。516* **建立互動式 UI？** 啟用 [串流](/docs/zh-TW/agent-sdk/streaming-output) 以在迴圈執行時顯示即時文字和工具呼叫。

486* **需要對代理程式可以做什麼進行更嚴格的控制？** 使用 [權限](/zh-TW/agent-sdk/permissions) 鎖定工具存取，並使用 [hooks](/zh-TW/agent-sdk/hooks) 在工具執行前審計、阻止或轉換工具呼叫。517* **需要對代理程式可以做什麼進行更嚴格的控制？** 使用 [權限](/docs/zh-TW/agent-sdk/permissions) 鎖定工具存取，並使用 [hooks](/docs/zh-TW/agent-sdk/hooks) 在工具執行前審計、阻止或轉換工具呼叫。

487* **執行長期或昂貴的任務？** 將隔離的工作卸載到 [子代理程式](/zh-TW/agent-sdk/subagents) 以保持主上下文精簡。518* **執行長期或昂貴的任務？** 將隔離的工作卸載到 [子代理程式](/docs/zh-TW/agent-sdk/subagents) 以保持主上下文精簡。

519* **部署為服務？** 請參閱 [託管 Agent SDK](/docs/zh-TW/agent-sdk/hosting) 以取得容器和無伺服器指導，以及 [工作階段儲存](/docs/zh-TW/agent-sdk/session-storage) 以將工作階段保存到您自己的後端。

488 520

489有關代理程式迴圈的更廣泛概念圖片（不是 SDK 特定的），請參閱 [Claude Code 如何運作](/zh-TW/how-claude-code-works)。如需在 Claude Code 中設計迴圈的實用指南，從輪流制到目標導向和主動迴圈，請參閱部落格上的 [Loop engineering: getting started with loops](https://claude.com/blog/getting-started-with-loops)。521有關代理程式迴圈的更廣泛概念圖片（不是 SDK 特定的），請參閱 [Claude Code 如何運作](/docs/zh-TW/how-claude-code-works)。如需在 Claude Code 中設計迴圈的實用指南，從輪流制到目標導向和主動迴圈，請參閱部落格上的 [Loop engineering: getting started with loops](https://claude.com/blog/getting-started-with-loops)。

agent-sdk/examples.md +33 −0 created

Details

1> ## Documentation Index

2> 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.

5# 範例

7> 尋找完整、可執行的 Agent SDK 專案或 Claude Cookbook 中的引導式配方，以符合您想要建置的內容。

9此頁面會引導您前往完整、可執行的 Agent SDK 專案和引導式 Claude Cookbook 配方。TypeScript 應用程式位於 [`claude-agent-sdk-demos`](https://github.com/anthropics/claude-agent-sdk-demos) 儲存庫中，Python 配方位於 [Claude Cookbook](https://platform.claude.com/cookbook) 中。

11<h2 id="run-a-minimal-agent-first">

12 先執行最小化代理

13</h2>

15如果您還沒有使用 SDK 建置任何東西，請在完整應用程式之前從以下其中一個開始：

17* [Agent SDK 快速入門](/docs/zh-TW/agent-sdk/quickstart)：在 TypeScript 或 Python 中建置您的第一個可運作的代理，包括設定步驟。代理會在範例檔案中尋找並修復錯誤。

19* [Hello World](https://github.com/anthropics/claude-agent-sdk-demos/tree/main/hello-world)：當您想從儲存庫程式碼開始時要複製的最小化 TypeScript 專案

21<h2 id="explore-a-typescript-application">

22 探索 TypeScript 應用程式

23</h2>

25[`claude-agent-sdk-demos`](https://github.com/anthropics/claude-agent-sdk-demos) 中的 TypeScript 應用程式是本機開發的示範，從電子郵件用戶端到多代理研究系統。複製其形狀與您正在建置的內容相符的示範。

27<h2 id="work-through-a-python-recipe">

28 進行 Python 配方

29</h2>

31Claude Cookbook 的 Agent SDK 系列是一系列配方，每個配方都是 Python 筆記本，從簡單的研究代理進展到複雜的多代理系統。每個筆記本都以前一個為基礎，引入新的概念和功能。從[單行研究代理](https://platform.claude.com/cookbook/claude-agent-sdk-00-the-one-liner-research-agent)開始並向前進行。

33如需跨 Claude 產品的配方，請參閱完整的 [Claude Cookbook](https://platform.claude.com/cookbook)。

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

Details

393 393

394預設情況下，Claude Code 在會話的第一個請求時建立系統提示詞一次，包含您的 `append` 文字或自訂提示詞，並將其記錄在會話中。在會話被壓縮之前，每個稍後的請求都使用該記錄的提示詞，包括在您使用 `resume` 或 `continue` 返回會話後。如果您在稍後的呼叫上傳遞不同的 `append` 或自訂提示詞，它在會話被壓縮或在新會話中時生效。394預設情況下，Claude Code 在會話的第一個請求時建立系統提示詞一次，包含您的 `append` 文字或自訂提示詞，並將其記錄在會話中。在會話被壓縮之前，每個稍後的請求都使用該記錄的提示詞，包括在您使用 `resume` 或 `continue` 返回會話後。如果您在稍後的呼叫上傳遞不同的 `append` 或自訂提示詞，它在會話被壓縮或在新會話中時生效。

395 395

396記錄適用於 [擷取功能旗標](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching) 的會話，如使用 claude.ai 或 Console 帳戶的會話預設執行的那樣。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和其他不擷取它們的會話中，Claude Code 在每個請求上重建提示詞。如果您通過傳遞 `--bare` 通過 `extraArgs` 或設定 `CLAUDE_CODE_SIMPLE=1` 在 [裸模式](/docs/zh-TW/headless#start-faster-with-bare-mode) 中啟動 Claude Code，記錄保持關閉，除非您在 `systemPrompt` 的物件形式上設定 `snapshot: true`。預設情況下記錄 `append` 或自訂提示詞需要 Claude Code v2.1.265 或更新版本，TypeScript Agent SDK 從 v0.3.265 開始捆綁。396如果您通過傳遞 `--bare` 通過 `extraArgs` 或設定 `CLAUDE_CODE_SIMPLE=1` 在 [裸模式](/docs/zh-TW/headless#start-faster-with-bare-mode) 中啟動 Claude Code，記錄保持關閉，除非您在 `systemPrompt` 的物件形式上設定 `snapshot: true`。預設情況下記錄 `append` 或自訂提示詞需要 Claude Code v2.1.265 或更新版本，TypeScript Agent SDK 從 v0.3.265 開始捆綁。在 Claude Code v2.1.268 之前，不 [擷取功能旗標](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching) 的會話，包括 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上的會話，在每個請求上重建提示詞，`snapshot` 無效。

397 397

398要改為在每個請求上重建提示詞，請在 TypeScript SDK 中的 `systemPrompt` 的物件形式上設定 `snapshot: false`：`{ type: "preset", preset: "claude_code", append, snapshot: false }` 或 `{ type: "custom", prompt, snapshot: false }`。在您迭代提示詞措辭時或當您的應用程式在恢復相同會話的呼叫之間變更 `append` 時，請使用此形式。`snapshot` 欄位需要 `@anthropic-ai/claude-agent-sdk` v0.3.257 或更新版本，在不擷取功能旗標的會話中無效。398要改為在每個請求上重建提示詞，請在 TypeScript SDK 中的 `systemPrompt` 的物件形式上設定 `snapshot: false`：`{ type: "preset", preset: "claude_code", append, snapshot: false }` 或 `{ type: "custom", prompt, snapshot: false }`。在您迭代提示詞措辭時或當您的應用程式在恢復相同會話的呼叫之間變更 `append` 時，請使用此形式。`snapshot` 欄位需要 `@anthropic-ai/claude-agent-sdk` v0.3.257 或更新版本。

399 399

400<h2 id="compare-the-four-approaches">400<h2 id="compare-the-four-approaches">

401 比較四種方法401 比較四種方法

agent-sdk/permissions.md +11 −9

Details

41 </Step>41 </Step>

42 42

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

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

45 </Step>45 </Step>

46 46

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

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

74</h2>74</h2>

75 75

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

77 77

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

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

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

91<Warning>91<Warning>

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

93 93

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

95</Warning>95</Warning>

96 96

97對於鎖定的代理程式，將 `allowedTools` 與 `permissionMode: "dontAsk"` 配對。列出的工具會被批准，除了上述警告中的始終提示工具外；其他任何工具都會被直接拒絕，而不是提示：97對於鎖定的代理程式，將 `allowedTools` 與 `permissionMode: "dontAsk"` 配對：

98 98

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

100const options = {100const options = {

103};103};

104```104```

105 105

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

107

106<Warning>108<Warning>

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

108</Warning>110</Warning>

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

123 125

124| 模式 | 描述 | 工具行為 |126| 模式 | 描述 | 工具行為 |

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

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

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

272</h4>274</h4>

273 275

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

275 277

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

277 279

agent-sdk/python.md +0 −2

Details

3164**Tool 名稱：** `TodoWrite`3164**Tool 名稱：** `TodoWrite`

3165 3165

3166<Note>3166<Note>

3167 在 Python Agent SDK 0.2.139 及更新版本上，以下限制適用。

~~3168~~

3169 The following tools are available by default only on Claude 3.x models, Opus 4 through 4.7, Sonnet 4 through 4.6, and Haiku 4.5. On every other model, including model IDs Claude Code doesn't recognize, they aren't available unless you opt in:3167 The following tools are available by default only on Claude 3.x models, Opus 4 through 4.7, Sonnet 4 through 4.6, and Haiku 4.5. On every other model, including model IDs Claude Code doesn't recognize, they aren't available unless you opt in:

3170 3168

3171 * `TodoWrite`3169 * `TodoWrite`

agent-sdk/todo-tracking.md +2 −4

Details

6 6

7> 在 Agent SDK 工作階段中追蹤待辦事項，並從結構化工具呼叫在應用程式中呈現 Claude 的進度7> 在 Agent SDK 工作階段中追蹤待辦事項，並從結構化工具呼叫在應用程式中呈現 Claude 的進度

8 8

9在[模型可用性](#model-availability)下列出的模型上，Claude 無需書面待辦事項清單即可追蹤多步驟工作，而 Claude Code 預設會將[任務追蹤工具](/docs/zh-TW/tools-reference#task-tool-availability)排除在工作階段之外。您不需要本頁面上的任何內容，Claude 就能在這些模型上完成多步驟任務。9Claude Code 預設只在[模型可用性](#model-availability)下列出的模型上提供[任務追蹤工具](/docs/zh-TW/tools-reference#task-tool-availability)。較新的模型可以在沒有書面待辦事項清單的情況下追蹤多步驟工作，因此在這些模型上，您不需要本頁面上的任何內容，Claude 就能完成多步驟任務。

10 10

11在具有任務追蹤工具的工作階段中，Claude 保持書面待辦事項清單，在工作時更新每個項目的狀態。您在訊息流中看到每個變更都是結構化工具呼叫。僅當您的應用程式讀取這些工具呼叫時才選擇加入工作階段，無論是記錄任務活動還是呈現自己的進度顯示。11在具有任務追蹤工具的工作階段中，Claude 保持書面待辦事項清單，在工作時更新每個項目的狀態。您在訊息流中看到每個變更都是結構化工具呼叫。僅當您的應用程式讀取這些工具呼叫時才選擇加入工作階段，無論是記錄任務活動還是呈現自己的進度顯示。

12 12

15</h2>15</h2>

16 16

17<Note>17<Note>

~~18 在 TypeScript Agent SDK 0.3.233 及更新版本或 Python Agent SDK 0.2.139 及更新版本上，以下限制適用。~~

20 The following tools are available by default only on Claude 3.x models, Opus 4 through 4.7, Sonnet 4 through 4.6, and Haiku 4.5. On every other model, including model IDs Claude Code doesn't recognize, they aren't available unless you opt in:18 The following tools are available by default only on Claude 3.x models, Opus 4 through 4.7, Sonnet 4 through 4.6, and Haiku 4.5. On every other model, including model IDs Claude Code doesn't recognize, they aren't available unless you opt in:

21 19

22 * `TodoWrite`20 * `TodoWrite`

30 This default set applies in Claude Code v2.1.268 and later, which the TypeScript Agent SDK bundles from v0.3.268.28 This default set applies in Claude Code v2.1.268 and later, which the TypeScript Agent SDK bundles from v0.3.268.

31</Note>29</Note>

32 30

33在列出的模型上，除非您選擇加入工作階段，否則您在訊息流中看不到這些工具的 `tool_use` 區塊。Agent SDK 通過它捆綁的 Claude Code 二進位檔案應用這些預設值。如果您將 `pathToClaudeCodeExecutable`（TypeScript）或 `cli_path`（Python）指向您自己的 Claude Code 安裝，您將獲得該安裝提供的任何工具，在其自己的預設值下。要查看執行中工作階段中的確切集合，請[檢查哪些工具可用](/docs/zh-TW/tools-reference#check-which-tools-are-available)。要選擇加入工作階段，請執行以下操作之一：31在預設情況下沒有工具的模型上，除非您選擇加入工作階段，否則您在訊息流中看不到這些工具的 `tool_use` 區塊。Agent SDK 通過它捆綁的 Claude Code 二進位檔案應用這些預設值。如果您將 `pathToClaudeCodeExecutable`（TypeScript）或 `cli_path`（Python）指向您自己的 Claude Code 安裝，您將獲得該安裝提供的任何工具，在其自己的預設值下。要查看執行中工作階段中的確切集合，請[檢查哪些工具可用](/docs/zh-TW/tools-reference#check-which-tools-are-available)。要選擇加入工作階段，請執行以下操作之一：

34 32

35* 在 [`allowedTools`](/docs/zh-TW/agent-sdk/permissions#allow-and-deny-rules)（TypeScript）或 `allowed_tools`（Python）選項中命名其中一個工具33* 在 [`allowedTools`](/docs/zh-TW/agent-sdk/permissions#allow-and-deny-rules)（TypeScript）或 `allowed_tools`（Python）選項中命名其中一個工具

36* 在 `tools` 選項中列出工具，這會將工作階段的內置工具限制為它命名的工具。將您想要的工具與您使用的其他內置工具一起包含34* 在 `tools` 選項中列出工具，這會將工作階段的內置工具限制為它命名的工具。將您想要的工具與您使用的其他內置工具一起包含

agent-sdk/troubleshooting.md +161 −0 created

Details

1> ## Documentation Index

2> 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.

5# 排除 Agent SDK 的故障

7> 根據您看到的確切錯誤訊息修復 Agent SDK 錯誤，包括 TypeScript 和 Python SDK 中每個錯誤的原因和修復方法。

9此頁面上的項目按您看到的錯誤進行分類。每個項目都說明原因和解決方法。

11<h2 id="cli-startup">

12 CLI 啟動

13</h2>

15<h3 id="clinotfounderror-claude-code-not-found">

16 CLINotFoundError: Claude Code not found

17</h3>

19Python SDK 將 Claude Code CLI 作為子程序啟動。當它找不到 `claude` 可執行檔時，連線會失敗並出現 `CLINotFoundError`：

21```

22Claude Code not found at: /your/configured/path

23```

25當您設定 `ClaudeAgentOptions(cli_path=...)` 且它指向遺失的檔案時，訊息會包含設定的路徑。沒有 `cli_path` 時，SDK 會搜尋您的 `PATH` 和常見安裝位置，訊息會包含您平台的安裝說明。

27若要修復：

29* 如果尚未安裝 Claude Code，請安裝。請參閱[安裝 Claude Code](/docs/zh-TW/setup#install-claude-code)以取得您平台上的命令。

30* 如果您設定了 `cli_path`，請確認檔案存在且是 `claude` 可執行檔。

31* 如果您依賴 `PATH` 解析，請確認 `claude --version` 在您的應用程式執行的相同環境中有效。您在 shell 外啟動的程序（例如從 IDE 或服務管理員），通常會以不同的 `PATH` 執行。

33TypeScript SDK 在其捆綁的平台套件和您在 `pathToClaudeCodeExecutable` 中設定的路徑中尋找 CLI。符合您看到的訊息：

35* `Native CLI binary for <platform>-<arch> not found`：捆綁的平台套件遺失，最常見的原因是安裝跳過了可選依賴項。重新安裝 `@anthropic-ai/claude-agent-sdk` 而不跳過可選依賴項，或將 `pathToClaudeCodeExecutable` 指向[原生安裝](/docs/zh-TW/setup#install-claude-code)。在使用 `bun build --compile` 建立的單一檔案可執行檔中，相同的訊息有不同的原因和修復。請參閱[編譯為單一可執行檔](/docs/zh-TW/agent-sdk/typescript#compile-to-a-single-executable)。

36* `Claude Code native binary not found at <path>` 或 `Claude Code executable not found at <path>. Is options.pathToClaudeCodeExecutable set?`：已解析路徑上的檔案遺失，或程序無法存取它。確認檔案存在於該路徑且程序可以存取它。

38<h3 id="cliconnectionerror-refusing-to-execute-batch-script">

39 CLIConnectionError: Refusing to execute batch script

40</h3>

42在 Windows 上，當 Python SDK 使用的 CLI 路徑是 `.bat` 或 `.cmd` 批次指令碼（包括 npm 安裝建立的 `claude.cmd` 填充程式）時，連線會失敗並出現 `CLIConnectionError`：

44```

45Refusing to execute batch script 'C:\\Users\\you\\AppData\\Roaming\\npm\\claude.cmd': Windows runs .bat/.cmd files via cmd.exe, which can execute commands injected through CLI arguments, and no reliable escaping for cmd.exe exists. Use a native claude executable instead: install Claude Code natively (irm https://claude.ai/install.ps1 | iex), point ClaudeAgentOptions(cli_path=...) at a claude.exe, or install the claude-agent-sdk wheel for a platform that bundles claude.exe (e.g. Windows x64).

46```

48拒絕是刻意的安全強化，不是破損的安裝。Windows 通過將生成重寫為 `cmd.exe /c` 呼叫來執行批次指令碼，而 `cmd.exe` 在執行時重新解析整個命令列，因此引數值可以執行注入的命令。

50大多數 Windows 安裝永遠不會達到此錯誤。`claude-agent-sdk` 的 Windows x64 wheel 捆綁了 `claude.exe`，SDK 優先使用捆綁的 CLI，然後是它可以發現的任何原生 `claude.exe`，最後才回退到批次填充程式。您在兩種情況下會看到拒絕：

52* 您將 `ClaudeAgentOptions(cli_path=...)` 設定為 `.bat` 或 `.cmd` 檔案，例如 npm 的 `claude.cmd` 填充程式。

53* 您的安裝沒有捆綁或原生 `claude.exe`，例如 ARM64 Windows 上的原始碼安裝，其中您的 `PATH` 上唯一的 `claude` 是 npm 填充程式。

55若要修復，請給 SDK 一個原生可執行檔而不是批次指令碼：

57* 如果您設定了 `ClaudeAgentOptions(cli_path=...)`，請將其指向 `claude.exe` 或移除該選項。當設定了 `cli_path` 時，SDK 會跳過發現，因此單獨的原生安裝無法生效。

58* 在 PowerShell 中原生安裝 Claude Code：`irm https://claude.ai/install.ps1 | iex`

59* 在 x64 Windows 上，安裝捆綁 `claude.exe` 的 `claude-agent-sdk` wheel。

61在 `claude-agent-sdk` 0.2.124 之前，Python SDK 通過 `cmd.exe` 生成批次指令碼而沒有此檢查。

63<h3 id="cliconnectionerror-failed-to-start-claude-code">

64 CLIConnectionError: Failed to start Claude Code

65</h3>

67SDK 在已解析的路徑上找到了檔案，但無法啟動它。Python 將這些失敗作為 `CLIConnectionError` 引發。TypeScript 以不帶 SDK 類別的錯誤拒絕訊息迭代。下表將每個訊息對應到它告訴您的內容。符合您看到的訊息：

69| 訊息 | SDK | 它告訴您什麼 |

70| ----------------------------------------------------------------- | ---------- | ----------------------- |

71| `Failed to start Claude Code: <detail>` | Python | 訊息的其餘部分是作業系統本身的錯誤 |

72| `Claude Code executable at <path> exists but failed to launch` | TypeScript | 設定路徑上的指令碼無法執行 |

73| `Claude Code native binary at <path> exists but failed to launch` | TypeScript | 二進位檔案無法執行，訊息附加了 libc 建議 |

74| `Failed to spawn Claude Code process: <detail>` | TypeScript | 任何其他啟動失敗 |

76在兩個 SDK 中，通常的原因是已解析的路徑指向無法執行的內容，例如文字檔案、目錄或沒有執行權限的檔案。將原生二進位訊息的 libc 建議讀作一個可能的原因。

78若要在任一 SDK 中修復：

80* 確認設定的路徑指向 `claude` 可執行檔本身，且檔案具有執行權限。

81* 如果您不需要自訂路徑，請在 Python 中移除 `cli_path` 或在 TypeScript 中移除 `pathToClaudeCodeExecutable`，以便 SDK 自行尋找 CLI，優先使用其捆綁的副本。

82* 當失敗的二進位檔案是容器映像中 SDK 的捆綁副本時，在映像建置期間重新安裝 SDK，以便捆綁的二進位檔案符合容器的平台，或為其執行的架構重建映像。通常的原因是不符合容器架構或 libc 的二進位檔案，或在映像建置中失去執行權限的二進位檔案。

84<h3 id="cliconnectionerror-not-connected">

85 CLIConnectionError: Not connected

86</h3>

88在 Python 中，在用戶端連線之前或斷開連線之後呼叫 `ClaudeSDKClient` 方法會引發帶有此訊息的 `CLIConnectionError`：

90```

91Not connected. Call connect() first.

92```

94按照訊息所說的做。在任何其他用戶端方法之前呼叫 `await client.connect()`，或使用 `async with ClaudeSDKClient() as client:` 開啟用戶端，它在進入時連線。

96<h2 id="cli-process-exit">

97 CLI 程序退出

98</h2>

100本節中的項目表示 Claude Code 程序在您的應用程式使用它時結束。您看到的錯誤取決於 SDK 語言以及 CLI 在退出前是否報告了錯誤結果。

101

102<h3 id="processerror-command-failed-with-exit-code">

103 ProcessError: Command failed with exit code

104</h3>

105

106當 Claude Code 程序以非零代碼退出時，Python SDK 會引發 `ProcessError`：

107

108```

109Command failed with exit code 1 (exit code: 1)

110Error output: Check stderr output for details

111```

112

113訊息陳述退出代碼兩次，`Error output` 行是固定文字而不是您程序的錯誤輸出。相同的固定文字填充異常的 `stderr` 屬性。異常的 `exit_code` 屬性攜帶代碼。若要捕獲 CLI 實際寫入 stderr 的內容，請在 `ClaudeAgentOptions` 中傳遞 `stderr` 回呼並記錄它接收的內容。

114

115裸露的 `ProcessError` 表示 CLI 退出而未報告錯誤結果。當 CLI 確實報告了一個時，SDK 會改為引發[`ResultError`](/docs/zh-TW/agent-sdk/python#resulterror)，涵蓋在[Claude Code returned an error result](#claude-code-returned-an-error-result)。`ResultError` 是 `ProcessError` 的子類別，因此 `except ProcessError` 會捕獲兩者。若要以不同方式處理它們，請先放置 `except ResultError` 子句。

116

117在 `claude-agent-sdk` 0.2.140 之前，Python SDK 將錯誤結果退出作為普通 `Exception` 而不是 `ResultError` 引發。

118

119<h3 id="claude-code-process-exited-with-code-n">

120 Claude Code process exited with code N

121</h3>

122

123IDE 包裝程式也會列印此訊息，[錯誤參考](/docs/zh-TW/errors#claude-code-process-exited-with-code-n)涵蓋了 VS Code 和其他啟動程式的內容。此項目涵蓋您的 TypeScript SDK 程式碼接收的內容。SDK 將非零 CLI 退出表面為普通 `Error`，它拒絕 `query()` 訊息上的 `for await` 迴圈。沒有 SDK 錯誤類別可捕獲，因此將迴圈包裝在 `try`/`catch` 中並符合訊息：

124

125```

126Claude Code process exited with code 1. stderr: <tail of the CLI's stderr>

127```

128

129當 CLI 寫入 stderr 時，訊息以其尾部結尾。若要捕獲完整串流，請在查詢選項中傳遞 `stderr` 回呼。被信號殺死的程序以相同形式報告 `Claude Code process terminated by signal <name>`。

130

131<h3 id="claude-code-returned-an-error-result">

132 Claude Code returned an error result

133</h3>

134

135當 CLI 在退出前報告錯誤結果時，兩個 SDK 都會用此訊息替換程序退出錯誤：

136

137```

138Claude Code returned an error result: <the CLI's own error report>

139```

140

141冒號後的文字是 CLI 對出錯原因的報告，因此從那裡開始而不是從退出本身開始。Python 將此作為[`ResultError`](/docs/zh-TW/agent-sdk/python#resulterror)引發，其 `data` 屬性攜帶完整的錯誤結果。TypeScript 以帶有相同訊息形狀的普通 `Error` 拒絕訊息迴圈。

142

143<h2 id="structured-outputs">

144 結構化輸出

145</h2>

146

147<h3 id="structured_output-is-none-but-the-result-says-success">

148 structured\_output is None but the result says success

149</h3>

150

151結果訊息可以以 `subtype: "success"` 結尾，而在 Python 中 `structured_output` 是 `None` 或在 TypeScript 中是 `undefined`。執行完成，但不存在驗證的輸出。達到此目標的一種方式是沒有輸出可以滿足的架構，例如衝突的長度約束。執行結束而沒有驗證錯誤，唯一的信號是遺失的 `structured_output`。

152

153在應用程式程式碼中將此結果視為失敗。在使用 `structured_output` 之前，檢查 `subtype` 是 `success` 且 `structured_output` 存在。[錯誤處理](/docs/zh-TW/agent-sdk/structured-outputs#error-handling)部分顯示了兩個 SDK 的此模式。

154

155如果它使用您認為正確的架構重複發生，請驗證架構是可滿足的，然後簡化它直到輸出驗證，並一次重新引入一個約束。

156

157<h2 id="report-a-new-issue">

158 報告新問題

159</h2>

160

161如果您的錯誤未在此涵蓋，請檢查開啟的問題或在 SDK 儲存庫中提交新問題：[claude-agent-sdk-typescript](https://github.com/anthropics/claude-agent-sdk-typescript/issues) 或 [claude-agent-sdk-python](https://github.com/anthropics/claude-agent-sdk-python/issues)。包括完整的錯誤文字和您的 SDK 版本。

agent-sdk/typescript.md +2159 −452

Details

17```17```

18 18

19<Note>19<Note>

20 SDK 為您的平台捆綁了一個原生 Claude Code 二進制文件作為可選依賴項，例如 `@anthropic-ai/claude-agent-sdk-darwin-arm64`。您不需要單獨安裝 Claude Code。如果您的包管理器跳過可選依賴項，SDK 會拋出 `Native CLI binary for <platform> not found`；改為將 [`pathToClaudeCodeExecutable`](#options) 設置為單獨安裝的 `claude` 二進制文件。20 SDK 為您的平台捆綁了一個原生 Claude Code 二進制文件作為可選依賴項，例如 `@anthropic-ai/claude-agent-sdk-darwin-arm64`。大多數安裝不需要單獨安裝 Claude Code。SDK 版本追蹤捆綁的 Claude Code 版本。SDK v0.3.191 捆綁 Claude Code v2.1.191，因此本頁面上需要特定 Claude Code 版本的功能需要具有相同補丁號或更高版本的 SDK 版本。如果您的包管理器跳過可選依賴項，SDK 會拋出 `Native CLI binary for <platform>-<arch> not found`；改為將 [`pathToClaudeCodeExecutable`](#options) 設置為單獨安裝的 `claude` 二進制文件。

22 如果您的包管理器不應用 npm 的 `libc` 欄位（如 Yarn 1.x 不應用），您會在 Linux 上同時獲得 glibc 和 musl 平台包，大約使安裝大小翻倍。在 Agent SDK v0.2.141 或更高版本上，SDK 仍會啟動正確的變體。要在容器映像中回收空間，請刪除與您的應用程式運行的 libc 不匹配的平台包；對於 x64 上的 glibc 運行時，即 `rm -rf node_modules/@anthropic-ai/claude-agent-sdk-linux-x64-musl`。在開發機器上，刪除是臨時的，因為 Yarn 會在下一次依賴項更改時重新安裝該包。

21</Note>23</Note>

22 24

23<h3 id="compile-to-a-single-executable">25<h3 id="compile-to-a-single-executable">

24 編譯為單個可執行文件26 編譯為單個可執行文件

25</h3>27</h3>

26 28

27當您使用 `bun build --compile` 將應用程序編譯為單個文件可執行文件時，SDK 無法在運行時解析捆綁的 CLI 二進制文件。`require.resolve` 在編譯後可執行文件的 `$bunfs` 虛擬文件系統內不起作用，因此 SDK 會拋出 `Native CLI binary for <platform> not found`。29當您使用 `bun build --compile` 將應用程式編譯為單個文件可執行文件時，SDK 無法在運行時解析捆綁的 CLI 二進制文件。`require.resolve` 在編譯後可執行文件的 `$bunfs` 虛擬文件系統內不起作用，因此 SDK 會拋出 `Native CLI binary for <platform>-<arch> not found`。

28 30

29要解決此問題，請將平台二進制文件嵌入為文件資產，在啟動時使用 `extractFromBunfs()` 將其提取到真實路徑，並將該路徑傳遞給 [`pathToClaudeCodeExecutable`](#options)。31要解決此問題，請將平台二進制文件嵌入為文件資產，在啟動時使用 `extractFromBunfs()` 將其提取到真實路徑，並將該路徑傳遞給 [`pathToClaudeCodeExecutable`](#options)。

30 32

45}47}

46```48```

47 49

48`extractFromBunfs()` 將嵌入的二進制文件從編譯後可執行文件的虛擬文件系統複製到每個用戶的臨時目錄，並返回真實路徑。在編譯後的可執行文件外，它返回輸入路徑不變，因此相同的代碼在開發中無需修改即可運行。50`extractFromBunfs()` 將嵌入的二進制文件從編譯後可執行文件的虛擬文件系統複製到每個使用者的臨時目錄，並返回真實路徑。在編譯後的可執行文件外，它返回輸入路徑不變，因此相同的程式碼在開發中無需修改即可運行。

49 51

50每個編譯後的可執行文件都嵌入單個平台的二進制文件。將導入中的平台包與您的 `--target` 匹配：52每個編譯後的可執行文件都嵌入單個平台的二進制文件。將導入中的平台包與您的 `--target` 匹配：

51 53

107| 參數 | 類型 | 描述 |109| 參數 | 類型 | 描述 |

108| :-------------------- | :-------------------- | :---------------------------------------------------------- |110| :-------------------- | :-------------------- | :---------------------------------------------------------- |

111 113

112<h4 id="returns-2">114<h4 id="returns-2">

113 返回值115 返回值

119 示例121 示例

120</h4>122</h4>

121 123

122早期調用 `startup()`，例如在應用程序啟動時，然後在提示準備好後在返回的句柄上調用 `.query()`。這將子進程生成和初始化移出關鍵路徑。124早期調用 `startup()`，例如在應用程式啟動時，然後在提示準備好後在返回的句柄上調用 `.query()`。這將子進程生成和初始化移出關鍵路徑。

123 125

124```typescript theme={null}126```typescript theme={null}

125import { startup } from "@anthropic-ai/claude-agent-sdk";127import { startup } from "@anthropic-ai/claude-agent-sdk";

137 `tool()`139 `tool()`

138</h3>140</h3>

139 141

140為與 SDK MCP 服務器一起使用創建類型安全的 MCP 工具定義。142為與 SDK MCP 伺服器一起使用創建類型安全的 MCP 工具定義。

141 143

142```typescript theme={null}144```typescript theme={null}

143function tool<Schema extends AnyZodRawShape>(145function tool<Schema extends AnyZodRawShape>(

145 description: string,147 description: string,

146 inputSchema: Schema,148 inputSchema: Schema,

147 handler: (args: InferShape<Schema>, extra: unknown) => Promise<CallToolResult>,149 handler: (args: InferShape<Schema>, extra: unknown) => Promise<CallToolResult>,

148 extras?: { annotations?: ToolAnnotations }150 extras?: { annotations?: ToolAnnotations; searchHint?: string; alwaysLoad?: boolean }

149): SdkMcpToolDefinition<Schema>;151): SdkMcpToolDefinition<Schema>;

150```152```

151 153

154</h4>156</h4>

155 157

156| 參數 | 類型 | 描述 |158| 參數 | 類型 | 描述 |

157| :------------ | :---------------------------------------------------------------- | :--------------------------------- |159| :------------ | :----------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- |

162| `extras` | `{ annotations?: `[`ToolAnnotations`](#toolannotations)` }` | 可選的 MCP 工具註釋，為客戶端提供行為提示 |164| `extras` | `{ annotations?: `[`ToolAnnotations`](#toolannotations)`; searchHint?: string; alwaysLoad?: boolean }` | 可選的額外項。`annotations` 為客戶端提供 MCP 行為提示。`searchHint` 是當 [tool search](/docs/zh-TW/agent-sdk/tool-search) 啟用時在延遲工具列表中顯示的單行功能短語。`alwaysLoad: true` 將此工具的完整架構保留在初始提示中，而不是延遲它 |

163 165

164<h4 id="toolannotations">166<h4 id="toolannotations">

165 `ToolAnnotations`167 `ToolAnnotations`

167 169

168從 `@modelcontextprotocol/sdk/types.js` 重新導出。所有字段都是可選提示；客戶端不應依賴它們進行安全決策。170從 `@modelcontextprotocol/sdk/types.js` 重新導出。所有字段都是可選提示；客戶端不應依賴它們進行安全決策。

169 171

170| 字段 | 類型 | 默認值 | 描述 |172| 字段 | 類型 | 預設值 | 描述 |

171| :---------------- | :-------- | :---------- | :------------------------------------------------------------- |173| :---------------- | :-------- | :---------- | :------------------------------------------------------------- |

177 179

178```typescript theme={null}180```typescript theme={null}

179import { tool } from "@anthropic-ai/claude-agent-sdk";181import { tool } from "@anthropic-ai/claude-agent-sdk";

194 `createSdkMcpServer()`196 `createSdkMcpServer()`

195</h3>197</h3>

196 198

197創建在與應用程序相同的進程中運行的 MCP 服務器實例。199創建在與應用程式相同的程序中運行的 MCP 伺服器實例。

198 200

199```typescript theme={null}201```typescript theme={null}

200function createSdkMcpServer(options: {202function createSdkMcpServer(options: {

201 name: string;203 name: string;

202 version?: string;204 version?: string;

205 instructions?: string;

203 tools?: Array<SdkMcpToolDefinition<any>>;206 tools?: Array<SdkMcpToolDefinition<any>>;

207 alwaysLoad?: boolean;

208 timeout?: number;

204}): McpSdkServerConfigWithInstance;209}): McpSdkServerConfigWithInstance;

205```210```

206 211

209</h4>214</h4>

210 215

211| 參數 | 類型 | 描述 |216| 參數 | 類型 | 描述 |

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

221| `options.tools` | `Array<SdkMcpToolDefinition>` | 使用 [`tool()`](#tool) 創建的工具定義陣列 |

222| `options.alwaysLoad` | `boolean` | 當為 `true` 時，此伺服器的每個工具都保留在初始提示中，永遠不會延遲到 [tool search](/docs/zh-TW/agent-sdk/tool-search) 後面。與 [`tool()`](#tool) 中的每個工具 `alwaysLoad` 結合 |

223| `options.timeout` | `number` | 此伺服器的工具調用超時時間（毫秒）。Claude Code 將其應用於此伺服器以代替 [`MCP_TOOL_TIMEOUT`](/docs/zh-TW/env-vars)。傳遞至少 1000 的整數。Claude Code 忽略其他值。需要 TypeScript Agent SDK v0.3.248 或更高版本 |

216 224

217<h3 id="listsessions">225<h3 id="listsessions">

218 `listSessions()`226 `listSessions()`

219</h3>227</h3>

220 228

221發現並列出具有輕量級元數據的過去會話。按項目目錄篩選或列出所有項目中的會話。229發現並列出具有輕量級元資料的過去會話。按項目目錄篩選或列出所有項目中的會話。

222 230

223```typescript theme={null}231```typescript theme={null}

224function listSessions(options?: ListSessionsOptions): Promise<SDKSessionInfo[]>;232function listSessions(options?: ListSessionsOptions): Promise<SDKSessionInfo[]>;

228 參數236 參數

229</h4>237</h4>

230 238

231| 參數 | 類型 | 默認值 | 描述 |239| 參數 | 類型 | 預設值 | 描述 |

232| :------------------------- | :-------- | :---------- | :---------------------------------------- |240| :------------------------- | :-------- | :---------- | :---------------------------------------- |

239</h4>247</h4>

240 248

241| 屬性 | 類型 | 描述 |249| 屬性 | 類型 | 描述 |

242| :------------- | :-------------------- | :----------------------------------------- |250| :------------- | :-------------------- | :------------------------------------------ |

253 261

254<h4 id="example-2">262<h4 id="example-2">

255 示例263 示例

256</h4>264</h4>

257 265

258打印項目的 10 個最近會話。結果按 `lastModified` 降序排序，因此第一項是最新的。省略 `dir` 以搜索所有項目。266打印項目的 10 個最近會話。結果按 `lastModified` 降序排序，因此第一項是最新的。省略 `dir` 以搜尋所有項目。

259 267

260```typescript theme={null}268```typescript theme={null}

261import { listSessions } from "@anthropic-ai/claude-agent-sdk";269import { listSessions } from "@anthropic-ai/claude-agent-sdk";

271 `getSessionMessages()`279 `getSessionMessages()`

272</h3>280</h3>

273 281

274從過去的會話記錄中讀取用戶和助手消息。282從過去的會話記錄中讀取使用者和助手消息。

275 283

276```typescript theme={null}284```typescript theme={null}

277function getSessionMessages(285function getSessionMessages(

284 參數292 參數

285</h4>293</h4>

286 294

287| 參數 | 類型 | 默認值 | 描述 |295| 參數 | 類型 | 預設值 | 描述 |

288| :--------------- | :------- | :---------- | :------------------------------ |296| :--------------- | :------- | :---------- | :------------------------------ |

293 301

296</h4>304</h4>

297 305

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

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

306 314

307<h4 id="example-3">315<h4 id="example-3">

308 示例316 示例

329 `getSessionInfo()`337 `getSessionInfo()`

330</h3>338</h3>

331 339

332按 ID 讀取單個會話的元數據，無需掃描完整項目目錄。340按 ID 讀取單個會話的元資料，無需掃描完整項目目錄。

333 341

334```typescript theme={null}342```typescript theme={null}

335function getSessionInfo(343function getSessionInfo(

342 參數350 參數

343</h4>351</h4>

344 352

345| 參數 | 類型 | 默認值 | 描述 |353| 參數 | 類型 | 預設值 | 描述 |

346| :------------ | :------- | :---------- | :------------------ |354| :------------ | :------- | :---------- | :------------------ |

349 357

350返回 [`SDKSessionInfo`](#return-type-sdksessioninfo)，如果找不到會話則返回 `undefined`。358返回 [`SDKSessionInfo`](#return-type-sdksessioninfo)，如果找不到會話則返回 `undefined`。

351 359

367 參數375 參數

368</h4>376</h4>

369 377

370| 參數 | 類型 | 默認值 | 描述 |378| 參數 | 類型 | 預設值 | 描述 |

371| :------------ | :------- | :---------- | :------------------ |379| :------------ | :------- | :---------- | :------------------ |

375 383

376<h3 id="tagsession">384<h3 id="tagsession">

377 `tagSession()`385 `tagSession()`

391 參數399 參數

392</h4>400</h4>

393 401

394| 參數 | 類型 | 默認值 | 描述 |402| 參數 | 類型 | 預設值 | 描述 |

395| :------------ | :--------------- | :---------- | :------------------ |403| :------------ | :--------------- | :---------- | :------------------ |

397| `tag` | `string \| null` | 必需 | 標籤字符串，或 `null` 以清除 |405| `tag` | `string \| null` | 必需 | 標籤字符串，或 `null` 以清除 |

399 407

400<h3 id="resolvesettings">408<h3 id="resolvesettings">

401 `resolveSettings()`409 `resolveSettings()`

404使用與 CLI 相同的合併引擎為給定目錄解析有效的 Claude Code 設定，無需生成 Claude CLI。在調用 `query()` 之前使用它來檢查 `query()` 調用將看到什麼配置。412使用與 CLI 相同的合併引擎為給定目錄解析有效的 Claude Code 設定，無需生成 Claude CLI。在調用 `query()` 之前使用它來檢查 `query()` 調用將看到什麼配置。

405 413

406<Note>414<Note>

407 此函數處於 alpha 階段，其 API 在穩定之前可能會更改。它讀取 MDM 源，包括 macOS plist 和 Windows HKLM/HKCU，以與 CLI 啟動保持一致，但不執行管理員配置的 `policyHelper` 子進程。`permissions.defaultMode` 字段從所有層級（包括項目設定）按原樣返回。CLI 在遵守升級權限模式之前應用的信任過濾器不被應用。415 此函數處於 alpha 階段，其 API 在穩定之前可能會更改。

408</Note>416</Note>

409 417

418快照與實時 `query()` 會話應用的內容不同：

419

420* **`policyHelper`**：`resolveSettings()` 讀取 MDM 源，包括 macOS plist 和 Windows HKLM/HKCU，但不執行管理員配置的 `policyHelper` 子程序。

421* **伺服器託管設定**：`resolveSettings()` 不會獲取[伺服器託管設定](/docs/zh-TW/server-managed-settings#fetch-and-caching-behavior)。將它們作為 `options.serverManagedSettings` 傳遞以包括它們。

422* **`defaultMode`**：快照從每個層級按原樣返回 `permissions.defaultMode`，因此它可以包括項目和本地設定中的 `'auto'` 和 `'bypassPermissions'` 值，[實時會話忽略](/docs/zh-TW/permission-modes#which-mode-a-session-starts-in)。

423

410```typescript theme={null}424```typescript theme={null}

411function resolveSettings(425function resolveSettings(

412 options?: ResolveSettingsOptions426 options?: ResolveSettingsOptions

419 433

420`resolveSettings()` 接受單個選項對象。所有字段都是可選的。434`resolveSettings()` 接受單個選項對象。所有字段都是可選的。

421 435

422| 參數 | 類型 | 默認值 | 描述 |436| 參數 | 類型 | 預設值 | 描述 |

423| :------------------------------ | :------------------------------------ | :-------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- |437| :------------------------------ | :------------------------------------ | :-------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

425| `options.settingSources` | [`SettingSource`](#settingsource)`[]` | 所有源 | 要加載的文件系統源。傳遞 `[]` 以跳過用戶、項目和本地設定。託管策略設定在所有情況下都會加載。伺服器託管設定取自 `serverManagedSettings`（當主機傳遞時），或從 CLI 的磁盤上緩存讀取；快照不會從網絡獲取它們 |439| `options.settingSources` | [`SettingSource`](#settingsource)`[]` | 所有源 | 要加載的檔案系統源。傳遞 `[]` 以跳過使用者、項目和本地設定。[端點託管策略](/docs/zh-TW/managed-settings#delivery-mechanisms)在所有情況下都會加載。`resolveSettings()` 僅當您傳遞 `options.serverManagedSettings` 時才包括伺服器託管設定 |

426| `options.managedSettings` | `Settings` | `undefined` | 由嵌入主機提供的限制性策略層設定。當存在管理員部署的託管層時被丟棄；當 [`parentSettingsBehavior`](/docs/zh-TW/settings#available-settings) 為 `"merge"` 時在該層下合併。非限制性鍵（如 `model`）會被靜默丟棄，以便此選項可以加強託管策略但不能放寬它 |440| `options.managedSettings` | `Settings` | `undefined` | 由嵌入主機提供的策略層設定。遵循與 [`managedSettings` in `Options`](#options) 相同的規則，除了 `resolveSettings()` 不執行配置的 [`policyHelper`](/docs/zh-TW/settings-reference#policyhelper)，因此快照可以包括實時會話丟棄的設定 |

428 442

429<h4 id="return-type-resolvedsettings">443<h4 id="return-type-resolvedsettings">

430 返回類型：`ResolvedSettings`444 返回類型：`ResolvedSettings`

442 示例456 示例

443</h4>457</h4>

444 458

445下面的示例為項目目錄解析設定並打印控制清理期的源。459下面的示例為項目目錄解析設定並打印控制清理期的源。在沒有設定檔案設置 `cleanupPeriodDays` 的機器上，兩條打印的行都顯示 `undefined` 作為值，這是預期的輸出而不是錯誤。

446 460

447```typescript theme={null}461```typescript theme={null}

448import { resolveSettings } from "@anthropic-ai/claude-agent-sdk";462import { resolveSettings } from "@anthropic-ai/claude-agent-sdk";

466 480

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

468 482

469| 屬性 | 類型 | 默認值 | 描述 |483| 屬性 | 類型 | 預設值 | 描述 |

470| :-------------------------------- | :------------------------------------------------------------------------------------------------------- | :---------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |484| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

477| `allowedTools` | `string[]` | `[]` | 無需提示即可自動批准的工具。這不會將 Claude 限制為僅這些工具；未列出的工具會進入 `permissionMode` 和 `canUseTool`。使用 `disallowedTools` 來阻止工具。見 [Permissions](/docs/zh-TW/agent-sdk/permissions#allow-and-deny-rules) |491| `allowedTools` | `string[]` | `[]` | 無需提示即可自動批准的工具。這不會將 Claude 限制為僅這些工具。如果您在此處命名其中一個 [task-tracking tools](/docs/zh-TW/agent-sdk/todo-tracking#model-availability)，Claude Code 也會選擇加入會話。其他未列出的工具會進入 `permissionMode` 和 `canUseTool`。使用 `disallowedTools` 來阻止工具。見 [Permissions](/docs/zh-TW/agent-sdk/permissions#allow-and-deny-rules) |

479| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | 自定義權限函數，僅在 [permission flow](/docs/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated) 進入提示時調用。不會為 `allowedTools`、allow 規則或 `permissionMode` 自動批准的調用調用。`AskUserQuestion`、connector tools [您的組織設置為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools) 和標記為 [`requiresUserInteraction`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP tools 即使您已允許它們也會到達它；在 `dontAsk` 模式下這些會被拒絕。見 [`CanUseTool`](#canusetool) 了解詳情 |493| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | 自定義權限函數，僅在 [permission flow](/docs/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated) 進入提示時調用。不會為 `allowedTools`、allow 規則或 `permissionMode` 自動批准的調用調用。Allow 規則不會預批准 [actions no mode auto-approves](/docs/zh-TW/permission-modes#actions-no-mode-auto-approves)。見 [`CanUseTool`](#canusetool) 了解詳情 |

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

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

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

493| `forwardSubagentText` | `boolean` | `false` | 轉發子代理文本和思考塊作為助手和用戶消息，並設置 `parent_tool_use_id`，以便消費者可以呈現嵌套記錄。默認情況下，只有來自子代理的 `tool_use` 和 `tool_result` 塊被發出 |507| `forwardSubagentText` | `boolean` | `false` | 轉發 subagent 文字和思考塊作為助手和使用者訊息，並設置 `parent_tool_use_id`，以便消費者可以呈現嵌套記錄。沒有此選項，Claude Code 會發出 subagent `tool_use` 和 `tool_result` 塊，但不會發出文字或思考。來自每個嵌套深度的 subagents 訊息會在 Claude Code v2.1.219 及更高版本上轉發；在 v2.1.219 之前，只有來自深度 1 subagents 的訊息出現 |

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

495| `includeHookEvents` | `boolean` | `false` | 將 hooks 生命週期事件包括在消息流中，作為 [`SDKHookStartedMessage`](#sdkhookstartedmessage)、[`SDKHookProgressMessage`](#sdkhookprogressmessage) 和 [`SDKHookResponseMessage`](#sdkhookresponsemessage)。`SessionStart` 和 `Setup` hooks 的生命週期事件始終包括在內，不需要此選項 |509| `includeHookEvents` | `boolean` | `false` | 將 hooks 生命週期事件包括在訊息流中，作為 [`SDKHookStartedMessage`](#sdkhookstartedmessage)、[`SDKHookProgressMessage`](#sdkhookprogressmessage) 和 [`SDKHookResponseMessage`](#sdkhookresponsemessage)。`SessionStart` 和 `Setup` hooks 的生命週期事件始終包括在內，不需要此選項。某些 hooks 事件，例如 `Notification`、`SessionEnd`、`PreCompact` 和 `PostCompact`，永遠不會產生 `SDKHookStartedMessage`，即使使用此選項也是如此。對於這些事件，Claude Code 仍會在執行超過一秒的命令 hooks 時發出 `SDKHookProgressMessage` 並產生輸出，並且僅當 hooks [that runs in the background](/docs/zh-TW/hooks#run-hooks-in-the-background) 完成時才發出 `SDKHookResponseMessage` |

498| `managedSettings` | `Settings` | `undefined` | 由生成父進程提供的策略層設置。當機器上已存在 IT 控制的託管設置層時被丟棄，除非該管理員選擇使用 `parentSettingsBehavior: 'merge'`。無論如何都被過濾為僅限制性鍵 |512| `managedSettings` | `Settings` | `undefined` | 您的主機進程提供給生成會話的策略層設定。在具有管理員部署的受管設定的機器上，Claude Code 會忽略這些，除非管理員的最高優先級受管來源設置 `parentSettingsBehavior: 'merge'`，並且當 [`policyHelper`](/docs/zh-TW/settings-reference#policyhelper) 提供受管設定時永遠不會合併它們。合併的值通過限制性專用篩選器；[Restrict parent settings](/docs/zh-TW/claude-apps-gateway#restrict-parent-settings) 涵蓋篩選器允許的內容和 `allowManaged*Only` 鎖定。設置 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-TW/env-vars) 的主機有三個鍵直接從此有效負載讀取：其在 Claude Code v2.1.222 或更高版本上的 [model configuration](/docs/zh-TW/model-config#restrict-model-selection)、當沒有受管來源在 v2.1.246 或更高版本上設置它時的 [`modelPricing`](/docs/zh-TW/settings-reference#modelpricing)，以及其在 v2.1.247 或更高版本上的 `ENABLE_TOOL_SEARCH` env 條目 |

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

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

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

506| `outputStyle` | `string` | `undefined` | 不是 `Options` 字段。改為在內聯 [`settings`](/docs/zh-TW/settings) 對象或設置文件中設置 `outputStyle`。見 [Activate an output style](/docs/zh-TW/agent-sdk/modifying-system-prompts#activate-an-output-style) |520| `outputStyle` | `string` | `undefined` | 不是 `Options` 欄位。改為在內聯 [`settings`](/docs/zh-TW/settings) 物件或設定檔中設置 `outputStyle`。見 [Activate an output style](/docs/zh-TW/agent-sdk/modifying-system-prompts#activate-an-output-style) |

528| `promptSuggestions` | `boolean` | `false` | 啟用提示建議。在每個轉數後，Claude Code 發出 `prompt_suggestion` 訊息，帶有預測的下一個使用者提示。Claude Code 不會為某些轉數生成建議，例如當您的帳戶接近或達到其使用限制時。見 [When Claude Code skips suggestions](/docs/zh-TW/interactive-mode#when-claude-code-skips-suggestions) |

518| `sessionStore` | [`SessionStore`](/docs/zh-TW/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | 將會話記錄鏡像到外部後端，以便任何主機都可以恢復它們。見 [Persist sessions to external storage](/docs/zh-TW/agent-sdk/session-storage) |534| `sessionStore` | [`SessionStore`](/docs/zh-TW/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | 將會話記錄鏡像到外部後端，以便另一個主機可以恢復它們。見 [Persist sessions to external storage](/docs/zh-TW/agent-sdk/session-storage) |

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

522| `skills` | `string[] \| 'all'` | `undefined` | 會話可用的 skills。傳遞 `'all'` 以啟用每個發現的 skill，或傳遞 skill 名稱列表。設置後，SDK 會自動將 Skill 工具添加到 `allowedTools`。如果您也傳遞 `tools`，請在該列表中包含 `'Skill'`。見 [Skills](/docs/zh-TW/agent-sdk/skills) |538| `skills` | `string[] \| 'all'` | `undefined` | 會話可用的 skills。傳遞 `'all'` 以啟用每個發現的 skill，或傳遞 skill 名稱列表。僅傳遞確切名稱。在 Agent SDK v0.3.221 或更高版本上，SDK 會在啟動 Claude Code 進程之前以錯誤拒絕格式不正確和萬用字元形式的名稱。設置後，SDK 會自動將 Skill 工具添加到 `allowedTools`。如果您也傳遞 `tools`，請在該列表中包含 `'Skill'`。見 [Skills](/docs/zh-TW/agent-sdk/skills) |

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](/docs/zh-TW/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |542| `systemPrompt` | `string \| string[] \| { type: 'custom'; prompt: string \| string[]; snapshot?: boolean } \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean; snapshot?: boolean }` | `undefined`（最小提示） | 系統提示配置。傳遞字串以獲得自定義提示，或 `{ type: 'preset', preset: 'claude_code' }` 以使用 Claude Code 的系統提示。傳遞包含匯出的 `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` 常數的字串陣列，在靜態和每個請求部分之間，以 [cache the static part of a custom prompt](/docs/zh-TW/agent-sdk/modifying-system-prompts#cache-the-static-part-of-a-custom-prompt)。使用預設物件形式時，添加 `append` 以使用其他指令擴展它，並設置 `excludeDynamicSections: true` 以將每個會話上下文移到第一個使用者訊息中，以獲得 [better prompt-cache reuse across machines](/docs/zh-TW/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines)。設置 `snapshot: false` 以在每個請求上重建提示，而不是 [reusing the prompt the session recorded on its first request](/docs/zh-TW/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session)。要在自定義提示上設置 `snapshot`，傳遞 `{ type: 'custom', prompt }` 形式。`{ type: 'custom' }` 形式和 `snapshot` 欄位需要 TypeScript Agent SDK v0.3.257 或更高版本 |

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

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

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

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

533 549

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

535 Handle slow or stalled API responses551 Handle slow or stalled API responses

536</h4>552</h4>

537 553

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

539 555

540```typescript theme={null}556```typescript theme={null}

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

558

541const result = query({559const result = query({

542 prompt: "Analyze this code",560 prompt: "Analyze this code",

543 options: {561 options: {

551});569});

552```570```

553 571

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

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

556* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：使用 `run_in_background` 啟動的子代理的停滯監視程序。默認 `600000`。在每個流事件上重置；在停滯時中止子代理，將任務標記為失敗，並將錯誤與任何部分結果一起呈現給父代理。不適用於同步子代理。574* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：subagents 的停滯監視程序。當串流監視程序開啟時，預設值為 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 加上 5 分鐘，總計 `600000`，除非您提高該變數。關閉串流監視程序時，預設值為 `600000`。在 v2.1.257 之前，預設值始終為 `600000`。

557* `CLAUDE_ENABLE_STREAM_WATCHDOG` 與 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`：當標頭已到達但響應正文停止流式傳輸時中止請求。監視程序對所有提供商默認開啟；設置 `CLAUDE_ENABLE_STREAM_WATCHDOG=0` 以禁用它。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` 默認為 `300000` 並被限制為該最小值。中止的請求通過正常重試路徑進行。575

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

577* `CLAUDE_ENABLE_STREAM_WATCHDOG` 與 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`：串流監視程序，當標頭已到達但回應正文停止串流時中止請求。監視程序對所有提供商預設開啟；設置 `CLAUDE_ENABLE_STREAM_WATCHDOG=0` 以禁用它。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` 預設為 `300000` 並被限制為該最小值。中止後，[Automatic retries](/docs/zh-TW/errors#automatic-retries) 涵蓋 Claude Code 根據回應進度的程度所做的事情。

578

579 當監視程序等待 `ANTHROPIC_BASE_URL` 後面的閘道使用保活 ping 保持開啟的回應時，設置 `includePartialMessages` 的主機會繼續接收 `ping` [stream events](#sdkpartialassistantmessage)，因此將這些框架讀取為活躍性而不是在沉默時逾時會話。在 v2.1.257 之前，框架在最後一個真實串流事件後 5 分鐘停止。

558 580

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

560 `Query` object582 `Query` object

572 setPermissionMode(mode: PermissionMode): Promise<void>;594 setPermissionMode(mode: PermissionMode): Promise<void>;

573 setModel(model?: string): Promise<void>;595 setModel(model?: string): Promise<void>;

574 setMaxThinkingTokens(maxThinkingTokens: number | null): Promise<void>;596 setMaxThinkingTokens(maxThinkingTokens: number | null): Promise<void>;

575 applyFlagSettings(settings: { [K in keyof Settings]?: Settings[K] | null }): Promise<void>;597 applyFlagSettings(settings: {

598 [K in keyof Settings]?: K extends 'effortLevel'

600 : Settings[K] | null;

601 }): Promise<void>;

602 updateSettings(

603 source: 'localSettings',

604 settings: Record<string, unknown>,

605 ): Promise<void>;

576 initializationResult(): Promise<SDKControlInitializeResponse>;606 initializationResult(): Promise<SDKControlInitializeResponse>;

577 reinitialize(): Promise<SDKControlInitializeResponse>;607 reinitialize(): Promise<SDKControlInitializeResponse>;

578 supportedCommands(): Promise<SlashCommand[]>;608 supportedCommands(): Promise<SlashCommand[]>;

579 supportedModels(): Promise<ModelInfo[]>;609 supportedModels(): Promise<ModelInfo[]>;

580 supportedAgents(): Promise<AgentInfo[]>;610 supportedAgents(): Promise<AgentInfo[]>;

581 mcpServerStatus(): Promise<McpServerStatus[]>;611 mcpServerStatus(): Promise<McpServerStatus[]>;

612 getContextUsage(opts?: {

613 detail?: 'summary' | 'full';

614 }): Promise<SDKControlGetContextUsageResponse>;

615 readFile(

616 path: string,

617 options?: { maxBytes?: number; encoding?: 'utf-8' | 'base64' }

618 ): Promise<SDKControlReadFileResponse | null>;

619 reloadSkills(): Promise<SDKControlReloadSkillsResponse>;

582 accountInfo(): Promise<AccountInfo>;620 accountInfo(): Promise<AccountInfo>;

583 reconnectMcpServer(serverName: string): Promise<void>;621 reconnectMcpServer(serverName: string): Promise<void>;

584 toggleMcpServer(serverName: string, enabled: boolean): Promise<void>;622 toggleMcpServer(serverName: string, enabled: boolean): Promise<void>;

594</h4>632</h4>

595 633

596| 方法 | 描述 |634| 方法 | 描述 |

597| :------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |635| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

598| `interrupt()` | 中斷查詢。僅在流式輸入模式下可用。當 CLI 在 [`SDKSystemMessage.capabilities`](#sdksystemmessage) 中公告 `interrupt_receipt_v1` 功能時，使用列出存活中斷的排隊消息的 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) 進行解決。在 v2.1.205 之前的 CLI 上解決為 `undefined` |636| `interrupt()` | 中斷查詢。僅在串流輸入模式下可用。當 CLI 在 [`SDKSystemMessage.capabilities`](#sdksystemmessage) 中公告 `interrupt_receipt_v1` 功能時，使用列出中斷時待處理訊息的 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) 進行解決。在 v2.1.205 之前的 CLI 上解決為 `undefined` |

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

604| `initializationResult()` | 返回完整的初始化結果，包括支持的命令、模型、帳戶信息和輸出樣式配置 |642| `updateSettings(source, settings)` | 將設定合併到專案的本地設定檔 `.claude/settings.local.json` 中；它們在下一個請求時生效。僅接受 `source: 'localSettings'` 和允許列表鍵集，目前為 `outputStyle`，具有字串值；不支持刪除鍵。在遠端傳輸和會話上拒絕，其 [`settingSources`](#options) 排除 `local`。需要 TypeScript SDK v0.3.257 或更高版本，它捆綁 Claude Code v2.1.257 |

605| `reinitialize()` | 重新發送 `initialize` 控制請求到運行的 CLI，並返回新鮮的結果而不是緩存的首次連接結果。在傳輸間隙後使用它，例如在斷開連接後重新附加到會話，以便待處理的權限請求再次到達您的 `canUseTool` 回調。使回調對每個請求 ID 冪等，因為響應丟失的請求會再次被分派。需要 Claude Code v2.1.195 或更高版本 |643| `initializationResult()` | 返回完整的初始化結果，包括支持的命令、模型、帳戶資訊和輸出樣式配置 |

611| `reconnectMcpServer(serverName)` | 按名稱重新連接 MCP 服務器 |649| `getContextUsage(opts?)` | 返回 [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse)，按類別、skill 和工具分解會話的上下文視窗使用情況。使用預設 `detail`，它與 `/context` 在互動式會話中顯示的資料相同。[`detail` 選項](#sdkcontrolgetcontextusageresponse) 需要 Agent SDK v0.3.257 或更高版本 |

612| `toggleMcpServer(serverName, enabled)` | 按名稱啟用或禁用 MCP 服務器 |650| `readFile(path, options?)` | 從會話的檔案系統讀取檔案。Claude Code 根據 `cwd` 解析路徑；[What `readFile()` can read](#what-readfile-can-read) 列出它提供的檔案。傳遞 `{ maxBytes }` 以更改讀取上限（預設 1 MB，上限 10 MB）和 `{ encoding: 'base64' }` 以讀取二進位檔案，例如影像。使用 [`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse) 進行解決，或在權限拒絕、檔案遺失或傳輸錯誤時使用 `null`。需要 TypeScript SDK v0.2.121 或更高版本 |

613| `setMcpServers(servers)` | 動態替換此會話的 MCP 服務器集。返回有關添加、刪除的服務器和任何錯誤的信息 |651| `reloadSkills()` | 從磁碟重新載入 skills，以便您在會話中期添加或編輯的 skills 對執行中的會話可用。使用 [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) 進行解決，列出重新載入後可用的 skills。需要 Agent SDK v0.3.163 或更高版本 |

615| `stopTask(taskId)` | 按 ID 停止運行的後台任務 |653| `reconnectMcpServer(serverName)` | 按名稱重新連接 MCP 伺服器。如果名稱也符合設定檔中的條目，例如 `.mcp.json` 或 `~/.claude.json`，Claude Code 會重新連接您通過 [`mcpServers`](#options) 或 `setMcpServers()` 配置的伺服器，而不是設定檔條目。該解析順序需要 Claude Code v2.1.257 或更高版本 |

654| `toggleMcpServer(serverName, enabled)` | 按名稱啟用或禁用 MCP 伺服器，使用與 `reconnectMcpServer()` 相同的名稱解析。禁用會斷開伺服器連接 |

655| `setMcpServers(servers)` | 動態替換此會話的 MCP 伺服器集。使用 [`McpSetServersResult`](#mcpsetserversresult) 進行解決，命名添加和移除的伺服器，以及任何錯誤 |

656| `streamInput(stream)` | 將輸入訊息串流到查詢以進行多轉對話 |

657| `stopTask(taskId)` | 按 ID 停止執行中的背景任務 |

617 659

618<h4 id="applyflagsettings">660<h4 id="applyflagsettings">

619 `applyFlagSettings()`661 `applyFlagSettings()`

620</h4>662</h4>

621 663

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

623 665

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

625 667

626* **在下一個轉數上應用**：`model`、`effortLevel`、`ultracode`、`permissions`、`hooks`、`skillOverrides`、`fastMode`、`agent`。切換 `agent` 也會在下一個轉數上應用該代理的模型覆蓋、hooks 和系統提示。668* **在下一個轉數上應用**：`effortLevel`、`ultracode`、`permissions`、`hooks`、`skillOverrides`、`fastMode`、`agent`。切換 `agent` 也會在下一個轉數上應用該代理的模型覆蓋和 hooks。其系統提示在下一個轉數上應用，或在 [reuses a recorded system prompt](/docs/zh-TW/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session) 的會話中，一旦會話被壓縮。

627* **在會話中期無效**：系統提示選項。這些在啟動時解決一次，因此運行會話保持原始值，即使調用成功。要更改它們，請啟動新會話。669* **在目前轉數期間應用**：`model`。如果您在 Claude 處理轉數時切換 `model`，Claude 已在生成的回應會在舊模型上完成，轉數的其餘部分（從 Claude Code 對模型進行的下一個呼叫開始）使用新模型。Subagents 保持自己的模型。在 v2.1.212 之前，中期切換會等待下一個轉數。

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

628 671

629`effortLevel` 接受 [effort level](/docs/zh-TW/model-config#adjust-effort-level) 名稱。它也接受 `"ultracode"`，它以 `xhigh` 努力運行會話並打開 [ultracode](/docs/zh-TW/workflows#let-claude-decide-with-ultracode)。`Settings` 類型聲明 `effortLevel` 沒有該值，因此在 TypeScript 中傳遞等效的 `{ ultracode: true }`。`ultracode` 值需要 Claude Code v2.1.203 或更高版本，並且僅由 `applyFlagSettings()` 接受，不由設置文件中的 `effortLevel` 鍵接受。672`effortLevel` 接受 [effort level](/docs/zh-TW/model-config#adjust-effort-level) 名稱。它也接受 `"ultracode"`，它要求 `xhigh` 努力並開啟 [ultracode](/docs/zh-TW/workflows#let-claude-decide-with-ultracode)。`applyFlagSettings()` 聲明 `effortLevel` 沒有該值，因此在 TypeScript 中傳遞等效的 `{ ultracode: true }`。`ultracode` 值需要 Claude Code v2.1.203 或更高版本，並且僅由 `applyFlagSettings()` 接受，不由設定檔中的 `effortLevel` 鍵接受。

630 673

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

632 675

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

634 677

635僅在流式輸入模式下可用，與 `setModel()` 和 `setPermissionMode()` 的約束相同。678僅在串流輸入模式下可用，與 `setModel()` 和 `setPermissionMode()` 的約束相同。

636 679

637下面的示例在會話中期切換活動模型，然後清除覆蓋，以便模型回退到用戶或項目設置指定的任何內容。680下面的範例在會話中期切換活動模型，然後清除覆蓋，以便模型回退到使用者或專案設定指定的任何內容。

638 681

639```typescript theme={null}682```typescript theme={null}

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

684

640const q = query({ prompt: messageStream });685const q = query({ prompt: messageStream });

641 686

642// 覆蓋會話其餘部分的模型687// 覆蓋會話其餘部分的模型

643await q.applyFlagSettings({ model: "claude-opus-4-6" });688await q.applyFlagSettings({ model: "claude-opus-4-6" });

644 689

645// 稍後：清除覆蓋並回退到較低優先級設置690// 稍後：清除覆蓋並回退到較低優先級設定

646await q.applyFlagSettings({ model: null });691await q.applyFlagSettings({ model: null });

647```692```

648 693

654 `WarmQuery`699 `WarmQuery`

655</h3>700</h3>

656 701

657由 [`startup()`](#startup) 返回的句柄。子進程已生成並初始化，因此在此句柄上調用 `query()` 會直接將提示寫入準備好的進程，無需啟動延遲。702由 [`startup()`](#startup) 返回的句柄。子進程已生成並初始化，因此在此句柄上呼叫 `query()` 會直接將提示寫入準備好的進程，無需啟動延遲。

658 703

659```typescript theme={null}704```typescript theme={null}

660interface WarmQuery extends AsyncDisposable {705interface WarmQuery extends AsyncDisposable {

669 714

670| 方法 | 描述 |715| 方法 | 描述 |

671| :-------------- | :------------------------------------------------------------ |716| :-------------- | :------------------------------------------------------------ |

674 719

675`WarmQuery` 實現 `AsyncDisposable`，因此可以與 `await using` 一起使用以進行自動清理。720`WarmQuery` 實現 `AsyncDisposable`，因此可以與 `await using` 一起使用以進行自動清理。

678 `SDKControlInitializeResponse`723 `SDKControlInitializeResponse`

679</h3>724</h3>

680 725

681`initializationResult()` 的返回類型。包含會話初始化數據。726`initializationResult()` 的返回類型。包含會話初始化資料。

682 727

683```typescript theme={null}728```typescript theme={null}

684type SDKControlInitializeResponse = {729type SDKControlInitializeResponse = {

689 models: ModelInfo[];734 models: ModelInfo[];

690 account: AccountInfo;735 account: AccountInfo;

691 fast_mode_state?: "off" | "cooldown" | "on";736 fast_mode_state?: "off" | "cooldown" | "on";

737 fast_mode_disabled_reason?: FastModeDisabledReason;

738 hooks_applied?: boolean;

692};739};

693```740```

694 741

695當客戶端向已運行的會話發送 `initialize` 時，控制響應包裝器也會帶有可選的 `pending_permission_requests` 數組。該字段位於響應包裝器本身上，而不是上面的 `SDKControlInitializeResponse` 有效負載中。每個條目都是一個完整的 `control_request` 消息，具有與會話在運行時為權限請求流式傳輸的相同 `{ type: "control_request", request_id, request }` 形狀。742`hooks_applied` 報告 Claude Code 是否註冊了 `initialize` 請求所帶的 `hooks`。SDK 在會話啟動時發送該請求一次，並在每個 [`reinitialize()`](#query-object) 呼叫上再次發送。該欄位需要 Agent SDK v0.3.238 或更高版本。

743

744當請求未帶 hooks 時，Claude Code 會省略該欄位。當請求帶 hooks 時，該值取決於請求是否是會話的首次初始化，以及對於重複的請求，它如何到達會話：

745

746* `true`：Claude Code 註冊了 hooks。會話的首次初始化返回此值。通過 CLI 的 stdin 發送的重複初始化也會返回此值。在這種情況下，新請求中的 hooks 會替換之前註冊的 hooks。

747* `false`：Claude Code 忽略了 hooks。發送到遠端會話的重複初始化返回此值，因此加入會話的第二個客戶端無法替換第一個客戶端註冊的 hooks。

748

749在 Agent SDK v0.3.238 之前，回應從未帶該欄位，Claude Code 在每個重複初始化上都忽略 `hooks`。

750

751回應始終報告 `fast_mode_state`，當某些東西阻止 [fast mode](/docs/zh-TW/fast-mode) 時，`fast_mode_disabled_reason` 會帶著原因代碼，以便您可以解釋被阻止的狀態，而不是重新推導可用性。兩種行為都需要 Claude Code v2.1.219 或更高版本。在 v2.1.219 之前，當快速模式不可用時回應會省略 `fast_mode_state`，並且永遠不會帶原因。有關原因代碼及其含義，見結果訊息上的 [`fast_mode_disabled_reason`](#sdkresultmessage)。

752

753成功 `initialize` 的控制回應包裝器也帶有 `pending_permission_requests` 陣列。該欄位位於回應包裝器本身上，而不是上面的 `SDKControlInitializeResponse` 有效負載中。每個條目都是一個完整的 `control_request` 訊息，具有與會話在執行時為權限請求串流的相同 `{ type: "control_request", request_id, request }` 形狀。

754

755該陣列列出此 Claude Code 進程已發出且尚未解決的權限請求。SDK 為您讀取陣列並將每個條目分派到您的 [`canUseTool`](#canusetool) 回調，這是 [`reinitialize()`](#query-object) 在傳輸間隙後觸發的相同重新傳遞。以冪等方式處理重複的請求 ID，因為一個條目可以重複回調已經收到的請求，然後連接斷開。

696 756

697這些是在客戶端連接之前發出的請求，仍在等待回复。SDK 為您讀取數組並將每個條目分派到您的 [`canUseTool`](#canusetool) 回調，這是 [`reinitialize()`](#query-object) 在傳輸間隙後觸發的相同重新傳遞。以冪等方式處理重複的請求 ID，因為一個條目可以重複回調已經收到的請求，然後連接斷開。757該陣列在成功 `initialize` 回應上始終存在，當此進程沒有未解決的權限請求時為空。需要 Claude Code v2.1.268 或更高版本。較早的版本可能會省略該欄位，因此如果您自己解析線路協議，請將遺失的欄位視為較舊的 CLI，而不是沒有待處理的證明。

698 758

699<h3 id="sdkcontrolinterruptresponse">759<h3 id="sdkcontrolinterruptresponse">

700 `SDKControlInterruptResponse`760 `SDKControlInterruptResponse`

705```typescript theme={null}765```typescript theme={null}

706type SDKControlInterruptResponse = {766type SDKControlInterruptResponse = {

707 still_queued: string[];767 still_queued: string[];

768 cancelled?: string[];

708};769};

709```770```

710 771

711`still_queued` 列出存活中斷的用戶消息的 UUID：仍在隊列中的消息，加上任何已出隊用於下一個轉數但尚未被中止到達的批次。除非您先取消它，否則每個都作為其自己的轉數在中斷後運行。使用收據決定是否重新發送任何內容；重新發送已列出的消息會產生重複轉數。772`still_queued` 列出中斷時待處理的使用者訊息的 UUID：仍在隊列中的訊息，加上任何 Claude Code 已從隊列中取出用於下一個轉數但尚未被中止到達的訊息。除非您先取消它，否則每個都作為其自己的轉數在中斷後執行。Claude Code 可以將多個合併為一個轉數。如果您在首個轉數啟動之前中斷，Claude Code 會在轉數啟動時立即中止它，該轉數中列出的訊息不會獲得回應。

773

774使用收據決定是否重新發送任何內容。已列出的訊息，如果您不取消它，無論是否獲得回應，都會進入對話，因此重新發送它會將其傳遞給 Claude 兩次。

712 775

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

714 777

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

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

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

718 781

719收據是在處理中斷時拍攝的快照，在乾淨中斷時，它在中斷轉數的 [`SDKResultMessage`](#sdkresultmessage) 之前到達。在該結果之後讀取收據而不是檢查隊列：循環立即啟動下一個排隊轉數，因此您在結果後檢查的隊列已經改變。782直接驅動 CLI 控制協議的客戶端，而不是通過 `interrupt()`，可以在 `interrupt` 控制請求上設置 `cancel_queued: true`。Claude Code v2.1.219 及更高版本在 [`SDKSystemMessage.capabilities`](#sdksystemmessage) 中使用 `interrupt_cancel_queued_v1` 功能公告支持；較舊的 CLI 會忽略該欄位並讓排隊訊息照常執行。這樣的中斷也會取消每個否則會在 `still_queued` 下列出的訊息：收據在 `cancelled` 下列出它們，`still_queued` 為空，它們都不執行。

783

784`cancelled` 列表帶著與 `still_queued` 相同的注意事項。`interrupt()` 方法永遠不會發送 `cancel_queued`，因此它解決的收據不帶 `cancelled`。

785

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

787

788<h3 id="sdkcontrolgetcontextusageresponse">

789 `SDKControlGetContextUsageResponse`

790</h3>

791

792[`getContextUsage()`](#query-object) 的返回類型。使用預設 `detail`，這是 Claude Code 在互動式會話中為 `/context` 命令呈現的相同有效負載，因此除了令牌計數外，它還帶著顯示欄位，例如 `color` 和 `gridRows`，Claude Code 使用這些欄位來繪製 `/context` 使用情況網格。

793

794方法的可選 `detail` 引數選擇 Claude Code 如何計算每個類別。使用預設 `'full'`，Claude Code 使用令牌計數 API 請求計算每個類別。傳遞 `{ detail: 'summary' }` 以從最後一個回應的使用情況和本地估計獲得答案。沒有令牌計數請求發出，每個類別的數字是近似的。`detail` 引數需要 Agent SDK v0.3.257 或更高版本。

795

796當您發送 `/context` 作為提示而不是呼叫方法時，Claude Code 會將 [`SDKContextUsage`](#sdkcontextusage) 有效負載附加到傳遞結果的助手訊息的 `context_usage` 欄位。該欄位需要 Agent SDK v0.3.232 或更高版本。

797

798```typescript theme={null}

799type SDKControlGetContextUsageResponse = {

800 categories: {

801 name: string;

802 tokens: number;

803 color: string;

804 isDeferred?: boolean;

805 }[];

806 totalTokens: number;

807 maxTokens: number;

808 rawMaxTokens: number;

809 percentage: number;

810 gridRows: {

811 color: string;

812 isFilled: boolean;

813 categoryName: string;

814 tokens: number;

815 percentage: number;

816 squareFullness: number;

817 }[][];

818 model: string;

819 memoryFiles: {

820 path: string;

821 type: string;

822 tokens: number;

823 }[];

824 mcpTools: {

825 name: string;

826 serverName: string;

827 tokens: number;

828 isLoaded?: boolean;

829 }[];

830 deferredBuiltinTools?: {

831 name: string;

832 tokens: number;

833 isLoaded: boolean;

834 }[];

835 systemTools?: {

836 name: string;

837 tokens: number;

838 }[];

839 systemPromptSections?: {

840 name: string;

841 tokens: number;

842 }[];

843 agents: {

844 agentType: string;

845 source: string;

846 tokens: number;

847 }[];

848 slashCommands?: {

849 totalCommands: number;

850 includedCommands: number;

851 tokens: number;

852 };

853 skills?: {

854 totalSkills: number;

855 includedSkills: number;

856 tokens: number;

857 skillFrontmatter: {

858 name: string;

859 source: string;

860 tokens: number;

861 }[];

862 };

863 autoCompactThreshold?: number;

864 isAutoCompactEnabled: boolean;

865 messageBreakdown?: {

866 toolCallTokens: number;

867 toolResultTokens: number;

868 attachmentTokens: number;

869 assistantMessageTokens: number;

870 userMessageTokens: number;

871 redirectedContextTokens: number;

872 unattributedTokens: number;

873 toolCallsByType: {

874 name: string;

875 callTokens: number;

876 resultTokens: number;

877 }[];

878 attachmentsByType: {

879 name: string;

880 tokens: number;

881 }[];

882 };

883 apiUsage: {

884 input_tokens: number;

885 output_tokens: number;

886 cache_creation_input_tokens: number;

887 cache_read_input_tokens: number;

888 } | null;

889};

890```

891

892從集合欄位讀取令牌歸屬：

893

894* `categories` 保存每個類別的總計。

895* `mcpTools` 和 `agents` 將令牌歸屬於個別 MCP 工具和 subagents。

896* `memoryFiles` 列出每個載入的記憶體檔案及其成本。

897* `skills.skillFrontmatter` 將 skill 列表的令牌歸屬於每個包含的 skill。每個 skill 的計數測量每個 skill 的列表條目，因為 Claude Code 實際發送它，可能比 skill 的完整 frontmatter 更短。比較 `skills.totalSkills` 與 `skills.includedSkills` 以查看每個發現的 skill 是否進入列表。

898

899`totalTokens` 是會話的目前上下文使用情況，`maxTokens` 是測量使用情況的視窗。該視窗是模型的上下文視窗，或當適用時較低的自動壓縮視窗。`rawMaxTokens` 帶著與 `maxTokens` 相同的值，`percentage` 是 `totalTokens` 作為該視窗的四捨五入百分比。

900

901Claude Code 將可選的 `deferredBuiltinTools`、`systemTools` 和 `systemPromptSections` 診斷保留為未設置，因此即使類型聲明它們，也應該期望它們不存在。

902

903<h3 id="sdkcontrolreadfileresponse">

904 `SDKControlReadFileResponse`

905</h3>

906

907[`readFile()`](#query-object) 的返回類型。

908

909```typescript theme={null}

910type SDKControlReadFileResponse = {

911 contents: string;

912 absPath: string;

913 truncated?: boolean;

914 encoding?: 'base64';

915};

916```

917

918`contents` 保存檔案文字，或當您要求 `encoding: 'base64'` 時的 base64 資料；回應的 `encoding` 欄位在該情況下設置為 `'base64'`。`absPath` 是解析的絕對路徑。`truncated` 在檔案長於 `maxBytes` 上限且內容在該限制處被切割時設置。

919

920<h4 id="what-readfile-can-read">

921 What `readFile()` can read

922</h4>

923

924`readFile()` 提供的檔案集比 Read 工具更窄：

925

926* 會話工作目錄之一內的常規檔案，例如 `cwd` 和 `additionalDirectories`

927* Claude Code 自己的一些檔案用於會話，例如工具結果

928

929Read 拒絕和詢問規則仍會阻止匹配的路徑，廣泛的 Read allow 規則不會向 `readFile()` 開啟檔案系統的其餘部分。對於任何其他內容，呼叫使用 `null` 進行解決。

930

931<h3 id="sdkcontrolreloadskillsresponse">

932 `SDKControlReloadSkillsResponse`

933</h3>

934

935[`reloadSkills()`](#query-object) 的返回類型。

936

937```typescript theme={null}

938type SDKControlReloadSkillsResponse = {

939 skills: SlashCommand[];

940};

941```

942

943`skills` 列出重新載入後可用的 skills，採用 `supportedCommands()` 返回的相同 [`SlashCommand`](#slashcommand) 形狀。

720 944

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

722 `AgentDefinition`946 `AgentDefinition`

723</h3>947</h3>

724 948

725以編程方式定義的子代理的配置。949以編程方式定義的 subagent 的配置。

726 950

727```typescript theme={null}951```typescript theme={null}

728type AgentDefinition = {952type AgentDefinition = {

743};967};

744```968```

745 969

746| 字段 | 必需 | 描述 |970| 欄位 | 必需 | 描述 |

747| :------------------------------------ | :- | :-------------------------------------------------------------------------------------------------------- |971| :------------------------------------ | :- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

748| `description` | 是 | 何時使用此代理的自然語言描述 |972| `description` | 是 | 何時使用此代理的自然語言描述 |

749| `tools` | 否 | 允許的工具名稱數組。如果省略，從父代理繼承所有工具。要將 Skills 預加載到代理的上下文中，請使用 `skills` 字段而不是在此處列出 `'Skill'` |973| `tools` | 否 | 允許的工具名稱陣列。如果省略，繼承 [tool available to subagents](/docs/zh-TW/sub-agents#available-tools) 的每個工具。要將 Skills 預載入到代理的上下文中，請使用 `skills` 欄位而不是在此處列出 `'Skill'` |

750| `disallowedTools` | 否 | 要為此代理明確禁止的工具名稱數組。MCP 服務器級別的模式也被接受：`mcp__server` 或 `mcp__server__*` 移除該服務器的每個工具，`mcp__*` 移除任何服務器的每個 MCP 工具 |974| `disallowedTools` | 否 | 要為此代理明確禁止的工具名稱陣列。MCP 伺服器級別的模式也被接受：`mcp__server` 或 `mcp__server__*` 移除該伺服器的每個工具，`mcp__*` 移除任何伺服器的每個 MCP 工具 |

751| `prompt` | 是 | 代理的系統提示 |975| `prompt` | 是 | 代理的系統提示 |

752| `model` | 否 | 此代理的模型覆蓋。接受別名如 `'fable'`、`'opus'`、`'sonnet'`、`'haiku'`、`'inherit'` 或完整模型 ID。如果省略或 `'inherit'`，使用主模型 |976| `model` | 否 | 此代理的模型覆蓋。接受別名如 `'fable'`、`'opus'`、`'sonnet'`、`'haiku'`、`'inherit'`，或完整模型 ID。`'inherit'` 使用主模型。當您省略它時，Claude Code 在 [subagent model order](/docs/zh-TW/sub-agents#choose-a-model) 中選擇模型 |

753| `mcpServers` | 否 | 此代理可用的 MCP 服務器規範 |977| `mcpServers` | 否 | 此代理可用的 MCP 伺服器規範 |

754| `skills` | 否 | 要預加載到代理上下文中的 skill 名稱數組 |978| `skills` | 否 | 要預載入到代理上下文中的 skill 名稱陣列 |

755| `initialPrompt` | 否 | 當此代理作為主線程代理運行時，自動提交為第一個用戶轉數 |979| `initialPrompt` | 否 | 當此代理作為主線程代理執行時，自動提交為首個使用者轉數 |

756| `maxTurns` | 否 | 最大代理轉數（API 往返），然後停止 |980| `maxTurns` | 否 | 最大代理轉數（API 往返），然後停止 |

757| `background` | 否 | 當調用時，將此代理作為非阻塞後台任務運行 |981| `background` | 否 | 當調用時，將此代理作為非阻止背景任務執行 |

758| `memory` | 否 | 此代理的內存源：`'user'`、`'project'` 或 `'local'` |982| `memory` | 否 | 此代理的記憶體來源：`'user'`、`'project'` 或 `'local'` |

759| `effort` | 否 | 此代理的推理努力級別。接受命名級別或整數 |983| `effort` | 否 | 此代理的推理努力級別。接受命名級別或整數 |

760| `permissionMode` | 否 | 此代理內工具執行的權限模式。見 [`PermissionMode`](#permissionmode) |984| `permissionMode` | 否 | 此代理內工具執行的權限模式。[subagent inheritance rules](/docs/zh-TW/agent-sdk/permissions#available-modes) 決定何時適用。見 [`PermissionMode`](#permissionmode) |

761| `criticalSystemReminder_EXPERIMENTAL` | 否 | 實驗性：添加到系統提示的關鍵提醒 |985| `criticalSystemReminder_EXPERIMENTAL` | 否 | 實驗性：添加到系統提示的關鍵提醒 |

762 986

763<h3 id="agentmcpserverspec">987<h3 id="agentmcpserverspec">

764 `AgentMcpServerSpec`988 `AgentMcpServerSpec`

765</h3>989</h3>

766 990

767指定子代理可用的 MCP 服務器。可以是服務器名稱（字符串，引用父代理 `mcpServers` 配置中的服務器）或內聯服務器配置記錄，將服務器名稱映射到配置。991指定 subagent 可用的 MCP 伺服器。可以是伺服器名稱（字串，引用父代理 `mcpServers` 配置中的伺服器）或內聯伺服器配置記錄，將伺服器名稱映射到配置。

768 992

769```typescript theme={null}993```typescript theme={null}

770type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;994type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;

776 `SettingSource`1000 `SettingSource`

777</h3>1001</h3>

778 1002

779控制 SDK 從哪些基於文件系統的配置源加載設置。1003控制 SDK 從哪些基於檔案系統的配置來源載入設定。

780 1004

781```typescript theme={null}1005```typescript theme={null}

782type SettingSource = "user" | "project" | "local";1006type SettingSource = "user" | "project" | "local";

783```1007```

784 1008

785| 值 | 描述 | 位置 |1009| 值 | 描述 | 位置 |

786| :---------- | :----------------- | :---------------------------- |1010| :---------- | :----------------------------------------- | :---------------------------- |

790 1014

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

792 Default behavior1016 Default behavior

793</h4>1017</h4>

794 1018

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

796 1020

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

798 Why use settingSources1022 Why use settingSources

799</h4>1023</h4>

800 1024

801**禁用文件系統設置：**1025**禁用檔案系統設定：**

802 1026

803```typescript theme={null}1027```typescript theme={null}

804// 不從磁盤加載用戶、項目或本地設置1028import { query } from "@anthropic-ai/claude-agent-sdk";

1029

1030// 不從磁碟載入使用者、專案或本地設定

805const result = query({1031const result = query({

806 prompt: "Analyze this code",1032 prompt: "Analyze this code",

807 options: { settingSources: [] }1033 options: { settingSources: [] }

808});1034});

809```1035```

810 1036

811**明確加載所有文件系統設置：**1037**僅載入特定設定來源：**

812 1038

813```typescript theme={null}1039```typescript theme={null}

814const result = query({1040import { query } from "@anthropic-ai/claude-agent-sdk";

815 prompt: "Analyze this code",

816 options: {

817 settingSources: ["user", "project", "local"] // 加載所有設置

818 }

819});

820```

~~821~~

822**僅加載特定設置源：**

823 1041

824```typescript theme={null}1042// 僅載入專案設定，忽略使用者和本地

825// 僅加載項目設置，忽略用戶和本地

826const result = query({1043const result = query({

827 prompt: "Run CI checks",1044 prompt: "Run CI checks",

828 options: {1045 options: {

831});1048});

832```1049```

833 1050

834**測試和 CI 環境：**1051要載入 CLAUDE.md 專案指令，請在 `settingSources` 中包含 `"project"`。見 [Modify system prompts](/docs/zh-TW/agent-sdk/modifying-system-prompts#claude-md-files-for-project-level-instructions) 了解 CLAUDE.md 載入如何與系統提示選項互動。

~~835~~

836```typescript theme={null}

837// 通過排除本地設置確保 CI 中的一致行為

838const result = query({

839 prompt: "Run tests",

840 options: {

841 settingSources: ["project"], // 僅團隊共享設置

842 permissionMode: "bypassPermissions"

843 }

844});

845```

~~846~~

847**僅 SDK 應用程序：**

~~848~~

849```typescript theme={null}

850// 以編程方式定義所有內容。

851// 傳遞 [] 以選擇退出文件系統設置源。

852const result = query({

853 prompt: "Review this PR",

854 options: {

855 settingSources: [],

856 agents: {

857 /* ... */

858 },

859 mcpServers: {

860 /* ... */

861 },

862 allowedTools: ["Read", "Grep", "Glob"]

863 }

864});

865```

~~866~~

867**加載 CLAUDE.md 項目指令：**

~~868~~

869```typescript theme={null}

870// 加載項目設置以包括 CLAUDE.md 文件

871const result = query({

872 prompt: "Add a new feature following project conventions",

873 options: {

874 systemPrompt: {

875 type: "preset",

876 preset: "claude_code" // 使用 Claude Code 的系統提示

877 },

878 settingSources: ["project"], // 從項目目錄加載 CLAUDE.md

879 allowedTools: ["Read", "Write", "Edit"]

880 }

881});

882```

883 1052

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

885 Settings precedence1054 Settings precedence

886</h4>1055</h4>

887 1056

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

889 1058

8901. 本地設置（`.claude/settings.local.json`）10591. 本地設定（`.claude/settings.local.json`）

8912. 項目設置（`.claude/settings.json`）10602. 專案設定（`.claude/settings.json`）

8923. 用戶設置（`~/.claude/settings.json`）10613. 使用者設定（`~/.claude/settings.json`）

893 1062

894編程選項（如 `agents`、`allowedTools` 和 `settings`）覆蓋用戶、項目和本地文件系統設置。託管策略設置優先於編程選項。1063編程選項，例如 `agents`、`allowedTools` 和 `settings`，覆蓋使用者、專案和本地檔案系統設定。受管策略設定優先於編程選項。

895 1064

896<h3 id="permissionmode">1065<h3 id="permissionmode">

897 `PermissionMode`1066 `PermissionMode`

900```typescript theme={null}1069```typescript theme={null}

901type PermissionMode =1070type PermissionMode =

902 | "default" // 標準權限行為1071 | "default" // 標準權限行為

903 | "acceptEdits" // 自動接受文件編輯1072 | "acceptEdits" // 自動接受檔案編輯

904 | "bypassPermissions" // 繞過權限檢查；明確要求規則仍然提示1073 | "bypassPermissions" // 繞過權限檢查；明確詢問規則仍然提示

905 | "plan" // Plan Mode - 無編輯探索1074 | "plan" // Plan Mode - 無編輯探索

906 | "dontAsk" // 不提示權限，如果未預批准則拒絕1075 | "dontAsk" // 不提示權限，如果未預批准則拒絕

907 | "auto"; // 使用模型分類器批准或拒絕每個工具調用1076 | "auto"; // 模型分類器批准或拒絕權限提示

908```1077```

909 1078

910<h3 id="canusetool">1079<h3 id="canusetool">

913 1082

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

915 1084

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

917 1086

918`AskUserQuestion`、標記為 [`requiresUserInteraction`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP tools 和 connector tools [您的組織設置為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools) 即使 allow 規則匹配也會到達函數。在 `dontAsk` 模式下這些調用會被拒絕，無需調用它。1087Allow 規則不會預批准 [actions no mode auto-approves](/docs/zh-TW/permission-modes#actions-no-mode-auto-approves)；見 [How permissions are evaluated](/docs/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated) 了解其中哪些到達回調，以及在 `dontAsk` 和 `auto` 模式中發生什麼。

919 1088

920```typescript theme={null}1089```typescript theme={null}

921type CanUseTool = (1090type CanUseTool = (

934```1103```

935 1104

936| 選項 | 類型 | 描述 |1105| 選項 | 類型 | 描述 |

937| :--------------- | :------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1106| :--------------- | :------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

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

945 1114

946回調通常通過返回 [`PermissionResult`](#permissionresult) 來解決請求，SDK 將其寫回其傳輸作為 `control_response`。僅當您的應用程序已通過其自己的通道為此請求發送 `control_response`（回顯 `requestId`）時才返回 `null`；SDK 然後跳過將響應寫入其傳輸。在任何其他情況下返回 `null` 會使工具調用無限期被阻止，因為永遠不會發送 `control_response` 且權限提示不會超時。1115回調通常通過返回 [`PermissionResult`](#permissionresult) 來解決請求，SDK 將其寫回其傳輸作為 `control_response`。僅當您的應用程式已通過其自己的通道為此請求發送 `control_response`（回顯 `requestId`）時才返回 `null`；SDK 然後跳過將回應寫入其傳輸。在任何其他情況下返回 `null` 會使工具呼叫無限期被阻止，因為永遠不會發送 `control_response` 且權限提示不會逾時。

947 1116

948`requestId` 選項和 `null` 返回值需要 Claude Code v2.1.199 或更高版本。1117`requestId` 選項和 `null` 返回值需要 Claude Code v2.1.199 或更高版本。

949 1118

983};1152};

984```1153```

985 1154

986| 字段 | 類型 | 描述 |1155| 欄位 | 類型 | 描述 |

987| :------------------------------ | :--------------------- | :---------------------------------------------------------------------------------------------------------------- |1156| :------------------------------ | :--------------------- | :---------------------------------------------------------------------------------------------------------------- |

989 1158

990<h3 id="mcpserverconfig">1159<h3 id="mcpserverconfig">

991 `McpServerConfig`1160 `McpServerConfig`

992</h3>1161</h3>

993 1162

994MCP 服務器的配置。1163MCP 伺服器的配置。

995 1164

996```typescript theme={null}1165```typescript theme={null}

997type McpServerConfig =1166type McpServerConfig =

1046type McpSdkServerConfigWithInstance = {1215type McpSdkServerConfigWithInstance = {

1047 type: "sdk";1216 type: "sdk";

1048 name: string;1217 name: string;

1218 timeout?: number;

1049 instance: McpServer;1219 instance: McpServer;

1050};1220};

1051```1221```

1066 `SdkPluginConfig`1236 `SdkPluginConfig`

1067</h3>1237</h3>

1068 1238

1069SDK 中加載 plugins 的配置。1239SDK 中載入 plugins 的配置。

1070 1240

1071```typescript theme={null}1241```typescript theme={null}

1072type SdkPluginConfig = {1242type SdkPluginConfig = {

1076};1246};

1077```1247```

1078 1248

1079| 字段 | 類型 | 描述 |1249| 欄位 | 類型 | 描述 |

1080| :----------------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------------ |1250| :----------------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------------ |

1083| `skipMcpDiscovery` | `boolean` | 當為 `true` 時，SDK 從此 plugin 加載 skills、hooks、agents 和 commands，但不讀取其 `.mcp.json` 或 manifest `mcpServers`。當您的應用程序擁有 plugin 的 MCP 連接時設置此項。 |1253| `skipMcpDiscovery` | `boolean` | 當為 `true` 時，SDK 從此 plugin 載入 skills、hooks、agents 和 commands，但不讀取其 `.mcp.json` 或 manifest `mcpServers`。當您的應用程式擁有 plugin 的 MCP 連接時設置此項。 |

1084 1254

1085**示例：**1255**範例：**

1086 1256

1087```typescript theme={null}1257```typescript theme={null}

1088plugins: [1258plugins: [

1091];1261];

1092```1262```

1093 1263

1094有關創建和使用 plugins 的完整信息，見 [Plugins](/docs/zh-TW/agent-sdk/plugins)。1264有關創建和使用 plugins 的完整資訊，見 [Plugins](/docs/zh-TW/agent-sdk/plugins)。

1095 1265

1096<h2 id="message-types">1266<h2 id="message-types">

1097 消息類型1267 消息類型

1157 message: BetaMessage; // 來自 Anthropic SDK1327 message: BetaMessage; // 來自 Anthropic SDK

1158 parent_tool_use_id: string | null;1328 parent_tool_use_id: string | null;

1159 error?: SDKAssistantMessageError;1329 error?: SDKAssistantMessageError;

1330 aborted?: true;

1331 timestamp?: string;

1332 context_usage?: SDKContextUsage;

1333 user_message_uuid?: string;

1334 user_message_uuids?: string[];

1160};1335};

1161```1336```

1162 1337

1163`message` 字段是來自 Anthropic SDK 的 [`BetaMessage`](https://platform.claude.com/docs/zh-TW/api/messages/create)。它包括 `id`、`content`、`model`、`stop_reason` 和 `usage` 等字段。1338`message` 字段是來自 Anthropic SDK 的 [`BetaMessage`](https://platform.claude.com/docs/zh-TW/api/messages/create)。它包括 `id`、`content`、`model`、`stop_reason` 和 `usage` 等字段。

1164 1339

1165`SDKAssistantMessageError` 是以下之一：`'authentication_failed'`、`'oauth_org_not_allowed'`、`'billing_error'`、`'rate_limit'`、`'overloaded'`、`'invalid_request'`、`'model_not_found'`、`'server_error'`、`'max_output_tokens'` 或 `'unknown'`。`'model_not_found'` 表示選定的模型不存在或對您的帳戶或部署不可用。`'overloaded'` 表示 API 返回了 529，因為伺服器已滿載，與 `'rate_limit'` 相對，後者是針對您配額的 429。1340`SDKAssistantMessageError` 是以下之一：`'authentication_failed'`、`'oauth_org_not_allowed'`、`'account_on_hold'`、`'billing_error'`、`'rate_limit'`、`'overloaded'`、`'invalid_request'`、`'model_not_found'`、`'server_error'`、`'max_output_tokens'`、`'cloud_credential_error'` 或 `'unknown'`。其中四個值的含義超出了它們的名稱：

1341

1342* `'model_not_found'`：選定的模型不存在或對您的帳戶或部署不可用

1343* `'overloaded'`：API 返回了 529，因為伺服器已滿載，與 `'rate_limit'` 相對，後者是針對您配額的 429

1344* `'account_on_hold'`：[您的帳戶已被凍結](/docs/zh-TW/errors#your-account-is-on-hold)

1345* `'cloud_credential_error'`：Claude Code 無法在其運行的機器上獲得可用的 AWS 或 Google Cloud 認證，因此沒有請求到達雲端提供商。通常的原因是在該機器上過期或從未完成的雲端登入，儘管暫時無法到達的認證服務會報告相同的值。請參閱[無法載入 AWS 或 Google Cloud 認證](/docs/zh-TW/errors#could-not-load-aws-or-google-cloud-credentials)。需要 TypeScript Agent SDK v0.3.267 或更高版本，其中包含 Claude Code v2.1.267

1346

1347當中斷或中止在流完成之前截斷助手消息時，`aborted` 為 `true`：消息沒有 `stop_reason`，內容可能在中間詞結束。該字段在正常完成的消息上不存在。它需要 Agent SDK v0.3.214 或更高版本。

1348

1349Claude Code 在轉數的第一個助手消息上設置 `user_message_uuid` 和 `user_message_uuids`，條件在 [`user_message_uuid`](#user_message_uuid) 中。

1350

1351`timestamp` 是 ISO 8601 時間，表示消息內容在產生它的程序上完成生成的時間。該值來自該機器的時鐘，因此僅用於顯示，不要按它排序消息。一個 API 轉數可以產生多個共享 `message.id` 的助手消息，每個都有自己的 `timestamp`。當字段不存在時，回退到您收到消息的時間。

1352

1353`context_usage` 是 `/context` 報告的結構化副本，類型為 [`SDKContextUsage`](#sdkcontextusage)，需要 Agent SDK v0.3.232 或更高版本。當您發送 `/context` 作為提示時，Claude Code 將報告作為助手消息傳遞，其 `message.content` 保存 markdown 表格，並將 `context_usage` 附加到同一消息。Claude Code 不在任何其他助手消息上設置該字段，較早的版本傳遞 `/context` 表格而不設置它，因此當字段存在時從字段讀取分解，當不存在時回退到 markdown 文本。

1166 1354

1167<h3 id="sdkusermessage">1355<h3 id="sdkusermessage">

1168 `SDKUserMessage`1356 `SDKUserMessage`

1169</h3>1357</h3>

1170 1358

1171用戶輸入消息。1359使用者輸入消息。

1172 1360

1173```typescript theme={null}1361```typescript theme={null}

1174type SDKUserMessage = {1362type SDKUserMessage = {

1184};1372};

1185```1373```

1186 1374

1187將 `shouldQuery` 設置為 `false` 以將消息附加到記錄而不觸發助手轉數。消息被保留並合併到下一個觸發轉數的用戶消息中。使用此方法注入上下文，例如您在帶外運行的命令的輸出，而無需在其上花費模型調用。1375將 `shouldQuery` 設置為 `false` 以將消息附加到記錄而不觸發助手轉數。消息被保留並合併到下一個觸發轉數的使用者消息中。使用此方法注入上下文，例如您在帶外運行的命令的輸出，而無需在其上花費模型調用。

1188 1376

1189在攜帶 `tool_result` 塊的消息上，`tool_use_result` 是工具的結構化輸出物件，而不是發送給模型的文本。其形狀取決於匹配 `tool_use` 塊命名的工具，因此該字段的類型為 `unknown`；內建形狀列在[工具輸出類型](#tool-output-types)下。1377在攜帶 `tool_result` 塊的消息上，`tool_use_result` 是工具的結構化輸出物件，而不是發送給模型的文本。其形狀取決於匹配 `tool_use` 塊命名的工具，因此該字段的類型為 `unknown`；內建形狀列在[工具輸出類型](#tool-output-types)下。

1190 1378

1191對於 `Agent` 工具，`tool_use_result` 是 [`AgentOutput`](#agent-2)。在 `completed` 結果上，`content` 保存子代理的報告，不包含 Claude Code 附加到 `tool_result` 文本的代理 ID 和使用情況尾部，因此應從 `tool_use_result` 呈現，而不是解析該文本。1379對於 `Agent` 工具，`tool_use_result` 是 [`AgentOutput`](#agent-2)。在 `completed` 結果上，`content` 保存子代理的報告，不包含 Claude Code 附加到 `tool_result` 文本的代理 ID 和使用情況尾部，因此應從 `tool_use_result` 呈現，而不是解析該文本。

1192 1380

1381對於其結果包含 `resource_link` 塊的 MCP 工具，`tool_use_result` 是一個物件，其中包含 [`SDKMcpResourceLink`](#sdkmcpresourcelink) 項目的 `resourceLinks` 陣列。Claude 將每個連結作為 `tool_result` 塊中的一行文本接收，因此讀取 `resourceLinks` 以呈現伺服器返回的檔案，而不是解析該文本。Claude Code 在結果沒有連結時省略 `resourceLinks`，在來自子代理的結果上省略，每個結果最多保留 50 個連結，並在陣列達到 64 KiB 序列化 JSON 後停止添加連結。`resourceLinks` 需要 Agent SDK v0.3.257 或更高版本。

1382

1193<h3 id="sdkusermessagereplay">1383<h3 id="sdkusermessagereplay">

1194 `SDKUserMessageReplay`1384 `SDKUserMessageReplay`

1195</h3>1385</h3>

1196 1386

1197帶有必需 UUID 的重放用戶消息。1387帶有必需 UUID 的重放使用者消息。

1198 1388

1199```typescript theme={null}1389```typescript theme={null}

1200type SDKUserMessageReplay = {1390type SDKUserMessageReplay = {

1210};1400};

1211```1401```

1212 1402

1213從會話外部注入的用戶轉數，其 [`origin`](#sdkmessageorigin) 類型為 `peer` 或 `channel`，無論是在活躍轉數期間傳遞還是在會話閒置時啟動新轉數，都會作為重放到達流。在 v2.1.207 之前，在會話閒置時傳遞的注入轉數在流上不產生任何消息，僅在您重新讀取記錄時出現。1403從會話外部注入的使用者轉數，其 [`origin`](#sdkmessageorigin) 類型為 `peer` 或 `channel`，無論是在活躍轉數期間傳遞還是在會話閒置時啟動新轉數，都會作為重放到達流。在 v2.1.207 之前，在會話閒置時傳遞的注入轉數在流上不產生任何消息，僅在您重新讀取記錄時出現。

1214 1404

1215<h3 id="sdkresultmessage">1405<h3 id="sdkresultmessage">

1216 `SDKResultMessage`1406 `SDKResultMessage`

1234 stop_reason: string | null;1424 stop_reason: string | null;

1235 ttft_ms?: number;1425 ttft_ms?: number;

1236 ttft_stream_ms?: number;1426 ttft_stream_ms?: number;

1427 user_message_uuid?: string;

1428 user_message_uuids?: string[];

1429 request_sent_wall_ms?: number;

1430 first_content_frame_ms?: number;

1431 first_stream_post_ms?: number;

1432 first_stream_post_ack_ms?: number;

1433 first_stream_post_wall_ms?: number;

1237 total_cost_usd: number;1434 total_cost_usd: number;

1238 usage: NonNullableUsage;1435 usage: NonNullableUsage;

1239 modelUsage: { [modelName: string]: ModelUsage };1436 modelUsage: { [modelName: string]: ModelUsage };

1240 permission_denials: SDKPermissionDenial[];1437 permission_denials: SDKPermissionDenial[];

1438 queued_turn_count?: number;

1241 structured_output?: unknown;1439 structured_output?: unknown;

1242 deferred_tool_use?: { id: string; name: string; input: Record<string, unknown> };1440 deferred_tool_use?: { id: string; name: string; input: Record<string, unknown> };

1243 terminal_reason?: TerminalReason;1441 terminal_reason?: TerminalReason;

1244 fast_mode_state?: FastModeState;1442 fast_mode_state?: FastModeState;

1443 fast_mode_disabled_reason?: FastModeDisabledReason;

1245 origin?: SDKMessageOrigin;1444 origin?: SDKMessageOrigin;

1246 }1445 }

1247 | {1446 | {

1262 usage: NonNullableUsage;1461 usage: NonNullableUsage;

1263 modelUsage: { [modelName: string]: ModelUsage };1462 modelUsage: { [modelName: string]: ModelUsage };

1264 permission_denials: SDKPermissionDenial[];1463 permission_denials: SDKPermissionDenial[];

1464 queued_turn_count?: number;

1265 errors: string[];1465 errors: string[];

1466 user_message_uuid?: string;

1467 user_message_uuids?: string[];

1266 terminal_reason?: TerminalReason;1468 terminal_reason?: TerminalReason;

1267 fast_mode_state?: FastModeState;1469 fast_mode_state?: FastModeState;

1470 fast_mode_disabled_reason?: FastModeDisabledReason;

1268 origin?: SDKMessageOrigin;1471 origin?: SDKMessageOrigin;

1269 };1472 };

1270```1473```

1271 1474

1272結果上的多個字段除了 `subtype` 之外還攜帶診斷詳細信息：1475結果上的多個字段除了 `subtype` 之外還攜帶診斷詳細資訊：

1273 1476

1274* `api_error_status`：終止對話的 API 錯誤的 HTTP 狀態碼。當轉數在沒有 API 錯誤的情況下結束時，不存在或為 `null`。1477* `api_error_status`：終止對話的 API 錯誤的 HTTP 狀態碼。當轉數在沒有 API 錯誤的情況下結束時，不存在或為 `null`。

1275* `ttft_ms`：首個令牌的時間（毫秒），在第一個完整助手消息到達時測量。僅在成功分支上出現。1478* `ttft_ms`：首個令牌的時間（毫秒），在第一個完整助手消息到達時測量。僅在成功分支上出現。

1276* `ttft_stream_ms`：直到第一個 `message_start` 流事件的時間（毫秒），當響應流打開時。低於 `ttft_ms`；兩者之間的差距是流式傳輸第一條消息所花費的時間。僅在成功分支上出現。1479* `ttft_stream_ms`：直到第一個 `message_start` 流事件的時間（毫秒），當響應流打開時。低於 `ttft_ms`；兩者之間的差距是流式傳輸第一條消息所花費的時間。僅在成功分支上出現。

1277* `terminal_reason`：循環結束的原因。為 `"completed"`、`"max_turns"`、`"tool_deferred"`、`"aborted_streaming"`、`"aborted_tools"`、`"hook_stopped"`、`"stop_hook_prevented"`、`"background_requested"`、`"blocking_limit"`、`"rapid_refill_breaker"`、`"prompt_too_long"`、`"image_error"`、`"model_error"`、`"api_error"`、`"malformed_tool_use_exhausted"`、`"budget_exhausted"`、`"structured_output_retry_exhausted"`、`"tool_deferred_unavailable"` 或 `"turn_setup_failed"` 之一。1480* `user_message_uuid`：此轉數回答的您發送的消息的 `uuid`。請參閱 [`user_message_uuid`](#user_message_uuid) 以了解哪些結果攜帶它。

1481* `user_message_uuids`：Claude Code 在此轉數中回答的您發送的每條消息的 `uuid`。請參閱 [`user_message_uuids`](#user_message_uuids)。

1482* `request_sent_wall_ms`：Claude Code 分派 API 請求的紀元毫秒，用於與伺服器端時間戳記的連接。僅與 [`user_message_uuid`](#user_message_uuid) 一起出現，在成功結果上，其中 `is_error` 為 false，且轉數發送了 API 請求。

1483* `first_content_frame_ms`：直到第一個 `content_block_start` 或 `content_block_delta` 流事件的時間（毫秒），將思考塊計為內容。僅在成功分支上出現，當 `is_error` 為 false 時。需要 Agent SDK v0.3.260 或更高版本。

1484* `first_stream_post_ms`、`first_stream_post_ack_ms`、`first_stream_post_wall_ms`：上傳轉數第一個流事件的時序。Claude Code 僅在它流式傳輸到 claude.ai 的會話中記錄它們，例如[雲端會話](/docs/zh-TW/claude-code-on-the-web)，而 `query()` 產生的結果不攜帶它們。需要 Agent SDK v0.3.260 或更高版本。

1485* `usage`：僅限主代理迴圈。排除子代理和輔助模型調用，在流式輸入會話中按轉數計算。對於令牌/成本會計，優先使用 `modelUsage`。

1486* `modelUsage`：在此 `query()` 調用期間通過查詢管道進行的每個模型調用的每模型總計，包括主迴圈、子代理和內部調用（例如壓縮和 Workflow 代理）。該管道外的輔助調用（例如權限分類器和令牌計數請求）被排除。在流式輸入會話中，總計在轉數間累積，因此讀取最新結果而不是在結果間求和。請參閱[在流式輸入模式中追蹤成本](/docs/zh-TW/agent-sdk/cost-tracking#track-costs-in-streaming-input-mode)以了解重置，以及[在會話崩潰後恢復總計](/docs/zh-TW/agent-sdk/cost-tracking#recover-totals-after-a-session-crash)以了解歸零結果。

1487* `total_cost_usd`：此 `query()` 調用的累積估計成本（美元），涵蓋與 `modelUsage` 相同的調用並在相同點重置。這是一個估計值，不是帳單聲明。請參閱[追蹤成本和使用情況](/docs/zh-TW/agent-sdk/cost-tracking)以了解準確性注意事項。

1488* `queued_turn_count`：您發送的帶有 `origin: { kind: "human" }` 的消息數量，在 Claude Code 產生結果時仍在等待。請參閱 [`queued_turn_count`](#queued_turn_count) 以了解 `0` 和缺少的字段告訴您什麼。

1489* `terminal_reason`：迴圈結束的原因。為 `"completed"`、`"max_turns"`、`"tool_deferred"`、`"aborted_streaming"`、`"aborted_tools"`、`"hook_stopped"`、`"stop_hook_prevented"`、`"background_requested"`、`"blocking_limit"`、`"rapid_refill_breaker"`、`"prompt_too_long"`、`"image_error"`、`"model_error"`、`"api_error"`、`"malformed_tool_use_exhausted"`、`"budget_exhausted"`、`"structured_output_retry_exhausted"`、`"tool_deferred_unavailable"` 或 `"turn_setup_failed"` 之一。

1278* `fast_mode_state`：為 `"on"`、`"off"` 或 `"cooldown"` 之一。1490* `fast_mode_state`：為 `"on"`、`"off"` 或 `"cooldown"` 之一。

1491* `fast_mode_disabled_reason`：為什麼[快速模式](/docs/zh-TW/fast-mode)現在不可用。當沒有任何東西阻止快速模式時不存在，儘管請求仍可能以標準速度運行。在快速模式速率限制後的冷卻期間，Claude Code 報告 `fast_mode_state: "cooldown"` 且沒有原因代碼，並在冷卻期過期時重新啟用快速模式。需要 Claude Code v2.1.219 或更高版本。

1279 1492

1280`origin` 字段轉發觸發此結果的用戶消息的 [`SDKMessageOrigin`](#sdkmessageorigin)。當後台任務完成且 SDK 注入合成後續轉數時，生成的 `SDKResultMessage` 攜帶 `origin: { kind: "task-notification" }`。檢查此字段以區分回答您的提示的結果與為後台任務後續發出的結果，以便您可以路由或抑制後者。對於在任何用戶轉數之前發出的結果（例如啟動錯誤），該字段不存在。1493使用原因代碼在您自己的 UI 中解釋為什麼快速模式已關閉，而不是重新推導可用性。每個代碼命名阻止快速模式的檢查：

1281 1494

1282當 `PreToolUse` hook 返回 `permissionDecision: "defer"` 時，結果具有 `stop_reason: "tool_deferred"` 和 `deferred_tool_use` 攜帶待處理工具的 `id`、`name` 和 `input`。讀取此字段以在您自己的 UI 中顯示請求，然後使用相同的 `session_id` 恢復以繼續。有關完整往返，請參閱[稍後延遲工具調用](/docs/zh-TW/hooks#defer-a-tool-call-for-later)。1495| 原因代碼 | 含義 |

1496| ---------------------- | ------------------------------------------------------------------------------------------------------------ |

1497| `free` | 帳戶沒有快速模式所需的付費訂閱或使用額度 |

1498| `preference` | 組織已禁用快速模式 |

1499| `extra_usage_disabled` | 帳戶已關閉使用額度 |

1500| `network_error` | [可用性檢查](/docs/zh-TW/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)無法到達 `api.anthropic.com` |

1501| `unknown` | Claude Code 無法確定可用性 |

1502| `not_first_party` | 會話使用 Anthropic API 以外的提供商 |

1503| `disabled_by_env` | [`CLAUDE_CODE_DISABLE_FAST_MODE`](/docs/zh-TW/env-vars) 已設置 |

1504| `model_not_allowed` | 快速模式 Opus 模型不在組織的 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection) 允許清單中 |

1505| `sdk_opt_in_required` | 會話尚未選擇加入快速模式：在 [`settings`](#options) 選項中傳遞 `fastMode: true` 或通過 [`applyFlagSettings()`](#applyflagsettings) |

1506| `pending` | 可用性檢查尚未完成 |

1507

1508相同的字段對出現在 [`SDKSystemMessage`](#sdksystemmessage) 和 [`SDKControlInitializeResponse`](#sdkcontrolinitializeresponse) 上，因此您可以在第一個轉數之前讀取快速模式狀態。

1509

1510`origin` 字段轉發觸發此結果的使用者消息的 [`SDKMessageOrigin`](#sdkmessageorigin)。當 SDK 注入合成後續轉數（例如針對完成的背景任務）時，生成的 `SDKResultMessage` 攜帶 `origin: { kind: "task-notification" }`。例程的觸發器已觸發且伺服器驗證的來自您其他會話的消息也會到達此類型，每個都帶有[任務通知子類型](#task-notification-subkinds)中描述的 `subkind`。檢查 `kind` 以區分回答您的提示的結果與注入的後續，然後再路由或抑制它們。

1511

1512該字段對於在任何使用者轉數之前發出的結果（例如啟動錯誤）不存在。

1513

1514當 `PreToolUse` hook 返回 `permissionDecision: "defer"` 時，結果具有 `stop_reason: "tool_deferred"` 和 `deferred_tool_use` 攜帶待處理工具的 `id`、`name` 和 `input`。讀取此字段以在您自己的 UI 中顯示請求，然後使用相同的 `session_id` 恢復以繼續。請參閱[稍後延遲工具調用](/docs/zh-TW/hooks#defer-a-tool-call-for-later)以了解完整往返。

1515

1516<h4 id="user_message_uuid">

1517 `user_message_uuid`

1518</h4>

1519

1520此轉數回答的 [`SDKUserMessage`](#sdkusermessage) 的 `uuid`，回顯以便您可以將 Claude Code 的回覆與您發送的消息相匹配。Claude Code 僅在您在消息上設置 `uuid` 時才回顯 `uuid`。該字段在 `SDKUserMessage` 上是可選的，傳遞給 `query()` 的字符串提示不攜帶任何。

1521

1522轉數回答的消息取決於轉數如何開始：

1523

1524* **您發送的常規消息**，即沒有 `isSynthetic: true` 的消息：轉數在其整個運行中回答該消息。當您發送多條消息時，Claude Code 可以將它們合併為一個轉數，該字段然後僅攜帶最後一條消息的 `uuid`。要將回覆與任何合併的消息相匹配，請使用 [`user_message_uuids`](#user_message_uuids)。

1525* **您發送的帶有 `isSynthetic: true` 的消息**：轉數最初回答該消息。如果 Claude Code 在工具調用之間拾取您的常規消息，轉數從那時起回答拾取的消息。回顯合成消息的 `uuid` 需要 Agent SDK v0.3.265 或更高版本；較早的版本在合成轉數上不回顯任何內容。

1526* **Claude Code 自己生成的提示**，例如在會話重新啟動後繼續中斷工作的轉數：轉數最初不回答您的任何消息，其幀不攜帶任何回顯。如果 Claude Code 在工具調用之間拾取您的常規消息，轉數從那時起回答該消息。拾取回顯需要 Agent SDK v0.3.265 或更高版本；較早的版本在這些轉數上不回顯任何內容。

1527

1528Claude Code 在三種幀上回顯回答的消息的 `uuid`：

1529

1530* **結果**：回答您發送的消息的轉數的每個結果。在 Agent SDK v0.3.265 或更高版本上，每個這樣的結果都攜帶它。在 v0.3.265 之前，常規消息啟動的轉數的成功結果在轉數未發送 API 請求或以延遲工具調用結束時缺少它。在 v0.3.246 之前，錯誤結果也缺少它，在 v0.3.216 之前每個結果都缺少它。

1531* **轉數的第一個回覆**：第一個[助手消息](#sdkassistantmessage)，或使用 `includePartialMessages` 時第一個[流事件](#sdkpartialassistantmessage)，其 `event.type` 不是 `ping`，因此您可以在結果到達之前綁定回覆。當轉數不流式傳輸任何內容時，Claude Code 改為在第一個助手消息上設置它。第一個回覆回顯需要 Agent SDK v0.3.246 或更高版本。當轉數回答的消息在中途改變時，變更後的第一個回覆也攜帶該字段，在 Agent SDK v0.3.265 或更高版本上；較早的版本在每個轉數上設置一個回覆幀。

1532* **轉數的每個 [`thinking_tokens`](#sdkthinkingtokensmessage) 幀**：因此您可以將思考進度歸因於您發送的消息，而無需等待轉數的第一個回覆。需要 Agent SDK v0.3.260 或更高版本。

1533

1534Claude Code 在這些情況下省略該字段：

1535

1536* 除了那些第一個回覆之外的回覆幀

1537* 子代理幀

1538* 回答沒有 `uuid` 的消息的轉數：轉數回答了您發送的沒有 `uuid` 的消息，或 Claude Code 啟動了轉數本身並拾取了沒有 `uuid` 的常規消息

1539* 回答您未發送的消息的結果，例如崩潰的工作程序進程後的歸零結果

1540

1541<h4 id="user_message_uuids">

1542 `user_message_uuids`

1543</h4>

1544

1545Claude Code 在此轉數中回答的您發送的每條消息的 `uuid`。當您發送多條消息時，Claude Code 可以將它們合併為一個轉數，`user_message_uuid` 然後僅命名其中的最後一個。要將回覆與任何合併的消息相匹配，請在此清單中的任何位置查找該消息的 `uuid`。需要 Agent SDK v0.3.259 或更高版本。

1546

1547Claude Code 在攜帶該字段的每個回覆幀和結果上設置清單，以及 `user_message_uuid`。有關攜帶 `user_message_uuid` 的完整幀集以及每個所需的版本，請參閱 [`user_message_uuid`](#user_message_uuid)。清單始終包含 `user_message_uuid` 並最多保留 64 個項目。

1548

1549當 Claude Code 在轉數運行時拾取您發送的常規消息時，它會將該消息的 `uuid` 添加到結果的清單中。

1550

1551當第一個回覆或結果攜帶 `user_message_uuid` 而不攜帶清單時，它來自較早的 Claude Code 版本，因此回退到單個字段。

1552

1553<h4 id="queued_turn_count">

1554 `queued_turn_count`

1555</h4>

1556

1557您發送的帶有 [`origin: { kind: "human" }`](#sdkmessageorigin) 的消息數量，在 Claude Code 產生結果時仍在命令隊列中等待。需要 Agent SDK v0.3.242 或更高版本。

1558

1559`0` 和缺少的字段告訴您什麼：

1560

1561* **`0`**：Claude Code 不計算您發送的沒有該 `origin` 的消息，也不計算任務通知，因此轉數仍可能跟隨。

1562* **缺少**：Claude Code 在崩潰或致命啟動錯誤後發出的最終結果省略該字段，並且[可能攜帶歸零的總計](/docs/zh-TW/agent-sdk/cost-tracking#recover-totals-after-a-session-crash)。

1283 1563

1284<h3 id="sdksystemmessage">1564<h3 id="sdksystemmessage">

1285 `SDKSystemMessage`1565 `SDKSystemMessage`

1306 model: string;1586 model: string;

1307 permissionMode: PermissionMode;1587 permissionMode: PermissionMode;

1308 slash_commands: string[];1588 slash_commands: string[];

1589 terminal_slash_commands?: string[];

1309 output_style: string;1590 output_style: string;

1310 skills: string[];1591 skills: string[];

1311 plugins: { name: string; path: string }[];1592 plugins: { name: string; path: string }[];

1593 fast_mode_state?: FastModeState;

1594 fast_mode_disabled_reason?: FastModeDisabledReason;

1312 capabilities?: string[];1596 capabilities?: string[];

1313};1597};

1314```1598```

1315 1599

1600`fast_mode_state` 報告會話的[快速模式](/docs/zh-TW/fast-mode)狀態。當某些東西阻止快速模式時，`fast_mode_disabled_reason` 命名阻止它的檢查；該字段需要 Claude Code v2.1.219 或更高版本。有關原因代碼及其含義，請參閱結果消息上的 [`fast_mode_disabled_reason`](#sdkresultmessage)。

1601

1602`terminal_slash_commands` 命名 `slash_commands` 中其介面綁定到本地終端的項目，例如 `exit`。您可以像發送 `slash_commands` 中的任何其他項目一樣發送它們；該字段存在以便遠程或行動客戶端可以將它們隱藏在其命令菜單中。該字段僅在非空時出現，需要 Agent SDK v0.3.229 或更高版本。

1603

1604* `effort`：[努力級別](/docs/zh-TW/model-config#adjust-effort-level)Claude Code 在會話的下一個請求上發送，或在不發送時為 `null`。Claude Code 僅在發送給[遠程控制](/docs/zh-TW/remote-control)客戶端的初始化消息上設置該字段，並從您的應用程式讀取的初始化消息中省略它。需要 Agent SDK v0.3.234 或更高版本。

1605

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

1317 1607

1318| 功能 | 含義 |1608| 功能 | 含義 |

1319| ---------------------- | ------------------------------------------------------------------------------------------------------------------ |1609| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

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

1611| `interrupt_cancel_queued_v1` | `interrupt` 控制請求尊重 `cancel_queued: true`，取消收據在 `still_queued` 下列出的消息，並改為在 `cancelled` 下列出它們。請參閱 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse)。需要 Claude Code v2.1.219 或更高版本 |

1321 1612

1322<h3 id="sdkpartialassistantmessage">1613<h3 id="sdkpartialassistantmessage">

1323 `SDKPartialAssistantMessage`1614 `SDKPartialAssistantMessage`

1333 uuid: UUID;1624 uuid: UUID;

1334 session_id: string;1625 session_id: string;

1335 ttft_ms?: number; // 首個令牌的時間（毫秒），僅在 message_start 事件上出現1626 ttft_ms?: number; // 首個令牌的時間（毫秒），僅在 message_start 事件上出現

1627 user_message_uuid?: string;

1628 user_message_uuids?: string[];

1336};1629};

1337```1630```

1338 1631

1632Claude Code 在轉數的第一個非 ping 流事件上設置 `user_message_uuid` 和 `user_message_uuids`，並在轉數回答的消息改變時再次設置，條件在 [`user_message_uuid`](#user_message_uuid) 中。

1633

1339<h3 id="sdkcompactboundarymessage">1634<h3 id="sdkcompactboundarymessage">

1340 `SDKCompactBoundaryMessage`1635 `SDKCompactBoundaryMessage`

1341</h3>1636</h3>

1359 `SDKInformationalMessage`1654 `SDKInformationalMessage`

1360</h3>1655</h3>

1361 1656

1362由循環發出的通用文本橫幅。攜帶非錯誤狀態行、hook 反饋（例如 `UserPromptSubmit` hook 的阻止原因）和命令輸出。將 `content` 呈現為給定 `level` 的純文本。1657由迴圈發出的通用文本橫幅。攜帶非錯誤狀態行、hook 反饋（例如 `UserPromptSubmit` hook 的阻止原因）和命令輸出。在 Claude Code v2.1.227 或更高版本上，hook 的 [`systemMessage`](/docs/zh-TW/hooks#json-output) 可以作為此消息到達，每行以 hook 的名稱為前綴，例如 `PostToolUse:Bash says:`。hook 的 `systemMessage` 是否作為此消息到達取決於事件。每個[事件的部分](/docs/zh-TW/hooks#hook-events)在 hooks 頁面上說明輸出如何顯示。將 `content` 呈現為給定 `level` 的純文本。

1363 1658

1364```typescript theme={null}1659```typescript theme={null}

1365type SDKInformationalMessage = {1660type SDKInformationalMessage = {

1378 `SDKWorkerShuttingDownMessage`1673 `SDKWorkerShuttingDownMessage`

1379</h3>1674</h3>

1380 1675

1381在優雅的 worker 拆卸時發出，以便遠程客戶端可以顯示 worker 消失的原因，而不是等待心跳超時。`reason` 是由主機 CLI 設置的短 snake\_case 字符串，例如 `"host_exit"` 或 `"remote_control_disabled"`。僅在實時流式傳輸時對此採取行動。恢復的會話會重放此消息的過去實例，因此在這種情況下忽略它們。1676在優雅的工作程序拆卸時發出，以便遠程客戶端可以顯示工作程序消失的原因，而不是等待心跳超時。`reason` 是由主機 CLI 設置的短 snake\_case 字符串，例如 `"host_exit"` 或 `"remote_control_disabled"`。僅在實時流式傳輸時對此採取行動。恢復的會話會重放此消息的過去實例，因此在這種情況下忽略它們。

1382 1677

1383```typescript theme={null}1678```typescript theme={null}

1384type SDKWorkerShuttingDownMessage = {1679type SDKWorkerShuttingDownMessage = {

1412 `SDKPermissionDeniedMessage`1707 `SDKPermissionDeniedMessage`

1413</h3>1708</h3>

1414 1709

1415當權限系統自動拒絕工具調用而不進行互動式提示時發出的流事件。使用它在發生時在您的 UI 中呈現拒絕，而不是僅觀察隨後的 `is_error` 工具結果。互動式詢問路徑通過 [`canUseTool`](#canusetool) 回調單獨到達您的應用程式。由 `PreToolUse` hook 發出的拒絕不會通過此事件報告。1710當權限系統拒絕工具調用而不進行互動式提示時發出的流事件。使用它在發生時在您的 UI 中呈現拒絕，而不是僅觀察隨後的 `is_error` 工具結果。它報告哪些拒絕取決於運行如何處理權限提示：

1711

1712* **使用 [`canUseTool`](#canusetool) 回調**和預設 [`permissionPrompts: 'host'`](#options)：權限提示進入您的回調，此事件報告 Claude Code 自己決定的拒絕，而不調用它。

1713* **沒有任何一個**：裸 `-p` 運行，或 `query()` 既不設置 `canUseTool` 也不設置 `permissionPromptToolName`，拒絕任何會提示的工具調用，此事件也報告這些拒絕以及 Claude Code 自己決定的拒絕。在 v2.1.223 之前，Claude Code 在沒有回調的運行中不發出此事件。

1714* **使用 MCP 提示工具**，使用 `permissionPromptToolName` 或 [`--permission-prompt-tool`](/docs/zh-TW/cli-reference#cli-flags) 標誌設置，和預設 `permissionPrompts: 'host'`：Claude Code 根本不發出此事件，即使對於它自己決定的規則拒絕也不發出。

1715* **使用 [`permissionPrompts: 'none'`](#options)**：Claude Code 拒絕會提示的調用，即使也設置了 `canUseTool` 或 MCP 提示工具，此事件也報告這些拒絕以及 Claude Code 自己決定的拒絕。需要 Claude Code v2.1.259 或更高版本。

1416 1716

1417此事件需要 Claude Code v2.1.136 或更高版本。1717在每個配置中，此事件跳過在 `PreToolUse` hook 路徑上決定的任何拒絕，無論 hook 本身拒絕了調用還是拒絕規則覆蓋了 hook 的允許或詢問決定。該事件也是盡力而為：偶爾 Claude Code 會記錄拒絕而不發出此事件，因此[結果消息](#sdkresultmessage)上的 `permission_denials` 是權威記錄。

1418 1718

1419```typescript theme={null}1719```typescript theme={null}

1420type SDKPermissionDeniedMessage = {1720type SDKPermissionDeniedMessage = {

1444 `SDKPermissionDenial`1744 `SDKPermissionDenial`

1445</h3>1745</h3>

1446 1746

1447有關被拒絕的工具使用的信息。1747有關被拒絕的工具使用的資訊。

1448 1748

1449```typescript theme={null}1749```typescript theme={null}

1450type SDKPermissionDenial = {1750type SDKPermissionDenial = {

1454};1754};

1455```1755```

1456 1756

1757<h3 id="sdkcontextusage">

1758 `SDKContextUsage`

1759</h3>

1760

1761`/context` 報告的結構化形式，作為 `context_usage` 在傳遞 `/context` 結果的 [`SDKAssistantMessage`](#sdkassistantmessage) 上攜帶。Agent SDK v0.3.232 及更高版本導出該類型。與 [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse) 不同，它僅攜帶呈現使用情況分解所需的資料，不包括 `color` 和 `gridRows` 等顯示字段。

1762

1763```typescript theme={null}

1764type SDKContextUsage = {

1765 model: string;

1766 total_tokens: number;

1767 raw_max_tokens: number;

1768 percentage: number;

1769 over_limit?: {

1770 tokens_over: number;

1771 kind: "hard_limit" | "compaction_window";

1772 };

1773 categories: SDKContextUsageCategory[];

1774 mcp_tools: {

1775 name: string;

1776 server_name: string;

1777 tokens: number;

1778 }[];

1779 memory_files: {

1780 path: string;

1781 type: string;

1782 tokens: number;

1783 }[];

1784 agents: {

1785 agent_type: string;

1786 source: string;

1787 tokens: number;

1788 }[];

1789 skills?: {

1790 name: string;

1791 source: string;

1792 plugin_name?: string;

1793 tokens: number;

1794 }[];

1795};

1796```

1797

1798表格列出了 Claude Code 在每個字段中放置的內容。從 `model` 到 `over_limit` 的字段描述整個會話，集合字段將令牌歸因於單個項目。

1799

1800| 字段 | 類型 | 描述 |

1801| ---------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1802| `model` | `string` | Claude Code 計算使用情況的主迴圈的模型，不是子代理的 |

1803| `total_tokens` | `number` | Claude Code 對使用中令牌的估計。未限制在視窗內，因此當會話超過限制時可能超過 `raw_max_tokens` |

1804| `raw_max_tokens` | `number` | 模型的上下文視窗，或較低的[自動壓縮視窗](/docs/zh-TW/model-config#context-window-and-auto-compaction)（當適用時），例如您設置的或 Claude Code 應用於某些具有 1M 令牌視窗的模型的 200K 邊界。Claude Code 根據此視窗測量 `total_tokens` |

1805| `percentage` | `number` | `total_tokens` 作為 `raw_max_tokens` 的四捨五入百分比，因此當會話超過限制時可能超過 100 |

1806| `over_limit` | `object` | 僅當 `total_tokens` 超過 `raw_max_tokens` 時出現。`tokens_over` 是超出的金額，`kind` 說明 Claude Code 如何解決視窗 |

1807| `categories` | [`SDKContextUsageCategory`](#sdkcontextusagecategory)`[]` | 使用情況按類別分解的每一行一個項目 |

1808| `mcp_tools` | `object[]` | 歸因於每個 MCP 工具的令牌，其線路名稱（例如 `mcp__linear__create_issue`）和其 `server_name` |

1809| `memory_files` | `object[]` | 歸因於每個載入的記憶檔案的令牌，其 `path` 和源標籤（例如 `Project` 或 `User`）在 `type` 中 |

1810| `agents` | `object[]` | 歸因於每個自訂子代理定義的令牌，其源識別符（例如 `projectSettings`、`userSettings` 或 `plugin`）。內建子代理未列出 |

1811| `skills` | `object[]` | 歸因於技能清單中每個技能的令牌，其源識別符和對於插件技能，插件的名稱在 `plugin_name` 中。當沒有技能貢獻令牌時不存在 |

1812

1813`over_limit.kind` 記錄 Claude Code 如何解決視窗，而不是 API 是否接受下一個請求：

1814

1815* `hard_limit`：視窗是 Claude Code 認為是模型自己的限制，超過該限制 API 拒絕請求

1816* `compaction_window`：視窗是壓縮策略視窗，可能與模型的限制一致，也可能不一致

1817

1818Claude Code 以附加方式演進該類型，添加新資料作為可選字段而不是重新塑造現有字段。讀取您知道的字段並忽略您不認識的任何字段。

1819

1820<h3 id="sdkcontextusagecategory">

1821 `SDKContextUsageCategory`

1822</h3>

1823

1824`/context` 使用情況按類別分解的一行。

1825

1826```typescript theme={null}

1827type SDKContextUsageCategory = {

1828 name: string;

1829 tokens: number;

1830 kind: "used" | "free" | "buffer" | "deferred";

1831};

1832```

1833

1834表格列出了 Claude Code 在行的每個字段中放置的內容。

1835

1836| 字段 | 類型 | 描述 |

1837| -------- | -------- | ----------------------------------------------------------- |

1838| `name` | `string` | 行的顯示名稱，如 `/context` 列印的那樣，例如 `Messages`。按 `kind` 分類行，而不是按名稱 |

1839| `tokens` | `number` | 行的令牌計數。行可以攜帶零令牌 |

1840| `kind` | `string` | 行代表什麼：`used`、`free`、`buffer` 或 `deferred` |

1841

1842每個 `kind` 值說明行的令牌是什麼：

1843

1844* `used`：佔據上下文視窗的內容

1845* `free`：剩餘視窗

1846* `buffer`：壓縮儲備

1847* `deferred`：Claude Code 保留在視窗外的工具架構，從使用情況計算中排除，列出以供參考

1848

1457<h3 id="sdkmessageorigin">1849<h3 id="sdkmessageorigin">

1458 `SDKMessageOrigin`1850 `SDKMessageOrigin`

1459</h3>1851</h3>

1460 1852

1461用戶角色消息的來源。這在 [`SDKUserMessage`](#sdkusermessage) 上顯示為 `origin`，並轉發到相應的 [`SDKResultMessage`](#sdkresultmessage)，以便您可以判斷給定轉數的觸發因素。1853使用者角色消息的來源。這在 [`SDKUserMessage`](#sdkusermessage) 上顯示為 `origin`，並轉發到相應的 [`SDKResultMessage`](#sdkresultmessage)，以便您可以判斷給定轉數的觸發因素。

1462 1854

1463```typescript theme={null}1855```typescript theme={null}

1464type SDKMessageOrigin =1856type SDKMessageOrigin =

1467 | {1859 | {

1468 kind: "peer";1860 kind: "peer";

1469 from: string;1861 from: string;

1862 fromMode?: "bypass" | "prompting";

1470 name?: string;1863 name?: string;

1864 fromSession?: string;

1471 senderTaskId?: string;1865 senderTaskId?: string;

1472 body?: string;1866 body?: string;

1867 verifiedPeerPid?: number;

1868 }

1869 | {

1870 kind: "task-notification";

1871 subkind?: "scheduled-trigger" | "peer-send-message";

1473 }1872 }

1474 | { kind: "task-notification" }

1475 | { kind: "coordinator" }1873 | { kind: "coordinator" }

1476 | { kind: "auto-continuation" };1874 | { kind: "auto-continuation" }

1875 | { kind: "unclassified" };

1477```1876```

1478 1877

1479| `kind` | 含義 |1878| `kind` | 含義 |

1480| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1879| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1481| `human` | 來自最終用戶的直接輸入。在用戶消息上，缺少的 `origin` 也表示人類輸入。 |1880| `human` | 來自最終使用者的直接輸入。如果您的應用程式將使用者輸入的內容轉發為使用者消息，請明確將其 `origin` 設置為 `{ kind: "human" }`：Claude Code 將沒有 `origin` 的使用者消息視為未歸因，並檢查需要人類輸入的提示（例如 [`ultracode` 工作流程關鍵字](/docs/zh-TW/workflows#ask-for-a-workflow-in-your-prompt)）不接受它。在 v2.1.210 之前，Claude Code 將使用者消息上缺少的 `origin` 視為人類輸入。 |

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

1484| `task-notification` | 後台任務完成後注入的合成轉數。請參閱 [`SDKTaskNotificationMessage`](#sdktasknotificationmessage)。 |1883| `task-notification` | 為沒有新使用者提示的傳遞注入的合成轉數，例如完成的背景任務；請參閱 [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) 以了解該分支。可選的 `subkind` 標記引發通知的內容。請參閱[任務通知子類型](#task-notification-subkinds)。 |

1886| `unclassified` | 注入轉數，其來源無法確定。需要 Claude Code v2.1.223 或更高版本。當 Claude Code 收到帶有 `isSynthetic: true` 的 [`SDKUserMessage`](#sdkusermessage) 並無法將其分類為任何其他 `kind` 時，它在消息到達時設置此類型，並將轉數框架化為模型作為非使用者來源，而不是將其視為人類輸入。您的應用程式不應設置此值。 |

1887

1888<h3 id="task-notification-subkinds">

1889 任務通知子類型

1890</h3>

1891

1892當 Claude Code 將任務通知傳遞到會話時，它僅在 Anthropic 伺服器驗證該通知來自何處時才在通知的 `origin` 上設置 `subkind`。`subkind` 需要 Claude Code v2.1.213 或更高版本，它採用以下兩個值之一：

1893

1894* `scheduled-trigger`：通知是[例程](/docs/zh-TW/routines)的儲存提示，因為例程的觸發器之一已觸發：其排程、其 [API 觸發器](/docs/zh-TW/routines#add-an-api-trigger)、其 [GitHub 觸發器](/docs/zh-TW/routines#add-a-github-trigger) 或**立即運行**。Claude Code 將這些框架化為模型作為會話的指派任務，帶有與[其他任務通知攜帶的通知](#sdktasknotificationmessage)不同的通知。

1895* `peer-send-message`：通知是另一個您的會話使用[Claude Code on the web](/docs/zh-TW/claude-code-on-the-web) 會話使用的伺服器端 `send_message` 工具發送的消息，而不是[跨會話 `SendMessage` 工具](/docs/zh-TW/cross-session-messaging)，並且 Anthropic 伺服器驗證了兩個會話都屬於同一個私人會話組。需要 Claude Code v2.1.224 或更高版本。伺服器未以該方式驗證的 `send_message` 傳遞沒有 subkind。

1896

1897每個其他任務通知都沒有 `subkind`。這包括在您自己的機器上觸發的[排程任務](/docs/zh-TW/scheduled-tasks)、[PR 活動](/docs/zh-TW/claude-code-on-the-web#how-claude-responds-to-pr-activity)傳遞到會話，以及背景事件（例如完成的任務）。來自[跨會話 `SendMessage` 工具](/docs/zh-TW/cross-session-messaging)的消息根本不是任務通知：無論它們來自同一機器上的會話還是通過 Anthropic 伺服器來自另一台機器，Claude Code 都給予它們 `kind: "peer"` 和[對等來源字段](#peer-origin-fields)。

1898

1899<h3 id="peer-origin-fields">

1900 對等來源字段

1901</h3>

1902

1903`peer` 來源識別哪個代理發送了消息：進程內[隊友](/docs/zh-TW/agent-teams)使用 `SendMessage` 發送到 `main`，或[跨會話對等體](/docs/zh-TW/cross-session-messaging)，您的另一個 Claude Code 會話。跨會話對等體需要 macOS 和 Linux 上的 Claude Code v2.1.224 或更高版本；請參閱[跨會話消息傳遞可用性](/docs/zh-TW/cross-session-messaging#availability)以了解本機 Windows 要求。跨會話對等體可以在同一機器上運行，或在[您的另一台機器](/docs/zh-TW/cross-session-messaging#message-sessions-on-other-machines)或[Claude Code on the web](/docs/zh-TW/claude-code-on-the-web) 上，當其消息通過遠程控制到達時。兩種發送者類型填充字段的方式不同：

1904

1905* `from`：隊友的名稱，或跨會話對等體的發送者地址。對於[單向跨機器消息](/docs/zh-TW/cross-session-messaging#message-sessions-on-other-machines)，發送者沒有回覆地址，`from` 是 `"unknown"`。該值是發送者編寫的；`verifiedPeerPid` 是驗證的身份。

1906* `fromMode`：發送會話的權限類別，`bypass` 或 `prompting`，由在您的會話之間轉發對等消息的主機聲明，例如[桌面應用程式](/docs/zh-TW/desktop#work-across-sessions)。Claude Code 在接收會話中讀取它，當它應用[入站控制](/docs/zh-TW/cross-session-messaging#control-inbound-messages)時。需要 Agent SDK v0.3.234 或更高版本。

1907* `senderTaskId`：隊友的任務 ID。對於跨會話對等體不存在。

1908* `name`：發送者的顯示名稱，由 Claude Code 規範化：它去除 Unicode 控制、格式、代理和行或段落分隔符代碼點，然後修剪結果並將其限制為 64 個代碼點，帶有省略號。需要 Claude Code v2.1.205 或更高版本。

1909* `body`：去除對等信封的已解碼消息正文，與模型看到的內容完全相同。對於隊友消息始終存在；對於跨會話對等體，僅當轉數恰好是由 Claude Code 形成的一個對等信封時才存在。呈現 `name` 和 `body` 而不是重新解析消息文本。需要 Claude Code v2.1.205 或更高版本。

1910* `fromSession`：發送者的主機可開啟會話 ID，由發送者的主機設置，以便您的 UI 可以連結回發送會話。像 `from` 一樣，它是發送者聲稱的：僅將其用作導航目標，不要將其視為發送者身份的證明。需要 Claude Code v2.1.216 或更高版本。

1911* `verifiedPeerPid`：連接到此會話的跨會話消息傳遞套接字的程序的程序 ID，由核心驗證並從連接本身讀取，從不從有效負載讀取。使用它，而不是 `from`，來識別發送者：`from` 可由任何同一使用者程序偽造。當 Claude Code 無法驗證它時，該字段不存在，例如在 Windows 或非套接字入口上，因此缺少值意味著發送者未驗證。對於轉發的流量，它識別轉發者而不是消息的作者，程序 ID 是可回收的，因此將其視為來源而不是身份驗證令牌。需要 Claude Code v2.1.216 或更高版本。

1487 1912

1488<h2 id="hook-types">1913<h2 id="hook-types">

1489 Hook 類型1914 Hook 類型

1505 | "PostToolBatch"1930 | "PostToolBatch"

1506 | "Notification"1931 | "Notification"

1507 | "UserPromptSubmit"1932 | "UserPromptSubmit"

1933 | "UserPromptExpansion"

1508 | "SessionStart"1934 | "SessionStart"

1509 | "SessionEnd"1935 | "SessionEnd"

1510 | "Stop"1936 | "Stop"

1937 | "StopFailure"

1511 | "SubagentStart"1938 | "SubagentStart"

1512 | "SubagentStop"1939 | "SubagentStop"

1513 | "PreCompact"1940 | "PreCompact"

1941 | "PostCompact"

1942 | "PreModelSwitch"

1943 | "PostModelSwitch"

1514 | "PermissionRequest"1944 | "PermissionRequest"

1945 | "PermissionDenied"

1515 | "Setup"1946 | "Setup"

1516 | "TeammateIdle"1947 | "TeammateIdle"

1948 | "TaskCreated"

1517 | "TaskCompleted"1949 | "TaskCompleted"

1950 | "Elicitation"

1951 | "ElicitationResult"

1518 | "ConfigChange"1952 | "ConfigChange"

1953 | "DirectoryAdded"

1519 | "WorktreeCreate"1954 | "WorktreeCreate"

1520 | "WorktreeRemove"1955 | "WorktreeRemove"

1956 | "InstructionsLoaded"

1957 | "CwdChanged"

1958 | "FileChanged"

1521 | "MessageDisplay";1959 | "MessageDisplay";

1522```1960```

1523 1961

1561 | PostToolUseHookInput1999 | PostToolUseHookInput

1562 | PostToolUseFailureHookInput2000 | PostToolUseFailureHookInput

1563 | PostToolBatchHookInput2001 | PostToolBatchHookInput

2002 | PermissionDeniedHookInput

1564 | NotificationHookInput2003 | NotificationHookInput

1565 | UserPromptSubmitHookInput2004 | UserPromptSubmitHookInput

2005 | UserPromptExpansionHookInput

1566 | SessionStartHookInput2006 | SessionStartHookInput

1567 | SessionEndHookInput2007 | SessionEndHookInput

1568 | StopHookInput2008 | StopHookInput

2009 | StopFailureHookInput

1569 | SubagentStartHookInput2010 | SubagentStartHookInput

1570 | SubagentStopHookInput2011 | SubagentStopHookInput

1571 | PreCompactHookInput2012 | PreCompactHookInput

2013 | PostCompactHookInput

2014 | PreModelSwitchHookInput

2015 | PostModelSwitchHookInput

1572 | PermissionRequestHookInput2016 | PermissionRequestHookInput

1573 | SetupHookInput2017 | SetupHookInput

1574 | TeammateIdleHookInput2018 | TeammateIdleHookInput

2019 | TaskCreatedHookInput

1575 | TaskCompletedHookInput2020 | TaskCompletedHookInput

2021 | ElicitationHookInput

2022 | ElicitationResultHookInput

1576 | ConfigChangeHookInput2023 | ConfigChangeHookInput

2024 | InstructionsLoadedHookInput

2025 | DirectoryAddedHookInput

1577 | WorktreeCreateHookInput2026 | WorktreeCreateHookInput

1578 | WorktreeRemoveHookInput2027 | WorktreeRemoveHookInput

2028 | CwdChangedHookInput

2029 | FileChangedHookInput

1579 | MessageDisplayHookInput;2030 | MessageDisplayHookInput;

1580```2031```

1581 2032

1664};2115};

1665```2116```

1666 2117

2118<h4 id="permissiondeniedhookinput">

2119 `PermissionDeniedHookInput`

2120</h4>

2121

2122```typescript theme={null}

2123type PermissionDeniedHookInput = BaseHookInput & {

2124 hook_event_name: "PermissionDenied";

2125 tool_name: string;

2126 tool_input: unknown;

2127 tool_use_id: string;

2128 reason: string;

2129};

2130```

2131

1667<h4 id="notificationhookinput">2132<h4 id="notificationhookinput">

1668 `NotificationHookInput`2133 `NotificationHookInput`

1669</h4>2134</h4>

1685type UserPromptSubmitHookInput = BaseHookInput & {2150type UserPromptSubmitHookInput = BaseHookInput & {

1686 hook_event_name: "UserPromptSubmit";2151 hook_event_name: "UserPromptSubmit";

1687 prompt: string;2152 prompt: string;

2153 session_title?: string;

2154};

2155```

2156

2157<h4 id="userpromptexpansionhookinput">

2158 `UserPromptExpansionHookInput`

2159</h4>

2160

2161```typescript theme={null}

2162type UserPromptExpansionHookInput = BaseHookInput & {

2163 hook_event_name: "UserPromptExpansion";

2164 expansion_type: "slash_command" | "mcp_prompt";

2165 command_name: string;

2166 command_args: string;

2167 command_source?: string;

2168 prompt: string;

1688};2169};

1689```2170```

1690 2171

1695```typescript theme={null}2176```typescript theme={null}

1696type SessionStartHookInput = BaseHookInput & {2177type SessionStartHookInput = BaseHookInput & {

1697 hook_event_name: "SessionStart";2178 hook_event_name: "SessionStart";

1699 agent_type?: string;2180 agent_type?: string;

1700 model?: string;2181 model?: string;

2182 session_title?: string;

1701};2183};

1702```2184```

1703 2185

1726};2208};

1727```2209```

1728 2210

2211<h4 id="stopfailurehookinput">

2212 `StopFailureHookInput`

2213</h4>

2214

2215```typescript theme={null}

2216type StopFailureHookInput = BaseHookInput & {

2217 hook_event_name: "StopFailure";

2218 error: SDKAssistantMessageError;

2219 error_details?: string;

2220 last_assistant_message?: string;

2221};

2222```

2223

1729<h4 id="subagentstarthookinput">2224<h4 id="subagentstarthookinput">

1730 `SubagentStartHookInput`2225 `SubagentStartHookInput`

1731</h4>2226</h4>

1786};2281};

1787```2282```

1788 2283

2284<h4 id="postcompacthookinput">

2285 `PostCompactHookInput`

2286</h4>

2287

2288```typescript theme={null}

2289type PostCompactHookInput = BaseHookInput & {

2290 hook_event_name: "PostCompact";

2291 trigger: "manual" | "auto";

2292 compact_summary: string;

2293};

2294```

2295

2296<h4 id="premodelswitchhookinput">

2297 `PreModelSwitchHookInput`

2298</h4>

2299

2300在請求的模型切換生效之前觸發。`context_tokens` 和其後的欄位估計重新傳送對話到新模型的成本。如需完整的欄位說明和阻止語義，見 [PreModelSwitch](/docs/zh-TW/hooks#premodelswitch)。

2301

2302```typescript theme={null}

2303type PreModelSwitchHookInput = BaseHookInput & {

2304 hook_event_name: "PreModelSwitch";

2305 from_model: string;

2306 to_model: string;

2307 requested_model: string | null;

2308 source: "command" | "picker" | "sdk";

2309 context_tokens: number;

2310 prompt_cache_warm: boolean;

2311 cache_ttl: "5m" | "1h";

2312 estimated_cache_write_usd: number;

2313 pricing: "configured" | "catalog" | "default";

2314};

2315```

2316

2317<h4 id="postmodelswitchhookinput">

2318 `PostModelSwitchHookInput`

2319</h4>

2320

2321在工作階段的模型變更後觸發。它攜帶與 `PreModelSwitchHookInput` 相同的欄位，加上兩個額外的 `source` 值。見 [PostModelSwitch](/docs/zh-TW/hooks#postmodelswitch)。

2322

2323```typescript theme={null}

2324type PostModelSwitchHookInput = BaseHookInput & {

2325 hook_event_name: "PostModelSwitch";

2326 from_model: string;

2327 to_model: string;

2328 requested_model: string | null;

2329 source: "command" | "picker" | "sdk" | "auto" | "resume";

2330 context_tokens: number;

2331 prompt_cache_warm: boolean;

2332 cache_ttl: "5m" | "1h";

2333 estimated_cache_write_usd: number;

2334 pricing: "configured" | "catalog" | "default";

2335};

2336```

2337

1789<h4 id="permissionrequesthookinput">2338<h4 id="permissionrequesthookinput">

1790 `PermissionRequestHookInput`2339 `PermissionRequestHookInput`

1791</h4>2340</h4>

1823};2372};

1824```2373```

1825 2374

1826<h4 id="taskcompletedhookinput">2375<h4 id="taskcreatedhookinput">

1827 `TaskCompletedHookInput`2376 `TaskCreatedHookInput`

1828</h4>2377</h4>

1829 2378

1830```typescript theme={null}2379```typescript theme={null}

1831type TaskCompletedHookInput = BaseHookInput & {2380type TaskCreatedHookInput = BaseHookInput & {

2381 hook_event_name: "TaskCreated";

2382 task_id: string;

2383 task_subject: string;

2384 task_description?: string;

2385 teammate_name?: string;

2386 /** @deprecated 自 v2.1.178 起已棄用。攜帶工作階段衍生的團隊名稱；將被移除。 */

2387 team_name?: string;

2388};

2389```

2390

2391<h4 id="taskcompletedhookinput">

2392 `TaskCompletedHookInput`

2393</h4>

2394

2395```typescript theme={null}

2396type TaskCompletedHookInput = BaseHookInput & {

1832 hook_event_name: "TaskCompleted";2397 hook_event_name: "TaskCompleted";

1833 task_id: string;2398 task_id: string;

1834 task_subject: string;2399 task_subject: string;

1839};2404};

1840```2405```

1841 2406

2407<h4 id="elicitationhookinput">

2408 `ElicitationHookInput`

2409</h4>

2410

2411```typescript theme={null}

2412type ElicitationHookInput = BaseHookInput & {

2413 hook_event_name: "Elicitation";

2414 mcp_server_name: string;

2415 message: string;

2416 mode?: "form" | "url";

2417 url?: string;

2418 elicitation_id?: string;

2419 requested_schema?: Record<string, unknown>;

2420};

2421```

2422

2423<h4 id="elicitationresulthookinput">

2424 `ElicitationResultHookInput`

2425</h4>

2426

2427```typescript theme={null}

2428type ElicitationResultHookInput = BaseHookInput & {

2429 hook_event_name: "ElicitationResult";

2430 mcp_server_name: string;

2431 elicitation_id?: string;

2432 mode?: "form" | "url";

2433 action: "accept" | "decline" | "cancel";

2434 content?: Record<string, unknown>;

2435};

2436```

2437

1842<h4 id="configchangehookinput">2438<h4 id="configchangehookinput">

1843 `ConfigChangeHookInput`2439 `ConfigChangeHookInput`

1844</h4>2440</h4>

1856};2452};

1857```2453```

1858 2454

2455<h4 id="instructionsloadedhookinput">

2456 `InstructionsLoadedHookInput`

2457</h4>

2458

2459```typescript theme={null}

2460type InstructionsLoadedHookInput = BaseHookInput & {

2461 hook_event_name: "InstructionsLoaded";

2462 file_path: string;

2463 memory_type: "User" | "Project" | "Local" | "Managed";

2464 load_reason:

2465 | "session_start"

2466 | "nested_traversal"

2467 | "path_glob_match"

2468 | "include"

2469 | "compact";

2470 globs?: string[];

2471 trigger_file_path?: string;

2472 parent_file_path?: string;

2473};

2474```

2475

2476<h4 id="directoryaddedhookinput">

2477 `DirectoryAddedHookInput`

2478</h4>

2479

2480```typescript theme={null}

2481type DirectoryAddedHookInput = BaseHookInput & {

2482 hook_event_name: "DirectoryAdded";

2483 directory: string;

2484 source: "slash_command" | "register_repo_root";

2485};

2486```

2487

2488`directory` 是被新增目錄的絕對路徑。`source` 是 `"slash_command"`（當 `/add-dir` 新增時）或 `"register_repo_root"`（當 SDK 控制請求執行時）。

2489

1859<h4 id="worktreecreatehookinput">2490<h4 id="worktreecreatehookinput">

1860 `WorktreeCreateHookInput`2491 `WorktreeCreateHookInput`

1861</h4>2492</h4>

1878};2509};

1879```2510```

1880 2511

2512<h4 id="cwdchangedhookinput">

2513 `CwdChangedHookInput`

2514</h4>

2515

2516```typescript theme={null}

2517type CwdChangedHookInput = BaseHookInput & {

2518 hook_event_name: "CwdChanged";

2519 old_cwd: string;

2520 new_cwd: string;

2521};

2522```

2523

2524<h4 id="filechangedhookinput">

2525 `FileChangedHookInput`

2526</h4>

2527

2528```typescript theme={null}

2529type FileChangedHookInput = BaseHookInput & {

2530 hook_event_name: "FileChanged";

2531 file_path: string;

2532 event: "change" | "add" | "unlink";

2533};

2534```

2535

1881<h4 id="messagedisplayhookinput">2536<h4 id="messagedisplayhookinput">

1882 `MessageDisplayHookInput`2537 `MessageDisplayHookInput`

1883</h4>2538</h4>

1925 stopReason?: string;2580 stopReason?: string;

1926 decision?: "approve" | "block";2581 decision?: "approve" | "block";

1927 systemMessage?: string;2582 systemMessage?: string;

2583 /**

2584 * 終端逸出序列（例如 OSC 9 / OSC 777 桌面通知）

2585 * 供 Claude Code 代表您發出。僅允許通知/標題 OSCs

2586 * （0、1、2、9、99、777）和 BEL；包含

2587 * 其他任何內容的值會被整體忽略。僅互動式 CLI 會發出

2588 * 它；SDK 會忽略此欄位。

2589 */

2590 terminalSequence?: string;

1928 reason?: string;2591 reason?: string;

1929 hookSpecificOutput?:2592 hookSpecificOutput?:

1930 | {2593 | {

1937 | {2600 | {

1938 hookEventName: "UserPromptSubmit";2601 hookEventName: "UserPromptSubmit";

1939 additionalContext?: string;2602 additionalContext?: string;

2603 sessionTitle?: string;

2604 /** 當決定為 "block" 時，從阻止訊息中省略原始提示。 */

2605 suppressOriginalPrompt?: boolean;

2606 }

2607 | {

2608 hookEventName: "UserPromptExpansion";

2609 additionalContext?: string;

1940 }2610 }

1941 | {2611 | {

1942 hookEventName: "SessionStart";2612 hookEventName: "SessionStart";

1943 additionalContext?: string;2613 additionalContext?: string;

2614 initialUserMessage?: string;

2615 sessionTitle?: string;

2616 watchPaths?: string[];

2617 /**

2618 * SessionStart hooks 完成後重新掃描 skill 和命令目錄，

2619 * 以便 hook 安裝的 skills 在同一工作階段中可用。

2620 */

2621 reloadSkills?: boolean;

1944 }2622 }

1945 | {2623 | {

1946 hookEventName: "Setup";2624 hookEventName: "Setup";

1947 additionalContext?: string;2625 additionalContext?: string;

1948 }2626 }

2627 | {

2628 hookEventName: "PreModelSwitch";

2629 /**

2630 * 與 PreToolUse 相同的合約："allow" 繼續、"deny" 取消

2631 * 切換、"ask" 要求使用者確認。僅互動式工作階段中的 /model

2632 * 顯示該提示；其他所有表面（包括 set_model 請求）

2633 * 將 "ask" 視為拒絕。

2634 */

2635 permissionDecision?: "allow" | "deny" | "ask";

2636 permissionDecisionReason?: string;

2637 }

2638 | {

2639 hookEventName: "PostModelSwitch";

2640 /** 透過新模型提供的下一個請求到達模型。 */

2641 additionalContext?: string;

2642 }

1949 | {2643 | {

1950 hookEventName: "SubagentStart";2644 hookEventName: "SubagentStart";

1951 additionalContext?: string;2645 additionalContext?: string;

1953 | {2647 | {

1954 hookEventName: "PostToolUse";2648 hookEventName: "PostToolUse";

1955 additionalContext?: string;2649 additionalContext?: string;

2650 /**

2651 * 關於此工具呼叫結果的簡短說明，供自動模式

2652 * 權限分類器使用。上限為 2000 個字元，在回應

2653 * 同一呼叫的所有 hooks 中共享；僅在同步

2654 * hook 回應上受尊重。不要將不受信任的工具輸出複製到其中。

2655 */

2656 classifierContext?: string;

1956 updatedToolOutput?: unknown;2657 updatedToolOutput?: unknown;

1957 /** @deprecated 使用 `updatedToolOutput`，適用於所有工具。 */2658 /** @deprecated 使用 `updatedToolOutput`，適用於所有工具。 */

1958 updatedMCPToolOutput?: unknown;2659 updatedMCPToolOutput?: unknown;

1965 hookEventName: "PostToolBatch";2666 hookEventName: "PostToolBatch";

1966 additionalContext?: string;2667 additionalContext?: string;

1967 }2668 }

2669 | {

2670 hookEventName: "Stop";

2671 additionalContext?: string;

2672 }

2673 | {

2674 hookEventName: "SubagentStop";

2675 additionalContext?: string;

2676 }

2677 | {

2678 hookEventName: "PermissionDenied";

2679 retry?: boolean;

2680 }

1968 | {2681 | {

1969 hookEventName: "Notification";2682 hookEventName: "Notification";

1970 additionalContext?: string;2683 additionalContext?: string;

1982 message?: string;2695 message?: string;

1983 interrupt?: boolean;2696 interrupt?: boolean;

1984 };2697 };

2698 }

2699 | {

2700 hookEventName: "Elicitation";

2701 action?: "accept" | "decline" | "cancel";

2702 content?: Record<string, unknown>;

2703 }

2704 | {

2705 hookEventName: "ElicitationResult";

2706 action?: "accept" | "decline" | "cancel";

2707 content?: Record<string, unknown>;

2708 }

2709 | {

2710 hookEventName: "CwdChanged";

2711 watchPaths?: string[];

2712 }

2713 | {

2714 hookEventName: "FileChanged";

2715 watchPaths?: string[];

2716 }

2717 | {

2718 hookEventName: "WorktreeCreate";

2719 worktreePath: string;

2720 }

2721 | {

2722 hookEventName: "MessageDisplay";

2723 /** 用來代替 delta 顯示的文字。省略（或返回 delta 不變）以顯示原始內容。 */

2724 displayContent?: string;

1985 };2725 };

1986};2726};

1987```2727```

1990 工具輸入類型2730 工具輸入類型

1991</h2>2731</h2>

1992 2732

1993所有內置 Claude Code 工具的輸入架構文檔。這些類型從 `@anthropic-ai/claude-agent-sdk` 導出，可用於類型安全的工具交互。2733所有內建 Claude Code 工具的輸入架構文件。這些類型從 `@anthropic-ai/claude-agent-sdk` 匯出，可用於類型安全的工具互動。

1994 2734

1995<h3 id="toolinputschemas">2735<h3 id="toolinputschemas">

1996 `ToolInputSchemas`2736 `ToolInputSchemas`

1997</h3>2737</h3>

1998 2738

1999所有工具輸入類型的聯合，從 `@anthropic-ai/claude-agent-sdk` 導出。2739從 `@anthropic-ai/claude-agent-sdk` 匯出的工具輸入類型的聯合；成員包括：

2000 2740

2001```typescript theme={null}2741```typescript theme={null}

2002type ToolInputSchemas =2742type ToolInputSchemas =

2003 | AgentInput2743 | AgentInput

2744 | ArtifactInput

2004 | AskUserQuestionInput2745 | AskUserQuestionInput

2005 | BashInput2746 | BashInput

2006 | TaskOutputInput2747 | CronCreateInput

2748 | CronDeleteInput

2749 | CronListInput

2750 | EnterPlanModeInput

2007 | EnterWorktreeInput2751 | EnterWorktreeInput

2008 | ExitPlanModeInput2752 | ExitPlanModeInput

2753 | ExitWorktreeInput

2009 | FileEditInput2754 | FileEditInput

2010 | FileReadInput2755 | FileReadInput

2011 | FileWriteInput2756 | FileWriteInput

2015 | McpInput2760 | McpInput

2016 | MonitorInput2761 | MonitorInput

2017 | NotebookEditInput2762 | NotebookEditInput

2763 | ProjectsInput

2764 | PushNotificationInput

2765 | ReadMcpResourceDirInput

2018 | ReadMcpResourceInput2766 | ReadMcpResourceInput

2019 | SubscribeMcpResourceInput2767 | RefreshMcpToolsInput

2020 | SubscribePollingInput2768 | RemoteTriggerInput

2769 | REPLInput

2770 | ReportFindingsInput

2771 | ScheduleWakeupInput

2772 | ShowOnboardingRolePickerInput

2021 | TaskCreateInput2773 | TaskCreateInput

2022 | TaskGetInput2774 | TaskGetInput

2023 | TaskListInput2775 | TaskListInput

2776 | TaskOutputInput

2024 | TaskStopInput2777 | TaskStopInput

2025 | TaskUpdateInput2778 | TaskUpdateInput

2026 | TodoWriteInput2779 | TodoWriteInput

2027 | UnsubscribeMcpResourceInput

2028 | UnsubscribePollingInput

2029 | WebFetchInput2780 | WebFetchInput

2030 | WebSearchInput2781 | WebSearchInput

2031 | WorkflowInput;2782 | WorkflowInput;

2035 Agent2786 Agent

2036</h3>2787</h3>

2037 2788

2038**工具名稱：** `Agent`（之前是 `Task`，仍然接受作為別名）2789**工具名稱：** `Agent`。先前的名稱 `Task` 仍被接受為別名，[`SDKSystemMessage`](#sdksystemmessage) 初始化訊息中的 `tools` 陣列目前仍將此工具列為 `Task` 以保持向後相容性。

2790

2791<Note>

2792 `mode` 欄位在 Claude Code v2.1.212 或更新版本上已棄用且被忽略。子代理在父工作階段的權限模式或其定義的 [`permissionMode`](#agentdefinition) 中執行，[子代理繼承規則](/docs/zh-TW/agent-sdk/permissions#available-modes) 決定使用哪一個。

2793</Note>

2039 2794

2040```typescript theme={null}2795```typescript theme={null}

2041type AgentInput = {2796type AgentInput = {

2046 run_in_background?: boolean;2801 run_in_background?: boolean;

2047 name?: string;2802 name?: string;

2805 isolation?: "worktree" | "remote";

2050};2806};

2051```2807```

2052 2808

2066 options: Array<{ label: string; description: string; preview?: string }>;2822 options: Array<{ label: string; description: string; preview?: string }>;

2067 multiSelect: boolean;2823 multiSelect: boolean;

2068 }>;2824 }>;

2825 answers?: Record<string, string>;

2826 annotations?: Record<string, { preview?: string; notes?: string }>;

2827 metadata?: { source?: string };

2069};2828};

2070```2829```

2071 2830

2072在執行期間向用戶提出澄清問題。見 [處理批准和用戶輸入](/docs/zh-TW/agent-sdk/user-input#handle-clarifying-questions) 了解使用詳情。2831在執行期間向使用者提出澄清問題。詳見[處理核准和使用者輸入](/docs/zh-TW/agent-sdk/user-input#handle-clarifying-questions)以了解使用詳情。

2073 2832

2074<h3 id="bash">2833<h3 id="bash">

2075 Bash2834 Bash

2087};2846};

2088```2847```

2089 2848

2090在持久 shell 會話中執行 bash 命令，具有可選的超時和後台執行。2849執行 Bash 命令，支援選擇性逾時和背景執行。工作目錄在命令之間保持不變，包括多輪工作階段後續執行的命令；shell 狀態（例如匯出的環境變數）則不會保持。如需了解哪些目錄變更會保留，詳見[命令之間保持的內容](/docs/zh-TW/tools-reference#what-persists-between-commands)。

2091 2850

2092<h3 id="monitor">2851<h3 id="monitor">

2093 Monitor2852 Monitor

2103 protocols?: string[];2862 protocols?: string[];

2104 };2863 };

2105 description: string;2864 description: string;

2106 timeout_ms?: number;2865 timeout_ms: number;

2107 persistent?: boolean;2866 persistent: boolean;

2108};2867};

2109```2868```

2110 2869

2111運行後台來源並將每個事件傳遞給 Claude，以便它可以在不輪詢的情況下做出反應：`command` 運行腳本並每個 stdout 行發出一個事件，`ws` 打開 WebSocket 並每個文本幀發出一個事件。提供 `command` 或 `ws` 中的恰好一個。`ws` 來源需要 Claude Code v2.1.195 或更高版本。2870執行背景來源並將每個事件傳遞給 Claude，使其能夠做出反應而無需輪詢：`command` 執行指令碼並每行 stdout 發出一個事件，`ws` 開啟 WebSocket 並每個文字框架發出一個事件。提供 `command` 或 `ws` 中的恰好一個。`ws` 來源需要 Claude Code v2.1.195 或更新版本。

2112 2871

2113為會話長度的監視（如日誌尾部）設置 `persistent: true`。Monitor 運行命令時，遵循與 Bash 相同的權限規則；WebSocket 監視會單獨提示批准。見 [Monitor 工具參考](/docs/zh-TW/tools-reference#monitor-tool) 了解行為和提供商可用性。2872將 `persistent: true` 設定為工作階段長度的監視，例如日誌尾部。Monitor 執行命令時，遵循與 Bash 相同的權限規則；WebSocket 監視會單獨提示核准。詳見[Monitor 工具參考](/docs/zh-TW/tools-reference#monitor-tool)以了解行為和提供者可用性。匯出的類型將 `timeout_ms` 和 `persistent` 標記為必需，因為架構填入其預設值 300000 和 `false`；省略它們的呼叫會驗證通過。

2114 2873

2115<h3 id="taskoutput">2874<h3 id="taskoutput">

2116 TaskOutput2875 TaskOutput

2118 2877

2119**工具名稱：** `TaskOutput`2878**工具名稱：** `TaskOutput`

2120 2879

2880<Note>`TaskOutput` 已棄用；改為在任務的輸出檔案路徑上使用 `Read`。以下架構對於遇到該工具的 hooks 和權限處理程式仍然有效。</Note>

2881

2121```typescript theme={null}2882```typescript theme={null}

2122type TaskOutputInput = {2883type TaskOutputInput = {

2123 task_id: string;2884 task_id: string;

2126};2887};

2127```2888```

2128 2889

2129從運行或已完成的後台任務檢索輸出。2890從執行中或已完成的背景任務中擷取輸出。

2130 2891

2131<h3 id="edit">2892<h3 id="edit">

2132 Edit2893 Edit

2143};2904};

2144```2905```

2145 2906

2146在文件中執行精確字符串替換。2907在檔案中執行精確的字串替換。

2147 2908

2148<h3 id="read">2909<h3 id="read">

2149 Read2910 Read

2160};2921};

2161```2922```

2162 2923

2163從本地文件系統讀取文件，包括文本、圖像、PDF 和 Jupyter 筆記本。對 PDF 頁面範圍使用 `pages`（例如，`"1-5"`）。2924從本機檔案系統讀取檔案，包括文字、影像、PDF 和 Jupyter 筆記本。使用 `pages` 指定 PDF 頁面範圍（例如 `"1-5"`）。

2925

2926對於 PDF，Claude 在 Read 呼叫的 `tool_result` 內容中接收檔案的內容。傳回 `pdf` [輸出](#tool-output-types)的讀取會帶有摘要 `text` 區塊，後面跟著 `document` 區塊。傳回 `parts` 輸出的讀取會帶有摘要 `text` 區塊，後面跟著每個提取頁面的一個區塊：`image` 區塊，或當 Claude Code 無法將其呈現為影像時命名該頁面的 `text` 區塊。在 Agent SDK v0.3.242 之前，Claude Code 在工具結果後作為單獨的 `user` 訊息傳遞檔案的內容。

2164 2927

2165<h3 id="write">2928<h3 id="write">

2166 Write2929 Write

2175};2938};

2176```2939```

2177 2940

2178將文件寫入本地文件系統，如果存在則覆蓋。2941將檔案寫入本機檔案系統，如果存在則覆蓋。

2179 2942

2180<h3 id="glob">2943<h3 id="glob">

2181 Glob2944 Glob

2190};2953};

2191```2954```

2192 2955

2193快速文件模式匹配，適用於任何代碼庫大小。2956快速檔案模式匹配，適用於任何程式碼庫大小。

2194 2957

2195<h3 id="grep">2958<h3 id="grep">

2196 Grep2959 Grep

2206 type?: string;2969 type?: string;

2207 output_mode?: "content" | "files_with_matches" | "count";2970 output_mode?: "content" | "files_with_matches" | "count";

2208 "-i"?: boolean;2971 "-i"?: boolean;

2972 "-o"?: boolean; // print only the matched parts of each line; requires output_mode: "content"

2209 "-n"?: boolean;2973 "-n"?: boolean;

2210 "-B"?: number;2974 "-B"?: number;

2211 "-A"?: number;2975 "-A"?: number;

2217};2981};

2218```2982```

2219 2983

2220基於 ripgrep 的強大搜索工具，支持正則表達式。2984基於 ripgrep 的強大搜尋工具，支援正規表達式。

2221 2985

2222<h3 id="taskstop">2986<h3 id="taskstop">

2223 TaskStop2987 TaskStop

2228```typescript theme={null}2992```typescript theme={null}

2229type TaskStopInput = {2993type TaskStopInput = {

2230 task_id?: string;2994 task_id?: string;

2231 shell_id?: string; // 已棄用：使用 task_id2995 shell_id?: string; // Deprecated: use task_id

2232};2996};

2233```2997```

2234 2998

2235按 ID 停止運行的後台任務或 shell。自 v2.1.198 起，`task_id` 也接受代理團隊隊友或按代理 ID 或名稱的命名後台代理。2999按 ID 停止執行中的背景任務或 shell。自 v2.1.198 起，`task_id` 也接受代理團隊隊友或按代理 ID 或名稱的具名背景代理。

2236 3000

2237<h3 id="notebookedit">3001<h3 id="notebookedit">

2238 NotebookEdit3002 NotebookEdit

2250};3014};

2251```3015```

2252 3016

2253編輯 Jupyter 筆記本文件中的單元格。3017編輯 Jupyter 筆記本檔案中的儲存格。

2254 3018

2255<h3 id="webfetch">3019<h3 id="webfetch">

2256 WebFetch3020 WebFetch

2265};3029};

2266```3030```

2267 3031

2268從 URL 獲取內容並使用 AI 模型處理它。3032從 URL 擷取內容並使用 AI 模型進行處理。

2269 3033

2270<h3 id="websearch">3034<h3 id="websearch">

2271 WebSearch3035 WebSearch

2281};3045};

2282```3046```

2283 3047

2284搜索網絡並返回格式化結果。3048搜尋網路並傳回格式化的結果。

2285 3049

2286<h3 id="workflow">3050<h3 id="workflow">

2287 Workflow3051 Workflow

2294 script?: string;3058 script?: string;

2295 name?: string;3059 name?: string;

2296 scriptPath?: string;3060 scriptPath?: string;

2297 args?: unknown;3061 args?: unknown; // any JSON value; the published typings render this as an object map

2298 resumeFromRunId?: string;3062 resumeFromRunId?: string;

3063 title?: string; // ignored; the script's meta block sets the title

3064 description?: string; // ignored; the script's meta block sets the description

2299};3065};

2300```3066```

2301 3067

2302運行 [動態工作流](/docs/zh-TW/workflows)：一個在後台協調許多子代理並返回一個統一結果的腳本。`Workflow` 工具在 Agent SDK v0.3.149 及更高版本中可用。至少需要 `script`、`name` 或 `scriptPath` 之一。3068執行[動態工作流程](/docs/zh-TW/workflows)：在背景中協調許多子代理並傳回一個統一結果的指令碼。Workflow 工具在 Agent SDK v0.3.149 及更新版本中可用。至少需要 `script`、`name` 或 `scriptPath` 中的一個。

2303 3069

2304| 字段 | 類型 | 描述 |3070| 欄位 | 類型 | 說明 |

2305| ----------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |3071| ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

2306| `script` | `string` | 內聯工作流腳本。必須以 `export const meta = { name, description }` 作為字面量開始，然後是使用 `agent()`、`parallel()`、`pipeline()` 和 `phase()` 的腳本主體。`meta` 中的可選 `phases` 陣列在進度檢視中將代理分組到命名階段下 |3072| `script` | `string` | 內嵌工作流程指令碼。必須以 `export const meta = { name, description }` 作為字面值開始，後面跟著使用 `agent()`、`parallel()`、`pipeline()` 和 `phase()` 的指令碼主體。`meta` 中的選擇性 `phases` 陣列在進度檢視中將代理分組到具名階段下 |

3077| `title` | `string` | 已忽略；指令碼的 `meta` 區塊設定標題 |

3078| `description` | `string` | 已忽略；指令碼的 `meta` 區塊設定說明 |

2311 3079

2312<h3 id="todowrite">3080<h3 id="todowrite">

2313 TodoWrite3081 TodoWrite

2325};3093};

2326```3094```

2327 3095

2328創建和管理結構化任務列表以跟蹤進度。3096建立和管理結構化任務清單以追蹤進度。

2329 3097

2330<Note>3098<Note>

2331 自 TypeScript Agent SDK 0.3.142 起，`TodoWrite` 預設為禁用。改用 `TaskCreate`、`TaskGet`、`TaskUpdate` 和 `TaskList`。見 [遷移到 Task 工具](/docs/zh-TW/agent-sdk/todo-tracking#migrate-to-task-tools) 更新您的監視代碼，或設置 `CLAUDE_CODE_ENABLE_TASKS=0` 以恢復為 `TodoWrite`。3099 The following tools are available by default only on Claude 3.x models, Opus 4 through 4.7, Sonnet 4 through 4.6, and Haiku 4.5. On every other model, including model IDs Claude Code doesn't recognize, they aren't available unless you opt in:

3100

3101 * `TodoWrite`

3102 * `TaskCreate`

3103 * `TaskGet`

3104 * `TaskUpdate`

3105 * `TaskList`

3106

3107 Wherever the tools are available, Claude Code provides the four Task tools, or `TodoWrite` instead when you set `CLAUDE_CODE_ENABLE_TASKS=0`.

3108

3109 This default set applies in Claude Code v2.1.268 and later, which the TypeScript Agent SDK bundles from v0.3.268.

3110

3111 詳見[模型可用性](/docs/zh-TW/agent-sdk/todo-tracking#model-availability)以選擇加入。

2332</Note>3112</Note>

2333 3113

2334<h3 id="taskcreate">3114<h3 id="taskcreate">

2346};3126};

2347```3127```

2348 3128

2349創建單個任務並返回其分配的 ID。3129建立單一任務並傳回其指派的 ID。

2350 3130

2351<h3 id="taskupdate">3131<h3 id="taskupdate">

2352 TaskUpdate3132 TaskUpdate

2368};3148};

2369```3149```

2370 3150

2371按 ID 修補一個任務。將 `status` 設置為 `"deleted"` 以移除它。3151按 ID 修補一個任務。將 `status` 設定為 `"deleted"` 以移除它。

2372 3152

2373<h3 id="taskget">3153<h3 id="taskget">

2374 TaskGet3154 TaskGet

2382};3162};

2383```3163```

2384 3164

2385返回一個任務的完整詳情，或在找不到 ID 時返回 `null`。3165傳回一個任務的完整詳情，或在找不到 ID 時傳回 `null`。

2386 3166

2387<h3 id="tasklist">3167<h3 id="tasklist">

2388 TaskList3168 TaskList

2394type TaskListInput = {};3174type TaskListInput = {};

2395```3175```

2396 3176

2397返回當前列表中所有任務的快照。3177傳回目前清單中所有任務的快照。

2398 3178

2399<h3 id="exitplanmode">3179<h3 id="exitplanmode">

2400 ExitPlanMode3180 ExitPlanMode

2404 3184

2405```typescript theme={null}3185```typescript theme={null}

2406type ExitPlanModeInput = {3186type ExitPlanModeInput = {

2407 /** 已棄用：不再使用。 */3187 /** Deprecated: no longer used. */

2408 allowedPrompts?: Array<{3188 allowedPrompts?: Array<{

2409 tool: "Bash";3189 tool: "Bash";

2410 prompt: string;3190 prompt: string;

2411 }>;3191 }>;

3192 [k: string]: unknown;

2412};3193};

2413```3194```

2414 3195

2415退出規劃模式。`allowedPrompts` 字段已棄用且被忽略；Claude Code 仍然接受它，以便現有調用者和記錄驗證。在 v2.1.205 之前，它請求基於提示的 Bash 權限以實施計劃。3196退出計畫模式。`allowedPrompts` 欄位已棄用且被忽略；Claude Code 仍接受它以便現有呼叫者和文字記錄驗證。在 v2.1.205 之前，它要求基於提示的 Bash 權限以實施計畫。

2416 3197

2417<h3 id="listmcpresources">3198<h3 id="listmcpresources">

2418 ListMcpResources3199 ListMcpResources

2426};3207};

2427```3208```

2428 3209

2429列出來自連接服務器的可用 MCP 資源。3210列出來自已連接伺服器的可用 MCP 資源。

2430 3211

2431<h3 id="readmcpresource">3212<h3 id="readmcpresource">

2432 ReadMcpResource3213 ReadMcpResource

2441};3222};

2442```3223```

2443 3224

2444從服務器讀取特定的 MCP 資源。3225從伺服器讀取特定 MCP 資源。

2445 3226

2446<h3 id="enterworktree">3227<h3 id="enterworktree">

2447 EnterWorktree3228 EnterWorktree

2456};3237};

2457```3238```

2458 3239

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

3241

3242<h3 id="exitworktree">

3243 ExitWorktree

3244</h3>

3245

3246**工具名稱：** `ExitWorktree`

3247

3248```typescript theme={null}

3249type ExitWorktreeInput = {

3250 action: "keep" | "remove";

3251 discard_changes?: boolean;

3252};

3253```

3254

3255退出目前 git worktree 並返回原始工作目錄。`keep` 動作將 worktree 和分支保留在磁碟上，而 `remove` 刪除兩者。當移除具有未提交檔案或未合併提交的 worktree 時，`discard_changes` 必須為 `true`。

3256

3257<h3 id="enterplanmode">

3258 EnterPlanMode

3259</h3>

3260

3261**工具名稱：** `EnterPlanMode`

3262

3263```typescript theme={null}

3264type EnterPlanModeInput = {};

3265```

3266

3267進入計畫模式，其中 Claude 在進行變更前研究並呈現計畫。

3268

3269<h3 id="croncreate">

3270 CronCreate

3271</h3>

3272

3273**工具名稱：** `CronCreate`

3274

3275```typescript theme={null}

3276type CronCreateInput = {

3277 cron: string;

3278 prompt: string;

3279 recurring?: boolean;

3280 durable?: boolean;

3281};

3282```

3283

3284在本機時間的 5 欄位 cron 排程上排程提示執行。將 `recurring` 設定為 `false` 以在下一個符合時單次觸發。工作預設為工作階段範圍：啟動新對話會清除它們，使用 `--resume` 或 `--continue` 繼續會還原尚未過期的工作。詳見[排程任務](/docs/zh-TW/scheduled-tasks)。

3285

3286將 `durable` 設定為 `true` 以要求持久化到 `.claude/scheduled_tasks.json`，使工作在重新啟動後存活。持久化排程並非在每個工作階段都可用：當不可用時，Claude Code 接受 `durable: true` 但建立工作階段專用工作。讀取輸出的 `durable` 欄位以查看工作是否已持久化。

3287

3288<h3 id="crondelete">

3289 CronDelete

3290</h3>

3291

3292**工具名稱：** `CronDelete`

3293

3294```typescript theme={null}

3295type CronDeleteInput = {

3296 id: string;

3297};

3298```

3299

3300按從 `CronCreate` 傳回的 ID 刪除排程的 cron 工作。

3301

3302<h3 id="cronlist">

3303 CronList

3304</h3>

3305

3306**工具名稱：** `CronList`

3307

3308```typescript theme={null}

3309type CronListInput = {};

3310```

3311

3312列出排程的 cron 工作：來自 `.claude/scheduled_tasks.json` 的持久化工作和來自目前工作階段的工作階段專用工作。

3313

3314<h3 id="schedulewakeup">

3315 ScheduleWakeup

3316</h3>

3317

3318**工具名稱：** `ScheduleWakeup`

3319

3320```typescript theme={null}

3321type ScheduleWakeupInput = {

3322 delaySeconds?: number;

3323 reason?: string;

3324 prompt?: string;

3325 noop?: boolean;

3326 stop?: boolean;

3327};

3328```

3329

3330排程一次性喚醒，在延遲後觸發給定的提示。此工具支援自步調 `/loop` 命令。執行時間將 `delaySeconds` 限制在 60 到 3600 秒之間。除非 `stop` 為 true，否則 `delaySeconds`、`reason`、`prompt` 和 `noop` 欄位為必需。`noop: true` 報告沒有任何變更的喚醒。設定 `stop: true` 以取消待處理的喚醒並結束自步調 `/loop`。`stop` 欄位需要 Claude Code v2.1.202 或更新版本。詳見[工具參考中的 ScheduleWakeup 列](/docs/zh-TW/tools-reference)。

3331

3332<h3 id="remotetrigger">

3333 RemoteTrigger

3334</h3>

3335

3336**工具名稱：** `RemoteTrigger`

3337

3338```typescript theme={null}

3339type RemoteTriggerInput = {

3340 action:

3341 | "list"

3342 | "get"

3343 | "create"

3344 | "update"

3345 | "run"

3346 | "create_webhook_trigger"

3347 | "list_runs"

3348 | "get_run_log";

3349 trigger_id?: string;

3350 session_id?: string;

3351 cursor?: string;

3352 body?: {

3353 [k: string]: unknown;

3354 };

3355};

3356```

3357

3358管理[例行工作](/docs/zh-TW/routines)，即在雲端託管的排程和觸發 Claude Code 執行。此工具支援 `/schedule` 命令。`trigger_id` 對於 `get`、`update`、`run` 和 `list_runs` 動作為必需。`body` 對於 `create`、`update` 和 `create_webhook_trigger` 為必需，對於 `run` 為選擇性。

3359

3360`create_webhook_trigger` 將事件來源附加到現有例行工作，例如觸發它的 [GitHub 事件](/docs/zh-TW/routines#add-a-github-trigger)。`body` 命名來源、事件和要觸發的例行工作。需要 Claude Code v2.1.225 或更新版本。

3361

3362`list_runs` 列出例行工作的最近執行，`get_run_log` 讀取一個執行的日誌。`session_id` 命名要讀取的執行，來自 `list_runs` 結果，`cursor` 透過任一動作的結果進行分頁。兩個動作都需要 Claude Code v2.1.227 或更新版本。

3363

3364此工具僅在工作階段使用啟用例行工作的計畫的 claude.ai 帳戶進行驗證時可用，當您的組織政策停用[網路上的 Claude Code](/docs/zh-TW/claude-code-on-the-web) 時不存在。在 Claude Code v2.1.227 或更新版本上，當所有者[為組織關閉例行工作](/docs/zh-TW/routines#routines-are-disabled-by-your-organizations-policy)時，該工具也不存在。在 v2.1.227 之前，僅關閉例行工作切換的工作階段仍顯示該工具，伺服器拒絕其呼叫。

3365

3366<h3 id="pushnotification">

3367 PushNotification

3368</h3>

3369

3370**工具名稱：** `PushNotification`

3371

3372```typescript theme={null}

3373type PushNotificationInput = {

3374 message: string;

3375 status: "proactive";

3376};

3377```

3378

3379向使用者傳送主動推播通知。將 `message` 保持在 200 個字元以下，因為行動作業系統會截斷較長的文字。詳見[工具參考中的 PushNotification 列](/docs/zh-TW/tools-reference)以了解提供者可用性；推播傳遞透過 Anthropic 託管的基礎設施執行，無法從 Amazon Bedrock、AWS 上的 Claude Platform、Google Cloud 的 Agent Platform 或 Microsoft Foundry 存取。

3380

3381<h3 id="repl">

3382 REPL

3383</h3>

3384

3385**工具名稱：** `REPL`

3386

3387```typescript theme={null}

3388type REPLInput = {

3389 code: string;

3390 description?: string;

3391 timeout?: number;

3392};

3393```

3394

3395在持久 REPL 中執行 JavaScript 程式碼。狀態在呼叫之間保持，並支援頂層 await。`timeout` 以毫秒為單位，預設為 30000，最大為 600000。

3396

3397類型已匯出，但除非您在 [`env` 選項](#options)中設定 `CLAUDE_CODE_REPL=1`，否則該工具在 SDK 工作階段中關閉，並且還需要原生安裝程式提供的基於 Bun 的 `claude` 可執行檔。

3398

3399<h3 id="reportfindings">

3400 ReportFindings

3401</h3>

3402

3403**工具名稱：** `ReportFindings`

3404

3405```typescript theme={null}

3406type ReportFindingsInput = {

3407 level?: "low" | "medium" | "high" | "xhigh" | "max";

3408 findings: Array<{

3409 file: string;

3410 line?: number;

3411 summary: string;

3412 failure_scenario: string;

3413 short_summary?: string;

3414 category?: string;

3415 verdict?: "CONFIRMED" | "PLAUSIBLE";

3416 outcome?: "fixed" | "skipped" | "no_change_needed";

3417 }>;

3418};

3419```

3420

3421將程式碼審查發現報告為結構化清單，以便 Claude Code 可以呈現它們而不是將其列印為文字。`level` 是審查執行的工作量級別。發現按最嚴重優先排序，每次呼叫最多 32 個，當沒有倖存時陣列為空。需要 Claude Code v2.1.196 或更新版本。

3422

3423每個發現包含這些欄位：

3424

3425* `file`：發現所在的儲存庫相對路徑。選擇性 `line` 是它錨定到的 1 索引行。

3426* `summary`：缺陷的單句陳述。`failure_scenario` 描述導致錯誤輸出或當機的具體輸入和狀態。

3427* `short_summary`：選擇性的最多 60 個字元的壓縮標籤，用於緊湊顯示。需要 Claude Code v2.1.212 或更新版本。

3428* `category`：選擇性的發現類型的短 kebab-case slug，例如 `correctness` 或 `test-coverage`。需要 Claude Code v2.1.199 或更新版本。

3429* `verdict`：在驗證通過執行時設定；在僅內嵌審查中不存在。

3430* `outcome`：僅在應用修復後重新報告時設定。

3431

3432<h3 id="artifact">

3433 Artifact

3434</h3>

3435

3436**工具名稱：** `Artifact`

3437

3438```typescript theme={null}

3439type ArtifactInput = {

3440 action?: "publish" | "list";

3441 file_path?: string;

3442 favicon?: string;

3443 limit?: number;

3444 scope?: "mine" | "shared" | "all";

3445 title?: string;

3446 description?: string;

3447 label?: string;

3448 url?: string;

3449 force?: boolean;

3450 capabilities?: Record<string, unknown>;

3451 contract?: "latest" | string;

3452};

3453```

3454

3455將本機 `.html` 或 `.md` 檔案發佈為託管成品頁面，或列出使用者的已發佈成品。省略 `action` 或傳遞 `"publish"` 以發佈 `file_path`，這對於發佈動作以及 `favicon` 為必需，一或兩個標記成品在使用者圖庫中的表情符號。當 HTML 檔案沒有 `<title>` 標籤時，`title` 命名瀏覽器標籤和圖庫中的已發佈頁面。`url` 以現有成品為目標以就地更新，而不是鑄造新的。

3456

3457`force` 是最後手段的覆蓋，捨棄另一個工作階段發佈的較新版本。發生衝突時，失敗的發佈會傳回較新的內容；Claude 將其變更合併到該內容上，或重新讀取成品，然後再次發佈。僅當使用者明確要求捨棄該版本時才傳遞 `force`。

3458

3459傳遞 `"list"` 以列舉使用者的已發佈成品；只有 `limit` 和 `scope` 可能伴隨它。`scope` 預設為 `"mine"`，列出使用者擁有的成品；`"shared"` 列出其他人與使用者共享的成品，`"all"` 列出兩者。

3460

3461* `capabilities`：已發佈頁面使用的執行時功能，按功能名稱鍵入，例如[頁面可能呼叫的連接器](/docs/zh-TW/artifacts#pull-live-data-with-mcp-connectors)。成品服務驗證宣告並拒絕命名帳戶無法使用的功能或給予無效設定的發佈。傳遞 `{}` 以清除儲存的宣告，並在重新部署時省略欄位以保留它。需要 Agent SDK v0.3.235 或更新版本。

3462* `contract`：已發佈頁面執行的執行時版本。省略它以保留成品的目前版本，傳遞 `"latest"` 以升級，或傳遞特定版本以釘選或回滾。需要 Agent SDK v0.3.235 或更新版本。

3463

3464類型已匯出，但該工具在 Agent SDK 工作階段中預設關閉。發佈還需要[成品可用性表](/docs/zh-TW/artifacts#availability)中的每個條件，使用 API 金鑰驗證的工作階段不符合。

3465

3466<h3 id="projects">

3467 Projects

3468</h3>

3469

3470**工具名稱：** `Projects`

3471

3472```typescript theme={null}

3473type ProjectsInput = {

3474 method:

3475 | "project_info"

3476 | "project_read"

3477 | "project_search"

3478 | "project_write"

3479 | "project_delete";

3480 path?: string;

3481 content?: string;

3482 local_path?: string;

3483 present_to_user?: boolean;

3484 query?: string;

3485 n?: number;

3486};

3487```

3488

3489讀取和寫入附加到工作階段的 claude.ai 專案。按 `method` 分派：

3490

3491* `project_info`：傳回專案中繼資料和文件清單。

3492* `project_read`：按 `path` 讀取一個文件。

3493* `project_search`：使用 `query` 查詢專案的知識庫。`n` 限制點擊數，預設為 5。

3494* `project_write`：在 `path` 建立或取代文件，來自 `content`（帶有內嵌文字）或 `local_path`（命名工作目錄內的檔案）中的恰好一個。`present_to_user: true` 將寫入的文件標記為使用者需要查看的可交付成果。

3495* `project_delete`：按 `path` 刪除文件。

3496

3497<h3 id="readmcpresourcedir">

3498 ReadMcpResourceDir

3499</h3>

3500

3501**工具名稱：** `ReadMcpResourceDirTool`

3502

3503```typescript theme={null}

3504type ReadMcpResourceDirInput = {

3505 server: string;

3506 uri: string;

3507};

3508```

3509

3510列出 MCP 伺服器上目錄資源的直接子項。僅可用於已宣告支援目錄列表的伺服器；列表不是遞迴的。目錄列表並非在每個工作階段都啟用：當關閉時，呼叫傳回空的 `resources` 清單，`error` 欄位報告目錄列表未啟用。

3511

3512<h3 id="refreshmcptools">

3513 RefreshMcpTools

3514</h3>

3515

3516**工具名稱：** `RefreshMcpTools`

3517

3518```typescript theme={null}

3519type RefreshMcpToolsInput = {

3520 server?: string; // refresh only this server; omit to refresh all connected servers

3521};

3522```

3523

3524重新查詢已連接 MCP 伺服器的工具清單並應用任何變更。類型已匯出，但 Claude Code 僅在您在 [`env` 選項](#options)中設定 `CLAUDE_CODE_ENABLE_REFRESH_MCP_TOOLS=1` 時註冊該工具，並且僅在至少有一個 MCP 伺服器的工作階段中。需要 Claude Code v2.1.211 或更新版本。

3525

3526<h3 id="showonboardingrolepicker">

3527 ShowOnboardingRolePicker

3528</h3>

3529

3530**工具名稱：** `ShowOnboardingRolePicker`

3531

3532```typescript theme={null}

3533type ShowOnboardingRolePickerInput = {};

3534```

3535

3536在 Cowork 上線期間呈現可點擊的角色選擇器晶片列，以便使用者可以選擇其角色並取得相符的外掛程式安裝。不帶任何引數；角色清單由用戶端定義。呼叫會阻止直到使用者回應。

3537

3538<h3 id="mcpinput">

3539 McpInput

3540</h3>

3541

3542**工具名稱：** `mcp__<server>__<tool>` 形式的動態 MCP 工具名稱

3543

3544```typescript theme={null}

3545type McpInput = {

3546 [k: string]: unknown;

3547};

3548```

3549

3550MCP 工具引數是開放物件：每個伺服器定義自己的參數，因此類型對欄位名稱或值不施加任何限制。請查閱伺服器自己的工具架構以了解特定工具接受的欄位。

2460 3551

2461<h2 id="tool-output-types">3552<h2 id="tool-output-types">

2462 工具輸出類型3553 工具輸出類型

2463</h2>3554</h2>

2464 3555

2465所有內置 Claude Code 工具的輸出架構文檔。這些類型從 `@anthropic-ai/claude-agent-sdk` 導出，代表每個工具返回的實際響應數據。3556所有內建 Claude Code 工具的輸出架構文件。這些類型從 `@anthropic-ai/claude-agent-sdk` 匯出，代表每個工具傳回的實際回應資料。

2466 3557

2467<h3 id="tooloutputschemas">3558<h3 id="tooloutputschemas">

2468 `ToolOutputSchemas`3559 `ToolOutputSchemas`

2469</h3>3560</h3>

2470 3561

2471所有工具輸出類型的聯合。3562從 `@anthropic-ai/claude-agent-sdk` 匯出的工具輸出類型聯合；成員包括：

2472 3563

2473```typescript theme={null}3564```typescript theme={null}

2474type ToolOutputSchemas =3565type ToolOutputSchemas =

2475 | AgentOutput3566 | AgentOutput

3567 | ArtifactOutput

2476 | AskUserQuestionOutput3568 | AskUserQuestionOutput

2477 | BashOutput3569 | BashOutput

3570 | CronCreateOutput

3571 | CronDeleteOutput

3572 | CronListOutput

3573 | EnterPlanModeOutput

2478 | EnterWorktreeOutput3574 | EnterWorktreeOutput

2479 | ExitPlanModeOutput3575 | ExitPlanModeOutput

3576 | ExitWorktreeOutput

2480 | FileEditOutput3577 | FileEditOutput

2481 | FileReadOutput3578 | FileReadOutput

2482 | FileWriteOutput3579 | FileWriteOutput

2483 | GlobOutput3580 | GlobOutput

2484 | GrepOutput3581 | GrepOutput

2485 | ListMcpResourcesOutput3582 | ListMcpResourcesOutput

3583 | McpOutput

2486 | MonitorOutput3584 | MonitorOutput

2487 | NotebookEditOutput3585 | NotebookEditOutput

3586 | ProjectsOutput

3587 | PushNotificationOutput

3588 | ReadMcpResourceDirOutput

2488 | ReadMcpResourceOutput3589 | ReadMcpResourceOutput

3590 | RefreshMcpToolsOutput

3591 | RemoteTriggerOutput

3592 | REPLOutput

3593 | ReportFindingsOutput

3594 | ScheduleWakeupOutput

3595 | ShowOnboardingRolePickerOutput

2489 | TaskCreateOutput3596 | TaskCreateOutput

2490 | TaskGetOutput3597 | TaskGetOutput

2491 | TaskListOutput3598 | TaskListOutput

2501 Agent3608 Agent

2502</h3>3609</h3>

2503 3610

2504**工具名稱：** `Agent`（之前是 `Task`，仍然接受作為別名）3611**工具名稱：** `Agent`。先前的名稱 `Task` 仍被接受為別名，且 [`SDKSystemMessage`](#sdksystemmessage) 初始化訊息中的 `tools` 陣列目前仍將此工具列為 `Task` 以保持向後相容性。

2505 3612

2506```typescript theme={null}3613```typescript theme={null}

2507type AgentOutput =3614type AgentOutput =

2511 agentType?: string;3618 agentType?: string;

2512 content: Array<{ type: "text"; text: string; citations?: unknown[] | null }>;3619 content: Array<{ type: "text"; text: string; citations?: unknown[] | null }>;

2513 resolvedModel?: string;3620 resolvedModel?: string;

3621 modelsUsed?: string[];

2514 totalToolUseCount: number;3622 totalToolUseCount: number;

2515 totalDurationMs: number;3623 totalDurationMs: number;

2516 totalTokens: number;3624 totalTokens: number;

2531 inference_geo?: string | null;3639 inference_geo?: string | null;

2532 speed?: string | null;3640 speed?: string | null;

2533 iterations?: unknown;3641 iterations?: unknown;

3642 output_tokens_details?: {

3643 thinking_tokens?: number | null;

3644 } | null;

2534 };3645 };

2535 toolStats?: {3646 toolStats?: {

2536 readCount: number;3647 readCount: number;

2552 agentId: string;3663 agentId: string;

2553 description: string;3664 description: string;

2554 resolvedModel?: string;3665 resolvedModel?: string;

3666 modelsUsed?: string[];

2555 prompt: string;3667 prompt: string;

2556 outputFile: string;3668 outputFile: string;

2557 canReadOutputFile?: boolean;3669 canReadOutputFile?: boolean;

2566 };3678 };

2567```3679```

2568 3680

2569返回子代理的結果。在 `status` 字段上區分：`"completed"` 用於已完成的任務，`"async_launched"` 用於後台任務，以及 `"remote_launched"` 用於 Claude Code 分派到遠端雲端工作階段的任務，其中 `sessionUrl` 連結到該工作階段，`taskId` 識別它。3681傳回子代理的結果。根據 `status` 欄位進行區分：`"completed"` 表示已完成的工作，`"async_launched"` 表示背景工作，`"remote_launched"` 表示 Claude Code 分派到遠端雲端工作階段的工作，其中 `sessionUrl` 連結到該工作階段，`taskId` 識別它。

3682

3683在 `completed` 變體上，`resolvedModel` 命名子代理啟動時使用的模型，當套用 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection) 或其他覆蓋時，可能與要求的 `model` 輸入不同。此欄位需要 Claude Code v2.1.174 或更新版本。在 `async_launched` 上，它命名工作移至背景時使用的模型。

3684

3685`modelsUsed` 列出子代理使用的模型，按順序排列。此欄位僅在發生中途交換時出現，當執行交換回該模型時，模型會再次出現。在 `async_launched` 上，列表涵蓋背景化前使用的模型。`modelsUsed` 和 `resolvedModel` 的背景化行為都需要 Claude Code v2.1.212 或更新版本。

2570 3686

2571`completed` 和 `async_launched` 變體上的 `resolvedModel` 字段命名子代理實際運行的模型，當應用 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection) 或其他覆蓋時，該模型可能與請求的 `model` 輸入不同。此字段需要 Claude Code v2.1.174 或更高版本。3687如果 Claude Code [保留了子代理的隔離 worktree](/docs/zh-TW/worktrees#isolate-subagents-with-worktrees)，`completed` 結果上的 `worktreePath` 是找到它的位置。`worktreeBranch` 是其分支，當 Claude Code 使用 git 建立 worktree 時出現。

2572 3688

2573在 `completed` 變體上，當子代理在隔離的 git worktree 中運行時，`worktreePath` 被設置，當 Claude Code 創建它時，`worktreeBranch` 命名該 worktree 的分支。`usage.service_tier` 攜帶 API 為子代理的請求報告的服務層字符串。3689Claude Code 從子代理的最終 API 要求填充 `usage` 和 `totalTokens`，而不是從整個執行，所以 `usage.service_tier` 是 API 在該要求上報告的服務層級字串。當存在時，`usage.output_tokens_details.thinking_tokens` 是該要求的輸出令牌中作為思考令牌的數量。`output_tokens_details` 欄位需要 TypeScript SDK v0.3.228 或更新版本，該版本包含 Claude Code v2.1.228。

2574 3690

2575在 v2.1.207 之前，發佈的類型更窄。它省略了 `worktreePath`、`worktreeBranch`、`citations`、`toolStats.frameCount` 以及 `inference_geo`、`speed` 和 `iterations` 使用字段，並將 `service_tier` 類型化為 `"standard" | "priority" | "batch"`。類型標記為可選的字段可能在由較早版本記錄的結果中不存在。3691`usage.output_tokens_details` 在意義上與 [`Usage.output_tokens_details`](#usage) 相符，範圍限於該最終要求，但其每個層級都是選擇性的。保護物件和欄位，例如 `usage.output_tokens_details?.thinking_tokens ?? 0`，而不是直接讀取它。

3692

3693在 v2.1.207 之前，發佈的類型更窄。它省略了 `worktreePath`、`worktreeBranch`、`citations`、`toolStats.frameCount` 和 `inference_geo`、`speed` 和 `iterations` 使用欄位，並將 `service_tier` 類型化為 `"standard" | "priority" | "batch"`。類型標記為選擇性的欄位可能在較早版本記錄的結果中不存在。

2576 3694

2577<h3 id="askuserquestion-2">3695<h3 id="askuserquestion-2">

2578 AskUserQuestion3696 AskUserQuestion

2590 }>;3708 }>;

2591 answers: Record<string, string>;3709 answers: Record<string, string>;

2592 response?: string;3710 response?: string;

3711 annotations?: Record<string, { preview?: string; notes?: string }>;

3712 afkTimeoutMs?: number;

2593};3713};

2594```3714```

2595 3715

2596返回提出的問題和用戶的答案。當用戶輸入自由形式的回覆而不是回答結構化問題時，`response` 被設置；當存在時，Claude 會收到「用戶回應：…」而不是每個問題的答案列表。3716傳回提出的問題和使用者的答案。當使用者輸入自由格式回覆而不是回答結構化問題時，`response` 會被設定；當存在時，Claude 會收到「使用者回應：…」而不是每個問題的答案清單。

2597 3717

2598<h3 id="bash-2">3718<h3 id="bash-2">

2599 Bash3719 Bash

2610 isImage?: boolean;3730 isImage?: boolean;

2611 backgroundTaskId?: string;3731 backgroundTaskId?: string;

2612 backgroundedByUser?: boolean;3732 backgroundedByUser?: boolean;

3733 timedOutAfterMs?: number;

3734 backgroundCwdHint?: string;

3735 backgroundEndsWithFinalResponse?: true;

2613 dangerouslyDisableSandbox?: boolean;3736 dangerouslyDisableSandbox?: boolean;

2614 returnCodeInterpretation?: string;3737 returnCodeInterpretation?: string;

3738 noOutputExpected?: boolean;

2615 structuredContent?: unknown[];3739 structuredContent?: unknown[];

2616 persistedOutputPath?: string;3740 persistedOutputPath?: string;

2617 persistedOutputSize?: number;3741 persistedOutputSize?: number;

3742 staleReadFileStateHint?: string;

3743 ghRateLimitHint?: string;

3744 gitOperation?: {

3745 commit?: { sha: string; kind: "committed" | "amended" | "cherry-picked"; branch?: string };

3746 push?: { branch: string };

3747 branch?: { ref: string; action: "merged" | "rebased" };

3748 pr?: {

3749 number: number;

3750 url?: string;

3752 };

3753 };

2618};3754};

2619```3755```

2620 3756

2621返回命令輸出，stdout/stderr 分開。後台命令包括 `backgroundTaskId`。3757`stdout`、`stderr` 和 `backgroundTaskId` 欄位攜帶：

3758

3759| 欄位 | 它攜帶的內容 |

3760| ------------------ | -------------------------------------- |

3761| `stdout` | 命令的 stdout 和 stderr，合併為一個交錯流 |

3762| `stderr` | 工具本身新增的通知，例如 shell 工作目錄重設，不是命令的 stderr |

3763| `backgroundTaskId` | 對於背景命令存在 |

3764

3765`timedOutAfterMs` 是逾時（以毫秒為單位），當命令達到其逾時並移至背景而不是明確從那裡開始時設定。`backgroundCwdHint` 在背景化命令包含目錄變更內建函式（例如 `cd`、`pushd`、`popd` 或 `chdir`）時設定，並注意工作階段工作目錄未變更。兩個欄位都需要 Claude Code v2.1.210 或更新版本。

3766

3767當在前景執行的子代理擁有背景化命令時，Claude Code 會在該子代理給出最終回應時終止命令。Claude Code 在此類命令上將 `backgroundEndsWithFinalResponse` 設定為 `true`，並在命令存活該輪時省略欄位，如主對話或背景子代理啟動的命令一樣。此欄位需要 Claude Code v2.1.227 或更新版本。

3768

3769Claude Code 將 `gitOperation.commit.branch` 設定為 git 提交摘要行中命名的分支，並對在分離 HEAD 上進行的提交省略它。此欄位需要 Agent SDK v0.3.227 或更新版本。Claude Code 將 `gh pr reopen` 命令報告為 `reopened` PR 動作，需要 Agent SDK v0.3.234 或更新版本。

2622 3770

2623<h3 id="monitor-2">3771<h3 id="monitor-2">

2624 Monitor3772 Monitor

2634};3782};

2635```3783```

2636 3784

2637返回運行監視器的後台任務 ID。使用此 ID 與 `TaskStop` 一起提前取消監視。3785傳回執行中監視器的背景工作 ID。使用此 ID 搭配 `TaskStop` 以提前取消監視。

2638 3786

2639<h3 id="edit-2">3787<h3 id="edit-2">

2640 Edit3788 Edit

2647 filePath: string;3795 filePath: string;

2648 oldString: string;3796 oldString: string;

2649 newString: string;3797 newString: string;

2650 originalFile: string;3798 originalFile: string | null;

2651 structuredPatch: Array<{3799 structuredPatch: Array<{

2652 oldStart: number;3800 oldStart: number;

2653 oldLines: number;3801 oldLines: number;

2664 deletions: number;3812 deletions: number;

2665 changes: number;3813 changes: number;

2666 patch: string;3814 patch: string;

3815 repository?: string | null;

2667 };3816 };

2668};3817};

2669```3818```

2670 3819

2671返回編輯操作的結構化差異。3820傳回編輯操作的結構化差異。

2672 3821

2673<h3 id="read-2">3822<h3 id="read-2">

2674 Read3823 Read

2686 numLines: number;3835 numLines: number;

2687 startLine: number;3836 startLine: number;

2688 totalLines: number;3837 totalLines: number;

3838 /** 當整個檔案讀取因超過令牌上限而自動分頁時為真（內容是部分第一頁）。 */

3839 truncatedByTokenCap?: boolean;

2689 };3840 };

2690 }3841 }

2691 | {3842 | {

2725 count: number;3876 count: number;

2726 outputDir: string;3877 outputDir: string;

2727 };3878 };

3879 /** 第一個提取頁面的文件頁碼；標記工具結果內容中的頁面影像。 */

3880 firstPage?: number;

3881 /** 僅在程序中：頁面影像位元組作為影像區塊在工具結果內容中傳遞，不會保留在發出的 tool_use_result 上，所以此鍵在那裡不存在。 */

3882 pages?: {

3883 base64: string;

3884 mediaType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";

3885 error?: string;

3886 }[];

3887 }

3888 | {

3889 type: "file_unchanged";

3890 file: {

3891 filePath: string;

3892 };

3893 /** 當重複資料刪除符合啟動時播種的項目（CLAUDE.md / 巢狀記憶）而不是先前的 Read tool_result 時設定。 */

3894 source?: "seeded";

2728 };3895 };

2729```3896```

2730 3897

2731返回適合文件類型的文件內容。在 `type` 字段上區分。3898以適合檔案類型的格式傳回檔案內容。根據 `type` 欄位進行區分。

2732 3899

2733<h3 id="write-2">3900<h3 id="write-2">

2734 Write3901 Write

2756 deletions: number;3923 deletions: number;

2757 changes: number;3924 changes: number;

2758 patch: string;3925 patch: string;

3926 repository?: string | null;

2759 };3927 };

3928 userModified?: boolean;

2760};3929};

2761```3930```

2762 3931

2763返回寫入結果，包含結構化差異信息。3932傳回寫入結果及結構化差異資訊。`originalFile` 和 `structuredPatch` 持有的內容取決於寫入：

3933

3934* 對於新建立的檔案，`originalFile` 為 null，`structuredPatch` 為空

3935* 在覆蓋時，`originalFile` 攜帶先前的內容，除非該內容大於約 10 MB：Claude Code 會跳過差異並傳回 `originalFile` null 和 `structuredPatch` 空

3936* 當寫入未變更任何內容或差異逾時時，`structuredPatch` 也為空

2764 3937

2765<h3 id="glob-2">3938<h3 id="glob-2">

2766 Glob3939 Glob

2774 numFiles: number;3947 numFiles: number;

2775 filenames: string[];3948 filenames: string[];

2776 truncated: boolean;3949 truncated: boolean;

3950 totalMatches?: number;

3951 countIsComplete?: boolean;

2777};3952};

2778```3953```

2779 3954

2780返回與 Glob 模式匹配的文件路徑，按修改時間排序。3955傳回符合 glob 模式的檔案路徑，按修改時間排序。

3956

3957`totalMatches` 和 `countIsComplete` 需要 Claude Code v2.1.191 或更新版本。`totalMatches` 報告截斷前的符合檔案數。當 `countIsComplete` 為 false 時，`totalMatches` 是下限，因為基礎搜尋截斷了自己的輸出。

2781 3958

2782<h3 id="grep-2">3959<h3 id="grep-2">

2783 Grep3960 Grep

2793 content?: string;3970 content?: string;

2794 numLines?: number;3971 numLines?: number;

2795 numMatches?: number;3972 numMatches?: number;

3973 totalFiles?: number;

3974 totalLines?: number;

2796 appliedLimit?: number;3975 appliedLimit?: number;

2797 appliedOffset?: number;3976 appliedOffset?: number;

2798};3977};

2799```3978```

2800 3979

2801返回搜索結果。形狀因 `mode` 而異：文件列表、帶匹配的內容或匹配計數。3980傳回搜尋結果。形狀因 `mode` 而異：檔案清單、包含符合的內容或符合計數。在 `count` 模式中，`numFiles` 和 `numMatches` 是完整結果集上的總計，不是分頁切片。在 v2.1.208 之前，截斷列出項目的 `head_limit` 或 `offset` 也會截斷這些總計。

3981

3982`totalFiles` 需要 Claude Code v2.1.208 或更新版本，並在 `files_with_matches` 模式中報告 `head_limit` 和 `offset` 分頁前的結果總數。`totalLines` 需要 Claude Code v2.1.210 或更新版本，並在 `content` 模式中報告分頁前的行總數。

2802 3983

2803<h3 id="taskstop-2">3984<h3 id="taskstop-2">

2804 TaskStop3985 TaskStop

2815};3996};

2816```3997```

2817 3998

2818停止後台任務後返回確認。3999傳回停止背景工作後的確認。

2819 4000

2820<h3 id="notebookedit-2">4001<h3 id="notebookedit-2">

2821 NotebookEdit4002 NotebookEdit

2826```typescript theme={null}4007```typescript theme={null}

2827type NotebookEditOutput = {4008type NotebookEditOutput = {

2828 new_source: string;4009 new_source: string;

4010 old_source?: string;

2829 cell_id?: string;4011 cell_id?: string;

2830 cell_type: "code" | "markdown";4012 cell_type: "code" | "markdown";

2831 language: string;4013 language: string;

2837};4019};

2838```4020```

2839 4021

2840返回筆記本編輯的結果，包含原始和更新的文件內容。4022傳回筆記本編輯的結果及原始和更新的檔案內容。

2841 4023

2842<h3 id="webfetch-2">4024<h3 id="webfetch-2">

2843 WebFetch4025 WebFetch

2853 result: string;4035 result: string;

2854 durationMs: number;4036 durationMs: number;

2855 url: string;4037 url: string;

4038 artifactRead?: {

4039 slug: string;

4040 ver?: string;

4041 seeded?: false;

4042 };

2856};4043};

2857```4044```

2858 4045

2859返回獲取的內容，包含 HTTP 狀態和元數據。4046傳回提取的內容及 HTTP 狀態和中繼資料。

4047

4048`artifactRead` 是 Claude Code 自己的成品讀取記錄，僅當 Claude 提取工作階段可以發佈的成品時出現。Claude Code 在工作階段恢復時讀取它回來，以便稍後發佈基於正確版本；您的程式碼不需要對其採取行動。`slug` 命名成品，`ver` 是讀取記錄的版本，當它未記錄任何內容時不存在，`seeded: false` 標記其完整來源未到達 Claude 的讀取。`seeded` 欄位需要 Agent SDK v0.3.239 或更新版本。

2860 4049

2861<h3 id="websearch-2">4050<h3 id="websearch-2">

2862 WebSearch4051 WebSearch

2875 | string4064 | string

2876 >;4065 >;

2877 durationSeconds: number;4066 durationSeconds: number;

4067 searchCount?: number;

2878};4068};

2879```4069```

2880 4070

2881返回來自網絡的搜索結果。4071傳回來自網路的搜尋結果。

2882 4072

2883<h3 id="workflow-2">4073<h3 id="workflow-2">

2884 Workflow4074 Workflow

2888 4078

2889```typescript theme={null}4079```typescript theme={null}

2890type WorkflowOutput = {4080type WorkflowOutput = {

2891 status: "async_launched";4081 status: "async_launched" | "remote_launched";

2892 taskId: string;4082 taskId: string;

4083 taskType?: "local_workflow" | "remote_agent";

4084 workflowName?: string;

2893 runId?: string;4085 runId?: string;

2894 summary?: string;4086 summary?: string;

2895 transcriptDir?: string;4087 transcriptDir?: string;

2896 scriptPath?: string;4088 scriptPath?: string;

4089 sessionUrl?: string; // 當工作流程作為遠端工作階段啟動時設定

4090 warning?: string;

2897 error?: string;4091 error?: string;

2898};4092};

2899```4093```

2900 4094

2901在工具接受調用後立即返回。最終結果稍後作為任務完成到達。在將運行視為已啟動之前檢查 `error`：失敗語法檢查的腳本返回 `status: "async_launched"` 並設置 `error`，並且永遠不會運行。4095在工具接受呼叫後立即傳回。最終結果稍後作為工作完成到達。在將執行視為已啟動之前檢查 `error`：語法檢查失敗的指令碼傳回 `status: "async_launched"` 並設定 `error`，且永遠不會執行。

2902 4096

2903| 字段 | 類型 | 描述 |4097| 欄位 | 類型 | 描述 |

2904| --------------- | ------------------ | ---------------------------------------------------- |4098| --------------- | --------------------------------------- | --------------------------------------------------------------------------------------- |

4106| `scriptPath` | `string` | 此執行的持久化工作流程指令碼路徑。編輯它並作為 `scriptPath` 傳回以重新執行而不重新傳送指令碼 |

4107| `sessionUrl` | `string` | 雲端工作階段 URL，當 `status` 為 `"remote_launched"` 時設定 |

4108| `warning` | `string` | 非阻止性提醒，例如本機 git 狀態與雲端工作階段將複製的推送分支不同 |

4109| `error` | `string` | 當指令碼語法檢查失敗時設定。當存在時，儘管啟動狀態，執行未啟動 |

2912 4110

2913<h3 id="todowrite-2">4111<h3 id="todowrite-2">

2914 TodoWrite4112 TodoWrite

2931};4129};

2932```4130```

2933 4131

2934返回之前和更新的任務列表。4132傳回先前和更新的工作清單。

2935 4133

2936<Note>4134<Note>

2937 自 TypeScript Agent SDK 0.3.142 起，`TodoWrite` 預設為禁用。改用 `TaskCreate`、`TaskGet`、`TaskUpdate` 和 `TaskList`。請參閱[遷移到 Task 工具](/docs/zh-TW/agent-sdk/todo-tracking#migrate-to-task-tools)以更新您的監視代碼，或設置 `CLAUDE_CODE_ENABLE_TASKS=0` 以恢復為 `TodoWrite`。4135 The following tools are available by default only on Claude 3.x models, Opus 4 through 4.7, Sonnet 4 through 4.6, and Haiku 4.5. On every other model, including model IDs Claude Code doesn't recognize, they aren't available unless you opt in:

4136

4137 * `TodoWrite`

4138 * `TaskCreate`

4139 * `TaskGet`

4140 * `TaskUpdate`

4141 * `TaskList`

4142

4143 Wherever the tools are available, Claude Code provides the four Task tools, or `TodoWrite` instead when you set `CLAUDE_CODE_ENABLE_TASKS=0`.

4144

4145 This default set applies in Claude Code v2.1.268 and later, which the TypeScript Agent SDK bundles from v0.3.268.

4146

4147 請參閱[模型可用性](/docs/zh-TW/agent-sdk/todo-tracking#model-availability)以選擇加入。

2938</Note>4148</Note>

2939 4149

2940<h3 id="taskcreate-2">4150<h3 id="taskcreate-2">

2952};4162};

2953```4163```

2954 4164

2955返回創建的任務及其分配的 ID。4165傳回建立的工作及其指派的 ID。

2956 4166

2957<h3 id="taskupdate-2">4167<h3 id="taskupdate-2">

2958 TaskUpdate4168 TaskUpdate

2973};4183};

2974```4184```

2975 4185

2976返回更新結果，包括哪些字段已更改。4186傳回更新結果，包括哪些欄位已變更。

2977 4187

2978<h3 id="taskget-2">4188<h3 id="taskget-2">

2979 TaskGet4189 TaskGet

2994};4204};

2995```4205```

2996 4206

2997返回完整的任務記錄，或在找不到 ID 時返回 `null`。4207傳回完整工作記錄，或當找不到 ID 時傳回 `null`。

2998 4208

2999<h3 id="tasklist-2">4209<h3 id="tasklist-2">

3000 TaskList4210 TaskList

3014};4224};

3015```4225```

3016 4226

3017返回當前列表中所有任務的快照。4227傳回目前清單中所有工作的快照。

3018 4228

3019<h3 id="exitplanmode-2">4229<h3 id="exitplanmode-2">

3020 ExitPlanMode4230 ExitPlanMode

3028 isAgent: boolean;4238 isAgent: boolean;

3029 filePath?: string;4239 filePath?: string;

3030 hasTaskTool?: boolean;4240 hasTaskTool?: boolean;

4241 planWasEdited?: boolean;

3031 awaitingLeaderApproval?: boolean;4242 awaitingLeaderApproval?: boolean;

3032 requestId?: string;4243 requestId?: string;

3033};4244};

3034```4245```

3035 4246

3036返回退出 Plan Mode 後的計劃狀態。4247傳回退出計畫模式後的計畫狀態。

3037 4248

3038<h3 id="listmcpresources-2">4249<h3 id="listmcpresources-2">

3039 ListMcpResources4250 ListMcpResources

3051}>;4262}>;

3052```4263```

3053 4264

3054返回可用 MCP 資源的數組。4265傳回可用 MCP 資源的陣列。

3055 4266

3056<h3 id="readmcpresource-2">4267<h3 id="readmcpresource-2">

3057 ReadMcpResource4268 ReadMcpResource

3065 uri: string;4276 uri: string;

3066 mimeType?: string;4277 mimeType?: string;

3067 text?: string;4278 text?: string;

4279 blobSavedTo?: string;

3068 }>;4280 }>;

4281 error?: string;

3069};4282};

3070```4283```

3071 4284

3072返回請求的 MCP 資源的內容。4285傳回要求的 MCP 資源的內容。

3073 4286

3074<h3 id="enterworktree-2">4287<h3 id="enterworktree-2">

3075 EnterWorktree4288 EnterWorktree

3085};4298};

3086```4299```

3087 4300

3088返回有關 git worktree 的信息。4301傳回關於 git worktree 的資訊。

4302

4303<h3 id="exitworktree-2">

4304 ExitWorktree

4305</h3>

4306

4307**工具名稱：** `ExitWorktree`

4308

4309```typescript theme={null}

4310type ExitWorktreeOutput = {

4311 action: "keep" | "remove";

4312 originalCwd: string;

4313 worktreePath: string;

4314 worktreeBranch?: string;

4315 tmuxSessionName?: string;

4316 discardedFiles?: number;

4317 discardedCommits?: number;

4318 message: string;

4319};

4320```

4321

4322傳回採取的動作和已退出 worktree 的詳細資訊。

4323

4324<h3 id="enterplanmode-2">

4325 EnterPlanMode

4326</h3>

4327

4328**工具名稱：** `EnterPlanMode`

4329

4330```typescript theme={null}

4331type EnterPlanModeOutput = {

4332 message: string;

4333};

4334```

4335

4336傳回進入計畫模式的確認。

4337

4338<h3 id="croncreate-2">

4339 CronCreate

4340</h3>

4341

4342**工具名稱：** `CronCreate`

4343

4344```typescript theme={null}

4345type CronCreateOutput = {

4346 id: string;

4347 humanSchedule: string;

4348 recurring: boolean;

4349 durable?: boolean; // 當持久化到 .claude/scheduled_tasks.json 時為真；當僅限工作階段時為假

4350};

4351```

4352

4353傳回工作 ID 和排程的人類可讀描述。

4354

4355<h3 id="crondelete-2">

4356 CronDelete

4357</h3>

4358

4359**工具名稱：** `CronDelete`

4360

4361```typescript theme={null}

4362type CronDeleteOutput = {

4363 id: string;

4364};

4365```

4366

4367傳回已刪除工作的 ID。

4368

4369<h3 id="cronlist-2">

4370 CronList

4371</h3>

4372

4373**工具名稱：** `CronList`

4374

4375```typescript theme={null}

4376type CronListOutput = {

4377 jobs: {

4378 id: string;

4379 cron: string;

4380 humanSchedule: string;

4381 prompt: string;

4382 recurring?: boolean;

4383 durable?: boolean;

4384 }[];

4385};

4386```

4387

4388傳回排程的 cron 工作：來自 `.claude/scheduled_tasks.json` 的持久化工作和來自目前工作階段的僅限工作階段工作。僅限工作階段的工作攜帶 `durable: false`；從磁碟讀取的工作省略欄位。

4389

4390<h3 id="schedulewakeup-2">

4391 ScheduleWakeup

4392</h3>

4393

4394**工具名稱：** `ScheduleWakeup`

4395

4396```typescript theme={null}

4397type ScheduleWakeupOutput = {

4398 scheduledFor: number;

4399 clampedDelaySeconds: number;

4400 wasClamped: boolean;

4401 stopped?: boolean;

4402 cancelledWakeups?: number;

4403};

4404```

4405

4406傳回喚醒將觸發的時間（作為紀元毫秒時間戳記）、實際使用的延遲以及要求的延遲是否被限制。`stopped` 欄位在呼叫以 `stop: true` 結束迴圈時為 `true`。它需要 Claude Code v2.1.202 或更新版本。`cancelledWakeups` 欄位計算 `stop: true` 呼叫取消了多少個待處理喚醒。值 0 表示沒有待處理，重複 `/loop` cron 不會被 `stop: true` 取消。它需要 Claude Code v2.1.206 或更新版本。

4407

4408<h3 id="remotetrigger-2">

4409 RemoteTrigger

4410</h3>

4411

4412**工具名稱：** `RemoteTrigger`

4413

4414```typescript theme={null}

4415type RemoteTriggerOutput = {

4416 status: number;

4417 json: string;

4418 summary?: string;

4419};

4420```

4421

4422傳回觸發操作的 API 回應狀態和本體。

4423

4424<h3 id="pushnotification-2">

4425 PushNotification

4426</h3>

4427

4428**工具名稱：** `PushNotification`

4429

4430```typescript theme={null}

4431type PushNotificationOutput = {

4432 message: string;

4433 pushSent?: boolean;

4434 localSent?: boolean;

4435 disabledReason?: "config_off" | "user_present" | "no_transport";

4436 sentAt?: string;

4437};

4438```

4439

4440傳回傳遞詳細資訊，包括是否傳送了推送或本機通知以及為什麼跳過傳遞。

4441

4442<h3 id="repl-2">

4443 REPL

4444</h3>

4445

4446**工具名稱：** `REPL`

4447

4448```typescript theme={null}

4449type REPLOutput = {

4450 code: string;

4451 result: {

4452 [k: string]: unknown;

4453 };

4454 stdout: string;

4455 stderr: string;

4456 error?: string;

4457 registeredTools?: string[];

4458 images?: {

4459 base64: string;

4460 mediaType: string;

4461 }[];

4462 documents?: {

4463 base64: string;

4464 }[];

4465};

4466```

4467

4468傳回執行結果、擷取的主控台輸出以及內部 `Read` 呼叫呈現的任何影像或文件。

4469

4470<h3 id="reportfindings-2">

4471 ReportFindings

4472</h3>

4473

4474**工具名稱：** `ReportFindings`

4475

4476```typescript theme={null}

4477type ReportFindingsOutput = {

4478 count: number;

4479 level?: "low" | "medium" | "high" | "xhigh" | "max";

4480 findings: Array<{

4481 file: string;

4482 line?: number;

4483 summary: string;

4484 failure_scenario: string;

4485 short_summary?: string;

4486 category?: string;

4487 verdict?: "CONFIRMED" | "PLAUSIBLE";

4488 outcome?: "fixed" | "skipped" | "no_change_needed";

4489 }>;

4490};

4491```

4492

4493傳回報告的發現數、審查執行的工作量級別以及為結果本體回顯的發現。需要 Claude Code v2.1.196 或更新版本。回顯的 `short_summary` 欄位需要 Claude Code v2.1.212 或更新版本。

4494

4495<h3 id="artifact-2">

4496 Artifact

4497</h3>

4498

4499**工具名稱：** `Artifact`

4500

4501```typescript theme={null}

4502type ArtifactOutput =

4503 | {

4504 url: string;

4505 path: string;

4506 title?: string;

4507 version?: string;

4508 capabilities?: unknown;

4509 stored?: {

4510 contract: string;

4511 capabilities?: Record<string, unknown>;

4512 };

4513 warnings?: string[];

4514 contract?: string;

4515 updated?: boolean;

4516 liveSubscription?: string;

4517 }

4518 | {

4519 artifacts: Array<{

4520 title: string;

4521 url: string;

4522 updatedAt?: string;

4523 rel?: "mine" | "shared";

4524 }>;

4525 truncated?: boolean;

4526 scope?: "shared" | "all";

4527 };

4528```

4529

4530傳回已發佈頁面的 `url` 和為發佈動作發佈的本機 `path`，當發佈重新部署現有成品時 `updated` 設定為 true，`warnings` 攜帶任何發佈時間建議。清單動作改為傳回 `artifacts` 列，當存在超過要求限制的成品時 `truncated` 設定。在其範圍不是 `"mine"` 的清單上，每列攜帶 `rel` 標記使用者是否擁有成品或與他們共享，輸出的 `scope` 記錄哪個非預設範圍產生清單；兩者在預設清單上不存在。

4531

4532<h3 id="projects-2">

4533 Projects

4534</h3>

4535

4536**工具名稱：** `Projects`

4537

4538```typescript theme={null}

4539type ProjectsOutput =

4540 | {

4541 method: "project_info";

4542 notice?: string;

4543 name: string;

4544 description: string;

4545 instructions: string;

4546 docs: Array<{ path: string; created_at: string | null }>;

4547 files?: Array<{

4548 path: string;

4549 file_kind: string;

4550 created_at: string | null;

4551 }>;

4552 sync_sources?: Array<{

4553 type: string | null;

4554 config: Record<string, unknown>;

4555 }>;

4556 knowledge: {

4557 knowledge_size: number;

4558 max_knowledge_size: number;

4559 };

4560 }

4561 | {

4562 method: "project_read";

4563 notice?: string;

4564 path: string;

4565 file_kind?: string;

4566 content?: string;

4567 local_file?: string;

4568 created_at: string | null;

4569 }

4570 | {

4571 method: "project_search";

4572 notice?: string;

4573 rag: boolean;

4574 hits?: Array<{ name?: string; doc_uuid?: string; text?: string }>;

4575 docs?: string[];

4576 }

4577 | {

4578 method: "project_write";

4579 notice?: string;

4580 path: string;

4581 doc_uuid: string;

4582 replaced: boolean;

4583 present_to_user?: boolean;

4584 local_path?: string;

4585 }

4586 | {

4587 method: "project_delete";

4588 notice?: string;

4589 path: string;

4590 deleted: boolean;

4591 };

4592```

4593

4594根據 `method` 欄位進行區分，鏡像輸入。`project_read` 在 `content` 中內聯傳回小文字文件，並改為將較大文件寫入 `local_file` 路徑；`project_search` 當專案的索引可用時傳回 RAG `hits` 並設定 `rag: true`，否則回退到 `docs` 路徑清單。

4595

4596<h3 id="readmcpresourcedir-2">

4597 ReadMcpResourceDir

4598</h3>

4599

4600**工具名稱：** `ReadMcpResourceDirTool`

4601

4602```typescript theme={null}

4603type ReadMcpResourceDirOutput = {

4604 resources: Array<{

4605 uri: string;

4606 name: string;

4607 mimeType?: string;

4608 }>;

4609 error?: string;

4610};

4611```

4612

4613傳回目錄資源的直接子項。子目錄以 mimeType `"inode/directory"` 出現；`error` 在伺服器無法列出目錄時攜帶人類可讀的訊息。

4614

4615<h3 id="refreshmcptools-2">

4616 RefreshMcpTools

4617</h3>

4618

4619**工具名稱：** `RefreshMcpTools`

4620

4621```typescript theme={null}

4622type RefreshMcpToolsOutput = Array<{

4623 server: string;

4624 status: "refreshed" | "error" | "not_connected";

4625 toolCount?: number; // 此伺服器現在可用的工具

4626 added?: string[]; // 此重新整理新增的工具名稱

4627 removed?: string[]; // 此重新整理移除的工具名稱

4628 error?: string; // 重新整理失敗或伺服器無法使用的原因

4629}>;

4630```

4631

4632傳回每個伺服器一個項目：`refreshed` 表示已套用重新查詢的工具清單，`error` 表示重新查詢失敗且保留了先前的工具集，`not_connected` 表示伺服器沒有即時連線可查詢。

4633

4634<h3 id="showonboardingrolepicker-2">

4635 ShowOnboardingRolePicker

4636</h3>

4637

4638**工具名稱：** `ShowOnboardingRolePicker`

4639

4640```typescript theme={null}

4641type ShowOnboardingRolePickerOutput = {

4642 role?: string;

4643 dismissed?: boolean;

4644};

4645```

4646

4647傳回使用者的選擇：當他們選擇角色晶片或輸入一個時為 `role`，當他們關閉選擇器時為 `dismissed: true`。空物件表示使用者批准了呼叫而未選擇角色。

4648

4649<h3 id="mcpoutput">

4650 McpOutput

4651</h3>

4652

4653**工具名稱：** 形式為 `mcp__<server>__<tool>` 的動態 MCP 工具名稱

4654

4655```typescript theme={null}

4656type McpOutput =

4657 | string

4658 | {

4659 type: string;

4660 [k: string]: unknown;

4661 }[]

4662 | {

4663 [k: string]: unknown;

4664 };

4665```

4666

4667MCP 工具結果根據伺服器傳回為字串或內容區塊陣列。匯出類型中的尾部純物件分支是架構產生成品：SDK 不傳回裸物件，因為伺服器的結構化輸出在傳回前被序列化為 JSON 字串。在執行時值也可能是 `undefined`，儘管匯出的類型不對此進行建模。

3089 4668

3090<h2 id="permission-types">4669<h2 id="permission-types">

3091 權限類型4670 權限類型

3174 `ApiKeySource`4753 `ApiKeySource`

3175</h3>4754</h3>

3176 4755

4756會話請求的 API 金鑰來源，在 [`SDKSystemMessage`](#sdksystemmessage) 初始化消息上報告為 `apiKeySource`。

4757

3177```typescript theme={null}4758```typescript theme={null}

3178type ApiKeySource = "user" | "project" | "org" | "temporary" | "oauth";4759type ApiKeySource =

4760 | "ANTHROPIC_API_KEY"

4761 | "apiKeyHelper"

4762 | "/login managed key"

4763 | "none"

4764 | "user"

4765 | "project"

4766 | "org"

4767 | "temporary"

4768 | "oauth";

3179```4769```

3180 4770

4771Claude Code 報告四個值之一：

4772

4773| 值 | 使用中的金鑰 |

4774| -------------------- | --------------------------------------------------------------------------------------------------- |

4775| `ANTHROPIC_API_KEY` | `ANTHROPIC_API_KEY` 環境變數中的金鑰 |

4776| `apiKeyHelper` | 您的 [`apiKeyHelper`](/docs/zh-TW/settings-reference#apikeyhelper) 命令返回的金鑰 |

4777| `/login managed key` | 當您使用 [Claude Console 帳戶](/docs/zh-TW/authentication#claude-console-authentication) 登入時 Claude Code 儲存的金鑰 |

4778| `none` | 沒有 API 金鑰。會話以其他方式進行身份驗證，例如 claude.ai 登入、持有人令牌或雲端提供者 |

4779

4780Agent SDK v0.3.234 及更高版本在類型中列出這四個值。該類型也保留 `user`、`project`、`org`、`temporary` 和 `oauth`，以便舊代碼仍然可以編譯，Claude Code 不報告它們。

4781

3181<h3 id="sdkbeta">4782<h3 id="sdkbeta">

3182 `SdkBeta`4783 `SdkBeta`

3183</h3>4784</h3>

3184 4785

3185可通過 `betas` 選項啟用的可用測試功能。見 [Beta 標頭](https://platform.claude.com/docs/zh-TW/api/beta-headers) 了解更多信息。4786可通過 `betas` 選項啟用的可用測試功能。見 [Beta 標頭](https://platform.claude.com/docs/en/api/beta-headers) 了解更多資訊。

3186 4787

3187```typescript theme={null}4788```typescript theme={null}

3188type SdkBeta = "context-1m-2025-08-07";4789type SdkBeta = "context-1m-2025-08-07";

3189```4790```

3190 4791

3191<Warning>4792<Warning>

3192 `context-1m-2025-08-07` beta 自 2026 年 4 月 30 日起已停用。使用 Claude Sonnet 4.5 或 Sonnet 4 傳遞此值無效，超過標準 200k 令牌上下文窗口的請求返回錯誤。要使用 1M 令牌上下文窗口，請遷移到 [Claude Sonnet 5、Claude Sonnet 4.6、Claude Opus 4.6、Claude Opus 4.7 或 Claude Opus 4.8](https://platform.claude.com/docs/zh-TW/about-claude/models/overview)，它們以標準定價包括 1M 上下文，無需 beta 標頭。4793 `context-1m-2025-08-07` beta 自 2026 年 4 月 30 日起已停用。使用 Claude Sonnet 4.5 或 Sonnet 4 傳遞此值無效，超過標準 200k 令牌上下文視窗的請求返回錯誤。要使用 1M 令牌上下文視窗，請遷移到 [Claude Opus 5、Claude Sonnet 5、Claude Sonnet 4.6、Claude Opus 4.6、Claude Opus 4.7 或 Claude Opus 4.8](https://platform.claude.com/docs/en/about-claude/models/overview)，它們以標準定價包括 1M 上下文，無需 beta 標頭。

3193</Warning>4794</Warning>

3194 4795

3195<h3 id="slashcommand">4796<h3 id="slashcommand">

3196 `SlashCommand`4797 `SlashCommand`

3197</h3>4798</h3>

3198 4799

3199有關可用 slash command 的信息。4800有關可用命令的資訊。

3200 4801

3201```typescript theme={null}4802```typescript theme={null}

3202type SlashCommand = {4803type SlashCommand = {

3211 `ModelInfo`4812 `ModelInfo`

3212</h3>4813</h3>

3213 4814

3214有關可用模型的信息。4815有關可用模型的資訊。

3215 4816

3216```typescript theme={null}4817```typescript theme={null}

3217type ModelInfo = {4818type ModelInfo = {

3227};4828};

3228```4829```

3229 4830

3230| 字段 | 類型 | 描述 |4831| 欄位 | 類型 | 描述 |

3231| :------------------------- | :----------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- |4832| :------------------------- | :----------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- |

3241 4842

3242<h3 id="agentinfo">4843<h3 id="agentinfo">

3243 `AgentInfo`4844 `AgentInfo`

3244</h3>4845</h3>

3245 4846

3246有關可通過 Agent 工具調用的可用子代理的信息。4847有關可通過 Agent 工具調用的可用子代理的資訊。

3247 4848

3248```typescript theme={null}4849```typescript theme={null}

3249type AgentInfo = {4850type AgentInfo = {

3253};4854};

3254```4855```

3255 4856

3256| 字段 | 類型 | 描述 |4857| 欄位 | 類型 | 描述 |

3257| :------------ | :-------------------- | :------------------------------------------ |4858| :------------ | :-------------------- | :------------------------------------------------------------------------------------------------------------------------- |

3261 4862

3262<h3 id="mcpserverstatus">4863<h3 id="mcpserverstatus">

3263 `McpServerStatus`4864 `McpServerStatus`

3264</h3>4865</h3>

3265 4866

3266連接的 MCP 服務器的狀態。4867連接的 MCP 伺服器的狀態。

3267 4868

3268```typescript theme={null}4869```typescript theme={null}

3269type McpServerStatus = {4870type McpServerStatus = {

3292 `McpServerStatusConfig`4893 `McpServerStatusConfig`

3293</h3>4894</h3>

3294 4895

3295MCP 服務器的配置，如 `mcpServerStatus()` 報告的那樣。這是所有 MCP 服務器傳輸類型的聯合。4896MCP 伺服器的設定，如 `mcpServerStatus()` 報告的那樣。這是所有 MCP 伺服器傳輸類型的聯合。

3296 4897

3297```typescript theme={null}4898```typescript theme={null}

3298type McpServerStatusConfig =4899type McpServerStatusConfig =

3309 `AccountInfo`4910 `AccountInfo`

3310</h3>4911</h3>

3311 4912

3312經過身份驗證的用戶的帳戶信息。4913經過身份驗證的使用者的帳戶資訊。

3313 4914

3314```typescript theme={null}4915```typescript theme={null}

3315type AccountInfo = {4916type AccountInfo = {

3325 `ModelUsage`4926 `ModelUsage`

3326</h3>4927</h3>

3327 4928

3328結果消息中返回的每個模型使用統計。`costUSD` 值是客戶端估計。見 [跟蹤成本和使用情況](/docs/zh-TW/agent-sdk/cost-tracking) 了解計費注意事項。4929結果消息中返回的每個模型使用統計。`costUSD` 值是客戶端估計。見 [追蹤成本和使用情況](/docs/zh-TW/agent-sdk/cost-tracking) 了解計費注意事項。

3329 4930

3330```typescript theme={null}4931```typescript theme={null}

3331type ModelUsage = {4932type ModelUsage = {

3332 inputTokens: number;4933 inputTokens: number;

3333 outputTokens: number;4934 outputTokens: number;

4935 thinkingTokens?: number;

3334 cacheReadInputTokens: number;4936 cacheReadInputTokens: number;

3335 cacheCreationInputTokens: number;4937 cacheCreationInputTokens: number;

3336 webSearchRequests: number;4938 webSearchRequests: number;

3337 costUSD: number;4939 costUSD: number;

3338 contextWindow: number;4940 contextWindow: number;

3339 maxOutputTokens: number;4941 maxOutputTokens: number;

4942 canonicalModel?: string;

4943 provider?: string;

4944 costBasis?: 'list' | 'managed' | 'unknown';

3340};4945};

3341```4946```

3342 4947

4948`thinkingTokens` 計算此模型生成的思考令牌。`outputTokens` 已包括它們，所以不要將兩者相加。該欄位在執行在記錄它的 Claude Code 版本上的轉數之前不存在，因此在較早版本上開始的已復原會話報告部分計數。`thinkingTokens` 需要 Agent SDK v0.3.257 或更高版本。

4949

4950`canonicalModel` 和 `provider` 欄位需要 Claude Code v2.1.218 或更高版本。`canonicalModel` 是定價查詢使用的規範模型 ID；它可能與鍵入項目的原始模型字串不同，例如當該字串是提供者特定 ID 或別名時。

4951

4952`provider` 命名提供模型的 API 後端，例如 `firstParty`、`bedrock`、`vertex`、`foundry`、`anthropicAws`、`mantle` 或 `gateway`。

4953

4954`costBasis` 命名為模型最新請求定價的價格表：`list` 表示清單價格，`managed` 表示 [`modelPricing`](/docs/zh-TW/settings-reference#modelpricing) 表，或 `unknown` 當兩者都不符合模型 ID 時。該欄位需要 Claude Code v2.1.246 或更高版本。

4955

3343<h3 id="configscope">4956<h3 id="configscope">

3344 `ConfigScope`4957 `ConfigScope`

3345</h3>4958</h3>

3352 `NonNullableUsage`4965 `NonNullableUsage`

3353</h3>4966</h3>

3354 4967

3355[`Usage`](#usage) 的版本，所有可空字段都變為非可空。4968[`Usage`](#usage) 的版本，所有可空欄位都變為非可空。

3356 4969

3357```typescript theme={null}4970```typescript theme={null}

3358type NonNullableUsage = {4971type NonNullableUsage = {

3381 speed: "standard" | "fast" | null;4994 speed: "standard" | "fast" | null;

3382 inference_geo: string | null;4995 inference_geo: string | null;

3383 iterations: BetaIterationsUsage | null;4996 iterations: BetaIterationsUsage | null;

4997 output_tokens_details: BetaOutputTokensDetails | null;

3384};4998};

3385```4999```

3386 5000

3387`BetaServerToolUsage` 和 `BetaIterationsUsage` 在 `@anthropic-ai/sdk` 中定義。5001`BetaServerToolUsage`、`BetaIterationsUsage` 和 `BetaOutputTokensDetails` 在 `@anthropic-ai/sdk` 中定義。

5002

5003`output_tokens_details` 按類別分解計費輸出。它目前包含一個欄位 `thinking_tokens: number`，計算模型生成的輸出令牌作為內部推理，包括思考塊分隔符。`output_tokens_details` 欄位需要 TypeScript SDK v0.3.228 或更高版本，它捆綁 Claude Code v2.1.228。

5004

5005* **計費**：讀取分解以進行可觀測性，而不是計費。`output_tokens` 保持權威總計，`output_tokens - thinking_tokens` 近似非推理輸出。

5006* **計數涵蓋的內容**：模型生成的原始推理，可能比響應正文中返回的思考文本更長。API 通過重新令牌化該原始文本來計算它，因此它可能與模型的確切生成計數相差幾個令牌。

5007* **串流**：在串流助手消息上，此分解（如 `output_tokens`）是 `message_start` 佔位符，不包含實際計數，因此從結果消息的 `usage` 讀取它，如 [從結果消息讀取輸出令牌](/docs/zh-TW/agent-sdk/cost-tracking#read-output-tokens-from-the-result-message) 所述。在結果消息上，當模型或提供者不報告分解時，`thinking_tokens` 讀取 `0`。

5008* **`null` 情況**：`output_tokens_details` 本身在 Claude Code 合成的助手消息上為 `null`，例如 API 錯誤消息。

3388 5009

3389<h3 id="calltoolresult">5010<h3 id="calltoolresult">

3390 `CallToolResult`5011 `CallToolResult`

3391</h3>5012</h3>

3392 5013

3393MCP 工具結果類型（來自 `@modelcontextprotocol/sdk/types.js`）。`structuredContent` 是一個 JSON 對象，可以與 `content` 一起返回，包括圖像塊。見 [返回結構化數據](/docs/zh-TW/agent-sdk/custom-tools#return-structured-data)。5014MCP 工具結果類型（來自 `@modelcontextprotocol/sdk/types.js`）。`structuredContent` 是一個 JSON 物件，可以與 `content` 一起返回，包括圖像塊。見 [返回結構化資料](/docs/zh-TW/agent-sdk/custom-tools#return-structured-data)。

3394 5015

3395```typescript theme={null}5016```typescript theme={null}

3396type CallToolResult = {5017type CallToolResult = {

3397 content: Array<{5018 content: Array<{

3399 // 其他字段因類型而異5020 // 其他欄位因類型而異

3400 }>;5021 }>;

3401 structuredContent?: Record<string, unknown>;5022 structuredContent?: Record<string, unknown>;

3402 isError?: boolean;5023 isError?: boolean;

3403};5024};

3404```5025```

3405 5026

5027<h3 id="sdkmcpresourcelink">

5028 `SDKMcpResourceLink`

5029</h3>

5030

5031MCP 工具按參考返回的一個檔案。Claude Code 從工具結果中的 `resource_link` 塊構建每個項目，並將清單作為 `resourceLinks` 傳遞到 [`SDKUserMessage.tool_use_result`](#sdkusermessage)，或作為 `resource_links` 傳遞到 [`SDKTaskNotificationMessage`](#sdktasknotificationmessage)（當呼叫在背景中完成時）。需要 Agent SDK v0.3.257 或更高版本。

5032

5033```typescript theme={null}

5034type SDKMcpResourceLink = {

5035 uri: string;

5036 name: string;

5037 title?: string;

5038 description?: string;

5039 mimeType?: string;

5040 size?: number;

5041 annotations?: Record<string, unknown>;

5042};

5043```

5044

5045Claude Code 丟棄其 `uri` 或 `name` 不是字串的塊，並省略其值不是列出類型的可選欄位。

5046

5047| 欄位 | 類型 | 描述 |

5048| :------------ | :------------------------------------- | :------------------ |

5049| `uri` | `string` | 資源的 URI，如伺服器返回的那樣 |

5050| `name` | `string` | 伺服器給資源的名稱 |

5056

3406<h3 id="thinkingconfig">5057<h3 id="thinkingconfig">

3407 `ThinkingConfig`5058 `ThinkingConfig`

3408</h3>5059</h3>

3413type ThinkingDisplay = "summarized" | "omitted";5064type ThinkingDisplay = "summarized" | "omitted";

3414 5065

3415type ThinkingConfig =5066type ThinkingConfig =

3416 | { type: "adaptive"; display?: ThinkingDisplay } // 模型確定何時以及多少推理（Opus 4.6+）5067 | { type: "adaptive"; display?: ThinkingDisplay } // 模型決定何時以及多少推理（Opus 4.6+）

3417 | { type: "enabled"; budgetTokens?: number; display?: ThinkingDisplay } // 固定思考令牌預算5068 | { type: "enabled"; budgetTokens?: number; display?: ThinkingDisplay } // 固定思考令牌預算

3418 | { type: "disabled" }; // 無擴展思考5069 | { type: "disabled" }; // 無擴展思考

3419```5070```

3420 5071

3421可選的 `display` 字段控制思考文本是否返回為 `"summarized"` 或 `"omitted"`。在 Claude Opus 4.7 及更高版本上，API 默認值為 `"omitted"`，因此設置 `"summarized"` 以在 `thinking` 塊中接收思考內容。5072可選的 `display` 欄位控制思考文本是否返回為 `"summarized"` 或 `"omitted"`。在 Claude Opus 4.7 及更高版本上，API 預設值為 `"omitted"`，因此設定 `"summarized"` 以在 `thinking` 塊中接收思考內容。Claude Code 不會將 `display` 傳送到 Amazon Bedrock 或 Google Cloud 的 Agent Platform，因此在這些提供者上 Opus 4.7 及更高版本返回空 `thinking` 塊，即使您將 `display` 設定為 `"summarized"`。

3422 5073

3423<h3 id="spawnedprocess">5074<h3 id="spawnedprocess">

3424 `SpawnedProcess`5075 `SpawnedProcess`

3425</h3>5076</h3>

3426 5077

3427自定義進程生成的介面（與 `spawnClaudeCodeProcess` 選項一起使用）。`ChildProcess` 已滿足此介面。5078自訂進程生成的介面（與 `spawnClaudeCodeProcess` 選項一起使用）。`ChildProcess` 已滿足此介面。

3428 5079

3429```typescript theme={null}5080```typescript theme={null}

3430interface SpawnedProcess {5081interface SpawnedProcess {

3455 `SpawnOptions`5106 `SpawnOptions`

3456</h3>5107</h3>

3457 5108

3458傳遞給自定義生成函數的選項。5109傳遞給自訂生成函數的選項。

3459 5110

3460```typescript theme={null}5111```typescript theme={null}

3461interface SpawnOptions {5112interface SpawnOptions {

3468```5119```

3469 5120

3470<Note>5121<Note>

3471 `signal` 字段告訴您的生成函數何時拆除進程。將其作為 `signal` 選項傳遞給 Node 的 `spawn()`，或將其傳遞給您的 VM 或容器拆除處理程序。5122 `signal` 欄位告訴您的生成函數何時拆除進程。將其作為 `signal` 選項傳遞給 Node 的 `spawn()`，或將其傳遞給您的 VM 或容器拆除處理程序。

3472 5123

3473 此信號不會在 [`Options.abortController`](#options) 中止的瞬間觸發。SDK 首先關閉進程的 stdin 並等待約兩秒，以便 CLI 可以乾淨地關閉，然後中止此信號。要在調用者中止的瞬間做出反應，請改為監聽您自己的 `Options.abortController.signal`，您的生成函數可以從其封閉範圍引用。5124 此信號不會在 [`Options.abortController`](#options) 中止的瞬間觸發。SDK 首先關閉進程的 stdin 並等待約兩秒，以便 CLI 可以乾淨地關閉，然後中止此信號。要在呼叫者中止的瞬間做出反應，請改為監聽您自己的 `Options.abortController.signal`，您的生成函數可以從其封閉範圍參考。

3474</Note>5125</Note>

3475 5126

3476<h3 id="mcpsetserversresult">5127<h3 id="mcpsetserversresult">

3487};5138};

3488```5139```

3489 5140

5141當您呼叫 `setMcpServers()` 時，Claude Code 應用這些規則：

5142

5143* **呼叫未命名的伺服器**：Claude Code 保持外掛提供的伺服器運行。需要 Agent SDK v0.3.210 或更高版本。

5144* **呼叫命名的伺服器**：除了 CLI 在啟動時啟動的內建伺服器外，Claude Code 僅當其設定與您傳遞的設定不同時才替換運行中的伺服器。

5145* **CLI 在啟動時啟動的內建伺服器**：如果呼叫命名一個，Claude Code 丟棄該項目並在 `errors` 中報告它。

5146

5147承諾在新添加的 stdio、HTTP 和 SSE 伺服器連接或失敗後解決，因此來自已連接伺服器的工具在下一個轉數上可用。

5148

5149`added` 列出 Claude Code 添加或替換的伺服器，無論它們是否連接。未能連接的伺服器同時出現在 `added` 和 `errors` 中，失敗文本在 `errors` 下，`failed` 行在 [`mcpServerStatus()`](#methods) 中。在 Claude Code v2.1.257 之前，其連接嘗試拋出的伺服器僅在 `errors` 下報告。

5150

3490<h3 id="rewindfilesresult">5151<h3 id="rewindfilesresult">

3491 `RewindFilesResult`5152 `RewindFilesResult`

3492</h3>5153</h3>

3500 filesChanged?: string[];5161 filesChanged?: string[];

3501 insertions?: number;5162 insertions?: number;

3502 deletions?: number;5163 deletions?: number;

5164 skippedLinks?: number;

3503};5165};

3504```5166```

3505 5167

5168`skippedLinks` 計算倒帶拒絕復原或刪除以確保連結安全的追蹤路徑：追蹤路徑上的符號連結、硬連結或其他非常規檔案，不再解析為檢查點時指向的位置的父目錄，或無法安全讀取的備份。該欄位需要 Claude Code v2.1.216 或更高版本。使用 `rewindFiles(userMessageId, { dryRun: true })` 的預覽呼叫永遠不會設定它。

5169

3506<h3 id="sdkstatusmessage">5170<h3 id="sdkstatusmessage">

3507 `SDKStatusMessage`5171 `SDKStatusMessage`

3508</h3>5172</h3>

3524 `SDKTaskNotificationMessage`5188 `SDKTaskNotificationMessage`

3525</h3>5189</h3>

3526 5190

3527後台任務完成、失敗或停止時的通知。後台任務包括 `run_in_background` Bash 命令、[Monitor](#monitor) 監視和後台子代理。5191背景任務完成、失敗或停止時的通知。背景任務包括 `run_in_background` Bash 命令、[Monitor](#monitor) 監視和背景子代理。對於 `ambient` 欄位，見 [`SDKTaskStartedMessage`](#sdktaskstartedmessage)，它定義它及其版本要求。

3528 5192

3529```typescript theme={null}5193```typescript theme={null}

3530type SDKTaskNotificationMessage = {5194type SDKTaskNotificationMessage = {

3535 status: "completed" | "failed" | "stopped";5199 status: "completed" | "failed" | "stopped";

3536 output_file: string;5200 output_file: string;

3537 summary: string;5201 summary: string;

5202 ambient?: boolean;

3538 usage?: {5203 usage?: {

3539 total_tokens: number;5204 total_tokens: number;

3540 tool_uses: number;5205 tool_uses: number;

3541 duration_ms: number;5206 duration_ms: number;

3542 };5207 };

5208 resource_links?: SDKMcpResourceLink[];

3543 uuid: UUID;5209 uuid: UUID;

3544 session_id: string;5210 session_id: string;

3545};5211};

3546```5212```

3547 5213

5214當 Claude Code [將長 MCP 工具呼叫移至背景](/docs/zh-TW/mcp#automatic-backgrounding-of-long-tool-calls) 時，該呼叫的 `tool_result` 塊僅保留佔位符，呼叫的實際結果在此通知中到達。使用 `tool_use_id` 將通知與呼叫匹配。在 `completed` 通知上，`resource_links` 列出工具按參考返回的檔案作為 [`SDKMcpResourceLink`](#sdkmcpresourcelink) 項目，具有與 [`tool_use_result.resourceLinks`](#sdkusermessage) 相同的 50 連結和 64 KiB 限制。Claude Code 在結果沒有連結時省略 `resource_links`，以及在不是 MCP 工具呼叫的任務通知上。`resource_links` 需要 Agent SDK v0.3.257 或更高版本。

5215

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

5217

5218要檢測任務通知轉數，請檢查 [`SDKUserMessage`](#sdkusermessage) 或 [`SDKResultMessage`](#sdkresultmessage) 上的 `origin.kind === "task-notification"`，而不是匹配通知文本。如果您需要知道引發它的內容，請從同一欄位讀取 `subkind`。在 v2.1.205 之前，Claude Code 在會話閒置時到達的通知上留下通知。

5219

3548<h3 id="sdktoolusesummarymessage">5220<h3 id="sdktoolusesummarymessage">

3549 `SDKToolUseSummaryMessage`5221 `SDKToolUseSummaryMessage`

3550</h3>5222</h3>

3567 5239

3568Hook 開始執行時發出。5240Hook 開始執行時發出。

3569 5241

3570Claude Code 將此消息、[`SDKHookProgressMessage`](#sdkhookprogressmessage) 和 [`SDKHookResponseMessage`](#sdkhookresponsemessage) 立即傳遞到消息流，包括在會話啟動期間 `SessionStart` 或 `Setup` hook 仍在運行時。Claude Code v2.1.169 至 v2.1.203 在 `SessionStart` 或 `Setup` hook 完成後以一個批次傳遞這些消息；v2.1.204 恢復了實時傳遞。5242Claude Code 將此消息、[`SDKHookProgressMessage`](#sdkhookprogressmessage) 和 [`SDKHookResponseMessage`](#sdkhookresponsemessage) 立即傳遞到消息流，包括在會話啟動期間 `SessionStart` 或 `Setup` hook 仍在運行時。Claude Code v2.1.169 至 v2.1.203 在 `SessionStart` 或 `Setup` hook 完成後以一個批次傳遞這些消息；v2.1.204 復原了實時傳遞。

3571 5243

3572```typescript theme={null}5244```typescript theme={null}

3573type SDKHookStartedMessage = {5245type SDKHookStartedMessage = {

3639 parent_tool_use_id: string | null;5311 parent_tool_use_id: string | null;

3640 elapsed_time_seconds: number;5312 elapsed_time_seconds: number;

3641 task_id?: string;5313 task_id?: string;

5314 heartbeat?: boolean;

5315 subagent_type?: string;

5316 subagent_retry?: {

5317 agent_id: string;

5318 attempt: number;

5319 max_retries: number;

5320 retry_delay_ms: number;

5321 error_status: number | null;

5322 error_category: string;

5323 };

3642 uuid: UUID;5324 uuid: UUID;

3643 session_id: string;5325 session_id: string;

3644};5326};

3645```5327```

3646 5328

5329當工具呼叫在主對話中運行時，Claude Code 每 30 秒發出一個 `tool_progress` 消息，帶有 `heartbeat: true`。每個心跳攜帶工具名稱和經過的秒數，因此您可以區分長時間運行的呼叫與停滯的會話。Claude Code 不為子代理內的工具呼叫發出心跳。`heartbeat` 欄位需要 Agent SDK v0.3.214 或更高版本。在 v2.1.257 之前，Claude Code 也不為前景 Agent 工具呼叫發出心跳。

5330

5331在 Agent 工具的 `tool_progress` 消息上（除了心跳外），`subagent_type` 命名運行中的子代理類型，例如 `general-purpose`。`subagent_retry` 在該子代理等待 API 錯誤退避時出現，例如速率限制或過載，每個重試嘗試一個消息。兩個欄位都需要 Agent SDK v0.3.214 或更高版本。

5332

5333要從 `subagent_retry` 呈現重試指示器：

5334

5335* 按 `parent_tool_use_id` 追蹤指示器，它對每個子代理是唯一的。`tool_use_id` 由一個助手轉數的平行子代理共享，因此按它追蹤會讓一個子代理的更新清除另一個的指示器。

5336* 當同一 `parent_tool_use_id` 的稍後 `tool_progress` 到達時清除指示器，既不帶 `subagent_retry` 也不帶 `heartbeat: true`，或當工具的結果消息到達時。帶 `heartbeat: true` 的幀僅報告活躍性，因此當一個到達時保持指示器。`attempt` 可能在持續重試下超過 `max_retries`，因此不要從計數器派生清除。

5337* 將 `error_category` 視為選擇您自己的消息文本的令牌，而不是顯示文本。值為 `rate_limit`、`overloaded`、`authentication_failed`、`server_error`、`cloud_credential_error` 和 `unknown`。處理您不認識的值的方式與處理 `unknown` 的方式相同，因為稍後的版本可以添加值。

5338

3647<h3 id="sdkauthstatusmessage">5339<h3 id="sdkauthstatusmessage">

3648 `SDKAuthStatusMessage`5340 `SDKAuthStatusMessage`

3649</h3>5341</h3>

3665 `SDKTaskStartedMessage`5357 `SDKTaskStartedMessage`

3666</h3>5358</h3>

3667 5359

3668後台任務開始時發出。`task_type` 字段是 `"local_bash"` 用於後台 Bash 命令和 [Monitor](#monitor) 監視，`"local_agent"` 用於子代理，或 `"remote_agent"`。5360任務開始時發出。`task_type` 欄位是 `"local_bash"` 用於 Bash 命令和 [Monitor](#monitor) 監視，`"local_agent"` 用於子代理，或 `"remote_agent"`。

3669 5361

3670```typescript theme={null}5362```typescript theme={null}

3671type SDKTaskStartedMessage = {5363type SDKTaskStartedMessage = {

3675 tool_use_id?: string;5367 tool_use_id?: string;

3676 description: string;5368 description: string;

3677 task_type?: string;5369 task_type?: string;

5370 is_backgrounded?: boolean;

5371 spawn_depth?: number;

5372 ambient?: boolean;

3678 uuid: UUID;5373 uuid: UUID;

3679 session_id: string;5374 session_id: string;

3680};5375};

3681```5376```

3682 5377

5378`ambient` 對於不是會話工作一部分的任務為 `true`，例如 Claude Code 為其自身操作運行的任務。實時更新監視器也是環境的，包括使用者要求的監視器。從活動指示器中排除環境任務。該欄位需要 Agent SDK v0.3.247 或更高版本。

5379

5380`ambient` 也出現在 [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) 和 [`SDKBackgroundTasksChangedMessage`](#sdkbackgroundtaskschangedmessage) 項目上。

5381

5382`is_backgrounded` 和 `spawn_depth` 描述 Claude Code 如何啟動任務。兩個欄位都需要 Agent SDK v0.3.238 或更高版本。

5383

5384* `is_backgrounded`：Claude Code 在 `"local_agent"` 和 `"local_bash"` 任務上設定它。`true` 表示任務在背景中運行。`false` 表示任務在前景中運行，啟動它的工具呼叫保持阻止，直到任務完成或移至背景。

5385* `spawn_depth`：Claude Code 僅在 `"local_agent"` 任務上設定它。主線程生成的子代理的深度為 `1`。深度 `1` 子代理生成的子代理的深度為 `2`，以此類推。

5386

5387[已復原的子代理](/docs/zh-TW/agent-sdk/subagents#resume-subagents) 始終報告 `is_backgrounded: true`，因為 Claude Code 在背景中運行每個已復原的子代理。當前景任務稍後移至背景時，Claude Code 在 [`task_updated`](#sdktaskupdatedmessage) 消息中報告新的 `is_backgrounded` 值，而不是發送第二個 `task_started`。

5388

3683<h3 id="sdktaskprogressmessage">5389<h3 id="sdktaskprogressmessage">

3684 `SDKTaskProgressMessage`5390 `SDKTaskProgressMessage`

3685</h3>5391</h3>

3686 5392

3687子代理或後台任務運行時定期發出。`summary` 字段僅在啟用 [`agentProgressSummaries`](#options) 時填充。5393子代理或背景任務運行時定期發出。`summary` 欄位僅在啟用 [`agentProgressSummaries`](#options) 時填充。

3688 5394

3689```typescript theme={null}5395```typescript theme={null}

3690type SDKTaskProgressMessage = {5396type SDKTaskProgressMessage = {

3710 `SDKTaskUpdatedMessage`5416 `SDKTaskUpdatedMessage`

3711</h3>5417</h3>

3712 5418

3713後台任務的狀態發生變化時發出，例如當它從 `running` 轉換為 `completed` 時。將 `patch` 合併到按 `task_id` 鍵入的本地任務映射中。`end_time` 字段是 Unix 紀元時間戳（以毫秒為單位），可與 `Date.now()` 比較。5419背景任務的狀態發生變化時發出，例如當它從 `running` 轉換為 `completed` 時。將 `patch` 合併到按 `task_id` 鍵入的本地任務映射中。`end_time` 欄位是 Unix 紀元時間戳（以毫秒為單位），可與 `Date.now()` 比較。

3714 5420

3715```typescript theme={null}5421```typescript theme={null}

3716type SDKTaskUpdatedMessage = {5422type SDKTaskUpdatedMessage = {

3734 `SDKBackgroundTasksChangedMessage`5440 `SDKBackgroundTasksChangedMessage`

3735</h3>5441</h3>

3736 5442

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

5444

5445`tasks` 陣列是完整的實時集合。用每個有效負載替換任何緩存的集合，而不是配對 `task_started` 和 `task_notification` 事件，以便下一個成員資格變化更正您可能錯過的任何事件。

3738 5446

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

3740 5448

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

3742 5450

5451當您向運行中的會話發送重複的 `initialize` 控制請求時，例如在傳輸間隙後使用 [`reinitialize()`](#query-object)，Claude Code 在響應後跟隨當前實時集合的快照，即使它是空的。因此，重新連接的主機可以了解正在運行的內容，而無需等待下一個成員資格變化。在 Agent SDK v0.3.239 之前，Claude Code 在重複 `initialize` 後沒有發送快照。

5452

3743需要 Claude Code v2.1.203 或更高版本。5453需要 Claude Code v2.1.203 或更高版本。

3744 5454

3745```typescript theme={null}5455```typescript theme={null}

3750 task_id: string;5460 task_id: string;

3751 task_type: string;5461 task_type: string;

3752 description: string;5462 description: string;

5463 ambient?: boolean;

3753 }[];5464 }[];

3754 uuid: UUID;5465 uuid: UUID;

3755 session_id: string;5466 session_id: string;

3760 `SDKThinkingTokensMessage`5471 `SDKThinkingTokensMessage`

3761</h3>5472</h3>

3762 5473

3763在 Claude 生成思考塊（包括編輯過的思考塊）時發出，帶有迄今為止生成的思考令牌的運行估計。`estimated_tokens` 是當前思考塊的運行總計，`estimated_tokens_delta` 是此幀攜帶的增量。將其用於進度顯示。頂級代理循環的最終計數是結果消息的 `usage.output_tokens`，它[不包括子代理令牌](/docs/zh-TW/agent-sdk/cost-tracking#get-the-total-cost-of-a-query)；使用 [`modelUsage`](#modelusage) 進行整樹會計。5474在 Claude 生成思考塊時發出，包括編輯過的思考塊。`estimated_tokens` 是目前在當前塊中生成的思考令牌的運行估計，`estimated_tokens_delta` 是此幀攜帶的增量。將這些估計用於進度顯示。

5475

5476當模型或提供者報告分解時，頂級代理循環的最終計數是結果消息的 [`usage.output_tokens_details.thinking_tokens`](#usage)，它[不包括子代理令牌](/docs/zh-TW/agent-sdk/cost-tracking#get-the-total-cost-of-a-query)。

3764 5477

3765需要 Claude Code v2.1.153 或更高版本。5478需要 Claude Code v2.1.153 或更高版本。

3766 5479

3770 subtype: "thinking_tokens";5483 subtype: "thinking_tokens";

3771 estimated_tokens: number;5484 estimated_tokens: number;

3772 estimated_tokens_delta: number;5485 estimated_tokens_delta: number;

5486 user_message_uuid?: string;

3773 uuid: UUID;5487 uuid: UUID;

3774 session_id: string;5488 session_id: string;

3775};5489};

3779 `SDKFilesPersistedEvent`5493 `SDKFilesPersistedEvent`

3780</h3>5494</h3>

3781 5495

3782文件檢查點持久化到磁盤時發出。5496檔案檢查點持久化到磁碟時發出。

3783 5497

3784```typescript theme={null}5498```typescript theme={null}

3785type SDKFilesPersistedEvent = {5499type SDKFilesPersistedEvent = {

3815};5529};

3816```5530```

3817 5531

3818當 `errorCode` 為 `"credits_required"` 時，拒絕來自 claude.ai 訂閱，其包含的使用量已耗盡，會話無法繼續，直到用戶購買使用額度。`canUserPurchaseCredits` 指示經過身份驗證的用戶是否可以為帳戶購買額度，`hasChargeableSavedPaymentMethod` 指示是否有保存的付款方式。這三個字段在非信用額度必需拒絕的速率限制事件上不存在。需要 Claude Code v2.1.181 或更高版本。5532當 `errorCode` 為 `"credits_required"` 時，拒絕來自 claude.ai 訂閱，其包含的使用量已耗盡，會話無法繼續，直到使用者購買使用額度。`canUserPurchaseCredits` 指示經過身份驗證的使用者是否可以為帳戶購買額度，`hasChargeableSavedPaymentMethod` 指示是否有保存的付款方式。這三個欄位在非信用額度必需拒絕的速率限制事件上不存在。需要 Claude Code v2.1.181 或更高版本。

3819 5533

3820<h3 id="sdklocalcommandoutputmessage">5534<h3 id="sdklocalcommandoutputmessage">

3821 `SDKLocalCommandOutputMessage`5535 `SDKLocalCommandOutputMessage`

3822</h3>5536</h3>

3823 5537

3824本地 slash command 的輸出（例如，`/voice` 或 `/usage`）。在記錄中顯示為助手風格的文本。5538本地命令（例如 `/voice` 或 `/usage`）的輸出。在記錄中顯示為助手風格的文本。

3825 5539

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

3827type SDKLocalCommandOutputMessage = {5541type SDKLocalCommandOutputMessage = {

3837 `SDKCommandsChangedMessage`5551 `SDKCommandsChangedMessage`

3838</h3>5552</h3>

3839 5553

3840可用命令集在會話中期發生變化時發出，例如當代理進入子目錄時發現技能。`commands` 陣列是完整的更新列表，因此用此有效負載替換任何緩存的命令列表。再次調用 `supportedCommands()` 不等同：該方法返回在初始化時捕獲的快照，不反映會話中期的變化。5554可用命令集在會話中期發生變化時發出，例如當代理進入子目錄時發現 skills。`commands` 陣列是完整的更新清單，因此用此有效負載替換任何緩存的命令清單。在此消息後呼叫 [`supportedCommands()`](#query-object) 返回相同的更新清單，因為該方法追蹤最新推送；這需要 Agent SDK v0.3.216 或更高版本。在較早的 SDK 版本中，`supportedCommands()` 返回在初始化時捕獲的快照，永遠不反映會話中期的變化。

3841 5555

3842```typescript theme={null}5556```typescript theme={null}

3843type SDKCommandsChangedMessage = {5557type SDKCommandsChangedMessage = {

3853 `SDKPromptSuggestionMessage`5567 `SDKPromptSuggestionMessage`

3854</h3>5568</h3>

3855 5569

3856啟用 `promptSuggestions` 時在每個轉數後發出。包含預測的下一個用戶提示。5570在啟用 [`promptSuggestions`](#options) 時轉數後發出，Claude Code 為該轉數生成了建議。包含預測的下一個使用者提示。對於未獲得任何建議的轉數，見 [當 Claude Code 跳過建議](/docs/zh-TW/interactive-mode#when-claude-code-skips-suggestions)。

3857 5571

3858```typescript theme={null}5572```typescript theme={null}

3859type SDKPromptSuggestionMessage = {5573type SDKPromptSuggestionMessage = {

3868 `SDKConversationResetMessage`5582 `SDKConversationResetMessage`

3869</h3>5583</h3>

3870 5584

3871會話的對話被替換而不結束會話時發出，例如在 `/clear` 之後、計劃模式退出時，或當新對話啟動時。在 `new_conversation_id` 下掛載空記錄，並丟棄任何緩存的會話標題。5585會話的對話被替換而不結束會話時發出。在 `query()` 呼叫中，僅 `/clear` 及其別名產生此消息。在 `new_conversation_id` 下掛載空記錄，並丟棄任何緩存的會話標題。

3872 5586

3873```typescript theme={null}5587```typescript theme={null}

3874type SDKConversationResetMessage = {5588type SDKConversationResetMessage = {

3879};5593};

3880```5594```

3881 5595

3882SDK 的已發佈類型在 Claude Code v2.1.203 及更高版本中聲明 `SDKConversationResetMessage`。在 v2.1.203 之前，`SDKMessage` 引用該類型而不聲明它，因此當 `skipLibCheck` 被禁用時，在 `type === "conversation_reset"` 上縮小範圍失敗類型檢查。5596SDK 的已發佈類型在 Claude Code v2.1.203 及更高版本中聲明 `SDKConversationResetMessage`。在 v2.1.203 之前，`SDKMessage` 參考該類型而不聲明它，因此當 `skipLibCheck` 被禁用時，在 `type === "conversation_reset"` 上縮小範圍失敗類型檢查。

3883 5597

3884<h3 id="aborterror">5598<h3 id="aborterror">

3885 `AbortError`5599 `AbortError`

3886</h3>5600</h3>

3887 5601

3888中止操作的自定義錯誤類。5602中止操作的自訂錯誤類。

3889 5603

3890```typescript theme={null}5604```typescript theme={null}

3891class AbortError extends Error {}5605class AbortError extends Error {}

3892```5606```

3893 5607

5608`AbortError` 是 SDK 的類型化 API 中唯一的錯誤類。其他失敗，例如 Claude Code 進程退出或無法啟動，使用沒有 SDK 類可匹配的錯誤拒絕消息迭代。[疑難排解](/docs/zh-TW/agent-sdk/troubleshooting) 按消息鍵入這些錯誤，每個都有原因和修復。

5609

3894<h2 id="sandbox-configuration">5610<h2 id="sandbox-configuration">

3895 沙箱配置5611 Sandbox 設定

3896</h2>5612</h2>

3897 5613

3898<h3 id="sandboxsettings">5614<h3 id="sandboxsettings">

3899 `SandboxSettings`5615 `SandboxSettings`

3900</h3>5616</h3>

3901 5617

3902沙箱行為的配置。使用此選項以編程方式啟用命令沙箱和配置網絡限制。5618Sandbox 行為的設定。使用此設定以程式設計方式啟用命令 sandboxing 並設定網路限制。

3903 5619

3904```typescript theme={null}5620```typescript theme={null}

3905type SandboxSettings = {5621type SandboxSettings = {

3916};5632};

3917```5633```

3918 5634

3919| 屬性 | 類型 | 預設值 | 描述 |5635| 屬性 | 類型 | 預設值 | 說明 |

3920| :-------------------------- | :---------------------------------------------------- | :---------- | :------------------------------------------------------------------------------------------------------------------------------ |5636| :-------------------------- | :---------------------------------------------------- | :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |

3928| `ignoreViolations` | `Record<string, string[]>` | `undefined` | 違規類別到要忽略的模式的映射（例如，`{ file: ['/tmp/*'], network: ['localhost'] }`） |5644| `ignoreViolations` | `Record<string, string[]>` | `undefined` | 命令子字串或 `*`（適用於每個命令）對應到要忽略的違規文字子字串的對應，例如 `{ "*": ['/etc/hosts'] }`；請參閱 [`sandbox.ignoreViolations`](/docs/zh-TW/settings-reference#sandbox-ignoreviolations) |

3930| `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | 沙箱環境中的自訂 ripgrep 二進制配置 |5646| `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | Sandbox 環境的自訂 ripgrep 二進位設定 |

3931 5647

3932<Note>5648<Note>

3933 沙箱取決於平台支援，在 Linux 上，還需要 `bubblewrap` 和 `socat` 等工具。當 `enabled` 為 `true` 且沙箱無法啟動時，`query()` 會報告一條 `result` 訊息，其中 `subtype: "error_during_execution"`，並在 `errors` 中包含原因。對於單一訊息 `query()` 呼叫，SDK 會在產生該錯誤結果後拋出異常，因此請將迴圈包裝在 try 區塊中以繼續執行。請參閱[處理結果](/docs/zh-TW/agent-sdk/agent-loop#handle-the-result)以了解錯誤合約。5649 Sandbox 取決於平台支援，在 Linux 上，需要 `bubblewrap` 和 `socat` 等工具。當 `enabled` 為 `true` 且 sandbox 無法啟動時，`query()` 會報告一個 `result` 訊息，其中 `subtype: "error_during_execution"` 且原因在 `errors` 中。對於單一訊息 `query()` 呼叫，SDK 會在產生該錯誤結果後拋出，因此請將迴圈包裝在 try 區塊中以繼續執行。請參閱[處理結果](/docs/zh-TW/agent-sdk/agent-loop#handle-the-result)以了解錯誤合約。

3934 5650

3935 要改為運行無沙箱，請設置 `failIfUnavailable: false`。5651 若要改為以未 sandboxed 的方式執行，請設定 `failIfUnavailable: false`。

3936</Note>5652</Note>

3937 5653

3938<h4 id="example-usage">5654<h4 id="example-usage">

3939 範例用法5655 使用範例

3940</h4>5656</h4>

3941 5657

3942```typescript theme={null}5658```typescript theme={null}

3958 if ("result" in message) console.log(message.result);5674 if ("result" in message) console.log(message.result);

3959 }5675 }

3960} catch (error) {5676} catch (error) {

3961 // 單一 query() 呼叫會在產生錯誤結果後拋出異常，5677 // A single-shot query() throws after yielding an error result,

3962 // 例如當沙箱無法啟動時（failIfUnavailable 預設為 true）。5678 // such as when the sandbox can't start (failIfUnavailable defaults to true).

3963 console.log(`Session ended with an error: ${error}`);5679 console.log(`Session ended with an error: ${error}`);

3964}5680}

3965```5681```

3966 5682

3967<Warning>5683<Warning>

3968 **Unix socket 安全性：** `allowUnixSockets` 選項可以授予對強大系統服務的訪問權限。例如，允許 `/var/run/docker.sock` 實際上通過 Docker API 授予對主機系統的完全訪問權限，繞過沙箱隔離。僅允許絕對必要的 Unix sockets 並了解每個的安全含義。5684 **Unix socket 安全性：** `allowUnixSockets` 選項可以授予存取權限給可以到達 sandbox 外的系統服務。例如，允許 `/var/run/docker.sock` 實際上會透過 Docker API 授予完整的主機系統存取權限，繞過 sandbox 隔離。只允許嚴格必要的 Unix socket，並了解每個 socket 的安全含義。

3969</Warning>5685</Warning>

3970 5686

3971<h3 id="sandboxnetworkconfig">5687<h3 id="sandboxnetworkconfig">

3972 `SandboxNetworkConfig`5688 `SandboxNetworkConfig`

3973</h3>5689</h3>

3974 5690

3975沙箱模式的網絡特定配置。這些設置適用於當父級 [`SandboxSettings`](#sandboxsettings) 中的 `enabled` 為 `true` 時的沙箱化 Bash 命令。它們不限制 WebFetch 工具，該工具改用[權限規則](/docs/zh-TW/permissions#webfetch)。5691Sandbox 模式的網路特定設定。當父 [`SandboxSettings`](#sandboxsettings) 中的 `enabled` 為 `true` 時，這些設定適用於 sandboxed Bash 命令。它們不會限制 WebFetch 工具，該工具改為使用[權限規則](/docs/zh-TW/permissions#webfetch)。

3976 5692

3977```typescript theme={null}5693```typescript theme={null}

3978type SandboxNetworkConfig = {5694type SandboxNetworkConfig = {

3979 allowedDomains?: string[];5695 allowedDomains?: string[];

3980 deniedDomains?: string[];5696 deniedDomains?: string[];

5697 strictAllowlist?: boolean;

3981 allowManagedDomainsOnly?: boolean;5698 allowManagedDomainsOnly?: boolean;

3982 allowLocalBinding?: boolean;5699 allowLocalBinding?: boolean;

3983 allowUnixSockets?: string[];5700 allowUnixSockets?: string[];

3987};5704};

3988```5705```

3989 5706

3990| 屬性 | 類型 | 預設值 | 描述 |5707| 屬性 | 類型 | 預設值 | 說明 |

3991| :------------------------ | :--------- | :---------- | :----------------------------------------------------------------------------------------------------------------------- |5708| :------------------------ | :--------- | :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

4000 5718

4001<Note>5719<Note>

4002 內置沙箱代理根據請求的主機名強制執行 `allowedDomains`，並且不終止或檢查 TLS 流量，因此[網域前置](https://en.wikipedia.org/wiki/Domain_fronting)等技術可能會繞過它。有關詳細資訊，請參閱[沙箱安全限制](/docs/zh-TW/sandboxing#security-limitations)，以及[安全部署](/docs/zh-TW/agent-sdk/secure-deployment#traffic-forwarding)以配置 TLS 終止代理。5720 內建的 sandbox proxy 根據請求的主機名稱強制執行 `allowedDomains`，不會終止或檢查 TLS 流量，因此[網域前置](/docs/zh-TW/sandboxing#security-limitations)等技術可能會繞過它。請參閱 [Sandbox 安全限制](/docs/zh-TW/sandboxing#security-limitations)以了解詳細資訊，以及[安全部署](/docs/zh-TW/agent-sdk/secure-deployment#traffic-forwarding)以設定 TLS 終止 proxy。

4003</Note>5721</Note>

4004 5722

4005<h3 id="sandboxfilesystemconfig">5723<h3 id="sandboxfilesystemconfig">

4006 `SandboxFilesystemConfig`5724 `SandboxFilesystemConfig`

4007</h3>5725</h3>

4008 5726

4009沙箱模式的檔案系統特定配置。5727Sandbox 模式的檔案系統特定設定。

4010 5728

4011```typescript theme={null}5729```typescript theme={null}

4012type SandboxFilesystemConfig = {5730type SandboxFilesystemConfig = {

4016};5734};

4017```5735```

4018 5736

4019| 屬性 | 類型 | 預設值 | 描述 |5737| 屬性 | 類型 | 預設值 | 說明 |

4020| :----------- | :--------- | :--- | :------------ |5738| :----------- | :--------- | :--- | :------------ |

4024 5742

4025<h3 id="permissions-fallback-for-unsandboxed-commands">5743<h3 id="permissions-fallback-for-unsandboxed-commands">

4026 無沙箱命令的權限回退5744 未 Sandboxed 命令的權限回退

4027</h3>5745</h3>

4028 5746

4029啟用 `allowUnsandboxedCommands` 時，模型可以通過在工具輸入中設置 `dangerouslyDisableSandbox: true` 來請求在沙箱外運行命令。這些請求回退到現有的權限系統，意味著您的 `canUseTool` 處理程序被調用，允許您實現自訂授權邏輯。在下面的範例中，`isCommandAuthorized` 代表您定義的授權檢查。5747當 `allowUnsandboxedCommands` 啟用時，模型可以透過在工具輸入中設定 `dangerouslyDisableSandbox: true` 來要求在 sandbox 外執行命令。這些請求會回退到現有的權限系統，這表示您的 `canUseTool` 處理程式會被呼叫，允許您實現自訂授權邏輯。列在 `excludedCommands` 中的命令改為自動繞過 sandbox，無需模型參與；請參閱 [`SandboxSettings`](#sandboxsettings)。

~~4030~~

4031<Note>

~~4032 **`excludedCommands` vs `allowUnsandboxedCommands`：**~~

4033 5748

4034 * `excludedCommands`：始終自動繞過沙箱的命令的靜態列表（例如，`['docker']`）。模型對此無控制。5749在下面的範例中，`isCommandAuthorized` 代表您定義的授權檢查。

4035 * `allowUnsandboxedCommands`：讓模型在執行時通過在工具輸入中設置 `dangerouslyDisableSandbox: true` 來決定是否請求無沙箱執行。

4036</Note>

4037 5750

4038```typescript theme={null}5751```typescript theme={null}

4039import { query } from "@anthropic-ai/claude-agent-sdk";5752import { query } from "@anthropic-ai/claude-agent-sdk";

4043 options: {5756 options: {

4044 sandbox: {5757 sandbox: {

4045 enabled: true,5758 enabled: true,

4046 allowUnsandboxedCommands: true // 模型可以請求無沙箱執行5759 allowUnsandboxedCommands: true // Model can request unsandboxed execution

4047 },5760 },

4048 permissionMode: "default",5761 permissionMode: "default",

4049 canUseTool: async (tool, input) => {5762 canUseTool: async (tool, input) => {

4050 // 檢查模型是否請求繞過沙箱5763 // Check if the model is requesting to bypass the sandbox

4051 if (tool === "Bash" && input.dangerouslyDisableSandbox) {5764 if (tool === "Bash" && input.dangerouslyDisableSandbox) {

4052 // 模型請求在沙箱外運行此命令5765 // The model is requesting to run this command outside the sandbox

4053 console.log(`Unsandboxed command requested: ${input.command}`);5766 console.log(`Unsandboxed command requested: ${input.command}`);

4054 5767

4055 if (isCommandAuthorized(input.command)) {5768 if (isCommandAuthorized(input.command)) {

4068}5781}

4069```5782```

4070 5783

4071此模式使您能夠：

~~4072~~

4073* **審計模型請求：** 記錄模型何時請求無沙箱執行

4074* **實現允許清單：** 僅允許特定命令在沙箱外運行

4075* **新增批准工作流程：** 需要對特權操作進行明確授權

~~4076~~

4077<Warning>5784<Warning>

4078 使用 `dangerouslyDisableSandbox: true` 運行的命令具有完整的系統訪問權限。確保您的 `canUseTool` 處理程序仔細驗證這些請求。5785 使用 `dangerouslyDisableSandbox: true` 執行的命令具有完整的系統存取權限。確保您的 `canUseTool` 處理程式仔細驗證這些請求。

4079 5786

4080 如果 `permissionMode` 設置為 `bypassPermissions` 且 `allowUnsandboxedCommands` 啟用，模型可以自主執行沙箱外的命令，無需任何批准提示（明確的[`ask` 規則](/docs/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated)仍會強制執行一個）。此組合實際上允許模型無聲地逃離沙箱隔離。5787 如果 `permissionMode` 設定為 `bypassPermissions` 且 `allowUnsandboxedCommands` 啟用，模型可以自主執行 sandbox 外的命令，無需核准提示，除了[動作無模式自動核准的動作](/docs/zh-TW/permission-modes#actions-no-mode-auto-approves)。此組合實際上允許模型以無聲方式逃脫 sandbox 隔離。

4081</Warning>5788</Warning>

4082 5789

4083<h2 id="see-also">5790<h2 id="see-also">

4084 另見5791 另請參閱

4085</h2>5792</h2>

4086 5793

4087* [SDK 概述](/docs/zh-TW/agent-sdk/overview) - 常規 SDK 概念5794* [SDK 概觀](/docs/zh-TW/agent-sdk/overview) - 一般 SDK 概念

4088* [Python SDK 參考](/docs/zh-TW/agent-sdk/python) - Python SDK 文檔5795* [Python SDK 參考](/docs/zh-TW/agent-sdk/python) - Python SDK 文件

4089* [CLI 參考](/docs/zh-TW/cli-reference) - 命令行介面5796* [CLI 參考](/docs/zh-TW/cli-reference) - 命令列介面

4090* [常見工作流](/docs/zh-TW/common-workflows) - 分步指南5797* [常見工作流程](/docs/zh-TW/common-workflows) - 逐步指南

agent-teams.md +5 −5

Details

252 Claude 如何啟動 agent teams252 Claude 如何啟動 agent teams

253</h3>253</h3>

254 254

255若要啟動一個團隊，請向 Claude 要求隊友。當 Claude 在啟用 agent teams 時呼叫 [Agent tool](/docs/zh-TW/tools-reference) 並帶有 [`name`](/docs/zh-TW/sub-agents#subagent-names) 時，Claude Code 不會要求您確認，Claude 就會啟動一個隊友。Claude 也會自行命名普通 subagents，以便稍後可以向它們傳送訊息，而當啟用 agent teams 時，命名的 subagent 會作為隊友啟動，因此即使您沒有要求，團隊也可能形成。255若要啟動一個團隊，請向 Claude 要求隊友。當 Claude 在啟用 agent teams 時呼叫 [Agent tool](/docs/zh-TW/tools-reference) 並帶有 [`name`](/docs/zh-TW/sub-agents#subagent-names) 時，Claude 會啟動一個隊友，除非該呼叫是[分支](/docs/zh-TW/sub-agents#fork-the-current-conversation)或在呼叫本身上傳遞 `isolation`。Claude Code 不會要求您確認啟動。

256 256

257如果您想要 subagents，請[關閉 agent teams](#claude-spawns-teammates-instead-of-subagents)。257Claude 也會自行命名普通 subagents，以便稍後可以向它們傳送訊息。這些呼叫遵循相同的規則，因此即使您沒有要求，團隊也可能形成。如果您想要 subagents，請[關閉 agent teams](#claude-spawns-teammates-instead-of-subagents)。

258 258

259<h3 id="architecture">259<h3 id="architecture">

260 架構260 架構

294 為隊友使用 subagent 定義294 為隊友使用 subagent 定義

295</h3>295</h3>

296 296

297生成隊友時，您可以參考來自任何 [subagent 範圍](/docs/zh-TW/sub-agents#choose-the-subagent-scope)的 [subagent](/docs/zh-TW/sub-agents) 類型：專案、使用者、plugin 或 CLI 定義。這讓您定義一個角色一次，例如安全審查者或測試執行者，並將其同時重複使用為委派的 subagent 和 agent team 隊友。297在任一顯示模式中生成隊友時，您可以參考來自專案、使用者或受管 [subagent 範圍](/docs/zh-TW/sub-agents#choose-the-subagent-scope)的 [subagent](/docs/zh-TW/sub-agents) 類型。這讓您定義一個角色一次，例如安全審查者或測試執行者，並將其同時重複使用為委派的 subagent 和 agent team 隊友。

298 298

299若要使用 subagent 定義，在要求 Claude 生成隊友時按名稱提及它：299若要使用 subagent 定義，在要求 Claude 生成隊友時按名稱提及它：

300 300

314 權限314 權限

315</h3>315</h3>

316 316

317隊友開始時具有主管的權限設定。如果主管使用 `--dangerously-skip-permissions` 運行，所有隊友也會這樣做。生成後，您可以更改個別隊友模式，但在生成時無法設定每個隊友的模式。317隊友開始時具有主管的權限模式，除了 [`dontAsk` 模式](/docs/zh-TW/permission-modes#allow-only-pre-approved-tools-with-dontask-mode)，他們不會繼承。如果主管使用 `--dangerously-skip-permissions` 運行，所有隊友也會這樣做。生成後，您可以更改個別隊友的權限模式，但在生成時無法設定每個隊友的權限模式。

318 318

319隊友權限提示會出現在主管工作階段中，因此請在那裡自己批准它們。[Plan approval](#have-teammates-plan-before-implementing) 是設計的例外：主管工作階段會授予隊友 plan approvals，無需向您發出單獨的提示。319隊友權限提示會出現在主管工作階段中，因此請在那裡自己批准它們。[Plan approval](#have-teammates-plan-before-implementing) 是設計的例外：主管工作階段會授予隊友 plan approvals，無需向您發出單獨的提示。

320 320

549* **沒有嵌套團隊**：隊友無法生成自己的隊友。只有主管可以管理團隊。549* **沒有嵌套團隊**：隊友無法生成自己的隊友。只有主管可以管理團隊。

550* **沒有來自 in-process 隊友的背景子代理**：in-process 隊友自己的子代理在前景中執行，因為隊友的背景工作無法超越主管的程序。Claude Code 在隊友生成定義設定 `background: true` 的子代理時會傳回錯誤。隊友的 `run_in_background: true` 請求也會失敗，可能傳回錯誤或在前景中無聲執行，如 [Claude Code 如何選擇前景或背景](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background) 中所述。從主要對話啟動的子代理遵循[背景預設](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)。550* **沒有來自 in-process 隊友的背景子代理**：in-process 隊友自己的子代理在前景中執行，因為隊友的背景工作無法超越主管的程序。Claude Code 在隊友生成定義設定 `background: true` 的子代理時會傳回錯誤。隊友的 `run_in_background: true` 請求也會失敗，可能傳回錯誤或在前景中無聲執行，如 [Claude Code 如何選擇前景或背景](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background) 中所述。從主要對話啟動的子代理遵循[背景預設](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)。

551* **主管是固定的**：主要工作階段在其生命週期內是主管。您無法將隊友提升為主管或轉移領導權。551* **主管是固定的**：主要工作階段在其生命週期內是主管。您無法將隊友提升為主管或轉移領導權。

552* **權限在生成時設定**：所有隊友開始時具有主管的權限模式。您可以在生成後更改個別隊友模式，但在生成時無法設定每個隊友的模式。552* **權限在生成時設定**：隊友開始時具有 [權限](#permissions) 下所述的權限模式。您可以在生成後更改個別隊友的權限模式，但在生成時無法設定每個隊友的權限模式。

553* **分割窗格需要 tmux 或 iTerm2**：預設 in-process 模式在任何終端中工作。VS Code 的整合終端、Windows Terminal 或 Ghostty 不支援分割窗格模式。553* **分割窗格需要 tmux 或 iTerm2**：預設 in-process 模式在任何終端中工作。VS Code 的整合終端、Windows Terminal 或 Ghostty 不支援分割窗格模式。

554 554

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

agent-view.md +452 −172

Details

19若要比較 agent view 與 subagents、agent teams 和 worktrees，請參閱 [平行執行代理](/docs/zh-TW/agents)。19若要比較 agent view 與 subagents、agent teams 和 worktrees，請參閱 [平行執行代理](/docs/zh-TW/agents)。

20 20

21<Note>21<Note>

~~22 Agent view 是研究預覽版本，需要 Claude Code v2.1.139 或更新版本。使用 `claude --version` 檢查您的版本。隨著功能的發展，介面和快捷鍵可能會改變。~~22 Agent view 處於研究預覽版本。隨著功能的發展，介面和快捷鍵可能會改變。

23</Note>23</Note>

24 24

~~25本頁涵蓋：~~

~~27* [快速開始](#quick-start)：給 Claude 一個在背景中執行的任務，檢查它，並在需要時介入~~

~~28* [使用 agent view 監控工作階段](#monitor-sessions-with-agent-view)，包括狀態圖示、查看和回覆、附加、組織和快捷鍵~~

~~29* [分派新代理](#dispatch-new-agents)，從 agent view、從工作階段內部或從 shell~~

~~30* [從 shell 管理工作階段](#manage-sessions-from-the-shell)，使用 `claude agents`、`claude attach` 和相關命令~~

~~31* [背景工作階段如何被託管](#how-background-sessions-are-hosted)，由監督程序~~

33<h2 id="quick-start">25<h2 id="quick-start">

34 快速開始26 快速開始

35</h2>27</h2>

44 claude agents36 claude agents

45 ```37 ```

46 38

47 Agent view 開啟，底部有輸入框，隨著工作階段啟動，表格會填入。隨時按 `Esc` 返回您的 shell。您的工作階段在您離開時繼續執行，下次開啟 agent view 時會重新出現。39 如果您尚未接受該目錄的[工作區信任對話](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)，Claude Code 會在 agent view 開啟前顯示它，與 `claude` 顯示的對話相同。接受以儲存工作區的信任並繼續。如果您拒絕，Claude Code 會退出而不開啟 agent view。

41 Agent view 開啟，底部有輸入框，隨著工作階段啟動，表格會填入。隨時按 `Esc` 返回您的 shell；如果您透過背景化工作階段 `←` 開啟了 agent view，`Esc` 會改為返回該對話。您的工作階段在您離開時繼續執行，下次開啟 agent view 時會重新出現。

48 </Step>42 </Step>

49 43

50 <Step title="分派工作階段">44 <Step title="分派工作階段">

51 輸入描述工作的提示並按 `Enter`。新的背景工作階段在該工作上啟動並顯示為一列，顯示它是否正在工作、等待您或已完成。新工作階段使用 agent view 標題中顯示的模型和在該目錄中執行 `claude` 時會獲得的相同[權限模式](#permission-mode-model-and-effort)。45 輸入描述工作的提示並按 `Enter`。新的背景工作階段在該工作上啟動並顯示為一列，顯示它是否正在工作、等待您或已完成。新工作階段使用 agent view 標題中顯示的模型。[它啟動時所在的權限模式](#permission-mode-model-and-effort)取決於您如何開啟 agent view。

52 46

53 您在此輸入的每個提示都會啟動自己的新工作階段。輸入另一個提示並按 `Enter` 會在第一個工作階段旁邊啟動第二個工作階段，而不是向其發送後續訊息。您可以以這種方式並行執行多個工作階段。47 您在此輸入的每個提示都會啟動自己的新工作階段。輸入另一個提示並按 `Enter` 會在第一個工作階段旁邊啟動第二個工作階段，而不是向其發送後續訊息。您可以以這種方式並行執行多個工作階段。

54 48

60 </Step>54 </Step>

61 55

62 <Step title="附加和分離">56 <Step title="附加和分離">

63 在一列上按 `Enter` 或 `→` 以在需要完整對話時附加。工作階段接管終端，就像完整的互動式 Claude Code 工作階段一樣。在空提示上按 `←` 分離並返回表格。57 在一列上按 `Enter` 或 `→` 以在需要完整對話時附加。工作階段接管終端作為完整的互動式 Claude Code 工作階段。在空提示上按 `←` 分離並返回表格。

64 </Step>58 </Step>

65 59

66 <Step title="帶入現有工作階段">60 <Step title="帶入現有工作階段">

67 這個步驟需要一個執行中的工作階段。如果您遵循了之前的步驟，您在此終端中沒有開啟的工作階段，因此請在另一個終端中開啟一個常規 `claude` 工作階段並先向其發送訊息。要將您已開啟的工作階段移入 agent view，在其中執行 `/bg`，或在空提示上按 `←` 以在一個步驟中背景化工作階段並開啟 agent view。工作階段繼續執行並顯示為一列，與您分派的工作階段並排。61 這個步驟需要一個執行中的工作階段。如果您遵循了之前的步驟，您在此終端中沒有開啟的工作階段，因此請在另一個終端中開啟一個常規 `claude` 工作階段並先向其發送訊息。

63 要將您已開啟的工作階段移入 agent view，在其中執行 `/bg`，或在空提示上按 `←` 以在一個步驟中背景化工作階段並開啟 agent view。在沒有訊息的全新工作階段中，`/bg` 會要求您先發送訊息，而 `←` 可以立即運作。工作階段繼續執行並顯示為一列，與您分派的工作階段並排。

68 </Step>64 </Step>

69</Steps>65</Steps>

70 66

71您可以使用 `claude agents` 作為主要進入點而不是 `claude`：從 agent view 分派每個工作，在需要完整對話時附加，然後按 `←` 返回表格。67您可以使用 `claude agents` 作為主要進入點而不是 `claude`：從 agent view 分派每個工作，在需要完整對話時附加，然後按 `←` 返回表格。

72 68

73在常規 `claude` 工作階段內，提示頁尾的 `←` 提示會計算正在等待您的背景 agent 數量，例如 `← 2 agents`，當沒有任何 agent 需要輸入時會返回 `← for agents`。超過 99 的計數顯示為 `99+`。當終端獲得焦點時，計數大約每十秒刷新一次，當焦點返回時立即刷新。當計數移動時以及當 agent 完成時，它會短暫改變顏色，除非啟用了 [`prefersReducedMotion` 設定](/docs/zh-TW/settings#available-settings)，並且在[螢幕閱讀器模式](/docs/zh-TW/accessibility)中隱藏。在 [Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry](/docs/zh-TW/third-party-integrations) 上，提示保持其純 `← for agents` 形式，不顯示計數。需要 Claude Code v2.1.205 或更新版本。69在常規 `claude` 工作階段內，提示頁尾的 `←` 提示會計算正在等待您的背景 agent 數量，例如 `← 2 agents`，當沒有任何 agent 需要輸入時會返回 `← for agents`。超過 99 的計數顯示為 `99+`。當終端獲得焦點時，計數大約每十秒刷新一次，當焦點返回時立即刷新。當計數移動時以及當 agent 完成時，它會短暫改變顏色，當背景工作階段完成且沒有任何工作階段需要您的輸入時，它會短暫顯示已完成的數量，例如 `← 2 done`。當啟用了 [`prefersReducedMotion` 設定](/docs/zh-TW/settings-reference#prefersreducedmotion)時，兩個閃爍都會關閉，並且在[螢幕閱讀器模式](/docs/zh-TW/accessibility)中隱藏提示。

74 70

75<h2 id="monitor-sessions-with-agent-view">71<h2 id="monitor-sessions-with-agent-view">

76 使用 agent view 監控工作階段72 使用 agent view 監控工作階段

78 74

79執行 `claude agents` 開啟 agent view。它接管整個終端並列出按狀態分組的每個工作階段，固定的工作階段和需要您的工作階段在頂部。每行顯示工作階段的名稱、當前活動和其年齡，從工作階段建立時開始計算；已完成的工作階段的年齡會凍結在執行花費的時間。75執行 `claude agents` 開啟 agent view。它接管整個終端並列出按狀態分組的每個工作階段，固定的工作階段和需要您的工作階段在頂部。每行顯示工作階段的名稱、當前活動和其年齡，從工作階段建立時開始計算；已完成的工作階段的年齡會凍結在執行花費的時間。

80 76

81名稱以該工作階段中由 [`/color`](/docs/zh-TW/commands) 設定的顏色著色。自 v2.1.199 起，當您使用 `←` 或 `/background` [背景化工作階段](#from-inside-a-session)時，顏色會保留。77名稱以該工作階段中由 [`/color`](/docs/zh-TW/commands) 設定的顏色著色。當您使用 `←` 或 `/background` [背景化工作階段](#from-inside-a-session)時，顏色會保留。

82 78

83根據預設，該列表顯示您啟動的每個背景工作階段，跨越所有您的專案。在一個儲存庫中工作的工作階段和在不同 worktree 中工作的另一個工作階段都會出現在這裡，無論您從哪個目錄開啟 agent view。要將檢視範圍限制在一個專案，請傳遞 `--cwd`：79根據預設，該列表顯示您啟動的每個背景工作階段，跨越所有您的專案。在一個儲存庫中工作的工作階段和在不同 worktree 中工作的另一個工作階段都會出現在這裡，無論您從哪個目錄開啟 agent view。要將檢視範圍限制在一個專案，請傳遞 `--cwd`：

84 80

117每行開始的圖示，其顏色和動畫顯示工作階段的狀態：113每行開始的圖示，其顏色和動畫顯示工作階段的狀態：

118 114

119| 狀態 | 圖示顯示為 | 含義 |115| 狀態 | 圖示顯示為 | 含義 |

120| :--- | :---- | :---------------------------------- |116| :--- | :---- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

121| 工作中 | 動畫 | Claude 正在主動執行工具或生成回應 |117| 工作中 | 動畫 | Claude 正在主動執行工具或生成回應 |

122| 需要輸入 | 黃色 | Claude 正在等待您的特定問題或權限決定 |118| 需要輸入 | 黃色 | Claude 正在等待只有您才能提供的內容：問題的答案、權限決定，或只有您才能回答的另一個提示，例如 [沙箱](/docs/zh-TW/sandboxing)提示以允許網路主機或 MCP 伺服器的[輸入請求](/docs/zh-TW/mcp#respond-to-mcp-elicitation-requests)。需要附加終端的命令，例如 `/install-github-app` 或 `/mcp` 設定列表，[也會在此處保持未處理的工作階段](#attach-to-a-session) |

123| 閒置 | 淡化 | 工作階段沒有事情要做，準備好接收您的下一個提示 |119| 閒置 | 淡化 | 工作階段沒有事情要做，準備好接收您的下一個提示 |

124| 已完成 | 綠色 | 任務成功完成 |120| 已完成 | 綠色 | 任務成功完成 |

125| 失敗 | 紅色 | 任務以錯誤結束 |121| 失敗 | 紅色 | 任務以錯誤結束 |

126| 已停止 | 灰色 | 工作階段已使用 `Ctrl+X` 或 `claude stop` 停止 |122| 已停止 | 灰色 | 您使用 `Ctrl+X` 或 `claude stop` 停止了工作階段，[其程序從 Claude Code 外部結束](#the-supervisor-process)，或[背景服務關閉時它結束](#sessions-show-as-failed-after-shutdown) |

127 123

128另外，圖示的形狀顯示底層程序是否正在執行：124另外，圖示的形狀顯示底層程序是否正在執行：

129 125

130| 形狀 | 含義 |126| 形狀 | 含義 |

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

132| `✻` 或動畫 `✽` | 工作階段程序處於活動狀態並立即回覆 |128| `✻` 或動畫 `✽` | 工作階段程序處於活動狀態並立即回覆 |

133| `∙` | 程序已退出。您仍然可以查看、回覆或附加，Claude 從中斷的地方重新啟動 |129| `∙` | 程序已退出。您仍然可以查看該行，當您回覆或附加時，Claude 從中斷的地方重新啟動 |

134| `✢` | 一個 [`/loop`](/docs/zh-TW/scheduled-tasks) 工作階段在迭代之間休眠。該行顯示其執行計數和倒計時 |130| `✢` | 一個 [`/loop`](/docs/zh-TW/scheduled-tasks) 工作階段在迭代之間休眠。該行顯示其執行計數和倒計時 |

135 131

136出現在行右邊緣的 `#N` 標籤是[工作階段開啟的拉取請求](#pull-request-status)，不是狀態圖示的一部分。132出現在行右邊緣的 `#N` 或 `!N` 標籤是[工作階段的拉取請求或合併請求](#pull-request-status)的連結，不是狀態圖示的一部分。

137 133

138終端標籤標題在 agent view 開啟時顯示等待輸入計數：當工作階段需要輸入時為 `2 awaiting input · claude agents`，或當沒有工作階段需要輸入時為 `claude agents`。134終端標籤標題在 agent view 開啟時顯示等待輸入計數：當工作階段需要輸入時為 `2 awaiting input · claude agents`，或當沒有工作階段需要輸入時為 `claude agents`。

139 135

140自 v2.1.198 起，當 agent view 開啟時，Claude Code 也會通過您配置的[終端通知頻道](/docs/zh-TW/terminal-config#get-a-terminal-bell-or-notification)發送通知，當本機背景工作階段開始需要您的輸入、完成或失敗時。在排程上執行的工作階段，例如 [`/loop`](/docs/zh-TW/scheduled-tasks) 工作階段，只在需要您的輸入時通知。通知使用與 Claude Code 其餘部分相同的 [`preferredNotifChannel` 設定](/docs/zh-TW/settings#available-settings)，並使用 `agent_needs_input` 或 `agent_completed` 類型觸發 [`Notification` hook](/docs/zh-TW/hooks#notification)。136要從指令碼或另一個程式讀取工作階段狀態，請使用 [`claude agents --json`](#read-session-state-from-a-script) 而不是 `~/.claude/jobs/` 下的檔案。

137

138當 agent view 開啟時，Claude Code 也會通過您配置的[終端通知頻道](/docs/zh-TW/terminal-config#get-a-terminal-bell-or-notification)發送通知，當本機背景工作階段開始需要您的輸入、完成或失敗時。在排程上執行的工作階段，例如 [`/loop`](/docs/zh-TW/scheduled-tasks) 工作階段，只在需要您的輸入時通知。通知使用與 Claude Code 其餘部分相同的 [`preferredNotifChannel` 設定](/docs/zh-TW/settings-reference#preferrednotifchannel)，並使用 `agent_needs_input` 或 `agent_completed` 類型觸發 [`Notification` hook](/docs/zh-TW/hooks#notification)。

141 139

142背景工作階段不需要任何開啟的終端即可繼續工作。單獨的[監督程序](#the-supervisor-process)執行它們，因此您可以關閉 agent view、關閉 shell 或啟動新的互動工作階段，您分派的工作會繼續進行。140背景工作階段不需要任何開啟的終端即可繼續工作。單獨的[監督程序](#the-supervisor-process)執行它們，因此您可以關閉 agent view、關閉 shell 或啟動新的互動工作階段，您分派的工作會繼續進行。

143 141

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

145 143

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

147 145

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

149 行摘要147 行摘要

151 149

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

153 151

154工作中的行顯示工作階段說它正在做什麼，被阻止的行顯示它正在詢問的問題。在長回合期間，模型也會大約每分鐘重寫一次摘要，每次重寫後等待時間加倍，最多四分鐘，因此繁忙的行不會持續顯示過時的摘要。摘要文字填充該行的剩餘寬度，只在終端的右邊緣截斷；開啟[查看面板](#peek-and-reply)以讀取邊緣裁剪的句子。在 v2.1.206 之前，文字在 64 列處截斷，無論終端寬度如何。152工作中的行顯示工作階段說它正在做什麼，被阻止的行顯示它正在詢問的問題。在長回合期間，模型也會大約每幾分鐘重寫一次摘要，因此繁忙的行不會持續顯示過時的摘要。摘要文字填充該行的剩餘寬度；開啟[查看面板](#peek-and-reply)以讀取終端邊緣裁剪的句子。

155 153

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

157 155

158整個輸出不包含字母或數字的回合，例如在安靜迭代中列印單個符號的 [`/loop`](/docs/zh-TW/scheduled-tasks) 工作階段，保持該行的先前摘要和狀態。在 v2.1.205 之前，該回合被重新分類，可能會將等待您輸入的工作階段翻轉回 `Working`。156回合結束摘要和每次中途重寫都是通過您的正常提供者的一個簡短 Haiku-class 請求，按照與工作階段本身相同的[資料使用條款](/docs/zh-TW/data-usage)計費和處理。15 秒的模型重寫之間的更新重用工作階段自己的輸出，不發送請求。在沒有配置 Haiku-class 模型的第三方提供者或閘道上，請求會使用工作階段的主要模型；設定 [`ANTHROPIC_DEFAULT_HAIKU_MODEL`](/docs/zh-TW/model-config#environment-variables) 以選擇一個。

~~159~~

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

161 157

162<h3 id="pull-request-status">158<h3 id="pull-request-status">

163 拉取請求狀態159 拉取請求狀態

164</h3>160</h3>

165 161

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

163

164* Claude Code 將標籤寫為拉取請求的 `#1234` 和 GitLab 合併請求的 `!1234`。

165* Claude Code 發出連結，即使它無法偵測超連結支援，例如通過 SSH 或 tmux。設定 [`FORCE_HYPERLINK=0`](/docs/zh-TW/env-vars) 以將標籤呈現為純文字。

166* 在您向工作階段發送後續訊息後，Claude Code 保留標籤，同時該行返回即時進度。

167 167

168在現有拉取請求上工作的工作階段以相同方式連結到它。使用 `gh` 編輯、評論、關閉或標記拉取請求為準備好會連結該命令自己的輸出命名的拉取請求，因此其捕獲的輸出不命名拉取請求的 `gh` 命令不會建立連結；`gh pr merge` 是常見情況，因為它只將其結果列印到互動終端。使用 `gh pr checkout` 簽出拉取請求，或推送到具有開啟拉取請求的分支，會改為使用 `gh pr view` 查詢該分支來連結它。在 v2.1.205 之前，只有工作階段建立或簽出的拉取請求被連結，推送只在本機分支名稱匹配時連結一個。168在現有拉取請求上工作的工作階段以相同方式連結到它。Claude Code 根據 Claude 執行的命令以不同方式查詢拉取請求：

169 169

170Claude Code 從完整命令輸出讀取拉取請求，包括當命令輸出超過內聯限制時保存到檔案的部分。在 v2.1.205 之前，在 Bash 呼叫中建立的拉取請求，其輸出超過約 30,000 個字元，未被連結。170* 當 Claude 使用 `gh` 編輯、評論、關閉或標記拉取請求為準備好時，Claude Code 連結該命令自己的輸出命名的拉取請求。其捕獲的輸出不命名拉取請求的 `gh` 命令不會建立連結；`gh pr merge` 是常見情況，因為它只將其結果列印到互動終端。

171* 當 Claude 使用 `gh pr checkout` 簽出拉取請求或推送到分支時，Claude Code 使用 `gh pr view` 查詢該分支並連結其開啟的拉取請求。

172* 當 Claude 推送時拉取請求不需要已存在：Claude Code 在同一目錄中執行最多五個後續 `git`、`gh`、`glab` 或 `curl` 命令後重試分支查詢，因此在推送後建立的拉取請求，包括 Claude 通過 GitHub REST API 建立的拉取請求，在重試找到它時連結。

171 173

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

173 175

180| 紫色 | 已合併 |182| 紫色 | 已合併 |

181| 灰色 | 草稿或已關閉 |183| 灰色 | 草稿或已關閉 |

182 184

183對於大多數任務，此欄是您收集結果的地方：當拉取請求編號變綠時審查並合併拉取請求。185對於以拉取請求結束的任務，檢查此標籤以獲取結果：當拉取請求編號變綠時審查並合併拉取請求。

184 186

185<h3 id="peek-and-reply">187<h3 id="peek-and-reply">

186 查看和回覆188 查看和回覆

196 198

197大多數時候查看面板就足夠了，您不需要開啟完整記錄。199大多數時候查看面板就足夠了，您不需要開啟完整記錄。

198 200

199在 v2.1.207 之前，每次查看都以狀態句子和裸時間戳開啟，被阻止的工作階段的問題出現在它們下方，前綴為相同的時間戳第二次。201在查看面板中輸入回覆並按 `Enter` 將其發送到該工作階段。當工作階段詢問具有預定義選擇的問題時，查看面板將它們顯示為編號列表，您可以按數字鍵選擇一個。權限提示顯示為描述工作階段想要執行的內容的文字，沒有編號選項。輸入回覆以回答它，或附加以使用標準提示回答。對於其他被阻止的工作階段，按 `Tab` 用建議的回覆填充輸入，您可以在發送前編輯。使用 `!` 前綴回覆以發送 Bash 命令。

200 202

201在查看面板中輸入回覆並按 `Enter` 將其發送到該工作階段。當工作階段詢問多選問題時，查看面板顯示選項，您可以按數字鍵選擇一個。對於其他被阻止的工作階段，按 `Tab` 用建議的回覆填充輸入，您可以在發送前編輯。使用 `!` 前綴回覆以發送 Bash 命令。203當 [`PermissionRequest`](/docs/zh-TW/hooks#permissionrequest) 或 [`PreToolUse`](/docs/zh-TW/hooks#pretooluse) hook 返回 Claude Code 無法驗證工作階段詢問的呼叫的輸出時，該行顯示 hook 事件和 `hook output invalid:` 以及驗證錯誤，然後是待處理請求的文字。對於以其他方式失敗的 hook，該行說 hook 失敗。工作階段仍然等待相同的請求。

202 204

203無法傳遞的回覆，因為背景服務無法連接或發送失敗，會被保存並在其程序再次啟動時作為其下一個提示發送到工作階段，錯誤訊息說回覆已保存。以 `!` 前綴的回覆不會被保存，因為保存的文字會作為純提示而不是 Bash 命令到達工作階段。205無法傳遞的回覆，因為背景服務無法連接或發送失敗，會被保存並在其程序再次啟動時作為其下一個提示發送到工作階段，錯誤訊息說回覆已保存。以 `!` 前綴的回覆不會被保存，因為保存的文字會作為純提示而不是 Bash 命令到達工作階段。

204 206

214 216

215附加時，工作階段的行為與任何其他 Claude Code 工作階段相同：[命令](/docs/zh-TW/commands)、快捷鍵和功能都有效，下面列出的例外除外。217附加時，工作階段的行為與任何其他 Claude Code 工作階段相同：[命令](/docs/zh-TW/commands)、快捷鍵和功能都有效，下面列出的例外除外。

216 218

217背景工作階段拒絕 `/install-github-app` 和 [`/mcp`](/docs/zh-TW/mcp) 設定列表，包括其驗證動作，無論您是附加還是從查看面板回覆。訊息會引導您到常規 `claude` 工作階段，而 `/mcp reconnect <server>`、`/mcp enable` 和 `/mcp disable` 仍然有效。219附加時，`/install-github-app` 和 [`/mcp`](/docs/zh-TW/mcp) 設定列表正常工作，因為終端上的人類可以完成它們的對話。當沒有人附加時，這些命令無法開啟它們的對話，因此工作階段在 agent view 中出現在 `Needs input` 下，行如 `open this session to manage MCP servers`，記錄回覆說相同的內容。附加並再次執行命令以繼續；當您附加時，needs-input 行會清除。`/mcp reconnect <server>`、`/mcp enable` 和 `/mcp disable` 無論如何都可以工作。

218 220

219附加的工作階段始終以[全螢幕模式](/docs/zh-TW/fullscreen)呈現，無論您的 `tui` 設定如何，因為背景工作階段沒有終端滾動回溯可附加。使用 `PgUp`、`PgDn` 或滑鼠滾輪滾動，並按 `Ctrl+O` 進入記錄模式。您終端的原生滾動和 tmux 複製模式只顯示當前視口，與執行任何全螢幕應用程式時相同。221附加的工作階段始終以[全螢幕模式](/docs/zh-TW/fullscreen)呈現，無論您的 `tui` 設定如何，因為背景工作階段沒有終端滾動回溯可附加。使用 `PgUp`、`PgDn` 或滑鼠滾輪滾動，並按 `Ctrl+O` 進入記錄模式。您終端的原生滾動和 tmux 複製模式只顯示當前視口，與執行任何全螢幕應用程式時相同。

220 222

221在空提示上按 `←` 或執行 `/exit` 以分離並返回 agent view。自 v2.1.198 起，無論您是從 agent view 開啟工作階段還是從 shell 執行 `claude attach <id>`，這都以相同的方式工作。223在空提示上按 `←` 或執行 `/exit` 以分離並返回 agent view，無論您是從 agent view 開啟工作階段還是從 shell 執行 `claude attach <id>`。

224

225當 [`/btw` overlay](/docs/zh-TW/interactive-mode#side-questions-with-%2Fbtw) 開啟時，`←` 也會分離。需要 Claude Code v2.1.257 或更新版本。仍在回答的側問題在您離開時繼續執行。下次您附加時，overlay 會重新開啟它，或使用其答案。

226

227在 Windows 上，如果您在附加後約半秒內按 `←`，Claude Code 會顯示 `Ambiguous ←, press again to detach`，因為在該視窗中終端可以重新傳遞您附加前的按鍵。再次按 `←` 以分離。

222 228

223`Ctrl+Z` 也會分離但會回到您開始的地方：如果您從 agent view 附加則返回 agent view，或如果您執行 `claude attach` 則返回 shell。當對話框有焦點且不響應 `←` 時使用 `Ctrl+Z`。229`Ctrl+Z` 也會分離但會回到您開始的地方：如果您從 agent view 附加則返回 agent view，或如果您執行 `claude attach` 則返回 shell。當對話框有焦點且不響應 `←` 時使用 `Ctrl+Z`。

224 230

226 232

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

228 234

235<h4 id="switch-sessions-without-leaving-the-terminal">

236 在不離開終端的情況下切換工作階段

237</h4>

238

229在前景中執行的工作階段中，您在終端中啟動的工作階段而不是從 agent view 附加的工作階段，在空提示上按 `←` 會背景化它並開啟 agent view，預先選擇該行，因此您可以在不離開終端的情況下切換工作階段。同一個按鍵會分離附加的工作階段。239在前景中執行的工作階段中，您在終端中啟動的工作階段而不是從 agent view 附加的工作階段，在空提示上按 `←` 會背景化它並開啟 agent view，預先選擇該行，因此您可以在不離開終端的情況下切換工作階段。同一個按鍵會分離附加的工作階段。

230 240

231如果工具在您按 `←` 時執行，Claude Code 會等待最多約十秒鐘讓它完成然後背景化，回應在背景工作階段中繼續。再次按 `←` 以立即背景化，而不是等待。當進行中的工作無法轉移到背景工作階段時，`Background this session?` 對話會首先出現，與 [`/background`](#from-inside-a-session) 相同。241如果您在刪除提示的最後文字或通過提示歷史移動後立即按 `←`，Claude Code 會要求您確認：第一次按顯示 `Press ← again to open agents`，或在附加的工作階段中 `Press ← again to go back to agents`，第二次按會切換。

242

243當 `←` 背景化前景工作階段時，agent view 在列表上方顯示 `Your conversation moved to the background`，該工作階段的行已預先選擇。從那裡：

244

245* 按 `Enter` 重新開啟對話。

246* 按 `Esc` 撤銷切換並返回對話。如果 `Esc` 顯示 `Still starting — try again in a moment`，背景工作階段還沒準備好，所以稍後再按一次 `Esc`。

247* 按 `Ctrl+C` 兩次以退出到 shell。

248

249當 Claude Code 無法重新開啟對話時，它會退出並列印一個 `claude --resume` 命令來恢復它。

232 250

233當 [subagents](/docs/zh-TW/sub-agents) 執行時，十秒限制不適用。Claude Code 會繼續等待，以便它們的工作能夠轉移，並在等待時顯示 `Still backgrounding after the current tool` 通知；再次按 `←` 以立即背景化而不等待，這會從頭開始重新啟動 subagents。在 v2.1.203 之前，等待在十秒後結束，執行中的 subagents 會在沒有警告的情況下從頭開始重新啟動。251[Claude 的任務列表](/docs/zh-TW/interactive-mode#task-list)隨對話移動到背景工作階段，因此當您返回該行時檢查清單是完整的。

234 252

235該行會被建立，即使是從沒有對話歷史的全新工作階段，所以 `→` 會返回到它。在 v2.1.203 之前，當該行是唯一的行時，agent view 會在其下方顯示一個入門提示。253您按 `←` 的行在使用箭頭鍵或滑鼠移動選擇後也保持粗體、未淡化的名稱，因此您可以告訴您來自哪個工作階段。

254

255如果工具在您按 `←` 時執行，Claude Code 會等待最多約十秒鐘讓它完成然後背景化，回應在背景工作階段中繼續。再次按 `←` 以立即背景化，而不是等待。當進行中的工作無法轉移到背景工作階段時，Claude Code 會首先顯示 `Background this session?` 對話，與 [`/background`](#from-inside-a-session) 相同。十秒限制在[前景 subagents](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background) Claude 在對話中啟動的仍在執行時不適用。Claude Code 會繼續等待，以便它們的工作能夠轉移，並在等待時顯示 `Still backgrounding after the current tool` 通知。再次按 `←` 以立即背景化而不等待，這會從頭開始重新啟動這些 subagents。Claude Code 不會等待[動態工作流程](/docs/zh-TW/workflows)執行的 subagents。當工作流程有 subagents 執行時，Claude Code 會改為顯示 `Background this session?` 對話。

256

257Claude Code 在您的提示輸入中有未發送的文字時不會背景化工作階段，因為文字會保留在您終端的輸入框中，不會移動到背景工作階段。如果您在 Claude Code 等待背景化工作階段時輸入到輸入中，它會取消切換，顯示 `Backgrounding cancelled — you have unsent text in the input. Send it or clear it, then press ← again.`

258

259按 `←` 會建立工作階段的行，即使對話還沒有訊息，所以 `→` 仍然會返回到它。

236 260

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

238 262

253 277

254要移除工作階段，按 `Ctrl+X` 停止它，然後在兩秒內再次按 `Ctrl+X` 刪除它。在組標題上按 `Ctrl+X` 會在確認後刪除該組中的每個工作階段。278要移除工作階段，按 `Ctrl+X` 停止它，然後在兩秒內再次按 `Ctrl+X` 刪除它。在組標題上按 `Ctrl+X` 會在確認後刪除該組中的每個工作階段。

255 279

256刪除會從 agent view 中移除工作階段。如果 Claude[為工作階段建立了 worktree](#how-file-edits-are-isolated)，刪除會移除該 worktree，包括其中的任何未提交的更改，因此在刪除前推送或提交您想保留的工作。您自己建立的 worktree 並在其中啟動工作階段的會保留在原地。對話記錄會保留在您的本機上，並且仍然可以通過 `claude --resume` 存取。280第二次按會刪除工作階段，即使停止嘗試失敗，例如因為[背景服務沒有回應](#agent-view-says-the-background-service-did-not-respond)：確認會再保持活動兩秒，刪除會結束工作階段的程序本身。按 `Esc` 以在不刪除的情況下關閉確認。

281

282除了[刪除工作階段會移除什麼](#what-deleting-a-session-removes)中涵蓋的保留情況外，刪除會從列表中移除工作階段，Claude 為其建立的 worktree 會被移除、保留或留在原地，取決於您如何刪除以及 worktree 保留的內容。對話記錄始終保留在您的本機上，可通過 `claude --resume` 存取。

257 283

258刪除永遠不會移除具有未推送到任何地方的提交的 worktree，或另一個執行中的工作階段聲稱或已鎖定的 worktree。Claude Code 會保留 worktree 和工作階段，頁腳會命名保留的路徑和原因。推送提交或關閉另一個工作階段，然後再次刪除。284要在 Claude Code v2.1.212 或更新版本上恢復工作階段，在分派輸入中輸入 `/resume`。選擇器開啟，顯示您開啟 agent view 的儲存庫的過去工作階段，最新的優先，包括您從列表中刪除的工作階段；已有行的工作階段不會列出。`↑`/`↓` 移動選擇，`Enter` 將選定的工作階段恢復為背景工作階段，使其重新加入列表作為行，`Esc` 關閉選擇器。

259 285

260刪除也會從[監督程序](#the-supervisor-process)的工作階段列表中清除工作階段，無論您使用 `Ctrl+X` 刪除還是從 shell 使用 [`claude rm`](#manage-sessions-from-the-shell) 刪除，因此移除在監督程序重新啟動時保存。在 v2.1.206 之前，在監督程序重新啟動或無法連接時移除工作階段會將其留在該列表中，下一個監督程序會重新啟動其程序並再次顯示該行。286選擇器只在裸 `/resume` 時開啟。有目標、範圍或受限的恢復無法由選擇器提供，因此當以下情況時 agent view 會顯示 `attach to a session to run it` 提示：

287

288* `/resume` 命名 id 或搜尋詞

289* 檢視以 `--cwd` 為範圍

290* 檢視以 [`--safe-mode`](/docs/zh-TW/cli-reference#cli-flags) 啟動

291* 檢視以 `--permission-mode` 或 `--settings` 等旗標開啟

261 292

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

263 294

268在分派輸入中輸入以篩選而不是分派：299在分派輸入中輸入以篩選而不是分派：

269 300

270| 篩選 | 顯示 |301| 篩選 | 顯示 |

271| :------------------- | :----------------------------------------------------- |302| :----------------------- | :----------------------------------------------------- |

275| 任何其他 URL | 其第一個提示包含該 URL 的工作階段 |306| 任何其他 URL | 其第一個提示包含該 URL 的工作階段 |

276 307

277<h3 id="keyboard-shortcuts">308<h3 id="keyboard-shortcuts">

281在 agent view 中按 `?` 查看每個快捷鍵。下表總結了它們。312在 agent view 中按 `?` 查看每個快捷鍵。下表總結了它們。

282 313

283| 快捷鍵 | 動作 |314| 快捷鍵 | 動作 |

284| :-------------------- | :-------------------------------- |315| :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

285| `↑` / `↓` | 在行之間移動 |316| `↑` / `↓` | 在行之間移動 |

320| `Ctrl+Enter` | 分派並立即附加，在終端中 `?` overlay 列出 `ctrl+enter to start and open` |

289| `→` | 附加到選定的工作階段 |321| `→` | 附加到選定的工作階段 |

291| `Tab` | 在空輸入上，瀏覽所有 subagents。否則應用突出顯示的建議 |323| `Tab` | 在空輸入上，瀏覽所有 subagents。否則應用突出顯示的建議 |

328| `Ctrl+J` | 在分派輸入中插入新行 |

298| `Esc` | 關閉查看面板、清除輸入或退出 |331| `Esc` | 關閉查看面板、清除輸入或退出。當您通過使用 `←` 背景化工作階段開啟 agent view 時，最後的 `Esc` 會返回該對話而不是退出。啟用 [vim 編輯器模式](/docs/zh-TW/interactive-mode#vim-editor-mode)時，在輸入中按 `Esc` 會從 INSERT 切換到 NORMAL 模式並保留您的文字，如同主提示 |

300| `?` | 顯示所有快捷鍵 |333| `?` | 顯示所有快捷鍵 |

301 334

335`Ctrl+S`、`Ctrl+T` 和 `Ctrl+G` 遵循您的 [`keybindings.json`](/docs/zh-TW/keybindings)。使用 [`Agents` 上下文](/docs/zh-TW/keybindings#agents-actions)中的 `agents:switchView` 和 `agents:togglePin` 動作重新綁定或取消綁定 `Ctrl+S` 和 `Ctrl+T`，以及通過 `Chat` 上下文的 `chat:externalEditor` 綁定重新綁定 `Ctrl+G`。表中的其他快捷鍵無法重新綁定。

336

302<h2 id="dispatch-new-agents">337<h2 id="dispatch-new-agents">

303 分派新代理338 分派新代理

304</h2>339</h2>

311 346

312在 agent view 底部的輸入框中輸入提示，然後按 `Enter` 啟動新的背景工作階段。工作階段從提示自動命名；稍後可以使用 `Ctrl+R` 重命名它。347在 agent view 底部的輸入框中輸入提示，然後按 `Enter` 啟動新的背景工作階段。工作階段從提示自動命名；稍後可以使用 `Ctrl+R` 重命名它。

313 348

314工作階段稍後獲得的名稱也會出現在其行上，包括當您在該工作階段中[接受計畫](/docs/zh-TW/permission-modes#review-and-approve-a-plan)時 Claude 衍生的名稱。在 v2.1.207 之前，通過接受計畫命名的背景工作階段在 `/status` 中顯示該名稱，但在您自己重命名之前不會在其 agent-view 行上顯示。349自動名稱是由 [Haiku-class model](/docs/zh-TW/model-config) 撰寫的簡短標籤。工作階段稍後獲得的名稱也會出現在其行上，包括當您在該工作階段中[接受計畫](/docs/zh-TW/permission-modes#review-and-approve-a-plan)時工作階段獲得的[生成標題](/docs/zh-TW/sessions#name-your-sessions)。

315 350

316將圖像粘貼到提示中以包含螢幕截圖或圖表與任務。351將圖像粘貼到提示中以包含螢幕截圖或圖表與任務。

317 352

318粘貼的文字超過 800 個字符或超過兩行會摺疊為 `[Pasted text #N]` 佔位符，以便輸入保持在一行；完整文字會在您分派時發送。要在分派前檢查或編輯摺疊的文字，請再次粘貼相同的文字，佔位符會展開回輸入框。在至少 90 列寬的終端上，粘貼後會在輸入下方出現 `paste again to expand` 提醒，持續幾秒鐘。在 v2.1.207 之前，再次粘貼相同的文字會新增第二個佔位符，而不是展開第一個。353粘貼的文字超過 800 個字符或超過三行會摺疊為 `[Pasted text #N]` 佔位符，以便輸入保持在一行；完整文字會在您分派時發送。要在分派前檢查或編輯摺疊的文字，請再次粘貼相同的文字，佔位符會展開回輸入框。

319 354

320前綴或提及提示的部分以控制工作階段如何啟動：355前綴或提及提示的部分以控制工作階段如何啟動：

321 356

322| 輸入 | 效果 |357| 輸入 | 效果 |

323| :---------------------- | :---------------------------------------------------------------------------------------- |358| :----------------------- | :---------------------------------------------------------------------------------------- |

324| `<agent-name> <prompt>` | 如果第一個單詞與自訂 [subagent](/docs/zh-TW/sub-agents) 名稱匹配，該 subagent 以工作階段的主代理身份執行，其 frontmatter 中的配置 |359| `<agent-name> <prompt>` | 如果第一個單詞與自訂 [subagent](/docs/zh-TW/sub-agents) 名稱匹配，該 subagent 以工作階段的主代理身份執行，其 frontmatter 中的配置 |

330| `Shift+Enter` | 分派並立即附加到新工作階段 |

331 365

332一小組命令在 agent view 本身中執行，而不是分派：366一小組命令在 agent view 本身中執行，而不是分派：

333 367

334* `/exit` 和 `/quit` 關閉 agent view368* `/exit` 和 `/quit` 關閉 agent view

335* `/logout` 將您登出369* `/logout` 將您登出

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

337* 自 v2.1.198 起，`/login` 開啟登入對話框，讓您無需附加到工作階段即可再次登入371* `/login` 開啟登入對話框，讓您無需附加到工作階段即可再次登入

372* 裸 `/resume` 或其 `/continue` 別名開啟儲存庫過去工作階段的選擇器，以[將其帶回](#organize-the-list)作為背景工作階段。需要 Claude Code v2.1.212 或更新版本

338 373

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

340 375

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

342 377

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

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

357 392

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

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

360 395

361當 agent view 按目錄分組時，突出顯示的行的目錄成為分派目標，因此您可以滾動到組並在其中分派，無需重新輸入路徑。396當 agent view 按目錄分組時，分派會將提示發送到選定行的目錄，因此您可以選擇一個組並在其中分派，無需重新輸入路徑。

362 397

363<h3 id="from-inside-a-session">398<h3 id="from-inside-a-session">

364 從工作階段內部399 從工作階段內部

365</h3>400</h3>

366 401

402兩個命令將工作從您所在的工作階段移動到背景：`/background` 將當前對話發送到那裡並釋放您的終端，而 `/fork` 在您繼續工作的地方發送一份副本。

403

404<h4 id="send-the-session-to-the-background">

405 將工作階段發送到背景

406</h4>

407

367執行 `/background` 或其別名 `/bg` 將當前對話移動到背景工作階段。傳遞提示，例如 `/bg run the test suite and fix any failures`，以在分派前發送一個額外的指令。如果 Claude 在您執行 `/bg` 時正在回應，回應會在背景工作階段中繼續。408執行 `/background` 或其別名 `/bg` 將當前對話移動到背景工作階段。傳遞提示，例如 `/bg run the test suite and fix any failures`，以在分派前發送一個額外的指令。如果 Claude 在您執行 `/bg` 時正在回應，回應會在背景工作階段中繼續。

368 409

369退出仍有背景工作執行的互動工作階段（例如 subagents、背景 shell 命令、工作流程或 [monitors](/docs/zh-TW/tools-reference#monitor-tool)）會顯示 `Background work is running` 對話而不是立即退出。自 v2.1.198 起，對話框提供 `Move to background and exit` 以及 `Exit anyway` 和 `Stay`。選擇它會以與 `/background` 相同的方式將工作階段移動到背景，然後返回您的 shell，因此可以繼續的工作會保持執行，工作階段會出現在 agent view 中。當 agent view [關閉](#turn-off-agent-view)時，不會顯示此選項。410退出仍有背景工作執行的互動工作階段（例如 subagents、背景 shell 命令、工作流程或 [monitors](/docs/zh-TW/tools-reference#monitor-tool)）會顯示 `Background work is running` 對話而不是立即退出。選擇 `Move to background and exit` 以與 `/background` 相同的方式將工作階段移動到背景並返回您的 shell。當 agent view [關閉](#turn-off-agent-view)時，不會顯示此選項。

411

412如果背景工作階段列表上已有相同名稱的對話，Claude Code 會為新行的名稱編號，例如 `my-session (2)`，並保持現有行的名稱不變。要重命名新行，請在 agent view 中選擇它並按 `Ctrl+R`。

413

414<h4 id="copy-the-session-with-/fork">

415 使用 /fork 複製工作階段

416</h4>

417

418執行 `/fork` 將當前對話複製到新的背景工作階段，同時原始工作階段繼續執行。副本從該點之前的對話中的所有內容開始；請參閱下面的項目符號以了解副本在何處執行。它還帶來了模型、權限模式、努力級別以及您在工作階段期間新增的任何目錄或「不再詢問」權限授予。副本在 agent view 中顯示為其自己的行。

419

420在 fork 之後，兩個對話是獨立的：副本所做的任何事情都不會自動進入原始對話，儘管在啟用[跨工作階段訊息](/docs/zh-TW/cross-session-messaging)的工作階段中，任一工作階段的 Claude 都可以明確地向另一個發送訊息。

421

422複製工作階段需要 Claude Code v2.1.212 或更新版本；在 v2.1.161 到 v2.1.211 上，`/fork` 啟動[分叉 subagent](/docs/zh-TW/sub-agents#fork-the-current-conversation)，現在是 `/subtask`。當[agent view 關閉](#turn-off-agent-view)時，`/fork` 保持分叉 subagent 行為，`/subtask` 不可用。

423

424傳遞提示，例如 `/fork open a draft pull request with the work so far`，副本立即開始處理它。沒有提示的情況下，副本等待其第一個指令：在 `claude agents` 中選擇其行並按 `Space` 發送一個，或執行 `claude attach <id>`。選定的行在等待時顯示 `space to send it a prompt`。

425

426`/fork` 確認是一行，顯示副本的狀態，例如 `session running`、其 agent-view 行的名稱和其工作階段 ID 用於 `claude attach`。點擊名稱以切換到副本：此工作階段移動到背景，與按 `←` 相同，agent view 開啟副本的工作階段。

427

428除非副本[就地編輯](#how-file-edits-are-isolated)，Claude Code 指示它在進行程式碼更改前建立自己的 worktree。在 git 儲存庫外，只有從 hook 建立的 worktree 移出的副本才會獲得指令；沒有 [`WorktreeCreate` hook](/docs/zh-TW/hooks#worktreecreate)，副本就地編輯。從您的 worktree 移出的副本也被告知永遠不要編輯、執行命令或進入該 worktree，無論隔離設定如何。

429

430副本開始的位置取決於當前工作階段執行的位置：

431

432* 像任何分派的工作階段一樣，副本[在編輯檔案前移動到其自己的 worktree](#how-file-edits-are-isolated)。在這種情況下，確認不會提及副本執行的位置。

433* 當您的工作階段在啟動後移動到其連結的 [worktree](/docs/zh-TW/worktrees) 時，副本開始回到工作階段移動前的位置，除非它[就地編輯](#how-file-edits-are-isolated)，在那裡建立自己的 worktree 進行程式碼更改。當您的 worktree 簽出在一個分支上時，該指令也告訴一個副本，其任務建立在您的工作基礎上，以您的分支為基礎建立其新分支，因為您的分支在您的 worktree 中保持簽出。確認以 `runs in the origin tree` 結尾。

434* 當您在已連結 worktree 內啟動工作階段，該儲存庫有主工作樹時，副本開始於該主工作樹，具有相同的 worktree-of-its-own 規則但沒有分支指令。確認也以 `runs in the origin tree` 結尾。

435* 在裸儲存庫佈局的 worktree 內啟動的工作階段沒有主工作樹可返回，因此副本保持原位，確認以 `edits this checkout` 結尾。當 worktree 隔離在不在連結 worktree 內的工作階段中[關閉](#how-file-edits-are-isolated)時，也會出現相同的註記，因為副本隨後編輯您打開的檔案。

436

437使用副本不會繼承的啟動標誌啟動的工作階段，例如替換的系統提示或 `--tools` 允許清單，無法分叉；Claude Code 會說明這一點，而不是製作部分副本。從 agent view 分派的工作階段正常分叉：副本使用與其來自的工作階段相同的[代理定義](/docs/zh-TW/sub-agents)和附加指令啟動。

370 438

371從互動工作階段背景化會啟動一個新的進程，該進程從保存的對話恢復，進行中的工作會轉移到它：執行中的背景 shell 命令、背景化的 subagents、動態工作流程和您使用 [`/loop`](/docs/zh-TW/scheduled-tasks)建立的排定任務會轉移到背景工作階段並在那裡繼續執行。Subagent 與它啟動的所有內容一起移動，因此只有當所有工作都能轉移時它才會轉移，包括在 Windows 上。要停止進行中的工作而不是轉移它，請設定 [`CLAUDE_DISABLE_ADOPT=1`](/docs/zh-TW/env-vars#variables)環境變數；Claude Code 隨後會要求您在背景化前確認。439<h4 id="what-carries-over-when-you-background">

440 背景化時帶來的內容

441</h4>

442

443背景化啟動一個新進程，從保存的對話恢復，進行中的工作會轉移到它：執行中的背景 shell 命令、背景化的 subagents、動態工作流程、您使用 [`/loop`](/docs/zh-TW/scheduled-tasks) 建立的排定任務，以及 Claude 對[工件註解的自動回覆](/docs/zh-TW/artifacts#let-claude-reply-to-comments-on-its-own)都會轉移並在那裡繼續執行。Subagent 與它啟動的所有內容一起移動，因此只有當所有工作都能轉移時它才會轉移。要停止進行中的工作而不是轉移它，請設定 [`CLAUDE_DISABLE_ADOPT=1`](/docs/zh-TW/env-vars#variables) 環境變數；Claude Code 隨後會要求您在背景化前確認。

444

445當[動態工作流程](/docs/zh-TW/workflows)仍有 subagents 執行時，Claude Code 會在背景化前詢問 `Background this session?` 對話，說明有多少 subagents 會重新啟動。選擇 `Stay` 讓它們先完成。如果您確認，Claude Code 會在背景工作階段中重新執行該執行：仍在執行的 subagents 從頭開始，因此它們迄今為止使用的令牌會再次花費。請參閱[暫停後恢復](/docs/zh-TW/workflows#resume-after-a-pause)以了解哪些已完成的 subagents 返回其保存的結果，哪些再次執行。

372 446

373無法轉移的工作，例如執行中的 [monitor](/docs/zh-TW/tools-reference#monitor-tool)，會被停止。擁有監視器的背景化 subagent 會與它一起被停止。當任何此類工作執行時，Claude Code 會顯示 `Background this session?` 對話，以便您可以在停止前確認。447Claude Code 停止無法轉移的工作，例如執行中的 [monitor](/docs/zh-TW/tools-reference#monitor-tool)，並停止擁有監視器的背景化 subagent 及其一起。當任何此類工作執行時，Claude Code 會顯示 `Background this session?` 對話，以便您可以在停止前確認。

374 448

375進入背景後，工作階段可以啟動新的 subagents、monitors 和背景命令，這些命令在稍後分離和重新附加時保持執行。449進入背景後，工作階段可以啟動新的 subagents、monitors 和背景命令，這些命令在稍後分離和重新附加時保持執行。

376 450

383* `--fallback-model`457* `--fallback-model`

384* `--allow-dangerously-skip-permissions`458* `--allow-dangerously-skip-permissions`

385 459

386您在工作階段期間使用 [`/add-dir`](/docs/zh-TW/permissions#additional-directories-grant-file-access-not-configuration)新增的目錄也會傳遞。460您在工作階段期間使用 [`/add-dir`](/docs/zh-TW/permissions#additional-directories-grant-file-access-not-configuration) 新增的目錄也會轉移。轉移 `--allow-dangerously-skip-permissions` 會在背景化工作階段中保持 `bypassPermissions` 可達，但它不會授予任何新的權限：該模式仍然需要[Permission mode, model, and effort](#permission-mode-model-and-effort)中所述的一次性互動接受。

~~387~~

388傳遞 `--allow-dangerously-skip-permissions` 會在背景化工作階段中保持 `bypassPermissions` 可達，但它不會授予任何新的權限。該模式仍然需要在任何工作階段使用它之前進行相同的一次性互動接受，如[Permission mode, model, and effort](#permission-mode-model-and-effort)中所述。

389 461

390<h3 id="from-your-shell">462<h3 id="from-your-shell">

391 從您的 shell463 從您的 shell

397claude --bg "investigate the flaky SettingsChangeDetector test"469claude --bg "investigate the flaky SettingsChangeDetector test"

398```470```

399 471

400提示是位置引數，不是 `-p` 值。自 v2.1.198 起，將 `--bg` 與 `-p` 或 `--print` 結合會在建立任何工作階段前被拒絕並出現錯誤，因為 `--print` 永遠不會啟動 `claude agents` 附加到的互動工作階段。472提示是位置引數，不是 `-p` 值。Claude Code 在建立任何工作階段前拒絕 `--bg` 與 `-p` 或 `--print` 的組合，因為 `--print` 永遠不會啟動 `claude agents` 附加到的互動工作階段。

401 473

402要執行特定 subagent 作為工作階段的主代理，將 `--bg` 與 `--agent` 結合：474要執行特定 [subagent](/docs/zh-TW/sub-agents)（例如 `code-reviewer`）作為工作階段的主代理，請將 `--bg` 與 `--agent` 結合：

403 475

404```bash theme={null}476```bash theme={null}

405claude --agent code-reviewer --bg "address review comments on PR 1234"477claude --agent code-reviewer --bg "address review comments on PR 1234"

406```478```

407 479

480如果名稱不與任何 subagents 匹配，啟動失敗：Claude Code 列印 `no agent named` 警告，仍然報告工作階段為背景化，但工作階段立即以 `--agent '<name>' not found` 錯誤退出。

481

482當背景化工作階段稍後恢復或重新啟動時，Claude Code 恢復代理及其工具限制；對於其系統提示，請參閱[已恢復對話中的系統提示標誌](/docs/zh-TW/cli-reference#system-prompt-flags-in-resumed-conversations)。它首先在工作階段自己的目錄中搜索代理，前提是您已[信任該工作區](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)，因此專案範圍的代理在從另一個目錄恢復工作階段時仍會載入。如果代理不再存在，工作階段會繼續使用預設工具，其文字記錄會以[警告命名代理](/docs/zh-TW/errors#session-agent-no-longer-available)開啟。

483

484要在背景中繼續現有對話，請使用 `--resume` 傳遞其完整工作階段 ID：

485

486```bash theme={null}

487claude --resume 1f0e2c9a-6d0b-4c11-9f39-2a77c1d4e8b5 --bg "pick up where you left off and finish the migration"

488```

489

490在 Claude Code v2.1.257 或更新版本上，Claude Code 要麼在相同 ID 下繼續該工作階段，要麼在新 ID 下啟動副本並列印 `note:` 行解釋為什麼它無法就地繼續。當工作階段就地繼續時，`claude agents` 為其顯示一行。

491

492當您將 `--bg` 與 `--continue`、裸 `--resume` 或 `--resume` 與名稱或檔案路徑結合時，Claude Code 總是啟動這樣的副本。新增 `--fork-session` 以故意啟動副本，無需註記。

493

408傳遞 `--name` 以在 agent view 中設定工作階段的顯示名稱，而不是自動生成的名稱：494傳遞 `--name` 以在 agent view 中設定工作階段的顯示名稱，而不是自動生成的名稱：

409 495

410```bash theme={null}496```bash theme={null}

425 執行 shell 命令511 執行 shell 命令

426</h4>512</h4>

427 513

428要執行 shell 命令作為背景工作而不是 Claude 工作階段，請在 agent view 分派輸入的第一個字符中輸入 `!`。`!` 顯示為前綴，您在其後輸入的所有內容都是命令。以下示例從 agent view 輸入框分派 `pytest -x`：514要執行 shell 命令作為背景工作而不是 Claude 工作階段，請傳遞 `--exec`。以下示例將 `pytest -x` 作為背景工作執行：

~~429~~

430```text theme={null}

431! pytest -x

432```

~~433~~

434按 `Enter` 啟動工作。相同的工作也可以直接從您的 shell 使用 `--exec` 啟動：

435 515

436```bash theme={null}516```bash theme={null}

437claude --bg --exec 'pytest -x'517claude --bg --exec 'pytest -x'

438```518```

439 519

520從 agent view，通過在分派輸入的第一個字符中輸入 `!` 分派相同類型的工作：`!` 顯示為前綴，其後的所有內容都是命令，`Enter` 啟動工作。

521

440該命令作為 PTY 支持的工作執行，並在 agent view 中顯示為一行，其最近的輸出行作為其狀態。shell 工作執行命令代替 Claude，因此不調用任何模型，輸出不發送到任何工作階段。522該命令作為 PTY 支持的工作執行，並在 agent view 中顯示為一行，其最近的輸出行作為其狀態。shell 工作執行命令代替 Claude，因此不調用任何模型，輸出不發送到任何工作階段。

441 523

442要查看輸出，附加到該行，按 `Space` 以在不附加的情況下查看，或從您的 shell 執行 `claude logs <id>`。捕獲的輸出保留在記憶體中，不寫入磁碟。該行及其輸出在命令退出後約五分鐘自動清理，因此如果您需要結果，請在那之前讀取它。524要查看輸出，附加到該行，按 `Space` 以在不附加的情況下查看，或從您的 shell 執行 `claude logs <id>`。捕獲的輸出保留在記憶體中，不寫入磁碟。該行及其輸出在命令退出後約五分鐘自動清理，因此如果您需要結果，請在那之前讀取它。

445 檔案編輯如何隔離527 檔案編輯如何隔離

446</h3>528</h3>

447 529

448每個背景工作階段，無論是從 agent view、`/bg` 或 `claude --bg` 啟動，都在您的工作目錄中啟動。編輯檔案前，Claude 將工作階段移動到 `.claude/worktrees/` 下的隔離 [git worktrees](/docs/zh-TW/worktrees)中，因此並行工作階段可以讀取相同的檢出，但每個都寫入自己的。530每個背景工作階段，無論是從 agent view、`/bg` 或 `claude --bg` 啟動，都在您的工作目錄中啟動。編輯檔案前，Claude 將工作階段移動到 `.claude/worktrees/` 下的隔離 [git worktree](/docs/zh-TW/worktrees)，因此並行工作階段可以讀取相同的檢出，但每個都寫入自己的。一旦工作階段在其 worktree 中，Claude Code [為工作階段和它生成的任何 subagents 強制執行 worktree 隔離](/docs/zh-TW/worktrees#how-claude-code-enforces-isolation)。

449 531

450Claude 在以下情況下跳過 worktree：532Claude 在以下情況下跳過 worktree：

451 533

452* 工作階段已在連結的 git worktree 內，無論 Claude 是在 `.claude/worktrees/` 下建立它，還是您使用 `git worktree add` 在其他地方建立它534* 工作階段已在連結的 git worktree 內，無論 Claude 是在 `.claude/worktrees/` 下建立它，還是您使用 `git worktree add` 在其他地方建立它

535* Claude 正在編輯的檔案在連結的 git worktree 內，例如工作階段或其 subagent 使用 `git worktree add` 建立的那個

453* 工作目錄不是 git 儲存庫且沒有配置 [`WorktreeCreate` hook](/docs/zh-TW/hooks#worktreecreate)536* 工作目錄不是 git 儲存庫且沒有配置 [`WorktreeCreate` hook](/docs/zh-TW/hooks#worktreecreate)

454* 寫入在工作目錄外537* 寫入在工作目錄外

455 538

456要為 git worktrees 不實用的儲存庫關閉 worktree 隔離，請將 [`worktree.bgIsolation`](/docs/zh-TW/settings#worktree-settings)設定為 `"none"`。背景工作階段隨後直接編輯您的工作副本，無需先移動到 worktree。將設定新增到專案的 `.claude/settings.json`：539要為 git worktrees 不實用的儲存庫關閉 worktree 隔離，請將 [`worktree.bgIsolation`](/docs/zh-TW/settings-reference#worktree-bgisolation) 設定為 `"none"`。背景工作階段隨後直接編輯您的工作副本，無需先移動到 worktree。將設定新增到專案的 `.claude/settings.json`：

457 540

458```json theme={null}541```json theme={null}

459{542{

465 548

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

467 550

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

~~469~~

470刪除工作階段會移除或保留 Claude 為其建立的 worktree，取決於您如何刪除它以及 worktree 包含的內容：

~~471~~

472* 在 agent view 中使用 `Ctrl+X` 兩次刪除會移除 worktree，包括任何未提交的更改，因此請先提交您想保留的更改。

473* 從 shell 使用 [`claude rm`](#manage-sessions-from-the-shell)刪除會保留具有未提交更改的 worktree，以及其工作階段行。

474* 兩種方式都不會移除具有未推送到任何地方的提交的 worktree：worktree 會[與其工作階段一起保留](#organize-the-list)，輸出會命名保留的路徑和原因。

475* 您自己建立並在其中啟動工作階段的 worktree 無論如何都會保留在原位。

476 552

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

478 554

479[subagent](/docs/zh-TW/sub-agents)背景工作階段生成的會繼承工作階段的工作目錄，因此其檔案編輯會進入工作階段的 worktree 而不是您的工作副本。要給 subagent 其自己的單獨 worktree，請在其 frontmatter 中設定 [`isolation: worktree`](/docs/zh-TW/sub-agents#supported-frontmatter-fields)或在生成它時傳遞 `isolation: "worktree"`。555[subagent](/docs/zh-TW/sub-agents) 背景工作階段生成的會繼承工作階段的工作目錄，因此其檔案編輯會進入工作階段的 worktree 而不是您的工作副本。要給 subagent 其自己的單獨 worktree，請在其 frontmatter 中設定 [`isolation: worktree`](/docs/zh-TW/sub-agents#supported-frontmatter-fields) 或在生成它時傳遞 `isolation: "worktree"`。

556

557當背景工作階段在 Claude 進入的 worktree 中進行了程式碼更改時，Claude Code 指示 Claude 在完成前保留工作，因此如果您刪除工作階段及其 worktree，它會存活：

480 558

481自 v2.1.198 起，在隔離 worktree 中隔離其程式碼更改的背景工作階段也會提交、推送其自己的分支，並開啟草稿拉取請求而無需停止詢問。當拉取請求開啟時，[`#N` 標籤](#pull-request-status)會出現在其行上。它永遠不會推送到 `main` 或 `master`，永遠不會強制推送或合併，並且當您告訴它不要開啟拉取請求或儲存庫沒有遠端時會跳過拉取請求。559* **提交並推送**：Claude 無需詢問即可提交，當儲存庫有遠端時推送分支。

560* **草稿拉取請求**：當任務要求時 Claude 開啟一個，[`#N` 標籤](#pull-request-status)出現在行上。

561* **永遠不會**：推送到 `main` 或 `master`、強制推送和合併。

562* **您的 git 指令優先**：如果任務、`CLAUDE.md` 或[記憶](/docs/zh-TW/memory)說您自己處理提交或推送，Claude 將 git 留給您。

482 563

483編輯未自行隔離的檢出的工作階段在提交或切換分支前仍會詢問。這適用於隔離設定為 `"none"` 時、worktree 移動失敗時，或工作階段在已存在的 worktree 內啟動時。564編輯未自行隔離的檢出的工作階段在提交或切換分支前仍會詢問。這適用於隔離設定為 `"none"` 時、worktree 移動失敗時，或工作階段在已存在的 worktree 內啟動時。

484 565

566無論任務如何，Claude 以報告結尾，說明它做了什麼以及工作在哪裡：路徑、分支、拉取請求或答案本身。

567

568<h4 id="what-deleting-a-session-removes">

569 刪除工作階段會移除什麼

570</h4>

571

572使用 [agent view](#organize-the-list) 中的 `Ctrl+X` 兩次或使用 [`claude rm`](#manage-sessions-from-the-shell) 刪除工作階段。除了下面保留的情況外，工作階段會離開列表。其文字記錄通過 `claude --resume` 保留在您的機器上，移除在監督者重新啟動後存活。

573

574Claude 為工作階段建立的 worktree 會發生什麼：

575

576* Agent view 移除它，包括未提交的更改，因此請先提交您想保留的內容。

577* `claude rm` 在它有未提交更改時保留它，以及工作階段行。

578* 當另一個執行中的工作階段正在使用或已鎖定 worktree 時，agent view 和 `claude rm` 都不會移除它，再次刪除不會改變這一點。Claude Code 保留 worktree 和工作階段，並命名保留的目錄和原因；在 agent view 中，工作階段的行顯示 `not deleted`。關閉另一個工作階段，然後再次刪除。

579* 當您刪除一個 worktree 有 Claude Code 無法確認保存在其他地方的提交的工作階段時，Claude Code 保留 worktree 和工作階段，訊息命名 worktree 的分支以及有多少提交未推送。訊息還提供了兩種前進方式：推送提交，或再次刪除以丟棄它們。

580

581 遠端上的提交不會阻止刪除。本地副本上的提交也不會，您的 `origin` 遠端的預設分支，只要該分支在您的主檢出中簽出，儲存庫目錄本身而不是 worktree。

582

583 在該拒絕後，您選擇：

584

585 * 要保留提交，推送它們或將它們合併到該預設分支，然後再次刪除工作階段。

586 * 要丟棄它們，再次刪除工作階段而不推送：在 agent view 中的其行上按 `Ctrl+X` 兩次，或執行拒絕列印的 `claude rm <id> --discard-unpushed` 命令。這會移除工作階段和 worktree 及其分支，丟棄未推送的提交和任何未提交的更改。

587

588 當您再次刪除時，Claude Code 只丟棄拒絕顯示的內容：如果 worktree 自那以後獲得了提交，Claude Code 會再次保留它並顯示更新的狀態。

589

590 當另一個已完成工作階段的記錄也命名 worktree 時，它在您再次刪除時保留；推送提交，然後再次刪除。

591* git 不再識別的 worktree，例如在 `git worktree prune` 之後，不會阻止刪除。Claude Code 刪除工作階段並將目錄留在磁碟上。

592* 當 git 或您的 [`WorktreeRemove` hook](/docs/zh-TW/hooks#worktreeremove) 無法移除 worktree 時，Claude Code 保留 worktree 和工作階段，訊息命名原因。對於 hook，訊息說它如何結束，例如 `exited 1`，並引用其 stderr 的開始。訊息還告訴您接下來要做以下哪一個：

593

594 * 再次刪除工作階段以無論如何移除目錄，通過在 agent view 中的其行上按 `Ctrl+X` 兩次或執行 `claude rm` 拒絕列印的 `claude rm <id> --force-remove-worktree <worktree-id>` 命令。Claude Code 只在它可以確認目錄是儲存庫在 `.claude/worktrees/` 下的連結 worktrees 之一，沒有對追蹤檔案的未提交更改、其內沒有嵌套儲存庫且沒有其他工作階段的記錄命名它時才提供此選項。Worktree 的分支保留在儲存庫中。

595 * 修復阻礙的內容，例如提交或儲存未提交的更改、關閉使用目錄的任何內容或修復 hook，然後再次刪除工作階段。

596 * 自己移除目錄，然後再次刪除工作階段。

597

598您自己建立並在其中啟動工作階段的 worktree 無論如何都會保留在原位。

599

600一個 worktree 目錄不屬於任何 git 儲存庫的工作階段，因為儲存庫被刪除或 [`WorktreeCreate` hook](/docs/zh-TW/hooks#worktreecreate) 在其他地方建立了目錄，仍然可以被刪除。當檔案保留在目錄中時：

601

602* Agent view 在丟棄它們前要求相同的 `Ctrl+X` 雙擊。對於 hook 建立的目錄，它執行您的 [`WorktreeRemove` hook](/docs/zh-TW/hooks#worktreeremove)，沒有一個它拒絕刪除並保留工作階段。

603* `claude rm` 保留工作階段和 worktree，並命名原因。

604

605任一路徑都保留另一個已完成工作階段的記錄命名的目錄。

606

485<h3 id="set-the-model">607<h3 id="set-the-model">

486 設定模型608 設定模型

487</h3>609</h3>

488 610

489agent view 標題中顯示的模型名稱是分派預設值。您從輸入啟動的新工作階段使用此模型，這來自您使用者設定中的 [`model` setting](/docs/zh-TW/settings#available-settings)。通過在 [`/model` picker](/docs/zh-TW/model-config)中選擇模型來設定它，或直接編輯設定。611agent view 標題中顯示的模型名稱是分派預設值。您從輸入啟動的新工作階段使用此模型，這來自您使用者設定中的 [`model` setting](/docs/zh-TW/settings-reference#model)。通過在 [`/model` picker](/docs/zh-TW/model-config) 中選擇模型來設定它，或直接編輯設定。

490 612

491要為整個 agent view 工作階段覆蓋分派預設值，請在開啟 agent view 時傳遞 `--model`。請參閱[Permission mode, model, and effort](#permission-mode-model-and-effort)。613要為整個 agent view 工作階段覆蓋分派預設值，請在開啟 agent view 時傳遞 `--model`。請參閱[Permission mode, model, and effort](#permission-mode-model-and-effort)。

492 614

493要從 agent view 內部更改分派預設值，請在分派輸入中輸入 `/model` 後跟模型名稱，然後按 `Enter`。標題會更新以顯示該模型，並帶有 `(session)` 標記，之後您分派的工作階段會使用它。輸入 `/model default` 以清除覆蓋並返回分派預設值。此覆蓋會持續到當前 `claude agents` 執行的其餘部分，不會寫入您的設定檔案。以下示例在 Opus 上分派一個工作階段，在 Sonnet 上分派下一個：615要從 agent view 內部更改分派預設值，請在分派輸入中輸入 `/model` 後跟模型名稱，然後按 `Enter`。標題會更新以顯示該模型，帶有 `(session)` 標記，之後您分派的工作階段會使用它。輸入 `/model default` 以清除覆蓋並返回分派預設值。此覆蓋會持續到當前 `claude agents` 執行的其餘部分，不會寫入您的設定檔案。以下示例在 Opus 上分派一個工作階段，在 Sonnet 上分派下一個：

494 616

495```text theme={null}617```text theme={null}

496/model opus618/model opus

509 Permission mode, model, and effort631 Permission mode, model, and effort

510</h3>632</h3>

511 633

512背景工作階段從它執行的目錄讀取其 [settings](/docs/zh-TW/settings)，就像您在那裡啟動了 `claude` 一樣。這包括專案設定中的 [`env` values](/docs/zh-TW/settings#available-settings)，因此在那裡設定的 `ANTHROPIC_MODEL` 或提供者變數適用於該目錄中的背景工作階段。634背景工作階段從它執行的位置和方式取得其設定、提供者、權限模式、模型和努力。下面的小節涵蓋每個來源，以及監督者重新啟動工作階段時持續的內容。

635

636<h4 id="settings-and-provider">

637 Settings and provider

638</h4>

639

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

641

642背景工作階段也使用您分派它的 shell 的 `PATH` 執行，因此它執行的命令找到與您的終端相同的工具。它也保留該 shell 的雲提供者選擇，例如 `CLAUDE_CODE_USE_BEDROCK` 或 `CLAUDE_CODE_USE_VERTEX`，以及其 `ANTHROPIC_DEFAULT_*_MODEL` 別名和任何您在那裡匯出的 [`CLAUDE_CODE_EXTRA_BODY`](/docs/zh-TW/env-vars) 覆蓋。

643

644<h4 id="llm-gateway">

645 LLM gateway

646</h4>

647

648如果您通過 [LLM gateway](/docs/zh-TW/llm-gateway) 路由 Claude Code，請將閘道變數放在設定檔案的 `env` 區塊中，而不是在您的 shell 中匯出它們，背景工作階段會與其餘設定一起讀取它們。[在設定檔案中設定](/docs/zh-TW/llm-gateway-connect#set-in-a-settings-file)顯示區塊以及要使用哪個設定檔案來獲取認證。

649

650如果您只在 shell 中匯出閘道 `ANTHROPIC_BASE_URL`，它只在以下情況下到達背景工作階段，以及您與它匯出的 `ANTHROPIC_CUSTOM_HEADERS` 和認證，只有當[監督者](#the-supervisor-process)本身從匯出相同閘道的 shell 啟動時，並且只在這些情況下：

513 651

514雲提供者選擇，例如 `CLAUDE_CODE_USE_BEDROCK` 或 `CLAUDE_CODE_USE_VERTEX`，以及 `ANTHROPIC_DEFAULT_*_MODEL` 別名遵循分派工作階段的 shell。如果您在該 shell 中匯出 [`CLAUDE_CODE_EXTRA_BODY`](/docs/zh-TW/env-vars)請求體覆蓋，它也會以相同方式到達工作階段。在 v2.1.206 之前，背景工作者忽略了 shell 匯出的 `CLAUDE_CODE_EXTRA_BODY`。652* 您使用 `←` 或 `/background` 背景化您自己的工作階段

653* 您分派工作階段到您所在的目錄

654* 您通過附加或回覆它來喚醒您所在目錄中的停止工作階段

515 655

516如果您在分派 shell 中匯出閘道 `ANTHROPIC_BASE_URL`，它也會到達工作階段，以及 `ANTHROPIC_CUSTOM_HEADERS`，當監督者使用相同的閘道環境執行且工作階段在您分派的目錄中執行或是您自己的工作階段使用 `←` 或 `/background` 背景化時。這是當第一個開啟 agent view 或分派背景工作階段的 shell 是閘道 shell 時的正常情況。使用 `@repo` 或 `--cwd` 分派到不同目錄不會攜帶 shell 的閘道；該專案的 [settings](/docs/zh-TW/settings)提供端點。請參閱[the supervisor process](#the-supervisor-process)以了解背景工作階段如何源自提供者設定和認證。656Claude Code 在雲提供者前轉發閘道。如果您分派的 shell 選擇提供者並使用其認證繞過標誌匯出其閘道端點，Claude Code 會在適用於 `ANTHROPIC_BASE_URL` 的條件下轉發端點和標誌對，以及 `ANTHROPIC_CUSTOM_HEADERS`。例如，匯出 `CLAUDE_CODE_USE_VERTEX=1` 與 `ANTHROPIC_VERTEX_BASE_URL` 和 `CLAUDE_CODE_SKIP_VERTEX_AUTH=1`，Claude Code 會轉發該端點和標誌。

517 657

518[permission mode](/docs/zh-TW/permissions)取決於您如何啟動工作階段。使用 `/bg` 或 `←` 背景化現有工作階段會保持當前權限模式，因此您切換到 `acceptEdits` 或 `auto` 的工作階段在分離後仍保持該模式。從 agent view 輸入分派或從 shell 執行 `claude --bg` 使用該目錄設定中的 `defaultMode`，或分派的 [subagent 的 frontmatter](/docs/zh-TW/sub-agents#supported-frontmatter-fields)中的 `permissionMode`。658Claude Code 只將轉發的閘道應用於該工作階段的執行進程，永遠不會將其寫入磁碟。

519 659

520背景工作階段啟動時的權限模式、模型和努力，以及它攜帶的 [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` 在工作階段中途更改的模型或努力會被保留。660<h4 id="permission-mode">

661 Permission mode

662</h4>

663

664[permission mode](/docs/zh-TW/permissions) 取決於您如何啟動工作階段：

665

666* **使用 `/bg` 或 `←` 背景化**：Claude Code 保留工作階段所在的權限模式，因此您切換到 `acceptEdits` 或 `auto` 的工作階段在分離後仍保持該模式

667* **從您使用 `←` 開啟的 agent view 分派**：目標自己的配置優先，當沒有其他設定時，您來自的工作階段的權限模式適用

668* **從 shell 中啟動的 `claude agents` 或使用 `claude --bg` 分派**：新工作階段以新 `claude` 工作階段在該目錄中啟動的方式開始，除非您從使用[分派預設值](#dispatch-defaults)開啟的 agent view 分派它。[工作階段在哪個權限模式中啟動](/docs/zh-TW/permission-modes#which-mode-a-session-starts-in)列出順序

669

670對於您從使用 `←` 開啟的 agent view 分派的工作階段，Claude Code 從適用的第一個中取得權限模式：

671

6721. 目標目錄的 [`permissions.defaultMode`](/docs/zh-TW/settings-reference#permissions-defaultmode)。兩個來源規則適用：

673 * `auto` 和 `bypassPermissions` [只從受管設定、`--settings` 檔案或 `~/.claude/settings.json` 生效](/docs/zh-TW/settings-reference#permissions-defaultmode)。

674 * Claude Code 拒絕來自專案的 `.claude/settings.json` 或 `.claude/settings.local.json` 的 `defaultMode`，選擇比您來自的工作階段所在的更寬鬆的模式。

6752. 您來自的工作階段的權限模式

521 676

522工作階段從 [`effortLevel` setting](/docs/zh-TW/settings#available-settings)而不是從 `--effort` 或 `/effort` 取得的努力不會在分派時固定：為工作階段啟動的每個進程都會再次讀取設定，因此編輯 `settings.json` 中的 `effortLevel` 會到達您使用 `←` 或 `/bg` 背景化的工作階段及其稍後的重新啟動。在 v2.1.203 之前，背景化工作階段會記錄其設定衍生的努力，就像您傳遞了 `--effort` 一樣，因此稍後的 `effortLevel` 編輯永遠無法到達它。677當 Claude Code 拒絕來源的模式過於寬鬆時，列表中的下一個來源決定。例如，如果您從計畫模式工作階段分派到其簽入設定要求 `acceptEdits` 的目錄，新工作階段以計畫模式啟動。如果您將該 `defaultMode` 移動到 `~/.claude/settings.json`，它無論您來自的工作階段的權限模式如何都適用。

523 678

524您使用 [`/rename`](/docs/zh-TW/commands) 或 `Ctrl+R` 設定的名稱也會在該重新啟動時持續，因此 [`claude --resume <name>`](/docs/zh-TW/sessions#name-your-sessions) 仍會解析工作階段。在 v2.1.202 之前，重新啟動會將工作階段還原為分派時的名稱，新名稱停止解析。679寬鬆度執行計畫，然後手動和 `dontAsk`，然後 `acceptEdits` 和 auto，每個都計為比另一個更寬鬆，然後 `bypassPermissions`。

680

681<h4 id="dispatch-defaults">

682 Dispatch defaults

683</h4>

525 684

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

527 686

529claude agents --permission-mode plan --model opus --effort high688claude agents --permission-mode plan --model opus --effort high

530```689```

531 690

532`--agent` 設定 [subagent](/docs/zh-TW/sub-agents)，當分派提示未使用 `@name` 或作為第一個單詞命名時使用。如果設定了 [`agent` setting](/docs/zh-TW/settings#available-settings)，則預設為該設定，否則為內建的全能 `claude` 代理。在分派輸入中命名 subagent 會覆蓋兩者。691`--effort` 此處接受與[頂級 `--effort` 標誌](/docs/zh-TW/cli-reference#cli-flags)相同的值，包括 `ultracode`。

692

693`--agent` 設定 [subagent](/docs/zh-TW/sub-agents)，當分派提示未使用 `@name` 或作為第一個單詞命名時使用。如果設定了 [`agent` setting](/docs/zh-TW/settings-reference#agent)，則預設為該設定，否則為內建的全能 `claude` 代理。在分派輸入中命名 subagent 會覆蓋兩者。

694

695`claude agents` 也接受 `--dangerously-skip-permissions` 作為 `--permission-mode bypassPermissions` 的簡寫，以及 `--allow-dangerously-skip-permissions` 以在每個分派工作階段的 `Shift+Tab` 循環中提供 `bypassPermissions`，而不是以該模式啟動。兩者都與[頂級 CLI 標誌](/docs/zh-TW/cli-reference)相符。

533 696

534`claude agents` 也接受 `--dangerously-skip-permissions` 作為 `--permission-mode bypassPermissions` 的簡寫，以及 `--allow-dangerously-skip-permissions` 以在每個分派工作階段的 `Shift+Tab` 循環中提供 `bypassPermissions`，而不是以該模式啟動。兩者都與 [top-level CLI flags](/docs/zh-TW/cli-reference)相符。697傳遞 `--restricted` 以在[受限模式](/docs/zh-TW/cli-reference#cli-flags)中啟動您從檢視分派的每個工作階段，就像每個都使用頂級 `--restricted` 標誌啟動一樣。需要 Claude Code v2.1.248 或更新版本。

535 698

536活動預設值出現在分派輸入下方的頁腳中。699活動預設值出現在分派輸入下方的頁腳中。

537 700

538沒有這些標誌，工作階段使用該目錄設定中的 `defaultMode` 或分派的 [subagent 的 frontmatter](/docs/zh-TW/sub-agents#supported-frontmatter-fields)中的 `permissionMode`，以及 agent view 標題中顯示的模型。701Claude Code 拒絕 `claude --bg --permission-mode bypassPermissions`，直到您通過執行 `claude --dangerously-skip-permissions` 一次互動式接受了繞過免責聲明，因為該模式讓您未監視的工作階段無需批准即可行動。將 `--dangerously-skip-permissions` 或 `--permission-mode bypassPermissions` 傳遞給 `claude agents` 會在您之前未接受時顯示相同的免責聲明，接受會將 `bypassPermissions` 應用於您從檢視啟動的工作階段。傳遞 `--allow-dangerously-skip-permissions` 也會顯示相同的免責聲明，接受會在這些工作階段的 `Shift+Tab` 循環中提供 `bypassPermissions`，而不是以它啟動它們。

539 702

540使用 `bypassPermissions` 與 `claude --bg --permission-mode` 被拒絕，直到您通過執行 `claude --dangerously-skip-permissions` 一次互動式接受了繞過免責聲明，因為該模式讓您未監視的工作階段無需批准即可行動。將 `--dangerously-skip-permissions` 或 `--permission-mode bypassPermissions` 傳遞給 `claude agents` 會在您之前未接受時顯示相同的免責聲明，接受會將 `bypassPermissions` 應用於您從檢視啟動的工作階段。傳遞 `--allow-dangerously-skip-permissions` 也會顯示相同的免責聲明，接受會在這些工作階段的 `Shift+Tab` 循環中提供 `bypassPermissions`，而不是以它啟動它們。703<h4 id="what-persists-across-restarts">

704 重新啟動時持續的內容

705</h4>

706

707您為背景工作階段選擇的權限模式、模型和努力，以及它攜帶的[配置標誌](#what-carries-over-when-you-background)，在監督者稍後[停止並重新啟動](#the-supervisor-process)其進程時都會持續。您使用 `claude --bg --dangerously-skip-permissions` 或 `claude --bg --permission-mode bypassPermissions` 啟動的工作階段在該重新啟動後保持 `bypassPermissions`。您使用 `/model` 或 `/effort` 在工作階段中途更改的模型或努力也會被保留。

708

709如果工作階段從您的設定而不是從 `--effort` 或 `/effort` 取得其努力，Claude Code 會在每次為工作階段啟動進程時再次讀取您的設定。因此，當您編輯 `settings.json` 中保存的努力時，更改會到達您使用 `←` 或 `/bg` 背景化的工作階段及其稍後的重新啟動。保存的努力是 [`effortLevel`](/docs/zh-TW/settings-reference#effortlevel) 鍵或 [`modelSettings`](/docs/zh-TW/settings-reference#modelsettings) 條目。

710

711Claude Code 也保留您使用 [`/rename`](/docs/zh-TW/commands) 或 `Ctrl+R` 設定的名稱在該重新啟動時，因此您仍然可以執行 [`claude --resume <name>`](/docs/zh-TW/sessions#name-your-sessions) 以到達工作階段。

712

713您使用 [`Ctrl+S`](/docs/zh-TW/interactive-mode#general-controls) 在附加時儲存的提示也會與工作階段一起保留。在其進程被停止或重新啟動後重新開啟工作階段，`Ctrl+S` 恢復儲存的文字。儲存中的粘貼內容不會在重新啟動後存活。

541 714

542<h3 id="settings-plugins-and-mcp-servers">715<h3 id="settings-plugins-and-mcp-servers">

543 Settings, plugins, and MCP servers716 Settings, plugins, and MCP servers

544</h3>717</h3>

545 718

546Agent view 接受與 `claude` 相同的配置標誌，用於載入 settings、plugins、MCP servers 和額外目錄。每個標誌適用於 agent view 本身，並傳遞給您從它分派的每個工作階段，因此以這種方式載入的 plugin 或 MCP server 在這些工作階段中也可用。719Agent view 接受與 `claude` 相同的配置標誌，用於載入 settings、plugins、MCP servers 和額外目錄。Agent view 將 `--settings` 和 `--plugin-dir` 應用於自己，並將每個配置標誌傳遞給您從它分派的工作階段，因此以這種方式載入的 plugin 或 MCP server 在這些工作階段中也可用。

547 720

548| 標誌 | 效果 |721| 標誌 | 效果 |

549| :-------------------------------------------------------------------------------------------------- | :--------------------------------------------- |722| :-------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ |

551| [`--add-dir <path>`](/docs/zh-TW/permissions#additional-directories-grant-file-access-not-configuration) | 授予對額外目錄的檔案存取權限 |724| [`--add-dir <path>`](/docs/zh-TW/permissions#additional-directories-grant-file-access-not-configuration) | 授予對額外目錄的檔案存取權限 |

554| `--strict-mcp-config` | 僅使用來自 `--mcp-config` 的 MCP servers，忽略其他 MCP 配置 |727| `--strict-mcp-config` | 僅使用來自 `--mcp-config` 的 MCP servers，忽略其他 MCP 配置。請參閱[使用 managed-mcp.json 的獨佔控制](/docs/zh-TW/managed-mcp#exclusive-control-with-managed-mcp-json)以了解該標誌在受管 MCP 檔案下做什麼 |

555 728

556每個值重複 `--add-dir`、`--plugin-dir` 或 `--mcp-config` 一次。空格分隔的形式，例如 `--add-dir a b c`，不支援與 `claude agents` 一起使用。729每個值重複 `--add-dir`、`--plugin-dir` 或 `--mcp-config` 一次。`claude agents` 不支援空格分隔的形式，例如 `--add-dir a b c`。

730

731您可以將 `--settings` 和 `--plugin-dir` 放在 `agents` 之前或之後。將 `--add-dir` 和 `--mcp-config` 保留在 `agents` 之後：如果您將任一個放在 `agents` 之前，[`claude agents --json`](#manage-sessions-from-the-shell) 會失敗，出現 `unknown option` 錯誤。

557 732

558以下示例使用 settings 覆蓋和一個額外目錄開啟 agent view：733以下示例使用 settings 覆蓋和一個額外目錄開啟 agent view：

559 734

561claude agents --settings ./ci-settings.json --add-dir ../shared-lib736claude agents --settings ./ci-settings.json --add-dir ../shared-lib

562```737```

563 738

739`--settings` 接受檔案路徑或內聯 JSON 字符串。檔案路徑必須指向現有檔案；如果不存在，Claude Code 會以 `Settings file not found` 錯誤退出。

740

564<h2 id="manage-sessions-from-the-shell">741<h2 id="manage-sessions-from-the-shell">

565 從 shell 管理工作階段742 從 shell 管理工作階段

566</h2>743</h2>

568每個背景工作階段都有一個短 ID，您可以從 shell 使用。當您使用 `claude --bg` 啟動工作階段時會列印該 ID，每個工作階段的 ID 是其在 `~/.claude/jobs/` 下的目錄名稱。這些命令對於指令碼編寫或當您不想開啟 agent view 時很有用。745每個背景工作階段都有一個短 ID，您可以從 shell 使用。當您使用 `claude --bg` 啟動工作階段時會列印該 ID，每個工作階段的 ID 是其在 `~/.claude/jobs/` 下的目錄名稱。這些命令對於指令碼編寫或當您不想開啟 agent view 時很有用。

569 746

570| 命令 | 目的 |747| 命令 | 目的 |

571| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |748| :--------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

574| `claude agents --json` | 將即時工作階段列印為 JSON 陣列並結束：每個即時工作階段，加上仍在執行或被阻止的背景工作階段，即使其程序已結束。新增 `--all` 以同時包含已完成的背景工作階段。每個項目都有 `cwd`、`kind` 和 `startedAt`。背景項目也有 `id`（可與 `claude attach`/`logs`/`stop` 搭配使用）和 `state`：`working`、`blocked`、`done`、`failed` 或 `stopped` 之一。`pid` 和 `status` 僅在程序執行時出現，加上當 status 為 `waiting` 時的 `waitingFor`，其說明工作階段被阻止的原因，例如 `permission prompt` 或 `input needed`；`sessionId` 和 `name` 在設定時出現。互動項目您從未命名的會帶有預設 `name`，由其工作目錄的名稱加上兩個字符後綴組成，例如 `my-app-3f`。與 `--cwd <path>` 結合以篩選 |751| `claude agents --json` | 將工作階段列印為 JSON 陣列並結束。請參閱 [將工作階段列為 JSON](#list-sessions-as-json) |

580| `claude rm <id>` | 從清單中移除工作階段。如果沒有未提交的變更且沒有未推送到任何地方的提交，會移除 Claude 為工作階段建立的 worktree；否則會保留工作階段，命令會列印 worktree 路徑和原因，以便您解決並再次執行 `claude rm`。保留您自己建立的 worktree。對話記錄會保留在您的本機上，並可透過 `claude --resume` 繼續使用 |757| `claude rm <id>` | 從清單中移除工作階段，以及 Claude 為其建立的 worktree（當安全刪除時）；請參閱 [刪除工作階段會移除什麼](#what-deleting-a-session-removes)。對話記錄會保留在您的本機上，並可透過 `claude --resume` 繼續使用 |

581| `claude daemon status` | 列印 [supervisor](#the-supervisor-process)的狀態、版本、socket 目錄和 worker 計數 |758| `claude rm <id> --discard-unpushed <commit>@<worktree-id>` | 刪除因未推送提交而拒絕刪除的工作階段，捨棄 worktree 及其分支和提交。傳遞拒絕列印的確切值；請參閱 [刪除工作階段會移除什麼](#what-deleting-a-session-removes)。需要 v2.1.260 或更新版本 |

759| `claude rm <id> --force-remove-worktree <worktree-id>` | 刪除因 git 或 `WorktreeRemove` hook 無法移除其 worktree 而拒絕刪除的工作階段，無論如何刪除 worktree 目錄並在儲存庫中保留其分支。傳遞拒絕列印的確切值；請參閱 [刪除工作階段會移除什麼](#what-deleting-a-session-removes)。需要 v2.1.268 或更新版本 |

760| `claude daemon status` | 列印 [supervisor](#the-supervisor-process) 的狀態、版本、socket 目錄和 worker 計數 |

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

583 762

584<h2 id="how-background-sessions-are-hosted">763<h3 id="list-sessions-as-json">

585 背景工作階段如何被託管764 將工作階段列為 JSON

586</h2>

~~587~~

588agent view 中列出的每個工作階段都被視為背景工作階段，無論您目前是否連接到它。相比之下，直接執行 `claude` 啟動的工作階段與該終端相關聯，並在終端關閉時結束，除非您[將其發送到背景](#from-inside-a-session)。

~~589~~

590<h3 id="the-supervisor-process">

591 監督程序

592</h3>765</h3>

593 766

594背景工作階段由每個使用者的監督程序託管，與您的終端和 agent view 分開。監督程序在您第一次背景化工作階段或開啟 agent view 時自動啟動，您不直接管理它。767`claude agents --json` 將作用中的工作階段列印為 JSON 陣列並結束：每個即時工作階段，加上仍在執行或被阻止的背景工作階段，即使其程序已結束。新增 `--all` 以同時包含已完成的背景工作階段，並新增 `--cwd <path>` 以將清單限制為在該目錄下啟動的工作階段。

~~595~~

596當更新已替換或移除執行中的 Claude Code 程序啟動的二進位檔案時，該程序會從另一個已安裝的副本（例如已安裝的 `claude` 啟動器或磁碟上的最新版本）啟動監督程序。

~~597~~

598監督程序保持一個預熱的工作程序就緒，以便來自 agent view 或 `claude --bg` 的分派無需冷啟動的延遲即可開始。當您分派時，監督程序將預熱的工作程序分配給您的工作階段，將該工作階段的目錄、設定和認證應用於它，然後為下一次分派啟動替代程序。如果沒有可用的健康預熱工作程序，監督程序會改為啟動新程序。

~~599~~

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

601 768

602分派 shell 的 `PATH` 以相同方式應用於工作程序，因此工作階段執行的 shell 命令會找到您的終端所擁有的相同工具。在 v2.1.203 之前，背景工作階段保持啟動監督程序的 shell 的 `PATH`，因此自那時以來添加到您 `PATH` 的工具可能會遺失，最常見的是在 Windows 上。769每個項目都描述一個工作階段：

603 770

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

772| :----------------------- | :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ |

773| `cwd`、`kind`、`startedAt` | 一律 | 工作目錄、`interactive` 或 `background`，以及 Unix 毫秒為單位的開始時間 |

774| `id` | 背景工作階段 | 短 ID，可與 `claude attach`、`claude logs` 和 `claude stop` 搭配使用 |

775| `state` | 背景工作階段 | `working`、`blocked`、`done`、`failed` 或 `stopped` 之一。請參閱 [從指令碼讀取工作階段狀態](#read-session-state-from-a-script)，了解每個值的含義 |

776| `pid`、`status` | 程序執行時 | 程序 ID 和 `busy`、`waiting` 或 `idle` 之一 |

777| `waitingFor` | 當 `status` 為 `waiting` 時 | 工作階段被阻止的原因：`permission prompt` 表示需要核准、`input needed` 表示 Claude 或 MCP 伺服器的輸入請求、`sandbox request`、`worker request` 或 `dialog open` |

778| `sessionId`、`name` | 設定時 | `sessionId` 是完整的工作階段 UUID，可與 [`claude --resume`](/docs/zh-TW/sessions) 搭配使用。互動工作階段的 `name` 是其 [預設顯示名稱](/docs/zh-TW/sessions#name-your-sessions)，直到您命名工作階段或在其中接受計畫 |

605 779

606在您分派的 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。780<h3 id="read-session-state-from-a-script">

~~607~~ 781 從指令碼讀取工作階段狀態

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

~~609~~

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

611 783

612一旦工作階段完成並在未附加的情況下閒置約一小時，監督程序停止其程序以釋放資源。您使用 `Ctrl+T` [釘選](#organize-the-list)的工作階段不受此限制，在閒置時保持其程序執行。無論如何，文字記錄和狀態保留在磁碟上，下次您附加、查看或回覆已停止的工作階段時，監督程序從中斷的地方啟動新程序。當每個工作階段都完成且沒有終端連接時，監督程序本身退出，並在下次您需要它時再次啟動。784`claude agents --json` 是從 Claude Code 外部讀取工作階段狀態的支援方式，例如從狀態列、排程器或監督背景工作的另一個 Claude 工作階段。輪詢 `claude agents --json --all`，它會持續列出程序已結束的工作階段，並讀取每個項目的 `state`、`status` 和 `waitingFor`。

613 785

614工作階段本身在頂層啟動的背景工作會在其程序被停止、重新啟動或更新時交付，包括在 Windows 上。為該工作階段啟動的下一個程序會接收它們：786| `state` | 含義 |

787| :----------------- | :------------------------------------------------------------------------------------------------------- |

788| `working` | 正在執行一個回合，或工作階段在其自行驅動的工作步驟之間，例如 [`/loop`](/docs/zh-TW/scheduled-tasks) 反覆運算或等待 CI。`status` 會告訴您其程序現在是否為 `busy` |

789| `blocked` | 工作階段正在等待您：它提出的問題、權限或沙箱決定、只有您才能清除的錯誤（例如過期的登入），或如果您在沒有提示的情況下啟動它，則為其第一個提示。當等待是即時程序中的開啟提示時，`waitingFor` 會命名它 |

790| `done` | 最後一個回合完成了您要求的內容，工作階段已準備好接收您的下一個提示，無論其程序是否仍在執行 |

791| `failed`、`stopped` | 工作已因錯誤而結束，或工作階段已停止 |

615 792

616* 在此期間完成的背景 shell 命令會報告為已完成及其輸出793完成其回合並等待您下一個指令的工作階段讀取 `done`，而不是 `blocked`。`blocked` 一律表示工作階段在繼續之前需要您提供的內容。

617* 動態工作流程會從中斷的地方恢復

618* [背景子代理](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)會從其自己的文字記錄恢復

619 794

620自 v2.1.198 起，交付涵蓋所有三項。在 v2.1.198 之前，它只涵蓋 shell 命令和工作流程，因此背景子代理會與程序一起停止，並在下次喚醒時報告為失敗。795`~/.claude/jobs/<id>/` 下的檔案不是穩定的介面。工作階段或其他程式寫入 `state`、`detail`、`tempo` 或 `needs` 的值會在下次更新時被取代。

621 796

622其狀態僅存在於程序內部的工作會與它一起停止，而不是被交付。那是子代理啟動的 shell 命令，恢復的子代理可以再次啟動，以及執行中的[監視器](/docs/zh-TW/tools-reference#monitor-tool)，其事件流無法移動到另一個程序。797如果您想讓工作階段用自己的話報告進度，請讓它寫入自己的檔案，例如在 `$CLAUDE_JOB_DIR/tmp` 下，而不是編輯 `state.json`。

623 798

624刪除工作階段會停止它交付的所有內容。要讓所有工作階段的背景工作與程序一起停止而不是被交付，請將 [`CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF`](/docs/zh-TW/env-vars#variables) 環境變數設定為 `1`。799<h2 id="how-background-sessions-are-hosted">

800 背景工作階段如何被託管

801</h2>

625 802

626重新啟動的程序會找到[移入 worktree](#how-file-edits-are-isolated) 中途任務的工作階段的對話：當文字記錄不在工作階段啟動的位置時，Claude Code 也會在儲存庫的已註冊 worktrees 下查看。在 v2.1.207 之前，在其程序停止後從 agent view 重新開啟該工作階段可能會顯示只有其原始提示的空白對話，文字記錄仍完整保存在磁碟上；在 v2.1.207 或更新版本上再次開啟工作階段會恢復它。803Claude Code 將 agent view 中列出的每個工作階段視為背景工作階段，無論您目前是否連接到它。相比之下，直接執行 `claude` 啟動的工作階段與該終端相關聯，並在終端關閉時結束，除非您[將其發送到背景](#from-inside-a-session)。

627 804

628如果重新啟動的工作階段回來時只顯示其原始提示，因為 Claude Code 誤讀其文字記錄為空，對話文字記錄會被重命名為 `.orphaned-` 後綴，而不是被刪除，因此它會保留在您的機器上。805要檢查您在哪種工作階段中，請執行 [`/status`](/docs/zh-TW/commands)。`Session kind` 列在背景工作階段中顯示 `background job · attached` 或 `background job · unattended`（取決於是否連接了終端），在任何其他工作階段中顯示 `interactive`。

629 806

630按 `←` 留下的空白列，從未被給予提示，會在約五分鐘後被完全移除，以便列表自動清除。使用 `claude --bg` 啟動的工作階段和等待設定提示（例如信任對話）的工作階段不會以這種方式被移除。807<h3 id="the-supervisor-process">

808 監督程序

809</h3>

631 810

632當主機記憶體不足時，監督程序首先停止閒置的未釘選工作階段，只有在釋放任何資源時才停止閒置的釘選工作階段。811監督程序是一個背景服務，執行您的背景工作階段，使其在您關閉 agent view 或終端後繼續工作。Claude Code 在您第一次背景化工作階段或開啟 agent view 時啟動它，您不需要自己管理它。

633 812

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

635 814

636一旦新監督程序接管，它也會在短暫延遲後在背景中一次重新啟動幾個剩餘的閒置工作階段到新版本，該延遲讓在重新啟動期間連接的終端有時間先重新連接。正在工作、等待您的輸入或已連接終端的工作階段不會被中斷；它會在其程序下次重新啟動時移動到新版本。在 v2.1.206 之前，監督程序每分鐘只移動幾個閒置工作階段到新版本，因此工作階段在更新後可能會繼續執行舊版本一段時間。815* **工作中、暫停在權限提示或其他對話框上，或已連接**：程序保持執行。執行中的子代理、工作流程或監視器計為工作中。

816* **已完成或等待您的下一條訊息，且未連接約一小時**：監督程序停止程序以釋放資源。通過提出問題結束其輪次的工作階段計為等待您的下一條訊息。對話保存在磁碟上，下次您連接或回覆時，工作階段從中斷的地方恢復。使用 `Ctrl+T` 釘選工作階段以保持其程序執行。

817* **在監督程序執行時意外退出**：監督程序重新啟動程序。使用 `←` 或 `/background` 結束您背景化的工作階段（例如使用 `kill`）會將其標記為已停止而不是重新啟動。對於以關閉結束的工作階段，請參閱[工作階段在關閉後顯示為失敗或已停止](#sessions-show-as-failed-after-shutdown)。

818* **自動更新後**：監督程序重新啟動自身到新版本，並在背景中移動閒置工作階段。正在工作、等待您或已連接的工作階段不會被中斷。

637 819

638這些重新啟動只會將工作階段移動到較新版本。執行比工作階段程序啟動時的版本更舊的 Claude Code 版本的監督程序會單獨保留該程序；工作階段會繼續執行較新版本，直到較新的監督程序接管。820當工作階段的程序停止或重新啟動時，Claude 在其中啟動的背景 shell 命令、動態工作流程和背景子代理會轉移到其下一個程序；執行中的監視器和子代理啟動的 shell 命令會隨程序停止。刪除工作階段會停止它轉移的所有內容。要讓所有內容隨程序停止而不是轉移，請將 [`CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF`](/docs/zh-TW/env-vars#variables) 設定為 `1`。

639 821

640在監督程序重新啟動工作階段時執行 `claude attach`，無論是為了更新、停滯或遷移，會等待替換程序而不是失敗。狀態行（例如 `Agent is updating to the new Claude Code…`）會命名它正在等待的內容並計算經過的秒數，命令會在工作階段準備好時立即連接。大約 60 秒後，它會停止等待並報告錯誤。在 v2.1.205 之前，`claude attach` 在幾秒後停止重試並列印錯誤，而工作階段仍在重新啟動。822監督程序及其工作階段使用與您的互動工作階段相同的儲存認證進行身份驗證。對於哪些設定和 shell 變數到達工作階段（包括 `PATH`），請參閱[設定和提供者](#settings-and-provider)。對於閘道端點，請參閱 [LLM 閘道](#llm-gateway)。

641 823

642<h3 id="where-state-is-stored">824<h3 id="where-state-is-stored">

643 狀態存儲位置825 狀態存儲位置

644</h3>826</h3>

645 827

646工作階段狀態存儲在您的 Claude Code 配置目錄下。如果您設定 [`CLAUDE_CONFIG_DIR`](/docs/zh-TW/env-vars)，監督程序改用該目錄而不是 `~/.claude`，並作為具有其自己工作階段的單獨實例執行。828工作階段狀態存儲在您的 Claude Code 設定目錄下。如果您設定 [`CLAUDE_CONFIG_DIR`](/docs/zh-TW/env-vars)，監督程序改用該目錄而不是 `~/.claude`，並作為具有其自己工作階段的單獨實例執行。

647 829

648| 路徑 | 內容 |830| 路徑 | 內容 |

649| :------------------------------- | :------------------------------- |831| :------------------------------- | :--------------------------------------------------------------------------------------------------- |

654 836

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

656 838

658 840

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

660 842

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

~~662~~

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

664 844

665<h3 id="turn-off-agent-view">845<h3 id="turn-off-agent-view">

666 關閉 agent view846 關閉 agent view

667</h3>847</h3>

668 848

669要完全關閉背景代理和 agent view，將 `disableAgentView` [設定](/docs/zh-TW/settings)設為 `true` 或設定 `CLAUDE_CODE_DISABLE_AGENT_VIEW` 環境變數。管理員可以通過[受管設定](/docs/zh-TW/permissions#managed-settings)強制執行此操作。849要完全關閉背景代理和 agent view，將 `disableAgentView` [設定](/docs/zh-TW/settings)設為 `true` 或設定 `CLAUDE_CODE_DISABLE_AGENT_VIEW` 環境變數。管理員可以通過[受管設定](/docs/zh-TW/managed-settings)強制執行此操作。

670 850

671<h2 id="troubleshooting">851<h2 id="troubleshooting">

672 故障排除852 故障排除

690 背景化顯示 `Background this session?` 對話870 背景化顯示 `Background this session?` 對話

691</h3>871</h3>

692 872

693如果按 `←` 將當前工作階段放在背景中顯示 `Background this session?` 對話，工作階段有進行中的工作無法轉移到背景工作階段，例如執行中的 [monitor](/docs/zh-TW/tools-reference#monitor-tool)，Claude Code 不會無聲地停止它。對話命名將被停止的工作，並分別計算轉移的任務。執行 `/tasks` 以查看正在執行的內容，然後確認以無論如何背景化或選擇 `Stay` 讓工作先完成。請參閱[從工作階段內部](#from-inside-a-session)以了解哪些任務類型轉移，哪些被停止。873如果按 `←` 將當前工作階段放在背景中，Claude Code 顯示 `Background this session?` 對話，工作階段有進行中的工作無法轉移到背景工作階段、可能會停止、重新啟動或無人看管地執行，Claude Code 在執行任何操作之前會詢問：

874

875* **無法移動的工作**：工作階段有無法移動到背景工作階段的工作，例如執行中的 [monitor](/docs/zh-TW/tools-reference#monitor-tool)。對話命名 Claude Code 會停止的工作，並分別計算轉移的任務。

876* **具有執行中子代理的工作流程**：[動態工作流程](/docs/zh-TW/workflows)仍有子代理執行。工作流程本身會轉移，但其執行中的子代理會從頭開始重新啟動，對話會說明有多少個。

877* **自動成品回覆**：Claude 正在[自行回覆成品上的評論](/docs/zh-TW/artifacts#let-claude-reply-to-comments-on-its-own)。這些回覆會在背景工作階段中繼續，對話會說明。

878

879執行 `/tasks` 以查看正在執行的所有內容，然後確認以無論如何背景化或選擇 `Stay` 讓工作先完成。請參閱[背景化時轉移的內容](#what-carries-over-when-you-background)以了解哪些工作類型轉移，哪些 Claude Code 停止。

694 880

695<h3 id="prompt-rejected-as-too-short">881<h3 id="prompt-rejected-as-too-short">

696 提示被拒絕為過短882 提示被拒絕為過短

699分派輸入期望任務描述，而不是對話開場白。短於四個字元的提示會被拒絕並顯示 `Too short` 提示，以便隨意按鍵不會啟動工作階段。描述您希望工作階段執行的操作，例如 `investigate the flaky checkout test`。885分派輸入期望任務描述，而不是對話開場白。短於四個字元的提示會被拒絕並顯示 `Too short` 提示，以便隨意按鍵不會啟動工作階段。描述您希望工作階段執行的操作，例如 `investigate the flaky checkout test`。

700 886

701<h3 id="sessions-show-as-failed-after-shutdown">887<h3 id="sessions-show-as-failed-after-shutdown">

702 工作階段在關閉後顯示為失敗888 工作階段在關閉後顯示為失敗或停止

703</h3>889</h3>

704 890

705關閉或重新啟動您的機器會停止執行中的背景工作階段，因此當您下次開啟 agent view 時，它們會顯示為失敗。附加、查看或回覆任何工作階段，工作階段會從中斷的地方重新啟動。891關閉或重新啟動您的機器會停止執行中的背景工作階段。等待您輸入的工作階段在您回來時會保留在 `Needs input` 下。對於任何其他執行中的工作階段，agent view 顯示的內容取決於它上次取得進度的時間有多久：

892

893* 在 48 小時內，工作階段顯示為失敗。附加或回覆它，它會從中斷的地方重新啟動。

894* 超過 48 小時，例如機器關閉數天後，工作階段顯示為停止，並顯示 `ended while the background service was off`。在該列上按 `Enter`，頁腳會顯示 `Press enter again to resume this session (it ended while the background service was off), or ctrl+x to delete it.` 在同一列上再次按 `Enter` 以恢復其已儲存的對話。回覆或 `claude attach <id>` 會在沒有該頁腳提示的情況下恢復它。

706 895

707睡眠單獨不會導致這種情況。工作階段在睡眠期間會被保留，監督程序在喚醒時會重新連接到它們。896當[文字記錄清理](/docs/zh-TW/settings-reference#cleanupperioddays)已移除停止工作階段的已儲存對話時，Claude Code 拒絕開啟該列：訊息說沒有要恢復的內容。`claude rm <id>` 刪除該列，除了[保留的情況](#what-deleting-a-session-removes)中描述的情況外，`claude respawn <id>` 會再次執行其原始提示。請參閱[此工作階段的已儲存對話不再在磁碟上](/docs/zh-TW/errors#this-sessions-saved-conversation-is-no-longer-on-disk)。

897

898睡眠單獨不會停止工作階段。工作階段在睡眠期間會被保留，監督程序在喚醒時會重新連接到它們。

708 899

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

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

711</h3>902</h3>

712 903

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

905

906* 您恢復對話的終端，例如使用 `claude --resume` 或 `/resume`：該列顯示 `Open in a terminal`，並提示在那裡繼續，開啟該列會顯示 `Can't open — this session is running in another terminal`。在該終端中繼續，或退出它並再次開啟該列。

907* 另一個非互動式 Claude Code 程序，例如同一對話的背景工作階段程序尚未退出：開啟該列會顯示 `This conversation is already open in another running Claude session`。使用該程序，或等待它退出並再次開啟該列。

908

909Claude Code 會儲存您在拒絕嘗試時輸入的回覆，並在工作階段下次啟動時發送它。

910

911<h3 id="opening-a-session-says-it-has-no-saved-transcript">

912 開啟工作階段時顯示它沒有已儲存的文字記錄

913</h3>

914

915停止工作階段[從另一個對話背景化](#from-inside-a-session)並在其第一個回覆完成之前停止，沒有要恢復的內容：在該第一個回覆完成之前，對話仍然只存在於它背景化的工作階段中。`claude attach` 拒絕開啟它，顯示 `This session has no saved transcript`。

916

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

714 918

715在 v2.1.203 之前，此狀態無論如何都會啟動第二個程序。該程序以 `currently running as a background agent` 錯誤退出，該列顯示為失敗。919原始對話完整無缺；使用 `claude --resume` 恢復它或繼續在其中工作。請參閱[錯誤參考](/docs/zh-TW/errors#this-session-has-no-saved-transcript)以取得詳細資訊。

920

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

922 終端主機已死亡或工作階段停止回應

923</h3>

924

925[監督程序](#the-supervisor-process)在其自己的主機程序中執行每個背景工作階段的終端。當該程序死亡或停止回應時，Claude Code 會顯示原因並提供重新啟動；在兩種情況下，對話都會被儲存，重新啟動會恢復它。[錯誤參考](/docs/zh-TW/errors#terminal-host-process-died)引用完整訊息。

926

927Claude Code 永遠不會重新啟動執行[shell 命令](#run-a-shell-command)的列，來自 `Enter` 或來自 `claude attach`，因為那樣會再次執行命令；該列的訊息和 `claude attach` 都說命令不會再次執行。

928

929<h4 id="terminal-host-died">

930 終端主機已死亡

931</h4>

932

933在 Linux 和 WSL 上，監督程序每隔幾秒檢查每個主機程序，無論您是否開啟工作階段，並在程序已退出但其與監督程序的連接從未關閉時將工作階段標記為失敗。

934

935* 在 agent view 中，該列顯示 `terminal host process died — press Enter to restart`。在它上面按 `Enter`，Claude Code 會在新的主機程序上重新啟動工作階段。

936* 從 shell，`claude attach <id>` 重新啟動已標記為失敗的工作階段。否則它會報告原因並退出，告訴您執行 `claude attach <id>`。

937

938<h4 id="session-isn’t-responding">

939 工作階段沒有回應

940</h4>

941

942當監督程序接受開啟但約十秒內沒有輸出到達時，Claude Code 會結束嘗試並提供重新啟動。僅僅停滯的工作階段，例如跨機器睡眠，不會達到此提供：監督程序[在開啟時自行重新啟動](#read-session-state)。

943

944* 在 agent view 中，頁腳顯示 `Press enter again to restart this session — it isn't responding (its conversation is saved and resumes).` 在同一列上再次按 `Enter`，Claude Code 會停止無回應的程序並重新啟動工作階段；它在沒有第二次按下的情況下不會停止任何內容。

945* 從 shell，`claude attach <id>` 報告原因並退出，告訴您執行 `claude stop <id>`，然後 `claude attach <id>`。

716 946

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

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

719</h3>949</h3>

720 950

721自 v2.1.199 起，當背景工作階段的程序在完成啟動前退出，且主機記憶體不足時，該列的狀態會命名退出並新增 `possibly low memory — free some up and retry`。較早的版本只顯示此失敗的裸退出原因。951當背景工作階段的程序在完成啟動前退出，且主機記憶體不足時，該列的狀態會命名退出並新增 `possibly low memory — free some up and retry`。

722 952

723該註記是一個假設，而不是確認的原因。Claude Code 只在程序無聲退出時新增它，沒有寫入錯誤，也沒有被信號停止，且主機在該時刻報告記憶體不足。當程序在退出前確實寫入了錯誤時，該列會改為顯示該錯誤。953該註記是一個假設，而不是確認的原因。Claude Code 只在程序無聲退出時新增它，沒有寫入錯誤，也沒有被信號停止，且主機在該時刻報告記憶體不足。當程序在退出前確實寫入了錯誤時，該列會改為顯示該錯誤。

724 954

725釋放機器上的記憶體，然後附加、查看或回覆該列，監督程序會為工作階段啟動新的程序。當記憶體保持不足時，監督程序也會[停止閒置工作階段](#the-supervisor-process)以自行釋放資源。955釋放機器上的記憶體，然後附加或回覆該列，監督程序會為工作階段啟動新的程序。當記憶體保持不足時，監督程序也會[停止閒置工作階段](#the-supervisor-process)以自行釋放資源，如果停止其他工作階段沒有釋放任何內容，也會停止閒置釘選工作階段。

726 956

727<h3 id="agent-view-says-the-background-service-did-not-respond">957<h3 id="agent-view-says-the-background-service-did-not-respond">

728 Agent view 表示背景服務未回應958 Agent view 表示背景服務未回應

738 968

739啟動但無法接受連接的監督程序會自行退出並釋放其鎖定，因此下一個 `claude agents` 會啟動新的程序，無需此手動停止。上述步驟適用於執行中的監督程序停止回應的情況。969啟動但無法接受連接的監督程序會自行退出並釋放其鎖定，因此下一個 `claude agents` 會啟動新的程序，無需此手動停止。上述步驟適用於執行中的監督程序停止回應的情況。

740 970

971如果命令改為退出，說記錄的程序無法驗證為監督程序，請檢查報告的程序 ID：如果它是您擁有的監督程序，自行停止它，然後刪除 `~/.claude/daemon.lock`，以便下一個 `claude agents` 啟動新的程序。

972

741在 Windows 上，如果監督程序未回應停止請求，該命令會列印其程序 ID。使用 `taskkill /PID <pid>` 結束該程序以完成復原。當您傳遞 `--keep-workers` 時，背景工作階段仍會被保留。973在 Windows 上，如果監督程序未回應停止請求，該命令會列印其程序 ID。使用 `taskkill /PID <pid>` 結束該程序以完成復原。當您傳遞 `--keep-workers` 時，背景工作階段仍會被保留。

742 974

743<h3 id="dispatch-fails-with-could-not-resolve-authentication-method">975<h3 id="dispatch-fails-with-could-not-resolve-authentication-method">

744 背景分派失敗，出現 `Could not resolve authentication method`976 背景分派失敗，出現 `Could not resolve authentication method`

745</h3>977</h3>

746 978

747如果背景分派失敗，出現 `Could not resolve authentication method`，而互動式工作階段正常驗證，接收分派的背景工作程序未取得認證。監督程序在指派[預先準備的背景工作程序](#the-supervisor-process)時提供新的認證快照，因此此錯誤表示監督程序本身沒有可用的已儲存認證。確認您已執行 `/login` 或設定 API 金鑰，然後停止監督程序：979如果背景分派失敗，出現 `Could not resolve authentication method`，而互動式工作階段正常驗證，接收分派的背景工作程序未取得認證。背景工作階段從[監督程序](#the-supervisor-process)取得其認證，因此此錯誤表示監督程序本身沒有可用的已儲存認證。確認您已執行 `/login` 或設定 API 金鑰，然後停止監督程序：

748 980

749```bash theme={null}981```bash theme={null}

750claude daemon stop --any --keep-workers982claude daemon stop --any --keep-workers

766 背景工作階段無法在 macOS 上連接到本機網路主機998 背景工作階段無法在 macOS 上連接到本機網路主機

767</h3>999</h3>

768 1000

769在 macOS 15 及更新版本上，系統會阻止程序連接到您本機網路上的裝置，直到您授予本機網路權限。在 v2.1.198 之前，背景工作階段主機從未請求該權限，因此針對 LAN 位址的命令失敗，出現 `connect: no route to host`，即使相同的命令在前景終端中有效。自 v2.1.198 起，背景工作階段中連接到本機網路位址的第一個命令會觸發 Claude Code 的 macOS 本機網路權限提示。授予一次，這些命令就能像在前景終端中一樣連接到 LAN 主機。1001在 macOS 15 及更新版本上，系統會阻止程序連接到您本機網路上的裝置，直到您授予本機網路權限，因此針對 LAN 位址的命令可能會在背景工作階段中失敗，出現 `connect: no route to host`，即使相同的命令在前景終端中有效。背景工作階段中連接到本機網路位址的第一個命令會觸發 Claude Code 的 macOS 本機網路權限提示。授予一次，這些命令就能像在前景終端中一樣連接到 LAN 主機。

770 1002

771<h3 id="a-session-is-slow-to-respond-after-attaching">1003<h3 id="a-session-is-slow-to-respond-after-attaching">

772 工作階段在附加後響應緩慢1004 工作階段在附加後響應緩慢

773</h3>1005</h3>

774 1006

775一旦工作階段完成並在未附加的情況下閒置約一小時，監督程序會停止其程序以釋放資源。附加會啟動從中斷的地方開始的新程序，並立即切換到工作階段，而程序重新啟動。正在工作、等待您或[釘選](#organize-the-list)的工作階段不會以這種方式停止，因此使用 `Ctrl+T` 釘選工作階段以保持其回應性。1007當完成或等待您下一個訊息的工作階段在未附加的情況下閒置約一小時時，監督程序會停止其程序以釋放資源。附加會啟動從中斷的地方開始的新程序，並在程序重新啟動時立即切換到工作階段。正在工作、暫停在權限提示或其他對話上，或[釘選](#organize-the-list)的工作階段不會以這種方式停止，因此使用 `Ctrl+T` 釘選工作階段以保持其回應性。

776 1008

777當程序啟動時，工作階段文字記錄的最後一個螢幕會顯示，下方有 `Session is starting` 註記，當工作階段準備好時，即時工作階段會立即取代它。1009當程序啟動時，Claude Code 會顯示工作階段文字記錄的尾部，格式化為即時工作階段呈現的方式，包含 markdown、突出顯示的程式碼區塊和工具呼叫作為暗淡列，上方有暗淡提示區域和 `Session is starting` 註記。即時工作階段在準備好時立即取代它。

778 1010

779<h3 id="claude/worktrees/-is-filling-up">1011<h3 id="claude/worktrees/-is-filling-up">

780 `.claude/worktrees/` 正在填滿1012 `.claude/worktrees/` 正在填滿

781</h3>1013</h3>

782 1014

783在 agent view 中刪除工作階段會移除 Claude 為其建立的 worktree，而無法安全移除的 worktree 會[保留其工作階段列](#organize-the-list)，以便不會被孤立。`claude rm` 會保留具有未提交變更的 worktree，並列印保留的路徑。在專案目錄中使用 `git worktree list` 列出剩餘條目，並使用 `git worktree remove <path>` 移除每個。請參閱[清理 worktrees](/docs/zh-TW/worktrees#clean-up-worktrees)。1015在 agent view 中刪除工作階段會移除 Claude 為其建立的 worktree，但[某些刪除會保留 worktree 或在磁碟上留下其目錄](#what-deleting-a-session-removes)，因此剩餘目錄可能會累積。Git 不再識別的目錄不會出現在 `git worktree list` 中，因此請手動移除這些目錄。

1016

1017在專案目錄中使用 `git worktree list` 列出剩餘條目，並使用 `git worktree remove <path>` 移除每個。請參閱[清理 worktrees](/docs/zh-TW/worktrees#clean-up-worktrees)。

784 1018

785<h2 id="limitations">1019<h2 id="limitations">

786 限制1020 限制

790 1024

791* **速率限制適用**：背景工作階段與互動工作階段一樣消耗您的訂閱使用量，因此並行執行十個代理的使用配額速度快十倍。1025* **速率限制適用**：背景工作階段與互動工作階段一樣消耗您的訂閱使用量，因此並行執行十個代理的使用配額速度快十倍。

792* **工作階段是本地的**：背景工作階段在您的機器上執行。它們在睡眠時保留，但如果機器關閉則停止。1026* **工作階段是本地的**：背景工作階段在您的機器上執行。它們在睡眠時保留，但如果機器關閉則停止。

793* **Claude 建立的 worktrees 在 agent view 中隨工作階段刪除**：在刪除在其自己的 worktree 中編輯檔案的工作階段之前，提交變更。具有未推送任何地方的提交的 worktree 會與工作階段一起保留。`claude rm` 也會保留具有未提交變更的 worktree 與其工作階段一起，而您自己建立的 worktree 會保留在原位。1027* **Claude 建立的 worktrees 在 agent view 中隨工作階段刪除**：在刪除在其自己的 worktree 中編輯檔案的工作階段之前，提交變更。[某些刪除會改為保留 worktree](#what-deleting-a-session-removes)。

794 1028

795<h2 id="related-resources">1029<h2 id="related-resources">

796 相關資源1030 相關資源

797</h2>1031</h2>

798 1032

799如需了解在平行中執行 Claude 的其他方式，請參閱：1033如需了解在平行中執行 Claude 的其他方式，以及在您執行的工作階段之間傳遞發現結果，請參閱：

800 1034

801* [在平行中執行代理](/docs/zh-TW/agents)：比較 agent view 與 subagents、agent teams 和 worktrees1035* [在平行中執行代理](/docs/zh-TW/agents)：比較 agent view 與 subagents、agent teams 和 worktrees

1036* [跨工作階段傳訊](/docs/zh-TW/cross-session-messaging)：讓您的工作階段相互傳遞發現結果

802* [Agent teams](/docs/zh-TW/agent-teams)：協調相互傳遞訊息的多個工作階段1037* [Agent teams](/docs/zh-TW/agent-teams)：協調相互傳遞訊息的多個工作階段

803* [Claude Code on the web](/docs/zh-TW/claude-code-on-the-web)：在受管雲環境中執行工作階段，而不是本地執行1038* [Claude Code on the web](/docs/zh-TW/claude-code-on-the-web)：在受管雲環境中執行工作階段，而不是本地執行

804 1039

809Agent view 在研究預覽期間發展迅速。如果您使用較舊的 Claude Code 版本，本頁上的某些行為可能會有所不同；特別是，`claude agents` 會以 `unknown option` 錯誤拒絕它尚不支援的旗標。下表列出了每個旗標和行為何時新增。1044Agent view 在研究預覽期間發展迅速。如果您使用較舊的 Claude Code 版本，本頁上的某些行為可能會有所不同；特別是，`claude agents` 會以 `unknown option` 錯誤拒絕它尚不支援的旗標。下表列出了每個旗標和行為何時新增。

810 1045

811| 版本 | 變更 |1046| 版本 | 變更 |

812| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1047| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1048| v2.1.268 | 當[刪除因 git 或您的 `WorktreeRemove` hook 無法移除 worktree 而被拒絕](#what-deleting-a-session-removes)時，訊息會命名原因，包括 hook 如何結束及其 stderr 的開始。對於位於儲存庫的 `.claude/worktrees/` 下的連結 worktree，沒有對追蹤檔案的未提交變更、其內沒有巢狀儲存庫，且沒有其他工作階段的記錄命名它，再次刪除工作階段會從 agent view 或使用 `claude rm <id> --force-remove-worktree <worktree-id>` 移除目錄。在此版本之前，列只顯示 `worktree could not be removed (WorktreeRemove hook failed)` 或 git 的錯誤，hook 的 stderr 只進入偵錯日誌，再次刪除被以相同方式拒絕。 |

1049| v2.1.260 | 當您[背景化工作階段](#from-inside-a-session)時，您的其他工作階段的[代理清單](/docs/zh-TW/cross-session-messaging#see-which-sessions-claude-can-reach)會顯示對話一次，作為其背景工作階段，它們對它的訊息不再到達您移動它的終端。在此版本之前，該終端可能會在對話名稱下列為第二個互動工作階段，在移動前已訊息對話的工作階段會繼續傳遞到該終端。 |

1050| v2.1.260 | 當[刪除因未推送的提交而被拒絕](#what-deleting-a-session-removes)時，訊息會命名 worktree 的分支及有多少提交未推送，再次刪除工作階段會丟棄 worktree 及其提交。在此版本之前，拒絕只說 `worktree has commits that are not pushed anywhere`，再次刪除被以相同方式拒絕，刪除工作階段需要推送提交或手動移除 worktree。 |

1051| v2.1.257 | `←` [在 `/btw` 覆蓋層開啟時從附加的工作階段分離](#attach-to-a-session)，即使在中途回答，覆蓋層會在您下次附加時重新開啟。在此版本之前，覆蓋層開啟時 `←` 不會分離。 |

1052| v2.1.257 | 當您執行 [`claude --resume <session-id> --bg`](#from-your-shell) 時，Claude Code 會在其自己的 ID 下繼續該工作階段，或在新 ID 下啟動副本並列印 `note:` 行說明原因。`--continue`、裸露的 `--resume` 和帶有名稱或路徑的 `--resume` 會啟動具有相同備註的副本。在此版本之前，`--resume` 與 `--bg` 總是在新 ID 下啟動副本且不說任何內容。 |

1053| v2.1.257 | 當您從使用 `←` 開啟的 agent view 分派工作階段時，Claude Code 會在[目標目錄透過 `permissions.defaultMode` 配置的權限模式](#permission-mode)中啟動它。當目錄未設定一個時，您來自的工作階段的權限模式適用。在此版本之前，分派的工作階段總是在您來自的工作階段的權限模式中啟動，覆蓋它。 |

1054| v2.1.257 | Agent view 中的 `Ctrl+S`、`Ctrl+T` 和 `Ctrl+G` [遵循您的 `keybindings.json`](#keyboard-shortcuts)：`Ctrl+S` 和 `Ctrl+T` 透過 `Agents` 內容的 `agents:switchView` 和 `agents:togglePin` 動作，以及 `Ctrl+G` 透過 `Chat` 內容的 `chat:externalEditor` 繫結。在此版本之前，agent view 忽略 `keybindings.json`，這些鍵是固定的。 |

1055| v2.1.257 | 啟動[背景服務](#the-supervisor-process)會從兩個失敗原因恢復。在 macOS npm 安裝上，自我更新期間的啟動[等待安裝](/docs/zh-TW/errors#eacces-when-starting-a-background-session)，而不是執行 npm 在取代二進位檔時放下的預留位置。在 Windows 上，在機器上次啟動前寫入的過時 `daemon.lock`，或其記錄的程序 ID 現在屬於不同程序的，會被取代。在此版本之前，macOS 啟動在安裝視窗期間失敗，出現 `Error: claude native binary not installed.`，Windows 鎖定使每次啟動都失敗，出現 [`exited before it became reachable`](/docs/zh-TW/errors#background-service-exited-before-it-became-reachable)，直到您刪除 `~/.claude/daemon.lock`。 |

1056| v2.1.257 | 當您在另一個 Claude Code 程序下載 npm 更新時開啟或分派背景工作階段時，Claude Code [保持等待最多兩分鐘](/docs/zh-TW/errors#eacces-when-starting-a-background-session)，同時安裝執行，然後失敗，說 `Claude Code is being updated by npm on this machine`。在此版本之前，等待在十秒時停止，所以開啟在下載仍在執行時失敗，出現 `Couldn't start the background service`。 |

1057| v2.1.257 | 持有[跨工作階段訊息](/docs/zh-TW/cross-session-messaging#control-inbound-messages)等待您批准的背景工作階段在其 `Needs input` 列上顯示 `approve message from`，帶有寄件者的地址和寄件者聲稱的名稱。在此版本之前，列移到 `Needs input` 但保留其先前的文字，所以 `claude agents` 中沒有任何內容命名等待的訊息或其寄件者。 |

1058| v2.1.257 | 在開啟的背景工作階段內使用 `Ctrl+S` 隱藏的提示[與工作階段一起保留](#what-persists-across-restarts)，所以 `Ctrl+S` 在工作階段的程序停止並再次啟動後恢復它。在此版本之前，隱藏只存在於執行中的程序中，當工作階段閒置足夠長的時間以至於其程序停止時，或當它停止然後重新開啟時會遺失。 |

1059| v2.1.251 | 在尚未[移入 worktree](#how-file-edits-are-isolated) 的背景工作階段中，Claude 和它生成的子代理可以編輯連結 git worktree 內的檔案。 |

1060| v2.1.251 | Claude Code 轉發在您分派的 shell 中匯出的雲端提供者閘道，例如 `ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_BEDROCK_BASE_URL` 及其驗證繞過旗標，到[工作階段的工作程序](#llm-gateway)，條件與 `ANTHROPIC_BASE_URL` 相同。在此版本之前，如果您只透過這樣的閘道背景化或分派，工作階段進行的每個請求都失敗，因為端點和旗標從其環境中被丟棄。 |

1061| v2.1.251 | 當背景工作階段在另一個 Claude Code 程序重新整理[外掛程式市場](/docs/zh-TW/plugin-marketplaces)時啟動，例如執行[市場自動更新](/docs/zh-TW/discover-plugins#configure-auto-updates)的同級工作階段，Claude Code 保持該市場的外掛程式可用。在此版本之前，這樣的工作階段可能在沒有該市場的任何技能、代理、hook 和 MCP 伺服器的情況下啟動，並在其整個執行期間保持這樣。 |

1062| v2.1.248 | [分派輸入](#keyboard-shortcuts)中的 `Shift+Enter` 插入換行符，符合主提示，`Ctrl+Enter` 在 `?` 覆蓋層列出 `ctrl+enter to start and open` 的終端中立即分派並附加。在此版本之前，`Shift+Enter` 分派並附加。 |

1063| v2.1.248 | [刪除工作階段](#what-deleting-a-session-removes)在 worktree 的提交已在您的 `origin` 遠端預設分支的本機副本上且您的主簽出已簽出該分支時成功；在此版本之前，刪除被拒絕，出現 `has commits that are not pushed anywhere`。 |

1064| v2.1.248 | 使用 `←` 或 `/background` 背景化的工作階段在執行時持有其 worktree 上的 [`git worktree lock`](/docs/zh-TW/worktrees#clean-up-subagent-and-background-session-worktrees)；在此版本之前，背景化釋放鎖定，清理或 `git worktree remove` 可以在執行中的工作階段下移除 worktree。 |

1065| v2.1.248 | 未等待您輸入且在其最後活動超過 48 小時後被發現已死亡的背景工作階段，例如在機器關閉數天後，[顯示為已停止](#sessions-show-as-failed-after-shutdown)，出現 `ended while the background service was off`，`Enter` 在它上面會在恢復其已保存的對話前詢問。在此版本之前，這樣的工作階段重新出現為新鮮失敗，排序到列表的頂部，單一 `Enter` 將數週前的對話拉入前景。 |

1066| v2.1.248 | 開啟已停止列，其對話[您在另一個終端恢復](#opening-a-session-says-the-conversation-is-already-open)被拒絕，出現 `Can't open — this session is running in another terminal`，列顯示 `Open in a terminal` 而不是在 `Working` 下顯示。在此版本之前，開啟列啟動第二個程序寫入相同的對話。 |

1067| v2.1.248 | 等待權限決定的背景工作階段，同時 `PermissionRequest` 或 `PreToolUse` hook 列印了無效答案[在其列上命名 hook 事件和架構錯誤](#peek-and-reply)。在此版本之前，列只顯示待決請求。 |

1068| v2.1.248 | 在 Windows 上，`claude agents` 在早期程序留下 win32-input-mode 的終端標籤中啟動時回應鍵盤。在此版本之前，Claude Code 沒有解碼這樣的標籤傳送的關鍵記錄。 |

1069| v2.1.247 | 在 Linux 和 WSL 上，[其終端主機程序已死亡](#the-terminal-host-died-or-the-session-stopped-responding)的工作階段在數秒內失敗，出現原因。沒有輸出的開啟在約十秒後結束，出現重新啟動提供，`Enter` 在列上使用其對話重新啟動工作階段；`claude attach <id>` 報告原因並退出。在此版本之前，開啟這樣的工作階段無限期地顯示 `opening… · esc to cancel`，`claude attach <id>` 等待而不報告錯誤。 |

1070| v2.1.246 | 在 npm 安裝上，當[背景服務](#the-supervisor-process)在 `npm install -g @anthropic-ai/claude-code` 取代二進位檔時無法啟動時，Claude Code 等待最多十秒以完成安裝並重試，然後報告 [`EACCES: permission denied`](/docs/zh-TW/errors#eacces-when-starting-a-background-session)。 |

1071| v2.1.246 | 當[背景服務](#the-supervisor-process)程序在列印錯誤後死亡時，Claude Code 報告失敗並[引用服務的第一個錯誤行](/docs/zh-TW/errors#background-service-exited-before-it-became-reachable)。 |

1072| v2.1.246 | 如果您的機器在[背景服務](#the-supervisor-process)啟動時進入睡眠，Claude Code 會重試啟動一次，而不是失敗。 |

1073| v2.1.246 | Claude Code 等待約兩分鐘，而不是 45 秒，以便新啟動的[背景服務](#the-supervisor-process)活著但接受連接速度緩慢。 |

1074| v2.1.246 | [背景服務](#the-supervisor-process)從您的主目錄啟動，所以在 macOS 和 Linux 上已刪除或移動的啟動目錄不再阻止啟動。 |

1075| v2.1.246 | `/fork` [複製完整對話](#copy-the-session-with-%2Ffork)，來自本身作為副本啟動且未記錄新提示的工作階段：您附加到的 `/fork` 副本、在 `←` 或 `/background` 將其移到背景後重新附加的工作階段，或使用 `claude --resume <id> --fork-session` 啟動的工作階段。在此版本之前，如果您在這樣的工作階段中在傳送新提示前執行 `/fork`，Claude Code 列印正常確認但使用空對話啟動副本。使用 `←` 或 `/background` 將這樣的工作階段移到背景以相同方式遺失對話。 |

1076| v2.1.246 | 當您開啟您剛分派的工作階段，同時其工作程序仍在啟動時，例如按 `Enter` 在其列上，Claude Code 等待程序然後附加。在此版本之前，如果您在程序仍在啟動時按 `Enter`，Claude Code 可能會停止工作階段，出現 [`Session <id> was stopped while the respawn was in flight`](/docs/zh-TW/errors#session-was-stopped-while-the-respawn-was-in-flight)。 |

1077| v2.1.246 | 當您[背景化](#from-inside-a-session)命名的工作階段時，Claude Code 列出它一次，當您再次背景化相同的對話時，它對新列的名稱進行編號，例如 `my-session (2)`，現有列保留其名稱。在此版本之前，您按 `←` 的終端可能在 `claude agents --json` 中作為同一名稱下的第二個工作階段出現，如果您再次背景化相同的對話，Claude Code 在相同名稱下新增另一列。 |

1078| v2.1.239 | 使用 [vim 編輯器模式](/docs/zh-TW/interactive-mode#vim-editor-mode)開啟，在 agent view 的輸入中按 `Esc` 從 INSERT 切換到 NORMAL 模式並保留您的文字，符合主提示；在 NORMAL 模式下，輸入中仍有文字，按 `Esc` 清除它，在空輸入上按 `Esc` 退出，如 [`Esc` 快捷鍵](#keyboard-shortcuts)描述。在此版本之前，`Esc` 清除輸入。 |

1079| v2.1.233 | 對於連結到 GitLab 合併請求的工作階段，Claude Code 以 GitLab 的 `!1234` 參考語法寫入列的標籤。您也可以將合併請求的 URL 貼到[分派輸入](#filter-sessions)中以選擇該工作階段。在此版本之前，標籤呈現為 `#1234`，貼上的合併請求 URL 只在其第一個提示包含 URL 時符合工作階段。 |

1080| v2.1.227 | [刪除工作階段](#what-deleting-a-session-removes)在另一個活躍 Claude Code 工作階段在該 worktree 目錄內執行時保留工作階段及其 worktree。Agent view 在列上顯示 `not deleted` 及頁尾中的原因，`claude rm` 列印 `kept <id>` 及原因，命名其他工作階段的程序 ID。在此版本之前，刪除工作階段在其他工作階段仍在其中工作時移除 worktree。 |

1081| v2.1.225 | 您未信任的目錄中的 `claude agents` 顯示與 `claude` 在啟動時顯示的相同[工作區信任對話](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)，在 agent view 開啟前。接受會為該工作區保存信任；拒絕會在不開啟 agent view 的情況下退出。在此版本之前，`claude agents` 開啟而不詢問，所以您從它分派的工作階段在您從未被要求信任的目錄中執行。<br /><br />列按目錄分組，將滑鼠懸停在列上會突出顯示它，而不改變[分派目標](#dispatch-to-a-specific-directory)；使用箭頭鍵或點擊選擇列仍會改變目標。在此版本之前，將滑鼠移到另一個專案中的工作階段會無聲地改變下一個分派的工作階段啟動的目錄。 |

1082| v2.1.221 | `/status` 顯示 `Session kind` 列：背景工作階段中的 `background job · attached` 或 `background job · unattended`，取決於是否附加了終端，以及任何其他工作階段中的 `interactive`。在此版本之前，`/status` 沒有報告工作階段種類。<br /><br />`/fork`：Claude Code 指示[副本](#from-inside-a-session)隔離其工作與原始工作階段的：副本在進行程式碼變更前建立自己的 worktree，遠離原始工作階段的 worktree，當其任務建立在該工作上時基於原始分支的新分支。請參閱連結的部分以了解確切條件。在此版本之前，副本沒有收到隔離指令，可能最終編輯原始工作階段仍在工作的 worktree 或簽出。<br /><br />使用 [vim 編輯器模式](/docs/zh-TW/interactive-mode#vim-editor-mode)開啟，在使用 `u` 撤銷提示回到空後立即按 `←` 會詢問與刪除文字或移動提示歷史相同的確認，並僅在第二次按下時切換；在此版本之前按下立即切換。 |

1083| v2.1.219 | 使用 [vim 編輯器模式](/docs/zh-TW/interactive-mode#vim-editor-mode)開啟，在空提示上按 `←` 從 NORMAL 模式以及 INSERT 開啟 agent view，頁尾的 `←` 提示在 NORMAL 模式中顯示；在此版本之前手勢和提示是 INSERT 專用的，在 NORMAL 模式中空提示上的 `←` 不執行任何操作。在 Claude Code 等待背景化工作階段時輸入輸入會取消切換，出現 `Backgrounding cancelled — you have unsent text in the input. Send it or clear it, then press ← again.` 所以輸入的草稿不會遺失。 |

1084| v2.1.218 | 在清空提示的刪除後兩秒內或移動提示歷史後按 `←` 顯示 `Press ← again to open agents`，或在附加的工作階段中 `Press ← again to go back to agents`，並僅在至少一秒後的第二次按下時切換；在此版本之前按下立即切換。到達貼上或指令碼輸入內的 `←` 不再觸發切換。使用 `←` 背景化前景工作階段在列上方顯示 `Your conversation moved to the background`，`Esc` 在 agent view 的根部返回該對話，而不是退出到 shell，雙 `Ctrl+C` 保持退出；如果對話無法重新開啟，Claude Code 退出並列印 `claude --resume` 命令。在 Windows 上，在附加後約半秒內按下的 `←` 顯示 `Ambiguous ←, press again to detach` 並在第二次按下時分離。 |

1085| v2.1.217 | 工作階段列上的拉取請求徽章呈現為超連結，即使 Claude Code 無法偵測終端超連結支援，例如透過 SSH 或 tmux；設定 [`FORCE_HYPERLINK=0`](/docs/zh-TW/env-vars) 以將其呈現為純文字。在此版本之前，未偵測到支援時徽章呈現為純文字。 |

1086| v2.1.216 | `/fork`：[確認](#from-inside-a-session)是一行，顯示副本的狀態、其 agent view 列的名稱及其工作階段 ID 以供 `claude attach`，僅當副本在主工作樹中執行或編輯您開啟的簽出時以 `runs in the origin tree` 或 `edits this checkout` 結尾。點擊名稱會背景化此工作階段並在副本的工作階段中開啟 agent view。確認不再重述副本的繼承權限模式；較早版本列印多行確認，沒有可點擊的名稱。<br /><br />需要輸入：`/install-github-app` 和 `/mcp` 設定清單，在沒有人附加時執行，在 `Needs input` 下顯示工作階段，帶有命名命令的列，附加並重新執行命令會繼續；從 v2.1.208 到 v2.1.215 它們在該狀態下被直接拒絕。<br /><br />`--agent` 恢復：恢復或重新啟動[背景化 `--agent` 工作階段](#from-your-shell)會恢復代理的系統提示和工具限制，在工作階段自己的目錄中搜尋代理，當其工作區被信任時；代理不再存在的工作階段會繼續使用預設工具和系統提示，並以可見警告開啟，而不是無聲地還原為預設代理。<br /><br />`Ctrl+X`：按兩次會刪除工作階段，即使停止嘗試失敗，而不是失敗的停止取消待決刪除，已刪除的工作階段，其工作程序已死亡，不再在下一次重新整理時重新出現。<br /><br />Worktree 刪除：其 worktree 目錄不屬於任何 git 儲存庫的工作階段可以被刪除；在此版本之前，每次刪除這樣的工作階段的嘗試都被拒絕。已消失的目錄立即清除。Agent view 雙按移除仍有檔案的目錄，為 hook 建立的目錄執行您的 `WorktreeRemove` hook，除非另一個工作階段的記錄也命名它。`claude rm` 只要檔案仍然存在就保留這樣的目錄。 |

1087| v2.1.214 | 使用 `←` 或 `/background` 背景化且閒置時沒有執行任何操作的工作階段會停止其程序，如同任何其他閒置工作階段，而不是保持其程序和背景服務無限期執行。已完成的工作階段可以在背景服務閒置後使用 `claude rm` 或從 agent view 移除，進入 worktree 的工作階段在從不是 git 儲存庫的目錄分派後，例如多儲存庫工作區資料夾，當 worktree 本身屬於 git 儲存庫時可以從 agent view 刪除，因為清理是從 worktree 而不是分派工作階段的目錄解決的；兩次移除在之前的每次嘗試都被拒絕。重新開啟已停止的工作階段會恢復其已保存的對話，即使記錄存儲中的資料夾無法讀取。 |

1088| v2.1.213 | `/install-github-app`、[`/mcp`](/docs/zh-TW/mcp) 設定清單和 MCP 驗證動作在附加終端時在背景工作階段中工作，僅當沒有人附加時被拒絕，帶有告訴您附加並再次執行命令的訊息；從 v2.1.208 到 v2.1.212 即使附加了終端也被拒絕。 |

1089| v2.1.212 | [互動工作階段中的 `/fork`](#from-inside-a-session) 將對話複製到顯示為其自己列的新背景工作階段，以它來自的工作階段命名，或對於未命名工作階段的提示分支，以分支提示命名，而原始工作階段保持執行；`/fork` 的較早分支子代理行為移到 `/subtask`。使用[關閉 agent view](#turn-off-agent-view)，`/fork` 保持分支子代理行為。等待其第一個提示的焦點列顯示 `space to send it a prompt`。`Ctrl+J` 在具有擴展鍵報告的終端上在分派輸入中插入換行符，其中按鍵先前被忽略，`?` 覆蓋層列出快捷鍵。當背景工作階段完成且沒有任何需要您輸入時，互動工作階段中的 `←` 頁尾提示簡要顯示 `N done`。在 agent view 中輸入裸露的 `/resume` 會開啟您開啟 agent view 的儲存庫的過去工作階段的選擇器，包括從列表中刪除的工作階段，選擇一個會將其恢復為背景工作階段；在此版本之前 `/resume` 在 agent view 中不可用，已刪除的工作階段只能透過 `claude --resume` 或互動工作階段中的 `/resume` 到達。目標、範圍和受限形式保留較早版本為每個形式顯示的 `attach to a session to run it` 提示。等待沙箱網路主機提示、MCP 輸入請求或受管設定提示的工作階段在 agent view 和 `claude agents --json` 中顯示為 `Needs input` 而不是 `Working`，Claude 的問題報告 `waitingFor: input needed` 而不是 `permission prompt`。附加到其程序已停止的工作階段會顯示其記錄，格式化為活躍工作階段呈現的方式，而不是原始文字。已停止的工作階段，其記錄在意外位置，透過您已保存記錄的最後手段掃描恢復，開啟沒有已保存記錄的列顯示 `Press enter again to restart this session fresh`，在第二次按下時新鮮重新啟動；v2.1.211 顯示拒絕，沒有辦法從 agent view 重新啟動。 |

1090| v2.1.211 | 喚醒已停止的工作階段，透過附加或從其執行的目錄回覆，再次轉發您的 shell 的閘道 `ANTHROPIC_BASE_URL`，條件與新鮮分派相同，所以透過閘道 `ANTHROPIC_AUTH_TOKEN` 驗證的工作階段在閘道上恢復，而不是報告 `Not logged in`。附加到在另一個對話之前背景化的已停止工作階段，在其第一個回應完成前被拒絕，出現 `This session has no saved transcript` 而不是無聲地在相同工作階段 ID 下啟動空白對話；從 agent view 開啟相同列顯示頁尾中的拒絕。從 Claude Code 外部結束 `←` 或 `/background` 工作階段的程序會將其標記為已停止，而不是監督程序重新啟動它，已記錄在磁碟上的停止會被尊重，除非您傳送的回覆仍在等待傳遞，崩潰後重新啟動的工作階段被告知它已重新啟動，重新啟動的 `←` 或 `/background` 工作階段不會恢復超過約一小時的中斷回應。回答或拒絕提示而不是標籤的工作階段命名回覆，例如對於主要是連結的提示，會被丟棄，列保留從提示文字取得的名稱。其 worktree git 不再識別的工作階段刪除成功，在磁碟上留下 worktree 目錄並命名其路徑，而不是每次嘗試都被拒絕。拒絕的刪除在工作階段列上顯示原因，包括 worktree 無法移除時的基礎 git 錯誤，而不是列無聲地重新出現。 |

1091| v2.1.210 | `claude attach` 在背景服務啟動或重新連接時等待，而不是失敗，出現 `job not found` 或 `still starting` 錯誤，報告在附加期間完成的工作階段為已退出，並應用在慢速附加期間進行的終端調整大小，當附加完成時。提示頁尾的 `←` 需要輸入計數出現在每個提供者上，包括先前顯示純 `← for agents` 形式的第三方提供者。使用 `←` 背景化工作階段會將 Claude 的任務清單帶到背景工作階段，而不是丟棄它。您按 `←` 的列在選擇移動後保留粗體、未變暗的名稱。`claude agents --effort` 接受 `ultracode` 而不是無聲地丟棄它。 |

813| v2.1.208 | 附加到其程序已停止的工作階段會顯示其記錄的最後一屏，同時程序啟動，而不是只顯示 `Session is starting` 備註。無法傳遞的回覆（因為背景服務無法連線或傳送失敗）會被保存，並在其程序再次啟動時作為工作階段的下一個提示傳送；在此版本之前，背景服務無法連線時遺失的回覆會被丟棄。其自身二進位檔被更新取代的程序仍然可以啟動監督程序，從已安裝的 `claude` 啟動器或磁碟上的最新版本，而不是失敗直到 Claude Code 重新啟動。執行較舊版本的監督程序永遠不會將由較新版本啟動的閒置工作階段重新啟動到其自身較舊的二進位檔。刪除工作階段會移除其 worktree，即使工作階段將 worktree 移到不同的分支，並在 worktree 有未推送到任何地方的提交或另一個工作階段聲稱它時將 worktree 與工作階段列保持在一起，而不是銷毀提交或孤立 worktree。`/install-github-app` 和 `/mcp` 設定清單及其驗證動作在背景工作階段中被拒絕，並顯示命名替代方案的訊息；在 v2.1.208 中，`/model` 選擇器以相同方式被拒絕，輸入的 `/model <name>` 只切換該工作階段，而不是也保存您的預設模型。 |1092| v2.1.208 | 附加到其程序已停止的工作階段會顯示其記錄的最後一屏，同時程序啟動，而不是只顯示 `Session is starting` 備註。無法傳遞的回覆（因為背景服務無法連線或傳送失敗）會被保存，並在其程序再次啟動時作為工作階段的下一個提示傳送；在此版本之前，背景服務無法連線時遺失的回覆會被丟棄。其自身二進位檔被更新取代的程序仍然可以啟動監督程序，從已安裝的 `claude` 啟動器或磁碟上的最新版本，而不是失敗直到 Claude Code 重新啟動。執行較舊版本的監督程序永遠不會將由較新版本啟動的閒置工作階段重新啟動到其自身較舊的二進位檔。刪除工作階段會移除其 worktree，即使工作階段將 worktree 移到不同的分支，並在 worktree 有未推送到任何地方的提交或另一個工作階段聲稱它時將 worktree 與工作階段列保持在一起，而不是銷毀提交或孤立 worktree。`/install-github-app` 和 `/mcp` 設定清單及其驗證動作在背景工作階段中被拒絕，並顯示命名替代方案的訊息；在 v2.1.208 中，`/model` 選擇器以相同方式被拒絕，輸入的 `/model <name>` 只切換該工作階段，而不是也保存您的預設模型。 |

814| v2.1.207 | 查看面板以列截斷的句子開啟，例如等待您的工作階段的確切問題，並顯示被阻止的工作階段已等待多長時間，作為單一 `waiting 3m` 行，而不是將相同的時間戳記前綴到狀態句子和問題。在分派輸入中再次貼上相同的文字會展開摺疊的 `[Pasted text #N]` 預留位置，而不是新增第二個。按名稱接受計畫的背景工作階段會在其列上顯示該名稱。移入 worktree 的背景工作階段在其程序從 agent view 重新啟動時會保留其對話。 |1093| v2.1.207 | 查看面板以列截斷的句子開啟，例如等待您的工作階段的確切問題，並顯示被阻止的工作階段已等待多長時間，作為單一 `waiting 3m` 行，而不是將相同的時間戳記前綴到狀態句子和問題。在分派輸入中再次貼上相同的文字會展開摺疊的 `[Pasted text #N]` 預留位置，而不是新增第二個。按名稱接受計畫的背景工作階段會在其列上顯示該名稱。移入 worktree 的背景工作階段在其程序從 agent view 重新啟動時會保留其對話。 |

815| v2.1.206 | 列摘要填充列的剩餘寬度，並僅在終端的右邊緣截斷，而不是在 64 欄處。監督程序重新啟動到新的 Claude Code 版本後，它會在背景中將剩餘的閒置背景工作階段重新啟動到該版本，而不是每分鐘幾個。使用 `Ctrl+X` 或 `claude rm` 刪除工作階段也會從監督程序的工作階段清單中清除它，因此列在監督程序重新啟動後不再重新出現。 |1094| v2.1.206 | 列摘要填充列的剩餘寬度，並僅在終端的右邊緣截斷，而不是在 64 欄處。監督程序重新啟動到新的 Claude Code 版本後，它會在背景中將剩餘的閒置背景工作階段重新啟動到該版本，而不是每分鐘幾個。使用 `Ctrl+X` 或 `claude rm` 刪除工作階段也會從監督程序的工作階段清單中清除它，因此列在監督程序重新啟動後不再重新出現。在分派 shell 中匯出的 `CLAUDE_CODE_EXTRA_BODY` 請求本體覆蓋到達背景工作階段，而不是被忽略。 |

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

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

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

819| v2.1.200 | 較舊的 Claude Code 版本在 `roster.json` 中重寫工作階段清單時會保留較新版本寫入的欄位，符合現有的 `state.json` 保證，因此由較新版本啟動的工作階段在監督程序重新啟動後繼續接受輸入。當您開啟已停止回應的工作階段時，監督程序會重新啟動其程序，工作階段會從中斷的地方繼續中斷的回應。 |1098| v2.1.200 | 較舊的 Claude Code 版本在 `roster.json` 中重寫工作階段清單時會保留較新版本寫入的欄位，符合現有的 `state.json` 保證，因此由較新版本啟動的工作階段在監督程序重新啟動後繼續接受輸入。當您開啟已停止回應的工作階段時，監督程序會重新啟動其程序，工作階段會從中斷的地方繼續中斷的回應。Agent view 應用放在 `agents` 後面的 `--plugin-dir` 旗標到其自己的子代理和技能自動完成，在分派輸入中以及分派的工作階段。 |

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

821| v2.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` 結合會被拒絕並出現錯誤。 |1100| v2.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` 結合會被拒絕並出現錯誤。背景工作階段主機在首次 LAN 存取時要求 macOS 本機網路權限，而不是失敗，出現 `connect: no route to host`。 |

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

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

1103| v2.1.191 | `claude --bg` 與不符合您任何子代理的 `--agent` 名稱失敗啟動：工作階段立即退出，出現 `--agent '<name>' not found` 錯誤，而不是使用預設代理執行。 |

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

825| v2.1.172 | 分派輸入中的 `/model` 設定工作階段範圍的分派模型覆蓋。 |1105| v2.1.172 | 分派輸入中的 `/model` 設定工作階段範圍的分派模型覆蓋。 |

826| v2.1.161 | 列摘要顯示平行工作項目的 `done/total` 計數；查看面板命名最長執行的平行工作項目。 |1106| v2.1.161 | 列摘要顯示平行工作項目的 `done/total` 計數；查看面板命名最長執行的平行工作項目。 |

agents.md +1 −1

Details

19 19

20還有三個工具支援此工作，但它們本身不是執行代理的方式：20還有三個工具支援此工作，但它們本身不是執行代理的方式：

21 21

22* [Worktrees](/docs/zh-TW/worktrees) 為每個工作階段提供單獨的 git 簽出，因此平行工作階段永遠不會編輯相同的檔案。將它們用於您自己執行的工作階段。代理檢視會自動將每個分派的工作階段移動到自己的 worktree 中，您生成的子代理也可以各自獲得一個。22* [Worktrees](/docs/zh-TW/worktrees) 為每個工作階段提供單獨的 git 簽出，因此平行工作階段永遠不會編輯相同的檔案。將它們用於您自己執行的工作階段。代理檢視會自動將每個分派的工作階段 [移動到自己的 worktree 中](/docs/zh-TW/agent-view#how-file-edits-are-isolated)，您生成的子代理也可以各自獲得一個。

23* [跨工作階段訊息傳遞](/docs/zh-TW/cross-session-messaging) 讓 Claude 列出並訊息傳遞您在此機器上、另一台機器上或 [網路上的 Claude Code](/docs/zh-TW/claude-code-on-the-web) 上的其他 Claude Code 工作階段，因此您自己執行的工作階段可以在彼此之間傳遞發現和狀態。23* [跨工作階段訊息傳遞](/docs/zh-TW/cross-session-messaging) 讓 Claude 列出並訊息傳遞您在此機器上、另一台機器上或 [網路上的 Claude Code](/docs/zh-TW/claude-code-on-the-web) 上的其他 Claude Code 工作階段，因此您自己執行的工作階段可以在彼此之間傳遞發現和狀態。

24* [`/batch`](/docs/zh-TW/commands) 是一個 [skill](/docs/zh-TW/skills)，讓 Claude 將一個大型變更分成 5 到 30 個 worktree 隔離的子代理，每個都開啟一個拉取請求。這是子代理和 worktrees 的打包使用，不是單獨的協調風格。24* [`/batch`](/docs/zh-TW/commands) 是一個 [skill](/docs/zh-TW/skills)，讓 Claude 將一個大型變更分成 5 到 30 個 worktree 隔離的子代理，每個都開啟一個拉取請求。這是子代理和 worktrees 的打包使用，不是單獨的協調風格。

25 25

amazon-bedrock.md +3 −3

Details

265 265

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

267 267

268* 自 v2.1.172 起，您只需設定 `AWS_REGION` 以覆寫您的 AWS 設定檔的區域或當您的設定檔沒有區域時。Claude Code 按此順序解析區域：268* 您只需設定 `AWS_REGION` 以覆寫您的 AWS 設定檔的區域或當您的設定檔沒有區域時。Claude Code 按此順序解析區域：

269 269

270 * `AWS_REGION`270 * `AWS_REGION`

271 * `AWS_DEFAULT_REGION`271 * `AWS_DEFAULT_REGION`

276 276

277 作用中設定檔是 `AWS_PROFILE`（如果已設定），否則為 `default`。設定 `AWS_SHARED_CREDENTIALS_FILE` 或 `AWS_CONFIG_FILE` 以指向非預設檔案路徑。277 作用中設定檔是 `AWS_PROFILE`（如果已設定），否則為 `default`。設定 `AWS_SHARED_CREDENTIALS_FILE` 或 `AWS_CONFIG_FILE` 以指向非預設檔案路徑。

278 278

279 執行 `/status` 以查看解析的區域。當區域來自您的 AWS 設定檔或預設後備時，Claude Code 也會在 `/status` 輸出中記錄來源。在 v2.1.171 及更早版本上，Claude Code 不會讀取 AWS 設定檔，因此請明確設定 `AWS_REGION`。279 執行 `/status` 以查看解析的區域。當區域來自您的 AWS 設定檔或預設後備時，Claude Code 也會在 `/status` 輸出中記錄來源。

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

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

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

531export AWS_REGION=us-east-1531export AWS_REGION=us-east-1

532```532```

533 533

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

535 535

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

537 537

analytics.md +0 −6

Details

139 139

140啟用貢獻指標後，Claude Code 會分析已合併的提取要求，以確定哪些程式碼是使用 Claude Code 協助撰寫的。這是透過將 Claude Code 工作階段活動與每個 PR 中的程式碼進行比對來完成的。140啟用貢獻指標後，Claude Code 會分析已合併的提取要求，以確定哪些程式碼是使用 Claude Code 協助撰寫的。這是透過將 Claude Code 工作階段活動與每個 PR 中的程式碼進行比對來完成的。

141 141

142<h4 id="tagging-criteria">

143 標籤準則

144</h4>

~~145~~

146如果 PR 包含在 Claude Code 工作階段期間撰寫的至少一行程式碼，則會標籤為「包含 Claude Code」。系統使用保守的比對：只有在高度確信 Claude Code 參與的程式碼才會計為協助。

~~147~~

148<h4 id="attribution-process">142<h4 id="attribution-process">

149 歸因程序143 歸因程序

150</h4>144</h4>

artifacts.md +13 −11

Details

35 artifact 不是什麼35 artifact 不是什麼

36</h3>36</h3>

37 37

38artifact 是工作的擷取：一個自包含的頁面，沒有後端，因此無法儲存表單輸入或提供多個路由，當有人查看它時，其唯一的外部資料路徑是[呼叫 MCP 連接器](#pull-live-data-with-mcp-connectors)。對於具有後端的託管內部工具，請改為在您自己的基礎設施上部署它。請參閱[頁面限制](#page-constraints)以取得完整的限制集合。38artifact 是工作的擷取：一個自包含的頁面，沒有後端，因此無法提供多個路由。對於具有後端的託管內部工具，請改為在您自己的基礎設施上部署它。請參閱[頁面限制](#page-constraints)以取得完整的限制集合。

39 39

40<h2 id="create-an-artifact">40<h2 id="create-an-artifact">

41 建立成品41 建立成品

64 64

65在首次發佈後，Claude 會列印 URL，你的瀏覽器會開啟到新頁面。如果你從 claude.ai、Claude Desktop 或 Claude 行動應用程式透過[遠端控制](/docs/zh-TW/remote-control)傳送提示，執行工作階段的機器上不會開啟任何標籤。下次 Claude 從你在終端機輸入的提示發佈成品時，瀏覽器會在那裡開啟。隨時按 `Ctrl+]` 以重新開啟工作階段的最新成品。65在首次發佈後，Claude 會列印 URL，你的瀏覽器會開啟到新頁面。如果你從 claude.ai、Claude Desktop 或 Claude 行動應用程式透過[遠端控制](/docs/zh-TW/remote-control)傳送提示，執行工作階段的機器上不會開啟任何標籤。下次 Claude 從你在終端機輸入的提示發佈成品時，瀏覽器會在那裡開啟。隨時按 `Ctrl+]` 以重新開啟工作階段的最新成品。

66 66

67Claude 會為成品選擇標題和瀏覽器標籤圖示的表情符號。兩者都會出現在你在 claude.ai 上的[成品庫](#share-an-artifact)和共享連結中，因此如果你想要特定標題或圖示，請要求 Claude 使用一個。67Claude 會為成品選擇標題和表情符號，兩者都會出現在你在 claude.ai 上的[成品庫](#share-an-artifact)和共享連結中。Claude 也可以選擇與頁面內容相符的瀏覽器標籤圖示，例如圖表或日曆。如果你想要特定標題、表情符號或標籤圖示，請要求 Claude。

68 68

69若要停止瀏覽器在發佈新成品時自動開啟，請在你的環境中設定 `CLAUDE_CODE_ARTIFACT_AUTO_OPEN=0`。69若要停止瀏覽器在發佈新成品時自動開啟，請在你的環境中設定 `CLAUDE_CODE_ARTIFACT_AUTO_OPEN=0`。

70 70

328| 限制 | 效果 |328| 限制 | 效果 |

329| :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |329| :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

330| 外部請求 | 頁面可以從 Google Fonts 載入字型，以及從[四個公開 CDN 主機](#allowlist-the-viewer-domain)載入指令碼：cdnjs、Tailwind 和 jQuery CDN，以及 jsDelivr 上的選定路徑，例如 `/npm/`。CSP 會阻止所有外部影像和所有其他外部指令碼、樣式表和字型，並讓 `fetch`、XHR 和 WebSocket 呼叫只能到達頁面自身的來源和 Google Fonts 主機。因此，Claude 會從這些 CDN 之一載入頁面需要的任何程式庫，內嵌所有其他 CSS 和 JavaScript，並將影像嵌入為資料 URI。[Connector 呼叫](#pull-live-data-with-mcp-connectors)會通過 claude.ai 進行，它會自行進行網路呼叫。 |330| 外部請求 | 頁面可以從 Google Fonts 載入字型，以及從[四個公開 CDN 主機](#allowlist-the-viewer-domain)載入指令碼：cdnjs、Tailwind 和 jQuery CDN，以及 jsDelivr 上的選定路徑，例如 `/npm/`。CSP 會阻止所有外部影像和所有其他外部指令碼、樣式表和字型，並讓 `fetch`、XHR 和 WebSocket 呼叫只能到達頁面自身的來源和 Google Fonts 主機。因此，Claude 會從這些 CDN 之一載入頁面需要的任何程式庫，內嵌所有其他 CSS 和 JavaScript，並將影像嵌入為資料 URI。[Connector 呼叫](#pull-live-data-with-mcp-connectors)會通過 claude.ai 進行，它會自行進行網路呼叫。 |

331| 無後端 | 成品是靜態頁面。它無法儲存透過表單提交的資料或自行驗證檢視者。它在有人檢視時擷取資料的唯一方式是[呼叫 MCP connector](#pull-live-data-with-mcp-connectors)，而不是它自己的 API。 |331| 無後端 | 成品是靜態頁面。它無法自行驗證檢視者。 |

332| 下載 | 頁面無法自行啟動下載。為了讓檢視者儲存頁面產生的檔案，Claude 會宣告下載功能。請參閱[提供檔案下載](#offer-a-file-download)。 |332| 下載 | 頁面無法自行啟動下載。為了讓檢視者儲存頁面產生的檔案，Claude 會宣告下載功能。請參閱[提供檔案下載](#offer-a-file-download)。 |

333| 單一頁面 | 相對連結無法解析，因為頁面旁邊沒有部署任何內容。對於多區段內容，Claude 使用頁面內錨點而不是個別檔案。 |333| 單一頁面 | 相對連結無法解析，因為頁面旁邊沒有部署任何內容。對於多區段內容，Claude 使用頁面內錨點而不是個別檔案。 |

334| 來源檔案類型 | 發佈的檔案必須是 `.html`、`.htm` 或 `.md`。Markdown 檔案會呈現為樣式化的 HTML。 |334| 來源檔案類型 | 發佈的檔案必須是 `.html`、`.htm` 或 `.md`，且必須解碼為 UTF-8，或根據其位元組順序標記解碼為小端 UTF-16。Markdown 檔案會呈現為樣式化的 HTML。無法解碼或包含替換字元 `U+FFFD` 的檔案會[被拒絕並顯示要修正的行和列](/docs/zh-TW/errors#the-source-file-is-not-valid-utf-8-text)。 |

335| 呈現大小 | 呈現的頁面必須為 16 MiB 或更小。大型嵌入影像通常是發佈因大小而失敗的原因。 |335| 呈現大小 | 呈現的頁面必須為 16 MiB 或更小。大型嵌入影像通常是發佈因大小而失敗的原因。 |

336 336

337產生成品會像任何其他回應一樣使用輸出權杖，而樣式化頁面比相同內容作為終端文字更耗費權杖。內嵌 CSS、用於互動控制的 JavaScript，尤其是嵌入為資料 URI 的影像，是主要貢獻者。若要減少成品的權杖成本：337產生成品會像任何其他回應一樣使用輸出權杖，而樣式化頁面比相同內容作為終端文字更耗費權杖。內嵌 CSS、用於互動控制的 JavaScript，尤其是嵌入為資料 URI 的影像，是主要貢獻者。若要減少成品的權杖成本：

355| 表面 | Claude Code CLI 版本 2.1.183 或更新版本，或 Claude 桌面應用程式版本 1.13576.0 或更新版本。[Claude Tag](https://claude.com/docs/claude-tag/overview) 工作階段在 Claude Tag 和成品都為組織啟用時也可以發佈成品。在 [Agent SDK](/docs/zh-TW/agent-sdk/overview)、GitHub Action 和 MCP 伺服器上下文中預設關閉，以及當設定 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/zh-TW/env-vars) 時。 |355| 表面 | Claude Code CLI 版本 2.1.183 或更新版本，或 Claude 桌面應用程式版本 1.13576.0 或更新版本。[Claude Tag](https://claude.com/docs/claude-tag/overview) 工作階段在 Claude Tag 和成品都為組織啟用時也可以發佈成品。在 [Agent SDK](/docs/zh-TW/agent-sdk/overview)、GitHub Action 和 MCP 伺服器上下文中預設關閉，以及當設定 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/zh-TW/env-vars) 時。 |

356 356

357<h2 id="disable-artifacts">357<h2 id="disable-artifacts">

358 停用成品358 停用 artifacts

359</h2>359</h2>

360 360

361要根據您組織的設定為您自己的工作階段關閉成品，請使用以下任何一個：361若要關閉您自己工作階段中的 artifacts，無論您的組織設定為何，請使用以下任一方式：

362 362

363| 方法 | 設定 |363| 位置 | 操作 |

364| :--------------------------- | :----------------------------------------------------------------------------------------------------- |364| :--------------------------- | :----------------------------------------------------------------------------------------------------- |

365| [`/config`](/docs/zh-TW/commands) | 關閉 **Artifacts** 列，這會將 [`"enableArtifact": false`](/docs/zh-TW/settings-reference#enableartifact) 寫入您的使用者設定 |365| [`/config`](/docs/zh-TW/commands) | 關閉 **Artifacts** 列，這會將 [`"enableArtifact": false`](/docs/zh-TW/settings-reference#enableartifact) 寫入您的使用者設定 |

369 369

370一旦您在 [`--settings`](/docs/zh-TW/cli-reference#cli-flags) 檔案中或使用 `CLAUDE_CODE_DISABLE_ARTIFACT` 關閉成品，或您的管理員在[受管設定](/docs/zh-TW/server-managed-settings)中關閉成品，就沒有設定檔能將其重新開啟。在 v2.1.242 之前，[優先順序堆疊](/docs/zh-TW/settings#settings-precedence)中較高位置的檔案可能會重新開啟成品，即使較低優先順序的檔案設定了 `"enableArtifact": false`。370一旦您在 [`--settings`](/docs/zh-TW/cli-reference#cli-flags) 檔案中或使用 `CLAUDE_CODE_DISABLE_ARTIFACT` 關閉 artifacts，或您的管理員在[受管設定](/docs/zh-TW/server-managed-settings)中關閉它們，就沒有設定檔能將其重新開啟。在 v2.1.242 之前，[優先順序堆疊](/docs/zh-TW/settings#settings-precedence)中較高位置的檔案可能會重新開啟 artifacts，即使較低優先順序的檔案設定了 `"enableArtifact": false`。

371 371

372您也可以在專案的 `.claude/settings.json` 或 `.claude/settings.local.json` 中設定 `"enableArtifact": false`，以關閉該專案中工作階段的成品。任一檔案中的 `"enableArtifact": true` 都不會將其重新開啟。在專案和本機設定中接受此金鑰需要 Claude Code v2.1.242 或更新版本。372您也可以在專案的 `.claude/settings.json` 或 `.claude/settings.local.json` 中設定 `"enableArtifact": false`，以關閉該專案中工作階段的 artifacts。任一檔案中的 `"enableArtifact": true` 都不會將其重新開啟。在專案和本機設定中接受此金鑰需要 Claude Code v2.1.242 或更新版本。

373

374如果您新增 `WebFetch` deny 或 ask 規則但不含 `domain:` 部分，它不會關閉 artifacts 或阻止 artifact 讀取。[`permissions` 中 `deny` 或 `ask` 內的 `WebFetch(domain:claude.ai)` 規則確實適用於 artifact 讀取](/docs/zh-TW/permissions#allow-or-deny-every-fetch)。

373 375

374<h2 id="manage-artifacts-for-your-organization">376<h2 id="manage-artifacts-for-your-organization">

375 為您的組織管理成品377 為您的組織管理成品

authentication.md +5 −1

Details

235 235

236已簽署的 [Claude apps gateway](/docs/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` 和設定檔等認證來源也不會被使用。236已簽署的 [Claude apps gateway](/docs/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` 和設定檔等認證來源也不會被使用。

237 237

238如果您有有效的 Claude 訂閱，但您的環境中也設定了 `ANTHROPIC_API_KEY`，則 API 金鑰在核准後優先。如果金鑰屬於已停用或過期的組織，這可能會導致驗證失敗。執行 `unset ANTHROPIC_API_KEY` 以回退到您的訂閱，並檢查 `/status` 以確認哪種方法處於活動狀態。`Login method` 列會顯示您的訂閱帳戶，當 API 金鑰在使用中時會出現 `API key` 列。238如果您機器的[受管設定](/docs/zh-TW/managed-settings)將 [`forceLoginMethod`](/docs/zh-TW/settings-reference#forceloginmethod) 設定為 `"gateway"` 或設定 [`forceLoginGatewayUrl`](/docs/zh-TW/settings-reference#forcelogingatewayurl)，且您未透過 `CLAUDE_CODE_USE_BEDROCK` 或 `CLAUDE_CODE_USE_VERTEX` 等變數選擇雲端提供商，您的工作階段僅使用閘道登入。Claude Code 會跳過其他認證來源，並要求您使用 `/login` 登入。請參閱[系統管理員原則需要雲端閘道登入](/docs/zh-TW/errors#administrator-policy-requires-a-cloud-gateway-sign-in)以了解您在每個剩餘認證中看到的內容。在 v2.1.261 之前，或在僅設定 `forceLoginGatewayUrl` 的機器上在 v2.1.265 之前，Claude Code 會在這些機器上使用剩餘的已儲存登入，直到您登入閘道。

239

240如果您有有效的 Claude 訂閱，但您的環境中也設定了 `ANTHROPIC_API_KEY`，則 API 金鑰在核准後優先。如果金鑰屬於已停用或過期的組織，這可能會導致驗證失敗。

241

242執行 `unset ANTHROPIC_API_KEY` 以回退到您的訂閱，並檢查 `/status` 以確認哪種方法處於活動狀態。當登入和 API 金鑰都已設定時，`/status` 會標記未使用的認證。

239 243

240[網頁版 Claude Code](/docs/zh-TW/claude-code-on-the-web) 始終使用您的訂閱認證。如果您在沙箱環境中設定 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN`，它不會覆蓋您的訂閱認證。244[網頁版 Claude Code](/docs/zh-TW/claude-code-on-the-web) 始終使用您的訂閱認證。如果您在沙箱環境中設定 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN`，它不會覆蓋您的訂閱認證。

241 245

auto-mode-config.md +3 −3

Details

397 397

398若要查看分類器阻止了什麼，請在對話中找到工具呼叫。如果呼叫顯示為縮短或摺疊成摘要行（例如 `Ran 3 shell commands`），請按 `Ctrl+O` 開啟[文字記錄檢視器](/docs/zh-TW/interactive-mode#transcript-viewer)，它會展開該呼叫。398若要查看分類器阻止了什麼，請在對話中找到工具呼叫。如果呼叫顯示為縮短或摺疊成摘要行（例如 `Ran 3 shell commands`），請按 `Ctrl+O` 開啟[文字記錄檢視器](/docs/zh-TW/interactive-mode#transcript-viewer)，它會展開該呼叫。

399 399

400螢幕上另外兩個報告拒絕的位置會省略命令或 URL：輸入框附近的通知（例如 `bash denied by auto mode · Blocked by classifier · /permissions`）會提供工具和原因，而 **Recently denied** 標籤會按 Claude 為其撰寫的描述列出 shell 命令。若要以程式設計方式擷取這些拒絕的確切輸入，請新增 [`PermissionDenied` hook](/docs/zh-TW/hooks#permissiondenied)，它會將其作為 `tool_input` 接收。400螢幕上另外兩個報告拒絕的位置會省略命令或 URL：輸入框附近的通知（例如 `bash denied by auto mode · [Data Exfiltration] · /permissions`）會提供工具和原因，而 **Recently denied** 標籤會按 Claude 為其撰寫的描述列出 shell 命令。若要以程式設計方式擷取這些拒絕的確切輸入，請新增 [`PermissionDenied` hook](/docs/zh-TW/hooks#permissiondenied)，它會將其作為 `tool_input` 接收。

401 401

402呼叫下方的文字會告訴您是否有任何需要修復的內容。報告分類器本身問題的文字，例如 `is temporarily unavailable` 的模型或分類器錯誤，表示 Claude Code 在沒有分類器最終判決的情況下阻止了呼叫；請參閱[自動模式無法判定動作的安全性](/docs/zh-TW/errors#auto-mode-cannot-determine-the-safety-of-an-action)以了解該怎麼做。否則，讀取 `Denied by auto mode classifier` 的行加上原因（例如 `Blocked by classifier`）表示分類器判定呼叫不安全，因此請從呼叫嘗試到達或執行的內容中選擇修復：402呼叫下方的文字會告訴您是否有任何需要修復的內容。報告分類器本身問題的文字，例如 `is temporarily unavailable` 的模型或分類器錯誤，表示 Claude Code 在沒有分類器最終判決的情況下阻止了呼叫；請參閱[自動模式無法判定動作的安全性](/docs/zh-TW/errors#auto-mode-cannot-determine-the-safety-of-an-action)以了解該怎麼做。否則，讀取 `Denied by auto mode classifier` 的行加上原因（例如 `[Production Deploy]` 或 `Blocked by classifier`）表示分類器判定呼叫不安全，因此請從呼叫嘗試到達或執行的內容中選擇修復：

403 403

404* 一個 Claude 在整個任務中需要的目的地，例如套件登錄、內部網域或儲存庫主機：將其新增至 `autoMode.environment`。404* 一個 Claude 在整個任務中需要的目的地，例如套件登錄、內部網域或儲存庫主機：將其新增至 `autoMode.environment`。

405* 一個您想要從現在開始無需檢視即可執行的命令：新增 `allow` 規則。405* 一個您想要從現在開始無需檢視即可執行的命令：新增 `allow` 規則。

407 407

408您可以從 `/permissions` 對話框的 [**Auto mode** 標籤](#edit-rules-from-permissions)新增環境項目或 `allow` 規則。408您可以從 `/permissions` 對話框的 [**Auto mode** 標籤](#edit-rules-from-permissions)新增環境項目或 `allow` 規則。

409 409

410在大多數工作階段中，與呼叫一起顯示的原因是固定文字 `Blocked by classifier`，在 Claude Code v2.1.208 及更新版本中：分類器在內部嚴重程度量表上對每個動作進行評分，而不是寫出解釋。某些工作階段執行分類器模型，在 v2.1.193 及更新版本中寫出簡短解釋；當出現時，將其視為關於分類器遺漏哪個目的地或意圖的提示。Claude Code 會選取分類器模型，因此您看到的原因不是您可以設定的內容。410在大多數工作階段中，原因會命名分類器符合的規則，以方括號表示，例如 `[Data Exfiltration]` 或 `[Production Deploy]`，而某些工作階段執行的分類器模型會新增簡短說明。Claude Code 會選取分類器模型，因此您看到的形式不是您可以設定的內容。

411 411

412<h3 id="fix-repeated-denials">412<h3 id="fix-repeated-denials">

413 修復重複拒絕413 修復重複拒絕

channels.md +2 −2

Details

47 * `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 新增市場，然後重試安裝。47 * `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 新增市場，然後重試安裝。

48 * 外掛程式[在市場中找不到](/docs/zh-TW/discover-plugins#install-plugins)：檢查外掛程式名稱。48 * 外掛程式[在市場中找不到](/docs/zh-TW/discover-plugins#install-plugins)：檢查外掛程式名稱。

49 49

50 當安裝要求安裝範圍時，選擇使用者範圍選項，以便外掛程式在所有專案中可用。檢查安裝摘要：如果報告 `Run /reload-plugins to activate.`，執行該命令以啟用外掛程式的設定命令。50 當安裝要求安裝範圍時，選擇使用者範圍選項，以便外掛程式在所有專案中可用。檢查安裝摘要：如果報告 `Run /reload-plugins to activate.`，請參閱[在不重新啟動的情況下套用外掛程式變更](/docs/zh-TW/discover-plugins#apply-plugin-changes-without-restarting)以使外掛程式的設定命令可用。

51 </Step>51 </Step>

52 52

53 <Step title="設定您的權杖">53 <Step title="設定您的權杖">

125 * `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 新增市場，然後重試安裝。125 * `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 新增市場，然後重試安裝。

126 * 外掛程式[在市場中找不到](/docs/zh-TW/discover-plugins#install-plugins)：檢查外掛程式名稱。126 * 外掛程式[在市場中找不到](/docs/zh-TW/discover-plugins#install-plugins)：檢查外掛程式名稱。

127 127

128 當安裝要求安裝範圍時，選擇使用者範圍選項，以便外掛程式在所有專案中可用。檢查安裝摘要：如果報告 `Run /reload-plugins to activate.`，執行該命令以啟用外掛程式的設定命令。128 當安裝要求安裝範圍時，選擇使用者範圍選項，以便外掛程式在所有專案中可用。檢查安裝摘要：如果報告 `Run /reload-plugins to activate.`，請參閱[在不重新啟動的情況下套用外掛程式變更](/docs/zh-TW/discover-plugins#apply-plugin-changes-without-restarting)以使外掛程式的設定命令可用。

129 </Step>129 </Step>

130 130

131 <Step title="設定您的權杖">131 <Step title="設定您的權杖">

channels-reference.md +1 −1

Details

170 170

171 如果事件未到達，診斷取決於 `curl` 返回的內容：171 如果事件未到達，診斷取決於 `curl` 返回的內容：

172 172

173 * **`curl` 成功但沒有任何內容到達 Claude**：在您的工作階段中執行 `/mcp` 以檢查伺服器的狀態。`failed` 狀態通常表示伺服器檔案中的相依性或匯入錯誤；檢查 `~/.claude/debug/<session-id>.txt` 的偵錯日誌以取得 stderr 追蹤。173 * **`curl` 成功但沒有任何內容到達 Claude**：在您的工作階段中執行 `/mcp` 以檢查伺服器的狀態。`failed` 狀態通常表示伺服器檔案中的相依性或匯入錯誤。若要查看 stderr 追蹤，請使用 `claude --debug --dangerously-load-development-channels server:webhook` 重新啟動，並檢查 `~/.claude/debug/<session-id>.txt` 的偵錯日誌。

174 * **`curl` 失敗，出現「連接被拒絕」**：連接埠要麼尚未繫結，要麼來自較早執行的過時程序正在佔用它。`lsof -i :<port>` 顯示正在監聽的內容；在重新啟動工作階段之前 `kill` 過時程序。174 * **`curl` 失敗，出現「連接被拒絕」**：連接埠要麼尚未繫結，要麼來自較早執行的過時程序正在佔用它。`lsof -i :<port>` 顯示正在監聽的內容；在重新啟動工作階段之前 `kill` 過時程序。

175 </Step>175 </Step>

176</Steps>176</Steps>

checkpointing.md +11 −3

Details

12 Checkpointing 的運作方式12 Checkpointing 的運作方式

13</h2>13</h2>

14 14

~~15當您與 Claude 合作時，checkpointing 會自動捕捉每次使用者提示前的程式碼狀態。~~15當您與 Claude 合作時，checkpointing 會自動捕捉每次使用者提示開始一個回合前的程式碼狀態。

16 16

17<h3 id="automatic-tracking">17<h3 id="automatic-tracking">

18 自動追蹤18 自動追蹤

20 20

21Claude Code 追蹤由其檔案編輯工具所做的所有變更：21Claude Code 追蹤由其檔案編輯工具所做的所有變更：

22 22

~~23* 每個使用者提示都會建立一個新的 checkpoint~~23* 每個使用者提示開始一個回合都會建立一個新的 checkpoint

24* Claude Code 在一個會話中保留最近 100 個 checkpoint 的檔案快照。捨棄較舊的 checkpoint 會刪除沒有其他 checkpoint 參考的快照檔案，除了每個檔案的第一個快照，VS Code 擴充功能將其用作會話差異的基準。24* Claude Code 在一個會話中保留最近 100 個 checkpoint 的檔案快照。捨棄較舊的 checkpoint 會刪除沒有其他 checkpoint 參考的快照檔案，除了每個檔案的第一個快照，VS Code 擴充功能將其用作會話差異的基準。

25* Claude Code 將 checkpoints 與對話一起儲存，因此您可以在恢復會話後仍然執行 `/rewind`25* Claude Code 將 checkpoints 與對話一起儲存，因此您可以在恢復會話後仍然執行 `/rewind`

26* Claude Code 在[保留掃描](/docs/zh-TW/claude-directory#cleaned-up-automatically)中刪除會話的檔案快照，預設情況下約在會話最後一次儲存後 30 天。回溯到快照已消失的 checkpoint 可能會失敗，並出現 [`No files were restored`](/docs/zh-TW/errors#no-files-were-restored) 錯誤。若要保留快照更久，請設定 [`cleanupPeriodDays`](/docs/zh-TW/settings-reference#cleanupperioddays)。26* Claude Code 在[保留掃描](/docs/zh-TW/claude-directory#cleaned-up-automatically)中刪除會話的檔案快照，預設情況下約在會話最後一次儲存後 30 天。回溯到快照已消失的 checkpoint 可能會失敗，並出現 [`No files were restored`](/docs/zh-TW/errors#no-files-were-restored) 錯誤。若要保留快照更久，請設定 [`cleanupPeriodDays`](/docs/zh-TW/settings-reference#cleanupperioddays)。

35 如果提示輸入包含文字，雙 `Esc` 會清除它而不是開啟選單。清除的文字會儲存到您的輸入歷史記錄中，因此在您完成回溯選單後，按 `Up` 可以召回它。35 如果提示輸入包含文字，雙 `Esc` 會清除它而不是開啟選單。清除的文字會儲存到您的輸入歷史記錄中，因此在您完成回溯選單後，按 `Up` 可以召回它。

36</Note>36</Note>

37 37

~~38回溯選單列出您在會話期間傳送的每個提示。選擇您想要操作的點，然後選擇一個動作：~~38回溯選單列出您在會話期間傳送的每個提示，除了[在回合中途傳送的訊息](#messages-sent-mid-turn-not-checkpointed)。選擇您想要操作的點，然後選擇一個動作：

39 39

40* **恢復程式碼和對話**：將程式碼和對話都回復到該點40* **恢復程式碼和對話**：將程式碼和對話都回復到該點

41* **恢復對話**：回溯到該訊息，同時保持目前程式碼41* **恢復對話**：回溯到該訊息，同時保持目前程式碼

110 110

111Checkpointing 只追蹤在目前會話中已編輯的檔案。您在 Claude Code 外部對檔案所做的手動變更以及來自其他並行會話的編輯通常不會被捕捉，除非它們碰巧修改與目前會話相同的檔案。111Checkpointing 只追蹤在目前會話中已編輯的檔案。您在 Claude Code 外部對檔案所做的手動變更以及來自其他並行會話的編輯通常不會被捕捉，除非它們碰巧修改與目前會話相同的檔案。

112 112

113<h3 id="messages-sent-mid-turn-not-checkpointed">

114 訊息在回合中途傳送未進行檢查點

115</h3>

116

117當您[在 Claude 工作時排隊的訊息](/docs/zh-TW/interactive-mode#queue-messages-while-claude-works)在執行中的回合內到達 Claude 時，它會加入該回合而不是開始新的回合。訊息會出現在對話中，但 Claude Code 不會為其建立檢查點，回溯功能表也不會列出它。Claude Code 作為其自己的回合傳送的排隊訊息會照常獲得檢查點。

118

119若要移除此類訊息，或撤銷 Claude 在其後所做的編輯，請回溯到開始該回合的提示。這會回溯整個回合，包括 Claude 在您的訊息到達之前所做的工作。

120

113<h3 id="symlinked-and-hard-linked-paths-not-restored">121<h3 id="symlinked-and-hard-linked-paths-not-restored">

114 符號連結和硬連結路徑未復原122 符號連結和硬連結路徑未復原

115</h3>123</h3>

claude-apps-gateway.md +9 −4

Details

285}285}

286```286```

287 287

288開發人員按 Enter 進行連接。[首次連接 TLS 指紋提示](#connect-developers)仍然出現。288開發人員按 Enter 進行連接。[首次連接 TLS 指紋提示](#connect-developers)仍然出現。一旦檔案在機器上，未完成閘道登入的開發人員會看到[管理員原則要求雲端閘道登入](/docs/zh-TW/errors#administrator-policy-requires-a-cloud-gateway-sign-in)下所述的其中一則訊息。透過環境變數（例如 `CLAUDE_CODE_USE_BEDROCK`）選擇雲端提供商的開發人員不需要閘道登入。

289 289

290開發人員無法手動設定此項。登入選擇器中沒有閘道選項，`forceLoginGatewayUrl` 在開發人員自己的設定檔中被忽略。`forceLoginMethod` 單獨，沒有 URL，將開發人員留在「聯絡您的 IT 管理員」訊息處。登入金鑰應該在您推送到機器的檔案中，而不是在閘道的 `managed.policies[].cli` 區塊中，該區塊僅到達已連接的用戶端。290開發人員無法手動設定此項。登入選擇器中沒有閘道選項，`forceLoginGatewayUrl` 在開發人員自己的設定檔中被忽略。`forceLoginMethod` 單獨，沒有 URL，將開發人員留在「聯絡您的 IT 管理員」訊息處。登入金鑰應該在您推送到機器的檔案中，而不是在閘道的 `managed.policies[].cli` 區塊中，該區塊僅到達已連接的用戶端。

291 291

421這些保證適用於每個透過 `/login` 登入的會話。Claude Desktop 啟動的嵌入式會話按[將原則傳遞給 Claude Desktop 會話](#deliver-policy-to-claude-desktop-sessions)中所述獲取其原則，遙測項目說明其匯出的去向。421這些保證適用於每個透過 `/login` 登入的會話。Claude Desktop 啟動的嵌入式會話按[將原則傳遞給 Claude Desktop 會話](#deliver-policy-to-claude-desktop-sessions)中所述獲取其原則，遙測項目說明其匯出的去向。

422 422

423* **模型存取**：對於原則不授予的模型的請求返回 400，`/model` 選擇器被篩選為原則的 `availableModels` 允許清單。在原則中設定 [`enforceAvailableModels: true`](/docs/zh-TW/model-config#default-model-behavior)，以便預設選項解析為 `availableModels` 內的模型，而不是 Claude Code 的內建預設值；沒有它，預設保持可選擇，如果該模型未被授予，則在請求時被拒絕。423* **模型存取**：對於原則不授予的模型的請求返回 400，`/model` 選擇器被篩選為原則的 `availableModels` 允許清單。在原則中設定 [`enforceAvailableModels: true`](/docs/zh-TW/model-config#default-model-behavior)，以便預設選項解析為 `availableModels` 內的模型，而不是 Claude Code 的內建預設值；沒有它，預設保持可選擇，如果該模型未被授予，則在請求時被拒絕。

424* **遙測目的地**：在透過 `/login` 登入的會話中，CLI 將其 OTLP/HTTP 匯出傳送到閘道，無論任何本地設定的 `OTEL_EXPORTER_OTLP_ENDPOINT`，閘道將它們轉發到 [`telemetry.forward_to`](/docs/zh-TW/claude-apps-gateway-config#telemetry) 中的目的地。在[Claude Desktop 啟動](#connect-claude-desktop)的嵌入式會話中，CLI 將其匯出傳送到配置的 `OTEL_EXPORTER_OTLP_ENDPOINT`。CLI 僅當該端點指向閘道本身時才將閘道會話令牌附加到這些匯出。沒有為信號配置目的地時，閘道接受並丟棄它，因此如果您已經直接收集 Claude Code 遙測，將您的收集器新增為 `forward_to` 目的地。424* **遙測目的地**：在透過 `/login` 登入的會話中，CLI 將其 OTLP/HTTP 匯出傳送到閘道，而不是本地設定的 `OTEL_EXPORTER_OTLP_ENDPOINT`，除非原則[將您的收集器命名為端點](/docs/zh-TW/claude-apps-gateway-config#export-directly-to-your-collector)。閘道將它接收的匯出轉發到 [`telemetry.forward_to`](/docs/zh-TW/claude-apps-gateway-config#telemetry) 中的目的地。

425* **認證**：閘道令牌是會話的唯一認證。`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_API_KEY`、`apiKeyHelper`、[Anthropic 設定檔](/docs/zh-TW/authentication#anthropic-profiles-and-federation-credentials)和任何較早的 claude.ai 登入在登入時被忽略，因此開發人員不需要先登出 claude.ai。425 * 在[Claude Desktop 啟動](#connect-claude-desktop)的嵌入式會話中，CLI 將其匯出傳送到配置的 `OTEL_EXPORTER_OTLP_ENDPOINT`。CLI 僅當該端點指向閘道本身時才將閘道會話令牌附加到這些匯出。

426 * 沒有為信號配置目的地時，閘道接受並丟棄它。

427 * 如果您已經直接收集 Claude Code 遙測，將您的收集器新增為 `forward_to` 目的地，或在原則中命名它以跳過轉發。

428* **認證**：閘道令牌是會話的唯一認證。[Anthropic 設定檔](/docs/zh-TW/authentication#anthropic-profiles-and-federation-credentials)和任何較早的 claude.ai 登入在登入時被忽略，因此開發人員不需要先登出 claude.ai。對於配置的 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 認證，請參閱[管理員原則要求雲端閘道登入](/docs/zh-TW/errors#administrator-policy-requires-a-cloud-gateway-sign-in)。

426* **受管設定**：鎖定的金鑰無法在本地覆蓋。CLI 在啟動時應用原則，並在每個每小時輪詢時應用變更，除了[僅在下次啟動時應用的變更](/docs/zh-TW/server-managed-settings#fetch-and-caching-behavior)。429* **受管設定**：鎖定的金鑰無法在本地覆蓋。CLI 在啟動時應用原則，並在每個每小時輪詢時應用變更，除了[僅在下次啟動時應用的變更](/docs/zh-TW/server-managed-settings#fetch-and-caching-behavior)。

427* **閘道無法到達時啟動**：已登入的會話在啟動時約 10 秒後以錯誤退出，而不是在沒有其設定的情況下啟動。430* **閘道無法到達時啟動**：已登入的會話在啟動時約 10 秒後以錯誤退出，而不是在沒有其設定的情況下啟動。

428* **閘道結束會話後啟動**：請參閱[強制執行故障關閉啟動](/docs/zh-TW/server-managed-settings#enforce-fail-closed-startup)，了解哪些啟動在登出閘道的情況下開啟，哪些在閘道以 `401` 回答時退出。431* **閘道結束會話後啟動**：請參閱[強制執行故障關閉啟動](/docs/zh-TW/server-managed-settings#enforce-fail-closed-startup)，了解哪些啟動在登出閘道的情況下開啟，哪些在閘道以 `401` 回答時退出。

452| 按使用者和按群組支出限制 | 可用 | 請參閱[支出限制](/docs/zh-TW/claude-apps-gateway-spend-limits) |455| 按使用者和按群組支出限制 | 可用 | 請參閱[支出限制](/docs/zh-TW/claude-apps-gateway-spend-limits) |

453| 伺服器端網路搜尋 | 不可用 | CLI 無法看到閘道路由到的上游提供商，因此無法驗證網路搜尋支援並在閘道會話上禁用 WebSearch |456| 伺服器端網路搜尋 | 不可用 | CLI 無法看到閘道路由到的上游提供商，因此無法驗證網路搜尋支援並在閘道會話上禁用 WebSearch |

454| [Remote Control](/docs/zh-TW/remote-control) | 不可用 | CLI 顯示[命名閘道的錯誤](/docs/zh-TW/errors#remote-control-requires-the-anthropic-api) |457| [Remote Control](/docs/zh-TW/remote-control) | 不可用 | CLI 顯示[命名閘道的錯誤](/docs/zh-TW/errors#remote-control-requires-the-anthropic-api) |

455| 標準提示快取 | 可用 | 閘道將 `cache_control` 斷點轉發到每個上游，CLI 標記[系統內容，它在對話中途附加](/docs/zh-TW/prompt-caching#where-the-cache-lives)以在閘道會話上進行快取，就像在其他每個提供商和連接上一樣。 |458| [`/design-sync`](/docs/zh-TW/commands#all-commands) 和 `/design-login` | 不可用 | 兩者都需要 claude.ai，CLI 在閘道會話上不聯絡，因此兩個命令都不會出現 |

459| 需要功能旗標擷取的功能，例如 `/import` 和 `claude import` | 不可用 | CLI 在閘道會話上跳過旗標擷取。[需要功能旗標擷取的功能](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)列出關閉的內容 |

460| 標準提示快取 | 可用 | 閘道將 `cache_control` 斷點轉發到每個上游。[快取位置](/docs/zh-TW/prompt-caching#where-the-cache-lives)涵蓋 CLI 標記的區塊，包括它在對話中途附加的系統內容 |

456| 1 小時快取 TTL | 不可用 | CLI 在閘道會話上省略擴展快取 TTL 測試版，因為並非閘道可以路由到的每個上游都支援 1 小時 TTL，因此透過閘道的提示快取使用 5 分鐘 TTL；請參閱上面的測試版標頭備註 |461| 1 小時快取 TTL | 不可用 | CLI 在閘道會話上省略擴展快取 TTL 測試版，因為並非閘道可以路由到的每個上游都支援 1 小時 TTL，因此透過閘道的提示快取使用 5 分鐘 TTL；請參閱上面的測試版標頭備註 |

457| 自動模式 | 可用 | 遵循[第三方提供商規則](/docs/zh-TW/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)：只有第三方提供商上符合條件的模型可以使用它。在 v2.1.207 之前，閘道會話上的自動模式需要設定 `CLAUDE_CODE_ENABLE_AUTO_MODE=1`，可透過受管原則 `env` 區塊傳遞 |462| 自動模式 | 可用 | 遵循[第三方提供商規則](/docs/zh-TW/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)：只有第三方提供商上符合條件的模型可以使用它。在 v2.1.207 之前，閘道會話上的自動模式需要設定 `CLAUDE_CODE_ENABLE_AUTO_MODE=1`，可透過受管原則 `env` 區塊傳遞 |

458| 僅限第一方的最佳化，例如全域快取範圍和令牌高效工具 | 不可用 | CLI 在閘道會話上不啟用它們；請參閱上面的測試版標頭備註 |463| 僅限第一方的最佳化，例如全域快取範圍和令牌高效工具 | 不可用 | CLI 在閘道會話上不啟用它們；請參閱上面的測試版標頭備註 |

claude-apps-gateway-deploy.md +14 −5

Details

62 62

63此處的每個生產拓撲都在純 HTTP 副本前面放置 L7 代理，例如 Ingress、Cloud Run 的前端或 ALB。設定 [`listen.trusted_proxies`](/docs/zh-TW/claude-apps-gateway-config#listen) 為代理的來源範圍，以便閘道從 `X-Forwarded-For` 讀取用戶端 IP。閘道只在 TCP 對等體受信任時才遵守標頭。[Google Cloud](/docs/zh-TW/claude-apps-gateway-on-gcp) 和 [AWS](/docs/zh-TW/claude-apps-gateway-on-aws) 實際工作範例為每個拓撲提供具體值。沒有受信任的代理，每個請求似乎都來自代理的 IP，這會將按 IP 速率限制摺疊為一個共享桶，並在審計事件中記錄代理的 IP。63此處的每個生產拓撲都在純 HTTP 副本前面放置 L7 代理，例如 Ingress、Cloud Run 的前端或 ALB。設定 [`listen.trusted_proxies`](/docs/zh-TW/claude-apps-gateway-config#listen) 為代理的來源範圍，以便閘道從 `X-Forwarded-For` 讀取用戶端 IP。閘道只在 TCP 對等體受信任時才遵守標頭。[Google Cloud](/docs/zh-TW/claude-apps-gateway-on-gcp) 和 [AWS](/docs/zh-TW/claude-apps-gateway-on-aws) 實際工作範例為每個拓撲提供具體值。沒有受信任的代理，每個請求似乎都來自代理的 IP，這會將按 IP 速率限制摺疊為一個共享桶，並在審計事件中記錄代理的 IP。

64 64

65不要將請求重新導向到閘道的裝置授權和權杖端點。Claude Code 不會在這些請求上跟隨重新導向，因此重新導向它們的 Ingress 規則（例如 HTTP 到 HTTPS 或主機規範化重寫）會破壞登入和權杖重新整理。65不要將請求重新導向到閘道的裝置授權和權杖端點，例如使用 HTTP 到 HTTPS 或主機規範化重寫在 Ingress 處。Claude Code 不會在這些請求上跟隨重新導向，因此重新導向它們的 Ingress 規則會破壞登入和權杖重新整理。

66 66

67給代理任何閒置逾時時間長於閘道的保活間隔，這取決於上游：67給代理任何閒置逾時時間長於閘道的保活間隔，這取決於上游：

68 68

120 將閘道 URL 推送到開發人員機器120 將閘道 URL 推送到開發人員機器

121</h3>121</h3>

122 122

123一旦閘道開始提供服務，透過受管設定、MDM 或直接寫入各個 OS `managed-settings.json` 將 `forceLoginMethod`、`forceLoginGatewayUrl` 和 `parentSettingsBehavior: "merge"` 推送到每個開發人員的機器。沒有這個，`/login` 顯示標準帳戶選擇器，沒有閘道選項。請參閱 [用戶端受管設定](/docs/zh-TW/claude-apps-gateway-config#client-side-managed-settings) 以取得檔案路徑和 Claude Desktop `bootstrapUrl` 等效項。123一旦閘道開始提供服務，透過受管設定、MDM 或直接寫入各個 OS `managed-settings.json` 將 `forceLoginMethod`、`forceLoginGatewayUrl` 和 `parentSettingsBehavior: "merge"` 推送到每個開發人員的機器。沒有這個，`/login` 顯示標準帳戶選擇器，沒有閘道選項。

124

125一旦您部署金鑰，Claude Code 就會停止在機器上使用剩餘的 API 金鑰或 claude.ai 登入，因此請將推送與您的登入指示一起規劃。[管理員原則需要 Cloud 閘道登入](/docs/zh-TW/errors#administrator-policy-requires-a-cloud-gateway-sign-in)描述開發人員看到的訊息。

126

127請參閱 [每個機制儲存原則的位置](/docs/zh-TW/managed-settings#where-each-mechanism-stores-the-policy) 以取得檔案路徑，以及 [用戶端受管設定](/docs/zh-TW/claude-apps-gateway-config#client-side-managed-settings) 以取得 Claude Desktop `bootstrapUrl` 等效項。

124 128

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

126 運營130 運營

136 140

137* **審計事件**：每個安全相關事件的單行 JSON。將 stderr 管道傳輸到您的日誌聚合器。發出的事件包括 `config.load`、`session.mint`、`session.refresh`、`device.authorize`、`device.verify`、`device.callback`、`auth.denied`、`access.denied`、`inference`、`managed.serve`、`desktop_bootstrap.serve`、`desktop_bootstrap.denied`、`spend.blocked`、`admin.denied`、`admin.limit.upsert` 和 `admin.limit.delete`。欄位因事件而異：141* **審計事件**：每個安全相關事件的單行 JSON。將 stderr 管道傳輸到您的日誌聚合器。發出的事件包括 `config.load`、`session.mint`、`session.refresh`、`device.authorize`、`device.verify`、`device.callback`、`auth.denied`、`access.denied`、`inference`、`managed.serve`、`desktop_bootstrap.serve`、`desktop_bootstrap.denied`、`spend.blocked`、`admin.denied`、`admin.limit.upsert` 和 `admin.limit.delete`。欄位因事件而異：

138 * 成功的 mint 和 refresh 事件攜帶 `sub`、`email`、`client_ip` 和結果142 * 成功的 mint 和 refresh 事件攜帶 `sub`、`email`、`client_ip` 和結果

139 * `auth.denied` 和 `access.denied` 攜帶原因和用戶端 IP，加上 `auth.denied` 的請求路徑，因為在這些拒絕時不存在使用者身份143 * `auth.denied` 和 `access.denied` 攜帶原因和用戶端 IP，加上 `auth.denied` 的請求路徑，因為在這些拒絕時不存在使用者身份。兩個 `access.denied` 原因改變事件攜帶的內容：

144 * `xff_unparseable`：事件也攜帶無法讀取的 `X-Forwarded-For` 項目

145 * `client_ip_unknown`：事件不攜帶用戶端 IP，因為連線沒有對等位址，而設定了 `access_control` 清單

140 * `inference` 記錄哪個上游提供了請求以及回應狀態146 * `inference` 記錄哪個上游提供了請求以及回應狀態

141 * `desktop_bootstrap.denied` 記錄被拒絕的 Claude Desktop bootstrap 擷取，包含原因（`not_configured`、`policy_not_opted_in` 或 `no_policy_matched`）和使用者的身份147 * `desktop_bootstrap.denied` 記錄被拒絕的 Claude Desktop bootstrap 擷取，包含原因（`not_configured`、`policy_not_opted_in` 或 `no_policy_matched`）和使用者的身份

142 * `admin.denied` 記錄被拒絕的管理員 API 驗證嘗試，包括用戶端 IP、方法、路徑和原因，不包括呈現的金鑰材料：當呈現了 `x-api-key` 但與沒有配置的金鑰相符時為 `invalid_key`，當只呈現了 `Authorization` 標頭且它未驗證為 `admin.admin_groups` 中的閘道會話時為 `bearer_rejected`，或當兩個標頭都未呈現時為 `no_credentials`148 * `admin.denied` 記錄被拒絕的管理員 API 驗證嘗試，包括用戶端 IP、方法、路徑和原因，不包括呈現的金鑰材料：當呈現了 `x-api-key` 但與沒有配置的金鑰相符時為 `invalid_key`，當只呈現了 `Authorization` 標頭且它未驗證為 `admin.admin_groups` 中的閘道會話時為 `bearer_rejected`，或當兩個標頭都未呈現時為 `no_credentials`

274閘道的 stderr 包含審計事件串流，審計日誌記錄開發人員身分，除錯檔案記錄來自開發人員機器的 hook 和 MCP 伺服器輸出。在發佈到公開議題之前，請檢查並隱蔽這些資訊。280閘道的 stderr 包含審計事件串流，審計日誌記錄開發人員身分，除錯檔案記錄來自開發人員機器的 hook 和 MCP 伺服器輸出。在發佈到公開議題之前，請檢查並隱蔽這些資訊。

275 281

276| 症狀 | 原因 | 修復 |282| 症狀 | 原因 | 修復 |

277| ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |283| ------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

278| 開發人員的 `/login` 顯示標準帳戶選擇器而不是 **Cloud 閘道** 螢幕 | `forceLoginMethod` 或 `forceLoginGatewayUrl` 未在該機器上的受管設定中設定 | 將 [受管設定檔案](/docs/zh-TW/claude-apps-gateway#set-the-gateway-url) 部署到設備；`/login` 從那裡讀取閘道 URL |284| 開發人員的 `/login` 顯示標準帳戶選擇器而不是 **Cloud 閘道** 螢幕 | `forceLoginMethod` 或 `forceLoginGatewayUrl` 未在該機器上的受管設定中設定 | 將 [受管設定檔案](/docs/zh-TW/claude-apps-gateway#set-the-gateway-url) 部署到設備；`/login` 從那裡讀取閘道 URL |

285| 開發人員的請求失敗，顯示 `Not signed in to the Cloud gateway — run /login.` | 機器的受管設定設定 `forceLoginMethod: "gateway"` 或 `forceLoginGatewayUrl`，且會話沒有閘道簽入。剩餘的 claude.ai 登入不滿足要求。 | 讓開發人員執行 `/login` 並完成閘道簽入。另請參閱 [管理員原則需要 Cloud 閘道簽入](/docs/zh-TW/errors#administrator-policy-requires-a-cloud-gateway-sign-in)。 |

279| Claude Desktop 報告其啟動程序設定無法擷取 | `/user/bootstrap` 傳回 404：符合使用者的原則不包含 `desktop` 金鑰，或沒有原則符合。閘道的審計日誌將每個拒絕記錄為 `desktop_bootstrap.denied`，並附上原因。 | 將 `desktop` 區塊新增到符合使用者的原則，或新增到 `match: {}` 基礎層；空的 `desktop: {}` 就足夠了。請參閱 [Claude Desktop 覆蓋](/docs/zh-TW/claude-apps-gateway-config#claude-desktop-overlay)。 |286| Claude Desktop 報告其啟動程序設定無法擷取 | `/user/bootstrap` 傳回 404：符合使用者的原則不包含 `desktop` 金鑰，或沒有原則符合。閘道的審計日誌將每個拒絕記錄為 `desktop_bootstrap.denied`，並附上原因。 | 將 `desktop` 區塊新增到符合使用者的原則，或新增到 `match: {}` 基礎層；空的 `desktop: {}` 就足夠了。請參閱 [Claude Desktop 覆蓋](/docs/zh-TW/claude-apps-gateway-config#claude-desktop-overlay)。 |

280| 啟動顯示 `Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support.` | 已安裝的 Claude Code 建置早於閘道支援 | 讓開發人員更新 Claude Code 到包含 Cloud 閘道支援的版本 |287| 啟動顯示 `Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support.` | 已安裝的 Claude Code 建置早於閘道支援 | 讓開發人員更新 Claude Code 到包含 Cloud 閘道支援的版本 |

288| 啟動或 `/login` 在受管設定載入上報告 `Claude Code may not be enabled for your organization` 後出現 403 | 閘道或其前面的某些東西以 403 回應 `/managed/settings` 請求。閘道自己的設定路由永遠不會回應 403。狀態來自 [`access_control`](/docs/zh-TW/claude-apps-gateway-config#http-tuning) IP 檢查或閘道前面的代理或 WAF。審計日誌將 IP 檢查拒絕記錄為 `access.denied`，並附上原因。開發人員保持簽入。 | 檢查審計日誌中失敗時的 `access.denied` 並修復 `access_control` 清單或前端，然後讓開發人員再次啟動 `claude` |

281| CLI `/login`：`Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | 閘道主機名解析為至少一個公開 IP 地址。Claude Code 檢查每個解析的地址，並要求每個都是私有的。常見原因是雙堆棧名稱，其中一個系列解析為公開地址，包括 AWS 內部雙堆棧負載平衡器，它們傳回公開範圍 AAAA 地址。 | 讓閘道名稱在開發人員機器上只解析為私有地址。對於雙堆棧名稱，刪除公開範圍記錄或提供單獨的僅內部 DNS 名稱。請參閱 [私有網路先決條件](/docs/zh-TW/claude-apps-gateway#prerequisites)。 |289| CLI `/login`：`Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | 閘道主機名解析為至少一個公開 IP 地址。Claude Code 檢查每個解析的地址，並要求每個都是私有的。常見原因是雙堆棧名稱，其中一個系列解析為公開地址，包括 AWS 內部雙堆棧負載平衡器，它們傳回公開範圍 AAAA 地址。 | 讓閘道名稱在開發人員機器上只解析為私有地址。對於雙堆棧名稱，刪除公開範圍記錄或提供單獨的僅內部 DNS 名稱。請參閱 [私有網路先決條件](/docs/zh-TW/claude-apps-gateway#prerequisites)。 |

282| CLI `/login`：`Gateway login would go through proxy <proxy>, which is not on a private network` | `HTTPS_PROXY` 或 `HTTP_PROXY` 適用於閘道主機，代理的主機名解析為公開地址。代理的主機解析為僅私有地址是允許的，不會觸發此錯誤 | 在開發人員的機器上將閘道主機新增到 `NO_PROXY`，以便連接是直接的，或使用主機名解析為私有地址的代理。訊息會命名要新增的確切 `NO_PROXY` 項目 |290| CLI `/login`：`Gateway login would go through proxy <proxy>, which is not on a private network` | `HTTPS_PROXY` 或 `HTTP_PROXY` 適用於閘道主機，代理的主機名解析為公開地址。代理的主機解析為僅私有地址是允許的，不會觸發此錯誤 | 在開發人員的機器上將閘道主機新增到 `NO_PROXY`，以便連接是直接的，或使用主機名解析為私有地址的代理。訊息會命名要新增的確切 `NO_PROXY` 項目 |

289| `/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`。 |297| `/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`。 |

290| 日誌：`token exchange failed request_id=<id>: 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`。 |298| 日誌：`token exchange failed request_id=<id>: 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`。 |

299| 日誌：`refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …)`，開發人員每 `session.ttl_hours` 看到 `Cloud gateway session expired` | IdP 接受了重新整理令牌但沒有隨之傳回 id\_token，所以閘道詢問 IdP 的 userinfo 端點以取得使用者的聲明。IdP 在那裡拒絕了重新整理的存取令牌。閘道回應 `temporarily_unavailable`，所以 Claude Code 保留重新整理令牌但無法更新會話。v2.1.260 之前的閘道版本記錄相同行但沒有 `(at …)` 詳細資訊。 | 設定 [`oidc.scope_on_refresh: true`](/docs/zh-TW/claude-apps-gateway-config#oidc)，在閘道 v2.1.260 或更新版本中可用，以便重新整理請求再次要求 `openid`。某些 IdP（例如 Okta）僅在被要求時才在重新整理時傳回 id\_token。在 PingFederate 上，改為在 **Applications > OAuth > OpenID Connect Policy Management** 下啟用 **Return ID Token On Refresh Grant**。該金鑰不會改變 PingFederate 的行為。對於仍然省略它的其他 IdP，檢查 userinfo 端點是否接受由重新整理發行的存取令牌。作為臨時解決方案，提高 [`session.ttl_hours`](/docs/zh-TW/claude-apps-gateway-config#session)。請參閱 [身分提供者設定](#identity-provider-setup) 以了解取消佈建權衡。 |

291| 每個 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 容器認證端點讀取認證，完全避免變更，或在專用閘道實例上應用變更以限制暴露。 |300| 每個 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 容器認證端點讀取認證，完全避免變更，或在專用閘道實例上應用變更以限制暴露。 |

300| CLI `/login` 完成瀏覽器簽入，然後會話以 `Cloud gateway sign-in was not completed` 和 TLS 憑證不匹配結束 | 在簽入後的第一個請求上，閘道提供了與 Claude Code 固定的指紋不符的憑證，所以 Claude Code 沒有保留任何閘道認證。常見原因是一個地址後面的副本提供不同的憑證，或網路路徑上的某些東西攔截 TLS。 | 為主機名提供一個憑證，例如在 ingress 終止 TLS 一次，然後讓開發人員再次執行 `/login`。如果該憑證與固定的不同，Claude Code 會在 [信任提示](/docs/zh-TW/claude-apps-gateway#connect-developers) 上顯示警告，指出憑證已變更。 |309| CLI `/login` 完成瀏覽器簽入，然後會話以 `Cloud gateway sign-in was not completed` 和 TLS 憑證不匹配結束 | 在簽入後的第一個請求上，閘道提供了與 Claude Code 固定的指紋不符的憑證，所以 Claude Code 沒有保留任何閘道認證。常見原因是一個地址後面的副本提供不同的憑證，或網路路徑上的某些東西攔截 TLS。 | 為主機名提供一個憑證，例如在 ingress 終止 TLS 一次，然後讓開發人員再次執行 `/login`。如果該憑證與固定的不同，Claude Code 會在 [信任提示](/docs/zh-TW/claude-apps-gateway#connect-developers) 上顯示警告，指出憑證已變更。 |

301| CLI `/login` 停止，顯示 `The gateway's TLS certificate changed during sign-in: it no longer matches the one you trusted` | 簽入請求到達一個伺服器，其憑證與開發人員在 `/login` 開始時接受的不符：一個地址後面的副本提供不同的憑證、路徑上的 TLS 攔截，或簽入進行中的憑證輪換。 | 為主機名提供一個憑證，然後讓開發人員再次開始簽入，並在 [信任提示](/docs/zh-TW/claude-apps-gateway#connect-developers) 上檢查新憑證。 |310| CLI `/login` 停止，顯示 `The gateway's TLS certificate changed during sign-in: it no longer matches the one you trusted` | 簽入請求到達一個伺服器，其憑證與開發人員在 `/login` 開始時接受的不符：一個地址後面的副本提供不同的憑證、路徑上的 TLS 攔截，或簽入進行中的憑證輪換。 | 為主機名提供一個憑證，然後讓開發人員再次開始簽入，並在 [信任提示](/docs/zh-TW/claude-apps-gateway#connect-developers) 上檢查新憑證。 |

302 311

303`Cloud gateway sign-in was not completed` 訊息命名閘道主機名，以及當 Claude Code 有兩個指紋時，固定指紋的前 16 個字元和提供的指紋。312`Cloud gateway sign-in was not completed` 訊息命名閘道主機名。當 Claude Code 有兩個指紋時，訊息也會顯示每個的前 16 個字元。

304 313

305如果 Claude Code 在閘道簽入後報告 `couldn't load your organization's managed settings`，Claude Code 會命名原因、就地重新啟動並繼續對話。如果 Claude Code 無法重新啟動，例如在背景會話中，Claude Code 會結束會話並保留簽入。314如果 Claude Code 在閘道簽入後報告 `couldn't load your organization's managed settings`，Claude Code 會命名原因、就地重新啟動並繼續對話。如果 Claude Code 無法重新啟動，例如在背景會話中，Claude Code 會結束會話並保留簽入。

306 315

claude-apps-gateway-on-aws.md +553 −0 created

Details

1> ## Documentation Index

2> 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.

5# 在 AWS 上部署 Claude apps gateway

7> 在 AWS 上執行 Claude apps gateway 的實際範例：ECS Fargate 或 EKS、Amazon RDS for PostgreSQL、AWS Secrets Manager 和 IAM 角色驗證至 Amazon Bedrock。

9<Note>

10 本頁面介紹在 AWS 上執行 Claude apps gateway 的一種方式。此設定是客戶管理基礎設施的實際運作範例，而非受支援的生產部署；在將其調整至您自己的環境之前，請使用它來了解各個部分如何組合在一起。如需平台無關的需求，請參閱[部署指南](/docs/zh-TW/claude-apps-gateway-deploy)。

11</Note>

13此範例在 AWS 上佈建 Claude apps gateway，使用 Amazon Bedrock 作為模型上游，並使用 [Amazon ECS](https://aws.amazon.com/ecs/) on [AWS Fargate](https://aws.amazon.com/fargate/) 或 [Amazon EKS](https://aws.amazon.com/eks/) 進行計算。[Okta](https://www.okta.com/) 是範例身份提供者 (IdP)，但任何符合 OpenID Connect (OIDC) 的 IdP 都可以使用；有關各個 IdP 的詳細資訊，請參閱[身份提供者設定](/docs/zh-TW/claude-apps-gateway-deploy#identity-provider-setup)。

15<Note>

16 Bedrock 不是 AWS 上唯一的 Claude 上游。gateway 也支援 Claude Platform on AWS，這是 Anthropic 營運的 Claude API，具有 AWS 驗證和 AWS Marketplace 計費，可以代替 Bedrock 或與其並行使用。其上游項目、認證和 IAM 權限與本頁面的 Bedrock 範圍的不同；[Claude Platform on AWS 上游參考](/docs/zh-TW/claude-apps-gateway-config#claude-platform-on-aws)涵蓋了哪些內容會改變，本頁面的其餘部分保持不變。

17</Note>

19<h2 id="architecture">

20 架構

21</h2>

23<Frame caption="範例架構，以 Amazon Bedrock 作為模型上游。Claude Platform on AWS 上游佔據相同位置。">

24 <img src="https://mintcdn.com/claude-code/PHweeRmDUYEKff49/images/claude-gateway-aws-architecture.svg?fit=max&auto=format&n=PHweeRmDUYEKff49&q=85&s=8599cc34aa28522cde208ee831439bb4" alt="AWS 上 Claude apps gateway 的圖表：Claude Code 客戶端透過 HTTPS 連接到內部應用程式負載平衡器，該平衡器位於 gateway（ECS Fargate 或 EKS）前面，gateway 在私有子網中執行，旁邊是用於工作階段狀態的 Amazon RDS for PostgreSQL 實例。gateway 透過 OIDC 讓使用者登入公司 IdP，從 AWS Secrets Manager 讀取機密，使用其 IAM 角色將模型請求轉發至 Amazon Bedrock，並在部署時從 Amazon ECR 提取其映像。" width="820" height="430" data-path="images/claude-gateway-aws-architecture.svg" />

25</Frame>

27gateway 在您的網路上作為私有 HTTPS 端點執行，開發人員透過您的 IdP 登入。他們的 Claude Code 工作階段透過 gateway 的 IAM 角色到達 Amazon Bedrock 上的 Claude 模型，因此沒有模型認證會落在開發人員機器上。參考設定佈建：

29* **Amazon ECS on AWS Fargate** 服務或 **Amazon EKS** Deployment 執行 gateway 容器

30* **Amazon ECR** 儲存庫用於 gateway 映像

31* **Amazon RDS for PostgreSQL** 實例在私有子網中，不可公開存取，用於 gateway 的[儲存](/docs/zh-TW/claude-apps-gateway-config#store)

32* **AWS Secrets Manager** 機密用於 JWT 簽署金鑰、OIDC 客戶端機密和 Postgres URL

33* **IAM 角色**具有 `bedrock:InvokeModel`、`bedrock:InvokeModelWithResponseStream` 和 `bedrock:CountTokens`，附加為 ECS 任務角色或透過 EKS 上的 IAM Roles for Service Accounts (IRSA) 綁定

34* **內部應用程式負載平衡器**用於 HTTPS

36<h2 id="prerequisites">

37 先決條件

38</h2>

40此逐步解說建立 gateway 自己的資源，但它建立在您已經擁有的網路和身份基礎設施之上。在開始之前，您需要：

42* 具有建立[上述資源](#architecture)權限的 AWS 帳戶

43* 已安裝並[驗證](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-authentication.html)的 [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)，以及在本地安裝的 [Docker](https://docs.docker.com/get-started/get-docker/)

44* 一個[VPC](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html)，至少有兩個[私有子網](https://docs.aws.amazon.com/vpc/latest/userguide/configure-subnets.html)在不同的可用區中，透過[NAT 閘道](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html)具有出站網際網路存取；內部負載平衡器需要兩個 AZ 中的子網，gateway 需要到 Bedrock 和您的 IdP 的出站流量

45* 一個 Okta OIDC Web 應用程式，重新導向 URI 為 `https://<gateway-host>/oauth/callback`；請參閱[身份提供者設定](/docs/zh-TW/claude-apps-gateway-deploy#identity-provider-setup)

46* gateway 的 TLS 主機名稱，通常是[Route 53 私有託管區域](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zones-private.html)中的內部 DNS 名稱，指向負載平衡器，具有該名稱的 [ACM 憑證](https://docs.aws.amazon.com/acm/latest/userguide/gs.html)，由[AWS Private CA](https://docs.aws.amazon.com/privateca/latest/userguide/PcaWelcome.html)匯入或簽發

48<h3 id="set-your-environment-variables">

49 設定您的環境變數

50</h3>

52此頁面上的每個命令都從您的 shell 讀取四個值：`AWS_REGION`、`ACCOUNT_ID`、`VPC_ID` 和 `PRIVATE_SUBNETS`。

54選擇一個 Bedrock 提供您需要的 Claude 模型的美國區域。此逐步解說依賴 gateway 的內建模型目錄，該目錄解析為 `us.anthropic.*` 推論設定檔，IAM 原則授予這些 ARN。在非美國區域中，新增一個[`models:` 區塊](/docs/zh-TW/claude-apps-gateway-config#models)，其中包含該地理位置的推論設定檔 ID，並將 IAM 原則的 ARN 前綴更改為相符。

56如果您手邊沒有 VPC ID，請使用 `aws ec2 describe-vpcs` 列出您的 VPC，然後列出該 VPC 的子網以找到兩個不同可用區中的私有子網：

58```bash theme={null}

59aws ec2 describe-subnets --filters "Name=vpc-id,Values=<your-vpc-id>" \

60 --query 'Subnets[].{ID:SubnetId,AZ:AvailabilityZone,CIDR:CidrBlock}' --output table

61```

63在繼續之前匯出所有四個：

65```bash theme={null}

66export AWS_REGION=us-east-1 # Bedrock 提供您需要的 Claude 模型的美國區域

67export ACCOUNT_ID="$(aws sts get-caller-identity --query Account --output text)"

68export VPC_ID=<your-vpc-id>

69export PRIVATE_SUBNETS="<subnet-id-a> <subnet-id-b>"

70```

72<h2 id="deploy-the-gateway">

73 部署 gateway

74</h2>

76下面的步驟使用 `aws` 命令佈建完整部署。

78<Steps>

79 <Step title="建立安全群組">

80 三個安全群組鏈接流量路徑：您的公司網路在 443 上到達負載平衡器，負載平衡器在 8080 上到達 gateway，gateway 在 5432 上到達 Postgres。沒有其他任何東西是可到達的。您如何附加它們取決於計算軌道：

82 * 在 ECS Fargate 上，部署步驟將 `$ALB_SG` 附加到負載平衡器，將 `$GW_SG` 附加到服務。

83 * 在 EKS 上，AWS Load Balancer Controller 為 ALB 建立自己的前端安全群組，因此 `$ALB_SG` 和 `$GW_SG` 未使用：部署步驟的 `inbound-cidrs` 註釋將監聽器限制為您的公司網路，資料庫安全群組允許叢集的安全群組而不是 `$GW_SG`。

85 ```bash theme={null}

86 ALB_SG="$(aws ec2 create-security-group --group-name claude-gateway-alb \

87 --description "Claude gateway ALB" --vpc-id "$VPC_ID" \

88 --query GroupId --output text)"

89 GW_SG="$(aws ec2 create-security-group --group-name claude-gateway-svc \

90 --description "Claude gateway service" --vpc-id "$VPC_ID" \

91 --query GroupId --output text)"

92 DB_SG="$(aws ec2 create-security-group --group-name claude-gateway-db \

93 --description "Claude gateway Postgres" --vpc-id "$VPC_ID" \

94 --query GroupId --output text)"

96 aws ec2 authorize-security-group-ingress --group-id "$ALB_SG" \

97 --protocol tcp --port 443 --cidr <your-corporate-cidr>

98 aws ec2 authorize-security-group-ingress --group-id "$GW_SG" \

99 --protocol tcp --port 8080 --source-group "$ALB_SG"

100 aws ec2 authorize-security-group-ingress --group-id "$DB_SG" \

101 --protocol tcp --port 5432 --source-group "$GW_SG"

102 ```

103 </Step>

104

105 <Step title="建立 IAM 角色並提交使用案例表單">

106 gateway 使用專用任務角色執行，其唯一權限是在 Bedrock 上叫用 Claude 模型。根據 [Bedrock 上游參考](/docs/zh-TW/claude-apps-gateway-config#amazon-bedrock)，原則必須涵蓋跨區域推論設定檔 ARN 和基礎基礎模型 ARN：

107

108 ```bash theme={null}

109 cat > bedrock-invoke.json <<EOF

110 {

111 "Version": "2012-10-17",

112 "Statement": [{

113 "Effect": "Allow",

114 "Action": ["bedrock:InvokeModel", "bedrock:InvokeModelWithResponseStream", "bedrock:CountTokens"],

115 "Resource": [

116 "arn:aws:bedrock:${AWS_REGION}:${ACCOUNT_ID}:inference-profile/us.anthropic.*",

117 "arn:aws:bedrock:*::foundation-model/anthropic.*"

118 ]

119 }]

120 }

121 EOF

122 cat > ecs-trust.json <<'EOF'

123 {

124 "Version": "2012-10-17",

125 "Statement": [{

126 "Effect": "Allow",

127 "Principal": { "Service": "ecs-tasks.amazonaws.com" },

128 "Action": "sts:AssumeRole"

129 }]

130 }

131 EOF

132

133 aws iam create-role --role-name claude-gateway-task \

134 --assume-role-policy-document file://ecs-trust.json

135 aws iam put-role-policy --role-name claude-gateway-task \

136 --policy-name bedrock-invoke --policy-document file://bedrock-invoke.json

137 ```

138

139 ECS 也需要執行角色，ECS 代理本身使用它從 ECR 提取映像並注入稍後建立的 Secrets Manager 值。它與 gateway 的 AWS SDK 在執行時使用的任務角色分開：

140

141 ```bash theme={null}

142 aws iam create-role --role-name claude-gateway-execution \

143 --assume-role-policy-document file://ecs-trust.json

144 aws iam attach-role-policy --role-name claude-gateway-execution \

145 --policy-arn arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy

146 cat > secrets-read.json <<EOF

147 {

148 "Version": "2012-10-17",

149 "Statement": [{

150 "Effect": "Allow",

151 "Action": ["secretsmanager:GetSecretValue", "secretsmanager:DescribeSecret"],

152 "Resource": [

153 "arn:aws:secretsmanager:${AWS_REGION}:${ACCOUNT_ID}:secret:gateway-jwt-secret-??????",

154 "arn:aws:secretsmanager:${AWS_REGION}:${ACCOUNT_ID}:secret:gateway-oidc-client-secret-??????",

155 "arn:aws:secretsmanager:${AWS_REGION}:${ACCOUNT_ID}:secret:gateway-postgres-url-??????"

156 ]

157 }]

158 }

159 EOF

160 aws iam put-role-policy --role-name claude-gateway-execution \

161 --policy-name read-gateway-secrets --policy-document file://secrets-read.json

162 ```

163

164 原則按名稱一個 ARN 而不是裸 `gateway-*` 萬用字元，在共享帳戶中也會符合不相關的機密；尾部的 `-??????` 完全符合 Secrets Manager 附加到每個機密 ARN 的隨機六字元後綴。尾部的 `-*` 將是純前綴 glob，也會符合更長的名稱，例如 `gateway-postgres-url-prod`。

165

166 IAM 原則授予 gateway 呼叫 Bedrock 的權限，Bedrock 在商業區域中預設啟用模型存取。剩餘的帳戶級別閘道是 Anthropic 的一次性使用案例表單：如果您帳戶中沒有人提交過，請開啟 [Amazon Bedrock 主控台](https://console.aws.amazon.com/bedrock/)，從模型目錄中選擇 Anthropic 模型，並完成表單。提交後立即授予存取權；有關 AWS Organizations 表單和提交者需要的 IAM 權限，請參閱 [Claude Code on Amazon Bedrock](/docs/zh-TW/amazon-bedrock#1-submit-use-case-details)。

167

168 EKS 軌道改為在 IRSA 角色上重複使用兩個原則文件，而不是兩個 ECS 角色；請參閱部署步驟。

169 </Step>

170

171 <Step title="佈建 Amazon RDS for PostgreSQL">

172 實例在私有子網中執行，沒有公開地址，儲存加密已開啟。引擎版本固定為 Postgres 16，滿足 gateway 支援的 PostgreSQL 14 下限，並保證下面的參數群組系列與實例相符。

173

174 首先，建立將資料庫放在私有子網中的子網群組，以及具有 `rds.force_ssl=1` 的參數群組，以便伺服器拒絕純文字連接。引擎版本固定一次，因為參數群組的系列必須與實例執行的引擎主要版本相符：

175

176 ```bash theme={null}

177 aws rds create-db-subnet-group --db-subnet-group-name claude-gateway-db \

178 --db-subnet-group-description "Claude gateway" --subnet-ids $PRIVATE_SUBNETS

179

180 PG_VERSION=16

181 PG_FAMILY="postgres${PG_VERSION}"

182 aws rds create-db-parameter-group --db-parameter-group-name claude-gateway-db \

183 --db-parameter-group-family "$PG_FAMILY" \

184 --description "Claude gateway - require TLS on every connection"

185 aws rds modify-db-parameter-group --db-parameter-group-name claude-gateway-db \

186 --parameters "ParameterName=rds.force_ssl,ParameterValue=1,ApplyMethod=immediate"

187 ```

188

189 然後使用生成的主密碼建立實例：

190

191 ```bash theme={null}

192 PGPASS="$(openssl rand -hex 24)"

193 aws rds create-db-instance --db-instance-identifier claude-gateway-db \

194 --engine postgres --engine-version "$PG_VERSION" \

195 --db-instance-class db.t4g.micro \

196 --allocated-storage 20 --db-name claude_gateway \

197 --master-username gateway --master-user-password "$PGPASS" \

198 --db-subnet-group-name claude-gateway-db \

199 --db-parameter-group-name claude-gateway-db \

200 --vpc-security-group-ids "$DB_SG" \

201 --no-publicly-accessible --storage-encrypted

202 ```

203

204 字面 `--master-user-password` 引數在命令執行時在程序表和稽核/EDR 日誌中可見，與機密步驟的註釋涵蓋的相同曝露。在共享或受監控的主機上，改為從 `0600` 檔案透過 `--cli-input-json` 傳遞密碼，就像套件的 `setup.sh` 所做的那樣。

205

206 等待實例啟動，這可能需要幾分鐘，然後讀取其私有端點並組合 gateway 將使用的連接字串：

207

208 ```bash theme={null}

209 aws rds wait db-instance-available --db-instance-identifier claude-gateway-db

210 DB_HOST="$(aws rds describe-db-instances --db-instance-identifier claude-gateway-db \

211 --query 'DBInstances[0].Endpoint.Address' --output text)"

212 GATEWAY_POSTGRES_URL="postgres://gateway:${PGPASS}@${DB_HOST}:5432/claude_gateway?sslmode=verify-full"

213 ```

214

215 `sslmode=verify-full` 使 gateway 驗證 RDS 伺服器憑證的鏈和主機名稱，不僅加密。信任錨是 [AWS RDS 憑證套件](https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem)，映像建置步驟下面將其複製到 `/etc/claude/rds-global-bundle.pem` 並透過 `NODE_EXTRA_CA_CERTS` 信任。不要將 libpq 風格的 `sslrootcert=` 參數附加到 URL：gateway 的驅動程式只從查詢字串讀取 `sslmode`，並會將 `sslrootcert` 轉發給 Postgres 作為啟動參數，伺服器會拒絕。

216

217 ECS 服務或 EKS pod 必須在此 VPC 中執行，以便它們可以到達實例的私有端點，`claude-gateway-db` 安全群組只允許 gateway 的安全群組。

218 </Step>

219

220 <Step title="寫入 gateway.yaml">

221 `upstreams` 區塊使用 `auth: {}` 指向 Bedrock，因此 gateway 透過 ECS 上的任務角色或 EKS 上的 IRSA 角色從 AWS 預設認證鏈進行驗證。有關每個欄位，請參閱[設定參考](/docs/zh-TW/claude-apps-gateway-config)。

222

223 兩個 `listen` 欄位描述什麼位於 gateway 前面：

224

225 * `public_url`：外部 `https://` 來源，非環回繫結時必需；請參閱 [`listen` 參考](/docs/zh-TW/claude-apps-gateway-config#listen)。gateway 僅從此值建置 IdP `redirect_uri` 和其發現文件，絕不從 `X-Forwarded-*` 標頭建置。

226 * `trusted_proxies`：前端的來源範圍。gateway 僅當 TCP 對等體在此清單中時才接受 `X-Forwarded-For`，然後在受信任的躍點之後遍歷鏈，因此每 IP 登入速率限制和稽核事件記錄開發人員 IP 而不是負載平衡器的。

227

228 在兩個軌道上，前端都是內部 ALB，無論是直接建立還是由 AWS Load Balancer Controller 建立，ALB 的節點從其附加到的子網中取得地址，因此將 `trusted_proxies` 設定為這些子網的 CIDR。這信任這些子網中的每個主機作為代理。保持 ALB 的入站來源（您的公司 CIDR）不與它們重疊，並且不要與可能透過 `X-Forwarded-For` 欺騙客戶端 IP 的不受信任的工作負載共享子網。

229

230 ALB 的客戶端連接埠保留屬性 `routing.http.xff_client_port.enabled` 可以保持任一設定：開啟時，ALB 將客戶端寫為 `203.0.113.7:54321` 或 `[2001:db8::1]:54321`，gateway 讀取兩者並刪除連接埠。

231

232 ```yaml gateway.yaml theme={null}

233 listen:

234 host: 0.0.0.0

235 port: 8080

236 public_url: https://claude-gateway.internal.example.com

237 trusted_proxies: [<your-alb-subnet-cidrs>]

238

239 oidc:

240 issuer: https://example.okta.com

241 client_id: 0oa1example2

242 client_secret: ${OIDC_CLIENT_SECRET} # EKS: ${file:/secrets/oidc-client-secret}

243 allowed_email_domains: [example.com]

244 # Okta org 授權伺服器傳回省略電子郵件和群組的精簡 id_token；

245 # gateway 從 /userinfo 填充它們。

246 userinfo_fallback: true

247 # Okta 僅在要求 `groups` 範圍且應用程式的群組宣告篩選器允許時才發出群組。

248 scopes: [openid, profile, email, offline_access, groups]

249

250 session:

251 jwt_secret: ${GATEWAY_JWT_SECRET} # EKS: ${file:/secrets/jwt-secret}

252 ttl_hours: 8 # 限制取消佈建延遲；降低

253 # 朝向 1 以獲得更緊密的撤銷

254

255 store:

256 postgres_url: ${GATEWAY_POSTGRES_URL} # EKS: ${file:/secrets/postgres-url}

257

258 upstreams:

259 - provider: bedrock

260 region: <your-region> # 符合 $AWS_REGION 以便 IAM

261 # 原則的 ARN 涵蓋它

262 auth: {} # AWS 預設認證鏈：

263 # ECS 任務角色，或 EKS 上的 IRSA

264 ```

265

266 <Note>

267 只有 `oidc` 區塊是 Okta 特定的。若要改為使用 Microsoft Entra ID，請將 `issuer` 設定為 `https://login.microsoftonline.com/<tenant-id>/v2.0`，刪除 `userinfo_fallback` 和 `groups` 範圍，並注意 Entra 發出群組物件 ID 而不是名稱，因此 [`managed.policies`](/docs/zh-TW/claude-apps-gateway-config#managed) 必須符合 GUID，或使用 `oidc.groups_claim: roles` 的應用程式角色。請參閱[身份提供者設定](/docs/zh-TW/claude-apps-gateway-deploy#identity-provider-setup)。

268 </Note>

269 </Step>

270

271 <Step title="在 AWS Secrets Manager 中儲存機密">

272 建立三個機密；IAM 步驟中的執行角色已經可以讀取它們：

273

274 ```bash theme={null}

275 aws secretsmanager create-secret --name gateway-jwt-secret \

276 --secret-string "$(openssl rand -base64 32)"

277 aws secretsmanager create-secret --name gateway-oidc-client-secret \

278 --secret-string '<your-okta-client-secret>'

279 aws secretsmanager create-secret --name gateway-postgres-url \

280 --secret-string "$GATEWAY_POSTGRES_URL"

281 ```

282

283 注意每個呼叫列印的 ARN；ECS 任務定義按 ARN 參考機密。

284

285 <Note>

286 字面 `--secret-string` 引數在每個命令執行時在程序表和稽核/EDR 日誌中可見。在共享或受監控的主機上，將值放在 `0600` 檔案中，改為傳遞 `--secret-string file://<path>`。套件的 `setup.sh` 以相同方式將機密值保持在程序 argv 之外，將 `0600` 臨時檔案傳遞給 `--cli-input-json`。

287 </Note>

288

289 與機密不同，`gateway.yaml` 本身不包含機密值，因為每個認證在啟動時透過 [`${VAR}` 或 `${file:...}` 擴展](/docs/zh-TW/claude-apps-gateway-config#secret-expansion)解析。一切如何到達容器因軌道而異：

290

291 * 在 ECS 上，下一步的建置將 `gateway.yaml` 複製到映像中的 `/etc/claude/gateway.yaml`，任務定義透過其 `secrets` 欄位將三個機密注入為環境變數，因此 YAML 參考 `${GATEWAY_JWT_SECRET}`、`${OIDC_CLIENT_SECRET}` 和 `${GATEWAY_POSTGRES_URL}`。

292 * 在 EKS 上，從 ConfigMap 掛載 `gateway.yaml` 和機密作為 `/secrets` 中的檔案，參考為 `${file:/secrets/...}`。使用 External Secrets Operator 或 Secrets Store CSI 驅動程式的 AWS 提供者從 Secrets Manager 來源 Kubernetes Secrets，或使用 `kubectl` 直接建立它們。

293 </Step>

294

295 <Step title="建置映像並推送到 Amazon ECR">

296 根據[容器映像需求](/docs/zh-TW/claude-apps-gateway-deploy#container-image)建置映像，將 `linux-x64` glibc 二進位檔案放在建置上下文中的 `./claude`。編寫您自己的 Dockerfile 根據這些需求或從套件的 [`Dockerfile`](https://github.com/anthropics/claude-code/blob/main/examples/gateway/aws/Dockerfile) 開始，它將填充的 `gateway.yaml` 從前面的步驟複製到映像中的 `/etc/claude/gateway.yaml`。在 ECS 上，該嵌入副本是設定到達容器的方式，這就是為什麼建置在檔案寫入後進行。EKS 軌道改為在部署時從 ConfigMap 掛載 `gateway.yaml`，因此嵌入副本在那裡未使用。

297

298 映像也攜帶 AWS RDS 憑證套件作為連接字串的 `sslmode=verify-full` 的信任錨，因此首先將其下載到建置上下文中。AWS 輪換套件（新的區域 CA 被附加），因此每次建置時下載它，而不是固定校驗和或提交它：

299

300 ```bash theme={null}

301 curl -fL --proto '=https' -o rds-global-bundle.pem \

302 https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem

303 ```

304

305 容器映像需求不涵蓋套件，因此如果您編寫自己的 Dockerfile，新增複製和信任它的兩行；套件的 `Dockerfile` 已經包含兩者：

306

307 ```dockerfile theme={null}

308 COPY rds-global-bundle.pem /etc/claude/rds-global-bundle.pem

309 ENV NODE_EXTRA_CA_CERTS=/etc/claude/rds-global-bundle.pem

310 ```

311

312 建立 ECR 儲存庫並將 Docker 登入到它。不可變標籤意味著部署步驟固定的 `<version>` 標籤之後無法無聲地重新指向不同的映像：

313

314 ```bash theme={null}

315 aws ecr create-repository --repository-name claude-gateway \

316 --image-tag-mutability IMMUTABLE \

317 --image-scanning-configuration scanOnPush=true

318 aws ecr get-login-password --region "$AWS_REGION" \

319 | docker login --username AWS --password-stdin \

320 "${ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com"

321 ```

322

323 建置並推送映像。下面的任務定義執行 `linux/amd64`，因此平台必須在此處相符；對於 Fargate on ARM64 (Graviton)，使用 `linux-arm64` 二進位檔案建置 `linux/arm64` 並改為將 `cpuArchitecture` 設定為 `ARM64`：

324

325 ```bash theme={null}

326 docker build --platform=linux/amd64 \

327 -t "${ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com/claude-gateway:<version>" .

328 docker push "${ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com/claude-gateway:<version>"

329 ```

330 </Step>

331

332 <Step title="部署">

333 <Tabs>

334 <Tab title="ECS Fargate">

335 建立叢集和 gateway 的日誌群組，用於其 stderr，其中包含其稽核事件和操作日誌。保留期是單獨的呼叫，若不設定，CloudWatch 會永遠保留日誌；將 90 天與您的稽核保留原則對齊：

336

337 ```bash theme={null}

338 aws ecs create-cluster --cluster-name claude-gateway

339 aws logs create-log-group --log-group-name /ecs/claude-gateway

340 aws logs put-retention-policy --log-group-name /ecs/claude-gateway \

341 --retention-in-days 90

342 ```

343

344 寫入任務定義。任務角色攜帶 Bedrock 權限，執行角色注入機密；使用 Secrets Manager 步驟中的機密 ARN：

345

346 ```json claude-gateway-task.json theme={null}

347 {

348 "family": "claude-gateway",

349 "networkMode": "awsvpc",

350 "requiresCompatibilities": ["FARGATE"],

351 "cpu": "1024",

352 "memory": "2048",

353 "runtimePlatform": { "cpuArchitecture": "X86_64", "operatingSystemFamily": "LINUX" },

354 "executionRoleArn": "arn:aws:iam::<account-id>:role/claude-gateway-execution",

355 "taskRoleArn": "arn:aws:iam::<account-id>:role/claude-gateway-task",

356 "containerDefinitions": [

357 {

358 "name": "gateway",

359 "image": "<account-id>.dkr.ecr.<region>.amazonaws.com/claude-gateway:<version>",

360 "portMappings": [{ "containerPort": 8080 }],

361 "secrets": [

362 { "name": "GATEWAY_JWT_SECRET", "valueFrom": "<gateway-jwt-secret ARN>" },

363 { "name": "OIDC_CLIENT_SECRET", "valueFrom": "<gateway-oidc-client-secret ARN>" },

364 { "name": "GATEWAY_POSTGRES_URL", "valueFrom": "<gateway-postgres-url ARN>" }

365 ],

366 "logConfiguration": {

367 "logDriver": "awslogs",

368 "options": {

369 "awslogs-group": "/ecs/claude-gateway",

370 "awslogs-region": "<region>",

371 "awslogs-stream-prefix": "gateway"

372 }

373 }

374 }

375 ]

376 }

377 ```

378

379 註冊它：

380

381 ```bash theme={null}

382 aws ecs register-task-definition --cli-input-json file://claude-gateway-task.json

383 ```

384

385 在前面放置內部 ALB，具有對 gateway 進行健康檢查的目標群組。`--ip-address-type ipv4` 很重要：內部雙堆疊 ALB 發佈公開範圍 AAAA 記錄，`/login` 私有網路檢查拒絕：

386

387 ```bash theme={null}

388 ALB_ARN="$(aws elbv2 create-load-balancer --name claude-gateway \

389 --scheme internal --type application --ip-address-type ipv4 \

390 --subnets $PRIVATE_SUBNETS --security-groups "$ALB_SG" \

391 --query 'LoadBalancers[0].LoadBalancerArn' --output text)"

392

393 TG_ARN="$(aws elbv2 create-target-group --name claude-gateway \

394 --protocol HTTP --port 8080 --vpc-id "$VPC_ID" --target-type ip \

395 --health-check-path /readyz \

396 --query 'TargetGroups[0].TargetGroupArn' --output text)"

397 ```

398

399 新增 HTTPS 監聽器。`--ssl-policy` 固定現代 TLS 下限，因為省略它會回到舊版 `ELBSecurityPolicy-2016-08` 預設值，仍然接受 TLS 1.0/1.1。

400

401 ALB 預設在 60 秒後沒有資料的連接關閉。gateway 的保活 ping 保持串流在該預設值內，因此提高逾時在 ping 頻率上方增加邊距；[故障排除](#troubleshooting)行關於掉落的串流涵蓋機制和較舊的 gateway。下面的命令新增監聽器並提高逾時：

402

403 ```bash theme={null}

404 aws elbv2 create-listener --load-balancer-arn "$ALB_ARN" \

405 --protocol HTTPS --port 443 \

406 --ssl-policy ELBSecurityPolicy-TLS13-1-2-2021-06 \

407 --certificates CertificateArn=<your-acm-certificate-arn> \

408 --default-actions Type=forward,TargetGroupArn="$TG_ARN"

409

410 aws elbv2 modify-load-balancer-attributes --load-balancer-arn "$ALB_ARN" \

411 --attributes Key=idle_timeout.timeout_seconds,Value=3600

412 ```

413

414 建立服務。部署斷路器將其任務持續失敗的部署（來自不良映像或無法啟動的設定）回滾到最後穩定狀態，而不是永遠重新啟動失敗的任務：

415

416 ```bash theme={null}

417 aws ecs create-service --cluster claude-gateway --service-name claude-gateway \

418 --task-definition claude-gateway --desired-count 1 --launch-type FARGATE \

419 --deployment-configuration "deploymentCircuitBreaker={enable=true,rollback=true}" \

420 --health-check-grace-period-seconds 60 \

421 --network-configuration "awsvpcConfiguration={subnets=[$(echo $PRIVATE_SUBNETS | tr ' ' ',')],securityGroups=[$GW_SG],assignPublicIp=DISABLED}" \

422 --load-balancers "targetGroupArn=$TG_ARN,containerName=gateway,containerPort=8080"

423 ```

424

425 60 秒的寬限期給冷任務時間拉取映像、連接到儲存並在 ECS 開始計算針對部署的失敗之前回答其第一個健康檢查。目標群組在 `GET /readyz` 上的健康檢查驗證儲存是否可到達，因此無法到達 Postgres 的任務永遠不會進入輪換；有關權衡和 `/healthz` 替代方案，請參閱[中斷行為](/docs/zh-TW/claude-apps-gateway-deploy#outage-behavior)。

426

427 任務在沒有公開 IP 的私有子網中執行，因此所有出站流量（到 Bedrock、您的 IdP、Secrets Manager、ECR 和 CloudWatch Logs）都透過 NAT 閘道。為了保持 Bedrock 流量不走公開路徑，建立 `bedrock-runtime` 介面 VPC 端點並將上游的 `base_url` 指向它，如 [Bedrock 上游參考](/docs/zh-TW/claude-apps-gateway-config#amazon-bedrock)所示；IdP 仍然需要網際網路出站。

428

429 完成方式是給開發人員一個私有可解析的主機名稱：在 Route 53 私有託管區域中，將 gateway 的內部 DNS 名稱別名到 ALB，並將 `listen.public_url` 設定為該主機名稱。ALB 自己的 `*.elb.amazonaws.com` 名稱解析為內部 ALB 上的私有地址，但它無法攜帶您的 ACM 憑證，因此使用您自己的名稱。

430

431 在第一次登入之前，將 OAuth 客戶端的授權重新導向 URI 更新為 `<public_url>/oauth/callback`。更改 `public_url` 後，在新標籤下重建並推送映像，註冊新任務定義修訂版本，然後重新部署。在 ECS 上，設定位於映像的嵌入 `gateway.yaml` 中，gateway 僅從該設定建置其公開來源，忽略 `X-Forwarded-Host` 和 `X-Forwarded-Proto`。`X-Forwarded-For` 僅在設定 `listen.trusted_proxies` 時才被接受用於客戶端 IP。

432 </Tab>

433

434 <Tab title="EKS">

435 此軌道需要在本地安裝 `kubectl` 和 `eksctl`，以及具有 IAM OIDC 提供者和已安裝 AWS Load Balancer Controller 的現有 EKS 叢集。叢集必須在 `$VPC_ID` 上，以便 pod 可以到達 RDS 私有端點，`claude-gateway-db` 安全群組必須允許叢集的 pod 或節點安全群組而不是 `$GW_SG`。

436

437 在 EKS 上，gateway 透過 IRSA 而不是 ECS 角色從 Bedrock 獲得其認證。IAM 步驟中的 `ecs-tasks.amazonaws.com` 信任原則在此不適用；IRSA 需要一個信任原則在叢集的 OIDC 提供者上聯合的角色，範圍為 `system:serviceaccount:claude-gateway:gateway`。`eksctl create iamserviceaccount` 在一個步驟中建立該角色、附加原則並使用角色 ARN 註釋 Kubernetes 服務帳戶。將 IAM 步驟中的兩個原則文件轉換為它可以附加的受管原則：

438

439 ```bash theme={null}

440 BEDROCK_POLICY_ARN="$(aws iam create-policy --policy-name claude-gateway-bedrock-invoke \

441 --policy-document file://bedrock-invoke.json --query Policy.Arn --output text)"

442 SECRETS_POLICY_ARN="$(aws iam create-policy --policy-name claude-gateway-secrets-read \

443 --policy-document file://secrets-read.json --query Policy.Arn --output text)"

444

445 kubectl create namespace claude-gateway

446 eksctl create iamserviceaccount --cluster <your-cluster> --region "$AWS_REGION" \

447 --namespace claude-gateway --name gateway --role-name claude-gateway \

448 --attach-policy-arn "$BEDROCK_POLICY_ARN" \

449 --attach-policy-arn "$SECRETS_POLICY_ARN" \

450 --approve

451 ```

452

453 機密原則僅在 pod 自己讀取 Secrets Manager 時才需要，如 Secrets Store CSI 驅動程式的 AWS 提供者使用掛載 pod 的服務帳戶所做的那樣；如果您以其他方式建立 Kubernetes Secrets，請刪除它。提供者需要原則的兩個動作：它在協調輪換的機密時呼叫 `DescribeSecret`，因此僅 `GetSecretValue` 授予在第一次部署時掛載但停止拾取輪換。

454

455 將 gateway 部署為標準 Deployment 加上 Service 和 Ingress，如[Kubernetes 部署](/docs/zh-TW/claude-apps-gateway-deploy#kubernetes)所述，具有：

456

457 * `serviceAccountName: gateway`

458 * 從 ConfigMap 掛載的 `gateway.yaml` 和掛載在 `/secrets` 的機密

459 * 就緒探針指向 `GET /readyz`

460

461 對於前端，由 AWS Load Balancer Controller 管理的 Ingress 佈建內部 ALB。使用以下註釋進行註釋：

462

463 * `alb.ingress.kubernetes.io/scheme: internal` 和 `alb.ingress.kubernetes.io/target-type: ip`

464 * `alb.ingress.kubernetes.io/ip-address-type: ipv4`，因此不會發佈會被 `/login` [私有網路檢查](/docs/zh-TW/claude-apps-gateway#prerequisites)拒絕的公開範圍 AAAA 記錄

465 * `alb.ingress.kubernetes.io/inbound-cidrs: <your-corporate-cidr>`，因此控制器管理的前端安全群組僅允許您的公司網路代替其 `0.0.0.0/0` 預設值

466 * `alb.ingress.kubernetes.io/certificate-arn` 與 ACM 憑證

467 * `alb.ingress.kubernetes.io/ssl-policy: ELBSecurityPolicy-TLS13-1-2-2021-06`，因此監聽器不會回到接受 TLS 1.0 和 1.1 的舊版預設原則

468 * `alb.ingress.kubernetes.io/load-balancer-attributes: idle_timeout.timeout_seconds=3600`，在 gateway 的串流保活上方的邊距；請參閱[故障排除](#troubleshooting)

469

470 使用 IRSA，AWS SDK 讀取投影的服務帳戶權杖並與 AWS STS 交換它，因此 pod 永遠不需要 EC2 實例中繼資料服務；出站 NetworkPolicy 可能會為 gateway pod 阻止 `169.254.169.254`。下面[故障排除](#troubleshooting)中的節點躍點限制問題僅適用於跳過 IRSA 並依賴節點實例角色的叢集。

471 </Tab>

472 </Tabs>

473 </Step>

474

475 <Step title="將 gateway URL 推送到開發人員機器">

476 gateway 現在正在執行，但開發人員無法從 `/login` 到達它，直到 gateway URL 在他們的機器上。在[受管設定檔](/docs/zh-TW/claude-apps-gateway#set-the-gateway-url)中設定 `forceLoginMethod` 和 `forceLoginGatewayUrl`，您透過 MDM 部署到每個裝置。登入選擇器中沒有 gateway 選項供開發人員手動選擇。

477 </Step>

478</Steps>

479

480<h2 id="terraform-reference">

481 Terraform 參考

482</h2>

483

484[`examples/gateway/aws`](https://github.com/anthropics/claude-code/tree/main/examples/gateway/aws) 中的配套套件將此頁面打包為程式碼：

485

486* **`setup.sh`** 使用相同的 `aws` 命令在 ECS Fargate 軌道上編寫佈建逐步解說。它是冪等的：現有資源被檢測並跳過，因此重新執行它是安全的，任何預設值都可以透過環境變數覆蓋。您仍然自己建立 Okta OIDC 客戶端機密和 ACM 憑證：沒有它們的執行會跳過 ECS/ALB 部署，命名缺失的輸入，並列印 `create-secret` 命令；建立兩者並重新執行。Bedrock 使用案例表單和 Route 53 別名列印為下一步而不是自動執行，客戶端 MDM 推送保持此頁面的手動步驟。

487* **`gateway.yaml.example`** 是 gateway.yaml 步驟中的設定範本，包含可選金鑰註釋掉。將其複製到 `gateway.yaml` 並在建置前替換每個 `REPLACE_ME`。

488* **`Dockerfile`** 從預建的 `linux-x64` 二進位檔案建置執行時映像，並將您填充的 `gateway.yaml` 複製到 `/etc/claude/gateway.yaml`，加上錨定儲存的 `sslmode=verify-full` 的 AWS RDS 憑證套件。`setup.sh` 僅在建置上下文中尚不存在時下載套件；刪除檔案並在新標籤下重建以拾取 AWS CA 輪換。設定檔不包含機密值，因為每個認證在啟動時透過 `${VAR}` 擴展解析。因此，設定編輯意味著在新標籤下重建；`setup.sh` 透過使用檔案的雜湊標記映像來自動化此操作。

489* **`terraform/`** 聲明性地佈建相同的 ECS Fargate 範圍：安全群組、IAM 角色、ECR 儲存庫、RDS 實例、Secrets Manager 機密和內部 ALB 後面的 ECS 服務。VPC 和私有子網保持先決條件，作為變數傳入。Terraform 建立 ECR 儲存庫但不建置映像，服務定義參考映像，因此應用是兩個通過：儲存庫的目標應用，然後建置和推送，然後完整應用。套件的 `terraform/README.md` 涵蓋變數、遠端狀態和拆除。

490

491像此頁面一樣，套件是客戶管理基礎設施的實際運作範例，而非受支援的生產部署；在依賴它之前，檢查並將其調整至您自己的環境。

492

493<h2 id="troubleshooting">

494 故障排除

495</h2>

496

497如需 gateway 啟動和登入錯誤，請參閱平台無關的[故障排除表](/docs/zh-TW/claude-apps-gateway-deploy#troubleshooting)。下面的項目特定於 AWS。

498

499| 症狀 | 原因 | 修復 |

500| ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

501| CLI `/login`：`Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | gateway 名稱解析為至少一個公開地址。雙堆疊內部 ALB 發佈公開範圍 AAAA 記錄，[私有網路檢查](/docs/zh-TW/claude-apps-gateway#prerequisites)要求每個解析的地址都是私有的 | 使用 `--ip-address-type ipv4` 建立 ALB，或提供沒有公開 AAAA 記錄的單獨內部 DNS 名稱 |

502| 每個 Bedrock 請求都傳回 502；日誌顯示 `Could not load credentials from any providers` | 任務在沒有任務角色的 ECS EC2 啟動類型上執行，或 pod 在沒有 IRSA 的 EKS 節點上執行，因此認證來自實例中繼資料，IMDSv2 的預設躍點限制 1 在容器內停止。此頁面上的兩個軌道都不受影響：Fargate 任務角色和 IRSA 不使用實例中繼資料 | 偏好任務角色和 IRSA。在實例認證不可避免的地方，使用 `aws ec2 modify-instance-metadata-options --instance-id <id> --http-put-response-hop-limit 2` 提高躍點限制；[平台無關表](/docs/zh-TW/claude-apps-gateway-deploy#troubleshooting)涵蓋權衡 |

503| Bedrock 請求傳回 `403 AccessDeniedException` | 帳戶尚未提交 Anthropic 的一次性使用案例表單，自動 AWS Marketplace 訂閱在帳戶的第一次叫用時啟動尚未完成，或任務角色的原則缺少推論設定檔或基礎模型 ARN | 從 Bedrock 主控台的模型目錄提交使用案例表單；如果剛剛提交或這是帳戶的第一次叫用，請在幾分鐘後重試。在兩個 ARN 系列上授予 `bedrock:InvokeModel` 和 `bedrock:InvokeModelWithResponseStream`。 |

504| Bedrock 傳回 `ValidationException` 說不支援按需輸送量 | 自訂 `models:` 項目對應到區域僅透過推論設定檔提供的裸基礎模型 ID | 改為將模型對應到其跨區域推論設定檔 ID (`us.anthropic.*`)；內建目錄已經這樣做 |

505| ECS 任務在 gateway 記錄任何內容之前停止，出現 `ResourceInitializationError` | 執行角色無法讀取 Secrets Manager 機密，或私有子網沒有到 Secrets Manager 或 ECR 的路徑 | 在三個 `gateway-` 機密的 ARN 上授予 `secretsmanager:GetSecretValue` 給執行角色，並透過 NAT 閘道提供出站，或沒有一個，Secrets Manager、ECR 和 CloudWatch Logs 的介面端點，`awslogs` 驅動程式在同一階段需要，加上 S3 閘道端點 |

506| Gateway 啟動退出，出現 Postgres 連接逾時錯誤 | 資料庫安全群組不允許 gateway 的安全群組在 5432 上，或服務在資料庫的 VPC 外執行；儲存在 5 秒後停止等待 | 在資料庫的安全群組上允許來自 gateway 安全群組的 5432，並在與 DB 子網群組相同的 VPC 中執行服務 |

507| Gateway 啟動退出，出現 Postgres TLS 憑證驗證錯誤 | 連接字串設定 `sslmode=verify-full` 但映像不信任 RDS CA 套件：套件未複製到映像中，或 `NODE_EXTRA_CA_CERTS` 不指向它 | 新增建置步驟的兩個 Dockerfile 行，複製套件並設定 `NODE_EXTRA_CA_CERTS`，然後重建、在新標籤下推送並重新部署 |

508| 串流回應在安靜期間中途掉落 | v2.1.229 之前的 gateway 在 Bedrock 或 Claude Platform on AWS 上游上在上游安靜時不發送任何內容，例如沒有串流輸出的擴展思考。ALB 預設在 60 秒後沒有資料的連接關閉，因此它在該間隙處切斷串流。v2.1.229 及更新版本的 gateway 在該逾時下保持安靜串流：在這些上游上，gateway 在大約 15 秒後沒有串流資料時發出 SSE `ping` 事件，在 Anthropic API 上游上它中繼 API 自己的 ping | 將 gateway 更新到 v2.1.229 或更新版本，或透過 `modify-load-balancer-attributes` 或 EKS 上的 `load-balancer-attributes` Ingress 註釋將 `idle_timeout.timeout_seconds` 屬性設定為 `3600` |

509

510<h2 id="telemetry">

511 遙測

512</h2>

513

514gateway 為您提供每個開發人員的使用指標，無需任何每台機器的 OTEL 設定。Claude Code 發出 OpenTelemetry (OTLP) 指標、日誌和選擇加入的追蹤；[監控使用](/docs/zh-TW/monitoring-usage)涵蓋 CLI 報告的所有內容。在 gateway 工作階段上，CLI 使用已驗證的 IdP 身份屬性 `user.id`、`user.email` 和 `user.groups` 標記每個匯出，因此使用按開發人員匯總，無需 `OTEL_RESOURCE_ATTRIBUTES` 配管。

515

516gateway 本身是經過驗證的 OTLP 中繼。將 [`telemetry.forward_to`](/docs/zh-TW/claude-apps-gateway-config#telemetry) 與 `listen.public_url` 一起設定，它將 OTEL 匯出器設定推送到每個連接的客戶端，並將其 OTLP 流量逐字轉發到您列出的每個目的地。每個目的地獨立選擇加入指標、日誌和追蹤，預設為僅指標；有關每個信號欄位及其敏感性權衡，請參閱 [`telemetry` 參考](/docs/zh-TW/claude-apps-gateway-config#telemetry)。gateway 不緩衝、聚合或儲存遙測，因此資料落在何處完全是收集器的匯出器設定。

517

518客戶端遙測預設關閉；設定 `telemetry.forward_to` 是為連接的開發人員開啟它的方式，每個互動式客戶端為推送的設定顯示一次性安全批准對話，如[設定參考](/docs/zh-TW/claude-apps-gateway-config#telemetry)所述。在 AWS 上，每個信號對應到目的地如下。

519

520<h3 id="client-metrics-logs-and-traces">

521 客戶端指標、日誌和追蹤

522</h3>

523

524將 `telemetry.forward_to` 指向 OpenTelemetry 收集器，例如 [AWS Distro for OpenTelemetry (ADOT) 收集器](https://aws-otel.github.io/)，並從那裡匯出到 Amazon CloudWatch、Amazon Managed Service for Prometheus 或任何 OTLP 後端。

525

526將收集器作為其自己的內部服務執行，可透過 `https://` 到達；[`telemetry` 參考](/docs/zh-TW/claude-apps-gateway-config#telemetry)涵蓋環回例外和 `CLAUDE_GATEWAY_ALLOW_LOOPBACK`。

527

528<h3 id="gateway-logs">

529 Gateway 日誌

530</h3>

531

532在 ECS Fargate 上，無需額外設定：`awslogs` 驅動程式將 gateway 的 stderr（其中包含其稽核事件和操作日誌）傳遞到上面建立的 `/ecs/claude-gateway` 日誌群組。在 EKS 上，pod 日誌預設不到達 CloudWatch，因此稽核軌跡丟失，直到您安裝日誌收集：啟用容器日誌擷取的 Amazon CloudWatch Observability 附加元件，或 Fluent Bit DaemonSet。在任一軌道上，使用 CloudWatch Logs Insights 查詢日誌並從指標篩選器驅動警報。

533

534<h3 id="container-metrics">

535 容器指標

536</h3>

537

538使用 `aws ecs update-cluster-settings --cluster claude-gateway --settings name=containerInsights,value=enabled` 在叢集上啟用 Container Insights，用於每個任務的 CPU、記憶體和網路。在 EKS 上，安裝 Amazon CloudWatch Observability 附加元件。

539

540<h3 id="spend">

541 支出

542</h3>

543

544遙測在事後顯示使用；[支出限制](/docs/zh-TW/claude-apps-gateway-spend-limits)是 gateway 在共享上游認證之上的即時每個開發人員檢視和執行。

545

546<h2 id="next-steps">

547 後續步驟

548</h2>

549

550* [設定參考](/docs/zh-TW/claude-apps-gateway-config)：每個 `gateway.yaml` 選項，包括 `managed.policies` 和 `telemetry`

551* [部署和操作](/docs/zh-TW/claude-apps-gateway-deploy)：IdP 設定、健康檢查、JWT 機密輪換、升級和安全模型

552* [Claude apps gateway 概述](/docs/zh-TW/claude-apps-gateway)：快速入門和連接開發人員

553* [Claude apps gateway 的 AWS 範例](https://github.com/aws-samples/anthropic-on-aws/tree/main/claude-apps-gateway)：AWS 維護的部署範例，涵蓋一系列客戶環境

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

Details

42 42

43雲端工作階段需要存取您的 GitHub 儲存庫以複製程式碼和推送分支。您可以通過兩種方式授予存取權限：43雲端工作階段需要存取您的 GitHub 儲存庫以複製程式碼和推送分支。您可以通過兩種方式授予存取權限：

44 44

~~45| 方法 | 運作方式 | 最適合 |~~45| 方法 | 運作方式 | 工作階段可以存取的儲存庫 | 最適合 |

~~46| :--------------- | :------------------------------------------------------- | :----------------------------------------- |~~46| :--------------- | :------------------------------------------------------ | :------------------------------------- | :----------------------------------------- |

49 49

~~50<Note>~~50在儲存庫上安裝 Claude GitHub App 也會為其中的提取請求啟用[自動修復](#auto-fix-pull-requests)。

51 使用任一方法，雲端工作階段都可以存取連接的 GitHub 帳戶可以看到的任何儲存庫，而不僅僅是安裝了 Claude GitHub App 的儲存庫。App 安裝啟用 PR webhooks 以進行[自動修復](#auto-fix-pull-requests)；它不是工作階段級別的存取控制。若要限制您的團隊可以從雲端工作階段存取的儲存庫，請在 GitHub 本身上限制存取，例如通過限制連接的 GitHub 帳戶的團隊或儲存庫成員資格。

~~52</Note>~~

53 51

54任一方法都可以。有關 `/schedule` 如何在建立例行工作之前檢查該存取，請參閱[儲存庫和分支權限](/docs/zh-TW/routines#repositories-and-branch-permissions)。有關 `/web-setup` 的逐步說明，請參閱[從您的終端連接](/docs/zh-TW/web-quickstart#connect-from-your-terminal)。52有關 `/schedule` 如何在建立例行工作之前檢查儲存庫存取，請參閱[儲存庫和分支權限](/docs/zh-TW/routines#repositories-and-branch-permissions)。有關 `/web-setup` 的逐步說明，請參閱[從您的終端連接](/docs/zh-TW/web-quickstart#connect-from-your-terminal)，包括 `/web-setup` 儲存的內容以及如何移除它。

55 53

56快速網頁設定是一個組織設定，讓成員使用 `/web-setup` 連接 GitHub，在瀏覽器上線期間跳過 Claude GitHub App 安裝提示，並讓瀏覽器上線為他們建立[**預設**環境](/docs/zh-TW/cloud-environments#the-default-environment)，而不是顯示環境表單。在 Team 和 Enterprise 計畫上，預設情況下它是關閉的，這會隱藏 `/web-setup`。[擁有者](/docs/zh-TW/server-managed-settings#access-control)可以在 [**管理設定 > Claude Code**](https://claude.ai/admin-settings/claude-code) 使用**快速網頁設定**切換來開啟它。54快速網頁設定是一個組織設定，讓成員使用 `/web-setup` 連接 GitHub，在瀏覽器上線期間跳過 Claude GitHub App 安裝提示，並讓瀏覽器上線為他們建立[**預設**環境](/docs/zh-TW/cloud-environments#the-default-environment)，而不是顯示環境表單。在 Team 和 Enterprise 計畫上，預設情況下它是關閉的，這會隱藏 `/web-setup`。[擁有者](/docs/zh-TW/server-managed-settings#access-control)可以在 [**管理設定 > Claude Code**](https://claude.ai/admin-settings/claude-code) 使用**快速網頁設定**切換來開啟它。

57 55

79claude --cloud "Fix the authentication bug in src/auth/login.ts"77claude --cloud "Fix the authentication bug in src/auth/login.ts"

80```78```

81 79

82這會在 claude.ai 上建立新的雲端工作階段。雲端 VM 複製您目前目錄的 GitHub 遠端，位於您目前的分支，而不是您的本機簽出，因此如果您有本機提交，請先推送。`--cloud` 一次適用於單一儲存庫。任務在雲端執行，而您繼續在本機工作。較舊的 `--remote` 拼寫仍然可作為 `--cloud` 的已棄用別名。80這會在 claude.ai 上建立新的雲端工作階段。雲端 VM 複製您目前目錄的 GitHub 遠端，位於您目前的分支，而不是您的本機簽出，因此如果您有本機提交，請先推送。請參閱[不使用 GitHub 發送本機儲存庫](#send-local-repositories-without-github)以了解 Claude Code 上傳您的本機儲存庫而不是複製的情況。

82`--cloud` 一次適用於單一儲存庫。任務在雲端執行，而您繼續在本機工作。較舊的 `--remote` 拼寫仍然可作為 `--cloud` 的已棄用別名。

83 83

84當雲端容器啟動時，CLI 會顯示設定步驟的即時檢查清單，例如複製儲存庫和執行您的[設定指令碼](/docs/zh-TW/cloud-environments#setup-scripts)。它會排隊您在佈建期間輸入的訊息，並在工作階段準備好後發送它們。84當雲端容器啟動時，CLI 會顯示設定步驟的即時檢查清單，例如複製儲存庫和執行您的[設定指令碼](/docs/zh-TW/cloud-environments#setup-scripts)。它會排隊您在佈建期間輸入的訊息，並在工作階段準備好後發送它們。

85 85

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

122</h4>122</h4>

123 123

124當您從未連接到 GitHub 的儲存庫執行 `claude --cloud` 時，Claude Code 會捆綁您的本機儲存庫並直接上傳到雲端工作階段。捆綁包括您的完整儲存庫歷史記錄，跨所有分支，加上任何未提交的對追蹤檔案的變更。124當您從未連接到 GitHub 的儲存庫執行 `claude --cloud` 時，或從 Claude GitHub App 未安裝的 github.com 儲存庫執行時，Claude Code 會捆綁您的本機儲存庫並直接上傳到雲端工作階段。即使您使用 `/web-setup` 連接了 GitHub，這也適用。捆綁包括您的完整儲存庫歷史記錄，跨所有分支，加上對追蹤檔案的未提交變更。

125 125

126在 macOS、Linux 和 WSL 上，Claude Code 會將名稱類似認證或金鑰的檔案的未提交變更排除在上傳之外，並列出它排除的檔案名稱。這涵蓋 `.env` 檔案、Terraform `*.tfvars` 檔案和金鑰檔案，例如 `id_rsa` 和 `*.pem`。工作階段會以每個檔案的已提交版本啟動，或如果沒有已提交的檔案，則不使用該檔案。在連結的 worktree、子模組或類似配置中，Claude Code 會上傳這些變更與其餘部分一起，並列出它上傳的檔案名稱。126在 macOS、Linux 和 WSL 上，Claude Code 會將名稱類似認證或金鑰的檔案的未提交變更排除在上傳之外，並列出它排除的檔案名稱。這涵蓋 `.env` 檔案、Terraform `*.tfvars` 檔案和金鑰檔案，例如 `id_rsa` 和 `*.pem`。工作階段會以每個檔案的已提交版本啟動，或如果沒有已提交的檔案，則不使用該檔案。在連結的 worktree、子模組或類似配置中，Claude Code 會上傳這些變更與其餘部分一起，並列出它上傳的檔案名稱。

127 127

128當 GitHub 存取不可用時，此回退會自動啟動。若要即使在 GitHub 已連接時也強制它，請設定 `CCR_FORCE_BUNDLE=1`：128若要即使在 Claude Code 會以其他方式從遠端複製時也強制上傳捆綁，請設定 `CCR_FORCE_BUNDLE=1`：

129 129

130```bash theme={null}130```bash theme={null}

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

136* 目錄必須是至少有一個提交的 git 儲存庫136* 目錄必須是至少有一個提交的 git 儲存庫

137* 捆綁的儲存庫必須在 100 MB 以下。較大的儲存庫回退到僅捆綁目前分支，然後回退到工作樹的單一壓縮快照，並且僅在快照仍然太大時失敗137* 捆綁的儲存庫必須在 100 MB 以下。較大的儲存庫回退到僅捆綁目前分支，然後回退到工作樹的單一壓縮快照，並且僅在快照仍然太大時失敗

138* 未追蹤的檔案不包括；在您希望雲端工作階段看到的檔案上執行 `git add`138* 未追蹤的檔案不包括；在您希望雲端工作階段看到的檔案上執行 `git add`

139* 從捆綁建立的工作階段無法推送回遠端，除非您也配置了 [GitHub 驗證](#github-authentication-options)139* 從捆綁建立的工作階段只有在您的 [GitHub 連接](#github-authentication-options)對該儲存庫具有推送存取權時，才能推送回 GitHub 遠端

140 140

141<h3 id="send-follow-ups-from-the-cli">141<h3 id="send-follow-ups-from-the-cli">

142 從 CLI 發送後續訊息142 從 CLI 發送後續訊息

352每個雲端工作階段通過多個層與您的機器和其他工作階段分離：352每個雲端工作階段通過多個層與您的機器和其他工作階段分離：

353 353

354* **隔離的虛擬機器**：每個工作階段在隔離的 Anthropic 管理的 VM 中執行。您的組織路由到[自託管環境](/docs/zh-TW/self-hosted-environments)的工作階段改為在您自己的基礎設施上執行，其中隔離是您的部署的責任354* **隔離的虛擬機器**：每個工作階段在隔離的 Anthropic 管理的 VM 中執行。您的組織路由到[自託管環境](/docs/zh-TW/self-hosted-environments)的工作階段改為在您自己的基礎設施上執行，其中隔離是您的部署的責任

355* **網路存取控制**：在 Anthropic 託管的環境中，網路存取預設受限，可以禁用。在自託管環境中，您在自己的網路邊界限制工作階段出口。當以禁用的網路存取執行時，Claude Code 仍然可以與 Anthropic API 通訊，這可能允許資料離開 VM。355* <span id="default-allowed-domains" />**網路存取控制**：在 Anthropic 託管的環境中，網路存取預設受限，可以禁用。請參閱[網路存取](/docs/zh-TW/cloud-environments#network-access)以了解存取層級、[預設允許的網域](/docs/zh-TW/cloud-environments#default-allowed-domains)，以及不通過允許清單的流量。在自託管環境中，您在自己的網路邊界限制工作階段出口。當以禁用的網路存取執行時，Claude Code 仍然可以與 Anthropic API 通訊，這可能允許資料離開 VM。

356* **認證保護**：在 Anthropic 託管的環境中，git 認證和簽署金鑰保持在沙箱外，代理使用限定認證代表工作階段進行驗證。在自託管環境中，您的部署提供 git 認證；請參閱[配置 git](/docs/zh-TW/self-hosted-environments-deploy#configure-git)356* **認證保護**：在 Anthropic 託管的環境中，git 認證和簽署金鑰保持在沙箱外，代理使用限定認證代表工作階段進行驗證。在自託管環境中，您的部署提供 git 認證；請參閱[配置 git](/docs/zh-TW/self-hosted-environments-deploy#configure-git)

357* **API 認證**：在 Pro 和 Max 計畫的 Anthropic 託管環境中，您[新增到雲端環境](/docs/zh-TW/cloud-environments#add-api-credentials)的金鑰保持在沙箱外，以相同的方式附加到匹配的請求，在它們離開工作階段後。自託管環境沒有 API 認證，Team 和 Enterprise 計畫還沒有357* **API 認證**：在 Pro 和 Max 計畫的 Anthropic 託管環境中，您[新增到雲端環境](/docs/zh-TW/cloud-environments#add-api-credentials)的金鑰保持在沙箱外，以相同的方式附加到匹配的請求，在它們離開工作階段後。自託管環境沒有 API 認證，Team 和 Enterprise 計畫還沒有

358* **安全分析**：程式碼在隔離的工作階段環境內進行分析和修改，然後建立 PR358* **安全分析**：程式碼在隔離的工作階段環境內進行分析和修改，然後建立 PR

371 371

372* 檢查 [status.claude.com](https://status.claude.com) 以查找雲端工作階段事件372* 檢查 [status.claude.com](https://status.claude.com) 以查找雲端工作階段事件

373* 一分鐘後重試，因為容量是按需佈建的373* 一分鐘後重試，因為容量是按需佈建的

374* 確認您的儲存庫可到達。連接的 GitHub 帳戶必須能夠存取 GitHub 上的儲存庫，可以通過 Claude GitHub App 授權或通過 `/web-setup` 同步的 `gh` 令牌進行存取。不需要在儲存庫上安裝 App。請參閱 [GitHub 驗證選項](#github-authentication-options)。374* 確認您的 GitHub 連線可以到達儲存庫，請遵循[連接 GitHub 後沒有儲存庫出現](/docs/zh-TW/web-quickstart#no-repositories-appear-after-connecting-github)

375 375

376<h3 id="unable-to-get-organization-uuid">376<h3 id="unable-to-get-organization-uuid">

377 無法取得組織 UUID377 無法取得組織 UUID

407 407

408* **速率限制**：Claude Code 網頁版與您帳戶內所有其他 Claude 和 Claude Code 使用共享速率限制。並行執行多個任務會按比例消耗更多速率限制。雲端 VM 沒有單獨的計算費用。408* **速率限制**：Claude Code 網頁版與您帳戶內所有其他 Claude 和 Claude Code 使用共享速率限制。並行執行多個任務會按比例消耗更多速率限制。雲端 VM 沒有單獨的計算費用。

409* **儲存庫驗證**：您只能在驗證到相同帳戶時將工作階段從網頁移動到本機409* **儲存庫驗證**：您只能在驗證到相同帳戶時將工作階段從網頁移動到本機

410* **平台限制**：儲存庫複製和拉取請求建立需要 GitHub。自託管[GitHub Enterprise Server](/docs/zh-TW/github-enterprise-server) 執行個體支援 Team 和 Enterprise 計畫。GitLab、Bitbucket 和其他非 GitHub 儲存庫可以作為[本機捆綁](#send-local-repositories-without-github)發送到雲端工作階段，但工作階段無法將結果推送回遠端410* **平台限制**：儲存庫複製和拉取請求建立需要 GitHub。自託管 [GitHub Enterprise Server](/docs/zh-TW/github-enterprise-server) 執行個體支援 Team 和 Enterprise 計畫。您可以透過設定 `CCR_FORCE_BUNDLE=1`，將 GitLab、Bitbucket 或其他非 GitHub 儲存庫作為[本機捆綁](#send-local-repositories-without-github)發送到雲端工作階段，但工作階段無法將結果推送回該遠端

411* **組織 IP 允許清單**：雲端工作階段從 Anthropic 管理的基礎設施而不是您的網路呼叫 Anthropic API，而[自託管環境](/docs/zh-TW/self-hosted-environments)中的工作階段從您自己的網路呼叫它。如果您的組織啟用了 [IP 允許清單](https://support.claude.com/en/articles/13200993-restrict-access-to-claude-with-ip-allowlisting)，每個 Anthropic 託管的雲端工作階段都會失敗，出現驗證錯誤。這同樣適用於[程式碼審查](/docs/zh-TW/code-review)和[例行工作](/docs/zh-TW/routines)，在 Anthropic 託管的環境中執行；路由到自託管環境的例行工作從您自己的網路呼叫 API。聯絡 [Anthropic 支援](https://support.claude.com/)以從您的組織的 IP 允許清單中豁免 Anthropic 託管的服務。411* **組織 IP 允許清單**：雲端工作階段從 Anthropic 管理的基礎設施而不是您的網路呼叫 Anthropic API，而[自託管環境](/docs/zh-TW/self-hosted-environments)中的工作階段從您自己的網路呼叫它。如果您的組織啟用了 [IP 允許清單](https://support.claude.com/en/articles/13200993-restrict-access-to-claude-with-ip-allowlisting)，每個 Anthropic 託管的雲端工作階段都會失敗，出現驗證錯誤。這同樣適用於[程式碼審查](/docs/zh-TW/code-review)和[例行工作](/docs/zh-TW/routines)，在 Anthropic 託管的環境中執行；路由到自託管環境的例行工作從您自己的網路呼叫 API。聯絡 [Anthropic 支援](https://support.claude.com/)以從您的組織的 IP 允許清單中豁免 Anthropic 託管的服務。

412 412

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

claude-security.md +171 −0 created

Details

1> ## Documentation Index

2> 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.

5# 掃描程式碼庫以尋找漏洞

7> 安裝 Claude Security plugin 以在 Claude Code 工作階段中掃描程式碼庫以尋找漏洞，並將發現的問題轉換為您可以檢查和應用的修補程式。

9Claude Security plugin 在 Claude Code 工作階段內執行程式碼庫的多代理漏洞掃描。一個 Claude 代理團隊會對您的架構進行對應、建立威脅模型、搜尋漏洞，並在撰寫報告前獨立檢查每項發現。使用此 plugin 掃描整個儲存庫或[僅掃描一組變更](#scan-only-your-changes)，例如分支的差異、pull request 的差異或單一提交，然後將您選擇的發現轉換為您可以自行檢查和應用的修補程式。

11此 plugin 在您的工作階段中本地執行，使用您在 Claude Code 中可以存取的任何模型，每次掃描都會計入您方案的使用限制。如果您想要一個監控您儲存庫的受管服務，或想要在 [Claude Mythos 5](https://platform.claude.com/docs/en/about-claude/models/introducing-claude-fable-5-and-claude-mythos-5) 上執行掃描，請參閱 [Claude Security](https://claude.com/product/claude-security) 產品，該產品在企業方案上提供。此 plugin 可以存取受管產品無法存取的程式碼，例如託管在 GitLab 或 Bitbucket 上的儲存庫，或在不允許入站連線的網路上的儲存庫。

13此 plugin 也不同於 Claude Code 中已有的檢查工具：[security guidance plugin](/docs/zh-TW/security-guidance) 在 Claude 撰寫程式碼時檢查程式碼，[`/security-review`](/docs/zh-TW/commands#all-commands) 對您的分支執行單一掃描，而 [Code Review](/docs/zh-TW/code-review) 檢查 pull request。如需了解這些層級如何堆疊，請參閱 [此 plugin 如何與其他安全工具配合](#how-the-plugin-fits-with-other-security-tools)。

15<h2 id="prerequisites">

16 先決條件

17</h2>

19若要執行此外掛程式，您需要：

21* 付費方案，用於掃描用來協調其代理的[動態工作流程](/docs/zh-TW/workflows)。在 Pro 上，從 `/config` 中的「動態工作流程」列啟用它們。

22* Python 3.9 或更新版本，在您的 `PATH` 上可用為 `python3`。使用 `python3 --version` 檢查。此外掛程式的工具僅使用 Python 標準程式庫，因此不會安裝任何內容。

23* Linux、macOS 或 Windows。

24* Git，用於變更掃描和將發現轉換為修補程式；這些工作不支援其他版本控制系統。完整掃描在任何目錄中都有效，無論是否有版本控制。

26<h2 id="install-the-plugin">

27 安裝外掛程式

28</h2>

30在 Claude Code 工作階段中，從[官方 Anthropic 市集](/docs/zh-TW/discover-plugins#official-anthropic-marketplace)安裝：

32```text theme={null}

33/plugin install claude-security@claude-plugins-official

34```

36該命令會開啟外掛程式的詳細資訊，您可以在其中選擇[安裝範圍](/docs/zh-TW/discover-plugins#install-plugins)以開始安裝。

38如果安裝失敗，修復方法取決於 Claude Code 報告的訊息：

40* 如果它報告 `Marketplace "claude-plugins-official" not found`，使用 `/plugin marketplace add anthropics/claude-plugins-official` 新增市集，然後重試安裝。

41* 如果它報告[在市集中找不到外掛程式](/docs/zh-TW/discover-plugins#install-plugins)，檢查外掛程式名稱是否有拼寫錯誤。

43檢查安裝摘要。如果它報告 `Run /reload-plugins to activate.`，請參閱[在不重新啟動的情況下套用外掛程式變更](/docs/zh-TW/discover-plugins#apply-plugin-changes-without-restarting)以在您目前的工作階段中啟用外掛程式。

45外掛程式啟用後，您已準備好[掃描和修復您的程式碼庫](#scan-and-fix-your-codebase)。

47<h3 id="uninstall-the-plugin">

48 解除安裝外掛程式

49</h3>

51若要移除外掛程式，從 `/plugin` 功能表解除安裝它，或在您的終端中執行 `claude plugin uninstall claude-security`。

53<h2 id="scan-and-fix-your-codebase">

54 掃描和修復您的程式碼庫

55</h2>

57此外掛程式新增一個命令 `/claude-security`，它開啟其三個工作的功能表：掃描程式碼庫、掃描一組變更和建議修補程式。快樂路徑執行完整掃描，然後將其發現轉換為修補程式：

59<Steps>

60 <Step title="開啟 Claude Security 功能表">

61 執行 `/claude-security` 並選擇 **Scan codebase**。

62 </Step>

64 <Step title="選擇要掃描的內容">

65 外掛程式首先讀取您的儲存庫，然後提供整個儲存庫或聚焦區域，每個選項都說明檔案計數和相對成本。選擇整個儲存庫，或回答「我不知道」，外掛程式會為您的儲存庫大小選擇合理的預設值。

66 </Step>

68 <Step title="確認執行">

69 掃描可能需要一段時間，可能使用大量令牌，並需要 Claude Code 在完成時保持開啟。在您確認之前，不會執行任何操作。

70 </Step>

72 <Step title="讀取報告">

73 掃描執行時，它會在每個階段開始時報告，詳細資訊可在 [`/workflows`](/docs/zh-TW/workflows) 下取得。結果進入您儲存庫中的時間戳記目錄，如[讀取掃描結果](#read-the-scan-results)中所述。

74 </Step>

76 <Step title="將發現轉換為修補程式">

77 再次執行 `/claude-security` 並選擇 **Suggest patches**，然後選擇要解決的發現。已檢查的修補程式進入報告的 `patches/` 資料夾；[修復發現](#fix-findings)涵蓋每個修補程式的建立和檢查方式。

78 </Step>

80 <Step title="應用您接受的修補程式">

81 從您的 shell 使用 `git apply` 應用每個修補程式，在其自己的 pull request 中。修補程式永遠不會自動應用。

82 </Step>

83</Steps>

85您不必從功能表開始：直接要求工作，作為命令的引數，例如 `/claude-security scan my branch`，或以純文字形式，例如「scan commit abc1234」。此外掛程式在[自動模式](/docs/zh-TW/permission-modes)中效果最佳，這讓掃描的代理在每一步都無需權限提示即可進行。

87<h3 id="scan-only-your-changes">

88 僅掃描您的變更

89</h3>

91當您的分支有其基礎沒有的提交時，`/claude-security` 功能表會提供僅掃描該差異的選項，以便您可以在合併前檢查分支。您也可以掃描您的一個開啟 pull request，或通過要求它來掃描單一提交，例如「scan commit abc1234」。僅掃描已提交的變更：首先提交或 stash 進行中的編輯，或執行完整掃描，它會讀取工作樹。

93變更掃描需要 git 儲存庫；未版本控制目錄的完整掃描仍然有效。尋找您的開啟 pull request 是唯一到達網路的步驟，僅當您的工作階段已有權限執行 GitHub CLI 且 `gh` 已登入時才提供。

95<h3 id="scope-large-repositories">

96 限制大型儲存庫的範圍

97</h3>

99在大型儲存庫上，一次掃描一個區域而不是整個樹。選擇外掛程式提供的聚焦範圍之一，例如您的 API 層或您的驗證程式碼，執行會根據您選擇的內容調整大小。報告的涵蓋範圍部分說明檢查了什麼和未檢查什麼。隨時在不同區域執行另一次掃描。

100

101<h3 id="read-the-scan-results">

102 讀取掃描結果

103</h3>

104

105每次掃描都會將其結果寫入您儲存庫中的時間戳記 `CLAUDE-SECURITY-<timestamp>/` 目錄：

106

107* **`CLAUDE-SECURITY-RESULTS.md`**：報告，包含每項發現的 ID，例如 `F1`，加上其影響、利用情景、嚴重性、信心和建議

108* **`CLAUDE-SECURITY-RESULTS.jsonl`**：相同的發現以機器可讀形式，每行一個 JSON 物件

109* **`CLAUDE-SECURITY-RESULTS.sarif`**：相同的發現作為 [SARIF 2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html) 日誌，用於 GitHub 程式碼掃描和任何其他讀取標準的工具。掃描將發現分類在其 [CWE](https://cwe.mitre.org/) 弱點類別下

110* **`CLAUDE-SECURITY-REVISION-<commit>.json`**：修訂戳記，記錄掃描了哪個提交、付出了多少努力、未提交的變更是否是掃描樹的一部分，以及執行的驗證程度如何，因此報告始終與其描述的程式碼相關聯。版本控制外的掃描在提交位置戳記 `UNVERSIONED`

111

112該目錄是掃描對您簽出的唯一變更，它帶有自己的 `.gitignore`，因此隨意的 `git add` 永遠不會將報告掃入提交。若要在歷史記錄中保留報告以進行稽核追蹤，刪除該一個 `.gitignore` 檔案並像任何其他檔案一樣提交目錄。

113

114發現僅在獨立驗證代理分析它們後才出現在報告中，這使報告簡短且值得閱讀。掃描是非確定性的：同一程式碼的兩次掃描可能會發現不同的發現。定期執行掃描，並使用修訂戳記將每份報告歸因於它涵蓋的確切程式碼和設定。

115

116<h2 id="fix-findings">

117 修復發現

118</h2>

119

120通過從 `/claude-security` 功能表選擇 **Suggest patches** 開始修復流程，或以純文字形式要求，例如「fix finding F3」，然後選擇要解決的報告中的發現。修補程式是針對已提交的程式碼建立的，報告必須仍然描述您擁有的程式碼：其程式碼已更改的發現會被跳過並附帶說明，外掛程式會提供新鮮掃描而不是從陳舊報告進行修補。每個修補程式都是在您儲存庫的暫存副本中起草的，因此您的原始檔案保持未觸及狀態，直到您自己應用修補程式。

121

122在交付前，每個修補程式都由獨立於撰寫它的代理的代理檢查，當程式碼有測試時它會針對變更執行您的專案測試，並自行讀取差異以查看它可能引入的任何新內容。修補程式僅在該檢查可以保證變更解決了一項發現、不引入新漏洞且以其他方式保持行為不變時才被撰寫。當它無法保證全部三項時，您會得到一個簡短的說明而不是修補程式。

123

124<h3 id="patches-are-never-applied-automatically">

125 修補程式永遠不會自動應用

126</h3>

127

128應用修補程式始終是您的決定。修補程式進入報告的 `patches/` 資料夾，每個發現一個 `F<n>.patch`，旁邊有說明變更的說明。從您的 shell 應用一個，或要求 Claude 應用它並開啟 pull request：

129

130```bash theme={null}

131git apply CLAUDE-SECURITY-<timestamp>/patches/F1.patch

132```

133

134當修補的程式碼沒有測試時，修補程式的說明會說明這一點，因此您知道其檢查在沒有測試通過的情況下執行。在其自己的 pull request 中應用每個修補程式，以便可以獨立檢查和測試。

135

136<h2 id="how-the-plugin-fits-with-other-security-tools">

137 此外掛程式如何與其他安全工具配合

138</h2>

139

140Claude Security 外掛程式是深度掃描層，在防禦深度堆疊中，與 [security guidance 外掛程式](/docs/zh-TW/security-guidance)、[`/security-review`](/docs/zh-TW/commands#all-commands)、[Code Review](/docs/zh-TW/code-review)、受管 [Claude Security](https://claude.com/product/claude-security) 產品和您現有的掃描器一起：

141

142| 階段 | 工具 | 涵蓋內容 |

143| :--------------- | :-------------------------------------------------------------------------- | :----------------------------- |

144| 在工作階段中 | [Security guidance 外掛程式](/docs/zh-TW/security-guidance) | Claude 撰寫的程式碼中的常見漏洞，在同一工作階段中修復 |

145| 按需，單一掃描 | [`/security-review`](/docs/zh-TW/commands#all-commands) | 目前分支上的一次性安全掃描 |

146| 按需，深度掃描 | Claude Security 外掛程式 | 儲存庫或差異的多代理掃描，具有獨立檢查的發現和修補程式 |

147| 在 pull request 上 | [Code Review](/docs/zh-TW/code-review)，Team 和 Enterprise 方案 | 具有完整程式碼庫上下文的多代理正確性和安全檢查 |

148| 受管 | [Claude Security](https://claude.com/product/claude-security)，Enterprise 方案 | 監控連接儲存庫的託管掃描 |

149| 在 CI 中 | 您現有的靜態分析和依賴掃描器 | 特定語言規則、供應鏈檢查和政策執行 |

150

151此外掛程式不會取代您現有的原始碼安全工具。與靜態分析、依賴掃描和程式碼檢查一起執行它：它以人類安全研究人員的方式推理您的程式碼，這補充了這些工具提供的確定性檢查。

152

153<h2 id="troubleshooting">

154 疑難排解

155</h2>

156

157**`/claude-security` 功能表開啟時出現 Python 警告。** 此外掛程式需要 `python3` 3.9 或更新版本在您的 `PATH` 上。當它根本找不到 `python3` 時，功能表會警告在安裝一個之前 Claude Security 無法工作；當您 `PATH` 上的第一個 `python3` 較舊時，警告會命名它找到的版本。安裝 Python 3，或在您的 `PATH` 上放置較新的 `python3`，然後開始新工作階段。

158

159**在 Fable 模型上掃描時，您可能會看到「safeguards flagged this message」通知。** 訊息會命名模型，例如「Fable 5.1's safeguards flagged this message」。Fable 的網路安全安全分類器會標記某些請求，Claude Code 會通過[自動模型回退](/docs/zh-TW/model-config#automatic-model-fallback)在 Opus 模型上重新執行標記的請求。這是預期的，掃描應該仍然成功完成。

160

161<h2 id="related-resources">

162 相關資源

163</h2>

164

165若要深入了解此頁面涉及的部分：

166

167* [Security guidance 外掛程式](/docs/zh-TW/security-guidance)：在同一工作階段中 Claude 撰寫程式碼時捕捉問題

168* [Code Review](/docs/zh-TW/code-review)：設定 PR 時間多代理檢查

169* [Claude Security](https://claude.com/product/claude-security)：監控連接儲存庫的受管服務

170* [Claude Code 安全](/docs/zh-TW/security)：Claude Code 如何處理信任、權限和保護措施

171* [探索和安裝外掛程式](/docs/zh-TW/discover-plugins#official-anthropic-marketplace)：瀏覽其他官方外掛程式

claude-tag.md +11 −0 created

Details

1> ## Documentation Index

2> 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.

5# Claude Tag

7> 透過 Claude Tag 將 Claude 帶入您的團隊 Slack 頻道，並在 claude.com 上找到其設定和使用文件。

9[Claude Tag](https://claude.com/product/tag) 是一個 Slack 整合，在您的團隊頻道中以組織的共享身份執行 `@Claude`，具有管理員配置的存取權限。頻道中的任何人都可以在執行緒中標記 `@Claude` 並為其指派任務。請閱讀 claude.com 上的 [Claude Tag 文件](https://claude.com/docs/claude-tag/overview)，以設定並開始使用它。

11Claude Tag 適用於 Team 和 Enterprise 方案，與較早的 [Claude Code in Slack](/docs/zh-TW/slack) 不同，後者在個別使用者的帳戶下執行每個工作階段。在 Pro 和 Max 方案上，Claude Tag 不可用，Claude Code in Slack 仍然是設定路徑。

cli-reference.md +4 −4

Details

13您可以使用這些命令來啟動工作階段、管道內容、繼續對話和管理更新：13您可以使用這些命令來啟動工作階段、管道內容、繼續對話和管理更新：

14 14

15| 命令 | 描述 | 範例 |15| 命令 | 描述 | 範例 |

16| :------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------- |16| :------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------- |

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

44| `claude remote-control` | 啟動 [Remote Control](/docs/zh-TW/remote-control) 伺服器以從 Claude.ai 或 Claude 應用程式控制 Claude Code。在伺服器模式下執行（無本機互動式工作階段）。請參閱 [伺服器模式旗標](/docs/zh-TW/remote-control#start-a-remote-control-session)。停止伺服器後，您可以恢復它正在服務的工作階段。請參閱 [停止伺服器後恢復工作階段](/docs/zh-TW/remote-control#resume-sessions-after-stopping-the-server) | `claude remote-control --name "My Project"` |44| `claude remote-control` | 啟動 [Remote Control](/docs/zh-TW/remote-control) 伺服器以從 Claude.ai 或 Claude 應用程式控制 Claude Code。在伺服器模式下執行（無本機互動式工作階段）。請參閱 [伺服器模式旗標](/docs/zh-TW/remote-control#start-a-remote-control-session)。停止伺服器後，您可以恢復它正在服務的工作階段。請參閱 [停止伺服器後恢復工作階段](/docs/zh-TW/remote-control#resume-sessions-after-stopping-the-server) | `claude remote-control --name "My Project"` |

45| `claude respawn <id>` | 重新啟動 [背景工作階段](/docs/zh-TW/agent-view#manage-sessions-from-the-shell)（執行中或已停止），保持其對話完整。使用 `--all` 重新啟動每個執行中的工作階段，例如以取得更新的 Claude Code 二進位檔 | `claude respawn 7c5dcf5d` |45| `claude respawn <id>` | 重新啟動 [背景工作階段](/docs/zh-TW/agent-view#manage-sessions-from-the-shell)（執行中或已停止），保持其對話完整。使用 `--all` 重新啟動每個執行中的工作階段，例如以取得更新的 Claude Code 二進位檔 | `claude respawn 7c5dcf5d` |

46| `claude rm <id>` | 從清單中移除 [背景工作階段](/docs/zh-TW/agent-view#manage-sessions-from-the-shell)。接受 `--discard-unpushed <commit>@<worktree-id>` 以捨棄 worktree 及其提交；當 [刪除因未推送的提交而被拒絕](/docs/zh-TW/agent-view#what-deleting-a-session-removes) 時，拒絕會列印要傳遞的確切值。`--discard-unpushed` 需要 Claude Code v2.1.260 或更新版本。對話文字記錄保留在您的本機電腦上，可透過 `claude --resume` 取得 | `claude rm 7c5dcf5d` |46| `claude rm <id>` | 從清單中移除 [背景工作階段](/docs/zh-TW/agent-view#manage-sessions-from-the-shell)。當移除因工作樹上的未推送提交而被拒絕時，[拒絕會列印確切的旗標和值以傳遞](/docs/zh-TW/agent-view#what-deleting-a-session-removes)：`--discard-unpushed <commit>@<worktree-id>` 會捨棄具有未推送提交的工作樹及這些提交，`--force-remove-worktree <worktree-id>` 會刪除 git 或 `WorktreeRemove` 鉤子無法移除的工作樹目錄。`--discard-unpushed` 需要 Claude Code v2.1.260 或更新版本，而 `--force-remove-worktree` 需要 v2.1.268 或更新版本。對話文字記錄保留在您的本機電腦上，可透過 `claude --resume` 取得 | `claude rm 7c5dcf5d` |

47| `claude self-hosted-runner` | 啟動執行程序，將此機器或容器註冊到 [自託管環境](/docs/zh-TW/self-hosted-environments)，並在您的基礎設施上託管 Claude Code 雲端工作階段。執行 `claude self-hosted-runner setup` 以進行引導式操作員逐步解說，執行 `claude self-hosted-runner doctor` 以 [診斷已部署的執行程序](/docs/zh-TW/self-hosted-environments-deploy#troubleshooting)，執行 `claude self-hosted-runner orchestrator` 以生成 [隨選執行程序](/docs/zh-TW/self-hosted-environments-configuration#on-demand-runners)。需要 Claude Code v2.1.224 或更新版本 | `claude self-hosted-runner setup` |47| `claude self-hosted-runner` | 啟動執行程序，將此機器或容器註冊到 [自託管環境](/docs/zh-TW/self-hosted-environments)，並在您的基礎設施上託管 Claude Code 雲端工作階段。執行 `claude self-hosted-runner setup` 以進行引導式操作員逐步解說，執行 `claude self-hosted-runner doctor` 以 [診斷已部署的執行程序](/docs/zh-TW/self-hosted-environments-deploy#troubleshooting)，執行 `claude self-hosted-runner orchestrator` 以生成 [隨選執行程序](/docs/zh-TW/self-hosted-environments-configuration#on-demand-runners)。需要 Claude Code v2.1.224 或更新版本 | `claude self-hosted-runner setup` |

137| `--teammate-mode` | 設定 [agent team](/docs/zh-TW/agent-teams) 隊友的顯示方式：`in-process`（預設）、`auto`、`tmux` 或 `iterm2`（在 v2.1.186 中新增）。覆蓋此工作階段的 [`teammateMode`](/docs/zh-TW/settings-reference#teammatemode) 設定。請參閱 [Choose a display mode](/docs/zh-TW/agent-teams#choose-a-display-mode) | `claude --teammate-mode auto` |137| `--teammate-mode` | 設定 [agent team](/docs/zh-TW/agent-teams) 隊友的顯示方式：`in-process`（預設）、`auto`、`tmux` 或 `iterm2`（在 v2.1.186 中新增）。覆蓋此工作階段的 [`teammateMode`](/docs/zh-TW/settings-reference#teammatemode) 設定。請參閱 [Choose a display mode](/docs/zh-TW/agent-teams#choose-a-display-mode) | `claude --teammate-mode auto` |

139| `--tools` | 限制 Claude 可以使用的內建工具。使用 `""` 停用全部、`"default"` 為全部，或工具名稱如 `"Bash,Edit,Read"`。如果您在此命名其中一個 [task-tracking tools](/docs/zh-TW/tools-reference#task-tool-availability)，Claude Code 也會選擇加入工作階段。旗標不會影響 MCP tools；若要拒絕這些工具，請改用 `--disallowedTools "mcp__*"`。省略 [`EndConversation`](/docs/zh-TW/tools-reference#endconversation-tool-behavior) 的清單不會移除它；`""` 僅在沒有 MCP tools 保持時移除它 | `claude --tools "Bash,Edit,Read"` |139| `--tools` | 限制 Claude 可以使用的內建工具。使用 `""` 停用全部、`"default"` 為預設集合，或工具名稱如 `"Bash,Edit,Read"`。在 macOS、Linux 和 WSL 上，預設集合會排除 `Glob` 和 `Grep`，如 [Glob tool behavior](/docs/zh-TW/tools-reference#glob-tool-behavior) 下所述。如果您在此命名其中一個 [task-tracking tools](/docs/zh-TW/tools-reference#task-tool-availability)，Claude Code 也會選擇加入工作階段。旗標不會影響 MCP tools；若要拒絕這些工具，請改用 `--disallowedTools "mcp__*"`。省略 [`EndConversation`](/docs/zh-TW/tools-reference#endconversation-tool-behavior) 的清單不會移除它；`""` 僅在沒有 MCP tools 保持時移除它 | `claude --tools "Bash,Edit,Read"` |

142| `--worktree`、`-w` | 在隔離的 [git worktree](/docs/zh-TW/worktrees) 中啟動 Claude，位於 `<repo>/.claude/worktrees/<name>`。如果未提供名稱，Claude Code 會產生一個。傳遞 `#<number>`、GitHub 提取請求 URL 或 GitLab 合併請求 URL 以 [從 `origin` 擷取該 PR 或 MR 並從它分支 worktree](/docs/zh-TW/worktrees#branch-from-a-pull-request)。從 GitLab 合併請求分支需要 Claude Code v2.1.233 或更新版本 | `claude -w feature-auth` |142| `--worktree`、`-w` | 在隔離的 [git worktree](/docs/zh-TW/worktrees) 中啟動 Claude，位於 `<repo>/.claude/worktrees/<name>`。如果未提供名稱，Claude Code 會產生一個。傳遞 `#<number>`、GitHub 提取請求 URL 或 GitLab 合併請求 URL 以 [從 `origin` 擷取該 PR 或 MR 並從它分支 worktree](/docs/zh-TW/worktrees#branch-from-a-pull-request)。從 GitLab 合併請求分支需要 Claude Code v2.1.233 或更新版本 | `claude -w feature-auth` |

167 167

168預設情況下，Claude Code 在對話的第一個請求上建立系統提示一次，應用任何系統提示旗標中的文字，並在工作階段中記錄它。在對話被壓縮之前，每個稍後的請求都會使用該記錄的提示，包括在您使用 `--resume` 或 `--continue` 返回對話後。如果您在該稍後的啟動上傳遞不同的系統提示旗標文字或沒有，它會在對話被壓縮或您啟動新對話時生效。168預設情況下，Claude Code 在對話的第一個請求上建立系統提示一次，應用任何系統提示旗標中的文字，並在工作階段中記錄它。在對話被壓縮之前，每個稍後的請求都會使用該記錄的提示，包括在您使用 `--resume` 或 `--continue` 返回對話後。如果您在該稍後的啟動上傳遞不同的系統提示旗標文字或沒有，它會在對話被壓縮或您啟動新對話時生效。

169 169

170記錄適用於 [fetch feature flags](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching) 的工作階段，因為使用 claude.ai 或 Console 帳戶登入的工作階段預設會執行此操作。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和其他不擷取它們的工作階段中，Claude Code 在每個請求上重建提示，`--system-prompt-snapshot` 無效。如果您透過傳遞 `--bare` 或設定 `CLAUDE_CODE_SIMPLE=1` 在 [bare mode](/docs/zh-TW/headless#start-faster-with-bare-mode) 中啟動 Claude Code，記錄會保持關閉，除非您傳遞 `--system-prompt-snapshot on`。170如果您以 [bare mode](/docs/zh-TW/headless#start-faster-with-bare-mode) 啟動 Claude Code，透過傳遞 `--bare` 或設定 `CLAUDE_CODE_SIMPLE=1`，記錄會保持關閉，除非您傳遞 `--system-prompt-snapshot on`。在 v2.1.268 之前，不 [fetch feature flags](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching) 的工作階段（包括 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上的工作階段）在每個請求上重建提示，`--system-prompt-snapshot` 無效。

171 171

172若要改為在每個請求上重建提示，例如當您在 `--continue` 執行中反覆進行其措辭時，請傳遞 `--system-prompt-snapshot off`。在 v2.1.265 之前，傳遞任何系統提示旗標也會關閉記錄，除非您傳遞 `--system-prompt-snapshot on`。172若要改為在每個請求上重建提示，例如當您在 `--continue` 執行中反覆進行其措辭時，請傳遞 `--system-prompt-snapshot off`。在 v2.1.265 之前，傳遞任何系統提示旗標也會關閉記錄，除非您傳遞 `--system-prompt-snapshot on`。

173 173

cloud-environments.md +806 −0 created

Details

1> ## Documentation Index

2> 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.

5# 設定雲端環境

7> 為 Claude Code 雲端工作階段設定雲端環境：網路存取層級、環境變數、設定指令碼和環境快取。

9<Note>

10 雲端環境需要 [Claude Code on the web](/docs/zh-TW/claude-code-on-the-web)，該功能目前處於研究預覽階段，適用於 Pro、Max 和 Team 使用者，以及具有 [premium seats 或 Chat + Claude Code seats](https://support.claude.com/en/articles/11845131-use-claude-code-with-your-team-or-enterprise-plan) 的 Enterprise 使用者。

11</Note>

13每個 [雲端工作階段](/docs/zh-TW/claude-code-on-the-web) 都在雲端環境中執行。您可以設定環境以允許或拒絕 [網路存取](#access-levels)、[為工作階段設定環境變數](#set-environment-variables)，在 Pro 和 Max 方案上儲存工作階段使用的 [API 認證](#add-api-credentials) 而不會看到它們，以及在 Claude 開始工作前執行 [設定指令碼](#setup-scripts)。

15相同的環境適用於您啟動雲端工作階段的任何地方：[Claude Code on the web](/docs/zh-TW/claude-code-on-the-web)、終端機搭配 [`claude --cloud`](/docs/zh-TW/claude-code-on-the-web#from-terminal-to-web)、[Claude Tag](https://claude.com/docs/claude-tag/overview)、[routines](/docs/zh-TW/routines)、[Claude 行動應用程式](/docs/zh-TW/mobile) 和 [Desktop 應用程式](/docs/zh-TW/desktop)。這些介面中的每一個也可以路由到 [自託管環境](/docs/zh-TW/self-hosted-environments)。[可用性和限制](/docs/zh-TW/self-hosted-environments#availability-and-limitations) 涵蓋當 Claude Tag 工作階段在其中執行時 Claude 尚無法使用的內容。

17<Info>

18 [Remote Control](/docs/zh-TW/remote-control) 工作階段將網頁和行動介面連接到您自己機器上的工作階段，該工作階段使用您機器的網路和檔案，而不是雲端環境。Claude Tag 頻道工作階段僅使用組織層級環境，可以是 [共用環境](#organization-shared-environments) 或 [自託管環境](/docs/zh-TW/self-hosted-environments)。

19</Info>

21<h2 id="the-default-environment">

22 Default 環境

23</h2>

25如果您還沒有環境，上線設定會為您設定 **Default** 環境。具體方式取決於您在哪裡上線：

27* **CLI 流程（例如 `/web-setup`）**：為您建立 **Default**

28* **Pro 和 Max 上的網頁上線設定**：為您建立 **Default**

29* **Team 和 Enterprise 上的網頁上線設定**：顯示 **Create your first cloud environment** 表單，除非管理員已開啟[快速網頁設定](/docs/zh-TW/claude-code-on-the-web#github-authentication-options)；保持表單的預設值並點擊 **Create & finish** 以取得相同的 **Default** 環境

31**Default** 本身不帶有任何設定：

33* [**Trusted** 網路存取](#access-levels)：工作階段可以到達套件登錄檔和其他[允許清單中的網域](#default-allowed-domains)，但無法透過工作階段的網路到達其他任何內容。

34* 無其他設定：**Default** 不定義任何環境變數或設定指令碼，因此工作階段只會以[預先安裝的工具](#installed-tools)開始。

36只有 **Default** 可用時，每個工作階段都在其中執行。當您有多個環境時，工作階段會根據介面選擇一個：

38* 在網頁、桌面應用程式和行動應用程式上，工作階段使用[選擇器](#configure-your-environment)中顯示的環境。當您尚未選擇時，管理員設定的[組織預設](#organization-shared-environments)會填入選擇。

39* 從 CLI，Claude Code 使用您的 [`/remote-env` 選擇](#select-an-environment-from-the-cli)，或在您的清單有一個時回退到 Anthropic 託管的環境，否則回退到您清單中第一個不是橋接環境的環境，即 [Remote Control](/docs/zh-TW/remote-control) 登錄以代表您自己的機器而非雲端環境的項目。對於[自託管環境](/docs/zh-TW/self-hosted-environments)，在[分派工作階段](/docs/zh-TW/self-hosted-environments-testing#run-the-test-loop)時使用其 `ccpool_` ID 傳遞 `--environment <environment-id>` 會覆蓋該調用的 `/remote-env` 選擇和回退。Claude Code 拒絕傳遞給該旗標的 Anthropic 託管 `env_` ID，因此使用 `/remote-env` 來定位這些。該旗標需要 Claude Code v2.1.224 或更新版本。

41當預設不夠時，請設定環境：當 Claude 需要到達[預設允許清單](#default-allowed-domains)之外的網域、需要為其工作階段設定環境變數，或需要在開始工作前安裝相依性時。

43<h2 id="configure-your-environment">

44 設定您的環境

45</h2>

47在 [claude.ai/code](https://claude.ai/code) 上建立、編輯和封存環境，您可以在 [Web 快速入門](/docs/zh-TW/web-quickstart)後或從 [Desktop 應用程式](/docs/zh-TW/desktop#cloud-sessions)的提示框中存取環境選擇器。您建立的環境是您帳戶的個人環境；由擁有者建立的[共用環境](#organization-shared-environments)會出現在相同的選擇器中。請參閱[已安裝的工具](#installed-tools)以了解無需任何設定即可使用的工具。

49<Steps>

50 <Step title="開啟環境選擇器">

51 在 [claude.ai/code](https://claude.ai/code) 上，選擇顯示目前環境名稱的雲端圖示，位於訊息框上方的列中。選擇器沒有設定頁面或直接 URL。

53 <Frame>

54 <img src="https://mintcdn.com/claude-code/ZFId6l95856c5LSw/images/cloud-environment-selector.png?fit=max&auto=format&n=ZFId6l95856c5LSw&q=85&s=cc2813a5664519eaf5a89d793ce5af26" alt="環境選擇器在 claude.ai/code 的訊息框上方開啟。顯示環境名稱「預設」的雲端按鈕位於訊息框上方的列中。開啟的選單列出本機列（僅顯示「下載」和「Desktop」標籤）、雲端區段（其中「預設」環境被選中並顯示核取記號，滑鼠懸停時顯示設定齒輪圖示）、「新增雲端環境」選項，以及「遠端控制」區段（包含設定說明）。" width="1672" height="682" data-path="images/cloud-environment-selector.png" />

55 </Frame>

56 </Step>

58 <Step title="新增或編輯環境">

59 選擇**新增雲端環境**，或將滑鼠懸停在現有環境上，然後選擇右側出現的設定圖示。對話框包括名稱、網路存取層級、環境變數和設定指令碼。當您在 Pro 或 Max 方案上編輯現有的雲端環境時，對話框還包括 [API 認證](#add-api-credentials)。

61 <Frame>

62 <img src="https://mintcdn.com/claude-code/ZFId6l95856c5LSw/images/cloud-environment-dialog.png?fit=max&auto=format&n=ZFId6l95856c5LSw&q=85&s=30d4478b31d1f879f7ee287ddab32505" alt="新增雲端環境對話框。名稱欄位，預留位置為「預設」；網路存取選擇器設定為「信任」，並包含網路政策和存取層級的連結；環境變數框顯示 .env 格式的預留位置文字，並附註值對使用該環境的任何人都可見；設定指令碼框描述為 Bash 指令碼，在新工作階段啟動時執行，在 Claude Code 啟動前執行；以及「取消」和「建立環境」按鈕。" width="874" height="1372" data-path="images/cloud-environment-dialog.png" />

63 </Frame>

64 </Step>

65</Steps>

67<h3 id="set-environment-variables">

68 設定環境變數

69</h3>

71環境變數使用 `.env` 格式，每行一個 `KEY=value` 對。純值不需要引號，如果您用匹配的一對引號引用值，引號不會成為值的一部分。引用跨越多行或包含 `#` 的值：在未引用的值中，`#` 開始註解，該行的其餘部分會被捨棄。

73以下範例定義三個變數。

75```text theme={null}

76NODE_ENV=development

77LOG_LEVEL=debug

78DATABASE_URL=postgres://localhost:5432/myapp

79```

81每個工作階段在啟動時將環境的值複製一次到普通環境變數中，Claude 執行的任何命令都可以讀取。由於執行中的工作階段不會重新讀取設定，編輯或新增變數會影響您之後啟動的工作階段；已執行的工作階段會保留它們啟動時的值。

83Claude Code 在網路上也會在啟動工作階段時自行設定一些變數。對於 [`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`](/docs/zh-TW/claude-code-on-the-web#manage-context)，Claude Code 在網路上設定的值會覆蓋您在此新增的值，因此在此新增該金鑰沒有效果。

85使用該環境的任何人都可以讀取這些值。在 Pro 和 Max 方案上，改為使用 [API 認證](#add-api-credentials)來取得代理程式可以附加到請求的金鑰。[永遠不會取得認證的請求](#requests-that-never-get-the-credential)列在那裡。

87<h3 id="add-api-credentials">

88 新增 API 認證

89</h3>

91API 認證是您儲存在雲端環境上的 API 金鑰或權杖，以便 Claude 可以從環境中的任何工作階段呼叫該 API，而無需查看金鑰。Anthropic 的代理程式會在每個請求離開工作階段的 VM 後，將金鑰新增到您列出的主機的請求中。金鑰永遠不會到達 Claude、它執行的命令或工作階段的環境變數。

93API 認證在 Pro 和 Max 方案上可用。它們在 Team 或 Enterprise 方案上尚不可用，因此 **API 認證**區段不會出現在這些方案的環境對話框中。

95<h4 id="requirements">

96 需求

97</h4>

99其中兩個決定您是否可以新增認證，另外兩個決定代理程式在新增後是否可以使用它：

100

101* **角色**：您的 claude.ai 組織中的組織管理員角色

102 * 在 Team 和 Enterprise 上，擁有者持有它，管理員沒有

103 * 在 Pro 和 Max 上，您在自己的組織中持有它

104 * 沒有它，您會看到一個註記而不是認證清單，即使在您自己的環境上也是如此。請要求擁有者將認證新增到共用環境並在那裡執行您的工作階段

105* **環境類型**：已存在的 Anthropic 託管雲端環境。[自託管環境](/docs/zh-TW/self-hosted-environments)沒有 API 認證

106* **API 可達性**：API 接受來自網際網路的連線，因為請求來自 Anthropic 的網路

107* **加密金鑰**：如果您的組織使用客戶管理的加密金鑰，您無法儲存認證

108

109<h4 id="add-a-credential">

110 新增認證

111</h4>

112

113您從已存在的環境編輯器一次新增一個認證。新環境的對話框不提供它們。也沒有編輯。若要變更認證的主機或值，請刪除它並再次新增。

114

115<Steps>

116 <Step title="開啟環境的 API 認證">

117 在 [claude.ai/code](https://claude.ai/code) [開啟環境進行編輯](#configure-your-environment)。在**更新雲端環境**對話框中，在**環境變數**下方找到 **API 認證**。您會看到環境上已有的認證，每個都顯示它適用的主機。

118 </Step>

119

120 <Step title="新增認證">

121 選擇**新增認證**並填寫表單。保留預設的**認證類型** **Bearer**，用於在請求標頭中傳輸的 API 金鑰，並填寫這些欄位：

122

123 * **名稱**：認證的標籤，例如 `Internal billing API`

124 * **允許的網站**：API 的主機，例如 `api.example.com`。前導 `*.` 符合每個子網域

125 * **自訂標頭**：標頭的一列，該標頭攜帶金鑰。該列以 `Authorization` 作為標頭的**名稱**和 `Bearer` 作為其**前綴**開始；將金鑰本身貼上為**值**。對於採用裸值的標頭（如 `X-Api-Key`），變更名稱並清除前綴

126

127 對於以其他方式進行身份驗證的 API，請選擇不同的**認證類型**。清單與 [Claude Tag](https://claude.com/docs/claude-tag/overview)（Team 和 Enterprise 方案的 Slack 整合）為[連線](https://claude.com/docs/claude-tag/admins/add-connections)提供的清單相同。

128 </Step>

129

130 <Step title="儲存認證">

131 選擇**連線**。認證出現在清單中，其主機已儲存，無需對話框的**儲存變更**按鈕。儲存後，您無法再次檢視該值。

132 </Step>

133</Steps>

134

135若要確認認證有效，請在環境中啟動工作階段並要求 Claude 呼叫 API，例如使用 `curl`。API 的回應就像金鑰在請求中一樣，金鑰不會出現在工作階段的環境變數或任何檔案中。如果清單將認證標記為**未傳送**，其下方的註記會說明原因和解決方法。兩個主機重疊但不完全相符的認證不會獲得標記，代理程式只會傳送其中一個。

136

137<h4 id="which-requests-get-the-credential">

138 哪些請求會取得認證

139</h4>

140

141當請求的主機符合您在該認證上列出的主機之一時，代理程式會將認證附加到請求。工作階段可以到達這些主機，即使環境的[網路存取層級](#access-levels)否則不允許，除了[永遠不會取得認證的主機](#requests-that-never-get-the-credential)。認證適用於在環境中執行的每個工作階段，無論誰啟動它，直到您刪除它。

142

143<h4 id="requests-that-never-get-the-credential">

144 永遠不會取得認證的請求

145</h4>

146

147代理程式永遠不會將您新增的認證附加到這些請求：

148

149* **GitHub**：[GitHub 代理程式](#github-proxy)改為驗證對 GitHub 的請求，因此您不需要為其提供 API 認證

150* **Anthropic API 和公開套件登錄**：`api.anthropic.com`、`registry.npmjs.org`、`jsr.io`、`npm.jsr.io`、`pypi.org`、`files.pythonhosted.org`、`index.crates.io` 和 `proxy.golang.org` — 代理程式永遠不會將您新增的認證附加到對這些主機的請求

151* **設定指令碼請求**：Claude Code 在啟動時連線到代理程式，在[設定指令碼](#setup-scripts)執行後

152

153<h3 id="select-an-environment-from-the-cli">

154 從 CLI 選擇環境

155</h3>

156

157在您的終端中執行 `/remote-env` 以選擇您從 CLI 建立的雲端工作階段的預設環境，例如 [`claude --cloud`](/docs/zh-TW/claude-code-on-the-web#from-terminal-to-web)。該命令開啟現有環境的選擇器，並將您的選擇儲存到[使用者設定](/docs/zh-TW/settings#where-settings-live)中的 `remote.defaultEnvironmentId` 金鑰，因此它適用於您機器上的每個專案，直到您變更它，除非在更高優先順序的[設定層](/docs/zh-TW/settings#settings-precedence)（例如儲存庫的專案設定）上設定相同的金鑰。

158

159[自託管環境](/docs/zh-TW/self-hosted-environments) ID（形式為 `ccpool_...`）遵循更嚴格的來源規則。請參閱 [`remote.defaultEnvironmentId`](/docs/zh-TW/settings-reference#remote-defaultenvironmentid) 以了解 Claude Code 從中接受它的設定層。

160

161`/remote-env` 只設定預設值：它不啟動工作階段，也無法新增或編輯環境。從[環境選擇器](#configure-your-environment)管理它們。

162

163<h3 id="archive-an-environment">

164 封存環境

165</h3>

166

167若要封存環境，請開啟它進行編輯並選擇**封存**。您無法刪除環境，只能封存它。

168

169封存會影響新工作階段，而不是執行中的工作階段：

170

171* 已在環境中執行的工作階段會繼續工作。

172* 環境從選擇器和 `/remote-env` 中消失，因此您無法為新工作階段選擇它。

173* 環境上的 API 認證在其執行中的工作階段中保持附加。在封存前刪除您不再需要的任何認證。

174* 沒有新工作階段可以在任何表面上的封存環境中啟動。如果環境是您儲存的 [CLI 預設](#select-an-environment-from-the-cli)，當您的清單有一個時，Claude Code 會在 Anthropic 託管環境中啟動 CLI 雲端工作階段，否則在清單中不是[遠端控制橋接環境](#the-default-environment)的第一個環境中啟動。任何明確使用環境設定的內容，例如[例行程序](/docs/zh-TW/routines#environments-and-network-access)，無法在其中啟動新工作階段。將其指向另一個環境。

175

176<h3 id="organization-shared-environments">

177 組織共用環境

178</h3>

179

180在 Team 和 Enterprise 方案上，擁有者可以建立與組織的每個成員共用的雲端環境。相同的角色管理**雲端環境**管理頁面上的所有其他內容，包括[自託管環境](/docs/zh-TW/self-hosted-environments)；管理員角色無法開啟該頁面。可以開啟它的完整角色清單是[管理伺服器管理的設定](/docs/zh-TW/server-managed-settings#access-control)的角色清單。共用環境與個人環境一起出現在每個成員的環境選擇器中，因此團隊可以標準化一個設定，而不是每個成員重新建立它。

181

182從 [admin 設定](https://claude.ai/admin-settings)中的**雲端環境**頁面建立、編輯和封存共用環境。共用環境也可以從 [claude.ai/code](https://claude.ai/code) 的[環境選擇器](#configure-your-environment)開啟：擁有者可以在那裡編輯它。其他成員以唯讀方式看到它。每個共用環境都有一個名稱、一個[網路存取層級](#access-levels)、`.env` 格式的[環境變數](#set-environment-variables)和一個[設定指令碼](#setup-scripts)。擁有者在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 分別選擇組織的[預設環境](#the-default-environment)。

183

184每個成員在共用環境中的工作階段都會讀取其變數，因此不要在其中包含機密。[API 認證](#add-api-credentials)（為工作階段提供它們無法讀取的金鑰）在 Team 或 Enterprise 方案上尚不可用。

185

186<h3 id="set-the-environment-a-claude-tag-channel-uses">

187 設定 Claude Tag 頻道使用的環境

188</h3>

189

190在 [Claude Tag](https://claude.com/docs/claude-tag/overview) 頻道中，Claude 作為您組織的共用身分工作，而不是任何成員，因此頻道工作階段只使用組織級別的環境，即共用環境或[自託管環境](/docs/zh-TW/self-hosted-environments)。若要為頻道提供不是[預先安裝](#installed-tools)的工具鏈（例如 .NET），擁有者可以從**雲端環境** admin 頁面建立[共用環境](#organization-shared-environments)，其中包含[設定指令碼](#setup-scripts)來安裝它。以兩種方式之一將頻道指向環境：

191

192* 在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 將共用或自託管環境設定為組織的[預設環境](#the-default-environment)。

193* 在 Claude Tag admin 設定中[將其釘選到頻道](https://claude.com/docs/claude-tag/admins/troubleshooting#channel-sessions-use-the-wrong-environment-or-can%E2%80%99t-find-one)。

194

195<h2 id="network-access">

196 網路存取

197</h2>

198

199每個環境都設定一個網路存取層級，控制其工作階段可以進行的出站連線。預設層級 **Trusted** 允許套件登錄和其他[允許清單中的網域](#default-allowed-domains)；**Custom** 採用您自己的網域清單。

200

201若要變更環境的網路存取，[開啟它進行編輯](#configure-your-environment)並在對話框中使用 **Network access** 選擇器。開啟選擇器的雲端圖示出現在[Default 環境](#the-default-environment)下列出的應用程式表面上，以及在[例行編輯器](/docs/zh-TW/routines#environments-and-network-access)中；個人環境在您的 claude.ai 帳戶設定中沒有單獨的頁面。

202

203<Note>

204 您在工作階段或例行上啟用的 MCP 連接器無需將其主機新增到 **Allowed domains**，因為連接器流量透過 Anthropic 的伺服器而不是工作階段的網路傳輸。您可以按工作階段或按例行配置連接器；移除任何您不需要的連接器，以限制 Claude 可以到達的工具。這依賴於[安全性和隔離](/docs/zh-TW/claude-code-on-the-web#security-and-isolation)下提到的相同 Anthropic 繫結通道。

205</Note>

206

207<h3 id="access-levels">

208 存取層級

209</h3>

210

211[環境對話框](#configure-your-environment)中的 **Network access** 欄位採用以下四個層級之一：

212

213| 層級 | 出站連線 |

214| :---------- | :-------------------------------------------------------- |

215| **None** | 透過工作階段的網路沒有出站網路存取 |

216| **Trusted** | 僅限[允許清單中的網域](#default-allowed-domains)：套件登錄、GitHub、雲端 SDK |

217| **Full** | 任何網域 |

218| **Custom** | 您自己的允許清單，可選擇性地包括預設值 |

219

220無論您選擇哪個層級，工作階段仍然可以到達這些，因為每一個都採用不通過工作階段的網路允許清單的路徑：

221

222* GitHub，透過其[單獨的代理](#github-proxy)

223* 您啟用的 [MCP 連接器](#network-access)，其流量透過 Anthropic 的伺服器傳輸

224* 您在環境的 [API 認證](#add-api-credentials)上列出的主機，除了[代理跳過的主機](#requests-that-never-get-the-credential)

225* Anthropic API，用於 Claude Code 自己的請求，即使在 **None** 時也是如此，如[安全性和隔離](/docs/zh-TW/claude-code-on-the-web#security-and-isolation)下所述

226

227<h3 id="allow-specific-domains">

228 允許特定網域

229</h3>

230

231若要允許不在 Trusted 清單中的網域，在環境的網路存取設定中選擇 **Custom**，然後在 **Allowed domains** 欄位中每行列出一個網域。此範例允許內部專案可能需要的三個主機。

232

233```text theme={null}

234api.example.com

235*.internal.example.com

236registry.example.com

237```

238

239此環境中的工作階段現在可以到達 `api.example.com`、`internal.example.com` 的任何子網域和 `registry.example.com`，但透過工作階段的網路無法到達其他網域。[GitHub 流量](#github-proxy)、[MCP 連接器流量](#network-access)和對環境 [API 認證](#add-api-credentials)主機的請求（除了[代理跳過的主機](#requests-that-never-get-the-credential)）不會通過此允許清單。前導 `*.` 符合每個子網域。若要同時保留[Trusted 網域](#default-allowed-domains)，請勾選 **Also include default list of common package managers**；不勾選則只允許您列出的內容。

240

241如果您的組織使用[成品](/docs/zh-TW/artifacts#availability)，工作階段讀取成品時不需要在清單中包含 `*.frame.claudeusercontent.com`。當清單省略該主機時，Claude Code 會透過工作階段與 Anthropic 的連線讀取成品內容。在兩種情況下將主機保留在允許清單中：

242

243* **此環境中的工作階段開啟另一個組織的公開成品**：Claude Code 直接從主機擷取這些成品，因此將其新增到此清單。

244* **您正在配置本機 CLI 或自託管執行器**：在該允許清單中保留主機。請參閱[網路存取需求](/docs/zh-TW/network-config#network-access-requirements)和自託管[網路需求](/docs/zh-TW/self-hosted-environments-deploy#network-requirements)。

245

246每個環境都有自己的允許網域清單；沒有組織層級的允許清單可供管理員推送到每個成員的環境。[伺服器管理的設定](/docs/zh-TW/server-managed-settings)仍適用於雲端工作階段內，但其中沒有任何設定會將網域新增到環境的網路允許清單。

247

248<h3 id="github-proxy">

249 GitHub 代理

250</h3>

251

252在 Anthropic 託管的環境中，所有 GitHub 操作都通過專用代理，將您的真實 GitHub 認證保留在工作階段的 VM 外，獨立於環境的[存取層級](#access-levels)。自託管環境中的工作階段使用您的部署提供的認證進行 git 操作驗證；[配置 git](/docs/zh-TW/self-hosted-environments-deploy#configure-git) 涵蓋選項，包括按工作階段鑄造的認證和選擇加入此相同代理。代理提供：

253

254* **Git 認證**：VM 內的 git 用戶端使用限定範圍的認證，代理驗證並將其交換為您的實際 GitHub 令牌。

255* **API 請求**：來自內建 GitHub 工具的請求，以及來自 [`proxy-injected` 預留位置](#work-with-github-issues-and-pull-requests)下的 `gh` 的請求，會以您的真實認證替換後發出。

256* **推送保護**：`git push` 僅適用於工作階段的目前工作分支；複製、擷取和 PR 操作正常運作。

257* **儲存庫範圍**：GitHub API 和發行資產請求僅到達附加到工作階段的儲存庫，因此從未附加的儲存庫下載發行資產的設定指令碼會收到 403。

258* **GraphQL 限制**：代理僅提供一組固定的 GraphQL 操作用於拉取請求工作流程。代理在 GraphQL 端點上拒絕所有其他內容，並返回 403，說明 `This GraphQL query is not enabled for this session` 並命名 REST 備用方案 `gh api repos/{owner}/{repo}/...`。無論您提供的認證如何，限制都適用於通過代理的每個請求，因此您設定的 `GH_TOKEN` 會收到相同的 403。Claude 無法透過代理到達僅存在於 GraphQL 中的 GitHub API，例如 Projects v2。

259

260來自公開儲存庫的已提交檔案透過 `raw.githubusercontent.com` 到達，改由[安全代理](#security-proxy)處理。該網域在預設[Trusted 清單](#default-allowed-domains)中，因此除非環境的[存取層級](#access-levels)排除它，否則這些檔案保持可到達。

261

262<h3 id="security-proxy">

263 安全代理

264</h3>

265

266Anthropic 託管環境中的雲端工作階段在 HTTP/HTTPS 網路代理後面執行，用於安全和濫用防止目的；在[自託管環境](/docs/zh-TW/self-hosted-environments-deploy#default-deny-egress)中，出站流量改為通過您自己的網路邊界。來自 Anthropic 託管工作階段的所有出站網際網路流量都通過此代理，提供：

267

268* 防止惡意請求

269* 速率限制和濫用防止

270* 內容篩選以增強安全性

271* 所請求主機名稱的 DNS 層級稽核軌跡

272

273<h2 id="what’s-available-in-cloud-sessions">

274 雲端工作階段中可用的內容

275</h2>

276

277在 Anthropic 託管的環境中，每個工作階段都會取得執行 Ubuntu 24.04 的全新虛擬機器 (VM)，無論您自己的作業系統和 CPU 架構為何，您的儲存庫已複製，常見的工具鏈已預先安裝。當相依性提供預先編譯的二進位檔案（例如具有原生擴充功能的 Ruby gems 或預先建置的 Python wheels）時，請使用其 x86\_64 Linux 建置以符合 VM。本節涵蓋 Anthropic 託管的預設值、內建 GitHub 工具、如何 [執行測試和服務](#run-tests-start-services-and-add-packages)，以及每個 VM 取得的 [資源限制](#resource-limits)。

278

279<Note>

280 您的組織路由到 [自託管環境](/docs/zh-TW/self-hosted-environments) 的工作階段改為在您自己的執行器上執行，搭配您的執行器映像提供的工具。

281</Note>

282

283<h3 id="what-carries-over-from-your-setup">

284 您的設定中帶來的內容

285</h3>

286

287雲端工作階段從您儲存庫的全新複製開始。您提交到儲存庫的任何內容都可用。您只在自己的機器上安裝或設定的任何內容在工作階段中都不可用。您組織的政策透過 [伺服器管理的設定](/docs/zh-TW/server-managed-settings) 分別到達。

288

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

290| :--------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

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

292| 您的儲存庫的 `.claude/settings.json` hooks | 是 | 複製的一部分 |

293| 您的儲存庫的 `.mcp.json` MCP 伺服器 | 是 | 複製的一部分 |

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

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

296| 在 `.claude/settings.json` 中宣告的 Plugins | 是 | 在工作階段啟動時從您宣告的 [marketplace](/docs/zh-TW/plugin-marketplaces) 安裝。需要網路存取以到達 marketplace 來源 |

297| 您組織的 [伺服器管理的設定](/docs/zh-TW/server-managed-settings) | 是 | 在工作階段啟動時從 Anthropic 的伺服器擷取。請參閱 [Surface coverage](/docs/zh-TW/model-config#surface-coverage) 以了解 `availableModels` 在雲端工作階段中如何強制執行。透過 MDM 或管理設定檔部署到您的裝置的設定不適用，因為工作階段在 Anthropic 管理的 VM 上執行；在 [自託管環境](/docs/zh-TW/self-hosted-environments) 中，工作階段也會讀取執行器映像中的管理設定檔，根據 [Claude Code 如何結合管理來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources) |

298| 您的使用者 `~/.claude/CLAUDE.md` | 否 | 位於您的機器上，不在儲存庫中 |

299| 您的使用者 `~/.claude/skills/`、`~/.claude/agents/`、`~/.claude/commands/` | 否 | 位於您的機器上，不在儲存庫中。改為將它們提交到儲存庫的 `.claude/` 目錄。雲端工作階段會自動載入您在 claude.ai 上啟用的技能 |

300| 僅在您的使用者設定中啟用的 Plugins | 否 | 使用者範圍的 `enabledPlugins` 位於 `~/.claude/settings.json`。改為在儲存庫的 `.claude/settings.json` 中宣告它們，或在您的 claude.ai 帳戶上啟用它們，以便 Claude Code 將它們載入為 [同步的 plugins](/docs/zh-TW/plugins-reference#synced-plugins) |

301| 您使用 `claude mcp add` 在預設本機範圍或使用者範圍新增的 MCP 伺服器 | 否 | 這些寫入您機器上的 `~/.claude.json`，不是儲存庫。使用 `claude mcp add --scope project` 新增伺服器，該伺服器寫入儲存庫的 [`.mcp.json`](/docs/zh-TW/mcp#project-scope)，並提交該檔案 |

302| 您的儲存庫的 `.claude/settings.json` `env` 區塊中的傳輸變數，例如 `NODE_EXTRA_CA_CERTS` 和 [mTLS 用戶端憑證變數](/docs/zh-TW/network-config#mtls-authentication) | 否 | 託管環境管理工作階段的 API 連接，因此 Claude Code 忽略這些金鑰，並在工作階段的偵錯日誌中記錄每個忽略的金鑰 |

303| Claude 呼叫的服務的 API 金鑰和令牌 | 在 Pro 和 Max 方案上，作為 [API 認證](#add-api-credentials) | 您在環境上新增金鑰一次，代理程式代理會將其附加到您列出的主機的請求。代理程式代理 [無法附加](#requests-that-never-get-the-credential) 的金鑰，或任何 Team 或 Enterprise 方案上的金鑰，保留在環境變數中 |

304| 互動式驗證，例如 AWS SSO | 否 | 不支援。SSO 需要無法在雲端工作階段中執行的基於瀏覽器的登入 |

305

306若要在雲端工作階段中提供您自己的設定，請將其提交到儲存庫。

307

308任何使用環境的人都可以讀取其環境變數和設定指令碼。對話框在 **環境變數** 下的注意事項說明了這一點，並警告不要在那裡放置機密。在 Pro 和 Max 方案上，改為儲存代理程式代理可以附加的金鑰作為 [API 認證](#add-api-credentials)。

309

310<h3 id="installed-tools">

311 已安裝的工具

312</h3>

313

314雲端工作階段預先安裝了常見的語言執行時、建置工具和資料庫。下表按類別總結了包含的內容。

315

316| 類別 | 包含 |

317| :------------ | :------------------------------------------------------------ |

318| **Python** | Python 3.x，搭配 pip、poetry、uv、black、mypy、pytest、ruff |

319| **Node.js** | 20、21 和 22，搭配 npm、yarn、pnpm、bun¹、eslint、prettier、chromedriver |

320| **Ruby** | 3.1、3.2、3.3，搭配 gem、bundler、rbenv |

321| **PHP** | 8.3，搭配 Composer |

322| **Java** | OpenJDK 21，搭配 Maven 和 Gradle |

323| **Go** | Go，搭配模組支援 |

324| **Rust** | rustc 和 cargo |

325| **C/C++** | GCC、Clang、cmake、ninja、conan |

326| **Docker** | docker、dockerd、docker compose |

327| **Databases** | PostgreSQL 16、Redis 7.0 |

328| **Utilities** | git、gh、jq、yq、ripgrep、tmux、vim、nano |

329

330¹ Bun 已安裝，但在套件擷取時有已知的 [代理相容性問題](#install-dependencies-with-a-sessionstart-hook)。

331

332若要取得此表中大多數工具的版本，請要求 Claude 在雲端工作階段中執行 `check-tools`。它是安裝在工作階段 VM 上的 shell 命令，不是 slash command；您要求 Claude 是因為 [Claude 為您執行所有 VM 命令](#run-tests-start-services-and-add-packages)。對於它不報告的工具，例如 Ruby、PHP、bun、PostgreSQL 或 Redis，請要求 Claude 執行工具自己的版本命令，例如 `psql --version`。

333

334Node.js 版本安裝在 `/opt/node20`、`/opt/node21` 和 `/opt/node22`，預設情況下 22 在 `PATH` 上。若要使用不同的版本，請要求 Claude 將該版本的 `bin` 目錄（例如 `/opt/node20/bin`）前置到 `PATH`。

335

336此清單之外的工具鏈，例如 .NET SDK，即使其套件登錄在 [預設允許清單](#default-allowed-domains) 上也不會預先安裝。使用 [設定指令碼](#setup-scripts) 安裝它們。

337

338<h3 id="work-with-github-issues-and-pull-requests">

339 使用 GitHub 問題和提取請求

340</h3>

341

342雲端工作階段包括內建 GitHub 工具，讓 Claude 無需任何設定即可讀取問題、列出提取請求、擷取差異和發佈評論。這些工具透過 [GitHub 代理](#github-proxy) 使用您在 [GitHub 驗證選項](/docs/zh-TW/claude-code-on-the-web#github-authentication-options) 下設定的任何方法進行驗證，因此您的令牌永遠不會進入容器。

343

344您可以在 [環境設定](#set-environment-variables) 中自己設定 `GH_TOKEN` 或 `GITHUB_TOKEN`，或兩者都不設定，讓 [GitHub 代理](#github-proxy) 為您驗證：

345

346* 如果您設定令牌，它會原封不動地傳遞到容器，因此您的指令碼和 GitHub 的 [`gh` CLI](https://cli.github.com) 直接使用它。

347* 如果您都不設定，[GitHub 代理](#github-proxy) 正在為您的工作階段處理驗證，兩個變數在 Claude 執行的命令中讀取為預留位置字串 `proxy-injected`，代理在出站 GitHub 請求上替換您的真實認證。`gh` 無需您自己的令牌即可工作，但直接讀取 `GITHUB_TOKEN` 的指令碼會取得預留位置，而不是可用的令牌。

348

349您設定的令牌是普通環境變數，因此使用環境的任何人都可以讀取它；代理路徑將認證保留在環境設定和工作階段 VM 之外。

350

351若要檢查哪種情況適用於您的工作階段，請要求 Claude 執行 `echo $GH_TOKEN`。

352

353GitHub 的 [`gh` CLI](https://cli.github.com) 已預先安裝。如果您需要內建工具未涵蓋的 `gh` 命令，例如 `gh release` 或 `gh workflow run`，請要求 Claude 執行它。`gh` 會自動讀取 `GH_TOKEN`，因此您不需要執行 `gh auth login`。

354

355<h3 id="link-output-back-to-the-session">

356 將輸出連結回工作階段

357</h3>

358

359每個雲端工作階段在 claude.ai 上都有一個文字記錄 URL，工作階段可以從 `CLAUDE_CODE_REMOTE_SESSION_ID` 環境變數讀取自己的 ID。使用此在 PR 主體、提交訊息、Slack 貼文或產生的報告中放置可追蹤的連結，以便檢閱者可以開啟產生它們的執行。

360

361Claude 在雲端工作階段中建立的提交包括 `Claude-Session: <url>` git 預告片，PR 主體包括工作階段 URL 在其自己的列上。這需要 v2.1.179 或更新版本。若要省略預告片和 PR 主體連結，請將 [`attribution.sessionUrl`](/docs/zh-TW/settings-reference#attribution-sessionurl) 設定為 `false`。此設定需要 v2.1.182 或更新版本。

362

363若要在提交或 PR 以外的內容中包含工作階段連結，例如 Claude 發佈的 Slack 訊息或它寫入的報告檔案，請要求 Claude 執行以下命令並使用其輸出。該命令將環境變數值中的 `cse_` 前綴轉換為文字記錄 URL 預期的 `session_` 前綴：

364

365```bash theme={null}

366echo "https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID/#cse_/session_}"

367```

368

369<h3 id="run-tests-start-services-and-add-packages">

370 執行測試、啟動服務和新增套件

371</h3>

372

373您無法進入工作階段 VM 的 shell。Claude 為您執行每個命令，因此請將本節中的工作表述為您提示中的請求。

374

375<h4 id="run-tests">

376 執行測試

377</h4>

378

379Claude 執行測試作為處理工作的一部分。在您的提示中要求它，例如「修復 `tests/` 中的失敗測試」或「在每次變更後執行 pytest」。隨 [預先安裝的工具鏈](#installed-tools) 提供的測試執行器（例如 pytest 和 cargo test）無需額外設定即可工作。您的專案宣告為相依性的執行器（例如 jest）會隨您的相依性一起安裝。

380

381<h4 id="start-services">

382 啟動服務

383</h4>

384

385PostgreSQL 和 Redis 已預先安裝但預設不執行。要求 Claude 啟動您需要的任何一個；它執行的命令是：

386

387```bash theme={null}

388service postgresql start

389```

390

391```bash theme={null}

392service redis-server start

393```

394

395Docker 可用於執行容器化服務。要求 Claude 執行 `docker compose up` 以啟動您專案的服務。拉取映像的網路存取遵循您環境的 [存取層級](#access-levels)，[Trusted 預設值](#default-allowed-domains) 包括 Docker Hub 和其他常見登錄。

396

397如果您的映像很大或拉取速度很慢，請將 `docker compose pull` 或 `docker compose build` 新增到您的 [設定指令碼](#setup-scripts)。[環境快取](#environment-caching) 保留拉取的映像，因此每個新工作階段都在磁碟上有它們。快取僅儲存檔案，不儲存執行中的程序，因此 Claude 仍然每個工作階段啟動容器。

398

399<h4 id="add-packages">

400 新增套件

401</h4>

402

403若要新增未預先安裝的套件，請使用 [設定指令碼](#setup-scripts)。[環境快取](#environment-caching) 保留指令碼安裝的內容，因此您在那裡安裝的套件在每個工作階段開始時都可用，無需每次重新安裝。您也可以要求 Claude 在工作階段中期安裝套件，但這些安裝不會帶到其他工作階段。

404

405<h3 id="resource-limits">

406 資源限制

407</h3>

408

409Anthropic 託管環境中的雲端工作階段執行時具有可能隨時間變化的近似資源上限：

410

411* 4 vCPU

412* 16 GB RAM

413* 30 GB 磁碟

414

415VM 可能會停止需要明顯更多記憶體的工作，例如大型建置工作或記憶體密集型測試。對於超出這些限制的工作負載，請使用 [Remote Control](/docs/zh-TW/remote-control) 在您自己的硬體上執行 Claude Code，或在 [自託管環境](/docs/zh-TW/self-hosted-environments) 中執行雲端工作階段，在您的組織操作的計算上。

416

417<h2 id="setup-scripts">

418 設定指令碼

419</h2>

420

421設定指令碼是一個 Bash 指令碼，在新的雲端工作階段啟動時執行，在 Claude Code 啟動之前執行。使用設定指令碼來安裝相依性、設定工具，或取得工作階段需要但未預先安裝的任何內容。

422

423指令碼以 root 身份在 Ubuntu 24.04 上執行，因此 `apt install` 和大多數語言套件管理員都能運作。

424

425若要新增設定指令碼，請開啟環境設定對話框，並在 **Setup script** 欄位中輸入您的指令碼。

426

427此範例安裝 [ShellCheck](https://www.shellcheck.net/)，這不是預先安裝的。

428

429```bash theme={null}

430#!/bin/bash

431apt update && apt install -y shellcheck

432```

433

434<h3 id="script-requirements">

435 指令碼需求

436</h3>

437

438設定指令碼有三個限制條件需要考慮：

439

440* **Exit zero**：如果指令碼以非零狀態結束，工作階段將無法啟動。在非關鍵命令後附加 `|| true`，以便間歇性安裝失敗不會阻止工作階段。

441* **在五分鐘內完成**：將指令碼的總執行時間保持在大約五分鐘以內，以便[環境快取](#environment-caching)可以建立。使用 `&` 和 `wait` 並行執行獨立安裝，並將任何無法納入的單一下載移至[SessionStart hook](#setup-scripts-vs-sessionstart-hooks)，在背景中啟動它。

442* **安裝的網路存取**：套件安裝需要連接到登錄檔。預設的 **Trusted** 層級涵蓋[常見套件登錄檔](#default-allowed-domains)，包括 npm、PyPI、RubyGems 和 crates.io；使用 **None** 網路存取時，安裝會失敗。

443

444<h3 id="environment-caching">

445 環境快取

446</h3>

447

448設定指令碼在您第一次在環境中啟動工作階段時執行。完成後，Anthropic 會快照檔案系統，並將該快照重複用作後續工作階段的起點。新工作階段會以您的相依性、工具和 Docker 映像已在磁碟上開始，並跳過設定指令碼步驟。即使指令碼安裝大型工具鏈或拉取容器映像，這也能保持啟動速度快。

449

450快取是檔案系統快照，因此它會保留設定指令碼寫入磁碟的內容，並丟失任何僅在執行中的內容。您安裝的套件、您拉取的 Docker 映像和您寫入的檔案都會保留。指令碼啟動的資料庫、`docker compose up` 堆疊或任何其他背景程序不會；透過詢問 Claude 或使用 [SessionStart hook](#setup-scripts-vs-sessionstart-hooks) 在每個工作階段啟動這些。

451

452當您變更環境的設定指令碼或允許的網路主機時，以及當快取在大約七天後達到過期時，設定指令碼會再次執行以重建快取。恢復現有工作階段永遠不會重新執行設定指令碼。

453

454您不需要自己啟用快取或管理快照。

455

456<h3 id="setup-scripts-vs-sessionstart-hooks">

457 設定指令碼與 SessionStart hooks

458</h3>

459

460使用設定指令碼來佈建 VM 本身：未[預先安裝](#installed-tools)的工具鏈和 CLI 工具。使用 [SessionStart hook](/docs/zh-TW/hooks#sessionstart) 進行應在各處執行的專案設定，雲端和本機，例如 `npm install`。

461

462設定指令碼和 SessionStart hooks 在雲端工作階段啟動時按固定順序執行。下表比較您在哪裡設定它們、何時執行以及在哪裡執行。

463

464| | 設定指令碼 | SessionStart hooks |

465| ------------ | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |

466| **您在哪裡設定它們** | [claude.ai/code](https://claude.ai/code) 的環境對話框，加上[共用環境](#organization-shared-environments)的 **Cloud environments** 管理頁面 | [設定檔](/docs/zh-TW/settings#where-settings-live)，例如您的儲存庫的 `.claude/settings.json`；請參閱[您的設定中保留的內容](#what-carries-over-from-your-setup)，了解哪些檔案到達雲端工作階段 |

467| **它們何時執行** | 在 Claude Code 啟動之前，當存在[快取環境](#environment-caching)時跳過 | 在 Claude Code 啟動後，在每個工作階段（包括已恢復的工作階段）上 |

468| **它們在哪裡執行** | 僅限雲端工作階段 | 本機和雲端工作階段 |

469

470如果您在使用者層級 `~/.claude/settings.json` 中有 SessionStart hooks，不要期望它們在雲端中：使用者層級設定保留在您的機器上。其他 hooks 執行的位置取決於工作階段執行的位置：

471

472* **Anthropic 託管環境**：Claude Code 執行來自儲存庫和您組織的[伺服器管理設定](/docs/zh-TW/server-managed-settings)的 hooks。

473* **[自託管環境](/docs/zh-TW/self-hosted-environments-configuration#permissions-and-tool-approval)**：Claude Code 也執行操作員從執行器主機的 `~/.claude/` 中植入的 hooks，以及執行器映像的受管設定檔中的 hooks，當該檔案是 Claude Code 應用的[受管來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)之一時。

474

475<h3 id="install-dependencies-with-a-sessionstart-hook">

476 使用 SessionStart hook 安裝相依性

477</h3>

478

479若要僅在雲端工作階段中安裝相依性，請將 SessionStart hook 與檢查其執行位置的指令碼配對。

480

481首先，將 SessionStart hook 新增至您的儲存庫的 `.claude/settings.json`。此設定告訴 Claude Code 在工作階段啟動或恢復時執行儲存庫中的 `scripts/install_pkgs.sh`：

482

483```json theme={null}

484{

485 "hooks": {

486 "SessionStart": [

487 {

488 "matcher": "startup|resume",

489 "hooks": [

490 {

491 "type": "command",

492 "command": "bash \"$CLAUDE_PROJECT_DIR\"/scripts/install_pkgs.sh"

493 }

494 ]

495 }

496 ]

497 }

498}

499```

500

501`matcher` 將 hook 限制為 `startup` 和 `resume` 事件，`$CLAUDE_PROJECT_DIR` 解析為儲存庫根目錄，因此 hook 無論工作階段的工作目錄如何都能找到指令碼。

502

503接下來，在 `scripts/install_pkgs.sh` 建立指令碼。它在雲端外立即結束，然後安裝您的相依性：

504

505```bash theme={null}

506#!/bin/bash

507

508if [ "$CLAUDE_CODE_REMOTE" != "true" ]; then

509 exit 0

510fi

511

512npm install

513pip install -r requirements.txt

514exit 0

515```

516

517`CLAUDE_CODE_REMOTE` 檢查是將安裝限制在雲端工作階段的原因：工作階段 VM 的環境將該變數設為 `true`，本機上永遠不會是 `true`，因此在您的筆記型電腦上，指令碼在安裝任何內容之前結束。

518

519這兩個檔案一起為每個雲端工作階段在啟動時提供新鮮的 `npm install` 和 `pip install`，同時保持本機工作階段不受影響。

520

521<h4 id="limitations-in-cloud-sessions">

522 雲端工作階段中的限制

523</h4>

524

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

526

527* **無雲端專用範圍**：hooks 在本機和雲端工作階段中執行。若要跳過本機執行，請檢查 `CLAUDE_CODE_REMOTE` 環境變數，如上所示。

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

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

530* **增加啟動延遲**：hooks 在每次工作階段啟動或恢復時執行，不同於設定指令碼，設定指令碼受益於[環境快取](#environment-caching)。透過在重新安裝之前檢查相依性是否已存在來保持安裝指令碼快速。

531

532若要自訂基礎映像，請使用設定指令碼在[提供的映像](#installed-tools)上安裝您需要的內容，或使用 `docker compose` 作為 Claude 旁邊的容器執行您自己的映像。目前不支援完全取代基礎映像。

533

534<h2 id="default-allowed-domains">

535 預設允許的網域

536</h2>

537

538使用 **Trusted** 網路存取，工作階段預設可以到達以下網域。標記為 `*` 的網域表示萬用字元子網域符合，因此 `*.gcr.io` 允許 `gcr.io` 的任何子網域。

539

540<AccordionGroup>

541 <Accordion title="Anthropic 服務">

542 * api.anthropic.com

543 * statsig.anthropic.com

544 * docs.claude.com

545 * platform.claude.com

546 * code.claude.com

547 * claude.ai

548 </Accordion>

549

550 <Accordion title="版本控制">

551 * github.com

552 * [www.github.com](http://www.github.com)

553 * api.github.com

554 * npm.pkg.github.com

555 * raw\.githubusercontent.com

556 * pkg-npm.githubusercontent.com

557 * objects.githubusercontent.com

558 * release-assets.githubusercontent.com

559 * codeload.github.com

560 * avatars.githubusercontent.com

561 * camo.githubusercontent.com

562 * gist.github.com

563 * gitlab.com

564 * [www.gitlab.com](http://www.gitlab.com)

565 * registry.gitlab.com

566 * bitbucket.org

567 * [www.bitbucket.org](http://www.bitbucket.org)

568 * api.bitbucket.org

569 </Accordion>

570

571 <Accordion title="容器登錄">

572 * registry-1.docker.io

573 * auth.docker.io

574 * index.docker.io

575 * hub.docker.com

576 * [www.docker.com](http://www.docker.com)

577 * production.cloudflare.docker.com

578 * download.docker.com

579 * gcr.io

580 * \*.gcr.io

581 * ghcr.io

582 * mcr.microsoft.com

583 * \*.data.mcr.microsoft.com

584 * public.ecr.aws

585 </Accordion>

586

587 <Accordion title="雲端平台">

588 * cloud.google.com

589 * accounts.google.com

590 * gcloud.google.com

591 * \*.googleapis.com

592 * storage.googleapis.com

593 * compute.googleapis.com

594 * container.googleapis.com

595 * azure.com

596 * portal.azure.com

597 * microsoft.com

598 * [www.microsoft.com](http://www.microsoft.com)

599 * \*.microsoftonline.com

600 * packages.microsoft.com

601 * dotnet.microsoft.com

602 * dot.net

603 * visualstudio.com

604 * dev.azure.com

605 * \*.amazonaws.com

606 * \*.api.aws

607 * oracle.com

608 * [www.oracle.com](http://www.oracle.com)

609 * java.com

610 * [www.java.com](http://www.java.com)

611 * java.net

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

613 * download.oracle.com

614 * yum.oracle.com

615 </Accordion>

616

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

618 * registry.npmjs.org

619 * [www.npmjs.com](http://www.npmjs.com)

620 * [www.npmjs.org](http://www.npmjs.org)

621 * npmjs.com

622 * npmjs.org

623 * yarnpkg.com

624 * registry.yarnpkg.com

625 </Accordion>

626

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

628 * pypi.org

629 * [www.pypi.org](http://www.pypi.org)

630 * files.pythonhosted.org

631 * pythonhosted.org

632 * test.pypi.org

633 * pypi.python.org

634 * pypa.io

635 * [www.pypa.io](http://www.pypa.io)

636 </Accordion>

637

638 <Accordion title="Ruby 套件管理員">

639 * rubygems.org

640 * [www.rubygems.org](http://www.rubygems.org)

641 * api.rubygems.org

642 * index.rubygems.org

643 * ruby-lang.org

644 * [www.ruby-lang.org](http://www.ruby-lang.org)

645 * rubyforge.org

646 * [www.rubyforge.org](http://www.rubyforge.org)

647 * rubyonrails.org

648 * [www.rubyonrails.org](http://www.rubyonrails.org)

649 * rvm.io

650 * get.rvm.io

651 </Accordion>

652

653 <Accordion title="Rust 套件管理員">

654 * crates.io

655 * [www.crates.io](http://www.crates.io)

656 * index.crates.io

657 * static.crates.io

658 * rustup.rs

659 * static.rust-lang.org

660 * [www.rust-lang.org](http://www.rust-lang.org)

661 </Accordion>

662

663 <Accordion title="Go 套件管理員">

664 * proxy.golang.org

665 * sum.golang.org

666 * index.golang.org

667 * golang.org

668 * [www.golang.org](http://www.golang.org)

669 * goproxy.io

670 * pkg.go.dev

671 </Accordion>

672

673 <Accordion title="JVM 套件管理員">

674 * maven.org

675 * repo.maven.org

676 * central.maven.org

677 * repo1.maven.org

678 * repo.maven.apache.org

679 * jcenter.bintray.com

680 * gradle.org

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

682 * services.gradle.org

683 * plugins.gradle.org

684 * kotlinlang.org

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

686 * spring.io

687 * repo.spring.io

688 </Accordion>

689

690 <Accordion title="其他套件管理員">

691 * packagist.org (PHP Composer)

692 * [www.packagist.org](http://www.packagist.org)

693 * repo.packagist.org

694 * nuget.org (.NET NuGet)

695 * [www.nuget.org](http://www.nuget.org)

696 * api.nuget.org

697 * pub.dev (Dart/Flutter)

698 * api.pub.dev

699 * hex.pm (Elixir/Erlang)

700 * [www.hex.pm](http://www.hex.pm)

701 * cpan.org (Perl CPAN)

702 * [www.cpan.org](http://www.cpan.org)

703 * metacpan.org

704 * [www.metacpan.org](http://www.metacpan.org)

705 * api.metacpan.org

706 * cocoapods.org (iOS/macOS)

707 * [www.cocoapods.org](http://www.cocoapods.org)

708 * cdn.cocoapods.org

709 * haskell.org

710 * [www.haskell.org](http://www.haskell.org)

711 * hackage.haskell.org

712 * swift.org

713 * [www.swift.org](http://www.swift.org)

714 </Accordion>

715

716 <Accordion title="Linux 發行版">

717 * archive.ubuntu.com

718 * security.ubuntu.com

719 * ubuntu.com

720 * [www.ubuntu.com](http://www.ubuntu.com)

721 * \*.ubuntu.com

722 * ppa.launchpad.net

723 * launchpad.net

724 * [www.launchpad.net](http://www.launchpad.net)

725 * \*.nixos.org

726 </Accordion>

727

728 <Accordion title="開發工具和平台">

729 * dl.k8s.io (Kubernetes)

730 * pkgs.k8s.io

731 * k8s.io

732 * [www.k8s.io](http://www.k8s.io)

733 * releases.hashicorp.com (HashiCorp)

734 * apt.releases.hashicorp.com

735 * rpm.releases.hashicorp.com

736 * archive.releases.hashicorp.com

737 * hashicorp.com

738 * [www.hashicorp.com](http://www.hashicorp.com)

739 * repo.anaconda.com (Anaconda/Conda)

740 * conda.anaconda.org

741 * anaconda.org

742 * [www.anaconda.com](http://www.anaconda.com)

743 * anaconda.com

744 * continuum.io

745 * apache.org (Apache)

746 * [www.apache.org](http://www.apache.org)

747 * archive.apache.org

748 * downloads.apache.org

749 * eclipse.org (Eclipse)

750 * [www.eclipse.org](http://www.eclipse.org)

751 * download.eclipse.org

752 * nodejs.org (Node.js)

753 * [www.nodejs.org](http://www.nodejs.org)

754 * developer.apple.com

755 * developer.android.com

756 * pkg.stainless.com

757 * binaries.prisma.sh

758 </Accordion>

759

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

761 * statsig.com

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

763 * api.statsig.com

764 * sentry.io

765 * \*.sentry.io

766 * downloads.sentry-cdn.com

767 * http-intake.logs.datadoghq.com

768 * browser-intake-us5-datadoghq.com

769 * \*.datadoghq.com

770 * \*.datadoghq.eu

771 * api.honeycomb.io

772 </Accordion>

773

774 <Accordion title="內容傳遞和鏡像">

775 * sourceforge.net

776 * \*.sourceforge.net

777 * packagecloud.io

778 * \*.packagecloud.io

779 * fonts.googleapis.com

780 * fonts.gstatic.com

781 </Accordion>

782

783 <Accordion title="架構和設定">

784 * json-schema.org

785 * [www.json-schema.org](http://www.json-schema.org)

786 * json.schemastore.org

787 * [www.schemastore.org](http://www.schemastore.org)

788 </Accordion>

789

790 <Accordion title="Model Context Protocol">

791 * \*.modelcontextprotocol.io

792 </Accordion>

793</AccordionGroup>

794

795<h2 id="related-resources">

796 相關資源

797</h2>

798

799* [Claude Code on the web](/docs/zh-TW/claude-code-on-the-web)：啟動、管理和共用雲端工作階段

800* [Web quickstart](/docs/zh-TW/web-quickstart)：連接 GitHub 並啟動您的第一個雲端工作階段

801* [Claude Tag](https://claude.com/docs/claude-tag/overview)：Claude 從 Slack 啟動的工作階段在相同的環境中執行

802* [Routines](/docs/zh-TW/routines)：排程執行使用相同的環境和網路存取層級

803* [Remote Control](/docs/zh-TW/remote-control)：改為在您自己的機器的網路和檔案上執行工作階段

804* [Self-hosted environments](/docs/zh-TW/self-hosted-environments)：在您組織自己的基礎設施上執行雲端工作階段

805* [SessionStart hooks](/docs/zh-TW/hooks#sessionstart)：儲存庫提交的設定，在本機和雲端工作階段中執行

806* [Server-managed settings](/docs/zh-TW/server-managed-settings)：到達雲端工作階段的組織政策

corporate-launcher.md +1 −1

Details

49 程序監視器中的協助程序名稱49 程序監視器中的協助程序名稱

50</h3>50</h3>

51 51

52配置了啟動程式後，`ps` 和 Activity Monitor 會顯示背景協助程序的版本化二進位檔案名稱，而不是 Claude Code 的 `claude bg-pty-host` 和 `claude bg-spare` 標籤，因為啟動程式的 `exec` 會重建引數清單。重新命名是副作用，不是隱蔽：程序在其他方面保持不變，Claude Code 透過二進位檔案路徑識別自己的程序，永遠不會透過顯示名稱。52配置了啟動程式後，`ps` 和 Activity Monitor 不再顯示背景協助程序的 Claude Code `claude bg-pty-host` 和 `claude bg-spare` 標籤，因為啟動程式的 `exec` 會重建引數清單。遺失標籤是副作用，而不是隱蔽：程序在其他方面保持不變，Claude Code 透過二進位檔案路徑識別自己的程序，永遠不會透過顯示名稱。

53 53

54<h2 id="set-up-the-launcher">54<h2 id="set-up-the-launcher">

55 設定啟動程式55 設定啟動程式

cross-session-messaging.md +405 −0 created

Details

1> ## Documentation Index

2> 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.

5# 訊息傳送至您的其他 Claude Code 工作階段

7> 讓 Claude 列出並訊息傳送至您在此機器上的其他 Claude Code 工作階段，並與您在其他機器或網路上的工作階段聯繫。

9<Note>

10 跨工作階段訊息傳送需要 macOS 和 Linux 上的 Claude Code v2.1.224 或更新版本，包括 WSL 2 內的 Linux。在原生 Windows 上，需要 Claude Code v2.1.234 或更新版本。當工作階段符合要求時，訊息傳送功能預設為開啟，無需啟用。請參閱[可用性](#availability)以了解提供者要求以及如何確認工作階段具有此功能。

11</Note>

13跨工作階段訊息傳送讓 Claude 從您的一個 Claude Code 工作階段傳遞訊息至另一個工作階段。當一個工作階段中的變更破壞了另一個工作階段正在建立的內容時，Claude 可以在您注意到之前警告該工作階段。當一個工作階段解決了另一個工作階段被阻止的問題時，Claude 可以跨工作階段傳送答案。

15訊息是一個 Claude 寫給另一個 Claude 的文字片段，絕不包括寄件者的對話歷史記錄或檔案。若要移動整個對話或其內容，請[復原工作階段](/docs/zh-TW/sessions#resume-a-session)。

17Claude 使用兩個工具來實現此功能：`ListAgents` 用於探索它可以到達的代理程式，以及 `SendMessage` 用於按名稱將訊息傳遞給其中一個代理程式。使用相同的 `SendMessage` 工具，Claude 也可以在單一工作階段或團隊內訊息傳送至[子代理程式](/docs/zh-TW/sub-agents#resume-subagents)和[代理程式團隊](/docs/zh-TW/agent-teams)隊友。本頁涵蓋您獨立工作階段之間的訊息。

19<h2 id="when-to-use-cross-session-messaging">

20 何時使用跨工作階段訊息傳送

21</h2>

23當您的一個工作階段有另一個工作階段在任務中期需要的內容時，使用訊息傳送。Claude 可以在看到需要時自動傳送訊息，例如在進行影響另一個工作階段正在進行的工作的變更後，或者您可以要求它傳送一個。常見的情況：

25* **移交發現**：當一個工作階段發現破壞性變更或做出決定時，Claude 為在受影響區域工作的工作階段總結它，而不是您在那裡重新解釋它。

26* **協調平行 worktrees**：當工作階段在單獨的 [worktrees](/docs/zh-TW/worktrees) 中處理同一個儲存庫時，Claude 可以告訴其他工作階段已合併的內容。

27* **從長時間執行的工作獲取狀態**：讓遷移或測試執行回報給您正在監視的工作階段，或從那裡自己要求它。如果該工作階段在此機器上，Claude 也可以[在它下次閒置或退出時要求一個通知](#get-a-notice-when-another-session-goes-idle)。

28* **跨機器訊息傳送**：到達您在另一台機器或網路上的一個工作階段。

30在您自己啟動和引導的獨立工作階段之間使用訊息傳送。Claude Code 為運行或到達多個工作階段的其他每種方式都有專用功能，因此請使用為您正在做的事情而建立的功能：

32* 若要在另一個終端機中繼續一個對話，或與新工作階段共享其內容，請[恢復工作階段](/docs/zh-TW/sessions#resume-a-session)

33* 對於 Claude 生成和監督的協調團隊工作階段，請使用[代理團隊](/docs/zh-TW/agent-teams)

34* 若要從一個地方監視和引導許多工作階段，請使用[代理檢視](/docs/zh-TW/agent-view)

35* 若要從您的手機或另一台裝置自己引導工作階段，而不是讓工作階段互相訊息傳送，請使用[遠端控制](/docs/zh-TW/remote-control)

36* 若要將外部事件（例如 CI 結果或聊天訊息）推送到工作階段中，請使用[頻道](/docs/zh-TW/channels)

38<h2 id="message-another-session">

39 訊息傳送至另一個工作階段

40</h2>

42當您的一個工作階段學到另一個工作階段需要的內容（例如發現、狀態或決定）時，Claude 會傳遞它，而不是您在終端機之間複製貼上。Claude 使用 `ListAgents` 發現目標並使用 `SendMessage` 傳送，因此您永遠不會自己呼叫任一工具。Claude 可以決定在未被要求的情況下傳送訊息，您也可以提示傳送一個。

44若要自己提示，告訴 Claude 您希望另一個工作階段知道或做什麼。此範例是您輸入的提示，不是 Claude 傳送的訊息：

46```text wrap theme={null}

47詢問在我的另一個終端機中執行的工作階段遷移是否完成

48```

50Claude 自己寫實際訊息，因此您的提示可以將內容留給 Claude。此提示要求摘要而不指定其措辭，Claude 傳送的內容會有所不同：

52```text wrap theme={null}

53向處理付款 API 的工作階段解釋我們剛剛做了什麼

54```

56若要自己命名目標，在您的提示中提及工作階段：輸入 `@` 後跟工作階段名稱的前幾個字母，然後從預先輸入中選擇工作階段，與您[@-提及子代理](/docs/zh-TW/sub-agents#invoke-subagents-explicitly)的方式相同。需要 Claude Code v2.1.232 或更新版本。Claude Code 插入提及，例如 `@api-worker`，並告訴 Claude 它命名的工作階段，因此 Claude 可以訊息傳送至該工作階段而無需先列出您的工作階段。此提示使用提及命名目標：

58```text wrap theme={null}

59讓 @api-worker 知道架構遷移已完成

60```

62預先輸入列出您在此機器上的其他即時工作階段。兩種情況需要超過名稱的前幾個字母：

64* **超出此機器的工作階段**：雲端或遠端控制工作階段僅在 Claude 列出或訊息傳送至您超出此機器的工作階段後才出現在預先輸入中，因此請先要求 Claude 列出它們。

65* **名稱包含空格或字母、數字、連字號和底線以外的其他字元**：在雙引號中輸入它，例如 `@"release notes"`。當您從預先輸入中選擇工作階段時，Claude Code 會為您插入引號。

67您也可以在沒有選擇器的情況下輸入提及。當多個即時工作階段回應提及的名稱時，Claude 會在傳送前要求您指定您的意思。

69有關 Claude 寫的訊息在到達時的外觀，包括其中一個範例，請參閱[訊息的外觀](#what-a-message-looks-like)。

71<h3 id="message-delivery">

72 訊息傳遞

73</h3>

75接收 Claude 在活躍回合期間的工具呼叫之間讀取訊息，因此執行中的工具永遠不會被中斷。當接收工作階段閒置時，Claude Code 使用訊息啟動新回合。

77來自另一個工作階段的訊息作為純文字到達。如果它使用 `@` 提及檔案或 [MCP 資源](/docs/zh-TW/mcp#use-mcp-resources)，Claude 會看到如寫入的提及，Claude Code 不會附加任何內容，無論訊息是啟動新回合還是在一個回合期間到達。Claude 仍然可以使用自己的工具在接收機器上開啟提及的路徑，受該工作階段的權限限制。在 v2.1.251 之前，啟動新回合的訊息中的 `@` 提及會在接收端附加檔案或 MCP 資源。

79Claude Code 在以下情況下拒絕訊息：

81* 訊息[超過大小上限](#limitations)。Claude Code 在傳送工作階段中拒絕它，在它離開之前。

82* 對此機器上工作階段的快速突發已達到[該工作階段的收件匣接受](#limitations)的內容。Claude Code 拒絕進一步訊息傳送至該工作階段。

83* 此機器上的回覆目標未通過安全檢查，例如符號連結目標或不是預期程序的端點。[拒絕傳送跨工作階段訊息](/docs/zh-TW/errors#refusing-to-send-a-cross-session-message)列出這些檢查。

84* Claude 將訊息定址到此工作階段自己的名稱，如[查看 Claude 可以到達的工作階段](#see-which-sessions-claude-can-reach)下所述。

86接收工作階段根據其自己的[入站控制](#control-inbound-messages)檢查每條到達的訊息，檢查以三種結果之一結束：

88* **已傳遞**：Claude Code 將訊息傳遞給接收 Claude。

89* **已保留**：Claude Code 將訊息擱置未傳遞。保留的訊息僅在您批准它或稍後的模式或設定變更允許它時才到達 Claude。

90* **已拒絕**：Claude Code 在未傳遞的情況下丟棄訊息。

92一旦傳遞，訊息計入[使用量](/docs/zh-TW/costs)，如同您輸入的提示，接收 Claude 可以以相同方式回覆寄件者，除了[單向跨機器情況](#message-sessions-on-other-machines)。

94權限邊界保持每個工作階段。Claude 被指示永遠不要要求另一個工作階段執行在其自己的工作階段中被拒絕或阻止的操作，或其自己的權限設定會阻止的操作，並將該工作路由回您。在接收端，[接收工作階段自己的權限提示和規則仍然適用](#how-a-session-treats-an-incoming-message)於訊息要求的任何內容。

96<h3 id="get-a-notice-when-another-session-goes-idle">

97 在另一個工作階段閒置時獲取通知

98</h3>

100Claude 可以要求您在此機器上的一個工作階段在該工作階段下次閒置或退出時傳回一個通知。閒置在此表示工作階段完成了一個回合，沒有任何排隊。當您在另一個工作階段中等待長時間任務並想在完成時聽到而不是檢查時使用它。需要兩個工作階段中的 Claude Code v2.1.236 或更新版本。

101

102<h4 id="ask-for-a-notice">

103 要求通知

104</h4>

105

106告訴 Claude 您在等待什麼。此提示要求來自遷移工作階段的通知：

107

108```text wrap theme={null}

109告訴我遷移工作階段何時完成它正在進行的工作

110```

111

112Claude 使用 `SendMessage` 工具的 `notify_when_idle` 輸入訂閱，要麼附加到它正在傳送的訊息，要麼自己訂閱。自己訂閱時，Claude Code 訂閱而不在監視工作階段中啟動回合或花費代幣，如果該工作階段已經閒置，則立即傳送通知。附加到訊息時，Claude Code 先傳遞訊息，稍後傳送通知。

113

114<h4 id="what-each-session-shows">

115 每個工作階段顯示什麼

116</h4>

117

118監視工作階段顯示一行，說另一個程序要求在工作階段下次閒置時被告知。要求工作階段顯示通知作為命名監視工作階段的一行。該行可以包括該工作階段回合完成的時間和該回合的單行狀態。如果要求工作階段閒置，Claude Code 使用通知啟動新回合。

119

120<h4 id="limits">

121 限制

122</h4>

123

124通知是一次性的：Claude Code 從監視工作階段傳送一次，兩個工作階段都不輪詢另一個。如果在 12 小時內沒有通知到達，Claude Code 會丟棄訂閱並告訴 Claude，因此它不會繼續等待。

125

126每一側的[入站控制](#control-inbound-messages)適用於通知，如同訊息：

127

128* **任一側的 `refuse`**：沒有任何內容到達。監視工作階段在未記錄或回答的情況下丟棄請求，因此訂閱在 12 小時後未回答而過期，具有 `refuse` 的要求工作階段永遠不會訂閱。

129* **任一側的 `hold`**：通知到達時內容較少。監視工作階段省略單行狀態，要求工作階段在您的文字記錄中顯示通知而不將其傳遞給 Claude。

130

131只有您主要對話中的 Claude 可以訂閱，並且只能訂閱此機器上的您的工作階段。當子代理或代理團隊隊友設定 `notify_when_idle` 時，Claude Code 不進行訂閱並告訴它。當 Claude 要求來自任何其他代理（例如隊友、子代理或超出此機器的工作階段）的通知時，Claude Code 拒絕整個呼叫，包括附加到它的任何訊息，並向 Claude 報告拒絕，以便它可以在沒有請求的情況下重新傳送訊息。

132

133<h3 id="see-which-sessions-claude-can-reach">

134 查看 Claude 可以到達的工作階段

135</h3>

136

137Claude 自己找到訊息的目標，因此您不需要在要求它傳送之前執行任何操作。若要自己查看 Claude 可以到達的工作階段，請執行 `/list-agents` 命令。第一行（如果存在）是此工作階段自己的名稱，您的其他工作階段用來訊息傳送至它的名稱。下面的行是 Claude 可以到達的工作階段：

138

139* **子代理**：在目前工作階段內執行的代理。

140* **隊友**：此工作階段自己的[代理團隊](/docs/zh-TW/agent-teams)隊友。在 v2.1.239 之前，隊友沒有出現在列表中，儘管 Claude 已經可以按名稱訊息傳送至他們。

141* **您的其他本地工作階段**：在同一台機器上執行的 Claude Code 工作階段，包括[背景工作階段](/docs/zh-TW/agent-view)。工作階段僅在綁定[收件匣通訊端](#the-sessions-inbox-socket)時出現。

142* **您的雲端工作階段**：您的[網路上的 Claude Code](/docs/zh-TW/claude-code-on-the-web) 工作階段，在此工作階段連接到[遠端控制](/docs/zh-TW/remote-control)時顯示。Claude Code 在列表中將它們標記為 `cloud`。

143* **您在其他機器上的遠端控制工作階段**：在此工作階段連接到[遠端控制](/docs/zh-TW/remote-control)時顯示，並標記為 `Remote Control`。Claude Code 將遠端控制連接已斷開的工作階段的狀態顯示為 `offline`。

144

145此工作階段不是其中一行。如果 Claude 將訊息定址到此工作階段自己的名稱，Claude Code 拒絕它並告訴 Claude 目標是目前工作階段。在 v2.1.239 之前，列表沒有顯示此工作階段的名稱，Claude Code 報告發送給它的訊息為它找不到的代理。

146

147當此工作階段連接到[遠端控制](/docs/zh-TW/remote-control)時，Claude Code 從 `/list-agents` 輸出中隱藏您本地工作階段的某些詳細資訊，而不改變 Claude 自己在尋找要訊息傳送的工作階段時看到的內容：

148

149* **工作目錄**：它省略每個本地工作階段的工作目錄。

150* **工作階段名稱**：它省略任何它無法歸因於某人的工作階段名稱，因此沒有名稱的行讀作 `(unnamed session)`。

151* **第一行**：它省略帶有此工作階段自己名稱的行，除非您在此終端機上輸入該名稱，使用 `--name` 或使用 `/rename`，自從您啟動或最後恢復工作階段以來。

152

153當輸出列出任何內容時，它以說明詳細資訊被隱藏的注釋結束。在工作階段自己的鍵盤上執行 `/rename` 後跟未使用的名稱會給該工作階段一個出現在輸出中的名稱。

154

155Claude Code 首先讀取您的雲端和遠端控制工作階段列表，並在每個列表後停止有限數量的頁面。如果您的帳戶有超過適合的那些工作階段，Claude Code 不會列出較舊的工作階段，Claude 無法按名稱訊息傳送至它們。當發生這種情況時，Claude Code 在列表中說明，Claude 在傳送訊息時看到相同的注釋。

156

157Claude 按名稱定址超出此機器的工作階段，與本地工作階段相同。請參閱[訊息傳送至其他機器上的工作階段](#message-sessions-on-other-machines)以了解這些訊息如何傳遞。

158

159工作階段回應您使用 [`/rename`](/docs/zh-TW/commands) 命令或 [`--name`](/docs/zh-TW/cli-reference#cli-flags) 旗標設定的名稱。當您不設定一個時，Claude Code 自己命名工作階段。對於互動式工作階段，這是[執行工作階段列表](/docs/zh-TW/sessions#name-your-sessions)中顯示的名稱。

160

161當您重新命名工作階段時，Claude Code 也會更新您的其他工作階段用來查詢工作階段名稱的共享記錄。如果它無法更新該記錄，它會在 `/rename` 輸出中警告您其他工作階段可能仍然顯示舊名稱。使用 [`--debug`](/docs/zh-TW/cli-reference#cli-flags) 執行工作階段，Claude Code 會記錄失敗更新的原因。

162

163當您重新命名工作階段或啟動或恢復互動式工作階段時，使用此機器上另一個即時工作階段已經使用的名稱，Claude Code 將名稱留給已經擁有它的工作階段，並[將您的重新命名為變體](/docs/zh-TW/sessions#name-your-sessions)。工作階段可以共享名稱，例如當其中一個執行較早版本的 Claude Code 或共享名稱是 Claude Code 生成的名稱時。除非此工作階段連接到遠端控制，Claude Code 在 `/list-agents` 輸出中顯示每個本地工作階段的工作目錄，因此當它們在不同目錄中執行時，您可以區分同名工作階段。Claude 根據有多少個即時工作階段回應名稱，以兩種方式之一定址訊息：

164

165* **一個工作階段回應名稱**：Claude Code 僅在名稱上傳遞訊息。

166* **多個工作階段共享名稱，或 Claude Code 無法檢查您的工作階段執行的所有地方**：Claude 為其列表的每一行添加短識別符，並在地址中使用識別符。

167

168<h3 id="message-sessions-on-other-machines">

169 訊息傳送至其他機器上的工作階段

170</h3>

171

172訊息如何傳遞，以及它是否通過 Anthropic 伺服器，取決於目標工作階段執行的位置：

173

174| 其他工作階段執行的位置 | 訊息如何傳遞 |

175| :------------------------------------------------- | :---------------------------------------------------------------------------- |

176| 在此機器上 | 在 macOS 和 Linux 上通過每個工作階段的通訊端，或在原生 Windows 上通過每個工作階段的具名管道，永遠不通過 Anthropic 伺服器 |

177| 在您的另一台機器上 | 通過 Anthropic 伺服器，通過該機器的[遠端控制](/docs/zh-TW/remote-control)連接到達 |

178| 在[網路上的 Claude Code](/docs/zh-TW/claude-code-on-the-web) | 通過 Anthropic 伺服器，直接到雲端工作階段 |

179

180與您另一台機器上的工作階段開始對話需要 Claude Code v2.1.225 或更新版本以及出現在[列表](#see-which-sessions-claude-can-reach)中的目標。在 v2.1.225 之前，Claude 只能回覆從一個到達的訊息。

181

182您可以訊息傳送至在[列表](#see-which-sessions-claude-can-reach)中顯示為 `offline` 的工作階段，其遠端控制連接已斷開的工作階段。傳送通過，但訊息僅在該工作階段的機器重新連接後到達。Claude 在傳送時被告知這一點。

183

184相同機器傳遞在啟用該功能的任何地方都有效。每個工作階段在磁碟上的檔案中註冊自己。當 Claude 列出或訊息傳送至您的本地工作階段時，Claude Code 讀取這些檔案以找到工作階段，因此兩個工作階段只有在能夠看到相同檔案時才能相互到達。

185

186容器有自己的檔案系統，因此容器內的工作階段和主機上的工作階段無法相互到達。同一容器內的兩個工作階段仍然可以訊息傳送至彼此，包括在[自託管執行器](/docs/zh-TW/self-hosted-environments)上。WSL 2 內的工作階段和同一台電腦上的原生 Windows 工作階段也無法相互到達，因為它們在不同的主目錄下註冊並在不同的通訊端類型上監聽。

187

188當此工作階段連接到遠端控制時，當您訊息傳送至您另一台機器上的工作階段時，Claude Code 在該工作階段的對話中顯示訊息，在此工作階段的遠端控制名稱下。該機器上的 Claude 可以回覆該名稱。例如，當此工作階段作為 `laptop-graceful-unicorn` 連接到遠端控制並且您訊息傳送至您的桌面時，您在桌面工作階段中看到 `laptop-graceful-unicorn` 下的訊息。

189

190如果此工作階段在 Claude 傳送至超出此機器的工作階段時未連接到遠端控制，訊息仍然通過，但沒有[回覆地址](#what-a-message-looks-like)，因此接收 Claude 無法回答它。Claude 在傳送時被告知這一點。

191

192若要在任何訊息超出此機器之前要求您的批准，請設定 [`isolatePeerMachines`](#require-approval-for-cross-machine-messages)。

193

194<h2 id="how-a-session-treats-an-incoming-message">

195 工作階段如何處理傳入的訊息

196</h2>

197

198當工作階段 A 傳訊息給工作階段 B 時，Claude Code 會告訴 B 的 Claude 該訊息來自另一個工作階段，而不是來自您，並限制訊息可以執行的操作：

199

200* **無法批准任何事項**：來自另一個工作階段的訊息永遠不會被視為您的同意，因此無法代表您回答待處理的權限提示。

201* **無法變更設定**：Claude Code 指示接收端的 Claude 永遠不要變更權限設定、`CLAUDE.md` 或其他設定，因為另一個工作階段要求。

202* **命令不執行**：訊息文字中的命令（例如 `/compact`）會以純文字形式送達。Claude Code 永遠不會執行它。

203* **權限提示仍會觸發**：如果根據訊息採取行動需要接收工作階段沒有的權限，您會看到與任何其他工作相同的提示。

204

205<h3 id="what-a-message-looks-like">

206 訊息看起來的樣子

207</h3>

208

209當訊息送達時，Claude Code 會在對話中將其顯示為暗淡的單行預覽，預覽行在之後會保留在對話中。預覽會顯示寄件者的名稱和訊息的第一行，當很長時會用 `…` 截斷，例如 `› Message from @api-worker: Schema migration finished (ctrl+o to expand)`。在 v2.1.247 之前，Claude Code 會完整顯示送達的訊息，而不是預覽。

210

211以下任一方式都可以顯示完整文字：

212

213* 按 `Ctrl+O` 開啟[文字記錄檢視器](/docs/zh-TW/interactive-mode#transcript-viewer)，並在寄件者的工作階段名稱下閱讀完整文字。

214* 在以 [`--verbose`](/docs/zh-TW/cli-reference#cli-flags) 啟動的工作階段中，Claude Code 會顯示完整文字而不是預覽。

215

216預覽只會縮短您看到的內容。無論您是否展開它，Claude 都會讀取完整訊息。

217

218Claude 會收到訊息，其中包含寄件者的名稱和回覆地址，除了[單向跨機器訊息](#message-sessions-on-other-machines)，它不包含回覆地址。除了名稱和回覆地址外，接收端的 Claude 會取得訊息的文字，永遠不會取得寄件者的對話歷史記錄或檔案。[訊息傳遞](#message-delivery)涵蓋文字中的 `@` 提及。

219

220[子代理](/docs/zh-TW/sub-agents)撰寫的訊息會以傳送工作階段的名稱送達，訊息文字中會識別子代理。對它的回覆會到達該工作階段的主要對話，而不是子代理。

221

222這個範例是一個 Claude 寫給另一個的訊息，當您展開它時，其完整文字如下所示：

223

224```text wrap theme={null}

225Schema migration finished

226The new column is tenant_id, and rebasing on main is safe now.

227```

228

229<h3 id="control-inbound-messages">

230 控制傳入訊息

231</h3>

232

233設定 [`crossSessionInbound`](/docs/zh-TW/settings-reference#crosssessioninbound) 以選擇工作階段對來自您其他工作階段的訊息執行的操作：

234

235| 值 | 行為 |

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

237| `accept` | Claude Code 將每條訊息傳遞給 Claude |

238| `hold` | Claude Code 為每條訊息顯示通知，不傳遞它。如果稍後應用 `accept`，根據[優先順序規則](/docs/zh-TW/settings-reference#crosssessioninbound)，Claude Code 會釋放保留的訊息 |

239| `refuse` | Claude Code 丟棄每條訊息，不傳遞它 |

240

241除了編輯設定檔外，您可以在 `/config` 列中選擇**來自您其他工作階段的訊息**的值。Claude Code 會將您選擇的值寫入您的使用者設定。該列需要 Claude Code v2.1.232 或更新版本，當受管設定或 `--settings` 旗標設定金鑰時不會出現，因為使用者設定值在那時不適用。Claude Code 拒絕此金鑰的 `/config crossSessionInbound=value` 簡寫。

242

243若要查看適用的值，請遵循[設定參考](/docs/zh-TW/settings-reference#crosssessioninbound)中的 `crossSessionInbound` 優先順序規則。當沒有值適用時，Claude Code 會根據兩個工作階段的權限模式決定每條訊息。它將[略過權限提示](/docs/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode)的工作階段分組為一個類別，將所有其他工作階段分組為另一個類別。Plan Mode 在具有可用的略過權限的工作階段中計為略過，[auto](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)、`acceptEdits` 和 `dontAsk` 計為提示：

244

245* **接收工作階段提示權限**：Claude Code 傳遞每條訊息。只有當傳送工作階段識別自己為略過權限提示時，它才會保留一條訊息以供您批准。

246* **接收工作階段略過權限提示**：Claude Code 保留每條訊息以供您批准。只有當傳送工作階段識別自己也略過時，它才會傳遞一條訊息。

247

248當預設保留訊息時，Claude Code 會在接收工作階段中開啟批准對話框。對話框顯示寄件者和預覽：

249

250* **批准**會將該訊息傳遞給 Claude。

251* **拒絕**或關閉對話框會丟棄它。

252* 當對話框在 [`dialogExpiry`](/docs/zh-TW/settings-reference#dialogexpiry) 截止時間後仍未回答時，Claude Code 會關閉它並丟棄訊息。截止時間預設為五分鐘。

253* 當沒有終端連接到[背景工作階段](/docs/zh-TW/agent-view)時，Claude Code 會將對話框保持在截止時間之後。連接後，如果對話框在完整截止時間內仍未回答，Claude Code 會關閉它並丟棄訊息。

254* 如果此工作階段的權限模式類別在保留訊息時變更，Claude Code 會重新應用傳入規則，傳遞它們現在接受的訊息，並顯示通知。

255* 如果設定變更使 `refuse` 在保留訊息時適用，Claude Code 會丟棄每條保留的訊息，並向它可以到達的每個寄件者報告拒絕。

256

257當寄件者是同一機器上的互動式工作階段時，Claude Code 會在接收端保留訊息時在那裡顯示通知，以及在接收端稍後傳遞、拒絕或過期時顯示後續通知。如果接收端拒絕它，Claude Code 會在那裡顯示通知，表示接收端不接受跨工作階段訊息，並告訴寄件者的 Claude 不要等待或重新傳送。

258

259Claude Code 最多保留 100 條訊息，與傳遞佇列分開，超過該數量會丟棄最舊的訊息。

260

261<h3 id="non-interactive-sessions">

262 非互動式工作階段

263</h3>

264

265Claude Code 為 [`claude -p`](/docs/zh-TW/headless) 工作階段綁定收件匣套接字，就像互動式工作階段一樣，因此長時間執行的 `-p` 背景工作程式可以接收訊息並出現在列表中。當您以[裸機模式](/docs/zh-TW/headless#start-faster-with-bare-mode)啟動工作階段時，Claude Code 不會綁定套接字，因此該工作階段無法接收訊息，也不會出現在代理列表中。

266

267`-p` 工作階段無法顯示批准對話框。當[傳入預設](#control-inbound-messages)在那裡保留訊息時，Claude Code 會為其保留相同的 [`dialogExpiry`](/docs/zh-TW/settings-reference#dialogexpiry) 截止時間，預設為五分鐘：

268

269* **在截止時間之前**：如果模式或設定變更允許訊息，Claude Code 會傳遞它。

270* **在截止時間之後**：Claude Code 會丟棄訊息，並向它可以到達的寄件者報告為已過期。

271

272將 `dialogExpiry` 設定為 `"never"` 以在工作階段結束前保留預設保留的訊息。由明確 `hold` 設定保留的訊息不會過期；Claude Code 只有在稍後應用 `accept` 時才會傳遞它。

273

274當工作階段結束且仍有訊息被保留時，Claude Code 會向它可以到達的每個寄件者報告它們為已過期。在 v2.1.225 之前，`-p` 工作階段中沒有截止時間：保留的訊息會保持保留狀態，除非在執行期間進行權限模式變更會傳遞它，而以保留訊息結束的工作階段不會向其寄件者報告任何內容。

275

276若要讓 `-p` 背景工作程式無人值守地接收訊息，請使用 `--settings` 值中設定為 `accept` 的 `crossSessionInbound` 啟動它。您使用者設定中的 `accept` 也有效，但適用於您執行的每個工作階段。

277

278<h3 id="the-sessions-inbox-socket">

279 工作階段的收件匣套接字

280</h3>

281

282當您預期的工作階段不在代理列表中、當您想要指令碼或 hook 發佈到工作階段中，或當沙箱化命令無法到達套接字時，請閱讀本節。

283

284Claude Code 為啟用跨工作階段訊息的每個工作階段綁定收件匣套接字，其中機器上的其他工作階段傳遞訊息。套接字是 macOS 和 Linux 上的 Unix 網域套接字（包括 WSL 2 內的 Linux），以及原生 Windows 上的具名管道。有關哪些工作階段類型綁定一個，請參閱[非互動式工作階段](#non-interactive-sessions)。

285

286您可以在兩個位置找到套接字的路徑：

287

288* `/status` 在 `Peer address` 列中顯示它。路徑前綴為 `uds:`。

289* Claude Code 將其匯出到[hooks](/docs/zh-TW/hooks) 和 Bash 命令作為 [`CLAUDE_CODE_MESSAGING_SOCKET`](/docs/zh-TW/env-vars#variables) 環境變數：

290 * 在以訊息開啟啟動的工作階段中，Claude Code 在任何 hook 執行前匯出變數，包括 `SessionStart`。

291 * 每個工作階段匯出其自己的套接字，永遠不會匯出從父工作階段繼承的套接字。

292

293在 macOS 和 Linux 上，Claude Code 將套接字限制為您的作業系統使用者。在原生 Windows 上，它改為要求每個連線首先使用只有您的作業系統使用者可以讀取的金鑰進行驗證。無論哪種方式，在共享機器上，另一個使用者的工作階段無法傳遞到它。

294

295在 macOS 和 Linux 上，Claude Code 也拒絕在無法接受的目錄中建立套接字，例如另一個使用者擁有的目錄，並改為使用私人的每使用者目錄 `/tmp/cc-socks-<uid>`。當它無法接受任何目錄時，工作階段會在沒有收件匣的情況下執行：Claude Code 會顯示通知，`/status` 在其 `Peer address` 列中顯示 `unavailable` 和原因，[`--debug`](/docs/zh-TW/cli-reference#cli-flags) 日誌會記錄完整拒絕。

296

297除了套接字的路徑外，Claude Code 還會匯出每個工作階段的權杖作為 [`CLAUDE_CODE_MESSAGING_TOKEN`](/docs/zh-TW/env-vars#variables)。發佈到其自己工作階段套接字的指令碼可以發送 `{"type":"auth","token":"<token>"}` 作為其連線的第一行，其中 `<token>` 是 `CLAUDE_CODE_MESSAGING_TOKEN` 的值。Claude Code 是否需要該行取決於平台：

298

299* **macOS 和 Linux，包括 WSL 2**：該行是選擇性的。Claude Code 接受有或沒有它的連線。

300* **原生 Windows**：該行是必需的。Claude Code 會關閉任何第一行不是有效驗證行的連線，並且不會從該連線傳遞任何內容。

301

302只有在您要發佈的訊息準備好時才開啟連線。Claude Code 會關閉在 30 秒內未發送完整行的連線，因此請先擷取緩慢命令的輸出，然後開啟連線以發送它。

303

304下面的[自有子訊息規則](#own-child-messages)說明 Claude Code 何時查詢權杖以及它如何處理無法驗證的訊息。

305

306<span id="own-child-messages" />Claude Code 會透過與任何其他對等訊息相同的[傳入控制](#control-inbound-messages)執行到達套接字的訊息，但有一個例外和一個先決條件：

307

308* **自有子訊息**：當沒有 `crossSessionInbound` 值適用時，Claude Code 會傳遞它驗證來自工作階段自己的子程序的訊息，例如 hook 或 Bash 命令發佈回其自己工作階段的套接字。

309 * 在 Linux 上（包括 WSL 2 內），Claude Code 即使對於已經退出的子程序也可以透過程序證據進行驗證。在 macOS 上，它只能在發佈程序仍在執行時以這種方式驗證，在 Claude Code 作為程序 ID 1 執行的容器中，它根本沒有程序證據。在原生 Windows 上也沒有。

310 * 在 macOS 上發佈程序已退出後，以及在 Claude Code 作為程序 ID 1 執行的容器中，該程序證據遺失，Claude Code 改為驗證在開啟其連線的驗證行中發送工作階段匯出的 [`CLAUDE_CODE_MESSAGING_TOKEN`](/docs/zh-TW/env-vars#variables) 的子程序。在原生 Windows 上，該權杖是 Claude Code 驗證自有子訊息的唯一方式。

311 * 當 Claude Code 無法以任何方式驗證時，它會將訊息視為任何其他不聲稱權限類別的訊息，因此略過權限提示的工作階段會為您的批准保留它。

312* **沙箱化工作階段**：使用沙箱的 Unix 套接字設定 [`sandbox.network.allowAllUnixSockets` 和 `sandbox.network.allowUnixSockets`](/docs/zh-TW/settings-reference#sandbox-settings) 控制 Bash 命令是否可以從[沙箱](/docs/zh-TW/sandboxing)內到達套接字。

313

314<h2 id="restrict-cross-session-messaging">

315 限制跨工作階段訊息傳送

316</h2>

317

318除了每條訊息的預設值，您可以以兩種方式縮小訊息傳送。在任何訊息離開機器之前要求您的批准，或為工作階段或組織關閉訊息傳送。

319

320<h3 id="require-approval-for-cross-machine-messages">

321 要求批准跨機器訊息

322</h3>

323

324設定 [`isolatePeerMachines`](/docs/zh-TW/settings-reference#isolatepeermachines) 為 `true` 以要求您的明確批准，在任何 `SendMessage` 到達超出此機器的工作階段之前：

325

326```json theme={null}

327{

328 "isolatePeerMachines": true

329}

330```

331

332設定此項後，Claude Code 在 Claude 的訊息到達超出此機器的工作階段之前要求您的批准，即使在 `bypassPermissions` 模式中，它跳過普通權限提示。任何設定範圍中的 `true` 適用，因此簽入的專案檔案可以打開要求但不能關閉。Claude Code 不提示同一台機器上工作階段之間的訊息。

333

334<h3 id="turn-off-cross-session-messaging">

335 關閉跨工作階段訊息傳送

336</h3>

337

338接收和傳送是分開的控制，因此關閉您需要的任一方向，或兩者。使用 `crossSessionInbound` 用於到達的訊息，以及權限規則用於 Claude 可以傳送或列出的內容：

339

340* **停止接收**：設定 `crossSessionInbound` 為 `refuse`，Claude Code 在未傳遞的情況下丟棄入站對等訊息。從專案或本地設定，`refuse` 適用於每個其他來源，從您的使用者設定，它適用，除非受管設定或 `--settings` 旗標設定值。

341* **停止傳送和列出**：新增[權限拒絕規則](/docs/zh-TW/permissions#tool-specific-permission-rules)命名 `SendMessage` 和 `ListAgents`。兩者都採用沒有指定符的裸工具名稱。

342

343管理員可以在[受管設定](/docs/zh-TW/managed-settings)中為組織關閉兩側，結合拒絕規則與 `refuse`：

344

345```json theme={null}

346{

347 "permissions": {

348 "deny": ["SendMessage", "ListAgents"]

349 },

350 "crossSessionInbound": "refuse"

351}

352```

353

354設定此項後，Claude Code 仍然為每個工作階段綁定收件匣通訊端，但丟棄到達它的每條訊息而不向 Claude 傳遞任何內容。拒絕 `SendMessage` 也移除訊息傳送至子代理和代理團隊隊友，因為相同工具服務兩者。拒絕工作階段在其自己的 `/status` 或同一台機器上其他工作階段的列表中顯示無可見變更，因此若要確認它，請檢查適用於該工作階段的設定檔而不是其狀態。

355

356<h2 id="availability">

357 可用性

358</h2>

359

360跨工作階段訊息傳送需要 macOS、Linux 和 WSL 2 上的 Claude Code v2.1.224 或更新版本，以及原生 Windows 上的 v2.1.234 或更新版本。可用性以及 Claude 可以訊息傳送的工作階段也取決於您的作業系統、提供者和設定：

361

362* **作業系統**：在 macOS、Windows 和 Linux 上可用，包括 WSL 2 內的 Linux。

363

364* **此機器上的工作階段**：在每個提供者上可用，包括 Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 和 Microsoft Foundry，以及在執行時[功能旗標擷取](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)關閉的工作階段。在這些提供者上，以及旗標擷取關閉時，相同機器訊息傳送需要 Claude Code v2.1.248 或更新版本。Claude Code 通過您機器上的[每個工作階段通訊端](#the-sessions-inbox-socket)傳遞這些訊息，永遠不通過 Anthropic 伺服器。

365

366 若要停止工作階段接收它們，請設定 [`crossSessionInbound`](#turn-off-cross-session-messaging) 為 `refuse`。

367

368* **超出此機器的工作階段**：Claude 從連接到遠端控制的工作階段找到您的[網路上的 Claude Code](/docs/zh-TW/claude-code-on-the-web) 工作階段和您在其他機器上的工作階段，這需要 claude.ai 登入作為此工作階段的活躍驗證以及其他[遠端控制要求](/docs/zh-TW/remote-control#requirements)。Claude 無法使用 API 金鑰或在 Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上找到這些工作階段。

369

370若要檢查工作階段，輸入 `/list-agents`，也可用作 `/peers`。結果將沒有該功能的工作階段與某些較窄的東西阻止訊息的工作階段分開，例如缺少 `SendMessage` 工具或拒絕的傳送：

371

372* **`/list-agents` 無法識別**：工作階段沒有跨工作階段訊息傳送。通過上面的要求進行工作，從 `claude --version` 開始以了解版本要求。

373* **`/list-agents` 有效但傳送未到達**：訊息傳送已啟用，某些較窄的東西適用：

374 * **拒絕規則**：[權限拒絕規則](#turn-off-cross-session-messaging)移除 `SendMessage` 和 `ListAgents` 工具。

375 * **入站控制**：[接收工作階段的入站控制](#control-inbound-messages)可以保留或丟棄您傳送給它的內容。

376 * **雲端工作階段缺失**：雲端工作階段僅在此工作階段連接到[遠端控制](/docs/zh-TW/remote-control)時出現。

377 * **其他機器工作階段缺失**：您另一台機器上的工作階段僅在它執行[遠端控制](/docs/zh-TW/remote-control)並且此工作階段也連接時出現。

378 * **其他機器工作階段 `offline`**：訊息傳送至列為 `offline` 的工作階段通過，但[僅在該工作階段的機器重新連接後到達](#message-sessions-on-other-machines)。

379 * **較舊的雲端或其他機器工作階段缺失**：Claude Code [首先讀取這些工作階段列表，並在有限數量的頁面後停止](#see-which-sessions-claude-can-reach)，因此 Claude 無法按名稱訊息傳送至超過它們的工作階段。

380 * **啟動對話**：[訊息傳送至其他機器上的工作階段](#message-sessions-on-other-machines)涵蓋與超出此機器的工作階段啟動對話。

381

382在具有訊息傳送的工作階段中，`/status` 也顯示 `Peer address` 行，帶有工作階段自己的收件匣地址，或 `unavailable` 和原因，當 Claude Code [無法設定收件匣](#the-sessions-inbox-socket)時。

383

384<h2 id="limitations">

385 限制

386</h2>

387

388此處的限制是訊息傳送頻道本身的屬性，在該功能執行的任何地方適用。有關平台和提供者差距，請改為參閱[可用性](#availability)。

389

390* **純文字只**：Claude 僅跨工作階段傳送純文字。結構化[代理團隊](/docs/zh-TW/agent-teams)協議訊息保留在團隊內。

391* **相同機器訊息大小有上限**：Claude Code 拒絕訊息到此機器上的工作階段，一旦其序列化形式超過約一百萬個字元。拒絕[命名確切大小](/docs/zh-TW/errors#message-too-large-for-cross-session-delivery)。沒有任何內容到達接收工作階段。

392* **對一個工作階段的快速突發在寄件者處被拒絕**：一旦對此機器上工作階段的快速訊息突發達到該工作階段的收件匣接受的內容，Claude Code 拒絕傳送工作階段中的進一步傳送。[拒絕命名突發](/docs/zh-TW/errors#too-many-messages-to-this-session-just-now)並告訴 Claude 將其餘部分批處理為一條訊息或等待。在 v2.1.236 之前，Claude Code 報告這些傳送為已傳送，而接收工作階段丟棄它們。

393* **訊息迴圈被限制**：在接收工作階段中，Claude Code 速率限制每個寄件者的重複訊息，丟棄在短時間窗口內到達的相同重複，並最多為 Claude 讀取排隊 50 條接受的訊息。因此，兩個工作階段之間的訊息迴圈自行停止。當速率限制、重複檢查或佇列上限丟棄來自此機器上互動式工作階段的訊息時，Claude Code 告訴該工作階段哪一個丟棄了它，並告訴其 Claude 不要立即重新傳送。

394

395<h2 id="related-resources">

396 相關資源

397</h2>

398

399* [子代理](/docs/zh-TW/sub-agents#resume-subagents)和[代理團隊](/docs/zh-TW/agent-teams#messages-between-agents)：單一工作階段或團隊內的訊息傳送

400* [背景代理](/docs/zh-TW/agent-view)：分派和監視您可能訊息傳送的平行工作階段

401* [遠端控制](/docs/zh-TW/remote-control)：連接此工作階段以到達您在其他機器上的工作階段

402* [設定](/docs/zh-TW/settings-reference#all-settings)：`crossSessionInbound`、`isolatePeerMachines` 和 `dialogExpiry`

403* [權限模式](/docs/zh-TW/permission-modes)：入站預設的兩個類別背後的模式

404* [工具參考](/docs/zh-TW/tools-reference)：工具表中的 `ListAgents` 和 `SendMessage` 行

405* [平行執行代理](/docs/zh-TW/agents)：比較 Claude Code 執行多個代理的方式

desktop-ios-simulator.md +176 −0 created

Details

1> ## Documentation Index

2> 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.

5# 在模擬器中測試 iOS 應用程式

7> Claude Code Desktop 在 Claude 建置、執行或檢查應用程式時，會在 iOS Simulator 窗格中開啟您的應用程式，每個工作階段都有一個獨立的模擬器。

9<Note>

10 iOS Simulator 窗格在 macOS 上的 Claude Code Desktop 中處於公開測試版。它在 Pro、Max、Team 和 Enterprise 方案上可用，但在啟用 HIPAA 設定的 Enterprise 組織中除外。

11</Note>

13iOS Simulator 窗格在 Claude Code Desktop 中的對話旁邊顯示您的應用程式在 Apple 的 iOS Simulator 中執行。當 Claude 在模擬器中建置、安裝、啟動或檢查您的應用程式時，窗格會自動開啟並即時串流裝置螢幕。使用它來觀看 Claude 執行和測試您的應用程式，或在 Claude 繼續工作時自己點選應用程式。

15模擬器窗格直接驅動模擬器，因此不需要[電腦使用](/docs/zh-TW/desktop#let-claude-use-your-computer)，也不會接管您的螢幕或隱藏其他視窗。從 CLI，Claude 透過[電腦使用](/docs/zh-TW/computer-use#test-a-simulator-flow)到達 iOS Simulator，它以滑鼠的方式控制螢幕上的模擬器。

17<h2 id="requirements">

18 需求

19</h2>

21模擬器窗格使用 Apple 的模擬器工具，桌面應用程式不包含這些工具。在開始工作階段之前，請確保您有：

23* Claude Desktop v1.24012.0 或更新版本

24* Mac，因為 Apple 的 iOS Simulator 只在 macOS 上執行

25* [Xcode](https://developer.apple.com/xcode/)，已安裝 iOS 平台，提供模擬器裝置。如果 Xcode 尚未列出任何模擬器，請參閱[模擬器窗格顯示找不到模擬器](#the-simulator-pane-says-no-simulators-were-found)

26 * 使用 Xcode 26.x。窗格尚不支援 Xcode 27，它用 Device Hub 取代了 Simulator 應用程式。如果 `xcode-select` 在您的 Mac 上指向 Xcode 27，請參閱[模擬器窗格在 Xcode 27 中失敗](#the-simulator-pane-fails-with-xcode-27)

28<Note>

29 在本頁面上，「裝置」是指模擬的 iPhone 或 iPad，是您在 Xcode 中的 **Window → Devices and Simulators** 下管理的相同模擬器裝置之一，不是實體硬體。

30</Note>

32模擬器窗格僅在本機工作階段中可用。在[雲端](/docs/zh-TW/desktop#run-long-running-tasks-remotely)和 [SSH](/docs/zh-TW/desktop#ssh-sessions) 工作階段中，Claude 在無法到達您 Mac 上模擬器的機器上執行。

34<h2 id="run-your-app-in-the-simulator">

35 在模擬器中執行您的應用程式

36</h2>

38您不需要命令或設定來開啟模擬器窗格。當 Claude 在模擬器中執行您的應用程式時，它會開啟窗格。

40<Steps>

41 <Step title="開啟您的 iOS 專案">

42 在 Claude Code Desktop 中，開啟 **Code** 標籤，並以您應用程式的專案作為[專案資料夾](/docs/zh-TW/desktop#start-a-session)開始工作階段。任何為 iOS Simulator 建置應用程式的專案都可以使用。

43 </Step>

45 <Step title="要求 Claude 執行或測試應用程式">

46 圍繞執行或驗證應用程式的任務進行表述。例如：

48 ```text theme={null}

49 Build the app and run it in the simulator to check the onboarding flow.

50 ```

51 </Step>

53 <Step title="在模擬器窗格中觀看應用程式">

54 當應用程式在模擬器中啟動時，iOS Simulator 窗格會在對話旁邊開啟。Claude 第一次使用裝置時，桌面應用程式會要求您允許；請參閱[授予 Claude 對裝置的存取權](#grant-claude-access-to-a-device)。Claude 安裝應用程式、點選應用程式，並讀取螢幕以驗證自己的變更，同時您觀看。

55 </Step>

56</Steps>

58模擬器窗格在 Claude 在工作階段中的任何時間在模擬器中啟動應用程式時開啟。當您的要求是關於查看應用程式時，例如「新螢幕看起來對嗎？」，Claude 在開始工作之前啟動模擬器。Claude 修復錯誤或變更螢幕後，要求它驗證變更：重新啟動應用程式會在窗格未開啟時重新開啟窗格。

60模擬器窗格顯示應用程式實際啟動的任何裝置。要在特定裝置上測試，在您的要求中命名它，例如「在 iPhone SE 模擬器上執行它」，Claude 在建置和啟動時會針對該裝置。

62Claude 啟動的裝置也會出現在 Apple 的 Simulator 應用程式中，Claude 可以在您已經啟動的裝置上安裝應用程式。

64您也可以自己開啟模擬器窗格。一旦工作階段有附加的模擬器或已編輯 Swift 檔案，工作階段工具列中的 **Views** 功能表會顯示 **iOS Simulator** 項目。如果窗格尚未顯示裝置，請按一下 **Attach simulator**，或從旁邊的裝置功能表中選擇特定裝置；選擇已關閉的裝置會啟動它。如果 Xcode 或其模擬器遺失，窗格會改為顯示設定步驟，並在您完成每個步驟時檢查它們。

66<h2 id="control-the-simulator-yourself">

67 自己控制模擬器

68</h2>

70模擬器窗格是互動式的，不僅是檢視器。在 Claude 工作時或在任務之間，您可以：

72* 透過在裝置螢幕上按一下和拖曳來點選和滑動

73* 使用與 Apple 的 Simulator 應用程式相同的快捷鍵按下硬體按鈕：**Cmd+Shift+H** 表示主畫面、**Cmd+L** 表示鎖定、**Cmd+Up Arrow** 和 **Cmd+Down Arrow** 表示音量

74* 使用旋轉按鈕或 **Cmd+Right Arrow** 將裝置順時針旋轉四分之一圈

75* 從裝置功能表切換窗格顯示的裝置，該功能表列出每個模擬器的作業系統版本以及是否已啟動

76* 使用 **Cmd+S** 儲存螢幕擷圖或使用 **Cmd+R** 儲存螢幕錄製，使用窗格的擷取按鈕或快捷鍵；檔案會儲存到您的桌面

77* 透過按一下 **Detach simulator** 停止串流裝置而不關閉它，這會將窗格返回其 **Attach simulator** 狀態

79裝置名稱下方的列調整來自模擬器的影片串流。如果窗格對您的 Mac 造成負擔，請降低 **Frame rate** 或 **Resolution**，在 H.264 和 JPEG 之間切換 **Encoding**，或檢查 **FPS** 以顯示窗格接收的幀速率。這些設定會變更窗格顯示裝置的方式，而不是應用程式的執行方式。

81您和 Claude 驅動相同的裝置，因此您的點選會變更 Claude 看到的應用程式狀態。要讓 Claude 檢查特定螢幕，請透過點選導航到它，然後要求。當 Claude 驅動裝置時，窗格會在螢幕上方顯示 **Claude is using this device** 徽章；在徽章清除之前暫停點選，以便結果反映應用程式而不是您的輸入。

83<h2 id="how-sessions-manage-devices">

84 工作階段如何管理裝置

85</h2>

87每個裝置都屬於啟動它的工作階段，因此[平行工作階段](/docs/zh-TW/desktop#work-in-parallel-with-sessions)不共享裝置：您在一個工作階段的窗格中看到的內容反映該工作階段的工作，而不是另一個的。在側邊欄中切換工作階段會切換模擬器檢視以及對話，切換回去會在相同裝置上恢復它停止的位置。如果 Claude 使用多個裝置，每個都會開啟自己的窗格，每個工作階段最多 4 個。

89Claude Code Desktop 在模擬器不再使用時關閉它啟動的模擬器：當您退出應用程式時、當您封存工作階段時，或在您從其窗格分離裝置後 10 分鐘。您自己啟動的裝置，無論是從窗格還是在 Apple 的 Simulator 應用程式中，永遠不會自動關閉。要立即關閉附加的裝置，請使用窗格中的關閉按鈕。

91<h2 id="grant-claude-access-to-a-device">

92 授予 Claude 對裝置的存取權

93</h2>

95Claude 在控制裝置之前要求您的同意，而建置應用程式或在其上開啟 URL 遵循您工作階段的權限模式。您或您的組織也可以完全關閉 Claude 的存取。

97<h3 id="allow-a-device-the-first-time">

98 第一次允許裝置

99</h3>

100

101Claude 第一次使用模擬器時，桌面應用程式會要求您允許。同意涵蓋控制該裝置和擷取其螢幕擷圖，您每個裝置給予一次，而不是每個工作階段一次。Claude 對裝置的螢幕擷圖會傳送到 Anthropic，並根據您的正常對話保留設定保留，因此不要在 Claude 使用的裝置上登入真實帳戶。

102

103您允許裝置後，Claude 對其的操作，例如點選、輸入、啟動應用程式和擷取螢幕擷圖，無需進一步提示即可執行。它們具有與您在窗格中按一下相同的信任，並且它們只觸及模擬的裝置，因此窗格不需要電腦使用所需的 macOS 無障礙和螢幕錄製權限。

104

105如果您拒絕，裝置仍會啟動，窗格仍可用於您自己的點選；只有 Claude 的存取保持關閉。要稍後改變主意，請按一下窗格中的 **Let Claude use it**。

106

107<h3 id="actions-that-follow-your-permission-mode">

108 遵循您的權限模式的操作

109</h3>

110

111兩個操作遵循您工作階段的[權限模式](/docs/zh-TW/permissions#permission-modes)，而不是一次性同意：

112

113* 在裝置上開啟 URL，例如測試深層連結或在裝置的 Safari 中載入頁面，因為 URL 可以攜帶資料離開裝置。

114* 建置應用程式，因為 `xcodebuild` 在您的 Mac 上執行您專案的建置指令碼。檢查已在進行中的建置不會提示。

115

116<h3 id="turn-off-simulator-access">

117 關閉模擬器存取

118</h3>

119

120您可以在桌面應用程式的設定中關閉 Claude 的模擬器存取。組織有兩種方式為所有人關閉它：

121

122* `disableMobileSimulatorTools` [受管設定](/docs/zh-TW/desktop#managed-settings)阻止 Claude 的模擬器工具。模擬器窗格仍可用於您自己的點選，該設定無法從應用程式內覆寫。

123* `requireCoworkFullVmSandbox` 原則金鑰，它在隔離的虛擬機器內而不是在您的 Mac 上執行 Claude 的工具，完全停用模擬器窗格和 Claude 的模擬器工具，因此在設定時窗格無法附加裝置。

124

125Claude 會告訴您何時適用任一項。

126

127<h2 id="limitations">

128 限制

129</h2>

130

131Claude 只驅動模擬的裝置，無法控制實體 iPhone 或 iPad。要在其上測試，請自己從 Xcode 在其上執行應用程式，然後描述您看到的內容或將螢幕擷圖附加到對話中，以便 Claude 從中工作。

132

133<h2 id="troubleshooting">

134 疑難排解

135</h2>

136

137<h3 id="the-simulator-pane-doesn’t-open-when-claude-runs-the-app">

138 當 Claude 執行應用程式時，模擬器窗格不開啟

139</h3>

140

141Claude 可能沒有識別出您想要執行或測試應用程式，或模擬器工具可能遺失。檢查以下內容：

142

143* 明確說明目標，例如「在 iOS Simulator 中執行應用程式並點選註冊流程」。

144* 確認 Xcode 和 iOS 模擬器已安裝，且您的 Xcode 版本符合[需求](#requirements)。

145* 如果您的組織管理 Claude Code，[模擬器工具可能被原則停用](#turn-off-simulator-access)。

146* 如果您在啟用 HIPAA 設定的 Enterprise 組織中，模擬器窗格對您不可用。

147* 模擬器窗格需要 Claude Desktop v1.24012.0 或更新版本。開啟 **Claude → Check for Updates**，然後重新啟動應用程式。

148

149<h3 id="the-simulator-pane-says-no-simulators-were-found">

150 模擬器窗格顯示找不到模擬器

151</h3>

152

153如果 `xcode-select` 指向 Xcode 27，即使裝置存在，窗格也可能報告找不到模擬器；請參閱[模擬器窗格在 Xcode 27 中失敗](#the-simulator-pane-fails-with-xcode-27)。否則，Xcode 已安裝但沒有 iOS 模擬器可列出。模擬器窗格顯示要遵循的設定步驟，並在每個步驟完成時檢查它們。要手動安裝遺失的部分，請從 Xcode 的設定下載 iOS 模擬器執行時間，或執行 `xcodebuild -downloadPlatform iOS`。

154

155<h3 id="the-simulator-pane-fails-with-xcode-27">

156 模擬器窗格在 Xcode 27 中失敗

157</h3>

158

159窗格尚不支援 Xcode 27，它用 Device Hub 取代了 Simulator 應用程式。選擇 Xcode 27 後，附加裝置失敗，或窗格報告找不到模擬器，即使裝置存在。

160

161窗格使用 `xcode-select` 指向的任何 Xcode。如果 Xcode 27 是您唯一的安裝，請先在其旁邊安裝 Xcode 26.x。然後按其路徑選擇 26.x 安裝。例如，如果它安裝為 `/Applications/Xcode-26.4.app`：

162

163```bash theme={null}

164sudo xcode-select -s /Applications/Xcode-26.4.app

165```

166

167執行 `xcode-select -p` 以檢查選擇了哪個安裝。

168

169<h2 id="see-also">

170 另請參閱

171</h2>

172

173* [Desktop 中的電腦使用](/docs/zh-TW/desktop#let-claude-use-your-computer)：沒有專用窗格的應用程式的螢幕控制

174* [CLI 中的電腦使用](/docs/zh-TW/computer-use)：CLI 如何到達 iOS Simulator

175* [使用工作階段平行工作](/docs/zh-TW/desktop#work-in-parallel-with-sessions)：工作階段如何隔離變更

176* [開始使用 Claude Code Desktop](/docs/zh-TW/desktop-quickstart)

desktop-quickstart.md +7 −7

Details

9桌面應用程式為您提供具有圖形介面的 Claude Code，專為並行執行多個會話而設計：用於管理並行工作的側邊欄、具有整合終端機和檔案編輯器的拖放式佈局、視覺化差異檢查、即時應用程式預覽、GitHub PR 監控與自動合併，以及排程任務。無需終端機。9桌面應用程式為您提供具有圖形介面的 Claude Code，專為並行執行多個會話而設計：用於管理並行工作的側邊欄、具有整合終端機和檔案編輯器的拖放式佈局、視覺化差異檢查、即時應用程式預覽、GitHub PR 監控與自動合併，以及排程任務。無需終端機。

10 10

11<CardGroup cols={3}>11<CardGroup cols={3}>

~~12 <Card title="Download for macOS" icon="apple" href="https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code&utm_medium=docs">~~12 <Card title="下載 macOS 版本" icon="apple" href="https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code&utm_medium=docs">

~~13 Universal build for Intel and Apple Silicon~~13 適用於 Intel 和 Apple Silicon 的通用版本

14 </Card>14 </Card>

15 15

~~16 <Card title="Download for Windows" icon="windows" href="https://claude.ai/api/desktop/win32/x64/setup/latest/redirect?utm_source=claude_code&utm_medium=docs">~~16 <Card title="下載 Windows 版本" icon="windows" href="https://claude.ai/api/desktop/win32/x64/setup/latest/redirect?utm_source=claude_code&utm_medium=docs">

~~17 For x64 processors~~17 適用於 x64 處理器

18 </Card>18 </Card>

19 19

~~20 <Card title="Get Claude for Linux (beta)" icon="linux" href="/docs/en/desktop-linux">~~20 <Card title="取得 Claude for Linux (測試版)" icon="linux" href="/docs/zh-TW/desktop-linux">

~~21 apt or .deb for Ubuntu and Debian~~21 適用於 Ubuntu 和 Debian 的 apt 或 .deb

22 </Card>22 </Card>

23</CardGroup>23</CardGroup>

24 24

25For Windows ARM64, download the [ARM64 installer](https://claude.ai/api/desktop/win32/arm64/setup/latest/redirect?utm_source=claude_code\&utm_medium=docs). On Linux, install with apt; see [Claude Desktop on Linux](/docs/en/desktop-linux).25若要使用 Windows ARM64，請下載 [ARM64 安裝程式](https://claude.ai/api/desktop/win32/arm64/setup/latest/redirect?utm_source=claude_code\&utm_medium=docs)。在 Linux 上，使用 apt 安裝；請參閱 [Claude Desktop on Linux](/docs/zh-TW/desktop-linux)。

26 26

27<Note>27<Note>

28 Claude Code 需要 [Pro、Max、Team 或 Enterprise 訂閱](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=desktop_quickstart_pricing)。28 Claude Code 需要 [Pro、Max、Team 或 Enterprise 訂閱](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=desktop_quickstart_pricing)。

desktop-scheduled-tasks.md +14 −14

Details

14 比較排程選項14 比較排程選項

15</h2>15</h2>

16 16

~~17Claude Code offers three ways to schedule recurring or one-off work:~~17Claude Code 提供三種方式來排程定期或一次性的工作：

18 18

~~20| :------------------------- | :---------------------------------- | :------------------------------------- | :------------------------------------------------------------------------- |~~20| :-------- | :----------------------- | :---------------------------------------- | :--------------------------------------------------------- |

~~22| Requires machine on | No | Yes | Yes |~~22| 需要機器開啟 | 否 | 是 | 是 |

~~23| Requires open session | No | No | Yes |~~23| 需要開啟的工作階段 | 否 | 否 | 是 |

~~24| Persistent across restarts | Yes | Yes | Restored on `--resume`, with [exceptions](/docs/en/scheduled-tasks#limitations) |~~24| 跨重新啟動持續存在 | 是 | 是 | 在 `--resume` 上復原，有[例外](/docs/zh-TW/scheduled-tasks#limitations) |

~~25| Access to local files | No (fresh clone) | Yes | Yes |~~25| 存取本機檔案 | 否（全新複製） | 是 | 是 |

~~28| Customizable schedule | Via `/schedule` in the CLI | Yes | Yes |~~28| 可自訂排程 | 透過 CLI 中的 `/schedule` | 是 | 是 |

~~29| Minimum interval | 1 hour | 1 minute | 1 minute |~~29| 最小間隔 | 1 小時 | 1 分鐘 | 1 分鐘 |

30 30

31<Tip>31<Tip>

~~32 Use **cloud tasks** for work that should run reliably without your machine. Use **Desktop tasks** when you need access to local files and tools. Use **`/loop`** for quick polling during a session.~~32 使用**雲端工作**來執行應該在沒有您的機器的情況下可靠執行的工作。當您需要存取本機檔案和工具時，使用**Desktop 工作**。使用 **`/loop`** 進行工作階段期間的快速輪詢。

33</Tip>33</Tip>

34 34

35<Note>35<Note>

discover-plugins.md +11 −8

Details

207 </Step>207 </Step>

208 208

209 <Step title="使用您的新外掛程式">209 <Step title="使用您的新外掛程式">

210 檢查安裝摘要：如果它報告 `Run /reload-plugins to activate.`，執行 `/reload-plugins`，如果該命令警告重新載入將重新讀取對話，請以 `/reload-plugins --force` 重新執行。210 如果安裝摘要報告 `Run /reload-plugins to activate.`，Claude Code 會為您執行該重新載入。如果重新載入警告您的下一則訊息會重新讀取對話，請執行 `/reload-plugins --force` 以啟用外掛程式。

211 211

212 外掛程式 skills 由外掛程式名稱命名空間，因此 **commit-commands** 提供 `/commit-commands:commit` 之類的 skills。212 外掛程式 skills 由外掛程式名稱命名空間，因此 **commit-commands** 提供 `/commit-commands:commit` 之類的 skills。

213 213

349當您從 `/plugin` 介面安裝時，安裝摘要會告訴您外掛程式在您目前工作階段中是否為作用中：349當您從 `/plugin` 介面安裝時，安裝摘要會告訴您外掛程式在您目前工作階段中是否為作用中：

350 350

351* `Plugin is now active.`：Claude Code 在安裝過程中啟動了外掛程式。351* `Plugin is now active.`：Claude Code 在安裝過程中啟動了外掛程式。

352* `Run /reload-plugins to activate.`：外掛程式尚未作用中，因為啟動它會[使提示快取失效](/docs/zh-TW/prompt-caching#enabling-or-disabling-a-plugin)或因為啟動嘗試失敗。執行命令以啟動外掛程式。352* `Run /reload-plugins to activate.`：外掛程式尚未作用中，因為啟動它會[使提示快取失效](/docs/zh-TW/prompt-caching#enabling-or-disabling-a-plugin)或因為啟動嘗試失敗。Claude Code 接著會為您執行 `/reload-plugins`。如果該重新載入警告提示快取，請執行 `/reload-plugins --force` 以[在不重新啟動的情況下啟動外掛程式](#apply-plugin-changes-without-restarting)。

353* 如果外掛程式無法載入，摘要會報告失敗，而 `/plugin` **Errors** 標籤會顯示詳細資訊。353* 如果外掛程式無法載入，摘要會報告失敗，而 `/plugin` **Errors** 標籤會顯示詳細資訊。

354 354

355在 v2.1.221 之前，在您執行 `/reload-plugins` 或重新啟動之前，沒有安裝在目前工作階段中生效。355在 v2.1.221 之前，在您執行 `/reload-plugins` 或重新啟動之前，沒有安裝在目前工作階段中生效。

393 393

394您也可以使用直接命令管理外掛程式：394您也可以使用直接命令管理外掛程式：

395 395

396* 當您執行 `/plugin disable`、`/plugin enable` 或 `/plugin uninstall` 時，Claude Code 會開啟外掛程式面板以套用變更並保持其開啟。按 **Esc** 以在輸入另一個命令之前關閉面板。396* 當您執行 `/plugin disable`、`/plugin enable` 或 `/plugin uninstall` 時，Claude Code 會開啟外掛程式面板以套用變更並保持其開啟。按 **Esc** 以在輸入另一個命令之前關閉面板。[在不重新啟動的情況下套用外掛程式變更](#apply-plugin-changes-without-restarting)說明變更在您的工作階段中何時生效。

397* 對於指令碼編寫，請改用 `claude plugin` shell 命令，這些命令不會開啟面板。397* 對於指令碼編寫，請改用 `claude plugin` shell 命令，這些命令不會開啟面板。

398 398

399列出已安裝的外掛程式而不開啟選單：399列出已安裝的外掛程式而不開啟選單：

437 在不重新啟動的情況下套用外掛程式變更437 在不重新啟動的情況下套用外掛程式變更

438</h3>438</h3>

439 439

440當 [安裝摘要](#install-plugins) 報告 `Plugin is now active.` 時，Claude Code 已經啟動外掛程式，您可以跳過此步驟。對於其他所有情況，您在工作階段期間啟用或停用的外掛程式以及安裝摘要報告 `Run /reload-plugins to activate.` 的安裝，請執行以下命令以在不重新啟動的情況下套用所有變更：440當您關閉 `/plugin` 選單時，Claude Code 會為您執行 `/reload-plugins` 以套用您在其中所做的變更，例如安裝、啟用、停用和解除安裝外掛程式。如果重新載入會[使提示快取失效](/docs/zh-TW/prompt-caching#enabling-or-disabling-a-plugin)，它會發出警告並改為保留變更待處理；執行 `/reload-plugins --force` 以無論如何套用它們。如果 Claude 在您關閉選單時仍在回應，重新載入會在回應完成後執行。

441 441

442```shell theme={null}442對於在選單外發生的外掛程式變更，請自行執行 `/reload-plugins`。這些變更包括：

443/reload-plugins443

444```444* 您在另一個終端中執行的 `claude plugin` 命令

445* 您在開發時使用 [`--plugin-dir`](/docs/zh-TW/plugins#test-your-plugins-locally) 載入的外掛程式編輯

446* 外掛程式[自動更新](#configure-auto-updates)，其通知要求您重新載入

447* [`--plugin-dir` 資料夾](/docs/zh-TW/plugins#test-your-plugins-locally)中的變更，Claude Code 保留該變更是因為套用它會使提示快取失效

445 448

446當重新載入會使提示快取失效時，命令會發出警告並跳過，直到您使用 `--force` 重新執行它。449在 v2.1.268 之前，您在選單中啟用、停用或解除安裝的外掛程式，以及在安裝期間未啟動的安裝，會保持待處理狀態，直到您執行 `/reload-plugins`。

447 450

448`/reload-plugins` 也在沒有互動式終端的工作階段中執行，例如桌面應用程式、Agent SDK 和 [非互動模式](/docs/zh-TW/headless)（使用 `-p`）。需要 Claude Code v2.1.260 或更新版本。在這些工作階段中適用兩個限制：451`/reload-plugins` 也在沒有互動式終端的工作階段中執行，例如桌面應用程式、Agent SDK 和 [非互動模式](/docs/zh-TW/headless)（使用 `-p`）。需要 Claude Code v2.1.260 或更新版本。在這些工作階段中適用兩個限制：

449 452

env-vars.md +432 −297

Details

4 4

5# 環境變數5# 環境變數

6 6

~~7> 控制 Claude Code 行為的環境變數完整參考。~~7> 控制 Claude Code 行為的環境變數參考。

8 8

9環境變數可以控制 Claude Code 的行為，例如模型選擇、驗證、請求路由和功能切換。許多相同的行為也可以透過 [settings 檔案](/docs/zh-TW/settings) 欄位、[CLI 旗標](/docs/zh-TW/cli-reference) 或工作階段內命令（如 `/model`）進行配置。9環境變數可以控制 Claude Code 的行為，例如模型選擇、身份驗證、請求路由和功能切換。許多相同的行為也可以透過[設定檔](/docs/zh-TW/settings)欄位、[CLI 旗標](/docs/zh-TW/cli-reference)或工作階段內命令（如 `/model`）進行設定。

10 10

~~11本頁涵蓋如何：~~11本頁涵蓋以下內容：

12 12

~~13* [在您的 shell 或 settings 檔案中設定環境變數](#set-environment-variables)~~13* [在您的 shell 或設定檔中設定環境變數](#set-environment-variables)

14* [當行為可以透過多種方式設定時，檢查哪個值適用](#precedence)14* [當行為可以透過多種方式設定時，檢查哪個值適用](#precedence)

15* [查詢 Claude Code 讀取的變數](#variables)15* [查詢 Claude Code 讀取的變數](#variables)

16* [查看當變數關閉功能旗標擷取時，哪些功能停止運作](#features-that-need-feature-flag-fetching)

16 17

17<h2 id="set-environment-variables">18<h2 id="set-environment-variables">

18 設定環境變數19 設定環境變數

19</h2>20</h2>

20 21

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

22 23

23<h3 id="in-your-shell">24<h3 id="in-your-shell">

24 在您的 shell 中25 在您的 shell 中

33 claude34 claude

34 ```35 ```

35 36

~~36 若要為每個工作階段設定，請將 `export` 行新增到 `~/.bashrc`、`~/.zshrc` 或您的 shell 設定檔。~~37 若要在每個工作階段都設定它，請將 `export` 行新增到 `~/.bashrc`、`~/.zshrc` 或您的 shell 設定檔。

37 </Tab>38 </Tab>

38 39

39 <Tab title="Windows PowerShell">40 <Tab title="Windows PowerShell">

42 claude43 claude

43 ```44 ```

44 45

~~45 若要為每個工作階段設定，請執行 `[Environment]::SetEnvironmentVariable("API_TIMEOUT_MS", "1200000", "User")` 並開啟新的終端。~~46 若要在每個工作階段都設定它，請執行 `[Environment]::SetEnvironmentVariable("API_TIMEOUT_MS", "1200000", "User")` 並開啟新的終端機。

46 </Tab>47 </Tab>

47 48

48 <Tab title="Windows CMD">49 <Tab title="Windows CMD">

51 claude52 claude

52 ```53 ```

53 54

~~54 若要為每個工作階段設定，請執行 `setx API_TIMEOUT_MS "1200000"` 並開啟新的終端。~~55 若要在每個工作階段都設定它，請執行 `setx API_TIMEOUT_MS "1200000"` 並開啟新的終端機。

56 </Tab>

57</Tabs>

59指派行在成功時不會列印任何內容，因此請在執行 `claude` 之前在同一個 shell 中列印變數來確認變數已設定：

61<Tabs>

62 <Tab title="macOS, Linux, WSL">

63 ```bash theme={null}

64 echo $API_TIMEOUT_MS

65 ```

66 </Tab>

68 <Tab title="Windows PowerShell">

69 ```powershell theme={null}

70 echo $env:API_TIMEOUT_MS

71 ```

72 </Tab>

74 <Tab title="Windows CMD">

75 ```batch theme={null}

76 echo %API_TIMEOUT_MS%

77 ```

55 </Tab>78 </Tab>

56</Tabs>79</Tabs>

57 80

58<h3 id="in-settings-files">81<h3 id="in-settings-files">

~~59 在 settings 檔案中~~82 在設定檔中

60</h3>83</h3>

61 84

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

63 86

64```json ~/.claude/settings.json theme={null}87```json ~/.claude/settings.json theme={null}

65{88{

70}93}

71```94```

72 95

~~73您選擇的檔案控制變數適用於誰：~~96您選擇的檔案控制變數套用的對象：

74 97

~~75| 檔案 | 適用於 |~~98| 檔案 | 套用對象 |

~~76| :---------------------------- | :----------------------------------- |~~99| :---------------------------- | :---------------------------------------------------------------------- |

~~80| 受管 settings | 您組織中的每個人，由管理員部署 |~~103| 受管理的設定 | 您組織中的所有人，由管理員部署 |

81 104

82請參閱 [Settings 檔案](/docs/zh-TW/settings#settings-files) 以了解每個檔案的位置，以及 [Settings 優先順序](/docs/zh-TW/settings#settings-precedence) 以了解當多個檔案設定相同變數時它們如何結合。105請參閱 [設定檔](/docs/zh-TW/settings#where-settings-live) 以了解每個檔案的位置，以及 [設定優先順序](/docs/zh-TW/settings#settings-precedence) 以了解當多個檔案設定相同變數時它們如何結合。

83 106

84<h2 id="precedence">107<h2 id="precedence">

85 優先順序108 優先順序

86</h2>109</h2>

87 110

88當相同的行為同時具有環境變數和 settings 欄位時，環境變數優先。例如，`ANTHROPIC_MODEL` 覆蓋 `model` 設定，`CLAUDE_CODE_AUTO_CONNECT_IDE` 覆蓋 `autoConnectIde`。當環境變數未設定時，settings 欄位適用。111某些行為同時具有環境變數和專用設定鍵，Claude Code 讀取哪一個的順序因鍵而異。對於 `ANTHROPIC_MODEL` 和 `CLAUDE_CODE_AUTO_CONNECT_IDE`，Claude Code 會先讀取變數，只有在變數未設定時才使用 `model` 或 `autoConnectIde` 設定。對於您要設定的配對，請檢查下方變數的列，以及 [設定參考](/docs/zh-TW/settings-reference) 上的鍵項目。

112

113當相同的變數同時在您的 shell 和設定檔 `env` 區塊中設定時，設定檔值會套用。Claude Code 會將每個 `env` 項目寫入程序環境，取代從 shell 繼承的值。[`env` 設定](/docs/zh-TW/settings-reference#when-claude-code-applies-env-values) 說明何時套用它們。少數變數有特殊處理；[`env` 設定](/docs/zh-TW/settings-reference#env) 列出例外。

89 114

90當相同的變數同時在您的 shell 和 settings 檔案 `env` 區塊中設定時，settings 檔案值適用。Claude Code 在啟動時將每個 `env` 項目寫入程序環境，取代從 shell 繼承的值。少數變數有特殊處理；[`env` 設定](/docs/zh-TW/settings#available-settings)列出例外。115在設定檔中，您可以設定變數，但無法移除變數。若要覆寫無法取消設定的變數，例如由您無法控制的 shell 設定檔匯出的過時 `CLAUDE_CODE_USE_VERTEX`，請在 `env` 區塊中將其設定為空字串：`"CLAUDE_CODE_USE_VERTEX": ""`。Claude Code 將空值視為未設定以進行提供者選擇。子程序仍會繼承空值。

91 116

92在 settings 檔案之間，`env` 值遵循 [settings 優先順序](/docs/zh-TW/settings#settings-precedence)，因此受管理的 settings 項目覆蓋使用者或專案 settings 中的相同變數。117在設定檔之間，`env` 值遵循 [設定優先順序](/docs/zh-TW/settings#settings-precedence)，因此受管設定項目會覆寫使用者或專案設定中的相同變數。

93 118

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

95 120

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

97 122

98<h2 id="variables">123<h2 id="variables">

99 變數124 變數

100</h2>125</h2>

101 126

127數值變數（例如逾時、權杖預算和重試次數）除了接受純數字外，還接受科學記號法和數字分隔符拼寫，除非變數的列表註記它只接受純數字。例如，Claude Code 將 `2e3` 讀作 2000，將 `64_000` 讀作 64000。在 v2.1.211 之前，這些拼寫可能會無聲地設定一個更小的值，例如 `1e6` 將逾時設定為 1。

128

129<Note>

130 對於開啟或關閉行為的變數，設定 `1` 或 `true` 以開啟，設定 `0` 或 `false` 以關閉，不分大小寫。

131

132 某些變數只讀取您是否設定了它們，因此任何非空值（包括 `0`）都會開啟行為，而您可以透過取消設定變數或將其設定為空值來關閉行為。這些變數的工作方式如下：

133

134 * `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`

135 * `DISABLE_TELEMETRY`

136 * `DISABLE_ERROR_REPORTING`

137 * `CLAUDE_CODE_TMUX_TRUECOLOR`

138 * `FALLBACK_FOR_ALL_PRIMARY_MODELS`

139 * `IS_DEMO`

140

141 另一個變數有自己的規則：`FORCE_HYPERLINK` 讀取一個數字，所以只有 `0` 會關閉它。每個變數的列表也說明了自己的規則。

142</Note>

143

102| 變數 | 用途 |144| 變數 | 用途 |

103| :------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |145| :------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

104| `ANTHROPIC_API_KEY` | 作為 `X-Api-Key` 標頭發送的 API 金鑰。設定時，即使您已登入，此金鑰也會用於代替您的 Claude Pro、Max、Team 或 Enterprise 訂閱。在非互動式模式（`-p`）中，金鑰存在時始終使用。在互動式模式中，系統會提示您在金鑰覆蓋您的訂閱之前批准一次。若要改用您的訂閱，請執行 `unset ANTHROPIC_API_KEY` |146| `ANTHROPIC_API_KEY` | 作為 `X-Api-Key` 標頭傳送的 API 金鑰。設定時，即使您已登入，此金鑰也會用於代替您的 Claude Pro、Max、Team 或 Enterprise 訂閱。在非互動模式 (`-p`) 中，金鑰存在時始終使用。在互動模式中，系統會提示您在金鑰覆蓋訂閱之前批准一次。若要改用您的訂閱，請執行 `unset ANTHROPIC_API_KEY` |

106| `ANTHROPIC_AWS_API_KEY` | [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 的工作區 API 金鑰，在 AWS 主控台中產生。作為 `x-api-key` 發送，優先於 AWS SigV4 |148| `ANTHROPIC_AWS_API_KEY` | [AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws) 的工作區 API 金鑰，在 AWS 主控台中產生。作為 `x-api-key` 傳送，優先於 AWS SigV4 |

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

108| `ANTHROPIC_AWS_WORKSPACE_ID` | [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 所需。在每個請求上作為 `anthropic-workspace-id` 標頭發送 |150| `ANTHROPIC_AWS_WORKSPACE_ID` | [AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws) 所需。在每個請求上作為 `anthropic-workspace-id` 標頭傳送 |

109| `ANTHROPIC_BASE_URL` | 覆蓋 API 端點以透過代理或閘道路由請求。設定為非第一方主機時，[MCP tool search](/docs/zh-TW/mcp#scale-with-mcp-tool-search) 預設停用。如果您的代理轉發 `tool_reference` 區塊，請設定 `ENABLE_TOOL_SEARCH=true`。自 v2.1.196 起，當此項指向 `api.anthropic.com` 以外的主機時，[Remote Control](/docs/zh-TW/remote-control#requirements) 會停用，符合其在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上的行為 |151| `ANTHROPIC_BASE_URL` | 覆蓋 API 端點以透過代理或閘道路由請求。設定為非第一方主機時，[MCP 工具搜尋](/docs/zh-TW/mcp#scale-with-mcp-tool-search) 預設停用。如果您的代理轉發 `tool_reference` 區塊，請設定 `ENABLE_TOOL_SEARCH=true`。從 v2.1.196 開始，當此指向 `api.anthropic.com` 以外的主機時，[Remote Control](/docs/zh-TW/remote-control#requirements) 停用，與其在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上的行為相符 |

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

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

112| `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](/docs/zh-TW/amazon-bedrock#service-tiers) |154| `ANTHROPIC_BEDROCK_REGION_PREFIX` | 跨區域推論設定檔前綴（`us`、`eu`、`apac`、`jp`、`au` 或 `global`）Claude Code 首先嘗試，而不是從 AWS 區域衍生的前綴。在 AWS GovCloud 區域中忽略。需要 Claude Code v2.1.224 或更新版本。請參閱 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock#cross-region-inference-profile-prefixes) |

113| `ANTHROPIC_BETAS` | 逗號分隔的其他 `anthropic-beta` 標頭值清單，以包含在 API 請求中。Claude Code 已發送其需要的 beta 標頭；使用此選項可在 Claude Code 新增原生支援之前選擇加入 [Anthropic API beta](https://platform.claude.com/docs/en/api/beta-headers)。與 [`--betas` 旗標](/docs/zh-TW/cli-reference#cli-flags)（需要 API 金鑰驗證）不同，此變數適用於所有驗證方法，包括 Claude.ai 訂閱 |155| `ANTHROPIC_BEDROCK_SERVICE_TIER` | Amazon Bedrock [服務層](https://docs.aws.amazon.com/bedrock/latest/userguide/service-tiers-inference.html)（`default`、`flex` 或 `priority`）。作為 `X-Amzn-Bedrock-Service-Tier` 標頭傳送。請參閱 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock#service-tiers) |

114| `ANTHROPIC_CUSTOM_HEADERS` | 要新增至請求的自訂標頭（`Name: Value` 格式，多個標頭以換行符分隔） |156| `ANTHROPIC_BETAS` | 逗號分隔的其他 `anthropic-beta` 標頭值清單，以包含在 API 請求中。Claude Code 已傳送它需要的測試版標頭；在 Claude Code 新增原生支援之前，使用此選項加入 [Anthropic API 測試版](https://platform.claude.com/docs/en/api/beta-headers)。與 [`--betas` 旗標](/docs/zh-TW/cli-reference#cli-flags)（需要 API 金鑰驗證）不同，此變數適用於所有驗證方法，包括 Claude.ai 訂閱 |

115| `ANTHROPIC_CUSTOM_MODEL_OPTION` | 要在 `/model` 選擇器中新增為自訂項目的模型 ID。使用此選項可使非標準或閘道特定的模型可選擇，而無需替換內建別名。請參閱 [Model configuration](/docs/zh-TW/model-config#add-a-custom-model-option) |157| `ANTHROPIC_CUSTOM_HEADERS` | 要新增至請求的自訂標頭（`Name: Value` 格式，多個標頭以換行符分隔）。如果名稱或值包含 HTTP 標頭無法攜帶的字元（例如彎引號或零寬空格），請求會失敗並出現錯誤，該錯誤按位置識別該對。需要 Claude Code v2.1.227 或更新版本。[無效的請求標頭值](/docs/zh-TW/errors#invalid-request-header-value) 列出確切的字元集和檢查執行的位置。設定認證、組織或租戶、路由或 API 行為標頭（例如 `Authorization` 或 `Host`）的值在伺服器管理的設定傳遞時計為 [需要批准的設定](/docs/zh-TW/server-managed-settings#environment-variables-and-the-approval-dialog)。從專案或本機設定，此類值遵循 [何時應用 `env` 值的規則](/docs/zh-TW/settings-reference#when-claude-code-applies-env-values) |

116| `ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION` | `/model` 選擇器中自訂模型項目的顯示描述。未設定時預設為 `Custom model (<model-id>)` |158| `ANTHROPIC_CUSTOM_MODEL_OPTION` | 要在 `/model` 選擇器中新增為自訂項目的模型 ID。使用此選項可使非標準或閘道特定的模型可選，而無需取代內建別名。請參閱 [模型設定](/docs/zh-TW/model-config#add-a-custom-model-option) |

118| `ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES` | 請參閱 [Model configuration](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |160| `ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` | `/model` 選擇器中自訂模型項目的顯示名稱。未設定時，如果 Claude Code [識別 ID](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)，項目會顯示模型的名稱，否則顯示模型 ID |

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

120| `ANTHROPIC_DEFAULT_FABLE_MODEL_DESCRIPTION` | 請參閱 [Model configuration](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |162| `ANTHROPIC_DEFAULT_FABLE_MODEL` | `fable` 別名解析為的模型 ID，以及 Claude Code 識別為 Fable 模型的 ID，用於第三方提供者上的 [自動模型回退](/docs/zh-TW/model-config#automatic-model-fallback)。請參閱 [模型設定](/docs/zh-TW/model-config#environment-variables) |

121| `ANTHROPIC_DEFAULT_FABLE_MODEL_NAME` | 請參閱 [Model configuration](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |163| `ANTHROPIC_DEFAULT_FABLE_MODEL_DESCRIPTION` | `/model` 選擇器中釘選 Fable 模型的顯示說明。未設定時，列表顯示以 `Custom Fable model` 開頭的預設說明。請參閱 [模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

122| `ANTHROPIC_DEFAULT_FABLE_MODEL_SUPPORTED_CAPABILITIES` | 請參閱 [Model configuration](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |164| `ANTHROPIC_DEFAULT_FABLE_MODEL_NAME` | `/model` 選擇器中釘選 Fable 模型的顯示名稱。未設定時，如果 Claude Code 識別釘選 ID，列表顯示模型的名稱，否則顯示釘選 ID。請參閱 [模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

123| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | 請參閱 [Model configuration](/docs/zh-TW/model-config#environment-variables) |165| `ANTHROPIC_DEFAULT_FABLE_MODEL_SUPPORTED_CAPABILITIES` | 釘選 Fable 模型支援的 [功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) 的逗號分隔清單，例如 `effort,thinking`。請參閱 [模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

124| `ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION` | 請參閱 [Model configuration](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |166| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | `haiku` 別名解析為的模型 ID，也用於 [背景功能](/docs/zh-TW/costs#background-token-usage)。請參閱 [模型設定](/docs/zh-TW/model-config#environment-variables) |

125| `ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME` | 請參閱 [Model configuration](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |167| `ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION` | `/model` 選擇器中釘選 Haiku 模型的顯示說明。未設定時，列表顯示以 `Custom Haiku model` 開頭的預設說明。請參閱 [模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

126| `ANTHROPIC_DEFAULT_HAIKU_MODEL_SUPPORTED_CAPABILITIES` | 請參閱 [Model configuration](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |168| `ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME` | `/model` 選擇器中釘選 Haiku 模型的顯示名稱。未設定時，如果 Claude Code 識別釘選 ID，列表顯示模型的名稱，否則顯示釘選 ID。請參閱 [模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

127| `ANTHROPIC_DEFAULT_OPUS_MODEL` | 請參閱 [Model configuration](/docs/zh-TW/model-config#environment-variables) |169| `ANTHROPIC_DEFAULT_HAIKU_MODEL_SUPPORTED_CAPABILITIES` | 釘選 Haiku 模型支援的 [功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) 的逗號分隔清單，例如 `effort,thinking`。請參閱 [模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

128| `ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION` | 請參閱 [Model configuration](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |170| `ANTHROPIC_DEFAULT_MODEL` | 新工作階段預設啟動的模型。需要 Claude Code v2.1.236 或更新版本。請參閱 [為新工作階段設定預設模型](/docs/zh-TW/model-config#set-a-default-model-for-new-sessions) |

129| `ANTHROPIC_DEFAULT_OPUS_MODEL_NAME` | 請參閱 [Model configuration](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |171| `ANTHROPIC_DEFAULT_OPUS_MODEL` | `opus` 別名解析為的模型 ID，以及 Plan Mode 啟用時 `opusplan` 使用的模型 ID。請參閱 [模型設定](/docs/zh-TW/model-config#environment-variables) |

130| `ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES` | 請參閱 [Model configuration](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |172| `ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION` | `/model` 選擇器中釘選 Opus 模型的顯示說明。未設定時，列表顯示以 `Custom Opus model` 開頭的預設說明。請參閱 [模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

131| `ANTHROPIC_DEFAULT_SONNET_MODEL` | 請參閱 [Model configuration](/docs/zh-TW/model-config#environment-variables) |173| `ANTHROPIC_DEFAULT_OPUS_MODEL_NAME` | `/model` 選擇器中釘選 Opus 模型的顯示名稱。未設定時，如果 Claude Code 識別釘選 ID，列表顯示模型的名稱，否則顯示釘選 ID。請參閱 [模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

132| `ANTHROPIC_DEFAULT_SONNET_MODEL_DESCRIPTION` | 請參閱 [Model configuration](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |174| `ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES` | 釘選 Opus 模型支援的 [功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) 的逗號分隔清單，例如 `effort,thinking`。請參閱 [模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

133| `ANTHROPIC_DEFAULT_SONNET_MODEL_NAME` | 請參閱 [Model configuration](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |175| `ANTHROPIC_DEFAULT_SONNET_MODEL` | `sonnet` 別名解析為的模型 ID，以及 Plan Mode 未啟用時 `opusplan` 使用的模型 ID。請參閱 [模型設定](/docs/zh-TW/model-config#environment-variables) |

134| `ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES` | 請參閱 [Model configuration](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |176| `ANTHROPIC_DEFAULT_SONNET_MODEL_DESCRIPTION` | `/model` 選擇器中釘選 Sonnet 模型的顯示說明。未設定時，列表顯示以 `Custom Sonnet model` 開頭的預設說明。請參閱 [模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

177| `ANTHROPIC_DEFAULT_SONNET_MODEL_NAME` | `/model` 選擇器中釘選 Sonnet 模型的顯示名稱。未設定時，如果 Claude Code 識別釘選 ID，列表顯示模型的名稱，否則顯示釘選 ID。請參閱 [模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

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

179| `ANTHROPIC_FEDERATION_RULE_ID` | [工作負載身份聯盟](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的聯盟規則 ID。與 `ANTHROPIC_ORGANIZATION_ID` 一起設定時，Claude Code 選擇聯盟認證，其優先順序高於您的 `/login` 認證。請參閱 [驗證優先順序](/docs/zh-TW/authentication#authentication-precedence) |

136| `ANTHROPIC_FOUNDRY_AUTH_TOKEN` | Microsoft Foundry 驗證的 Bearer 權杖，例如 Microsoft Entra 存取權杖。Claude Code 將其作為 `Authorization: Bearer` 標頭發送。優先於 `ANTHROPIC_FOUNDRY_API_KEY` 和 Azure 預設認證鏈。請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)。需要 Claude Code v2.1.203 或更新版本 |181| `ANTHROPIC_FOUNDRY_AUTH_TOKEN` | Microsoft Foundry 驗證的持有人權杖，例如 Microsoft Entra 存取權杖。Claude Code 將其作為 `Authorization: Bearer` 標頭傳送。優先於 `ANTHROPIC_FOUNDRY_API_KEY` 和 Azure 預設認證鏈。請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)。需要 Claude Code v2.1.203 或更新版本 |

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

138| `ANTHROPIC_FOUNDRY_RESOURCE` | Microsoft Foundry 資源名稱（例如，`my-resource`）。如果未設定 `ANTHROPIC_FOUNDRY_BASE_URL`，則為必需（請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)） |183| `ANTHROPIC_FOUNDRY_RESOURCE` | Microsoft Foundry 資源名稱（例如 `my-resource`）。如果未設定 `ANTHROPIC_FOUNDRY_BASE_URL`，則為必需（請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)） |

140| `ANTHROPIC_SMALL_FAST_MODEL` | \[已棄用] [Haiku 級別模型用於背景任務](/docs/zh-TW/costs)的名稱 |185| `ANTHROPIC_ORGANIZATION_ID` | [工作負載身份聯盟](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的組織 ID。與 `ANTHROPIC_FEDERATION_RULE_ID` 一起設定。請參閱 [驗證優先順序](/docs/zh-TW/authentication#authentication-precedence) |

141| `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 否則會為背景任務使用 [default Sonnet model or the primary model](/docs/zh-TW/amazon-bedrock#4-pin-model-versions) |186| `ANTHROPIC_PROFILE` | 要驗證的 Anthropic 設定檔名稱，例如由 [`ant auth login`](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/authentication) 建立的或透過 [登入主控台帳戶而不使用 API 金鑰](/docs/zh-TW/authentication#sign-in-without-an-api-key)。請參閱 [驗證優先順序](/docs/zh-TW/authentication#authentication-precedence) |

142| `ANTHROPIC_VERTEX_BASE_URL` | 覆蓋 Google Cloud's Agent Platform 端點 URL。用於自訂 Google Cloud's Agent Platform 端點或透過 [LLM gateway](/docs/zh-TW/llm-gateway) 路由。請參閱 [Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai) |187| `ANTHROPIC_SMALL_FAST_MODEL` | \[已棄用] [背景工作的 Haiku 級模型](/docs/zh-TW/costs) 的名稱 |

143| `ANTHROPIC_VERTEX_PROJECT_ID` | Google Cloud's Agent Platform 的 GCP 專案 ID。被 `GCLOUD_PROJECT`、`GOOGLE_CLOUD_PROJECT` 或您的 `GOOGLE_APPLICATION_CREDENTIALS` 認證檔案中的專案覆蓋。請參閱 [Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai) |188| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | 使用 Amazon Bedrock 或 Amazon Bedrock Mantle 時，覆蓋 Haiku 級模型的 AWS 區域。在 Amazon Bedrock 上，只有在同時設定 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 或已棄用的 `ANTHROPIC_SMALL_FAST_MODEL` 時，此才會生效，因為 Amazon Bedrock 否則會在工作階段區域中的 [預設 Sonnet 模型或主要模型](/docs/zh-TW/amazon-bedrock#4-pin-model-versions) 上執行背景工作 |

144| `ANTHROPIC_WORKSPACE_ID` | [workload identity federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的工作區 ID。當您的聯盟規則的範圍涵蓋多個工作區時設定此項，以便權杖交換知道要針對哪個工作區 |189| `ANTHROPIC_VERTEX_BASE_URL` | 覆蓋 Google Cloud 的 Agent Platform 端點 URL。用於自訂 Google Cloud 的 Agent Platform 端點或透過 [LLM 閘道](/docs/zh-TW/llm-gateway) 路由時。請參閱 [Google Cloud 的 Agent Platform](/docs/zh-TW/google-vertex-ai) |

145| `API_FORCE_IDLE_TIMEOUT` | 覆蓋 5 分鐘的閒置逾時，該逾時會在沒有位元組到達時中止串流模型回應。設定為 `0` 以停用逾時，例如當緩慢的 [gateway](/docs/zh-TW/llm-gateway) 或本機模型在區塊之間暫停超過 5 分鐘時。設定為 `1` 以在每個提供者上保持逾時。未設定時，逾時在直接 Anthropic API 和 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 連線上無效，其中 Claude Code 自己的位元組級串流監視程式執行，在每個其他提供者上有效，包括 [Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai)、[Microsoft Foundry](/docs/zh-TW/microsoft-foundry)、[Mantle](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint)、[Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 和閘道連線，因此停滯的串流會中止而不是掛起。自 v2.1.169 起 |190| `ANTHROPIC_VERTEX_PROJECT_ID` | Google Cloud 的 Agent Platform 請求所定址的 GCP 專案 ID。請參閱 [設定 GCP 認證](/docs/zh-TW/google-vertex-ai#3-configure-gcp-credentials) |

146| `API_TIMEOUT_MS` | API 請求的逾時（以毫秒為單位）（預設值：600000，或 10 分鐘；最大值：2147483647）。在緩慢網路上請求逾時或透過代理路由時增加此值。超過最大值的值會導致基礎計時器溢位，並導致請求立即失敗 |191| `ANTHROPIC_WORKSPACE_ID` | [工作負載身份聯盟](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的工作區 ID。當您的聯盟規則範圍涵蓋多個工作區時設定此項，以便權杖交換知道要定位哪個工作區 |

147| `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/)） |192| `API_FORCE_IDLE_TIMEOUT` | 覆蓋 5 分鐘的主體閒置逾時，該逾時在沒有位元組到達時中止串流模型回應。設定為 `0` 以關閉逾時，例如當緩慢的 [閘道](/docs/zh-TW/llm-gateway) 或本機模型在區塊之間暫停超過 5 分鐘時，或 `1` 以為每個提供者保持開啟。未設定時，逾時在直接 Anthropic API 和 [AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws) 以外的提供者上啟用。[串流監視狗](/docs/zh-TW/network-config#streaming-idle-watchdogs) 獨立執行，即使您在此設定 `0`，也會中止長時間的無聲暫停 |

193| `API_TIMEOUT_MS` | API 請求的逾時（毫秒）（預設值：600000，或 10 分鐘；最大值：2147483647）。在慢速網路上或透過代理路由時請求逾時時增加此值。超過最大值的值會溢出基礎計時器並導致請求立即失敗 |

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

149| `BASH_MAX_OUTPUT_LENGTH` | bash 輸出中的最大字元數，超過此數量後完整輸出會儲存到檔案，Claude 會收到路徑加上簡短預覽。請參閱 [Bash tool behavior](/docs/zh-TW/tools-reference#bash-tool-behavior) |196| `BASH_MAX_OUTPUT_LENGTH` | Claude Code 讀回命令結果的 bash 輸出的最大字元數（預設值：30000；最大值：150000）。如果您設定 [`bashOutputMaxChars`](/docs/zh-TW/settings-reference#bashoutputmaxchars) 設定，Claude Code 會忽略此變數。請參閱 [輸出限制](/docs/zh-TW/tools-reference#output-limits) |

151| `CCR_FORCE_BUNDLE` | 設定為 `1` 以強制 [`claude --cloud`](/docs/zh-TW/claude-code-on-the-web#send-local-repositories-without-github) 在 GitHub 存取可用時也要捆綁並上傳您的本機儲存庫 |198| `BETA_TRACING_ENDPOINT` | [詳細測試版追蹤](/docs/zh-TW/monitoring-usage#traces-beta) 的 OTLP 端點：使用 `ENABLE_BETA_TRACING_DETAILED=1`，日誌和追蹤會傳送到那裡，而不是配置的匯出器。在您的 shell、使用者設定或受管設定中設定。在 [專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env) 中忽略 |

152| `CLAUDECODE` | 在 Claude Code 生成的子程序中設定為 `1`（Bash 和 PowerShell 工具、tmux 工作階段、[hook](/docs/zh-TW/hooks) 命令、[status line](/docs/zh-TW/statusline) 命令、stdio [MCP server](/docs/zh-TW/mcp) 子程序）。IDE 擴充功能也在其整合終端中設定此項。用於偵測指令碼何時在 Claude Code 生成的子程序內執行。若要檢查目前程序是否由工具呼叫或 hook 直接生成，而不是在 Claude Code 啟動的 stdio MCP 伺服器內，請改用 `CLAUDE_CODE_CHILD_SESSION` |199| `CCR_FORCE_BUNDLE` | 設定為 `1` 以強制 [`claude --cloud`](/docs/zh-TW/claude-code-on-the-web#send-local-repositories-without-github) 捆綁並上傳您的本機儲存庫，而不是從其遠端複製 |

153| `CLAUDE_AFK_COUNTDOWN_MS` | 在未回答的 [`AskUserQuestion`](/docs/zh-TW/tools-reference) 對話框上自動繼續前，螢幕上倒數計時出現前的毫秒數。預設 `20000`（20 秒），上限為自動繼續逾時。除非自動繼續開啟，否則無效；請參閱 [`askUserQuestionTimeout`](/docs/zh-TW/settings#available-settings) 設定和 `CLAUDE_AFK_TIMEOUT_MS`。需要 Claude Code v2.1.198 或更新版本 |200| `CLAUDECODE` | 在 Claude Code 產生的子程序中設定為 `1`（Bash 和 PowerShell 工具、tmux 工作階段、[hook](/docs/zh-TW/hooks) 命令、[狀態列](/docs/zh-TW/statusline) 命令、stdio [MCP 伺服器](/docs/zh-TW/mcp) 子程序）。IDE 擴充功能也在其整合終端中設定此項。用於偵測指令碼何時在 Claude Code 產生的子程序內執行。若要檢查目前程序是由工具呼叫或 hook 直接產生，而不是在 Claude Code 啟動的 stdio MCP 伺服器內，請改用 `CLAUDE_CODE_CHILD_SESSION` |

154| `CLAUDE_AFK_TIMEOUT_MS` | 在未回答的 [`AskUserQuestion`](/docs/zh-TW/tools-reference) 對話框自動繼續前的閒置時間（以毫秒為單位）。自動繼續預設關閉；使用 [`askUserQuestionTimeout`](/docs/zh-TW/settings#available-settings) 設定選擇加入。此變數是演示和自動化測試的覆蓋：設定時，它優先於該設定並開啟自動繼續，即使設定未設定或為 `never`。設定 `0` 不會關閉逾時；它會立即關閉對話框。在 v2.1.198 和 v2.1.199 中，自動繼續預設開啟，逾時為 `60000`（60 秒）。需要 Claude Code v2.1.198 或更新版本 |201| `CLAUDE_AFK_COUNTDOWN_MS` | 自動繼續前，螢幕上倒數計時出現在未回答的 [`AskUserQuestion`](/docs/zh-TW/tools-reference) 對話上的毫秒數。預設 `20000`（20 秒），上限為自動繼續逾時。除非自動繼續開啟，否則無效；請參閱 [`askUserQuestionTimeout`](/docs/zh-TW/settings-reference#askuserquestiontimeout) 設定和 `CLAUDE_AFK_TIMEOUT_MS`。需要 Claude Code v2.1.198 或更新版本 |

155| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 設定為 `1` 以停用所有內建 [subagent](/docs/zh-TW/sub-agents) 類型，例如 Explore 和 Plan。僅適用於非互動式模式（`-p` 旗標）。對於想要空白狀態的 SDK 使用者很有用 |202| `CLAUDE_AFK_TIMEOUT_MS` | 未回答的 [`AskUserQuestion`](/docs/zh-TW/tools-reference) 對話在沒有您的情況下自動繼續之前的閒置時間（毫秒）。自動繼續預設關閉；使用 [`askUserQuestionTimeout`](/docs/zh-TW/settings-reference#askuserquestiontimeout) 設定加入。此變數是演示和自動化測試的覆蓋：設定時，它優先於該設定並開啟自動繼續，即使設定未設定或 `never`。設定 `0` 不會關閉逾時；它會立即關閉對話。在 v2.1.198 和 v2.1.199 中，自動繼續預設開啟，逾時為 `60000`（60 秒）。需要 Claude Code v2.1.198 或更新版本 |

156| `CLAUDE_AGENT_SDK_MCP_NO_PREFIX` | 設定為 `1` 以跳過來自 SDK 建立的 MCP 伺服器的工具名稱上的 `mcp__<server>__` 前綴。工具使用其原始名稱。僅限 SDK 使用 |203| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 設定為 `1` 以停用所有內建 [子代理](/docs/zh-TW/sub-agents) 類型，例如 Explore 和 Plan。僅適用於非互動模式（`-p` 旗標）。對於想要空白狀態的 SDK 使用者很有用。這也會移除 `general-purpose`，即當 Agent 工具呼叫省略 `subagent_type` 時 Claude Code 執行的子代理。此類呼叫隨後會失敗，並出現 [`subagent_type is required`](/docs/zh-TW/errors#subagent-type-is-required) |

157| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | 背景 subagents 的停滯逾時（以毫秒為單位）。預設 `600000`（10 分鐘）。計時器在每個串流進度事件時重設；如果在視窗內沒有進度到達，subagent 會被中止，任務會標記為失敗，將任何部分結果呈現給父級 |204| `CLAUDE_AGENT_SDK_MCP_NO_PREFIX` | 設定為 `1` 以跳過 SDK 建立的 MCP 伺服器中工具名稱上的 `mcp__<server>__` 前綴。工具使用其原始名稱。僅限 SDK 使用 |

158| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 設定自動壓縮觸發的上下文容量百分比 (1-100)。使用較低的值（如 `50`）以更早進行壓縮。此變數僅在 Claude Code 主動進行壓縮時導致更早壓縮：當設定 `CLAUDE_CODE_AUTO_COMPACT_WINDOW` 時、在 [cloud sessions](/docs/zh-TW/claude-code-on-the-web) 中、在沒有 [extended context](/docs/zh-TW/model-config#extended-context) 的 Sonnet 4.6 和 Opus 4.6 上，預設在 200K 邊界進行壓縮。在 Sonnet 5 上，proactive compaction 在模型的 [default threshold](/docs/zh-TW/model-config#sonnet-5-context-window) 處應用。在其他情況下，例如本機工作階段上的 Opus 4.8，當對話達到模型的上下文限制時，自動壓縮觸發。覆蓋只能降低閾值，因此高於預設值的值無效。適用於主要對話和 subagents |205| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | 子代理的停滯逾時（毫秒）。預設 `600000`（10 分鐘）；如果您在串流監視狗開啟時提高 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`，預設值會隨之上升，如 [處理緩慢或停滯的 API 回應](/docs/zh-TW/agent-sdk/typescript#handle-slow-or-stalled-api-responses) 所述。計時器在每個串流進度事件上重設；如果在視窗內沒有進度到達，Claude Code 會中止子代理並向父代報告停滯 |

159| `CLAUDE_AUTO_BACKGROUND_TASKS` | 設定為 `1` 以強制啟用長時間執行的代理任務的自動背景執行。啟用時，subagents 在執行約兩分鐘後會移至背景 |206| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 設定自動壓縮視窗的百分比（1-100），自動壓縮在該百分比觸發。使用較低的值（如 `50`）以更早壓縮；變數無法提高閾值，因此高於預設百分比的值會被忽略。它僅適用於在模型的上下文限制之前 [壓縮的工作階段](/docs/zh-TW/model-config#context-window-and-auto-compaction)。適用於主要對話和子代理 |

160| `CLAUDE_AX_SCREEN_READER` | 設定為 `1` 以呈現螢幕閱讀器友善的輸出：沒有裝飾邊框或動畫的平面文字。設定為 `0` 以強制關閉螢幕閱讀器模式，即使 [`axScreenReader`](/docs/zh-TW/settings#available-settings) 為 `true`。[`--ax-screen-reader`](/docs/zh-TW/cli-reference#cli-flags) 旗標優先。需要 Claude Code v2.1.181 或更新版本 |207| `CLAUDE_AUTO_BACKGROUND_TASKS` | 設定為 `1` 以強制啟用長時間執行的代理工作的自動背景化。啟用時，子代理在執行約兩分鐘後會移至背景。也在 Claude Code v2.1.212 或更新版本的非互動模式中啟用 [長 MCP 工具呼叫的自動背景化](/docs/zh-TW/mcp#automatic-backgrounding-of-long-tool-calls) |

208| `CLAUDE_AX_PREPARK_MS` | 在 [螢幕閱讀器模式](/docs/zh-TW/accessibility#what-your-screen-reader-hears) 中，Claude Code 在游標位於行首時等待的毫秒數，然後才寫入新的或變更的行。預設 `50`。設定 `0` 以立即寫入。Claude Code 將等待上限設為 `5000`。需要 Claude Code v2.1.233 或更新版本 |

209| `CLAUDE_AX_SCREEN_READER` | 設定為 `1` 以呈現螢幕閱讀器友善的輸出：沒有裝飾邊框或動畫的平面文字。設定為 `0` 以強制關閉螢幕閱讀器模式，即使 [`axScreenReader`](/docs/zh-TW/settings-reference#axscreenreader) 為 `true`。[`--ax-screen-reader`](/docs/zh-TW/cli-reference#cli-flags) 旗標優先。需要 Claude Code v2.1.181 或更新版本 |

210| `CLAUDE_AX_STARTUP_QUIET_MS` | 在 [螢幕閱讀器模式](/docs/zh-TW/accessibility) 中，Claude Code 在啟動確認行後保持第一個介面呈現的毫秒數，以便您的螢幕閱讀器可以在新輸出中斷之前完整說出該行。預設 `3000`。設定 `0` 以立即呈現。Claude Code 將保持上限設為 `600000`（10 分鐘）。您的第一次按鍵會提前結束保持。需要 Claude Code v2.1.217 或更新版本 |

162| `CLAUDE_CLIENT_PRESENCE_FILE` | 外部工具（例如螢幕鎖定監聽器）在您解鎖螢幕時建立並在您鎖定螢幕時刪除的檔案路徑。檔案存在時，Claude Code 會跳過 [Remote Control mobile push notifications](/docs/zh-TW/remote-control#mobile-push-notifications)，因此當您主動使用電腦時，您會停止收到推送。檔案不存在或無法讀取時，通知會正常發送。Claude Code 每次推送觸發事件檢查一次檔案，而不是輪詢它。需要 Claude Code v2.1.181 或更新版本 |212| `CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` | 位元組級串流閒置監視狗的逾時（毫秒）；設定時，它優先於 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 用於該監視狗，並保持事件級監視狗不變。Claude Code 將此變數限制在 10 秒到 30 分鐘之間。需要 Claude Code v2.1.210 或更新版本 |

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

164| `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` | 設定為 `1` 以從使用 `--add-dir` 指定的目錄載入記憶體檔案。載入 `CLAUDE.md`、`.claude/CLAUDE.md`、`.claude/rules/*.md` 和 `CLAUDE.local.md`。預設情況下，其他目錄不載入記憶體檔案 |215| `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` | 設定為 `1` 以從使用 `--add-dir` 指定的目錄載入記憶體檔案。載入 `CLAUDE.md`、`.claude/CLAUDE.md`、`.claude/rules/*.md` 和 `CLAUDE.local.md`。預設情況下，其他目錄不載入記憶體檔案 |

165| `CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT` | 設定為 `1` 以在 [fullscreen rendering](/docs/zh-TW/fullscreen) 中的每一幀上重新繪製整個螢幕，而不是發送增量更新。如果全螢幕模式顯示過時或錯位的文字片段，請使用此選項。Claude Code 在 Windows 上的背景工作階段和 [agent view](/docs/zh-TW/agent-view) 中自動啟用此功能 |216| `CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT` | 設定為 `1` 以在 [全螢幕呈現](/docs/zh-TW/fullscreen) 中每幀重繪整個螢幕，而不是傳送增量更新。如果全螢幕模式顯示過時或錯位的文字片段，請使用此選項。Claude Code 在 Windows 上的背景工作階段和 [代理檢視](/docs/zh-TW/agent-view) 上自動啟用此功能 |

166| `CLAUDE_CODE_ALWAYS_ENABLE_EFFORT` | 設定為 `1` 以在每個請求中發送 [effort](/docs/zh-TW/model-config#adjust-effort-level) 參數，即使 Claude Code 不將模型 ID 識別為支援努力的模型。在透過 [LLM gateway](/docs/zh-TW/llm-gateway) 或第三方提供者路由時使用，該提供者在自訂識別碼下提供模型。在 API 中拒絕努力參數的模型，包括 Claude 3 模型、Sonnet 4.0 和 4.5、Opus 4.0 和 4.1 以及 Haiku 4.5，仍被排除，以便請求不會失敗 |217| `CLAUDE_CODE_ALWAYS_ENABLE_EFFORT` | 設定為 `1` 以在每個請求中傳送 [effort](/docs/zh-TW/model-config#adjust-effort-level) 參數，即使 Claude Code 不識別模型 ID 為 effort 功能。在透過 [LLM 閘道](/docs/zh-TW/llm-gateway) 或第三方提供者以自訂識別碼提供模型時使用此選項。在 API 上拒絕 effort 參數的模型（包括 Claude 3 模型、Sonnet 4.0 和 4.5、Opus 4.0 和 4.1 以及 Haiku 4.5）仍被排除，因此請求不會失敗 |

168| `CLAUDE_CODE_ARTIFACT_AUTO_OPEN` | 設定為 `0` 以停止 Claude Code 在發佈新 [artifact](/docs/zh-TW/artifacts) 時自動開啟瀏覽器。重新發佈現有 artifact 無論此設定如何都不會開啟瀏覽器 |219| `CLAUDE_CODE_ARTIFACT_AUTO_OPEN` | 設定為 `0` 以停止 Claude Code 在發佈新 [artifact](/docs/zh-TW/artifacts#create-an-artifact) 時自動開啟瀏覽器 |

169| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 設定為 `0` 以省略系統提示開始處的歸屬區塊（用戶端版本和提示指紋）。停用它會改善透過 [LLM gateway](/docs/zh-TW/llm-gateway) 路由時的提示快取命中率。Anthropic API 快取不受影響 |220| `CLAUDE_CODE_ARTIFACT_COMMENTS` | 設定為 `0` 以停止 Claude 讀取和回覆 [artifact 上的評論](/docs/zh-TW/artifacts#collect-comments-on-an-artifact)。當 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` [關閉 artifact](/docs/zh-TW/artifacts#availability) 時無效。需要 Claude Code v2.1.221 或更新版本 |

170| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 設定用於自動壓縮計算的上下文容量（以 token 為單位）。預設為模型的上下文視窗：標準模型為 200K 或 [extended context](/docs/zh-TW/model-config#extended-context) 模型為 1M，除了 Sonnet 5，其具有自己的 [default threshold](/docs/zh-TW/model-config#sonnet-5-context-window)。在 1M 模型上使用較低的值（如 `500000`）以將視窗視為 500K 用於壓縮目的。該值上限為模型的實際上下文視窗。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 作為此值的百分比應用。設定此變數會將壓縮閾值與狀態行的 `used_percentage` 解耦，後者始終使用模型的完整上下文視窗 |221| `CLAUDE_CODE_ARTIFACT_COMMENTS_AUTOREACT` | 設定為 `0` 以停止 Claude [自動回覆傳送給它的評論](/docs/zh-TW/artifacts#let-claude-reply-to-comments-on-its-own)。需要 Claude Code v2.1.228 或更新版本 |

171| `CLAUDE_CODE_AUTO_CONNECT_IDE` | 覆蓋自動 [IDE connection](/docs/zh-TW/vs-code)。預設情況下，在支援的 IDE 的整合終端內啟動時，Claude Code 會自動連線。設定為 `false` 以防止此情況。設定為 `true` 以在自動偵測失敗時強制連線嘗試，例如當 tmux 遮蔽父終端時。優先於 [`autoConnectIde`](/docs/zh-TW/settings#global-config-settings) 全域配置設定 |222| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 設定為 `0` 以省略 [歸屬區塊](/docs/zh-TW/llm-gateway-protocol#system-prompt-attribution-block)，該區塊在系統提示開始時攜帶用戶端版本和提示指紋。直接連線到 Anthropic API 的快取無論如何都不受影響。在某些直接連線設定中，Claude Code 在 [自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 分類器請求上保持區塊，即使您設定 `0`。在 [系統提示歸屬區塊](/docs/zh-TW/llm-gateway-protocol#system-prompt-attribution-block) 中，檢查此涵蓋哪些連線和認證。在 v2.1.181 之前，該區塊在自訂基礎 URL 和 Microsoft Foundry 連線上包含每個請求的權杖，因此在這些版本上，當您的 LLM 閘道在請求主體上快取或將請求轉發給第三方提供者時，或當您直接連線到 Microsoft Foundry 時，將其設定為 `0` |

172| `CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS` | Claude Code 等待 AWS 預設認證提供者鏈產生認證的時間（以毫秒為單位），然後請求失敗並出現 [`AWS default-chain credential resolve timed out`](/docs/zh-TW/errors#aws-default-chain-credential-resolve-timed-out)（預設值：`60000`）。當您的鏈中的步驟合法需要更長時間時提高此值，例如透過 `aws-vault` 等包裝器進行 MFA 的瀏覽器型 SSO 登入。適用於 Claude Code 使用預設鏈簽署的任何地方：[Amazon Bedrock](/docs/zh-TW/amazon-bedrock#credential-caching-and-resolution-timeout)、[Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 和 [Mantle endpoint](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint)。需要 Claude Code v2.1.207 或更新版本 |223| `CLAUDE_CODE_AUTO_BACKGROUND_WORKER_CHECKIN_SECONDS` | 啟用 `CLAUDE_AUTO_BACKGROUND_TASKS` 時，提醒 Claude 檢查仍在執行的 [背景子代理](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background) 之間的秒數。僅接受 `1` 到 `86400` 的純整數；任何其他值或拼寫讀作未設定。未設定時，沒有檢查提醒。需要 Claude Code v2.1.248 或更新版本 |

173| `CLAUDE_CODE_BRIDGE_SESSION_ID` | 在工作階段具有作用中 [Remote Control](/docs/zh-TW/remote-control) 連線時在 Bash 工具和 [hook command](/docs/zh-TW/hooks) 子程序中自動設定，並在連線結束時移除。該值是工作階段的 ID，格式為 `session_`，與出現在工作階段 `claude.ai/code` URL 中的識別碼相同，因此指令碼可以連結回執行它的工作階段。需要 Claude Code v2.1.199 或更新版本。在 [cloud sessions](/docs/zh-TW/claude-code-on-the-web) 中，改為讀取 `CLAUDE_CODE_REMOTE_SESSION_ID` |224| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 設定 [自動壓縮視窗](/docs/zh-TW/model-config#set-the-auto-compact-window)（權杖），從 `100000` 到 `1000000`。僅接受純整數（如 `500000`）：像 `500k` 這樣的值讀作 `500` 並限制在 100K 最小值。有效視窗也上限為模型的上下文視窗。優先於 `/autocompact` 命令、`--autocompact` 旗標和 `autoCompactWindow` 設定。狀態列的 `used_percentage` 始終針對模型的完整上下文視窗進行測量，因此一旦設定此變數，該百分比不再指示何時會執行壓縮 |

174| `CLAUDE_CODE_CERT_STORE` | TLS 連線的 CA 憑證來源逗號分隔清單。`bundled` 是隨 Claude Code 提供的 Mozilla CA 集。`system` 是作業系統信任存放區，在具有 `tls.getCACertificates` 的執行時上唯讀：原生二進位檔或 npm 安裝的 Node 22.15 或更新版本。請參閱 [CA certificate store](/docs/zh-TW/network-config#ca-certificate-store)。預設為 `bundled,system` |225| `CLAUDE_CODE_AUTO_CONNECT_IDE` | 覆蓋自動 [IDE 連線](/docs/zh-TW/vs-code)。預設情況下，Claude Code 在支援的 IDE 的整合終端內啟動時自動連線。設定為 `false` 以防止此情況。設定為 `true` 以在自動偵測失敗時強制連線嘗試，例如當 tmux 隱藏父終端時。優先於 [`autoConnectIde`](/docs/zh-TW/settings-reference#autoconnectide) 全域設定 |

175| `CLAUDE_CODE_CHILD_SESSION` | 在 Claude Code 透過 Bash、PowerShell 和 Monitor 工具、[hook](/docs/zh-TW/hooks) 命令和 [status line](/docs/zh-TW/statusline) 命令生成的子程序中設定為 `1`。不為 stdio [MCP server](/docs/zh-TW/mcp) 子程序設定，這些是長期存在的，並且超過啟動它們的工作階段。與 `CLAUDECODE` 不同，這僅由 Claude Code 自己的生成路徑設定，而不是由 IDE 擴充功能設定，因此它可靠地區分嵌套工作階段與在 IDE 整合終端中啟動的頂層 `claude`。以這種方式啟動的嵌套互動式 `claude` TUI 會自動從 `--resume`、`--continue`、向上箭頭歷史記錄和 `claude agents` 清單中排除。非互動式 `claude -p` 工作階段仍然保留。設定 `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1` 以覆蓋此排除。需要 Claude Code v2.1.172 或更新版本 |226| `CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS` | Claude Code 等待 AWS 預設認證提供者鏈產生認證的時間（毫秒），然後請求失敗，並出現 [`AWS default-chain credential resolve timed out`](/docs/zh-TW/errors#aws-default-chain-credential-resolve-timed-out)（預設值：`60000`）。當鏈中的步驟合法需要更長時間時提高此值，例如透過 `aws-vault` 等包裝器進行基於瀏覽器的 SSO 登入（帶 MFA）。適用於 Claude Code 簽署預設鏈的任何地方：[Amazon Bedrock](/docs/zh-TW/amazon-bedrock#credential-caching-and-resolution-timeout)、[AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws) 和 [Mantle 端點](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint)。需要 Claude Code v2.1.207 或更新版本 |

176| `CLAUDE_CODE_CLIENT_CERT` | 用於 mTLS 驗證的用戶端憑證檔案的路徑 |227| `CLAUDE_CODE_BRIDGE_SESSION_ID` | 在工作階段有活躍 [Remote Control](/docs/zh-TW/remote-control) 連線時，在 Bash 工具和 [hook 命令](/docs/zh-TW/hooks) 子程序中自動設定，連線結束時移除。值是工作階段在 `session_` 形式中的 ID，與出現在工作階段 `claude.ai/code` URL 中的識別碼相同，因此指令碼可以連結回執行它的工作階段。需要 Claude Code v2.1.199 或更新版本。在 [雲工作階段](/docs/zh-TW/claude-code-on-the-web) 中，改為讀取 `CLAUDE_CODE_REMOTE_SESSION_ID` |

177| `CLAUDE_CODE_CLIENT_KEY` | 用於 mTLS 驗證的用戶端私密金鑰檔案的路徑 |228| `CLAUDE_CODE_BS_AS_CTRL_BACKSPACE` | 設定為 `0` 以使 Claude Code 將 `0x08` 位元組（也寫作 `^H`）讀作純 Backspace，或 `1` 以讀作 Ctrl+Backspace。任一值都會取代平台預設值。預設情況下，Claude Code 在 Windows 上將其讀作 Ctrl+Backspace，除非 `TERM_PROGRAM` 是 `mintty` 或 `TERM` 是 `cygwin`，在 macOS 和 Linux 上讀作純 Backspace。在 Windows 終端中設定 `0`，其中 [Backspace 刪除整個單詞](/docs/zh-TW/terminal-config#fix-backspace-deleting-a-whole-word-on-windows) |

178| `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE` | 加密 CLAUDE\_CODE\_CLIENT\_KEY 的密碼（可選） |229| `CLAUDE_CODE_CERT_STORE` | TLS 連線的 CA 憑證來源的逗號分隔清單。`bundled` 是隨 Claude Code 提供的 Mozilla CA 集。`system` 是作業系統信任存放區，僅在具有 `tls.getCACertificates` 的執行時上讀取：原生二進位檔或 npm 安裝的 Node 22.15 或更新版本。請參閱 [CA 憑證存放區](/docs/zh-TW/network-config#ca-certificate-store)。預設為 `bundled,system` |

179| `CLAUDE_CODE_CONNECT_TIMEOUT_MS` | 在 v2.1.186 中移除，現在是無操作。先前設定串流 API 請求的連線、TLS 和回應標頭階段的逾時。使用 `API_TIMEOUT_MS` 進行每個請求的逾時 |230| `CLAUDE_CODE_CHILD_SESSION` | 在 Claude Code 透過 Bash、PowerShell 和 Monitor 工具、[hook](/docs/zh-TW/hooks) 命令和 [狀態列](/docs/zh-TW/statusline) 命令產生的子程序中設定為 `1`。未針對 stdio [MCP 伺服器](/docs/zh-TW/mcp) 子程序設定，這些是長期存在的，並且超過產生它們的工作階段。與 `CLAUDECODE` 不同，這僅在 Claude Code 啟動子程序時由 Claude Code 本身設定，而不是由 IDE 擴充功能設定，因此它可靠地區分嵌套工作階段與在 IDE 整合終端中啟動的頂級 `claude`。以這種方式啟動的嵌套互動 `claude` TUI 會自動從 `--resume`、`--continue`、向上箭頭歷史記錄和 `claude agents` 清單中排除。非互動 `claude -p` 工作階段仍然持續。設定 `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1` 以覆蓋此排除。需要 Claude Code v2.1.172 或更新版本 |

231| `CLAUDE_CODE_CLIENT_CERT` | mTLS 驗證的用戶端憑證檔案路徑 |

232| `CLAUDE_CODE_CLIENT_KEY` | mTLS 驗證的用戶端私密金鑰檔案路徑 |

233| `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE` | 加密 CLAUDE\_CODE\_CLIENT\_KEY 的密碼（選用） |

234| `CLAUDE_CODE_CONNECT_TIMEOUT_MS` | 在 v2.1.186 中移除，現在是無操作。先前為串流 API 請求的連線、TLS 和回應標頭階段設定單獨的逾時。使用 `API_TIMEOUT_MS` 用於每個請求的逾時。對於串流請求的回應標頭階段，請參閱 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` |

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

181| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | 寫入偵錯日誌檔案的最小日誌級別。值：`verbose`、`debug`（預設）、`info`、`warn`、`error`。設定為 `verbose` 以包含高容量診斷，例如完整狀態行命令輸出，或提高到 `error` 以減少雜訊 |236| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | 寫入偵錯日誌檔案的最小日誌級別。值：`verbose`、`debug`（預設）、`info`、`warn`、`error`。設定為 `verbose` 以包含高容量診斷（如完整狀態列命令輸出），或提高到 `error` 以減少雜訊 |

182| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | 設定為 `1` 以停用 [1M context window](/docs/zh-TW/model-config#extended-context) 支援。設定時，1M 模型變體在模型選擇器中不可用，[Sonnet 5](/docs/zh-TW/model-config#sonnet-5-context-window) 工作階段被視為具有 200K 視窗。對於具有合規性要求的企業環境很有用 |237| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | 設定為 `1` 以停用 [1M 上下文視窗](/docs/zh-TW/model-config#extended-context) 支援。設定時，1M 模型變體在模型選擇器中不可用，Claude Code 將具有原生 1M 視窗的模型上的工作階段保持在 200K 視窗，例如 [Sonnet 5](/docs/zh-TW/model-config#sonnet-5-context-window) 和 Fable 模型；請參閱 [擴展上下文](/docs/zh-TW/model-config#extended-context) 以了解如何強制執行保持。對於具有合規要求的企業環境很有用。對於其在為無法識別的 `[1m]` 模型 ID 更正視窗中的角色，請參閱 [為閘道或自訂模型 ID 更正視窗](/docs/zh-TW/model-config#correct-the-window-for-a-gateway-or-custom-model-id) |

183| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | 設定為 `1` 以停用 Opus 4.6 和 Sonnet 4.6 的 [adaptive reasoning](/docs/zh-TW/model-config#adjust-effort-level)，並回退到由 `MAX_THINKING_TOKENS` 控制的固定思考預算。從 v2.1.111 起，對 Fable 5、Sonnet 5 或 Opus 4.7 及更新版本無效，其始終使用自適應推理 |238| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | 設定為 `1` 以停用 Opus 4.6 和 Sonnet 4.6 上的 [自適應推理](/docs/zh-TW/model-config#adjust-effort-level)，並回退到由 `MAX_THINKING_TOKENS` 控制的固定思考預算。對 [Fable 模型](/docs/zh-TW/model-config#extended-thinking)、Sonnet 5 或 Opus 4.7 及更新版本無效，它們始終使用自適應推理 |

184| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | 設定為 `1` 以停用 [advisor tool](/docs/zh-TW/advisor)。`/advisor` 命令變為不可用，任何配置的 `advisorModel` 都會被忽略，`--advisor` 旗標被接受但無效，因此傳遞它的現有指令碼繼續工作而不出現錯誤 |239| `CLAUDE_CODE_DISABLE_ADMIN_ENV_UNION` | 設定為 `1` 以停止 Claude Code 在管理員來源之間按金鑰合併 [受管設定](/docs/zh-TW/managed-settings#precedence-within-the-managed-tier) `env` 區塊，因此只有最高優先順序來源的整個 `env` 區塊適用，如 v2.1.223 之前。在啟動 Claude Code 的環境中設定它，因為 Claude Code 會忽略透過設定 `env` 區塊傳遞的副本。需要 Claude Code v2.1.223 或更新版本 |

185| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | 設定為 `1` 以關閉 [background agents and agent view](/docs/zh-TW/agent-view)：`claude agents`、`--bg`、`/background` 和隨選主管。相當於 [`disableAgentView`](/docs/zh-TW/settings#available-settings) 設定 |240| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | 設定為 `1` 以停用 [advisor 工具](/docs/zh-TW/advisor)。`/advisor` 命令變為不可用，任何配置的 `advisorModel` 都被忽略，`--advisor` 旗標被接受但無效，因此傳遞它的現有指令碼繼續工作而不出錯 |

186| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | 設定為 `1` 以停用 [fullscreen rendering](/docs/zh-TW/fullscreen) 並使用經典主螢幕渲染器。對話保留在您終端的原生捲動回溯中，因此 `Cmd+f` 和 tmux 複製模式可以正常工作。優先於 `CLAUDE_CODE_NO_FLICKER` 和 [`tui`](/docs/zh-TW/settings#available-settings) 設定。您也可以使用 `/tui default` 切換。不適用於從 [agent view](/docs/zh-TW/agent-view) 開啟的背景工作階段，其始終使用全螢幕渲染 |241| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | 設定為 `1` 以關閉 [背景代理和代理檢視](/docs/zh-TW/agent-view)：`claude agents`、`--bg`、`/background` 和按需主管。等同於 [`disableAgentView`](/docs/zh-TW/settings-reference#disableagentview) 設定 |

187| `CLAUDE_CODE_DISABLE_ARTIFACT` | 設定為 `1` 以停用 [Artifact](/docs/zh-TW/artifacts) 工具，該工具將工作階段輸出發佈為 claude.ai 上的私人網頁。相當於 [`disableArtifact`](/docs/zh-TW/settings#available-settings) 設定 |242| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | 設定為 `1` 以停用 [全螢幕呈現](/docs/zh-TW/fullscreen) 並使用經典主螢幕呈現器。對話保留在您終端的原生捲軸中，因此 `Cmd+f` 和 tmux 複製模式可以正常工作。優先於 `CLAUDE_CODE_NO_FLICKER` 和 [`tui`](/docs/zh-TW/settings-reference#tui) 設定。您也可以使用 `/tui default` 切換。不適用於從 [代理檢視](/docs/zh-TW/agent-view) 開啟的背景工作階段，它們始終使用全螢幕呈現 |

188| `CLAUDE_CODE_DISABLE_ATTACHMENTS` | 設定為 `1` 以停用附件處理。使用 `@` 語法的檔案提及會作為純文字發送，而不是擴展為檔案內容 |243| `CLAUDE_CODE_DISABLE_ARTIFACT` | 設定為 `1` 以關閉 [Artifact](/docs/zh-TW/artifacts) 工具，該工具將工作階段輸出發佈為 claude.ai 上的私人網頁。設定後，沒有設定檔會開啟工具。若要改為從設定檔關閉工具，請將 [`enableArtifact`](/docs/zh-TW/settings-reference#enableartifact) 設定為 `false`；已棄用的 [`disableArtifact`](/docs/zh-TW/settings-reference#disableartifact) 金鑰也會關閉它 |

189| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | 設定為 `1` 以停用 [auto memory](/docs/zh-TW/memory#auto-memory)。設定為 `0` 以在 `--bare` 模式或 [`autoMemoryEnabled: false`](/docs/zh-TW/settings#available-settings) 會以其他方式停用時強制啟用自動記憶體。停用時，Claude 不會建立或載入自動記憶體檔案 |244| `CLAUDE_CODE_DISABLE_ATTACHMENTS` | 設定為 `1` 以停用附件處理。帶有 `@` 語法的檔案提及會作為純文字傳送，而不是擴展為檔案內容 |

190| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | 設定為 `1` 以停用所有背景任務功能，包括 Bash 和 subagent 工具上的 `run_in_background` 參數、自動背景執行和 Ctrl+B 快捷鍵 |245| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | 設定為 `1` 以停用 [自動記憶](/docs/zh-TW/memory#auto-memory)。設定為 `0` 以強制開啟自動記憶，即使 `--bare` 模式或 [`autoMemoryEnabled: false`](/docs/zh-TW/settings-reference#automemoryenabled) 會停用它。停用時，Claude 不會建立或載入自動記憶檔案 |

191| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` | 設定為 `1` 以跳過檢查 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 串流回應是否帶有 `application/vnd.amazon.eventstream` 內容類型。沒有此變數，具有不同內容類型的回應會失敗並出現命名該內容類型的錯誤，這意味著 [gateway or proxy is transforming the response](/docs/zh-TW/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)。僅當閘道重寫 `Content-Type` 標頭但未修改的二進位事件串流主體通過時設定它；如果主體本身被轉換，請求會改為失敗並出現 `Truncated event message received`。需要 Claude Code v2.1.208 或更新版本 |246| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | 設定為 `1` 以停用所有背景工作功能，包括 Bash 和子代理工具上的 `run_in_background` 參數、自動背景化和 Ctrl+B 快捷鍵 |

192| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | 設定為 `1` 以停止 [background session](/docs/zh-TW/agent-view) 的執行中背景 shell 命令、動態工作流程，以及自 v2.1.198 起的背景 subagents，當 [supervisor](/docs/zh-TW/agent-view#the-supervisor-process) 停止、重新啟動或更新該工作階段的程序時，而不是將它們交給工作階段的下一個程序。僅影響該交接：使用 `←` 或 [`/background`](/docs/zh-TW/agent-view#from-inside-a-session) 將工作階段背景化仍會帶入進行中的工作，`CLAUDE_DISABLE_ADOPT` 會關閉兩者。需要 Claude Code v2.1.196 或更新版本 |247| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_DEFAULT` | 設定為 `1` 以停止 Claude Code 將缺少或空的 `Content-Type` 標頭的 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 串流回應視為 Amazon Bedrock 的二進位事件串流。預設情況下，Claude Code 假設閘道從其他未修改的回應中丟棄了標頭，因此它會解碼主體，串流保持工作。僅針對也將串流重新發出為伺服器傳送事件的閘道設定此項；Claude Code 隨後將無標頭主體讀作伺服器傳送事件。需要 Claude Code v2.1.239 或更新版本 |

193| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | 設定為 `1` 以停止 Claude Code 在作業系統報告記憶體壓力時終止 [background shell commands](/docs/zh-TW/interactive-mode#background-bash-commands)。預設情況下，在 macOS 和 Linux 上，Claude Code 在主工作階段中啟動的背景 shell 在記憶體壓力信號上終止，一旦工作階段已閒置 30 分鐘且沒有回合或 subagent 執行。Windows 沒有記憶體壓力信號，因此此變數對其無效。需要 Claude Code v2.1.193 或更新版本 |248| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` | 設定為 `1` 以跳過檢查 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 串流回應是否攜帶 `application/vnd.amazon.eventstream` 內容類型。沒有此變數，當回應攜帶不同的內容類型時，Claude Code 會失敗請求，並出現命名該類型的錯誤，這意味著 [閘道或代理正在轉換回應](/docs/zh-TW/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)。配置閘道以未修改地轉發 `Content-Type` 標頭和主體，而不是設定此變數。需要 Claude Code v2.1.208 或更新版本 |

194| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | 設定為 `1` 以停用隨 Claude Code 提供的 [skills](/docs/zh-TW/skills) 和工作流程：捆綁的 skills 和工作流程會完全移除，而內建的斜線命令（如 `/init`）保持可輸入但對模型隱藏。來自外掛程式、`.claude/skills/` 和 `.claude/commands/` 的 skills 不受影響。相當於 [`disableBundledSkills`](/docs/zh-TW/settings#available-settings) 設定；`0` 不會覆蓋它 |249| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | 設定為 `1` 以停止 [背景工作階段的](/docs/zh-TW/agent-view) 執行中背景 shell 命令、動態工作流程，以及從 v2.1.198 開始的背景子代理，當 [主管](/docs/zh-TW/agent-view#the-supervisor-process) 停止、重新啟動或更新該工作階段的程序時，而不是將它們交給工作階段的下一個程序。僅影響該交接：使用 `←` 或 [`/background`](/docs/zh-TW/agent-view#from-inside-a-session) 背景化工作階段仍會進行中的工作，`CLAUDE_DISABLE_ADOPT` 關閉兩者。需要 Claude Code v2.1.196 或更新版本 |

195| `CLAUDE_CODE_DISABLE_CLAUDE_MDS` | 設定為 `1` 以防止將任何 CLAUDE.md 記憶體檔案載入上下文，包括使用者、專案和自動記憶體檔案 |250| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | 設定為 `1` 以停止 Claude Code 在作業系統報告記憶體壓力時終止 [背景 shell 命令](/docs/zh-TW/interactive-mode#background-bash-commands)。預設情況下，在 macOS 和 Linux 上，Claude Code 在工作階段閒置 30 分鐘且沒有轉向或子代理執行時，在記憶體壓力信號上終止在主工作階段中啟動的背景 shell。Windows 沒有記憶體壓力信號，因此此變數在那裡無效。需要 Claude Code v2.1.193 或更新版本 |

196| `CLAUDE_CODE_DISABLE_CRON` | 設定為 `1` 以停用 [scheduled tasks](/docs/zh-TW/scheduled-tasks)。`/loop` skill 和 cron 工具變為不可用，任何已排程的任務停止觸發，包括已在工作階段中執行的任務 |251| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | 設定為 `1` 以停用 Claude Code 包含的 [skills](/docs/zh-TW/skills) 和工作流程：捆綁的 skills 和工作流程會完全移除，而內建命令（如 `/init`）保持可輸入但對模型隱藏。`/doctor` 保持可輸入，如內建命令；使用 `DISABLE_DOCTOR_COMMAND` 隱藏它。來自外掛程式、`.claude/skills/` 和 `.claude/commands/` 的 Skills 不受影響。等同於 [`disableBundledSkills`](/docs/zh-TW/settings-reference#disablebundledskills) 設定 |

197| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | 設定為 `1` 以從 API 請求中移除 Anthropic 特定的 `anthropic-beta` 請求標頭和 beta 工具架構欄位（例如 `defer_loading` 和 `eager_input_streaming`）。當代理閘道拒絕請求並出現「Unexpected value(s) for the `anthropic-beta` header」或「Extra inputs are not permitted」之類的錯誤時，請使用此選項。標準欄位（`name`、`description`、`input_schema`、`cache_control`）會保留。[MCP tool search](/docs/zh-TW/mcp#scale-with-mcp-tool-search) 會停用，所有 MCP 工具會提前載入，即使設定 `ENABLE_TOOL_SEARCH` |252| `CLAUDE_CODE_DISABLE_CFC_PROMPT` | 設定為 `1` 以保持 [Chrome 中的 Claude](/docs/zh-TW/chrome) 瀏覽器工具可用，同時省略系統提示的 Chrome 部分和 `/claude-in-chrome` [捆綁 skill](/docs/zh-TW/skills#bundled-skills)。適用於嵌入 Claude Code 並提供自己的瀏覽器指導的主機。需要 Claude Code v2.1.257 或更新版本 |

198| `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS` | 設定為 `1` 以停用內建的 [Explore and Plan subagents](/docs/zh-TW/sub-agents#built-in-subagents)。Claude 改為使用其搜尋工具或通用 subagent 進行探索，[plan mode](/docs/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 直接讀取檔案而不是啟動 Explore 和 Plan agents。名為 `Explore` 或 `Plan` 的自訂 subagents 不受影響。若要在 Agent SDK 或非互動式模式中移除每個內建 subagent 類型，請改用 `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS`。需要 Claude Code v2.1.198 或更新版本 |253| `CLAUDE_CODE_DISABLE_CLAUDE_MDS` | 設定為 `1` 以防止將任何 CLAUDE.md 記憶體檔案載入上下文，包括使用者、專案和自動記憶檔案 |

200| `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`](/docs/zh-TW/settings#available-settings) 設定。請參閱 [Session quality surveys](/docs/zh-TW/data-usage#session-quality-surveys) |255| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | 設定為 `1` 以從 API 請求中移除 Anthropic 特定的 `anthropic-beta` 請求標頭和測試版工具架構欄位（例如 `defer_loading` 和 `eager_input_streaming`）。當代理閘道拒絕請求並出現錯誤（例如「`anthropic-beta` 標頭的意外值」或「不允許額外輸入」）時使用此選項。標準欄位（`name`、`description`、`input_schema`、`cache_control`）被保留。[MCP 工具搜尋](/docs/zh-TW/mcp#scale-with-mcp-tool-search) 停用，所有 MCP 工具立即載入，即使您設定 `ENABLE_TOOL_SEARCH`。在 Claude Code v2.1.227 或更新版本上，[受管設定](/docs/zh-TW/managed-settings) 可以保持工具搜尋開啟。[停用預發行功能](/docs/zh-TW/llm-gateway-protocol#disable-pre-release-capabilities) 涵蓋覆蓋適用的位置 |

201| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | 設定為 `1` 以停用檔案 [checkpointing](/docs/zh-TW/checkpointing)。`/rewind` 命令將無法還原程式碼變更 |256| `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS` | 設定為 `1` 以停用內建 [Explore 和 Plan 子代理](/docs/zh-TW/sub-agents#built-in-subagents)。Claude 使用其搜尋工具或通用子代理進行探索，[plan mode](/docs/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 直接讀取檔案，而不是啟動 Explore 和 Plan 代理。名為 `Explore` 或 `Plan` 的自訂子代理不受影響。若要在 Agent SDK 或非互動模式中移除每個內建子代理類型，請改用 `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS`。需要 Claude Code v2.1.198 或更新版本 |

202| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | 設定為 `1` 以從 Claude 的系統提示中移除內建的提交和 PR 工作流程指令以及 git 狀態快照。在使用您自己的 git 工作流程 skills 時很有用。設定時優先於 [`includeGitInstructions`](/docs/zh-TW/settings#available-settings) 設定 |257| `CLAUDE_CODE_DISABLE_FAST_MODE` | 設定為 `1` 以停用 [快速模式](/docs/zh-TW/fast-mode) |

203| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | 設定為 `1` 以防止在 Anthropic API 上自動重新對應 Opus 4.0 和 4.1 至目前的 Opus 版本。在您想要刻意固定較舊模型時使用。重新對應不在 Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry 上執行 |258| `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`](/docs/zh-TW/settings-reference#feedbacksurveyrate) 設定。請參閱 [工作階段品質調查](/docs/zh-TW/data-usage#session-quality-surveys) |

204| `CLAUDE_CODE_DISABLE_MOUSE` | 設定為 `1` 以停用 [fullscreen rendering](/docs/zh-TW/fullscreen) 中的滑鼠追蹤。使用 `PgUp` 和 `PgDn` 的鍵盤捲動仍然有效。使用此選項可保留您終端的原生選擇複製行為 |259| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | 設定為 `1` 以停用檔案 [checkpointing](/docs/zh-TW/checkpointing)。`/rewind` 命令將無法復原程式碼變更。覆蓋 [`fileCheckpointingEnabled`](/docs/zh-TW/settings-reference#filecheckpointingenabled) 設定 |

205| `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` | 設定為 `1` 以停用 [fullscreen rendering](/docs/zh-TW/fullscreen) 中的點擊、拖曳和懸停處理，同時保留滑鼠滾輪捲動。當您想要滾輪捲動在 Claude Code 內工作但不想要點擊來定位游標、展開工具輸出或開啟連結時使用。當兩者都設定時，`CLAUDE_CODE_DISABLE_MOUSE` 優先。需要 Claude Code v2.1.195 或更新版本 |260| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | 設定為 `1` 以移除內建提交和 PR 工作流程指示以及 Claude 系統提示中的 git 狀態快照。在使用您自己的 git 工作流程 skills 時很有用。當設定時優先於 [`includeGitInstructions`](/docs/zh-TW/settings-reference#includegitinstructions) 設定 |

206| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 相當於設定 `DISABLE_AUTOUPDATER`、`DISABLE_FEEDBACK_COMMAND`、`DISABLE_ERROR_REPORTING` 和 `DISABLE_TELEMETRY` |261| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | 設定為 `1` 以防止在 Anthropic API 上自動重新對應 Opus 4.0 和 4.1 到目前的 Opus 版本。在您想要故意釘選較舊模型時使用。重新對應不在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上執行 |

207| `CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK` | 設定為 `1` 以停用串流請求在中途失敗時的非串流回退。串流錯誤會傳播到重試層。當代理或閘道導致回退產生重複的工具執行時很有用 |262| `CLAUDE_CODE_DISABLE_MOUSE` | 設定為 `1` 以停用 [全螢幕呈現](/docs/zh-TW/fullscreen) 中的滑鼠追蹤。使用 `PgUp` 和 `PgDn` 的鍵盤捲軸仍然有效。使用此選項以保持終端的原生選擇複製行為 |

208| `CLAUDE_CODE_DISABLE_NOTIFICATION_PRESENCE_CHECK` | 設定為 `1` 以在您在終端中輸入或聚焦時發送 `PushNotification` 工具的桌面通知。預設情況下，當工具偵測到最近的鍵盤活動或終端焦點時，工具會跳過桌面通知和 [mobile push](/docs/zh-TW/remote-control#mobile-push-notifications)。此變數僅停用該本機檢查，因此伺服器仍可在偵測到您活躍時抑制行動推送。需要 Claude Code v2.1.193 或更新版本 |263| `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` | 設定為 `1` 以停用 [全螢幕呈現](/docs/zh-TW/fullscreen) 中的點擊、拖曳和懸停處理，同時保持滑鼠滾輪捲軸。當您想要滾輪捲軸在 Claude Code 內工作但不想要點擊來定位游標、展開工具輸出或開啟連結時使用此選項。設定兩者時 `CLAUDE_CODE_DISABLE_MOUSE` 優先。需要 Claude Code v2.1.195 或更新版本 |

209| `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` | 設定為 `1` 以跳過首次執行時官方外掛程式市場的自動新增 |264| `CLAUDE_CODE_DISABLE_MTLS_RELOAD_ON_STALE_CONNECTION` | 設定為 `1` 以停止 Claude Code 在 API 請求因連線級錯誤（例如連線重設或 TLS 握手錯誤）失敗時重新讀取 [mTLS 用戶端憑證和金鑰](/docs/zh-TW/network-config#mtls-authentication)。停用重新載入後，Claude Code 僅在下次應用設定或下次啟動時載入輪換的檔案。需要 Claude Code v2.1.232 或更新版本 |

265| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 設定為任何非空值（例如 `1`）以停用非必要的網路流量：自動更新、遙測、錯誤報告、`/feedback` 命令、[Claude 起草的回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior)、發行說明、[PR 和 MR 狀態徽章](/docs/zh-TW/interactive-mode#pr-review-status) 檢查以及可用性檢查（例如 [快速模式](/docs/zh-TW/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) 檢查）。它也停止 [外掛程式 `command` 來源的背景執行](/docs/zh-TW/plugin-marketplaces#when-claude-code-re-runs-the-command)，這些是本機命令而不是網路流量，因為它們可能觸發依賴項安裝。**將其設定為 `0` 或 `false` 仍會停用此流量**，與大多數開啟/關閉變數不同；取消設定變數以再次允許它。也停用功能旗標擷取，這使 [Remote Control](/docs/zh-TW/remote-control#requirements) 和其他 [需要功能旗標擷取的功能](#features-that-need-feature-flag-fetching) 不可用。官方外掛程式市場自動安裝不涵蓋；使用 `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` 停用它。不影響 [閘道模型發現](/docs/zh-TW/llm-gateway-connect#add-gateway-models-to-the-model-picker)，它有自己的選擇加入 |

266| `CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK` | 設定為 `1` 以停用串流請求在中途失敗時的非串流回退。串流錯誤傳播到重試層。當代理或閘道導致回退產生重複工具執行時很有用 |

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

268| `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` | 設定為 `1` 以停用官方外掛程式市場的自動註冊。Claude Code 在即將註冊市場時讀取變數，通常在機器的第一次互動啟動期間。如果變數在該點設定，Claude Code 會永久跳過註冊。稍後取消設定變數不會撤銷跳過。隨時執行 `claude plugin marketplace add anthropics/claude-plugins-official` 以註冊市場 |

269| `CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS` | 設定為 `1` 以停止 Claude Code 在 Claude Code 將它們傳送到 Agent SDK 的 `canUseTool` 回呼的工作階段中執行 [未回答的權限請求的 `Notification` hooks](/docs/zh-TW/hooks#notification)，這是 Claude Desktop 和 VS Code 擴充功能主機 Claude Code 的方式。在終端工作階段中無效。需要 Claude Code v2.1.233 或更新版本 |

211| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | 設定為 `1` 以停用基於對話上下文的自動終端標題更新。在 Agent SDK 和 `claude -p` 工作階段中，這也會跳過產生工作階段標題的背景 Haiku 請求 |271| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | 設定為 `1` 以停用基於對話上下文的自動終端標題更新。在 Agent SDK 和 `claude -p` 工作階段中，這也會跳過產生工作階段標題的背景小型/快速模型請求 |

212| `CLAUDE_CODE_DISABLE_THINKING` | 設定為 `1` 以完全省略 API 請求中的 `thinking` 參數。這是代理和閘道拒絕該參數的相容性選項。該變數的行為與早期版本相同；在預設思考的模型上，省略該參數意味著模型仍可能思考。若要在 Anthropic API 上明確停用 [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)，請改用 `MAX_THINKING_TOKENS=0`，這在 Fable 5 上也無效，因為它無法關閉思考。在 [third-party providers](/docs/zh-TW/third-party-integrations) 上，`0` 同樣省略該參數，因此兩個變數在那裡的行為相同 |272| `CLAUDE_CODE_DISABLE_THINKING` | 設定為 `1` 以完全從 API 請求中省略 `thinking` 參數。這是代理和閘道拒絕參數的相容性選項。在預設思考的模型上，省略參數意味著模型仍可能思考。若要在 Anthropic API 上明確停用 [擴展思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)，請改用 `MAX_THINKING_TOKENS=0`。兩個變數都不會在 Fable 模型上關閉思考，Fable 模型無法關閉思考。在 [第三方提供者](/docs/zh-TW/third-party-integrations) 上，`MAX_THINKING_TOKENS=0` 同樣省略參數，因此兩個變數在那裡的行為相同 |

213| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | 設定為 `1` 以停用 [fullscreen rendering](/docs/zh-TW/fullscreen) 中的虛擬捲動，並呈現文字記錄中的每條訊息。如果全螢幕模式中的捲動顯示應該出現訊息的空白區域，請使用此選項 |273| `CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT` | 設定為 `1` 以在 Claude Code 不識別模型 ID 時跳過主動 [自動壓縮](/docs/zh-TW/costs#reduce-token-usage)，例如 [LLM 閘道](/docs/zh-TW/llm-gateway) 別名。沒有此變數，Claude Code 在它為 ID 假設的上下文視窗處壓縮。`CLAUDE_CODE_MAX_CONTEXT_TOKENS` 可以改為更正假設的視窗；請參閱 [為閘道或自訂模型 ID 更正視窗](/docs/zh-TW/model-config#correct-the-window-for-a-gateway-or-custom-model-id) 以了解何時應用每個變數。需要 Claude Code v2.1.223 或更新版本 |

214| `CLAUDE_CODE_DISABLE_WORKFLOWS` | 設定為 `1` 以停用 [workflows](/docs/zh-TW/workflows#turn-workflows-off)。相當於 [`disableWorkflows`](/docs/zh-TW/settings#available-settings) 設定 |274| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | 設定為 `1` 以停用 [全螢幕呈現](/docs/zh-TW/fullscreen) 中的虛擬捲軸並呈現文字記錄中的每條訊息。如果全螢幕模式中的捲軸顯示應該出現訊息的空白區域，請使用此選項 |

215| `CLAUDE_CODE_EFFORT_LEVEL` | 為支援的模型設定努力級別。值：`low`、`medium`、`high`、`xhigh`、`max` 或 `auto` 以使用模型預設值。可用級別取決於模型。優先於 `/effort` 和 `effortLevel` 設定。請參閱 [Adjust effort level](/docs/zh-TW/model-config#adjust-effort-level) |275| `CLAUDE_CODE_DISABLE_WORKFLOWS` | 設定為 `1` 以停用 [工作流程](/docs/zh-TW/workflows#turn-workflows-off)。等同於 [`disableWorkflows`](/docs/zh-TW/settings-reference#disableworkflows) 設定 |

216| `CLAUDE_CODE_ENABLE_APPEND_SUBAGENT_PROMPT` | 設定為 `1` 以啟用將額外文字附加到每個 [subagent](/docs/zh-TW/sub-agents) 系統提示的末尾。[`--append-subagent-system-prompt`](/docs/zh-TW/cli-reference#cli-flags) 旗標提供附加的文字並自動設定此變數，因此您不需要自己設定它。需要 Claude Code v2.1.205 或更新版本 |276| `CLAUDE_CODE_EFFORT_LEVEL` | 為支援的模型設定 effort 級別。值：`low`、`medium`、`high`、`xhigh`、`max` 或 `auto` 以使用模型預設值。可用級別取決於模型。優先於 `--effort`、`/effort` 和 `modelSettings` 和 `effortLevel` 設定。[`maxEffortLevel`](/docs/zh-TW/settings-reference#maxeffortlevel) 上限仍適用。請參閱 [調整 effort 級別](/docs/zh-TW/model-config#adjust-effort-level) |

217| `CLAUDE_CODE_ENABLE_AUTO_MODE` | 為相容性接受，無效。Auto mode 在每個提供者上預設可用，包括 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 和已登入的 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway) 工作階段。在 v2.1.158 到 v2.1.206 中，設定此項為 `1` 是在這些提供者上提供 [auto mode](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 所需的 |277| `CLAUDE_CODE_ENABLE_APPEND_SUBAGENT_PROMPT` | 設定為 `1` 以啟用將額外文字附加到除 [forked 子代理](/docs/zh-TW/sub-agents#fork-the-current-conversation) 外的每個 [子代理](/docs/zh-TW/sub-agents) 的系統提示末尾。[`--append-subagent-system-prompt`](/docs/zh-TW/cli-reference#cli-flags) 和 [`--append-subagent-system-prompt-file`](/docs/zh-TW/cli-reference#cli-flags) 旗標提供附加的文字並自動設定此變數，因此您不需要自己設定它。需要 Claude Code v2.1.205 或更新版本 |

218| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | 覆蓋 [session recap](/docs/zh-TW/interactive-mode#session-recap) 可用性。設定為 `0` 以強制關閉摘要，無論 `/config` 切換如何。設定為 `1` 以在 [`awaySummaryEnabled`](/docs/zh-TW/settings#available-settings) 為 `false` 時強制啟用摘要。優先於設定和 `/config` 切換 |278| `CLAUDE_CODE_ENABLE_AUTO_MODE` | 為與較舊版本相容而接受，無效。自動模式在每個提供者上預設可用，包括 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和已登入的 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway) 工作階段。在 v2.1.158 到 v2.1.206 中，設定此為 `1` 是在這些提供者上提供 [自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 所必需的 |

219| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 設定為 `1` 以在 [non-interactive mode](/docs/zh-TW/headless) 中背景安裝完成後在回合邊界處刷新外掛程式狀態。預設關閉，因為刷新會在工作階段中途更改系統提示，這會使該回合的 [prompt caching](/docs/zh-TW/prompt-caching) 失效 |279| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | 覆蓋 [工作階段摘要](/docs/zh-TW/interactive-mode#session-recap) 可用性。設定為 `0` 以強制摘要關閉，無論 `/config` 切換如何。設定為 `1` 以在 [`awaySummaryEnabled`](/docs/zh-TW/settings-reference#awaysummaryenabled) 為 `false` 時強制摘要開啟。優先於設定和 `/config` 切換 |

220| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | 設定為 `1` 以在 Anthropic 綁定的非必要流量被阻止時將「Claude 表現如何？」工作階段品質調查路由到您自己的 [OpenTelemetry collector](/docs/zh-TW/monitoring-usage)。調查評分僅作為 OTEL 事件發出到您配置的收集器。在此模式下，沒有調查資料發送到 Anthropic。在設定 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`、`DISABLE_TELEMETRY` 或 `DO_NOT_TRACK` 時適用，否則無效。`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` 和組織產品反饋政策優先 |280| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 設定為 `1` 以在背景安裝完成後在轉向邊界處刷新 [非互動模式](/docs/zh-TW/headless) 中的外掛程式狀態。預設關閉，因為刷新會在工作階段中途變更系統提示，這會使該轉向的 [提示快取](/docs/zh-TW/prompt-caching) 失效 |

221| `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](/docs/zh-TW/llm-gateway) 連線上預設關閉 |281| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | 設定為 `1` 以在 Anthropic 綁定的非必要流量被阻止時將「Claude 表現如何？」工作階段品質調查路由到您自己的 [OpenTelemetry 收集器](/docs/zh-TW/monitoring-usage)。調查評分僅作為 OTEL 事件發出到您配置的收集器。在此模式中，沒有調查資料傳送到 Anthropic。當設定 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`、`DISABLE_TELEMETRY` 或 `DO_NOT_TRACK` 時適用，否則無效。`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` 和組織產品回饋政策優先 |

222| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 設定為 `1` 以在 `ANTHROPIC_BASE_URL` 指向 Anthropic 相容閘道（例如 LiteLLM、Kong 或內部代理）時從您的閘道的 `/v1/models` 端點填充 `/model` 選擇器。預設關閉，因為由共享 API 金鑰支援的閘道會以其他方式向每個使用者顯示該金鑰可以存取的每個模型。探索的模型仍由 [`availableModels`](/docs/zh-TW/settings#available-settings) 允許清單篩選，工作階段接收；由於 [server-managed delivery is not available on gateway configurations](/docs/zh-TW/server-managed-settings#platform-availability)，透過 MDM 或受管設定檔案傳遞清單 |282| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 控制工具呼叫輸入是否在 Claude 產生時從 API 串流。關閉此選項時，大型工具輸入（例如長檔案寫入）僅在 Claude 完成產生後到達，這可能看起來像它掛起了。在 Anthropic API 上預設啟用。在 Amazon Bedrock 和 Google Cloud 的 Agent Platform 上，在部署的容器支援的每個模型上啟用。設定為 `0` 以選擇退出。設定為 `1` 以在透過 `ANTHROPIC_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_BEDROCK_BASE_URL` 透過代理路由時強制開啟。在 Microsoft Foundry 和 [閘道](/docs/zh-TW/llm-gateway) 連線上預設關閉 |

223| `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE` | {{/* max-version: 2.1.141 */}}在 v2.1.142 中移除，當 [fast mode](/docs/zh-TW/fast-mode) 預設從 Opus 4.6 移至 Opus 4.7 時 |283| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 設定為 `1` 以在 `ANTHROPIC_BASE_URL` 指向 Anthropic 相容閘道（例如 LiteLLM、Kong 或內部代理）時從您的閘道的 `/v1/models` 端點填充 `/model` 選擇器。預設關閉，因為由共用 API 金鑰支援的閘道會否則向每個使用者顯示金鑰可以存取的每個模型。發現的模型仍由工作階段接收的 [`availableModels`](/docs/zh-TW/settings-reference#availablemodels) 允許清單篩選；透過 [MDM 或受管設定檔](/docs/zh-TW/managed-settings#delivery-mechanisms) 傳遞清單，因為 [伺服器管理的傳遞在閘道設定上不可用](/docs/zh-TW/server-managed-settings#platform-availability) |

224| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 設定為 `false` 以停用提示建議（`/config` 中的「提示建議」切換）。這些是在 Claude 回應後出現在您的提示輸入中的灰顯預測。請參閱 [Prompt suggestions](/docs/zh-TW/interactive-mode#prompt-suggestions) |284| `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE` | 在 v2.1.142 中移除，當 [快速模式](/docs/zh-TW/fast-mode) 預設從 Opus 4.6 移至 Opus 4.7 時 |

225| `CLAUDE_CODE_ENABLE_TASKS` | 控制工作階段是否使用結構化 Task 工具（`TaskCreate`、`TaskUpdate`、`TaskGet`、`TaskList`）或舊版 `TodoWrite` 工具。{{/* min-version: 2.1.142 */}}自 Claude Code v2.1.142 起，Task 工具是所有模式中的預設值。設定為 `0` 以還原為 `TodoWrite`。請參閱 [Task list](/docs/zh-TW/interactive-mode#task-list) 和 [Migrate to Task tools](/docs/zh-TW/agent-sdk/todo-tracking#migrate-to-task-tools) |285| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 設定為 `false` 以關閉提示建議，即出現在提示輸入中的灰色預測。優先於 [`promptSuggestionEnabled`](/docs/zh-TW/settings-reference#promptsuggestionenabled) 設定，這是 `/config` 中的**提示建議**切換寫入的。Claude Code 也 [在您的帳戶接近或達到使用限制時暫停建議](/docs/zh-TW/interactive-mode#when-claude-code-skips-suggestions)。設定為 `true` 以在達到限制前保持它們開啟。需要 Claude Code v2.1.238 或更新版本。請參閱 [提示建議](/docs/zh-TW/interactive-mode#prompt-suggestions) |

226| `CLAUDE_CODE_ENABLE_TELEMETRY` | 設定為 `1` 以啟用 OpenTelemetry 資料收集以進行指標和日誌記錄。在配置 OTel 匯出器之前需要。請參閱 [Monitoring](/docs/zh-TW/monitoring-usage) |286| `CLAUDE_CODE_ENABLE_TASKS` | 選擇 Claude Code 在 [具有它們的工作階段](/docs/zh-TW/tools-reference#task-tool-availability) 中提供的工作追蹤工具。預設情況下，Claude Code 提供 Task 工具 `TaskCreate`、`TaskUpdate`、`TaskGet` 和 `TaskList`。設定為 `0` 以改為取得舊版 `TodoWrite` 工具。請參閱 [工作清單](/docs/zh-TW/interactive-mode#task-list) |

228| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | 設定為 `1` 以啟用 [agent teams](/docs/zh-TW/agent-teams)。Agent teams 是實驗性的，預設停用 |288| `CLAUDE_CODE_ENABLE_TODO_TOOLS` | 設定為 `1` 以在每個模型上取得工作追蹤工具。沒有它，Claude Code 預設僅在 [工作工具可用性](/docs/zh-TW/tools-reference#task-tool-availability) 下列出的模型上提供它們。`CLAUDE_CODE_ENABLE_TASKS` 仍選擇 Task 工具或 `TodoWrite`。需要 Claude Code v2.1.233 或更新版本 |

229| `CLAUDE_CODE_EXTRA_BODY` | JSON 物件以合併到每個 API 請求主體的頂層。對於傳遞 Claude Code 不直接公開的提供者特定參數很有用。在您的 shell 中匯出的值也適用於您使用 `claude agents` 或 `--bg` 分派的 [background sessions](/docs/zh-TW/agent-view)。在 v2.1.206 之前，背景工作階段忽略了 shell 匯出的值，並使用背景主管程序繼承的任何副本 |289| `CLAUDE_CODE_EXIT_AFTER_STOP_DELAY` | 查詢迴圈變為閒置後自動退出前等待的時間（毫秒）。對於使用 SDK 模式的自動化工作流程和指令碼很有用 |

231| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | {{/* min-version: 2.1.172 */}}設定為 `1` 以強制文字記錄持久化、提示歷史記錄和 `claude agents` 註冊，即使此 `claude` 是從另一個 Claude Code 工作階段內啟動的。在繼承的 `CLAUDE_CODE_CHILD_SESSION` 值（例如來自 Claude Code 的 Bash 工具首次啟動的 `screen` 工作階段）導致真正的頂層工作階段被誤分類為嵌套時使用。{{/* min-version: 2.1.178 */}}自 v2.1.178 起，Claude Code 會自動偵測 tmux 情況並忽略繼承的標記，因此 tmux 不再需要此變數。也在 v2.1.169 及更早版本上受尊重；對 v2.1.170 和 v2.1.171 無效，其中它覆蓋的嵌套工作階段偵測被移除 |291| `CLAUDE_CODE_EXTRA_BODY` | JSON 物件以合併到每個 API 請求主體的頂級。對於傳遞 Claude Code 不直接公開的提供者特定參數很有用。在您的 shell 中匯出的值也適用於您使用 `claude agents` 或 `--bg` 分派的 [背景工作階段](/docs/zh-TW/agent-view)。在 v2.1.206 之前，背景工作階段忽略 shell 匯出的值，並使用背景主管程序繼承的任何副本 |

232| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | {{/* min-version: 2.1.186 */}}設定為 `1` 以在您的終端支援但未自動偵測時強制刪除線呈現 `~~text~~`，例如透過 SSH 而未轉發 `TERM_PROGRAM`。沒有此選項，未偵測的終端會顯示文字刪除線標記而不是呈現為刪除線。需要 Claude Code v2.1.186 或更新版本 |292| `CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS` | 覆蓋檔案讀取的預設權杖限制。當您需要完整讀取較大的檔案時很有用 |

233| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 設定為 `1` 以強制啟用 DEC 私有模式 2026 [synchronized output](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)（當您的終端支援但未自動偵測時）。對於實現 BSU/ESU 但不回覆功能探測的模擬器（例如 Emacs `eat`）很有用。在 tmux 下無效。與 `CLAUDE_CODE_NO_FLICKER` 不同，後者會切換到 [fullscreen rendering](/docs/zh-TW/fullscreen)，這不會改變渲染器 |293| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | 設定為 `1` 以強制文字記錄持續性、提示歷史記錄和 `claude agents` 註冊，即使此 `claude` 是從另一個 Claude Code 工作階段內啟動的。當繼承的 `CLAUDE_CODE_CHILD_SESSION` 值（例如來自 `screen` 工作階段或由 Claude Code 的 Bash 工具首次啟動的背景啟動器）導致真正的頂級工作階段被誤分類為嵌套時使用。從 v2.1.178 開始，Claude Code 自動偵測 tmux 情況並忽略繼承的標記，因此 tmux 不再需要此變數。也在 v2.1.169 及更早版本上受尊重；對 v2.1.170 和 v2.1.171 無效，其中它覆蓋的嵌套工作階段偵測被移除 |

234| `CLAUDE_CODE_FORK_SUBAGENT` | 設定為 `1` 以啟用 Claude 生成 [forked subagents](/docs/zh-TW/sub-agents#fork-the-current-conversation)，或 `0` 以停用它們，覆蓋任何伺服器端推出。啟用時，Claude 可以要求 `fork` subagent 類型以生成分叉，一個繼承完整對話上下文而不是從頭開始的 subagent。沒有 subagent 類型的生成仍使用通用 subagent，所有 subagent 生成都在背景中執行。明確的 [`/fork`](/docs/zh-TW/commands) 命令無需此變數即可工作。在互動式模式和透過 SDK 或 `claude -p` 中工作 |294| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | 設定為 `1` 以在您的終端支援但未自動偵測時強制 `~~text~~` 的刪除線呈現，例如透過 SSH 而不轉發 `TERM_PROGRAM`。沒有此選項，未偵測的終端會顯示文字 `~~` 標記，而不是呈現為刪除線。需要 Claude Code v2.1.186 或更新版本 |

235| `CLAUDE_CODE_GIT_BASH_PATH` | 僅限 Windows：Git Bash 可執行檔（`bash.exe`）的路徑。在 Git Bash 已安裝但不在您的 PATH 中時使用。請參閱 [Windows setup](/docs/zh-TW/setup#set-up-on-windows) |295| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 設定為 `1` 以在您的終端支援但未自動偵測時強制啟用 DEC 私人模式 2026 [同步輸出](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)。對於實現 BSU/ESU 但不回覆功能探測的模擬器（例如 Emacs `eat`）很有用。在 tmux 下無效。與 [全螢幕呈現](/docs/zh-TW/fullscreen) 的 `CLAUDE_CODE_NO_FLICKER` 不同，這不會變更呈現器 |

236| `CLAUDE_CODE_GLOB_HIDDEN` | 設定為 `false` 以在 Claude 呼叫 [Glob tool](/docs/zh-TW/tools-reference#glob-tool-behavior) 時從結果中排除隱藏檔案。預設包含。不影響 `@` 檔案自動完成、`ls`、Grep 或 Read |296| `CLAUDE_CODE_FORK_SUBAGENT` | 控制 [fork 模式](/docs/zh-TW/sub-agents#turn-fork-mode-on-or-off)，它讓 Claude 產生 [forked 子代理](/docs/zh-TW/sub-agents#fork-the-current-conversation) 本身，在互動工作階段中預設開啟。設定為 `1` 以在 `claude -p` 和 Agent SDK 中也開啟它，或 `0` 以在每種工作階段中關閉它。無論 fork 模式是否開啟，您都可以執行 `/subtask`。互動預設需要 Claude Code v2.1.232 或更新版本；在較早的版本上，設定變數為 `1` 以開啟 fork 模式 |

237| `CLAUDE_CODE_GLOB_NO_IGNORE` | 設定為 `false` 以使 [Glob tool](/docs/zh-TW/tools-reference#glob-tool-behavior) 尊重 `.gitignore` 模式。預設情況下，Glob 返回所有符合的檔案，包括 gitignored 的檔案。不影響 `@` 檔案自動完成，其具有自己的 [`respectGitignore` 設定](/docs/zh-TW/settings#available-settings) |297| `CLAUDE_CODE_FORWARD_SUBAGENT_TEXT` | 設定為 `1` 以在 `claude -p --output-format stream-json` 輸出中發出 [子代理](/docs/zh-TW/sub-agents) 文字和思考區塊，與 [`--forward-subagent-text`](/docs/zh-TW/cli-reference#cli-flags) 旗標相同的行為。當工具無法自己傳遞旗標時，在工具無法自己傳遞旗標時使用變數。與旗標不同，旗標在非互動模式下使用 stream-json 輸出時以錯誤退出，變數在那裡被忽略，因此當它在程序範圍內設定時嵌套呼叫保持工作。需要 Claude Code v2.1.211 或更新版本 |

238| `CLAUDE_CODE_GLOB_TIMEOUT_SECONDS` | Glob 工具檔案探索的逾時（以秒為單位）。在大多數平台上預設為 20 秒，在 WSL 上預設為 60 秒 |298| `CLAUDE_CODE_GIT_BASH_PATH` | 僅限 Windows：Git Bash 可執行檔 (`bash.exe`) 的路徑。在安裝了 Git Bash 但不在您的 PATH 中時使用。如果路徑不存在或檔案未命名為 `bash.exe`、`sh.exe`、`bash` 或 `sh`，Claude Code 會忽略變數並自動偵測 Git Bash，如同未設定一樣，記錄可見的警告 `--debug`。在 v2.1.219 之前，當路徑不存在時 Claude Code 在啟動時退出，並使用任何現有檔案作為 shell，而不檢查它是否為 bash 或 sh。請參閱 [Windows 設定](/docs/zh-TW/setup#set-up-on-windows) |

240| `CLAUDE_CODE_IDE_HOST_OVERRIDE` | 覆蓋用於連線至 IDE 擴充功能的主機位址。預設情況下，Claude Code 會自動偵測正確的位址，包括 WSL 到 Windows 路由 |300| `CLAUDE_CODE_GLOB_NO_IGNORE` | 設定為 `false` 以使 [Glob 工具](/docs/zh-TW/tools-reference#glob-tool-behavior) 尊重 `.gitignore` 模式。預設情況下，Glob 返回所有匹配的檔案，包括 gitignored 的檔案。不影響 `@` 檔案自動完成，它有自己的 [`respectGitignore` 設定](/docs/zh-TW/settings-reference#respectgitignore) |

242| `CLAUDE_CODE_IDE_SKIP_VALID_CHECK` | 設定為 `1` 以跳過連線期間 IDE 鎖定檔案項目的驗證。當自動連線無法找到您的 IDE（儘管它正在執行）時使用 |302| `CLAUDE_CODE_GOAL_CHECKIN_MINUTES` | 背景工作可以讓活躍目標等待多少分鐘，然後 Claude Code [要求 Claude 檢查它](/docs/zh-TW/goal#background-work-defers-evaluation)。預設 `30`。設定 `0` 以關閉檢查。給出純數字的整分鐘，最多 `10080`，即一週。Claude Code 將任何其他值視為未設定並使用預設值。需要 Claude Code v2.1.234 或更新版本 |

243| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | 覆蓋 Claude Code 假設用於作用中模型的上下文視窗大小。{{/* min-version: 2.1.193 */}}自 v2.1.193 起，直接應用於 Claude Code 不識別為 Claude 模型的模型名稱；對於識別的 Claude 模型，僅當同時設定 `DISABLE_COMPACT` 時才生效。當透過 `ANTHROPIC_BASE_URL` 路由到模型時使用，其上下文視窗與其名稱的內建大小不符 |303| `CLAUDE_CODE_HIDE_CWD` | 設定為 `1` 以在啟動徽標中隱藏工作目錄。對於螢幕共享或錄製很有用，其中路徑會公開您的 OS 使用者名稱 |

244| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 設定大多數請求的最大輸出 token 數。預設值和上限因模型而異；請參閱 [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)。增加此值會減少在 [auto-compaction](/docs/zh-TW/costs#reduce-token-usage) 觸發之前可用的有效上下文視窗 |304| `CLAUDE_CODE_IDE_HOST_OVERRIDE` | 覆蓋用於連線到 IDE 擴充功能的主機位址。預設情況下 Claude Code 自動偵測正確的位址，包括 WSL 到 Windows 路由 |

245| `CLAUDE_CODE_MAX_RETRIES` | 覆蓋重試失敗 API 請求的次數（預設值：10）。{{/* min-version: 2.1.186 */}}自 v2.1.186 起上限為 15；{{/* min-version: 2.1.199 */}}自 v2.1.199 起，`CLAUDE_CODE_RETRY_WATCHDOG` 會提高預設值並移除上限。對於需要等待較長中斷的無人值守工作階段，請改為設定 `CLAUDE_CODE_RETRY_WATCHDOG` |305| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | 設定為 `1` 以跳過 IDE 擴充功能的自動安裝。等同於將 [`autoInstallIdeExtension`](/docs/zh-TW/settings-reference#autoinstallideextension) 設定為 `false` |

247| `CLAUDE_CODE_MAX_TURNS` | 當未傳遞明確限制時，限制代理回合的數量。相當於傳遞 [`--max-turns`](/docs/zh-TW/cli-reference#cli-flags)，當兩者都設定時優先。不是正整數的值在啟動時會被拒絕並出現錯誤，而不是被視為無限制 |307| `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` | 在一個工作階段中可以執行多少個 [子代理](/docs/zh-TW/sub-agents#concurrent-subagent-limit)，然後 Agent 工具拒絕產生另一個（預設值：20）。接受純數字的正整數；其他任何東西都被忽略，因此變數可以調整上限但不能停用它。需要 Claude Code v2.1.217 或更新版本 |

248| `CLAUDE_CODE_MCP_ALLOWLIST_ENV` | 設定為 `1` 以使用僅安全基線環境加上伺服器配置的 `env` 而不是繼承您的 shell 環境來生成 stdio MCP 伺服器 |308| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | 覆蓋 Claude Code 為活躍模型假設的上下文視窗大小。從 v2.1.193 開始，它如何應用取決於 Claude Code 如何解析模型 ID；請參閱 [為閘道或自訂模型 ID 更正視窗](/docs/zh-TW/model-config#correct-the-window-for-a-gateway-or-custom-model-id)。在透過 `ANTHROPIC_BASE_URL` 路由到其上下文視窗與其名稱的內建大小不符的模型時使用此選項 |

249| `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` | {{/* min-version: 2.1.187 */}}MCP 工具呼叫的閒置逾時（以毫秒為單位）。當 stdio、HTTP、SSE、WebSocket 或 [claude.ai connector](/docs/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 伺服器不受閒置逾時限制 |309| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 為大多數請求設定最大輸出權杖數。預設值和上限因模型而異；請參閱 [最大輸出權杖](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)。Claude Code 為它不識別的模型 ID（例如閘道特定的名稱）預設為 32000，並將高於模型上限的值降低到上限。增加此值會減少 [自動壓縮](/docs/zh-TW/costs#reduce-token-usage) 觸發前可用的有效上下文視窗 |

250| `CLAUDE_CODE_NATIVE_CURSOR` | 設定為 `1` 以在輸入插入符號處顯示終端自己的游標，而不是繪製的區塊。游標尊重終端的閃爍、形狀和焦點設定 |310| `CLAUDE_CODE_MAX_RETRIES` | 覆蓋重試失敗 API 請求的次數（預設值：10）。從 v2.1.186 開始上限為 15；從 v2.1.199 開始，`CLAUDE_CODE_RETRY_WATCHDOG` 提高預設值並移除上限。對於需要等待更長中斷的無人值守工作階段，改為設定 `CLAUDE_CODE_RETRY_WATCHDOG` |

251| `CLAUDE_CODE_NEW_INIT` | 設定為 `1` 以使 `/init` 執行互動式設定流程。流程會詢問要產生哪些檔案，包括 CLAUDE.md、skills 和 hooks，然後再探索程式碼庫並寫入它們。沒有此變數，`/init` 會自動產生 CLAUDE.md 而不提示 |311| `CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION` | 在 v2.1.224 中移除，現在是無操作。先前上限了 Claude 可以在一個工作階段中使用 Agent 工具產生的 [子代理](/docs/zh-TW/sub-agents) 總數（預設值：200）；超過上限產生失敗，並出現 `Subagent spawn limit reached`。[並行子代理限制](/docs/zh-TW/sub-agents#concurrent-subagent-limit) 和 [深度限制](/docs/zh-TW/sub-agents#let-subagents-spawn-their-own-subagents) 仍適用 |

252| `CLAUDE_CODE_NO_FLICKER` | 設定為 `1` 以啟用 [fullscreen rendering](/docs/zh-TW/fullscreen)，一項研究預覽，可減少閃爍並在長對話中保持記憶體平坦。相當於 [`tui`](/docs/zh-TW/settings#available-settings) 設定；您也可以使用 `/tui fullscreen` 切換 |312| `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` | 主要對話下方允許的 [子代理層](/docs/zh-TW/sub-agents#let-subagents-spawn-their-own-subagents) 數（預設值：3）。在預設值，子代理可以產生自己的子代理，第三層的子代理無法進一步產生；設定 `1` 以關閉嵌套。在 v2.1.217 到 v2.1.218 中，預設值為 1，因此子代理無法產生自己的，除非您提高限制；v2.1.219 將預設值提高到 3。接受純數字的正整數；其他任何東西都被忽略，因此限制可以調整但不能移除。需要 Claude Code v2.1.217 或更新版本 |

254| `CLAUDE_CODE_OAUTH_SCOPES` | 重新整理權杖發出時所使用的空格分隔 OAuth 範圍，例如 `"user:profile user:inference user:sessions:claude_code"`。設定 `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` 時為必需 |314| `CLAUDE_CODE_MAX_TURNS` | 當沒有傳遞明確限制時，上限代理轉向數。等同於傳遞 [`--max-turns`](/docs/zh-TW/cli-reference#cli-flags)，當兩者都設定時優先。不是正整數的值在啟動時被拒絕，並出現錯誤，而不是視為無上限 |

255| `CLAUDE_CODE_OAUTH_TOKEN` | Claude.ai 驗證的 OAuth 存取權杖。`/login` 對於 SDK 和自動化環境的替代方案。優先於鑰匙圈儲存的認證。使用 [`claude setup-token`](/docs/zh-TW/authentication#generate-a-long-lived-token) 產生一個 |315| `CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION` | 一個工作階段可以進行的 [WebSearch](/docs/zh-TW/tools-reference#websearch-tool-behavior) 呼叫總數的上限（預設值：200）。當 Claude 達到上限時，進一步的 WebSearch 呼叫返回通知，告訴它繼續使用已經收集的資訊。接受沒有上限的正整數。其他任何東西都被忽略，預設值適用，因此上限可以提高但不能關閉。需要 Claude Code v2.1.212 或更新版本 |

256| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | {{/* max-version: 2.1.159 */}}在 v2.1.160 中移除，現在是無操作。先前將 [fast mode](/docs/zh-TW/fast-mode) 固定到 Claude Opus 4.6，而不是目前的預設值。Opus 4.6 不再支援快速模式 |316| `CLAUDE_CODE_MCP_ALLOWLIST_ENV` | 設定為 `1` 以使用僅安全基線環境加上伺服器配置的 `env` 產生 stdio MCP 伺服器，而不是繼承您的 shell 環境 |

257| `CLAUDE_CODE_OTEL_DIAG_STDERR` | {{/* min-version: 2.1.179 */}}設定為 `1` 以將 OpenTelemetry 匯出器診斷錯誤寫入 stderr。預設情況下，這些錯誤僅在 `--debug` 時出現，因此配置不當的匯出器（例如 Prometheus 連接埠衝突）會以其他方式無聲失敗。需要 Claude Code v2.1.179 或更新版本。請參閱 [Monitoring](/docs/zh-TW/monitoring-usage) |317| `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` | 仍在執行的 MCP 工具呼叫 [移至背景工作](/docs/zh-TW/mcp#automatic-backgrounding-of-long-tool-calls) 前的經過時間（毫秒）（預設值：120000，或 2 分鐘）。設定為 `0` 以關閉自動背景化。需要 Claude Code v2.1.212 或更新版本 |

258| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | 刷新待處理 OpenTelemetry spans 的逾時（以毫秒為單位）（預設值：5000）。請參閱 [Monitoring](/docs/zh-TW/monitoring-usage) |318| `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` | MCP 工具呼叫的閒置逾時（毫秒）。當 stdio、HTTP、SSE、WebSocket 或 [claude.ai 連接器](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai) MCP 伺服器在此長時間內沒有傳送回應和沒有進度通知時，工具呼叫會中止，並出現錯誤，而不是等待整體 `MCP_TOOL_TIMEOUT`。覆蓋網路伺服器的 300000（5 分鐘）和 stdio 伺服器的 1800000（30 分鐘）的每個傳輸預設值。設定為 `0` 以停用閒置檢查。低於 1000 的值提高到一秒，值上限為有效 `MCP_TOOL_TIMEOUT`。`.mcp.json` 中至少 1000 的每個伺服器 `timeout` 將該伺服器的閒置視窗提高到至少 `timeout` 值。不適用於 IDE 伺服器或 SDK 進程內伺服器。需要 Claude Code v2.1.187 或更新版本。在 v2.1.203 之前，stdio 伺服器免除閒置逾時 |

259| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 刷新動態 OpenTelemetry 標頭的間隔（以毫秒為單位）（預設值：1740000 / 29 分鐘）。請參閱 [Dynamic headers](/docs/zh-TW/monitoring-usage#dynamic-headers) |319| `CLAUDE_CODE_MESSAGING_SOCKET` | 由 Claude Code 設定，不由您設定：在繫結 [收件箱套接字](/docs/zh-TW/cross-session-messaging#the-sessions-inbox-socket) 的工作階段中，Claude Code 在繫結套接字時將該套接字的路徑匯出到 hooks 和 Bash 命令。在以啟用訊息開始的工作階段中，Claude Code 在任何 hook 執行之前繫結套接字。機器上的其他工作階段將訊息傳遞到此路徑。每個工作階段匯出自己的套接字，而不是從父工作階段繼承的套接字，到達它的訊息會透過工作階段的 [入站控制](/docs/zh-TW/cross-session-messaging#control-inbound-messages) 進行。設定 `env` 區塊無法設定它。需要 Claude Code v2.1.224 或更新版本 |

260| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | OpenTelemetry 匯出器在關閉時完成的逾時（以毫秒為單位）（預設值：2000）。如果指標在退出時被丟棄，請增加此值。請參閱 [Monitoring](/docs/zh-TW/monitoring-usage) |320| `CLAUDE_CODE_MESSAGING_TOKEN` | 由 Claude Code 設定，不由您設定：在繫結 [收件箱套接字](/docs/zh-TW/cross-session-messaging#the-sessions-inbox-socket) 的工作階段中，Claude Code 將此每個工作階段權杖匯出到 hooks 和 Bash 命令，與 `CLAUDE_CODE_MESSAGING_SOCKET` 一起。發佈到套接字的指令碼可以傳送 `{"type":"auth","token":"<token>"}` 作為其第一行以證明它屬於工作階段。在原生 Windows 上，Claude Code 需要此行並關閉任何不以有效行開啟的連線。[自有子規則](/docs/zh-TW/cross-session-messaging#the-sessions-inbox-socket) 說明何時 Claude Code 查詢權杖。每個工作階段匯出自己的權杖，絕不是從父工作階段繼承的權杖。設定 `env` 區塊無法設定它。需要 Claude Code v2.1.228 或更新版本 |

261| `CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE` | 設定為 `1` 以讓 Claude Code 在新版本可用時在背景中執行您的套件管理員的升級命令。適用於 Homebrew 和 WinGet 安裝。其他套件管理員繼續顯示升級命令而不執行它。請參閱 [Auto updates](/docs/zh-TW/setup#auto-updates) |321| `CLAUDE_CODE_NATIVE_CURSOR` | 設定為 `1` 以在輸入插入符處顯示終端自己的游標，而不是繪製的區塊。游標尊重終端的閃爍、形狀和焦點設定 |

262| `CLAUDE_CODE_PERFORCE_MODE` | 設定為 `1` 以啟用 Perforce 感知寫入保護。設定時，如果目標檔案缺少擁有者寫入位元（Perforce 在同步的檔案上清除，直到 `p4 edit` 開啟它們），Edit、Write 和 NotebookEdit 會失敗並提示 `p4 edit <file>`。這可防止 Claude Code 繞過 Perforce 變更追蹤 |322| `CLAUDE_CODE_NEW_INIT` | 設定為 `1` 以使 `/init` 執行互動設定流程。流程在探索程式碼庫並寫入它們之前詢問要產生哪些檔案，包括 CLAUDE.md、skills 和 hooks。沒有此變數，`/init` 會自動產生 CLAUDE.md，而不提示 |

263| `CLAUDE_CODE_PLUGIN_CACHE_DIR` | 覆蓋外掛程式根目錄。儘管名稱如此，這會設定父目錄，而不是快取本身：市場和外掛程式快取位於此路徑下的子目錄中。預設為 `~/.claude/plugins` |323| `CLAUDE_CODE_NONBLOCKING_STDOUT` | 設定為 `1` 以透過第二個非阻塞檔案描述符寫入終端輸出，因此停止讀取的終端（例如暫停的 tmux 控制模式窗格或停滯的 SSH 連線）無法在工作階段中途凍結 Claude Code。在 macOS、Linux 和 WSL 上應用，當 stdout 是終端時。需要 Claude Code v2.1.261 或更新版本 |

264| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 安裝或更新外掛程式時 git 操作的逾時（以毫秒為單位）（預設值：120000）。對於大型儲存庫或網路連線緩慢，請增加此值。請參閱 [Git operations time out](/docs/zh-TW/plugin-marketplaces#git-operations-time-out) |324| `CLAUDE_CODE_NO_FLICKER` | 設定為 `1` 以啟用 [全螢幕呈現](/docs/zh-TW/fullscreen)，一項減少閃爍並在長對話中保持記憶體平坦的研究預覽。覆蓋 [`tui`](/docs/zh-TW/settings-reference#tui) 設定；您也可以使用 `/tui fullscreen` 切換 |

265| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 設定為 `1` 以在 `git pull` 失敗時保留現有的市場快取，而不是擦除並重新複製。在離線或隔離環境中很有用，其中重新複製會以相同方式失敗。請參閱 [Marketplace updates fail in offline environments](/docs/zh-TW/plugin-marketplaces#marketplace-updates-fail-in-offline-environments) |325| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | Claude.ai 驗證的 OAuth 重新整理權杖。設定時，`claude auth login` 直接交換此權杖，而不是開啟瀏覽器。需要 `CLAUDE_CODE_OAUTH_SCOPES`。對於在自動化環境中佈建驗證很有用 |

266| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | 設定為 `1` 以透過 HTTPS 而不是 SSH 複製 GitHub `owner/repo` 外掛程式來源。在 CI 執行器、容器或任何沒有為 `github.com` 配置 SSH 金鑰的環境中很有用 |326| `CLAUDE_CODE_OAUTH_SCOPES` | 重新整理權杖發出時使用的空格分隔 OAuth 範圍，例如 `"user:profile user:inference user:sessions:claude_code"`。設定 `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` 時為必需 |

267| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 一個或多個唯讀外掛程式種子目錄的路徑，在 Unix 上以 `:` 分隔，在 Windows 上以 `;` 分隔。使用此選項可將預先填充的外掛程式目錄捆綁到容器映像中。Claude Code 在啟動時從這些目錄註冊市場，並使用預先快取的外掛程式而無需重新複製。請參閱 [Pre-populate plugins for containers](/docs/zh-TW/plugin-marketplaces#pre-populate-plugins-for-containers) |327| `CLAUDE_CODE_OAUTH_TOKEN` | claude.ai 驗證的 OAuth 存取權杖。`/login` 對 SDK 和自動化環境的替代方案。優先於鑰匙圈儲存的認證。使用 [`claude setup-token`](/docs/zh-TW/authentication#generate-a-long-lived-token) 產生一個。除非您執行 [`/login`](/docs/zh-TW/authentication#authentication-precedence)，否則 Claude Code 會為整個工作階段使用您設定的權杖。若要取代過期的權杖，產生新的並重新啟動 |

268| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | 設定為 `1` 以停止 Claude Code 在生成 PowerShell 以進行工具呼叫、hooks 和狀態行命令時傳遞 `-ExecutionPolicy Bypass`，並改為尊重機器的有效執行政策。預設情況下，Claude Code 在程序範圍內繞過執行政策，以便 `.ps1` 指令碼和模組匯入在預設受限的 Windows 安裝上工作。無論此設定如何，程序範圍繞過永遠不會覆蓋群組原則 `MachinePolicy` 或 `UserPolicy` |328| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | 在 v2.1.160 中移除，現在是無操作。先前將 [快速模式](/docs/zh-TW/fast-mode) 釘選到 Claude Opus 4.6，而不是目前的預設值。Opus 4.6 不再支援快速模式 |

269| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | {{/* min-version: 2.1.182 */}}[非互動式模式](/docs/zh-TW/headless#background-tasks-at-exit)使用 `-p` 旗標在最終回合後等待的最大時間（以毫秒為單位），用於背景 subagents 和工作流程，其結果是輸出的一部分。預設值：`600000`，或 10 分鐘。超過上限時，剩餘背景任務會被終止，程序會退出。設定為 `0` 以無限期等待。此上限與適用於純背景 shells 的 5 秒寬限期分開 |329| `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` | 內容承載 OpenTelemetry 屬性（模型回應、工具內容、系統提示、原始 API 主體）的最大長度，截斷標記包括在內，以 UTF-16 程式碼單位為單位（預設值：61440，即 60 KB）。僅當您的遙測後端接受大於 64 KB 的屬性值時才提高它，或降低它以減少遙測量。需要 Claude Code v2.1.214 或更新版本。請參閱 [監控](/docs/zh-TW/monitoring-usage) |

270| `CLAUDE_CODE_PROCESS_WRAPPER` | 透過包裝器可執行檔啟動 Claude Code 從其自己的二進位檔啟動的程序，指定為 argv 前綴，例如 `/opt/corp/launcher`。涵蓋託管 [agent view](/docs/zh-TW/agent-view) 工作階段的背景服務、它生成的每個工作階段以及 Claude Code 執行自身以完成安裝更新的重新啟動。第一個權杖必須是以 `exec "$@"` 結尾的可執行檔的絕對路徑，大多數啟動器都是該單一路徑。該值是引數清單，而不是 shell 命令：空格分隔權杖，雙引號將包含空格的路徑分組，以 `[` 開頭的值會讀取為 JSON 字串陣列。在使用者或 [managed settings](/docs/zh-TW/permissions#managed-settings) 的 `env` 區塊中設定它，而不是作為 shell 匯出，以便分離的背景服務繼承它；專案和本機設定無法設定它。VS Code 擴充功能透過其 `claudeProcessWrapper` 設定單獨配置其自己的啟動器。在 Windows 上被忽略。`CLAUDE_CODE_SHELL_PREFIX` 是一個單獨的控制：它將 Claude Code 執行的 shell 命令包裝為單個引用的字串，而此變數將 Claude Code 自己的程序包裝為 argv 前綴。請參閱 [Run Claude Code behind a corporate launcher](/docs/zh-TW/corporate-launcher) |330| `CLAUDE_CODE_OTEL_DIAG_STDERR` | 設定為 `1` 以將 OpenTelemetry 匯出器診斷錯誤寫入 stderr。預設情況下，這些錯誤僅在 `--debug` 時出現，因此配置不當的匯出器（例如 Prometheus 埠衝突）否則會無聲地失敗。需要 Claude Code v2.1.179 或更新版本。請參閱 [監控](/docs/zh-TW/monitoring-usage) |

271| `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)](/docs/zh-TW/monitoring-usage#traces-beta) |331| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | 刷新待處理 OpenTelemetry 跨度的逾時（毫秒）（預設值：5000）。請參閱 [監控](/docs/zh-TW/monitoring-usage) |

272| `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](/docs/zh-TW/data-usage#default-behaviors-by-api-provider) |332| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 刷新動態 OpenTelemetry 標頭的間隔（毫秒）（預設值：1740000 / 29 分鐘）。請參閱 [動態標頭](/docs/zh-TW/monitoring-usage#dynamic-headers) |

274| `CLAUDE_CODE_REMOTE` | 當 Claude Code 作為 [cloud session](/docs/zh-TW/claude-code-on-the-web) 執行時自動設定為 `true`。從 hook 或設定指令碼讀取此項以偵測您是否在雲端環境中 |334| `CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE` | 設定為 `1` 以讓 Claude Code 在新版本可用時在背景執行您的套件管理器的升級命令。適用於 Homebrew 和 WinGet 安裝。其他套件管理器繼續顯示升級命令而不執行它。請參閱 [自動更新](/docs/zh-TW/setup#auto-updates) |

275| `CLAUDE_CODE_REMOTE_SESSION_ID` | 在 [cloud sessions](/docs/zh-TW/claude-code-on-the-web) 中自動設定為目前工作階段的 ID。讀取此項以構造回到工作階段文字記錄的連結。請參閱 [Link output back to the session](/docs/zh-TW/claude-code-on-the-web#link-output-back-to-the-session) |335| `CLAUDE_CODE_PERFORCE_MODE` | 設定為 `1` 以啟用 Perforce 感知寫入保護。設定時，如果目標檔案缺少所有者寫入位元，Edit、Write 和 NotebookEdit 會失敗，並出現 `p4 edit <file>` 提示，Perforce 在同步的檔案上清除該位元，直到 `p4 edit` 開啟它們。這可防止 Claude Code 繞過 Perforce 變更追蹤 |

277| `CLAUDE_CODE_RESUME_PROMPT` | 覆蓋在繼續在中途結束的工作階段時注入的延續訊息。預設為 `Continue from where you left off.`。長時間執行的代理的生成指令碼可以將此設定為更具指令性的啟動訊息。空字串使用預設值 |337| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 安裝或更新外掛程式時 git 操作的逾時（毫秒）（預設值：120000）。對於大型儲存庫或慢速網路連線，增加此值。請參閱 [Git 操作逾時](/docs/zh-TW/plugin-marketplaces#git-operations-time-out) |

278| `CLAUDE_CODE_RETRY_WATCHDOG` | {{/* min-version: 2.1.186 */}}設定為 `1` 用於無人值守工作階段，例如評估工具、CI 工作或遠端工作者。無限期重試 `429` 和 `529` 容量錯誤，而不是在 `CLAUDE_CODE_MAX_RETRIES` 嘗試後失敗。監視程式在嘗試之間退避最多 5 分鐘，或直到限制在回應帶有速率限制重設時間時重設，因此達到使用限制的工作階段會等待剩餘視窗。{{/* min-version: 2.1.199 */}}自 v2.1.199 起，它也會提高其他暫時性錯誤（例如伺服器錯誤、逾時和丟棄的連線）的預設重試計數至 300，大約三小時的退避，並在您明確設定該變數時移除 `CLAUDE_CODE_MAX_RETRIES` 的上限 15。需要 Claude Code v2.1.186 或更新版本 |338| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 設定為 `1` 以在 `git pull` 失敗時跳過重新複製嘗試並繼續使用現有市場快取。在離線或隔離環境中很有用，其中重新複製會以相同方式失敗。請參閱 [市場更新在離線環境中失敗](/docs/zh-TW/plugin-marketplaces#marketplace-updates-fail-in-offline-environments) |

279| `CLAUDE_CODE_SAFE_MODE` | 設定為 `1` 以在安全模式下啟動：CLAUDE.md、skills、plugins、hooks、MCP 伺服器、自訂命令和代理、輸出樣式、工作流程、自訂主題、自訂快捷鍵、狀態行和檔案建議命令、LSP 伺服器和自動記憶體不載入，用於對損壞的配置進行故障排除。受管設定政策仍然適用，包括政策配置的 hooks、狀態行和檔案建議命令；受管外掛程式、受管 skills、受管 CLAUDE.md 和政策配置的 MCP 伺服器不適用。相當於傳遞 [`--safe-mode`](/docs/zh-TW/cli-reference#cli-flags)。直接生成的子程序繼承該變數 |339| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | 設定為 `1` 以透過 HTTPS 而不是 SSH 複製 GitHub `owner/repo` 速記來源。適用於外掛程式安裝和更新，以及 `/plugin marketplace add` 和 `update`。在 CI 執行器、容器或任何沒有為 `github.com` 配置 SSH 金鑰的環境中很有用 |

280| `CLAUDE_CODE_SCRIPT_CAPS` | JSON 物件，當設定 `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` 時限制特定指令碼在每個工作階段中可被呼叫的次數。鍵是針對命令文字進行比對的子字串；值是整數呼叫限制。例如，`{"deploy.sh": 2}` 允許 `deploy.sh` 最多被呼叫兩次。比對是基於子字串的，因此 shell 擴展技巧（如 `./scripts/deploy.sh $(evil)`）仍然計入上限。透過 `xargs` 或 `find -exec` 的執行時扇出未被偵測；這是深度防禦控制 |340| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 一個或多個唯讀外掛程式種子目錄的路徑，在 Unix 上以 `:` 分隔，在 Windows 上以 `;` 分隔。使用此選項將預先填充的外掛程式目錄捆綁到容器映像中。Claude Code 在啟動時從這些目錄註冊市場，並使用預先快取的外掛程式而不重新複製。請參閱 [為容器預先填充外掛程式](/docs/zh-TW/plugin-marketplaces#pre-populate-plugins-for-containers) |

281| `CLAUDE_CODE_SCROLL_SPEED` | 在 [fullscreen rendering](/docs/zh-TW/fullscreen#mouse-wheel-scrolling) 中設定滑鼠滾輪捲動乘數。接受 1 到 20 的值，以及低於 1 的分數值（例如 `0.5`）以減慢終端上原生捲動路徑中加速的觸控板和滾輪捲動。設定為 `3` 以符合 `vim`（如果您的終端在沒有放大的情況下每個刻度發送一個滾輪事件）。在 JetBrains IDE 終端中被忽略，Claude Code 使用其自己的捲動處理 |341| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | 設定為 `1` 以停止 Claude Code 在為工具呼叫、hooks 和狀態列命令產生 PowerShell 時傳遞 `-ExecutionPolicy Bypass`，並改為尊重機器的有效執行政策。預設情況下 Claude Code 在程序範圍內繞過執行政策，因此 `.ps1` 指令碼和模組匯入在預設限制的 Windows 安裝上工作。程序範圍繞過無論此設定如何都不會覆蓋 Group Policy `MachinePolicy` 或 `UserPolicy` |

282| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | 覆蓋 [SessionEnd](/docs/zh-TW/hooks#sessionend) hooks 的時間預算（以毫秒為單位）。適用於工作階段退出、`/clear` 和透過互動式 `/resume` 切換工作階段。預設情況下，預算為 1.5 秒，自動提高到設定檔案中配置的最高每個 hook `timeout`，最高 60 秒。外掛程式提供的 hooks 上的逾時不會提高預算 |342| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | 在 [非互動模式](/docs/zh-TW/headless#background-tasks-at-exit) 中使用 `-p` 旗標後最終轉向後等待背景子代理和工作流程的閒置等待上限（毫秒）。每次 Claude 採取轉向來處理背景結果時，閒置等待重新開始。預設：`600000`，或 10 分鐘。當閒置等待達到上限時，Claude Code 停止等待剩餘的背景工作並退出。設定為 `0` 以無限期等待。此上限與適用於純背景 shells 的五秒寬限期分開。需要 Claude Code v2.1.182 或更新版本 |

283| `CLAUDE_CODE_SESSION_ID` | 在 Bash 和 PowerShell 工具子程序、[hook command](/docs/zh-TW/hooks) 子程序和 stdio [MCP server](/docs/zh-TW/mcp) 子程序中自動設定為目前工作階段 ID。對於 Bash、PowerShell 和 hooks，這符合傳遞給 hook JSON 輸入的 `session_id` 欄位，並在 `/clear` 時更新。MCP 伺服器子程序保留它生成時的 ID。在 `--resume <session-id>` 上，它接收繼續的 ID，符合 hooks 和 Bash。在 `--continue` 或 `--resume` 沒有明確 ID 時，它可能接收初始啟動 ID。用於將指令碼和外部工具與啟動它們的 Claude Code 工作階段相關聯 |343| `CLAUDE_CODE_PROCESS_WRAPPER` | 透過公司啟動器啟動 Claude Code 從其自己的二進位檔啟動的程序，例如主機 [代理檢視](/docs/zh-TW/agent-view) 工作階段的背景服務，作為 `/opt/corp/launcher` 等 argv 前綴。在使用者或 [受管設定](/docs/zh-TW/managed-settings) 的 `env` 區塊中設定它，而不是作為 shell 匯出，因此分離的背景服務繼承它；專案和本機設定無法設定它。等同於 [`processWrapper` 設定](/docs/zh-TW/settings-reference#processwrapper)，需要 Claude Code v2.1.210 或更新版本；當兩者都設定時此變數優先。VS Code 擴充功能透過其 `claudeProcessWrapper` 設定單獨配置自己的啟動器。在 Windows 上忽略。請參閱 [在公司啟動器後執行 Claude Code](/docs/zh-TW/corporate-launcher) 以了解值格式、啟動器涵蓋的內容以及啟動器必須滿足的合約。需要 Claude Code v2.1.208 或更新版本 |

284| `CLAUDE_CODE_SHELL` | 設定 Claude Code 用來執行 Bash 工具命令的 shell。接受 `bash` 或 `zsh` 二進位檔的路徑，例如 `/opt/homebrew/bin/bash`。不支援 `fish` 等其他 shells。如果該值不是有效的 `bash` 或 `zsh` 路徑，Claude Code 會忽略它並回退到自動偵測。自動偵測在您的 `$SHELL` 指向 `bash` 或 `zsh` 時使用它，否則它會在您的 `PATH` 和標準安裝位置上選擇第一個有效的 `zsh` 然後 `bash` |344| `CLAUDE_CODE_PROJECT_DIR_NAME` | 與 `CLAUDE_CONFIG_DIR` 一起設定，以選擇 Claude Code 在其中儲存該工作階段的文字記錄和自動記憶的 `projects/` 目錄名稱，代替從工作目錄路徑衍生的名稱。例如，使用 `CLAUDE_CONFIG_DIR=/srv/tenant-a CLAUDE_CODE_PROJECT_DIR_NAME=work claude` 啟動 Claude Code 會將它們儲存在 `/srv/tenant-a/projects/work/` 下。當 `CLAUDE_CONFIG_DIR` 未設定時，Claude Code 會忽略此變數，並僅從您啟動 `claude` 的環境讀取它，絕不從 [設定檔 `env` 區塊](#in-settings-files)。請參閱 [自己命名專案目錄](/docs/zh-TW/sessions#name-the-project-directory-yourself)。需要 Claude Code v2.1.234 或更新版本 |

285| `CLAUDE_CODE_SHELL_PREFIX` | 命令前綴以包裝 Claude Code 生成的 shell 命令：Bash 工具呼叫、[hook](/docs/zh-TW/hooks) 命令、[status line](/docs/zh-TW/statusline) 命令和 stdio [MCP server](/docs/zh-TW/mcp) 啟動命令。PowerShell hooks 和 exec 形式的 hooks 無需前綴執行。對於日誌記錄或稽核很有用。設定裸可執行檔路徑（例如 `/path/to/logger.sh`）會將每個命令執行為 `/path/to/logger.sh '<command>'`。包裝器在 `$1` 中接收命令行作為單個 shell 引用的引數，因此包裝器必須使用 shell 重新評估 `$1`，例如 `exec bash -c "$1"`。將 `$1` 視為裸可執行檔路徑會破壞傳遞引數的 stdio MCP 伺服器，例如 `npx -y <package>`。對於 Bash 工具呼叫，`$1` 包含 Claude Code 組裝的完整 shell 呼叫，包括環境設定，而不僅僅是 Claude 執行的命令 |345| `CLAUDE_CODE_PROMPT_CACHE_TTL` | 設定 `5m` 或 `1h`，Claude Code 接受的唯一值，以選擇主要對話的 [提示快取 TTL](/docs/zh-TW/prompt-caching#cache-lifetime)：您的互動、`-p` 和 SDK 轉向，加上與它們內聯執行的幫助程式。優先於 `promptCacheTtl` 設定和 `ENABLE_PROMPT_CACHING_1H`，`FORCE_PROMPT_CACHING_5M` 覆蓋它。API 以更高的速率計費 1 小時快取寫入。需要 Claude Code v2.1.242 或更新版本 |

286| `CLAUDE_CODE_SIMPLE` | 設定為 `1` 以使用最小系統提示和僅 Bash、檔案讀取和檔案編輯工具執行。來自 `--mcp-config` 的 MCP 工具仍然可用。停用 hooks、skills、plugins、MCP 伺服器、自動記憶體和 CLAUDE.md 的自動探索。OAuth 權杖和鑰匙圈認證不會被讀取，因此 Anthropic 驗證必須來自 `ANTHROPIC_API_KEY` 或 `--settings` 中的 `apiKeyHelper`。相當於傳遞 [`--bare`](/docs/zh-TW/headless#start-faster-with-bare-mode) |346| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | 設定為 `1` 以在 `ANTHROPIC_BASE_URL` 指向自訂代理時傳播 W3C 追蹤上下文。傳播涵蓋模型和 HTTP MCP 請求上的 `traceparent` 標頭以及 Bash、PowerShell 和 hook 子程序的 `TRACEPARENT` 環境變數。預設情況下，傳播僅在直接連線到 Anthropic API 時啟用。在 v2.1.152 中新增。請參閱 [追蹤（測試版）](/docs/zh-TW/monitoring-usage#traces-beta) |

287| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 設定為 `1` 以在任何模型上使用較短的系統提示和縮寫工具描述。設定為 `0`、`false`、`no` 或 `off` 以選擇退出，即使實驗或伺服器配置會以其他方式啟用它。完整工具集、hooks、MCP 伺服器和 CLAUDE.md 探索保持啟用 |347| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | 由嵌入 Claude Code 並代表其管理模型提供者路由的主機平台設定。設定時，Claude Code 會忽略設定檔中的提供者選擇、端點和驗證變數（例如 `CLAUDE_CODE_USE_BEDROCK`、`ANTHROPIC_BASE_URL` 和 `ANTHROPIC_API_KEY`），因此使用者設定無法覆蓋主機的路由。Claude Code 也會忽略 [受管設定](/docs/zh-TW/managed-settings) 中的模型選擇金鑰（例如 `model`、`fallbackModel` 和 `modelOverrides`），無論受管來源傳遞它們，因此主機的模型設定優先於過期的受管模型釘選。Claude Code 也會忽略受管 `env` 區塊中的模型選擇變數（例如 `ANTHROPIC_MODEL` 和 `ANTHROPIC_DEFAULT_*_MODEL` 系列）；受管設定中的 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection) 允許清單仍適用，除非主機提供自己的。Claude Code 也會跳過它在第三方提供者（例如 Amazon Bedrock、AWS 上的 Claude Platform、Google Cloud 的 Agent Platform 和 Microsoft Foundry）上否則應用的自動遙測選擇退出，因此遙測遵循標準 `DISABLE_TELEMETRY` 選擇退出。請參閱 [按 API 提供者的預設行為](/docs/zh-TW/data-usage#default-behaviors-by-api-provider) |

289| `CLAUDE_CODE_SKIP_AWS_CRED_CACHE` | 設定為 `1` 以關閉 AWS 預設認證提供者鏈解析的認證進程內快取，以便 Claude Code 在每個 API 請求上解析鏈。關閉快取時，由 SSO 支援的設定檔會在每個請求時從 IAM Identity Center 要求認證。請參閱 [credential caching and resolution timeout](/docs/zh-TW/amazon-bedrock#credential-caching-and-resolution-timeout)。需要 Claude Code v2.1.207 或更新版本 |349| `CLAUDE_CODE_REMOTE` | 當 Claude Code 執行為 [雲工作階段](/docs/zh-TW/claude-code-on-the-web) 時自動設定為 `true`。從 hook 或設定指令碼讀取此項以偵測您是否在雲工作階段中 |

350| `CLAUDE_CODE_REMOTE_SESSION_ID` | 在 [雲工作階段](/docs/zh-TW/claude-code-on-the-web) 中自動設定為目前工作階段的 ID。讀取此項以構造連結回工作階段文字記錄。請參閱 [將輸出連結回工作階段](/docs/zh-TW/cloud-environments#link-output-back-to-the-session) |

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

352| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | 設定為 `1` 以在上一個工作階段在轉向中途結束時自動繼續。在 SDK 模式中使用，以便模型繼續而不需要 SDK 重新傳送提示。若要關閉此功能，取消設定變數或將其設定為 `0`。在 v2.1.221 之前，Claude Code 忽略 `0` 和其他虛假值，因此在非互動模式中設定 `0` 仍會觸發繼續，取消設定變數是關閉它的唯一方式 |

353| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN_MAX_AGE_MS` | 在轉向中途結束的工作階段自動繼續時，最後文字記錄訊息的最大年齡（毫秒）。當最後訊息比此界限更舊時，Claude Code 會跳過 `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` 自動繼續和注入的 `CLAUDE_CODE_RESUME_PROMPT` 繼續訊息，工作階段啟動閒置，因此您明確繼續。未設定或 `0` 表示無界限；負值或非數值值應用一小時界限。長時間執行的代理的產生指令碼可以設定此項，以便針對舊文字記錄的重新啟動不會重新執行過時的提示。Claude Code 在重新啟動崩潰的 [代理檢視](/docs/zh-TW/agent-view) 工作階段時自己設定一小時界限，該工作階段從互動工作階段繼承其對話。需要 Claude Code v2.1.211 或更新版本 |

354| `CLAUDE_CODE_RESUME_PROMPT` | 覆蓋在繼續在轉向中途結束的工作階段時注入的繼續訊息。預設為 `Continue from where you left off.`。長時間執行的代理的產生指令碼可以設定此項為更具指示性的啟動訊息。空字串使用預設值 |

355| `CLAUDE_CODE_RETRY_WATCHDOG` | 設定為 `1` 用於無人值守的工作階段，例如評估工具、CI 工作或遠端工作者。無限期重試 `429` 和 `529` 容量錯誤，而不是在 `CLAUDE_CODE_MAX_RETRIES` 嘗試後失敗。Claude Code 在報告支出限制或耗盡使用額度的 `429` 上立即失敗，即使來自 [閘道支出上限](/docs/zh-TW/errors#spend-limit-reached) 的按計劃重設。在 v2.1.239 之前，監視狗無限期重試這些。監視狗在嘗試之間備份最多 5 分鐘，或直到限制在回應攜帶速率限制重設時間時重設，因此達到使用限制的工作階段會等待剩餘視窗。在 v2.1.199 或更新版本上，它也為其他暫時性錯誤（例如伺服器錯誤、逾時和丟棄的連線）提高預設重試計數為 300，大約三小時的備份，如果您明確設定該變數，則移除 `CLAUDE_CODE_MAX_RETRIES` 的 15 上限。需要 Claude Code v2.1.186 或更新版本 |

356| `CLAUDE_CODE_SAFE_MODE` | 設定為 `1` 以在安全模式中啟動：CLAUDE.md、skills、外掛程式、hooks、MCP 伺服器、自訂命令和代理、輸出樣式、工作流程、自訂主題、自訂快捷鍵、狀態列和檔案建議命令、LSP 伺服器和自動記憶不載入，用於疑難排解損壞的設定。受管設定政策仍適用，包括政策配置的 hooks、狀態列和檔案建議命令；受管外掛程式、受管 skills、受管 CLAUDE.md 和政策配置的 MCP 伺服器不適用。等同於傳遞 [`--safe-mode`](/docs/zh-TW/cli-reference#cli-flags)。直接產生的子程序繼承變數 |

357| `CLAUDE_CODE_SCRIPT_CAPS` | JSON 物件限制當設定 `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` 時，特定指令碼在每個工作階段中可能被呼叫多少次。金鑰是針對命令文字匹配的子字串；值是整數呼叫限制。例如，`{"deploy.sh": 2}` 允許 `deploy.sh` 最多被呼叫兩次。匹配是基於子字串的，因此 shell 擴展技巧（如 `./scripts/deploy.sh $(evil)`）仍然計入上限。透過 `xargs` 或 `find -exec` 的執行時間扇出未被偵測；這是深度防禦控制 |

358| `CLAUDE_CODE_SCROLL_SPEED` | 在 [全螢幕呈現](/docs/zh-TW/fullscreen#mouse-wheel-scrolling) 中設定滑鼠滾輪捲軸乘數。接受任何正值最多 20，包括低於 1 的分數值（例如 `0.5`）以減慢已加速的觸控板和滾輪捲軸在已經放大滾輪事件的終端中。設定為 `3` 以符合 `vim`，如果您的終端在沒有放大的情況下每個凹槽傳送一個滾輪事件。在 JetBrains IDE 終端中忽略，Claude Code 在那裡使用自己的捲軸處理 |

359| `CLAUDE_CODE_SEND_FEEDBACK` | 設定為 `0` 以關閉工作階段的 [Claude 起草的回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior)。設定為 `1` 以在您的帳戶已有存取權的地方開啟；變數本身無法授予存取權，其他關閉回饋的開關（例如 `DISABLE_FEEDBACK_COMMAND` 和 [`feedbackDrafts`](/docs/zh-TW/settings-reference#feedbackdrafts) 設定的 `off` 值）仍適用 |

360| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | 覆蓋 [SessionEnd](/docs/zh-TW/hooks#sessionend) hooks 的時間預算（毫秒）。適用於工作階段退出、`/clear` 和透過互動 `/resume` 切換工作階段。預設情況下預算為 1.5 秒，自動提高到設定檔中配置的最高每個 hook `timeout`，最多 60 秒。外掛程式提供的 hooks 上的逾時不會提高預算 |

361| `CLAUDE_CODE_SESSION_ID` | 在 Bash 和 PowerShell 工具子程序、[hook 命令](/docs/zh-TW/hooks) 子程序和 stdio [MCP 伺服器](/docs/zh-TW/mcp) 子程序中自動設定為目前工作階段 ID。對於 Bash、PowerShell 和 hooks，這符合 hook JSON 輸入中的 `session_id` 欄位，並在 `/clear` 上更新。MCP 伺服器子程序保留它產生時的 ID。在 `--resume <session-id>` 上，它接收繼續的 ID，符合 hooks 和 Bash。在 `--continue` 或 `--resume` 沒有明確 ID 上，它可能接收初始啟動 ID。用於將指令碼和外部工具與啟動它們的 Claude Code 工作階段相關聯 |

362| `CLAUDE_CODE_SHELL` | 設定 Claude Code 用於執行 Bash 工具命令的 shell。接受 `bash` 或 `zsh` 二進位檔的路徑，例如 `/opt/homebrew/bin/bash`。不支援 `fish` 等其他 shells。如果值不是工作的 `bash` 或 `zsh` 路徑，Claude Code 會忽略它並回退到自動偵測。自動偵測在指向 `bash` 或 `zsh` 時使用您的 `$SHELL`，否則它選擇在您的 `PATH` 和標準安裝位置上找到的第一個工作的 `zsh`，然後 `bash` |

363| `CLAUDE_CODE_SHELL_PREFIX` | 包裝 Claude Code 產生的 shell 命令的命令前綴：Bash 工具呼叫、[hook](/docs/zh-TW/hooks) 命令、[狀態列](/docs/zh-TW/statusline) 命令和 stdio [MCP 伺服器](/docs/zh-TW/mcp) 啟動命令。PowerShell hooks 和 exec 形式 hooks 執行時不帶前綴。對於日誌記錄或稽核很有用。設定裸可執行檔路徑（例如 `/path/to/logger.sh`）將每個命令執行為 `/path/to/logger.sh '<command>'`。包裝器在 `$1` 中接收命令行作為單個 shell 引用的引數，因此包裝器必須使用 shell 重新評估 `$1`，例如 `exec bash -c "$1"`。將 `$1` 視為裸可執行檔路徑會破壞傳遞引數的 stdio MCP 伺服器，例如 `npx -y <package>`。對於 Bash 工具呼叫，`$1` 包含 Claude Code 組裝的完整 shell 呼叫，包括環境設定，而不僅僅是 Claude 執行的命令 |

364| `CLAUDE_CODE_SIMPLE` | 設定為 `1` 以使用最小系統提示和僅 Bash、檔案讀取和檔案編輯工具執行。來自 `--mcp-config` 的 MCP 工具仍然可用。停用 hooks、skills、自訂命令、子代理、外掛程式、MCP 伺服器、自動記憶和 CLAUDE.md 的自動發現。您使用 `--add-dir` 傳遞的目錄中的 Skills 仍然載入。OAuth 權杖和鑰匙圈認證不被讀取，因此 Anthropic 驗證必須來自 `ANTHROPIC_API_KEY` 或 `--settings` 中的 `apiKeyHelper`。等同於傳遞 [`--bare`](/docs/zh-TW/headless#start-faster-with-bare-mode) |

365| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 設定為 `1` 以在任何模型上使用較短的系統提示和縮寫工具說明。設定為 `0`、`false`、`no` 或 `off` 以選擇退出，即使實驗或伺服器設定會否則啟用它。完整工具集、hooks、MCP 伺服器和 CLAUDE.md 發現保持啟用 |

366| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | 跳過 [AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws) 的用戶端驗證，用於自己簽署請求的閘道 |

367| `CLAUDE_CODE_SKIP_AWS_CRED_CACHE` | 設定為 `1` 以關閉 AWS 預設認證提供者鏈解析的進程內快取，因此 Claude Code 在每個 API 請求上解析鏈。快取關閉後，SSO 支援的設定檔在每個請求上從 IAM Identity Center 請求認證。請參閱 [認證快取和解析逾時](/docs/zh-TW/amazon-bedrock#credential-caching-and-resolution-timeout)。需要 Claude Code v2.1.207 或更新版本 |

291| `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 金鑰 |369| `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS` | 設定為 `1` 以將失敗的 [快速模式](/docs/zh-TW/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) 可用性檢查視為可用，用於阻止檢查對 `api.anthropic.com` 的直接請求的網路。Claude Code 仍然尊重「您的組織停用了快速模式」回應 |

370| `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK` | 設定為 `1` 以跳過用戶端 [快速模式](/docs/zh-TW/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) 可用性檢查，用於攔截檢查請求而不是拒絕它的代理。API 在您的組織停用快速模式時仍會拒絕快速模式請求 |

371| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | 跳過 Microsoft Foundry 的 Azure 驗證，用於注入自己的 `Authorization` 標頭的代理或閘道。Claude Code 傳送沒有 Azure 認證的請求並保留您提供的 `Authorization` 標頭，例如透過 `ANTHROPIC_CUSTOM_HEADERS`。當設定 `ANTHROPIC_FOUNDRY_API_KEY` 或 `ANTHROPIC_FOUNDRY_AUTH_TOKEN` 時忽略。在 v2.1.203 之前，此變數使 Microsoft Foundry 用戶端無法傳送請求，除非同時設定了 API 金鑰 |

293| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 設定為 `1` 以跳過將提示歷史記錄和工作階段文字記錄寫入磁碟。使用此變數啟動的工作階段不會出現在 `--resume`、`--continue` 或向上箭頭歷史記錄中。對於臨時指令碼化工作階段很有用 |373| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 設定為 `1` 以跳過將提示歷史記錄和工作階段文字記錄寫入磁碟。使用此變數設定啟動的工作階段不會出現在 `--resume`、`--continue` 或向上箭頭歷史記錄中。對於短暫的指令碼工作階段很有用 |

295| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | [Stop](/docs/zh-TW/hooks#stop) 或 [SubagentStop](/docs/zh-TW/hooks#subagentstop) hook 可能連續阻止回合結束的最大次數，然後 Claude Code 覆蓋它並無論如何結束回合（預設值：8）。設定為 `0` 以停用上限。如果您的 hook 合法需要更多迭代來解決，請提高此值 |375| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | [Stop](/docs/zh-TW/hooks#stop) 或 [SubagentStop](/docs/zh-TW/hooks#subagentstop) hook 可能連續阻止轉向結束的最大次數，然後 Claude Code 覆蓋它並無論如何結束轉向（預設值：8）。設定為 `0` 以停用上限。如果您的 hook 合法需要更多迭代來解決，請提高此值 |

296| `CLAUDE_CODE_SUBAGENT_MODEL` | 請參閱 [Model configuration](/docs/zh-TW/model-config)。{{/* min-version: 2.1.196 */}}自 v2.1.196 起，將其設定為 `inherit` 與不設定相同；較早版本將 `inherit` 視為覆蓋，強制每個 subagent 進入主對話的模型 |376| `CLAUDE_CODE_SUBAGENT_MODEL` | [子代理](/docs/zh-TW/sub-agents#choose-a-model)、[代理團隊](/docs/zh-TW/agent-teams#specify-teammates-and-models) 隊友和 [工作流程](/docs/zh-TW/workflows) 代理的預設模型，這些代理未以其他方式指派模型。接受別名（例如 `haiku`）或完整模型名稱。兩個來源優先於它：Claude 產生代理時傳遞的模型，以及代理定義中的 `model` 欄位，包括 `inherit`。若要變更該，設定 [`CLAUDE_CODE_SUBAGENT_MODEL_FORCE`](/docs/zh-TW/sub-agents#run-every-subagent-on-one-model)。請參閱 [選擇模型](/docs/zh-TW/sub-agents#choose-a-model) 以了解完整順序。將其設定為 `inherit` 與保持未設定相同。在 v2.1.251 之前，此變數覆蓋了每個呼叫模型和定義的 `model` 欄位 |

297| `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` 會自動設定此項 |377| `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` | 設定為 `1` 以強制一個模型到子代理、隊友和工作流程代理。[在一個模型上執行每個子代理](/docs/zh-TW/sub-agents#run-every-subagent-on-one-model) 說明那是哪個模型。需要 Claude Code v2.1.257 或更新版本 |

298| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 在非互動式模式（`-p` 旗標）中設定為 `1` 以等待外掛程式安裝完成，然後再進行第一個查詢。沒有此選項，外掛程式會在背景中安裝，可能在第一個回合時不可用。與 `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` 結合以限制等待時間 |378| `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL` | 設定 `5m` 或 `1h`，Claude Code 接受的唯一值，以選擇主要對話外的請求的 [提示快取 TTL](/docs/zh-TW/prompt-caching#cache-lifetime)，例如 [子代理](/docs/zh-TW/sub-agents)、工作流程和背景工作。優先於 `subagentPromptCacheTtl` 設定和 `ENABLE_PROMPT_CACHING_1H`，`FORCE_PROMPT_CACHING_5M` 覆蓋它。API 以更高的速率計費 1 小時快取寫入。需要 Claude Code v2.1.242 或更新版本 |

299| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | 同步外掛程式安裝的逾時（以毫秒為單位）。超過時，Claude Code 會在沒有外掛程式的情況下繼續並記錄錯誤。無預設值：沒有此變數，同步安裝會等待直到完成 |379| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | 設定為 `1` 以從子程序環境中移除認證（Bash 工具、hooks、MCP stdio 伺服器）：Anthropic 和雲提供者認證、Claude Code 識別為認證的任何其他變數，以及嵌入在套件登錄 URL 中的認證。父 Claude 程序保留這些認證用於 API 呼叫，但子程序無法讀取它們，減少試圖透過 shell 擴展竊取秘密的提示注入攻擊的曝光。在 Linux 上，這也在隔離的 PID 命名空間中執行 Bash 子程序，因此它們無法透過 `/proc` 讀取主機程序環境；作為副作用，`ps`、`pgrep` 和 `kill` 無法看到或發信號給主機程序。`claude-code-action` 在配置 `allowed_non_write_users` 時自動設定此項 |

300| `CLAUDE_CODE_SYNC_SKILLS` | 設定為 `1` 以在第一個查詢之前將您啟用的 claude.ai skills 下載到 `~/.claude/skills/`，並每 10 分鐘重新同步一次。僅適用於非互動式模式，使用 `-p` 旗標。需要 claude.ai 驗證。[Claude Code on the web](/docs/zh-TW/claude-code-on-the-web) 工作階段會自動接收您啟用的 claude.ai skills；您不需要在那裡設定此項 |380| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 在非互動模式（`-p` 旗標）中設定為 `1` 以等待外掛程式安裝完成，然後才進行第一個查詢。沒有此選項，外掛程式在背景安裝，可能在第一個轉向上不可用。與 `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` 結合以限制等待 |

301| `CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MS` | 當設定 `CLAUDE_CODE_SYNC_SKILLS` 時，中途工作階段 skills 重新同步的逾時（以毫秒為單位）（預設值：30000）。限制在主機要求 skill 重新載入期間觸發的下載。超過時，重新同步停止，其餘下載在背景中繼續 |381| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | 同步外掛程式安裝的逾時（毫秒）。超過時，Claude Code 繼續進行而不使用外掛程式並記錄錯誤。無預設值：沒有此變數，同步安裝等待直到完成 |

302| `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` | 當設定 `CLAUDE_CODE_SYNC_SKILLS` 時，第一個查詢等待初始 skills 同步的逾時（以毫秒為單位）（預設值：5000）。超過時，查詢會繼續進行，其餘 skill 下載會在背景中繼續 |382| `CLAUDE_CODE_SYNC_SKILLS` | 設定為 `1` 以將您啟用的 claude.ai skills 下載到 `~/.claude/skills/synced/` 並每 10 分鐘重新同步。在執行第一個查詢之前，Claude Code 等待最多 `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` 以取得您的 skills 清單。下載本身在背景完成，Claude 在呼叫該 skill 時等待 skill 的下載。`synced` 資料夾名稱 [為此下載保留](/docs/zh-TW/skills#where-skills-live)。在 v2.1.227 之前，skills 直接下載到 `~/.claude/skills/` 中。僅適用於非互動模式，帶 `-p` 旗標。需要 claude.ai 驗證。[Claude Code on the web](/docs/zh-TW/claude-code-on-the-web) 工作階段自動接收您啟用的 claude.ai skills；您不需要在那裡設定此項。Claude Code 對下載的 skills 應用 [額外規則](/docs/zh-TW/skills#how-synced-skills-behave)，例如不在您的機器上執行它們的 `!` 命令 |

303| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | 設定為 `false` 以停用 diff 輸出中的語法醒目提示。當顏色干擾您的終端設定時很有用。若要也停用程式碼區塊和檔案預覽中的醒目提示，請使用 [`syntaxHighlightingDisabled`](/docs/zh-TW/settings) 設定 |383| `CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MS` | 當設定 `CLAUDE_CODE_SYNC_SKILLS` 時，中途工作階段 skills 重新同步的逾時（毫秒）（預設值：30000）。限制主機在工作階段期間請求 skill 重新載入時觸發的下載。超過時，重新同步停止，剩餘下載在背景繼續 |

304| `CLAUDE_CODE_TASK_LIST_ID` | 跨工作階段共享任務清單。在多個 Claude Code 實例中設定相同的 ID 以協調共享任務清單。請參閱 [Task list](/docs/zh-TW/interactive-mode#task-list) |384| `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` | 當設定 `CLAUDE_CODE_SYNC_SKILLS` 時，第一個查詢等待初始 skill 清單的逾時（毫秒）（預設值：5000）。超過時，第一個查詢執行時使用已到達的任何 skills。下載無論如何都在背景完成，Claude 在呼叫該 skill 時等待 skill 的下載 |

305| `CLAUDE_CODE_TEAM_NAME` | 此隊友所屬的 agent team 名稱。在 [agent team](/docs/zh-TW/agent-teams) 成員上自動設定 |385| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | 設定為 `false` 以停用 diff 輸出中的語法醒目提示。當顏色干擾您的終端設定時很有用。若要也停用程式碼區塊和檔案預覽中的醒目提示，請使用 [`syntaxHighlightingDisabled`](/docs/zh-TW/settings-reference#syntaxhighlightingdisabled) 設定 |

306| `CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MS` | 覆蓋，以毫秒為單位，非互動式工作階段在退出時等待其 [agent team](/docs/zh-TW/agent-teams) 完成拆卸的時間。接受 1000 到 60000；超出範圍的值被忽略，預設值 10000 適用。需要 Claude Code v2.1.206 或更新版本 |386| `CLAUDE_CODE_TASK_LIST_ID` | 跨工作階段共享工作清單。在多個 Claude Code 執行個體中設定相同的 ID 以協調共享工作清單，在 [具有 Task 工具的工作階段](/docs/zh-TW/tools-reference#task-tool-availability) 中。請參閱 [工作清單](/docs/zh-TW/interactive-mode#task-list) |

307| `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](/docs/zh-TW/sandboxing) Bash 子程序會在系統預設下收到簡短的回退 `$TMPDIR`，因為某些工具在臨時路徑變得太長時會失敗。未沙箱化的 Bash 命令繼承您的 shell 的 `$TMPDIR` 不變。Claude Code 自己的臨時檔案始終使用您的覆蓋 |387| `CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MS` | 覆蓋非互動工作階段在退出時等待其 [代理團隊](/docs/zh-TW/agent-teams) 完成拆卸的時間（毫秒）。接受 1000 到 60000；超出範圍的值被忽略，預設值 10000 適用。需要 Claude Code v2.1.206 或更新版本 |

308| `CLAUDE_CODE_TMUX_TRUECOLOR` | 設定為 `1` 以允許 tmux 內的 24 位真彩色輸出。預設情況下，當設定 `$TMUX` 時，Claude Code 會限制為 256 色，因為 tmux 不會通過真彩色逃逸序列，除非配置為這樣做。在將 `set -ga terminal-overrides ',*:Tc'` 新增到您的 `~/.tmux.conf` 後設定此項。請參閱 [Terminal configuration](/docs/zh-TW/terminal-config) 以取得其他 tmux 設定 |388| `CLAUDE_CODE_TMPDIR` | 覆蓋用於內部臨時檔案的臨時目錄。Claude Code 在 Unix 上附加 `/claude-{uid}/`，在 Windows 上附加 `/claude/` 到此路徑。預設：macOS 上 `/tmp`，Linux 和 Windows 上 `os.tmpdir()`。在 macOS 和 Linux 上，[沙箱化](/docs/zh-TW/sandboxing) Bash 子程序在您的覆蓋是長路徑時在系統預設下接收短回退 `$TMPDIR`，因為某些工具在臨時路徑變得太長時失敗。未沙箱化的 Bash 命令未變更地繼承您的 shell 的 `$TMPDIR`。Claude Code 自己的臨時檔案始終使用您的覆蓋。在您的 shell、使用者設定或受管設定中設定它。在 [專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env) 中忽略 |

309| `CLAUDE_CODE_USE_ANTHROPIC_AWS` | 使用 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) |389| `CLAUDE_CODE_TMUX_TRUECOLOR` | 設定為任何非空值（例如 `1`）以允許 tmux 內的 24 位真彩色輸出。**將其設定為 `0` 或 `false` 仍允許真彩色**，與大多數開啟/關閉變數不同；取消設定變數以恢復 256 色限制。預設情況下，當設定 `$TMUX` 時 Claude Code 限制為 256 色，因為 tmux 不會透過真彩色逃逸序列，除非配置。在將 `set -ga terminal-overrides ',*:Tc'` 新增到您的 `~/.tmux.conf` 後設定此項。請參閱 [終端設定](/docs/zh-TW/terminal-config) 以了解其他 tmux 設定 |

390| `CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE` | 在 Linux 和 WSL 上，設定為 Claude Code [從工具記憶體上限排除](/docs/zh-TW/tools-reference#memory-limit-on-linux-and-wsl) 的程序類型的逗號分隔清單，例如 `mcp` 或 `lsp`。設定 `none` 以上限每種類型，或 `all-new` 以僅上限 Bash、PowerShell 和 Monitor 工具命令。Claude Code 無論您列出什麼，都將 Bash、PowerShell 和 Monitor 工具命令保持在上限下。需要 Claude Code v2.1.246 或更新版本 |

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

392| `CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS` | Claude Code 在取消它轉發給遠端用戶端（例如 [Remote Control](/docs/zh-TW/remote-control) 或 SDK 主機）的對話之前的截止日期（毫秒），或 [保持的跨工作階段訊息](/docs/zh-TW/cross-session-messaging#control-inbound-messages) 的批准對話；權限提示和 `AskUserQuestion` 問題使用自己的流程，不受它管轄。在 Claude Code v2.1.236 或更新版本上，它也限制可能無人值守執行的工作階段中的中途 [Fable 使用額度同意提示](/docs/zh-TW/model-config#fable-and-usage-credits)。[控制入站訊息](/docs/zh-TW/cross-session-messaging#control-inbound-messages) 和 [非互動工作階段](/docs/zh-TW/cross-session-messaging#non-interactive-sessions) 涵蓋完整的保持訊息過期規則，包括截止日期不適用的情況。覆蓋 [`dialogExpiry`](/docs/zh-TW/settings-reference#dialogexpiry) 設定。`0` 或負值停用截止日期 |

393| `CLAUDE_CODE_USE_ANTHROPIC_AWS` | 使用 [AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws) |

313| `CLAUDE_CODE_USE_NATIVE_FILE_SEARCH` | 設定為 `1` 以使用 Node.js 檔案 API 而不是 ripgrep 來探索自訂命令、subagents 和輸出樣式。如果捆綁的 ripgrep 二進位檔案在您的環境中不可用或被阻止，請設定此項。不影響 Grep 或檔案搜尋工具 |397| `CLAUDE_CODE_USE_NATIVE_FILE_SEARCH` | 設定為 `1` 以使用 Node.js 檔案 API 而不是 ripgrep 發現自訂命令、子代理和輸出樣式。如果捆綁的 ripgrep 二進位檔在您的環境中不可用或被阻止，請設定此項。不影響 Grep 或檔案搜尋工具 |

314| `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](/docs/zh-TW/tools-reference#powershell-tool) |398| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | 控制 PowerShell 工具。在沒有 Git Bash 的 Windows 上，工具自動啟用；設定為 `0` 以停用它。在安裝了 Git Bash 的 Windows 上，工具對 claude.ai 和 Console 帳戶預設開啟；設定為 `1` 以在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 工作階段中啟用它，或 `0` 以關閉它。在 Linux、macOS 和 WSL 上，設定為 `1` 以啟用它，這需要您的 `PATH` 上的 `pwsh`。在 Windows 上啟用時，Claude 可以原生執行 PowerShell 命令，而不是透過 Git Bash 路由。請參閱 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool) |

316| `CLAUDE_CONFIG_DIR` | 覆蓋配置目錄（預設值：`~/.claude`）。所有設定、認證、工作階段歷史記錄和外掛程式都儲存在此路徑下。對於並排執行多個帳戶很有用：例如，`alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'` |400| `CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS` | 設定為 [WebFetch](/docs/zh-TW/tools-reference#webfetch-tool-behavior) 保持每個擷取 URL 回應快取的毫秒數。預設值為 `900000`，即 15 分鐘。僅接受純數字；`0`、小數或任何其他拼寫保持預設值。Claude Code 每次啟動讀取一次值，因此設定 `env` 區塊中的變更在您下次啟動 `claude` 時適用。需要 Claude Code v2.1.233 或更新版本 |

317| `CLAUDE_DISABLE_ADOPT` | {{/* min-version: 2.1.195 */}}設定為 `1` 以停止進行中的背景工作，而不是在您按 `←` 或使用 [`/background`](/docs/zh-TW/agent-view#from-inside-a-session) 將工作階段背景化時帶入它。Claude Code 會要求您在背景化前確認，然後停止會以其他方式帶入的任務。需要 Claude Code v2.1.195 或更新版本 |401| `CLAUDE_CODE_WEBFETCH_DEADLINE_MS` | [WebFetch](/docs/zh-TW/tools-reference#webfetch-tool-behavior) 等待頁面下載的上限（毫秒），包括它遵循的任何重新導向。未在該時間內完成的下載會失敗，並出現截止日期錯誤。預設值為 `300000`，即五分鐘。設定為 `0` 以移除限制。僅接受純數字；小數或任何其他拼寫保持預設值。需要 Claude Code v2.1.268 或更新版本 |

318| `CLAUDE_EFFORT` | 在 Bash 工具子程序和 hook 命令中自動設定為該回合的作用中 [effort level](/docs/zh-TW/model-config#adjust-effort-level)：`low`、`medium`、`high`、`xhigh` 或 `max`。Ultracode 不是一個不同的級別，報告為 `xhigh`。符合傳遞給 [hooks](/docs/zh-TW/hooks) 的 `effort.level` 欄位。僅在目前模型支援努力參數時設定 |402| `CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS` | [工作流程](/docs/zh-TW/workflows) 代理等待相同前綴同級的第一個回應開始的上限（毫秒），然後才傳送自己的第一個請求。當扇出啟動共享 [提示快取前綴](/docs/zh-TW/workflows#prompt-caching-in-a-fan-out) 的多個代理時，Claude Code 將除第一個外的所有代理保持最多此長時間，以便其餘代理讀取快取的前綴，而不是每個未快取地處理它。預設 `5000`。設定為 `0` 以停用等待。當設定 `DISABLE_PROMPT_CACHING` 時，代理永遠不會等待。需要 Claude Code v2.1.229 或更新版本 |

319| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 設定為 `1` 以強制啟用位元級串流閒置監視程式，或設定為 `0` 以強制停用它。未設定時，監視程式預設對 Anthropic API 和 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 連線啟用。位元監視程式會在 180 秒內沒有位元組到達線路時中止連線（直接 Anthropic API 連線上預設為 180 秒，Claude Platform on AWS 和其他提供者上為 300 秒），或在設定 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 時為該值，該值被限制為最少 5 分鐘，獨立於事件級監視程式 |403| `CLAUDE_CONFIG_DIR` | 覆蓋設定目錄（預設值：`~/.claude`）。所有設定、工作階段歷史記錄和外掛程式都儲存在此路徑下。對於認證，請參閱 [Claude Code 儲存認證的位置](/docs/zh-TW/authentication#credential-management)。對於並排執行多個帳戶很有用：例如，`alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'`。在您的 shell、使用者設定或受管設定中設定它。在 [專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env) 中忽略 |

320| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | 設定為 `1` 以在 Amazon Bedrock `vnd.amazon.eventstream` 回應上啟用位元級串流閒置監視程式。預設關閉。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置逾時 |404| `CLAUDE_DISABLE_ADOPT` | 設定為 `1` 以在您透過按 `←` 或 [`/background`](/docs/zh-TW/agent-view#from-inside-a-session) 背景化工作階段時停止進行中的背景工作，而不是進行。Claude Code 要求您在背景化前確認，然後停止否則會進行的工作。需要 Claude Code v2.1.195 或更新版本 |

321| `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` 配置逾時 |405| `CLAUDE_EFFORT` | 在 Bash 工具子程序和 hook 命令中自動設定為子程序啟動時有效的 [effort 級別](/docs/zh-TW/model-config#adjust-effort-level)：`low`、`medium`、`high`、`xhigh` 或 `max`。Ultracode 不是不同的級別，報告為 `xhigh`。符合傳遞給 [hooks](/docs/zh-TW/hooks) 的 `effort.level` 欄位。僅在目前模型支援 effort 參數時設定 |

322| `CLAUDE_ENV_FILE` | Claude Code 在每個 Bash 命令之前在同一 shell 程序中執行的 shell 指令碼的路徑，因此檔案中的匯出對命令可見。用於在命令之間保持 virtualenv 或 conda 啟用。也由 [SessionStart](/docs/zh-TW/hooks#persist-environment-variables)、[Setup](/docs/zh-TW/hooks#setup)、[CwdChanged](/docs/zh-TW/hooks#cwdchanged) 和 [FileChanged](/docs/zh-TW/hooks#filechanged) hooks 動態填充 |406| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 設定為 `1` 以強制啟用位元組級串流閒置監視狗，或設定為 `0` 以強制停用它。`0` 也關閉執行該截止日期的連線上的 [第一位元組截止日期](/docs/zh-TW/network-config#streaming-idle-watchdogs)。未設定時，監視狗在直接 Anthropic API 和 [AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws) 連線上預設啟用，以及透過 `ANTHROPIC_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 到達的 [閘道](/docs/zh-TW/gateways) 連線上的串流回應；在 v2.1.222 之前，它在這些閘道連線上不執行，因此事件級監視狗可能在那裡報告停滯，即使保活 ping 到達。對於逾時以及計時器如何互動，請參閱 [串流閒置監視狗](/docs/zh-TW/network-config#streaming-idle-watchdogs) |

323| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | 當未提供明確名稱時，自動產生的 [Remote Control](/docs/zh-TW/remote-control) 工作階段名稱的前綴。預設為您的機器主機名稱，產生名稱如 `myhost-graceful-unicorn`。`--remote-control-session-name-prefix` CLI 旗標為單一呼叫設定相同的值 |407| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | 設定為 `1` 以在 Amazon Bedrock `vnd.amazon.eventstream` 回應上啟用位元組級串流閒置監視狗，這也啟用 Bedrock 串流請求上的 [第一位元組截止日期](/docs/zh-TW/network-config#streaming-idle-watchdogs)。預設關閉。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置逾時 |

324| `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` |408| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 設定為 `0` 以強制停用事件級串流閒置監視狗，或設定為 `1` 以強制啟用它。未設定時，監視狗在所有提供者上預設開啟。在 v2.1.196 之前，未設定的預設值在直接 Anthropic API 上由伺服器控制，在其他提供者上關閉。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置逾時；對於與此一起執行的其他停滯計時器，請參閱 [串流閒置監視狗](/docs/zh-TW/network-config#streaming-idle-watchdogs) |

325| `DEBUG` | 設定為 `1` 以啟用偵錯模式，相當於使用 [`--debug`](/docs/zh-TW/cli-reference#cli-flags) 啟動。偵錯日誌會寫入 `~/.claude/debug/<session-id>.txt`，或寫入 `CLAUDE_CODE_DEBUG_LOGS_DIR` 設定的路徑。僅真值 `1`、`true`、`yes` 和 `on` 啟用偵錯模式，因此為其他工具設定的命名空間模式（如 `DEBUG=express:*`）不會觸發它 |409| `CLAUDE_ENV_FILE` | shell 指令碼的路徑，其內容 Claude Code 在同一 shell 程序中的每個 Bash 命令之前執行，因此檔案中的匯出對命令可見。用於在命令之間保持 virtualenv 或 conda 啟用。也由 [SessionStart](/docs/zh-TW/hooks#persist-environment-variables)、[Setup](/docs/zh-TW/hooks#setup)、[CwdChanged](/docs/zh-TW/hooks#cwdchanged) 和 [FileChanged](/docs/zh-TW/hooks#filechanged) hooks 動態填充 |

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

411| `CLAUDE_PID` | Claude Code 在它產生的子程序中設定此項為其自己的程序 ID：Bash 和 PowerShell 工具命令和 hook 命令。在 Linux 上，Bash 工具的 shell 整合使用它來拒絕會符合 Claude Code 程序本身的 `pkill` 模式；請參閱 [錯誤參考](/docs/zh-TW/errors#pkill-pattern-matches-the-claude-code-process)。從您自己的指令碼讀取它以識別或故意發信號給父 Claude Code 程序。需要 Claude Code v2.1.214 或更新版本 |

412| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | 當未提供明確名稱時，自動產生的 [Remote Control](/docs/zh-TW/remote-control) 工作階段名稱的前綴。預設為您機器的主機名稱，產生 `myhost-graceful-unicorn` 等名稱。`--remote-control-session-name-prefix` CLI 旗標為單一呼叫設定相同的值 |

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

414| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 事件級和位元組級串流閒置監視狗在停滯連線關閉前的逾時（毫秒）。當您明確設定此變數時，最小值為 `300000`（5 分鐘）；較低的值無聲地限制在吸收擴展思考暫停和代理緩衝，位元組級監視狗將值上限為 30 分鐘。`CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` 優先於此變數用於位元組級監視狗。對於每個監視狗未設定的預設值，請參閱 [串流閒置監視狗](/docs/zh-TW/network-config#streaming-idle-watchdogs) |

415| `CLAUDE_SUBAGENT_BG_SHELL_MAX_MS` | 在 v2.1.260 中移除，現在是無操作。先前上限了 [子代理](/docs/zh-TW/sub-agents) 啟動的 [背景 shell 命令](/docs/zh-TW/interactive-mode#background-bash-commands) 可以執行多長時間（毫秒），預設 60 分鐘。請參閱 [背景命令生命週期規則](/docs/zh-TW/tools-reference#background-commands) |

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

327| `DISABLE_AUTO_COMPACT` | 設定為 `1` 以停用接近上下文限制時的自動壓縮。手動 `/compact` 命令仍然可用。在您想要明確控制何時進行壓縮時使用 |418| `DISABLE_AUTO_COMPACT` | 設定為 `1` 以停用接近上下文限制時的自動壓縮。手動 `/compact` 命令保持可用。當您想要明確控制何時進行壓縮時使用。覆蓋 [`autoCompactEnabled`](/docs/zh-TW/settings-reference#autocompactenabled) 設定 |

330| `DISABLE_DOCTOR_COMMAND` | 設定為 `1` 以隱藏 [`/doctor`](/docs/zh-TW/commands#all-commands) 設定檢查 skill 及其 `/checkup` 別名。對於使用者不應執行安裝診斷的受管部署很有用。不影響 `claude doctor` 終端命令。{{/* min-version: 2.1.205 */}}在 v2.1.205 之前，此變數隱藏了 `/doctor` 診斷螢幕命令 |421| `DISABLE_DOCTOR_COMMAND` | 設定為 `1` 以隱藏 [`/doctor`](/docs/zh-TW/commands#all-commands) 設定檢查 skill 及其 `/checkup` 別名。對於使用者不應執行設定診斷的受管部署很有用。不影響 `claude doctor` 終端命令。在 v2.1.205 之前，此變數隱藏了 `/doctor` 診斷螢幕命令 |

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

334| `DISABLE_GROWTHBOOK` | 設定為 `1` 以停用 GrowthBook 功能旗標擷取並為每個旗標使用程式碼預設值。遙測事件日誌記錄保持開啟，除非也設定 `DISABLE_TELEMETRY` |425| `DISABLE_GROWTHBOOK` | 設定為 `1` 或 `true` 以停用 GrowthBook 功能旗標擷取並為每個旗標使用程式碼預設值。這使 [Remote Control](/docs/zh-TW/remote-control#requirements) 和其他 [需要功能旗標擷取的功能](#features-that-need-feature-flag-fetching) 不可用。將其設定為 `0` 或 `false` 保持擷取開啟。遙測事件日誌保持開啟，除非 `DISABLE_TELEMETRY` 也設定 |

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

337| `DISABLE_INTERLEAVED_THINKING` | 設定為 `1` 以防止發送交錯思考 beta 標頭。當您的 LLM 閘道或提供者不支援 [interleaved thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking) 時很有用 |428| `DISABLE_INTERLEAVED_THINKING` | 設定為 `1` 以防止傳送交錯思考測試版標頭。當您的 LLM 閘道或提供者不支援 [交錯思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking) 時很有用 |

345| `DISABLE_TELEMETRY` | 設定為 `1` 以選擇退出遙測。遙測事件不包括使用者資料，如程式碼、檔案路徑或 bash 命令。也停用功能旗標擷取，效果與 `DISABLE_GROWTHBOOK` 相同，因此某些標記的功能可能無法使用 |436| `DISABLE_TELEMETRY` | 設定為任何非空值（例如 `1`）以選擇退出遙測。**將其設定為 `0` 或 `false` 仍會選擇退出**，與大多數開啟/關閉變數不同；取消設定變數以重新開啟遙測。遙測事件不包含使用者資料，如程式碼、檔案路徑或 bash 命令。也停用功能旗標擷取，效果與 `DISABLE_GROWTHBOOK` 相同，這使 [Remote Control](/docs/zh-TW/remote-control#requirements) 和其他 [需要功能旗標擷取的功能](#features-that-need-feature-flag-fetching) 不可用。請參閱 [為您的組織關閉遙測](/docs/zh-TW/managed-settings#turn-telemetry-off-for-your-organization) |

346| `DISABLE_UPDATES` | 設定為 `1` 以阻止所有更新，包括手動 `claude update` 和 `claude install`。比 `DISABLE_AUTOUPDATER` 更嚴格。在透過您自己的管道分發 Claude Code 且使用者不應自行更新時使用 |437| `DISABLE_UPDATES` | 設定為 `1` 以阻止所有更新，包括手動 `claude update` 和 `claude install`。比 `DISABLE_AUTOUPDATER` 更嚴格。在透過您自己的通道分發 Claude Code 且使用者不應自我更新時使用 |

348| `DO_NOT_TRACK` | 設定為 `1` 以選擇退出遙測。相當於設定 `DISABLE_TELEMETRY`。Claude Code 尊重此作為許多開發者 CLI 認可的跨工具慣例 |439| `DO_NOT_TRACK` | 設定為 `1` 以選擇退出遙測，效果與 `DISABLE_TELEMETRY` 相同，包括使 [Remote Control](/docs/zh-TW/remote-control#requirements) 和其他 [需要功能旗標擷取的功能](#features-that-need-feature-flag-fetching) 不可用。Claude Code 將此變數讀作標準布林值，因此 `0` 保持遙測開啟，並尊重許多開發人員 CLI 識別的跨工具慣例 |

349| `ENABLE_CLAUDEAI_MCP_SERVERS` | 設定為 `false` 以停用 Claude Code 中的 [claude.ai MCP servers](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai)。對於已登入的使用者預設啟用。若要按專案或按組織停用，請改為在設定中設定 [`disableClaudeAiConnectors`](/docs/zh-TW/settings#available-settings) |440| `ENABLE_BETA_TRACING_DETAILED` | 設定為 `1`，與 `BETA_TRACING_ENDPOINT` 一起，以開啟 [詳細測試版追蹤](/docs/zh-TW/monitoring-usage#traces-beta)，它新增內容承載跨度屬性和 `claude_code.hook` 跨度。互動 CLI 工作階段也需要您的組織被允許列出用於測試版。兩個變數在 [專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env) 中被忽略 |

350| `ENABLE_PROMPT_CACHING_1H` | 設定為 `1` 以要求 1 小時的提示快取 TTL，而不是預設的 5 分鐘。適用於 API 金鑰、[Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai)、[Microsoft Foundry](/docs/zh-TW/microsoft-foundry) 和 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 使用者。訂閱使用者自動接收 1 小時 TTL。1 小時快取寫入以更高的速率計費 |441| `ENABLE_CLAUDEAI_MCP_SERVERS` | 設定為 `false` 以停止 Claude Code 擷取 [claude.ai MCP 伺服器](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai)。對於已登入的使用者預設啟用。若要按專案或按組織停用，改為在設定中設定 [`disableClaudeAiConnectors`](/docs/zh-TW/settings-reference#disableclaudeaiconnectors) |

442| `ENABLE_PROMPT_CACHING_1H` | 設定為 `1` 以請求 1 小時 [提示快取 TTL](/docs/zh-TW/prompt-caching#cache-lifetime)，而不是預設 5 分鐘。適用於 API 金鑰、[Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-TW/google-vertex-ai)、[Microsoft Foundry](/docs/zh-TW/microsoft-foundry) 和 [AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws) 使用者。訂閱使用者在包含的使用量內在 [主要對話](/docs/zh-TW/prompt-caching#which-ttl-each-request-gets) 上自動接收 1 小時 TTL。訂閱使用者從 [使用額度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) 中提取可以設定它以保持 1 小時 TTL。1 小時快取寫入以更高的速率計費。若要改為按請求桶選擇 TTL，請使用 `CLAUDE_CODE_PROMPT_CACHE_TTL` 和 `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`，它們優先於此變數 |

352| `ENABLE_TOOL_SEARCH` | 控制 [MCP tool search](/docs/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`（提前載入全部）。當設定 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` 時被忽略，這會強制所有工具提前載入 |444| `ENABLE_TOOL_SEARCH` | 控制 [MCP 工具搜尋](/docs/zh-TW/mcp#scale-with-mcp-tool-search)。未設定時，Claude Code 預設延遲所有 MCP 工具。它仍在早於 Claude 4.5 代的 Google Cloud 的 Agent Platform 模型上立即載入它們，在 Azure 上託管的 Microsoft Foundry 部署上，以及當 `ANTHROPIC_BASE_URL` 指向非第一方主機時。`true` 始終延遲並傳送測試版標頭，除了在這些相同的 Agent Platform 模型和 Microsoft Foundry 部署上；請求在不支援 `tool_reference` 的代理上失敗。`auto` 在工具定義符合上下文的 10% 時立即載入。`auto:N` 設定自訂閾值，例如 5% 的 `auto:5`。`false` 立即載入所有工具。當設定 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` 時，您自己設定的值被忽略。在 v2.1.221 之前，Claude Code 在 Google Cloud 的 Agent Platform 上為所有模型停用工具搜尋，除非您將此變數設定為 `true` |

353| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | 設定為任何非空值以在任何主要模型上重複過載錯誤後觸發回退。{{/* min-version: 2.1.160 */}}自 v2.1.160 起，配置的 [fallback model chain](/docs/zh-TW/model-config#fallback-model-chains) 會在任何主要模型的重複過載錯誤時觸發，因此此變數不影響切換到回退模型 |445| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | 設定為任何非空值（例如 `1`）以使 Claude Code 在未配置回退模型時停止在重複過載錯誤上重試每個模型。**將其設定為 `0` 或 `false` 仍會啟用此功能**，與大多數開啟/關閉變數不同；取消設定變數以恢復預設重試行為。沒有它，Claude Code 在您使用 API 金鑰或 [第三方提供者](/docs/zh-TW/third-party-integrations) 而不是 Claude 訂閱進行驗證時，停止在它識別為 Opus、Fable 或 Mythos 模型的重複過載錯誤上重試。在 Claude Code v2.1.160 或更新版本上，Claude Code 在任何主要模型上重複過載錯誤時切換到您配置的 [回退模型鏈](/docs/zh-TW/model-config#fallback-model-chains)，因此此變數不影響切換到回退模型 |

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

356| `FORCE_PROMPT_CACHING_5M` | 設定為 `1` 以強制 5 分鐘的提示快取 TTL，即使 1 小時 TTL 會以其他方式適用。覆蓋 `ENABLE_PROMPT_CACHING_1H` |448| `FORCE_PROMPT_CACHING_5M` | 設定為 `1` 以強制 5 分鐘提示快取 TTL，即使 1 小時 TTL 會否則適用。覆蓋 `CLAUDE_CODE_PROMPT_CACHE_TTL`、`CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`、`ENABLE_PROMPT_CACHING_1H` 和 `promptCacheTtl` 和 `subagentPromptCacheTtl` 設定 |

360| `MAX_MCP_OUTPUT_TOKENS` | MCP 工具回應中允許的最大 token 數。Claude Code 在輸出超過 10,000 token 時顯示警告。宣告 [`anthropic/maxResultSizeChars`](/docs/zh-TW/mcp#raise-the-limit-for-a-specific-tool) 的工具對文字內容使用該字元限制，但來自這些工具的影像內容仍受此變數限制（預設值：25000） |452| `MAX_MCP_OUTPUT_TOKENS` | MCP 工具回應中允許的最大權杖數。Claude Code 在輸出超過 10,000 權杖時顯示警告。聲明 [`anthropic/maxResultSizeChars`](/docs/zh-TW/mcp#raise-the-limit-for-a-specific-tool) 的工具改為為文字內容使用該字元限制，但來自這些工具的影像內容仍受此變數約束（預設值：25000） |

361| `MAX_STRUCTURED_OUTPUT_RETRIES` | 當模型的回應無法驗證非互動式模式（`-p` 旗標）中的 [`--json-schema`](/docs/zh-TW/cli-reference#cli-flags) 時重試的次數。預設為 5 |453| `MAX_STRUCTURED_OUTPUT_RETRIES` | 當模型的回應無法針對非互動模式中的 [`--json-schema`](/docs/zh-TW/cli-reference#cli-flags) 使用 `-p` 旗標進行驗證時，Claude Code 允許的嘗試次數；在那麼多次失敗的嘗試後沒有有效輸出，執行失敗。當 [工作流程](/docs/zh-TW/workflows) 子代理的結構化輸出無法驗證時，相同的上限適用。預設為 5，第一次嘗試加四次重試 |

362| `MAX_THINKING_TOKENS` | 覆蓋 [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) token 預算。上限是模型的 [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison) 減一。設定為 `0` 以在 Anthropic API 上停用思考，除了 Fable 5，它無法關閉思考。在 [third-party providers](/docs/zh-TW/third-party-integrations) 上，`0` 同樣省略該參數，具有 [adaptive reasoning](/docs/zh-TW/model-config#adjust-effort-level) 的模型仍可能思考。對於自適應推理模型上的非零值，預算會被忽略，除非透過 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 停用自適應推理 |454| `MAX_THINKING_TOKENS` | [擴展思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) 的固定權杖預算。Claude Code 將其上限設為請求的最大輸出權杖下方一個權杖，絕不低於 1,024。請參閱 `CLAUDE_CODE_MAX_OUTPUT_TOKENS` 以了解該限制如何設定。未設定時，具有 [自適應推理](/docs/zh-TW/model-config#adjust-effort-level) 的模型選擇自己的思考深度，其他模型使用上限。設定為 `0` 以在 Anthropic API 上停用思考，除了 Fable 模型，無法關閉思考。在 [第三方提供者](/docs/zh-TW/third-party-integrations) 上，`0` 改為省略 `thinking` 參數。在 Anthropic API 上關閉思考時，Claude Code 向它知道 [不接受該組合](/docs/zh-TW/errors#effort-isnt-available-with-thinking-turned-off) 的模型（例如 Opus 5）傳送 effort `high` 而不是更高級別。Claude Code 忽略自適應推理模型上的非零值，除了 Claude Code 關閉自適應推理的模型，除了 Claude Code 關閉自適應推理的模型 |

363| `MCP_CLIENT_SECRET` | 需要 [pre-configured credentials](/docs/zh-TW/mcp#use-pre-configured-oauth-credentials) 的 MCP 伺服器的 OAuth 用戶端密碼。在使用 `--client-secret` 新增伺服器時避免互動式提示 |455| `MCP_CLIENT_SECRET` | 需要 [預先配置的認證](/docs/zh-TW/mcp#use-pre-configured-oauth-credentials) 的 MCP 伺服器的 OAuth 用戶端密碼。在使用 `--client-secret` 新增伺服器時避免互動提示 |

364| `MCP_CONNECTION_NONBLOCKING` | 控制啟動是否在第一個查詢之前等待 MCP 伺服器連線。{{/* min-version: 2.1.142 */}}自 Claude Code v2.1.142 起，MCP 啟動預設為非阻止：伺服器在背景中連線，其工具在完成時變為可用。設定為 `0` 以還原阻止 5 秒連線等待。配置 [`alwaysLoad: true`](/docs/zh-TW/mcp#exempt-a-server-from-deferral) 的伺服器仍會阻止啟動，無論如何，因為其工具必須在建立第一個提示時存在 |456| `MCP_CONNECTION_NONBLOCKING` | 控制啟動是否在第一個查詢之前等待 MCP 伺服器連線。MCP 啟動預設非阻塞：伺服器在背景連線，其工具在完成時變為可用。設定為 `0` 以使 Claude Code 在第一個查詢之前等待伺服器連線。配置 [`alwaysLoad: true`](/docs/zh-TW/mcp#exempt-a-server-from-deferral) 的伺服器仍使啟動等待，除非從 [發現快取](/docs/zh-TW/mcp#server-status-detail) 提供，因為它們的工具必須在建立第一個提示時存在。在非互動模式 (`-p`) 中，Claude Code 也在第一個轉向之前等待仍待處理的伺服器，當您明確傳遞 [`--mcp-config`](/docs/zh-TW/cli-reference#cli-flags) 時有更長的截止日期；請參閱該旗標的項目以了解快取伺服器例外 |

365| `MCP_CONNECT_TIMEOUT_MS` | 阻止 MCP 啟動等待連線批次的時間（以毫秒為單位），然後拍攝工具清單快照（預設值：5000）。適用於 `MCP_CONNECTION_NONBLOCKING=0` 或標記為 [`alwaysLoad: true`](/docs/zh-TW/mcp#exempt-a-server-from-deferral) 的伺服器。在截止時間時仍待處理的伺服器會在背景中繼續連線，但在下一個查詢之前不會出現。與 `MCP_TIMEOUT` 不同，後者限制個別伺服器的連線嘗試 |457| `MCP_CONNECT_TIMEOUT_MS` | 阻塞 MCP 啟動等待連線批次的時間（毫秒），然後才快照工具清單（預設值：5000）。當 `MCP_CONNECTION_NONBLOCKING=0` 或伺服器標記 [`alwaysLoad: true`](/docs/zh-TW/mcp#exempt-a-server-from-deferral) 時適用。仍待處理的伺服器在截止日期後繼續在背景連線。與 `MCP_TIMEOUT` 不同，後者限制個別伺服器的連線嘗試 |

366| `MCP_OAUTH_CALLBACK_PORT` | OAuth 重新導向回呼的固定連接埠，作為在使用 [pre-configured credentials](/docs/zh-TW/mcp#use-pre-configured-oauth-credentials) 新增 MCP 伺服器時 `--callback-port` 的替代方案 |458| `MCP_DISCOVERY_CACHE` | 開啟或關閉 [MCP 發現快取](/docs/zh-TW/mcp#server-status-detail)。快取開啟時，您之前使用過的遠端 HTTP 或 SSE 伺服器可以顯示 [`cached` 狀態](/docs/zh-TW/mcp#server-status-detail)，Claude Code 在其第一個工具呼叫時連線它，而不是在啟動時。快取預設關閉，除非逐步推出已為您的帳戶啟用它。設定為 `1` 以開啟它，或 `0` 以保持關閉，即使推出已啟用它。在 v2.1.238 之前，快取預設開啟。`cached` 狀態需要 Claude Code v2.1.221 或更新版本 |

459| `MCP_DISCOVERY_CACHE_MAX_STALE_S` | [發現快取](/docs/zh-TW/mcp#server-status-detail) 項目的最大年齡（秒）（預設值：14400，或 4 小時）。在項目比該年齡更舊的啟動時，Claude Code 會丟棄它並在啟動時連線伺服器，如同快取關閉一樣。Claude Code 將值上限為 7 天。在 v2.1.238 之前，預設值為 86400，或 24 小時，Claude Code 未上限該值 |

460| `MCP_DISCOVERY_CACHE_STRIKES` | 在啟動時 [發現快取](/docs/zh-TW/mcp#server-status-detail) 項目比 `MCP_DISCOVERY_CACHE_TTL_S` 更舊時，Claude Code 在背景刷新它。此變數設定在 Claude Code 丟棄項目並在下一次啟動時連線伺服器之前，連續刷新可以失敗多少次（預設值：1）。如果您的網路連線偶爾掉線，請提高它，以便一次失敗的刷新不會丟棄項目。需要 Claude Code v2.1.238 或更新版本 |

461| `MCP_DISCOVERY_CACHE_TTL_S` | Claude Code 使用 [發現快取](/docs/zh-TW/mcp#server-status-detail) 項目而不刷新它的秒數（預設值：900）。在項目比該年齡更舊的啟動時，Claude Code 仍使用它但在背景刷新它。一旦項目比 `MCP_DISCOVERY_CACHE_MAX_STALE_S` 更舊，Claude Code 改為丟棄它。Claude Code 將值上限為 `MCP_DISCOVERY_CACHE_MAX_STALE_S`，預設為 4 小時。在 v2.1.238 之前，Claude Code 未上限該值 |

462| `MCP_OAUTH_CALLBACK_PORT` | OAuth 重新導向回呼的固定埠，作為使用 [預先配置的認證](/docs/zh-TW/mcp#use-pre-configured-oauth-credentials) 新增 MCP 伺服器時 `--callback-port` 的替代方案 |

463| `MCP_PROTOCOL_NEGOTIATION` | 在 [v2 MCP 用戶端執行時](/docs/zh-TW/mcp#mcp-client-runtimes) 上，Claude Code 是否探測伺服器以了解 MCP 協議修訂 2026-07-28。設定 `auto` 以探測 HTTP、claude.ai 連接器和 stdio 伺服器；不回答探測的伺服器在較早的協議上連線，SSE 和 WebSocket 伺服器始終這樣做。設定 `legacy` 以跳過每個伺服器的探測。沒有變數，Claude Code 在 Claude Code v2.1.232 或更新版本上探測 HTTP 和 claude.ai 連接器伺服器，但 [MCP 用戶端執行時](/docs/zh-TW/mcp#mcp-client-runtimes) 部分列出的例外。任何其他值被忽略，並在偵錯日誌中出現警告。需要 Claude Code v2.1.221 或更新版本 |

465| `MCP_SDK_GENERATION` | 釘選此程序連線 MCP 伺服器的 [MCP 用戶端執行時](/docs/zh-TW/mcp#mcp-client-runtimes)：`v1`，建立在 MCP TypeScript SDK 1.x 上，或 `v2`，建立在 [MCP TypeScript SDK 2.0](https://ts.sdk.modelcontextprotocol.io/v2/)。沒有變數，Claude Code 在 Claude Code v2.1.232 或更新版本上使用 v2，除了該部分說明它使用 v1 的地方。在 Claude Code v2.1.221 或更新版本上，v2 執行時檢查 MCP OAuth 伺服器在其授權回應中返回的簽發者，並在不符合時使用以 `Issuer mismatch in authorization response` 開頭的錯誤失敗登入。v1 執行時不執行此檢查。如果您設定無法識別的值，Claude Code 會忽略它並寫入偵錯日誌的警告。Claude Code 每個程序讀取一次值。需要 Claude Code v2.1.218 或更新版本 |

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

372| `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](/docs/zh-TW/monitoring-usage#assistant-response-event) |470| `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` | 標準 OpenTelemetry SDK 屬性值長度限制。Claude Code 將內容承載遙測屬性上限為此和 `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 中的較小值，因此截斷標記保持在 SDK 限制內。Claude Code 以相同方式讀取 `OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT` 和 `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` 變體，最小設定值適用於所有信號。需要 Claude Code v2.1.214 或更新版本。請參閱 [監控](/docs/zh-TW/monitoring-usage#common-configuration-variables) |

373| `OTEL_LOG_RAW_API_BODIES` | 設定為 `1` 以將完整的 Anthropic Messages API 請求和回應 JSON 作為 `api_request_body` / `api_response_body` 日誌事件發出（在 60 KB 處截斷），或 `file:<dir>` 以將未截斷的主體寫入磁碟並發出 `body_ref` 路徑。預設停用；主體包括整個對話歷史記錄。請參閱 [Monitoring](/docs/zh-TW/monitoring-usage#api-request-body-event) |471| `OTEL_LOG_ASSISTANT_RESPONSES` | 設定為 `1` 以在 `assistant_response` OpenTelemetry 日誌事件上包含模型的回應文字。未設定時，使用 `OTEL_LOG_USER_PROMPTS` 的值。設定為 `0` 以保持回應編輯，即使 `OTEL_LOG_USER_PROMPTS` 設定。需要 Claude Code v2.1.193 或更新版本。請參閱 [監控](/docs/zh-TW/monitoring-usage#assistant-response-event) |

374| `OTEL_LOG_TOOL_CONTENT` | 設定為 `1` 以在 OpenTelemetry span 事件中包含工具輸入和輸出內容。預設停用以保護敏感資料。請參閱 [Monitoring](/docs/zh-TW/monitoring-usage) |472| `OTEL_LOG_RAW_API_BODIES` | 發出 Anthropic Messages API 請求和回應 JSON 作為 `api_request_body` / `api_response_body` 日誌事件。設定為 `1` 用於在內容限制處截斷的內聯主體，或 `file:<dir>` 以將未截斷的主體寫入磁碟並改為發出 `body_ref` 路徑。`CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 配置內容限制，預設 60 KB。預設停用；主體包含整個對話歷史記錄。在您的 shell、使用者設定或受管設定中設定它。在 [專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env) 中忽略。請參閱 [監控](/docs/zh-TW/monitoring-usage#api-request-body-event) |

375| `OTEL_LOG_TOOL_DETAILS` | 設定為 `1` 以在 OpenTelemetry 追蹤和日誌中包含工具輸入引數、MCP 伺服器名稱、工具失敗時的原始錯誤字串、`api_refusal` 事件上的拒絕 `category` 和其他工具詳細資訊。預設停用以保護個人識別資訊。請參閱 [Monitoring](/docs/zh-TW/monitoring-usage) |473| `OTEL_LOG_TOOL_CONTENT` | 設定為 `1` 以在 OpenTelemetry 跨度事件中包含工具輸入和輸出內容。預設停用以保護敏感資料。請參閱 [監控](/docs/zh-TW/monitoring-usage) |

376| `OTEL_LOG_USER_PROMPTS` | 設定為 `1` 以在 OpenTelemetry 追蹤和日誌中包含使用者提示文字。預設停用（提示被編輯）。請參閱 [Monitoring](/docs/zh-TW/monitoring-usage) |474| `OTEL_LOG_TOOL_DETAILS` | 設定為 `1` 以在 OpenTelemetry 追蹤和日誌中包含工具輸入引數、MCP 伺服器名稱、使用者撰寫的工作流程名稱、工具失敗上的原始錯誤字串、`api_refusal` 事件上的拒絕 `category` 和其他工具詳細資訊。預設停用以保護 PII。請參閱 [監控](/docs/zh-TW/monitoring-usage) |

377| `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` | 設定為 `false` 以從指標屬性中排除帳戶 UUID（預設值：包含）。請參閱 [Monitoring](/docs/zh-TW/monitoring-usage) |475| `OTEL_LOG_USER_PROMPTS` | 設定為 `1` 以在 OpenTelemetry 追蹤和日誌中包含使用者提示文字。預設停用（提示被編輯）。請參閱 [監控](/docs/zh-TW/monitoring-usage) |

378| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | {{/* min-version: 2.1.152 */}}設定為 `true` 以在指標屬性中包含工作階段進入點（預設值：排除）。在 v2.1.152 中新增。請參閱 [Monitoring](/docs/zh-TW/monitoring-usage) |476| `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` | 設定為 `false` 以從指標屬性中排除帳戶 UUID（預設值：包含）。請參閱 [監控](/docs/zh-TW/monitoring-usage) |

379| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | {{/* min-version: 2.1.161 */}}自 v2.1.161 起，Claude Code 將 `OTEL_RESOURCE_ATTRIBUTES` 金鑰附加到指標資料點標籤。設定為 `false` 以排除它們（預設值：包含）。請參閱 [Monitoring](/docs/zh-TW/monitoring-usage#multi-team-organization-support) |477| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | 設定為 `true` 以在指標屬性中包含工作階段進入點（預設值：排除）。在 v2.1.152 中新增。請參閱 [監控](/docs/zh-TW/monitoring-usage) |

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

382| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | 覆蓋顯示給 [Skill tool](/docs/zh-TW/skills#control-who-invokes-a-skill) 的 skill 中繼資料的字元預算。預算在上下文視窗的 1% 處動態縮放，回退為 8,000 個字元。為了向後相容性保留舊名稱 |480| `OTEL_METRICS_INCLUDE_VERSION` | 設定為 `true` 以在指標屬性中包含 Claude Code 版本（預設值：排除）。請參閱 [監控](/docs/zh-TW/monitoring-usage) |

383| `TASK_MAX_OUTPUT_LENGTH` | [subagent](/docs/zh-TW/sub-agents) 輸出在截斷前的最大字元數（預設值：32000，最大值：160000）。截斷時，完整輸出會儲存到磁碟，路徑會包含在截斷的回應中 |481| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | 覆蓋 [Skill 工具](/docs/zh-TW/skills#control-who-invokes-a-skill) 顯示的 skill 中繼資料的字元預算。預算在上下文視窗的 1% 處動態縮放，回退為 8,000 字元。為向後相容性保留的舊名稱 |

384| `USE_BUILTIN_RIPGREP` | 設定為 `0` 以使用系統安裝的 `rg` 而不是 Claude Code 隨附的 `rg` |482| `TASK_MAX_OUTPUT_LENGTH` | [背景工作](/docs/zh-TW/tools-reference#background-commands) 輸出的最大字元數，`TaskOutput` 工具保持（預設值：32000；最大值：160000）。如果您設定 [`taskOutputMaxChars`](/docs/zh-TW/settings-reference#taskoutputmaxchars) 設定，Claude Code 會忽略此變數 |

395| `VERTEX_REGION_CLAUDE_4_7_OPUS` | {{/* min-version: 2.1.111 */}}使用 Google Cloud's Agent Platform 時覆蓋 Claude Opus 4.7 的區域。在 v2.1.111 中新增 |493| `VERTEX_REGION_CLAUDE_4_6_SONNET` | 使用 Google Cloud 的 Agent Platform 時，覆蓋 Claude Sonnet 4.6 的區域 |

396| `VERTEX_REGION_CLAUDE_4_8_OPUS` | {{/* min-version: 2.1.154 */}}使用 Google Cloud's Agent Platform 時覆蓋 Claude Opus 4.8 的區域。在 v2.1.154 中新增 |494| `VERTEX_REGION_CLAUDE_4_7_OPUS` | 使用 Google Cloud 的 Agent Platform 時，覆蓋 Claude Opus 4.7 的區域 |

397| `VERTEX_REGION_CLAUDE_5_SONNET` | {{/* min-version: 2.1.197 */}}使用 Google Cloud's Agent Platform 時覆蓋 Claude Sonnet 5 的區域。在 v2.1.197 中新增 |495| `VERTEX_REGION_CLAUDE_4_8_OPUS` | 使用 Google Cloud 的 Agent Platform 時，覆蓋 Claude Opus 4.8 的區域 |

398| `VERTEX_REGION_CLAUDE_FABLE_5` | {{/* min-version: 2.1.170 */}}使用 Google Cloud's Agent Platform 時覆蓋 Claude Fable 5 的區域。在 v2.1.170 中新增 |496| `VERTEX_REGION_CLAUDE_5_OPUS` | 使用 Google Cloud 的 Agent Platform 時，覆蓋 Claude Opus 5 的區域。在 v2.1.219 中新增 |

~~400~~ 498| `VERTEX_REGION_CLAUDE_FABLE_5` | 使用 Google Cloud 的 Agent Platform 時，覆蓋 Claude Fable 5 的區域。在 v2.1.170 中新增 |

401標準 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](/docs/zh-TW/monitoring-usage) 以取得配置詳細資訊。499| `VERTEX_REGION_CLAUDE_FABLE_5_1` | 使用 Google Cloud 的 Agent Platform 時，覆蓋 Claude Fable 5.1 的區域。在 v2.1.257 中新增 |

500| `VERTEX_REGION_CLAUDE_HAIKU_4_5` | 使用 Google Cloud 的 Agent Platform 時，覆蓋 Claude Haiku 4.5 的區域 |

501

502標準 OpenTelemetry 匯出器變數（`OTEL_METRICS_EXPORTER`、`OTEL_LOGS_EXPORTER`、`OTEL_EXPORTER_OTLP_ENDPOINT`、`OTEL_EXPORTER_OTLP_PROTOCOL`、`OTEL_EXPORTER_OTLP_HEADERS`、`OTEL_METRIC_EXPORT_INTERVAL`、`OTEL_RESOURCE_ATTRIBUTES` 和信號特定變體）也受支援。請參閱 [監控](/docs/zh-TW/monitoring-usage) 以了解設定詳細資訊。

503

504<h2 id="features-that-need-feature-flag-fetching">

505 需要功能旗標擷取的功能

506</h2>

507

508Claude Code 透過從 Anthropic 擷取的功能旗標來啟用某些功能。Claude Code 在以下工作階段中會跳過該擷取：

509

510* 設定 `DISABLE_GROWTHBOOK`、`DISABLE_TELEMETRY`、`DO_NOT_TRACK` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 的工作階段；[變數表](#variables)中每個變數的列會說明哪些值會關閉擷取

511* [第三方提供者](/docs/zh-TW/third-party-integrations)上的工作階段，例如 Amazon Bedrock、AWS 上的 Claude Platform、Google Cloud 的 Agent Platform 或 Microsoft Foundry，除非嵌入 Claude Code 的主機平台設定 `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`

512* [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway)工作階段

513

514擷取關閉時，您無法：

515

516* 在 Pro、Max 和 Team 方案上[預設以自動模式啟動工作階段](/docs/zh-TW/permission-modes#which-mode-a-session-starts-in)

517* 讓 VS Code 擴充功能[讀取設定檔以取得起始權限模式](/docs/zh-TW/permission-modes#switch-permission-modes)

518* 執行 [`/auto-mode-setup`](/docs/zh-TW/auto-mode-config#generate-environment-entries) 來草擬 `autoMode.environment` 項目

519* 使用[遠端控制](/docs/zh-TW/remote-control#requirements)

520* [訊息工作階段超越此機器](/docs/zh-TW/cross-session-messaging#message-sessions-on-other-machines)；此機器上工作階段之間的訊息傳遞在擷取關閉時可運作

521* 執行 [`claude import` 或 `/import` 命令](/docs/zh-TW/cli-reference#cli-commands)

522* 執行 [`/skill-doctor`](/docs/zh-TW/skills#find-unused-skills) 或在 `/plugin` **Stats** 標籤中開啟其報告

523* 使用[顧問工具](/docs/zh-TW/advisor#requirements)

524* 讀取或回覆[成品上的評論](/docs/zh-TW/artifacts#collect-comments-on-an-artifact)

525* 在不設定 `MCP_SDK_GENERATION` 和 `MCP_PROTOCOL_NEGOTIATION` 的情況下取得 [v2 MCP 用戶端執行階段](/docs/zh-TW/mcp#mcp-client-runtimes)及其協定探測；Claude Code 使用 v1 執行階段，除非您設定 `MCP_SDK_GENERATION=v2`，並且除非您設定 `MCP_PROTOCOL_NEGOTIATION=auto` 否則會跳過探測

526* 在安裝 Git Bash 的 Windows 上預設為 claude.ai 和 Console 帳戶取得 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool)；Claude Code 透過 Git Bash 路由 Shell 命令，除非您設定 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`。在沒有 Git Bash 的 Windows 上，工具保持開啟

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

528* 讓 Claude Code [排除 MCP 工具，其輸入結構描述 API 會拒絕](/docs/zh-TW/mcp#tools-with-invalid-input-schemas)；它仍會傳送結構描述，包含它的請求會失敗，並出現[命名工具位置的 400 錯誤](/docs/zh-TW/errors#tool-input-schema-is-invalid)

529

530<h3 id="first-session-after-an-install-or-upgrade">

531 安裝或升級後的第一個工作階段

532</h3>

533

534在您安裝 Claude Code 或升級到新增功能的版本後的第一個工作階段中，[旗標閘道功能](#features-that-need-feature-flag-fetching)可能會遺失，工作階段可能會在原本以自動模式啟動的方案上以手動模式啟動。Claude Code 在該工作階段期間擷取旗標，因此兩者都會在您的下一個工作階段中出現。

535

536在全新安裝後，在非互動式工作階段（例如 `claude -p`、Agent SDK 或 VS Code 擴充功能）中，Claude Code 仍可在[選擇起始權限模式](/docs/zh-TW/permission-modes#which-mode-a-session-starts-in)之前擷取旗標。

402 537

403<h2 id="see-also">538<h2 id="see-also">

404 另請參閱539 另請參閱

errors.md +3484 −637

Details

6 6

7> 查詢 Claude Code 執行時錯誤訊息，了解每個錯誤的含義及修復方法。7> 查詢 Claude Code 執行時錯誤訊息，了解每個錯誤的含義及修復方法。

8 8

9本頁列出 Claude Code 顯示的執行時錯誤及如何從每個錯誤中恢復，以及當回應似乎有問題但沒有錯誤時要檢查的內容。如需安裝錯誤（例如 `command not found` 或設定期間的 TLS 失敗），請參閱 [Troubleshoot installation and login](/docs/zh-TW/troubleshoot-install)。9本頁列出 Claude Code 顯示的執行時錯誤及如何從每個錯誤中復原，以及當回應似乎有問題但沒有錯誤時要檢查的內容。如需安裝錯誤（例如 `command not found` 或設定期間的 TLS 失敗），請參閱[疑難排解安裝和登入](/docs/zh-TW/troubleshoot-install)。

10 10

11這些錯誤和恢復命令適用於 CLI、[Desktop app](/docs/zh-TW/desktop) 和 [Claude Code on the web](/docs/zh-TW/claude-code-on-the-web)，因為這三者都包裝相同的 Claude Code CLI。如需特定表面的問題，請參閱該表面頁面上的疑難排解部分。11除了[包裝程式和 IDE 錯誤](#wrapper-and-ide-errors)（由啟動程式列印而非 Claude Code 本身列印）外，這些錯誤和復原命令適用於 CLI、[桌面應用程式](/docs/zh-TW/desktop)和 [Claude Code 網頁版](/docs/zh-TW/claude-code-on-the-web)，因為這三者都包裝相同的 Claude Code CLI。如需其他表面特定的問題，請參閱該表面頁面上的疑難排解部分。

12 12

13<Note>13<Note>

14 Claude Code 呼叫 Claude API 以取得模型回應，因此大多數執行時錯誤對應到基礎 API 錯誤代碼。本頁涵蓋每個錯誤在 Claude Code 中的含義及如何恢復。如需原始 HTTP 狀態代碼定義，請參閱 [Claude Platform error reference](https://platform.claude.com/docs/en/api/errors)。14 Claude Code 呼叫 Claude API 以取得模型回應，因此大多數執行時錯誤對應到基礎 API 錯誤代碼。本頁涵蓋每個錯誤在 Claude Code 中的含義及如何復原。如需原始 HTTP 狀態代碼定義，請參閱 [Claude Platform 錯誤參考](https://platform.claude.com/docs/en/api/errors)。

15</Note>15</Note>

16 16

17<h2 id="find-your-error">17<h2 id="find-your-error">

~~18 尋找您的錯誤~~18 找到您的錯誤

19</h2>19</h2>

20 20

~~21將您在終端中看到的訊息與下方的部分相符。~~21將您看到的訊息與下面的部分進行比對。

22 22

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

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

~~30| `<model> is temporarily unavailable, so auto mode cannot determine the safety of...` | [Server errors](#auto-mode-cannot-determine-the-safety-of-an-action) |~~30| `Connection lost mid-response` / `Your computer went to sleep mid-response` / `The response stopped arriving` | [伺服器錯誤](#the-response-above-may-be-incomplete) |

~~31| `Auto mode could not evaluate this action and is blocking it for safety` | [Server errors](#auto-mode-cannot-determine-the-safety-of-an-action) |~~31| `Connection closed mid-response` / `Response stalled mid-stream` | [伺服器錯誤](#the-response-above-may-be-incomplete) |

~~32| `Auto mode classifier transcript exceeded context window` | [Server errors](#auto-mode-cannot-determine-the-safety-of-an-action) |~~32| `Connection lost before a response was produced` / `Your computer went to sleep before a response was produced` / `The response stalled before a response was produced` | [自動重試](#automatic-retries) |

~~40| `Could not resolve authentication method` | [Authentication](#could-not-resolve-authentication-method) |~~40| `You've hit your session limit` / `You've hit your weekly limit` / `You've hit your Opus limit` / `You've hit your Sonnet limit` | [使用限制](#youve-hit-your-session-limit) |

56| `Waiting for API response · will retry in` | [Automatic retries](#automatic-retries)，或如果持續發生，則為 [Network](#unable-to-connect-to-api) |56| `Your organization has disabled API key authentication` | [驗證](#your-organization-has-disabled-api-key-authentication) |

~~57| `Bedrock streaming response has content-type "..."; expected "application/vnd.amazon.eventstream"` | [Network](#bedrock-streaming-response-has-an-unexpected-content-type) |~~57| `Your organization has disabled Claude subscription access` | [驗證](#your-organization-has-disabled-claude-subscription-access) |

~~67| `PDF too large` / `PDF is password protected` | [Request errors](#pdf-errors) |~~67| `Remote Control stopped — the app running this session is now signed in to a different Claude account` | [驗證](#remote-control-stopped-because-the-app-running-the-session-signed-out-or-switched-accounts) |

~~68| `Extra inputs are not permitted` | [Request errors](#extra-inputs-are-not-permitted) |~~68| `Remote Control stopped — the app running this session is signed out of Claude` | [驗證](#remote-control-stopped-because-the-app-running-the-session-signed-out-or-switched-accounts) |

~~73| `thinking.type.enabled is not supported for this model` | [Request errors](#thinking-type-enabled-is-not-supported-for-this-model) |~~73| `Administrator policy requires a Cloud gateway sign-in on this machine` | [驗證](#administrator-policy-requires-a-cloud-gateway-sign-in) |

~~75| `API Error: 400 due to tool use concurrency issues` | [Request errors](#tool-use-or-thinking-block-mismatch) |~~75| `Your account is on hold and can't use Claude Code. View details or appeal: https://claude.ai/restricted` | [驗證](#your-account-is-on-hold) |

~~76| `Claude Code is unable to respond to this request, which appears to violate our Usage Policy` | [Request errors](#usage-policy-refusal) |~~76| `Your account is on hold and can't sign in to Claude Code. View details or appeal: https://claude.ai/restricted` | [驗證](#your-account-is-on-hold) |

~~77| `<model> has safety measures that flagged this message for a cybersecurity topic` | [Request errors](#safety-measures-flagged-a-cybersecurity-topic) |~~77| `Anthropic profile login expired · Re-authenticate your Anthropic profile` | [驗證](#anthropic-profile-login-expired) |

~~78| `Installation was killed before it could finish (exit code 137)` | [Installation errors](#installation-was-killed-before-it-could-finish) |~~78| `Anthropic profile login expired · Run /login to use your claude.ai account instead, or re-authenticate the profile` | [驗證](#anthropic-profile-login-expired) |

~~86| `references ${user_config.*} in a shell-form command` | [Plugin errors](#plugin-command-references-user-config) |~~86| `Could not load AWS credentials` / `Could not load Google Cloud credentials` | [驗證](#could-not-load-aws-or-google-cloud-credentials) |

~~87| `Monitor "<name>" from plugin <plugin> references ${user_config.*} in its command` | [Plugin errors](#plugin-command-references-user-config) |~~87| `AWS default-chain credential resolve timed out` | [驗證](#aws-default-chain-credential-resolve-timed-out) |

~~88| `headersHelper for MCP server '<name>' references ${user_config.*}` | [Plugin errors](#plugin-command-references-user-config) |~~88| `Timed out after 60s waiting for AWS` | [驗證](#bedrock-setup-verification-timed-out-waiting-for-aws) |

~~89| `would be spawned with zero tools — refusing` | [Tool errors](#agent-would-be-spawned-with-zero-tools) |~~89| `A request to AWS timed out. Check your network and proxy settings, then try again.` | [驗證](#bedrock-setup-verification-timed-out-waiting-for-aws) |

~~90| `File is covered by a Read deny rule in your permission settings` | [Tool errors](#file-is-covered-by-a-read-deny-rule) |~~90| `Could not load the default credentials` on Google Cloud's Agent Platform | [驗證](#could-not-load-aws-or-google-cloud-credentials) |

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

~~93| `Ignoring N permissions.allow entries from ... this workspace has not been trusted` | [Configuration warnings](#workspace-has-not-been-trusted) |~~93| `Unable to connect to Anthropic services` during setup | [網路](#unable-to-connect-to-anthropic-services) |

95| `Waiting for API response · will retry in` | [自動重試](#automatic-retries)，或如果持續發生，則為[網路](#unable-to-connect-to-api) |

96| `API returned an empty or malformed response` | [網路](#api-returned-an-empty-or-malformed-response) |

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

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

99| `SSL certificate verification failed` | [網路](#ssl-certificate-errors) |

100| `SSL certificate error (...)` during login or startup | [網路](#ssl-certificate-errors) |

101| `unable to get local issuer certificate` | [網路](#ssl-certificate-errors) |

102| `403` with `x-deny-reason: host_not_allowed` in a cloud or routine session | [網路](#host-not-allowed-in-a-cloud-session) |

103| `proxy refused the connection` | [網路](#the-proxy-refused-the-connection) |

104| `403` with `This GraphQL query is not enabled for this session` in a cloud session | [GitHub proxy](/docs/zh-TW/cloud-environments#github-proxy) |

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

106| `Couldn't reconnect to your Remote Control session` | [網路](#couldnt-reconnect-to-your-remote-control-session) |

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

108| `Couldn't share the transcript.` | [網路](#couldnt-share-the-transcript) |

109| `Prompt is too long` / `Input is too long for requested model` | [請求錯誤](#prompt-is-too-long) |

110| `Prompt is too long · automatic compaction failed:` | [請求錯誤](#prompt-is-too-long) |

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

112| `Context limit reached · /compact or /clear to continue` | [請求錯誤](#prompt-is-too-long) |

113| `Context limit reached · /clear to continue` | [請求錯誤](#prompt-is-too-long) |

114| `capability_rejected: prompt_too_long` on a Claude apps gateway session | [請求錯誤](#prompt-is-too-long) |

115| `upstream rejected the request` / `request too large for this upstream` on a Claude apps gateway session | [上游錯誤訊息](/docs/zh-TW/claude-apps-gateway-config#upstream-error-messages) |

116| `upstream rate limit exceeded` on a Claude apps gateway session | [上游錯誤訊息](/docs/zh-TW/claude-apps-gateway-config#upstream-error-messages) |

117| `all upstreams failed (N attempted)` on a Claude apps gateway session | [上游錯誤訊息](/docs/zh-TW/claude-apps-gateway-config#upstream-error-messages) |

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

119| `Context exceeds the ...-token limit by ... tokens` in `/context` output | [請求錯誤](#context-exceeds-the-token-limit) |

120| `Error during compaction: Conversation too long` | [請求錯誤](#error-during-compaction-conversation-too-long) |

121| `Request too large` | [請求錯誤](#request-too-large) |

122| `Request too large for the API's 32MB request limit` | [請求錯誤](#request-too-large) |

123| `Image was too large` | [請求錯誤](#image-was-too-large) |

124| `Unable to resize image` | [請求錯誤](#unable-to-resize-image) |

125| `PDF too large` / `PDF is password protected` | [請求錯誤](#pdf-errors) |

126| `Extra inputs are not permitted` | [請求錯誤](#extra-inputs-are-not-permitted) |

127| `API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid` / `Property keys should match pattern` | [請求錯誤](#tool-input-schema-is-invalid) |

128| `There's an issue with the selected model` | [請求錯誤](#theres-an-issue-with-the-selected-model) |

129| `Model ... is not a recognized model id` | [請求錯誤](#model-is-not-a-recognized-model-id) |

130| `Model ... not found` | [請求錯誤](#model-not-found) |

131| `Claude Opus is not available with the Claude Pro plan` | [請求錯誤](#claude-opus-is-not-available-with-the-claude-pro-plan) |

132| `Claude Code ... does not support this model; version ... or newer is required` | [請求錯誤](#claude-code-does-not-support-this-model) |

133| `Claude Code ... is older than the minimum version required by your organization's policy` | [請求錯誤](#claude-code-does-not-support-this-model) |

134| `Model ... is restricted by your organization's settings` | [請求錯誤](#model-is-restricted-by-your-organizations-settings) |

135| `Model switch ... blocked by a PreModelSwitch hook` | [請求錯誤](#model-switch-was-blocked-by-a-premodelswitch-hook) |

136| `couldn't save it as your default` / `couldn't confirm it was saved as your default` | [請求錯誤](#couldnt-save-it-as-your-default) |

137| `thinking.type.enabled is not supported for this model` | [請求錯誤](#thinking-type-enabled-is-not-supported-for-this-model) |

138| `Effort '<level>' isn't available with thinking turned off on this model` | [請求錯誤](#effort-isnt-available-with-thinking-turned-off) |

139| `effort '<level>' is not supported when thinking is disabled` | [請求錯誤](#effort-isnt-available-with-thinking-turned-off) |

140| `max_tokens must be greater than thinking.budget_tokens` | [請求錯誤](#thinking-budget-exceeds-output-limit) |

141| `API Error: 400 due to tool use concurrency issues` | [請求錯誤](#tool-use-or-thinking-block-mismatch) |

142| `[Unsupported tool content removed]` | [請求錯誤](#unsupported-tool-content-removed) |

143| `server_tool_use.name: Input should be` on every turn of a resumed session | [請求錯誤](#unsupported-tool-content-removed) |

144| `<model> can't help with this. Start a new session to continue` | [請求錯誤](#usage-policy-refusal) |

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

146| `<model>'s safeguards flagged this message` | [請求錯誤](#safety-measures-flagged-a-cybersecurity-topic) |

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

148| `Installation was killed before it could finish (exit code 137)` | [安裝錯誤](#installation-was-killed-before-it-could-finish) |

149| `The connection dropped while downloading the update` | [安裝錯誤](#the-connection-dropped-while-downloading-the-update) |

150| `Download timed out: exceeded the total deadline` | [安裝錯誤](#the-connection-dropped-while-downloading-the-update) |

151| `--bg and --print conflict` | [命令列錯誤](#command-line-errors) |

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

153| `Error: --json-schema is not a valid JSON Schema` | [命令列錯誤](#command-line-errors) |

154| `Error: Invalid --agents configuration:` | [命令列錯誤](#invalid-agents-configuration) |

155| `Error: Settings file exceeds the 2MiB limit` | [命令列錯誤](#settings-file-exceeds-the-2mib-limit) |

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

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

158| `Error: Workspace not trusted` when starting Remote Control | [命令列錯誤](#workspace-not-trusted-when-starting-remote-control) |

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

160| `` `claude import` is not yet available in this build `` | [命令列錯誤](#claude-import-is-not-yet-available-in-this-build) |

161| `Could not read Claude Code config` | [命令列錯誤](#could-not-read-claude-code-config) |

162| `Could not import <server>: <reason>` | [命令列錯誤](#could-not-import-a-server-from-claude-desktop) |

163| `Cannot add MCP server to scope: managed` | [命令列錯誤](#cannot-add-mcp-server-to-the-managed-scope) |

164| `is Anthropic-hosted and doesn't support local OAuth` | [命令列錯誤](#anthropic-hosted-and-doesnt-support-local-oauth) |

165| `Can't read .mcp.json: it isn't a regular file or is larger than 2097152 bytes` | [命令列錯誤](#cant-read-mcp-json) |

166| `Server rejected the Authorization header minted by the configured headersHelper` | [命令列錯誤](#server-rejected-the-authorization-header-minted-by-the-configured-headershelper) |

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

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

169| `Shell command failed for pattern "..."`, from `/security-review` or any skill that injects dynamic context | [命令列錯誤](#security-review-fails-without-origin-head) |

170| `Shell command permission check failed for pattern "..."`, from a skill that injects dynamic context | [命令列錯誤](#security-review-fails-without-origin-head) |

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

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

173| `Error: Input contained only whitespace` | [命令列錯誤](#input-contained-only-whitespace) |

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

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

176| `Unknown command: /<name>`, with or without a `Did you mean` suggestion | [命令列錯誤](#unknown-command) |

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

178| `Could not find merge-base with <branch>` | [命令列錯誤](#could-not-find-merge-base-with-the-base-branch) |

179| `Your checkout has no branches (detached HEAD only)` | [命令列錯誤](#your-checkout-has-no-branches) |

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

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

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

183| `Failed to resume the conversation` | [命令列錯誤](#failed-to-resume-the-conversation) |

184| `No conversation found with session ID: <session-id>` | [命令列錯誤](#no-conversation-found-with-the-session-id) |

185| `Cannot switch renderers in this session` | [命令列錯誤](#cannot-switch-renderers-in-this-session) |

186| `Cannot switch renderers while work is running in the background` | [命令列錯誤](#cannot-switch-renderers-in-this-session) |

187| `Couldn't read your Zed keymap` / `Couldn't back up your Zed keymap` / `Couldn't update your Zed keymap` | [命令列錯誤](#terminal-setup-left-your-zed-keymap-unchanged) |

188| `Your Zed keymap isn't a readable list of keybindings` | [命令列錯誤](#terminal-setup-left-your-zed-keymap-unchanged) |

189| `Skill usage reports are not available on this connection.` | [命令列錯誤](#skill-usage-reports-are-not-available-on-this-connection) |

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

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

192| `references ${user_config.*} in a shell-form command` | [Plugin 錯誤](#plugin-command-references-user-config) |

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

194| `headersHelper for MCP server '<name>' references ${user_config.*}` | [Plugin 錯誤](#plugin-command-references-user-config) |

195| `Plugin archive integrity check failed` | [Plugin 錯誤](#plugin-archive-integrity-check-failed) |

196| `path escapes plugin directory` | [Plugin 錯誤](#path-escapes-plugin-directory) |

197| `path could not be checked` | [Plugin 錯誤](#path-could-not-be-checked) |

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

199| `Plugin source path refused` | [Plugin 錯誤](#marketplace-entry-path-does-not-stay-inside-the-marketplace-directory) |

200| `Failed to load marketplace configuration` | [Plugin 錯誤](#failed-to-load-marketplace-configuration) |

201| `Marketplace configuration file is corrupted` | [Plugin 錯誤](#failed-to-load-marketplace-configuration) |

202| `would be spawned with zero tools — refusing` | [工具錯誤](#agent-would-be-spawned-with-zero-tools) |

203| `File is covered by a Read deny rule in your permission settings` | [工具錯誤](#file-is-covered-by-a-read-deny-rule) |

204| `subagent_type is required: the general-purpose agent is not available in this session` | [工具錯誤](#subagent-type-is-required) |

205| `Error: this write left the memory index at MEMORY.md at ..., over its ... read limit` | [工具錯誤](#memory-index-is-over-its-read-limit) |

206| `pkill: refusing to run` | [工具錯誤](#pkill-pattern-matches-the-claude-code-process) |

207| `Failed to write to <name>'s inbox — nothing was sent` | [工具錯誤](#failed-to-write-to-a-teammate-inbox) |

208| `Failed to write the plan approval request to the lead's inbox — plan not submitted` | [工具錯誤](#failed-to-write-to-a-teammate-inbox) |

209| `Message too large for cross-session delivery` | [工具錯誤](#message-too-large-for-cross-session-delivery) |

210| `Too many messages to this session just now` | [工具錯誤](#too-many-messages-to-this-session-just-now) |

211| `Refusing to send: reply target is a symlink` / `Refusing to send: cannot vet reply target` | [工具錯誤](#refusing-to-send-a-cross-session-message) |

212| `Refusing to send: connected endpoint is not the expected process` / `Refusing to send: connected endpoint identity could not be read` | [工具錯誤](#refusing-to-send-a-cross-session-message) |

213| `Refusing to send: connected endpoint is not owned by this user` / `Refusing to send: connected endpoint owner could not be read` | [工具錯誤](#refusing-to-send-a-cross-session-message) |

214| `Refusing to send: connected endpoint is a different process with the expected pid` | [工具錯誤](#refusing-to-send-a-cross-session-message) |

215| `Refusing to read <path>: its symlink resolution changed after permission was checked` / `Refusing to search <path>: its symlink resolution changed after permission was checked` | [工具錯誤](#refusing-after-a-symlink-changed) |

216| `Refusing to write <path>: its parent-directory symlink resolution changed after permission was checked` / `Refusing to write <path>: it is a symbolic link. Write to the link's target path instead` | [工具錯誤](#refusing-after-a-symlink-changed) |

217| `Refusing to search <path>: a path one of its Read deny rules is written through changed while the search was being prepared` / `Refusing to search <path>: it could not be opened` | [工具錯誤](#refusing-after-a-symlink-changed) |

218| `its permission check expired before it ran (too many concurrent file operations)` / `ripgrep was found only by name on PATH` | [工具錯誤](#refusing-after-a-symlink-changed) |

219| `task output swap refused (tasks dir moved or linked)` | [工具錯誤](#task-output-swap-refused) |

220| `Command killed: its output file was replaced or could no longer be verified` | [工具錯誤](#task-output-swap-refused) |

221| `the source file is not valid UTF-8 text` / `the source file is not valid UTF-16 text` | [工具錯誤](#the-source-file-is-not-valid-utf-8-text) |

222| `the source file has the replacement character U+FFFD` | [工具錯誤](#the-source-file-is-not-valid-utf-8-text) |

223| `Can't open MCP settings while no terminal is attached to this background session` | [背景工作階段錯誤](#commands-refused-in-a-background-session) |

224| `Can't open MCP settings in a background session` | [背景工作階段錯誤](#commands-refused-in-a-background-session) |

225| `blocked because the path is spelled in a form that cannot be safely resolved` | [背景工作階段錯誤](#write-or-command-blocked-because-the-path-cannot-be-safely-resolved) |

226| `blocked because the path is network-shaped` | [背景工作階段錯誤](#write-or-command-blocked-because-the-path-names-a-network-location) |

227| `This session has no saved transcript` | [背景工作階段錯誤](#this-session-has-no-saved-transcript) |

228| `Can't open — this session is running in another terminal` | [背景工作階段錯誤](#this-session-is-running-in-another-terminal) |

229| `This conversation is already open in another running Claude session` | [背景工作階段錯誤](#this-session-is-running-in-another-terminal) |

230| `This session's saved conversation is no longer on disk` | [背景工作階段錯誤](#this-sessions-saved-conversation-is-no-longer-on-disk) |

231| `kept <id> — <n> unpushed commits on <branch>` | [背景工作階段錯誤](#worktree-has-commits-that-are-not-pushed-anywhere) |

232| `kept <id> — worktree has commits that are not pushed anywhere` | [背景工作階段錯誤](#worktree-has-commits-that-are-not-pushed-anywhere) |

233| `terminal host process died — press Enter to restart` / `This session's terminal host process died` | [背景工作階段錯誤](#terminal-host-process-died) |

234| `Session isn't responding` / `Press enter again to restart this session — it isn't responding` | [背景工作階段錯誤](#session-isnt-responding) |

235| `Session <id> was stopped while the respawn was in flight` | [背景工作階段錯誤](#session-was-stopped-while-the-respawn-was-in-flight) |

236| `This session was running agent '<name>', which is no longer available` | [背景工作階段錯誤](#session-agent-no-longer-available) |

237| `CLAUDE_CODE_PROCESS_WRAPPER: launcher ...` | [背景工作階段錯誤](#claude_code_process_wrapper-launcher-errors) |

238| `EUNKNOWN: unknown error, uv_spawn` | [背景工作階段錯誤](#eunknown-when-starting-a-background-session) |

239| `EACCES: permission denied, posix_spawn` | [背景工作階段錯誤](#eacces-when-starting-a-background-session) |

240| `exited before it became reachable` | [背景工作階段錯誤](#background-service-exited-before-it-became-reachable) |

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

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

243| `Claude Code process exited with code N` | [包裝程式和 IDE 錯誤](#claude-code-process-exited-with-code-n) |

244| `Could not locate the Claude CLI on PATH` | [包裝程式和 IDE 錯誤](#could-not-locate-the-claude-cli-on-path) |

245| `Restored the code, but skipped N files` | [Rewind 警告和錯誤](#restored-the-code-but-skipped-files) |

246| `No files were restored: N files failed (backup missing, or the file could not be updated)` | [Rewind 警告和錯誤](#no-files-were-restored) |

247| `Transcript writes are failing (...)` | [工作階段儲存警告](#transcript-writes-are-failing) |

248| `Transcript saving is off — CLAUDE_CODE_SKIP_PROMPT_HISTORY is set` | [工作階段儲存警告](#transcript-saving-is-off-skip-prompt-history) |

249| `Transcript saving is off — inherited CLAUDE_CODE_CHILD_SESSION marker` | [工作階段儲存警告](#transcript-saving-is-off-child-session-marker) |

250| `Claude Code's fullscreen renderer didn't finish starting last time on this machine` / `Claude Code's fullscreen renderer has repeatedly failed to start on this machine` | [設定警告](#fullscreen-failed-start-notice) |

251| `Claude Code exited after an unrecoverable interface error (...)` | [設定警告](#exited-after-an-unrecoverable-interface-error) |

252| `Agent descriptions are over the 15.0k-token limit` | [設定警告](#agent-descriptions-are-over-the-15000-token-limit) |

253| `Ignoring N permissions.allow entries from ... this workspace has not been trusted` | [設定警告](#workspace-has-not-been-trusted) |

254| `is a network path, which cannot be added as a working directory` | [設定警告](#working-directory-is-a-network-path) |

255| `Remote managed settings failed to load (<cause>)` | [設定警告](#remote-managed-settings-failed-to-load) |

256| `Managed settings were not approved; exiting without applying them.` | [設定警告](#managed-settings-were-not-approved) |

257| `MCP server <name> is blocked by enterprise managed policy` | [設定警告](#mcp-server-is-blocked-by-enterprise-managed-policy) |

258| `Managed settings document could not be parsed as a JSON object; none of its settings are in effect. Fix or remove it.` | [設定警告](#managed-settings-document-could-not-be-parsed) |

259| `Managed settings drop-in directory could not be read` | [設定警告](#managed-settings-document-could-not-be-parsed) |

260| `"crossSessionInbound" must be one of "accept", "hold", "refuse"` | [設定警告](#crosssessioninbound-must-be-one-of-accept-hold-refuse) |

261| `headersHelper not run — this workspace has no persisted trust` | [設定警告](#headershelper-not-run) |

262| `Invalid permission rule "..." was skipped: Malformed Tool(content) rule` | [設定警告](#malformed-tool-content-rule) |

263| `... is not matched by file permission checks` | [設定警告](#is-not-matched-by-file-permission-checks) |

264| `... has a wildcard before the rest of the command` | [設定警告](#has-a-wildcard-before-the-rest-of-the-command) |

265| `CLAUDE_CODE_DISABLE_1M_CONTEXT is set, but the 200K limit isn't enforced` | [設定警告](#the-200k-limit-isnt-enforced) |

266| `[claude-code:unrecognized_model]` | [設定警告](#unrecognized-model-id-on-a-request) |

267| `Stale sandbox mask files left by a killed session` | [設定警告](#stale-sandbox-mask-files-left-by-a-killed-session) |

268| 回應品質似乎比平常低 | [回應品質](#responses-seem-lower-quality-than-usual) |

95 269

96<h2 id="automatic-retries">270<h2 id="automatic-retries">

97 自動重試271 自動重試

98</h2>272</h2>

99 273

100Claude Code 在向您顯示錯誤之前會重試暫時性失敗。伺服器錯誤、過載回應、請求逾時、臨時 429 節流和中斷的連線都會以指數退避方式重試最多 10 次。自 v2.1.198 起，這涵蓋在任何可見輸出串流之前在回應中途中斷的連線：Claude Code 使用相同的退避重新發出請求，轉向繼續而不是停止並出現連線錯誤。自 v2.1.199 起，不帶您計畫配額標頭的臨時 429 節流在您使用 claude.ai 訂閱登入時也會重試；較早的版本僅針對 API 金鑰和 Enterprise 登入重試它們。274Claude Code 會在顯示錯誤之前，以指數退避方式重試暫時性故障最多 10 次。它不會總是重試在 Claude 回應中途出現的故障。當您看到本頁面上的其中一個錯誤時，Claude Code 已經對該故障進行了適用的重試；下面的清單說明哪些故障會獲得完整的重試預算、哪些會獲得較小的預算，以及哪些不會獲得任何預算。

101 275

102有些失敗類別不會重試，因為重試無法成功：276Claude Code 會重試這些故障：

103 277

104* 自 v2.1.199 起，TLS 憑證驗證失敗（例如 TLS 檢查代理、遺失的 `NODE_EXTRA_CA_CERTS` 套件或過期的憑證）在第一次嘗試時失敗，因此修復會立即出現，而不是在完整重試預算之後。請參閱 [SSL 憑證錯誤](#ssl-certificate-errors)。暫時性 TLS 條件（例如握手逾時）仍會重試。278* 伺服器錯誤、過載回應，以及在 Claude 回應開始串流之前到達的請求逾時。

105* 自 v2.1.199 起，在 Claude 已經串流可見輸出後到達的伺服器錯誤會保留部分回應並附加 [不完整回應通知](#the-response-above-may-be-incomplete)，而不是重試，因為重新執行請求可能會執行相同的工具兩次。較早的版本會捨棄部分輸出並將轉向報告為錯誤。279* 連線中斷。當連線在 Claude 完成其回應的任何部分（包括其思考）之前中途中斷時，Claude Code 會以相同的退避方式重新發出請求，並且回合會繼續，即使某些文字已經開始串流。當連線在 Claude 完成思考之後但在開始任何文字或工具呼叫之前中斷時，Claude Code 會改為快速連續重新發出請求最多兩次，如果連線在該點持續中斷，則以 `Connection lost before a response was produced` 結束回合。

106* [Amazon Bedrock 串流回應具有非預期的內容類型](#bedrock-streaming-response-has-an-unexpected-content-type)在第一次嘗試時失敗，因為重寫回應的閘道或代理會以相同方式重寫重試。需要 Claude Code v2.1.208 或更新版本。280* Claude Code 偵測到的連線在您的電腦進入睡眠狀態時在請求中途被中斷。Claude Code 將其計為上述規則下的連線中斷；一旦重試標籤命名了具體原因，它會讀作 `Connection lost while your computer was asleep`，如果回合在 Claude 完成思考但在任何文字或工具呼叫之前結束，訊息會讀作 `Your computer went to sleep before a response was produced`。

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

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

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

284 * 當您使用 claude.ai 訂閱登入時，這包括不帶有您計畫配額標頭的 429 節流。在 v2.1.199 之前，Claude Code 僅針對 API 金鑰和企業登入重試這些節流。

285* 因為輸入加上 `max_tokens` 超過內容限制而被拒絕的請求。以相同方式重新發送它會以相同方式失敗，所以 Claude Code 會以縮減的 `max_tokens` 重試，並在兩種情況下停止重試並改為壓縮：

286 * 當沒有縮減可以適應時，例如當對話本身幾乎填滿內容視窗時。

287 * 當重試無法進一步縮減 `max_tokens` 時。在 v2.1.218 之前，Claude Code 可以重新發送仍然不適應的縮減請求，例如當擴展思考預算超過剩餘內容時，直到重試預算用盡。

288* 在 [Google Cloud 的 Agent Platform](/docs/zh-TW/google-vertex-ai) 上過期或遺失的 Google Cloud 認證，或在您的機器上無法載入的 AWS 認證。Claude Code 會捨棄其快取的認證並重試最多兩次，然後報告錯誤，以便您可以立即重新驗證，如 [Could not load AWS or Google Cloud credentials](#could-not-load-aws-or-google-cloud-credentials) 下所述。在 v2.1.228 之前，Claude Code 會透過完整重試預算重試失敗的 Google Cloud 認證，然後才顯示錯誤。

289* 來自 Anthropic API 的 `401` 或 `403`，直接或透過 [LLM gateway](/docs/zh-TW/llm-gateway)，而 [`apiKeyHelper`](/docs/zh-TW/settings-reference#apikeyhelper) 指令碼提供認證。Claude Code 會重新執行指令碼並使用其新輸出重試，在完整重試預算內。當指令碼本身在重新執行時失敗時，Claude Code 會改為顯示 [Your apiKeyHelper script is failing](#your-apikeyhelper-script-is-failing)。

107 290

108重試時，微調器會在錯誤標籤後顯示 `Retrying in Ns · attempt x/y` 倒數計時。標籤命名第一次嘗試的特定原因，以便您可以立即採取行動的失敗：網路已關閉、TLS 握手失敗或您達到速率限制。對於其他錯誤，它最初讀取 `API error`。自 v2.1.198 起，它會切換到第三次嘗試的特定原因，或在 `CLAUDE_CODE_MAX_RETRIES` 允許少於三次時的最後一次嘗試；較早的版本僅在最後一次嘗試時切換。291在 v2.1.227 之前，`Connection lost before a response was produced` 讀作 `Connection closed while thinking, before producing a response`，`The response stalled before a response was produced` 讀作 `Response stalled while thinking, before producing a response`。

109 292

110自 v2.1.198 起，通常的微調器提示在重試期間被抑制。一旦錯誤原因被揭示，如果失敗是 529 過載，倒數計時下方的行也會命名檢查服務狀態的位置：Anthropic API 上的 `status.claude.com`，或其他配置上提供者或閘道主機命名的位置。293Claude Code 不會重試這些故障：

111 294

112如果在請求仍待處理時，回應串流上 20 秒內沒有資料到達，微調器會在任何重試開始之前顯示 `Waiting for API response · will retry in … · check your network`。請求尚未失敗：倒數計時會執行到 Claude Code 中止停滯連線並重試的位置，因此一旦資料恢復或重試成功，橫幅就會自動清除。自 v2.1.185 起，閾值為 20 秒；較早的版本會在 10 秒後顯示橫幅，措辭不同。如果它在每次嘗試時都重新出現，請將其視為[網路問題](#unable-to-connect-to-api)。295* TLS 憑證驗證失敗，例如 TLS 檢查代理、遺失的 `NODE_EXTRA_CA_CERTS` 套件，或過期的憑證。Claude Code 在第一次嘗試時報告錯誤，以便您可以立即修正憑證設定；請參閱 [SSL certificate errors](#ssl-certificate-errors)。Claude Code 仍會重試暫時性 TLS 條件，例如握手逾時。在 v2.1.199 之前，Claude Code 會透過完整重試預算重試憑證失敗，然後才顯示錯誤。

296* 伺服器錯誤、連線中斷，或停滯的串流在 Claude 完成文字區塊或工具呼叫之後到達，或在完成思考後開始一個但在完成回應之前。Claude Code 不會重新執行請求，因為這可能會執行相同的工具呼叫兩次。它會保留 Claude 完成的內容，執行 Claude 完成的任何工具呼叫，並從其結果繼續回合。關於您在互動式工作階段和非互動式工作階段中看到的內容，請閱讀 [The response above may be incomplete](#the-response-above-may-be-incomplete)。在 v2.1.199 之前，當伺服器錯誤在串流中途到達時，Claude Code 會捨棄部分輸出並將整個回合報告為錯誤。

297* 在 Claude 完成回應之後到達的故障：不需要重試任何內容，所以 Claude Code 會保留完整回應並正常結束回合。

298* [Amazon Bedrock 串流回應具有意外的 content-type](#bedrock-streaming-response-has-an-unexpected-content-type)，因為重寫回應的閘道或代理會以相同方式重寫重試。需要 Claude Code v2.1.208 或更新版本。

299* 失敗的串流請求的非串流重試獲得成功狀態但 [body 中沒有 Claude API 訊息](#api-returned-an-empty-or-malformed-response)。Claude Code 以該錯誤結束回合。

300* 您的組織的原則檢查拒絕的請求，其表現為帶有拒絕訊息的 `API Error:` 行。您的組織管理員使用 [Inference hooks](https://platform.claude.com/docs/en/manage-claude/inference-hooks)（Claude 企業功能）設定檢查，訊息以他們設定的指示結尾，或預設告訴您聯絡他們。Claude Code 不會將被拒絕的請求重新發送到相同的模型或 [fallback model](/docs/zh-TW/model-config#fallback-model-chains)，因為拒絕是關於請求的內容而不是模型。在 v2.1.239 之前，Claude Code 可以重新發送被拒絕的請求，不進行串流或在設定的後備模型上，然後才向您顯示拒絕。

113 301

114當您看到本頁上的其中一個錯誤時，這些重試已經用盡，除非它屬於不會重試的類別，例如憑證驗證失敗。您可以使用這些環境變數調整行為：302<h3 id="what-you-see-while-claude-code-retries-or-waits">

303 當 Claude Code 重試或等待時您看到的內容

304</h3>

305

306重試時，微調器在錯誤標籤後顯示 `Retrying in Ns · attempt x/y` 倒數計時。標籤命名第一次嘗試的具體原因，用於您可以立即採取行動的故障：網路已關閉、TLS 握手失敗，或您達到速率限制。對於其他錯誤，它最初讀作 `API error`。從 v2.1.198 開始，它會切換到第三次嘗試的具體原因，或當 `CLAUDE_CODE_MAX_RETRIES` 允許少於三次時在最後一次嘗試；較早的版本僅在最後一次嘗試時切換。

307

308從 v2.1.198 開始，在重試期間會隱藏通常的微調器提示。一旦錯誤原因被揭示，如果故障是 529 過載，倒數計時下方的行也會命名檢查服務狀態的位置：Anthropic API 上的 `status.claude.com`，或其他設定上的訊息中命名的提供者或閘道主機。

309

310如果在請求仍待處理時，回應串流上 20 秒內沒有資料到達，微調器會在任何重試開始之前顯示 `Waiting for API response · will retry in … · check your network`。請求尚未失敗：倒數計時執行到 Claude Code 中止停滯連線的點。中止後，您看到的內容取決於回應已進行的距離：

311

312* 在 Claude 完成文字區塊或工具呼叫之前，或在完成思考後開始一個，Claude Code 會重試請求或以錯誤結束回合。[Automatic retries](#automatic-retries) 說明它重試哪些停滯以及重試多少次。

313* 在 Claude 完成文字區塊或工具呼叫之後，或在完成思考後開始一個，但在 Claude 完成回應之前，Claude Code 會保留 Claude 完成的內容，從 Claude 完成的任何工具呼叫繼續回合，並顯示 [The response above may be incomplete](#the-response-above-may-be-incomplete)。在非互動式工作階段中，以及在任何工作階段中的子代理回應，Claude Code 可能會先提示 Claude 繼續回應；該項目說明何時執行以及何時您仍在那裡看到通知。

314* 在 Claude 完成回應之後，Claude Code 正常結束回合。

315

316一旦資料恢復或重試成功，橫幅會自動清除。如果它在每次嘗試時重新出現，請將其視為 [network issue](#unable-to-connect-to-api)。在 v2.1.185 之前，橫幅在 10 秒後出現，措辭不同。

317

318當 Claude 正在諮詢 [advisor](/docs/zh-TW/advisor) 時，橫幅在 90 秒無資料後出現，而不是 20 秒，因為長時間的顧問審查可以發送超過 20 秒的任何內容。在 v2.1.214 之前，20 秒的閾值也適用於顧問呼叫，所以橫幅在顧問審查期間出現，即使沒有任何問題。

319

320<h3 id="tune-retry-behavior">

321 調整重試行為

322</h3>

323

324您可以使用這些環境變數調整重試行為：

115 325

116| 變數 | 預設值 | 效果 |326| 變數 | 預設 | 效果 |

117| :---------------------------------------------- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |327| :------------------------------------------------------- | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

118| [`CLAUDE_CODE_MAX_RETRIES`](/docs/zh-TW/env-vars) | 10 | 重試次數。自 v2.1.186 起上限為 15；自 v2.1.199 起 `CLAUDE_CODE_RETRY_WATCHDOG` 提高預設值並移除上限。降低它以在指令碼中更快地顯示失敗。 |328| [`CLAUDE_CODE_MAX_RETRIES`](/docs/zh-TW/env-vars) | 10 | 重試嘗試次數。從 v2.1.186 開始上限為 15；從 v2.1.199 開始 `CLAUDE_CODE_RETRY_WATCHDOG` 會提高預設值並移除上限。降低它以在指令碼中更快地顯示故障。 |

119| [`CLAUDE_CODE_RETRY_WATCHDOG`](/docs/zh-TW/env-vars) | 未設定 | 在 CI 工作等無人值守的工作階段中設定為 `1`，以無限期重試 `429` 和 `529` 容量錯誤，而不是在 `CLAUDE_CODE_MAX_RETRIES` 次嘗試後失敗。自 v2.1.199 起，它也提高了其他暫時性錯誤（例如伺服器錯誤、逾時和中斷的連線）的預設重試計數至 300，大約三小時的退避，並在您明確設定該變數時移除 `CLAUDE_CODE_MAX_RETRIES` 的上限 15。 |329| [`CLAUDE_CODE_RETRY_WATCHDOG`](/docs/zh-TW/env-vars) | 未設定 | 在無人值守的工作階段（例如 CI 工作）中設定為 `1`，以無限期重試 `429` 和 `529` 容量錯誤，而不是在 `CLAUDE_CODE_MAX_RETRIES` 嘗試後失敗。Claude Code 在報告支出限制或耗盡使用額度的 `429` 上立即失敗，即使是來自 [gateway spend cap](#spend-limit-reached) 的重新設定排程。在 v2.1.239 之前，看門狗無限期重試這些。在 v2.1.199 或更新版本上，它也會提高其他暫時性錯誤（例如伺服器錯誤、逾時和連線中斷）的預設重試計數至 300，大約三小時的退避，如果您明確設定該變數，則移除 `CLAUDE_CODE_MAX_RETRIES` 的上限 15。 |

120| [`API_TIMEOUT_MS`](/docs/zh-TW/env-vars) | 600000 | 每個請求的逾時（毫秒）。為慢速網路或代理提高它。 |330| [`API_TIMEOUT_MS`](/docs/zh-TW/env-vars) | 600000 | 每個請求的逾時（毫秒）。為慢速網路或代理提高它。它也會上限 Claude Code 等待回應標頭的時間，如 [No response from API](#no-response-from-api) 中所述。 |

331| [`CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`](/docs/zh-TW/env-vars) | 未設定 | 串流請求的第一個回應位元組的截止時間（毫秒）。需要 Claude Code v2.1.242 或更新版本。關於當此未設定時 Claude Code 如何選擇截止時間，請參閱 [No response from API](#no-response-from-api)。 |

121 332

122<h2 id="server-errors">333<h2 id="server-errors">

123 伺服器錯誤334 伺服器錯誤

124</h2>335</h2>

125 336

126這些錯誤來自推論提供者，而非您的帳戶或請求。在 Anthropic API 上，這表示 Anthropic 基礎設施。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或自訂閘道上，這表示該提供者的基礎設施。337大多數這些錯誤來自推論提供者：Anthropic 在 Anthropic API 上的服務，以及該提供者在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或自訂閘道上的端點後面的服務。[Auto mode 無法判斷動作的安全性](#auto-mode-cannot-determine-the-safety-of-an-action)和[Agent 因 API 錯誤而提前終止](#agent-terminated-early-due-to-an-api-error)也涵蓋您這一方的原因，例如無法叫用分類器模型的 Amazon Bedrock 帳戶或達到使用限制的子代理。

127 338

128<h3 id="api-error-500-internal-server-error">339<h3 id="api-error-500-internal-server-error">

129 API 錯誤：500 內部伺服器錯誤340 API Error: 500 Internal server error

130</h3>341</h3>

131 342

132Claude Code 會顯示任何 5xx 回應的狀態碼和 API 的錯誤訊息。下面的範例顯示 Anthropic API 上的 500 回應：343Claude Code 會顯示任何 5xx 回應的狀態碼和 API 的錯誤訊息。下面的範例顯示 Anthropic API 上的 500 回應：

135API 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.346API 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.

136```347```

137 348

138結尾的句子會指出要檢查服務健康狀態的位置，並因提供者而異。Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 配置會指出該提供者的服務狀態。自訂 `ANTHROPIC_BASE_URL` 會指出閘道主機。349尾部句子名稱檢查服務健康狀況的位置，並因提供者而異。Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 設定會名稱該提供者的服務狀態。自訂 `ANTHROPIC_BASE_URL` 會名稱閘道主機。

139 350

140這表示 API 內部發生了意外故障。它不是由您的提示、設定或帳戶造成的。351這表示 API 內部發生意外故障。它不是由您的提示、設定或帳戶引起的。

141 352

142**該怎麼做：**353**該怎麼做：**

143 354

144* 檢查 [status.claude.com](https://status.claude.com) 或訊息中指名的提供者狀態頁面，查看是否有活躍的事件355* 檢查 [status.claude.com](https://status.claude.com) 或訊息中名稱的提供者狀態頁面，查看是否有活躍的事件

145* 等待一分鐘，然後再次傳送您的訊息。您的原始訊息仍在對話中，所以對於較長的提示，您可以輸入 `try again` 而不是貼上整個內容。356* 等待一分鐘，然後再次傳送您的訊息。您的原始訊息仍在對話中，因此對於較長的提示，您可以輸入 `try again` 而不是貼上整個內容。

146* 如果錯誤持續出現且沒有發佈的事件，請執行 `/feedback` 以便 Anthropic 可以使用您的請求詳細資訊進行調查。如果您的環境中無法使用 `/feedback`，請參閱[報告錯誤](#report-an-error)。357* 如果錯誤持續存在且沒有發佈的事件，請執行 `/feedback`，以便 Anthropic 可以使用您的請求詳細資訊進行調查。如果您的環境中無法使用 `/feedback`，請參閱[報告錯誤](#report-an-error)。

147 358

148<h3 id="api-error-repeated-529-overloaded-errors">359<h3 id="api-error-repeated-529-overloaded-errors">

149 API 錯誤：重複的 529 超載錯誤360 API Error: Repeated 529 Overloaded errors

150</h3>361</h3>

151 362

152API 在所有使用者中暫時達到容量上限。Claude Code 在顯示此訊息之前已經重試了多次：363API 在所有使用者中暫時達到容量。Claude Code 在顯示此訊息之前已經重試了多次：

153 364

154```text theme={null}365```text theme={null}

155API 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.366API 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.

156```367```

157 368

158結尾的句子因提供者而異，方式與上面的 500 錯誤相同。369尾部句子因提供者而異，方式與上面的 500 錯誤相同。

159 370

160529 不是您的使用限制，也不會計入您的配額。371529 不是您的使用限制，也不會計入您的配額。

161 372

162**該怎麼做：**373**該怎麼做：**

163 374

164* 檢查 [status.claude.com](https://status.claude.com) 或訊息中指名的提供者狀態頁面，查看是否有容量通知375* 檢查 [status.claude.com](https://status.claude.com) 或訊息中名稱的提供者狀態頁面，查看容量通知

165* 幾分鐘後再試一次376* 在幾分鐘後重試

166* 執行 `/model` 並切換到不同的模型以繼續工作，因為容量是按模型追蹤的。當某個模型負載特別高時，Claude Code 會提示您執行此操作，例如 `Opus is experiencing high load, please use /model to switch to Sonnet`。377* 執行 `/model` 並切換到不同的模型以繼續工作，因為容量是按模型追蹤的。Claude Code 會在一個模型負載特別高時提示您執行此操作，例如 `Opus is experiencing high load, please use /model to switch to Sonnet`。

167 378

168<h3 id="request-timed-out">379<h3 id="request-timed-out">

169 請求逾時380 Request timed out

170</h3>381</h3>

171 382

172API 在連線截止期限之前沒有回應。383API 在連線截止時間之前沒有回應。

173 384

174```text theme={null}385```text theme={null}

175Request timed out386Request timed out

181 392

182* 重試請求393* 重試請求

183* 對於長時間執行的任務，將工作分解為較小的提示394* 對於長時間執行的任務，將工作分解為較小的提示

184* 如果是緩慢的網路或代理造成的，請按照[自動重試](#automatic-retries)中的說明提高 `API_TIMEOUT_MS`395* 如果緩慢的網路或代理是原因，請按照[自動重試](#automatic-retries)中的說明提高 `API_TIMEOUT_MS`

185* 如果逾時頻繁且您的網路狀況良好，請參閱下面的[網路和連線錯誤](#network-and-connection-errors)396* 如果逾時頻繁且您的網路在其他方面狀況良好，請參閱下面的[網路和連線錯誤](#network-and-connection-errors)

397

398<h3 id="no-response-from-api">

399 No response from API

400</h3>

401

402Claude Code 傳送了串流請求，API 在第一個位元組的截止時間內沒有返回回應標頭，因此 Claude Code 中止了請求，而不是等待完整的 `API_TIMEOUT_MS` 請求逾時（預設為 10 分鐘）。Claude Code 最多再傳送一次請求，如果[重試預算](#tune-retry-behavior)允許的話。當重試也沒有得到回應時，該輪次以此訊息結束，該訊息顯示每次嘗試等待了多長時間。當您設定 [`CLAUDE_CODE_RETRY_WATCHDOG`](/docs/zh-TW/env-vars) 時，一次重試的上限不適用，Claude Code 會在[調整重試行為](#tune-retry-behavior)中描述的預算下重試。

403

404```text theme={null}

405API Error: No response from API (waited 3m, then 10m on the retry). If a proxy or gateway on your network holds responses until they complete, raise API_TIMEOUT_MS or CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS to wait longer.

406```

407

408Claude Code 分別為第一次嘗試的等待回應標頭和重試的等待設定：

409

410* **第一次嘗試**：當您將其設定為 1 或更多時，[`CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`](/docs/zh-TW/env-vars)，限制在 10 秒到 30 分鐘之間。否則 Claude Code 會使用[串流空閒監視程式](/docs/zh-TW/network-config#streaming-idle-watchdogs)中列出的位元組級監視程式逾時，因此改變該逾時的變數也會改變此等待。無論哪種方式，Claude Code 都會為請求正文的每 32KB 添加一秒。

411* **重試**：比 `API_TIMEOUT_MS` 少一秒，預設略低於 10 分鐘，以便重試可以超過保持回應直到生成完成的代理或閘道。在 Amazon Bedrock 上，重試使用與第一次嘗試相同的截止時間，訊息顯示一個持續時間而不是兩個。

412

413兩個等待都不超過正 `API_TIMEOUT_MS` 少一秒，正 `API_TIMEOUT_MS` 在 11 秒以下會關閉截止時間。位元組級監視程式僅在回應標頭到達後才開始，因此在此之後停止傳送位元組的回應遵循[停滯串流規則](#automatic-retries)而不是此截止時間。

414

415**該怎麼做：**

416

417* 再次傳送您的訊息。您的原始訊息仍在對話中，因此對於較長的提示，您可以輸入 `try again` 而不是貼上整個內容。

418* 如果重複出現，將其視為[網路或代理問題](#unable-to-connect-to-api)。接受連線但從不轉發請求的代理會在每次嘗試時產生此錯誤。

419* 如果您網路上的代理或閘道保持回應直到完成，請提高 `API_TIMEOUT_MS` 以便重試等待更長時間。在 Amazon Bedrock 上，也請提高 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`。

420* 如果第一次嘗試持續逾時，然後重試成功，請提高 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` 以便第一次嘗試也等待足夠長的時間。

421

422在 v2.1.242 之前，Claude Code 在未回應的串流請求失敗之前等待完整的 `API_TIMEOUT_MS` 請求逾時（預設為 10 分鐘）。在 v2.1.261 之前，重試等待與第一次嘗試相同的截止時間，訊息沒有顯示持續時間。

186 423

187<h3 id="the-response-above-may-be-incomplete">424<h3 id="the-response-above-may-be-incomplete">

188 上面的回應可能不完整425 The response above may be incomplete

189</h3>426</h3>

190 427

191串流回應在 Claude 已經產生可見輸出後失敗。重新傳送請求可能會執行相同的工具呼叫兩次，所以 Claude Code 會保留已經串流的內容，並改為附加此通知，而不是捨棄該輪次。您看到的變體會指出原因：428串流請求在回應仍在進行中時失敗，在 Claude 完成一個文字區塊或工具呼叫之後，或在完成思考後開始一個。重新傳送請求可能會執行相同的工具呼叫兩次，因此 Claude Code 會保留 Claude 完成的輸出並附加此通知，而不是丟棄該輪次。您看到的變體名稱原因：

192 429

193```text theme={null}430```text theme={null}

194API Error: Server error mid-response. The response above may be incomplete.431API Error: Server error mid-response. The response above may be incomplete.

195API Error: Connection closed mid-response. The response above may be incomplete.432API Error: Connection lost mid-response. The response above may be incomplete.

196API Error: Response stalled mid-stream. The response above may be incomplete.433API Error: Your computer went to sleep mid-response. The response above may be incomplete.

434API Error: The response stopped arriving. The response above may be incomplete.

197```435```

198 436

199* }`Server error mid-response`：中途串流超載或 5xx 伺服器錯誤。此變體需要 Claude Code v2.1.199 或更新版本；在此之前，該情況會捨棄部分輸出並將整個輪次報告為錯誤。437* `Server error mid-response`：中流過載或 5xx 伺服器錯誤。此變體需要 Claude Code v2.1.199 或更高版本；在此之前，該情況會丟棄部分輸出並將整個輪次報告為錯誤。

200* `Connection closed mid-response`：連線中斷。438* `Connection lost mid-response`：連線中斷。

201* `Response stalled mid-stream`：串流停止傳送資料。439* `Your computer went to sleep mid-response`：Claude Code 偵測到您的電腦在回應串流時進入睡眠狀態。一旦您的電腦喚醒，Claude Code 會將連線視為中斷並停止從中讀取。

440* `The response stopped arriving`：連線保持開啟但停止傳遞資料，因此串流空閒監視程式中止了它。在 v2.1.222 之前，Claude Code 也可能在通過 `ANTHROPIC_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 到達的[閘道](/docs/zh-TW/gateways)連線上報告此故障，同時伺服器的保活 ping 仍在到達，因為它只計算那裡解析的回應事件；升級會停止這些虛假逾時在這些路由上。通過提供者基礎 URL（例如 `ANTHROPIC_BEDROCK_BASE_URL`）到達的閘道不被位元組監視程式包裝；請參閱[串流空閒監視程式](/docs/zh-TW/network-config#streaming-idle-watchdogs)。

441

442在 v2.1.227 之前，`Connection lost mid-response` 讀作 `Connection closed mid-response`，`The response stopped arriving` 讀作 `Response stalled mid-stream`。

443

444在四種情況下，Claude Code 會在不立即顯示此通知的情況下處理故障：

445

446* 在回應的早期，Claude Code 要麼重試故障，要麼以不同的錯誤結束輪次。請參閱[自動重試](#automatic-retries)。

447* 當這些故障之一在 Claude 完成回應後到達時，Claude Code 會保留完整回應並正常結束輪次，沒有此通知。在 v2.1.222 之前，Claude Code 在連線中斷或在回應完成後停滯時顯示此通知，並將輪次報告為錯誤，儘管回應是完整的。

448* 在[非互動式工作階段](/docs/zh-TW/headless)中，例如 `-p` 執行、[Agent SDK](/docs/zh-TW/agent-sdk/overview) 執行或[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)，當截斷回應在主對話中且包含文字但沒有工具呼叫時，您不必自己傳送 `continue`：Claude Code 會保留部分輸出並提示 Claude 從停止的地方繼續，最多連續三次。您只有在 Claude Code 用完這些繼續後才會看到此通知。在 v2.1.246 之前，Claude Code 在第一次截斷時以此通知結束非互動式輪次。

449* 在[子代理](/docs/zh-TW/sub-agents#api-errors-in-subagents)中，無論工作階段是否互動：當其截斷回應包含文字但沒有工具呼叫時，Claude Code 會提示子代理繼續。通知僅在這些繼續用完後才成為子代理的最後一條訊息。在 v2.1.257 之前，子代理在第一次截斷時顯示此通知。

202 450

203**該怎麼做：**451**該怎麼做：**

204 452

205* 閱讀已串流的回應。沒有任何內容遺失，但最後的句子或工具呼叫可能缺失。453* 在互動式工作階段中，閱讀螢幕上保留的回應：Claude Code 保留 Claude 在錯誤之前完成的每個區塊，但在輪次結束時丟棄中斷的最後區塊，因此最後的句子或工具呼叫可能會遺失。回覆 `continue` 以讓 Claude 從其最後完成的區塊繼續。

206* 回覆 `continue` 以讓 Claude 從停止的地方繼續454* 在[非互動式模式](/docs/zh-TW/headless)（`-p`）中：

207* 如果相同的錯誤在任何可見輸出之前出現，Claude Code 會重試請求而不是完成它。請參閱[自動重試](#automatic-retries)。455 * 使用預設文字輸出，Claude Code 會列印它仍然從輪次早期保留的最後完成的文字區塊，然後是此訊息。當它沒有保留任何內容時，Claude Code 會單獨列印此訊息，例如因為 Claude Code 在輪次中間壓縮了對話並清除了該文字。在 v2.1.219 之前，Claude Code 在 `-p` 文字輸出中只列印此訊息並丟棄它已經產生的回應。

456 * 使用 `--output-format json` 或 `stream-json`，Claude Code 會在 `result` 欄位中報告此訊息。

457 * 一旦連線穩定，要繼續該輪次，請恢復工作階段並按照[繼續對話](/docs/zh-TW/headless#continue-conversations)中的說明傳送 `continue`。

208 458

209<h3 id="auto-mode-cannot-determine-the-safety-of-an-action">459<h3 id="auto-mode-cannot-determine-the-safety-of-an-action">

210 自動模式無法判斷動作的安全性460 Auto mode cannot determine the safety of an action

211</h3>461</h3>

212 462

213[自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)用來分類動作的模型無法做出決定，所以自動模式沒有自動批准該動作。您看到的訊息取決於分類器失敗的原因。463[auto mode](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 使用的模型無法產生決定來分類動作，因此 auto mode 沒有自動批准該動作。您看到的訊息取決於分類器如何失敗。

214 464

215在您的工作目錄內的讀取、搜尋和編輯會跳過分類器，所以它們在所有這些情況下都能繼續工作。465讀取、搜尋和編輯您的工作目錄內的內容會跳過分類器，因此它們在所有這些情況下都能繼續工作。

216 466

217當分類器模型超載時：467當分類器模型不可用時：

218 468

219```text theme={null}469```text theme={null}

220<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool> right now. Wait briefly and then try this action again.470<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool> right now. Wait a moment and then try this action again.

221```471```

222 472

473當 Claude Code 可以判斷故障類別時，它會在 `temporarily unavailable` 後面的括號中名稱該類別，例如 `<model> is temporarily unavailable (rate-limited), so auto mode cannot determine the safety of <tool> right now`。類別為 `(rate-limited)`、`(overloaded)`、`(server error)`、`(timed out)` 和 `(connection failed)`。速率限制、過載和伺服器錯誤是暫時的，重試有效。如果 `(timed out)` 或 `(connection failed)` 重複，請檢查您的連線；請參閱[無法連線到 API](#unable-to-connect-to-api)。在 v2.1.229 之前，訊息從不名稱類別，讀作 `Wait briefly and then try this action again`。

474

475當沒有類別符合時，訊息出現時括號中沒有類別；多個故障會產生該形式。在 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 上，包括 [Mantle 端點](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint)，當您的 AWS 帳戶無法叫用訊息中名稱的模型時，它也會出現，該故障在每次重試時重複，直到您的帳戶被授予存取該模型的權限。

476

223**該怎麼做：**477**該怎麼做：**

224 478

225* 幾秒鐘後重試；Claude 會看到相同的訊息，通常會自動重試479* 在幾秒後重試；Claude 會看到相同的訊息，通常會自動重試。暫時故障與 [auto mode 資格](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)無關；您不需要變更設定

226* 如果重試持續失敗，請繼續執行唯讀任務，稍後再回到被阻止的動作480* 如果重試持續失敗，請繼續進行唯讀任務，稍後再回到被阻止的動作

227* 這是暫時的，與[自動模式資格](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)無關；您不需要變更設定481* 在 Amazon Bedrock 上，如果訊息在每次重試時返回，請檢查您的帳戶是否可以叫用它名稱的模型：對於標準 Amazon Bedrock 模型，確認您的 [IAM 政策](/docs/zh-TW/amazon-bedrock#iam-configuration)允許叫用它；對於 Mantle 模型 ID，[聯絡您的 AWS 帳戶團隊](/docs/zh-TW/amazon-bedrock#mantle-endpoint-errors)

228 482

229當分類器傳回無法解析的回應時：483當分類器請求失敗是因為您的 OAuth 令牌過期或被另一個工作階段輪換時，Claude Code 會重新整理令牌並重試請求一次，因此例行令牌過期不會作為此訊息出現。在 v2.1.216 之前，過期或輪換的令牌會導致每個分類器請求失敗，auto mode 會以此訊息拒絕每個檢查的動作，直到令牌被重新整理。

484

485當分類器返回無法解析的回應時：

230 486

231```text theme={null}487```text theme={null}

232Auto mode could not evaluate this action and is blocking it for safety — run with --debug for details488Auto mode could not evaluate this action and is blocking it for safety — run with --debug for details

237* 重試該動作；這通常在下一次嘗試時成功493* 重試該動作；這通常在下一次嘗試時成功

238* 執行 `claude --debug` 並重複該動作以在偵錯日誌中查看基礎分類器回應494* 執行 `claude --debug` 並重複該動作以在偵錯日誌中查看基礎分類器回應

239 495

240當單獨的 API 安全檢查因為較早的對話內容而阻止了分類器請求時：496當單獨的 API 安全檢查因為早期對話內容而阻止分類器請求時：

241 497

242```text theme={null}498```text theme={null}

243Auto 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 details499Auto 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

244```500```

245 501

502Claude Code 拒絕該動作，但告訴 Claude 這不是對該動作不安全的判斷，並繼續進行其他任務而不是重試。這些拒絕不計入 [auto mode 的暫停閾值](/docs/zh-TW/permission-modes#when-auto-mode-falls-back)。在[非互動式](/docs/zh-TW/headless) `-p` 執行中，Claude Code 不會停止執行。Claude 接收的內容取決於它在哪裡請求該動作：

503

504* 對於 `-p` 執行中沒有 `--input-format stream-json` 的[背景子代理](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)，Claude Code 會返回包含 `Agent aborted: auto mode classifier request refused by the safety safeguard in headless mode` 的錯誤結果

505* 在其他地方，包括互動式工作階段和 `-p` 執行的主對話，Claude Code 會將該拒絕返回給 Claude

506

507在 v2.1.225 之前，Claude Code 計算這些拒絕以達到暫停閾值，並返回與真正分類器區塊相同的拒絕訊息。

508

246**該怎麼做：**509**該怎麼做：**

247 510

248* 這不是關於您的動作的決定。您對話中已有的內容在自動模式將對話傳送給分類器時觸發了 API 上的安全篩選器511* 這不是對您的動作的決定。您對話中已有的內容在 auto mode 將對話傳送給分類器時觸發了 API 上的安全篩選器

249* 重試無法幫助；相同的對話內容會再次觸發篩選器512* 重試無法幫助；相同的對話內容將再次觸發篩選器

250* 切換到不同的[權限模式](/docs/zh-TW/permission-modes)，以便在出現提示時批准該動作，或開始一個沒有觸發內容的新對話513* 在互動式工作階段中，切換到不同的[權限模式](/docs/zh-TW/permission-modes)，以便您可以在提示時批准該動作

514* 開始一個新的對話，不包含觸發內容

251 515

252當對話大小超過分類器的上下文視窗時：516當對話增長超過分類器的上下文視窗時：

253 517

254```text theme={null}518```text theme={null}

255Auto mode classifier transcript exceeded context window — falling back to manual approval (try /compact to reduce conversation size)519Auto mode classifier transcript exceeded context window — falling back to manual approval (try /compact to reduce conversation size)

256```520```

257 521

258在互動式工作階段中，自動模式會為該動作回退到正常的權限提示，以便您可以手動批准或拒絕它。在[非互動式模式](/docs/zh-TW/headless)中，執行會中止，因為文字記錄只會增長，重試無法成功。522動作發生的情況取決於 Claude 在哪裡請求它：

523

524* 在互動式工作階段中，auto mode 會回退到該動作的正常權限提示，以便您可以手動批准或拒絕它

525* 對於 [非互動式](/docs/zh-TW/headless) `-p` 執行中沒有 `--input-format stream-json` 的[背景子代理](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)，Claude Code 會返回包含 `Agent aborted: auto mode classifier transcript exceeded context window in headless mode` 的錯誤結果，執行繼續

526* 在 `-p` 執行中的其他地方，沒有 [`--permission-prompt-tool`](/docs/zh-TW/cli-reference#cli-flags)，沒有提示可以回退到，因此動作不執行，執行繼續

259 527

260**該怎麼做：**528**該怎麼做：**

261 529

262* 在出現的提示中批准或拒絕該動作530* 在互動式工作階段中，在出現的提示中批准或拒絕該動作

263* 執行 `/compact` 以減少對話大小，以便後續動作再次適應分類器視窗531* 在互動式工作階段中，執行 `/compact` 以減少對話大小，以便後續動作再次適應分類器視窗

264 532

265<h3 id="agent-terminated-early-due-to-an-api-error">533<h3 id="agent-terminated-early-due-to-an-api-error">

266 代理因 API 錯誤而提前終止534 Agent terminated early due to an API error

267</h3>535</h3>

268 536

269[子代理](/docs/zh-TW/sub-agents)的 API 請求終止失敗，例如因為達到使用限制或伺服器錯誤的重試用盡，所以子代理在完成其任務之前停止。此訊息需要 Claude Code v2.1.199 或更新版本；在此之前，API 錯誤文字被傳回給 Claude，就像它是子代理的結果一樣。537[子代理](/docs/zh-TW/sub-agents)的 API 請求終止失敗，例如因為達到使用限制或伺服器錯誤的重試用完，所以子代理在完成其任務之前停止。此訊息需要 Claude Code v2.1.199 或更高版本；在此之前，API 錯誤文字被返回給 Claude，就像它是子代理的結果一樣。

270 538

271```text theme={null}539```text theme={null}

272Agent terminated early due to an API error: <error detail>540Agent terminated early due to an API error: <error detail>

274 542

275**該怎麼做：**543**該怎麼做：**

276 544

277* 將冒號後的錯誤詳細資訊與此頁面上的自己的部分相符，例如[使用限制](#usage-limits)或[伺服器錯誤](#server-errors)，並遵循該部分的步驟545* 將冒號後的錯誤詳細資訊與此頁面上的其自己的部分相符，例如[使用限制](#usage-limits)或[伺服器錯誤](#server-errors)，並遵循該部分的步驟

278* 一旦基礎錯誤清除，請要求 Claude 重試任務或[恢復子代理](/docs/zh-TW/sub-agents#resume-subagents)546* 一旦基礎錯誤清除，請要求 Claude 重試任務或[恢復子代理](/docs/zh-TW/sub-agents#resume-subagents)

279 547

280當速率限制、超載或伺服器錯誤中斷已經產生文字輸出的前景子代理時，Claude 會收到該部分輸出標記為不完整，而不是此錯誤。只有工具呼叫輸出的子代理也會收到此錯誤；在 v2.1.199 中，該形狀改為傳回空的部分結果。請參閱[子代理中的 API 錯誤](/docs/zh-TW/sub-agents#api-errors-in-subagents)。548當速率限制、過載或伺服器錯誤中斷已經產生文字輸出的前景子代理時，Claude 會收到該部分輸出標記為不完整，而不是此錯誤。其唯一輸出是工具呼叫的子代理也會收到此錯誤；在 v2.1.199 中，該形狀返回了空部分結果。請參閱[子代理中的 API 錯誤](/docs/zh-TW/sub-agents#api-errors-in-subagents)。

281 549

282<h2 id="usage-limits">550<h2 id="usage-limits">

283 使用限制551 使用限制

284</h2>552</h2>

285 553

286這些錯誤表示與您的帳戶或方案相關的配額已達到。它們與[伺服器錯誤](#server-errors)不同，伺服器錯誤會影響所有人。554本節中的大多數錯誤表示與您的帳戶或方案相關的配額已達到。其中三個的運作方式不同：[`伺服器暫時限制請求`](#server-is-temporarily-limiting-requests) 是與您的方案配額無關的伺服器端節流，[`1M 上下文需要使用額度`](#usage-credits-required-for-1m-context) 是權利檢查而非耗盡的配額，[`確認提示未獲回應`](#the-prompt-to-confirm-went-unanswered) 表示使用額度同意提示已關閉且未獲回應，無論是否達到配額。

287 555

288<h3 id="youve-hit-your-session-limit">556<h3 id="youve-hit-your-session-limit">

289 您已達到工作階段限制557 您已達到工作階段限制

295You've hit your session limit · resets 3:45pm563You've hit your session limit · resets 3:45pm

296You've hit your weekly limit · resets Mon 12:00am564You've hit your weekly limit · resets Mon 12:00am

297You've hit your Opus limit · resets 3:45pm565You've hit your Opus limit · resets 3:45pm

566You've hit your Sonnet limit · resets 3:45pm

298```567```

299 568

300Claude Code 會阻止進一步的請求，直到訊息中顯示的重設時間。工作階段和每週限制在所有模型中共享，因此切換模型不會恢復存取。Opus 限制僅適用於 Opus 請求，因此使用 `/model` 切換到另一個模型可讓您繼續工作。569Claude Code 會阻止進一步的請求，直到訊息中顯示的重設時間。工作階段和每週限制在所有模型中共享，因此切換模型不會恢復存取。Opus 和 Sonnet 限制各自僅適用於對該模型系列的請求，因此使用 `/model` 切換到該系列外的模型可讓您繼續工作。

570

571在使用 claude.ai 訂閱登入的互動式工作階段中，Claude Code 也可以在開啟的工作階段中等待，並在重設後不久繼續中斷的任務。等待時，工作階段底部的一行會顯示 `Usage limit reached · continuing automatically at 3:45pm · esc to cancel`。在空提示處按 `Esc` 可取消等待。請參閱[等待使用限制重設](/docs/zh-TW/interactive-mode#wait-for-a-usage-limit-to-reset)以了解您看到的內容、如何開始或取消等待，以及如何關閉自動繼續。在 v2.1.234 之前，Claude Code 不提供此等待功能。

301 572

302使用額度會同時計入工作階段和每週額度。單一次的大量活動突發，例如大型工作流程扇出，可能會在工作階段視窗重設之前耗盡每週額度。573使用量同時計入工作階段和每週額度。單次大量活動突發（例如大型工作流程扇出）可能會在工作階段視窗重設之前耗盡每週額度。

303 574

304**該怎麼做：**575**該怎麼做：**

305 576

306* 等待錯誤訊息中顯示的重設時間577* 等待錯誤中顯示的重設時間

307* 對於 Opus 限制，執行 `/model` 並切換到另一個模型以繼續工作578* 在[桌面應用程式](/docs/zh-TW/desktop)的 Code 標籤中，工作階段限制卡片提供**達到限制時自動繼續**核取方塊。每週限制卡片則不提供。勾選後，桌面應用程式會在重設後重試中斷的回合，並在卡片上顯示重試時間。桌面核取方塊和 CLI 在 `/config` 中的**達到使用限制時自動繼續**設定是分開的，因此請分別關閉每一個。

308* 執行 `/usage` 以查看您的方案限制及其重設時間579* 對於 Opus 或 Sonnet 限制，執行 `/model` 並切換到該系列外的模型以繼續工作。每個模型都有自己的提示快取，因此下一個請求會重新讀取整個對話，沒有快取命中；請參閱[切換模型](/docs/zh-TW/prompt-caching#switching-models)

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

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

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

311 583

312若要在達到限制之前監控您的剩餘額度，請將 `rate_limits` 欄位新增至[自訂狀態列](/docs/zh-TW/statusline#rate-limit-usage)，或在桌面應用程式中按一下模型選擇器旁的[使用量環](/docs/zh-TW/desktop#check-usage)。584若要在達到限制之前監視您的剩餘額度，請將 `rate_limits` 欄位新增至[自訂狀態行](/docs/zh-TW/statusline#rate-limit-usage)，或在桌面應用程式中按一下模型選擇器旁的[使用量環](/docs/zh-TW/desktop#check-usage)。

313 585

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

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

316</h3>588</h3>

317 589

318選定的模型使用 1M 令牌擴展上下文視窗，而您的方案僅透過使用額度包含它。590選定的模型使用 1M 權杖擴展上下文視窗，而您的方案僅透過使用額度包括它。

319 591

320```text theme={null}592```text theme={null}

321API Error: Usage credits required for 1M context · run /usage-credits to turn them on, or /model to switch to standard context593API Error: Usage credits required for 1M context · run /usage-credits to turn them on, or /model to switch to standard context

322```594```

323 595

324這是一項權利檢查，而不是配額耗盡。即使您的工作階段和每週額度仍有容量，它也會觸發。請參閱[擴展上下文](/docs/zh-TW/model-config#extended-context)以了解哪些方案直接包含 1M 上下文，哪些需要使用額度。596這是權利檢查，而非配額耗盡。即使您的工作階段和每週額度有剩餘容量，它也會觸發。請參閱[擴展上下文](/docs/zh-TW/model-config#extended-context)以了解哪些方案直接包括 1M 上下文，哪些需要使用額度。Claude Code 在您使用 `/model` 選擇模型時執行此檢查，且僅在直接連接到 Anthropic API 時執行；如果您將 `ANTHROPIC_BASE_URL` 指向[LLM 閘道](/docs/zh-TW/llm-gateway)，`/model` 允許 `[1m]` 選擇，閘道決定請求是否成功。

325 597

326當此錯誤在對話中途出現，因為上下文增長超過 200K 令牌時，Claude Code 會自動將對話壓縮回標準上下文限制以下，並在之後將工作階段保持在該限制，因此無需採取任何行動。在 v2.1.172 之前的版本上，錯誤會在每個後續請求（包括 `/compact`）上重複出現；在這些版本上執行 `/clear` 以恢復。以下步驟適用於您明確選擇 `[1m]` 模型的情況。598當此錯誤在對話中期出現，因為上下文增長超過 200K 權杖時，Claude Code 會自動將對話壓縮回標準上下文限制以下，並之後將工作階段保持在該限制，因此無需採取任何行動。在 v2.1.172 之前的版本上，錯誤會在每個後續請求（包括 `/compact`）上重複；在這些版本上執行 `/clear` 以恢復。以下步驟適用於您明確選擇 `[1m]` 模型的情況。

327 599

328**該怎麼做：**600**該怎麼做：**

329 601

330* 執行 `/model` 並選擇不帶 `[1m]` 後綴的變體以回退到標準上下文視窗602* 執行 `/model` 並選擇不帶 `[1m]` 後綴的變體以回退到標準上下文視窗

331* 執行 `/usage-credits` 以在 Pro 和 Max 上開啟 1M 變體的計量計費，或在 Team 和 Enterprise 上向您的管理員請求603* 訊息提及 `/usage-credits` 的地方，執行它以在 Pro 和 Max 上為 1M 變體開啟計量計費，或在 Team 和 Enterprise 上向您的管理員請求使用額度

332* 如果 `/model` 後錯誤仍然存在，1M 模型 ID 可能在其他地方設定。請參閱[選定的模型有問題](#theres-an-issue-with-the-selected-model)以按優先順序檢查配置位置。604* 如果 `/model` 後錯誤仍然存在，1M 模型 ID 可能在其他地方設定。請參閱[設定您的模型](/docs/zh-TW/model-config#setting-your-model)以按優先順序檢查設定位置。

333* 若要從模型選擇器中完全移除 1M 變體，請設定 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/zh-TW/env-vars)605* 若要從模型選擇器中完全移除 1M 變體，請設定 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/zh-TW/env-vars)

334 606

607<h3 id="the-prompt-to-confirm-went-unanswered">

608 確認提示未獲回應

609</h3>

610

611如果您的帳戶需要 [Fable 使用額度同意](/docs/zh-TW/model-config#fable-and-usage-credits)，Claude Code 會要求您在 Fable 請求計費使用額度之前確認。當沒有人在可能沒有人在其終端的工作階段中回應該同意提示時，Claude Code 會關閉提示並以以下其中一條訊息結束回合：

612

613```text theme={null}

614Fable limit reached · continuing on Fable 5.1 uses usage credits, and the prompt to confirm went unanswered — nothing was sent · answer it where this session is running, or /model to change

615Fable 5.1 now uses usage credits · the prompt to confirm went unanswered — nothing was sent · answer it where this session is running, or /model to change

616```

617

618訊息會命名工作階段的 Fable 模型，因此在 Fable 5 上它們會讀作 `continuing on Fable 5` 和 `Fable 5 now uses usage credits`。在 v2.1.257 之前，第一條訊息以 `Fable 5 limit reached` 開頭。

619

620這發生在[遠端控制](/docs/zh-TW/remote-control)工作階段、[背景工作階段](/docs/zh-TW/agent-view)和[代理團隊](/docs/zh-TW/agent-teams)隊友工作階段中。Claude Code 僅在工作階段自己的互動式檢視中顯示同意提示：執行它的終端，或對於背景工作階段，一旦您附加，[代理檢視](/docs/zh-TW/agent-view)。遠端控制用戶端無法顯示它。Claude Code 在 [`dialogExpiry`](/docs/zh-TW/settings-reference#dialogexpiry) 截止時間（預設為五分鐘）關閉提示，或在沒有人在該終端輸入時立即有新提示到達，例如從遠端控制用戶端發送的提示。在執行工作階段的終端輸入會取消截止時間，Claude Code 會等待您的回答。在附加的背景工作階段檢視中，輸入不會取消截止時間，新提示仍會關閉同意提示，因此請在任一情況發生之前回答。Claude Code 不發送任何內容並保持您的模型，因此當您發送下一個提示時，Claude Code 會再次顯示同意提示。

621

622**該怎麼做：**

623

624* 在執行工作階段的終端，發送另一個提示，當同意提示重新出現時回答它。對於背景工作階段，請先從[代理檢視](/docs/zh-TW/agent-view)附加到它。從遠端控制用戶端重新發送會再次顯示此訊息，因為用戶端無法顯示提示。

625* 執行 `/model` 以切換到不計費使用額度的模型

626* 若要給自己更多時間到達該終端，請將 [`dialogExpiry`](/docs/zh-TW/settings-reference#dialogexpiry) 設定為更長的值或 `"never"`

627

628在 v2.1.236 之前，此訊息不會出現：當遠端控制用戶端已連接時，Claude Code 會等待 60 秒以獲得答案，然後在您的預設模型上繼續回合。

629

335<h3 id="server-is-temporarily-limiting-requests">630<h3 id="server-is-temporarily-limiting-requests">

336 伺服器暫時限制請求631 伺服器暫時限制請求

337</h3>632</h3>

342API Error: Server is temporarily limiting requests (not your usage limit)637API Error: Server is temporarily limiting requests (not your usage limit)

343```638```

344 639

345Claude Code 透過真實限制回應所攜帶的統一配額標頭的缺失來區分這些與您的方案限制。自 v2.1.199 起，無論您如何驗證，這都會[自動重試](#automatic-retries)並進行退避，然後才會顯示。在較早的版本上，使用 claude.ai 訂閱登入的工作階段在第一次出現時失敗；只有 API 金鑰和 Enterprise 登入會重試它。640Claude Code 通過真實限制回應所攜帶的統一配額標頭的缺失來區分這些。自 v2.1.199 起，無論您如何驗證，這都會[自動重試](#automatic-retries)並進行退避，然後才顯示。在較早的版本上，使用 claude.ai 訂閱登入的工作階段在第一次出現時失敗回合；只有 API 金鑰和 Enterprise 登入重試它。

346 641

347**該怎麼做：**642**該怎麼做：**

348 643

353 請求被拒絕 (429)648 請求被拒絕 (429)

354</h3>649</h3>

355 650

356您已達到為 API 金鑰、Amazon Bedrock 專案或 Google Cloud 專案配置的速率限制。651您已達到為您的 API 金鑰、Amazon Bedrock 專案或 Google Cloud 專案設定的速率限制。

357 652

358```text theme={null}653```text theme={null}

359API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com.654API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com.

360```655```

361 656

362尾部句子命名檢查服務健康狀況的位置，並因提供者而異。Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 配置會命名該提供者的服務狀態，而不是 Anthropic 狀態頁面。自訂 `ANTHROPIC_BASE_URL` 會命名閘道主機。657尾部句子命名檢查服務健康狀況的位置，並因提供者而異。Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 設定會命名該提供者的服務狀態，而不是 Anthropic 狀態頁面。自訂 `ANTHROPIC_BASE_URL` 會命名閘道主機。

363 658

364**該怎麼做：**659**該怎麼做：**

365 660

366* 執行 `/status` 並確認作用中的認證是您預期的認證。環境中的流浪 `ANTHROPIC_API_KEY` 可能會透過低階金鑰而不是您的訂閱來路由請求。661* 執行 `/status` 並確認作用中的認證是您預期的認證。環境中的流浪 `ANTHROPIC_API_KEY` 可能會透過低階金鑰而不是您的訂閱路由請求。

367* 檢查您的提供者主控台以了解作用中的限制，並在需要時請求更高的層級662* 檢查您的提供者主控台以了解作用中的限制，並在需要時請求更高的層級

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

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

665

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

667 已達到支出限制

668</h3>

669

670您透過[Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway)連接，並已超過閘道運營商設定的[支出上限](/docs/zh-TW/claude-apps-gateway-spend-limits)。閘道會阻止您的請求，直到命名的期間重設或運營商提高上限。它將每個被阻止的 `429` 回應標記為 `x-should-retry: false`，因此 Claude Code 會顯示此訊息而不重試。

671

672```text theme={null}

673spend limit reached (daily; resets 2026-08-09 00:00 UTC)

674```

675

676訊息會命名上限的期間和重設時間，當運營商設定了 `blocked_message` 時，他們的指示會跟在它後面。在 v2.1.225 之前，訊息只讀 `spend limit reached`；較舊版本上的閘道仍會發送該較短的形式。

677

678**該怎麼做：**

679

680* 等待訊息命名的重設時間，或如果訊息包含運營商的指示，請遵循它們

681* 如果您經常達到上限，請要求您的閘道運營商提高上限

682

683相關訊息 `spend limit unavailable` 表示閘道無法讀取其支出記錄，並作為預防措施而不是超過您的上限而阻止了請求。它通常會自行清除；如果它持續，請告訴您的閘道運營商。

370 684

371<h3 id="credit-balance-is-too-low">685<h3 id="credit-balance-is-too-low">

372 信用額度餘額過低686 信用額度餘額過低

373</h3>687</h3>

374 688

375您的 Console 組織已用完預付信用額度。689您的 Console 組織已用完預付額度，或 Claude Code 正在使用 Console API 金鑰發送您的請求，而您打算使用您的訂閱。

376 690

377```text theme={null}691```text theme={null}

378Credit balance is too low692Credit balance is too low

380 694

381**該怎麼做：**695**該怎麼做：**

382 696

383* 在 [platform.claude.com/settings/billing](https://platform.claude.com/settings/billing) 新增信用額度，並考慮在那裡啟用自動重新載入，以便在餘額達到零之前進行補充697* 如果您有 Pro、Max、Team 或 Enterprise 方案並看到此訊息，執行 `/status` 並檢查 `API key` 列。環境中已核准的 `ANTHROPIC_API_KEY` 會透過該金鑰而不是您的訂閱路由請求。在目前的 shell 中取消設定它，並從您的 shell 設定檔中移除它，然後重新啟動 `claude`。如果您還沒有使用您的訂閱登入，請執行 `/login`。

384* 如果您有 Pro、Max、Team 或 Enterprise 方案，請使用 `/login` 切換到訂閱驗證698* 在 [platform.claude.com/settings/billing](https://platform.claude.com/settings/billing) 新增額度，並考慮在那裡啟用自動重新載入，以便在餘額達到零之前重新填充

385* 在 Console 中設定每個工作區的支出上限，以防止單一專案耗盡組織餘額。請參閱[有效管理成本](/docs/zh-TW/costs)。699* 在 Console 中設定每個工作區的支出上限，以防止單個專案耗盡組織餘額。請參閱[有效管理成本](/docs/zh-TW/costs)。

700

701<h3 id="could-not-update-your-spend-limit">

702 無法更新您的支出限制

703</h3>

704

705伺服器拒絕了您從達到支出限制時出現的提示中進行的支出限制變更。

706

707```text theme={null}

708Could not update your spend limit: <reason from the server>

709```

710

711當伺服器解釋拒絕時，訊息以該原因結尾，重試相同值會再次失敗。當失敗沒有伺服器提供的原因（例如連接中斷）時，訊息會讀作 `Could not update your spend limit. Press Enter to retry.`，重試可能會成功。在 v2.1.216 之前，Claude Code 為每個失敗顯示通用形式。

712

713**該怎麼做：**

714

715* 如果訊息包含原因，請選擇滿足它的限制，例如較低的金額

716* 如果訊息僅顯示通用形式，請重試；失敗可能是暫時的

717* 如果變更持續失敗，請改為在瀏覽器中從您的 [claude.ai 計費設定](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)進行變更

386 718

387<h2 id="authentication-errors">719<h2 id="authentication-errors">

388 驗證錯誤720 驗證錯誤

389</h2>721</h2>

390 722

391這些錯誤表示 Claude Code 無法向 API 證明您的身份。隨時執行 `/status` 以查看目前使用的認證方式。723這些錯誤表示 Claude Code 無法向 API 證明您的身份。隨時執行 `/status` 以查看目前哪個認證資格處於活動狀態。

392 724

393<h3 id="not-logged-in">725<h3 id="not-logged-in">

394 未登入726 未登入

395</h3>727</h3>

396 728

397此工作階段沒有有效的認證方式可用。729此工作階段沒有有效的認證資格可用。

398 730

399```text theme={null}731```text theme={null}

400Not logged in · Please run /login732Not logged in · Please run /login

401```733```

402 734

403**應該怎麼做：**735**該怎麼做：**

404 736

405* 執行 `/login` 以使用您的 Claude 訂閱或 Console 帳戶進行驗證737* 執行 `/login` 以使用您的 Claude 訂閱或 Console 帳戶進行驗證

406* 如果您預期使用環境變數進行驗證，請確認 `ANTHROPIC_API_KEY` 已在啟動 `claude` 的 shell 中設定並匯出738* 如果您預期環境變數會驗證您，請確認 `ANTHROPIC_API_KEY` 已在啟動 `claude` 的 shell 中設定並匯出

407* 對於無法進行互動式登入的 CI 或自動化環境，請設定一個 [`apiKeyHelper`](/docs/zh-TW/settings#available-settings) 指令碼，在啟動時取得金鑰739* 對於無法進行互動式登入的 CI 或自動化，請設定一個 [`apiKeyHelper`](/docs/zh-TW/settings-reference#apikeyhelper) 指令碼，在啟動時擷取金鑰

408* 請參閱[驗證優先順序](/docs/zh-TW/authentication#authentication-precedence)以了解當存在多個認證方式時，Claude Code 使用哪一個740* 請參閱[驗證優先順序](/docs/zh-TW/authentication#authentication-precedence)以瞭解當存在多個認證資格時 Claude Code 使用哪一個

409 741

410如果系統反覆提示您登入，請參閱[未登入或權杖已過期](/docs/zh-TW/troubleshoot-install#not-logged-in-or-token-expired)以取得系統時鐘和 macOS Keychain 的修復方法。742如果系統反覆提示您登入，請參閱[未登入或權杖已過期](/docs/zh-TW/troubleshoot-install#not-logged-in-or-token-expired)以取得系統時鐘檢查和 macOS 認證儲存復原步驟。

411 743

412<h3 id="could-not-resolve-authentication-method">744<h3 id="could-not-resolve-authentication-method">

413 無法解析驗證方法745 無法解析驗證方法

414</h3>746</h3>

415 747

416工作階段到達 API 用戶端時沒有任何認證方式。這會出現在[背景工作階段](/docs/zh-TW/agent-view)、雲端工作階段和 Agent SDK 環境中，其中互動式登入檢查在第一個請求之前不會執行。748工作階段到達 API 用戶端時沒有任何認證資格。[背景工作階段](/docs/zh-TW/agent-view)和雲端工作階段在背景工作程序啟動時沒有認證資格時會顯示此訊息。互動式、`-p` 和 Agent SDK 執行會將相同條件報告為[未登入](#not-logged-in)，並僅將此字串寫入其偵錯記錄，因此如果您在那裡找到它，請改為遵循該項目。

417 749

418```text theme={null}750```text theme={null}

419Could 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 omitted751Could 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

420```752```

421 753

422在 v2.1.174 之前，指派給閒置預初始化背景工作程序的背景或雲端工作階段即使已設定有效認證方式也可能以此方式失敗。請升級以恢復。在目前版本中，此錯誤表示背景工作程序沒有可用的認證方式。754在目前版本上，此錯誤表示背景工作程序沒有可用的認證資格。在 v2.1.174 之前，指派給閒置預初始化背景工作程序的背景工作階段即使在設定了有效認證資格時也可能以此方式失敗。在 v2.1.176 之前，在被聲稱之前處於閒置狀態的雲端工作階段也可能如此。請升級以復原。

423 755

424**應該怎麼做：**756**該怎麼做：**

425 757

426* 如果此錯誤出現在背景或雲端工作階段中且您的認證方式已設定，請升級至 v2.1.174 或更新版本758* 如果此訊息出現在背景或雲端工作階段中，且您的認證資格已設定，請升級至 v2.1.176 或更新版本

427* 確認 `ANTHROPIC_API_KEY`、`CLAUDE_CODE_OAUTH_TOKEN` 或您的雲端提供者認證方式已在啟動背景工作程序的環境中設定，而不僅在您的互動式 shell 中759* 確認 `ANTHROPIC_API_KEY`、`CLAUDE_CODE_OAUTH_TOKEN` 或您的雲端提供者認證資格已在啟動背景工作程序的環境中設定，而不僅在您的互動式 shell 中設定

428* 對於 Agent SDK，請參閱[驗證設定](/docs/zh-TW/agent-sdk/overview#get-started)760* 對於 Agent SDK，請參閱[快速入門中的驗證設定](/docs/zh-TW/agent-sdk/quickstart#setup)

429* 在相同環境中的互動式工作階段中執行 `/status` 以確認哪個認證方式來源可以解析761* 在相同環境中的互動式工作階段中執行 `/status` 以確認哪個認證資格來源會解析

430 762

431<h3 id="invalid-api-key">763<h3 id="invalid-api-key">

432 無效的 API 金鑰764 無效的 API 金鑰

433</h3>765</h3>

434 766

435`ANTHROPIC_API_KEY` 環境變數或 `apiKeyHelper` 指令碼傳回的金鑰被 API 拒絕。767`ANTHROPIC_API_KEY` 環境變數或 `apiKeyHelper` 指令碼傳回的金鑰被 API 拒絕，或 Claude Code 在傳送前阻止了來自 `ANTHROPIC_API_KEY` 的金鑰。

436 768

437```text theme={null}769```text theme={null}

438Invalid API key · Fix external API key770Invalid API key · Fix external API key

439```771```

440 772

441**應該怎麼做：**773當訊息在 `Fix external API key` 之後繼續，並帶有描述（例如 `Invalid X-Api-Key header value from ANTHROPIC_API_KEY: it contains a line break at character 41 (120 characters on 2 lines).`）時，API 從未看到該金鑰。Claude Code 發現了 HTTP 標頭無法攜帶的字元，並在傳送前停止了請求。請參閱[無效的請求標頭值](#invalid-request-header-value)以瞭解如何讀取描述並修正該值。

442 774

443* 檢查是否有拼寫錯誤，並確認該金鑰未在 [Console](https://platform.claude.com/settings/keys) 中被撤銷775**該怎麼做：**

444* 在相同的 shell 中執行 `env | grep ANTHROPIC`。direnv、dotenv shell 外掛程式和 IDE 終端等工具可能會從您專案中的 `.env` 檔案載入過時的金鑰，而您並未明確設定它776

777* 檢查拼寫錯誤，並確認金鑰未在 [Console](https://platform.claude.com/settings/keys) 中被撤銷

778* 在相同的 shell 中，執行 `env | grep ANTHROPIC`，或在 PowerShell 中執行 `Get-ChildItem Env:ANTHROPIC*`。direnv、dotenv shell 外掛程式和 IDE 終端機等工具可以從您專案中的 `.env` 檔案載入過時的金鑰，而無需您明確設定它

445* 取消設定 `ANTHROPIC_API_KEY` 並執行 `/login` 以改用訂閱驗證779* 取消設定 `ANTHROPIC_API_KEY` 並執行 `/login` 以改用訂閱驗證

446* 如果金鑰來自 [`apiKeyHelper`](/docs/zh-TW/settings#available-settings) 指令碼，請直接執行該指令碼以確認它在 stdout 上列印有效的金鑰780* 如果金鑰來自 [`apiKeyHelper`](/docs/zh-TW/settings-reference#apikeyhelper) 指令碼，請直接執行該指令碼以確認它在 stdout 上列印有效的金鑰

447* 執行 `/status` 以確認 Claude Code 實際使用的認證方式來源781* 執行 `/status` 以確認 Claude Code 實際使用的認證資格來源

448 782

449<h3 id="your-apikeyhelper-script-is-failing">783<h3 id="your-apikeyhelper-script-is-failing">

450 您的 apiKeyHelper 指令碼失敗784 您的 apiKeyHelper 指令碼失敗

451</h3>785</h3>

452 786

453在 [`apiKeyHelper`](/docs/zh-TW/settings#available-settings) 設定中設定的命令已結束並出現錯誤、逾時或未在 stdout 上列印任何內容。如果沒有來自指令碼的金鑰，請求會到達 API 並使用預留位置認證方式，API 會以 `401` 拒絕它。787Claude Code 執行了您的 [`apiKeyHelper`](/docs/zh-TW/settings-reference#apikeyhelper) 設定中的命令，但沒有取回金鑰。沒有金鑰，請求會到達 API，並帶有預留位置認證資格，API 會以 `401` 拒絕它。終端機中的 `Authentication` 面板顯示發生了以下哪種情況：

788

789* 命令以錯誤結束或逾時

790* 命令未向 stdout 列印任何內容

791* 命令列印了除金鑰以外的內容，例如登入橫幅或記錄行。面板顯示 `returned output that cannot be used as an API key` 並說明出了什麼問題，而不重複輸出。在 v2.1.227 之前，Claude Code 會傳送命令列印的任何內容，在修剪周圍空白後。

454 792

455```text theme={null}793```text theme={null}

456Your apiKeyHelper script is failing · This usually means you need to re-authenticate with your provider · Run /status to see the script's error output794Your apiKeyHelper script is failing · This usually means you need to re-authenticate with your provider · Run /status to see the script's error output

457```795```

458 796

459Claude Code 會重新執行指令碼並在顯示此訊息之前最多重試兩次請求，因此失敗會在三次嘗試內出現。在 v2.1.208 之前，Claude Code 花費完整的[重試預算](#automatic-retries)使用預留位置認證方式重新傳送請求，然後報告通用的 `401` 驗證錯誤而不是指令碼失敗。797在[非互動式模式](/docs/zh-TW/headless)中，stderr 也會帶有具體原因，前綴為 `apiKeyHelper failed:`。

460 798

461執行 `/login` 在此無法幫助：只要設定存在，協助程式的輸出[優先於](/docs/zh-TW/authentication#authentication-precedence)已儲存的登入。799Claude Code 會重新執行指令碼並在顯示此訊息之前最多重試請求兩次，因此失敗會在三次嘗試內出現。在 v2.1.208 之前，Claude Code 會花費完整的[重試預算](#automatic-retries)使用預留位置認證資格重新傳送請求，然後報告通用 `401` 驗證錯誤，而不是指令碼失敗。

462 800

463**應該怎麼做：**801執行 `/login` 在這裡沒有幫助：只要設定存在，協助程式的輸出就會[優先於](/docs/zh-TW/authentication#authentication-precedence)已儲存的登入。

802

803**該怎麼做：**

804

805* 直接在您的 shell 中執行在 `apiKeyHelper` 中設定的命令以重現失敗

806* 如果命令報告工作階段已過期，請使用您的認證資格提供者重新驗證，例如再次登入您的 SSO 或機密保管庫

807* 修正命令，使其僅將金鑰列印到 stdout，作為單一可列印 ASCII 權杖，最多 16,384 個字元，並以代碼 0 結束。請參閱[使用 apiKeyHelper 輪換認證資格](/docs/zh-TW/llm-gateway-connect#rotate-credentials-with-apikeyhelper)以取得有效的設定。

808* 執行 `/status` 以確認 `apiKeyHelper` 是活動認證資格來源。每次命令失敗時，其結束代碼和錯誤輸出都會出現在終端機中的 `Authentication` 面板中。在 v2.1.212 之前，該面板的標題為 `Cloud authentication`。

809

810<h3 id="invalid-request-header-value">

811 無效的請求標頭值

812</h3>

813

814Claude Code 即將作為請求標頭傳送的值包含 HTTP 標頭無法攜帶的字元：換行符、NUL 位元組或 `U+00FF` 以上的字元，例如彎引號或零寬空格。Claude Code 在傳送任何內容之前停止請求，並命名要修正的變數或設定。常見原因是從帶有隱藏字元或雜散換行符的文件或聊天中貼上的認證資格。

815

816Claude Code 在直接向 Claude API 或透過 [LLM 閘道](/docs/zh-TW/llm-gateway)傳送請求時執行此檢查。在第三方雲端提供者（例如 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock)）上，Claude Code 在傳送前不執行此檢查。

817

818```text theme={null}

819Invalid auth token · Fix external auth token

820Invalid ANTHROPIC_CUSTOM_HEADERS · Fix the environment variable

821Invalid request header from the environment · Fix the environment variable

822```

823

824訊息的第一部分取決於不良值的來源：

825

826* `Invalid auth token`：來自 [`ANTHROPIC_AUTH_TOKEN`](/docs/zh-TW/env-vars) 或 [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/zh-TW/env-vars) 的持有人權杖

827* `Invalid ANTHROPIC_CUSTOM_HEADERS`：您在 [`ANTHROPIC_CUSTOM_HEADERS`](/docs/zh-TW/env-vars) 中設定的標頭名稱或值。描述計算哪個 `Name: Value` 對有問題，例如 `distinct header 2 of 3 parsed from ANTHROPIC_CUSTOM_HEADERS`，而不重複名稱或值，因為您選擇了兩者。

828* `Invalid request header from the environment`：Claude Code 從另一個環境變數（例如 `CLAUDE_AGENT_SDK_CLIENT_APP`）複製到請求標頭中的值。描述命名要修正的變數。

829

830Claude Code 將此檢查捕獲的不良 `ANTHROPIC_API_KEY` 報告為[無效的 API 金鑰](#invalid-api-key)，具有相同的尾部描述。它將不良的已儲存 `/login` 認證資格報告為[未登入](#not-logged-in)；執行 `/login` 以儲存新的認證資格。[`apiKeyHelper`](/docs/zh-TW/settings-reference#apikeyhelper) 指令碼的輸出永遠不會到達此檢查：Claude Code 在指令碼執行時驗證它，標頭無法攜帶的輸出會失敗，並顯示[您的 apiKeyHelper 指令碼失敗](#your-apikeyhelper-script-is-failing)。

831

832在第二個 `·` 之後，訊息描述問題，如此完整範例所示：

833

834```text theme={null}

835Invalid auth token · Fix external auth token · Invalid Authorization header value from ANTHROPIC_AUTH_TOKEN: it contains a line break at character 41 (120 characters on 2 lines).

836```

837

838位置從 1 開始計算字元。描述是從固定短語和字元計數建立的，因此它永遠不包括值本身。它僅在字元是眾所周知的隱藏或排版字元（例如位元組順序標記、零寬空格或彎引號）時命名該字元，並將其他任何內容報告為 `a non-ASCII character`。

839

840**該怎麼做：**

464 841

465* 在您的 shell 中直接執行在 `apiKeyHelper` 中設定的命令以重現失敗842* 重新設定訊息命名的變數或設定，重新輸入報告位置周圍的字元，而不是從相同來源再次貼上

466* 如果命令報告工作階段已過期，請使用您的認證方式提供者重新驗證，例如再次登入您的 SSO 或機密保管庫843* 對於 `ANTHROPIC_CUSTOM_HEADERS`，每行保留一個 `Name: Value` 對，並重寫訊息計數的對

467* 修復命令以便它將金鑰列印到 stdout 並以代碼 0 結束。請參閱[使用 apiKeyHelper 輪換認證方式](/docs/zh-TW/llm-gateway-connect#rotate-credentials-with-apikeyhelper)以取得有效的設定。844* 執行 `/status` 以確認哪個認證資格來源處於活動狀態

468* 執行 `/status` 以確認 `apiKeyHelper` 是使用中的認證方式來源。每次命令失敗時，其結束代碼和錯誤輸出會出現在終端中的 `Cloud authentication` 面板中。

469 845

470<h3 id="this-organization-has-been-disabled">846<h3 id="this-organization-has-been-disabled">

471 此組織已被停用847 此組織已被停用

472</h3>848</h3>

473 849

474來自已停用 Console 組織的過時 `ANTHROPIC_API_KEY` 正在覆蓋您的訂閱登入。850Claude Code 正在使用來自已停用 Console 組織的過時 `ANTHROPIC_API_KEY`。當您有已儲存的訂閱登入時，金鑰會覆蓋它。

475 851

476```text theme={null}852```text theme={null}

477Your ANTHROPIC_API_KEY belongs to a disabled organization · Unset the environment variable to use your other credentials853Your ANTHROPIC_API_KEY belongs to a disabled organization · Unset the environment variable to use your subscription instead

854Your ANTHROPIC_API_KEY belongs to a disabled organization · Update or unset the environment variable

478API Error: 400 ... This organization has been disabled.855API Error: 400 ... This organization has been disabled.

479```856```

480 857

481環境變數優先於 `/login`，因此即使您有有效的 Pro 或 Max 訂閱，在 shell 設定檔中匯出或從 `.env` 檔案載入的金鑰也會被使用。在非互動模式 (`-p`) 中，當金鑰存在時總是使用該金鑰。858`·` 之後的提示取決於您的已儲存認證資格：當已儲存的 `/login` 可以在您取消設定金鑰後接管時出現第一種形式，當金鑰是您唯一的認證資格時出現第二種形式。

482 859

483**應該怎麼做：**860環境變數優先於 `/login`，因此在您的 shell 設定檔中匯出或從 `.env` 檔案載入的金鑰即使在您有有效的 Pro 或 Max 訂閱時也會被使用。在非互動式模式 (`-p`) 中，當存在金鑰時總是使用該金鑰。

861

862**該怎麼做：**

484 863

485* 在目前 shell 中取消設定 `ANTHROPIC_API_KEY` 並從您的 shell 設定檔中移除它，然後重新啟動 `claude`864* 在目前的 shell 中取消設定 `ANTHROPIC_API_KEY` 並從您的 shell 設定檔中移除它，然後重新啟動 `claude`

486* 之後執行 `/status` 以確認使用中的認證方式是您的訂閱865* 如果訊息說 `Update or unset`，您沒有已儲存的登入可以回退到。取消設定金鑰並執行 `/login`，或將金鑰替換為來自活動 Console 組織的金鑰。

487* 如果未設定環境變數且錯誤仍然存在，則已停用的組織是與您的 `/login` 相關聯的組織。請聯絡支援或使用不同的帳戶登入。866* 之後執行 `/status` 以確認活動認證資格是您的訂閱

867* 如果未設定環境變數且錯誤仍然存在，已停用的組織是與您的 `/login` 相關聯的組織。聯絡支援或使用不同帳戶登入。

488 868

489<h3 id="your-organization-has-disabled-api-key-authentication">869<h3 id="your-organization-has-disabled-api-key-authentication">

490 您的組織已停用 API 金鑰驗證870 您的組織已停用 API 金鑰驗證

491</h3>871</h3>

492 872

493此訊息需要 Claude Code v2.1.169 或更新版本。您的 Console 組織管理員已關閉 API 金鑰驗證，因此 API 拒絕了 Claude Code 正在傳送的金鑰。`·` 之後的恢復提示會根據金鑰的來源而有所不同：873此訊息需要 Claude Code v2.1.169 或更新版本。您的 Console 組織管理員已關閉 API 金鑰驗證，因此 API 拒絕 Claude Code 正在傳送的金鑰。恢復提示在 `·` 之後會根據金鑰的來源而異：

494 874

495```text theme={null}875```text theme={null}

496Your organization has disabled API key authentication · Run /login to sign in with your claude.ai account876Your organization has disabled API key authentication · Run /login to sign in with your claude.ai account

499Your organization has disabled API key authentication · Unset the apiKeyHelper setting and run /login to sign in with your claude.ai account879Your organization has disabled API key authentication · Unset the apiKeyHelper setting and run /login to sign in with your claude.ai account

500```880```

501 881

502環境變數和 `apiKeyHelper` 優先於 `/login`，因此當其中任一個仍在提供金鑰時，單獨執行 `/login` 無法幫助。請參閱[驗證優先順序](/docs/zh-TW/authentication#authentication-precedence)。882環境變數和 `apiKeyHelper` 優先於 `/login`，因此在任一個仍在提供金鑰時單獨執行 `/login` 沒有幫助。請參閱[驗證優先順序](/docs/zh-TW/authentication#authentication-precedence)。

503 883

504**應該怎麼做：**884**該怎麼做：**

505 885

506* 如果訊息提及 `ANTHROPIC_API_KEY`，請在目前 shell 中取消設定它，並從您的 shell 設定檔或 `.env` 檔案中移除它，然後重新啟動 `claude`886* 如果訊息命名 `ANTHROPIC_API_KEY`，在目前的 shell 中取消設定它，並從您的 shell 設定檔或 `.env` 檔案中移除它，然後重新啟動 `claude`

507* 如果訊息提及 `apiKeyHelper`，請從您的 `settings.json` 中移除 [`apiKeyHelper`](/docs/zh-TW/settings#available-settings) 設定887* 如果訊息命名 `apiKeyHelper`，從您的 `settings.json` 中移除 [`apiKeyHelper`](/docs/zh-TW/settings-reference#apikeyhelper) 設定

508* 執行 `/login` 以使用您的 claude.ai 帳戶登入888* 執行 `/login` 以使用您的 claude.ai 帳戶登入

509* 之後執行 `/status` 以確認使用中的認證方式是您的訂閱而不是 API 金鑰889* 之後執行 `/status` 以確認活動認證資格是您的訂閱，而不是 API 金鑰

510* 如果您需要 API 金鑰驗證進行自動化，請要求您的組織管理員在 Console 中重新啟用它890* 如果您需要 API 金鑰驗證來進行自動化，請要求您的組織管理員在 Console 中重新啟用它

511 891

512<h3 id="your-organization-has-disabled-claude-subscription-access">892<h3 id="your-organization-has-disabled-claude-subscription-access">

513 您的組織已停用 Claude 訂閱存取893 您的組織已停用 Claude 訂閱存取

514</h3>894</h3>

515 895

516您的 Claude 組織不允許使用訂閱登入來登入 Claude Code。使用相同帳戶再次執行 `/login` 會傳回相同的錯誤。896您的 Claude 組織不允許使用訂閱登入登入 Claude Code。使用相同帳戶再次執行 `/login` 會傳回相同的錯誤。

517 897

518```text theme={null}898```text theme={null}

519Your organization has disabled Claude subscription access for Claude Code · Use an Anthropic API key instead, or ask your admin to enable access899Your organization has disabled Claude subscription access for Claude Code · Use an Anthropic API key instead, or ask your admin to enable access

521 901

522這是伺服器端組織設定，因此無法從本機設定、環境變數或 CLI 旗標覆蓋。902這是伺服器端組織設定，因此無法從本機設定、環境變數或 CLI 旗標覆蓋。

523 903

524Agent SDK 和 `-p` 非互動模式將此顯示為 `oauth_org_not_allowed` 錯誤代碼。904Agent SDK 和 `-p` 非互動式模式將此呈現為 `oauth_org_not_allowed` 錯誤代碼。

525 905

526**應該怎麼做：**906**該怎麼做：**

527 907

528* 要求您的管理員為您的組織啟用 Claude Code 存取908* 要求您的管理員為您的組織啟用 Claude Code 存取

529* 使用 Console API 金鑰而不是您的訂閱進行驗證。請參閱 [Claude Console 驗證](/docs/zh-TW/authentication#claude-console-authentication)以進行設定。909* 使用 Console API 金鑰而不是您的訂閱進行驗證。請參閱 [Claude Console 驗證](/docs/zh-TW/authentication#claude-console-authentication)以取得設定。

530* 如果您是管理員且看不到啟用存取的選項，請聯絡 [Anthropic 支援](https://support.claude.com)910* 如果您是管理員且看不到啟用存取的選項，請聯絡 [Anthropic 支援](https://support.claude.com)

531 911

532<h3 id="routines-are-disabled-by-your-organizations-policy">912<h3 id="routines-are-disabled-by-your-organizations-policy">

533 例行工作已被您的組織政策停用913 您的組織政策已停用例行程序

534</h3>914</h3>

535 915

536您的 Team 或 Enterprise 組織中的擁有者已在組織層級關閉例行工作。當您嘗試建立或執行例行工作時（包括從 `/schedule` 和 claude.ai/code 上的[例行工作](/docs/zh-TW/routines) UI），會出現此錯誤。916您的 Team 或 Enterprise 組織中的擁有者已在組織層級關閉例行程序。當您嘗試建立或執行例行程序時會出現此錯誤，例如從 claude.ai/code 上的[例行程序](/docs/zh-TW/routines) UI。在 Claude Code v2.1.227 或更新版本上，相同的設定也會[隱藏 CLI 中的 `/schedule`](/docs/zh-TW/routines#troubleshooting)。

537 917

538```text theme={null}918```text theme={null}

539Routines are disabled by your organization's policy.919Routines are disabled by your organization's policy.

541 921

542這是伺服器端設定，因此無法從本機設定、環境變數或 CLI 旗標覆蓋。922這是伺服器端設定，因此無法從本機設定、環境變數或 CLI 旗標覆蓋。

543 923

544**應該怎麼做：**924**該怎麼做：**

545 925

546* 要求您的組織中的擁有者在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 啟用**例行工作**切換926* 要求您的組織中的擁有者在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 啟用**例行程序**切換

547* 對於不需要組織層級例行工作的一次性排程工作，請參閱[排程工作](/docs/zh-TW/scheduled-tasks)927* 對於不需要組織層級例行程序的一次性排程工作，請參閱[排程工作](/docs/zh-TW/scheduled-tasks)

548 928

549<h3 id="remote-control-requires-the-anthropic-api">929<h3 id="remote-control-requires-the-anthropic-api">

550 Remote Control 需要 Anthropic API930 Remote Control 需要 Anthropic API

553工作階段未直接與 Anthropic API 通訊，因此沒有 claude.ai 後端供 [Remote Control](/docs/zh-TW/remote-control) 配對。933工作階段未直接與 Anthropic API 通訊，因此沒有 claude.ai 後端供 [Remote Control](/docs/zh-TW/remote-control) 配對。

554 934

555```text theme={null}935```text theme={null}

556Remote Control is only available when using Claude via api.anthropic.com.936Remote Control is only available when using Claude via api.anthropic.com. CLAUDE_CODE_USE_BEDROCK is set, so this session is using Amazon Bedrock — unset it (or run in a shell without it) to use Remote Control.

557```937```

558 938

559這會出現在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上。從 v2.1.196 開始，當 [`ANTHROPIC_BASE_URL`](/docs/zh-TW/env-vars) 指向 `api.anthropic.com` 以外的主機（例如 [LLM 閘道](/docs/zh-TW/llm-gateway)或代理）時，即使您使用 claude.ai 登入，也會出現此訊息。939第二句解釋了什麼將工作階段路由到遠離 Anthropic API；在 v2.1.219 之前，訊息僅為第一句。根據原因，訊息命名：

560 940

561**應該怎麼做：**941* `CLAUDE_CODE_USE_*` 提供者變數，例如 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 的 `CLAUDE_CODE_USE_BEDROCK` 或 [Google Cloud 的 Agent Platform](/docs/zh-TW/google-vertex-ai) 的 `CLAUDE_CODE_USE_VERTEX`

942* [`ANTHROPIC_BASE_URL`](/docs/zh-TW/env-vars) 指向 `api.anthropic.com` 以外的主機，例如 [LLM 閘道](/docs/zh-TW/llm-gateway)或代理，即使您使用 claude.ai 登入；在 v2.1.196 之前，自訂基礎 URL 不會阻止 Remote Control

943* 企業[雲端閘道](/docs/zh-TW/claude-apps-gateway)透過 `/login` 進行的登入，不支援 Remote Control，且沒有變數可取消設定

562 944

563* 取消設定 `ANTHROPIC_BASE_URL` 並重新啟動工作階段，或從直接與 Anthropic API 通訊的工作階段啟動 Remote Control945**該怎麼做：**

564* 對於此訊息和其他 Remote Control 啟動訊息，請參閱[疑難排解 Remote Control](/docs/zh-TW/remote-control#troubleshooting)

565 946

566<h3 id="oauth-token-revoked-or-expired">947* 取消設定訊息命名的變數，例如 `CLAUDE_CODE_USE_BEDROCK` 或 `ANTHROPIC_BASE_URL`，並重新啟動工作階段，或從直接與 Anthropic API 通訊的工作階段啟動 Remote Control

567 OAuth 權杖已撤銷或已過期948* 如果變數未在您的 shell 中設定，請檢查您的[設定檔](/docs/zh-TW/settings#where-settings-live)中的 `env` 金鑰，該金鑰將環境變數套用到每個工作階段

949* 對於此和其他 Remote Control 啟動訊息，請參閱[疑難排解 Remote Control](/docs/zh-TW/remote-control#troubleshooting)

950

951<h3 id="remote-control-couldnt-refresh-your-login">

952 Remote Control 無法重新整理您的登入

568</h3>953</h3>

569 954

570您儲存的登入不再有效。撤銷的權杖表示您已在所有地方登出或管理員移除了存取；過期的權杖表示自動重新整理在工作階段中途失敗。955Claude Code 在短期認證資格上執行即時 [Remote Control](/docs/zh-TW/remote-control) 連線，該認證資格是使用您已儲存的 claude.ai 登入取得和更新的。當 claude.ai 停止接受該登入，或 Claude Code 沒有剩餘的已儲存登入時，Claude Code 會停止 Remote Control 並需要您再次登入。任一失敗都可能在 Claude Code 仍在連線時或稍後在更新認證資格時發生。

571 956

572兩個訊息都報告 API 為 Claude Code 傳送的請求傳回的拒絕。當已儲存的登入在失敗的重新整理後已被清除時，您會看到[登入已過期](#login-expired)。957當 Claude Code 要求登入服務重新整理您的已儲存登入並且沒有收到答案時，它會保持 Remote Control 執行並在連線的目前認證資格仍然有效時再次嘗試重新整理。當 Claude Code 無法到達登入服務、請求逾時或服務在不拒絕您的登入的情況下失敗時，重新整理會沒有答案。如果登入服務在該認證資格過期時仍未回答，Claude Code 會停止 Remote Control 並報告 `OAuth token refresh failed`。

958

959當 Claude Code 停止 Remote Control 時，它會在警告和以 `Remote Control disconnected` 開頭的文字記錄行中顯示原因。您的本機工作階段會繼續執行，但沒有 Remote Control。本節涵蓋這些行：

573 960

574```text theme={null}961```text theme={null}

575OAuth token revoked · Please run /login962Remote Control disconnected — Claude.ai login expired — run /login to restore Remote Control

576OAuth token has expired · Please run /login963Remote Control disconnected — Claude.ai login expired — run /login, then /remote-control

577API Error: 401 ... authentication_error964Remote Control disconnected — Claude.ai login was rejected — run /login, then /remote-control

965Remote Control disconnected — OAuth token unavailable — run /login to restore Remote Control

966Remote Control disconnected — OAuth token refresh failed — run /login to re-authenticate

967Remote Control disconnected — JWT refresh failed: no OAuth token — run /login

968Remote Control disconnected — Signed out of Claude — run /login, then /remote-control

578```969```

579 970

580**應該怎麼做：**971Claude Code 在訊息中間命名原因：

581 972

582* 執行 `/login` 以重新登入973* ` Claude.ai login expired` 和 `Claude.ai login was rejected`：claude.ai 不再接受您的已儲存登入權杖，因為它已過期或被撤銷

583* 如果在同一工作階段中重新驗證後錯誤仍然出現，請先執行 `/logout` 以完全清除儲存的權杖，然後執行 `/login`974* ` OAuth token unavailable`：當連線的認證資格到期進行更新時，Claude Code 沒有已儲存的登入權杖

584* 對於跨啟動的重複登入提示，請參閱[疑難排解](/docs/zh-TW/troubleshoot-install#not-logged-in-or-token-expired)中的系統時鐘和 macOS Keychain 檢查975* `OAuth token refresh failed`：claude.ai 在 Claude Code 重新連線時拒絕了您的已儲存登入權杖，重新整理權杖未產生新的權杖

585* 對於其他失敗（包括 `403 Forbidden` 和 OAuth 瀏覽器問題），請參閱[登入和驗證](/docs/zh-TW/troubleshoot-install#login-and-authentication)976* `JWT refresh failed: no OAuth token`：Claude Code 找不到已儲存的登入權杖來更新

977* ` Signed out of Claude`：您在此機器上登出，例如在另一個終端機中執行 `/logout`，因此 Claude Code 沒有剩餘的已儲存登入來更新連線

586 978

587<h3 id="login-expired">979**該怎麼做：**

588 登入已過期

589</h3>

590 980

591Claude Code 嘗試更新您儲存的 claude.ai 或 Claude Console 登入，OAuth 服務拒絕了儲存的重新整理權杖，因此 Claude Code 清除了儲存的認證方式。之後，每個請求在到達 API 之前都會在本機停止，因為只有 `/login` 可以建立新的認證方式。在 v2.1.206 之前，Claude Code 無論如何都會傳送請求，並使用環境中剩餘的任何認證方式，然後每個模型都會失敗並出現[所選模型有問題](#theres-an-issue-with-the-selected-model)或 401 而不是登入提示。981* 執行 `/login` 以再次登入

982* 執行 `/remote-control` 以重新連線工作階段。以 `run /login to restore Remote Control` 結尾的訊息不需要此步驟：Claude Code 在您登入後會自動重新連線。

592 983

593```text theme={null}984在 v2.1.224 之前，`OAuth token refresh failed — run /login to re-authenticate` 讀作 `OAuth token refresh failed — re-authenticate, then re-enable Remote Control`，`JWT refresh failed: no OAuth token — run /login` 讀作 `no OAuth token available for recovery (code <N>)`。` Claude.ai login expired`、`Claude.ai login was rejected` 和 `OAuth token unavailable` 訊息已在 v2.1.225 中新增。

594Login expired · Please run /login985

595```986在 v2.1.238 之前，Claude Code 將現在說 `Signed out of Claude` 的情況報告為 `JWT refresh failed: no OAuth token — run /login`，並在一次登入重新整理沒有收到答案時立即停止 Remote Control，並顯示 `Claude.ai login expired — run /login to restore Remote Control`。

987

988<h3 id="remote-control-stopped-because-the-signed-in-account-changed">

989 Remote Control 因為已登入帳戶已變更而停止

990</h3>

991

992Claude Code 在 [Remote Control](/docs/zh-TW/remote-control) 工作階段期間顯示此行，當您在此機器上登入不同的 claude.ai 帳戶或組織時。您在 Claude Code 工作階段外進行了切換，例如在另一個終端機中執行 `/login`。

596 993

597在[非互動模式](/docs/zh-TW/headless)(`-p`) 和 [Agent SDK](/docs/zh-TW/agent-sdk/overview) 中，訊息如下所示，結構化錯誤代碼為 `authentication_failed`：994您在透過 `/login` 登入時啟動的 Remote Control 工作階段屬於當時登入的 claude.ai 帳戶和組織。

598 995

599```text theme={null}996```text theme={null}

600Failed to authenticate: OAuth session expired and could not be refreshed997Remote Control disconnected — signed-in claude.ai account or organization changed on this machine — run /remote-control to start a session for the current account, or /login to switch back, then /remote-control

601```998```

602 999

603這與[OAuth 權杖已撤銷或已過期](#oauth-token-revoked-or-expired)的狀態不同。這些訊息報告 API 傳回的 401。Claude Code 本身為已失敗更新的登入產生 `Login expired`，因此它不傳送任何請求。1000Claude Code 在 claude.ai 確認帳戶或組織已變更後立即停止 Remote Control 工作階段。您的本機工作階段會繼續執行，但沒有 Remote Control。

604 1001

605使用 API 金鑰、[`CLAUDE_CODE_OAUTH_TOKEN`](/docs/zh-TW/env-vars) 或第三方提供者驗證的工作階段不使用儲存的登入，永遠不會看到此訊息。1002**該怎麼做：**

606 1003

607**應該怎麼做：**1004* 執行 `/remote-control` 以在目前帳戶或組織下啟動新的 Remote Control 工作階段

1005* 若要切換回去，請執行 `/login` 並再次登入先前的帳戶或組織。然後執行 `/remote-control`。

608 1006

609* 執行 `/login` 以重新登入。在不登入的情況下重試會在每個請求上顯示相同的訊息。1007在 v2.1.234 之前，當您在 Claude Code 工作階段外切換到不同帳戶或組織時，Claude Code 沒有注意到。Claude Code 保持 Remote Control 工作階段連線，直到稍後對 Remote Control 伺服器的請求失敗，並顯示 `Remote Control server rejected the request (HTTP 404)`。該失敗可能在切換後數小時才出現。

610* 在非互動模式中，在相同環境中執行 `claude`，完成 `/login`，然後重新執行您的命令。對於無法互動式登入的自動化，請使用 `ANTHROPIC_API_KEY` 進行驗證或[使用 `claude setup-token` 產生長期權杖](/docs/zh-TW/authentication#generate-a-long-lived-token)。

611* 如果登入持續失敗，請參閱[登入和驗證](/docs/zh-TW/troubleshoot-install#login-and-authentication)

612 1008

613<h3 id="oauth-scope-requirement">1009<h3 id="remote-control-stopped-because-the-app-running-the-session-signed-out-or-switched-accounts">

614 OAuth 範圍要求1010 Remote Control 因為執行工作階段的應用程式登出或切換帳戶而停止

615</h3>1011</h3>

616 1012

617儲存的權杖早於較新功能所需的權限範圍。您最常從 `/usage` 和狀態列使用量指示器看到此訊息：1013當 Claude 桌面應用程式或 IDE 主持您的工作階段時，Claude Code 從該應用程式而不是從 `/login` 取得其登入權杖。當 claude.ai 拒絕該權杖時，Claude Code 要求應用程式提供新的權杖。如果應用程式回答它已登出，或它現在已登入不同的 Claude 帳戶，Claude Code 會結束 [Remote Control](/docs/zh-TW/remote-control) 工作階段並向應用程式傳送以下其中一行：

618 1014

619```text theme={null}1015```text theme={null}

620OAuth token does not meet scope requirement: user:profile1016Remote Control stopped — the app running this session is now signed in to a different Claude account

1017Remote Control stopped — the app running this session is signed out of Claude. Sign in there, then turn Remote Control back on

621```1018```

622 1019

623**應該怎麼做：**1020您的本機工作階段會繼續執行，但沒有 Remote Control。

624 1021

625* 執行 `/login` 以取得具有目前範圍的新權杖。您不需要先登出。1022**該怎麼做：**

626 1023

627<h3 id="aws-credentials-expired-or-invalid">1024* 如果應用程式已登出，請再次登入，然後在應用程式中重新開啟 Remote Control

628 AWS 認證方式已過期或無效1025* 如果應用程式切換了帳戶，Claude Code 無法在新帳戶下繼續已結束的工作階段。在該帳戶下啟動新的 Remote Control 工作階段。

1026

1027在 v2.1.238 之前，Claude Code 在兩種情況下都向應用程式傳送了[Remote Control 無法重新整理您的登入](#remote-control-couldnt-refresh-your-login)下列出的 `run /login` 訊息。

1028

1029<h3 id="oauth-token-revoked-or-expired">

1030 OAuth 權杖已撤銷或已過期

629</h3>1031</h3>

630 1032

631此訊息需要 Claude Code v2.1.198 或更新版本，且僅在您的設定檔中設定了 [`awsAuthRefresh`](/docs/zh-TW/amazon-bedrock#advanced-credential-configuration) 時出現。您的 AWS 工作階段權杖已過期或被拒絕，Claude Code 已執行的自動重新整理未產生 API 接受的認證方式。它會出現在來自 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 或 [Mantle 端點](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint) 的 401 上，這是這些提供者報告過期安全權杖的方式。1033您的已儲存登入不再有效。撤銷的權杖表示您在任何地方登出或管理員移除了存取；已過期的權杖表示自動重新整理在工作階段中失敗。

632 1034

633中間的動作提示會命名您設定中的 `awsAuthRefresh` 命令，因此會有所不同。穩定的部分是前導的 `AWS credentials expired or invalid`：1035兩個訊息都報告 API 為 Claude Code 傳送的請求傳回的拒絕。當已儲存的登入在失敗的重新整理後已被清除時，您會看到[登入已過期](#login-expired)。如果您在 [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/zh-TW/env-vars) 中使用長期權杖進行驗證，當該權杖過期或被撤銷時，您會看到相同的訊息。

634 1036

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

636AWS 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 ...1038OAuth token revoked · Please run /login

1039OAuth token has expired · Please run /login

1040API Error: 401 ... authentication_error

637```1041```

638 1042

639如果未設定 `awsAuthRefresh`，相同的 401 會改為顯示通用的 `Please run /login` 訊息，該訊息無法重新整理 AWS 認證方式。1043**該怎麼做：**

~~640~~

641**應該怎麼做：**

642 1044

643* 在另一個終端中執行訊息中命名的 `awsAuthRefresh` 命令（例如 `aws sso login --profile myprofile`）並完成瀏覽器登入，然後重試1045* 執行 `/login` 以再次登入

644* 在互動式工作階段中，執行 `/login`，選擇 **3rd-party platform**，然後在 **Using 3rd-party platforms** 下選擇 **Claude Platform on AWS · refresh credentials** 以執行相同的命令而無需重新啟動 Claude Code。請參閱[設定 AWS 認證方式](/docs/zh-TW/claude-platform-on-aws#1-configure-aws-credentials)1046* 如果在重新驗證後同一工作階段內錯誤返回，請先執行 `/logout` 以完全清除已儲存的權杖，然後執行 `/login`

645* 如果重新整理命令成功後錯誤仍然重複出現，請在相同的 shell 和設定檔中使用 `aws sts get-caller-identity` 確認身份在 Claude Code 外部有效1047* 如果您使用 `CLAUDE_CODE_OAUTH_TOKEN` 環境變數進行驗證，Claude Code 會在請求失敗並顯示 401 後繼續傳送您設定的值，而不是切換到已儲存登入的權杖。[`/status`](/docs/zh-TW/commands) 將此認證資格顯示為讀取 `CLAUDE_CODE_OAUTH_TOKEN` 的 `Auth token` 列。使用 [`claude setup-token`](/docs/zh-TW/authentication#generate-a-long-lived-token) 產生新的權杖並使用它重新啟動，或取消設定變數並執行 `/login`。在 v2.1.225 之前，Claude Code 可以在工作階段中期用已儲存登入的短期存取權杖替換變數的值，一旦該權杖過期，工作階段就會再次失敗，並顯示 401 錯誤。

1048* 對於跨啟動的重複登入提示，請參閱[疑難排解](/docs/zh-TW/troubleshoot-install#not-logged-in-or-token-expired)中的系統時鐘檢查和 macOS 認證儲存復原步驟

1049* 對於其他失敗，包括 `403 Forbidden` 和 OAuth 瀏覽器問題，請參閱[登入和驗證](/docs/zh-TW/troubleshoot-install#login-and-authentication)

646 1050

647<h3 id="aws-authentication-failed">1051<h3 id="api-error-401-invalid-authentication-credentials">

648 AWS 驗證失敗1052 API 錯誤：401 無效的驗證認證資格

649</h3>1053</h3>

650 1054

651此訊息需要 Claude Code v2.1.198 或更新版本，且僅在您的設定檔中設定了 [`awsAuthRefresh`](/docs/zh-TW/amazon-bedrock#advanced-credential-configuration) 時出現。您的 AWS 提供者傳回了 403，或 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 傳回了 401。1055API 識別了您的認證資格格式，但拒絕了其背後的帳戶或組織。當認證資格最近被撤銷、組織被停用或移除了您的存取，或帳戶本身被停用時，Anthropic 會傳回此訊息，因此過期的權杖不是原因。認證資格可以是您的已儲存登入或已核准的 `ANTHROPIC_API_KEY`，修正方式不同，因此首先執行 `/status` 以查看哪一個處於活動狀態。

~~652~~

653Claude Code 無法判斷您遇到了哪個原因。Amazon Bedrock 將過期的安全權杖報告為 403，但 403 也是它報告授權拒絕的方式，例如來自遺失 IAM 權限或未為您的帳戶啟用的模型的 `AccessDeniedException`。

~~654~~

655來自 Amazon Bedrock 的 401 也會落在此處而不是在 [AWS 認證方式已過期或無效](#aws-credentials-expired-or-invalid) 下，因為 Amazon Bedrock 不會將過期的權杖報告為 401。來自該端點的 401 通常來自請求路徑中的其他內容，例如公司代理。

~~656~~

657認證方式重新整理可以修復過期的權杖，無法修復其他原因，因此訊息提供了兩者：

658 1056

659```text theme={null}1057```text theme={null}

660AWS 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 ...1058Please run /login · API Error: 401 Invalid authentication credentials

661```1059```

662 1060

663中間的動作提示會命名您設定中的 `awsAuthRefresh` 命令，因此會有所不同。穩定的部分是前導的 `AWS authentication failed`。1061**該怎麼做：**

~~664~~

665**應該怎麼做：**

666 1062

667* 執行訊息中命名的 `awsAuthRefresh` 命令或 `aws sso login`，以防過期的認證方式是原因1063* 如果 `/status` 顯示未標記為未使用的 `API key` 列，則已核准的 [`ANTHROPIC_API_KEY`](/docs/zh-TW/authentication#authentication-precedence) 是活動認證資格，優先於您的登入，因此 `/login` 不會替換它。在 Claude Console 中輪換金鑰，或執行 `unset ANTHROPIC_API_KEY` 回退到您的訂閱，或在 PowerShell 中執行 `Remove-Item Env:ANTHROPIC_API_KEY`。

668* 如果您的認證方式是最新的，請確認 [IAM 配置](/docs/zh-TW/amazon-bedrock#iam-configuration) 中的 IAM 權限已附加到您使用的身份，且所選模型已為您的帳戶和區域啟用1064* 如果 `/status` 僅顯示您的登入，請執行 `/login` 一次。如果認證資格被撤銷，新的登入會替換它。

669* 執行 `aws sts get-caller-identity` 以確認您的請求使用哪個身份；過時的 `AWS_PROFILE` 或預設設定檔是權限不匹配的常見原因1065* 如果相同的訊息對相同的登入帳戶返回，則帳戶或組織不再活動。檢查 `/status` 報告的帳戶和組織，並要求您的組織管理員恢復存取。

1066* 如果 [`ANTHROPIC_BASE_URL`](/docs/zh-TW/env-vars) 指向 [LLM 閘道](/docs/zh-TW/llm-gateway)，`401` 之後的文字是您的閘道訊息，而不是 Anthropic 的訊息，`/login` 不會改變它。改為修正您的閘道期望的認證資格。

670 1067

671<h3 id="aws-default-chain-credential-resolve-timed-out">1068<h3 id="login-expired">

672 AWS 預設鏈認證方式解析逾時1069 登入已過期

673</h3>1070</h3>

674 1071

675AWS 預設認證方式提供者鏈在 60 秒內未產生認證方式，因此 Claude Code 停止了解析並使請求失敗。失敗是本機認證方式解析：請求永遠未到達 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 或 [Mantle 端點](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint)。Claude Code 在此錯誤出現之前會清除其[認證方式快取](/docs/zh-TW/amazon-bedrock#credential-caching-and-resolution-timeout)並在重複嘗試後重試，因此當您看到它時鏈已在重複嘗試上停滯。1072Claude Code 嘗試更新您已儲存的 claude.ai 或 Claude Console 登入，OAuth 服務拒絕了已儲存的重新整理權杖，因此 Claude Code 清除了已儲存的認證資格。之後，每個模型請求在到達 API 之前都會在本機停止，並顯示此訊息，因為只有 `/login` 可以建立新的認證資格。

1073

1074在 v2.1.206 之前，Claude Code 無論如何都會傳送模型請求，並使用環境中剩餘的任何認證資格，每個模型都會失敗，並顯示[所選模型有問題](#theres-an-issue-with-the-selected-model)或 401，而不是登入提示。

676 1075

677```text theme={null}1076```text theme={null}

678API Error: AWS default-chain credential resolve timed out1077Login expired · Please run /login

679```1078```

680 1079

681常見原因是您的 AWS 設定檔中的 `credential_process` 命令等待它無法接收的輸入，以及容器或 VM 的執行個體中繼資料服務 (IMDS) 永遠不會回答鏈的探測。在 v2.1.207 之前，停滯的鏈會讓請求無限期等待，而不是以此訊息失敗。1080在[非互動式模式](/docs/zh-TW/headless)(`-p`) 和 [Agent SDK](/docs/zh-TW/agent-sdk/overview) 中，訊息讀作如下，結構化錯誤代碼為 `authentication_failed`：

682 1081

683**應該怎麼做：**1082```text theme={null}

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

1084```

684 1085

685* 在相同的 shell 中使用相同的 `AWS_PROFILE` 執行 `aws sts get-caller-identity`。如果它也掛起，請修復設定檔；互動式提示的 `credential_process` 命令是常見原因。1086這與[OAuth 權杖已撤銷或已過期](#oauth-token-revoked-or-expired)的狀態不同。這些訊息報告 API 傳回的 401。Claude Code 本身為已失敗更新的登入產生 `Login expired`，因此它不傳送請求。當更新失敗是因為帳戶本身被暫停而不是登入過時時，Claude Code 會改為顯示[您的帳戶已被暫停](#your-account-is-on-hold)。

686* 在啟動 Claude Code 之前完成登入步驟，例如 `aws sso login --profile myprofile`，以便鏈從本機 SSO 快取解析而不是等待瀏覽器流程

687* 如果您的鏈執行合法需要超過 60 秒的互動式登入，例如透過 `aws-vault` 等包裝程式的 SSO 搭配 MFA，請使用 [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/zh-TW/env-vars) 以毫秒為單位提高限制

688 1087

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

690 網路和連線錯誤

691</h2>

692 1089

693這些錯誤表示來自 Claude Code 的網路請求無法到達其目的地，或 Claude Code 和 API 之間的某些東西在回程中改變了回應。它們通常源自您的本機網路、代理伺服器或防火牆，或雲端環境的網路政策。1090您可以在請求失敗之前檢查此狀態：[`/status`](/docs/zh-TW/commands) 顯示讀作 `Expired — log in again` 的 `Login` 列，加上它為過期登入儲存的組織和電子郵件。該列僅在已儲存的登入是您的活動認證資格且無法再更新時出現。以其他方式進行驗證的工作階段不會顯示該列，即使已儲存的過期登入仍然存在。在 v2.1.210 之前，`/status` 在此狀態下沒有指示登入曾經存在過，因為已清除的認證資格沒有留下任何內容供其報告。

694 1091

695<h3 id="unable-to-connect-to-api">1092**該怎麼做：**

696 無法連線到 API1093

1094* 執行 `/login` 以再次登入。在不登入的情況下重試會在每個請求上顯示相同的訊息。

1095* 在非互動式模式中，在相同環境中執行 `claude`，完成 `/login`，然後重新執行您的命令。對於無法以互動方式登入的自動化，使用 `ANTHROPIC_API_KEY` 或[使用 `claude setup-token` 產生長期權杖](/docs/zh-TW/authentication#generate-a-long-lived-token)進行驗證。

1096* 如果登入持續失敗，請參閱[登入和驗證](/docs/zh-TW/troubleshoot-install#login-and-authentication)

1097

1098<h3 id="administrator-policy-requires-a-cloud-gateway-sign-in">

1099 管理員政策需要雲端閘道登入

697</h3>1100</h3>

698 1101

699與 API 的 TCP 連線失敗或從未完成。1102此機器上的管理員[受管設定](/docs/zh-TW/managed-settings)將 [`forceLoginMethod`](/docs/zh-TW/settings-reference#forceloginmethod) 設定為 `"gateway"` 或設定 [`forceLoginGatewayUrl`](/docs/zh-TW/settings-reference#forcelogingatewayurl)。除非您透過 `CLAUDE_CODE_USE_BEDROCK` 等變數選擇雲端提供者，Claude Code 只接受 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway)登入。您會看到以下兩個訊息之一：

700 1103

701```text theme={null}1104```text theme={null}

702Unable to connect to API. Check your internet connection1105Not signed in to the Cloud gateway — run /login.

703Unable to connect to API (ECONNREFUSED)

704Unable to connect to API (ECONNRESET)

705Unable to connect to API (ETIMEDOUT)

706fetch failed

707Request timed out. Check your internet connection and proxy settings

708```1106```

709 1107

710常見原因包括沒有網際網路存取、阻止 `api.anthropic.com` 的 VPN，或未設定的必要公司代理伺服器。1108當工作階段沒有閘道登入時，模型請求會失敗，並顯示此訊息，例如因為您自政策到達機器後未執行 `/login`。

1109

1110如果您也有 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 認證資格已設定，且受管設定設定了 `forceLoginMethod`，Claude Code 會在啟動時改為結束，並顯示以下開頭的訊息：

1111

1112```text theme={null}

1113Administrator policy requires a Cloud gateway sign-in on this machine; the

1114Anthropic-issued credential configured here (ANTHROPIC_API_KEY,

1115ANTHROPIC_AUTH_TOKEN, or apiKeyHelper) is not used.

1116```

711 1117

712**該怎麼做：**1118**該怎麼做：**

713 1119

714* 透過在同一個 shell 中執行 `curl -I https://api.anthropic.com` 來確認您可以到達 API 主機。在 Windows PowerShell 上使用 `curl.exe -I https://api.anthropic.com`，以免使用內建的 `Invoke-WebRequest` 別名。1120* 執行 `/login` 並在**雲端閘道**畫面上完成登入

715* 如果您在公司代理伺服器後面，請在啟動 Claude Code 前設定 `HTTPS_PROXY`，並參閱[網路設定](/docs/zh-TW/network-config)1121* 對於啟動訊息，移除您設定的 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 設定，然後啟動 `claude` 並執行 `/login`

716* 如果您透過 LLM 閘道或中繼站路由，請將 [`ANTHROPIC_BASE_URL`](/docs/zh-TW/env-vars) 設定為其位址。請參閱[將 Claude Code 連線到 LLM 閘道](/docs/zh-TW/llm-gateway-connect)以取得設定說明。1122* 如果您認為機器不應該需要閘道，請要求管理該機器的管理員從其受管設定中移除 `forceLoginMethod` 和 `forceLoginGatewayUrl`

717* 確保您的防火牆允許[網路存取需求](/docs/zh-TW/network-config#network-access-requirements)中列出的主機

718* 間歇性故障會[自動重試](#automatic-retries)；持續性故障指向本機網路問題

719 1123

720如果 `curl` 成功但 Claude Code 仍然失敗，原因通常是執行時間和網路之間的某些東西，而不是網路本身：1124在 v2.1.265 上，迴歸也在某些使用 API 金鑰、`apiKeyHelper` 或自訂標頭進行驗證的 LLM 閘道和代理設定中顯示第一個訊息，即使機器上沒有管理員要求。更新至 v2.1.266 或更新版本。您不需要變更您的設定。

721 1125

722* 在 Linux 和 WSL 上，檢查 `/etc/resolv.conf` 是否有無法到達的名稱伺服器。特別是 WSL 可能會從主機繼承損壞的解析器。1126在 v2.1.261 之前，在將 `forceLoginMethod` 設定為 `"gateway"` 的機器上，Claude Code 使用剩餘的已儲存登入，而不是失敗模型請求，並報告已設定的環境認證資格，並顯示 `This machine's managed settings require a first-party login` 而不是啟動訊息。在 v2.1.265 之前，其受管設定僅設定 `forceLoginGatewayUrl` 的機器不需要閘道登入，Claude Code 在那裡使用剩餘的認證資格。

723* 在 macOS 上，已斷開連線或卸載的 VPN 用戶端可能會留下隧道介面或路由規則。檢查 `ifconfig` 是否有過時的 `utun` 介面，並在系統設定中移除 VPN 的網路擴充功能。

724* Docker Desktop 和類似的容器執行時間可能會攔截出站流量。結束它們並重試以排除此可能性。

725 1127

726<h3 id="bedrock-streaming-response-has-an-unexpected-content-type">1128<h3 id="your-account-is-on-hold">

727 Bedrock 串流回應有非預期的 content-type1129 您的帳戶已被暫停

728</h3>1130</h3>

729 1131

730Claude Code 和 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 之間的閘道或代理伺服器正在轉換串流回應本體或其 `Content-Type` 標頭。Amazon Bedrock 將回應串流為 `application/vnd.amazon.eventstream`，而 Claude Code 會拒絕報告不同 content-type 的成功串流回應，而不是解碼它無法讀取的本體。該請求不會重試。1132Claude 帳戶背後的登入已被暫停。Claude Code 在嘗試更新您的已儲存登入並瞭解暫停時顯示第一個訊息，在您在瀏覽器中完成的登入報告時顯示第二個訊息：

731 1133

732```text theme={null}1134```text theme={null}

733Bedrock streaming response has content-type "text/event-stream"; expected "application/vnd.amazon.eventstream". A gateway or proxy between Claude Code and Bedrock is likely transforming the response body — Bedrock's binary event-stream format must be passed through unmodified. Set CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1 to suppress this check while the gateway is being fixed.1135Your account is on hold and can't use Claude Code. View details or appeal: https://claude.ai/restricted

1136Your account is on hold and can't sign in to Claude Code. View details or appeal: https://claude.ai/restricted

734```1137```

735 1138

736在 v2.1.208 之前，相同的設定錯誤會在整個回應被緩衝後顯示為 `API Error: Truncated event message received`。1139使用相同帳戶再次登入不會清除訊息，因為暫停是在帳戶上，而不是登入上。在[非互動式模式](/docs/zh-TW/headless)(`-p`) 和 [Agent SDK](/docs/zh-TW/agent-sdk/overview) 中，結構化錯誤代碼為 `account_on_hold`。在 v2.1.235 之前，Claude Code 將被暫停的帳戶報告為[登入已過期 · 請執行 /login](#login-expired)，其復原步驟無法清除暫停。

737 1140

738**該怎麼做：**1141**該怎麼做：**

739 1142

740* 設定閘道以不修改地傳遞 `InvokeModelWithResponseStream` 回應本體及其 `Content-Type` 標頭。將串流重新發出為伺服器傳送事件的中介是常見原因。1143* 開啟訊息中的連結以檢視暫停的詳細資訊或對其提出異議

741* 如果閘道只重寫標頭並完整傳遞二進位本體，請設定 [`CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1`](/docs/zh-TW/env-vars) 以在閘道修復前跳過檢查。請參閱[閘道或代理伺服器後的串流錯誤](/docs/zh-TW/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)。1144* 如果您有另一個 Claude 帳戶或不受暫停影響的 API 金鑰，您可以在暫停解決期間繼續工作：執行 `/login` 使用該帳戶，或使用 `ANTHROPIC_API_KEY` 設定金鑰

742 1145

743<h3 id="ssl-certificate-errors">1146<h3 id="anthropic-profile-login-expired">

744 SSL 憑證錯誤1147 Anthropic 設定檔登入已過期

745</h3>1148</h3>

746 1149

747您網路上的代理伺服器或安全設備正在用其自己的憑證攔截 TLS 流量，而 Claude Code 不信任它。1150Claude Code 透過 Anthropic 認證資格設定檔進行驗證，其已儲存的登入認證資格已過期，且設定檔沒有 Claude Code 可用來更新它的重新整理認證資格。Claude Code 在本機停止每個請求，不重試，因為重試會讀取相同的過期認證資格。

748 1151

749```text theme={null}1152```text theme={null}

750Unable to connect to API: SSL certificate verification failed. Check your proxy or corporate SSL certificates1153Anthropic profile login expired · Re-authenticate your Anthropic profile

751Unable to connect to API: Self-signed certificate detected1154Anthropic profile login expired · Run /login to use your claude.ai account instead, or re-authenticate the profile

752```1155```

753 1156

754自 v2.1.199 起，憑證驗證失敗不會重試，因此此錯誤會在第一次嘗試時出現，而不是在完整[重試預算](#automatic-retries)後出現。較早的版本在顯示它之前會花費幾分鐘重試。暫時性 TLS 條件（例如握手逾時）仍會重試。1157這僅在活動認證資格來自 Anthropic 認證資格設定檔時出現，您可以使用 `ANTHROPIC_PROFILE` 環境變數選擇該設定檔，Claude Code 在您的 Anthropic 設定目錄中發現為活動設定檔，或 Claude Code 在您[登入時沒有 API 金鑰](/docs/zh-TW/authentication#sign-in-without-an-api-key)時寫入。使用 `/login` 的 claude.ai 選項、API 金鑰、持有人權杖（例如 `ANTHROPIC_AUTH_TOKEN`）或第三方提供者進行驗證的工作階段永遠不會看到此訊息。

755 1158

756在 `/login` 和啟動連線檢查期間，同樣的失敗會以 OpenSSL 代碼和內聯修復報告：1159在[提供無金鑰登入](/docs/zh-TW/authentication#sign-in-without-an-api-key)的機器上，執行 `/login`，選擇 Anthropic Console 帳戶，然後再次登入以更新無金鑰 Console 登入或 Claude Platform CLI 的 `ant auth login` 寫入的設定檔。Claude Code 替換該設定檔中的過期認證資格。對於聯盟設定檔或另一個工具建立的設定檔，`/login` 不會更新認證資格。您看到的形式取決於您是否明確選擇了設定檔或 Claude Code 發現了它：

757 1160

758```text theme={null}1161* 當您明確設定 `ANTHROPIC_PROFILE` 時，訊息以 `Re-authenticate your Anthropic profile` 結尾。

759SSL 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.1162* 當 Claude Code 從您的設定目錄發現設定檔時，訊息提供 `/login`，因為 Claude Code 優先使用有效的 `/login` 而不是發現的設定檔，然後改為使用您的 claude.ai 或 Console 帳戶進行驗證。在 v2.1.234 之前，Claude Code 在此情況下也顯示 `Re-authenticate your Anthropic profile` 形式。

760```

761 1163

762**該怎麼做：**1164**該怎麼做：**

763 1165

764* 匯出您組織的 CA 套件，並使用 `NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem` 將 Claude Code 指向它1166* 再次登入設定檔，然後重試：在[提供無金鑰登入](/docs/zh-TW/authentication#sign-in-without-an-api-key)的機器上，執行 `/login` 並為無金鑰 Console 登入或 Claude Platform CLI 的 `ant auth login` 寫入的設定檔選擇 Anthropic Console 帳戶；對於其他設定檔，使用建立它們的工具

765* 請參閱[網路設定](/docs/zh-TW/network-config#custom-ca-certificates)以取得完整設定說明1167* 如果管理員佈建了設定檔的認證資格，請要求他們簽發新的認證資格

766* 不要設定 `NODE_TLS_REJECT_UNAUTHORIZED=0`，這會完全停用憑證驗證1168* 執行 `/status` 以確認活動認證資格來源和設定檔名稱

1169* 若要停止使用設定檔，如果您設定了 `ANTHROPIC_PROFILE`，請取消設定它，然後以其他方式進行驗證，例如 `/login` 或 `ANTHROPIC_API_KEY`

767 1170

768<h3 id="host-not-allowed-in-a-cloud-session">1171<h3 id="oauth-scope-requirement">

769 雲端工作階段中不允許的主機1172 OAuth 範圍要求

770</h3>1173</h3>

771 1174

772來自雲端工作階段或例行程序的出站 HTTP 請求被環境的網路政策阻止。1175已儲存的權杖早於較新功能需要的權限範圍。您最常從 `/usage` 和狀態行使用指標看到此訊息：

773 1176

774```text theme={null}1177```text theme={null}

775HTTP 4031178OAuth token does not meet scope requirement: user:profile

776x-deny-reason: host_not_allowed

777```1179```

778 1180

779您也可能看到與目的地實際憑證不符的 TLS 憑證。雲端環境透過代理伺服器路由出站流量以強制執行網路政策，因此不符的憑證表示代理伺服器終止了連線，而不是目的地。

~~780~~

781這不是用戶端網路問題。雲端工作階段和[例行程序](/docs/zh-TW/routines)在沙箱環境內執行，其出站流量被篩選到環境的允許清單。**預設**環境使用**信任**存取，允許[預設允許清單](/docs/zh-TW/claude-code-on-the-web#default-allowed-domains)的套件登錄、雲端提供者 API、容器登錄和常見開發網域，但阻止其他所有內容。

~~782~~

783**該怎麼做：**1181**該怎麼做：**

784 1182

785* 開啟例行程序進行編輯，或啟動雲端工作階段。選擇顯示您環境名稱（例如**預設**）的雲端圖示以開啟選擇器。將滑鼠懸停在您的環境上，然後按一下設定圖示。1183* 執行 `/login` 以取得具有目前範圍的新權杖。您不需要先登出。

786* 在**更新雲端環境**對話方塊中，將**網路存取**從**信任**變更為**自訂**，然後將被阻止的網域新增到**允許的網域**。每行輸入一個網域。勾選**也包含常見套件管理員的預設清單**以在自訂網域旁保留[預設允許清單](/docs/zh-TW/claude-code-on-the-web#default-allowed-domains)。如果您想要不受限制的存取，請改為選擇**完整**。

787* 按一下**儲存變更**。下一次執行會使用更新的允許清單。

~~788~~

789請參閱[網路存取](/docs/zh-TW/claude-code-on-the-web#network-access)以取得存取層級和預設允許清單。本機 CLI 工作階段不受此政策影響。

790 1184

791<h3 id="couldnt-reconnect-to-your-remote-control-session">1185<h3 id="claude-ai-rejected-the-session-token">

792 無法重新連線到您的遠端控制工作階段1186 claude.ai 拒絕了工作階段權杖

793</h3>1187</h3>

794 1188

1189[claude.ai 連接器](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai)請求失敗，因為 claude.ai 拒絕了來自您的 Claude Code 登入的權杖，通常是已過期且無法更新的登入。被拒絕的權杖是您的登入，而不是連接器在 claude.ai 中的自身授權，因此再次授權連接器不會解決它。在 `/mcp` 中，連接器顯示為 `connected · session token rejected`，其詳細資訊檢視讀作：

1190

795```text theme={null}1191```text theme={null}

796Couldn't reconnect to your Remote Control session. Retry, or start a fresh session without --resume.1192claude.ai rejected the session token. Run /login, then reconnect.

797```1193```

798 1194

799使用 `claude --resume` 或 `claude --continue` 恢復會重新連線到該對話中記錄的[遠端控制](/docs/zh-TW/remote-control)工作階段。此訊息表示重新連線因可能是暫時性的原因（例如網路中斷或伺服器錯誤）而失敗，因此 Claude Code 無法確認遠端工作階段是否仍然存在。您的本機工作階段會繼續執行，但不使用遠端控制。

~~800~~

801**該怎麼做：**1195**該怎麼做：**

802 1196

803* 執行 `/remote-control` 以重試連線1197* 執行 `/login` 以再次登入

804* 啟動 Claude Code 時不使用 `--resume` 以建立新的遠端控制工作階段1198* 從 `/mcp` 重新連線連接器，或執行 `/mcp reconnect <server>`。在您再次登入之前重新連線會使連接器處於相同狀態。`/mcp` 面板的**重新連線**選項報告 `your claude.ai session token was rejected`；輸入的 `/mcp reconnect <server>` 形式報告成功重新連線，即使權杖仍被拒絕。

805* 如需其他遠端控制啟動訊息，請參閱[遠端控制疑難排解](/docs/zh-TW/remote-control#troubleshooting)

~~806~~

807當伺服器確認前一個工作階段不再存在時，您不會看到此訊息；Claude Code 在這種情況下會建立一個新的工作階段。在 v2.1.200 之前，任何重新連線失敗都會建立新的遠端控制工作階段，這在 claude.ai/code 的工作階段清單中留下額外的工作階段。

~~808~~

809<h2 id="request-errors">

810 請求錯誤

811</h2>

812 1199

813這些錯誤與您的請求內容有關。大多數來自 API 在拒絕請求後的回應；少數是由 Claude Code 在發送任何請求之前在本地產生的。1200在 v2.1.222 之前，Claude Code 改為將連接器標記為需要驗證，這指向您進行連接器的授權流程，即使完成它也不會解決狀態。

814 1201

815<h3 id="prompt-is-too-long">1202<h3 id="issuer-mismatch-in-authorization-response">

816 提示詞過長1203 授權回應中的簽發者不匹配

817</h3>1204</h3>

818 1205

819對話加上附加檔案超過了模型的上下文視窗。1206在 [MCP OAuth 登入](/docs/zh-TW/mcp#authenticate-with-remote-mcp-servers)期間，授權伺服器重新導向回 Claude Code，並帶有 `iss` 參數，該參數不命名 Claude Code 從伺服器的 OAuth 中繼資料預期的簽發者。此步驟中的簽發者錯誤是授權伺服器混合攻擊的樣子，因此 Claude Code 失敗登入，而不是交換授權代碼。Claude Code 在瀏覽器登入後在 `/mcp` 伺服器功能表中顯示錯誤：

820 1207

821```text theme={null}1208```text theme={null}

822Prompt is too long1209Issuer mismatch in authorization response (RFC 9207): expected "https://auth.example.com", received "https://other.example.com"

823```1210```

824 1211

1212`expected` 是來自伺服器的 OAuth 中繼資料的簽發者，`received` 是重新導向攜帶的 `iss` 值。其重新導向不攜帶 `iss` 參數的登入通過檢查，除非伺服器的中繼資料設定 `authorization_response_iss_parameter_supported`，在這種情況下 Claude Code 失敗登入。

1213

825**該怎麼做：**1214**該怎麼做：**

826 1215

827* 執行 `/compact` 來總結早期的回合並釋放空間，或執行 `/clear` 來重新開始1216* 嘗試從 `/mcp` 再次登入

828* 執行 `/context` 來查看視窗消耗的詳細分解：系統提示詞、工具、記憶檔案和訊息1217* 如果錯誤重複，請向伺服器操作員報告。修正是伺服器端的：授權伺服器必須在 `iss` 參數中傳回與在其中繼資料中宣傳的相同簽發者

829* 使用 `/mcp disable <name>` 停用您未使用的 MCP 伺服器，以從上下文中移除其工具定義1218* 若要在伺服器被修正時進行連線，請使用 [`MCP_SDK_GENERATION=v1`](/docs/zh-TW/env-vars) 啟動 Claude Code，其[執行時](/docs/zh-TW/mcp#mcp-client-runtimes)不執行此檢查。這會移除對混合攻擊的保護，因此偏好伺服器端修正

830* 修剪大型 `CLAUDE.md` 記憶檔案，或將指令移至[路徑範圍規則](/docs/zh-TW/memory#path-specific-rules)，這些規則只在相關時載入

831* 子代理繼承父工作階段中的每個 MCP 工具定義，這可能會在第一個回合之前填滿其上下文視窗。在生成子代理之前停用您未使用的 MCP 伺服器。

832* 自動壓縮預設為開啟，通常可防止此錯誤。如果您已設定 [`DISABLE_AUTO_COMPACT`](/docs/zh-TW/env-vars)，請重新啟用它或在視窗填滿之前手動執行 `/compact`。

833 1219

834請參閱[探索上下文視窗](/docs/zh-TW/context-window)以取得上下文如何填滿的互動式檢視。1220在 v2.1.232 之前，Claude Code 僅在逐步推出中或當您設定 `MCP_SDK_GENERATION=v2` 時使用 v2 執行時。

835 1221

836<h3 id="error-during-compaction-conversation-too-long">1222<h3 id="aws-credentials-expired-or-invalid">

837 壓縮期間出錯：對話過長1223 AWS 認證資格已過期或無效

838</h3>1224</h3>

839 1225

840`/compact` 本身失敗，因為沒有足夠的可用上下文來保存它產生的摘要。1226此訊息需要 Claude Code v2.1.198 或更新版本，且僅在您的設定檔中設定 [`awsAuthRefresh`](/docs/zh-TW/amazon-bedrock#advanced-credential-configuration) 時出現。您的 AWS 工作階段權杖已過期或被拒絕，Claude Code 已執行的自動重新整理未產生 API 接受的認證資格。它出現在來自 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 或 [Mantle 端點](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint) 的 401 上，這是這些提供者報告過期安全權杖的方式。

1227

1228中間的動作提示命名您設定中的 `awsAuthRefresh` 命令，因此它會有所不同。穩定的部分是前導 `AWS credentials expired or invalid`：

841 1229

842```text theme={null}1230```text theme={null}

843Error during compaction: Conversation too long. Press esc twice to go up a few messages and try again.1231AWS 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 ...

844```1232```

845 1233

846當視窗在自動壓縮觸發時已滿，或當您在看到 `Prompt is too long` 後執行 `/compact` 時，可能會發生這種情況。1234如果未設定 `awsAuthRefresh`，相同的 401 會改為顯示通用 `Please run /login` 訊息，該訊息無法重新整理 AWS 認證資格。

847 1235

848**該怎麼做：**1236**該怎麼做：**

849 1237

850* 按 Esc 兩次以開啟訊息清單並回溯幾個回合。這會從上下文中移除最近的訊息。然後再次執行 `/compact`。1238* 在另一個終端機中執行訊息中命名的 `awsAuthRefresh` 命令，例如 `aws sso login --profile myprofile`，並完成瀏覽器登入，然後重試

851* 如果回溯沒有釋放足夠的空間，執行 `/clear` 以開始新的工作階段。您之前的對話會被保留，可以使用 `/resume` 重新開啟。1239* 在互動式工作階段中，執行 `/login`，選擇**第三方平台**，然後在**使用第三方平台**下選擇 **Claude Platform on AWS · refresh credentials** 以執行相同命令，而無需重新啟動 Claude Code。請參閱[設定 AWS 認證資格](/docs/zh-TW/claude-platform-on-aws#1-configure-aws-credentials)

1240* 如果重新整理命令成功後錯誤重複，請在相同 shell 和設定檔中使用 `aws sts get-caller-identity` 確認身份在 Claude Code 外有效

852 1241

853<h3 id="request-too-large">1242<h3 id="aws-authentication-failed">

854 請求過大1243 AWS 驗證失敗

855</h3>1244</h3>

856 1245

857原始請求主體在標記化之前超過了 API 的位元組限制，通常是因為貼上了大型檔案或附件。1246此訊息需要 Claude Code v2.1.198 或更新版本，且僅在您的設定檔中設定 [`awsAuthRefresh`](/docs/zh-TW/amazon-bedrock#advanced-credential-configuration) 時出現。您的 AWS 提供者傳回 403，或 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 傳回 401。

1247

1248Claude Code 無法判斷您遇到了哪個原因。Amazon Bedrock 將過期的安全權杖報告為 403，但 403 也是它報告授權拒絕的方式，例如來自遺漏 IAM 權限或未為您的帳戶啟用的模型的 `AccessDeniedException`。

1249

1250來自 Amazon Bedrock 的 401 也會落在這裡，而不是在[AWS 認證資格已過期或無效](#aws-credentials-expired-or-invalid)下，因為 Amazon Bedrock 不將過期的權杖報告為 401。來自該端點的 401 通常來自請求路徑中的其他內容，例如公司代理。

1251

1252認證資格重新整理可以修正過期的權杖，無法修正其他原因，因此訊息提供兩者：

858 1253

859```text theme={null}1254```text theme={null}

860Request too large (max 30 MB). Double press esc to go back and remove or shrink the attached content.1255AWS 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 ...

861```1256```

862 1257

863這是 HTTP 請求的大小限制，與[上下文視窗限制](#prompt-is-too-long)分開。1258中間的動作提示命名您設定中的 `awsAuthRefresh` 命令，因此它會有所不同。穩定的部分是前導 `AWS authentication failed`。

864 1259

865**該怎麼做：**1260**該怎麼做：**

866 1261

867* 按 Esc 兩次並回溯到添加超大內容的回合之前1262* 執行訊息中命名的 `awsAuthRefresh` 命令或 `aws sso login`，以防過期的認證資格是原因

868* 按路徑參考大型檔案而不是貼上其內容，以便 Claude 可以分塊讀取它們1263* 如果您的認證資格是最新的，請確認 [IAM 設定](/docs/zh-TW/amazon-bedrock#iam-configuration)中的 IAM 權限已附加到您使用的身份，且所選模型已為您的帳戶和區域啟用

869* 對於影像，請參閱下面的[影像過大](#image-was-too-large)1264* 執行 `aws sts get-caller-identity` 以確認您的請求使用哪個身份；過時的 `AWS_PROFILE` 或預設設定檔是權限不匹配的常見原因

870 1265

871<h3 id="image-was-too-large">1266<h3 id="could-not-load-aws-or-google-cloud-credentials">

872 影像過大1267 無法載入 AWS 或 Google Cloud 認證資格

873</h3>1268</h3>

874 1269

875貼上或附加的影像超過了 API 的大小或尺寸限制。1270Claude Code 無法從 AWS 認證資格提供者鏈或從它執行的機器上的 Google 應用程式預設認證資格取得可用的認證資格，因此沒有請求到達您的雲端提供者。Claude Code 清除其快取的認證資格並在顯示此訊息之前重試兩次。`·` 之後的詳細資訊命名具體原因，例如過期的 SSO 工作階段、遺漏的應用程式預設認證資格報告為 `Could not load the default credentials`，或被拒絕的登入報告為 `invalid_grant`：

876 1271

877```text theme={null}1272```text theme={null}

878Image was too large. Double press esc to go back and try again with a smaller image.1273API Error: Could not load AWS credentials · Could not load credentials from any providers. Check or refresh your AWS credentials and try again.

879API Error: 400 ... image dimensions exceed max allowed size1274API Error: Could not load Google Cloud credentials · invalid_grant. Check or refresh your Google Cloud credentials and try again.

880```1275```

881 1276

882Claude Code 將無法處理的影像替換為文字佔位符並重試，因此後續訊息會成功。在 2.1.142 之前的版本上，貼上的影像可能會保留在對話中，並在每個後續訊息上重複相同的錯誤。若要在這些版本上恢復，請按 Esc 兩次並回溯到添加影像的回合之前。1277在[非互動式模式](/docs/zh-TW/headless)中使用 `-p` 和在 [Agent SDK](/docs/zh-TW/agent-sdk/overview) 中，結構化錯誤代碼為 `cloud_credential_error`。在 v2.1.267 之前，訊息僅顯示 `API Error:` 之後的詳細資訊文字，結構化代碼為 `server_error` 或 `unknown`。

883 1278

884**該怎麼做：**1279**該怎麼做：**

885 1280

886* 在貼上之前調整影像大小。API 接受單個影像最長邊最多 8000 像素的影像，或當許多影像在上下文中時為 2000 像素。1281* 執行您的提供者的登入命令，例如 `aws sso login --profile myprofile` 或 `gcloud auth application-default login`，然後重試。[Bedrock、Agent Platform 或 Foundry 認證資格未載入](/docs/zh-TW/troubleshoot-install#bedrock-agent-platform-or-foundry-credentials-not-loading)顯示如何在 Claude Code 外確認認證資格

887* 拍攝相關區域的更緊密螢幕截圖，而不是整個螢幕1282* 如果詳細資訊讀作 `AWS default-chain credential resolve timed out`，鏈掛起而不是失敗，因此改為遵循 [AWS default-chain credential resolve timed out](#aws-default-chain-credential-resolve-timed-out)

888 1283

889<h3 id="unable-to-resize-image">1284<h3 id="aws-default-chain-credential-resolve-timed-out">

890 無法調整影像大小1285 AWS default-chain credential resolve 逾時

891</h3>1286</h3>

892 1287

893Claude Code 無法在將附加影像發送到 API 之前將其縮小。1288AWS 預設認證資格提供者鏈未在 60 秒內產生認證資格，因此 Claude Code 停止了解析並失敗了請求。此逾時是[無法載入 AWS 或 Google Cloud 認證資格](#could-not-load-aws-or-google-cloud-credentials)的一個原因。失敗是本機認證資格解析：請求永遠不會到達 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 或 [Mantle 端點](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint)。Claude Code 在此錯誤出現之前清除其[認證資格快取](/docs/zh-TW/amazon-bedrock#credential-caching-and-resolution-timeout)並重試，因此到您看到它時，鏈已在重複嘗試中停滯。

894 1289

895```text theme={null}1290```text theme={null}

896Unable 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.1291API Error: Could not load AWS credentials · AWS default-chain credential resolve timed out. Check or refresh your AWS credentials and try again.

897Unable to resize image — dimensions exceed the 2000x2000px limit and image processing failed. Please resize the image to reduce its pixel dimensions.

898Unable to resize image (… raw, … base64). The image exceeds the … API limit and compression failed. Please resize the image manually or use a smaller image.

899Unable to resize image — could not verify image dimensions are within the 2000x2000px API limit.

900```1292```

901 1293

902Claude Code 通常會自動調整大型影像的大小。這些錯誤意味著原生影像處理器無法載入或返回錯誤，因此無法調整影像大小以符合 API 限制。1294常見原因是您的 AWS 設定檔中的 `credential_process` 命令等待它無法接收的輸入，以及其執行個體中繼資料服務 (IMDS) 永遠不會回答鏈探測的容器或 VM。

1295

1296在 v2.1.267 之前，訊息讀作 `API Error: AWS default-chain credential resolve timed out`。

1297在 v2.1.207 之前，停滯的鏈使請求無限期等待，而不是失敗。

903 1298

904**該怎麼做：**1299**該怎麼做：**

905 1300

906* 如果訊息要求您轉換影像，請將其轉換為 PNG、JPEG、GIF 或 WebP，然後再次附加。Claude Code 可以驗證這些格式的尺寸，無需影像處理器。1301* 在相同 shell 中使用相同 `AWS_PROFILE` 執行 `aws sts get-caller-identity`。如果它也掛起，請修正設定檔；以互動方式提示的 `credential_process` 命令是常見原因。

907* 如果訊息報告尺寸或大小限制，請在附加之前將影像調整或重新壓縮到該限制以下。1302* 在啟動 Claude Code 之前完成登入步驟，例如 `aws sso login --profile myprofile`，以便鏈從本機 SSO 快取解析，而不是等待瀏覽器流程

1303* 如果您的鏈執行合法需要超過 60 秒的互動式登入，例如透過 `aws-vault` 等包裝程式的 SSO 與 MFA，請使用 [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/zh-TW/env-vars) 以毫秒為單位提高限制

908 1304

909<h3 id="pdf-errors">1305<h3 id="bedrock-setup-verification-timed-out-waiting-for-aws">

910 PDF 錯誤1306 Bedrock 設定驗證逾時等待 AWS

911</h3>1307</h3>

912 1308

913您附加的 PDF 無法處理。1309在 [Bedrock 設定精靈](/docs/zh-TW/amazon-bedrock#sign-in-with-bedrock)的認證資格驗證期間對 AWS 的呼叫（例如認證資格查詢或身份檢查）未在 60 秒限制內完成。精靈停止等待並失敗驗證步驟：

914 1310

915```text theme={null}1311```text theme={null}

916PDF too large (max 100 pages, 32 MB). Try splitting it or extracting text first.1312Timed out after 60s waiting for AWS. Check your network and proxy settings; if a credential helper needs longer to prompt you, raise CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS.

917PDF is password protected. Try removing protection or extracting text first.

918The PDF file was not valid. Try converting to a different format first.

919```1313```

920 1314

921**該怎麼做：**1315該數字反映您的限制：預設 60 秒，或您在 [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/zh-TW/env-vars) 中設定的值。

922 1316

923* 對於超大 PDF，請要求 Claude 使用 Read 工具讀取頁面範圍，而不是附加整個檔案，或使用 `pdftotext` 之類的工具提取文字並按路徑參考輸出檔案1317常見原因是停滯對 AWS 的請求的網路或代理，包括 SSO 權杖重新整理，以及仍在等待您看不到的輸入的認證資格協助程式。僅在協助程式合法需要更多時間時提高限制。

924* 對於受保護或無效的 PDF，移除密碼或從其源應用程式重新匯出檔案，然後重試

925 1318

926<h3 id="extra-inputs-are-not-permitted">1319對 AWS 的單一停滯請求也可能在其自身的每個請求逾時上失敗，這在相同步驟上顯示較短的訊息：

1320

1321```text theme={null}

1322A request to AWS timed out. Check your network and proxy settings, then try again.

1323```

1324

1325當相同的逾時發生在模型釘選步驟上時，精靈會將模型標記為 `unreachable`，而不是顯示任一訊息。

1326

1327**該怎麼做：**

1328

1329* 在相同 shell 中執行 `aws sts get-caller-identity`。如果它也掛起，停滯在 Claude Code 外，在您的網路、您的代理或您的 AWS 設定檔中的認證資格協助程式中；首先修正那個。

1330* 在開啟精靈之前完成任何互動式登入，例如 `aws sso login --profile myprofile`

1331* 如果您的 AWS 設定檔中的認證資格協助程式合法需要超過 60 秒來提示您，請使用 [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/zh-TW/env-vars) 以毫秒為單位提高限制

1332

1333<h3 id="cloud-gateway-session-expired">

1334 雲端閘道工作階段已過期

1335</h3>

1336

1337您透過 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway)登入，此機器上儲存的閘道工作階段已過期且無法更新，或閘道不再接受它，例如在閘道的 [JWT 機密被替換](/docs/zh-TW/claude-apps-gateway-deploy#jwt-secret-rotation)後。如果您在以互動方式啟動 `claude` 時看到此行，工作階段已開啟，未登入閘道：

1338

1339```text theme={null}

1340Cloud gateway session expired — run /login to reconnect.

1341```

1342

1343相同的行可以在工作階段中期出現，當閘道認證資格過期且 Claude Code 無法更新它時。

1344

1345在[非互動式](/docs/zh-TW/headless)執行、背景或其他無人值守工作階段或 `claude` 子命令（除了 `claude auth`）中，Claude Code 會在閘道不再接受工作階段時改為結束，並顯示此訊息：

1346

1347```text theme={null}

1348Cloud gateway <url> no longer accepts this session. Start `claude` and sign in again with /login.

1349```

1350

1351**該怎麼做：**

1352

1353* 在工作階段中執行 `/login` 並完成瀏覽器登入

1354* 對於非互動式啟動，在相同環境中啟動 `claude`，執行 `/login`，然後重新執行您的命令

1355

1356<h2 id="network-and-connection-errors">

1357 網路和連線錯誤

1358</h2>

1359

1360大多數這些錯誤表示來自 Claude Code 的網路請求無法到達其目的地，或 Claude Code 和 API 之間的某些東西在回程中改變了回應；如果條目也有本機原因（例如失敗的封存寫入），其內容會說明。它們通常源自您的本機網路、代理或防火牆，或雲端環境的網路原則。

1361

1362<h3 id="unable-to-connect-to-api">

1363 無法連線到 API

1364</h3>

1365

1366到 API 的 TCP 連線失敗或從未完成。對於常見的連線錯誤代碼，訊息會命名失敗的類型並在括號中保留代碼：

1367

1368```text theme={null}

1369Unable to connect to API. Check your internet connection

1370Connection refused — a firewall or proxy may be blocking it (ConnectionRefused)

1371Can't reach the API server — check your internet or DNS (ENOTFOUND)

1372No internet route — check your connection or VPN (EHOSTUNREACH)

1373Couldn't connect through your proxy (ERR_PROXY_TUNNEL)

1374Connection dropped (ECONNRESET)

1375fetch failed

1376Request timed out. Check your internet connection and proxy settings

1377```

1378

1379Claude Code 無法識別的代碼會顯示為 `Unable to connect to API` 後跟括號中的代碼。某些這些訊息可以顯示多個代碼：例如 `Connection refused` 可以顯示 `ConnectionRefused` 或 `ECONNREFUSED`，而 `Can't reach the API server` 可以顯示 `ENOTFOUND` 或 `FailedToOpenSocket`。

1380

1381在 v2.1.227 之前，這些編碼訊息中的每一個都讀作 `Unable to connect to API` 後跟代碼，例如 `Unable to connect to API (ECONNREFUSED)`。

1382

1383常見原因包括沒有網際網路存取、阻止 `api.anthropic.com` 的 VPN，或未設定的必需公司代理。

1384

1385**該怎麼做：**

1386

1387* 通過從同一個 shell 執行 `curl -I https://api.anthropic.com` 來確認您可以到達 API 主機。在 Windows PowerShell 上使用 `curl.exe -I https://api.anthropic.com`，以便不使用內建的 `Invoke-WebRequest` 別名。

1388* 如果您在公司代理後面，在啟動 Claude Code 之前設定 `HTTPS_PROXY` 並查看[網路設定](/docs/zh-TW/network-config)

1389* 如果您通過 LLM 閘道或中繼路由，將 [`ANTHROPIC_BASE_URL`](/docs/zh-TW/env-vars) 設定為其位址。請參閱[將 Claude Code 連線到 LLM 閘道](/docs/zh-TW/llm-gateway-connect)以進行設定。

1390* 確保您的防火牆允許[網路存取要求](/docs/zh-TW/network-config#network-access-requirements)中列出的主機

1391* 間歇性故障會[自動重試](#automatic-retries)；持續故障指向本機網路問題

1392

1393如果 `curl` 成功但 Claude Code 仍然失敗，原因通常是執行時和網路之間的某些東西，而不是網路本身：

1394

1395* 在 Linux 和 WSL 上，檢查 `/etc/resolv.conf` 是否有無法到達的名稱伺服器。特別是 WSL 可以從主機繼承損壞的解析器。

1396* 在 macOS 上，已斷開連線或卸載的 VPN 用戶端可能會留下隧道介面或路由規則。檢查 `ifconfig` 是否有過時的 `utun` 介面，並在系統設定中移除 VPN 的網路擴充功能。

1397* Docker Desktop 和類似的容器執行時可以攔截出站流量。退出它們並重試以排除這種可能性。

1398

1399<h3 id="unable-to-connect-to-anthropic-services">

1400 無法連線到 Anthropic 服務

1401</h3>

1402

1403在首次執行設定期間，Claude Code 會檢查它是否可以到達 `api.anthropic.com` 和 `platform.claude.com`，然後才顯示登入步驟。當任一檢查失敗時，Claude Code 會列印原因並退出。

1404

1405```text theme={null}

1406Unable to connect to Anthropic services

1407Failed to connect to api.anthropic.com: ECONNREFUSED

1408Connection to api.anthropic.com timed out after 10 seconds

1409A proxy is configured via HTTPS_PROXY. Check that it allows connections to the host above.

1410```

1411

1412Claude Code 通過與 API 請求相同的[代理設定](/docs/zh-TW/network-config)發送檢查，並給每個探測 10 秒。當失敗的探測通過代理時，訊息會命名設定它的環境變數，例如 `HTTPS_PROXY`。在 v2.1.222 之前，檢查使用不同的代理傳輸，沒有逾時：在具有 `https://` 方案的代理 URL 後面，它可能會在 `Checking connectivity...` 上無限期停滯，然後即使通過同一代理的 API 請求成功也會失敗。

1413

1414當[受管設定檔案、MDM 原則或原則協助程式](/docs/zh-TW/managed-settings)將 [`forceLoginMethod`](/docs/zh-TW/settings-reference#forceloginmethod) 設定為 `"gateway"`，或設定 [`forceLoginGatewayUrl`](/docs/zh-TW/settings-reference#forcelogingatewayurl) 而不設定 `forceLoginMethod` 時，Claude Code 會跳過此檢查。使用任一設定，Claude Code 會在**雲端閘道**畫面上開啟登入步驟，而不是 Anthropic 登入方法。當機器上存在受管設定來源但無法讀取時，Claude Code 也會跳過檢查，因為該來源可能保有閘道設定。在 v2.1.247 之前，Claude Code 在此設定下也執行檢查，當 Anthropic 的端點無法到達時以此錯誤退出。

1415

1416**該怎麼做：**

1417

1418* 如果訊息命名代理變數，檢查其值是否指向正確的代理，並要求您的網路團隊允許通過它到訊息中主機的 HTTPS 連線。請參閱[網路設定](/docs/zh-TW/network-config)。

1419* 完成[無法連線到 API](#unable-to-connect-to-api) 中的檢查。那裡的 `curl` 測試和防火牆指導也適用於此檢查。

1420* 如果您的組織通過[雲端閘道](/docs/zh-TW/claude-apps-gateway)登入，並且此錯誤出現在首次執行時，請更新到 Claude Code v2.1.247 或更新版本。

1421* 如果您的網路是開放的，故障仍然存在，Claude Code 可能在您的國家[無法使用](https://www.anthropic.com/supported-countries)

1422

1423<h3 id="socket-is-closed">

1424 Socket 已關閉

1425</h3>

1426

1427`Socket is closed` 表示承載串流回應的連線在回應仍在到達時被關閉。最常見的原因是 Windows 上的公司代理在回應中途丟棄已建立的隧道。

1428

1429根據回應進行的距離，Claude Code 會重試請求、保留 Claude 產生的內容，或結束回合。請參閱[自動重試](#automatic-retries)。

1430

1431在 v2.1.214 之前，Claude Code 不會重試此故障，回合會停止並出現包含 `Socket is closed` 的錯誤。

1432

1433**該怎麼做：**

1434

1435* 如果您看到此錯誤，請使用 `claude update` 更新到 v2.1.214 或更新版本，然後再次傳送您的訊息

1436* 如果在更新後回合在同一代理後面持續失敗，請完成[無法連線到 API](#unable-to-connect-to-api) 並檢查[網路設定](/docs/zh-TW/network-config)中的代理設定

1437

1438<h3 id="api-returned-an-empty-or-malformed-response">

1439 API 傳回空的或格式不正確的回應

1440</h3>

1441

1442當 Claude Code 對失敗的串流請求進行非串流重試時，如果獲得 HTTP 成功狀態但主體不是 Claude API 訊息，Claude Code 會顯示此錯誤：通常是 HTML 錯誤或登入頁面、空主體或其他格式的 JSON。代理、閘道或網路登入頁面代替 API 回答是常見來源。Claude Code 不會重試請求，回合以此錯誤結束。

1443

1444```text theme={null}

1445API returned an empty or malformed response (HTTP 200) — check for a proxy or gateway intercepting the request.

1446```

1447

1448在該開頭之後，訊息會報告返回的內容以及哪個請求失敗：

1449

1450* 一個 `Response:` 子句，包含內容類型、主體類型（例如 `body is an HTML page` 或 `empty body`）、其大小（以位元組為單位），以及回應是否攜帶 Anthropic 請求 id。當回應命名可識別的伺服器（例如 `nginx` 或 `cloudflare`）或攜帶中介標頭（例如 `cf-ray` 或 `via`）時，子句也會列出這些。

1451* 一個句子，命名失敗的串流請求的 id 和觸發重試的故障。當串流在故障前開啟時，它也會報告有多少串流事件到達，以及如果有的話，當嘗試失敗時串流已沉默多長時間。

1452

1453在 v2.1.234 之前，訊息在 `intercepting the request` 後結束。

1454

1455**該怎麼做：**

1456

1457* 閱讀 `Response:` 子句以查看哪個系統回答。HTML 主體、沒有 Anthropic 請求 id 或命名的伺服器（例如 `nginx` 或 `cloudflare`）表示 Claude Code 和 API 之間的某些東西代替它回答

1458* 如果您通過[LLM 閘道](/docs/zh-TW/llm-gateway-connect#troubleshoot-gateway-errors)路由，使用直接請求測試路由，並修復返回非 API 回應的跳躍

1459* 在具有登入頁面的網路上（例如訪客 Wi-Fi），在瀏覽器中完成登入，然後重試

1460* 如果只有通過您的閘道的非串流路由損壞，設定 [`CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1`](/docs/zh-TW/env-vars#variables)，以便在串流中途失敗的請求進入正常重試路徑而不是此回退，除非串流端點本身傳回 `404`，Claude Code 仍然會回退

1461

1462<h3 id="streaming-response-ended-before-any-complete-data-was-received">

1463 串流回應在收到任何完整資料之前結束

1464</h3>

1465

1466來自您的模型提供者的串流回應完成，但未傳遞任何可用資料，因此 Claude Code 重新傳送請求而不進行串流以完成回合。Claude Code 每個工作階段顯示一次警告，僅在互動式工作階段中。在 v2.1.239 之前，Claude Code 無聲地重試而不進行串流。

1467

1468```text theme={null}

1469Streaming response ended before any complete data was received. Retrying without streaming. If this keeps happening, check any proxy or gateway between Claude Code and your model provider.

1470```

1471

1472Claude Code 傳送每個受影響的請求兩次：空串流嘗試和重試。常見原因是在回程中消耗或轉換串流回應主體的代理或閘道。

1473

1474**該怎麼做：**

1475

1476* 設定 Claude Code 和您的模型提供者之間的任何代理或閘道，以未修改的方式傳遞串流回應主體及其標頭

1477* 在 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 上，請參閱[閘道或代理後面的串流錯誤](/docs/zh-TW/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)以了解標頭和主體要求

1478

1479<h3 id="bedrock-streaming-response-has-an-unexpected-content-type">

1480 Bedrock 串流回應具有意外的 content-type

1481</h3>

1482

1483Claude Code 和 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 之間的閘道或代理正在轉換串流回應主體或其 `Content-Type` 標頭。Amazon Bedrock 將回應串流為 `application/vnd.amazon.eventstream`。Claude Code 不會解碼無法讀取的主體，而是拒絕報告不同 content-type 的成功串流回應。Claude Code 不會重試請求。

1484

1485```text theme={null}

1486Bedrock streaming response has content-type "text/event-stream"; expected "application/vnd.amazon.eventstream". A gateway or proxy between Claude Code and Bedrock is likely transforming the response body — Bedrock's binary event-stream format must be passed through unmodified. Set CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1 to suppress this check while the gateway is being fixed.

1487```

1488

1489在 v2.1.208 之前，相同的設定錯誤在整個回應被緩衝後顯示為 `API Error: Truncated event message received`。

1490

1491**該怎麼做：**

1492

1493* 設定閘道以未修改的方式傳遞 `InvokeModelWithResponseStream` 回應主體及其 `Content-Type` 標頭。重新發出串流為伺服器傳送事件的中介是常見原因。

1494* 設定 [`CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1`](/docs/zh-TW/env-vars) 會隱藏此錯誤，但 Claude Code 不會在重寫的標頭下解碼二進位主體，因此這些請求會回退到較慢的非串流路徑。請參閱[閘道或代理後面的串流錯誤](/docs/zh-TW/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)。

1495

1496<h3 id="ssl-certificate-errors">

1497 SSL 憑證錯誤

1498</h3>

1499

1500您網路上的代理或安全應用程式正在使用自己的憑證攔截 TLS 流量，Claude Code 不信任它。

1501

1502```text theme={null}

1503Unable to connect to API: SSL certificate verification failed. Check your proxy or corporate SSL certificates

1504Unable to connect to API: Self-signed certificate detected. Check your proxy or corporate SSL certificates

1505```

1506

1507從 v2.1.199 開始，憑證驗證失敗不會重試，因此此錯誤會在第一次嘗試時出現，而不是在完整[重試預算](#automatic-retries)後出現。較早的版本在顯示它之前花費幾分鐘重試。暫時性 TLS 條件（例如握手逾時）仍然會重試。

1508

1509在 `/login` 和啟動連線檢查期間，相同的故障會報告為 OpenSSL 代碼和內聯修復：

1510

1511```text theme={null}

1512SSL 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.

1513```

1514

1515在 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 上，Claude Code 本身發送給 AWS 的請求（例如 STS 和 SSO 角色認證呼叫、模型發現和設定精靈的檢查）取決於相同的憑證設定。請參閱[TLS 檢查代理後面的憑證錯誤](/docs/zh-TW/amazon-bedrock#certificate-errors-behind-a-tls-inspecting-proxy)。

1516

1517**該怎麼做：**

1518

1519* 匯出您組織的 CA 套件，並使用 `NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem` 將 Claude Code 指向它

1520* 請參閱[網路設定](/docs/zh-TW/network-config#custom-ca-certificates)以了解完整設定說明

1521* 不要設定 `NODE_TLS_REJECT_UNAUTHORIZED=0`，這會完全停用憑證驗證

1522

1523<h3 id="host-not-allowed-in-a-cloud-session">

1524 雲端工作階段中不允許主機

1525</h3>

1526

1527來自雲端工作階段或例行程式的出站 HTTP 請求被環境的網路原則阻止。

1528

1529```text theme={null}

1530HTTP 403

1531x-deny-reason: host_not_allowed

1532```

1533

1534您也可能看到與目的地的真實憑證不符的 TLS 憑證。雲端工作階段通過代理路由出站流量，該代理強制執行網路原則，因此不符的憑證表示代理終止了連線，而不是目的地。

1535

1536這不是用戶端網路問題。雲端工作階段和[例行程式](/docs/zh-TW/routines)在沙箱 VM 內執行，其通過工作階段網路的出站流量被過濾到[雲端環境的](/docs/zh-TW/cloud-environments)允許清單；[GitHub 操作](/docs/zh-TW/cloud-environments#github-proxy)和 MCP 連接器流量使用單獨的通道，這就是為什麼它們可以在其他主機被阻止時繼續工作。**預設**環境使用**信任**存取，允許[預設允許清單](/docs/zh-TW/cloud-environments#default-allowed-domains)的套件登錄、雲端提供者 API、容器登錄和常見開發網域，並阻止該路徑上的其他網域。

1537

1538**該怎麼做：**

1539

1540* 開啟例行程式進行編輯，或啟動雲端工作階段。選擇顯示您環境名稱的雲端圖示（例如**預設**）以開啟選擇器。將滑鼠懸停在您的環境上，然後按一下設定圖示。

1541* 在**更新雲端環境**對話方塊中，將**網路存取**從**信任**變更為**自訂**，然後將被阻止的網域新增到**允許的網域**。每行輸入一個網域。檢查**也包括常見套件管理員的預設清單**以在您的自訂網域旁邊保留[預設允許清單](/docs/zh-TW/cloud-environments#default-allowed-domains)。如果您想要不受限制的存取，請改為選擇**完整**。

1542* 按一下**儲存變更**。下一次執行使用更新的允許清單。

1543

1544請參閱[網路存取](/docs/zh-TW/cloud-environments#network-access)以了解存取層級和預設允許清單。本機 CLI 工作階段不受此原則影響。

1545

1546<h3 id="the-proxy-refused-the-connection">

1547 代理拒絕了連線

1548</h3>

1549

1550當 Claude 通過您在 `HTTPS_PROXY` 中設定的代理或相關[代理變數](/docs/zh-TW/network-config#environment-variables)讀取[成品](/docs/zh-TW/artifacts)時，您會看到此訊息。成品內容來自 `*.frame.claudeusercontent.com`，因此 Claude Code 首先向代理傳送 `CONNECT` 請求，要求它開啟到該主機的隧道。當代理拒絕時，沒有任何東西到達主機，訊息攜帶代理的 HTTP 狀態：

1551

1552```text theme={null}

1553artifact content fetch failed (proxy refused the connection: HTTP 407)

1554artifact content fetch failed (proxy refused the connection: HTTP 403)

1555the proxy refused the connection to the artifact's content host (HTTP 502)

1556```

1557

1558狀態是代理對 `CONNECT` 的回答。主機從未回答，因此每個狀態指向不同的修復：

1559

1560* `HTTP 407`：代理需要它沒有獲得的認證。將它們放在代理 URL 中，如[基本驗證](/docs/zh-TW/network-config#basic-authentication)所示。

1561* `HTTP 403`：代理拒絕隧道到 `*.frame.claudeusercontent.com`。要求運行代理的人允許該主機，[網路存取要求](/docs/zh-TW/network-config#network-access-requirements)會列出該主機。

1562* 任何其他狀態，例如 `HTTP 502`：代理因其自身原因未開啟隧道，例如無法到達主機。在代理的日誌中查詢狀態。

1563* `unreadable reply` 代替狀態：代理位址上的任何東西都沒有用 HTTP 狀態行回答。檢查位址是否為 HTTP 代理。

1564

1565**該怎麼做：**

1566

1567* 檢查代理變數中的位址和認證，如[代理設定](/docs/zh-TW/network-config#proxy-configuration)所述，然後從啟動 Claude Code 的 shell 執行 `curl -x http://proxy.example.com:8080 -I https://api.anthropic.com`，使用您自己的代理 URL。在 Windows PowerShell 上，執行 `curl.exe`。如果此探測以相同方式失敗，請先修復代理設定。如果成功，拒絕特定於成品主機。

1568* 如果您的網路讓 Claude Code 直接到達成品主機，將 `.frame.claudeusercontent.com` 新增到 [`NO_PROXY`](/docs/zh-TW/network-config#environment-variables)。保持條目狹窄：更廣泛的 `.claudeusercontent.com` 條目也會繞過 `bridge.claudeusercontent.com` 的代理，具有 [IP 允許清單](/docs/zh-TW/network-config#organization-ip-allowlists-and-proxy-egress)的組織需要將其保留在代理上。

1569

1570在 v2.1.238 之前，Claude Code 將拒絕的隧道報告為通用網路錯誤。

1571

1572<h3 id="the-cloud-environments-service-returned-an-empty-or-unexpected-response">

1573 雲端環境服務傳回空的或意外的回應

1574</h3>

1575

1576Claude Code 在多個點請求您的[雲端環境](/docs/zh-TW/cloud-environments)清單，例如當您從 CLI 建立雲端工作階段或執行 [`/remote-env`](/docs/zh-TW/cloud-environments#select-an-environment-from-the-cli) 時。當它無法讀取伺服器的回答時，它會顯示以下其中一個訊息：

1577

1578```text theme={null}

1579The cloud environments service returned an empty response (HTTP 200 with no body). This is usually temporary — try again in a moment.

1580The cloud environments service returned a response in an unexpected format (HTTP 200 with a non-JSON body). This is usually temporary — try again in a moment.

1581The cloud environments service returned a response in an unexpected format (HTTP 200 without a usable environments list). This is usually temporary — try again in a moment.

1582```

1583

1584伺服器接受了請求，但用不是環境清單的主體回答：空、不是 JSON 或沒有清單的 JSON。這通常伴隨服務端中斷，並自行清除。根據請求清單的表面，Claude Code 可能會新增前綴，例如 `/remote-env` 對話方塊中的 `couldn't list environments:`。

1585

1586**該怎麼做：**

1587

1588* 重試該操作。Claude Code 每次都會再次請求清單

1589* 如果訊息持續出現，請檢查 [status.claude.com](https://status.claude.com) 以了解活躍的事件

1590

1591在 v2.1.236 之前，Claude Code 顯示原始 JavaScript TypeError 而不是這些訊息。

1592

1593<h3 id="couldnt-reconnect-to-your-remote-control-session">

1594 無法重新連線到您的 Remote Control 工作階段

1595</h3>

1596

1597```text theme={null}

1598Couldn't reconnect to your Remote Control session. Retry, or start a fresh session without --resume.

1599```

1600

1601使用 `claude --resume` 或 `claude --continue` 重新開始會重新連線到該對話中記錄的 [Remote Control](/docs/zh-TW/remote-control) 工作階段。此訊息表示重新連線因可能是暫時的原因（例如網路中斷或伺服器錯誤）而失敗，因此 Claude Code 無法確認遠端工作階段是否仍然存在。您的本機工作階段在沒有 Remote Control 的情況下繼續執行。

1602

1603**該怎麼做：**

1604

1605* 執行 `/remote-control` 以重試連線

1606* 使用 `claude --remote-control` 啟動新工作階段以建立新的 Remote Control 工作階段

1607* 對於其他 Remote Control 啟動訊息，請參閱[Remote Control 疑難排解](/docs/zh-TW/remote-control#troubleshooting)

1608

1609如果伺服器改為報告前一個工作階段已消失，您不會看到此訊息。Claude Code 會在其位置啟動新工作階段或顯示 [`Previous session is unavailable — run /remote-control to start a new one`](/docs/zh-TW/remote-control#previous-session-is-unavailable)，取決於[對話的重新連線記錄](/docs/zh-TW/remote-control#resume-outcomes)。從 v2.1.227 到 v2.1.231，Claude Code 改為顯示以 `Remote Control could not resume the previous session under the current login` 開頭的訊息，[較早的版本行為也不同](/docs/zh-TW/remote-control#reconnect-history)。

1610

1611<h3 id="sessions-ended-while-this-machine-was-offline">

1612 此機器離線時工作階段已結束

1613</h3>

1614

1615Claude Code 在執行 [`claude remote-control`](/docs/zh-TW/remote-control#start-a-remote-control-session) 的終端中顯示此訊息，在您的機器離線足夠長的時間後，伺服器清理了您的機器正在提供的 Remote Control 環境。該環境中的工作階段已結束，您無法恢復它們。計數是已結束的工作階段數。

1616

1617```text theme={null}

16182 sessions ended while this machine was offline — the environment was cleaned up on the server and can't be resumed.

1619```

1620

1621**該怎麼做：**

1622

1623* 當 Claude Code 在此訊息下列出保留的 worktrees 時，從它們中拿起任何未提交的工作

1624* 執行 `claude remote-control` 以啟動新環境

1625

1626<h3 id="couldnt-share-the-transcript">

1627 無法共享文字記錄

1628</h3>

1629

1630在您同意從調查提示（例如[工作階段品質調查](/docs/zh-TW/data-usage#session-quality-surveys)）共享您的工作階段文字記錄後，Claude Code 將其上傳到 Anthropic，或在第三方提供者上、[Claude apps 閘道](/docs/zh-TW/claude-apps-gateway)工作階段上以及當沒有 Anthropic 認證可用時改為儲存本機封存。此訊息表示共享未完成。

1631

1632```text theme={null}

1633Couldn't share the transcript.

1634```

1635

1636上傳必須符合 8 MiB 限制。在長工作階段上，Claude Code 逐步丟棄共享的部分，最後一個請求的模型設定優先，然後是結構化對話和子代理文字記錄，並且只在無法傳送任何縮減版本或網路或伺服器錯誤停止上傳時顯示此訊息。當 Claude Code 改為儲存本機封存時，訊息表示它無法寫入封存。

1637

1638**該怎麼做：**

1639

1640* 執行 `/feedback` 以傳送文字記錄並描述發生了什麼。如果您的環境中無法使用 `/feedback`，請參閱[報告錯誤](#report-an-error)

1641* 如果其他請求也失敗，請檢查您的網路連線並查看[無法連線到 API](#unable-to-connect-to-api)

1642

1643<h2 id="request-errors">

1644 請求錯誤

1645</h2>

1646

1647這些錯誤與您的請求內容有關。大多數來自 API 在拒絕請求後的回應；少數是由 Claude Code 在發送任何請求之前在本地產生的。

1648

1649<h3 id="prompt-is-too-long">

1650 提示詞過長

1651</h3>

1652

1653對話加上附加檔案超過了模型的上下文視窗。

1654

1655```text theme={null}

1656Prompt is too long

1657```

1658

1659在互動式工作階段中，Claude Code 將此錯誤顯示為：

1660

1661```text theme={null}

1662Context limit reached · /compact or /clear to continue

1663```

1664

1665當設定了 [`DISABLE_COMPACT`](/docs/zh-TW/env-vars) 時，該行僅命名 `/clear`。較長形式的錯誤，例如下面的壓縮失敗形式，保留 `Prompt is too long ·` 的措辭。在 `-p` 輸出和文字記錄中，文字保持為 `Prompt is too long`。

1666

1667當您在 [使用者設定](/docs/zh-TW/settings-reference#autocompactenabled) 中關閉自動壓縮時，該行也會說明這一點：

1668

1669```text theme={null}

1670Context limit reached · /compact or /clear to continue · auto-compact is off · /config to turn it on

1671```

1672

1673`/config` 中的 **Auto-compact** 切換會將 `autoCompactEnabled` 寫入使用者設定。該提示僅在 `/config` 變更會生效時出現。例如，當 [`DISABLE_AUTO_COMPACT`](/docs/zh-TW/env-vars) 或 [`DISABLE_COMPACT`](/docs/zh-TW/env-vars) 關閉自動壓縮時，它不會出現。當更高優先級的範圍（例如專案或受管設定）將 `autoCompactEnabled` 設定為 `false` 時，它也不會出現。在 v2.1.235 之前，該行不包含自動壓縮提示。

1674

1675Amazon Bedrock 將此狀況報告為 `Input is too long for requested model.`，Claude Code 以相同方式處理。在 v2.1.217 之前，Claude Code 沒有識別 Bedrock 的措辭，因此自動壓縮從未在其上觸發，`/compact` 失敗並出現相同錯誤。

1676

1677[Claude apps gateway](/docs/zh-TW/claude-apps-gateway-config#upstream-error-messages) 在雲端上游以提供者自己的錯誤形狀拒絕請求時，將此狀況報告為 `capability_rejected: prompt_too_long`。Claude Code 將該令牌視為與 `Prompt is too long` 相同。在 v2.1.228 之前，Claude Code 沒有識別該令牌，因此自動壓縮沒有在其上觸發。

1678

1679當自動壓縮在此輪上執行並在基礎錯誤（例如不可用的模型或驗證失敗）上失敗時，該訊息在分隔符後命名該錯誤：

1680

1681```text theme={null}

1682Prompt is too long · automatic compaction failed: <the underlying error>

1683```

1684

1685首先解決命名的錯誤；在您這樣做之前，`/compact` 會在相同錯誤上失敗。在 v2.1.229 之前，失敗的自動壓縮會顯示 `Prompt is too long` 而不顯示原因。

1686

1687單一交換對話沒有較早的輪次可以總結。當自動壓縮會在其上執行時，Claude Code 會跳過嘗試並解釋填充請求的內容。當 API 在其錯誤中不報告令牌計數時，訊息讀取：

1688

1689```text theme={null}

1690Prompt is too long · this conversation is a single exchange and cannot be compacted — the request size comes mostly from system prompt, tool definitions, or attachments.

1691```

1692

1693當 API 在其錯誤中報告令牌計數時，Claude Code 將其與自己對對話大小的估計進行比較，以判斷請求的大部分是什麼：對話自己的內容，或 Claude Code 與其一起發送的系統提示、工具定義和附加內容。當對話自己的內容是請求的大部分時，訊息讀取：

1694

1695```text theme={null}

1696Prompt is too long · the request is ~<request tokens> tokens (limit <limit>) and this conversation's own content is most of it. A single-exchange conversation cannot be compacted; start with less content (smaller files or pasted text).

1697```

1698

1699當請求的大部分在對話之外時，訊息讀取：

1700

1701```text theme={null}

1702Prompt is too long · the request is ~<request tokens> tokens (limit <limit>) but this conversation is only ~<conversation tokens> tokens — the rest is system prompt, tool definitions, and attachment content. A single-exchange conversation cannot be compacted; reduce attached files/tools or start with less context.

1703```

1704

1705在 v2.1.162 之前，Claude Code 嘗試了壓縮，並在失敗時顯示裸露的 `Prompt is too long`。

1706

1707**該怎麼辦：**

1708

1709* 在多輪對話中，執行 `/compact` 以總結較早的輪次並釋放空間，或執行 `/clear` 以重新開始。單一交換對話無法壓縮，因此請縮小請求

1710* 執行 `/context` 以查看視窗消耗內容的分解：系統提示、工具、記憶檔案和訊息

1711* 使用 `/mcp disable <name>` 禁用您未使用的 MCP 伺服器，以從上下文中移除其工具定義

1712* 修剪大型 `CLAUDE.md` 記憶檔案，或將指示移至 [路徑範圍規則](/docs/zh-TW/memory#path-specific-rules)，這些規則僅在相關時載入

1713* 子代理繼承父工作階段的每個 MCP 工具定義，這可能在第一輪之前填滿其上下文視窗。在生成子代理之前，禁用您未使用的 MCP 伺服器。

1714* 自動壓縮預設為開啟，通常可防止此錯誤。如果您在 `/config` 中或使用 [`DISABLE_AUTO_COMPACT`](/docs/zh-TW/env-vars) 關閉了它，請將其重新開啟。如果您保持關閉，請在視窗填滿之前自己執行 `/compact`。

1715

1716請參閱 [探索上下文視窗](/docs/zh-TW/context-window) 以互動方式查看上下文如何填滿。

1717

1718<h3 id="context-exceeds-the-token-limit">

1719 上下文超過令牌限制

1720</h3>

1721

1722當對話超過模型的上下文視窗時，`/context` 在其輸出頂部顯示此警告。在您釋放空間之前，請求會失敗並出現 [`Prompt is too long`](#prompt-is-too-long)。互動式工作階段將該錯誤顯示為 `Context limit reached` 行。

1723

1724```text theme={null}

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

1726```

1727

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

1729

1730```text theme={null}

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

1732```

1733

1734當您設定了 [`DISABLE_COMPACT`](/docs/zh-TW/env-vars) 時，兩種形式都命名 `/clear` 而不是 `/compact`。

1735

1736**該怎麼辦：**

1737

1738* 在多輪對話中，執行 `/compact` 以總結較早的輪次並釋放空間。若要重新開始，請執行 `/clear`

1739* 有關減少使用量的更多方式，請參閱 [Prompt is too long](#prompt-is-too-long)

1740

1741在 v2.1.216 之前，`/context` 顯示使用量超過 100%，沒有警告行解釋這意味著什麼或如何恢復。

1742

1743<h3 id="error-during-compaction-conversation-too-long">

1744 壓縮期間出錯：對話過長

1745</h3>

1746

1747`/compact` 本身失敗，因為沒有足夠的可用上下文來保存它產生的摘要。

1748

1749```text theme={null}

1750Error during compaction: Conversation too long. Press esc twice to go up a few messages and try again.

1751```

1752

1753當視窗在自動壓縮觸發時已滿，或當您在看到 [`Prompt is too long`](#prompt-is-too-long) 後執行 `/compact` 時，可能會發生這種情況。在互動式工作階段中，該錯誤是 `Context limit reached` 行。

1754

1755**該怎麼辦：**

1756

1757* 按 Esc 兩次以開啟訊息清單並回退幾輪。這會從上下文中刪除最近的訊息。然後再次執行 `/compact`。

1758* 如果回退沒有釋放足夠的空間，請執行 `/clear` 以在同一專案中開始新的工作階段。您之前的對話已保存在磁碟上，可以使用 `/resume` 重新開啟。

1759

1760此訊息和其他 `/compact` 失敗以錯誤樣式顯示。在 v2.1.216 之前，它們以與成功命令輸出相同的暗淡樣式呈現，因此您可能將失敗的壓縮讀取為成功。

1761

1762<h3 id="request-too-large">

1763 請求過大

1764</h3>

1765

1766原始請求正文在令牌化之前超過了 API 的 32MB 限制，通常是由於大型貼上內容、工具結果或附加檔案。此限制與 [上下文視窗](#prompt-is-too-long) 分開。

1767

1768```text theme={null}

1769Request too large (max 32MB). Accumulated images and attachments in the conversation pushed the request over the limit. Run /compact, or double press esc to go back and remove attachments.

1770```

1771

1772當請求直接進入 Claude API 且 API 本身拒絕它時，Claude Code 會測量對話並根據恢復是否可行來措辭訊息。通過代理、閘道或雲端提供者，您會收到一般訊息。測量的形式：

1773

1774* `Request too large (max 32MB; 20.1MB of about 33.4MB is images or documents).`：影像或文件將請求推過限制。Claude Code 會在去除它們後重試。

1775* `Request too large for the API's 32MB request limit`：訊息本身超過限制，因此訊息說 `compacting cannot make it fit`，Claude Code 不會重試。在 [非互動模式](/docs/zh-TW/headless) 中，訊息告訴您減少輸入或改為開始新工作階段。

1776

1777在 v2.1.212 之前，具有足夠累積影像的對話在每輪上都失敗，出現 `Request too large (max 32MB). Double press esc to go back and try with a smaller file.` 在 v2.1.229 之前，Claude Code 為每次拒絕顯示附加建議，即使壓縮無法幫助。

1778

1779**該怎麼辦：**

1780

1781* 如果訊息說 `compacting cannot make it fit`，按 Esc 兩次以回退到添加大型內容的輪次之前，或執行 `/clear` 以重新開始

1782* 否則，執行 `/compact`，它會刪除累積的影像和附加檔案

1783* 按路徑參考大型檔案而不是貼上其內容，以便 Claude 可以分塊讀取它們

1784* 對於影像，請參閱下面的 [Image was too large](#image-was-too-large)

1785

1786<h3 id="image-was-too-large">

1787 影像過大

1788</h3>

1789

1790貼上或附加的影像超過了 API 的大小或尺寸限制。

1791

1792```text theme={null}

1793Image was too large. Double press esc to go back and try again with a smaller image.

1794API Error: 400 ... image dimensions exceed max allowed size

1795```

1796

1797Claude Code 用文字佔位符替換無法處理的影像並重試，因此後續訊息成功。在 2.1.142 之前的版本上，貼上的影像可能保留在對話中，並在後續每條訊息上重複相同的錯誤。若要在這些版本上恢復，按 Esc 兩次並回退到添加影像的輪次之前。

1798

1799**該怎麼辦：**

1800

1801* 在貼上之前調整影像大小。API 接受單個影像最長邊最多 8000 像素的影像，或當許多影像在上下文中時為 2000 像素。

1802* 拍攝相關區域的更緊密螢幕截圖，而不是整個螢幕

1803

1804<h3 id="unable-to-resize-image">

1805 無法調整影像大小

1806</h3>

1807

1808Claude Code 無法在將附加影像發送到 API 之前對其進行縮小。

1809

1810```text theme={null}

1811Unable 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.

1812Unable to resize image — dimensions exceed the 2000x2000px limit and image processing failed. Please resize the image to reduce its pixel dimensions.

1813Unable to resize image (… raw, … base64). The image exceeds the … API limit and compression failed. Please resize the image manually or use a smaller image.

1814Unable to resize image — could not verify image dimensions are within the 2000x2000px API limit.

1815Unable to resize image — it is a CMYK JPEG, which Claude Code cannot decode, and at …px it is over the 2000x2000px limit, so it cannot be sent. Re-save it as an RGB PNG or JPEG and try again.

1816Unable to resize image — it is an animated WebP whose first frame Claude Code cannot decode, and at …px it is over the 2000x2000px limit, so it cannot be sent. Save its first frame as a PNG or JPEG and try again.

1817Unable to resize image — its pixels could not be decoded (the file may be damaged, or use an encoding Claude Code cannot read), and it is over the … API limit (… raw, … base64), so it cannot be sent. Re-save it as a PNG or JPEG and try again.

1818```

1819

1820Claude Code 通常會自動調整大型影像的大小。這些錯誤意味著無法解碼或調整影像大小以適應 API 限制。

1821

1822**該怎麼辦：**

1823

1824* 如果訊息要求您轉換影像，請將其轉換為 PNG、JPEG、GIF 或 WebP，然後再次附加。Claude Code 可以從檔案標頭驗證這些格式的尺寸，而無需解碼影像。

1825* 如果訊息報告尺寸或大小限制，請在附加之前將影像調整大小或重新壓縮到該限制以下。

1826* 如果訊息命名原因，例如 CMYK JPEG、動畫 WebP 或可能損壞的檔案，請以訊息建議的格式重新保存影像並再次附加。

1827

1828<h3 id="pdf-errors">

1829 PDF 錯誤

1830</h3>

1831

1832您附加的 PDF 無法處理。訊息在此處以非互動形式顯示；在互動式工作階段中，它們會提示您按 Esc 兩次並重試。

1833

1834```text theme={null}

1835PDF too large (max 100 pages, 20MB). Try reading the file a different way (e.g., extract text with pdftotext).

1836PDF is password protected. Try using a CLI tool to extract or convert the PDF.

1837The PDF file was not valid. Try converting it to text first (e.g., pdftotext).

1838```

1839

1840**該怎麼辦：**

1841

1842* 對於超大 PDF，要求 Claude 使用 Read 工具讀取頁面範圍而不是附加整個檔案，或使用 `pdftotext` 之類的工具提取文字並按路徑參考輸出檔案

1843* 對於受保護或無效的 PDF，移除密碼或從其來源應用程式重新匯出檔案，然後重試

1844

1845<h3 id="extra-inputs-are-not-permitted">

927 不允許額外輸入1846 不允許額外輸入

928</h3>1847</h3>

929 1848

930Claude Code 和 API 之間的代理或 LLM 閘道移除了 `anthropic-beta` 請求標頭，因此 API 拒絕了依賴它的欄位。1849Claude Code 和 API 之間的代理或 LLM 閘道去除了 `anthropic-beta` 請求標頭，因此 API 拒絕了依賴它的欄位。

1850

1851```text theme={null}

1852API Error: 400 ... Extra inputs are not permitted ... context_management

1853API Error: 400 ... Unexpected value(s) for the `anthropic-beta` header

1854```

1855

1856Claude Code 發送測試版專用欄位（例如 `context_management` 和 `effort`）以及啟用它們的 `anthropic-beta` 標頭。當閘道轉發正文但刪除標頭時，API 會看到它不識別的欄位。

1857

1858**該怎麼辦：**

1859

1860* 配置您的閘道以轉發 `anthropic-beta` 標頭。請參閱 [feature pass-through](/docs/zh-TW/llm-gateway-protocol#feature-pass-through) 以了解閘道必須轉發的內容。

1861* 作為備用方案，在啟動前設定 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/docs/zh-TW/env-vars)。[Disable pre-release capabilities](/docs/zh-TW/llm-gateway-protocol#disable-pre-release-capabilities) 涵蓋確切範圍。

1862

1863<h3 id="tool-input-schema-is-invalid">

1864 工具輸入架構無效

1865</h3>

1866

1867請求中的工具聲明了 `input_schema`，該架構未通過 API 的 JSON Schema 驗證，因此 API 拒絕了整個請求。`tools.` 後面的數字是失敗工具在請求的工具清單中的位置，而不是您可以查找的名稱。

1868

1869```text theme={null}

1870API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid

1871API Error: 400 ... tools.N.custom.input_schema.properties: Property keys should match pattern '^[a-zA-Z0-9_.-]{1,64}$'

1872```

1873

1874第一種形式意味著架構不是有效的 JSON Schema draft 2020-12。第二種意味著頂級屬性名稱與訊息引用的模式不匹配。

1875

1876Claude Code [在載入伺服器的工具時排除輸入架構會失敗此驗證的 MCP 工具](/docs/zh-TW/mcp#tools-with-invalid-input-schemas)，因此請求通常永遠不會包含一個。

1877

1878在 [標誌擷取關閉的部署](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching) 上，或在標誌從未到達的機器上，Claude Code 在伺服器的日誌中記錄哪個工具會被拒絕，但仍然發送它，因此此錯誤仍然可能發生。

1879

1880該錯誤也可能發生在工具的架構在 `$schema` 中聲明 JSON Schema 方言而不是 draft 2020-12 的工具上。Claude Code 不會根據 JSON Schema 元架構檢查這些架構，儘管頂級屬性名稱檢查仍然適用。

1881

1882在 v2.1.216 之前，沒有部署執行排除檢查。

1883

1884**該怎麼辦：**

1885

1886* 如果您的 Claude Code 版本早於 v2.1.216，請執行 `claude update`。

1887* 移除或 [禁用](/docs/zh-TW/mcp#disable-a-server-without-removing-it) 聲明無效架構的 MCP 伺服器。該錯誤僅按位置命名工具。在 v2.1.216 或更新版本上，檢查每個伺服器的日誌以查找命名工具的行，其輸入架構會被拒絕。如果沒有日誌命名一個，請逐個禁用伺服器。

1888* 如果您維護伺服器，請修復工具的 `input_schema`。架構必須是有效的 JSON Schema，頂級屬性名稱必須為 1 到 64 個字元長，並且只能使用 ASCII 字母和數字、`_`、`.` 和 `-`。請參閱 [Tools with invalid input schemas](/docs/zh-TW/mcp#tools-with-invalid-input-schemas)。

1889

1890<h3 id="theres-an-issue-with-the-selected-model">

1891 選定的模型有問題

1892</h3>

1893

1894配置的模型名稱未被識別，或您的帳戶缺乏對其的存取權限。從 v2.1.160 開始，尾部提示（此處以其互動形式顯示）因表面而異。

1895

1896```text theme={null}

1897There'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.

1898```

1899

1900**該怎麼辦：**

1901

1902* **互動式 CLI**：執行 `/model` 以從您帳戶可用的模型中選擇。

1903* **非互動模式 (`-p`)**：使用有效的別名或 ID 傳遞 `--model`，或設定 [`ANTHROPIC_MODEL`](/docs/zh-TW/env-vars)。錯誤文字在此表面上顯示 `Run --model`。

1904* **Agent SDK**：錯誤文字省略提示，因為模型是以程式設計方式設定的。在 TypeScript 中的 [`Options` 上設定 `model`](/docs/zh-TW/agent-sdk/typescript#options)，或在 Python 中設定 [`ClaudeAgentOptions(model=...)`](/docs/zh-TW/agent-sdk/python#claudeagentoptions)，並處理結構化 `model_not_found` 錯誤以顯示您自己的重試或模型選擇器。

1905* 使用別名（例如 `sonnet` 或 `opus`）而不是完整版本化 ID。別名解析為維護的預設值，因此它們不會過時。請參閱 [Model configuration](/docs/zh-TW/model-config)。

1906* 如果錯誤的模型在 CLI 中不斷出現，則在某處設定了過時的 ID。按 [優先順序](/docs/zh-TW/model-config#setting-your-model) 檢查您可以設定模型的位置，並移除過時的值。

1907* 新推出的模型可能在 Anthropic API 上可用，但在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上可用之前。如果您在其中一個提供者上固定了新模型 ID 並看到此錯誤，請檢查您提供者的模型目錄以了解您區域的可用性，並保持固定先前版本，直到新版本出現。

1908* Claude Code 將過期的 claude.ai 登入報告為 [Login expired](#login-expired)，而不是此錯誤。在 v2.1.206 之前，無法再刷新的過期登入對每個模型失敗，出現此錯誤；如果您在較舊版本上看到這種情況，請執行 `/login`。

1909* 對於 Google Cloud 的 Agent Platform 部署，請參閱 [Google Cloud 的 Agent Platform 故障排除](/docs/zh-TW/google-vertex-ai#troubleshooting)。

1910

1911<h3 id="model-is-not-a-recognized-model-id">

1912 模型不是公認的模型 ID

1913</h3>

1914

1915您傳遞給模型切換的模型字串不是模型別名、此 Claude Code 版本知道的模型 ID，也不是以 `claude-` 開頭的 ID。常見原因是 ID 中的拼寫錯誤、顯示名稱（例如 `Sonnet 5`，其中需要 ID `claude-sonnet-5`），或只有較新 Claude Code 版本識別的別名。Claude Code 立即拒絕切換。在 v2.1.200 之前，Claude Code 保存字串並在下一個請求上失敗，出現 [There's an issue with the selected model](#theres-an-issue-with-the-selected-model)。

1916

1917```text theme={null}

1918Model "claud-sonnet-5" is not a recognized model id. Did you mean 'claude-sonnet-5'?

1919```

1920

1921尾部提示命名最接近的匹配別名或模型 ID。當沒有足夠接近的內容時，它讀取 `Run /model to see available models.`。

1922

1923Claude Code 在請求切換的時刻在本地產生此錯誤，在任何 API 請求之前。它適用於通過 [Agent SDK](/docs/zh-TW/agent-sdk/typescript) `setModel()` 方法設定模型、由執行 Claude Code CLI 的應用程式（例如 [Desktop app](/docs/zh-TW/desktop)）設定，或當您從通過 [Remote Control](/docs/zh-TW/remote-control) 連接的裝置選擇模型時。在 v2.1.260 之前，檢查不涵蓋 Remote Control 選擇，因此 Claude Code 應用了選擇，下一個請求失敗，出現 [There's an issue with the selected model](#theres-an-issue-with-the-selected-model)。

1924

1925**該怎麼辦：**

1926

1927* 執行 `/model` 不帶引數以開啟選擇器並從您帳戶可用的模型中選擇，然後傳遞那裡顯示的別名或 ID

1928* 如果您使用了較新 Claude Code 版本支援的別名，請執行 `claude update`。以 `claude-` 開頭的完整 ID 即使模型比您的 Claude Code 版本更新，也會通過此本地檢查。伺服器仍然可能需要該模型的最低版本；請參閱 [Claude Code does not support this model](#claude-code-does-not-support-this-model)。

1929* v2.1.200 之前保存的模型不會被此檢查修復。如果過時的值不斷出現，請從 [Setting your model](/docs/zh-TW/model-config#setting-your-model) 下列出的位置移除它。

1930* 檢查僅在 Anthropic API 上執行。在任何其他提供者或閘道上，包括自訂 `ANTHROPIC_BASE_URL`，提供者定義模型名稱，因此 Claude Code 接受任何字串並將其傳遞。Claude Code 仍然可以在請求時寫入 [unrecognized-model diagnostic line](#unrecognized-model-id-on-a-request)，在每個提供者上。

1931

1932<h3 id="model-not-found">

1933 找不到模型

1934</h3>

1935

1936您使用 `/model <name>` 選擇了模型，Claude Code 無法確認存在具有該名稱的模型。當名稱不是 [model alias](/docs/zh-TW/model-config#model-aliases) 或 Claude Code 在本地接受的另一種拼寫時，`/model` 使用最小 API 請求驗證它，此錯誤通常是您的 API 端點的答案。無法成為模型 ID 的名稱（例如包含空格的名稱）會收到相同訊息。

1937

1938```text theme={null}

1939Model 'claude-opus-9' not found

1940```

1941

1942在具有提供者特定模型 ID 的提供者上，訊息可能會添加 `Try '...' instead` 建議，該建議命名您提供者的備用模型 ID。

1943

1944**該怎麼辦：**

1945

1946* 執行 `/model` 不帶引數並從您帳戶可用的模型中選擇，或使用 [model alias](/docs/zh-TW/model-config#model-aliases)（例如 `sonnet`），它解析為維護的預設值

1947* 如果您輸入了完整 ID，請根據您提供者的模型目錄檢查它。新推出的模型可能在 Anthropic API 上可用，但您的提供者或區域尚未提供。

1948* 在 v2.1.265 之前，`/model` 也以此錯誤拒絕了 `opusplan[1m]` 別名拼寫。在這些版本上，更新 Claude Code，或在 [settings](/docs/zh-TW/model-config#setting-your-model) 中或使用 `--model` 設定模型。

1949

1950<h3 id="claude-opus-is-not-available-with-the-claude-pro-plan">

1951 Claude Opus 不適用於 Claude Pro 方案

1952</h3>

1953

1954您的有效訂閱方案不包括您選擇的模型。

1955

1956```text theme={null}

1957Claude Opus is not available with the Claude Pro plan. If you have updated your subscription plan recently, run /logout and /login for the plan to take effect.

1958```

1959

1960**該怎麼辦：**

1961

1962* 執行 `/model` 並選擇您的方案包括的模型

1963* 如果您最近升級了方案但仍然看到這個，請執行 `/logout` 然後 `/login`。儲存的令牌反映您登入時的方案，因此在現有工作階段中在網路上升級不會生效，直到您重新驗證。

1964* 請參閱 [claude.com/pricing](https://claude.com/pricing) 以了解每個方案包括哪些模型

1965

1966<h3 id="claude-code-does-not-support-this-model">

1967 Claude Code 不支援此模型

1968</h3>

1969

1970API 因為您的 Claude Code 版本低於所需最低版本而拒絕了請求，出現 400。您選擇的模型需要較新版本（伺服器按模型檢查），或您的組織政策需要一個。400 帶有錯誤代碼 `claude_code_version_too_old`，訊息說明適用的最低版本。

1971

1972```text theme={null}

1973API Error: 400 Claude Code 2.1.219 does not support this model; version 2.1.255 or newer is required. Run 'claude update', or update the Claude desktop app, then try again.

1974```

1975

1976組織政策措辭讀取：

1977

1978```text theme={null}

1979API Error: 400 Claude Code 2.1.240 is older than the minimum version required by your organization's policy. Run 'claude update', or update the Claude desktop app, to continue.

1980```

1981

1982**該怎麼辦：**

1983

1984* 執行 `claude update`，或更新 Claude 桌面應用程式，然後開始新的工作階段

1985* 對於按模型措辭，您可以通過使用 `/model` 切換到另一個模型來在目前工作階段中繼續工作

1986* 對於組織政策措辭，在繼續之前更新

1987

1988<h3 id="model-is-restricted-by-your-organizations-settings">

1989 模型受您的組織設定限制

1990</h3>

1991

1992您的組織管理員已在 claude.ai 管理控制台中禁用此模型，或它被受管設定中的 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection) 允許清單排除。當受限制的模型使用 `--model`、`ANTHROPIC_MODEL` 或 `model` 設定設定時，Claude Code 替換允許的模型並繼續。為受限制的模型輸入 `/model <name>` 被拒絕，出現 `Run /model to choose a different model.`，工作階段保持其目前模型。

1993

1994```text theme={null}

1995Model "claude-opus-4-8" is restricted by your organization's settings. Using claude-sonnet-4-6 instead.

1996```

1997

1998以代理、技能或命令名稱為前綴的通知意味著限制適用於該 [子代理的請求模型](/docs/zh-TW/sub-agents#choose-a-model)：子代理在替換模型上執行，您的工作階段模型保持不變。在 v2.1.223 之前，Claude Code 僅對使用 Agent 工具啟動的子代理顯示通知。

1999

2000Claude Code 將模型系列別名（`opus`、`sonnet`、`haiku` 或 `fable` 之一）視為對該系列的請求，而不是對其最新版本的請求。在 Anthropic API 和 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 上，受限制的系列別名解析為您的組織和 `availableModels` 允許清單允許的系列的最新版本，替換通知命名該版本。Claude Code 僅在系列的每個版本都受限制時拒絕 `/model <alias>`。在 v2.1.205 之前，系列別名基於其最新版本單獨替換或拒絕，即使同一系列的較舊版本被允許。

2001

2002**該怎麼辦：**

2003

2004* 執行 `/model` 以從您的組織允許的模型中選擇。受限制的模型在選擇器中隱藏。

2005* 如果受限制的模型在 `--model`、`ANTHROPIC_MODEL`、設定檔案的 `model` 欄位或 [subagent](/docs/zh-TW/sub-agents#choose-a-model)、技能或命令的 `model` frontmatter 中設定，請移除或更新該值，以便通知不會再次出現

2006* 如果您需要存取受限制的模型，請要求您的組織管理員啟用它。請參閱 [Organization model restrictions](/docs/zh-TW/model-config#organization-model-restrictions)。

2007

2008<h3 id="model-switch-was-blocked-by-a-premodelswitch-hook">

2009 模型切換被 PreModelSwitch hook 阻止

2010</h3>

2011

2012[PreModelSwitch hook](/docs/zh-TW/hooks#premodelswitch) 沒有批准您或用戶端請求的模型切換，因此工作階段保持其目前模型。當切換來自 [Agent SDK](/docs/zh-TW/agent-sdk/overview) 主機或 [Remote Control](/docs/zh-TW/remote-control) 而不是您輸入的命令時，訊息讀取 `Model switch blocked by a PreModelSwitch hook` 而不命名目標模型。

2013

2014```text theme={null}

2015Model switch to Opus 4.6 was blocked by a PreModelSwitch hook: Opus 4.6 is retired for this project. Use a newer model.

2016```

2017

2018冒號後的原因說明拒絕切換的原因：

2019

2020* **hook 寫入的原因**：PreModelSwitch hook 在 [拒絕切換或要求確認](/docs/zh-TW/hooks#premodelswitch-decision-control) 時提供了該原因。解決它要求的內容，或選擇您的 hook 允許的模型。

2021* **`PreModelSwitch hook <name> did not respond before its timeout`**：在其 [timeout](/docs/zh-TW/hooks#timeouts) 之前沒有回答的 hook 會阻止切換。修復掛起的命令或提高該 hook 的 `timeout`，然後再次切換。

2022* **`confirmation required, and this session cannot ask`**：hook 回答 `ask` 而沒有原因，控制請求無法顯示確認提示。[`-p` 執行](/docs/zh-TW/headless) 中的控制請求以原因後的 `(run /model interactively to confirm)` 報告相同狀況。從互動式工作階段進行切換，或更改 hook 對此模型的決定。

2023* **`so organization-managed PreModelSwitch hooks could not be checked`**：Claude Code 無法判斷您的組織的 [managed plugins](/docs/zh-TW/settings-reference#enabledplugins) 提供哪些 PreModelSwitch hook，例如因為受管外掛程式無法載入。其中一個 hook 可能會阻止切換，因此 Claude Code 拒絕而不是應用未檢查的切換。原因的開始命名失敗的內容。Claude Code 在每次切換嘗試時重新檢查，因此已清除的失敗停止阻止；如果它繼續失敗，執行 `claude --debug` 並再次切換以捕獲詳細資訊，然後修復外掛程式或要求您的管理員修復它。

2024* **`a PreModelSwitch hook failed before answering`** 或 **`PreModelSwitch hooks were cancelled (the control stream closed) before answering`**：hook 執行在沒有判決的情況下結束，Claude Code 不將其視為批准。執行 `claude --debug` 以查看失敗的內容，然後再次切換。

2025

2026在 v2.1.260 之前，受管外掛程式拒絕讀取 `plugin hooks could not be loaded, so PreModelSwitch hooks could not be checked; see the debug log`。Claude Code 重試外掛程式載入一次，然後在工作階段中拒絕後續切換，即使您的組織沒有受管外掛程式。在這些版本上重新啟動工作階段以再次執行外掛程式載入。

2027

2028<h3 id="couldnt-save-it-as-your-default">

2029 無法將其保存為您的預設值

2030</h3>

2031

2032您選擇了一個模型以保存為您的預設值，例如使用 `/model <name>` 或 `/model` 選擇器中的 Enter，Claude Code 無法將選擇寫入您的使用者設定檔案 `~/.claude/settings.json`。切換本身已應用，因此目前工作階段在您選擇的模型上執行，但您的預設值保持不變，下一個工作階段在舊值上開始。

2033

2034```text theme={null}

2035Set model to Fable 5.1 for this session only · couldn't save it as your default: ~/.claude/settings.json can't be written (EROFS)

2036```

2037

2038檔案路徑後的原因說明失敗的內容：

2039

2040* **`can't be written (<code>)`**：寫入失敗，出現括號中的作業系統錯誤代碼，例如當檔案或它連結到的檔案位於拒絕寫入的檔案系統上時的 `EROFS`。使檔案可寫入並再次切換。如果另一個工具產生檔案，請在該工具中設定 `model` 鍵；請參閱 [A change you made in Claude Code is lost in new sessions](/docs/zh-TW/settings#a-change-you-made-in-claude-code-is-lost-in-new-sessions)。

2041* **`isn't valid JSON`**：磁碟上的檔案不解析，Claude Code 保持不動而不是覆蓋它無法讀回的內容。修復語法錯誤，然後再次切換；請參閱 [Fix a broken settings file](/docs/zh-TW/settings#fix-a-broken-settings-file)。

2042

2043以 `couldn't confirm it was saved as your default (~/.claude/settings.json is still being written)` 結尾的通知意味著寫入在三秒後未完成。它在背景中繼續，因此預設值可能仍然被保存；檢查您的下一個工作階段開始的模型，或再次執行 `/model <name>`。

2044

2045在 v2.1.265 之前，通知說模型被 `saved as your default for new sessions`，即使寫入失敗。

2046

2047<h3 id="thinking-type-enabled-is-not-supported-for-this-model">

2048 此模型不支援 thinking.type.enabled

2049</h3>

2050

2051您的 Claude Code 版本早於所選模型的最低版本。CLI 發送了模型不再接受的思考配置。

2052

2053```text theme={null}

2054API Error: 400 ... "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

2055```

2056

2057**該怎麼辦：**

2058

2059* 執行 `claude update` 並重新啟動 Claude Code。Opus 4.7 需要 v2.1.111 或更新版本。Opus 4.8 需要 v2.1.154 或更新版本。Sonnet 5 需要 v2.1.197 或更新版本。Opus 5 需要 v2.1.219 或更新版本

2060* 如果您無法升級，執行 `/model` 並改為選擇 Opus 4.6 或 Sonnet 4.6

2061* 如果您在 [Agent SDK](/docs/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 或更新版本。Opus 5 需要 TypeScript SDK v0.3.219 或更新版本

2062

2063<h3 id="effort-isnt-available-with-thinking-turned-off">

2064 關閉思考時努力不可用

2065</h3>

2066

2067您關閉了 [extended thinking](/docs/zh-TW/model-config#extended-thinking) 並以 [effort level](/docs/zh-TW/model-config#adjust-effort-level) 高於 `high` 執行。模型不接受該組合，因此 API 拒絕了請求。

2068

2069```text theme={null}

2070API Error: Effort 'xhigh' isn't available with thinking turned off on this model · run /effort high to continue, or turn thinking back on (unset MAX_THINKING_TOKENS=0)

2071```

2072

2073**該怎麼辦：**

2074

2075* [降低努力級別](/docs/zh-TW/model-config#set-the-effort-level) 至 `high` 或以下。

2076* 打開思考，例如通過取消設定 [`MAX_THINKING_TOKENS`](/docs/zh-TW/env-vars) 或從您的設定中移除 [`"alwaysThinkingEnabled": false`](/docs/zh-TW/settings-reference#alwaysthinkingenabled)。

2077

2078在 v2.1.242 之前，Claude Code 顯示 API 自己的訊息：`API Error: 400 output_config.effort 'xhigh' is not supported when thinking is disabled on this model. Use effort 'high' or below, or enable thinking.` 在 v2.1.251 之前，Claude Code 在您設定的努力級別發送請求，因此 Opus 5 拒絕了關閉思考時高於 `high` 的每個請求。Claude Code 現在改為向它知道拒絕該組合的模型（例如 Opus 5）發送努力 `high`，因此在 v2.1.251 或更新版本上，此錯誤僅從 Claude Code 不知道拒絕它的模型到達您。

2079

2080<h3 id="thinking-budget-exceeds-output-limit">

2081 思考預算超過輸出限制

2082</h3>

2083

2084配置的擴展思考預算超過最大回應長度，因此實際答案沒有剩餘空間。

2085

2086```text theme={null}

2087API Error: 400 ... max_tokens must be greater than thinking.budget_tokens

2088```

2089

2090Claude Code 在 Anthropic API 上自動調整這些值。當 [`MAX_THINKING_TOKENS`](/docs/zh-TW/env-vars) 設定高於提供者的輸出限制，或當計畫模式提高思考預算時，您通常在 Amazon Bedrock 或 Google Cloud 的 Agent Platform 上看到此錯誤。

2091

2092**該怎麼辦：**

2093

2094* 降低 `MAX_THINKING_TOKENS`，或提高 [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/docs/zh-TW/env-vars) 高於思考預算

2095* 請參閱 [Extended thinking](/docs/zh-TW/model-config#extended-thinking) 以了解預算如何與輸出長度互動

2096

2097<h3 id="tool-use-or-thinking-block-mismatch">

2098 工具使用或思考區塊不匹配

2099</h3>

2100

2101對話歷史記錄到達 API 時處於不一致狀態，通常在工具呼叫被中斷或輪次在串流中途被編輯後。

2102

2103```text theme={null}

2104API Error: 400 due to tool use concurrency issues. Run /rewind to recover the conversation.

2105API Error: 400 ... unexpected `tool_use_id` found in `tool_result` blocks

2106API Error: 400 ... thinking blocks ... cannot be modified

2107```

2108

2109所有三個變體都意味著相同的事情：歷史記錄中 `tool_use`、`tool_result` 和 `thinking` 區塊的序列不再與 API 期望的相符。

2110

2111**該怎麼辦：**

2112

2113* 如果您使用 Opus 4.7 或 Opus 4.8，請先執行 `claude update`。v2.1.156 之前的版本可以在正常工具使用期間觸發此錯誤，`/rewind` 不會清除它。

2114* 執行 `/rewind`，或按 Esc 兩次，以回退到損壞輪次之前的檢查點並從那裡繼續。請參閱 [Checkpointing](/docs/zh-TW/checkpointing) 以了解檢查點如何建立和恢復。

2115

2116<h3 id="unsupported-tool-content-removed">

2117 移除了不支援的工具內容

2118</h3>

2119

2120當 Claude Code 直接連接到 Anthropic API 並載入或預覽已保存的工作階段時，它會移除 Anthropic API 不接受的工具內容，並在兩個思考區塊之間移除的內容所在的位置留下此行：

2121

2122```text theme={null}

2123[Unsupported tool content removed]

2124```

2125

2126當 API 格式以外的內容回答時，此類內容到達工作階段檔案，通常是通過 [`ANTHROPIC_BASE_URL`](/docs/zh-TW/env-vars) 設定的第三方代理，它轉譯另一個提供者的工具呼叫。Claude Code 僅在工作階段直接連接到 Anthropic API 時移除它，並在工作階段通過代理或在另一個提供者上執行時按原樣載入已保存的歷史記錄。在 v2.1.246 之前，Claude Code 將工具使用及其結果發送回 API，已恢復工作階段的每輪都失敗，出現 400 錯誤，例如 `messages.1.content.0.server_tool_use.name: Input should be 'web_search', 'web_fetch', ...`。

2127

2128**該怎麼辦：**

2129

2130* 當您看到佔位符行時，無需執行任何操作。工作階段在沒有移除內容的情況下繼續。

2131* 如果已恢復工作階段的每輪都失敗，出現 400 錯誤，請執行 `claude update` 並再次恢復工作階段。v2.1.246 之前的版本不會移除內容。

2132

2133<h3 id="usage-policy-refusal">

2134 使用政策拒絕

2135</h3>

2136

2137API 拒絕回應，因為對話中的內容觸發了 [Usage Policy](https://www.anthropic.com/legal/aup) 檢查。訊息包括您可以引用給支援的請求 ID，如果您認為拒絕不正確。

2138

2139```text theme={null}

2140API Error: Opus 4.6 can't help with this. Start a new session to continue.

2141

2142Send feedback with /feedback or learn more: https://www.anthropic.com/legal/aup

2143```

2144

2145訊息命名拒絕的模型，或當沒有記錄模型時命名 `Claude`。

2146

2147檢查評估完整對話，而不僅是您的最新提示，因此在同一工作階段中發送新訊息通常會重新觸發相同的拒絕。使用 `--continue` 或 `--resume` 退出並重新開啟工作階段後也是如此，因為磁碟上的文字記錄仍然包含觸發內容。在 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-TW/google-vertex-ai) 和 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry) 上，此訊息也涵蓋模型的安全措施標記為網路安全主題的請求。請參閱 [Safety measures flagged a cybersecurity topic](#safety-measures-flagged-a-cybersecurity-topic)。

2148

2149在 v2.1.219 之前，訊息讀取 `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.`

2150

2151**該怎麼辦：**

2152

2153* 按 Esc 兩次或執行 `/rewind` 以回退到觸發拒絕的輪次之前的檢查點，然後重新措辭或採取不同的方法。請參閱 [Checkpointing](/docs/zh-TW/checkpointing)。

2154* 如果您無法識別哪個輪次導致了它，執行 `/clear` 以在同一專案中開始新的對話。您之前的對話保存在磁碟上，並在 `/resume` 中保持可用。

2155* 在 [非互動模式](/docs/zh-TW/headless) (`-p`) 中，其中倒帶不可用，使用重新措辭的提示在沒有 `--continue` 的新工作階段中重試。政策檢查因模型而異，因此使用 `--model` 切換到不同的模型也可能在某些情況下解決拒絕。

2156

2157<h3 id="safety-measures-flagged-a-cybersecurity-topic">

2158 安全措施標記了網路安全主題

2159</h3>

2160

2161模型的安全措施將對話中的內容標記為網路安全主題。訊息命名標記請求的模型：

2162

2163```text theme={null}

2164API Error: Opus 4.8's safeguards flagged this message. Our intentionally broad safeguards allow us to deliver more capabilities faster, but can sometimes flag legitimate cybersecurity work. Apply to the Cyber Verification Program to reduce these interruptions. Send feedback with /feedback or learn more: https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude

2165```

2166

2167訊息連結到 [Cyber Verification Program](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)，它為合法網路安全工作授予存取權限。

2168

2169在 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-TW/google-vertex-ai) 和 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry) 上，網路安全標記會改為產生 [Usage Policy refusal](#usage-policy-refusal) 訊息。

2170

2171防護本身是伺服器端的，早於 v2.1.203；自那時以來的用戶端版本僅更改了訊息的措辭。

2172從 v2.1.203 到 v2.1.218，訊息讀取 `<model> 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:` 後跟相同的說明中心連結，互動式工作階段附加 `If you were not engaging in a cybersecurity topic, please send feedback via /feedback.`

2173在 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:` 後跟豁免表單連結。

2174

2175**該怎麼辦：**

2176

2177* 如果您的工作需要此內容，請通過 [Cyber Verification Program](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude) 申請存取權限

2178* 如果您的請求不是關於網路安全主題，執行 `/feedback` 以報告誤報

2179* 若要在同一工作階段中繼續工作，按 Esc 兩次或執行 `/rewind` 以回退到觸發標記的輪次之前的檢查點，然後採取不同的方法。請參閱 [Checkpointing](/docs/zh-TW/checkpointing)。

2180

2181<h2 id="installation-errors">

2182 安裝錯誤

2183</h2>

2184

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

2186

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

2188 安裝在完成前被中止

2189</h3>

2190

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

2192

2193```text theme={null}

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

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

2196```

2197

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

2199

2200**該怎麼做：**

2201

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

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

2204

2205<h3 id="the-connection-dropped-while-downloading-the-update">

2206 下載更新時連線中斷

2207</h3>

2208

2209在 `claude install`、`claude update` 或 [自動更新程式](/docs/zh-TW/setup#auto-updates) 擷取 Claude Code 二進位檔案時，與下載伺服器的連線已關閉，且重試未能復原。Claude Code 會在連線中斷、傳輸停滯或下載的檔案未通過總和檢查時重試下載，總共最多三次嘗試。已完成的 HTTP 錯誤（例如 404）不會重試，因為伺服器已經回應。在 v2.1.202 之前，單一連線中斷會立即導致下載失敗，並顯示裸錯誤 `aborted`，而不是重試。

2210

2211```text theme={null}

2212The connection dropped while downloading the update (attempt 3/3: aborted). Check your network — proxies sometimes cut off large downloads.

2213```

2214

2215括號中的文字命名失敗的嘗試和基礎網路錯誤。`claude update` 在 stderr 上以 `Error: Failed to install native update` 開頭該訊息。

2216

2217保持連線但未在 10 分鐘內完成的下載會失敗，並顯示 `Download timed out: exceeded the total deadline`。Claude Code 不會重試逾時的下載，因為連線太慢而無法在期限內完成，在立即重試時也不會完成。以下步驟適用於兩個訊息。

2218

2219通常的原因是代理或閘道在傳輸完成前關閉長傳輸。Claude Code 二進位檔案是大型下載，因此永遠不會影響正常 API 流量的代理連線限制仍然可能中斷它。

2220

2221**該怎麼做：**

2222

2223* 再次執行 `claude update`。在網路狀況良好的情況下，下載通常在下次執行時成功。對於逾時訊息，請從更快或限制較少的網路重新執行。

2224* 如果您的網路需要代理，請在執行安裝程式或 `claude update` 之前設定 `HTTPS_PROXY`。請參閱 [檢查網路連線](/docs/zh-TW/troubleshoot-install#check-network-connectivity)。

2225* 如果公司代理持續關閉傳輸，請要求您的網路團隊允許從 `downloads.claude.ai` 進行完整下載。請參閱 [網路存取需求](/docs/zh-TW/network-config#network-access-requirements)。

2226* 從您的 shell 執行 `claude doctor` 以進行安裝診斷

2227

2228<h2 id="command-line-errors">

2229 命令列錯誤

2230</h2>

2231

2232這些錯誤來自 `claude` 命令列及其子命令、您在提示符處提交的命令名稱，以及 `/security-review` 等命令，這些命令在執行其提示之前透過執行 shell 命令來收集上下文。`/tui` 也會產生錯誤，它會重新啟動 CLI。

2233

2234<h3 id="conflict-between-bg-and-print">

2235 \--bg 和 --print 之間的衝突

2236</h3>

2237

2238此訊息需要 Claude Code v2.1.198 或更新版本。您在同一個 `claude` 呼叫中結合了 `--bg` 與 `-p` 或 `--print`。`--bg` 啟動一個[背景工作階段](/docs/zh-TW/agent-view#from-your-shell)，您稍後可以使用 `claude agents` 附加到該工作階段，而 `--print` 以[非互動模式](/docs/zh-TW/headless)執行，永遠不會啟動 `claude agents` 附加到的互動工作階段。在 v2.1.198 之前，此組合會無聲地建立一個永遠無法附加的背景工作。

2239

2240```text theme={null}

2241--bg 和 --print 衝突：--print 永遠不會啟動 `claude agents` 附加到的互動工作階段，所以該工作將無法附加。提示是位置引數 — 移除 --print：`claude --bg '<task>'`。

2242```

2243

2244**該怎麼做：**

2245

2246* 移除 `-p` 或 `--print`。`--bg` 將提示作為其位置引數，所以 `claude --bg "<task>"` 是完整命令。請參閱[從您的 shell 分派新代理](/docs/zh-TW/agent-view#from-your-shell)。

2247* 若要以非互動模式執行提示並列印結果而不是建立背景工作階段，請移除 `--bg` 並執行 `claude -p "<task>"`

2248

2249<h3 id="invalid-agents-configuration">

2250 無效的 --agents 設定

2251</h3>

2252

2253您傳遞給 `--agents` 的值無效，所以 `claude` 以代碼 1 結束而不是啟動工作階段。當您傳遞 `--safe-mode`、`--resume` 或 `--continue`，或設定 [`CLAUDE_CODE_SAFE_MODE`](/docs/zh-TW/env-vars#variables) 時，Claude Code 不會檢查該值並啟動工作階段。在 v2.1.242 之前，Claude Code 無論如何都會啟動工作階段，並遺漏它無法載入的定義。

2254

2255```text theme={null}

2256Error: Invalid --agents configuration:

2257<what failed>

2258```

2259

2260第一行之後的內容取決於該值如何失敗。Claude Code 按順序執行這些檢查，並在第一個失敗的檢查處停止。如果您的值有兩種問題，您只會在修復第一個問題後看到第二個：

2261

22621. 當該值無法解析為 JSON 時，Claude Code 會列印一行 `invalid JSON:` 行，其中包含 JSON 解析器自己的訊息

22632. 當它解析但代理定義與 [CLI 定義的子代理](/docs/zh-TW/sub-agents#choose-the-subagent-scope)的架構不符時，Claude Code 會為每個問題列印一行

22643. 當代理名稱以 `-` 開頭時，Claude Code 會列印 `<name>: agent names must not start with '-'`

2265

2266當有超過 20 行問題時，Claude Code 會列印前 20 行，並用 `…and N more` 取代其餘部分。

2267

2268**該怎麼做：**

2269

2270* 修復訊息列出的每個問題，然後再次執行命令。請參閱 [CLI 定義的子代理採用的欄位](/docs/zh-TW/sub-agents#choose-the-subagent-scope)。

2271

2272<h3 id="cloud-sessions-cannot-be-created-from-a-restricted-session">

2273 無法從 --restricted 工作階段建立雲端工作階段

2274</h3>

2275

2276當您使用 [`--restricted`](/docs/zh-TW/cli-reference#cli-flags) 啟動工作階段時，Claude Code 拒絕從中建立[雲端工作階段](/docs/zh-TW/claude-code-on-the-web#from-terminal-to-web)，因為新工作階段將在受限程序之外執行，不會強制執行受限模式。Claude Code 在用戶端拒絕，在聯絡伺服器之前，所以不會建立任何雲端工作階段：

2277

2278```text theme={null}

2279Cloud sessions cannot be created from a --restricted session: they would not enforce it.

2280```

2281

2282**該怎麼做：**

2283

2284* 在受限工作階段中本地執行任務

2285* 如果您控制工作階段的啟動方式，請啟動新的 `claude` 工作階段而不使用 `--restricted`，並從那裡建立雲端工作階段

2286

2287在 v2.1.248 之前，Claude Code 沒有 `--restricted` 旗標；較早的版本會以未知選項錯誤拒絕該旗標。

2288

2289<h3 id="the-json-schema-value-is-not-a-valid-json-schema">

2290 \--json-schema 值不是有效的 JSON Schema

2291</h3>

2292

2293您傳遞給 [`--json-schema`](/docs/zh-TW/cli-reference#cli-flags) 的架構在[非互動模式](/docs/zh-TW/headless#get-structured-output)中未能通過 JSON Schema 編譯，所以 `claude` 以代碼 1 結束而不是執行提示。在 v2.1.205 之前，無效的架構會產生無結構的輸出而沒有錯誤，任何使用 `format` 關鍵字的架構都被視為無效。

2294

2295```text theme={null}

2296Error: --json-schema is not a valid JSON Schema: data/type must be equal to one of the allowed values

2297```

2298

2299第二個冒號之後的文字是驗證器的診斷，並命名失敗的關鍵字或位置。使用 `format` 關鍵字的架構，例如 `"format": "email"`，是有效的：Claude Code 接受 `format` 作為註釋，不強制執行它。

2300

2301Claude Code 在架構編譯之前執行兩項檢查：它拒絕無法解析為 JSON 的值，並顯示 `Error: --json-schema is not valid JSON`，以及有效但不是物件的 JSON，並顯示 `Error: --json-schema must be a JSON object`。

2302

2303**該怎麼做：**

2304

2305* 修復診斷命名的架構部分，然後重新執行命令

2306* 如果診斷是 `schema too large`，請減少架構的巢狀和 `$ref` 重複使用

2307* 請參閱[取得結構化輸出](/docs/zh-TW/headless#get-structured-output)以取得有效的架構和命令

2308

2309<h3 id="settings-file-exceeds-the-2mib-limit">

2310 設定檔超過 2MiB 限制

2311</h3>

2312

2313您傳遞給 [`--settings`](/docs/zh-TW/cli-reference#cli-flags) 的檔案大於 2 MiB，所以 `claude` 在啟動時以代碼 1 結束，而不是載入它。設定檔是一個小型 JSON 文件，所以這麼大的檔案通常意味著路徑指向錯誤的檔案。在 v2.1.214 之前，Claude Code 讀取檔案時沒有大小檢查，多 GB 的檔案或 `/dev/zero` 等裝置檔案會無限制地增加記憶體。

2314

2315```text theme={null}

2316Error: Settings file exceeds the 2MiB limit: /path/to/settings.json

2317```

2318

2319Claude Code 以相同方式拒絕不是常規檔案的 `--settings` 路徑：裝置、FIFO 或 socket 會報告 `Error: Cannot use settings file (Not a regular file (device, FIFO, or socket))`，後面跟著路徑，目錄會報告 `EISDIR` 原因。

2320

2321**該怎麼做：**

2322

2323* 將 `--settings` 指向 2 MiB 以下的常規 JSON 設定檔。請參閱[設定](/docs/zh-TW/settings)以了解格式。

2324

2325<h3 id="the-current-directory-no-longer-exists">

2326 目前目錄不再存在

2327</h3>

2328

2329您從一個在您的 shell 進入後被刪除或移動的目錄啟動 `claude`，例如另一個 shell 移除的 worktree 或臨時目錄。Claude Code 無法讀取其工作目錄，所以它在啟動工作階段之前以代碼 1 結束，在互動和[非互動](/docs/zh-TW/headless)模式中都是如此。在 v2.1.239 之前，Claude Code 會因縮小的套件來源和原始 `ENOENT ... uv_cwd` 堆疊而在 stderr 上崩潰，而不是顯示此訊息。

2330

2331```text theme={null}

2332The current directory no longer exists (it was deleted or moved). Start Claude Code from an existing directory.

2333error: The current working directory was deleted, so that command didn't work. Please cd into a different directory and try again.

2334```

2335

2336原因和修復對兩種形式都是相同的。

2337

2338當 Claude Code 因其他原因（例如權限變更）無法讀取工作目錄時，訊息會命名錯誤代碼：`Can't read the current directory (EACCES). Start Claude Code from a different directory.`

2339

2340在 macOS 上，`~/Desktop`、`~/Documents`、`~/Downloads` 或 iCloud Drive 中目錄的 `EPERM` 通常意味著 macOS 阻止您的終端應用程式存取該資料夾。讀取該資料夾的其他命令也會以相同方式失敗：即使使用 `sudo`，那裡的 `ls` 也會報告 `Operation not permitted`。

2341

2342**該怎麼做：**

2343

2344* 變更到存在的目錄，例如您的主目錄或專案目錄，然後再次執行 `claude`

2345* 如果目錄在相同路徑上被重新建立，您的 shell 仍然持有已刪除的目錄。執行 `cd "$PWD"` 或離開並重新進入目錄，然後再次執行 `claude`

2346* 對於 macOS 上的 `EPERM`，使用 Cmd+Q 結束您的終端應用程式，重新開啟它，返回該資料夾，然後執行 `claude`。如果該資料夾中的 `ls` 仍然失敗，請開啟**系統設定 > 隱私與安全 > 檔案和資料夾**，為您的終端應用程式開啟該資料夾，然後重新開啟終端

2347

2348<h3 id="directory-couldnt-be-resolved-to-a-real-location">

2349 目錄無法解析為實際位置

2350</h3>

2351

2352您為工作目錄的子目錄執行了 `/add-dir`，Claude Code 無法將目錄解析為其實際位置。

2353

2354您已經可以存取工作目錄的子目錄，所以 `/add-dir` 只會載入其技能、命令和代理。在載入它們之前，Claude Code 會檢查目錄的實際位置（解析任何符號連結）是否在工作目錄內。當 Claude Code 無法解析該位置時，它不會載入任何內容並顯示此訊息：

2355

2356```text theme={null}

2357packages/app couldn't be resolved to a real location, so its skills, commands, and agents weren't loaded. Check that it is a directory inside the working directory and try again.

2358```

2359

2360**該怎麼做：**

2361

2362* 檢查路徑是否命名工作目錄內的真實目錄，然後再次執行 `/add-dir`

2363* 訊息不會改變您的檔案存取；它只報告目錄的 `.claude/` 內容未被載入

2364

2365在 v2.1.261 之前，當工作目錄在 `/net/<host>` 自動掛載上時，此訊息也會為每個 `/add-dir <subdirectory>` 出現，Claude Code 根據設計拒絕解析路徑；目錄很好，重試無法幫助。

2366

2367<h3 id="workspace-not-trusted-when-starting-remote-control">

2368 啟動遠端控制時工作區未受信任

2369</h3>

2370

2371您在未信任的目錄中使用 `claude remote-control` 或其 `claude rc` 別名啟動[遠端控制](/docs/zh-TW/remote-control)伺服器模式。該命令本身不會顯示工作區信任對話框，所以它以代碼 1 結束並命名修復：

2372

2373```text theme={null}

2374Error: Workspace not trusted. Please run `claude` in /Users/you/project first to review and accept the workspace trust dialog.

2375```

2376

2377在您的主目錄中，訊息是不同的，因為工作區信任對話框永遠不會為主目錄儲存信任，所以在那裡接受它無法滿足此檢查。在 v2.1.214 之前，主目錄顯示上述訊息，其建議在那裡無法成功。

2378

2379```text theme={null}

2380Error: Workspace not trusted. /Users/you is your home directory, and for security home-directory trust is never saved, so running `claude` here first won't help. Run `claude rc` from a project directory instead (run `claude` there once to accept the trust dialog).

2381```

2382

2383**該怎麼做：**

2384

2385* 在目錄中執行 `claude`，接受[工作區信任對話框](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)，然後再次執行 `claude remote-control`

2386* 在您的主目錄中，變更到專案目錄並在那裡啟動遠端控制

2387

2388<h3 id="not-carried-over-to-the-sessions-remote-control-starts">

2389 未帶到遠端控制啟動的工作階段

2390</h3>

2391

2392您使用全域 `claude` 旗標在 `remote-control` 動詞之前啟動[遠端控制](/docs/zh-TW/remote-control)，該旗標會限制或設定遠端控制啟動的工作階段，例如 `--settings`、`--setting-sources`、`--permission-mode`、`--disallowed-tools` 或 `--mcp-config`。放在動詞之前的旗標永遠不會到達這些工作階段。Claude Code 拒絕啟動，並命名該旗標：

2393

2394```text theme={null}

2395Error: `--settings` before `remote-control` is not carried over to the sessions Remote Control starts, so Remote Control refuses to start rather than drop it — remove it, and give Remote Control's own options after the verb (see `claude remote-control --help`).

2396```

2397

2398Claude Code 不拒絕無害的全域旗標，例如 `--verbose`、`--model` 或包裝器注入的 `--session-id` 或 `--plugin-dir`：它會忽略它們，遠端控制會啟動。

2399

2400Claude Code 也拒絕為它尚未識別為無害的全域旗標啟動，所以在較新版本中新增的旗標可能會在此訊息中出現，直到稍後的版本將其標記為無害。

2401

2402**該怎麼做：**

2403

2404* 從動詞之前移除旗標，並在其後傳遞[遠端控制自己的選項](/docs/zh-TW/remote-control#start-a-remote-control-session)；`claude remote-control --help` 列出它們

2405* 當被拒絕的旗標是 `--permission-mode` 時，執行 `claude remote-control --permission-mode <mode>` 來設定遠端控制啟動的工作階段的權限模式

2406

2407在 v2.1.248 之前，當全域旗標首先出現時，`claude remote-control` 不接受自己的旗標，命令失敗並出現 `unknown option` 錯誤。

2408

2409<h3 id="claude-import-is-not-yet-available-in-this-build">

2410 claude import 在此組建中尚不可用

2411</h3>

2412

2413您執行了 [`claude import`](/docs/zh-TW/cli-reference#cli-commands)，Claude Code 發現匯入流程已關閉，所以命令以代碼 1 結束而不是啟動匯入。在 v2.1.222 之前，關閉匯入流程的組建會將 `import` 視為提示並啟動互動工作階段，而不是列印此訊息。

2414

2415```text theme={null}

2416`claude import` is not yet available in this build. Run `claude` and use /mcp or edit ~/.claude/settings.json directly.

2417```

2418

2419Claude Code 透過從 Anthropic 取得並在磁碟上快取的功能旗標開啟 `claude import`。此訊息意味著快取的值已關閉。原因通常是以下之一：

2420

2421* 您在安裝後尚未啟動工作階段，所以 Claude Code 尚未取得旗標。第一個 `claude import` 即使功能對您可用，也可能列印此訊息。

2422* 您透過 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 AWS 上的 Claude Platform，或透過 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway#availability-and-limitations)使用 Claude Code。Claude Code 在這些工作階段中不取得功能旗標，所以 `claude import` 保持不可用。

2423* 您設定了 `DISABLE_TELEMETRY`、`DO_NOT_TRACK`、`DISABLE_GROWTHBOOK` 或 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/zh-TW/env-vars)，這會關閉功能旗標取得，所以 `claude import` 保持不可用。

2424

2425**該怎麼做：**

2426

2427* 在全新安裝上，啟動 `claude`，等待工作階段載入，結束，然後再次執行 `claude import`

2428* 功能旗標取得保持關閉的地方，自己設定設定：使用 [`claude mcp add`](/docs/zh-TW/mcp#installing-mcp-servers) 新增 MCP 伺服器，並建立您想要帶過來的 [`CLAUDE.md` 檔案](/docs/zh-TW/memory#how-claude-md-files-load)、[技能和命令](/docs/zh-TW/skills#where-skills-live)和[子代理](/docs/zh-TW/sub-agents#choose-the-subagent-scope)。訊息也命名 `~/.claude/settings.json`。在 `claude import` 帶來的設定中，該檔案只保存[權限模式](/docs/zh-TW/settings-reference#permission-settings)；Claude Code 不從中讀取 MCP 伺服器。

2429

2430<h3 id="could-not-read-claude-code-config">

2431 無法讀取 Claude Code 設定

2432</h3>

2433

2434您在 Claude Code 無法解析 `~/.claude.json` 時執行了 [`claude import`](/docs/zh-TW/cli-reference#cli-commands)，該檔案是它儲存您的登入和每個專案狀態的地方。子命令讀取該檔案以檢查可用性，但不會顯示互動工作階段顯示的恢復對話框，所以它以代碼 1 結束。在 v2.1.222 之前，具有無法讀取的設定檔的 `claude import` 啟動了互動工作階段，其恢復對話框處理了該檔案。

2435

2436```text theme={null}

2437Could not read Claude Code config — run `claude` with no arguments to recover it.

2438```

2439

2440**該怎麼做：**

2441

2442* 執行 `claude` 而不帶引數。Claude Code 偵測無效檔案並提供重設它。然後再次執行 `claude import`。

2443* 若要保留您所做的手動編輯，請在編輯器中修復 `~/.claude.json` 中的 JSON 語法，然後重新執行 `claude import`

2444

2445<h3 id="could-not-import-a-server-from-claude-desktop">

2446 無法從 Claude Desktop 匯入伺服器

2447</h3>

2448

2449Claude Code 無法新增您在 `claude mcp add-from-claude-desktop` 中選擇的其中一個伺服器。該命令仍會匯入其他選定的伺服器，並為每個無法新增的伺服器列印一行。在 v2.1.205 之前，第一個失敗的伺服器停止了匯入，所有選定的伺服器都未被新增。

2450

2451```text theme={null}

2452Could not import my server: Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.

2453```

2454

2455伺服器名稱之後的文字是原因。最常見的是名稱檢查：Claude Desktop 允許伺服器名稱中的字元，例如空格和句號，而 `claude mcp` 限制為字母、數字、連字號和底線。其他原因包括無法通過驗證的伺服器設定和被您組織的 [MCP 原則](/docs/zh-TW/managed-mcp)阻止的伺服器。

2456

2457**該怎麼做：**

2458

2459* 在 `claude_desktop_config.json` 中重新命名伺服器以僅使用字母、數字、連字號和底線，然後再次執行 `claude mcp add-from-claude-desktop`

2460* 使用有效名稱直接使用 `claude mcp add` 或 `claude mcp add-json` 新增該伺服器。請參閱[從 Claude Desktop 匯入 MCP 伺服器](/docs/zh-TW/mcp#import-mcp-servers-from-claude-desktop)。

2461

2462<h3 id="cannot-add-mcp-server-to-the-managed-scope">

2463 無法將 MCP 伺服器新增到受管範圍

2464</h3>

2465

2466您使用 `--scope managed` 執行了 `claude mcp add` 或 `claude mcp add-json`。該範圍保存您的組織透過 [`managedMcpServers`](/docs/zh-TW/settings-reference#managedmcpservers) 受管設定提供的伺服器。Claude Code 只從受管設定讀取它們，所以命令無法將伺服器寫入該範圍。

2467

2468```text theme={null}

2469Cannot add MCP server to scope: managed

2470```

2471

2472**該怎麼做：**

2473

2474* 將伺服器新增到您可以寫入的範圍：`local`、`user` 或 `project`。不使用 `--scope` 時，命令使用 `local`。請參閱 [MCP 安裝範圍](/docs/zh-TW/mcp#mcp-installation-scopes)

2475* 若要為組織中的每個使用者提供伺服器，請將其新增到您部署的受管設定中的 [`managedMcpServers`](/docs/zh-TW/settings-reference#managedmcpservers)

2476

2477<h3 id="cant-read-mcp-json">

2478 無法讀取 .mcp.json

2479</h3>

2480

2481讀取專案 [`.mcp.json`](/docs/zh-TW/mcp#project-scope) 的命令，例如 `claude mcp add` 或 `claude mcp add-json` 搭配 `--scope project`，或 `claude mcp remove`，發現您目前目錄中的檔案不是常規檔案或大於 2 MiB，所以它以此錯誤結束而不是讀取檔案。

2482

2483```text theme={null}

2484Can't read .mcp.json: it isn't a regular file or is larger than 2097152 bytes. Fix or remove it, then run the command again.

2485```

2486

2487在 v2.1.257 之前，`.mcp.json` 處的 FIFO 會讓命令無限期等待而沒有輸出，到裝置檔案（例如 `/dev/zero`）的符號連結會增加記憶體直到程序被殺死。

2488

2489**該怎麼做：**

2490

2491* 檢查您目前目錄中 `.mcp.json` 處的內容。將其替換為[專案範圍格式](/docs/zh-TW/mcp#project-scope)中的普通 JSON 檔案，或刪除它，然後再次執行命令。

2492

2493<h3 id="anthropic-hosted-and-doesnt-support-local-oauth">

2494 伺服器是 Anthropic 託管的，不支援本地 OAuth

2495</h3>

2496

2497您為 URL 指向透過第三方身份提供者進行驗證的 Anthropic 託管連接器主機的 MCP 伺服器啟動了登入。這些主機包括 `microsoft365.mcp.claude.com`、`gmail.mcp.claude.com` 和 `gcal.mcp.claude.com`。Claude Code 拒絕為這些主機從 `/mcp` 面板和 `claude mcp login` 啟動其本地 OAuth 流程，因為[它們的登入僅透過 claude.ai 工作](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai)。

2498

2499```text theme={null}

2500"gmail" is Anthropic-hosted and doesn't support local OAuth. Connect it via Settings → Connectors on claude.ai (requires `claude login`), then it'll be available here automatically.

2501```

2502

2503Claude Code 按 URL 匹配這些主機，所以當您使用 `claude mcp add` 或在 `.mcp.json` 中新增的伺服器指向其中之一時，訊息會出現。

2504

2505**該怎麼做：**

2506

2507* 使用 `claude mcp remove <name>` 移除您的項目，以便它無法隱藏相同 URL 處的 claude.ai 連接器

2508* 移除後，在[claude.ai/customize/connectors](https://claude.ai/customize/connectors)連接服務，同時登入您在 Claude Code 中使用的帳戶。連接後，如果您的活躍驗證方法是 claude.ai 訂閱登入，[連接器會自動出現在 Claude Code 中](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai)

2509

2510<h3 id="server-rejected-the-authorization-header-minted-by-the-configured-headershelper">

2511 伺服器拒絕了由設定的 headersHelper 鑄造的授權標頭

2512</h3>

2513

2514其 [`headersHelper`](/docs/zh-TW/mcp#use-dynamic-headers-for-custom-authentication) 提供 `Authorization` 標頭的 MCP 伺服器以 HTTP 401 或 403 回答連接，所以 Claude Code 將連接報告為失敗。因為幫助程式提供 `Authorization` 標頭，Claude Code [不會回退到 OAuth](/docs/zh-TW/mcp#authenticate-with-remote-mcp-servers) 用於伺服器：

2515

2516```text theme={null}

2517Server rejected the Authorization header minted by the configured headersHelper (HTTP 401). Check that the helper command returns a valid credential for this MCP endpoint — OAuth fallback is disabled when the helper supplies Authorization.

2518```

2519

2520Claude Code 在每次連接嘗試時重新執行幫助程式，所以在暫時拒絕後重試（例如權杖輪換競爭）可以使用新認證成功。

2521

2522**該怎麼做：**

2523

2524* 按照 Claude Code 執行它的方式執行 `headersHelper` 命令：從 [Claude Code 執行它的目錄](/docs/zh-TW/mcp#where-the-helper-runs)，使用 [Claude Code 為其設定的環境變數](/docs/zh-TW/mcp#use-dynamic-headers-for-custom-authentication)，以及不使用 [Claude Code 為來自專案 `.mcp.json`、外掛程式或專案代理檔案的伺服器移除的認證變數](/docs/zh-TW/mcp#which-variables-a-helper-can-read)。檢查它列印的 `Authorization` 值伺服器的端點接受

2525* 修復幫助程式或其認證來源後，在 `/mcp` 中選擇伺服器並選擇**重新連接**

2526

2527在 v2.1.248 之前，Claude Code 為其幫助程式提供 `Authorization` 標頭的伺服器執行了 OAuth 發現。該發現可能失敗並出現 `Incompatible auth server: does not support dynamic client registration` 而不是報告被拒絕的認證。

2528

2529<h3 id="mcp-permission-prompt-tool-not-found">

2530 找不到 MCP 權限提示工具

2531</h3>

2532

2533您傳遞給 [`--permission-prompt-tool`](/docs/zh-TW/cli-reference#cli-flags) 的工具在執行首次需要權限決定時不在連接的 MCP 工具中，可能是因為其伺服器從未連接，或因為沒有連接的伺服器公開該名稱的工具。Claude Code 仍會傳送您的提示：[非互動](/docs/zh-TW/headless)執行在第一個需要批准的工具呼叫時以此錯誤和結束代碼 1 結束，所以即使提出了請求，它也不會產生答案。在第一個提示之前，Claude Code 等待最多由 [`MCP_TIMEOUT`](/docs/zh-TW/env-vars) 設定的每個伺服器連接逾時 30 秒，以便該伺服器連接。在 v2.1.206 之前，啟動不會等待伺服器完成連接，所以啟動緩慢但健康的伺服器也會產生此錯誤。

2534

2535```text theme={null}

2536Error: MCP tool mcp__permissions__approve (passed via --permission-prompt-tool) not found. Available MCP tools: none

2537```

2538

2539`Available MCP tools:` 之後的清單命名等待結束時連接的 MCP 工具。

2540

2541**該怎麼做：**

2542

2543* 檢查伺服器啟動並保持連接：在同一目錄中執行 `claude mcp list` 並確認伺服器列為已連接

2544* 確認工具名稱與伺服器公開的 `mcp__<server>__<tool>` 名稱相符

2545* 如果伺服器需要超過 30 秒才能啟動，請提高 [`MCP_TIMEOUT`](/docs/zh-TW/env-vars)

2546

2547<h3 id="oauth-callback-port-is-already-in-use">

2548 OAuth 回呼連接埠已在使用中

2549</h3>

2550

2551當您使用 OAuth 登入遠端 MCP 伺服器時，Claude Code 啟動本地接聽程式以接收登入回呼。如果該接聽程式需要的連接埠被另一個程序持有，登入會失敗並出現此訊息。這主要發生在透過 [`MCP_OAUTH_CALLBACK_PORT`](/docs/zh-TW/env-vars) 變數或 `--callback-port` 設定的[固定回呼連接埠](/docs/zh-TW/mcp#use-a-fixed-oauth-callback-port)上，因為沒有一個 Claude Code 會選擇可用的連接埠。

2552

2553```text theme={null}

2554OAuth callback port <port> is already in use — another process may be holding it. Run `lsof -ti:<port> -sTCP:LISTEN` to find it.

2555```

2556

2557在 Windows 上，建議的命令是 `netstat -ano | findstr :<port>`。

2558

2559**該怎麼做：**

2560

2561* 執行訊息中的命令以找到持有連接埠的程序，並停止它或等待它完成

2562* 如果另一個程式永久需要該連接埠，請向伺服器註冊不同的重定向 URI，並使用 `MCP_OAUTH_CALLBACK_PORT` 或 `--callback-port` 設定其連接埠，以及您使用的任何一個

2563* 然後再次啟動登入，例如在 `/mcp` 中選擇伺服器

2564

2565<h3 id="security-review-fails-without-origin-head">

2566 /security-review 在沒有 origin/HEAD 的情況下失敗

2567</h3>

2568

2569[`/security-review`](/docs/zh-TW/commands#all-commands) 透過針對 `origin/HEAD` 進行差異來建立其審查上下文，該本地參考記錄您的 `origin` 遠端上的預設分支。當該參考不存在時，收集差異的 git 命令失敗，審查在啟動前停止。

2570

2571```text theme={null}

2572Error: Shell command failed for pattern "!`git diff --name-only origin/HEAD...`": [stderr]

2573fatal: ambiguous argument 'origin/HEAD...': unknown revision or path not in the working tree.

2574Use '--' to separate paths from revisions, like this:

2575'git <command> [<revision>...] -- [<file>...]'

2576```

2577

2578引用的命令在執行之間變化：審查同時針對 `origin/HEAD` 啟動多個 `git` 命令，並報告首先失敗的命令，所以您可能會在其位置看到 `git log` 或不同的 `git diff`。Git 只在遠端的預設分支被遠端公告且被您的取得 refspec 涵蓋時建立參考。遠端的完整 `git clone` 滿足兩個條件。單分支和 CI 檢查取得太窄的 refspec，伺服器端 HEAD 指向沒有人推送的分支不公告預設值，沒有 `origin` 遠端的儲存庫或您從未取得的儲存庫提供兩者都不提供。

2579

2580Claude Code 為任何[注入動態上下文](/docs/zh-TW/skills#when-an-injected-command-fails)的技能顯示相同的錯誤。失敗的注入命令會中止該技能的呼叫。兩個同級字串在命令執行之前就會觸發：

2581

2582* `Shell command permission check failed for pattern "..."`：命令的權限檢查返回了允許以外的內容。注入的命令永遠不會提示，所以呼叫會中止而不詢問您。使用 [`allowed-tools`](/docs/zh-TW/skills#pre-approve-tools-for-a-skill) 預先批准沒有規則符合的命令。符合的詢問或拒絕規則仍會中止呼叫，無論 `allowed-tools` 如何

2583* ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found``：技能的 frontmatter 在沒有它的機器上要求 bash。安裝 Git for Windows 或將 frontmatter 變更為 `shell: powershell`。請參閱[注入命令如何執行](/docs/zh-TW/skills#how-injected-commands-run)

2584

2585**該怎麼做：**

2586

2587* 透過命名您的遠端預設分支建立參考：`git remote set-head origin <default-branch>`。只要本地追蹤參考 `origin/<default-branch>` 存在，這就有效。如果它不存在，如在單分支複製中，首先取得分支：執行 `git remote set-branches --add origin <branch>`，然後 `git fetch origin`，然後重新執行 set-head 命令。重新執行 `/security-review`。

2588* 如果您寧願不命名分支，執行 `git fetch origin` 然後 `git remote set-head origin --auto`，它詢問遠端其預設分支是什麼。當遠端不公告預設分支時它失敗並出現 `error: Cannot determine remote HEAD`，因為它是空的或其 HEAD 指向沒有人推送的分支；改為明確命名分支。當您的複製不取得該分支時它失敗並出現 `error: Not a valid ref`；首先如上所述擴大 refspec。

2589* 如果儲存庫沒有遠端，使用 `git remote add origin <url>` 新增一個並在建立參考之前取得。如果遠端是空的，首先使用 `git push -u origin HEAD` 推送您的分支，並在 set-head 命令中命名該分支；`origin/HEAD` 然後指向您剛推送的分支，所以 `/security-review` 看到空差異直到分支與它分歧。

2590

2591<h3 id="input-must-be-provided-when-using-print">

2592 使用 --print 時必須提供輸入

2593</h3>

2594

2595裸 `claude` 需要 stdout 是終端才能啟動互動 UI。當 stdout 被重定向或控制台不是真實終端時，例如 PowerShell ISE 和某些 IDE 輸出窗格，`claude` 改為以[非互動](/docs/zh-TW/headless)模式執行。這與 `claude -p` 相同，它需要提示，所以訊息命名 `--print` 即使您沒有傳遞旗標。在任何地方傳遞 `-p`/`--print` 而沒有提示且 stdin 上沒有任何內容會產生相同的錯誤。

2596

2597```text theme={null}

2598Error: Input must be provided either through stdin or as a prompt argument when using --print

2599```

2600

2601**該怎麼做：**

2602

2603* 為了互動使用，在真實終端中執行 `claude`：Windows Terminal 或 PowerShell 控制台而不是 ISE，以及您的 IDE 整合終端而不是輸出窗格

2604* 為了一次性使用，傳遞提示：`claude -p "your question"`，或使用 `echo "your question" | claude -p` 管道它

2605

2606<h3 id="input-contained-only-whitespace">

2607 輸入僅包含空白

2608</h3>

2609

2610在[非互動模式](/docs/zh-TW/headless)中，Claude Code 拒絕完全由空格、製表符或換行符組成的提示，而不是傳送它，因為 API 拒絕沒有可見文字的訊息。您看到的訊息取決於空白提示來自何處：

2611

2612* **`claude -p` 的提示引數或管道 stdin**：`claude` 以 `Error: Input contained only whitespace. Provide a prompt with text through stdin or as a prompt argument when using --print` 結束

2613* **提交到執行中的 `--input-format stream-json` 或 [Agent SDK](/docs/zh-TW/agent-sdk/overview) 工作階段的訊息**：Claude Code 在沒有呼叫模型的情況下結束轉身，工作階段保持可用。拒絕作為資訊訊息和轉身的結果文字到達：`Blank prompt — the message was only whitespace, so nothing was sent to the model.`

2614

2615在 v2.1.229 之前，Claude Code 將僅空白訊息傳送到 API，API 以 400 錯誤拒絕了請求。

2616

2617**該怎麼做：**

2618

2619* 在提示中包含可見文字。如果指令碼從變數或檔案建立提示，請在呼叫 Claude Code 之前檢查來源是否不為空。

2620

2621<h3 id="stream-json-input-carried-over-256m-characters-with-no-newline">

2622 stream-json 輸入在沒有換行符的情況下超過 256M 個字元

2623</h3>

2624

2625您的程式在沒有換行符的情況下在 stdin 上傳送了超過 268,435,456 個字元到 `claude -p --input-format stream-json` 執行，所以 Claude Code 將此錯誤列印到 stderr 並以代碼 1 結束，而不是緩衝更多輸入。訊息將該預算陳述為 `256M`。在 v2.1.257 之前，Claude Code 無限制地緩衝此類輸入，增加記憶體直到程序崩潰或被殺死。

2626

2627```text theme={null}

2628Error: stream-json input carried over 256M characters with no newline. Each stream-json message must be a single newline-terminated JSON line: either the producer is not newline-terminating its messages, or one message exceeded this budget.

2629```

2630

2631沒有換行符的這麼長的輸入通常意味著生產者根本不是 stream-json 生產者，例如二進位檔案或意外管道的純日誌輸出。超過預算的單個訊息失敗相同的檢查。

2632

2633**該怎麼做：**

2634

2635* 檢查什麼被管道到 stdin。使用 [`--input-format stream-json`](/docs/zh-TW/cli-reference#cli-flags)，每個訊息必須是一個換行符終止的 JSON 行

2636* 若要改為傳送純文字，請放棄 `--input-format stream-json`；`claude -p` 預設從 stdin 讀取純文字提示

2637

2638<h3 id="unknown-command">

2639 未知命令

2640</h3>

2641

2642您提交了一個 `/` 名稱，它與此工作階段中的任何命令都不符，所以 Claude Code 報告該名稱而不是執行任何操作：

2643

2644```text theme={null}

2645Unknown command: /hepl. Did you mean /help?

2646```

2647

2648Claude Code 建議此工作階段中功能表列出的最接近的命令名稱或別名。當沒有接近的時，訊息在名稱後結束。原因通常是以下之一：

2649

2650* 打字錯誤，例如 `/hepl` 代替 `/help`。[命令功能表如何符合您輸入的內容](/docs/zh-TW/commands#how-the-command-menu-matches-what-you-type)涵蓋在您提交之前選擇接近的符合。

2651* 存在但在此工作階段中不可用的命令，因為不符合要求，例如您的平台、計畫或驗證方法。[`/web-setup`](/docs/zh-TW/web-quickstart#web-setup-shows-no-commands-match-or-unknown-command) 和 [`/schedule`](/docs/zh-TW/routines#schedule-returns-unknown-command) 的疑難排解項目演練兩個常見情況。某些命令在您的組織原則禁用它們時以自己的訊息回答

2652* 來自此工作階段中未安裝或連接的[外掛程式](/docs/zh-TW/plugins)或 [MCP 伺服器](/docs/zh-TW/mcp#use-mcp-prompts-as-commands)的命令

2653

2654Claude Code 不會將每個以 `/` 開頭的提示視為命令。當 `/` 之後的第一個單詞以標點符號開頭時，它會將提示傳送給 Claude 作為普通訊息，例如開啟 Lean 文件註釋的 `/--`，或是路徑，例如 `/var/log/syslog`。

2655

2656在 v2.1.236 之前，如果您在命令功能表列出您輸入的名稱的接近符合時按下 `Enter`，Claude Code 會執行該符合，所以 `/hepl` 之類的打字錯誤會執行 `/help` 而不是產生此訊息。

2657

2658**該怎麼做：**

2659

2660* 執行建議的名稱，或輸入 `/` 後跟名稱的一部分以查看此工作階段中可用的內容

2661* 如果 Claude Code 將記錄的命令報告為未知，請檢查[命令參考](/docs/zh-TW/commands)中的其行以了解它命名的要求

2662

2663<h3 id="diff-is-too-large-for-ultrareview">

2664 差異對於 ultrareview 來說太大

2665</h3>

2666

2667您的分支與基礎分支之間的差異，包括未提交和暫存的變更，超過了 [ultrareview](/docs/zh-TW/ultrareview) 的大小限制，所以 `/code-review ultra` 和 `claude ultrareview` 子命令在雲端工作階段啟動之前拒絕審查。被拒絕的審查不使用免費執行，也不計費使用額度。訊息命名有效的限制、您的差異大小以及貢獻最多變更行的檔案。在 v2.1.216 之前，訊息只顯示原始差異統計。

2668

2669```text theme={null}

2670Diff is too large for ultrareview: 812 files, 96,410 lines changed (limits: 500 files, 8,000 lines). Largest files: package-lock.json (41,904 lines), dist/bundle.js (18,210 lines), src/generated/api.ts (9,876 lines). Pass a closer base branch (`/code-review ultra <branch>`) to narrow the scope, or split the change.

2671```

2672

2673審查拉取請求應用相同的限制；該形式的訊息以 `PR #<N> is too large for ultrareview` 開頭，並命名 PR 的檔案和行計數。

2674

2675**該怎麼做：**

2676

2677* 傳遞更接近您工作的基礎分支，例如 `/code-review ultra develop`，以便審查僅涵蓋針對該分支的差異

2678* 將變更分成較小的分支並審查每一個。訊息命名的檔案貢獻最多變更行，所以首先開始將這些移到自己的分支。

2679

2680<h3 id="could-not-find-merge-base-with-the-base-branch">

2681 找不到與基礎分支的合併基礎

2682</h3>

2683

2684`/code-review ultra` 和 `claude ultrareview` 子命令審查您的分支與基礎分支之間的差異，這需要兩者共享的提交。當 `git merge-base` 找不到時，Claude Code 在雲端工作階段啟動之前拒絕審查。在 Claude Code 可以驗證完整的複製上，至少有一個分支，它改為[審查每個追蹤的檔案](/docs/zh-TW/ultrareview#diff-limits-and-fallbacks)而不是拒絕。當基礎分支根本找不到時，當 Claude Code 無法驗證您的複製完整時，或在罕見的儲存庫中（例如 SHA-256 物件格式），您會看到此拒絕。

2685

2686```text theme={null}

2687Could not find merge-base with main. Pass the base branch explicitly (e.g. `/code-review ultra develop`) or make sure you're in a git repo with a main branch.

2688```

2689

2690第一句之後的提示取決於 Claude Code 觀察到的內容：

2691

2692* **您沒有傳遞基礎分支**：Claude Code 與儲存庫的預設分支進行了比較，並建議明確傳遞您的基礎，如上例所示

2693* **您傳遞的基礎分支已在您的複製中**：提示讀取 ``Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)``

2694* **您傳遞的基礎分支不在您的複製中**：Claude Code 在比較之前從 origin 取得了它。提示讀取 ``<branch> was fetched from origin but shares no history with HEAD. If another branch is your real base, pass it explicitly (`/code-review ultra <branch>`)``；當 Claude Code 無法判斷您的複製是否淺時，它改為建議 `git fetch --unshallow origin`。在 v2.1.221 之前，提示為每個取得的基礎分支建議 `git fetch --unshallow origin`，在完整複製上該命令失敗並出現 `fatal: --unshallow on a complete repository does not make sense`。

2695

2696**該怎麼做：**

2697

2698* 如果另一個分支是您的真實基礎，明確傳遞它：`/code-review ultra <branch>`

2699* 如果您的複製可能沒有完整歷史，執行 `git fetch --unshallow origin` 並重新執行審查

2700

2701<h3 id="your-checkout-has-no-branches">

2702 您的檢查沒有分支

2703</h3>

2704

2705檢查可以有提交但沒有分支：如果您執行 `git init` 後跟 `git fetch <url>` 和 `git checkout FETCH_HEAD`，您會得到一個分離的 HEAD 而沒有參考。Claude Code 將您的儲存庫打包為 git 套件以上傳以進行 [ultrareview](/docs/zh-TW/ultrareview)，它無法捆綁沒有分支或其他參考的儲存庫，所以 `/code-review ultra` 和 `claude ultrareview` 子命令在雲端工作階段啟動之前拒絕審查。

2706

2707```text theme={null}

2708Your checkout has no branches (detached HEAD only), which cloud review can't bundle. Create one first — `git checkout -b <name>` — then rerun /code-review ultra.

2709```

2710

2711在 v2.1.221 之前，Claude Code 嘗試審查此檢查中的每個追蹤檔案，上傳失敗。

2712

2713**該怎麼做：**

2714

2715* 使用 `git checkout -b <name>` 在您目前的提交處建立分支，然後重新執行審查

2716

2717<h3 id="no-github-account-is-connected-to-your-claude-account">

2718 沒有 GitHub 帳戶連接到您的 Claude 帳戶

2719</h3>

2720

2721您執行了 `/code-review ultra <PR#>` 或 `claude ultrareview <PR#>`，在建立雲端工作階段之前，Claude Code 詢問伺服器[連接到您的 Claude 帳戶的 GitHub 帳戶](/docs/zh-TW/ultrareview#review-a-pull-request)是否可以到達 PR 的儲存庫。沒有帳戶連接，或連接已過期，所以雲端複製會失敗，Claude Code 拒絕啟動。Claude Code 不會為被拒絕的啟動花費免費執行或計費使用額度。

2722

2723```text theme={null}

2724Ultrareview clones <owner>/<repo> in the cloud with the GitHub account connected to your Claude account, and none is connected (or the connection expired). To fix: run /web-setup to reuse your GitHub CLI login, or connect an account at https://claude.ai/connect-github — then re-run /code-review ultra 1234 (allow a minute after connecting).

2725```

2726

2727當 [`/web-setup`](/docs/zh-TW/web-quickstart#connect-from-your-terminal) 在您的工作階段中不可用時，訊息只命名 claude.ai 連結。

2728

2729**該怎麼做：**

2730

2731* 執行 `/web-setup` 以將您的 GitHub CLI 登入連接到您的 Claude 帳戶，或在 [claude.ai/connect-github](https://claude.ai/connect-github) 連接帳戶

2732* 連接後一分鐘重新執行審查

2733

2734在 v2.1.248 之前，Claude Code 在啟動前不檢查此項。

2735

2736<h3 id="your-connected-github-account-cant-see-the-repository">

2737 您連接的 GitHub 帳戶看不到儲存庫

2738</h3>

2739

2740您執行了 `/code-review ultra <PR#>` 或 `claude ultrareview <PR#>`，[連接到您的 Claude 帳戶的 GitHub 帳戶](/docs/zh-TW/ultrareview#review-a-pull-request)無法讀取 PR 的儲存庫，所以雲端複製會失敗，Claude Code 拒絕啟動。Claude Code 不會為被拒絕的啟動花費免費執行或計費使用額度。

2741

2742```text theme={null}

2743Your connected GitHub account can't see <owner>/<repo> — usually the Claude GitHub app isn't installed on <owner> or wasn't granted this repo (web-connected accounts need it for private repos), or a different GitHub account is connected. To fix: run /web-setup to reuse your GitHub CLI login, or install the app at https://github.com/apps/claude/installations/new — then re-run /code-review ultra 1234.

2744```

2745

2746當 [`/web-setup`](/docs/zh-TW/web-quickstart#connect-from-your-terminal) 在您的工作階段中不可用時，訊息只命名應用程式安裝。

2747

2748**該怎麼做：**

2749

2750* 如果您的本地 `gh` CLI 可以讀取儲存庫，執行 `/web-setup` 以將該登入連接到您的 Claude 帳戶

2751* 變更後重新執行審查

2752

2753在 v2.1.248 之前，Claude Code 在啟動前不檢查此項。

2754

2755<h3 id="the-github-app-preflight-failed-transiently">

2756 GitHub App 預檢暫時失敗

2757</h3>

2758

2759您從本地儲存庫啟動了[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)，兩個步驟一起失敗。Claude Code 無法建立或上傳您的儲存庫套件。在上傳之前，它檢查了雲端服務是否可以從 GitHub 複製儲存庫，而不是明確的答案，該檢查以重試可以清除的錯誤結束，例如網路錯誤、逾時或暫時伺服器錯誤。完整訊息以停止套件的內容開頭，例如 `Could not upload repo bundle (<error>)`，並以預檢句子結尾：

2760

2761```text theme={null}

2762Could not upload repo bundle (<error>). The GitHub App preflight failed transiently (network or service hiccup) — retry in a moment to start from GitHub instead

2763```

2764

2765**該怎麼做：**

2766

2767* 片刻後重新執行命令。當 GitHub 檢查通過時，Claude Code 可以從 GitHub 複製啟動工作階段，所以失敗的上傳不再阻止啟動

2768* 如果重試持續失敗，訊息的開頭命名停止上傳的內容。當該原因是您可以修復的內容時，修復它以便工作階段可以改為從您的本地儲存庫啟動

2769

2770在 v2.1.251 之前，Claude Code 以 `Please set up GitHub on https://claude.ai/code` 結束訊息，即使 GitHub 檢查只是暫時失敗，設定建議無法清除暫時失敗。

2771

2772<h3 id="failed-to-resume-the-conversation">

2773 無法恢復對話

2774</h3>

2775

2776Claude Code 無法讀取或處理您從 [`claude --resume` 選擇器](/docs/zh-TW/sessions#use-the-session-picker)選擇的工作階段的已儲存文字記錄，所以它結束程序而不是在部分載入狀態下繼續。訊息包括重試的命令：

2777

2778```text theme={null}

2779Failed to resume the conversation.

2780Run claude --resume <session-id> to retry, or claude to start a new session.

2781```

2782

2783Claude Code 在顯示訊息後以代碼 1 結束。執行中工作階段內的 `/resume` 選擇器報告對話中的 `Failed to resume conversation`，您目前的工作階段保持執行。在 v2.1.216 之前，來自 `claude --resume` 選擇器的失敗恢復在 `Resuming conversation…` 微調器上無限期停留，而不是顯示此訊息。

2784

2785**該怎麼做：**

2786

2787* 執行 `claude --resume <session-id>` 搭配訊息中的工作階段 ID 以重試

2788* 如果重試再次失敗，執行 `claude` 以啟動新工作階段

2789

2790<h3 id="no-conversation-found-with-the-session-id">

2791 找不到具有工作階段 ID 的對話

2792</h3>

2793

2794您傳遞了工作階段 ID 給 `claude --resume <session-id>`，沒有儲存的文字記錄符合它：

2795

2796```text theme={null}

2797No conversation found with session ID: <session-id>

2798```

2799

2800Claude Code 在顯示訊息後以代碼 1 結束。Claude Code [首先搜尋目前專案，然後搜尋此機器上的每個其他專案](/docs/zh-TW/sessions#resume-a-session)以尋找 ID。在 v2.1.223 之前，查詢在目前專案目錄及其 git worktrees 處停止，所以從工作階段最後工作的目錄恢復。

2801

2802常見原因：

2803

2804* **打字錯誤的 ID**：對於非互動執行，ID 是 [`--output-format json` 輸出](/docs/zh-TW/headless#get-structured-output)的 `session_id` 欄位

2805* **已刪除的文字記錄**：Claude Code 在[保留期](/docs/zh-TW/sessions#where-transcripts-are-stored)後移除文字記錄，預設為 30 天，遵循[保留掃描規則](/docs/zh-TW/claude-directory#cleaned-up-automatically)

2806* **不同的機器**：Claude Code 在本地儲存文字記錄，所以在執行工作階段的機器上恢復工作階段

2807* **重複副本**：如果您在 `~/.claude/projects` 下複製了專案目錄，所以兩個文字記錄帶有相同的 ID，Claude Code 報告此訊息而不是任意恢復一個副本

2808

2809**該怎麼做：**

2810

2811* 對於互動工作階段，使用 `claude --resume` 開啟[工作階段選擇器](/docs/zh-TW/sessions#use-the-session-picker)，按 `Ctrl+A` 將其擴大到此機器上的每個專案，然後選擇工作階段

2812* 使用 `claude -p` 或 [Agent SDK](/docs/zh-TW/agent-sdk/overview) 建立的工作階段不會出現在選擇器中，所以重新檢查 ID 與您的原始執行列印的 `session_id`

2813

2814<h3 id="cannot-switch-renderers-in-this-session">

2815 無法在此工作階段中切換轉譯器

2816</h3>

2817

2818當您切換轉譯器時，Claude Code 重新啟動其程序。您在 Claude Code 拒絕重新啟動的工作階段中執行了 [`/tui`](/docs/zh-TW/fullscreen#enable-fullscreen-rendering)，所以它不會切換並保存任何內容。您看到的訊息告訴您原因：

2819

2820* `Cannot switch renderers while work is running in the background`：您有在背景執行的工作，重新啟動會放棄，例如背景 shell 或子代理。等待工作完成或使用 [`/tasks`](/docs/zh-TW/commands) 停止它，然後再次執行 `/tui fullscreen` 或 `/tui default`

2821* `Cannot switch renderers in this session`：工作階段有 Claude Code 無法傳遞給重新啟動程序的限制。在 v2.1.234 之前，Claude Code 無論如何都會重新啟動，重新啟動的工作階段執行時沒有它們

2822

2823在限制訊息中，括號中的部分命名 Claude Code 發現的限制：

2824

2825```text theme={null}

2826Cannot switch renderers in this session — it has restrictions a restart can't carry over (permission rules set for this session only). Nothing was changed. Running /tui fullscreen in a session started without them switches every later session too.

2827```

2828

2829訊息可以在括號中顯示的每個原因：

2830

2831* `launch flags: a custom system prompt, a tool allowlist, or restricted settings`：您使用 Claude Code 不傳遞回重新啟動程序的旗標啟動了工作階段。這些旗標包括 [`--system-prompt`](/docs/zh-TW/cli-reference#cli-flags)、`--system-prompt-file`、`--append-system-prompt-file`、[`--tools`](/docs/zh-TW/cli-reference#cli-flags) 允許清單、[`--setting-sources`](/docs/zh-TW/cli-reference#cli-flags) 和 [`--permission-prompt-tool`](/docs/zh-TW/cli-reference#cli-flags)

2832* `permission rules set for this session only`：來自鉤子或 SDK 呼叫者的[權限更新](/docs/zh-TW/hooks#permission-update-entries)新增了具有 `session` 目的地的拒絕或詢問規則。工作階段範圍的允許規則不會觸發拒絕。重新啟動會放棄它們，Claude Code 改為再次提示

2833* `ask-before-running rules with no command-line form`：來自鉤子或 SDK 呼叫者的權限更新新增了詢問規則以及 Claude Code 作為 `--allowed-tools` 和 `--disallowed-tools` 傳遞回的規則。沒有旗標存在用於詢問規則

2834* `permission rules a command line cannot carry intact` 和 `added directories a command line cannot carry intact`：權限更新在工作階段中期新增了規則或目錄路徑。重新啟動程序的命令列無法將其文字作為相同值帶回

2835

2836**該怎麼做：**

2837

2838* 在沒有這些限制的工作階段中，執行 `/tui fullscreen` 或 `/tui default` 以切換回。Claude Code 在那裡儲存 [`tui` 設定](/docs/zh-TW/settings-reference#tui)

2839

2840<h3 id="terminal-setup-left-your-zed-keymap-unchanged">

2841 /terminal-setup 讓您的 Zed 快捷鍵保持不變

2842</h3>

2843

2844您在 Zed 中執行了 [`/terminal-setup`](/docs/zh-TW/terminal-config#enter-multiline-prompts)，Claude Code 無法完成對您的 Zed `keymap.json` 的更新，所以它讓檔案保持原樣。

2845

2846每個訊息命名您的快捷鍵的路徑，並以您自己新增的快捷鍵區塊結尾：

2847

2848```text theme={null}

2849Couldn't update your Zed keymap, so it was left unchanged.

2850To add the binding yourself, add this block to the keymap array in <path to keymap.json>:

2851{ "context": "Terminal", "bindings": { "shift-enter": ["terminal::SendText", "\u001b\r"] } }

2852```

2853

2854訊息的第一行命名原因：

2855

2856* `Couldn't read your Zed keymap, so it was left unchanged.`：Claude Code 無法讀取檔案，例如因為檔案權限

2857* `Your Zed keymap isn't a readable list of keybindings, so it was left unchanged.`：檔案讀取良好，但不解析為快捷鍵區塊陣列，即使允許 `//` 註釋和尾隨逗號

2858* `Couldn't back up your Zed keymap; not modifying it.`：Claude Code 無法將檔案複製到其旁邊的 `.bak` 備份，所以它沒有變更任何內容

2859* `Couldn't update your Zed keymap, so it was left unchanged.`：合併的結果未驗證為有效的快捷鍵，帶有綁定，所以 Claude Code 改為丟棄它而不是寫入。具有重複鍵的快捷鍵區塊可能導致此情況

2860

2861**該怎麼做：**

2862

2863* 將訊息中的區塊複製到您 `keymap.json` 中訊息命名的路徑處的頂級陣列中

2864* 對於 `isn't a readable list of keybindings`，修復語法錯誤，或使檔案的頂級值成為陣列，然後再次執行 `/terminal-setup`

2865

2866在 v2.1.247 之前，`/terminal-setup` 無法解析使用 `//` 註釋或尾隨逗號的 Zed 快捷鍵，它用僅自己的綁定替換整個檔案，同時報告綁定已安裝。若要恢復較早版本替換的快捷鍵，請使用[輸入多行提示](/docs/zh-TW/terminal-config#enter-multiline-prompts)下描述的 `.bak` 備份檔案。

2867

2868<h3 id="skill-usage-reports-are-not-available-on-this-connection">

2869 此連接上不提供技能使用報告

2870</h3>

2871

2872您在[遠端控制](/docs/zh-TW/remote-control)上、從您的手機或瀏覽器執行了 [`/skill-doctor`](/docs/zh-TW/skills#find-unused-skills)。Claude Code 不會透過遠端控制傳送技能使用報告，並改為以此訊息回覆：

2873

2874```text theme={null}

2875Skill usage reports are not available on this connection.

2876```

2877

2878**該怎麼做：**

2879

2880* 在工作階段執行所在的機器上的終端中執行 `/skill-doctor`，或在那裡執行 `claude -p "/skill-doctor"`

2881

2882<h2 id="plugin-errors">

2883 Plugin 錯誤

2884</h2>

2885

2886這些錯誤來自 [plugin](/docs/zh-TW/plugins) 和 [marketplace](/docs/zh-TW/plugin-marketplaces) 設定。對於不會產生此頁面上其中一則訊息的 plugin 問題，例如無法載入的 marketplace URL 或已安裝但未出現的 plugin，請參閱 [Plugin 疑難排解](/docs/zh-TW/discover-plugins#troubleshooting)。

2887

2888<h3 id="plugin-eval-is-currently-in-early-access">

2889 plugin eval 目前處於早期存取階段

2890</h3>

2891

2892您執行了 [`claude plugin eval`](/docs/zh-TW/plugin-evals) 或 `claude plugin eval init`，它在執行任何操作之前以退出代碼 1 和以下其中一則訊息結束：

2893

2894```text theme={null}

2895`plugin eval` is currently in early access

2896```

2897

2898```text theme={null}

2899`plugin eval` is currently unavailable

2900```

2901

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

2903

2904**該怎麼做：**

2905

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

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

2908

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

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

2911</h3>

2912

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

2914

2915```text theme={null}

2916Marketplace "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.

2917```

2918

2919對於來源不是 GitHub 儲存庫或 Git URL 的 marketplace（例如本機目錄），中間句子改為 `can only be used with GitHub sources from the 'anthropics' organization`。`claude plugin marketplace add` 執行相同的檢查，並以 `Failed to add marketplace:` 後跟相同的保留名稱句子拒絕保留的名稱。

2920

2921**該怎麼做：**

2922

2923* 如果 marketplace 已經註冊，執行 `claude plugin marketplace remove <name>`，然後從官方 `github.com/anthropics` 儲存庫重新新增它

2924* 如果您發佈了在其名稱變成保留名稱之前使用該名稱的第三方 marketplace，請重新命名它並要求使用者從您的來源重新新增它

2925* 請參閱 [Marketplace schema](/docs/zh-TW/plugin-marketplaces#marketplace-schema) 下的保留名稱清單

2926

2927<h3 id="plugin-command-references-user-config">

2928 Plugin 命令在 shell 命令中參考 user\_config

2929</h3>

2930

2931Plugin hook、[monitor](/docs/zh-TW/plugins-reference#monitors) 或 MCP [`headersHelper`](/docs/zh-TW/mcp#use-dynamic-headers-for-custom-authentication) 命令參考 `${user_config.KEY}` [plugin 選項](/docs/zh-TW/plugins-reference#user-configuration)，而替換後的字串會被傳遞到 shell。設定的值包含 `$(...)` 、反引號或 `;` 會在該處作為程式碼執行，因此 Claude Code 拒絕啟動該元件而不是替換該值。檢查在命令範本上執行，因此即使尚未設定任何值，錯誤也會出現。在 v2.1.207 之前，該值被替換到 shell 命令中。

2932

2933措辭取決於哪個介面參考了該選項。Shell 形式的 hook 報告：

2934

2935```text theme={null}

2936Hook from plugin formatter@acme-tools references ${user_config.*} in a shell-form command. The substituted value would be re-parsed by the shell. Use exec form instead — {"command": "<executable>", "args": ["${user_config.KEY}", ...]} — or read $CLAUDE_PLUGIN_OPTION_<KEY> from the hook's environment. Command: ./scripts/notify.sh ${user_config.webhook_url}

2937```

2938

2939Monitor 報告：

2940

2941```text theme={null}

2942Monitor "deploy-status" from plugin deploy-tools references ${user_config.*} in its command. The substituted value would be passed to a shell. Monitor commands cannot safely reference ${user_config.*}; have the monitor script read the value from a config file or prompt instead.

2943```

2944

2945MCP `headersHelper` 報告：

2946

2947```text theme={null}

2948headersHelper for MCP server 'internal-api' references ${user_config.*}. The substituted value would be passed to a shell; read the value inside the helper script instead (e.g. from an env var set in the server's "env" block).

2949```

2950

2951**該怎麼做：**

2952

2953* 對於 hook，新增 `args` 陣列使其以 [exec 形式](/docs/zh-TW/hooks#exec-form-and-shell-form) 執行，其中每個 `${user_config.KEY}` 變成一個沒有 shell 的單一引數。或者移除參考並在指令碼內讀取 `$CLAUDE_PLUGIN_OPTION_<KEY>` 環境變數

2954* 對於 monitor，移除參考並讓 monitor 指令碼從設定檔讀取該值

2955* 對於 `headersHelper`，將 `${user_config.KEY}` 移到伺服器的 `headers` 欄位（不會進行 shell 解析），或在 helper 指令碼內讀取該值

2956

2957<h3 id="plugin-archive-integrity-check-failed">

2958 Plugin 封存完整性檢查失敗

2959</h3>

2960

2961Plugin 的 marketplace 項目使用具有 `sha256` 釘選的 [`archive` 來源](/docs/zh-TW/plugin-marketplaces#zip-archives)，而下載檔案的摘要與釘選不符。Claude Code 拒絕安裝，因此 plugin 快取中沒有任何變更。不符有三個可能的原因：

2962

2963* 作者計算釘選後，URL 上的檔案已變更

2964* 作者在 marketplace 項目中輸入了錯誤的摘要

2965* URL 提供的檔案與作者釘選的檔案不同

2966

2967```text theme={null}

2968Plugin archive integrity check failed for https://artifacts.example.com/claude-plugins/my-plugin.zip: expected sha256 6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1, got ac52220c0914ef8ca6a602e4a7362f88d30fb021110f72a6d15b68c3fe7df2b7. The archive was not installed. Verify the sha256 in the marketplace entry, or that the URL serves the intended file.

2969```

2970

2971**該怎麼做：**

2972

2973* 如果您發佈 plugin，使用 `shasum -a 256 my-plugin.zip` 或在 PowerShell 中使用 `Get-FileHash -Algorithm SHA256 my-plugin.zip` 重新計算 URL 提供的確切檔案的摘要，並更新 marketplace 項目中的 `sha256`

2974* 如果您安裝 plugin，執行 `/plugin marketplace update <name>` 以重新整理目錄以防項目已更正，然後重試安裝

2975* 如果在重新整理後摘要仍然不符，請在安裝前詢問 marketplace 擁有者他們釘選了哪個檔案

2976

2977<h3 id="path-escapes-plugin-directory">

2978 路徑逃逸 plugin 目錄

2979</h3>

2980

2981Plugin 元件路徑（在 plugin 的 `plugin.json` 或其 [marketplace 項目](/docs/zh-TW/plugin-marketplaces#plugin-entries) 中宣告）解析到 plugin 自己的目錄之外。Claude Code 捨棄該路徑並載入 plugin 的其餘部分。訊息中的元件名稱（例如 `commands` 或 `hooks`）命名了宣告路徑的欄位。

2982

2983```text theme={null}

2984commands path escapes plugin directory: ./../shared.md

2985```

2986

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

2988

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

2990

2991```text theme={null}

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

2993```

2994

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

2996

2997```text theme={null}

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

2999```

3000

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

3002

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

3004

3005**該怎麼做：**

3006

3007* 將參考的檔案移到 plugin 目錄內，並使用 `./` 相對路徑指向它

3008* 如果路徑是指向 plugin 外部檔案的符號連結，請用檔案副本替換符號連結

3009* 如果訊息說路徑包含反斜線，請使用正斜線寫入路徑，例如 `./commands/deploy.md`

3010* 若要與同一 marketplace 中的其他 plugin 共享檔案，請使用 plugin 目錄內的符號連結連結它們，遵循 [符號連結規則](/docs/zh-TW/plugins-reference#share-files-within-a-marketplace-with-symlinks)

3011

3012<h3 id="path-could-not-be-checked">

3013 無法檢查路徑

3014</h3>

3015

3016Claude Code 詢問作業系統 plugin 路徑是否存在，並收到除「找不到」以外的錯誤，因此它不會載入路徑命名的內容。plugin 的多少部分載入取決於哪個路徑失敗：

3017

3018* Plugin 的其中一個 [預設元件資料夾](/docs/zh-TW/plugins-reference#file-locations-reference)（例如 `skills/` 或 `commands/`）：plugin 的其他元件仍會載入

3019* Plugin 自己的目錄：該 plugin 中沒有任何內容載入

3020

3021對於根本不存在的路徑，您看不到此錯誤。在 `/plugin` 中，錯誤出現在 plugin 下方，並命名路徑和作業系統傳回的程式碼：

3022

3023```text theme={null}

3024skills path could not be checked: /home/user/my-plugin/skills (ELOOP)

3025```

3026

3027在 `claude plugin list` 中，相同的錯誤讀作 `Path not found: /home/user/my-plugin/skills (skills, ELOOP)`。

3028

3029產生此錯誤的原因包括：

3030

3031* `ELOOP`：路徑中的符號連結指向自己或形成迴圈

3032* `EIO` 或 `ESTALE`：路徑在損壞或陳舊的網路掛載上

3033* `EACCES`：路徑上方的其中一個目錄拒絕您遍歷它的權限

3034

3035**該怎麼做：**

3036

3037* 用真實資料夾替換指向自己的符號連結，或刪除它

3038* 如果路徑在網路掛載上，重新掛載共享

3039* 如果程式碼是 `EACCES`，恢復您在路徑上方目錄上的執行權限

3040* 修復路徑後執行 `/reload-plugins`，或重新啟動 Claude Code，以載入 plugin 或元件

3041

3042在 v2.1.265 之前，Claude Code 將無法檢查的預設元件資料夾視為不存在，並在沒有錯誤的情況下載入 plugin 而不包含該元件。

3043

3044<h3 id="marketplace-entry-path-does-not-stay-inside-the-marketplace-directory">

3045 Marketplace 項目路徑不保持在 marketplace 目錄內

3046</h3>

3047

3048Plugin 的 [marketplace 項目](/docs/zh-TW/plugin-marketplaces#plugin-entries) 宣告了一個來源路徑，Claude Code 無法將其解析到 marketplace 自己的目錄內的位置，因此 plugin 不會安裝或載入。拒絕涵蓋：

3049

3050* 絕對的項目路徑、使用 `..` 爬出 marketplace 或拼寫成網路路徑的項目路徑

3051* 從遠端來源（例如 git 或 URL）擷取的 marketplace 中的項目，通過解析到 marketplace 目錄外的符號連結到達其目標

3052* 相對項目在從直接 URL 新增到其 `marketplace.json` 的 marketplace 中：Claude Code 只下載該檔案，因此路徑命名的本機 plugin 檔案不存在。請參閱 [相對路徑的 Plugin 在基於 URL 的 marketplace 中失敗](/docs/zh-TW/plugin-marketplaces#plugins-with-relative-paths-fail-in-url-based-marketplaces)

3053

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

3055

3056```text theme={null}

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

3058```

3059

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

3061

3062```text theme={null}

3063Plugin source path refused: ./my-plugin does not stay inside its marketplace directory. Check that the marketplace entry has a plain relative path.

3064```

3065

3066**該怎麼做：**

3067

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

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

3070

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

3072 無法載入 marketplace 設定

3073</h3>

3074

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

3076

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

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

3079

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

3081

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

3083

3084```text theme={null}

3085✘ Failed to install plugin "my-plugin": Failed to load marketplace configuration: JSON Parse error: Unexpected EOF

3086```

3087

3088在 v2.1.246 之前，`claude plugin install` 沒有報告此失敗。

3089

3090**該怎麼做：**

3091

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

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

3094

3095<h2 id="tool-errors">

3096 工具錯誤

3097</h2>

3098

3099這些錯誤來自 Claude 的內建工具。Claude 會自動修正大多數工具錯誤。當需要您進行變更時，該錯誤的**應該怎麼做**清單會說明要變更的內容。

3100

3101<h3 id="agent-would-be-spawned-with-zero-tools">

3102 Agent would be spawned with zero tools

3103</h3>

3104

3105子代理的 [`tools` 清單](/docs/zh-TW/sub-agents#supported-frontmatter-fields)中的每個項目都無法符合可用的工具，因此 Claude Code 拒絕啟動子代理：沒有工具，它就無法行動。該訊息會按出錯原因將您的項目分組：

3106

3107* **Unrecognized**：該項目不符合任何工具名稱，通常是打字錯誤，例如 `Grpe` 而非 `Grep`。

3108* **Not available to subagents**：該項目命名了一個真實工具，但[子代理無法使用](/docs/zh-TW/sub-agents#available-tools)。背景子代理保持較小的內建工具集，因此當子代理在背景中執行時（這是預設行為），只有前景子代理才能使用的項目會出現在此處。如果您列出 `Agent`，該訊息會改為在下一個群組下報告它。

3109* **Matched no tools in this session**：該項目有效，但目前工作階段中沒有工具符合它，例如沒有連接 GitHub MCP 伺服器的 `mcp__github__*`，或位於[深度限制](/docs/zh-TW/sub-agents#let-subagents-spawn-their-own-subagents)的子代理的 `Agent`。

3110

3111省略 `tools` 欄位永遠不會觸發此拒絕。如果您將 `tools` 清單留空，或 `disallowedTools` 移除其中的每個項目，Claude Code 也會跳過拒絕並啟動沒有工具的子代理。

3112

3113在 v2.1.208 之前，子代理啟動時沒有工具，可能會傳回空的或令人困惑的結果。

3114

3115```text theme={null}

3116Agent 'code-reviewer' would be spawned with zero tools — refusing. Its tools list resolved to nothing: unrecognized [Grpe]. Fix the agent's tools frontmatter or pass a different subagent_type.

3117```

3118

3119**應該怎麼做：**

3120

3121* 根據[子代理可用的工具](/docs/zh-TW/sub-agents#available-tools)修正錯誤命名的每個項目

3122* 移除工作階段沒有的工具項目，例如來自未連接伺服器的 MCP 工具

3123* 對於[背景子代理會捨棄](/docs/zh-TW/sub-agents#available-tools)的工具（例如 `LSP`），移除該項目。若要保留工具，請[關閉 fork 模式](/docs/zh-TW/sub-agents#turn-fork-mode-on-or-off)並要求 Claude 在前景中執行子代理

3124* 刪除 `tools` 欄位而不是列出工具，以給予子代理[子代理可用的每個工具](/docs/zh-TW/sub-agents#available-tools)

3125* 對於只包含 `Agent` 的 `tools` 清單，提高[深度限制](/docs/zh-TW/sub-agents#let-subagents-spawn-their-own-subagents)或給予代理至少一個其他工具：Claude Code 在該限制處保留 `Agent`，因此只有其他內容的清單會解析為沒有工具

3126

3127<h3 id="file-is-covered-by-a-read-deny-rule">

3128 File is covered by a Read deny rule

3129</h3>

3130

3131Edit 或 Write 工具在由 [`Read` 拒絕規則](/docs/zh-TW/permissions#read-and-edit)符合的路徑上被呼叫，包括在該路徑建立新檔案。兩個工具都會變更 Claude 必須能夠讀回的內容，因此 Claude Code 在任何檔案存取之前拒絕呼叫。NotebookEdit 不受 `Read` 拒絕規則涵蓋。在 v2.1.228 之前，該規則僅阻止 Edit 工具，在 v2.1.208 之前，只有 `Edit` 拒絕規則阻止編輯。

3132

3133```text theme={null}

3134File is covered by a Read deny rule in your permission settings and cannot be edited.

3135```

3136

3137當 Claude Code 拒絕 Write 工具時，訊息結尾改為 `and cannot be written`。

3138

3139**應該怎麼做：**

3140

3141* 如果 Claude 應該能夠變更檔案，請在 `/permissions` 或[設定](/docs/zh-TW/settings-reference#permission-settings)中移除或縮小 `Read` 拒絕規則

3142* 如果檔案必須保持未觸及，請保留規則並為相同路徑新增 `Edit` 拒絕規則以同時阻止 NotebookEdit 工具

3143

3144<h3 id="subagent-type-is-required">

3145 subagent\_type is required

3146</h3>

3147

3148```text theme={null}

3149subagent_type is required: the general-purpose agent is not available in this session. Available agents: ...

3150```

3151

3152Claude 呼叫了 [Agent 工具](/docs/zh-TW/tools-reference#agent-tool-behavior)但沒有 `subagent_type`，而此工作階段沒有[通用子代理](/docs/zh-TW/sub-agents#built-in-subagents)可作為備用。這在兩種設定中是這樣的情況：

3153

3154* [`CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1`](/docs/zh-TW/env-vars) 在非互動模式中設定，這會移除每個內建子代理

3155* 工作階段的主執行緒代理有一個 [`tools: Agent(...)` 允許清單](/docs/zh-TW/sub-agents#restrict-which-subagents-can-be-spawned)，其中不包括 `general-purpose`

3156

3157**應該怎麼做：**

3158

3159* 通常不需要做任何事：該訊息列出工作階段確實擁有的子代理，因此 Claude 可以使用其中一個重試

3160* 如果 Claude 持續失敗，請將 `general-purpose` 新增到 `tools: Agent(...)` 允許清單，或取消設定 `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS`

3161

3162在 v2.1.235 之前，相同的呼叫失敗並顯示 `Agent type 'general-purpose' not found`。

3163

3164<h3 id="memory-index-is-over-its-read-limit">

3165 Memory index is over its read limit

3166</h3>

3167

3168Claude 寫入了[自動記憶](/docs/zh-TW/memory#auto-memory)索引 `MEMORY.md` 並將其留在其中一個讀取限制之上：200 行或 25KB。寫入成功，但只有前 200 行或 25KB（以先到者為準）在工作階段開始時載入，因此超過限制的所有內容在每次讀取索引時都會被捨棄。在 v2.1.210 之前，超過限制的索引在下次載入時會被無聲地截斷，沒有寫入時間訊號。

3169

3170```text theme={null}

3171Error: this write left the memory index at MEMORY.md at 214 lines, over its 200-line read limit. The write succeeded, but everything past the limit is silently dropped each time the index is loaded — entries at the end are already invisible to readers. Rewrite it to under 140 lines now: keep one line per entry, move detail into topic files, and merge or drop stale entries.

3172```

3173

3174只有載入的內容才計入限制。YAML frontmatter 和區塊級 HTML 註解在索引載入前會被移除，因此它們被排除在測量之外。在 v2.1.211 之前，Claude Code 測量原始檔案，frontmatter 或註解即使在載入的內容符合時也可能觸發此錯誤。

3175

3176Claude Code 在寫入後將錯誤傳遞給 Claude，而不是在您的終端中列印為橫幅，因此您可能只在文字記錄中注意到它。

3177

3178當 Claude 的寫入使檔案接近限制但未超過時，Claude Code 會傳回更溫和的提醒以壓縮索引，而不是此錯誤。

3179

3180**應該怎麼做：**

3181

3182* 讓 Claude 重寫 `MEMORY.md`，或要求它：每個項目保留一行，將詳細資訊移到主題檔案中，並合併或捨棄過時的項目

3183* 若要自己修剪索引，請參閱[稽核和編輯您的記憶](/docs/zh-TW/memory#audit-and-edit-your-memory)

3184

3185<h3 id="pkill-pattern-matches-the-claude-code-process">

3186 pkill pattern matches the Claude Code process

3187</h3>

3188

3189Bash 工具呼叫中的 `pkill` 命令使用了一個模式（通常使用 `-f`），該模式符合 Claude Code 程序本身，因此 Claude Code 拒絕該命令而不是讓它結束工作階段。Claude Code 在執行 `pkill` 之前使用 `pgrep` 測試模式，並在其自己的程序 ID 在結果中時拒絕。檢查僅在 Linux 上執行；在 macOS 上，`pkill` 不經修改地執行。在 v2.1.214 之前，命令執行，符合的模式在轉換中途殺死了 Claude Code 工作階段。

3190

3191```text theme={null}

3192pkill: refusing to run — this pattern matches the Claude CLI process (PID 12345). Narrow the pattern, or target your own children with `pkill -P $$ ...`.

3193```

3194

3195拒絕出現在 Bash 工具結果中，而不是作為您終端中的橫幅，Claude 通常會自行調整命令。

3196

3197**應該怎麼做：**

3198

3199* 縮小模式，使其僅符合預期的程序，例如目標二進位檔的完整路徑而不是短子字串

3200* 若要停止由目前 shell 啟動的程序，請使用 `pkill -P $$` 搭配模式，這會將符合限制為 shell 自己的子程序

3201

3202<h3 id="failed-to-write-to-a-teammate-inbox">

3203 Failed to write to a teammate's inbox

3204</h3>

3205

3206Claude Code 無法將訊息寫入 `~/.claude/teams/{team-name}/inboxes/` 下的隊友信箱檔案，因此收件人沒有收到任何內容。當 Claude Code 無法建立或更新檔案時寫入失敗，例如因為磁碟已滿、目錄不可寫，或另一個代理長時間持有收件箱鎖。在 v2.1.224 之前，Claude Code 即使寫入失敗也報告訊息已傳送。

3207

3208錯誤出現在傳送代理的工具結果中，而不是作為您終端中的橫幅，其文字告訴 Claude 重試：

3209

3210```text theme={null}

3211Failed to write to researcher's inbox — nothing was sent. Try again, or message the lead.

3212```

3213

3214結構化[代理團隊](/docs/zh-TW/agent-teams)協議訊息以相同方式失敗，錯誤命名未傳遞的訊息：當 Claude Code 無法寫入計畫核准、計畫拒絕、關閉要求或關閉拒絕時，錯誤讀作 `Failed to write the <message> to <name>'s inbox — nothing was sent`。該清單中的 `plan approval` 是領導者核准隊友計畫的決定；隊友的計畫提交是單獨的 `plan approval request` 訊息。該訊息和另外兩個協議訊息帶有自己的訊息文字和後果：

3215

3216* `Failed to write the plan approval request to the lead's inbox — plan not submitted; try again`：隊友的計畫從未到達領導者，隊友保持在計畫模式中，直到重新提交成功

3217* `The permission request could not be delivered to the team lead (mailbox write failed)`：隊友的權限要求從未到達領導者，因此沒有人核准工具呼叫

3218* `The confirmation could not be written to team-lead's inbox.`：關閉核准本身生效，隊友退出；只有對領導者的確認遺失

3219

3220當您自己訊息隊友時，在領導者工作階段中輸入 `@name` 後跟訊息，相同的失敗顯示為通知 `Couldn't write to @name's inbox — message not sent. Try again.`，Claude Code 將您的文字保留在提示框中，以便您可以再次傳送。

3221

3222**應該怎麼做：**

3223

3224* 要求傳送者重新傳送訊息；收件箱鎖的爭用是暫時的，在重試時清除

3225* 檢查可用磁碟空間，並檢查 `~/.claude/teams` 及其下的檔案是否可由您的使用者寫入

3226

3227<h3 id="message-too-large-for-cross-session-delivery">

3228 Message too large for cross-session delivery

3229</h3>

3230

3231Claude 的[跨工作階段訊息](/docs/zh-TW/cross-session-messaging)到此機器上您的另一個工作階段太長而無法傳送。Claude Code 拒絕了它，接收工作階段沒有收到任何內容。拒絕出現在傳送工作階段的工具結果中，而不是作為您終端中的橫幅。它命名了兩個大小以及如何使訊息符合：

3232

3233```text wrap theme={null}

3234Failed to send to api-worker: Message too large for cross-session delivery: the serialized message is 1,203,844 characters and the limit is 1,048,576. Shorten the message text — put bulk content in a file the recipient can read rather than in the message — or split it into smaller messages.

3235```

3236

3237重新傳送相同的文字以相同方式失敗。

3238

3239**應該怎麼做：**

3240

3241* 要求 Claude 總結訊息，或將大量內容放在收件人可以讀取的檔案中並傳送檔案的路徑

3242* 要求 Claude 將內容分割成幾個較短的訊息

3243

3244在 v2.1.235 之前，Claude Code 報告超大訊息已傳送。接收工作階段未讀就捨棄了它。

3245

3246<h3 id="too-many-messages-to-this-session-just-now">

3247 Too many messages to this session just now

3248</h3>

3249

3250Claude 向此機器上您的一個工作階段傳送了快速的[跨工作階段訊息](/docs/zh-TW/cross-session-messaging)爆發，爆發達到該工作階段的收件箱接受的內容。Claude Code 拒絕了下一個傳送，接收工作階段沒有收到任何內容。拒絕出現在傳送工作階段的工具結果中，而不是作為您終端中的橫幅：

3251

3252```text wrap theme={null}

3253Failed to send to api-worker: Too many messages to this session just now: 30 were sent recently and more would be dropped by its rate limit, so this one was not sent. Batch what remains into one message, or wait a little before sending more.

3254```

3255

3256**應該怎麼做：**

3257

3258* 通常不需要做任何事：Claude 將剩餘內容批次處理為一個訊息，或在傳送更多內容之前等待

3259* 如果您自己提示了爆發，請要求 Claude 將剩餘內容合併為單一訊息

3260

3261在 v2.1.236 之前，Claude Code 報告這些傳送已傳送。接收工作階段未讀就捨棄了它們。

3262

3263<h3 id="refusing-to-send-a-cross-session-message">

3264 Refusing to send a cross-session message

3265</h3>

3266

3267在 Claude Code 將[跨工作階段訊息](/docs/zh-TW/cross-session-messaging)寫入此機器上您的另一個工作階段之前，它會檢查目標工作階段的收件箱通訊端是否是訊息定址到的端點。當檢查失敗時，Claude Code 在傳送工作階段中拒絕傳送，目標工作階段沒有收到任何內容。對於 Claude 傳送的訊息，拒絕出現在傳送工作階段的工具結果中：

3268

3269```text theme={null}

3270Failed to send to api-worker: Refusing to send: reply target is a symlink

3271```

3272

3273`Refusing to send:` 之後的文字命名失敗的檢查：

3274

3275* `reply target is a symlink`：符號連結位於目標工作階段的通訊端路徑。Claude Code 不會透過它傳遞，因為那裡的連結可能會將訊息重新導向到目標工作階段未建立的端點。

3276* `cannot vet reply target`：Claude Code 無法檢查目標路徑，例如因為讀取失敗並出現權限錯誤。

3277* `connected endpoint is not the expected process`：持有通訊端的程序不是訊息定址到的工作階段，因此位址已過時或另一個程序取代了通訊端。

3278* `connected endpoint identity could not be read`：Claude Code 已連接但無法讀取哪個程序持有另一端，因此無法確認目標。這可能是暫時的。

3279* `connected endpoint is not owned by this user`：持有通訊端的程序以不同的使用者帳戶執行，因此它不是您的工作階段之一。

3280* `connected endpoint owner could not be read`：Claude Code 已連接但無法讀取哪個使用者帳戶擁有另一端，因此無法確認端點是您的。

3281* `connected endpoint is a different process with the expected pid`：程序 ID 符合訊息定址到的 ID，但 Claude Code 無法確認它是相同的程序。通常該工作階段已退出，作業系統重新使用了其程序 ID，因此位址已過時。

3282

3283**應該怎麼做：**

3284

3285* 通常不需要做任何事：檢查會防止訊息到達定址到的工作階段以外的端點，沒有傳送任何內容

3286* 要求 Claude 再次列出您的工作階段並重新傳送；由過時位址引起的拒絕在 Claude 傳送到目前的工作階段後清除

3287* 如果 `reply target is a symlink` 對一個工作階段重複，請檢查在該工作階段的通訊端路徑建立連結的內容，顯示在其 `/status` 下的 `Peer address`

3288* 對於 `connected endpoint identity could not be read`，重新傳送；該條件可能是暫時的

3289* 如果 `connected endpoint is not owned by this user` 出現在共用機器上，該位址的工作階段在另一個使用者帳戶下執行，因此 Claude 無法從您的帳戶訊息它

3290

3291在 v2.1.248 之前，Claude Code 沒有檢查端點的擁有使用者或程序啟動時間，因此命名這些檢查的拒絕不會出現在較早的版本上。

3292

3293<h3 id="refusing-after-a-symlink-changed">

3294 Refusing to read, write, or search a path

3295</h3>

3296

3297Claude Code 檢查檔案路徑的[權限規則](/docs/zh-TW/permissions#read-and-edit)，然後在工具開啟檔案或啟動搜尋時再次確認該解析。當它無法確認路徑仍然導向檢查核准的位置時，Claude Code 拒絕操作而不是跟隨它。拒絕出現在工具結果中：

3298

3299```text theme={null}

3300Refusing to read /path/to/file: its symlink resolution changed after permission was checked. If a link in the working directory is being rewritten concurrently, stop that and retry.

3301```

3302

3303路徑之後的文字命名原因：

3304

3305* `its symlink resolution changed after permission was checked`：路徑中的符號連結，或在 Grep 或 Glob 搜尋根目錄，在權限檢查和操作之間被取代

3306* `its parent-directory symlink resolution changed after permission was checked`：寫入路徑通過的目錄不再解析到核准的位置

3307* `it is a symbolic link. Write to the link's target path instead`：符號連結位於核准的寫入位置本身

3308* `a path one of its Read deny rules is written through changed while the search was being prepared. Retry.`：`Read` 拒絕規則的搜尋命名通過符號連結的路徑，該連結在 Claude Code 準備搜尋時變更

3309* `it could not be opened (EACCES) — it is unreadable, or is being replaced concurrently.`：搜尋根目錄存在但無法開啟；括號中的代碼是作業系統錯誤

3310* `its permission check expired before it ran (too many concurrent file operations). Retry.`：Claude Code 在許多同時檔案操作下驅逐核准記錄，然後工具使用它；重試執行新的權限檢查

3311* `ripgrep was found only by name on PATH, and a search outside the working directory cannot apply your Read deny rules in that configuration`：Claude Code 無法將 `rg` 二進位檔解析為絕對路徑，因此它拒絕在工作目錄外的搜尋，而不是執行您的拒絕規則不涵蓋的搜尋

3312

3313**應該怎麼做：**

3314

3315* 通常不需要做任何事：拒絕作為工具結果到達 Claude，被拒絕的操作不執行

3316* 如果符號連結拒絕在一個路徑上重複，請找到持續重寫那裡的連結的內容，例如建置工具或檔案監視程式，或要求 Claude 使用檔案的已解析路徑而不是連結的路徑

3317* 如果此拒絕在 Claude Code 在 Windows 內的 AppContainer 或受限制權杖沙箱中執行時出現在每個檔案上，請升級到 v2.1.265 或更新版本

3318* 對於 ripgrep 拒絕，使用您的套件管理員安裝 ripgrep，以便 `rg` 在 `PATH` 上解析為絕對路徑，或將搜尋保留在工作目錄下

3319

3320在 v2.1.251 之前，Claude Code 僅對檔案寫入重新檢查路徑的解析，因此在權限檢查後取代的連結可能會將讀取或搜尋重新導向到不同位置，而沒有訊息。在這些拒絕中，只有父目錄寫入拒絕出現在較早的版本上。

3321

3322<h3 id="task-output-swap-refused">

3323 Task output swap refused

3324</h3>

3325

3326Claude Code 將每個 Bash 命令的輸出儲存到其臨時目錄下的檔案。每次它開啟其中一個檔案時，它都會檢查路徑是否仍然導向它建立的檔案，沒有符號連結、額外硬連結或移動的目錄重新導向它。此訊息表示該檢查失敗，因此 Claude Code 拒絕操作而不是透過該路徑寫入或讀取輸出。訊息出現在 Bash 工具結果中：

3327

3328```text wrap theme={null}

3329task output swap refused (tasks dir moved or linked): /private/tmp/claude-501/-Users-you-my-project/1f0e62dc-4b0a-4f5e-9c2d-8a7b6c5d4e3f/tasks/b7k2f9m3q.output. To recover: restart Claude Code with CLAUDE_CODE_TMPDIR set to a fresh directory; or, if /private/tmp/claude-501/-Users-you-my-project is a stray directory or a symbolic link that should not be there, remove that entry itself (not what it points to) and restart.

3330```

3331

3332括號中的文字命名失敗的檢查。`output symlink was re-pointed`、`output file identity changed` 和 `not a regular file` 等原因都報告相同的條件：輸出路徑上或沿著的某些內容不再是 Claude Code 建立的檔案。只有某些原因帶有 `To recover:` 句子。

3333

3334如果檢查在命令仍在執行時失敗，Claude Code 會停止命令，其結果報告：

3335

3336```text theme={null}

3337Command killed: its output file was replaced or could no longer be verified

3338```

3339

3340**應該怎麼做：**

3341

3342* 升級到 v2.1.260 或更新版本。較早的版本有時在沒有連結或移動目錄存在時顯示此訊息

3343* 使用 [`CLAUDE_CODE_TMPDIR`](/docs/zh-TW/env-vars) 設定為新目錄重新啟動 Claude Code

3344* 或檢查 Claude Code 臨時目錄下的專案目錄，範例訊息中的 `/private/tmp/claude-501/-Users-you-my-project`。如果該路徑是符號連結，或不應該存在的目錄，請移除連結或目錄本身而不是連結的目標，然後重新啟動 Claude Code

3345* 如果拒絕重複，程序在工作階段執行時替換、連結或移除 Claude Code 臨時目錄下的項目。將 [`CLAUDE_CODE_TMPDIR`](/docs/zh-TW/env-vars) 設定為沒有其他內容管理的目錄並重新啟動

3346

3347<h3 id="the-source-file-is-not-valid-utf-8-text">

3348 The source file is not valid UTF-8 text

3349</h3>

3350

3351Claude 嘗試從位元組不解碼為文字的檔案發佈[成品](/docs/zh-TW/artifacts)，或其文字已包含替換字元 `U+FFFD`，因此 Claude Code 在上傳任何內容之前拒絕發佈。訊息出現在成品工具結果中並命名要修正的第一個位置：

3352

3353```text wrap theme={null}

3354file_path: the source file is not valid UTF-8 text (first invalid byte at line 12, column 40). It may be saved in another encoding or contain binary data. Rewrite it as UTF-8, then publish again. Nothing was published.

3355

3356file_path: the source file has the replacement character U+FFFD at line 12, column 40, usually left where an earlier edit or paste lost a character. Replace it with the intended text (in HTML, write an intended U+FFFD as �), then publish again. Nothing was published.

3357```

3358

3359Claude Code 將檔案解碼為 UTF-8，或當它以小端 UTF-16 位元組順序標記開頭時解碼為 UTF-16。當這樣的 UTF-16 檔案無法解碼時，第一個訊息命名 `UTF-16` 並仍然告訴您將檔案重寫為 UTF-8。當更多位置跟隨命名的位置時，訊息在位置之後新增計數，例如 `(+2 more)`。

3360

3361**應該怎麼做：**

3362

3363* 通常不需要做任何事：Claude 重寫檔案並再次發佈

3364* 如果檔案是您寫入或匯出的，請再次將其儲存為 UTF-8，並將每個 `U+FFFD` 替換為較早的編輯、貼上或轉換遺失的字元

3365* 若要在頁面上顯示有意的 `U+FFFD`，請在 HTML 中將其寫為 `�` 而不是字面字元

3366

3367在 v2.1.267 之前，Claude Code 上傳了這樣的檔案而不檢查它，伺服器改為拒絕發佈。

3368

3369<h2 id="background-session-errors">

3370 背景工作階段錯誤

3371</h2>

3372

3373[背景工作階段](/docs/zh-TW/agent-view)在沒有互動式終端的情況下執行，因此需要終端的命令在那裡的行為會有所不同。這些訊息會出現在背景工作階段的文字記錄中、附加到背景工作階段的終端中、您分派的工作階段或殼層中，或者對於下面的[worktree-guard 項目](#write-or-command-blocked-because-the-path-cannot-be-safely-resolved)，會出現在任何在 worktree 中隔離或執行 worktree 隔離子代理的工作階段中；當訊息特定於某個表面時，其項目會說明。

3374

3375<h3 id="commands-refused-in-a-background-session">

3376 在背景工作階段中拒絕的命令

3377</h3>

3378

3379開啟互動式對話框的命令在沒有終端附加到背景工作階段時無法執行。`/install-github-app`、`/mcp` 設定清單和 MCP 伺服器選單中的驗證動作會回應一則訊息，工作階段會在[代理檢視](/docs/zh-TW/agent-view)中的 **Needs input** 下出現，以便您可以找到它、附加並再次執行命令。當終端附加時，這些命令正常運作。

3380

3381在 v2.1.216 之前，工作階段在其中一個拒絕後不會在 **Needs input** 下出現。在 v2.1.213 到 v2.1.215 中，命令在附加終端時仍然有效，拒絕訊息告訴您附加並再次執行命令。從 v2.1.208 到 v2.1.212，Claude Code 即使在附加終端時也拒絕它們，訊息如 `Can't open MCP settings in a background session`；在這些版本上，改為從常規 `claude` 工作階段執行命令，或升級。在 v2.1.208 之前，它們在背景工作階段內開啟其對話框。在 v2.1.208 中，Claude Code 也拒絕了背景工作階段中的 `/model` 選擇器，`/upgrade` 列印升級 URL 而不是開啟瀏覽器。

3382

3383措辭會命名該命令。`/mcp` 設定清單報告：

3384

3385```text theme={null}

3386Can't open MCP settings while no terminal is attached to this background session. This session now shows "needs input" in agent view — open it and run /mcp to manage servers, or use `/mcp enable|disable|reconnect <server>` to steer without the panel.

3387```

3388

3389**該怎麼做：**

3390

3391* 從代理檢視附加到工作階段，其中它列在 **Needs input** 下，並再次執行命令

3392* 或使用訊息命名的形式，例如 `/mcp reconnect <server>`、`/mcp enable` 或 `/mcp disable`，這些在不附加的情況下有效

3393

3394<h3 id="write-or-command-blocked-because-the-path-cannot-be-safely-resolved">

3395 寫入或命令被阻止，因為路徑無法安全解析

3396</h3>

3397

3398Claude 透過 [worktree 隔離防護](/docs/zh-TW/agent-view#how-file-edits-are-isolated)無法解析為一個可驗證位置的拼寫來定址檔案或工作目錄。防護檢查[任何在 worktree 中隔離的工作階段](/docs/zh-TW/worktrees#how-claude-code-enforces-isolation)中的寫入和命令工作目錄，互動式或背景，以及[worktree 隔離子代理](/docs/zh-TW/worktrees#isolate-subagents-with-worktrees)中的寫入和命令工作目錄。它在檢查操作不會到達共享簽出之前解析符號連結，當解析失敗時，它會阻止操作而不是讓它落在那裡。訊息命名它拒絕的路徑形式以及如何重試：

3399

3400```text theme={null}

3401This write was blocked because the path is spelled in a form that cannot be safely resolved (for example through a symlink storing a raw dot segment, a network-share or device-namespace shape, or an unreadable ancestor directory). If the file is inside the worktree /path/to/worktree, address it by its direct symlink-free path instead.

3402```

3403

3404被阻止的命令報告其工作目錄的相同原因，並以 `re-run the command from its direct symlink-free path` 結尾。在 v2.1.217 之前，防護比較路徑拼寫而不解析符號連結，因此這些拼寫未被阻止，透過符號連結路由的寫入可能會落在共享簽出中。

3405

3406**該怎麼做：**

3407

3408* 通常什麼都不做：完整訊息作為工具錯誤傳遞給 Claude，Claude 使用它命名的直接路徑重試。對於被阻止的檔案編輯，對話檢視只顯示簡短的 `Error editing file` 行；完整訊息出現在文字記錄檢視中，您可以使用 `Ctrl+O` 開啟。被阻止的命令在其命令輸出中列印它。

3409* 如果同一檔案上的阻止重複，路徑可能透過已提交的符號連結執行，其目標包含 `..`，例如 `docs/current -> ../README.md`；要求 Claude 透過其真實路徑編輯目標檔案，而不是透過連結

3410

3411<h3 id="write-or-command-blocked-because-the-path-names-a-network-location">

3412 寫入或命令被阻止，因為路徑命名網路位置

3413</h3>

3414

3415Claude 透過命名不在您機器上的磁碟機、UNC 共享（例如 `\\server\share\file`）或 `/net` 自動掛載路徑的路徑來定址檔案或工作目錄，而工作階段的簽出在本機磁碟上。相同的 [worktree 隔離防護](#write-or-command-blocked-because-the-path-cannot-be-safely-resolved)無法驗證這樣的路徑保持在共享簽出之外，因此它會阻止操作。在 worktree 中隔離工作階段不會解除阻止。訊息命名要改用的路徑形式：

3416

3417```text theme={null}

3418This write was blocked because the path is network-shaped (a UNC share or /net automount spelling) while this session's checkout is local. Isolating cannot unblock it. If the file is genuinely inside the worktree /path/to/worktree, address it by its local, plainly-spelled path instead.

3419```

3420

3421被阻止的命令報告其工作目錄的相同原因，並以 `re-run the command from its local, plainly-spelled path` 結尾。在 v2.1.217 之前，防護只比較路徑文字，因此透過 UNC 或 `/net` 路徑定址簽出內的檔案未被阻止。

3422

3423**該怎麼做：**

3424

3425* 通常什麼都不做：Claude 使用訊息要求的本機拼寫重試

3426* 如果檔案在網路共享上而不是用網路路徑拼寫的本機檔案，它在工作階段的本機工作區之外；改為從常規互動式工作階段編輯它

3427

3428<h3 id="this-session-has-no-saved-transcript">

3429 此工作階段沒有已儲存的文字記錄

3430</h3>

3431

3432您附加到已停止的[背景工作階段](/docs/zh-TW/agent-view)，該工作階段使用 `←` 或 `/background` 從另一個對話背景化，並在其第一個回應完成之前停止。在該第一個回應完成之前，對話仍然只存在於背景化它的工作階段中，因此 `claude attach` 拒絕啟動已停止的工作階段，而不是在相同工作階段 ID 下開始空白對話。訊息以此工作階段的 `claude respawn` 命令結尾：

3433

3434```text theme={null}

3435This session has no saved transcript — it was stopped before its first response finished. If it was backgrounded from another conversation, that one is still intact; `claude respawn <id>` starts this one fresh.

3436```

3437

3438在[代理檢視](/docs/zh-TW/agent-view)中開啟相同工作階段的列在清單下方顯示 `Press enter again to restart this session fresh`，列上的第二個 `Enter` 使用空白對話重新啟動工作階段。在 v2.1.212 之前，開啟列顯示拒絕訊息，無法從代理檢視重新啟動。在 v2.1.211 之前，開啟已停止的工作階段無聲地啟動該空白對話，並可以重新執行工作階段的原始提示。

3439

3440**該怎麼做：**

3441

3442* 您背景化的對話完整無缺：使用 [`claude --resume`](/docs/zh-TW/sessions) 繼續它或繼續在其中工作

3443* 要無論如何啟動已停止的工作階段，請使用訊息中的 ID 執行 `claude respawn <id>`，或在代理檢視中的其列上按 `Enter` 兩次

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

3445

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

3447 此工作階段在另一個終端中執行

3448</h3>

3449

3450您在[代理檢視](/docs/zh-TW/agent-view)中開啟了已停止工作階段的列，其已儲存的對話已在此機器上的另一個即時 Claude Code 程序中開啟，因此 Claude Code 拒絕啟動將寫入相同文字記錄的第二個程序。您看到的訊息取決於[什麼保持對話](/docs/zh-TW/agent-view#opening-a-session-says-the-conversation-is-already-open)：

3451

3452```text theme={null}

3453Can't open — this session is running in another terminal

3454This conversation is already open in another running Claude session — use that one, or close it and try again

3455```

3456

3457* **`running in another terminal`**：終端保持對話，例如您使用 `claude --resume` 或 `/resume` 繼續它的終端。列也顯示 `Open in a terminal`。

3458* **`already open in another running Claude session`**：另一個非互動式 Claude Code 程序保持它，例如相同對話的[背景工作階段](/docs/zh-TW/agent-view#the-supervisor-process)程序，尚未退出。

3459

3460Claude Code 儲存您在開啟列時輸入的回覆，並在工作階段下次啟動時將其作為工作階段的下一個提示傳送。

3461

3462**該怎麼做：**

3463

3464* 在保持它開啟的程序中繼續對話，或退出該程序並再次開啟列

3465

3466在 v2.1.248 之前，只有 `already open in another running Claude session` 拒絕存在：在終端中繼續的對話不計為開啟，開啟列啟動寫入相同對話的第二個 Claude Code 程序。

3467

3468<h3 id="this-sessions-saved-conversation-is-no-longer-on-disk">

3469 此工作階段的已儲存對話不再在磁碟上

3470</h3>

3471

3472您開啟了在背景服務關閉時結束的[背景工作階段](/docs/zh-TW/agent-view)，[文字記錄清理](/docs/zh-TW/settings-reference#cleanupperioddays)已移除其已儲存的對話，例如在機器關閉數週後。通常開啟這樣的列會[繼續其已儲存的對話](/docs/zh-TW/agent-view#sessions-show-as-failed-after-shutdown)。沒有什麼可繼續，Claude Code 拒絕而不是在不詢問的情況下重新執行工作階段的原始提示：

3473

3474```text theme={null}

3475This session's saved conversation is no longer on disk (it ended while the background service was off, and old transcripts are cleaned up), so there is nothing to resume. `claude rm 7c5dcf5d` deletes the row; `claude respawn 7c5dcf5d` runs its original prompt again instead.

3476```

3477

3478`claude attach <id>` 列印此文字。在代理檢視中，頁腳較短，以 `ctrl+x deletes the row` 結尾。

3479

3480**該怎麼做：**

3481

3482* 執行 `claude rm <id>` 刪除列。當其中一個[保留案例](/docs/zh-TW/agent-view#what-deleting-a-session-removes)適用時，`claude rm` 保留列和 worktree，並命名原因

3483* 要再次執行工作階段的原始提示作為新對話，請執行 `claude respawn <id>`

3484

3485在 v2.1.248 之前，開啟這樣的列會重新執行工作階段的原始提示，而不是拒絕，將數週前的任務拉回前景。

3486

3487<h3 id="worktree-has-commits-that-are-not-pushed-anywhere">

3488 Worktree 有未推送到任何地方的提交

3489</h3>

3490

3491您嘗試刪除[背景工作階段](/docs/zh-TW/agent-view#what-deleting-a-session-removes)，其 worktree 保持 Claude Code 無法確認在其他地方儲存的提交。Claude Code 保留 worktree 和工作階段列，而不是銷毀提交。`claude rm` 命名分支和未推送的提交，並說明如何進行：

3492

3493```text theme={null}

3494kept 7c5dcf5d — 2 unpushed commits on claude/fix-login (a1b2c3d Fix login flow, … and 1 more)

3495 worktree: /home/you/project/.claude/worktrees/fix-login

3496 push them, or discard the worktree and its commits: claude rm 7c5dcf5d --discard-unpushed a1b2c3d000000000000000000000000000000000@0123456789abcdef0123456789abcdef

3497```

3498

3499當 Claude Code 無法總結提交時，訊息改為讀取 `worktree has commits that are not pushed anywhere`。在[代理檢視](/docs/zh-TW/agent-view)中，工作階段的列顯示 `not deleted`，原因相同。

3500

3501遠端上的提交不會阻止刪除。本機複製您的 `origin` 遠端預設分支上的提交也不會，只要該分支在您的主簽出中簽出，即儲存庫目錄本身而不是 worktree。

3502

3503**該怎麼做：**

3504

3505* 要保留提交，推送 worktree 的分支，或將其合併到在主簽出中簽出的預設分支，然後再次刪除工作階段

3506* 要捨棄提交，執行訊息列印的 `claude rm <id> --discard-unpushed` 命令，或在代理檢視中的工作階段列上再次按 `Ctrl+X` 兩次。這會移除工作階段和 worktree 以及其分支、未推送的提交和任何未提交的變更。如果 worktree 自拒絕以來獲得了提交，Claude Code 再次保留它並顯示更新的狀態

3507* 當訊息說 worktree 也由另一個已完成的工作階段記錄時，再次刪除不會捨棄它：推送提交，然後再次刪除工作階段

3508

3509在 v2.1.260 之前，訊息未命名分支或提交，再次刪除被拒絕的方式相同：刪除工作階段而不推送意味著使用 `git worktree remove --force <path>` 自己移除 worktree，然後再次執行 `claude rm <id>`。

3510

3511在 v2.1.248 之前，在主簽出中簽出的預設分支不計算：您已經合併到那裡的分支仍然觸發此拒絕，直到其提交到達遠端。

3512

3513<h3 id="terminal-host-process-died">

3514 終端主機程序已死亡

3515</h3>

3516

3517每個[背景工作階段的](/docs/zh-TW/agent-view)終端在背景服務下的主機程序中執行，該程序在服務仍保持其連線時死亡，因此無法到達工作階段。

3518

3519在 Linux 和 WSL 上，背景服務每隔幾秒檢查每個主機程序，當程序已退出但其與服務的連線從未關閉時標記工作階段失敗，並在[代理檢視](/docs/zh-TW/agent-view#read-session-state)中的其列上顯示原因：

3520

3521```text theme={null}

3522terminal host process died — press Enter to restart

3523```

3524

3525如果您在檢查執行之前開啟列，頁腳顯示 `This session's terminal host process died (the conversation is saved) — press Enter to restart it`，列變為失敗。

3526

3527從殼層，`claude attach <id>` 重新啟動已標記為死主機失敗的工作階段，否則列印原因並退出：

3528

3529```text theme={null}

3530Couldn't attach to <id> — This session's terminal host process died (the conversation is saved) — run `claude attach <id>` again to restart it on a fresh host.

3531```

3532

3533無論如何對話都會儲存。

3534

3535執行[殼層命令](/docs/zh-TW/agent-view#run-a-shell-command)的列改為顯示 `terminal host process died — its output is gone; the command was not run again`，`claude attach` 列印 `This command's terminal host process died — its output is gone and the command was not run again`。Claude Code 永遠不會為您重新執行命令。

3536

3537**該怎麼做：**

3538

3539* 在代理檢視中，在失敗的列上按 `Enter`；工作階段在新主機程序上重新啟動，對話繼續

3540* 從殼層，再次執行 `claude attach <id>`。Claude Code 列印 `Session <id>'s terminal host died — restarting it on a fresh one…` 並重新開啟工作階段

3541* 您無法以這種方式重新啟動殼層命令列；再次分派命令以重新執行它

3542

3543在 v2.1.247 之前，死主機程序可能通過背景服務執行的每個活躍性檢查，因此開啟工作階段無限期地顯示 `opening… · esc to cancel`，`claude attach <id>` 等待而不報告錯誤。

3544

3545<h3 id="session-isnt-responding">

3546 工作階段沒有回應

3547</h3>

3548

3549您開啟了[背景工作階段](/docs/zh-TW/agent-view)，背景服務接受了開啟，但約十秒內沒有輸出到達，因此 Claude Code 得出結論，中繼工作階段終端的程序無法傳遞輸出，並結束嘗試而不是等待。

3550

3551在代理檢視中，Claude Code 在頁腳中提供重新啟動：

931 3552

932```text theme={null}3553```text theme={null}

933API Error: 400 ... Extra inputs are not permitted ... context_management3554Press enter again to restart this session — it isn't responding (its conversation is saved and resumes).

934API Error: 400 ... Extra inputs are not permitted ... tools.0.custom.input_examples

935API Error: 400 ... Unexpected value(s) for the `anthropic-beta` header

936```3555```

937 3556

938Claude Code 發送測試版專用欄位，例如 `context_management`、`effort` 和工具 `input_examples`，以及啟用它們的 `anthropic-beta` 標頭。當閘道轉發主體但移除標頭時，API 會看到它不認識的欄位。3557從殼層，`claude attach <id>` 列印原因並退出：

3558

3559```text theme={null}

3560Couldn't attach to <id> — Session isn't responding — `claude stop <id>`, then `claude attach <id>` restarts it (the conversation is saved).

3561```

3562

3563Claude Code 永遠不會為您重新啟動執行[殼層命令](/docs/zh-TW/agent-view#run-a-shell-command)的列，因為重新啟動會再次執行命令。

939 3564

940**該怎麼做：**3565**該怎麼做：**

941 3566

942* 配置您的閘道以轉發 `anthropic-beta` 標頭。請參閱[功能傳遞](/docs/zh-TW/llm-gateway-protocol#feature-pass-through)以了解閘道必須轉發的內容。3567* 在代理檢視中，在相同列上再次按 `Enter`。Claude Code 停止無回應的程序並重新啟動工作階段，對話繼續。沒有第二次按下，什麼都不會停止

943* 作為備選方案，在啟動前設定 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/docs/zh-TW/env-vars)。這會停用需要測試版標頭的功能，以便請求通過無法轉發它的閘道成功。3568* 從殼層，執行 `claude stop <id>`，然後 `claude attach <id>`

3569* 對於殼層命令列，在代理檢視中按 `Ctrl+X` 或執行 `claude stop <id>` 停止它；再次分派命令以重新執行它

944 3570

945<h3 id="theres-an-issue-with-the-selected-model">3571<h3 id="session-was-stopped-while-the-respawn-was-in-flight">

946 選定的模型有問題3572 工作階段在重新生成進行中時被停止

947</h3>3573</h3>

948 3574

949配置的模型名稱未被識別，或您的帳戶缺乏對其的存取權限。從 v2.1.160 開始，尾部提示（此處以其互動形式顯示）因表面而異。3575您開啟了[背景工作階段](/docs/zh-TW/agent-view)，其程序未執行，當 Claude Code 重新啟動它時，另一個 Claude Code 程序停止了它，例如在另一個終端中的 `claude stop`。Claude Code 保持工作階段停止：

950 3576

951```text theme={null}3577```text theme={null}

952There'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.3578Session <id> was stopped while the respawn was in flight

953```3579```

954 3580

3581開啟您剛分派的工作階段，當其程序仍在啟動時，等待程序。在 v2.1.246 之前，在那一刻開啟它可能會停止它並顯示此訊息。

3582

955**該怎麼做：**3583**該怎麼做：**

956 3584

957* **互動式 CLI**：執行 `/model` 以從您帳戶可用的模型中選擇。3585* 如果您沒有停止工作階段，在代理檢視中再次開啟其列或執行 `claude respawn <id>` 重新啟動它

958* **非互動模式 (`-p`)**：使用有效的別名或 ID 傳遞 `--model`，或設定 [`ANTHROPIC_MODEL`](/docs/zh-TW/env-vars)。錯誤文字在此表面上顯示 `Run --model`。3586* 如果您自己停止了它，沒有什麼剩下要做的：工作階段保持停止

959* **Agent SDK**：錯誤文字省略提示，因為模型是以程式設計方式設定的。在 TypeScript 中設定 [`Options` 上的 `model`](/docs/zh-TW/agent-sdk/typescript#options)，或在 Python 中設定 [`ClaudeAgentOptions(model=...)`](/docs/zh-TW/agent-sdk/python#claudeagentoptions)，並處理結構化的 `model_not_found` 錯誤以呈現您自己的重試或模型選擇器。

960* 使用別名（例如 `sonnet` 或 `opus`）而不是完整的版本化 ID。別名解析為維護的預設值，因此不會過時。請參閱[模型配置](/docs/zh-TW/model-config)。

961* 如果 CLI 中一直出現錯誤的模型，則某處設定了過時的 ID。按[優先順序](/docs/zh-TW/model-config#setting-your-model)檢查：`--model` 標誌、`ANTHROPIC_MODEL` 環境變數，然後是 `.claude/settings.local.json` 中的 `model` 欄位、您專案的 `.claude/settings.json` 和 `~/.claude/settings.json`。移除過時的值，Claude Code 會回退到您的帳戶預設值。

962* Claude Code 將過期的 claude.ai 登入報告為[登入已過期](#login-expired)，而不是此錯誤。在 v2.1.206 之前，無法再刷新的過期登入在每個模型上都失敗，出現此錯誤；如果您在較舊版本上看到此情況，請執行 `/login`。

963* 對於 Google Cloud 的 Agent Platform 部署，請參閱 [Google Cloud 的 Agent Platform 故障排除](/docs/zh-TW/google-vertex-ai#troubleshooting)。

964 3587

965<h3 id="model-is-not-a-recognized-model-id">3588<h3 id="session-agent-no-longer-available">

966 模型不是公認的模型 ID3589 工作階段代理不再可用

967</h3>3590</h3>

968 3591

969您傳遞給模型切換的模型字串不是模型別名、此 Claude Code 版本知道的模型 ID，也不是以 `claude-` 開頭的 ID。常見原因是 ID 中的拼寫錯誤、顯示名稱（例如 `Sonnet 5`，其中需要 ID `claude-sonnet-5`），或只有較新 Claude Code 版本識別的別名。Claude Code 立即拒絕切換。在 v2.1.200 之前，Claude Code 會儲存字串並在下一個請求時失敗，出現[選定的模型有問題](#theres-an-issue-with-the-selected-model)。3592您繼續了執行[自訂代理](/docs/zh-TW/sub-agents#invoke-subagents-explicitly)的工作階段，使用 `--agent` 或 `agent` 設定啟動，Claude Code 未找到該名稱的代理。它首先搜索工作階段的原始目錄，當您[信任該工作區](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)時，然後搜索您繼續的目錄。工作階段仍然繼續，但使用預設工具，因此代理的工具限制不再適用：

970 3593

971```text theme={null}3594```text theme={null}

972Model "claud-sonnet-5" is not a recognized model id. Did you mean 'claude-sonnet-5'?3595This session was running agent 'code-reviewer', which is no longer available (no agent by that name in /home/you/project). Continuing with the default tools and system prompt — the agent's tool restrictions no longer apply. To restore it, re-create the agent, or resume with an explicit --agent <name>.

973```3596```

974 3597

975尾部提示命名最接近的匹配別名或模型 ID。當沒有足夠接近的內容時，它會改為讀取 `Run /model to see available models.`。3598訊息只命名 Claude Code 搜索的目錄，無論您喚醒[背景工作階段](/docs/zh-TW/agent-view)、執行 `/resume` 或 `claude --resume`，還是在[非互動模式](/docs/zh-TW/headless)中繼續，它都會出現在繼續的對話中，它也會進入 stderr。使用 `--input-format stream-json` 的工作階段不顯示它，因為 Agent SDK 在啟動後提供代理。

976 3599

977Claude Code 在請求切換時在本地產生此錯誤，在發出任何 API 請求之前。它適用於通過 [Agent SDK](/docs/zh-TW/agent-sdk/typescript) `setModel()` 方法或為您執行 Claude Code CLI 的應用程式（例如 [Desktop 應用程式](/docs/zh-TW/desktop)）設定模型的情況。3600Claude Code 不會將回退儲存到工作階段，因此警告在每次繼續時重複，直到您採取行動。內建 `claude` 代理不觸發警告，因為回退到預設工具集對它沒有變化。在 v2.1.216 之前，Claude Code 無聲地繼續作為預設代理，查詢僅涵蓋您繼續的目錄，因此專案範圍的代理在從另一個目錄繼續時丟失。

978 3601

979**該怎麼做：**3602**該怎麼做：**

980 3603

981* 執行不帶引數的 `/model` 以開啟選擇器並從您帳戶可用的模型中選擇，然後傳遞那裡顯示的別名或 ID3604* 在工作階段的專案中的 `.claude/agents/<name>.md` 或個人代理的 `~/.claude/agents/<name>.md` 重新建立代理檔案，然後再次繼續

982* 如果您使用了較新 Claude Code 版本支援的別名，請執行 `claude update`。以 `claude-` 開頭的完整 ID 即使模型比您的 Claude Code 版本更新，也會通過此檢查，因此不需要升級。3605* 或使用 `--agent <name>` 繼續，命名確實存在的代理，以改為作為該代理執行工作階段

983* v2.1.200 之前儲存的模型不會被此檢查修復。如果過時的值一直出現，請從[選定的模型有問題](#theres-an-issue-with-the-selected-model)下列出的位置移除它。3606* 如果代理是專案範圍的，您尚未信任工作階段的原始目錄，請在那裡執行 Claude Code 一次，接受信任對話，然後再次繼續

984* 檢查僅在 Anthropic API 上執行。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry、[AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws) 和 [LLM 閘道](/docs/zh-TW/llm-gateway)後面或自訂 `ANTHROPIC_BASE_URL`，您的提供者或閘道定義模型名稱，因此 Claude Code 接受任何字串並將其傳遞。

985 3607

986<h3 id="claude-opus-is-not-available-with-the-claude-pro-plan">3608<h3 id="claude_code_process_wrapper-launcher-errors">

987 Claude Opus 不適用於 Claude Pro 方案3609 CLAUDE\_CODE\_PROCESS\_WRAPPER 啟動器錯誤

988</h3>3610</h3>

989 3611

990您的有效訂閱方案不包括您選擇的模型。3612[`CLAUDE_CODE_PROCESS_WRAPPER`](/docs/zh-TW/corporate-launcher)已設定，其值無法使用，因此 Claude Code 拒絕啟動受影響的程序，而不是在沒有啟動器的情況下執行它。配置問題報告為以變數名稱開頭並說明原因的訊息，例如：

991 3613

992```text theme={null}3614```text theme={null}

993Claude Opus is not available with the Claude Pro plan · Select a different model in /model3615CLAUDE_CODE_PROCESS_WRAPPER: launcher `/opt/corp/launcher` is not an executable regular file

994```3616```

995 3617

3618啟動但在不用 Claude Code 替換自己的情況下退出的啟動器會使其啟動的工作階段失敗，工作階段在代理檢視中的列報告啟動器 `must exec, not daemonize`，後跟啟動器列印的任何內容。無法啟動或到達背景服務的工作階段因啟動器報告啟動器問題作為 `Couldn't reach the background service (...)` 內的原因。

3619

996**該怎麼做：**3620**該怎麼做：**

997 3621

998* 執行 `/model` 並選擇您的方案包括的模型3622* 將變數設定為以呼叫 `exec "$@"` 結尾的可執行檔的絕對路徑。有關完整合約，請參閱[啟動器合約](/docs/zh-TW/corporate-launcher#the-launcher-contract)

999* 如果您最近升級了方案但仍然看到此訊息，請執行 `/logout` 然後 `/login`。儲存的令牌反映您登入時的方案，因此在現有工作階段中在網路上升級不會生效，直到您重新驗證。3623* 檢查 `/status`，其在 Self-exec 項中顯示已解析的啟動命令，並在執行中的背景服務不符合時警告，或從殼層執行 `claude daemon status`

1000* 請參閱 [claude.com/pricing](https://claude.com/pricing) 以了解每個方案包括哪些模型3624* 在[設定](/docs/zh-TW/corporate-launcher#set-up-the-launcher)的 `env` 區塊中修復值後，使用 `claude daemon stop --any` 重新啟動背景服務，以便下次分派啟動包裝的服務

1001 3625

1002<h3 id="model-is-restricted-by-your-organizations-settings">3626<h3 id="eunknown-when-starting-a-background-session">

1003 模型受您組織的設定限制3627 啟動背景工作階段時 EUNKNOWN

1004</h3>3628</h3>

1005 3629

1006您的組織管理員已在 claude.ai 管理控制台中停用此模型，或它被託管設定中的 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection) 允許清單排除。當使用 `--model`、`ANTHROPIC_MODEL` 或 `model` 設定設定受限制的模型時，Claude Code 會替換為允許的模型並繼續。為受限制的模型鍵入 `/model <name>` 會被拒絕，顯示 `Run /model to choose a different model.`，工作階段保持其目前模型。3630Windows 拒絕使用沒有標準名稱的錯誤代碼啟動程式，因此失敗表現為 `EUNKNOWN`。通常的觸發器是軟體限制原則，例如群組原則或 AppLocker，阻止正在啟動的程式。當您使用 `/background` 或 `claude --bg` 啟動[背景工作階段](/docs/zh-TW/agent-view)時，錯誤出現：

1007 3631

1008```text theme={null}3632```text theme={null}

1009Model "claude-opus-4-8" is restricted by your organization's settings. Using claude-sonnet-4-6 instead.3633Couldn't reach the background service (spawn background service: EUNKNOWN: unknown error, uv_spawn) — run 'claude daemon status'

1010```3634```

1011 3635

1012Claude Code 將模型系列別名（`opus`、`sonnet`、`haiku` 或 `fable` 之一）視為對該系列的請求，而不是對其最新版本的請求。在 Anthropic API 和 [AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws) 上，受限制的系列別名解析為您的組織和 `availableModels` 允許清單允許的系列的最新版本，替換通知命名該版本。Claude Code 僅在系列的每個版本都受限制時才拒絕 `/model <alias>`。在 v2.1.205 之前，系列別名是根據其最新版本單獨替換或拒絕的，即使同一系列的較舊版本被允許。3636在某些帳戶上，訊息在 `daemon` 位置說 `background service`。

3637

3638在 npm 安裝上，在 `npm install -g @anthropic-ai/claude-code` 替換二進位檔案時出現的 `EUNKNOWN` 與[重新安裝期間的 `EACCES`](#eacces-when-starting-a-background-session) 有相同的原因，並在您在安裝完成後重試時清除。

3639

3640Claude Code 透過 PowerShell 啟動背景服務，以便服務在關閉終端時存活，在安裝時使用 PowerShell 7，否則使用 Windows PowerShell 5.1。當兩個 PowerShell 都無法執行時，Claude Code 改為直接啟動服務，因此只阻止 PowerShell 的原則不會導致此錯誤。如果您在沒有 npm 安裝執行時看到它，原則會阻止 Claude Code 可執行檔本身。

3641

3642在 v2.1.212 之前，Claude Code 僅使用 Windows PowerShell 5.1 啟動服務，因此任何群組原則阻止 PowerShell 5.1 的機器失敗，訊息為 `Couldn't start the session — EUNKNOWN: unknown error, uv_spawn`，即使安裝了 PowerShell 7。

1013 3643

1014**該怎麼做：**3644**該怎麼做：**

1015 3645

1016* 執行 `/model` 以從您的組織允許的模型中選擇。受限制的模型在選擇器中隱藏。3646* 如果訊息讀取 `Couldn't start the session`，升級到 v2.1.212 或更新版本。在較早的版本上，您也可以在單獨的終端中首先執行 `claude daemon run`，然後再次啟動背景工作階段。該命令在終端的前景中執行背景服務，因此服務僅在該終端保持開啟時持續。

1017* 如果受限制的模型是在 `--model`、`ANTHROPIC_MODEL` 或設定檔案的 `model` 欄位中設定的，請移除或更新該值，以便通知不會在每次啟動時重複出現3647* 如果 npm 安裝正在替換二進位檔案，等待它完成，然後再次啟動背景工作階段

1018* 如果您需要存取受限制的模型，請要求您的組織管理員啟用它。請參閱[組織模型限制](/docs/zh-TW/model-config#organization-model-restrictions)。3648* 如果錯誤在 v2.1.212 或更新版本上出現，沒有 npm 安裝執行，請要求您的 Windows 管理員在限制原則中允許 Claude Code 可執行檔

3649* 如果關閉終端時背景服務停止，Claude Code 在沒有 PowerShell 的情況下啟動它。安裝 PowerShell 7，或要求您的管理員解除阻止 PowerShell，以便服務可以超越終端。

1019 3650

1020<h3 id="thinking-type-enabled-is-not-supported-for-this-model">3651<h3 id="eacces-when-starting-a-background-session">

1021 此模型不支援 thinking.type.enabled3652 啟動背景工作階段時 EACCES

1022</h3>3653</h3>

1023 3654

1024您的 Claude Code 版本比 Sonnet 5、Opus 4.8 或 Opus 4.7 的最低版本更舊。CLI 發送了模型不再接受的思考配置。3655Claude Code 無法執行其自己的二進位檔案來啟動[背景服務](/docs/zh-TW/agent-view#the-supervisor-process)，該服務託管背景工作階段。在 npm 安裝上，這通常意味著 `npm install -g @anthropic-ai/claude-code` 在那一刻替換二進位檔案，無論您執行它還是[自動更新程式](/docs/zh-TW/setup#auto-updates)執行。當您從[代理檢視](/docs/zh-TW/agent-view)開啟工作階段時，錯誤出現：

1025 3656

1026```text theme={null}3657```text theme={null}

1027API Error: 400 ... "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.3658Couldn't start the background service — spawn background service: EACCES: permission denied, posix_spawn '/usr/local/lib/node_modules/@anthropic-ai/claude-code/bin/claude'

3659```

3660

3661當您使用 `/background` 或 `claude --bg` 啟動工作階段時，相同的原因出現在 `Couldn't reach the background service (...)` 內。在相同重新安裝視窗期間，錯誤可能命名另一個代碼，例如 `ENOENT` 或 `ENOEXEC`，或 Windows 上的 `EUNKNOWN` 或 `EPERM`；跨重試持續的 `EUNKNOWN` 有[不同的原因](#eunknown-when-starting-a-background-session)。

3662

3663在 npm 安裝上，Claude Code 等待重新安裝完成並自動重試：最多十秒，以及在 npm 安裝 Claude Code 在機器上明顯仍在執行時最多兩分鐘，涵蓋另一個 Claude Code 程序下載更新。當安裝超過該等待時，失敗命名更新而不是裸錯誤代碼：

3664

3665```text theme={null}

3666Claude Code is being updated by npm on this machine (still not runnable after 2 min, EACCES) — try again when the update finishes

1028```3667```

1029 3668

3669在 v2.1.257 之前，等待在每種情況下停止在十秒，因此此錯誤在另一個 Claude Code 程序仍在下載更新時出現。在 v2.1.246 之前，Claude Code 立即失敗，沒有等待。

3670

1030**該怎麼做：**3671**該怎麼做：**

1031 3672

1032* 執行 `claude update` 並重新啟動 Claude Code。Opus 4.7 需要 v2.1.111 或更新版本。Opus 4.8 需要 v2.1.154 或更新版本。Sonnet 5 需要 v2.1.197 或更新版本3673* 等待幾秒，然後開啟工作階段或再次分派。當訊息說 Claude Code 正在更新時，在更新完成後重試。

1033* 如果您無法升級，請執行 `/model` 並改為選擇 Opus 4.6 或 Sonnet 4.63674* 如果錯誤在沒有 npm 安裝執行時持續，您的使用者無法執行已安裝的二進位檔案。檢查其權限及其目錄的，或重新安裝 Claude Code。

1034* 如果您在 [Agent SDK](/docs/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 或更新版本

1035 3675

1036<h3 id="thinking-budget-exceeds-output-limit">3676<h3 id="background-service-exited-before-it-became-reachable">

1037 思考預算超過輸出限制3677 背景服務在變得可到達之前退出

1038</h3>3678</h3>

1039 3679

1040配置的擴展思考預算超過最大回應長度，因此沒有空間留給實際答案。3680Claude Code 啟動為[背景服務](/docs/zh-TW/agent-view#the-supervisor-process)的程序在變得可到達之前退出，因此 Claude Code 無法開啟您的工作階段。當服務在退出前列印錯誤時，括號中的原因給出退出代碼或訊號以及服務列印的第一行，其命名停止它的內容：

1041 3681

1042```text theme={null}3682```text theme={null}

1043API Error: 400 ... max_tokens must be greater than thinking.budget_tokens3683Couldn't reach the background service (background service exited before it became reachable (exit code N): <the service's first error line>) — run 'claude daemon status'

1044```3684```

1045 3685

1046Claude Code 在 Anthropic API 上自動調整這些值。當 [`MAX_THINKING_TOKENS`](/docs/zh-TW/env-vars) 設定高於提供者的輸出限制時，或當計畫模式提高思考預算時，您通常會在 Amazon Bedrock 或 Google Cloud 的 Agent Platform 上看到此錯誤。3686當您從[代理檢視](/docs/zh-TW/agent-view)開啟工作階段時，相同的原因跟隨 `Couldn't start the background service —`。當服務在退出前未列印任何內容時，訊息改為說 `nothing on stderr`。

3687

3688Claude Code 使用服務的錯誤行報告失敗。在 v2.1.246 之前，失敗僅在 45 秒等待後表現，為 `background service did not become reachable within 45s`，沒有服務的錯誤行。

3689

3690兩個引用的原因有已知的原因：

3691

3692* `Error: claude native binary not installed.`：npm 安裝在那一刻替換 Claude Code 二進位檔案，因此服務執行 npm 的佔位符。在安裝完成後重試；如果沒有安裝執行時行持續，[完成 npm 安裝](/docs/zh-TW/troubleshoot-install#native-binary-not-found-after-npm-install)。在 v2.1.257 之前，macOS npm 自我更新在安裝視窗期間在每次啟動時產生此失敗。

3693* Windows 上每次啟動時 `nothing on stderr` 和退出代碼 1：`daemon.lock` 命名 Claude Code 既無法訊號也無法證明已消失的程序，因此每個新服務得出結論另一個保持鎖定並退出。Claude Code 可以證明其寫入器已消失的鎖定會自動替換，不會產生此失敗。當失敗在每次啟動時重複時，刪除 `~/.claude/daemon.lock`，然後開啟工作階段或再次分派。在 v2.1.257 之前，這樣的鎖定阻止每次啟動，直到您刪除檔案。

1047 3694

1048**該怎麼做：**3695**該怎麼做：**

1049 3696

1050* 降低 `MAX_THINKING_TOKENS`，或將 [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/docs/zh-TW/env-vars) 提高到思考預算之上3697* 如果訊息引用一行，修復它命名的內容，然後開啟工作階段或再次分派。下次嘗試再次啟動服務

1051* 請參閱[擴展思考](/docs/zh-TW/model-config#extended-thinking)以了解預算如何與輸出長度互動3698* 執行 `claude daemon status` 檢查現在是否有服務執行

1052 3699

1053<h3 id="tool-use-or-thinking-block-mismatch">3700<h3 id="working-directory-no-longer-exists-when-starting-a-background-session">

1054 工具使用或思考區塊不匹配3701 啟動背景工作階段時工作目錄不再存在

1055</h3>3702</h3>

1056 3703

1057對話歷史以不一致的狀態到達 API，通常是在工具呼叫被中斷或回合在中途被編輯後。3704您嘗試在不再存在的目錄中啟動[背景工作階段](/docs/zh-TW/agent-view)。當您從代理檢視分派或在您工作的目錄被刪除或移動後執行 `/background` 時，會發生這種情況。當您附加到或重新啟動其程序已退出且其目錄已消失的工作階段時，也會發生這種情況，因為新程序會在相同目錄中啟動。Claude Code 不啟動工作階段，訊息命名遺漏的目錄：

1058 3705

1059```text theme={null}3706```text theme={null}

1060API Error: 400 due to tool use concurrency issues. Run /rewind to recover the conversation.3707Couldn't start a background session (working directory no longer exists or is not accessible: /tmp/demo)

1061API Error: 400 ... unexpected `tool_use_id` found in `tool_result` blocks

1062API Error: 400 ... thinking blocks ... cannot be modified

1063```3708```

1064 3709

1065所有三個變體都意味著同一件事：歷史中 `tool_use`、`tool_result` 和 `thinking` 區塊的序列不再與 API 期望的相符。3710在 v2.1.257 之前，工作階段似乎啟動，然後在代理檢視中顯示為失敗列，原因相同。

1066 3711

1067**該怎麼做：**3712**該怎麼做：**

1068 3713

1069* 如果您使用的是 Opus 4.7 或 Opus 4.8，請先執行 `claude update`。v2.1.156 之前的版本可能在正常工具使用期間觸發此錯誤，而 `/rewind` 不會清除它。3714* 重新建立訊息命名的目錄，或從存在的目錄分派，然後再試一次

1070* 執行 `/rewind` 或按 Esc 兩次，以回溯到損壞回合之前的檢查點並從那裡繼續。請參閱[檢查點](/docs/zh-TW/checkpointing)以了解如何建立和恢復檢查點。

1071 3715

1072<h3 id="usage-policy-refusal">3716<h2 id="wrapper-and-ide-errors">

1073 使用政策拒絕3717 包裝程式和 IDE 錯誤

3718</h2>

3719

3720這些錯誤來自啟動 Claude Code 的程式，例如 IDE 擴充功能或 [Agent SDK](/docs/zh-TW/agent-sdk/overview) 應用程式，而不是來自 Claude Code 本身。

3721

3722<h3 id="claude-code-process-exited-with-code-n">

3723 Claude Code 程序以代碼 N 結束

1074</h3>3724</h3>

1075 3725

1076API 拒絕回應，因為對話中的內容觸發了[使用政策](https://www.anthropic.com/legal/aup)檢查。訊息包括您可以引用給支援的請求 ID，如果您認為拒絕不正確。3726底層 `claude` 程序以非零代碼結束。結束代碼本身不會說明失敗的原因：真正的錯誤在於程序自己的輸出，包裝程式會在捕獲時附加該輸出，否則將其保留在日誌中。

1077 3727

1078```text theme={null}3728```text theme={null}

1079API 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.3729Error: Claude Code process exited with code 1

1080```3730```

1081 3731

1082檢查評估完整對話，而不僅是您的最新提示，因此在同一工作階段中發送新訊息通常會重新觸發相同的拒絕。在使用 `--continue` 或 `--resume` 退出並重新開啟工作階段後也是如此，因為磁碟上的文字記錄仍然包含觸發內容。在 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-TW/google-vertex-ai) 和 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry) 上，此訊息也涵蓋模型的安全措施標記為網路安全主題的請求。請參閱[安全措施標記了網路安全主題](#safety-measures-flagged-a-cybersecurity-topic)。

~~1083~~

1084**該怎麼做：**3732**該怎麼做：**

1085 3733

1086* 按 Esc 兩次或執行 `/rewind` 以回溯到觸發拒絕的回合之前的檢查點，然後重新表述或採取不同的方法。請參閱[檢查點](/docs/zh-TW/checkpointing)。3734* 在 VS Code 中，按照錯誤顯示的**檢視輸出日誌**連結查看底層失敗

1087* 如果您無法識別哪個回合導致了它，請執行 `/clear` 以在同一專案中開始新的對話。您之前的對話會保留在磁碟上，並在 `/resume` 中保持可用。3735* 在 Agent SDK 應用程式中，在訊息迴圈周圍捕獲錯誤。[CLI 程序結束](/docs/zh-TW/agent-sdk/troubleshooting#cli-process-exit)下的項目涵蓋了您的程式碼在每個 SDK 語言中接收的內容。

1088* 在[非互動模式](/docs/zh-TW/headless)(`-p`) 中，其中無法進行倒帶，請在沒有 `--continue` 的新工作階段中使用重新表述的提示重試。政策檢查因模型而異，因此使用 `--model` 切換到不同的模型也可能在某些情況下解決拒絕。3736* 在終端機中的同一專案中執行 `claude`。失敗通常會在那裡重現，並顯示其真實錯誤訊息，您可以在此頁面上查詢。

3737* 在終端機中執行 `claude doctor` 以檢查安裝和設定

1089 3738

1090<h3 id="safety-measures-flagged-a-cybersecurity-topic">3739<h3 id="could-not-locate-the-claude-cli-on-path">

1091 安全措施標記了網路安全主題3740 無法在 PATH 上找到 Claude CLI

1092</h3>3741</h3>

1093 3742

1094模型的安全措施將對話中的內容標記為網路安全主題。訊息命名標記請求的模型：3743當您在整合終端機中開啟 Claude Code、終端機的殼層是 PowerShell，且擴充功能無法在 PATH 上找到已安裝的 `claude` 可執行檔時，[VS Code 擴充功能](/docs/zh-TW/vs-code)會在 Windows 上顯示此錯誤。擴充功能拒絕啟動 Claude Code，直到它在 PATH 上找到已安裝的 `claude`。

1095 3744

1096```text theme={null}3745```text theme={null}

1097API 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.3746Failed to run Claude Code: Error: Could not locate the Claude CLI on PATH. Launching by name in a PowerShell terminal would run a 'claude' from the open folder instead of the installed CLI, so the launch was blocked. Make sure the Claude CLI's install directory is on your system PATH (not only your PowerShell profile), then restart VS Code and try again. VS Code reads PATH when it starts, so PATH changes take effect only after a restart.

3747```

3748

3749**該怎麼做：**

3750

3751* 在 VS Code 外開啟新的 PowerShell 視窗並執行 `where.exe claude`。如果它沒有列印路徑，CLI 不在您的 PATH 上：按照[驗證您的 PATH](/docs/zh-TW/troubleshoot-install#verify-your-path)新增其安裝目錄。如果它列印了路徑，該項目來自您的 PowerShell 設定檔或來自 VS Code 尚未取得的 PATH 變更；接下來的兩個步驟涵蓋了這些情況。

3752* 將 PATH 項目設定為使用者或系統環境變數，而不是在您的 PowerShell 設定檔中。擴充功能不執行您的設定檔，因此只存在於那裡的 PATH 編輯永遠無法到達它。

3753* 變更 PATH 後重新啟動 VS Code。擴充功能檢查 VS Code 在啟動時捕獲的 PATH，因此 PATH 變更只有在重新啟動後才會生效。

3754

3755<h2 id="rewind-warnings-and-errors">

3756 Rewind 警告和錯誤

3757</h2>

3758

3759這些訊息來自 [`/rewind`](/docs/zh-TW/checkpointing) 程式碼還原。`Restored the code, but skipped N files` 是一個警告，表示 Claude Code 跳過了某些路徑。`No files were restored` 是一個錯誤，表示它沒有還原任何內容。

3760

3761<h3 id="restored-the-code-but-skipped-files">

3762 Restored the code, but skipped files

3763</h3>

1098 3764

1099If you were not engaging in a cybersecurity topic, please send feedback via /feedback.3765`/rewind` 程式碼還原跳過了一個或多個追蹤的路徑，而不是透過它們進行寫入或刪除。Claude Code 在以下情況下會跳過路徑：

3766

3767* 它是或已成為符號連結、硬連結或其他非一般檔案

3768* 其目錄自檢查點以來已變更

3769* 其備份無法安全讀取

3770

3771跳過的路徑保留其目前的內容。在 v2.1.216 之前，`/rewind` 會透過追蹤路徑上的連結進行寫入和刪除，並且不會報告部分還原。

3772

3773```text theme={null}

3774Restored the code, but skipped 2 files: the tracked path is (or became) a link or other non-regular file, its directory changed since the checkpoint, or its backup could not be safely read. Skipped files were left untouched — run with --debug for the paths.

1100```3775```

1101 3776

1102訊息連結到[網路安全驗證計畫](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)，該計畫為合法網路安全工作授予存取權限。保護措施本身是伺服器端的，早於 v2.1.203；此版本僅更改了訊息的措辭和它連結到的頁面。3777**該怎麼做：**

3778

3779* 識別哪些檔案被跳過，以便您可以使用下面的步驟處理每個檔案。訊息只提供計數；位於 `~/.claude/debug/<session-id>.txt` 的偵錯日誌會在還原執行時列出每個跳過的路徑，因此在下次還原之前使用 `/debug` 開啟偵錯日誌。在 macOS 或 Linux 上，您可以改為直接找到連結：`find . -type l` 用於符號連結，`find . -type f -links +1` 用於硬連結檔案。

3780* 如果跳過的檔案是您有意建立的連結，例如由 dotfile 管理器管理的設定檔或由 pnpm 等工具硬連結的檔案，rewind 會保留其內容不變。若要復原工作階段對其所做的變更，請要求 Claude 反轉編輯或自行編輯檔案

3781* 如果您沒有建立連結，請在信任其內容之前檢查路徑：某些東西在檢查點之後替換了該檔案

3782

3783<h3 id="no-files-were-restored">

3784 No files were restored

3785</h3>

1103 3786

1104您看到的內容取決於您的提供者和模式：3787當您使用 [`/rewind`](/docs/zh-TW/checkpointing) 還原程式碼，且無法還原該檢查點中的任何檔案時，Claude Code 會顯示此訊息。對於每個檔案，Claude Code 在編輯前儲存的備份遺失，或 Claude Code 無法寫入或刪除該檔案。

1105 3788

1106* 在 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-TW/google-vertex-ai) 和 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry) 上，網路安全標記會產生[使用政策拒絕](#usage-policy-refusal)訊息。3789```text theme={null}

1107* [非互動模式](/docs/zh-TW/headless)省略 `/feedback` 句子。3790Failed to restore the code:

3791No files were restored: 1 file failed (backup missing, or the file could not be updated)

3792```

1108 3793

1109在 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:` 後跟豁免表單連結。3794Claude Code 在[保留掃描](/docs/zh-TW/claude-directory#cleaned-up-automatically)中刪除工作階段的備份，預設情況下約在工作階段最後一次儲存後 30 天。如果您在之後恢復工作階段，`/rewind` 仍會列出其檢查點，但還原到其中一個可能會因此錯誤而失敗。如果訊息還說 `N paths were skipped for link safety`，請參閱[Restored the code, but skipped files](#restored-the-code-but-skipped-files) 以了解這些路徑。

1110 3795

1111**該怎麼做：**3796**該怎麼做：**

1112 3797

1113* 如果您的工作需要此內容，請通過[網路安全驗證計畫](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)申請存取權限3798* 以其他方式復原變更：要求 Claude 反轉其編輯，或從版本控制還原檔案。當備份消失時，再次執行 `/rewind` 會以相同方式失敗。

1114* 如果您的請求不是關於網路安全主題，請執行 `/feedback` 以報告誤報3799* 如果 Claude Code 無法寫入或刪除檔案，請修復阻止寫入的問題，例如檔案權限，然後再次執行 `/rewind`。

1115* 若要在同一工作階段中繼續工作，請按 Esc 兩次或執行 `/rewind` 以回溯到觸發標記的回合之前的檢查點，然後採取不同的方法。請參閱[檢查點](/docs/zh-TW/checkpointing)。3800* 若要在未來的工作階段中保留備份更長時間，請提高 [`cleanupPeriodDays`](/docs/zh-TW/settings-reference#cleanupperioddays)。

1116 3801

1117<h2 id="installation-errors">3802在 v2.1.260 之前，Claude Code 會無聲地跳過備份遺失的檔案，還原似乎成功。

1118 安裝錯誤3803

3804<h2 id="session-saving-warnings">

3805 工作階段儲存警告

1119</h2>3806</h2>

1120 3807

1121這些錯誤會在安裝或更新 Claude Code 時出現，來自 [安裝指令碼](/docs/zh-TW/setup#install-claude-code)、`claude install` 或 `claude update`。如需 `command not found`、PATH、權限和設定期間的 TLS 問題，請參閱 [疑難排解安裝和登入](/docs/zh-TW/troubleshoot-install)。3808Claude Code 在輸入框下方的持續行上顯示這些警告，當它未儲存您的工作階段文字記錄時。無論哪種方式，工作階段都會繼續運作；警告告訴您工作階段稍後可能會在 [`--resume`](/docs/zh-TW/sessions) 中遺失。

1122 3809

1123<h3 id="installation-was-killed-before-it-could-finish">3810<h3 id="transcript-writes-are-failing">

1124 安裝在完成前被中止3811 文字記錄寫入失敗

1125</h3>3812</h3>

1126 3813

1127當 `claude install` 步驟被信號終止時，安裝指令碼會報告。在 Linux 上，結束代碼 137 表示程序收到 SIGKILL，在低記憶體主機上，通常是核心記憶體不足 (OOM) 殺手。指令碼會列印此說明並以代碼 137 結束：3814Claude Code 在您工作時將文字記錄儲存到磁碟，其對[文字記錄檔案](/docs/zh-TW/sessions#where-transcripts-are-stored)的寫入失敗。該訊息以基礎錯誤代碼命名原因，例如磁碟已滿：

1128 3815

1129```text theme={null}3816```text theme={null}

1130Installation was killed before it could finish (exit code 137). This usually means the system ran out of memory.3817Transcript writes are failing (disk full — ENOSPC) · recent messages may not be saved for resume

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

1132```3818```

1133 3819

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

3821

3822* 在不會自行清除的條件首次失敗時：磁碟已滿、超過磁碟配額、檔案系統唯讀、路徑超過檔案系統長度限制，或在 macOS 和 Linux 上，權限錯誤

3823* 在至少跨越一分鐘的重複失敗後，包括 Windows 上的權限錯誤，其中防毒軟體掃描可能會導致單次寫入失敗，然後在重試時成功

3824

3825在 v2.1.217 之前，Claude Code 會在沒有警告的情況下放棄失敗的寫入，稍後 `--resume` 遺失最近訊息是第一個跡象。

1135 3826

1136**該怎麼做：**3827**該怎麼做：**

1137 3828

1138* 停止其他程序以釋放記憶體，然後重新執行安裝程式3829* 修復錯誤代碼命名的條件：為 `ENOSPC` 釋放磁碟空間；為 `EDQUOT` 提高或清除配額；為 `EACCES`、`EPERM` 或 `EROFS` 恢復文字記錄位置的寫入存取

1139* 新增交換空間或移至更大的執行個體。請參閱 [在低記憶體 Linux 伺服器上安裝被中止](/docs/zh-TW/troubleshoot-install#install-killed-on-low-memory-linux-servers) 以取得交換檔案命令。3830* 警告在下一次成功寫入時自動清除；不需要重新啟動

3831* 在警告顯示時傳送的訊息稍後恢復工作階段時可能仍會遺失

1140 3832

1141<h3 id="the-connection-dropped-while-downloading-the-update">3833<h3 id="transcript-saving-is-off-skip-prompt-history">

1142 下載更新時連線中斷3834 因為設定了 CLAUDE\_CODE\_SKIP\_PROMPT\_HISTORY 所以文字記錄儲存已關閉

1143</h3>3835</h3>

1144 3836

1145當 `claude install`、`claude update` 或 [自動更新程式](/docs/zh-TW/setup#auto-updates) 正在擷取 Claude Code 二進位檔案時，與下載伺服器的連線已關閉，且重試未能恢復。當連線中斷、傳輸停滯或下載的檔案未通過校驗和時，Claude Code 會重試下載，最多嘗試三次。已完成的 HTTP 錯誤（例如 404）不會重試，因為伺服器已經回應。在 v2.1.202 之前，單一連線中斷會立即導致下載失敗，並顯示裸錯誤 `aborted`，而不是重試。3837此工作階段啟動時設定了 [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/docs/zh-TW/env-vars)，因此 Claude Code 不會為其寫入文字記錄或提示歷史記錄：

1146 3838

1147```text theme={null}3839```text theme={null}

1148The connection dropped while downloading the update (attempt 3/3: aborted). Check your network — proxies sometimes cut off large downloads.3840Transcript saving is off — CLAUDE_CODE_SKIP_PROMPT_HISTORY is set · --resume will not find this session; if unintended, unset it and restart

1149```3841```

1150 3842

1151括號中的文字命名失敗的嘗試和基礎網路錯誤。`claude update` 在 stderr 上以 `Error: Failed to install native update` 開頭該訊息。3843該變數是針對暫時性指令碼工作階段的有意選擇退出，但它也可以透過殼層設定檔、包裝指令碼或匯出它的父程序到達工作階段。

3844

3845**該怎麼做：**

1152 3846

1153保持連線但在 10 分鐘內未完成的下載會失敗，並顯示 `Download timed out: exceeded the total deadline`。Claude Code 不會重試逾時的下載，因為連線速度太慢而無法在期限內完成，在立即重試時也不會完成。下面的步驟適用於兩個訊息。在 v2.1.205 之前，相同的 10 分鐘期限被報告為 HTTP 用戶端的通用 `timeout of 600000ms exceeded`。3847* 如果您有意設定該變數，不需要採取任何行動；該通知確認工作階段不會出現在 `--resume`、`--continue` 或向上箭頭歷史記錄中

3848* 如果您沒有，請從啟動 `claude` 的殼層或指令碼中移除該變數，然後啟動新工作階段。目前工作階段的訊息不會被追溯儲存。

1154 3849

1155通常的原因是代理或閘道在傳輸完成前關閉長傳輸。Claude Code 二進位檔案是大型下載，因此永遠不會影響正常 API 流量的代理連線限制仍然可能中斷它。3850<h3 id="transcript-saving-is-off-child-session-marker">

3851 因為繼承了 CLAUDE\_CODE\_CHILD\_SESSION 標記所以文字記錄儲存已關閉

3852</h3>

3853

3854Claude Code 在它產生的子程序中設定 [`CLAUDE_CODE_CHILD_SESSION`](/docs/zh-TW/env-vars)，並將繼承它的互動式工作階段視為巢狀：Claude Code 不會為其儲存文字記錄，因此 Claude 本身啟動的工作階段不會填滿您的 `--resume` 清單。此通知表示您目前的工作階段繼承了該標記：

3855

3856```text theme={null}

3857Transcript saving is off — inherited CLAUDE_CODE_CHILD_SESSION marker · restart with CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1 to keep future transcripts

3858```

3859

3860當您從另一個 Claude Code 工作階段內執行 `claude` 時，該通知是預期的；當標記透過長期存在的中介（例如終端機、`screen` 工作階段或 Claude Code 工作階段原本啟動的啟動器）洩漏時，它會發出誤分類的訊號。

3861

3862在 tmux 內，Claude Code 會偵測透過 tmux 伺服器全域環境到達的標記，並繼續儲存，因此該通知不會出現在該情況下。

1156 3863

1157**該怎麼做：**3864**該怎麼做：**

1158 3865

1159* 再次執行 `claude update`。在網路狀況良好的情況下，下載通常在下次執行時成功。對於逾時訊息，請從更快或限制較少的網路重新執行。3866* 如果您有意從另一個 Claude Code 工作階段內啟動此工作階段，不需要採取任何行動

1160* 如果您的網路需要代理，請在執行安裝程式或 `claude update` 之前設定 `HTTPS_PROXY`。請參閱 [檢查網路連線](/docs/zh-TW/troubleshoot-install#check-network-connectivity)。3867* 如果這是頂層工作階段，請結束並使用設定的 [`CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1`](/docs/zh-TW/env-vars) 重新啟動。儲存從重新啟動時開始套用，因此在此之前傳送的訊息不會被儲存。

1161* 如果公司代理持續關閉傳輸，請要求您的網路團隊允許從 `downloads.claude.ai` 進行完整下載。請參閱 [網路存取需求](/docs/zh-TW/network-config#network-access-requirements)。3868* 若要修復從相同終端機或啟動器的未來啟動，請從其環境中移除 `CLAUDE_CODE_CHILD_SESSION`

1162* 從您的 shell 執行 `claude doctor` 以進行安裝診斷

1163 3869

1164<h2 id="command-line-errors">3870<h2 id="configuration-warnings">

1165 命令列錯誤3871 設定警告

1166</h2>3872</h2>

1167 3873

1168這些錯誤來自 `claude` 命令列及其子命令。Claude Code 在執行您的提示或傳送任何 API 請求之前會列印這些錯誤。3874Claude Code 將大多數這些訊息寫入 stderr，而不是寫入對話中，並在啟動時寫入大多數訊息。當訊息出現在其他地方（例如在偵錯日誌中或作為對話檢視中的啟動通知）或在其他時間（例如[要求時的無法辨識模型診斷行](#unrecognized-model-id-on-a-request)）時，條目會說明這一點。

1169 3875

1170<h3 id="conflict-between-bg-and-print">3876<h3 id="fullscreen-failed-start-notice">

1171 \--bg 和 --print 之間的衝突3877 全螢幕轉譯器未完成啟動

1172</h3>3878</h3>

1173 3879

1174此訊息需要 Claude Code v2.1.198 或更新版本。您在同一個 `claude` 呼叫中結合了 `--bg` 與 `-p` 或 `--print`。`--bg` 啟動一個[背景工作階段](/docs/zh-TW/agent-view#from-your-shell)，您稍後可以使用 `claude agents` 附加到該工作階段，而 `--print` 以[非互動模式](/docs/zh-TW/headless)執行，永遠不會啟動 `claude agents` 附加到的互動工作階段。在 v2.1.198 之前，此組合會無聲地建立一個永遠無法附加的背景工作。3880此機器上的先前[全螢幕](/docs/zh-TW/fullscreen)工作階段在完成啟動前退出，因此 Claude Code 在傳統轉譯器上啟動此工作階段並列印以下其中一個通知：

1175 3881

1176```text theme={null}3882```text theme={null}

3883Claude Code 的全螢幕轉譯器上次在此機器上未完成啟動，因此此次啟動使用傳統轉譯器。它將在下次啟動時嘗試全螢幕；/tui default 保持傳統轉譯器。

3884

3885Claude Code 的全螢幕轉譯器在此機器上多次啟動失敗，因此已在此處關閉。執行 /tui fullscreen 以再次嘗試（這也會在更新後重設）。

1177```3886```

1178 3887

1179**該怎麼做：**3888**該怎麼做：**

1180 3889

1181* 移除 `-p` 或 `--print`。`--bg` 將提示作為其位置引數，所以 `claude --bg "<task>"` 是完整的命令。請參閱[從您的 shell 分派新代理](/docs/zh-TW/agent-view#from-your-shell)。3890* 遵循[全螢幕轉譯](/docs/zh-TW/fullscreen#fullscreen-renderer-didnt-finish-starting)。它說明您會收到哪個通知、Claude Code 在後續工作階段中的作用，以及如何再次嘗試全螢幕或保持傳統轉譯器。

1182* 若要以非互動模式執行提示並列印結果而不是建立背景工作階段，請移除 `--bg` 並執行 `claude -p "<task>"`3891* 如果已終止的工作階段列印了結束訊息，請參閱 [Claude Code 在無法復原的介面錯誤後退出](#exited-after-an-unrecoverable-interface-error)以了解它命名的內容。

1183 3892

1184<h3 id="the-json-schema-value-is-not-a-valid-json-schema">3893在 v2.1.236 之前，Claude Code 未列印通知，並在啟動失敗後繼續在全螢幕轉譯中啟動工作階段。

1185 \--json-schema 值不是有效的 JSON Schema3894

3895<h3 id="exited-after-an-unrecoverable-interface-error">

3896 Claude Code 在無法復原的介面錯誤後退出

1186</h3>3897</h3>

1187 3898

1188您傳遞給[`--json-schema`](/docs/zh-TW/cli-reference#cli-flags)的結構描述在[非互動模式](/docs/zh-TW/headless#get-structured-output)中未能通過 JSON Schema 編譯，所以 `claude` 以代碼 1 結束而不是執行提示。在 v2.1.205 之前，無效的結構描述會產生無結構的輸出且沒有錯誤，任何使用 `format` 關鍵字的結構描述都被視為無效。3899當 Claude Code 退出時會列印此訊息，因為其終端介面遇到無法復原的錯誤，在任一轉譯器中都是如此。第二句僅在[全螢幕](/docs/zh-TW/fullscreen)轉譯器啟動時發生錯誤時出現：

1189 3900

1190```text theme={null}3901```text theme={null}

1191Error: --json-schema is not a valid JSON Schema: data/type must be equal to one of the allowed values3902Claude Code 在無法復原的介面錯誤 (<error>) 後退出。它在全螢幕轉譯器啟動時發生，因此下次啟動將使用傳統轉譯器（CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1 隨時強制執行）。

1192```3903```

1193 3904

1194第二個冒號之後的文字是驗證器的診斷，並命名失敗的關鍵字或位置。使用 `format` 關鍵字的結構描述（例如 `"format": "email"`）是有效的：Claude Code 接受 `format` 作為註解，不強制執行它。3905**該怎麼做：**

3906

3907* 再次啟動 Claude Code。若要繼續進行對話，請在同一目錄中執行 `claude --resume`。

3908* 如果訊息命名全螢幕轉譯器，[全螢幕轉譯](/docs/zh-TW/fullscreen#fullscreen-renderer-didnt-finish-starting)會說明下次啟動的作用，這取決於您如何開啟全螢幕，以及如何再次嘗試全螢幕或保持傳統轉譯器。

3909

3910在 v2.1.236 之前，Claude Code 在此類錯誤後退出而不列印訊息。

3911

3912<h3 id="agent-descriptions-are-over-the-15000-token-limit">

3913 代理程式描述超過 15.0k 令牌限制

3914</h3>

3915

3916Claude Code 在對話檢視中顯示此警告作為啟動通知，而不是在 stderr 上。您的[子代理程式](/docs/zh-TW/sub-agents)（除了內建代理程式外）的組合描述超過 15,000 個令牌，如 Claude Code 估計的那樣。每個代理程式計算其名稱加上其 `description` frontmatter。Claude Code 無論總數是否超過限制都會載入每個代理程式，因此警告不會改變載入的內容。

1195 3917

1196Claude Code 在結構描述編譯之前執行兩項檢查：它拒絕不可解析的 JSON 值並顯示 `Error: --json-schema is not valid JSON`，以及有效但不是物件的 JSON 並顯示 `Error: --json-schema must be a JSON object`。3918```text theme={null}

3919代理程式描述超過 15.0k 令牌限制（~16.2k 令牌）· 要求 Claude 修剪 .claude/agents/ 中的代理程式描述

3920```

1197 3921

1198**該怎麼做：**3922**該怎麼做：**

1199 3923

1200* 修復診斷命名的結構描述部分，然後重新執行命令3924* 縮短您的代理程式檔案的 `description` frontmatter，或要求 Claude 為您修剪它們。

1201* 如果診斷是 `schema too large`，請減少結構描述的巢狀和 `$ref` 重複使用3925* 移除您不再使用的代理程式檔案。

1202* 請參閱[取得結構化輸出](/docs/zh-TW/headless#get-structured-output)以取得有效的結構描述和命令

1203 3926

1204<h3 id="could-not-import-a-server-from-claude-desktop">3927<h3 id="workspace-has-not-been-trusted">

1205 無法從 Claude Desktop 匯入伺服器3928 工作區尚未受信任

1206</h3>3929</h3>

1207 3930

1208Claude Code 無法新增您在 `claude mcp add-from-claude-desktop` 中選擇的其中一個伺服器。該命令仍會匯入其他選定的伺服器，並為每個無法新增的伺服器列印一行。在 v2.1.205 之前，第一個失敗的伺服器會停止匯入，且沒有選定的伺服器被新增。3931Claude Code 在專案的 `.claude/settings.json` 或 `.claude/settings.local.json` 中找到 `permissions.allow` 規則或 `permissions.additionalDirectories` 項目，但未應用它們，因為[來自專案設定的允許規則需要工作區信任](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)。計數、設定名稱和訊息中命名的檔案因您的設定而異。`deny` 和 `ask` 規則不受影響。

1209 3932

1210```text theme={null}3933```text theme={null}

1211Could not import my server: Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.3934忽略來自 .claude/settings.local.json 的 2 個 permissions.allow 項目：此工作區尚未受信任。在此處以互動方式執行 Claude Code 一次並接受信任對話，或在 /Users/you/.claude.json 中設定 projects["/Users/you/project"].hasTrustDialogAccepted: true。

1212```3935```

1213 3936

1214伺服器名稱之後的文字是原因。最常見的是名稱檢查：Claude Desktop 允許伺服器名稱中的字元（例如空格和句號），而 `claude mcp` 限制為字母、數字、連字號和底線。其他原因包括無法通過驗證的伺服器配置，以及被您組織的 [MCP 原則](/docs/zh-TW/managed-mcp)阻止的伺服器。

~~1215~~

1216**該怎麼做：**3937**該怎麼做：**

1217 3938

1218* 在 `claude_desktop_config.json` 中重新命名伺服器，僅使用字母、數字、連字號和底線，然後再次執行 `claude mcp add-from-claude-desktop`3939* 在目錄中執行 `claude` 並接受信任對話。[專案允許規則和工作區信任](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)說明該接受涵蓋哪個資料夾。

1219* 使用 `claude mcp add` 或 `claude mcp add-json` 在有效名稱下直接新增該伺服器。請參閱[從 Claude Desktop 匯入 MCP 伺服器](/docs/zh-TW/mcp#import-mcp-servers-from-claude-desktop)。3940* 在[非互動模式](/docs/zh-TW/headless)中使用 `-p` 不會顯示對話。使用訊息列印的確切 `projects` 金鑰在 `~/.claude.json` 中設定 `hasTrustDialogAccepted` 項目。

3941* 如果訊息命名 `.claude/settings.local.json` 且您在 git 儲存庫外或在主目錄中啟動 Claude Code，請更新至 v2.1.200 或更新版本。版本 2.1.196 至 2.1.199 在這些工作區中將您自己的 `.claude/settings.local.json` 視為儲存庫提供的。在 v2.1.207 及更新版本上，如果您尚未信任資料夾，在 git 儲存庫外更新還不夠：確定資料夾不在儲存庫內會執行 git，Claude Code 僅在您接受信任對話後才執行該檢查，因此請使用第一步。您的主目錄和任何其他[設定主目錄](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)豁免且不等待對話。請參閱[專案允許規則和工作區信任](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)。

1220 3942

1221<h3 id="mcp-permission-prompt-tool-not-found">3943<h3 id="working-directory-is-a-network-path">

1222 找不到 MCP 權限提示工具3944 工作目錄是網路路徑

1223</h3>3945</h3>

1224 3946

1225您傳遞給 [`--permission-prompt-tool`](/docs/zh-TW/cli-reference#cli-flags) 的工具在執行首次需要權限決定時不在連接的 MCP 工具中，原因可能是其伺服器從未連接，或者沒有連接的伺服器公開該名稱的工具。Claude Code 仍會傳送您的提示：[非互動](/docs/zh-TW/headless)執行在第一個需要批准的工具呼叫時以此錯誤和結束代碼 1 結束，因此即使請求已發出也不會產生答案。在第一個提示之前，Claude Code 會等待最多由 [`MCP_TIMEOUT`](/docs/zh-TW/env-vars) 設定的每個伺服器連接逾時 30 秒，以便該伺服器連接。在 v2.1.206 之前，啟動不會等待伺服器完成連接，所以啟動緩慢但健康的伺服器也會產生此錯誤。3947Claude Code 不會將網路路徑新增為工作目錄。查詢網路路徑可以聯絡它命名的主機，在 Windows 上該聯絡可以將您的認證傳送給主機，因此 Claude Code 拒絕該路徑而不查詢它。當您使用此類路徑執行 `/add-dir` 時，或作為啟動時的警告時，您會看到此訊息。當它在啟動時出現時，Claude Code 啟動時不包含該目錄。

1226 3948

1227```text theme={null}3949```text theme={null}

1228Error: MCP tool mcp__permissions__approve (passed via --permission-prompt-tool) not found. Available MCP tools: none3950\\server\share 是網路路徑，無法新增為工作目錄。在 Windows 上，將共用對應到磁碟機代號，並在啟動時使用 --add-dir 傳遞它（在工作階段中新增的磁碟機代號尚未帶有遠端讀取信任）。

1229```3951```

1230 3952

1231`Available MCP tools:` 之後的清單命名了在等待結束時連接的 MCP 工具。3953Claude Code 以此方式拒絕的路徑包括：

3954

3955* UNC 共用，例如 `\\server\share`

3956* 自動掛載路徑，例如 `/net/<host>`，除非您從該主機的自動掛載下的目錄啟動 Claude Code

3957* 透過符號連結或連接點到達網路位置的本機路徑

3958

3959對應的磁碟機代號和 `\\wsl$` 路徑不計為網路路徑。

1232 3960

1233**該怎麼做：**3961**該怎麼做：**

1234 3962

1235* 檢查伺服器是否啟動並保持連接：在同一目錄中執行 `claude mcp list`，並確認伺服器列為已連接3963* 在 Windows 上，將共用對應到磁碟機代號，例如使用 `net use Z: \\server\share`，並在啟動時使用 `claude --add-dir Z:\` 傳遞磁碟機。

1236* 確認工具名稱與伺服器公開的 `mcp__<server>__<tool>` 名稱相符3964* 在 macOS 或 Linux 上，在本機路徑掛載共用並改為新增該路徑。

1237* 如果伺服器需要超過 30 秒才能啟動，請提高 [`MCP_TIMEOUT`](/docs/zh-TW/env-vars)3965* 如果路徑在 `permissions.additionalDirectories` 中，請從列出它的設定檔中移除它。

1238 3966

1239<h2 id="plugin-errors">3967在 v2.1.257 之前，Claude Code 接受可到達的網路路徑作為工作目錄。

1240 外掛程式錯誤3968

1241</h2>3969<h3 id="remote-managed-settings-failed-to-load">

3970 遠端受管設定無法載入

3971</h3>

1242 3972

1243這些錯誤來自 [外掛程式](/docs/zh-TW/plugins) 和 [市集](/docs/zh-TW/plugin-marketplaces) 設定。對於不會產生此頁面上其中一則訊息的外掛程式問題，例如無法載入的市集 URL 或已安裝但未出現的外掛程式，請參閱 [外掛程式疑難排解](/docs/zh-TW/discover-plugins#troubleshooting)。3973您的工作階段符合[伺服器受管設定](/docs/zh-TW/server-managed-settings)的資格，但 Claude Code 無法擷取它們，因此在互動工作階段中顯示此警告。括號中的原因命名失敗的內容，例如 `network error`、`request timed out` 或 `authentication rejected (401)`，行的其餘部分說明工作階段執行的策略：

1244 3974

1245<h3 id="marketplace-is-registered-from-an-untrusted-source">3975* **從較早成功擷取快取的設定**：Claude Code 在該快取策略上執行工作階段，除了[隱藏的環境變數](/docs/zh-TW/server-managed-settings#fetch-and-caching-behavior)，行讀取 `using cached policy`。

1246 市集是從不受信任的來源註冊的3976* **無快取**：Claude Code 在沒有伺服器受管設定的情況下執行工作階段，行讀取 `no remote policy applied`。

3977

3978**該怎麼做：**

3979

3980* 對訊息命名的原因採取行動：對於網路原因，檢查此機器是否可以到達 `api.anthropic.com`；對於驗證原因，使用 `/status` 檢查您的登入

3981* 執行 `/status` 或 `claude doctor` 以取得完整診斷

3982

3983在 v2.1.248 之前，Claude Code 僅在偵錯日誌中報告設定擷取失敗。

3984

3985<h3 id="managed-settings-were-not-approved">

3986 受管設定未獲批准

1247</h3>3987</h3>

1248 3988

1249市集是以 [為官方 Anthropic 市集保留的名稱](/docs/zh-TW/plugin-marketplaces#marketplace-schema) 註冊的，但其註冊的來源不是 `anthropics` GitHub 儲存庫。Claude Code 每次載入或重新整理市集時都會重新檢查保留的名稱，因此市集和從中安裝的外掛程式會停止載入。在 v2.1.205 之前，只有在新增市集時才會檢查名稱，因此在名稱變成保留名稱之前註冊的項目會繼續載入。3989您的組織的[伺服器受管設定](/docs/zh-TW/server-managed-settings)包括需要您批准的設定，且您拒絕了[安全批准對話](/docs/zh-TW/server-managed-settings#security-approval-dialogs)，因此 Claude Code 退出而不應用它們：

1250 3990

1251```text theme={null}3991```text theme={null}

1252Marketplace "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.3992受管設定未獲批准；退出而不應用它們。

1253```3993```

1254 3994

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

1256 3996

1257* 執行 `claude plugin marketplace remove <name>`，然後從官方 `github.com/anthropics` 儲存庫重新新增市集3997* 再次啟動 Claude Code 並批准對話以在您的組織設定下繼續。拒絕的對話不會被記住，因此在下次啟動時會再次出現。

1258* 如果您發佈了在名稱變成保留名稱之前使用該名稱的第三方市集，請重新命名它並要求使用者從您的來源重新新增它3998* 如果您對對話列出的設定不確定，在批准前詢問維護您的組織受管設定的人

1259* 請參閱 [市集結構描述](/docs/zh-TW/plugin-marketplaces#marketplace-schema) 下的保留名稱清單

1260 3999

1261<h3 id="plugin-command-references-user-config">4000<h3 id="mcp-server-is-blocked-by-enterprise-managed-policy">

1262 外掛程式命令在 shell 命令中參考 user\_config4001 MCP 伺服器被企業受管策略阻止

1263</h3>4002</h3>

1264 4003

1265外掛程式 hook、[monitor](/docs/zh-TW/plugins-reference#monitors) 或 MCP [`headersHelper`](/docs/zh-TW/mcp#use-dynamic-headers-for-custom-authentication) 命令參考 `${user_config.KEY}` [外掛程式選項](/docs/zh-TW/plugins-reference#user-configuration)，而替換後的字串會被傳遞到 shell。設定的值包含 `$(...)` 、反引號或 `;` 會在該處作為程式碼執行，因此 Claude Code 拒絕啟動元件而不是替換該值。檢查在命令範本上執行，因此即使尚未設定任何值，錯誤也會出現。在 v2.1.207 之前，該值被替換到 shell 命令中。4004您在 `/mcp` 中選擇了伺服器上的**重新連線**，或在那裡重新開啟了已停用的伺服器，且[限制 MCP 伺服器](/docs/zh-TW/managed-mcp)的設定阻止該伺服器。Claude Code 拒絕連線它並顯示：

~~1266~~

1267措辭取決於哪個介面參考了該選項。shell 形式的 hook 會報告：

1268 4005

1269```text theme={null}4006```text theme={null}

1270Hook from plugin formatter@acme-tools references ${user_config.*} in a shell-form command. The substituted value would be re-parsed by the shell. Use exec form instead — {"command": "<executable>", "args": ["${user_config.KEY}", ...]} — or read $CLAUDE_PLUGIN_OPTION_<KEY> from the hook's environment. Command: ./scripts/notify.sh ${user_config.webhook_url}4007MCP 伺服器 <name> 被企業受管策略阻止

1271```4008```

1272 4009

1273monitor 會報告：4010以下任何設定都可能產生訊息：

4011

4012* 與伺服器相符的 [`deniedMcpServers`](/docs/zh-TW/managed-mcp#policy-based-control-with-allowlists-and-denylists) 項目，包括您自己的 `~/.claude/settings.json` 或專案的 `.claude/settings.json` 中的項目

4013* 伺服器不相符的 [`allowedMcpServers`](/docs/zh-TW/managed-mcp#policy-based-control-with-allowlists-and-denylists) 清單

4014* [`strictPluginOnlyCustomization`](/docs/zh-TW/settings-reference#strictpluginonlycustomization) 且 `mcp` 已鎖定，這會阻止在 `~/.claude.json` 和 `.mcp.json` 中設定的伺服器

4015* [`disableClaudeAiConnectors`](/docs/zh-TW/mcp#disable-claude-ai-connectors)，當伺服器是 claude.ai 連接器時

4016

4017**該怎麼做：**

4018

4019* 檢查您自己的使用者和專案設定檔案中是否有這些設定之一，並變更或移除它

4020* 如果您自己的設定都不能解釋該阻止，請詢問您的管理員哪個受管設定阻止了伺服器

4021

4022在 v2.1.257 之前，**重新連線**和在 `/mcp` 中重新啟用可以連線伺服器，該伺服器被中途工作階段策略更新阻止。

4023

4024<h3 id="managed-settings-document-could-not-be-parsed">

4025 受管設定文件無法解析

4026</h3>

4027

4028您的組織部署[受管設定](/docs/zh-TW/managed-settings)，且其中一個已部署的文件存在但無法解析為 JSON 物件，因此 Claude Code 在啟動時以代碼 1 退出，而不是執行而不使用文件帶來的策略。行在訊息前命名失敗的來源：

1274 4029

1275```text theme={null}4030```text theme={null}

1276Monitor "deploy-status" from plugin deploy-tools references ${user_config.*} in its command. The substituted value would be passed to a shell. Monitor commands cannot safely reference ${user_config.*}; have the monitor script read the value from a config file or prompt instead.4031/Library/Application Support/ClaudeCode/managed-settings.json：受管設定文件無法解析為 JSON 物件；其設定都不生效。修復或移除它。

1277```4032```

1278 4033

1279MCP `headersHelper` 會報告：4034來源是以下其中之一：

4035

4036* `managed-settings.json` 檔案的路徑或 `managed-settings.d` 下的放入檔案

4037* macOS 受管偏好設定設定檔、`per-user managed preferences` 或 `device-level managed preferences`

4038* Windows 登錄值、`Registry: HKLM\SOFTWARE\Policies\ClaudeCode\Settings`

4039

4040[尋找 Claude Code 放棄的項目](/docs/zh-TW/managed-settings#find-entries-claude-code-dropped)列出使每個來源無法解析的原因。

4041

4042Claude Code 拒絕啟動，即使另一個管理來源提供有效策略。您在互動工作階段、`claude -p`、Agent SDK 工作階段、[背景工作階段](/docs/zh-TW/agent-view)和大多數子命令（包括 `claude doctor`）中看到此錯誤。拒絕故意失敗關閉：Claude Code 無法解析的文件中的設定無法強制執行，啟動時不應用組織的控制項會執行工作階段。

4043

4044可解析文件中的架構問題不會產生此錯誤。[尋找 Claude Code 放棄的項目](/docs/zh-TW/managed-settings#find-entries-claude-code-dropped)涵蓋 Claude Code 對其所做的操作。

4045

4046當 `managed-settings.d/` 目錄存在但無法列出時，Claude Code 報告 `Managed settings drop-in directory could not be read:` 後跟基礎錯誤。[尋找 Claude Code 放棄的項目](/docs/zh-TW/managed-settings#find-entries-claude-code-dropped)涵蓋讀取失敗在啟動時退出的時間。

4047

4048**該怎麼做：**

4049

4050* 如果您管理機器，修復命名的文件使其解析為 JSON 物件，或移除檔案、設定檔或登錄值。空的 `managed-settings.json` 計為 `{}` 且不會阻止啟動。

4051* 如果您不管理，請要求您的管理員修復已部署的文件。您自己的設定檔案中沒有任何內容會導致或清除此錯誤。

4052

4053<h3 id="headershelper-not-run">

4054 headersHelper 未執行

4055</h3>

4056

4057Claude Code 僅使用其靜態 `headers` 連線了 MCP 伺服器，並跳過了伺服器的 [`headersHelper`](/docs/zh-TW/mcp#use-dynamic-headers-for-custom-authentication)，因為協助程式是 shell 命令且資料夾沒有已儲存的信任。當您手動在 `~/.claude.json` 中設定其項目時，或在主目錄外，當您在互動工作階段中為其接受信任對話時，資料夾會獲得已儲存的信任。請參閱[在 headersHelper 執行前信任資料夾](/docs/zh-TW/mcp#trust-a-folder-before-its-headershelper-runs)以了解此檢查適用於哪些伺服器。

4058

4059Claude Code 僅在[非互動模式](/docs/zh-TW/headless)中寫入此行，每個伺服器一次。在互動工作階段中，它改為將相同的拒絕寫入偵錯日誌。

1280 4060

1281```text theme={null}4061```text theme={null}

1282headersHelper for MCP server 'internal-api' references ${user_config.*}. The substituted value would be passed to a shell; read the value inside the helper script instead (e.g. from an env var set in the server's "env" block).4062MCP 伺服器 'internal-api'：headersHelper 未執行 — 此工作區沒有持久化信任；在此處以互動方式接受信任對話一次，或在 /Users/you/.claude.json 中設定 projects["/Users/you/project"].hasTrustDialogAccepted。

1283```4063```

1284 4064

4065訊息列印的 `projects` 金鑰是資料夾[專案允許規則和工作區信任](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)說明 Claude Code 信任的金鑰。為父資料夾接受信任對話不滿足檢查，`-p` 或 SDK 工作階段也不滿足。

4066

1285**該怎麼做：**4067**該怎麼做：**

1286 4068

1287* 對於 hook，新增 `args` 陣列使其以 [exec 形式](/docs/zh-TW/hooks#exec-form-and-shell-form) 執行，其中每個 `${user_config.KEY}` 變成一個引數，中間沒有 shell。或者移除參考並在指令碼內讀取 `$CLAUDE_PLUGIN_OPTION_<KEY>` 環境變數4069* 在訊息命名的資料夾中執行 `claude`，接受信任對話，然後再次執行您的 `-p` 或 SDK 命令

1288* 對於 monitor，移除參考並讓 monitor 指令碼從設定檔讀取該值4070* 在 `~/.claude.json` 中自己設定 `hasTrustDialogAccepted` 項目，使用訊息列印的確切 `projects` 金鑰

1289* 對於 `headersHelper`，將 `${user_config.KEY}` 移到伺服器的 `headers` 欄位（不會進行 shell 解析），或在 helper 指令碼內讀取該值4071* 如果您在主目錄中啟動工作階段，請從您已信任的專案目錄工作。當您在主目錄中接受信任對話時，Claude Code 僅在目前工作階段中保持該信任。

1290 4072

1291<h2 id="tool-errors">4073<h3 id="malformed-tool-content-rule">

1292 工具錯誤4074 格式不正確的 Tool(content) 規則

1293</h2>4075</h3>

1294 4076

1295這些錯誤來自 Claude 的內建工具拒絕輸入。Claude 會自動修正大多數工具錯誤；以下兩個需要您進行變更，因為它們來自您控制的子代理定義或權限規則。4077您的設定檔案中的[權限規則](/docs/zh-TW/permissions#permission-rule-syntax)沒有 `Tool` 或 `Tool(content)` 的形狀，例如因為文字跟在右括號後面或其中一個括號遺失。Claude Code 跳過規則，並在互動工作階段啟動時在無效設定對話中列出它，以及在 [`claude doctor`](/docs/zh-TW/debug-your-config#check-resolved-settings) 輸出中：

1296 4078

1297<h3 id="agent-would-be-spawned-with-zero-tools">4079```text theme={null}

1298 Agent would be spawned with zero tools4080無效權限規則 "Bash(ls) x" 已跳過：格式不正確的 Tool(content) 規則。規則採用 Tool 或 Tool(content) 的形式，必須在右括號 ")" 處結束；括號內的內容是字面意思

4081```

4082

4083**該怎麼做：**

4084

4085* 在訊息列出的設定檔中，重寫規則使其在其右括號處結束，例如用 `Bash(ls *)` 代替 `Bash(ls) x`

4086* 將括號內的內容保留原樣。它們是字面意思，因此規則如 `Edit(./Finance (2024)/*)` 無需逃逸即有效

4087

4088在 v2.1.260 之前，Claude Code 將括號不相符的規則報告為 `Mismatched parentheses`。

4089

4090<h3 id="is-not-matched-by-file-permission-checks">

4091 不符合檔案權限檢查

1299</h3>4092</h3>

1300 4093

1301[子代理的 `tools` 清單](/docs/zh-TW/sub-agents#supported-frontmatter-fields)中沒有任何內容解析為工具，因此 Claude Code 拒絕啟動子代理，而不是啟動無法執行操作的代理。該訊息按它們未解析的原因對條目進行分組：未被識別的工具、不適用於子代理的工具，或已識別但與目前工作階段中的任何工具都不匹配。省略 `tools` 欄位永遠不會觸發此拒絕。MCP 伺服器模式（例如 `mcp__github__*`）不在豁免範圍內：當該伺服器沒有連接的工具時，啟動會被拒絕，並在不匹配的群組中顯示該模式。在 v2.1.208 之前，子代理會以零個工具啟動並返回空的或令人困惑的結果。4094Claude Code 在您的[設定檔案](/docs/zh-TW/settings#where-settings-live)、[受管設定](/docs/zh-TW/managed-settings)或 `--allowedTools`、`--disallowedTools` 或 `--settings` 旗標值中找到了具有路徑的 `Write`、`NotebookEdit`、`MultiEdit` 或 `Glob`[權限規則](/docs/zh-TW/permissions#read-and-edit)。它僅針對 `Edit` 和 `Read` 規則檢查檔案權限，因此它永遠不會查詢命名其他檔案工具之一的路徑規則。它保留規則並不改變其他任何內容；警告命名規則、其在括號中的來源和要寫入的替換：

1302 4095

1303```text theme={null}4096```text theme={null}

1304Agent 'code-reviewer' would be spawned with zero tools — refusing. Its tools list resolved to nothing: unrecognized [Grpe]. Fix the agent's tools frontmatter or pass a different subagent_type.4097權限拒絕規則 (.claude/settings.json)：Write(docs/**) 不符合檔案權限檢查 — 僅 Edit(path) 規則。改用 Edit(docs/**)（Edit 規則涵蓋所有檔案編輯工具）。

1305```4098```

1306 4099

1307**應該怎麼做：**4100**該怎麼做：**

1308 4101

1309* 根據[子代理可用的工具](/docs/zh-TW/sub-agents#available-tools)更正錯誤命名的每個條目4102* 將 `Write(path)`、`NotebookEdit(path)` 和舊版 `MultiEdit(path)` 規則替換為 `Edit(path)`。`Edit` 規則涵蓋所有檔案編輯工具。

1310* 移除工作階段沒有的工具條目，例如來自未連接伺服器的 MCP 工具4103* 除了在 `--allowedTools` 中，Claude Code 接受 `Glob` 規則而不警告，將 `Glob(path)` 規則替換為 `Read(path)`。

1311* 若要讓子代理擁有父代理的所有工具，請刪除 `tools` 欄位，而不是列出工具4104* 在警告在括號中命名的來源處修復規則：設定檔案路徑，或 `--allowed-tools` 和 `--disallowed-tools` 的旗標本身。不存在於磁碟上的 `claude-settings-<hash>.json` 路徑代表內聯 `--settings` 值。修復您傳遞給該旗標的 JSON。

4105* 將裸工具名稱規則（例如 `Write` 或 `Glob`）保留原樣。Claude Code 在[工具級別](/docs/zh-TW/permissions#match-all-uses-of-a-tool)上相符它們，不會警告它們。

4106* 如果來源讀取 `managed policy settings`，將警告轉發給維護您受管設定的人，因為您無法自己清除它。

1312 4107

1313<h3 id="file-is-covered-by-a-read-deny-rule">4108在[背景工作階段](/docs/zh-TW/agent-view)或使用 `--output-format json` 或 `stream-json` 時，Claude Code 將警告寫入偵錯日誌而不是 stderr，因此機器讀取輸出保持乾淨。使用 `--debug` 在 `~/.claude/debug/<session-id>.txt` 處擷取它。在 v2.1.210 之前，Claude Code 接受這些規則而不警告。

1314 File is covered by a Read deny rule4109

4110<h3 id="has-a-wildcard-before-the-rest-of-the-command">

4111 在命令的其餘部分之前有萬用字元

1315</h3>4112</h3>

1316 4113

1317Edit 工具在與 [`Read` 拒絕規則](/docs/zh-TW/permissions#read-and-edit)相符的路徑上被呼叫，包括在該路徑建立新檔案。編輯會重寫 Claude 必須能夠讀回的內容，因此呼叫在任何檔案存取之前被拒絕。該規則僅阻止 Edit 工具：Write 和 NotebookEdit 不受 `Read` 拒絕規則涵蓋。在 v2.1.208 之前，只有 `Edit` 拒絕規則會阻止編輯，而 `Read` 拒絕規則單獨不會。4114Claude Code 在您的[設定檔案](/docs/zh-TW/settings#where-settings-live)、[受管設定](/docs/zh-TW/managed-settings)或 `--allowedTools` 或 `--settings` 旗標值中找到了 `Bash` 允許規則，其 `*` 在決定它是哪個命令的後續單詞之前，例如 `Bash(git * main)` 或 `Bash(git -C * status *)`。`*` 符合任何文字，包括在該位置插入的選項：`Bash(git * main)` 也批准 `git -c core.fsmonitor=<script> diff main`，其中 `-c` 使 git 執行命令命名的程式。[萬用字元模式](/docs/zh-TW/permissions#wildcard-patterns)顯示相符規則。

4115

4116警告存在是為了讓您縮小萬用字元比您預期更寬的規則。Claude Code 保留規則並不改變它相符的方式；警告命名規則及其在括號中的來源：

1318 4117

1319```text theme={null}4118```text theme={null}

1320File is covered by a Read deny rule in your permission settings and cannot be edited.4119權限允許規則 (.claude/settings.json)：Bash(git -C * status *) 在命令的其餘部分之前有萬用字元，因此它也符合在該位置插入的任何選項並批准它們而不提示。對於 git，選項如 -c 和 --exec-path 可以執行任意命令。將該 * 替換為您的確切值，或僅在子命令後使用 *（例如 Bash(git status *)）。

1321```4120```

1322 4121

1323**應該怎麼做：**4122**該怎麼做：**

1324 4123

1325* 如果 Claude 應該能夠編輯該檔案，請在 `/permissions` 或[設定](/docs/zh-TW/settings#permission-settings)中移除或縮小 `Read` 拒絕規則4124* 將子命令前的 `*` 替換為您的確切值：用 `Bash(git checkout main)` 代替 `Bash(git * main)`。

1326* 如果檔案必須保持未觸及狀態，請保留該規則並為相同路徑新增 `Edit` 拒絕規則，以便 Write 和 NotebookEdit 工具也被阻止4125* 將每個 `*` 移到子命令後：用 `Bash(git status *)` 代替 `Bash(git -C * status *)`。為您想允許的每個子命令寫一個規則。

4126* 在警告在括號中命名的來源處修復規則：設定檔案路徑，或 `--allowed-tools` 旗標本身。不存在於磁碟上的 `claude-settings-<hash>.json` 路徑代表內聯 `--settings` 值。修復您傳遞給該旗標的 JSON。

4127* 如果來源讀取 `managed policy settings`，將警告轉發給維護您受管設定的人，因為您無法自己清除它。

1327 4128

1328<h2 id="background-session-errors">4129Claude Code 不警告具有相同形狀的拒絕和詢問規則：它拒絕或提示它們相符的額外命令，而不是批准它們。它也不警告子命令在第一個 `*` 之前的規則，例如 `Bash(git commit *)`，或沒有單詞（除了選項）跟在 `*` 後的規則，例如 `Bash(git *)`，或關於 `:*` 前綴規則如 `Bash(git:*)`。

1329 背景工作階段錯誤

1330</h2>

1331 4130

1332[背景工作階段](/docs/zh-TW/agent-view)在沒有互動式終端的情況下執行，因此需要終端的命令在那裡的行為會有所不同。這些訊息會出現在背景工作階段的文字記錄中，在代理檢視中或附加後。4131在[背景工作階段](/docs/zh-TW/agent-view)或使用 `--output-format json` 或 `stream-json` 時，Claude Code 將警告寫入偵錯日誌而不是 stderr，因此機器讀取輸出保持乾淨。使用 `--debug` 在 `~/.claude/debug/<session-id>.txt` 處擷取它。在 v2.1.246 之前，Claude Code 接受這些規則而不警告。

1333 4132

1334<h3 id="commands-refused-in-a-background-session">4133<h3 id="crosssessioninbound-must-be-one-of-accept-hold-refuse">

1335 背景工作階段中被拒絕的命令4134 crossSessionInbound 必須是 accept、hold、refuse 之一

1336</h3>4135</h3>

1337 4136

1338在背景工作階段中，開啟互動式對話框的命令會被拒絕，並顯示一條訊息，說明在該處有效的表單或告訴您從常規終端執行命令。`/install-github-app`、`/mcp` 設定清單和 MCP 伺服器選單中的驗證操作都以這種方式被拒絕。在 v2.1.208 之前，它們在背景工作階段內開啟了對話框。4137設定檔案將 [`crossSessionInbound`](/docs/zh-TW/settings-reference#crosssessioninbound) 設定為 Claude Code 無法辨識的值，例如打字錯誤 `"reject"`。警告的第二句取決於哪個檔案保持該值；在使用者、專案、本機或 `--settings` 檔案中讀取：

1339在 v2.1.208 中，`/model` 選擇器也在背景工作階段中被拒絕，`/upgrade` 列印升級 URL 而不是開啟瀏覽器。4138

4139```text theme={null}

4140"crossSessionInbound" 必須是 "accept"、"hold"、"refuse" 之一；收到 "reject"。此值被忽略；當它存在時，跨工作階段訊息被保持以供您批准，而不是被傳遞。將其設定為上述值之一。

4141```

4142

4143在[受管設定](/docs/zh-TW/managed-settings)中，Claude Code 將無法辨識的值視為 `refuse`（最限制的值），警告說跨工作階段訊息被拒絕，直到管理員修復它。有關保持如何與您其他設定檔案中的值結合，請參閱 [`crossSessionInbound`](/docs/zh-TW/settings-reference#crosssessioninbound)。

4144

4145**該怎麼做：**

4146

4147* 將金鑰設定為 `"accept"`、`"hold"` 或 `"refuse"`，或移除它

4148* 當警告命名受管設定時，要求管理員修復該值

1340 4149

1341措辭會說明被拒絕的命令。`/mcp` 設定清單報告：4150在 v2.1.248 之前，Claude Code 忽略無法辨識的值而不警告。

4151

4152<h3 id="the-200k-limit-isnt-enforced">

4153 200K 限制未強制執行

4154</h3>

4155

4156您設定了 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/zh-TW/env-vars)，這通常使[自動壓縮](/docs/zh-TW/model-config#default-auto-compact-thresholds)在 1M 上下文模型上保持工作階段至 200K 視窗，但沒有壓縮閾值將此工作階段限制在或低於 200K，因此對話可以超過它。

1342 4157

1343```text theme={null}4158```text theme={null}

1344Can't open MCP settings in a background session — use `/mcp enable|disable|reconnect <server>` to steer, or run /mcp from an interactive terminal to authenticate.4159CLAUDE_CODE_DISABLE_1M_CONTEXT 已設定，但 <model> 的 200K 限制未強制執行，因此此工作階段可以超過它。若要強制執行，設定 CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000（或 autoCompactWindow 設定）。

1345```4160```

1346 4161

4162Claude Code 為它辨識為具有原生 1M 視窗的每個模型自行強制執行 200K 限制，對於它無法辨識的模型 ID，它在它假設的視窗處壓縮。當其他設定擊敗該強制執行時出現警告：

4163

4164* 模型 ID 不是 Claude Code 辨識的，例如[LLM 閘道](/docs/zh-TW/llm-gateway)別名，且您設定了 [`CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1`](/docs/zh-TW/env-vars) 或使用 [`CLAUDE_CODE_MAX_CONTEXT_TOKENS`](/docs/zh-TW/env-vars) 將假設的視窗提高到 200K 以上。在此情況下，訊息也提供 `or update to a Claude Code version that recognizes <model>` 作為補救。

4165* 透過 [`ANTHROPIC_BETAS`](/docs/zh-TW/env-vars) 或 [`--betas`](/docs/zh-TW/cli-reference#cli-flags) 旗標要求的 `context-1m` 測試版仍要求 API 在接受該測試版的模型上使用 1M 視窗，而沒有任何內容在 200K 處壓縮工作階段

4166

1347**該怎麼做：**4167**該怎麼做：**

1348 4168

1349* 使用訊息所說的表單，例如 `/mcp reconnect <server>`、`/mcp enable` 或 `/mcp disable`4169* 設定 [`CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000`](/docs/zh-TW/env-vars)，或 [`autoCompactWindow`](/docs/zh-TW/settings-reference#autocompactwindow) 設定為 `200000`，以便自動壓縮在 200K 邊界處壓縮

1350* 對於登入和授權流程，請從終端中的常規 `claude` 工作階段執行命令4170* 如果訊息命名此版本無法辨識的模型 ID，執行 `claude update`。辨識 ID 為 1M 上下文模型的版本無需進一步設定即可強制執行限制。

4171* 如果您想讓工作階段改為使用模型的完整視窗，取消設定 `CLAUDE_CODE_DISABLE_1M_CONTEXT`；警告僅報告 200K 限制未強制執行

1351 4172

1352<h3 id="claude_code_process_wrapper-launcher-errors">4173在[背景工作階段](/docs/zh-TW/agent-view)或使用 `--output-format json` 或 `stream-json` 時，Claude Code 將警告寫入偵錯日誌而不是 stderr。

1353 CLAUDE\_CODE\_PROCESS\_WRAPPER 啟動器錯誤4174

4175<h3 id="unrecognized-model-id-on-a-request">

4176 要求上無法辨識的模型 ID

1354</h3>4177</h3>

1355 4178

1356[`CLAUDE_CODE_PROCESS_WRAPPER`](/docs/zh-TW/corporate-launcher) 已設定，但其值無法使用，因此 Claude Code 拒絕啟動受影響的程序，而不是在沒有啟動器的情況下執行它。配置問題會報告為以變數名稱開頭並說明原因的訊息，例如：4179Claude Code 為您的 Claude Code 版本無法辨識的模型 ID 傳送了要求，並找不到將該 ID 對應到它辨識的模型的 [`modelOverrides`](/docs/zh-TW/model-config#override-model-ids-per-version) 項目。Claude Code 仍使用您設定的 ID 傳送要求，不退出或切換模型。

1357 4180

1358```text theme={null}4181```text theme={null}

1359CLAUDE_CODE_PROCESS_WRAPPER: launcher `/opt/corp/launcher` is not an executable regular file4182[claude-code:unrecognized_model] {"model":"my-proxy-model","query_source":"sdk"}

1360```4183```

1361 4184

1362啟動但退出而不用 Claude Code 替換自身的啟動器會導致它啟動的工作階段失敗，該工作階段在代理檢視中的列會報告啟動器 `must exec, not daemonize`，後面跟著啟動器列印的任何內容。由於啟動器而無法啟動或無法到達背景服務的工作階段會將啟動器問題報告為 `Couldn't reach the background service (...)` 內的原因。4185在讀取 stderr 的指令碼或工具中，符合 `[claude-code:unrecognized_model]` 前綴。在前綴和一個空格之後，Claude Code 寫入一行 JSON 物件。Claude Code 可以在更新版本中向其新增欄位，因此忽略您不期望的任何欄位。它至少寫入這兩個：

4186

4187* `model`：您設定的模型字串

4188* `query_source`：使用模型的要求路徑。Claude Code 為 `-p` 執行報告 `sdk`，為子代理程式報告以 `agent:` 開頭的值。

4189

4190Claude Code 根據您執行它的方式將行寫入兩個位置之一：

4191

4192* 在[非互動模式](/docs/zh-TW/headless)中使用 `-p`，Claude Code 在每個 `--output-format` 下將其寫入 stderr，因此您可以解析 stdout 而不過濾行

4193* 在互動工作階段或[背景工作階段](/docs/zh-TW/agent-view)中，Claude Code 改為將其寫入偵錯日誌；使用 `--debug` 在 `~/.claude/debug/<session-id>.txt` 處擷取它

4194

4195Claude Code 每個模型字串每個程序寫入行一次。它為每個進一步的無法辨識的 ID 寫入單獨的行，例如[子代理程式](/docs/zh-TW/sub-agents#choose-a-model)或[背景功能](/docs/zh-TW/costs#background-token-usage)使用的 ID。

4196

4197Claude Code 不為它解析為它辨識的模型的提供者 ID 寫入行，例如 Amazon Bedrock `us.anthropic.claude-...` ID、Google Cloud 的 Agent Platform ID 帶有 `@` 版本後綴，以及包含 Claude 模型 ID 的 Microsoft Foundry 部署名稱。Claude Code 檢查 Amazon Bedrock[應用程式推論設定檔 ARN](/docs/zh-TW/amazon-bedrock#map-each-model-version-to-an-inference-profile) 後面的模型，而不是 ARN 本身。它為無法解析的 ARN（例如打字錯誤的 ARN）寫入無行。

1363 4198

1364**該怎麼做：**4199**該怎麼做：**

1365 4200

1366* 將變數設定為可執行檔的絕對路徑，該路徑以呼叫 `exec "$@"` 結尾。請參閱[啟動器合約](/docs/zh-TW/corporate-launcher#the-launcher-contract)以了解完整合約4201* 如果您故意設定 ID，例如[LLM 閘道](/docs/zh-TW/llm-gateway)別名，將 [`modelOverrides`](/docs/zh-TW/model-config#override-model-ids-per-version) 項目新增到您的[設定檔案](/docs/zh-TW/settings#where-settings-live)，以 ID 作為其值。使用 Anthropic 模型 ID 作為金鑰，而不是家族別名如 `opus`。對於範例行中的 `my-proxy-model`，新增此項目：

1367* 檢查 `/status`，它在其 Self-exec 項目中顯示已解析的啟動命令，並在執行中的背景服務不符合時發出警告，或從 shell 執行 `claude daemon status`

1368* 在修復 [settings](/docs/zh-TW/corporate-launcher#set-up-the-launcher) 的 `env` 區塊中的值後，使用 `claude daemon stop --any` 重新啟動背景服務，以便下一次分派啟動包裝的服務

1369 4202

1370<h2 id="configuration-warnings">4203 ```json theme={null}

1371 設定警告4204 {

1372</h2>4205 "modelOverrides": {

4206 "claude-opus-4-6": "my-proxy-model"

4207 }

4208 }

4209 ```

1373 4210

1374Claude Code 在啟動時將這些訊息寫入 stderr，而不是在對話中顯示錯誤。它們報告 Claude Code 讀取但未應用的設定。4211 Claude Code 然後將 `my-proxy-model` 視為 `claude-opus-4-6` 並停止寫入行。

1375 4212

1376<h3 id="workspace-has-not-been-trusted">4213* 如果 ID 命名比您的 Claude Code 版本更新的模型，執行 `claude update`

1377 工作區尚未受信任4214

4215* 如果 ID 是打字錯誤，在您可以設定模型的[位置](/docs/zh-TW/model-config#setting-your-model)或[別名變數](/docs/zh-TW/model-config#environment-variables)中修復它。如果 `query_source` 以 `agent:` 開頭，改為在您設定[子代理程式模型](/docs/zh-TW/sub-agents#choose-a-model)的位置修復它。

4216

4217在 v2.1.233 之前，Claude Code 為無法辨識的模型 ID 傳送要求時未寫入行。

4218

4219<h3 id="stale-sandbox-mask-files-left-by-a-killed-session">

4220 被殺死的工作階段留下的過時沙箱遮罩檔案

1378</h3>4221</h3>

1379 4222

1380Claude Code 在專案的 `.claude/settings.json` 或 `.claude/settings.local.json` 中找到了 `permissions.allow` 規則或 `permissions.additionalDirectories` 項目，但未應用它們，因為[來自專案設定的允許規則需要工作區信任](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)。訊息中的計數、設定名稱和檔案名稱會根據您的設定而變化。`deny` 和 `ask` 規則不受影響。4223`claude doctor` 在其診斷中列印此警告，`/status` 列出相同的行。它在 Linux 和 WSL2 上出現，當[沙箱](/docs/zh-TW/sandboxing)啟用且檔案系統隔離開啟時。

4224

4225當沙箱化命令執行時，沙箱透過在那裡建立 0 位元組唯讀佔位符來保持對尚不存在的檔案的寫入拒絕，並在之後移除它。在該清理執行前被殺死的工作階段（例如透過 SIGKILL）會留下佔位符。後續工作階段在每次啟動時再次唯讀繫結它們，因此設定寫入（例如儲存「是，不要再問」）在其中一個所在的位置失敗。

1381 4226

1382```text theme={null}4227```text theme={null}

1383Ignoring 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.4228- 被殺死的工作階段留下的過時沙箱遮罩檔案：/home/you/project/.claude/settings.local.json

4229 修復：在該專案中沒有其他 Claude Code 工作階段執行時，使用 `rm <path>` 移除每個 — 0 位元組唯讀檔案（其中設定檔案所在）使「是，不要再問」無法儲存，沙箱在每次啟動時再次唯讀繫結它

1384```4230```

1385 4231

1386**該怎麼做：**4232**該怎麼做：**

1387 4233

1388* 在目錄中執行 `claude` 並接受信任對話框。即使父目錄已經受信任，對話框仍會出現，列出被保留的規則，並讓您可以拒絕並繼續工作而不使用這些規則。在 v2.1.200 之前，在這種情況下不會出現對話框，因此無法在那裡完成此步驟。4234* 退出在該專案中執行的任何其他 Claude Code 工作階段，然後使用 `rm` 刪除每個列出的檔案。警告命名最多三個檔案並計算其餘的，因此在刪除後重新執行 `claude doctor` 直到警告不再出現。另一個工作階段的沙箱仍在使用的佔位符是該工作階段寫入保護的活躍部分

1389* 在[非互動模式](/docs/zh-TW/headless)中使用 `-p` 時不會顯示對話框。使用訊息列印的確切 `projects` 金鑰在 `~/.claude.json` 中設定 `hasTrustDialogAccepted` 項目。4235* 如果您使用「是，不要再問」儲存的權限選擇未堅持，在刪除佔位符後再次儲存它

1390* 如果訊息命名 `.claude/settings.local.json` 且您在 git 儲存庫外或在主目錄中啟動 Claude Code，請更新至 v2.1.200 或更新版本。版本 2.1.196 至 2.1.199 在這些工作區中將您自己的 `.claude/settings.local.json` 視為儲存庫提供的。在 v2.1.207 及更新版本上，如果您尚未信任該資料夾，在 git 儲存庫外更新是不夠的：判斷資料夾是否在儲存庫內會執行 git，而 Claude Code 只在您接受信任對話框後才執行該檢查，因此請使用第一步。您的主目錄和任何其他[設定主目錄](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)都被豁免，不需要等待對話框。請參閱[專案允許規則和工作區信任](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)。4236

4237在 v2.1.257 之前，`claude doctor` 未標記這些檔案；較早版本在工作階段被殺死時留下相同的佔位符。

1391 4238

1392<h2 id="responses-seem-lower-quality-than-usual">4239<h2 id="responses-seem-lower-quality-than-usual">

1393 回應品質似乎低於預期4240 回應品質似乎低於預期

1398 4244

1399* 配置的 [`--fallback-model`](/docs/zh-TW/cli-reference#cli-flags) 在可用性錯誤後接管該輪次，並在文字記錄中顯示通知4245* 配置的 [`--fallback-model`](/docs/zh-TW/cli-reference#cli-flags) 在可用性錯誤後接管該輪次，並在文字記錄中顯示通知

1400* Amazon Bedrock 或 Google Cloud 的 Agent Platform 啟動檢查發現您的預設模型不可用4246* Amazon Bedrock 或 Google Cloud 的 Agent Platform 啟動檢查發現您的預設模型不可用

1401* [自動模型備用](/docs/zh-TW/model-config#automatic-model-fallback)在 Fable 5 上將工作階段移至預設 Opus 模型，並在文字記錄中顯示通知4247* [自動模型備用](/docs/zh-TW/model-config#automatic-model-fallback)在 Fable 5.1、Fable 5 和 Opus 5 上將工作階段移至標記類別的備用模型（當該類別有備用模型時），並在文字記錄中顯示通知

1402 4248

1403下面的模型選擇檢查可捕捉第二和第三種情況；第一種情況顯示為文字記錄通知而非 `/model` 變更。[模型配置](/docs/zh-TW/model-config)說明每個備用何時適用。4249下面的模型選擇檢查可以捕捉第二和第三種情況；第一種情況顯示為文字記錄通知而非 `/model` 變更。[模型設定](/docs/zh-TW/model-config)說明每個備用何時適用。

1404 4250

1405首先檢查這些項目：4251首先檢查這些項目：

1406 4252

1407* **模型選擇**：執行 `/model` 以確認您使用的是預期的模型。先前的 `/model` 選擇或 `ANTHROPIC_MODEL` 環境變數可能使您使用的模型比預期的要小。4253* **模型選擇**：執行 `/model` 以確認您在預期的模型上。先前的 `/model` 選擇或 `ANTHROPIC_MODEL` 環境變數可能使您在比預期更小的模型上。

1408* **努力程度**：執行 `/effort` 以檢查目前的推理級別，並針對困難的除錯或設計工作提高它。預設值因模型而異，因此在假設您低於最大值之前請先檢查。請參閱[調整努力程度](/docs/zh-TW/model-config#adjust-effort-level)以了解每個模型的預設值和 `ultrathink` 快捷方式。4254* **努力程度**：執行 `/effort` 以檢查目前的推理程度，並為困難的除錯或設計工作提高它。預設值因模型而異，所以在假設您低於最大值之前請先檢查。請參閱[調整努力程度](/docs/zh-TW/model-config#adjust-effort-level)以了解每個模型的預設值和 `ultrathink` 快捷方式。

1409* **上下文壓力**：執行 `/context` 以查看視窗的滿度。如果接近容量，請在自然中斷點執行 `/compact` 或執行 `/clear` 以重新開始。請參閱[探索上下文視窗](/docs/zh-TW/context-window)以了解自動壓縮如何影響較早的輪次。4255* **上下文壓力**：執行 `/context` 以查看視窗有多滿。如果接近容量，請在自然斷點執行 `/compact` 或執行 `/clear` 以重新開始。請參閱[探索上下文視窗](/docs/zh-TW/context-window)以了解自動壓縮如何影響較早的輪次。

1410* **過時的指示**：大型或過時的 `CLAUDE.md` 檔案和 MCP 工具定義會消耗上下文，並可能引導回應。`/doctor` 檢查會標記超大記憶體檔案和未使用的擴充功能，而 `/context` 會顯示 MCP 工具令牌使用情況。在 v2.1.205 之前，`/doctor` 開啟診斷畫面，標記超大記憶體檔案和子代理定義。4256* **過時的指示**：大型或過時的 `CLAUDE.md` 檔案和 MCP 工具定義會消耗上下文並可能引導回應。`/doctor` 檢查會標記超大的記憶檔案和未使用的擴充功能，而 `/context` 會顯示 MCP 工具的權杖使用情況。在 v2.1.205 之前，`/doctor` 開啟了一個診斷畫面，標記超大的記憶檔案和子代理定義。

1411 4257

1412當回應出錯時，回溯通常比用更正回覆效果更好。按 Esc 兩次或執行 `/rewind` 以回到不良輪次之前，然後用更具體的內容重新表述提示。在執行緒中更正會將錯誤的嘗試保留在上下文中，這可能會將後續答案錨定到它。請參閱[檢查點](/docs/zh-TW/checkpointing)。4258當回應出錯時，回溯通常比用更正回覆效果更好。按 Esc 兩次或執行 `/rewind` 以回到不良輪次之前，然後用更多細節重新表述提示。在執行緒中更正會將錯誤的嘗試保留在上下文中，這可能會將後來的答案錨定到它。請參閱[檢查點](/docs/zh-TW/checkpointing)。

1413 4259

1414如果在檢查上述項目後品質仍然似乎不對，請執行 `/feedback` 並描述您預期的內容與您得到的內容。以這種方式提交的回饋包括對話文字記錄，這是 Anthropic 診斷真實回歸的最快方式。如果 `/feedback` 在您的環境中不可用，請參閱[報告錯誤](#report-an-error)。4260如果在檢查上述項目後品質仍然似乎有問題，請執行 `/feedback` 並描述您預期的內容與您得到的內容。以這種方式提交的回饋包括對話文字記錄，這是 Anthropic 診斷真實迴歸的最快方式。如果 `/feedback` 在您的環境中不可用，請參閱[報告錯誤](#report-an-error)。

1415 4261

1416如果 Claude 警告懷疑提示注入，或因懷疑注入而拒絕請求，而警告命名的文字是 Claude Code 自動添加到對話中的上下文而非檔案或網路內容，請執行 `claude update` 並重試。如果更新後警告重複出現，請[報告它](#report-an-error)而不是將標記的內容貼回提示中。在 v2.1.201 之前，Sonnet 5 以相同方式拒絕了某些請求。4262如果 Claude 警告懷疑提示注入，或因懷疑注入而拒絕請求，而警告命名的文字是 Claude Code 自動添加到對話中的上下文而非檔案或網路內容，請執行 `claude update` 並重試。如果更新後警告重複出現，請[報告它](#report-an-error)而不是將標記的內容貼回提示中。在 v2.1.201 之前，Sonnet 5 以相同方式拒絕了一些請求。

1417 4263

1418<h2 id="report-an-error">4264<h2 id="report-an-error">

1419 回報錯誤4265 回報錯誤

feature-availability.md +1 −1

Details

41* **MCP servers**：[來自 claude.ai 的連接器](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai)僅在您的 claude.ai 訂閱是作用中驗證方法時才會載入。[工具搜尋](/docs/zh-TW/mcp#configure-tool-search)在 `ANTHROPIC_BASE_URL` 指向非第一方主機時預設為關閉，在 Google Cloud's Agent Platform 上早於 Claude 4.5 世代的模型或在 Microsoft Foundry [部署於 Azure 上](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)時不受支援41* **MCP servers**：[來自 claude.ai 的連接器](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai)僅在您的 claude.ai 訂閱是作用中驗證方法時才會載入。[工具搜尋](/docs/zh-TW/mcp#configure-tool-search)在 `ANTHROPIC_BASE_URL` 指向非第一方主機時預設為關閉，在 Google Cloud's Agent Platform 上早於 Claude 4.5 世代的模型或在 Microsoft Foundry [部署於 Azure 上](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)時不受支援

42* **Subagents**：內建的 [Explore subagent](/docs/zh-TW/sub-agents#built-in-subagents) 在 Claude API 上將其繼承的模型上限設為 Opus，在任何其他提供者（包括 AWS 上的 Claude Platform）上直接繼承主要對話的模型42* **Subagents**：內建的 [Explore subagent](/docs/zh-TW/sub-agents#built-in-subagents) 在 Claude API 上將其繼承的模型上限設為 Opus，在任何其他提供者（包括 AWS 上的 Claude Platform）上直接繼承主要對話的模型

43* **[Commands](/docs/zh-TW/commands#all-commands)**：43* **[Commands](/docs/zh-TW/commands#all-commands)**：

~~44 * `/design-sync` 和 `/import` 及其 `claude import` 子命令形式在 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 和 AWS 上的 Claude Platform 上不可用~~44 * `/design-sync` 和 `/import` 及其 `claude import` 子命令形式在 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 和 AWS 上的 Claude Platform 上不可用，以及透過 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway#availability-and-limitations)

45 * `/voice` 需要 claude.ai 帳戶45 * `/voice` 需要 claude.ai 帳戶

46 * `/list-agents` 及其別名 `/peers` 僅在[啟用跨工作階段訊息傳遞](/docs/zh-TW/cross-session-messaging#availability)的工作階段中可用46 * `/list-agents` 及其別名 `/peers` 僅在[啟用跨工作階段訊息傳遞](/docs/zh-TW/cross-session-messaging#availability)的工作階段中可用

47 47

fullscreen.md +4 −2

Details

33 * 如果您倒帶到第一則訊息之前，Claude Code 會以空白對話重新啟動33 * 如果您倒帶到第一則訊息之前，Claude Code 會以空白對話重新啟動

34* 您的[權限模式](/docs/zh-TW/permission-modes)和[努力等級](/docs/zh-TW/model-config#adjust-effort-level)34* 您的[權限模式](/docs/zh-TW/permission-modes)和[努力等級](/docs/zh-TW/model-config#adjust-effort-level)

35* 您上次使用 [`/model`](/docs/zh-TW/model-config#setting-your-model) 選擇的模型35* 您上次使用 [`/model`](/docs/zh-TW/model-config#setting-your-model) 選擇的模型

~~36* 您使用 [`--allowed-tools` 或 `--disallowed-tools`](/docs/zh-TW/cli-reference#cli-flags) 傳遞的規則，以及您的 `--agent`、`--agents` 和 `--append-system-prompt` 旗標~~36* 您使用 [`--allowed-tools` 或 `--disallowed-tools`](/docs/zh-TW/cli-reference#cli-flags) 傳遞的規則，以及您的 `--agent`、`--agents`、`--append-system-prompt` 和 `--system-prompt-snapshot` 旗標

37 37

38Claude Code 會拒絕重新啟動，如果工作階段有它無法傳遞給重新啟動程序的限制。它無法傳遞的限制包括：38Claude Code 會拒絕重新啟動，如果工作階段有它無法傳遞給重新啟動程序的限制。它無法傳遞的限制包括：

39 39

149 149

150這些動作可重新繫結。請參閱[捲動動作](/docs/zh-TW/keybindings#scroll-actions)以取得完整的動作名稱清單，包括沒有預設繫結的半頁和全頁變體。150這些動作可重新繫結。請參閱[捲動動作](/docs/zh-TW/keybindings#scroll-actions)以取得完整的動作名稱清單，包括沒有預設繫結的半頁和全頁變體。

151 151

152當您向上捲動時，對話頂部會出現一個暗淡的標題列，顯示已捲動到檢視上方的最新提示。點擊該列以跳至該提示。

153

152<h3 id="auto-follow">154<h3 id="auto-follow">

153 自動跟隨155 自動跟隨

154</h3>156</h3>

179 181

180值 `3` 符合 `vim` 和類似應用程式中的預設值。此設定接受任何正值，最高為 20，包括低於 1 的小數值，例如 `0.25`，以減緩已經放大滾輪事件的終端機中的加速觸控板和滾輪捲動。182值 `3` 符合 `vim` 和類似應用程式中的預設值。此設定接受任何正值，最高為 20，包括低於 1 的小數值，例如 `0.25`，以減緩已經放大滾輪事件的終端機中的加速觸控板和滾輪捲動。

181 183

182若要以互動方式調整捲動速度，請執行 `/scroll-speed`。對話框會顯示一個尺標，您可以在對話框開啟時捲動，以便立即感受變化。按 `←` 和 `→` 調整速度，按 `r` 重設為自動偵測的預設值，按 `Enter` 儲存。對話框以整數步進到 10，在支援更精細控制的終端機上，它也提供四分之一步進到 0.25。四分之一步進需要 Claude Code v2.1.172 或更新版本。184若要以互動方式調整捲動速度，請執行 `/scroll-speed`。對話框會顯示一個尺標，您可以在對話框開啟時捲動，以便立即感受變化。按 `←` 和 `→` 調整速度，按 `r` 重設為自動偵測的預設值，按 `Enter` 儲存。對話框以整數步進到 10，在支援更精細控制的終端機上，它也提供四分之一步進到 0.25。

183 185

184該命令寫入與 `CLAUDE_CODE_SCROLL_SPEED` 環境變數設定相同的值，持久化到 `~/.claude/settings.json`。對話框的最大值為 10：如果您透過環境變數設定更高的值，對話框會顯示 10，從對話框儲存會持久化 10。此命令在 JetBrains IDE 終端機中不可用。186該命令寫入與 `CLAUDE_CODE_SCROLL_SPEED` 環境變數設定相同的值，持久化到 `~/.claude/settings.json`。對話框的最大值為 10：如果您透過環境變數設定更高的值，對話框會顯示 10，從對話框儲存會持久化 10。此命令在 JetBrains IDE 終端機中不可用。

185 187

github-actions-cloud-providers.md +324 −0 created

Details

1> ## Documentation Index

2> 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.

5# 使用 Claude Code GitHub Actions 搭配雲端提供者

7> 透過 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 執行 Claude Code GitHub Actions，而不是使用 Claude API

9[Claude Code GitHub Actions](/docs/zh-TW/github-actions) 預設會呼叫 Claude API。若要改為透過您自己的雲端帳戶路由推論，請設定 Claude Code GitHub Action 的 provider 輸入，並設定您的雲端以信任工作流程的 OpenID Connect (OIDC) 權杖。工作流程會使用該權杖進行驗證，因此您無需在儲存庫中儲存長期的雲端認證。

11<Info>

12 本頁面以 [GitHub Actions 設定](/docs/zh-TW/github-actions#setup) 為基礎。它假設您已經熟悉工作流程檔案和 `anthropics/claude-code-action` 步驟，僅涵蓋雲端提供者所變更的部分。

13</Info>

15<h2 id="choose-your-provider">

16 選擇您的提供者

17</h2>

19Claude Code GitHub Action 支援三個提供者，以下設定步驟僅在雲端側設定上有所不同。請使用您的組織已經擁有 Claude 模型存取權的提供者。您可以在 `anthropics/claude-code-action` 步驟的 `with:` 區塊中使用一個輸入來告訴 Claude Code GitHub Action 要使用哪個提供者：

21* **Amazon Bedrock**：`use_bedrock: "true"`

22* **Google Cloud 的 Agent Platform**：`use_vertex: "true"`

23* **Microsoft Foundry**：`use_foundry: "true"`

25[設定整合](#set-up-the-integration) 下的完整工作流程範例已經包含了每個提供者的輸入。

27<h2 id="prerequisites">

28 先決條件

29</h2>

31在開始之前，您需要：

33* 對執行 Claude Code GitHub Action 的儲存庫的管理員存取權，以安裝 GitHub App 並新增密鑰

34* 在您的雲端帳戶中建立身分識別資源的權限：AWS 上的 IAM 角色和 OIDC 身分識別提供者、Google Cloud 上的 Workload Identity Federation 資源和服務帳戶，或 Azure 上的 Microsoft Entra 應用程式

35* 在您的提供者上擁有 Claude 模型存取權：

36 * **Amazon Bedrock**：已授予 Claude 模型的存取權。跨區域推論設定檔（例如本頁面範例中的 `us.` 模型 ID）需要在其區域群組的每個區域中授予存取權。請參閱 [Amazon Bedrock 上的 Claude Code](/docs/zh-TW/amazon-bedrock)

37 * **Google Cloud 的 Agent Platform**：已啟用 Agent Platform API 的專案以及對 Claude 模型的存取權。請參閱 [Google Cloud 的 Agent Platform 上的 Claude Code](/docs/zh-TW/google-vertex-ai)

38 * **Microsoft Foundry**：具有 Claude 模型部署的 Foundry 資源。請參閱 [Microsoft Foundry 上的 Claude Code](/docs/zh-TW/microsoft-foundry)

40<h2 id="set-up-the-integration">

41 設定整合

42</h2>

44除了先決條件外，您需要建立四項內容：Claude Code GitHub Action 的 GitHub 身分識別、雲端側信任設定、儲存庫密鑰和工作流程檔案。以下步驟將逐一說明每一項。

46<Steps>

47 <Step title="選擇 GitHub 身分識別">

48 Claude Code GitHub Action 透過 GitHub 身分識別推送提交並發佈評論。[快速設定](/docs/zh-TW/github-actions#quick-setup) 會為此安裝官方 Claude GitHub App。使用雲端提供者時，您可以自己選擇身分識別：

50 * **官方 [Claude GitHub App](https://github.com/apps/claude)**：在儲存庫上安裝它，或如果已經安裝，請跳到下一步

51 * **自訂 GitHub App**：當您只想要 Claude Code GitHub Action 使用的三個權限，而不是[官方應用程式的完整集合](/docs/zh-TW/github-actions#github-app-permissions)時，建立您自己的應用程式，如下所述

52 * **GitHub 的自動 `GITHUB_TOKEN`**：無需建立或安裝應用程式，但 GitHub 不會在使用它進行的提交上觸發您的 CI 工作流程

54 第四步中的工作流程範例使用自訂應用程式進行驗證。該步驟也說明了其他兩個選項要變更的內容。

56 若要建立自訂應用程式，請[註冊新的 GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app)，並停用 Webhook，因為此整合不使用它們。授予它三個儲存庫權限：

58 * **Contents**：讀取和寫入

59 * **Issues**：讀取和寫入

60 * **Pull requests**：讀取和寫入

62 註冊應用程式後，產生私密金鑰並保留下載的 `.pem` 檔案，從應用程式的設定頁面記下應用程式 ID，並在執行 Claude Code GitHub Action 的儲存庫上[安裝應用程式](https://docs.github.com/en/apps/using-github-apps/installing-your-own-github-app)。您將在第三步中將金鑰和 ID 新增為密鑰。

63 </Step>

65 <Step title="設定雲端驗證">

66 設定您的雲端以信任 GitHub 向工作流程發出的 OIDC 權杖，以便每次工作流程執行都能獲得短期的雲端認證。每個標籤中的項目符號總結了要建立的內容，每個標籤都連結到雲端廠商自己的主控台級步驟指南。

68 <Tabs>

69 <Tab title="Amazon Bedrock">

70 按照 [AWS 建立 OIDC 身分識別提供者指南](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html)，在您的 AWS 帳戶中建立信任設定：

72 * 新增 GitHub OIDC 身分識別提供者，提供者 URL 為 `https://token.actions.githubusercontent.com`，對象為 `sts.amazonaws.com`

73 * 建立由該提供者信任的 IAM 角色作為網路身分識別，並附加來自 [IAM 設定](/docs/zh-TW/amazon-bedrock#iam-configuration) 的範圍調用原則，該原則授予 `bedrock:InvokeModel`、`bedrock:InvokeModelWithResponseStream`、`bedrock:ListInferenceProfiles` 和 `bedrock:GetInferenceProfile`，以及兩個 `aws-marketplace` 訂閱動作

74 * 使用主體條件（例如 `repo:your-org/your-repo:*`）將角色的信任原則限制在您的儲存庫。請參閱 [GitHub 的 OIDC 強化指南](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)以了解聲明格式

76 記下角色的 ARN。您將在下一步中將其新增為密鑰。

77 </Tab>

79 <Tab title="Google Cloud 的 Agent Platform">

80 按照 [Workload Identity Federation 文件](https://cloud.google.com/iam/docs/workload-identity-federation)，在您的 Google Cloud 專案中建立聯盟資源：

82 * 啟用三個 API：IAM Credentials、Security Token Service (STS) 和 Agent Platform API，其服務名稱為 `aiplatform.googleapis.com`

83 * 建立 Workload Identity Pool，其中包含 GitHub OIDC 提供者，其簽發者為 `https://token.actions.githubusercontent.com`，並新增將池限制在您的儲存庫的屬性條件

84 * 建立專用服務帳戶，僅具有 `Vertex AI User` 角色（即 `roles/aiplatform.user`），並允許池模擬它

86 記下提供者的完整資源名稱和服務帳戶的電子郵件地址。您將在下一步中將它們新增為密鑰。

87 </Tab>

89 <Tab title="Microsoft Foundry">

90 按照 [Microsoft 從 GitHub Actions 驗證指南](https://learn.microsoft.com/en-us/azure/developer/github/connect-from-azure-openid-connect)，建立具有儲存庫聯盟認證的 Microsoft Entra 應用程式：

92 * 註冊 Microsoft Entra 應用程式並新增聯盟身分識別認證，該認證信任 GitHub 向您的儲存庫發出的權杖。使用者指派的受管身分識別可以代替應用程式。兩者都有您在下面記下的用戶端 ID

93 * 在您的 Foundry 資源上為應用程式指派 `Azure AI User` 角色。請參閱 [Azure RBAC 設定](/docs/zh-TW/microsoft-foundry#azure-rbac-configuration)以了解更窄的自訂角色

95 記下應用程式的用戶端 ID、您的租用戶 ID 和您的訂閱 ID。您將在下一步中將它們新增為密鑰。

96 </Tab>

97 </Tabs>

98 </Step>

100 <Step title="新增儲存庫密鑰">

101 在執行 Claude Code GitHub Action 的儲存庫中，為您的提供者新增密鑰，如果您在第一步中建立了自訂 GitHub App，還要新增兩個應用程式密鑰。請參閱 GitHub 的 [在 GitHub Actions 中使用密鑰](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions)指南。

102

103 | 密鑰 | 需要用於 | 值 |

104 | -------------------------------- | ----------------------------- | ------------------------- |

105 | `AWS_ROLE_TO_ASSUME` | Amazon Bedrock | IAM 角色的 ARN |

106 | `GCP_WORKLOAD_IDENTITY_PROVIDER` | Google Cloud 的 Agent Platform | 提供者的完整資源名稱 |

107 | `GCP_SERVICE_ACCOUNT` | Google Cloud 的 Agent Platform | 服務帳戶的電子郵件地址 |

108 | `AZURE_CLIENT_ID` | Microsoft Foundry | Entra 應用程式的用戶端 ID |

109 | `AZURE_TENANT_ID` | Microsoft Foundry | 您的 Microsoft Entra 租用戶 ID |

110 | `AZURE_SUBSCRIPTION_ID` | Microsoft Foundry | 您的 Azure 訂閱 ID |

111 | `APP_ID` | 自訂 GitHub App | GitHub App 的 ID |

112 | `APP_PRIVATE_KEY` | 自訂 GitHub App | `.pem` 私密金鑰檔案的內容 |

113 </Step>

114

115 <Step title="建立工作流程檔案">

116 為您的提供者建立工作流程檔案，例如 `.github/workflows/claude.yml`。每個範例都會回應 `@claude` 提及，使用自訂應用程式向 GitHub 進行驗證，並包含 `id-token: write` 權限，GitHub 需要此權限來發出 OIDC 權杖，您的雲端提供者可以將其交換為認證。

117

118 如果您在第一步中選擇了不同的 GitHub 身分識別，請調整範例：

119

120 * **官方 Claude GitHub App**：刪除「產生 GitHub App 權杖」步驟和 `github_token` 行

121 * **GitHub 的自動權杖**：刪除權杖產生步驟，並將 `github_token` 行變更為 `github_token: ${{ secrets.GITHUB_TOKEN }}`

122

123 <Warning>

124 在公開儲存庫上，任何使用者的包含觸發短語的評論都會啟動此工作流程。認證步驟在 Claude Code GitHub Action 檢查評論者的寫入存取權之前執行，因此該動作僅在工作流程產生應用程式權杖並登入您的雲端提供者後才拒絕未授權的使用者，這會留下稽核日誌項目並消耗 Actions 分鐘數。為了避免這些執行，請新增一個步驟，在認證步驟之前驗證評論者的寫入存取權。

125 </Warning>

126

127 <Tabs>

128 <Tab title="Amazon Bedrock">

129 將 `aws-region` 值替換為您自己的值。認證步驟會將其匯出為 `AWS_REGION`，供工作的其餘部分使用。

130

131 ```yaml theme={null}

132 name: Claude PR Action

133

134 permissions:

135 contents: write

136 pull-requests: write

137 issues: write

138 id-token: write

139

140 on:

141 issue_comment:

142 types: [created]

143 pull_request_review_comment:

144 types: [created]

145 issues:

146 types: [opened]

147

148 jobs:

149 claude-pr:

150 if: |

151 (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||

152 (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||

153 (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))

154 runs-on: ubuntu-latest

155 steps:

156 - name: Checkout repository

157 uses: actions/checkout@v6

158

159 - name: Generate GitHub App token

160 id: app-token

161 uses: actions/create-github-app-token@v2

162 with:

163 app-id: ${{ secrets.APP_ID }}

164 private-key: ${{ secrets.APP_PRIVATE_KEY }}

165

166 - name: Configure AWS Credentials (OIDC)

167 uses: aws-actions/configure-aws-credentials@v4

168 with:

169 role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}

170 aws-region: us-west-2

171

172 - uses: anthropics/claude-code-action@v1

173 with:

174 github_token: ${{ steps.app-token.outputs.token }}

175 use_bedrock: "true"

176 claude_args: '--model us.anthropic.claude-sonnet-4-6'

177 ```

178

179 <Tip>

180 Bedrock 模型 ID 包含跨區域推論設定檔前綴，例如 `us.`。使用您授予模型存取權的區域群組的前綴。

181 </Tip>

182 </Tab>

183

184 <Tab title="Google Cloud 的 Agent Platform">

185 將 `CLOUD_ML_REGION` 值替換為您自己的值。您無需硬編碼專案 ID，因為工作流程會從 `auth` 步驟的輸出中讀取它。

186

187 ```yaml theme={null}

188 name: Claude PR Action

189

190 permissions:

191 contents: write

192 pull-requests: write

193 issues: write

194 id-token: write

195

196 on:

197 issue_comment:

198 types: [created]

199 pull_request_review_comment:

200 types: [created]

201 issues:

202 types: [opened]

203

204 jobs:

205 claude-pr:

206 if: |

207 (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||

208 (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||

209 (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))

210 runs-on: ubuntu-latest

211 steps:

212 - name: Checkout repository

213 uses: actions/checkout@v6

214

215 - name: Generate GitHub App token

216 id: app-token

217 uses: actions/create-github-app-token@v2

218 with:

219 app-id: ${{ secrets.APP_ID }}

220 private-key: ${{ secrets.APP_PRIVATE_KEY }}

221

222 - name: Authenticate to Google Cloud

223 id: auth

224 uses: google-github-actions/auth@v2

225 with:

226 workload_identity_provider: ${{ secrets.GCP_WORKLOAD_IDENTITY_PROVIDER }}

227 service_account: ${{ secrets.GCP_SERVICE_ACCOUNT }}

228

229 - uses: anthropics/claude-code-action@v1

230 with:

231 github_token: ${{ steps.app-token.outputs.token }}

232 use_vertex: "true"

233 claude_args: '--model claude-sonnet-5'

234 env:

235 ANTHROPIC_VERTEX_PROJECT_ID: ${{ steps.auth.outputs.project_id }}

236 CLOUD_ML_REGION: us-east5

237 ```

238 </Tab>

239

240 <Tab title="Microsoft Foundry">

241 將 `your-resource-name` 替換為您的 Foundry 資源名稱。Claude Code 會從中建立端點 URL。`azure/login` 步驟使用工作流程的 OIDC 權杖登入，Claude Code 透過 Azure [預設認證鏈](https://learn.microsoft.com/en-us/azure/developer/javascript/sdk/authentication/credential-chains#defaultazurecredential-overview)取得認證。

242

243 ```yaml theme={null}

244 name: Claude PR Action

245

246 permissions:

247 contents: write

248 pull-requests: write

249 issues: write

250 id-token: write

251

252 on:

253 issue_comment:

254 types: [created]

255 pull_request_review_comment:

256 types: [created]

257 issues:

258 types: [opened]

259

260 jobs:

261 claude-pr:

262 if: |

263 (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||

264 (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||

265 (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))

266 runs-on: ubuntu-latest

267 steps:

268 - name: Checkout repository

269 uses: actions/checkout@v6

270

271 - name: Generate GitHub App token

272 id: app-token

273 uses: actions/create-github-app-token@v2

274 with:

275 app-id: ${{ secrets.APP_ID }}

276 private-key: ${{ secrets.APP_PRIVATE_KEY }}

277

278 - name: Authenticate to Azure

279 uses: azure/login@v2

280 with:

281 client-id: ${{ secrets.AZURE_CLIENT_ID }}

282 tenant-id: ${{ secrets.AZURE_TENANT_ID }}

283 subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

284

285 - uses: anthropics/claude-code-action@v1

286 with:

287 github_token: ${{ steps.app-token.outputs.token }}

288 use_foundry: "true"

289 claude_args: '--model claude-sonnet-5'

290 env:

291 ANTHROPIC_FOUNDRY_RESOURCE: your-resource-name

292 ```

293

294 <Tip>

295 使用與您的 Foundry 資源中 Claude 部署相符的模型 ID。請參閱 [Microsoft Foundry 上的 Claude Code](/docs/zh-TW/microsoft-foundry)，了解模型設定和版本固定。

296 </Tip>

297 </Tab>

298 </Tabs>

299

300 使用任何提供者，您可以透過將 `--max-turns` 新增到 `claude_args` 來限制執行長度和成本。請參閱[管理成本](/docs/zh-TW/github-actions#manage-costs)。

301 </Step>

302

303 <Step title="測試設定">

304 在問題或 PR 評論中提及 `@claude`，然後在儲存庫的 Actions 標籤中觀看執行。Claude 會在同一問題或 PR 上的評論中回覆。

305 </Step>

306</Steps>

307

308<h2 id="troubleshooting">

309 疑難排解

310</h2>

311

312失敗的執行通常會在以下兩個地方之一中斷：

313

314* **驗證錯誤**：通常是 OIDC 設定錯誤。檢查工作流程是否包含 `id-token: write` 權限、信任設定的儲存庫條件是否與您的儲存庫完全相符，以及工作流程中的密鑰名稱是否與您新增的名稱相符

315* **觸發和 CI 問題**：這些的行為與 Claude Code GitHub Action 呼叫 Claude API 時相同。請參閱主頁的[疑難排解部分](/docs/zh-TW/github-actions#troubleshooting)和 Claude Code GitHub Action 的 [FAQ](https://github.com/anthropics/claude-code-action/blob/main/docs/faq.md)

316

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

318 接下來

319</h2>

320

321* [Claude Code GitHub Actions](/docs/zh-TW/github-actions)，了解範例、參數和最佳實踐

322* [Amazon Bedrock 上的 Claude Code](/docs/zh-TW/amazon-bedrock)，了解 Bedrock 模型 ID 和區域

323* [Google Cloud 的 Agent Platform 上的 Claude Code](/docs/zh-TW/google-vertex-ai)，了解 Agent Platform 模型 ID 和區域

324* [Microsoft Foundry 上的 Claude Code](/docs/zh-TW/microsoft-foundry)，了解 Foundry 模型和端點設定

glossary.md +19 −19

Details

96 Channel96 Channel

97</h3>97</h3>

98 98

99一個 [MCP server](#mcp-model-context-protocol)，它將事件推送到您正在運行的會話中，以便 Claude 可以對您離開終端時發生的事情做出反應。Channels 可以是雙向的：Claude 讀取入站事件並通過同一 channel 回覆。Telegram、Discord 和 iMessage 包含在研究預覽中。99一個[MCP 伺服器](#mcp-model-context-protocol)，可將事件推送到您執行中的工作階段，讓 Claude 能夠對您離開終端時發生的事情做出反應。Channel 可以是雙向的：Claude 讀取入站事件並透過同一 Channel 回覆。Telegram、Discord 和 iMessage 已包含在研究預覽中。

100 100

101了解更多：[Channels](/docs/zh-TW/channels)101深入瞭解：[Channels](/docs/zh-TW/channels)

102 102

103<h3 id="checkpoint">103<h3 id="checkpoint">

104 Checkpoint104 Checkpoint

105</h3>105</h3>

106 106

107在每個您發送的提示處建立的還原點。Claude Code 在每次編輯之前對檔案進行快照，以便 checkpoint 可以還原它們。按 `Esc` 兩次或執行 `/rewind` 以將程式碼、對話或兩者還原到較早的時間點，或從選定的訊息摘要對話的一部分。Checkpoints 會與對話一起儲存，因此恢復的會話仍然可以 `/rewind` 到它們。它們與 git 分開，不追蹤通過 Bash 工具進行的更改。107在您傳送開始一個回合的每個提示時建立的還原點。Claude Code 在每次編輯前都會快照檔案，以便 checkpoint 可以還原它們。按 `Esc` 兩次或執行 `/rewind` 以將程式碼、對話或兩者還原到較早的時間點，或從選定的訊息摘要對話的一部分。Checkpoint 會與對話一起儲存，因此已恢復的工作階段仍然可以 `/rewind` 回到它們。它們與 git 分開，不追蹤透過 Bash 工具所做的變更。

108 108

109了解更多：[Checkpointing](/docs/zh-TW/checkpointing)109深入瞭解：[Checkpointing](/docs/zh-TW/checkpointing)

110 110

111<h3 id="claude-directory">111<h3 id="claude-directory">

112 `.claude` directory112 `.claude` 目錄

113</h3>113</h3>

114 114

115Claude Code 讀取專案範圍配置的目錄：設定、hooks、skills、subagents、rules 和 auto memory。專案在其根目錄有 `.claude/`；您的使用者級預設值在 `~/.claude/`。115Claude Code 讀取專案範圍設定的目錄：設定、hooks、skills、subagents、rules 和自動記憶。專案在其根目錄有 `.claude/`；您的使用者層級預設值在 `~/.claude/`。

116 116

117了解更多：[The `.claude` directory](/docs/zh-TW/claude-directory)117深入瞭解：[The `.claude` directory](/docs/zh-TW/claude-directory)

118 118

119<h3 id="claude-md">119<h3 id="claude-md">

120 CLAUDE.md120 CLAUDE.md

121</h3>121</h3>

122 122

123您為 Claude 編寫的持久指令的 markdown 檔案，在每個會話開始時作為系統提示後的使用者訊息載入。將專案約定、架構筆記和「始終執行 X」規則放在這裡。專案根目錄 CLAUDE.md 在 [compaction](#compaction) 期間倖存，之後會從磁碟重新讀取。123您為 Claude 撰寫的持久指示的 markdown 檔案，在每個工作階段開始時作為系統提示之後的使用者訊息載入。將專案慣例、架構筆記和「始終執行 X」規則放在此處。專案根目錄 CLAUDE.md 在[壓縮](#compaction)後保留，並在之後從磁碟重新讀取。

124 124

125您可以在專案範圍內的 `./CLAUDE.md` 或 `./.claude/CLAUDE.md`、使用者範圍內的 `~/.claude/CLAUDE.md` 或作為組織的 [managed policy](#managed-settings) 放置 CLAUDE.md。所有發現的檔案都會連接到上下文中，而不是相互覆蓋，順序從最廣泛的範圍到最具體的範圍。125您可以在專案範圍的 `./CLAUDE.md` 或 `./.claude/CLAUDE.md`、使用者範圍的 `~/.claude/CLAUDE.md` 或作為組織的[受管原則](#managed-settings)放置 CLAUDE.md。所有發現的檔案都會連接到內容中，而不是相互覆蓋，順序從最廣泛的範圍到最具體的範圍。

126 126

127了解更多：[CLAUDE.md files](/docs/zh-TW/memory#claude-md-files)127深入瞭解：[CLAUDE.md files](/docs/zh-TW/memory#claude-md-files)

128 128

129<h3 id="command">129<h3 id="command">

130 Command130 Command

131</h3>131</h3>

132 132

133一個可重複使用的指令，您可以通過在提示中輸入 `/name` 來調用。內建命令（如 `/clear`、`/model` 和 `/compact`）控制會話。您可以在 `.claude/commands/` 中將自己的命令定義為檔案，或從 [plugin](#plugin) 安裝它們。[Skills](#skill) 是打包多步驟命令的推薦方式。133您透過在提示中輸入 `/name` 來叫用的可重複使用指示。內建命令（例如 `/clear`、`/model` 和 `/compact`）控制工作階段。您可以在 `.claude/commands/` 中將自己的命令定義為檔案，或從[外掛程式](#plugin)安裝它們。[Skills](#skill) 是封裝多步驟命令的建議方式。

134 134

135該詞的另外兩個用途是無關的：`claude` CLI 子命令（如 `claude mcp add`），列在 [CLI 參考](/docs/zh-TW/cli-reference#cli-commands) 中，以及 stdio [MCP server](#mcp-server) 項目的 `command` 欄位，它指定 Claude Code 啟動以啟動伺服器的可執行檔。135該詞的另外兩個用途不相關：`claude` CLI 子命令（例如 `claude mcp add`），列在 [CLI 參考](/docs/zh-TW/cli-reference#cli-commands) 中，以及 stdio [MCP 伺服器](#mcp-server)項目的 `command` 欄位，它指定 Claude Code 啟動伺服器時啟動的可執行檔。

136 136

137了解更多：[Commands](/docs/zh-TW/commands) · [Skills](/docs/zh-TW/skills)137深入瞭解：[Commands](/docs/zh-TW/commands) · [Skills](/docs/zh-TW/skills)

138 138

139<h3 id="compaction">139<h3 id="compaction">

140 Compaction140 Compaction

141</h3>141</h3>

142 142

143當 [context window](#context-window) 接近其限制時，自動摘要您的對話。首先清除較舊的工具輸出，然後摘要對話。專案根目錄 CLAUDE.md 和 auto memory 在 compaction 期間倖存並從磁碟重新載入；僅在對話中給出的指令可能會丟失。執行 `/compact` 手動觸發，可選擇使用焦點，如 `/compact focus on the API changes`。143當[內容視窗](#context-window)接近其限制時，自動摘要您的對話。較舊的工具輸出會先清除，然後對話會被摘要。專案根目錄 CLAUDE.md 和自動記憶在壓縮後保留並從磁碟重新載入；僅在對話中給出的指示可能會遺失。執行 `/compact` 以手動觸發，可選擇使用焦點，例如 `/compact focus on the API changes`。

144 144

145了解更多：[What survives compaction](/docs/zh-TW/context-window#what-survives-compaction) · [When context fills up](/docs/zh-TW/how-claude-code-works#when-context-fills-up)145深入瞭解：[What survives compaction](/docs/zh-TW/context-window#what-survives-compaction) · [When context fills up](/docs/zh-TW/how-claude-code-works#when-context-fills-up)

146 146

147<h3 id="connector">147<h3 id="connector">

148 Connector148 Connector

149</h3>149</h3>

150 150

151一個 [MCP server](#mcp-server)，添加到您的 claude.ai 帳戶而不是在 Claude Code 中配置。當您使用該帳戶登入 Claude Code 時，您的 connectors 會在 `/mcp` 中與您在本地添加的伺服器一起出現。組織也可以配置 connectors 並對其設定每個工具的控制。151添加到您的 claude.ai 帳戶而不是在 Claude Code 中設定的 [MCP 伺服器](#mcp-server)。當您使用該帳戶登入 Claude Code 時，您的連接器會在 `/mcp` 中與您在本地添加的伺服器一起出現。組織也可以佈建連接器並對其設定每個工具的控制。

152 152

153了解更多：[Use MCP servers from claude.ai](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai)153深入瞭解：[Use MCP servers from claude.ai](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai)

154 154

155<h3 id="context-window">155<h3 id="context-window">

156 Context window156 Context window

157</h3>157</h3>

158 158

159會話的工作記憶，保存對話歷史、檔案內容、命令輸出、CLAUDE.md、auto memory、載入的 skills 和系統指令。當您工作時，上下文會填滿直到 [compaction](#compaction) 摘要它。執行 `/context` 查看什麼在使用空間。對於基礎模型概念，請參閱[平台詞彙表](https://platform.claude.com/docs/zh-TW/about-claude/glossary#context-window)。159工作階段的工作記憶，保存對話歷史、檔案內容、命令輸出、CLAUDE.md、自動記憶、已載入的 skills 和系統指示。當您工作時，內容會填滿，直到[壓縮](#compaction)摘要它。執行 `/context` 以查看佔用空間的內容。如需基礎模型概念，請參閱[平台詞彙表](https://platform.claude.com/docs/en/about-claude/glossary#context-window)。

160 160

161了解更多：[Explore the context window](/docs/zh-TW/context-window)161深入瞭解：[Explore the context window](/docs/zh-TW/context-window)

162 162

163<h2 id="d">163<h2 id="d">

164 D164 D

headless.md +1 −1

Details

298若要為整個工作階段設定基準而不是列出個別工具，請傳遞 [權限模式](/docs/zh-TW/permission-modes)。對於 `-p`，[內建啟動權限模式](/docs/zh-TW/permission-modes#which-mode-a-session-starts-in) 在每個計畫上都是 Manual，因此傳遞您想要的權限模式：298若要為整個工作階段設定基準而不是列出個別工具，請傳遞 [權限模式](/docs/zh-TW/permission-modes)。對於 `-p`，[內建啟動權限模式](/docs/zh-TW/permission-modes#which-mode-a-session-starts-in) 在每個計畫上都是 Manual，因此傳遞您想要的權限模式：

299 299

300* **`auto`**：傳遞 `--permission-mode auto` 以讓分類器檢查大多數動作而不是您300* **`auto`**：傳遞 `--permission-mode auto` 以讓分類器檢查大多數動作而不是您

301* **`dontAsk`**：Claude Code 拒絕 `permissions.allow` 規則或 [唯讀命令集](/docs/zh-TW/permissions#read-only-commands) 中未包含的任何內容，這對於鎖定的 CI 執行很有用。`AskUserQuestion`、連接器工具 [您的組織設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools) 和標記為 [`requiresUserInteraction`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具即使當允許規則符合時也被拒絕301* **`dontAsk`**：Claude Code 拒絕每個會提示的呼叫，這對於鎖定的 CI 執行很有用。在 Manual 模式中不需要核准的動作仍然執行，例如您工作目錄中的檔案讀取和 [唯讀命令集](/docs/zh-TW/permissions#read-only-commands)，以及您的 `--allowedTools` 項目或 `permissions.allow` 規則涵蓋的動作。`AskUserQuestion`、連接器工具 [您的組織設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools) 和標記為 [`requiresUserInteraction`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具即使當允許規則符合時也被拒絕

302* **`acceptEdits`**：Claude 寫入檔案而無需提示，Claude Code 自動核准常見的檔案系統命令，例如 `mkdir`、`touch`、`mv` 和 `cp`。[任何模式都不自動核准的動作](/docs/zh-TW/permission-modes#actions-no-mode-auto-approves) 仍然適用。除了唯讀命令集，其他 shell 命令和網路請求仍然需要 `--allowedTools` 項目或 `permissions.allow` 規則。請參閱 [`acceptEdits` 自動核准的內容](/docs/zh-TW/permission-modes#auto-approve-file-edits-with-acceptedits-mode) 以取得完整清單302* **`acceptEdits`**：Claude 寫入檔案而無需提示，Claude Code 自動核准常見的檔案系統命令，例如 `mkdir`、`touch`、`mv` 和 `cp`。[任何模式都不自動核准的動作](/docs/zh-TW/permission-modes#actions-no-mode-auto-approves) 仍然適用。除了唯讀命令集，其他 shell 命令和網路請求仍然需要 `--allowedTools` 項目或 `permissions.allow` 規則。請參閱 [`acceptEdits` 自動核准的內容](/docs/zh-TW/permission-modes#auto-approve-file-edits-with-acceptedits-mode) 以取得完整清單

303 303

304此範例以 `acceptEdits` 作為基準應用 lint 修復：304此範例以 `acceptEdits` 作為基準應用 lint 修復：

hooks-guide.md +41 −36

Details

499 499

500Claude Code 在其生命週期的特定點觸發 hook 事件。當事件觸發時，Claude Code 會並行執行所有匹配的 hooks；請參閱 [Hook 處理程式欄位](/docs/zh-TW/hooks#hook-handler-fields)以了解如何處理重複的處理程式。下表顯示每個事件及其觸發時間：500Claude Code 在其生命週期的特定點觸發 hook 事件。當事件觸發時，Claude Code 會並行執行所有匹配的 hooks；請參閱 [Hook 處理程式欄位](/docs/zh-TW/hooks#hook-handler-fields)以了解如何處理重複的處理程式。下表顯示每個事件及其觸發時間：

501 501

502| Event | When it fires |502| 事件 | 何時觸發 |

503| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |503| :-------------------- | :-------------------------------------------------------------------------------------------------------------------- |

505| `Setup` | When you start Claude Code with `--init-only`, or with `--init` or `--maintenance` in `-p` mode. For one-time preparation in CI or scripts |505| `Setup` | 當您使用 `--init-only` 啟動 Claude Code，或在 `-p` 模式中使用 `--init` 或 `--maintenance` 時。用於 CI 或指令碼中的一次性準備 |

510| `PermissionDenied` | When auto mode denies a tool call, including denials without a classifier verdict. Use JSON `hookSpecificOutput.retry: true` to tell the model it may retry the denied tool call. Claude Code ignores `retry` when the classifier produced no verdict |510| `PermissionDenied` | 當自動模式拒絕工具呼叫時，包括沒有分類器判決的拒絕。使用 JSON `hookSpecificOutput.retry: true` 告訴模型它可能重試被拒絕的工具呼叫。Claude Code 在分類器未產生判決時忽略 `retry` |

523| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |523| `InstructionsLoaded` | 當 CLAUDE.md 或 `.claude/rules/*.md` 檔案被載入到上下文時。在工作階段開始時以及在工作階段期間延遲載入檔案時觸發 |

528| `WorktreeCreate` | When a worktree is being created via `--worktree`, `isolation: "worktree"`, or for a background session. Replaces default git behavior |528| `WorktreeCreate` | 當透過 `--worktree`、`isolation: "worktree"` 建立 worktree 時，或用於背景工作階段時。取代預設的 git 行為 |

537 537

538每個 hook 都有一個 `type` 來決定它如何執行。大多數 hooks 使用 `"type": "command"`，它執行 shell 命令。還有四種其他類型可用：538每個 hook 都有一個 `type` 來決定它如何執行。大多數 hooks 使用 `"type": "command"`，它執行 shell 命令。還有四種其他類型可用：

539 539

1077 Hook JSON 沒有效果1077 Hook JSON 沒有效果

1078</h3>1078</h3>

1079 1079

1080您的 hook 列印有效的 JSON，但決策沒有生效，文字記錄中也沒有出現錯誤。1080您的 hook 列印有效的 JSON，但決策沒有生效，文字記錄中也沒有出現錯誤。檢查哪個原因適用：

1081

1082* **JSON 前的額外輸出**：其他東西首先寫入 stdout，通常是您 shell 設定檔中的無條件 `echo`，所以輸出不再以 `{` 開頭，Claude Code 不會將其解析為 JSON。原因和修復方案如下所示。

1083* **欄位位置錯誤**：將每個欄位的位置與 [JSON 輸出](/docs/zh-TW/hooks#json-output)格式進行比較。例如，`permissionDecision` 應該在 `hookSpecificOutput` 內，而不是在頂層。

1081 1084

1082當 Claude Code 執行 shell 形式的命令 hook（沒有 `args` 的）時，它在 macOS 和 Linux 上生成 `sh -c`，在 Windows 上生成 Git Bash，或在預設未安裝 Git Bash 時生成 PowerShell。此 shell 是非互動式的，但 Git Bash 和某些配置（例如 `BASH_ENV` 指向 `~/.bashrc`）仍然會來源您的設定檔。如果該設定檔包含無條件的 `echo` 陳述式，輸出會被前置到您的 hook 的 JSON：1085當 Claude Code 執行 shell 形式的命令 hook（沒有 `args` 的）時，它在 macOS 和 Linux 上生成 `sh -c`，在 Windows 上生成 Git Bash，或在預設未安裝 Git Bash 時生成 PowerShell。此 shell 是非互動式的，但 Git Bash 和某些配置（例如 `BASH_ENV` 指向 `~/.bashrc`）仍然會來源您的設定檔。如果該設定檔包含無條件的 `echo` 陳述式，輸出會被前置到您的 hook 的 JSON：

1083 1086

1097 1100

1098`$-` 變數包含 shell 旗標，`i` 表示互動式。Hooks 在非互動式 shell 中執行，因此 echo 被跳過。1101`$-` 變數包含 shell 旗標，`i` 表示互動式。Hooks 在非互動式 shell 中執行，因此 echo 被跳過。

1099 1102

1103當您的 hook 在頂層而不是在 `hookSpecificOutput` 內傳回 `permissionDecision` 或 `additionalContext` 時，JSON 仍然會解析，Claude Code 會忽略放置錯誤的欄位而不報告錯誤。要查看它忽略了哪些欄位，使用 `claude --debug` 啟動 Claude Code 並在[除錯日誌](/docs/zh-TW/hooks#debug-hooks)中搜尋 `Hook JSON output had unrecognized keys`。

1104

1100<h3 id="debug-techniques">1105<h3 id="debug-techniques">

1101 除錯技術1106 除錯技術

1102</h3>1107</h3>

interactive-mode.md +2 −2

Details

384* 在空提示上按 `Escape`、`Backspace` 或 `Ctrl+U` 結束384* 在空提示上按 `Escape`、`Backspace` 或 `Ctrl+U` 結束

385* 將以 `!` 開頭的文字貼到空提示中會自動進入 shell 模式，符合輸入的 `!` 行為385* 將以 `!` 開頭的文字貼到空提示中會自動進入 shell 模式，符合輸入的 `!` 行為

386 386

387在一般互動式工作階段中，您在 shell 模式中輸入的命令會在[沙箱](/docs/zh-TW/sandboxing)外執行，即使您已啟用沙箱，因為沙箱適用於 Claude 執行的命令。請參閱[嚴格沙箱模式](/docs/zh-TW/sandboxing#the-unsandboxed-retry-escape-hatch)，了解 shell 模式命令也會在沙箱中執行的工作階段，例如啟用嚴格沙箱模式的背景工作階段。387除非您的工作階段是[嚴格沙箱模式](/docs/zh-TW/sandboxing#the-unsandboxed-retry-escape-hatch)下列出的其中一個，否則您在 shell 模式中輸入的命令會在[沙箱](/docs/zh-TW/sandboxing)外執行，即使您已啟用沙箱，因為沙箱適用於 Claude 執行的命令。

388 388

389一旦命令輸出進入文字記錄，Claude 會自動回應，因此您可以執行 `! npm test` 並取得失敗的說明，無需第二個提示。回應成本與傳送一般提示相同。若要還原先前的行為（其中輸出會新增至內容而不回應），請在 `settings.json` 中將 [`respondToBashCommands`](/docs/zh-TW/settings-reference#respondtobashcommands) 設定為 `false`。在 v2.1.186 之前，shell 模式始終將輸出新增至內容而不回應。389一旦命令輸出進入文字記錄，Claude 會自動回應，因此您可以執行 `! npm test` 並取得失敗的說明，無需第二個提示。回應成本與傳送一般提示相同。若要還原先前的行為（其中輸出會新增至內容而不回應），請在 `settings.json` 中將 [`respondToBashCommands`](/docs/zh-TW/settings-reference#respondtobashcommands) 設定為 `false`。在 v2.1.186 之前，shell 模式始終將輸出新增至內容而不回應。

390 390

679 679

680工作清單是 Claude 的待辦事項檢查清單：Claude 建立的項目，用於規劃多步驟工作，並顯示待處理、進行中或已完成的指示器。它與背景工作檢視分開。若要查看執行中的 shell 和子代理，請改用 [`/tasks`](/docs/zh-TW/commands)。680工作清單是 Claude 的待辦事項檢查清單：Claude 建立的項目，用於規劃多步驟工作，並顯示待處理、進行中或已完成的指示器。它與背景工作檢視分開。若要查看執行中的 shell 和子代理，請改用 [`/tasks`](/docs/zh-TW/commands)。

681 681

682在 [Opus 4.8、Sonnet 5、Fable 5、Mythos 5 及這些系列的更新版本](/docs/zh-TW/tools-reference#task-tool-availability)上，Claude 會追蹤多步驟工作而無需書面檢查清單，Claude Code 不提供填充此清單的工具，因此它保持空白。如果您仍想在這些模型上使用工作清單，請使用 `CLAUDE_CODE_ENABLE_TODO_TOOLS=1` 或 [工作工具可用性](/docs/zh-TW/tools-reference#task-tool-availability)下的其他方式選擇加入。在 Opus 4.7 等較早的模型上，以及在您選擇加入後，工作清單的運作方式如下：682此清單僅在具有工作追蹤工具的工作階段中填充，Claude Code 預設在 [Claude 3.x 模型、Opus 4 至 4.7、Sonnet 4 至 4.6 及 Haiku 4.5](/docs/zh-TW/tools-reference#task-tool-availability) 上提供。在任何其他模型上，包括 Claude Code 無法識別的模型 ID，除非您使用 `CLAUDE_CODE_ENABLE_TODO_TOOLS=1` 或 [工作工具可用性](/docs/zh-TW/tools-reference#task-tool-availability) 下的其他方式選擇加入，否則清單保持空白。當工作階段具有這些工具時，工作清單的運作方式如下：

683 683

684* 按 `Ctrl+T` 切換工作清單檢視。顯示一次最多五個工作。當 Claude 尚未建立任何檢查清單項目時，切換沒有可見效果，因為沒有任何內容可顯示684* 按 `Ctrl+T` 切換工作清單檢視。顯示一次最多五個工作。當 Claude 尚未建立任何檢查清單項目時，切換沒有可見效果，因為沒有任何內容可顯示

685* 如果您保持清單展開，Claude Code 會在下次啟動仍有工作的工作階段時（例如使用 `--resume` 或 `--continue`）還原展開檢視。當工作清單為空時，Claude Code 會以摺疊狀態啟動它685* 如果您保持清單展開，Claude Code 會在下次啟動仍有工作的工作階段時（例如使用 `--resume` 或 `--continue`）還原展開檢視。當工作清單為空時，Claude Code 會以摺疊狀態啟動它

keybindings.md +3 −1

Details

542 542

543這也適用於和弦繫結。取消繫結共享前綴的每個和弦會釋放該前綴以用作單一鍵繫結。任何作用中的內容中的和弦會保留其前綴的保留狀態，因此您必須在定義該和弦的內容中取消繫結每個和弦。543這也適用於和弦繫結。取消繫結共享前綴的每個和弦會釋放該前綴以用作單一鍵繫結。任何作用中的內容中的和弦會保留其前綴的保留狀態，因此您必須在定義該和弦的內容中取消繫結每個和弦。

544 544

545Claude Code 在 `ctrl+x` 前綴上繫結這些預設和弦：`Chat` 中的 `ctrl+x ctrl+k`、`ctrl+x ctrl+e` 和 `ctrl+x enter`，`Task` 中的 `ctrl+x ctrl+b`，以及 `DiffPanel` 中的 `ctrl+x b`。`ctrl+x enter` 和弦需要 v2.1.247 或更新版本，而 `ctrl+x b` 需要 v2.1.260 或更新版本。若要將 `ctrl+x` 本身回收為單一鍵繫結，請取消繫結所有這些：545Claude Code 在 `ctrl+x` 前綴上繫結這些預設和弦：`Chat` 中的 `ctrl+x ctrl+k`、`ctrl+x ctrl+e`、`ctrl+x enter`、`ctrl+x ctrl+a` 和 `ctrl+x tab`，`Task` 中的 `ctrl+x ctrl+b`，以及 `DiffPanel` 中的 `ctrl+x b`。`ctrl+x enter` 和弦需要 v2.1.247 或更新版本，而 `ctrl+x b`、`ctrl+x ctrl+a` 和 `ctrl+x tab` 需要 v2.1.260 或更新版本。若要將 `ctrl+x` 本身回收為單一鍵繫結，請取消繫結所有這些：

546 546

547```json theme={null}547```json theme={null}

548{548{

565 "ctrl+x ctrl+k": null,565 "ctrl+x ctrl+k": null,

566 "ctrl+x ctrl+e": null,566 "ctrl+x ctrl+e": null,

567 "ctrl+x enter": null,567 "ctrl+x enter": null,

568 "ctrl+x ctrl+a": null,

569 "ctrl+x tab": null,

568 "ctrl+x": "chat:newline"570 "ctrl+x": "chat:newline"

569 }571 }

570 }572 }

llm-gateway-connect.md +15 −2

Details

438 通過閘道路由到雲端提供者438 通過閘道路由到雲端提供者

439</h3>439</h3>

440 440

441這些配置使用提供者特定的基礎 URL 變數代替 `ANTHROPIC_BASE_URL` 將 Claude Code 指向通過閘道的雲端提供者。Amazon Bedrock 和 Google Cloud 的 Agent Platform 閘道接受這些提供者的本機請求格式；Microsoft Foundry 和 AWS 上的 Claude Platform 閘道接受 Anthropic Messages 格式，僅在哪個基礎 URL 變數到達它們方面有所不同。441這些配置使用提供者特定的基礎 URL 變數代替 `ANTHROPIC_BASE_URL` 將 Claude Code 指向通過閘道的雲端提供者。Amazon Bedrock 和 Google Cloud 的 Agent Platform 閘道接受這些提供者的本機請求格式；Microsoft Foundry 和 AWS 上的 Claude Platform 閘道接受 Anthropic Messages 格式。在 Amazon Bedrock 和 Google Cloud 的 Agent Platform 路由上，Claude Code 也會將它發送的 beta 標頭和請求欄位限制為該提供者接受的集合。有關您的閘道在每個路由上接收的內容，請參閱[閘道相容性指南](/docs/zh-TW/llm-gateway-protocol)。

442 442

443僅在您的閘道團隊特別命名 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 AWS 上的 Claude Platform 時使用一個。如果上面的[驗證請求](#verify-the-connection)返回 JSON，您可以跳過本部分。443僅在您的閘道團隊特別命名 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 AWS 上的 Claude Platform 時使用一個。如果上面的[驗證請求](#verify-the-connection)返回 JSON，您可以跳過本部分。

444 444

445為您的閘道團隊命名的提供者設定區塊。跳過身份驗證變數告訴 Claude Code 不要使用提供者認證簽署請求，因為閘道持有這些。如果閘道需要自己的令牌，請在區塊後添加 `ANTHROPIC_AUTH_TOKEN`，除了 Microsoft Foundry，它使用 `ANTHROPIC_FOUNDRY_API_KEY`，如所示。445為您的閘道團隊命名的提供者設定區塊。Amazon Bedrock、Google Cloud 的 Agent Platform 和 AWS 上的 Claude Platform 區塊中的跳過身份驗證變數告訴 Claude Code 不要使用雲端提供者的認證簽署請求，因為閘道持有這些。如果閘道也需要自己的令牌，您放置它的位置取決於提供者：

446

447* **Amazon Bedrock、Google Cloud 的 Agent Platform 或 AWS 上的 Claude Platform**：在區塊後添加 `ANTHROPIC_AUTH_TOKEN`。Claude Code 將其作為 `Authorization: Bearer` 標頭發送到閘道。對於不同方案或標頭中的認證，請改用 [`ANTHROPIC_CUSTOM_HEADERS`](#send-additional-headers)。無論如何都保持跳過身份驗證變數設定，因為沒有它，Claude Code 會移除 `ANTHROPIC_AUTH_TOKEN`、[`apiKeyHelper`](#rotate-credentials-with-apikeyhelper) 或 `ANTHROPIC_CUSTOM_HEADERS` 會添加的任何 `Authorization` 標頭。

448* **Microsoft Foundry**：使用 `ANTHROPIC_FOUNDRY_API_KEY`，如[其區塊](#microsoft-foundry)所示

446 449

447<h4 id="amazon-bedrock">450<h4 id="amazon-bedrock">

448 Amazon Bedrock451 Amazon Bedrock

449</h4>452</h4>

450 453

454當閘道發出自己的認證時，將 `AWS_BEARER_TOKEN_BEDROCK` 保留為未設定。如果您設定它，Claude Code 會將該 [Amazon Bedrock API 金鑰](/docs/zh-TW/amazon-bedrock#2-configure-aws-credentials)作為 `Authorization` 標頭發送，而不是您的閘道令牌，即使設定了 `CLAUDE_CODE_SKIP_BEDROCK_AUTH`。

455

451<Tabs>456<Tabs>

452 <Tab title="Bash or Zsh">457 <Tab title="Bash or Zsh">

453 ```bash theme={null}458 ```bash theme={null}

470 Google Cloud 的 Agent Platform475 Google Cloud 的 Agent Platform

471</h4>476</h4>

472 477

478將專案 ID 和區域替換為您自己的值。Claude Code 在它發送到閘道的每個請求的路徑中包含兩者：

479

473<Tabs>480<Tabs>

474 <Tab title="Bash or Zsh">481 <Tab title="Bash or Zsh">

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

492 </Tab>499 </Tab>

493</Tabs>500</Tabs>

494 501

502該區塊涵蓋路由和身份驗證。來自 [Agent Platform 設定](/docs/zh-TW/google-vertex-ai#4-configure-claude-code)的區域覆蓋和模型固定也通過閘道應用：

503

504* **每個模型的區域**：如果您的閘道從 `CLOUD_ML_REGION` 以外的區域提供某些模型，請為每個設定匹配的 `VERTEX_REGION_CLAUDE_*` 變數，例如 `VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1`。[環境變數參考](/docs/zh-TW/env-vars)列出了確切的名稱。

505* **模型版本**：如 [Pin model versions](/docs/zh-TW/google-vertex-ai#5-pin-model-versions) 中所示，固定 `ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。設定 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 也會將背景任務（如會話標題）移動到該模型，該部分解釋了哪個模型在其他情況下運行它們。

506* **模型功能**：如果您固定您的 Claude Code 版本不識別的模型 ID，功能（如努力級別或擴展思考）可能在其上保持禁用。使用 [`ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES`](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) 及其 Sonnet 和 Haiku 對應項聲明模型支持的內容。

507

495<h4 id="microsoft-foundry">508<h4 id="microsoft-foundry">

496 Microsoft Foundry509 Microsoft Foundry

497</h4>510</h4>

llm-gateway-protocol.md +27 −18

Details

34 API 格式34 API 格式

35</h2>35</h2>

36 36

~~37Gateway 必須向 Claude Code 用戶端公開以下至少一種 API 格式。用戶端選擇一種格式，並使用下表「選擇者」欄中的變數將 Claude Code 指向您的 gateway。~~37閘道必須向 Claude Code 用戶端公開以下至少一種 API 格式。用戶端會選擇一種格式，並使用下表「選擇者」欄中的變數將 Claude Code 指向您的閘道。

38 38

39Google Cloud 的 Agent Platform 是 Google Cloud 的 Claude 端點，前身為 Vertex AI；其變數名稱保留 `VERTEX` 拼寫。39Google Cloud 的 Agent Platform 是 Google Cloud 的 Claude 端點，前身為 Vertex AI；其變數名稱保留 `VERTEX` 拼寫。

40 40

41| 格式 | 選擇者 | 端點 | 轉發不變 |41| 格式 | 選擇者 | 端點 | 轉發不變 |

42| :--------------------------------------- | :---------------------------------------------------------- | :----------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------- |42| :--------------------------------------- | :---------------------------------------------------------- | :----------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------ |

44| Amazon Bedrock InvokeModel | `ANTHROPIC_BEDROCK_BASE_URL` 搭配 `CLAUDE_CODE_USE_BEDROCK=1` | `/model/{model}/invoke`、`/model/{model}/invoke-with-response-stream`、`/model/{model}/count-tokens`（可選） | `anthropic_beta` 和 `anthropic_version` 請求體欄位 |44| Amazon Bedrock InvokeModel | `ANTHROPIC_BEDROCK_BASE_URL` 搭配 `CLAUDE_CODE_USE_BEDROCK=1` | `/model/{model}/invoke`、`/model/{model}/invoke-with-response-stream`、`/model/{model}/count-tokens`（選用） | `anthropic_beta` 和 `anthropic_version` 請求本體欄位 |

45| 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` 請求體欄位 |45| 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` 請求本體欄位 |

46 46

47<h3 id="foundry-and-claude-platform-on-aws">47<h3 id="foundry-and-claude-platform-on-aws">

48 Foundry 和 AWS 上的 Claude Platform48 Foundry 和 AWS 上的 Claude Platform

49</h3>49</h3>

50 50

51Microsoft Foundry 和 [AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws) 實現了 Anthropic Messages 格式。Claude Code 通過它們自己的變數 `ANTHROPIC_FOUNDRY_BASE_URL` 和 `ANTHROPIC_AWS_BASE_URL` 路由到它們，但 gateway 在任一前面實現上述 Anthropic Messages 列。在 AWS 上的 Claude Platform 前面的 gateway 還必須轉發 `anthropic-workspace-id` 標頭，[該平台在每個請求上都需要](/docs/zh-TW/claude-platform-on-aws)。51Microsoft Foundry 和 [AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws) 實作 Anthropic Messages 格式。Claude Code 透過自己的變數 `ANTHROPIC_FOUNDRY_BASE_URL` 和 `ANTHROPIC_AWS_BASE_URL` 路由到它們，但閘道在任一前面實作上述 Anthropic Messages 列。在 AWS 上的 Claude Platform 前面的閘道也必須轉發 `anthropic-workspace-id` 標頭，[該平台在每個請求上都需要](/docs/zh-TW/claude-platform-on-aws)。

52 52

53<h3 id="optional-endpoints-and-startup-traffic">53<h3 id="optional-endpoints-and-startup-traffic">

~~54 可選端點和啟動流量~~54 選用端點和啟動流量

55</h3>55</h3>

56 56

57令牌計數端點是唯一可選的：當它們不存在時，Claude Code 會改為通過推理端點回退到計數上下文使用情況。推理請求發佈到 `/v1/messages?beta=true`，因此請匹配路徑，而不是完整 URL。Google Cloud 的 Agent Platform 方法後綴附加到發佈者模型路徑，如 `/projects/{project}/locations/{location}/publishers/anthropic/models/{model}:streamRawPredict`。57計數令牌端點是唯一的選用端點：當它們不存在時，Claude Code 會回退到基於字元的內容使用估計。

58 58

59Gateway 也會看到最佳努力的啟動流量，它可以拒絕而不會破壞任何東西。Anthropic Messages 格式的 gateway 會收到 `HEAD /api/hello` 連接預熱探測，當配置了 HTTP 代理或用戶端憑證時，Claude Code 會跳過此探測。Amazon Bedrock 格式的 gateway 會收到 `GET /inference-profiles?type=SYSTEM_DEFINED` 請求，以及當配置的模型是推理設定檔時，`GET /inference-profiles/{profile}` 查詢。59根據路徑而非完整 URL 進行比對：

60 60

61[快速模式](/docs/zh-TW/fast-mode)可用性檢查永遠不會出現在 gateway 日誌中：它直接呼叫 `api.anthropic.com` 而不是遵循 `ANTHROPIC_BASE_URL`，因此在阻止直接出站到 `api.anthropic.com` 的網路上，快速模式可能會報告連線錯誤，而通過 gateway 的推理仍然可以正常工作。[WebFetch 網域安全檢查](/docs/zh-TW/data-usage#webfetch-domain-safety-check)也直接呼叫 `api.anthropic.com`。[在代理和 LLM gateway 後面使用快速模式](/docs/zh-TW/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)涵蓋了恢復它的變數。61* 推理請求發佈到 `/v1/messages?beta=true`

62* Google Cloud 的 Agent Platform 方法後綴附加到發佈者模型路徑，如 `/projects/{project}/locations/{location}/publishers/anthropic/models/{model}:streamRawPredict`

64閘道也會看到最佳努力啟動流量，可以拒絕而不會破壞任何東西。Anthropic Messages 格式的閘道會收到 `HEAD /api/hello` 連線預熱探測，當設定了 HTTP 代理或用戶端憑證時，Claude Code 會跳過此探測。Amazon Bedrock 格式的閘道會收到 `GET /inference-profiles?type=SYSTEM_DEFINED` 請求，以及當設定的模型是推理設定檔時，`GET /inference-profiles/{profile}` 查詢。

66[快速模式](/docs/zh-TW/fast-mode)可用性檢查永遠不會出現在閘道日誌中：它直接呼叫 `api.anthropic.com` 而不是遵循 `ANTHROPIC_BASE_URL`，因此在阻止直接出站到 `api.anthropic.com` 的網路上，快速模式可能會報告連線錯誤，而透過閘道的推理會繼續運作。[WebFetch 網域安全檢查](/docs/zh-TW/data-usage#webfetch-domain-safety-check)也直接呼叫 `api.anthropic.com`。[在代理和 LLM 閘道後面使用快速模式](/docs/zh-TW/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)涵蓋恢復它的變數。

62 67

63<h3 id="streaming">68<h3 id="streaming">

64 串流69 串流

65</h3>70</h3>

66 71

~~67串流推理回應。Claude Code 在接收時讀取串流，因此如果您的 gateway 在轉發完整回應之前進行緩衝，Claude Code 會停滯。~~72串流推理回應。Claude Code 在到達時讀取串流，因此如果您的閘道在轉發前緩衝完整回應，Claude Code 會停滯。

68 73

69當用戶端使用 Amazon Bedrock 格式時，轉發 `InvokeModelWithResponseStream` 回應體及其 `Content-Type: application/vnd.amazon.eventstream` 標頭不做修改，並且不要將串流轉換為伺服器發送事件。請參閱[在 gateway 或代理後面的串流錯誤](/docs/zh-TW/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)。74當用戶端使用 Amazon Bedrock 格式時，不修改地轉發 `InvokeModelWithResponseStream` 回應本體及其 `Content-Type: application/vnd.amazon.eventstream` 標頭，並且不要將串流轉換為伺服器發送事件。請參閱[在閘道或代理後面的串流錯誤](/docs/zh-TW/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)。

70 75

71也要轉發保活 ping。在通過 `ANTHROPIC_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 的連線上，Claude Code 計算您的 gateway 轉發的每一位元組，包括 SSE `ping` 事件和註解行，並在預設情況下中止 300 秒無聲的串流。上游的 ping 是長思考暫停期間唯一的流量，因此如果您的 gateway 移除或緩衝它們，Claude Code 會在這些暫停期間中止串流；[自動重試](/docs/zh-TW/errors#automatic-retries)涵蓋了根據回應進度有多遠而中止的串流報告的內容。完全不發送 ping 的上游（例如 Amazon Bedrock 的二進位事件串流）在這些暫停期間沒有任何東西可轉發。從這樣的上游進行轉換時，在無聲間隙期間發出您自己的 `ping` 事件。通過 `ANTHROPIC_BEDROCK_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_FOUNDRY_BASE_URL` 到達的 gateway 不受此位元組級監視程式的包裝，即使它們轉發 Anthropic Messages 格式；在那裡，[5 分鐘空閒逾時](/docs/zh-TW/env-vars)會改為中止無聲串流，在 `ANTHROPIC_BEDROCK_BASE_URL` 連線上，您可以使用 [`CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK`](/docs/zh-TW/env-vars) 新增位元組監視程式。76也轉發保活 ping。在透過 `ANTHROPIC_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 的連線上，Claude Code 計算您的閘道轉發的每個位元組，包括 SSE `ping` 事件和註解行，並預設在 300 秒內沒有流量的串流中止。上游的 ping 是長思考暫停期間唯一的流量，因此如果您的閘道移除或緩衝它們，Claude Code 會在這些暫停期間中止串流；[自動重試](/docs/zh-TW/errors#automatic-retries)涵蓋根據回應進度有多遠而中止的串流報告。完全不發送 ping 的上游（例如 Amazon Bedrock 的二進位事件串流）在這些暫停中沒有任何東西可轉發。從這樣的上游轉譯時，在無聲間隙期間發出您自己的 `ping` 事件。透過 `ANTHROPIC_BEDROCK_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_FOUNDRY_BASE_URL` 到達的閘道不會被此位元組級監視狗包裝，即使它們轉發 Anthropic Messages 格式；在那裡，[5 分鐘閒置逾時](/docs/zh-TW/env-vars)會改為中止無聲串流，在 `ANTHROPIC_BEDROCK_BASE_URL` 連線上，您可以使用 [`CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK`](/docs/zh-TW/env-vars) 新增位元組監視狗。

72 77

73<h3 id="format-mismatch-with-the-upstream">78<h3 id="format-mismatch-with-the-upstream">

74 與上游的格式不匹配79 與上游的格式不匹配

75</h3>80</h3>

76 81

~~77用戶端使用的格式決定了您的 gateway 接收的內容。常見的失敗模式是用戶端發送給您的 gateway 的格式與其後面的上游提供者接受的格式不匹配。~~82用戶端使用的格式決定了您的閘道接收的內容。常見的失敗模式是用戶端發送到您的閘道的格式與其後面的上游提供者接受的格式不匹配。

78 83

79* 當用戶端使用 Amazon Bedrock 或 Google Cloud 的 Agent Platform 格式時，Claude Code 只發送那些提供者接受的完整功能集的子集84* 當用戶端使用 Amazon Bedrock 或 Google Cloud 的 Agent Platform 格式時，Claude Code 只發送那些提供者接受的完整功能集的子集

~~80* 當用戶端使用 Anthropic Messages 格式時，Claude Code 發送完整集合，即使您的 gateway 轉發到 Amazon Bedrock 或 Google Cloud 的 Agent Platform 上游~~85* 當用戶端使用 Anthropic Messages 格式時，Claude Code 發送完整集，即使您的閘道轉發到 Amazon Bedrock 或 Google Cloud 的 Agent Platform 上游

81 86

~~82橋接該差異是您的 gateway 的工作。[功能傳遞](#feature-pass-through)描述了當它不這樣做時會發生什麼。~~87橋接該差異是您的閘道的工作。[功能傳遞](#feature-pass-through)描述當它不這樣做時會破壞什麼。

83 88

84<h2 id="request-headers">89<h2 id="request-headers">

85 請求標頭90 請求標頭

152| 測試版[工具欄位](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) | 工具相關的測試版標頭與工具架構欄位（如 `strict` 和 `defer_loading`）配對 | 當請求體在沒有其標頭的情況下通過時，命名無法識別的工具架構欄位的 `400` | 轉發兩者，或 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](#disable-pre-release-capabilities) |157| 測試版[工具欄位](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) | 工具相關的測試版標頭與工具架構欄位（如 `strict` 和 `defer_loading`）配對 | 當請求體在沒有其標頭的情況下通過時，命名無法識別的工具架構欄位的 `400` | 轉發兩者，或 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](#disable-pre-release-capabilities) |

153| [努力](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` | 一起轉發欄位及其標頭 |158| [努力](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` | 一起轉發欄位及其標頭 |

154| [提示詞快取](/docs/zh-TW/prompt-caching) | 無測試版配對。Claude Code 將 `cache_control` 標記附加到 `system` 區塊和 `messages` 項目，包括在對話中途附加的 `role: "system"` 項目 | 無錯誤：對話在每個回合上都計費為未快取的輸入，在 `usage` 中可見為高 `input_tokens` 且很少或沒有快取活動 | 無論在何處出現，都逐字轉發 `cache_control`，並且不要將區塊形式的 `system` 或訊息內容轉換為純字串 |159| [提示詞快取](/docs/zh-TW/prompt-caching) | 無測試版配對。Claude Code 將 `cache_control` 標記附加到 `system` 區塊和 `messages` 項目，包括在對話中途附加的 `role: "system"` 項目 | 無錯誤：對話在每個回合上都計費為未快取的輸入，在 `usage` 中可見為高 `input_tokens` 且很少或沒有快取活動 | 無論在何處出現，都逐字轉發 `cache_control`，並且不要將區塊形式的 `system` 或訊息內容轉換為純字串 |

156 161

157`ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES` [變數](/docs/zh-TW/model-config)僅在提供者配置中聲明模型功能：`CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_VERTEX`、`CLAUDE_CODE_USE_FOUNDRY` 和 [`CLAUDE_CODE_USE_MANTLE`](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint)。它們在 `ANTHROPIC_BASE_URL` gateway 後面沒有效果。162`ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES` [變數](/docs/zh-TW/model-config)僅在提供者配置中聲明模型功能：`CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_VERTEX`、`CLAUDE_CODE_USE_FOUNDRY` 和 [`CLAUDE_CODE_USE_MANTLE`](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint)。它們在 `ANTHROPIC_BASE_URL` gateway 後面沒有效果。

158 163

160 自動重試和錯誤轉發165 自動重試和錯誤轉發

161</h3>166</h3>

162 167

163當上游拒絕 `thinking` 欄位、[思考簽名](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)、中途對話系統訊息或這些訊息之一上的 `cache_control` 標記時，Claude Code 會重試請求並為對話的其餘部分禁用被拒絕的功能。Claude Code 不會重試上下文管理或工具架構欄位拒絕；這些 `400` 錯誤會到達開發人員。168Claude Code 在上游拒絕後的行為取決於被拒絕的內容：

169

170* 當上游拒絕 `thinking` 欄位、中途對話系統訊息或這類訊息上的 `cache_control` 標記時，Claude Code 會重試請求並為對話的其餘部分禁用被拒絕的功能

171* 當上游拒絕[思考簽名](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)時，Claude Code 會重試請求而不包含對話的較早思考區塊，並將它們排除在每個後續請求之外。新回應仍包含思考

172* Claude Code 不會重試上下文管理或工具架構欄位的拒絕，因此這些 `400` 錯誤會到達開發人員

164 173

165重試邏輯與上游的錯誤措辭相匹配，因此不修改地轉發錯誤回應體。在自己的信封中包裝上游錯誤的 gateway 會破壞恢復路徑，即使它保留了狀態碼，除非信封的訊息攜帶穩定的 `capability_rejected:` 令牌。[Claude 應用程式 gateway 為雲端提供者的錯誤措辭替換這些令牌](/docs/zh-TW/claude-apps-gateway-config#upstream-error-messages)，例如 `capability_rejected: prompt_too_long`。174重試邏輯與上游的錯誤措辭相匹配，因此不修改地轉發錯誤回應體。在自己的信封中包裝上游錯誤的 gateway 會破壞恢復路徑，即使它保留了狀態碼，除非信封的訊息攜帶穩定的 `capability_rejected:` 令牌。[Claude 應用程式 gateway 為雲端提供者的錯誤措辭替換這些令牌](/docs/zh-TW/claude-apps-gateway-config#upstream-error-messages)，例如 `capability_rejected: prompt_too_long`。

166 175

llm-gateway-rollout.md +1 −1

Details

207 207

208將表中的條件變數新增到相同的 `env` 區塊。受管 `ANTHROPIC_BASE_URL` 被強制執行，無法被開發者的殼層匯出覆蓋，因為 Claude Code 在程序環境和較低優先順序設定上應用它。208將表中的條件變數新增到相同的 `env` 區塊。受管 `ANTHROPIC_BASE_URL` 被強制執行，無法被開發者的殼層匯出覆蓋，因為 Claude Code 在程序環境和較低優先順序設定上應用它。

209 209

210不要在受管設定中包括 `forceLoginMethod` 或 `forceLoginOrgUUID` 以及閘道認證。任一金鑰在啟動時阻止 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 和 `apiKeyHelper`，因此開發者看到 `This machine's managed settings require a first-party login` 並無法繼續。210不要在受管設定中包括 `forceLoginMethod` 或 `forceLoginOrgUUID` 以及閘道認證。任一金鑰在啟動時阻止 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 和 `apiKeyHelper`，開發者無法繼續。他們看到 `This machine's managed settings require a first-party login`，或在 `"gateway"` 值下看到 [`Administrator policy requires a Cloud gateway sign-in`](/docs/zh-TW/errors#administrator-policy-requires-a-cloud-gateway-sign-in)。

211 211

212[伺服器受管設定](/docs/zh-TW/server-managed-settings#platform-availability)傳遞需要直接連接到 `api.anthropic.com`，因此無法到達閘道路由的工作階段。閘道部署使用此檔案型受管設定路徑，它強制執行相同的金鑰。212[伺服器受管設定](/docs/zh-TW/server-managed-settings#platform-availability)傳遞需要直接連接到 `api.anthropic.com`，因此無法到達閘道路由的工作階段。閘道部署使用此檔案型受管設定路徑，它強制執行相同的金鑰。

213 213

managed-settings.md +445 −0 created

Details

1> ## Documentation Index

2> 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.

5# 部署受管設定

7> 將受管設定部署到每個開發者的機器：每個作業系統的傳遞機制、Claude Code 如何結合受管來源，以及如何驗證強制執行。

9受管設定是您的組織部署到每個開發者機器的設定。Claude Code 將它們應用於所有其他層級之上，因此沒有使用者、專案、本機或 `--settings` 值可以覆蓋它們，除了少數[安全敏感的例外](/docs/zh-TW/settings#exceptions-to-managed-settings-precedence)，其中來自較低層級的更嚴格值仍然適用。

11本頁面適用於部署受管設定或偵錯為什麼某個設定未應用的管理員。若要決定要強制執行什麼，請從[決定要強制執行什麼](/docs/zh-TW/admin-setup#decide-what-to-enforce)表開始。如需 claude.ai 主控台路徑，請參閱[伺服器受管設定](/docs/zh-TW/server-managed-settings)。如需開發者自己的值放在哪個檔案中，請參閱[設定](/docs/zh-TW/settings)。

13<h2 id="deploy-a-managed-settings-file">

14 部署受管設定檔案

15</h2>

17這是在每台機器上放置原則的最快方式：一個 `managed-settings.json` 檔案。如果您還沒有選擇如何傳遞受管設定，或您的裝置在 MDM 下或開發者執行雲端工作階段，請先閱讀[選擇傳遞機制](#choose-a-delivery-mechanism)。

19<Steps>

20 <Step title="編寫 managed-settings.json">

21 編寫一個 `managed-settings.json`，其中包含您決定要強制執行的金鑰，採用與 `settings.json` 相同的 JSON 形狀。[決定要強制執行什麼](/docs/zh-TW/admin-setup#decide-what-to-enforce)表列出每個控制項後面的金鑰，[設定參考](/docs/zh-TW/settings-reference)中的每個項目都說明受管來源是否可以設定它。此檔案會阻止兩個檔案讀取、關閉略過模式，並使 Claude Code 忽略來自使用者、專案和本機檔案以及 `--allowedTools` 的權限規則：

23 ```json managed-settings.json theme={null}

24 {

25 "permissions": {

26 "deny": [

27 "Read(./.env)",

28 "Read(./secrets/**)"

29 ],

30 "disableBypassPermissionsMode": "disable"

31 },

32 "allowManagedPermissionRulesOnly": true

33 }

34 ```

36 如需顯示更多受管金鑰形狀的更完整範例，包括登入方法、模型、MCP 伺服器和市場，請參閱[組織的受管設定](/docs/zh-TW/settings-example#an-organizations-managed-settings)。

37 </Step>

39 <Step title="將檔案放在每台機器上">

40 使用已經在您的機隊上放置檔案的任何工具，將檔案儲存為 `managed-settings.json` 在作業系統的系統目錄中：

42 * **macOS**: `/Library/Application Support/ClaudeCode/managed-settings.json`

43 * **Linux 和 WSL**: `/etc/claude-code/managed-settings.json`

44 * **Windows**: `C:\Program Files\ClaudeCode\managed-settings.json`

45 </Step>

47 <Step title="確認原則已應用">

48 在一台機器上，在 Claude Code 內執行 `/status`。`Setting sources` 行顯示 `Enterprise managed settings (file)`。在此之後推出到機隊的其餘部分；當該行遺失時，[檢查原則是否有效](#check-that-a-policy-is-in-force)涵蓋要查看的內容。

49 </Step>

50</Steps>

52<span id="managed-settings-delivery" />

54<span id="delivery-mechanisms" />

56<h2 id="choose-a-delivery-mechanism">

57 選擇傳遞機制

58</h2>

60上述步驟中的檔案是將受管設定放到機器上的四種方式之一。每個機制都帶有與 `settings.json` 檔案相同的原則金鑰，因此[設定參考](/docs/zh-TW/settings-reference)適用於所有機制。少數金鑰與特定來源相關聯，每個項目的 Scope 行說明哪些：

62* **傳遞控制項**：[`policyHelper`](/docs/zh-TW/settings-reference#policyhelper)、[`wslInheritsWindowsSettings`](/docs/zh-TW/settings-reference#wslinheritswindowssettings) 和 [`managedSourcesBehavior`](/docs/zh-TW/settings-reference#managedsourcesbehavior)

63* **閘道登入金鑰**：[`forceLoginGatewayUrl`](/docs/zh-TW/settings-reference#forcelogingatewayurl) 和 [`forceLoginMethod`](/docs/zh-TW/settings-reference#forceloginmethod) 的 `"gateway"` 值

65受管設定檔案、MDM 設定檔或 claude.ai 主控台對其到達的每個人應用一個原則。若要為一組開發者提供不同的原則，請將不同的檔案或設定檔部署到該組；claude.ai 主控台[還不能針對一個群組](/docs/zh-TW/server-managed-settings#current-limitations)，而自託管[Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway)按 IdP 群組傳遞受管設定。

67當多個機制將原則傳遞到同一台機器時，Claude Code 預設使用一個並忽略其他機制。[Claude Code 如何結合受管來源](#how-claude-code-combines-managed-sources)給出順序和適用於每個來源的選擇加入。

69MDM 和檔案行一起稱為端點受管設定，因為原則儲存在開發者的裝置上，而不是伺服器受管行，其中 Claude Code 會擷取它。

71使用下表根據您已經管理裝置的方式選擇機制。

73| 機制 | 您如何傳遞它 | Claude Code 何時讀取它 | 何時使用 |

74| :---------------------------------------- | :-------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------ | :----------------------------------- |

78| HKCU 登錄、Windows 和 WSL | 作為 Windows `HKCU` 登錄值；請參閱[每個機制儲存原則的位置](#where-each-mechanism-stores-the-policy) | 在啟動時讀取並每 30 分鐘檢查一次變更；Claude Code 僅在沒有其他受管來源傳遞原則金鑰且沒有[主機提供的父設定](#let-an-embedding-host-add-policy)提供限制性金鑰時才使用它 | 您無法寫入機器層級 `HKLM` 金鑰 |

80Jamf、Iru、Intune 和群組原則的入門範本位於 [MDM 範例儲存庫](https://github.com/anthropics/claude-code/tree/main/examples/mdm)。

82對於受管 MCP 伺服器，您可以透過 `managed-mcp.json` 與這些伺服器一起部署或透過 [`managedMcpServers`](/docs/zh-TW/settings-reference#managedmcpservers) 金鑰提供，請參閱[受管 MCP 設定](/docs/zh-TW/managed-mcp)。

84<h3 id="where-and-when-a-policy-applies">

85 原則應用的位置和時間

86</h3>

88部署的原則到達開發者的工作階段如下：

90* **表面**：在開發者的機器上，終端機、VS Code 和 JetBrains 擴充功能、桌面應用程式的 Code 標籤和 [Agent SDK](/docs/zh-TW/agent-sdk/typescript) 工作階段讀取所有這些來源。Agent SDK 工作階段即使在 `settingSources` 排除使用者、專案和本機檔案時也會載入受管設定。

91* **雲端工作階段**：Anthropic 託管環境中的工作階段不會讀取裝置的 MDM 設定檔或檔案，因此其原則必須來自伺服器受管設定。[自託管環境](/docs/zh-TW/self-hosted-environments)中的工作階段也會讀取其執行器映像中的受管設定檔案，預設情況下僅當伺服器受管設定不傳遞原則金鑰時，除了 [Claude Code 從每個管理來源讀取的金鑰](#keys-read-from-every-admin-source)。[Claude Code 如何結合受管來源](#how-claude-code-combines-managed-sources)涵蓋適用於兩者的選擇加入。

92* **共同工作工作階段**：Claude Desktop 應用程式中的 [Cowork](https://claude.com/docs/cowork/overview) 在 Claude Code 上執行其工作階段。在共同工作工作階段中，Claude Code 永遠不會從 claude.ai 管理主控台擷取伺服器受管設定，即使使用者使用團隊或企業帳戶登入，因此適用的原則取決於工作階段執行的位置：

94 * **在使用者的機器上**：預設情況下，共同工作工作階段中的 Claude Code 讀取該裝置上的 MDM 或作業系統層級原則和受管設定檔案，因此在那裡部署原則。

95 * **在完整 VM 沙箱中**：當您的 Claude Desktop 受管設定將 [`requireCoworkFullVmSandbox`](https://claude.com/docs/third-party/claude-desktop/configuration#requirecoworkfullvmsandbox) 設定時，Claude Code 在虛擬機器內執行，其中裝置的 MDM 原則和受管設定檔案不存在。

96 * **遠端共同工作工作階段**：這些在 Anthropic 受管 VM 上執行，其中 Claude Code 沒有裝置原則可讀取。

98 [表面涵蓋](/docs/zh-TW/model-config#surface-coverage)表比較共同工作與其他表面。

99* **執行中的工作階段**：大多數變更在[傳遞機制表](#choose-a-delivery-mechanism)中的排程上到達執行中的工作階段，無需重新啟動。

100 * 對 [`forceRemoteSettingsRefresh`](/docs/zh-TW/settings-reference#forceremotesettingsrefresh)、[`requiredMinimumVersion`](/docs/zh-TW/settings-reference#requiredminimumversion) 和[某些使用者可編輯的金鑰](/docs/zh-TW/settings#when-edits-take-effect)的變更在下一個工作階段啟動時生效。

101 * 新的或變更的 [`policyHelper`](/docs/zh-TW/settings-reference#policyhelper) 項目在下一次啟動時生效。如果伺服器受管設定在該啟動時遮蔽協助程式，協助程式會在擷取報告這些設定已移除時立即執行。

102* **需要批准的變更**：除了[等待下一次啟動的更新](/docs/zh-TW/server-managed-settings#fetch-and-caching-behavior)，伺服器受管變更到[需要批准](/docs/zh-TW/server-managed-settings#security-approval-dialogs)的設定，例如掛鉤或 `env` 變數，等待開發者在互動式工作階段中接受對話，並在 IDE 擴充功能或 Agent SDK 託管的工作階段中應用於目前執行。其他伺服器受管變更在下一次輪詢時應用。

103* **長期執行的工作階段**：保持開啟數週的工作階段仍然可能滯後於推出。[`requiredMinimumVersion`](/docs/zh-TW/settings-reference#requiredminimumversion) 阻止過時的二進位檔啟動，不會結束已在執行的工作階段。

104

105<span id="format-the-policy-for-each-platform" />

106

107<h3 id="where-each-mechanism-stores-the-policy">

108 每個機制儲存原則的位置

109</h3>

110

111金鑰在任何地方都是相同的，但每個機制以不同的位置和形狀儲存它們：

112

113* **伺服器受管**：Anthropic 的伺服器或您的閘道持有原則。Claude Code 保留一個本機快取，在啟動時應用它，並在[每次成功擷取時替換](/docs/zh-TW/server-managed-settings#security-considerations)。

114* **macOS 設定設定檔**：`com.anthropic.claudecode` 受管偏好設定網域。使用與 `managed-settings.json` 相同的頂層金鑰，嵌套設定為字典，列表為 plist 陣列。

115* **Windows HKLM 登錄**：JSON 作為 `HKLM\SOFTWARE\Policies\ClaudeCode` 下名為 `Settings` 的 `REG_SZ` 或 `REG_EXPAND_SZ` 值。

116* **基於檔案**：`managed-settings.json`、可選的 `managed-settings.d/` 目錄和 `managed-mcp.json` 在系統目錄中：macOS 上的 `/Library/Application Support/ClaudeCode/`、Linux 和 WSL 上的 `/etc/claude-code/`，以及 Windows 上的 `C:\Program Files\ClaudeCode\`。Claude Code 不讀取舊版 Windows 路徑 `C:\ProgramData\ClaudeCode\managed-settings.json`。

117* **Windows HKCU 登錄**：`HKCU\SOFTWARE\Policies\ClaudeCode` 下相同的 `Settings` 值。

118

119<h3 id="split-a-file-based-policy-across-teams">

120 跨團隊分割基於檔案的原則

121</h3>

122

123如果多個團隊擁有一個原則的部分，請將每個部分放在 `managed-settings.d/` 中的自己的檔案中，位於與 `managed-settings.json` 相同的系統目錄旁邊，而不是編輯一個共享檔案。

124

125Claude Code 首先合併 `managed-settings.json`，然後按字母順序合併目錄中的每個 `*.json` 檔案。使用數字前綴命名檔案以控制順序，例如 `10-telemetry.json` 和 `20-security.json`。Claude Code 忽略隱藏檔案和不以 `.json` 結尾的檔案。

126

127當兩個檔案設定相同的金鑰時，Claude Code 按這些規則合併它們：

128

129* **單一值**，例如 `"model": "opus"` 或 `"cleanupPeriodDays": 7`：較晚檔案的值替換較早的值

130* **列表**，例如 `permissions.deny` 或 `sandbox.network.allowedDomains`：兩個列表合併，移除重複項

131* **嵌套區塊**，例如 `env` 或 `sandbox`：兩個區塊按金鑰合併，每個金鑰內遵循這些相同的規則

132* **`fallbackModel`**：較晚的鏈完整替換較早的鏈

133* **[`extraKnownMarketplaces`](/docs/zh-TW/settings-reference#extraknownmarketplaces) 和 [`managedMcpServers`](/docs/zh-TW/settings-reference#managedmcpservers)**：具有相同名稱的較晚項目完整替換較早的項目

134* **[`modelPicker`](/docs/zh-TW/settings-reference#modelpicker)**：較晚的陣容完整替換較早的陣容

135

136<span id="precedence-within-the-managed-tier" />

137

138<span id="which-managed-source-claude-code-uses" />

139

140<h2 id="how-claude-code-combines-managed-sources">

141 Claude Code 如何結合受管來源

142</h2>

143

144當您的組織將多個受管來源傳遞到同一台機器時，[`managedSourcesBehavior`](/docs/zh-TW/settings-reference#managedsourcesbehavior) 金鑰決定 Claude Code 對其他來源的處理方式：

145

146* **`"first-wins"`，預設值**：Claude Code 使用傳遞至少一個原則金鑰的最高排名來源，並忽略其餘來源，而不是合併它們，除了[從每個管理來源讀取的金鑰](#keys-read-from-every-admin-source)中的少數金鑰。Claude Code 對它跳過的來源不顯示警告；`/status` [命名它使用的來源和它跳過的來源](#read-the-source-in-/status)。

147* **`"merge"`**：Claude Code 應用傳遞原則金鑰的每個管理來源，並按金鑰類型合併它們：在大多數金鑰上，最高排名來源的值適用，列表聯合，鎖定採用最嚴格的值。[組成每個受管來源](#compose-every-managed-source)說明在哪裡設定金鑰以及每種金鑰類型如何合併。需要 Claude Code v2.1.242 或更新版本。

148

149兩個設定以相同的方式排名來源。本節中重複出現兩個術語：

150

151* **原則金鑰**：除了兩個控制金鑰 [`wslInheritsWindowsSettings`](/docs/zh-TW/settings-reference#wslinheritswindowssettings) 和 [`managedSourcesBehavior`](/docs/zh-TW/settings-reference#managedsourcesbehavior) 之外的任何設定金鑰。只包含這些的受管設定檔案或 MDM 原則不計算，Claude Code 移動到下一個來源。

152* **管理來源**：下面前三個來源之一。HKCU 登錄是使用者可寫的，不是一個。

153

154Claude Code 按此順序檢查來源，最高優先順序優先：

155

1561. 遠端設定，從 claude.ai 作為[伺服器受管設定](/docs/zh-TW/server-managed-settings)或由[Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway)傳遞。Claude Code 僅在工作階段使用[符合條件的登入或金鑰](/docs/zh-TW/server-managed-settings#platform-availability)直接向 Anthropic 的 API 驗證，或使用 `/login` 登入閘道時擷取此來源。在其他提供者上，或當 `ANTHROPIC_BASE_URL` 指向 Anthropic 的 API 以外的地方時，它從下一個來源開始

1572. MDM 或作業系統層級原則：macOS plist 或 HKLM 登錄金鑰

1583. 受管設定檔案，`managed-settings.d/*.json` 和 `managed-settings.json` 合併在一起

1594. HKCU 登錄，在 Windows 上，以及在 WSL 上，一旦 HKLM 登錄或 Windows 受管設定檔案開啟 [`wslInheritsWindowsSettings`](/docs/zh-TW/settings-reference#wslinheritswindowssettings) 並且 HKCU 值也設定它。Claude Code 僅在沒有上面的來源傳遞原則金鑰且沒有[主機提供的父設定](#let-an-embedding-host-add-policy)提供限制性金鑰時讀取它

160

161此圖表顯示排名，以及 Claude Code 在任一設定下從前三個來源讀取的跨來源金鑰的範例：

162

163<img src="https://mintcdn.com/claude-code/zuWID2B-Rxm8DEC8/images/managed-source-precedence.svg?fit=max&auto=format&n=zuWID2B-Rxm8DEC8&q=85&s=53f6be49f06eff48e01422c8ae1bc2e6" className="dark:hidden" alt="圖表顯示四個受管設定來源，從頂部的遠端設定排名到 MDM、受管設定檔案和底部的 HKCU 登錄。預設情況下，具有原則金鑰的第一個來源提供原則，其餘的被跳過；將 managedSourcesBehavior 設定為合併時，每個具有原則金鑰的管理來源都有貢獻，按金鑰類型合併，HKCU 登錄保持不變。側面板顯示跨來源金鑰，例如沙箱鎖、forceRemoteSettingsRefresh 和每個變數 env 合併，從每個管理來源讀取，不包括 HKCU 登錄。" width="680" height="330" data-path="images/managed-source-precedence.svg" />

164

165<img src="https://mintcdn.com/claude-code/zuWID2B-Rxm8DEC8/images/managed-source-precedence-dark.svg?fit=max&auto=format&n=zuWID2B-Rxm8DEC8&q=85&s=ae407a9a08a3d680e80cf1a2af845d71" className="hidden dark:block" alt="圖表顯示四個受管設定來源，從頂部的遠端設定排名到 MDM、受管設定檔案和底部的 HKCU 登錄。預設情況下，具有原則金鑰的第一個來源提供原則，其餘的被跳過；將 managedSourcesBehavior 設定為合併時，每個具有原則金鑰的管理來源都有貢獻，按金鑰類型合併，HKCU 登錄保持不變。側面板顯示跨來源金鑰，例如沙箱鎖、forceRemoteSettingsRefresh 和每個變數 env 合併，從每個管理來源讀取，不包括 HKCU 登錄。" width="680" height="330" data-path="images/managed-source-precedence-dark.svg" />

166

167<h3 id="keys-read-from-every-admin-source">

168 從每個管理來源讀取的金鑰

169</h3>

170

171在預設 `"first-wins"` 設定下，Claude Code 僅從[它選擇的來源](#how-claude-code-combines-managed-sources)讀取大多數金鑰，並忽略較低排名來源中的值，即使選定的來源未設定該金鑰。

172

173少數金鑰的工作方式不同。Claude Code 從每個管理來源讀取它們，因此當選定的來源不設定時，較低排名的 MDM 原則或受管設定檔案仍然可以設定它們。Claude Code 將使用者可寫的 HKCU 登錄排除在該掃描之外；當 HKCU 是唯一的來源且沒有主機提供父設定時，HKCU 應用就像任何選定的來源。

174

175跨來源金鑰包括：

176

177* `sandbox.network.allowManagedDomainsOnly` 和 `sandbox.filesystem.allowManagedReadPathsOnly`：任何管理來源中的 `true` 開啟鎖定。當鎖定開啟時，Claude Code 聯合它鎖定的允許清單，`sandbox.network.allowedDomains` 與 `WebFetch(domain:...)` 允許規則，或 `sandbox.filesystem.allowRead`，跨每個管理來源。沒有鎖定，Claude Code 將允許清單視為任何其他金鑰，因此在 `"first-wins"` 下，未選定的管理來源的允許清單被忽略

178* `allowAllClaudeAiMcps`

179* 沙箱二進位路徑 `sandbox.bwrapPath` 和 `sandbox.socatPath`

180* 沙箱 `ripgrep` 二進位，[`sandbox.ripgrep`](/docs/zh-TW/settings-reference#sandbox-ripgrep)

181* `sandbox.filesystem.disabled` 和 `sandbox.network.strictAllowlist`

182* [`useAutoModeDuringPlan`](/docs/zh-TW/settings-reference#useautomodeduringplan) 和 [`syncClaudeAiSkills`](/docs/zh-TW/settings-reference#syncclaudeaiskills)，其中任何管理來源的 `false` 關閉行為。開發者的使用者或本機設定中的 `false` 也關閉它；每個金鑰只能拒絕

183* [`enableArtifact`](/docs/zh-TW/settings-reference#enableartifact)，其中任何管理來源的 `false` 關閉 [Artifact 工具](/docs/zh-TW/artifacts)。開發者的使用者、專案或本機設定中的 `false` 也關閉它，沒有來源將其打開；請參閱[哪些較低層級的值仍然計算](/docs/zh-TW/settings#exceptions-to-managed-settings-precedence)。需要 Claude Code v2.1.242 或更新版本

184* [`maxEffortLevel`](/docs/zh-TW/settings-reference#maxeffortlevel)，其中任何管理來源中的最低上限適用。如果開發者在自己的設定或 `--settings` 中設定較低的上限，Claude Code 應用那個；沒有來源可以提高上限。需要 Claude Code v2.1.267 或更新版本

185* `attribution` 中的提交預告片選擇退出，或在已棄用的 `includeCoAuthoredBy` 中，來自任何層級

186* [`forceRemoteSettingsRefresh`](/docs/zh-TW/server-managed-settings)

187* `env`，跨管理來源按變數合併：每個變數來自定義它的最高優先順序來源，因此較低來源填充較高來源未設定的變數。少數變數遵循自己的規則；[跨受管來源的每個金鑰例外](/docs/zh-TW/server-managed-settings#per-key-exceptions-across-managed-sources)命名每個。需要 Claude Code v2.1.223 或更新版本。在 v2.1.223 之前，Claude Code 僅應用選定來源的整個 `env` 區塊

188

189<h3 id="compose-every-managed-source">

190 組成每個受管來源

191</h3>

192

193若要讓 Claude Code 應用您的組織傳遞的每個管理來源，請在您部署的最高排名來源中將 [`managedSourcesBehavior`](/docs/zh-TW/settings-reference#managedsourcesbehavior) 設定為 `"merge"`。Claude Code 僅從攜帶金鑰或原則金鑰的最高排名來源讀取金鑰，因此較低來源無法選擇自己合併到上面的來源，並且從不接收伺服器受管設定的機器也需要其 MDM 設定檔中的金鑰。使用者可寫的 HKCU 登錄永遠不會與另一個來源合併。需要 Claude Code v2.1.242 或更新版本。

194

195在 `"merge"` 下，Claude Code 添加較低來源的列表項目，例如 `permissions.allow` 規則和掛鉤，到原則，因此僅在您最高排名來源下排名的每個來源都在管理員的控制下時才開啟它。

196

197此表顯示 Claude Code 在 `"merge"` 下如何組合每種金鑰。[`managedSourcesBehavior` 項目](/docs/zh-TW/settings-reference#managedsourcesbehavior)命名限制允許清單、值取整和最高來源僅行中的每個金鑰。

198

199| 金鑰類型 | Claude Code 如何組合它 | 範例 |

200| :------------ | :--------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------- |

201| 列表 | 組合來自每個來源的項目 | `permissions.allow`、`hooks`、`sandbox.network.allowedDomains`、`deniedMcpServers` |

202| 鎖定 | 應用任何來源設定的最嚴格值；較寬鬆的值僅從最高排名來源應用 | `allowManagedHooksOnly`、`permissions.disableBypassPermissionsMode`、`crossSessionInbound` |

203| 限制允許清單 | 從設定它的最高排名來源取整個列表，不添加來自較低來源的項目 | `availableModels`、`allowedMcpServers`、`strictKnownMarketplaces`、`allowedChannelPlugins` 和 `fallbackModel` 鏈 |

204| 值取整 | 從設定它的最高排名來源取整個值，不組合來自較低來源的項目或欄位 | `sandbox.credentials.awsPairs`、`sandbox.ripgrep` |

205| 提供的 MCP 伺服器 | 組合來自每個來源的伺服器名稱；當兩個來源設定相同的名稱時，應用最高排名來源的整個項目 | `managedMcpServers` |

206| 僅從最高排名來源讀取的金鑰 | 忽略每個較低來源中的金鑰，即使最高排名來源未設定它 | 認證協助程式，例如 `apiKeyHelper`、登入 pin，例如 `forceLoginOrgUUID`、`modelPicker`、`permissions.defaultMode` |

207| `env` | 在任一設定下跨管理來源按變數合併，如[從每個管理來源讀取的金鑰](#keys-read-from-every-admin-source)所述 | |

208| 每個其他金鑰 | 從設定它的最高排名來源取值 | `model`、`cleanupPeriodDays` |

209

210若要確認機器上組合了哪些來源，請[讀取 `/status` 中的 `Setting sources` 行](#read-the-source-in-/status)；該部分說明每個標籤的含義。

211

212<h3 id="compute-the-policy-with-a-helper-program">

213 使用協助程式程式計算原則

214</h3>

215

216[`policyHelper`](/docs/zh-TW/settings-reference#policyhelper) 是您的 MDM 原則或受管設定檔案命名的可執行檔，Claude Code 在啟動時執行它以計算受管設定。當選定的來源配置一個並且協助程式發出 `managedSettings` 物件時，該輸出改變 Claude Code 讀取的內容：

217

218* **發出的 `managedSettings` 物件是工作階段的唯一受管設定**，包括[它以其他方式從每個管理來源讀取的金鑰](#keys-read-from-every-admin-source)，除了[`forceRemoteSettingsRefresh`，它有自己的啟動規則](/docs/zh-TW/settings-reference#forceremotesettingsrefresh)

219

220如需協助程式執行失敗的情況以及 Claude Code 在執行失敗時的處理方式，請參閱[協助程式失敗](/docs/zh-TW/settings-reference#helper-failures)。

221

222<span id="parent-settings-from-embedding-hosts" />

223

224<span id="control-policy-from-an-embedding-host" />

225

226<span id="merge-policy-from-an-embedding-host" />

227

228<h3 id="let-an-embedding-host-add-policy">

229 讓嵌入主機添加原則

230</h3>

231

232當另一個應用程式啟動 Claude Code 時，例如 Claude Desktop、IDE 擴充功能或 Agent SDK 應用程式，該主機可以透過 SDK `managedSettings` 選項傳遞自己的受管設定。Claude Code 將這些稱為父設定。

233

234預設情況下，只要存在管理來源，Claude Code 就會忽略父設定：伺服器受管設定、MDM 或作業系統層級原則或受管設定檔案。

235

236若要讓 Claude Code 將父設定與管理來源合併，請在最高優先順序受管來源中將 [`parentSettingsBehavior`](/docs/zh-TW/settings-reference#parentsettingsbehavior) 設定為 `"merge"`；Claude Code 僅從該來源讀取金鑰。

237

238Claude Code 然後僅保留主機限制 Claude 可以做什麼的值，有一個要知道的間隙：除非您也設定 `allowManaged*Only` 鎖定，主機的權限允許規則和沙箱允許清單仍然適用。請參閱[限制父設定](/docs/zh-TW/claude-apps-gateway#restrict-parent-settings)以了解鎖定。

239

240[`policyHelper`](/docs/zh-TW/settings-reference#policyhelper) 可以關閉父合併，無論此金鑰如何；其項目說明何時。

241

242Claude Code 也將這些檢查應用於父提供的值本身：

243

244* 當任何管理來源設定 `allowManagedPermissionRulesOnly` 時，Claude Code 在讀取時刪除[父提供的](/docs/zh-TW/claude-apps-gateway#restrict-parent-settings)權限允許規則和 `additionalDirectories`，即使較高優先順序來源未設定金鑰。金鑰對您自己的權限規則的影響來自 Claude Code 應用的受管設定，或來自您選擇合併的父設定

245* Claude Code 強制執行它應用的受管設定中的 `forceLoginOrgUUID` 或 `allowedMcpServers` 值，並阻止父提供的值。較低管理來源中的值，Claude Code 不應用既不應用也不阻止父的值。[`managedSourcesBehavior`](/docs/zh-TW/settings-reference#managedsourcesbehavior) 項目說明在 `"merge"` 下哪個來源提供每個金鑰。在 v2.1.223 之前，任何管理來源中的值阻止父的值

246* `availableModels` 值遵循與 `allowedMcpServers` 相同的規則

247

248<h4 id="keep-cowork-folder-access-when-only-managed-rules-apply">

249 當僅應用受管規則時保持 Cowork 資料夾存取

250</h4>

251

252Claude Desktop 應用程式中的 [Cowork](https://claude.com/docs/cowork/overview) 在 Claude Code 上執行其工作階段，並透過在啟動工作階段時提供的允許規則授予每個工作階段對其工作資料夾（例如使用者連接的資料夾）的存取權。當您的受管原則設定 [`allowManagedPermissionRulesOnly`](/docs/zh-TW/settings-reference#allowmanagedpermissionrulesonly) 時，Claude Code 僅保留受管原則中的允許規則：它刪除主機作為父設定提供的允許規則、`--allowedTools` 或設定檔案中的允許規則，因此對這些資料夾的寫入失去其預先批准。在要求編輯前的 Cowork 工作階段中，Cowork 無法顯示提示，Claude 將每次寫入報告為被阻止，因為路徑解析為受保護的位置或連接資料夾外的路徑。

253

254若要恢復寫入，請為這些資料夾添加允許規則到 Claude Code [選擇](#precedence-within-the-managed-tier)的受管來源在這些機器上：在 MDM 受管機隊上，那是 MDM 原則而不是單獨的受管設定檔案。此範例使用檔案形式，MDM 原則採用相同的金鑰。它保持 `allowManagedPermissionRulesOnly` 設定並允許在每個使用者主目錄中的 `CoworkProjects` 資料夾下編輯；將路徑替換為您的使用者連接的資料夾：

255

256```json managed-settings.json theme={null}

257{

258 "allowManagedPermissionRulesOnly": true,

259 "permissions": {

260 "allow": [

261 "Edit(~/CoworkProjects/**)"

262 ]

263 }

264}

265```

266

267部署原則後，Claude 可以在新的 Cowork 工作階段中將檔案儲存在該資料夾下。[讀取和編輯規則](/docs/zh-TW/permissions#read-and-edit)涵蓋路徑語法，包括絕對路徑的 `//` 形式。

268

269<h3 id="what-a-developer-can-change">

270 開發者可以變更什麼

271</h3>

272

273開發者自己的設定檔案、`--settings` 值和專案檔案永遠不會覆蓋受管值；[例外](/docs/zh-TW/settings#exceptions-to-managed-settings-precedence)僅讓較嚴格的較低層級值計算。四件事在該規則之外：

274

275* **工作階段的模型**：受管 `model` 是預設值，不是鎖定。`--model` 和 `ANTHROPIC_MODEL` 仍然為該工作階段選擇模型，因此部署 [`availableModels`](/docs/zh-TW/settings-reference#availablemodels) 以限制選擇。

276* **本機管理員權限**：作為機器上管理員的開發者可以編輯受管來源本身，這就是為什麼 MDM 工具可以按排程重新部署設定檔或檔案，以及為什麼 HKLM 登錄和 macOS 受管偏好設定網域存在。

277* **伺服器受管快取**：伺服器受管設定來自 Anthropic 的伺服器，對本機快取的編輯[僅持續到下一次成功擷取](/docs/zh-TW/server-managed-settings#security-considerations)。

278* **其他工具**：受管設定僅綁定 Claude Code。從另一個工具呼叫 API 的開發者不在它們下。

279

280<span id="verify-enforcement" />

281

282<span id="verify-that-a-policy-is-in-force" />

283

284<h2 id="check-that-a-policy-is-in-force">

285 檢查原則是否有效

286</h2>

287

288開發者報告原則未應用，或您想在推出到機隊之前確認推出已著陸。該機器上的兩個命令回答它：`/status` 顯示 Claude Code 選擇了哪個受管來源，`claude doctor` 列出它刪除的內容。

289

290<h3 id="read-the-source-in-/status">

291 讀取 /status 中的來源

292</h3>

293

294在開發者的機器上，在 Claude Code 內執行 `/status` 並讀取 `Setting sources` 行。當受管來源有效時，該行列出 `Enterprise managed settings` 以及 Claude Code 在括號中選擇的來源：

295

296* `(remote)`：來自 claude.ai 或閘道的伺服器受管設定

297* `(plist)` 或 `(HKLM)`：MDM 或作業系統原則

298* `(file)`、`(drop-ins)` 或 `(file + drop-ins)`：`managed-settings.json`、放置目錄或兩者

299* `(remote + file, merged)` 或另一個以 `, merged` 結尾的列表：您的組織[組成每個受管來源](#compose-every-managed-source)，Claude Code 將列出的來源合併到原則中。較低來源仍然可以提供 `env` 變數而不出現在列表中。需要 Claude Code v2.1.242 或更新版本

300* `(HKCU)`：使用者可寫登錄回退

301* `(parent process)`：[嵌入主機](#let-an-embedding-host-add-policy)提供了限制性設定

302* `(helper)`：由選定的 MDM 或檔案來源配置的 [`policyHelper`](/docs/zh-TW/settings-reference#policyhelper)

303

304當 Claude Code 在機器上找到受管來源但未選擇它時，第二行 `Skipped sources` 命名每個這樣的來源。讀取它以區分從不到達機器的原則與到達它並被較高優先順序來源覆蓋的原則。需要 Claude Code v2.1.242 或更新版本。

305

306當原則未應用時，`Setting sources` 行告訴您您有以下兩個問題中的哪一個：

307

308* **該行遺失**：Claude Code 找不到傳遞原則金鑰的受管來源。

309

310 如果您部署了受管設定檔案，請檢查它位於作業系統的路徑，並且它包含[原則金鑰](#how-claude-code-combines-managed-sources)而不是僅控制金鑰。不是有效 JSON 的檔案不會產生此狀態；Claude Code [拒絕啟動](#find-entries-claude-code-dropped)。

311

312 當您改為透過伺服器受管設定部署時，執行 `claude doctor`，它報告[擷取結果](/docs/zh-TW/server-managed-settings#verify-settings-delivery)。

313* **該行命名您部署的來源以外的來源**：存在較高優先順序的來源，Claude Code 忽略了您的，`Skipped sources` 列出它。[Claude Code 如何結合受管來源](#how-claude-code-combines-managed-sources)給出順序。

314

315<span id="invalid-entries-in-managed-settings" />

316

317<h3 id="find-entries-claude-code-dropped">

318 尋找 Claude Code 刪除的項目

319</h3>

320

321當受管設定檔案、MDM 設定檔、登錄值或伺服器受管有效負載無法通過架構驗證時，Claude Code 首先跳過它可以修復的個別項目，例如一個無效的權限規則，每個都有警告，然後刪除任何頂層金鑰，其值仍然失敗，並繼續強制執行每個剩餘的有效金鑰。

322

323Claude Code 對 [`policyHelper`](/docs/zh-TW/settings-reference#policyhelper) 發出的 `managedSettings` 更嚴格：它進行相同的項目修復，但任何倖存的架構違規都會導致整個協助程式執行失敗，在啟動時 Claude Code 拒絕啟動，與協助程式退出非零相同。

324

325當受管設定檔案、放置檔案、MDM plist 或 HKLM 登錄值存在但無法解析為 JSON 物件時，Claude Code 拒絕啟動並列印[命名來源的錯誤](/docs/zh-TW/errors#managed-settings-document-could-not-be-parsed)，即使另一個管理來源傳遞有效原則。每個來源在以下情況下以這種方式失敗：

326

327* **受管設定檔案或放置檔案**：檔案不是有效的 JSON，或其頂層不是物件

328* **MDM plist**：macOS 的 `plutil` 報告 plist 格式不正確，或其轉換的內容不是 JSON 物件

329* **HKLM 登錄值**：`Settings` 值不是字串、為空或不持有 JSON 物件

330

331三個來源狀態不會導致此拒絕：

332

333* 缺少的檔案、設定檔或登錄值不是失敗；Claude Code 在沒有該來源的情況下執行。

334* 空的受管設定檔案計為 `{}`。

335* 使用者可寫 HKCU 登錄金鑰中的格式不正確的值永遠不會阻止啟動。Claude Code 將其報告為 `/status` 和 `claude doctor` 中的通知。

336

337如果受管設定檔案、放置檔案或 `managed-settings.d/` 目錄無法讀取，且沒有管理來源提供原則，使用 claude.ai 或 Claude Console 認證登入的工作階段在啟動時退出，並顯示聯絡管理員的訊息。

338

339若要尋找刪除的項目，請查看以下三個位置之一：

340

341* 互動式工作階段在啟動時顯示列出無效項目的對話。

342* 使用 `-p` 的非互動式執行將摘要列印到 stderr。

343* [`claude doctor`](/docs/zh-TW/debug-your-config) 列出每個無效項目及其來源和欄位。

344

345<h4 id="keys-that-fail-closed">

346 失敗關閉的金鑰

347</h4>

348

349少數強制執行金鑰在無效時不會被刪除。Claude Code 強制執行更嚴格的回退，直到值被修復；表格顯示它對每個金鑰強制執行的內容：

350

351| 欄位 | 存在但無效時的行為 |

352| :---------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

353| `allowedMcpServers` | 強制執行為空允許清單，直到值被修復，因此使用者添加的沒有 MCP 伺服器被允許。您的組織透過 [`managedMcpServers`](/docs/zh-TW/settings-reference#managedmcpservers) 傳遞的伺服器仍然載入，`managed-mcp.json` 伺服器按[伺服器如何被評估](/docs/zh-TW/managed-mcp#how-a-server-is-evaluated)載入。個別無效項目被剝離，有效子集被強制執行。 |

354| `allowedHttpHookUrls` | Claude Code 強制執行空[允許清單](/docs/zh-TW/settings-reference#allowedhttphookurls)，直到您修復值。如果僅個別項目無效，它會剝離該項目並強制執行其餘項目。 |

355| `httpHookAllowedEnvVars` | Claude Code 強制執行空[允許清單](/docs/zh-TW/settings-reference#httphookallowedenvvars)，直到您修復值。如果僅個別項目無效，它會剝離該項目並強制執行其餘項目。 |

356| `allowedChannelPlugins` | Claude Code 強制執行空允許清單，直到您修復值，因此傳遞給 `--channels` 的沒有頻道外掛被允許。如果僅個別項目無效，它會剝離該項目並強制執行其餘項目。 |

357| `allowManagedHooksOnly` | 視為 `true` 直到修復：[掛鉤限制](/docs/zh-TW/settings-reference#allowmanagedhooksonly)適用，除非 `disableCommandPluginSources` 明確為 `false`，否則命令來源的外掛被禁用。 |

358| `allowManagedMcpServersOnly` | 視為 `true`。 |

359| `disableCommandPluginSources` | 視為 `true`，因此命令來源的外掛保持禁用，直到值被修復。 |

360| `availableModels` | 強制執行為空允許清單，直到修復，因此僅預設模型可用；非字串項目被剝離，有效子集被強制執行。 |

361| `enforceAvailableModels` | 視為 `true`。 |

362| `forceLoginOrgUUID` | 沒有組織被允許登入，直到值被修復。 |

363| `crossSessionInbound` | 視為 `refuse`，最嚴格的值，因此入站[跨工作階段訊息](/docs/zh-TW/cross-session-messaging#control-inbound-messages)被拒絕，直到值被修復。開發者看到[警告](/docs/zh-TW/errors#crosssessioninbound-must-be-one-of-accept-hold-refuse)。 |

364| `deniedMcpServers` | 個別無效項目被剝離，有效子集被強制執行。完全無效的值被刪除並顯示警告，因為拒絕每個伺服器會阻止原則從未命名的伺服器。 |

365| `sandbox.credentials` | 可恢復的無效項目降級為 `mode: "deny"` 並顯示警告；無法恢復的項目被剝離；有效項目保持強制執行。請參閱[受管設定中的無效認證項目](/docs/zh-TW/settings-reference#invalid-credential-entries-in-managed-settings) |

366

367`allowedHttpHookUrls` 和 `httpHookAllowedEnvVars` 跨設定檔案合併，因此您的使用者、專案或本機設定中的項目在受管清單為空時仍然適用。這兩個金鑰和 `allowedChannelPlugins` 的回退需要 Claude Code v2.1.267 或更新版本；較早版本在其值或任何項目無效時刪除整個金鑰。

368

369`requiredMinimumVersion` 和 `requiredMaximumVersion` 按設計失敗開放：無效值被刪除而不是強制執行。

370

371此容差僅適用於受管設定。使用者、專案和本機設定檔案保持嚴格：JSON 或頂層形狀失敗驗證的檔案被整體拒絕並報告，無效的個別項目（例如格式不正確的權限規則）被跳過並顯示警告，而檔案的其餘部分適用。

372

373<span id="managed-only-settings" />

374

375<h2 id="keys-only-a-managed-source-can-set">

376 僅受管來源可以設定的金鑰

377</h2>

378

379Claude Code 僅從受管來源讀取以下金鑰；將它們放在使用者或專案設定檔案中無效。

380

381大多數是鎖定：鎖定管理的值，例如權限規則或 `sandbox.network.allowedDomains`，是任何層級都可以設定的普通金鑰，鎖定告訴 Claude Code 僅尊重受管值。

382

383表格涵蓋權限、外掛和傳遞控制項。對於此處未列出的任何金鑰，[設定參考](/docs/zh-TW/settings-reference#all-settings)索引的 Scope 列說明它是否僅受管；其餘僅受管金鑰包括閘道登入 URL、版本、瀏覽器、行動模擬器、SSH 主機、Desktop 本機工作階段、沙箱二進位路徑、模型定價和 CLAUDE.md 控制項。

384

385| 設定 | 描述 |

386| :----------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

387| [`allowAllClaudeAiMcps`](/docs/zh-TW/settings-reference#allowallclaudeaimcps) | 載入 Claude Code 自己擷取的 claude.ai 連接器，與部署的 `managed-mcp.json` 一起，而不是抑制它們 |

388| [`allowedChannelPlugins`](/docs/zh-TW/settings-reference#allowedchannelplugins) | 可能推送訊息的頻道外掛的允許清單。設定時替換預設 Anthropic 允許清單。需要 `channelsEnabled: true`。請參閱[限制哪些頻道外掛可以執行](/docs/zh-TW/channels#restrict-which-channel-plugins-can-run) |

389| [`allowManagedHooksOnly`](/docs/zh-TW/settings-reference#allowmanagedhooksonly) | 當 `true` 時，限制哪些掛鉤執行；請參閱[在 `allowManagedHooksOnly` 下執行什麼](/docs/zh-TW/settings-reference#what-runs-under-allowmanagedhooksonly)以了解完整效果清單 |

390| [`allowManagedMcpServersOnly`](/docs/zh-TW/settings-reference#allowmanagedmcpserversonly) | 當 `true` 時，僅受管設定中的 `allowedMcpServers` 被尊重。`deniedMcpServers` 仍然從所有來源合併。請參閱[受管 MCP 設定](/docs/zh-TW/managed-mcp) |

391| [`allowManagedPermissionRulesOnly`](/docs/zh-TW/settings-reference#allowmanagedpermissionrulesonly) | 使受管設定成為權限規則的唯一設定來源。項目列出它忽略的每個來源 |

392| [`blockedMarketplaces`](/docs/zh-TW/settings-reference#blockedmarketplaces) | 市場來源的封鎖清單。被封鎖的來源在下載前被檢查，因此它們永遠不會接觸檔案系統。請參閱[受管市場限制](/docs/zh-TW/plugin-marketplaces#managed-marketplace-restrictions) |

393| [`channelsEnabled`](/docs/zh-TW/settings-reference#channelsenabled) | 允許組織的[頻道](/docs/zh-TW/channels)。請參閱[企業控制項](/docs/zh-TW/channels#enterprise-controls)以了解每個計畫上的預設值 |

394| [`disableCommandPluginSources`](/docs/zh-TW/settings-reference#disablecommandpluginsources) | 當 `true` 時，完全阻止[`command` 外掛來源](/docs/zh-TW/plugin-marketplaces#command-sources)，因此市場聲明的命令永遠不會執行。也阻止市場[`headersHelper` 命令](/docs/zh-TW/plugin-marketplaces#authenticate-archive-downloads)，除了受管設定本身聲明的市場。未設定時，遵循 `allowManagedHooksOnly`。需要 Claude Code v2.1.229 或更新版本，`headersHelper` 區塊需要 v2.1.238 或更新版本 |

395| [`disableSideloadFlags`](/docs/zh-TW/settings-reference#disablesideloadflags) | 在啟動時拒絕 `--plugin-dir`、`--plugin-url`、`--agents` 和 `--mcp-config` 標誌。在雲端工作階段中，Claude Code 刪除伺服器透過 `--mcp-config` 傳遞的 MCP 伺服器，除了進程內 `type: "sdk"` 項目，並啟動工作階段。需要 Claude Code v2.1.193 或更新版本 |

396| [`forceRemoteSettingsRefresh`](/docs/zh-TW/settings-reference#forceremotesettingsrefresh) | 當 `true` 時，阻止 CLI 啟動，直到遠端受管設定被新鮮擷取，如果擷取失敗則退出。請參閱[失敗關閉強制執行](/docs/zh-TW/server-managed-settings#enforce-fail-closed-startup) |

397| [`managedMcpServers`](/docs/zh-TW/settings-reference#managedmcpservers) | 提供給每個使用者與他們自己的遠端 MCP 伺服器。它提供伺服器而不是鎖定任何東西。請參閱[透過受管設定提供伺服器](/docs/zh-TW/managed-mcp#provide-servers-through-managed-settings)。需要 Claude Code v2.1.259 或更新版本 |

398| [`managedSourcesBehavior`](/docs/zh-TW/settings-reference#managedsourcesbehavior) | Claude Code 是否僅應用最高優先順序受管來源或[組成它們中的每一個](#compose-every-managed-source) |

399| [`parentSettingsBehavior`](/docs/zh-TW/settings-reference#parentsettingsbehavior) | 主機提供的父設定是否在受管原則下合併 |

400| [`pluginSuggestionMarketplaces`](/docs/zh-TW/settings-reference#pluginsuggestionmarketplaces) | Claude Code 可能向使用者建議其外掛的市場 |

401| [`pluginTrustMessage`](/docs/zh-TW/settings-reference#plugintrustmessage) | 附加到安裝前顯示的外掛信任警告的自訂訊息 |

402| [`policyHelper`](/docs/zh-TW/settings-reference#policyhelper) | 在啟動時計算受管設定的可執行檔；請參閱[使用原則協助程式計算受管設定](/docs/zh-TW/settings-reference#policyhelper) |

403| [`sandbox.filesystem.allowManagedReadPathsOnly`](/docs/zh-TW/settings-reference#sandbox-filesystem-allowmanagedreadpathsonly) | 當 `true` 時，僅受管設定中的 `filesystem.allowRead` 路徑被尊重。`denyRead` 仍然從所有來源合併 |

404| [`sandbox.network.allowManagedDomainsOnly`](/docs/zh-TW/settings-reference#sandbox-network-allowmanageddomainsonly) | 僅尊重受管 `allowedDomains` 和 `WebFetch(domain:...)` 允許規則；阻止其他網域而不提示 |

405| [`strictKnownMarketplaces`](/docs/zh-TW/settings-reference#strictknownmarketplaces) | 控制使用者可以添加和安裝外掛的外掛市場來源。請參閱[受管市場限制](/docs/zh-TW/plugin-marketplaces#managed-marketplace-restrictions) |

406| [`strictPluginOnlyCustomization`](/docs/zh-TW/settings-reference#strictpluginonlycustomization) | 阻止技能、代理、掛鉤和 MCP 伺服器來自使用者和專案來源；`true` 鎖定所有四個，陣列命名哪些 |

407| [`wslInheritsWindowsSettings`](/docs/zh-TW/settings-reference#wslinheritswindowssettings) | 當在 HKLM 登錄或 `C:\Program Files\ClaudeCode` 下的檔案中設定時，讓 WSL 讀取 Windows 原則鏈，並僅當該目錄下的受管設定檔案或放置不傳遞[原則金鑰](#how-claude-code-combines-managed-sources)時讀取 `/etc/claude-code`；項目給出順序 |

408

409<Note>

410 在團隊和企業計畫上，所有者在 [Claude Code 管理設定](https://claude.ai/admin-settings/claude-code)中組織範圍內啟用或禁用[遠端控制](/docs/zh-TW/remote-control)和[網路工作階段](/docs/zh-TW/claude-code-on-the-web)。遠端控制可以另外透過 [`disableRemoteControl`](/docs/zh-TW/settings-reference#disableremotecontrol) 設定按裝置禁用。網路工作階段沒有按裝置受管設定金鑰。

411

412 若要檢查這些組織設定是否到達給定的機器，請在那裡執行 `claude doctor` 並讀取 `Organization policy` 行，它說明 Claude Code 從哪裡載入原則或為什麼它沒有載入。需要 Claude Code v2.1.261 或更新版本。在執行中的工作階段中，當原則未載入時，`/status` 顯示相同的行。

413</Note>

414

415<h2 id="turn-telemetry-off-for-your-organization">

416 為您的組織關閉遙測

417</h2>

418

419Claude Code 預設在使用 Anthropic API 的工作階段上發送 Anthropic 操作[遙測](/docs/zh-TW/data-usage#telemetry-services)，無論是直接、透過 LLM 閘道還是透過自訂 `ANTHROPIC_BASE_URL`；[按 API 提供者的預設行為](/docs/zh-TW/data-usage#default-behaviors-by-api-provider)說明哪些提供者發送它。若要為每個開發者關閉它而不依賴每個人的 shell，請透過受管設定的 `env` 區塊傳遞 `DISABLE_TELEMETRY`。此範例為原則到達的每個人設定 `DISABLE_TELEMETRY`：

420

421```json theme={null}

422{

423 "env": {

424 "DISABLE_TELEMETRY": "1"

425 }

426}

427```

428

429Claude Code 應用 `1` 的值而不向使用者顯示[批准對話](/docs/zh-TW/server-managed-settings#environment-variables-and-the-approval-dialog)。

430

431如果您關閉遙測，Claude Code 停止發送為原則到達的開發者提供您的組織[分析儀表板](/docs/zh-TW/analytics)的使用資料。變數也關閉功能標誌擷取，這使得遠端控制、預設自動模式和其他[需要功能標誌擷取的功能](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)對這些開發者不可用。

432

433[原則應用的位置和時間](#where-and-when-a-policy-applies)說明哪個傳遞機制到達每個表面，[平台可用性](/docs/zh-TW/server-managed-settings#platform-availability)說明哪些工作階段跳過伺服器受管設定擷取。

434

435如果您的組織使用客戶受管加密金鑰並透過閘道路由 Claude Code，[設定代理和閘道](/docs/zh-TW/third-party-integrations#configure-proxies-and-gateways)說明為什麼這些工作階段需要此變數。

436

437<h2 id="see-also">

438 另請參閱

439</h2>

440

441* [為您的組織設定 Claude Code](/docs/zh-TW/admin-setup)：決定要強制執行什麼以及如何強制執行

442* [伺服器受管設定](/docs/zh-TW/server-managed-settings)：從 claude.ai 主控台或閘道傳遞原則

443* [受管 MCP 設定](/docs/zh-TW/managed-mcp)：控制開發者可以使用哪些 MCP 伺服器

444* [所有設定](/docs/zh-TW/settings-reference)：每個金鑰，以及受管來源是否可以設定它

445* [範例設定檔案](/docs/zh-TW/settings-example#an-organizations-managed-settings)：完整的 `managed-settings.json` 顯示受管金鑰的形狀

memory.md +3 −1

Details

275 使用符號連結跨專案共享規則275 使用符號連結跨專案共享規則

276</h4>276</h4>

277 277

278`.claude/rules/` 目錄支援符號連結，因此您可以維護一組共享規則並將它們連結到多個專案中。符號連結被解析並正常載入，並且循環符號連結被檢測並妥善處理。278`.claude/rules/` 目錄支援符號連結，因此您可以維護一組共享規則並將它們連結到多個專案中。循環符號連結被檢測並妥善處理。

279

280Claude Code 將其目標在您工作目錄外的符號連結視為 [外部匯入](#import-additional-files)。連結的規則在您核准專案的外部匯入之前不會載入，之後只有沒有 [`paths` 欄位](#path-specific-rules) 的規則會載入。Claude Code 在專案記憶檔案使用 `@path` 匯入工作目錄外的檔案時要求核准，而不是針對符號連結單獨要求。要在不需要該核准的情況下載入共享規則，請將它們保留在 [`~/.claude/rules/`](#user-level-rules) 中，它們適用於您機器上的每個專案。

279 281

280此示例連結共享目錄和單個檔案：282此示例連結共享目錄和單個檔案：

281 283

mobile.md +104 −0 created

Details

1> ## Documentation Index

2> 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.

5# Claude Code 行動版

7> 從您的手機使用 Claude iOS 和 Android 應用程式來啟動、監控和引導 Claude Code 工作。

9Claude [iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) 和 [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude) 應用程式是 Claude Code 工作階段的用戶端，而不是程式碼執行的地點。從您的手機，您可以存取雲端上的[雲端工作階段](#start-and-monitor-cloud-sessions)、透過[遠端控制](#continue-a-local-session-with-remote-control)在您自己的機器上執行的工作階段，或透過 [Dispatch](/docs/zh-TW/desktop#sessions-from-dispatch) 的桌面應用程式。

11<Note>

12 Claude Code 沒有單獨的行動應用程式：雲端工作階段和遠端控制都位於 Claude 應用程式中的 **Code** 標籤，而 Dispatch 是您在應用程式中向其傳送訊息的工作。

13</Note>

15<h2 id="get-the-app">

16 取得應用程式

17</h2>

19<Steps>

20 <Step title="下載 Claude 應用程式">

21 安裝 [iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) 或 [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude) 的 Claude 應用程式。在 iPad 上，安裝相同的 iOS 應用程式。

23 <Tip>

24 在 Claude Code 工作階段中執行 `/mobile` 以顯示您可以掃描的下載 QR 碼。`/ios` 和 `/android` 執行相同的操作。

25 </Tip>

26 </Step>

28 <Step title="登入">

29 使用您用於 Claude Code 的相同 claude.ai 帳戶和組織登入。雲端工作階段和遠端控制需要 claude.ai 帳戶，因此無法透過 Anthropic Console API 金鑰或來自 Amazon Bedrock 等第三方提供者的帳戶存取。

30 </Step>

32 <Step title="開啟 Code 標籤">

33 在應用程式的導覽中點選 **Code** 以存取您的工作階段，或在您的手機上開啟 [claude.ai/code/new](https://claude.ai/code/new) 以在應用程式中啟動新的 Code 工作階段。如果您看不到 Code 標籤，您的方案或組織可能不包含這些功能；請參閱[按訂閱方案的可用性](/docs/zh-TW/feature-availability#availability-by-subscription-plan)。

34 </Step>

35</Steps>

37<h2 id="work-from-your-phone">

38 從您的手機工作

39</h2>

41從應用程式，您可以啟動雲端工作階段、驅動在您的電腦上執行的 Claude Code 工作階段，或向 Dispatch 傳送工作訊息。應用程式對所有三者都相同；它們在工作發生的位置上有所不同。

43| 功能 | 您連接到的內容 | 何時使用 |

44| :------------------------------------------------ | :------------------------------ | :--------------------------------------------------------------------- |

45| [Claude Code 網頁版](/docs/zh-TW/claude-code-on-the-web) | 雲端基礎設施上的雲端工作階段，預設由 Anthropic 管理 | 您的儲存庫在 GitHub 上，工作應在您放下手機後繼續執行。請參閱[網頁快速入門](/docs/zh-TW/web-quickstart)進行設定。 |

46| [遠端控制](/docs/zh-TW/remote-control) | 在您的電腦上執行的 Claude Code 工作階段 | 工作需要您的本機檔案系統、工具或 MCP 伺服器。 |

47| [Dispatch](/docs/zh-TW/desktop#sessions-from-dispatch) | 您電腦上的桌面應用程式 | 您想傳送工作訊息並讓 Dispatch 決定如何執行它。需要 Pro 或 Max 方案。 |

49如果您的電腦將關閉，請使用雲端工作階段，它們在雲端中執行並在您的筆記型電腦關閉後繼續執行。遠端控制和 Dispatch 驅動您自己的機器，因此它需要保持開啟並執行 Claude Code 或桌面應用程式。如果您的機器在遠端控制工作階段期間進入睡眠狀態，Claude Code 會在機器恢復上線時重新連接。

51如需更完整的比較，請參閱[當您遠離終端機時工作](/docs/zh-TW/platforms#work-when-you-are-away-from-your-terminal)。

53雲端工作階段和遠端控制從 **Code** 標籤執行。對於您在應用程式中作為工作傳送訊息的 Dispatch，請參閱[來自 Dispatch 的工作階段](/docs/zh-TW/desktop#sessions-from-dispatch)。

55<h3 id="start-and-monitor-cloud-sessions">

56 啟動和監控雲端工作階段

57</h3>

59Claude Code 網頁版在雲端基礎設施上執行工作，預設由 Anthropic 管理，因此工作階段在您放下手機後繼續執行。從 Code 標籤，選擇儲存庫和分支、描述工作，然後提交。工作階段在裝置間持續存在：您在筆記型電腦上啟動的工作已準備好從您的手機進行審查，您從手機啟動的工作在您回到辦公桌時正在等待。

61在應用程式中開啟工作階段以檢查進度、回答 Claude 的問題或將其引導到新的方向。您也可以告訴 Claude [監看拉取請求](/docs/zh-TW/claude-code-on-the-web#auto-fix-pull-requests)並在 CI 失敗或審查意見到達時修復它們。若要連接 GitHub 並設定您的環境，請遵循[網頁快速入門](/docs/zh-TW/web-quickstart)，並查看[Claude Code 網頁版](/docs/zh-TW/claude-code-on-the-web)以了解雲端工作階段可以執行的所有操作。

63<h3 id="continue-a-local-session-with-remote-control">

64 使用遠端控制繼續本機工作階段

65</h3>

67遠端控制將 Claude 應用程式連接到在您的機器上執行的 Claude Code 工作階段，因此程式碼執行和檔案系統存取保持本機，而您從手機驅動工作階段。在您的電腦上使用 `claude remote-control` 啟動工作階段，或在已開啟的工作階段中執行 `/remote-control`。然後掃描終端機可以顯示的工作階段 QR 碼，或開啟 Claude 應用程式、點選 **Code**，然後從清單中選擇工作階段。請參閱[從另一個裝置連接](/docs/zh-TW/remote-control#connect-from-another-device)以了解每個選項。

69當您在 Claude 應用程式中新增附件時，它也會到達本機工作階段：

71* **照片**：Claude 直接將附加的照片視為您訊息的一部分。Claude Code 也會將每張照片儲存在 `~/.claude/uploads/` 下，並告訴 Claude 儲存的檔案路徑，因此 Claude 可以將影像複製到它建立的檔案中。

72* **其他檔案**：Claude Code 將它們下載到您的機器，並將它們作為 `@` 檔案參考傳遞給 Claude。

74如需需求、調用模式和疑難排解，請參閱[遠端控制概述](/docs/zh-TW/remote-control)。

76<h3 id="get-push-notifications">

77 取得推播通知

78</h3>

80當遠端控制處於作用中時，Claude 可以向您的手機傳送推播通知，通常在長時間執行的工作完成或需要您做出決定時。您也可以在提示中要求一個，例如 `notify me when the tests finish`。請參閱[行動推播通知](/docs/zh-TW/remote-control#mobile-push-notifications)以了解兩個 `/config` 切換和傳遞疑難排解。

82Dispatch 在它產生的 Code 工作階段完成或需要您的批准時傳送自己的通知，如[來自 Dispatch 的工作階段](/docs/zh-TW/desktop#sessions-from-dispatch)中所述。

84<h2 id="limitations">

85 限制

86</h2>

88行動用戶端涵蓋工作階段所需的大部分內容，但有一些限制：

90* **僅限本機命令**：僅在終端機介面中執行的命令，例如 `/plugin` 和 `/resume`，無法從應用程式中工作。[遠端控制限制](/docs/zh-TW/remote-control#limitations)列出了從行動裝置工作的命令以及它們的行為如何不同。

91* **權限模式**：雲端工作階段在模式下拉式清單中提供接受編輯、Plan 和 Auto，遠端控制工作階段提供 Manual、接受編輯和 Plan。在任何情況下，您都無法從應用程式中選擇 Bypass permissions，也無法為遠端控制工作階段選擇 Auto。請參閱[切換權限模式](/docs/zh-TW/permission-modes#switch-permission-modes)。

92* **Dispatch 方案**：Dispatch 需要 Pro 或 Max 方案，在 Team 或 Enterprise 上不可用。

94<h2 id="related-resources">

95 相關資源

96</h2>

98* [平台和整合](/docs/zh-TW/platforms)：比較 Claude Code 執行的每個表面

99* [Claude Code 網頁版](/docs/zh-TW/claude-code-on-the-web)：雲端工作階段如何執行以及如何在您的終端機之間移動工作

100* [設定雲端環境](/docs/zh-TW/cloud-environments)：雲端工作階段的網路存取層級、環境變數和設定指令碼

101* [遠端控制](/docs/zh-TW/remote-control)：從任何裝置繼續本機工作階段

102* [來自 Dispatch 的工作階段](/docs/zh-TW/desktop#sessions-from-dispatch)：Dispatch 工作如何在桌面應用程式中成為 Code 工作階段

103* [Channels](/docs/zh-TW/channels)：在工作在您的機器上執行時，透過 Telegram、Discord 或 iMessage 從您的手機詢問 Claude 一些事情

104* [Claude Code 在 Slack 中](/docs/zh-TW/slack)：透過提及 `@Claude` 從您的 Slack 工作區委派編碼工作

monitoring-usage.md +246 −91

Details

6 6

7> 了解如何為 Claude Code 啟用和配置 OpenTelemetry。7> 了解如何為 Claude Code 啟用和配置 OpenTelemetry。

8 8

9透過 OpenTelemetry (OTel) 匯出遙測資料，追蹤 Claude Code 在整個組織中的使用情況、成本和工具活動。Claude Code 透過標準指標協議匯出指標作為時間序列資料、透過日誌/事件協議匯出事件，以及可選地透過[追蹤協議](#traces-beta)匯出分散式追蹤。配置您的指標、日誌和追蹤後端以符合您的監控需求。9透過 OpenTelemetry (OTel) 匯出遙測資料，追蹤 Claude Code 在整個組織中的使用情況、成本和工具活動。Claude Code 透過標準指標協議匯出指標作為時間序列資料、透過日誌/事件協議匯出事件，以及可選地透過[追蹤協議](#traces-beta)匯出分散式追蹤。

10 10

11<h2 id="quick-start">11<h2 id="quick-start">

12 快速開始12 快速開始

29# 4. 設定身份驗證（如果需要）29# 4. 設定身份驗證（如果需要）

30export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"30export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"

31 31

~~32# 5. 用於除錯：減少匯出間隔~~32# 5. 用於除錯：減少匯出間隔，並在生產環境中重設它們

33export OTEL_METRIC_EXPORT_INTERVAL=10000 # 10 秒（預設：60000ms）33export OTEL_METRIC_EXPORT_INTERVAL=10000 # 10 秒（預設：60000ms）

34export OTEL_LOGS_EXPORT_INTERVAL=5000 # 5 秒（預設：5000ms）34export OTEL_LOGS_EXPORT_INTERVAL=5000 # 5 秒（預設：5000ms）

35 35

37claude37claude

38```38```

39 39

~~40<Note>~~40若要驗證匯出指標的設定，請檢查您的後端是否有 `claude_code.session.count` 指標，Claude Code 會在工作階段啟動時發出此指標。若要驗證僅限日誌的設定，請提交提示並檢查 `claude_code.user_prompt` 事件。

~~41 預設匯出間隔為指標 60 秒和日誌 5 秒。在設定期間，您可能希望使用較短的間隔用於除錯目的。記得在生產環境中重設這些值。~~41

~~42</Note>~~42如果沒有任何內容到達，請執行 `claude --debug` 並檢查除錯日誌。Claude Code 會將您配置的匯出器失敗報告為 `[3P telemetry]` 錯誤，其中 3P 表示第三方。以 `[Anthropic telemetry]` 為前綴的行描述 [Anthropic 的獨立營運遙測](/docs/zh-TW/data-usage#telemetry-services)，不表示您的設定有問題。

43 43

44如需完整配置選項，請參閱 [OpenTelemetry 規範](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md#configuration-options)。44如需完整配置選項，請參閱 [OpenTelemetry 規範](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md#configuration-options)。

45 45

47 管理員配置47 管理員配置

48</h2>48</h2>

49 49

50管理員可以透過[受管設定檔](/docs/zh-TW/settings#settings-files)為所有使用者配置 OpenTelemetry 設定。這允許在整個組織中集中控制遙測設定。請參閱[設定優先順序](/docs/zh-TW/settings#settings-precedence)以了解有關如何應用設定的更多資訊。50管理員可以透過[受管設定檔](/docs/zh-TW/managed-settings#delivery-mechanisms)為所有使用者配置 OpenTelemetry 設定。請參閱[設定優先順序](/docs/zh-TW/settings#settings-precedence)以了解有關如何應用設定的更多資訊。

51 51

52受管設定配置範例：52受管設定配置範例：

53 53

64}64}

65```65```

66 66

~~67<Note>~~

~~68 受管設定可以透過 MDM（行動裝置管理）或其他裝置管理解決方案進行分發。在受管設定檔中定義的環境變數具有高優先順序，使用者無法覆蓋。~~

~~69</Note>~~

71Claude Code 不會將 `OTEL_*` 環境變數傳遞給它產生的子程序，包括 Bash 工具、hooks、MCP 伺服器和語言伺服器。透過 Bash 工具執行的 OpenTelemetry 檢測應用程式不會繼承 Claude Code 的匯出器端點或標頭，因此如果該應用程式需要匯出自己的遙測，請直接在命令中設定這些變數。67Claude Code 不會將 `OTEL_*` 環境變數傳遞給它產生的子程序，包括 Bash 工具、hooks、MCP 伺服器和語言伺服器。透過 Bash 工具執行的 OpenTelemetry 檢測應用程式不會繼承 Claude Code 的匯出器端點或標頭，因此如果該應用程式需要匯出自己的遙測，請直接在命令中設定這些變數。

72 68

69<h3 id="how-managed-settings-lock-the-otlp-destination">

70 受管設定如何鎖定 OTLP 目的地

71</h3>

73當您在受管設定中設定 `OTEL_EXPORTER_OTLP_*` 變數時，Claude Code 會在啟動時移除衝突的開發人員設定變數，並記錄您可以透過 `claude --debug` 查看的警告。它移除的內容取決於您設定的變數：

75* **端點**：當您設定 `OTEL_EXPORTER_OTLP_ENDPOINT` 時，Claude Code 會移除每個開發人員設定的每個信號端點。開發人員無法將一個信號指向不同的收集器，因此您不需要在受管設定中也設定每個信號的端點變數。

76* **協議**：當您設定 `OTEL_EXPORTER_OTLP_PROTOCOL` 時，Claude Code 會移除每個開發人員設定的每個信號協議。

77* **認證**：當您設定 `OTEL_EXPORTER_OTLP_HEADERS`、`OTEL_EXPORTER_OTLP_CLIENT_KEY` 或 `OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE` 時，Claude Code 會移除該變數的開發人員設定每個信號版本，加上每個開發人員設定的端點變數（通用或每個信號），因為這些認證否則會到達受管設定未選擇的收集器。

78* **匯出器選擇器**：`OTEL_METRICS_EXPORTER`、`OTEL_LOGS_EXPORTER` 和測試版 `OTEL_TRACES_EXPORTER` 遵循正常的每個鍵優先順序。開發人員的設定仍然可以禁用信號或將其切換到控制台匯出器，因此如果您需要鎖定選擇器，也請在受管設定中設定它們。在[管理員來源](/docs/zh-TW/managed-settings#precedence-within-the-managed-tier)中，`OTEL_LOGS_EXPORTER` 遵循[遙測單位](/docs/zh-TW/server-managed-settings#per-key-exceptions-across-managed-sources)，而其他兩個選擇器按鍵合併。需要 Claude Code v2.1.223 或更新版本。

79* **測試版追蹤端點**：當[詳細測試版追蹤](#traces-beta)啟用時，Claude Code 會將日誌和追蹤匯出到 `BETA_TRACING_ENDPOINT` 而不是透過日誌和追蹤匯出器。因此，Claude Code 會在以下任何受管設定決定任一信號的目的地時移除開發人員設定的 `BETA_TRACING_ENDPOINT`：

81 * 通用或日誌/追蹤端點或認證

82 * 一個 [`otelHeadersHelper`](/docs/zh-TW/settings-reference#otelheadershelper)

83 * 日誌或追蹤匯出器選擇器設定為 `none`、`console` 或空白，這些值會將信號保持在收集器之外

84 * `CLAUDE_CODE_ENABLE_TELEMETRY` 關閉

86 僅限指標的端點或認證不會移除它。在 v2.1.251 之前，開發人員設定的 `BETA_TRACING_ENDPOINT` 會重新導向詳細測試版追蹤匯出的日誌和追蹤，即使受管設定固定了收集器。

88Claude Code 不會移除您在受管設定本身中設定的每個信號變數，因此您可以透過在其中設定其變數來將一個信號路由到不同的收集器，如[SIEM 範例](#send-events-to-a-siem)所示。如果您在其中設定每個信號認證，Claude Code 會移除該信號的開發人員設定端點。

90此移除行為改變遙測的傳遞位置，而不是 Claude Code 收集的內容。

92在 v2.1.217 之前，每個變數獨立遵循每個鍵設定優先順序，因此在使用者設定或 shell 中設定的信號特定端點會將該信號重新導向離開受管收集器。

94當桌面應用程式或[自託管環境](/docs/zh-TW/self-hosted-environments)執行器啟動 Claude Code 並在其提供的環境中命名 OTLP 端點時，Claude Code 會以相同方式固定目的地：啟動器的遙測變數移除開發人員設定的變數，完全如受管設定所做的那樣。Claude Code 不會移除啟動器本身設定的變數。需要 Claude Code v2.1.251 或更新版本。

73<h2 id="configuration-details">96<h2 id="configuration-details">

74 配置詳情97 配置詳情

75</h2>98</h2>

78 常見配置變數101 常見配置變數

79</h3>102</h3>

80 103

104這些變數為所有部署配置匯出器、端點和匯出行為。如果您設定每個訊號端點或協議變數，例如 `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`，Claude Code 會改用它而不是該訊號的通用變數。如果您設定每個訊號標頭變數，例如 `OTEL_EXPORTER_OTLP_METRICS_HEADERS`，Claude Code 會將其與該訊號的通用 `OTEL_EXPORTER_OTLP_HEADERS` 合併。在具有受管設定的機器上，請參閱[受管設定如何鎖定 OTLP 目的地](#how-managed-settings-lock-the-otlp-destination)以了解 Claude Code 移除的內容。

105

81| 環境變數 | 描述 | 範例值 |106| 環境變數 | 描述 | 範例值 |

82| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |107| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------- |

83| `CLAUDE_CODE_ENABLE_TELEMETRY` | 啟用遙測收集（必需） | `1` |108| `CLAUDE_CODE_ENABLE_TELEMETRY` | 啟用遙測收集（必需） | `1` |

118| `OTEL_EXPORTER_OTLP_METRICS_HEADERS` | 指標的身份驗證標頭，與一般標頭合併 | `Authorization=Bearer token` |

119| `OTEL_EXPORTER_OTLP_LOGS_HEADERS` | 日誌的身份驗證標頭，與一般標頭合併 | `Authorization=Bearer token` |

93| `OTEL_METRIC_EXPORT_INTERVAL` | 匯出間隔（毫秒）（預設：60000） | `5000`、`60000` |120| `OTEL_METRIC_EXPORT_INTERVAL` | 匯出間隔（毫秒）（預設：60000） | `5000`、`60000` |

94| `OTEL_LOGS_EXPORT_INTERVAL` | 日誌匯出間隔（毫秒）（預設：5000） | `1000`、`10000` |121| `OTEL_LOGS_EXPORT_INTERVAL` | 日誌匯出間隔（毫秒）（預設：5000） | `1000`、`10000` |

95| `OTEL_LOG_USER_PROMPTS` | 啟用使用者提示內容的日誌記錄（預設：停用） | `1` 以啟用 |122| `OTEL_LOG_USER_PROMPTS` | 啟用使用者提示內容的日誌記錄（預設：停用） | `1` 以啟用 |

96| `OTEL_LOG_ASSISTANT_RESPONSES` | 啟用在 `assistant_response` 事件上記錄助手回應文字的日誌（預設：停用）。未設定時，會回退到 `OTEL_LOG_USER_PROMPTS` 的值。需要 Claude Code v2.1.193 或更新版本 | `1` 以啟用，`0` 以保持編輯 |123| `OTEL_LOG_ASSISTANT_RESPONSES` | 啟用在 `assistant_response` 事件上記錄助手回應文字的日誌（預設：停用）。未設定時，會回退到 `OTEL_LOG_USER_PROMPTS` 的值。需要 Claude Code v2.1.193 或更新版本 | `1` 以啟用，`0` 以保持編輯 |

97| `OTEL_LOG_TOOL_DETAILS` | 啟用在工具事件和追蹤跨度屬性中記錄工具參數和輸入引數的日誌：Bash 命令、MCP 伺服器和工具名稱、Skill 名稱、使用者撰寫的工作流程名稱和工具輸入。也在 `user_prompt` 事件上啟用自訂、plugin 和 MCP 命令名稱（預設：停用） | `1` 以啟用 |124| `OTEL_LOG_TOOL_DETAILS` | 啟用在工具事件和追蹤跨度屬性中記錄工具參數和輸入引數的日誌：Bash 命令、MCP 伺服器和工具名稱、Skill 名稱、使用者撰寫的工作流程名稱和工具輸入。也在 `user_prompt` 事件上啟用自訂、plugin 和 MCP 命令名稱（預設：停用）。對於 Claude Desktop 的內建伺服器，在 Claude Desktop 擁有的工作階段中，`mcp_server_name`/`mcp_tool_name` 在 `tool_decision`/`tool_result` 上發出，即使旗標關閉。例外需要 Claude Code v2.1.214 或更新版本 | `1` 以啟用 |

98| `OTEL_LOG_TOOL_CONTENT` | 啟用在跨度事件中記錄工具輸入和輸出內容的日誌（預設：停用）。需要[追蹤](#traces-beta)。內容在 60 KB 處截斷 | `1` 以啟用 |125| `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` 指標 |126| `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` 指標 |

127| `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` | 內容限制：內容承載屬性的最大長度，例如模型回應、工具內容、系統提示和原始 API 主體，截斷標記包括在內，以 UTF-16 代碼單位計（預設：61440，即 60 KB）。預設值適用於將屬性值上限設為 64 KB 的後端；僅在您的後端接受更大值時提高它，或降低它以減少遙測量。當設定了 OpenTelemetry SDK 屬性限制 `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` 或其日誌記錄和跨度變體時，Claude Code 在該較小值處截斷，以便 `[TRUNCATED ...]` 標記保持在 SDK 限制內。需要 Claude Code v2.1.214 或更新版本 | `262144` |

101| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 重新整理動態標頭的間隔（預設：1740000ms / 29 分鐘） | `900000` |129| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 重新整理動態標頭的間隔（預設：1740000ms / 29 分鐘） | `900000` |

102 130

131對於 `http/protobuf` 和 `http/json` 協議，Claude Code 會使用 `Content-Length` 標頭傳送每個匯出請求。在 v2.1.212 之前，v2.1.191 及以後的 Claude Code 版本使用分塊傳輸編碼傳送這些請求；Azure Monitor 和其他需要聲明長度的端點以 `411 Length Required` 或 `400` 錯誤拒絕它們。

132

103<h3 id="mtls-authentication">133<h3 id="mtls-authentication">

104 mTLS 身份驗證134 mTLS 身份驗證

105</h3>135</h3>

111| `http/protobuf`、`http/json` | `CLAUDE_CODE_CLIENT_CERT`、`CLAUDE_CODE_CLIENT_KEY` 和可選的 `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE`。請參閱[網路配置](/docs/zh-TW/network-config#mtls-authentication) | `NODE_EXTRA_CA_CERTS` |141| `http/protobuf`、`http/json` | `CLAUDE_CODE_CLIENT_CERT`、`CLAUDE_CODE_CLIENT_KEY` 和可選的 `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE`。請參閱[網路配置](/docs/zh-TW/network-config#mtls-authentication) | `NODE_EXTRA_CA_CERTS` |

112| `grpc` | `OTEL_EXPORTER_OTLP_CLIENT_KEY` 和 `OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE`，或每個訊號的變體，例如 `OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY` 以針對每個訊號使用不同的憑證 | `OTEL_EXPORTER_OTLP_CERTIFICATE` |142| `grpc` | `OTEL_EXPORTER_OTLP_CLIENT_KEY` 和 `OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE`，或每個訊號的變體，例如 `OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY` 以針對每個訊號使用不同的憑證 | `OTEL_EXPORTER_OTLP_CERTIFICATE` |

113 143

114對於 `grpc`，OpenTelemetry SDK 直接讀取標準 OTLP 變數，因此設定每個訊號指標變數的現有配置會繼續運作。144對於 `grpc`，OpenTelemetry SDK 直接讀取標準 OTLP 變數，因此設定每個訊號指標變數的現有配置會繼續運作。在具有受管設定的機器上，Claude Code [可能會在啟動時移除開發人員設定的每個訊號認證和端點](#how-managed-settings-lock-the-otlp-destination)。

115 145

116<h3 id="metrics-cardinality-control">146<h3 id="metrics-cardinality-control">

117 指標基數控制147 指標基數控制

129 159

130這些變數有助於控制指標的基數，這會影響指標後端中的儲存需求和查詢效能。較低的基數通常意味著更好的效能和更低的儲存成本，但分析的資料粒度較低。160較低的基數通常意味著更好的效能和更低的儲存成本，但分析的資料粒度較低。

131 161

132<h3 id="traces-beta">162<h3 id="traces-beta">

133 Traces (beta)163 Traces (beta)

135 165

136分散式追蹤匯出跨度，將每個使用者提示連結到它觸發的 API 請求和工具執行，因此您可以在追蹤後端中將完整請求檢視為單個追蹤。166分散式追蹤匯出跨度，將每個使用者提示連結到它觸發的 API 請求和工具執行，因此您可以在追蹤後端中將完整請求檢視為單個追蹤。

137 167

138追蹤預設為關閉。若要啟用它，請同時設定 `CLAUDE_CODE_ENABLE_TELEMETRY=1` 和 `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`，然後設定 `OTEL_TRACES_EXPORTER` 以選擇跨度的傳送位置。追蹤重複使用[常見 OTLP 配置](#common-configuration-variables)以取得端點、協議、標頭和 [mTLS](#mtls-authentication)。168追蹤預設為關閉。若要啟用它，請同時設定 `CLAUDE_CODE_ENABLE_TELEMETRY=1` 和 `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`，然後設定 `OTEL_TRACES_EXPORTER` 以選擇跨度的傳送位置。追蹤重複使用[常見 OTLP 配置](#common-configuration-variables)以取得端點、協議、標頭和 [mTLS](#mtls-authentication)。在具有受管設定的機器上，Claude Code [可能會在啟動時移除開發人員設定的每個訊號認證和端點](#how-managed-settings-lock-the-otlp-destination)。

139 169

140| 環境變數 | 描述 | 範例值 |170| 環境變數 | 描述 | 範例值 |

141| ------------------------------------- | ----------------------------------------------- | ---------------------------------- |171| ------------------------------------- | ----------------------------------------------- | ---------------------------------- |

176| `OTEL_EXPORTER_OTLP_TRACES_HEADERS` | 追蹤的身份驗證標頭，與 `OTEL_EXPORTER_OTLP_HEADERS` 合併 | `Authorization=Bearer token` |

146| `OTEL_TRACES_EXPORT_INTERVAL` | 跨度批次匯出間隔（毫秒）（預設：5000） | `1000`、`10000` |177| `OTEL_TRACES_EXPORT_INTERVAL` | 跨度批次匯出間隔（毫秒）（預設：5000） | `1000`、`10000` |

147 178

148跨度預設會編輯使用者提示文字、工具輸入詳情和工具內容。設定 `OTEL_LOG_USER_PROMPTS=1`、`OTEL_LOG_TOOL_DETAILS=1` 和 `OTEL_LOG_TOOL_CONTENT=1` 以包含它們。179跨度預設會編輯使用者提示文字、工具輸入詳情和工具內容。設定 `OTEL_LOG_USER_PROMPTS=1`、`OTEL_LOG_TOOL_DETAILS=1` 和 `OTEL_LOG_TOOL_CONTENT=1` 以包含它們。

149 180

150當追蹤處於活動狀態時，Bash 和 PowerShell 子程序會自動繼承包含活動工具執行跨度的 W3C 追蹤上下文的 `TRACEPARENT` 環境變數。這讓任何讀取 `TRACEPARENT` 的子程序都可以在同一追蹤下將其自己的跨度作為父項，透過 Claude 執行的指令碼和命令啟用端到端分散式追蹤。181當追蹤處於活動狀態時，Bash 和 PowerShell 子程序會自動繼承包含活動工具執行跨度的 W3C 追蹤上下文的 `TRACEPARENT` 環境變數。這讓任何讀取 `TRACEPARENT` 的子程序都可以在同一追蹤下將其自己的跨度作為父項，透過 Claude 執行的指令碼和命令啟用端到端分散式追蹤。

151 182

152當追蹤處於活動狀態且 Claude Code 直接連接到 Anthropic API 時，每個模型請求都會攜帶設定為 `claude_code.llm_request` 跨度上下文的 W3C `traceparent` 標頭，並且 API 的 `traceresponse` 標頭被記錄為跨度連結。這些一起透過任何相容的中介將 Claude Code 的用戶端跨度連接到伺服器端追蹤。標頭不會傳送給第三方提供者。183當追蹤處於活動狀態且 Claude Code 直接連接到 Anthropic API 時，每個模型請求都會攜帶設定為 `claude_code.llm_request` 跨度上下文的 W3C `traceparent` 標頭，並且 API 的 `traceresponse` 標頭被記錄為跨度連結。這些一起透過任何相容的中介將 Claude Code 的用戶端跨度連接到伺服器端追蹤。出站 HTTP MCP 請求以相同方式攜帶 `traceparent`。標頭不會傳送給第三方提供者。

153 184

154預設情況下，模型和 HTTP MCP 請求上的 `traceparent` 標頭僅在 `ANTHROPIC_BASE_URL` 未設定或指向 Anthropic API 時傳送，因為某些代理會拒絕無法識別的標頭。子程序 `TRACEPARENT` 變數由相同的開關控制以保持一致性。如果您透過自訂 `ANTHROPIC_BASE_URL` 代理執行 Claude Code 並想要傳播追蹤上下文，請設定 `CLAUDE_CODE_PROPAGATE_TRACEPARENT=1`。185預設情況下，模型和 HTTP MCP 請求上的 `traceparent` 標頭僅在 `ANTHROPIC_BASE_URL` 未設定或指向 Anthropic API 時傳送，因為某些代理會拒絕無法識別的標頭。子程序 `TRACEPARENT` 變數由相同的開關控制以保持一致性。如果您透過自訂 `ANTHROPIC_BASE_URL` 代理執行 Claude Code 並想要傳播追蹤上下文，請設定 `CLAUDE_CODE_PROPAGATE_TRACEPARENT=1`。

155 186

156在 Agent SDK 和以 `-p` 啟動的非互動式工作階段中，Claude Code 也會在啟動每個互動跨度時從其自己的環境中讀取 `TRACEPARENT` 和 `TRACESTATE`。這讓嵌入程序將其活動 W3C 追蹤上下文傳遞到子程序中，以便 Claude Code 的跨度顯示為呼叫者分散式追蹤的子項。互動式工作階段會忽略入站 `TRACEPARENT` 以避免意外繼承來自 CI 或容器環境的環境值。187在 Agent SDK 和以 `-p` 啟動的非互動式工作階段中，Claude Code 也會在啟動每個互動跨度時從其自己的環境中讀取 `TRACEPARENT` 和 `TRACESTATE`。這讓嵌入程序將其活動 W3C 追蹤上下文傳遞到子程序中，以便 Claude Code 的跨度顯示為呼叫者分散式追蹤的子項。互動式工作階段會忽略入站 `TRACEPARENT` 以避免意外繼承來自 CI 或容器環境的環境值。

157 188

189入站追蹤上下文也適用於[事件](#events)。在 Agent SDK 和設定了 `TRACEPARENT` 的 `-p` 工作階段中，每個 OTLP 事件日誌記錄都攜帶 `trace_id` 和 `span_id` 值，將其連結到您的應用程式追蹤，即使未配置追蹤匯出器，您的日誌後端也可以將事件與追蹤的其餘部分相關聯。

190

191在互動跨度處於活動狀態時發出的記錄會攜帶互動跨度的 ID，即使 Claude Code 在跨度的非同步上下文之外發出它，例如在權限提示回呼或在啟動期間緩衝並稍後匯出的記錄中。在沒有活動互動跨度的情況下發出的記錄會直接攜帶入站 `TRACEPARENT` ID。在 v2.1.214 之前，在跨度的非同步上下文之外發出的記錄會攜帶入站 `TRACEPARENT` ID 而不是跨度的 ID。在 v2.1.212 之前，在活動跨度之外發出的事件記錄不會攜帶 `trace_id` 或 `span_id`。

192

158<h4 id="span-hierarchy">193<h4 id="span-hierarchy">

159 跨度階層194 跨度階層

160</h4>195</h4>

173 208

174在 Agent SDK 和 `claude -p` 工作階段中，當環境中設定 `TRACEPARENT` 時，`claude_code.interaction` 本身會成為呼叫者跨度的子項。209在 Agent SDK 和 `claude -p` 工作階段中，當環境中設定 `TRACEPARENT` 時，`claude_code.interaction` 本身會成為呼叫者跨度的子項。

175 210

211當 `PreToolUse` hook [延遲工具呼叫](/docs/zh-TW/hooks#defer-a-tool-call-for-later)時，Claude Code 會儲存延遲它的輪次的追蹤上下文。當您恢復工作階段並且工具重新執行時，工具的跨度會作為該較早輪次的 `claude_code.interaction` 跨度的子項加入該較早輪次的追蹤。

212

176<h4 id="span-attributes">213<h4 id="span-attributes">

177 跨度屬性214 跨度屬性

178</h4>215</h4>

182**`claude_code.interaction`**219**`claude_code.interaction`**

183 220

184| 屬性 | 描述 | 由以下控制 |221| 屬性 | 描述 | 由以下控制 |

185| ------------------------- | ------------------------------ | ----------------------- |222| ------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------- |

226| `parent.source` | 跨度如何獲得其追蹤父項：當它在入站 `TRACEPARENT` 下作為父項時為 `env`，當它啟動自己的追蹤時為 `none`。需要 Claude Code v2.1.268 或更新版本 | |

190 228

191**`claude_code.llm_request`**229**`claude_code.llm_request`**

192 230

193| 屬性 | 描述 | 由以下控制 |231| 屬性 | 描述 | 由以下控制 |

194| -------------------------------- | --------------------------------------------------------------------------------------------------- | ----------------------- |232| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |

237| `query_source_safe` | `query_source` 的有界形式，無論詳細 beta 追蹤是否活動都發出，具有 `repl_main_thread` 或 `agent.builtin.general-purpose` 等值。`:` 變成 `.`，使用者命名的代理顯示為 `agent.custom`。需要 Claude Code v2.1.268 或更新版本 | |

246| `first_content_ms` | 從請求開始到成功嘗試的第一個內容區塊的時間（毫秒）。在回退到非串流路徑的請求上不存在。需要 Claude Code v2.1.268 或更新版本 | |

258| `error_class` | 請求失敗時的短錯誤類別權杖，例如 `api_timeout` 或 `server_overload`。需要 Claude Code v2.1.268 或更新版本 | |

224**`claude_code.tool`**265**`claude_code.tool`**

225 266

226| 屬性 | 描述 | 由以下控制 |267| 屬性 | 描述 | 由以下控制 |

227| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |268| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------- |

270| `tool_name_safe` | `tool_name` 的形式，不攜帶任何使用者選擇的名稱。內建工具名稱逐字傳遞。MCP 工具名稱顯示為 `mcp_other`，除了符合幾個固定形狀的工具名稱，例如名為 `browser_*` 的 playwright 工具，它們逐字傳遞。需要 Claude Code v2.1.268 或更新版本 | |

271| `bash_command_class` | 對於 Bash 工具：命令的第一個程式的類別，來自固定清單，例如 `vcs` 或 `package_manager`。`other` 用於清單外的程式，`unparsed` 當行無法解析時。需要 Claude Code v2.1.268 或更新版本 | |

272| `bash_argv0` | 對於 Bash 工具：當命令的第一個程式在同一固定清單上時，例如 `git` 或 `npm`。`other` 用於清單外的任何程式。需要 Claude Code v2.1.268 或更新版本 | |

241 285

242當 `OTEL_LOG_TOOL_CONTENT=1` 時，此跨度也會記錄一個 `tool.output` 跨度事件，其屬性包含工具的輸入和輸出主體，在每個屬性處截斷 60 KB。286當 `OTEL_LOG_TOOL_CONTENT=1` 時，此跨度也會記錄一個 `tool.output` 跨度事件，其屬性包含工具的輸入和輸出主體，在內容限制處截斷（預設 60 KB）。

243 287

244**`claude_code.tool.blocked_on_user`**288**`claude_code.tool.blocked_on_user`**

245 289

252**`claude_code.tool.execution`**296**`claude_code.tool.execution`**

253 297

254| 屬性 | 描述 | 由以下控制 |298| 屬性 | 描述 | 由以下控制 |

255| --------------------- | ------------------------------------------------------------- | ----------------------- |299| --------------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------- |

305| `error_class` | 識別碼形式的錯誤類別，字母、數字和底線以外的字元被 `_` 取代，例如 `Error_ENOENT` 或 `ShellError`。即使 `error` 攜帶完整訊息，也會攜帶類別。需要 Claude Code v2.1.268 或更新版本 | |

261 306

262**`claude_code.hook`**307**`claude_code.hook`**

263 308

264此跨度僅在詳細 beta 追蹤處於活動狀態時發出，除了上述追蹤匯出器配置外，還需要 `ENABLE_BETA_TRACING_DETAILED=1` 和 `BETA_TRACING_ENDPOINT`。在互動式 CLI 工作階段中，這也需要您的組織被列入該功能的允許清單。Agent SDK 和非互動式 `-p` 工作階段不受限制。當僅設定 `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA` 時不會發出。309此跨度僅在詳細 beta 追蹤處於活動狀態時發出，需要 `ENABLE_BETA_TRACING_DETAILED=1` 和 `BETA_TRACING_ENDPOINT`，這對也[改變您的日誌和追蹤的去向](/docs/zh-TW/env-vars#variables)。在您的 shell、使用者設定或受管設定中設定該對；兩個變數都在[專案和本地設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中被忽略。`CLAUDE_CODE_ENHANCED_TELEMETRY_BETA` 單獨不會產生它。

310

311在互動式 CLI 工作階段中，詳細 beta 追蹤也需要您的組織被列入該功能的允許清單。Agent SDK 和非互動式 `-p` 工作階段不需要允許清單。

265 312

266| 屬性 | 描述 | 由以下控制 |313| 屬性 | 描述 | 由以下控制 |

267| ------------------------ | -------------------------------- | ----------------------- |314| ------------------------ | -------------------------------- | ----------------------- |

277 324

278<Note>325<Note>

279 其他內容承載屬性，例如 `new_context`、`system_prompt_preview`、`user_system_prompt`、`tool_input` 和 `response.model_output`，僅在詳細 beta 追蹤處於活動狀態時發出。它們不是穩定跨度架構的一部分。`user_system_prompt` 另外需要 `OTEL_LOG_USER_PROMPTS=1`。它僅包含您透過 `systemPrompt` SDK 選項或 `--system-prompt` 和 `--append-system-prompt` 旗標提供的系統提示文字，在 60 KB 處截斷，並且每個工作階段發出一次而不是每個請求發出一次。326 其他內容承載屬性，例如 `new_context`、`system_prompt_preview`、`user_system_prompt`、`tool_input` 和 `response.model_output`，僅在詳細 beta 追蹤處於活動狀態時發出。它們不是穩定跨度架構的一部分。

327

328 `user_system_prompt` 另外需要 `OTEL_LOG_USER_PROMPTS=1`。它僅包含您透過 `systemPrompt` SDK 選項或 `--system-prompt` 和 `--append-system-prompt` 旗標提供的系統提示文字，在內容限制處截斷（預設 60 KB），並且每個工作階段發出一次而不是每個請求發出一次。

280</Note>329</Note>

281 330

282<h3 id="dynamic-headers">331<h3 id="dynamic-headers">

283 動態標頭332 動態標頭

284</h3>333</h3>

285 334

286對於需要動態身份驗證的企業環境，您可以配置指令碼來動態產生標頭。動態標頭僅適用於 `http/protobuf` 和 `http/json` 協議。`grpc` 匯出器僅使用靜態 `OTEL_EXPORTER_OTLP_HEADERS` 值。335對於需要動態身份驗證的企業環境，您可以配置指令碼來動態產生標頭。動態標頭僅適用於 `http/protobuf` 和 `http/json` 協議。使用 `grpc` 協議，Claude Code 僅使用靜態標頭變數 `OTEL_EXPORTER_OTLP_HEADERS` 及其每個訊號變體。

287 336

288<h4 id="settings-configuration">337<h4 id="settings-configuration">

289 設定配置338 設定配置

290</h4>339</h4>

291 340

292新增至您的 `.claude/settings.json`：341新增至您的 `.claude/settings.json`，將路徑替換為您自己的指令碼：

293 342

294```json theme={null}343```json theme={null}

295{344{

296 "otelHeadersHelper": "/bin/generate_opentelemetry_headers.sh"345 "otelHeadersHelper": "/path/to/generate-otel-headers.sh"

297}346}

298```347```

299 348

373 配置範例422 配置範例

374</h3>423</h3>

375 424

376在執行 `claude` 之前設定這些環境變數。每個區塊顯示不同匯出器或部署情境的完整配置：425在執行 `claude` 之前設定這些環境變數。每個情境下方顯示完整配置，每個變數在[常見配置變數](#common-configuration-variables)下描述。若要確認配置生效，請在啟動工作階段後檢查您的後端是否有 `claude_code.session.count` 指標；[快速入門](#quick-start)涵蓋僅日誌驗證和當沒有任何內容到達時要檢查的內容。

426

427對於控制台除錯，間隔為 1 秒：

377 428

378```bash theme={null}429```bash theme={null}

379# 控制台除錯（1 秒間隔）

380export CLAUDE_CODE_ENABLE_TELEMETRY=1430export CLAUDE_CODE_ENABLE_TELEMETRY=1

381export OTEL_METRICS_EXPORTER=console431export OTEL_METRICS_EXPORTER=console

382export OTEL_METRIC_EXPORT_INTERVAL=1000432export OTEL_METRIC_EXPORT_INTERVAL=1000

433```

434

435對於 OTLP over gRPC：

383 436

384# OTLP/gRPC437```bash theme={null}

385export CLAUDE_CODE_ENABLE_TELEMETRY=1438export CLAUDE_CODE_ENABLE_TELEMETRY=1

386export OTEL_METRICS_EXPORTER=otlp439export OTEL_METRICS_EXPORTER=otlp

387export OTEL_EXPORTER_OTLP_PROTOCOL=grpc440export OTEL_EXPORTER_OTLP_PROTOCOL=grpc

388export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317441export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

442```

389 443

390# Prometheus444對於 Prometheus，從 `http://localhost:9464/metrics` 抓取：

445

446```bash theme={null}

391export CLAUDE_CODE_ENABLE_TELEMETRY=1447export CLAUDE_CODE_ENABLE_TELEMETRY=1

392export OTEL_METRICS_EXPORTER=prometheus448export OTEL_METRICS_EXPORTER=prometheus

449```

450

451在[自託管環境](/docs/zh-TW/self-hosted-environments-reference#pass-through-session-child-metrics)上，工作階段僅在執行器的預設容量為 1 時綁定連接埠 9464。在更高容量下，執行器改為在其自己的 `/metrics` 端點上重新公開工作階段計數器和量表。

452

453若要將指標傳送到多個匯出器：

393 454

394# 多個匯出器455```bash theme={null}

395export CLAUDE_CODE_ENABLE_TELEMETRY=1456export CLAUDE_CODE_ENABLE_TELEMETRY=1

396export OTEL_METRICS_EXPORTER=console,otlp457export OTEL_METRICS_EXPORTER=console,otlp

397export OTEL_EXPORTER_OTLP_PROTOCOL=http/json458export OTEL_EXPORTER_OTLP_PROTOCOL=http/json

459```

398 460

399# 指標和日誌的不同端點/後端461若要將指標和日誌傳送到不同的端點或後端：

462

463```bash theme={null}

400export CLAUDE_CODE_ENABLE_TELEMETRY=1464export CLAUDE_CODE_ENABLE_TELEMETRY=1

401export OTEL_METRICS_EXPORTER=otlp465export OTEL_METRICS_EXPORTER=otlp

402export OTEL_LOGS_EXPORTER=otlp466export OTEL_LOGS_EXPORTER=otlp

404export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://metrics.example.com:4318468export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://metrics.example.com:4318

405export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc469export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc

406export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.com:4317470export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.com:4317

471```

472

473若要僅匯出指標，不匯出事件或日誌：

407 474

408# 僅指標（無事件/日誌）475```bash theme={null}

409export CLAUDE_CODE_ENABLE_TELEMETRY=1476export CLAUDE_CODE_ENABLE_TELEMETRY=1

410export OTEL_METRICS_EXPORTER=otlp477export OTEL_METRICS_EXPORTER=otlp

411export OTEL_EXPORTER_OTLP_PROTOCOL=grpc478export OTEL_EXPORTER_OTLP_PROTOCOL=grpc

412export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317479export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

480```

481

482若要僅匯出事件和日誌，不匯出指標：

413 483

414# 僅事件/日誌（無指標）484```bash theme={null}

415export CLAUDE_CODE_ENABLE_TELEMETRY=1485export CLAUDE_CODE_ENABLE_TELEMETRY=1

416export OTEL_LOGS_EXPORTER=otlp486export OTEL_LOGS_EXPORTER=otlp

417export OTEL_EXPORTER_OTLP_PROTOCOL=grpc487export OTEL_EXPORTER_OTLP_PROTOCOL=grpc

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

443 513

454 指標524 指標

455</h3>525</h3>

456 526

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

458 528

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

460| ------------------------------------- | ------------------- | ------ |530| ------------------------------------- | ------------------- | ------ |

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

468| `claude_code.active_time.total` | 總活躍時間（秒） | s |538| `claude_code.active_time.total` | 總活躍時間 | s |

539

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

469 541

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

471 指標詳情543 指標詳情

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

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

535* `marketplace.name`：擁有 plugin 的安裝市場。僅針對官方市場 plugin 發出。否則不存在。607* `marketplace.name`：擁有 plugin 的安裝市場。僅針對官方市場 plugin 發出。否則不存在。

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

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

538 610

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

540 權杖計數器612 權杖計數器

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

571</h4>643</h4>

572 644

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

574 646

575**屬性**：647**屬性**：

576 648

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

591 663

592| 屬性 | 描述 |664| 屬性 | 描述 |

593| ----------- | ------------------------------- |665| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

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

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

595 669

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

597 671

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

599 `prompt.id` 有意從指標中排除，因為每個提示都會產生唯一的 ID，這會建立不斷增長的時間序列數量。僅將其用於事件級分析和稽核追蹤。673

600</Note>674* `message.uuid` 在 `user_prompt` 和 `assistant_response` 上

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

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

601 677

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

603 使用者提示事件679 使用者提示事件

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

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

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

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

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

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

620 697

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

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

635* `response_length`：回應文字的長度（字元數）712* `response_length`：回應文字的長度（字元數）

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

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

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

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

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

640 718

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

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

664* `tool_result_size_bytes`：工具結果的大小（位元組）742* `tool_result_size_bytes`：工具結果的大小（位元組）

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

666* `tool_parameters`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：包含工具特定參數的 JSON 字串：744* `tool_parameters`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：包含工具特定參數的 JSON 字串。對於 Claude Desktop 的內建伺服器，在 Claude Desktop 擁有的工作階段中，即使旗標關閉，`mcp_server_name`/`mcp_tool_name` 配對也會包含，與[工具決定事件](#tool-decision-event)相同的主機撰寫例外，需要 Claude Code v2.1.214 或更新版本。參數因工具而異：

667 * 對於 Bash 工具：包括 `bash_command`、`full_command`、`timeout`、`description`、`dangerouslyDisableSandbox` 和 `git_commit_id`（git commit 命令成功時的提交 SHA）745 * 對於 Bash 工具：包括 `bash_command`、`full_command`、`timeout`、`description`、`dangerouslyDisableSandbox` 和 `git_commit_id`（git commit 命令成功時的提交 SHA）。桌面應用程式的工作區 bash 工具也將 `tool_name` 報告為 `Bash`，但僅包括 `bash_command`、`full_command` 和 `timeout`

668 * 對於 WorkspaceBash 工具：包括 `bash_command`、`full_command`、`timeout`

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

670 * 對於 Skill 工具：包括 `skill_name`747 * 對於 Skill 工具：包括 `skill_name`

671 * 對於 Agent 工具或舊版 Task 工具：包括 `subagent_type`748 * 對於 Agent 工具或舊版 Task 工具：包括 `subagent_type`

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

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

689* `cost_usd`：估計成本（美元）766* `cost_usd`：估計成本（美元）

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

690* `duration_ms`：請求持續時間（毫秒）768* `duration_ms`：請求持續時間（毫秒）

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

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

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

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

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

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

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

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

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

718* `duration_ms`：請求持續時間（毫秒）797* `duration_ms`：請求持續時間（毫秒）

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

812* `source`：決定來源：896* `source`：決定來源：

813 * `"config"`：根據專案設定、使用者個人設定中的允許規則、企業受管原則、`--allowedTools` 或 `--disallowedTools` 旗標、活躍權限模式、來自同一互動 CLI 工作階段中較早提示的工作階段範圍授予或因為工具本身是安全的，自動決定而不提示。該事件不指示這些來源中的哪一個相符。897 * `"config"`：根據專案設定、使用者個人設定中的允許或拒絕規則、企業受管原則、`--allowedTools` 或 `--disallowedTools` 旗標、活躍權限模式、來自同一互動 CLI 工作階段中較早提示的工作階段範圍授予或因為工具本身是安全的，自動決定而不提示。該事件不指示這些來源中的哪一個相符。Claude Code 也在權限提示請求本身失敗時報告 `"config"`，例如當 Agent SDK 的 [`canUseTool`](/docs/zh-TW/agent-sdk/typescript#canusetool) 回呼或 [`--permission-prompt-tool`](/docs/zh-TW/cli-reference#cli-flags) 工具傳回無效結果時，或當輸入串流在請求待處理時關閉時。在 v2.1.216 之前，Claude Code 將這些失敗報告為 `"user_reject"`。

814 * `"hook"`：`PreToolUse` 或 `PermissionRequest` hook 傳回了決定。898 * `"hook"`：`PreToolUse` 或 `PermissionRequest` hook 傳回了決定。

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

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

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

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

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

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

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

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

823 * 對於 Skill 工具：包括 `skill_name`907 * 對於 Skill 工具：包括 `skill_name`

824 * 對於 Agent 工具或舊版 Task 工具：包括 `subagent_type`908 * 對於 Agent 工具或舊版 Task 工具：包括 `subagent_type`

881* `duration_ms`：連線嘗試持續時間（毫秒）965* `duration_ms`：連線嘗試持續時間（毫秒）

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

883* `is_plugin`：當伺服器由 plugin 提供時為 `true`，否則為 `false`967* `is_plugin`：當伺服器由 plugin 提供時為 `true`，否則為 `false`

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

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

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

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

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

941* `marketplace.name`：plugin 的安裝市場（如果已知）。在與 `plugin.name` 相同的條件下編輯為 `"third-party"`1025* `marketplace.name`：plugin 的安裝市場（如果已知）。在與 `plugin.name` 相同的條件下編輯為 `"third-party"`

942* `plugin.version`：來自 plugin 清單的版本。僅當名稱未被編輯且清單宣告版本時才包含1026* `plugin.version`：來自 plugin 清單的版本。僅當名稱未被編輯且清單宣告版本時才包含

943* `plugin.scope`：plugin 的來源類別：`"official"`、`"org"`、`"user-local"` 或 `"default-bundle"`1027* `plugin.scope`：plugin 的來源類別：`"official"`、`"community"`、`"org"`、`"user-local"` 或 `"default-bundle"`

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

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

946* `has_hooks`：plugin 是否貢獻 hooks1030* `has_hooks`：plugin 是否貢獻 hooks

947* `has_mcp`：plugin 是否貢獻 MCP 伺服器1031* `has_mcp`：plugin 是否貢獻 MCP 伺服器

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

986* `event.name`：`"at_mention"`1070* `event.name`：`"at_mention"`

987* `event.timestamp`：ISO 8601 時間戳1071* `event.timestamp`：ISO 8601 時間戳

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

989* `mention_type`：提及的類型（`"file"`、`"directory"`、`"agent"`、`"mcp_resource"`）1073* `mention_type`：提及的類型（`"file"`、`"directory"`、`"agent"`、`"mcp_resource"`、`"peer"`）。值 `"peer"` 表示您提及了[您的其他 Claude Code 工作階段之一](/docs/zh-TW/cross-session-messaging)。需要 Claude Code v2.1.232 或更新版本

990* `success`：提及是否成功解析（`"true"` 或 `"false"`）1074* `success`：提及是否成功解析（`"true"` 或 `"false"`）

991 1075

992<h4 id="api-retries-exhausted-event">1076<h4 id="api-retries-exhausted-event">

1030* `safe_mode`：當工作階段以 [`--safe-mode`](/docs/zh-TW/cli-reference) 啟動時為 `"true"`，否則為 `"false"`。需要 Claude Code v2.1.169 或更新版本1114* `safe_mode`：當工作階段以 [`--safe-mode`](/docs/zh-TW/cli-reference) 啟動時為 `"true"`，否則為 `"false"`。需要 Claude Code v2.1.169 或更新版本

1031* `hook_matcher`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：hook 配置中的匹配器字串（如果已設定）1115* `hook_matcher`（當 `OTEL_LOG_TOOL_DETAILS=1` 時）：hook 配置中的匹配器字串（如果已設定）

1032* `plugin.name`（當 `hook_source` 是 `"pluginHook"` 時）：貢獻 plugin 的名稱。對於官方市場和內建捆綁之外的 plugin，除非 `OTEL_LOG_TOOL_DETAILS=1`，否則值為 `"third-party"`1116* `plugin.name`（當 `hook_source` 是 `"pluginHook"` 時）：貢獻 plugin 的名稱。對於官方市場和內建捆綁之外的 plugin，除非 `OTEL_LOG_TOOL_DETAILS=1`，否則值為 `"third-party"`

1033* `plugin_id_hash`（當 `hook_source` 是 `"pluginHook"` 時）：plugin 名稱和市場的確定性雜湊，僅傳送到您配置的匯出器。讓您計算不同的貢獻 plugin，而無需記錄其名稱1117* `plugin_id_hash`（當 `hook_source` 是 `"pluginHook"` 時）：plugin 名稱和市場的確定性雜湊，僅傳送到您配置的匯出器。讓您計算不同的貢獻 plugin，而無需記錄其名稱。Claude Code 按[plugin 已載入事件](#plugin-loaded-event)下所述計算它

1034 1118

1035<h4 id="hook-execution-start-event">1119<h4 id="hook-execution-start-event">

1036 Hook 執行開始事件1120 Hook 執行開始事件

1121* `error`：壓縮失敗時的錯誤訊息1205* `error`：壓縮失敗時的錯誤訊息

1122* `precompute_reuse`：僅在 `trigger` 為 `"manual"` 時設定。自動壓縮可以在內容視窗填滿之前在背景中準備摘要，此屬性記錄 `/compact` 是否重複使用該準備的摘要。`"hit"` 表示它被重複使用；`"miss_custom_instructions"`、`"miss_hook"` 和 `"miss_not_ready"` 給出改為計算新摘要的原因。需要 Claude Code v2.1.153 或更新版本1206* `precompute_reuse`：僅在 `trigger` 為 `"manual"` 時設定。自動壓縮可以在內容視窗填滿之前在背景中準備摘要，此屬性記錄 `/compact` 是否重複使用該準備的摘要。`"hit"` 表示它被重複使用；`"miss_custom_instructions"`、`"miss_hook"` 和 `"miss_not_ready"` 給出改為計算新摘要的原因。需要 Claude Code v2.1.153 或更新版本

1123 1207

1208<h4 id="subagent-completed-event">

1209 子代理已完成事件

1210</h4>

1211

1212當[子代理](/docs/zh-TW/sub-agents)完成並將其結果傳回啟動它的對話時記錄。使用它按子代理類型匯總工具使用和執行時間；對於權杖或成本匯總，使用[權杖計數器](#token-counter)和[成本計數器](#cost-counter)篩選到 `query_source` `"subagent"`，因為此事件的 `total_tokens` 僅涵蓋最終請求。`"subagent"` 類別也計算來自代理型 hooks 的請求，不發出子代理事件。

1213

1214**事件名稱**：`claude_code.subagent_completed`

1215

1216**屬性**：

1217

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

1219* `event.name`：`"subagent_completed"`

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

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

1222* `agent_type`：子代理類型。內建代理名稱和官方市場 plugin 的代理按原樣出現；其他代理名稱除非 `OTEL_LOG_TOOL_DETAILS=1` 設定，否則被替換為 `"custom"`

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

1224* `is_built_in`：子代理是否為內建代理類型

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

1226* `total_tokens`：子代理最終 API 請求的權杖足跡：該單個請求的輸入、快取建立、快取讀取和輸出權杖，大約是子代理在完成時的內容大小。不是整個執行的總和

1227* `total_tool_uses`：子代理在整個執行中進行的工具呼叫數

1228* `duration_ms`：執行時間（毫秒）

1229* `model`：子代理被解析為執行的模型

1230* `final_model`：產生子代理最終回應的模型，在中途切換（例如後備）後與 `model` 不同。需要 Claude Code v2.1.212 或更新版本

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

1232* `plugin_id_hash`、`plugin.name`：存在於 plugin 提供的代理。官方市場 plugin 名稱按原樣出現；其他 plugin 名稱除非 `OTEL_LOG_TOOL_DETAILS=1` 設定，否則被替換為 `"third-party"`

1233

1124<h4 id="feedback-survey-event">1234<h4 id="feedback-survey-event">

1125 回饋調查事件1235 回饋調查事件

1126</h4>1236</h4>

1141* `response`：使用者在 `responded` 事件上的選擇1251* `response`：使用者在 `responded` 事件上的選擇

1142* `enabled_via_override`：當設定 [`CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL`](/docs/zh-TW/env-vars) 時為 `true`。作為布林值而非字串發出。存在於 `session` 調查事件上。篩選此屬性以確認覆蓋在整個環境中應用1252* `enabled_via_override`：當設定 [`CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL`](/docs/zh-TW/env-vars) 時為 `true`。作為布林值而非字串發出。存在於 `session` 調查事件上。篩選此屬性以確認覆蓋在整個環境中應用

1143 1253

1254<h4 id="retention-sweep-event">

1255 保留掃描事件

1256</h4>

1257

1258在保留清理掃描執行時記錄一次，該掃描刪除[工作階段文字記錄和其他應用程式資料](/docs/zh-TW/claude-directory#cleaned-up-automatically)早於 [`cleanupPeriodDays`](/docs/zh-TW/settings-reference#cleanupperioddays) 設定的資料。Claude Code 在背景中最多每個工作階段執行一次掃描，刪除任何內容的執行仍會發出事件。如果 Claude Code 在過去 24 小時內在同一機器上的任何工作階段中執行了掃描，它會將此工作階段的掃描延遲至少 10 分鐘，因此更早退出的工作階段不會發出任何內容。當您使用 `--bare` 執行 `claude -p` 時，Claude Code 不會執行掃描且不會發出任何內容。

1259

1260與此頁面上的每個 OTel 事件一樣，它僅進入您配置的遙測後端。需要 Claude Code v2.1.227 或更新版本。

1261

1262當 Claude Code 無法安全地確定保留期時，它會暫停掃描並發出事件，`result` 設定為 `"skipped"` 和 `skip_reason`。當[受管設定](/docs/zh-TW/server-managed-settings)設定 `cleanupPeriodDays` 時，受管值會固定保留期，掃描即使在較低優先級範圍中的設定檔案損壞或無效時也會執行。當 `managed-settings.json` 本身無法讀取時，Claude Code 仍會暫停掃描，除非[受管層](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)從其他地方（例如伺服器受管設定或損壞檔案旁的 `managed-settings.d/` 放置）提供 `cleanupPeriodDays`。刪除計數器屬性僅在 `result` 為 `"complete"` 時存在。

1263

1264**事件名稱**：`claude_code.retention_sweep`

1265

1266**屬性**：

1267

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

1269* `event.name`：`"retention_sweep"`

1270* `event.timestamp`：ISO 8601 時間戳

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

1272* `result`：掃描執行時為 `"complete"`，Claude Code 暫停時為 `"skipped"`

1273* `period_days`：合併設定中的 `cleanupPeriodDays` 值（以天為單位），或當沒有來源設定時為 `30`。在跳過的事件上，掃描會使用的值，從 Claude Code 可以讀取的設定來源計算

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

1275* `skip_reason`：Claude Code 暫停掃描的原因。僅當 `result` 為 `"skipped"` 時存在：

1276 * `"user_source_disabled"`：使用者設定被排除，例如透過 [`--setting-sources`](/docs/zh-TW/cli-reference#cli-flags) 旗標或 SDK 的 [`settingSources`](/docs/zh-TW/agent-sdk/typescript#options) 選項，且沒有啟用的來源提供 `cleanupPeriodDays`

1277 * `"settings_unknowable"`：設定檔案無法讀取或解析，因此 `cleanupPeriodDays` 或 `desktopSessionCleanupPeriodDays` 可能設定為 Claude Code 無法看到的值

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

1279* `transcripts_deleted`：掃描刪除的工作階段文字記錄數，頂級 `~/.claude/projects/*/*.jsonl` 檔案

1280* `transcripts_exempted_desktop`：超過保留期的文字記錄數，掃描在[Claude Desktop 和 Cowork 規則](/docs/zh-TW/claude-directory#cleaned-up-automatically)下保留。這些不計入 `files_past_cutoff`。需要 Claude Code v2.1.248 或更新版本

1281* `session_files_deleted`：工作階段檔案掃描刪除的項目數：文字記錄加每個工作階段的伴隨檔案，例如邊車、錄製和工具結果

1282* `artifacts_deleted`：掃描跨越其涵蓋的資料目錄刪除的總項目，包括工作階段檔案。某些掃描將整個移除的目錄樹計為一個項目，少數清理通過不貢獻計數器，因此將值視為下限而不是精確檔案計數

1283* `files_retained_fresh`：檢查並保留在原位的檔案，因為它們仍在保留期內。僅每個檔案掃描計算這些，因此值是下限；非零值是正常穩定狀態

1284* `files_past_cutoff`：超過保留期的檔案，掃描無法刪除，例如因為權限錯誤或檔案被保持開啟。值高於零表示檔案超過配置的保留期；零不是證明沒有任何檔案，因為整個目錄的失敗移除計入 `error_count` 代替

1285* `error_count`：掃描在列出或刪除檔案時遇到的錯誤數

1286

1144<h2 id="interpret-metrics-and-events-data">1287<h2 id="interpret-metrics-and-events-data">

1145 解釋指標和事件資料1288 解釋指標和事件資料

1146</h2>1289</h2>

1172 成本指標是近似值。如需官方帳單資料，請參閱您的 API 提供者（Claude Console、Amazon Bedrock 或 Google Cloud 的 Agent Platform）。1315 成本指標是近似值。如需官方帳單資料，請參閱您的 API 提供者（Claude Console、Amazon Bedrock 或 Google Cloud 的 Agent Platform）。

1173</Note>1316</Note>

1174 1317

1318Claude Code 將每個串流回應計入成本和權杖指標中恰好一次，包括當閘道或代理在 `ANTHROPIC_BASE_URL` 後面跨多個框架逐步串流使用情況時。在 v2.1.214 之前，在多個框架中攜帶使用情況的串流會使 `claude_code.cost.usage` 和 `claude_code.token.usage` 膨脹，大約每個額外框架增加一個完整請求。

1319

1175<h3 id="alerting-and-segmentation">1320<h3 id="alerting-and-segmentation">

1176 警報和分段1321 警報和分段

1177</h3>1322</h3>

1182* 異常的權杖消耗1327* 異常的權杖消耗

1183* 來自特定使用者的高工作階段量1328* 來自特定使用者的高工作階段量

1184 1329

1185所有指標都可以按[標準屬性](#standard-attributes)進行分段。`model` 屬性可在 `claude_code.token.usage`、`claude_code.cost.usage` 上使用，以及從 v2.1.172 開始，`claude_code.lines_of_code.count` 上也可使用。提交的按模型細分只能透過在 `session.id` 上與權杖或成本指標進行聯接來近似，因為一個工作階段可以跨越多個模型。篩選權杖或成本端的列，使 `query_source` 為 `"main"`，以便輔助和子代理請求不會將工作階段的提交歸因於未進行提交的模型。1330所有指標都可以按[標準屬性](#standard-attributes)進行分段。`model` 屬性可在 `claude_code.token.usage`、`claude_code.cost.usage` 上使用，以及從 v2.1.172 開始，`claude_code.lines_of_code.count` 上也可使用。

1331

1332提交的按模型細分只能透過在 `session.id` 上與權杖或成本指標進行聯接來近似，因為一個工作階段可以跨越多個模型。篩選權杖或成本端的列，使 `query_source` 為 `"main"`，以便輔助和子代理請求不會將工作階段的提交歸因於未進行提交的模型。

1186 1333

1187<h3 id="detect-retry-exhaustion">1334<h3 id="detect-retry-exhaustion">

1188 偵測重試耗盡1335 偵測重試耗盡

1190 1337

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

1192 1339

1193事件上的 `attempt` 屬性記錄進行的嘗試總次數。`CLAUDE_CODE_MAX_RETRIES` 預設為 10，上限為 15；從 v2.1.199 開始，`CLAUDE_CODE_RETRY_WATCHDOG` 提高了預設值並移除了上限。當請求在暫時性錯誤上耗盡所有重試時，`attempt` 等於該有效限制加一：預設為 11，除非設定了看門狗，否則永遠不超過 16。較低的值表示不可重試的錯誤，例如 `400` 回應。1340事件上的 `attempt` 屬性記錄進行的嘗試總次數。`CLAUDE_CODE_MAX_RETRIES` 預設為 10，上限為 15。在 v2.1.199 或更新版本上，您可以設定 `CLAUDE_CODE_RETRY_WATCHDOG` 以提高預設值並移除上限。

1341

1342當請求在暫時性錯誤上耗盡所有重試時，`attempt` 等於該有效限制加一：預設為 11，除非設定了看門狗，否則永遠不超過 16。較低的值表示不可重試的錯誤，例如 `400` 回應，或具有自己較小重試預算的原因。例如，Claude Code 最多重試兩次載入 AWS 或 Google Cloud 認證的失敗。

1194 1343

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

1196 1345

1219 將屬性操作歸因於使用者1368 將屬性操作歸因於使用者

1220</h3>1369</h3>

1221 1370

1222每個事件上的[標準屬性](#standard-attributes)包括已驗證使用者的身份：使用 Claude 帳戶登入時的 `user.email`、`user.account_uuid`、`user.account_id` 和 `organization.id`，加上 `user.id` 和每個工作階段的 `session.id`。`user.id` 是安裝範圍的識別碼，除了在 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway) 工作階段上，其中它是來自閘道簽發令牌的 IdP 主體。1371每個事件上的[標準屬性](#standard-attributes)包括已驗證使用者的身份：使用 Claude 帳戶登入時的 `user.email`、`user.account_uuid`、`user.account_id` 和 `organization.id`，或在[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)中，當工作階段自身的認證攜帶它們時，加上 `user.id` 和每個工作階段的 `session.id`。`user.id` 是安裝範圍的識別碼，除了在 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway) 工作階段上，其中它是來自閘道簽發令牌的 IdP 主體。

1223 1372

1224MCP 工具呼叫、Bash 命令和檔案編輯因此歸因於啟動工作階段的開發人員。Claude Code 不在單獨的服務帳戶下運作；每個事件上記錄的身份是開發人員自己的 Claude 帳戶，或開發人員在 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway) 工作階段上的 IdP 身份。1373MCP 工具呼叫、Bash 命令和檔案編輯因此歸因於啟動工作階段的開發人員。Claude Code 不在單獨的服務帳戶下運作；每個事件上記錄的身份是開發人員自己的 Claude 帳戶，或開發人員在 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway) 工作階段上的 IdP 身份。

1225 1374

1243 1392

1244沒有 `OTEL_LOG_TOOL_DETAILS`，這些事件會捨棄識別詳情：1393沒有 `OTEL_LOG_TOOL_DETAILS`，這些事件會捨棄識別詳情：

1245 1394

1246* `tool_result`：保留 `tool_name` 和 `mcp_server_scope`，省略 `mcp_server_name`、`mcp_tool_name` 和引數1395* `tool_result`：保留 `mcp_server_scope` 和 `tool_name` 對使用者設定的伺服器編輯為字面上的 `"mcp_tool"`，省略引數內容。對於 Claude Desktop 的內建伺服器，在 Claude Desktop 擁有的工作階段中，它也保留 `tool_parameters` 內的 `mcp_server_name`/`mcp_tool_name` 配對，與 `tool_decision` 相同的主機編寫例外，需要 Claude Code v2.1.214 或更新版本

1247* `tool_decision`：保留 `tool_name`，省略 `tool_parameters`1396* `tool_decision`：保留 `tool_source` 和 `tool_name` 對使用者設定的伺服器編輯為字面上的 `"mcp_tool"`，省略引數內容。對於 Claude Desktop 的內建伺服器，在 Claude Desktop 擁有的工作階段中，它也保留 `tool_parameters` 內的 `mcp_server_name`/`mcp_tool_name` 配對；`tool_source` 和名稱配對都需要 Claude Code v2.1.214 或更新版本

1248* `mcp_server_connection`：省略 `server_name` 和錯誤訊息，但保留 `is_plugin`、`plugin_id_hash` 和 `plugin.name`，非 Anthropic plugin 名稱被編輯為字面上的 `"third-party"`，因此 plugin 提供的伺服器在沒有詳細日誌的情況下仍然可以區分1397* `mcp_server_connection`：省略 `server_name` 和錯誤訊息，但保留 `is_plugin`、`plugin_id_hash` 和 `plugin.name`，非 Anthropic plugin 名稱被編輯為字面上的 `"third-party"`，因此 plugin 提供的伺服器在沒有詳細日誌的情況下仍然可以區分

1249 1398

1250<h3 id="map-security-questions-to-events">1399<h3 id="map-security-questions-to-events">

1284}1433}

1285```1434```

1286 1435

1436若要確認事件已到達，請在執行此設定的工作階段中提交提示，並檢查您的 SIEM 是否有 `claude_code.user_prompt` 事件。如果沒有任何內容到達，請執行 `claude --debug` 並檢查偵錯日誌中的 `[3P telemetry]` 匯出錯誤。

1437

1287<h2 id="backend-considerations">1438<h2 id="backend-considerations">

1288 後端考量1439 後端考量

1289</h2>1440</h2>

1294 對於指標1445 對於指標

1295</h3>1446</h3>

1296 1447

1297* **時間序列資料庫（例如，Prometheus）**：速率計算、聚合指標1448* **時間序列資料庫**：速率計算、聚合指標

1298* **欄式存儲（例如，ClickHouse）**：複雜查詢、唯一使用者分析1449* **欄式存儲**：複雜查詢、唯一使用者分析

1299* **功能完整的可觀測性平台（例如，Honeycomb、Datadog、Grafana Cloud）**：進階查詢、視覺化、警報1450* **功能完整的可觀測性平台**：進階查詢、視覺化、警報

1300 1451

1301<h3 id="for-events/logs">1452<h3 id="for-events/logs">

1302 對於事件/日誌1453 對於事件/日誌

1303</h3>1454</h3>

1304 1455

1305* **日誌聚合系統（例如，Elasticsearch、Loki）**：全文搜尋、日誌分析1456* **日誌聚合系統**：全文搜尋、日誌分析

1306* **欄式存儲（例如，ClickHouse）**：結構化事件分析1457* **欄式存儲**：結構化事件分析

1307* **功能完整的可觀測性平台（例如，Honeycomb、Datadog、Grafana Cloud）**：指標和事件之間的關聯1458* **功能完整的可觀測性平台**：指標和事件之間的關聯

1308 1459

1309<h3 id="for-traces">1460<h3 id="for-traces">

1310 對於追蹤1461 對於追蹤

1312 1463

1313選擇支援分散式追蹤儲存和跨度關聯的後端：1464選擇支援分散式追蹤儲存和跨度關聯的後端：

1314 1465

1315* **分散式追蹤系統（例如，Jaeger、Zipkin、Grafana Tempo）**：跨度視覺化、請求瀑布圖、延遲分析1466* **分散式追蹤系統**：跨度視覺化、請求瀑布圖、延遲分析

1316* **功能完整的可觀測性平台（例如，Honeycomb、Datadog、Grafana Cloud）**：追蹤搜尋和與指標和日誌的關聯1467* **功能完整的可觀測性平台**：追蹤搜尋和與指標和日誌的關聯

1317 1468

1318對於需要日活躍使用者/週活躍使用者/月活躍使用者 (DAU/WAU/MAU) 指標的組織，請考慮支援高效唯一值查詢的後端。1469對於需要日活躍使用者/週活躍使用者/月活躍使用者 (DAU/WAU/MAU) 指標的組織，請考慮支援高效唯一值查詢的後端。

1319 1470

1323 1474

1324所有指標和事件都使用以下資源屬性匯出：1475所有指標和事件都使用以下資源屬性匯出：

1325 1476

1326* `service.name`：`claude-code`1477* `service.name`：終端機工作階段為 `claude-code`，從 [Claude Desktop 應用程式](/docs/zh-TW/desktop)中的 Code 標籤啟動的工作階段為 `claude-code-desktop`

1327* `service.version`：目前的 Claude Code 版本1478* `service.version`：目前的 Claude Code 版本，或 Code 標籤工作階段的 Desktop 應用程式版本

1328* `os.type`：作業系統類型（例如，`linux`、`darwin`、`windows`）1479* `os.type`：作業系統類型（例如，`linux`、`darwin`、`windows`）

1329* `os.version`：作業系統版本字串1480* `os.version`：作業系統版本字串

1330* `host.arch`：主機架構（例如，`amd64`、`arm64`）1481* `host.arch`：主機架構（例如，`amd64`、`arm64`）

1331* `wsl.version`：WSL 版本號（僅在 Windows Subsystem for Linux 上執行時出現）1482* `wsl.version`：WSL 版本號（僅在 Windows Subsystem for Linux 上執行時出現）

1332* 計量器名稱：`com.anthropic.claude_code`1483* 計量器名稱：`com.anthropic.claude_code`

1333 1484

1485如果您的收集器管道或儀表板在 `service.name = claude-code` 上進行篩選，請將 `claude-code-desktop` 新增至篩選條件，以同時擷取來自 Code 標籤工作階段的遙測資料。

1486

1334<h2 id="roi-measurement-resources">1487<h2 id="roi-measurement-resources">

1335 ROI 測量資源1488 ROI 測量資源

1336</h2>1489</h2>

1343 1496

1344* OpenTelemetry 匯出到您的後端是選擇加入的，需要明確配置。如需了解 Anthropic 的獨立營運遙測以及如何停用它，請參閱[資料使用](/docs/zh-TW/data-usage#telemetry-services)1497* OpenTelemetry 匯出到您的後端是選擇加入的，需要明確配置。如需了解 Anthropic 的獨立營運遙測以及如何停用它，請參閱[資料使用](/docs/zh-TW/data-usage#telemetry-services)

1345* 原始檔案內容和程式碼片段不包含在指標或事件中。追蹤跨度是單獨的資料路徑：請參閱下面的 `OTEL_LOG_TOOL_CONTENT` 項目1498* 原始檔案內容和程式碼片段不包含在指標或事件中。追蹤跨度是單獨的資料路徑：請參閱下面的 `OTEL_LOG_TOOL_CONTENT` 項目

1346* 透過 OAuth 驗證時，`user.email` 包含在遙測屬性中。如果這對您的組織是個問題，請與您的遙測後端合作以篩選或編輯此欄位1499* 透過 OAuth 驗證時，`user.email` 包含在遙測屬性中，僅傳送到您配置的 OTel 端點，絕不會傳送到 Anthropic。如果這對您的組織是個問題，請與您的遙測後端合作以篩選或編輯此欄位

1347* 預設不收集使用者提示內容。僅記錄提示長度。若要包含提示內容，請設定 `OTEL_LOG_USER_PROMPTS=1`1500* 預設不收集使用者提示內容。僅記錄提示長度。若要包含提示內容，請設定 `OTEL_LOG_USER_PROMPTS=1`

1348* 助理回應文字預設不收集。僅記錄回應長度。若要包含回應文字，請設定 `OTEL_LOG_ASSISTANT_RESPONSES=1`。如同 Claude Code 的所有 OpenTelemetry 資料，回應文字僅傳送到您配置的 OTel 端點，絕不會傳送到 Anthropic。當此變數未設定時，`OTEL_LOG_USER_PROMPTS` 會用作備用方案，因此如果您想要提示內容而不要回應內容，請設定 `OTEL_LOG_ASSISTANT_RESPONSES=0`1501* 助理回應文字預設不收集。僅記錄回應長度。若要包含回應文字，請設定 `OTEL_LOG_ASSISTANT_RESPONSES=1`。如同 Claude Code 的所有 OpenTelemetry 資料，回應文字僅傳送到您配置的 OTel 端點，絕不會傳送到 Anthropic。當此變數未設定時，`OTEL_LOG_USER_PROMPTS` 會用作備用方案，因此如果您想要提示內容而不要回應內容，請設定 `OTEL_LOG_ASSISTANT_RESPONSES=0`

1349* 工具輸入引數和參數預設不記錄。若要包含它們，請設定 `OTEL_LOG_TOOL_DETAILS=1`。此資料僅傳送到您配置的 OTEL 端點，絕不會傳送到 Anthropic。引數仍可能包含敏感值，因此請根據需要配置您的遙測後端以篩選或編輯這些屬性。啟用時：1502* 工具輸入引數和參數預設不記錄。若要包含它們，請設定 `OTEL_LOG_TOOL_DETAILS=1`。針對 Claude Desktop 的內建伺服器，在 Claude Desktop 擁有的工作階段中，`tool_decision` 和 `tool_result` 帶有 `mcp_server_name`/`mcp_tool_name` 配對，即主機撰寫的名稱而非引數內容，即使旗標關閉也是如此。此例外需要 Claude Code v2.1.214 或更新版本。此資料僅傳送到您配置的 OTEL 端點，絕不會傳送到 Anthropic。引數仍可能包含敏感值，因此請根據需要配置您的遙測後端以篩選或編輯這些屬性。啟用時：

1350 * `tool_result` 和 `tool_decision` 事件包含 `tool_parameters` 屬性，其中包含 Bash 命令、MCP 伺服器和工具名稱以及技能名稱。`full_command` 等欄位未截斷地發出1503 * `tool_result` 和 `tool_decision` 事件包含 `tool_parameters` 屬性，其中包含 Bash 命令、MCP 伺服器和工具名稱以及技能名稱。`full_command` 等欄位未截斷地發出

1351 * `tool_result` 事件另外包含 `tool_input` 屬性，其中包含檔案路徑、URL、搜尋模式和其他引數。超過 512 個字元的個別值會被截斷，總計上限約為 4 K 字元1504 * `tool_result` 事件另外包含 `tool_input` 屬性，其中包含檔案路徑、URL、搜尋模式和其他引數。超過 512 個字元的個別值會被截斷，總計上限約為 4 K 字元

1352 * `user_prompt` 事件包含自訂、plugin 和 MCP 命令的逐字 `command_name`1505 * `user_prompt` 事件包含自訂、plugin 和 MCP 命令的逐字 `command_name`

1353 * 追蹤跨度包含相同的 `tool_input` 屬性和輸入衍生屬性，例如 `file_path`，截斷方式與 `tool_input` 相同1506 * 追蹤跨度包含相同的 `tool_input` 屬性和輸入衍生屬性，例如 `file_path`，截斷方式與 `tool_input` 相同

1354* 工具輸入和輸出內容預設不在追蹤跨度中記錄。若要包含它，請設定 `OTEL_LOG_TOOL_CONTENT=1`。啟用時，跨度事件包含完整工具輸入和輸出內容，在每個跨度處截斷 60 KB。這可以包含來自 Read 工具結果的原始檔案內容和 Bash 命令輸出。根據需要配置您的遙測後端以篩選或編輯這些屬性1507* 工具輸入和輸出內容預設不在追蹤跨度中記錄。若要包含它，請設定 `OTEL_LOG_TOOL_CONTENT=1`。啟用時，跨度事件包含完整工具輸入和輸出內容，在內容限制（預設 60 KB）處按屬性截斷。這可以包含來自 Read 工具結果的原始檔案內容和 Bash 命令輸出。根據需要配置您的遙測後端以篩選或編輯這些屬性

1355* 原始 Anthropic Messages API 請求和回應主體預設不記錄。若要包含它們，請設定 `OTEL_LOG_RAW_API_BODIES`。使用 `=1` 時，每個 API 呼叫發出 `api_request_body` 和 `api_response_body` 日誌事件，其 `body` 屬性是 JSON 序列化的承載，在 60 KB 處截斷。使用 `=file:<dir>` 時，未截斷的主體寫入該目錄下的 `.request.json` 和 `.response.json` 檔案，事件帶有 `body_ref` 路徑而不是內聯主體。使用日誌收集器或邊車傳送目錄，而不是透過遙測流。在兩種模式中，主體包含完整的對話歷史記錄（系統提示、每個先前的使用者和助手輪次、工具結果），因此啟用此選項意味著同意其他 `OTEL_LOG_*` 內容旗標會揭露的所有內容。Claude 的擴展思考內容始終從這些主體中編輯，無論其他設定如何1508* 原始 Anthropic Messages API 請求和回應主體預設不記錄。若要包含它們，請在您的 shell、使用者設定或受管設定中設定 `OTEL_LOG_RAW_API_BODIES`。在[專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略。主體包含完整的對話歷史記錄，包括系統提示、每個先前的使用者和助手輪次以及工具結果，因此啟用此選項意味著同意其他 `OTEL_LOG_*` 內容旗標會揭露的所有內容。Claude Code 始終從這些主體中編輯 Claude 的擴展思考內容，無論其他設定如何。您設定的值決定了 Claude Code 如何傳遞主體：

1509 * 使用 `=1` 時，Claude Code 為每個 API 呼叫發出 `api_request_body` 和 `api_response_body` 日誌事件。事件的 `body` 屬性帶有 JSON 序列化的承載，在內容限制（預設 60 KB）處截斷

1510 * 使用 `=file:<dir>` 時，Claude Code 將未截斷的主體寫入該目錄下的 `.request.json` 和 `.response.json` 檔案，事件帶有 `body_ref` 路徑而不是內聯主體。使用日誌收集器或邊車傳送目錄，而不是透過遙測流

1356 1511

1357<h2 id="monitor-claude-code-on-amazon-bedrock">1512<h2 id="monitor-claude-code-on-amazon-bedrock">

1358 在 Amazon Bedrock 上監控 Claude Code1513 在 Amazon Bedrock 上監控 Claude Code

overview.md +13 −13

Details

18 <Tab title="終端機">18 <Tab title="終端機">

19 功能完整的 CLI，用於直接在您的終端機中使用 Claude Code。編輯檔案、執行命令，並從命令列管理您的整個專案。19 功能完整的 CLI，用於直接在您的終端機中使用 Claude Code。編輯檔案、執行命令，並從命令列管理您的整個專案。

20 20

~~21 To install Claude Code, use one of the following methods:~~21 若要安裝 Claude Code，請使用下列其中一種方法：

22 22

23 <Tabs>23 <Tabs>

~~24 <Tab title="Native Install (Recommended)">~~24 <Tab title="原生安裝（建議）">

~~25 **macOS, Linux, WSL:**~~25 **macOS、Linux、WSL：**

26 26

27 ```bash theme={null}27 ```bash theme={null}

28 curl -fsSL https://claude.ai/install.sh | bash28 curl -fsSL https://claude.ai/install.sh | bash

29 ```29 ```

30 30

~~31 **Windows PowerShell:**~~31 **Windows PowerShell：**

32 32

33 ```powershell theme={null}33 ```powershell theme={null}

34 irm https://claude.ai/install.ps1 | iex34 irm https://claude.ai/install.ps1 | iex

35 ```35 ```

36 36

~~37 **Windows CMD:**~~37 **Windows CMD：**

38 38

39 ```batch theme={null}39 ```batch theme={null}

40 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd40 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

41 ```41 ```

42 42

43 If you see `The token '&&' is not a valid statement separator`, you're in PowerShell, not CMD. If you see `'irm' is not recognized as an internal or external command`, you're in CMD, not PowerShell. Your prompt shows `PS C:\` when you're in PowerShell and `C:\` without the `PS` when you're in CMD.43 如果您看到 `The token '&&' is not a valid statement separator`，表示您在 PowerShell 中，而非 CMD。如果您看到 `'irm' is not recognized as an internal or external command`，表示您在 CMD 中，而非 PowerShell。當您在 PowerShell 中時，提示符會顯示 `PS C:\`，而在 CMD 中時會顯示 `C:\`（不含 `PS`）。

44 44

45 If the install command fails with `syntax error near unexpected token '<'`, a `403`, or another curl error, see [Troubleshoot installation](/docs/en/troubleshoot-install#find-your-error) to match the error to a fix and for alternative install methods.45 如果安裝命令失敗並出現 `syntax error near unexpected token '<'`、`403` 或其他 curl 錯誤，請參閱[疑難排解安裝](/docs/zh-TW/troubleshoot-install#find-your-error)以將錯誤與修正相對應，並查看替代安裝方法。

46 46

47 [Git for Windows](https://git-scm.com/downloads/win) is recommended on native Windows so Claude Code can use the Bash tool. If Git for Windows is not installed, Claude Code uses PowerShell as the shell tool instead. WSL setups do not need Git for Windows.47 建議在原生 Windows 上安裝 [Git for Windows](https://git-scm.com/downloads/win)，以便 Claude Code 可以使用 Bash 工具。如果未安裝 Git for Windows，Claude Code 會改用 PowerShell 作為殼層工具。WSL 設定不需要 Git for Windows。

48 48

49 <Info>49 <Info>

~~50 Native installations automatically update in the background to keep you on the latest version.~~50 原生安裝會在背景自動更新，以保持您使用最新版本。

51 </Info>51 </Info>

52 </Tab>52 </Tab>

53 53

56 brew install --cask claude-code56 brew install --cask claude-code

57 ```57 ```

58 58

59 Homebrew offers two casks. `claude-code` tracks the stable release channel, which is typically about a week behind and skips releases with major regressions. `claude-code@latest` tracks the latest channel and receives new versions as soon as they ship.59 Homebrew 提供兩個 casks。`claude-code` 追蹤穩定版本通道，通常比最新版本晚約一週，並跳過有重大迴歸的版本。`claude-code@latest` 追蹤最新通道，並在新版本發佈時立即接收。

60 60

61 <Info>61 <Info>

62 Homebrew installations do not auto-update. Run `brew upgrade claude-code` or `brew upgrade claude-code@latest`, depending on which cask you installed, to get the latest features and security fixes.62 Homebrew 安裝不會自動更新。執行 `brew upgrade claude-code` 或 `brew upgrade claude-code@latest`（取決於您安裝的 cask），以取得最新功能和安全修正。

63 </Info>63 </Info>

64 </Tab>64 </Tab>

65 65

69 ```69 ```

70 70

71 <Info>71 <Info>

~~72 WinGet installations do not auto-update. Run `winget upgrade Anthropic.ClaudeCode` periodically to get the latest features and security fixes.~~72 WinGet 安裝不會自動更新。定期執行 `winget upgrade Anthropic.ClaudeCode` 以取得最新功能和安全修正。

73 </Info>73 </Info>

74 </Tab>74 </Tab>

75 </Tabs>75 </Tabs>

76 76

~~77 You can also install with [apt, dnf, or apk](/docs/en/setup#install-with-linux-package-managers) on Debian, Fedora, RHEL, and Alpine.~~77 您也可以在 Debian、Fedora、RHEL 和 Alpine 上使用 [apt、dnf 或 apk](/docs/zh-TW/setup#install-with-linux-package-managers) 進行安裝。

78 78

79 然後在任何專案中啟動 Claude Code。將 `your-project` 替換為您機器上的專案目錄路徑：79 然後在任何專案中啟動 Claude Code。將 `your-project` 替換為您機器上的專案目錄路徑：

80 80

permission-modes.md +3 −3

Details

27 27

28審查每個操作的模式在 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 或更新版本。桌面應用程式的標籤不取決於您的 CLI 版本。28審查每個操作的模式在 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 或更新版本。桌面應用程式的標籤不取決於您的 CLI 版本。

474 1. 與您的[允許、詢問或拒絕規則](/docs/zh-TW/permissions#manage-permissions)匹配的操作立即解決。寫入[受保護路徑](#protected-paths)的操作即使允許規則匹配也會路由到分類器，`rm` 和 `rmdir` 移除針對 Claude Code v2.1.218 及更新版本中的[關鍵路徑](#critical-paths)也會。標記為 [`requiresUserInteraction`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具即使允許規則匹配也會直接提示您，連接器工具[您的組織設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools) 在設定到達 Claude Code 的會話中也會。與命令內容匹配的詢問規則，例如 `Bash(git push *)`，回退到權限提示474 1. 與您的[允許、詢問或拒絕規則](/docs/zh-TW/permissions#manage-permissions)匹配的操作立即解決。寫入[受保護路徑](#protected-paths)的操作即使允許規則匹配也會路由到分類器，`rm` 和 `rmdir` 移除針對 Claude Code v2.1.218 及更新版本中的[關鍵路徑](#critical-paths)也會。標記為 [`requiresUserInteraction`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具即使允許規則匹配也會直接提示您，連接器工具[您的組織設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools) 在設定到達 Claude Code 的會話中也會。與命令內容匹配的詢問規則，例如 `Bash(git push *)`，回退到權限提示

475 2. 唯讀操作和您工作目錄中的檔案編輯自動批准，除了寫入[受保護路徑](#protected-paths)和[工作目錄外的第一次讀取](#first-read-outside-the-working-directories)，這會提示您475 2. 唯讀操作和您工作目錄中的檔案編輯自動批准，除了寫入[受保護路徑](#protected-paths)和[工作目錄外的第一次讀取](#first-read-outside-the-working-directories)，這會提示您

476 3. 其他所有內容都進入分類器。在步驟 1 中直接提示您的連接器工具和 `requiresUserInteraction` MCP 工具永遠不會到達分類器，因此既不是組織要求的批准也不是同意步驟自動批准476 3. 其他所有內容都進入分類器。在步驟 1 中直接提示您的連接器工具和 `requiresUserInteraction` MCP 工具永遠不會到達分類器，因此既不是組織要求的批准也不是同意步驟自動批准

477 4. 如果分類器阻止，Claude 收到原因並嘗試替代方案。在大多數會話中原因是固定文本 `Blocked by classifier` 而不是書面解釋，在 Claude Code v2.1.208 及更新版本中；請參閱[審查拒絕](/docs/zh-TW/auto-mode-config#review-denials)477 4. 如果分類器阻止，Claude 收到原因並嘗試替代方案。在大多數會話中原因名稱分類器匹配的規則，例如 `[Data Exfiltration]`，而不是給出書面解釋；請參閱[審查拒絕](/docs/zh-TW/auto-mode-config#review-denials)

478 478

479 進入自動模式時，授予任意程式碼執行的廣泛允許規則被丟棄：479 進入自動模式時，授予任意程式碼執行的廣泛允許規則被丟棄：

480 480

518 使用 dontAsk 模式僅允許預先批准的工具518 使用 dontAsk 模式僅允許預先批准的工具

519</h2>519</h2>

520 520

521如果您設定 `dontAsk` 模式，Claude Code 會自動拒絕所有原本會提示的工具呼叫。Claude 只執行符合您的 `permissions.allow` 規則、[唯讀 Bash 命令](/docs/zh-TW/permissions#read-only-commands)的操作以及由 [PreToolUse hook](/docs/zh-TW/permissions#extend-permissions-with-hooks) 批准的呼叫。在您預先定義 Claude 可以執行的確切操作的 CI 管道或受限環境中使用此模式；工作階段永遠不會等待輸入。此模式啟用時，狀態列會顯示 `⏵⏵ don't ask on`。521如果您設定 `dontAsk` 模式，Claude Code 會自動拒絕所有原本會提示的工具呼叫。Claude 仍會執行在 Manual 模式中不需要批准的操作，例如您工作目錄內的檔案讀取和[唯讀 Bash 命令](/docs/zh-TW/permissions#read-only-commands)，加上符合您 `permissions.allow` 規則的操作和由 [PreToolUse hook](/docs/zh-TW/permissions#extend-permissions-with-hooks) 批准的呼叫。在您預先定義 Claude 可以執行的確切操作的 CI 管道或受限環境中使用此模式；工作階段永遠不會等待輸入。此模式啟用時，狀態列會顯示 `⏵⏵ don't ask on`。

522 522

523Claude Code 會拒絕符合您明確 [`ask` 規則](/docs/zh-TW/permissions#manage-permissions)的呼叫，而不是提示。它也會拒絕內建的 `AskUserQuestion` 工具，即使您的允許規則符合它，以及您的組織[設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools)的連接器工具在該設定到達 Claude Code 的工作階段中。它以相同方式拒絕標記為 [`_meta["anthropic/requiresUserInteraction"]`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具，因為它們的批准卡需要此模式永遠不會收集的答案；這需要 Claude Code v2.1.199 或更新版本。523Claude Code 會拒絕符合您明確 [`ask` 規則](/docs/zh-TW/permissions#manage-permissions)的呼叫，而不是提示。它也會拒絕內建的 `AskUserQuestion` 工具，即使您的允許規則符合它，以及您的組織[設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools)的連接器工具在該設定到達 Claude Code 的工作階段中。它以相同方式拒絕標記為 [`_meta["anthropic/requiresUserInteraction"]`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具，因為它們的批准卡需要此模式永遠不會收集的答案；這需要 Claude Code v2.1.199 或更新版本。

524 524

permissions.md +8 −4

Details

82Claude Code 支援多種權限模式來控制工具呼叫的批准方式。請參閱 [Permission modes](/docs/zh-TW/permission-modes) 以了解何時使用每一種。若要變更工作階段啟動時的模式，請在您的 [settings files](/docs/zh-TW/settings#where-settings-live) 中設定 `defaultMode`。[Which mode a session starts in](/docs/zh-TW/permission-modes#which-mode-a-session-starts-in) 涵蓋每個計畫的內建預設值以及 VS Code 擴充功能讀取的內容。82Claude Code 支援多種權限模式來控制工具呼叫的批准方式。請參閱 [Permission modes](/docs/zh-TW/permission-modes) 以了解何時使用每一種。若要變更工作階段啟動時的模式，請在您的 [settings files](/docs/zh-TW/settings#where-settings-live) 中設定 `defaultMode`。[Which mode a session starts in](/docs/zh-TW/permission-modes#which-mode-a-session-starts-in) 涵蓋每個計畫的內建預設值以及 VS Code 擴充功能讀取的內容。

83 83

84| 模式 | 描述 |84| 模式 | 描述 |

85| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |85| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

86| `default` | 在首次使用每個工具時提示權限。在 CLI、VS Code 和 JetBrains 擴充功能以及桌面應用程式中標示為 Manual，Claude Code 接受 `manual` 作為別名。標籤和別名需要 Claude Code v2.1.200 或更新版本。桌面應用程式的標籤不取決於您的 CLI 版本 |86| `default` | 在首次使用每個工具時提示權限。在 CLI、VS Code 和 JetBrains 擴充功能以及桌面應用程式中標示為 Manual，Claude Code 接受 `manual` 作為別名。標籤和別名需要 Claude Code v2.1.200 或更新版本。桌面應用程式的標籤不取決於您的 CLI 版本 |

88| `plan` | Claude 讀取檔案並執行唯讀 shell 命令以探索，但不編輯您的原始檔案；在 [auto mode](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 可用的情況下，分類器批准的命令也會執行。在 CLI 和 VS Code 擴充功能中標示為 Plan |88| `plan` | Claude 讀取檔案並執行唯讀 shell 命令以探索，但不編輯您的原始檔案；在 [auto mode](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 可用的情況下，分類器批准的命令也會執行。在 CLI 和 VS Code 擴充功能中標示為 Plan |

90| `dontAsk` | 自動拒絕工具，除非透過 `/permissions` 或 `permissions.allow` 規則預先批准。`AskUserQuestion`、標示為 [`requiresUserInteraction`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具，以及連接器工具 [您的組織設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools) 在工作階段中即使您已允許它們也會被拒絕 |90| `dontAsk` | 自動拒絕每個會提示的呼叫；工作目錄中的檔案讀取和其他不需要批准的操作仍會執行，透過 `/permissions` 或 `permissions.allow` 規則預先批准的工具也會執行。`AskUserQuestion`、標示為 [`requiresUserInteraction`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具，以及連接器工具 [您的組織設定為 `ask`](/docs/zh-TW/mcp#organization-controls-on-connector-tools) 在工作階段中（該設定到達 Claude Code 的地方）即使您已允許它們也會被拒絕 |

92 92

93<Warning>93<Warning>

455當 Claude 存取符號連結時，權限規則檢查兩個路徑：符號連結本身和它解析到的檔案。Allow 和 deny 規則對該對的處理方式不同：allow 規則回退到提示您，而 deny 規則直接阻止。455當 Claude 存取符號連結時，權限規則檢查兩個路徑：符號連結本身和它解析到的檔案。Allow 和 deny 規則對該對的處理方式不同：allow 規則回退到提示您，而 deny 規則直接阻止。

456 456

457* **允許規則**：僅在符號連結路徑及其目標都符合時適用。允許目錄內的符號連結指向外部仍會提示您。457* **允許規則**：僅在符號連結路徑及其目標都符合時適用。允許目錄內的符號連結指向外部仍會提示您。

458* **Deny 規則**：在符號連結路徑或其目標符合時適用。指向被拒絕檔案的符號連結本身被拒絕。458* **Deny 規則**：在符號連結路徑或其目標符合時適用。指向被拒絕檔案的符號連結本身被拒絕。例如，使用 `Read(./project/**)` 允許和 `Read(~/.ssh/**)` 拒絕，位於 `./project/key` 指向 `~/.ssh/id_rsa` 的符號連結被阻止：目標未通過允許規則且符合 deny 規則。

459 459

460例如，使用 `Read(./project/**)` 允許和 `Read(~/.ssh/**)` 拒絕，位於 `./project/key` 指向 `~/.ssh/id_rsa` 的符號連結被阻止：目標未通過允許規則且符合 deny 規則。460在 macOS 和 Linux 上，透過符號連結目錄編寫的 deny 或 ask 規則（帶有 `//`、`~/` 或 `/` 模式）也適用於目錄的真實位置。例如，在 macOS 上，其中 `/etc` 解析為 `/private/etc`，`Read(//etc/**)` 也會阻止 `/private/etc/hosts`。在 v2.1.268 之前，透過符號連結目錄編寫的 deny 或 ask 規則不適用於由其真實位置給出的路徑。

461 461

462當工具開啟已批准的檔案時，Claude Code [確認路徑仍然解析到權限檢查批准的位置](/docs/zh-TW/errors#refusing-after-a-symlink-changed)。462當工具開啟已批准的檔案時，Claude Code [確認路徑仍然解析到權限檢查批准的位置](/docs/zh-TW/errors#refusing-after-a-symlink-changed)。

463 463

492 492

493兩種形式在[成品](/docs/zh-TW/artifacts)的讀取上也有所不同，即成品工具在 claude.ai 上發佈的頁面。裸 `WebFetch` deny 或 ask 規則不適用於這些讀取。涵蓋 `claude.ai` 或 `*.claudeusercontent.com` 內容主機的 `domain:` 規則，如 `WebFetch(domain:claude.ai)` 或 `WebFetch(domain:*)`，會拒絕每次讀取或在讀取前提示。[`Artifact` 規則](/docs/zh-TW/artifacts#disable-artifacts)也會執行相同操作。

494

495當規則阻止讀取時，拒絕會命名規則。在 v2.1.268 之前，裸 `WebFetch` deny 規則會阻止每次成品讀取，裸 ask 規則會在每次讀取前提示。

496

493若要讓 Claude 自由擷取，同時保持沙箱允許清單不變，請使用裸形式。此 `settings.json` 執行此操作：497若要讓 Claude 自由擷取，同時保持沙箱允許清單不變，請使用裸形式。此 `settings.json` 執行此操作：

494 498

495```json theme={null}499```json theme={null}

platforms.md +10 −10

Details

48 當您遠離終端時工作48 當您遠離終端時工作

49</h2>49</h2>

50 50

~~51Claude Code offers several ways to work when you're not at your terminal. They differ in what triggers the work, where Claude runs, and how much you need to set up.~~51Claude Code 提供了多種方式讓您在不在終端機時進行工作。它們在觸發工作的方式、Claude 執行的位置以及您需要設定的程度上有所不同。

52 52

53| | Trigger | Claude runs on | Setup | Best for |53| | 觸發 | Claude 執行位置 | 設定 | 最適合 |

54| :------------------------------------------------------- | :--------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------ |54| :---------------------------------------------------------- | :------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------ | :------------------------ |

59| [Self-hosted environments](/docs/en/self-hosted-environments) | Start a [cloud session](/docs/en/claude-code-on-the-web) and pick your organization's environment | Your organization's infrastructure | [Deploy runners](/docs/en/self-hosted-environments-quickstart), on Team and Enterprise plans | Cloud sessions that must run inside your network |59| [Self-hosted environments](/docs/zh-TW/self-hosted-environments) | 啟動 [雲端工作階段](/docs/zh-TW/claude-code-on-the-web) 並選擇您組織的環境 | 您組織的基礎設施 | [部署執行器](/docs/zh-TW/self-hosted-environments-quickstart)，在 Team 和 Enterprise 方案上 | 必須在您的網路內執行的雲端工作階段 |

61 61

62如果您不確定從何處開始，[安裝 CLI](/docs/zh-TW/quickstart) 並在專案目錄中執行它。如果您不想使用終端，[Desktop](/docs/zh-TW/desktop-quickstart) 為您提供相同的引擎和圖形介面。62如果您不確定從何處開始，[安裝 CLI](/docs/zh-TW/quickstart) 並在專案目錄中執行它。如果您不想使用終端，[Desktop](/docs/zh-TW/desktop-quickstart) 為您提供相同的引擎和圖形介面。

63 63

plugin-evals.md +705 −0 created

Details

1> ## Documentation Index

2> 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.

5# 使用 evals 測試 plugins

7> 為您的 Claude Code plugin 編寫 eval 案例，使用 claude plugin eval 執行它們，評分結果，與無 plugin 基準線進行比較，並在 CI 中根據分數進行把關。

9`claude plugin eval` 針對一套測試案例執行您的 [plugin](/docs/zh-TW/plugins)，並對結果進行評分。每個案例都是一個真實的提示加上一個或多個評分器。評分器是對 Claude 產生的內容進行的通過/失敗檢查，例如對回覆的正規表達式、是否呼叫了特定工具，或由第二個模型判斷回覆的評分標準。

11您不必手動編寫測試套件；`claude plugin eval init` 會詢問您有關 plugin 的問題，提議案例和評分器，嘗試它們，並編寫檔案。您也可以要求 Claude 從已開啟的工作階段中執行相同操作。

13使用 evals 來測量您的 plugin 可靠地引導 Claude 達到正確結果的程度，在您變更 plugin 或新模型發佈時捕捉迴歸，以及查看與沒有 plugin 相比 plugin 的貢獻。

15本頁面適用於擁有可運作 plugin 並想測試其行為的 plugin 和 skill 作者，以及在 CI 中把關 plugin 變更的團隊。其案例格式與 [skill-creator plugin](/docs/zh-TW/skills#run-evals-with-skill-creator) 使用的 `evals/evals.json` 檔案分開。若要建立 plugin，請參閱 [Create plugins](/docs/zh-TW/plugins)；若要檢查 plugin 的檔案是否存在語法和架構錯誤而不是其行為，請使用 [`claude plugin validate`](/docs/zh-TW/plugins-reference#plugin-validate)。

17<Note>

18 每次 eval 執行和每個評判評分器都是您帳戶上的真實模型呼叫，計入您的方案使用量或 API 帳單，因此請先檢查 [requirements](#requirements)。然後 [create your first eval suite](#create-your-first-eval-suite)，或如果您已經有一個，請前往 [Run evals in CI](#run-evals-in-ci)。

19</Note>

21<h2 id="requirements">

22 Requirements

23</h2>

25若要執行 plugin evals，您需要：

27* Claude Code v2.1.269 或更新版本。執行 `claude --version` 檢查，執行 `claude update` 升級。

28* 具有 `plugin.json` 或 `.claude-plugin/plugin.json` 資訊清單的 plugin 目錄，或 [skills-directory plugin](/docs/zh-TW/plugins-reference#skills-directory-plugins)。

29* 與您的正常 Claude Code 工作階段相同的驗證和模型提供者。Eval 執行、評判評分器和 `claude plugin eval init` 使用您的認證呼叫模型，因此它們計入您的方案使用量限制或 API 帳單。當命令報告成本時，該數字是這些呼叫的 [list-price estimate](/docs/zh-TW/costs)。

31<h2 id="how-an-eval-run-works">

32 Eval 執行的運作方式

33</h2>

35Eval 套件位於 plugin 內名為 `evals/` 的目錄中，其佈局如 [Write and refine cases](#write-and-refine-cases) 所示。每個案例都是其自己的子目錄，包含 [prompt](#set-run-limits-and-tools-in-prompt-md) 和一個或多個 [graders](#grade-the-result)。提示是使用您的 plugin 的人可能輸入的內容，例如其中一個 skills 應該處理的請求。

37<h3 id="what-happens-in-a-run">

38 執行中發生的情況

39</h3>

41對於案例的每次執行，Claude Code 啟動一個新的、[isolated](#how-runs-are-isolated) [non-interactive session](/docs/zh-TW/headless)，僅載入您的 plugin，發送提示，並讓 Claude 工作直到完成或達到案例的轉數或時間限制。然後每個評分器檢查最終回覆、完整文字記錄或 Claude 建立的檔案，並通過或失敗。

43<h3 id="how-a-case-is-scored">

44 案例如何評分

45</h3>

47非確定性代理的一次執行告訴您很少，所以每個案例預設執行三次。執行的分數是其通過的評分器的比例，如果您設定權重則加權，案例的分數是其執行的平均值。當案例的分數達到 [`--threshold`](#command-options)（預設為 1.0）時，案例通過。在模型呼叫中，套件大約進行案例 × 執行代理執行與 plugin，以及同樣多的 [no-plugin baseline](#the-no-plugin-baseline)，加上每個 `llm` 或 `baseline` 評分器每次執行三個短評判呼叫。

49<h3 id="the-no-plugin-baseline">

50 No-plugin 基準線

51</h3>

53高分本身並不能告訴您 plugin 是否有幫助，因為 Claude 可能在沒有它的情況下做得同樣好。為了區分兩者，預設情況下每個案例的執行會在沒有載入 plugin 的情況下重複，您會獲得兩個分數：`WITH` 和 `W/OUT`。它們的差異 `Δ` 是 plugin 的貢獻。如果案例在有 plugin 和沒有 plugin 的情況下都得分 1.0，則不是 plugin 使其通過。這兩組執行稱為 with-arm 和 without-arm；[Compare against a no-plugin baseline](#compare-against-a-no-plugin-baseline) 涵蓋評分器如何在它們之間評分以及如何關閉基準線。

55<h2 id="create-your-first-eval-suite">

56 建立您的第一個 eval suite

57</h2>

59本逐步解說為您自己的 plugin 編寫一個案例，執行它，並讀取結果。在開始之前，請確保您有：

61* Claude Code v2.1.269 或更新版本以及其他 [requirements](#requirements)

62* 在 plugin 根目錄開啟的終端機，即包含 `plugin.json` 或 `.claude-plugin/plugin.json` 的目錄

63* plugin 中您想測試的一個 skill，以及使用者應該輸入的請求以觸發它

65<Steps>

66 <Step title="Create the cases">

67 從 plugin 根目錄執行：

69 ```bash theme={null}

70 claude plugin eval init

71 ```

73 如果 Claude Code 還不信任此目錄，它首先會詢問 `Trust this plugin directory?`；回答 `y`。然後開啟互動式 Claude Code 工作階段。Claude 讀取您的 plugin 並詢問您好的結果是什麼樣子，提議應該和不應該觸發 plugin 的提示，為每個設計評分器，試驗它們一次以檢查它們的行為，並在 `evals/` 下為每個提示編寫一個案例目錄，每個都以其提示命名。當 Claude 告訴您套件已準備好時，使用 `/exit` 或 Ctrl+D 退出該工作階段以返回您的 shell。

75 如果您已經在 plugin 根目錄開啟了 Claude Code 工作階段，您可以改為要求 Claude 在該對話中執行 `claude plugin eval init`。Claude 執行命令，然後在該對話中詢問您相同的問題。

77 如果您寧願自己編寫案例以查看檔案包含的確切內容，請遵循 [Write a case manually](#write-a-case-manually) 並返回此處執行它。

78 </Step>

80 <Step title="Run the suite">

81 回到 plugin 根目錄的 shell，執行 `evals/` 下的每個案例：

83 ```bash theme={null}

84 claude plugin eval .

85 ```

87 您已在步驟 1 中信任此目錄，因此執行立即開始。如果您改為手動編寫案例，執行首先會詢問 `Trust this plugin directory? [y/N]`；回答 `y`。[What a run can access](#security) 解釋了您同意的內容。

89 每個案例使用您的 plugin 執行三次，沒有它執行三次，因此一個案例是六次執行。隨著每次執行完成，進度行會列印，顯示該執行的分數和每個評分器的判決。

90 </Step>

92 <Step title="Read the summary">

93 當套件完成時，您會看到摘要表，然後是報告的位置：

95 ```text theme={null}

96 CASE WITH W/OUT Δ RUNS COST NOTES

97 first-case 1.00 0.33 +0.67 6 $0.41

99 1 case(s) · mean Δ +0.67 · 74s · $0.41

100 Report: /Users/you/my-plugin/evals/results/2026-09-10T17-02-11-482Z/report.html

101 Published: https://claude.ai/... · keep local next time with --no-publish

102 ```

103

104 `WITH` 是案例在載入您的 plugin 時的分數，`W/OUT` 是沒有它時的分數，正 `Δ` 表示 plugin 提高了分數。`COST` 是模型呼叫的 list-price estimate，`NOTES` 顯示最高權重失敗評分器的解釋或執行的錯誤，來自 with-arm。

105 </Step>

106

107 <Step title="Open the report and iterate">

108 開啟 `Published:` URL 或當沒有 `Published:` 行出現時開啟 `Report:` 路徑，以查看每個評分器對每次執行的判決和解釋，以及對於 `llm` 評分器的評判投票和它判斷的摘錄。`Published:` 行僅在您的帳戶可以 [publish reports](#html-report) 時出現。

109

110 最常見的第一個發現是 `Δ` 接近零，案例的 `tool_used: Skill` 評分器失敗，這意味著 Claude 在自然措辭上沒有選擇您的 skill。調整 skill 的 [`description`](/docs/zh-TW/skills#frontmatter-reference)，再次執行 `claude plugin eval .`，並進行比較。

111

112 若要廉價地迭代單個案例，執行單個 arm 一次。單次執行是有噪音的，因此在信任任何變更之前，請在預設三次執行時確認任何變更。使用一個 arm，表格顯示 `SCORE` 和 `PASS%` 列而不是 `WITH`、`W/OUT` 和 `Δ`：

113

114 ```bash theme={null}

115 claude plugin eval . --case <case-name> --runs 1 --ablation none

116 ```

117

118 將 `<case-name>` 替換為 `evals/` 下的目錄名稱之一。

119 </Step>

120</Steps>

121

122<h2 id="write-and-refine-cases">

123 撰寫和改進案例

124</h2>

125

126`claude plugin eval init` 撰寫的案例是純文字檔案，您可以開啟、變更和新增。案例是外掛程式 eval 目錄下的目錄，包含 `prompt.md`、`case.yaml` 或兩者。若要分組案例，請將它們巢狀放在不是案例本身的目錄下；案例目錄內的任何內容（例如 `graders/` 和 fixture 檔案）都屬於該案例。

127

128這是 `claude plugin eval init` 撰寫的配置，也是用於新套件的配置。[eval 套件參考](#eval-suite-reference)包含完整的樹狀結構，包括 mocks 和結果：

129

130```text theme={null}

131my-plugin/

132├── .claude-plugin/plugin.json

133├── skills/...

134└── evals/

135 ├── first-case/

136 │ ├── prompt.md # frontmatter: case fields; body: the prompt

137 │ ├── graders/

138 │ │ ├── criteria.md # frontmatter: type + options; body: rubric or pattern

139 │ │ └── skill-fired.md

140 │ └── case.yaml # optional: only for context.* fields

141 ├── ignores-unrelated-request/

142 │ └── ...

143 └── results/ # written by each run; add to .gitignore

144```

145

146<h3 id="write-a-case-manually">

147 手動撰寫案例

148</h3>

149

150讓 Claude 使用 `claude plugin eval init` 撰寫案例是建議的方式。若要自己撰寫，請從空白範本開始。下列命令會撰寫一個名為 `first-case` 的案例，包含預留位置 `prompt.md` 和一個預留位置 grader，且不執行任何內容：

151

152```bash theme={null}

153claude plugin eval init --bare first-case

154```

155

156```text theme={null}

157evals/first-case/

158├── prompt.md # the prompt sent to Claude, plus run limits

159└── graders/

160 └── criteria.md # one grader: how to score the result

161```

162

163在 `prompt.md` 中，您撰寫 Claude 在每次執行時收到的訊息，並在 frontmatter 中設定執行的限制和案例可能使用的工具。開啟 `evals/first-case/prompt.md` 並將預留位置本文替換為您的請求，用使用者會輸入的方式表述，而不是命名技能。此範例適用於起草提交訊息的技能；請使用您自己的請求：

164

165```markdown theme={null}

166---

167max_turns: 10

168allowed_tools: [Read, Glob, Grep, Skill]

169---

170

171Write me a commit message for this change: I renamed getUser to fetchUser and updated the three call sites.

172```

173

174每次執行都在空的工作目錄中開始，所以將任務需要的內容放在提示本身中，或[先設定工作區](#add-setup-or-history-with-case-yaml)。[frontmatter 欄位的完整清單](#prompt-md-fields)涵蓋模型、逾時、標籤和環境變數。

175

176`graders/` 下的每個檔案都是執行後套用的一項檢查。開啟 `evals/first-case/graders/criteria.md` 並將預留位置替換為評判模型的評分標準，寫成具體的 PASS 和 FAIL 條件：

177

178```markdown theme={null}

179---

180type: llm

181---

182

183PASS if <what a correct response contains>.

184FAIL if <what a wrong or missing response looks like>.

185```

186

187然後新增第二個 grader，檢查您的技能是否是產生答案的原因。建立 `evals/first-case/graders/skill-fired.md`，將 `your-skill-name` 替換為您技能的 `SKILL.md` 中的 `name`：

188

189```markdown theme={null}

190---

191type: tool_used

192tool: Skill

193input_match: '"skill"\s*:\s*"(?:[\w-]+:)?your-skill-name"'

194---

195```

196

197當 Claude 在執行期間至少呼叫過該技能一次時，這會通過，包括其命名空間 `plugin-name:skill-name` 形式。[Grader 類型](#grader-types)列出其他可用的檢查，例如符合正規表達式或確認檔案已建立。

198

199兩個檔案都儲存後，按照[快速入門](#create-your-first-eval-suite)的方式執行案例，從外掛程式根目錄執行 `claude plugin eval .`。

200

201<h3 id="set-run-limits-and-tools-in-prompt-md">

202 在 prompt.md 中設定執行限制和工具

203</h3>

204

205在 `prompt.md` frontmatter 中設定案例的 `max_turns`、`timeout_seconds`、`model`、`tags` 和它可能使用的 `allowed_tools`；[prompt.md frontmatter](#prompt-md-fields) 參考列出每個欄位及其預設值。Claude 會完全按照您撰寫的方式接收本文。其中的 `@path` 提及不會展開為檔案附件，所以如果 Claude 需要讀取檔案，請在 `allowed_tools` 中授予工具。

206

207<h3 id="grade-the-result">

208 選擇和加權 graders

209</h3>

210

211Grader 的 frontmatter 設定其 `type`，以及可選的 `weight` 使其計入執行分數的更多部分，以及控制如何針對基準線評分的 [`arm`](#compare-against-a-no-plugin-baseline)。在六種類型中，`regex`、`tool_used`、`tool_order` 和 `file_exists` 是從文字記錄和檔案計算的，不需要成本，而 `llm` 和 `baseline` 呼叫評判模型並增加執行成本。

212

213沒有自訂程式碼 graders。[Grader 類型](#grader-types)列出每種類型的選項和通過條件，[grader 可以查看的內容](#what-a-grader-can-look-at)列出 `target` 和 `focus` 接受的值。

214

215`llm` 和 `baseline` graders 的評判者預設是小型快速模型。傳遞 `--judge-model sonnet` 或完整模型 ID 以使用更強大的模型來處理細微的評分標準。

216

217<h4 id="choose-graders-that-give-a-stable-signal">

218 選擇提供穩定訊號的 graders

219</h4>

220

221`llm` grader 要求模型提供判決，所以其答案可能在執行之間有所不同，且文字越長差異越大。這些習慣可以讓套件的分數穩定到足以信任：

222

223* 對於長輸出（例如產生的檔案），使用檔案內容上的 `regex` grader 進行評分，它每次都以相同的方式檢查整個檔案。將 `llm` graders 保留用於短輸出，評分標準寫成具體的 PASS 和 FAIL 條件。

224* 為每個案例提供一個 grader 來評分結果（例如最終訊息或產生的檔案），以及一個來評分 Claude 如何達成的（例如 `tool_used` 或 `tool_order`）。它們一起告訴您答案是否正確以及您的外掛程式是否產生了它。

225* 如果案例的 `tool_used: Skill` grader 通過但 `Δ` 為負，請懷疑評判者而不是外掛程式。小型評判模型可能會因為格式與評分標準描述的不同而將正確答案標記為錯誤。使用 `--judge-model sonnet` 重新執行，並收緊評分標準，使格式不會決定判決。

226* 若要檢查建置或測試在執行內通過，請讓提示要求 Claude 執行它並將結果寫入檔案，評分該檔案，並使用 `tool_used` grader（其 `input_match` 命名該命令）判斷命令已執行。

227

228<h3 id="compare-against-a-no-plugin-baseline">

229 針對無外掛程式基準線評分

230</h3>

231

232當外掛程式在測試中時，每個案例預設在兩個 arm 中執行。with-arm 是使用外掛程式載入的執行，without-arm 是沒有外掛程式的相同數量執行。摘要和報告顯示兩個分數和 `Δ`（with-arm 分數減去 without-arm 分數）。傳遞 `--ablation none` 以僅執行 with-arm，當您不需要比較時（例如在迭代 graders 時）成本減半。

233

234在雙 arm 執行中，某些 graders 會以 `scored: false` 報告。像「技能已呼叫」這樣的檢查在沒有外掛程式的情況下永遠無法通過，所以計算它會將 without-arm 推向零並誇大 `Δ`。為了保持兩個 arm 可比較，Claude Code 在兩個 arm 中排除此類 graders 的分數，並在 with-arm 中將其報告為僅通過/失敗指標。這包括：

235

236* 每個 `tool` 為 `Skill` 的 `tool_used` grader

237* 任何您標記為 `arm: with-only` 的 grader

238

239如果案例中的每個 grader 都是其中之一，它們會改為正常評分，因為沒有其他內容可評分。在 grader 上設定 `arm: both` 以無論如何在兩個 arm 中評分，這是您想要的「不得呼叫技能」檢查，具有 `min: 0` 和 `max: 0`。在 `--ablation none` 下，沒有任何內容被排除，所以相同的套件在兩種模式中可能產生不同的絕對分數。

240

241<h3 id="use-a-different-eval-directory">

242 使用不同的 eval 目錄

243</h3>

244

245如果 `evals/` 已被另一個工具佔用，請將套件保留在不同的目錄中。您可以在外掛程式的 `plugin.json` 中記錄該目錄，以便每次執行和每個協作者都使用它，或在命令列上傳遞它以進行單次執行：

246

247* **在 `plugin.json` 中**：新增 `"experimental": { "evals": "quality/evals" }`。

248* **在命令列上**：將 `--eval-dir quality/evals` 傳遞給 `claude plugin eval` 和 `claude plugin eval init`。

249

250如果同時設定兩者，則使用旗標的目錄。給出相對路徑，包含純目錄名稱，例如 `qa` 或 `quality/evals`；絕對路徑或包含 `..` 的路徑會被拒絕：作為旗標值時會出現錯誤，而無法使用的資訊清單值會列印 `Warning:` 行，執行會改用 `evals/`。案例、結果和 `init` 輸出都會移至該目錄。

251

252<h2 id="set-up-fixtures-and-mocks">

253 設定 fixtures 和 mocks

254</h2>

255

256案例可能需要的不僅僅是提示：工作區中的檔案或 git 儲存庫、要繼續的早期對話，或您的 plugin 與之交談的 MCP 伺服器的答案。每個都在案例旁邊設定，以便執行保持可重複。

257

258<h3 id="add-setup-or-history-with-case-yaml">

259 Seed the workspace or conversation

260</h3>

261

262每次執行都在空工作區中開始。當案例需要的不僅僅是提示時，在 `prompt.md` 旁邊新增 `case.yaml`，其中包含 `context` 區塊。

263

264若要首先建立 fixture 檔案或 git 儲存庫，請在案例目錄中編寫 Bash 指令碼並在 `context.scaffold_script` 中命名它。指令碼以您的身份在代理沙箱外執行，僅當您傳遞 `--scaffold` 時，因此僅對您或您的組織編寫的套件傳遞該標誌。若要繼續早期對話，請將文字記錄保存為 `.jsonl` 檔案並在 `context.history_file` 中命名它，案例的提示變成下一個使用者轉數。若要讓 Claude 在執行期間讀取案例中的 fixture 目錄，請在 `context.add_dirs` 中列出它們。

265

266`case.yaml` 也需要 `schema_version: "1.1"` 和 `name`；[case.yaml fields](#case-yaml-fields) 參考有完整列表。

267

268此 `case.yaml` 從指令碼播種工作區並讓 Claude 從 `resources/` 目錄讀取 fixtures：

269

270```yaml theme={null}

271schema_version: "1.1"

272name: changelog-from-diff

273tags: [smoke]

274context:

275 scaffold_script: fixture.sh

276 add_dirs: [resources]

277```

278

279<h3 id="mock-mcp-servers">

280 Mock MCP servers

281</h3>

282

283您可以評估 plugin，其 skills 呼叫 MCP 工具，而無需它們後面的真實服務。在 `evals/mocks/<server>/<tool>.md` 下為整個套件放置一個 Markdown 檔案，或在案例自己的 `mocks/` 目錄下為一個案例，其中 `<server>` 是您的 plugin 的 [MCP configuration](/docs/zh-TW/plugins-reference#mcp-servers) 中伺服器的名稱。

284

285執行永遠不會啟動您的 plugin 的真實 MCP 伺服器，除非您要求。Claude Code 在每個伺服器自己的名稱下註冊替代品。具有 mock 檔案的工具從它回答，並且無需 `--allow-tools` 授予即可允許，具有無 mock 檔案的工具對 Claude 不可用。完全沒有 mocks 的伺服器在案例的 `mocked:` 進度行中顯示為 `plugin_<plugin>_<server>[not started: no mock]`。

286

287檔案的主體是工具返回給 Claude 的內容。此 mock 代替名為 `tracker` 的伺服器上的 `create_issue` 工具，檢查 Claude 發送的輸入，並回顯標題。將其保存為 `evals/mocks/tracker/create_issue.md`：

288

289```markdown theme={null}

290---

291expect:

292 title: string

293 priority: [low, medium, high]

294---

295

296Created issue #4821: {{input.title}}

297```

298

299使用 `{{input.<field>}}` 從呼叫的輸入插入欄位，使用 `{{file:fixtures/{input.<field>}.json}}` 插入 mock 旁邊的 fixture 檔案的內容。`expect:` 區塊保護輸入。如果呼叫違反它，執行會中止，分數為 0，並記錄原因，因此案例可以斷言您的 plugin 要求伺服器執行的操作。設定 `error: true` 以改為將主體作為工具錯誤返回，或 `type: agent` 讓小型模型從主體中的指令作為伺服器回答。[mock file reference](#mock-files) 列出每個鍵和 `_server.md` 和 `_tools.json` 檔案。

300

301若要評分呼叫本身，請將評分器指向 `target: mock_calls`。

302

303若要改為針對 plugin 的真實 MCP 伺服器執行，請傳遞以下標誌之一。無論哪種方式，這些程序都以您的身份在執行沙箱外執行，其工具需要 [`--allow-tools` 授予](#grant-tools)：

304

305* **`--allow-real-servers`**：為您未 mock 的每個伺服器啟動真實程序，並繼續從其檔案回答 mocked 工具

306* **`--mocks off`**：完全忽略 `mocks/` 並啟動 plugin 宣告的每個伺服器

307

308<h4 id="replay-agent-mock-answers">

309 Replay agent mock answers

310</h4>

311

312`type: agent` mock 使用 [`--judge-model`](#command-options) 呼叫回答，因此其輸出在執行之間變化，如果您變更評判者則會改變。當執行完成而沒有錯誤或中止時，Claude Code 在結果目錄中的 `mock-recordings/` 下保存代理 mock 給出的每個答案。

313

314開啟那裡的 `ADOPT.txt` 以查看每個記錄和 `.replay/<server>/` 目錄以複製到，在產生它的 mock 旁邊。複製記錄後，稍後執行會從它回答相同呼叫，沒有模型呼叫。將 `mocks/.replay/` 與 `mocks/` 的其餘部分一起提交，以便 CI 執行可重複。

315

316<h2 id="run-evals">

317 執行 evals

318</h2>

319

320一旦套件存在，`claude plugin eval` 就執行它。您選擇哪個 plugin 和案例使用目標引數執行，使用 `--allow-tools` 授予案例需要的任何工具超過唯讀集，並使用其他選項控制執行計數、模型、成本和輸出。

321

322<h3 id="choose-what-to-evaluate">

323 選擇要評估的內容

324</h3>

325

326大多數時候您從 plugin 根目錄執行 `claude plugin eval .`，它執行套件中 eval 目錄下的每個案例，並載入您所在的 plugin。若要執行單個案例檔案，或評估您安裝的 plugin 而不是您正在開發的 plugin，請傳遞不同的目標：

327

328| Target | What runs |

329| :-------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

330| A plugin's root directory, such as `.` | Every case under its eval directory, with that plugin loaded |

331| A single `prompt.md` or `case.yaml` file | That case, with its enclosing plugin loaded |

332| An installed plugin by name, `name` or `name@marketplace` | The cases in the installed copy's eval directory, with the installed copy loaded. Results are written under `./evals/results/` in your current directory, or `./<dir>/results/` with `--eval-dir` |

333| `name@skills-dir` | The same, for a [skills-directory plugin](/docs/zh-TW/plugins-reference#skills-directory-plugins) |

334| Omitted | The current directory as a path |

335

336新增 `--case <glob>` 按案例名稱篩選，`--tag <tag>` 保留具有任何給定標籤的案例。將目標放在 `--tag`、`--allow-tools` 和 `--json` 之前。前兩個採用列表，`--json` 採用可選路徑，因此它們中的每一個都讀取跟隨它的目標作為其自己的值。

337

338<h3 id="grant-tools">

339 授予工具

340</h3>

341

342執行永遠不會停止要求許可。需要您未授予的授予的內建工具，例如 `Bash`、`Write`、`Edit`、`WebFetch` 和 `WebSearch`，會從工作階段中移除，因此 Claude 根本無法呼叫它們。允許清單是案例在 `allowed_tools` 中列出的唯讀工具，來自 `Read`、`Glob`、`Grep`、`NotebookRead`、`Skill`、`Agent`、`TodoWrite` 和任務工具 `TaskCreate`、`TaskGet`、`TaskList`、`TaskUpdate`、`TaskStop` 和 `TaskOutput`，加上您使用 `--allow-tools` 授予的任何內容，它適用於執行中的每個案例。若要讓案例使用 `Bash`、`Write`、`Edit`、`WebFetch` 或 `WebSearch`，請自己授予它們：

343

344```bash theme={null}

345claude plugin eval . --allow-tools Write Edit "Bash(npm test *)"

346```

347

348當案例要求您未授予的工具時，執行在 stderr 上將其列為 `not granted`。[mocked](#mock-mcp-servers) MCP 伺服器上的工具不需要授予。真實 plugin MCP 伺服器上的工具需要伺服器啟動（使用 `--allow-real-servers` 或 `--mocks off`）和按名稱授予，例如 `--allow-tools "mcp__plugin_my-plugin_github__*"`；plugin 的 MCP 工具命名為 `mcp__plugin_<plugin>_<server>__<tool>`。

349

350當您以任何形式授予 `Bash` 時，每個命令都在 Claude Code 的 [OS-level sandbox](/docs/zh-TW/sandboxing) 下執行。寫入限制在執行的工作區、您的主目錄和 Claude Code 設定無法讀取，網路存取限制在您使用 `--allow-tools "WebFetch(domain:example.com)"` 授予的網域。如果您在沒有沙箱後端的機器上授予 Bash 或 PowerShell，Claude Code 拒絕每次執行而不是無限制執行它，案例顯示執行錯誤，通常分數為 0。原生 Windows 沒有後端，因此在 WSL2 下執行 shell 授予套件；在 Linux 上，首先安裝 `bubblewrap` 和 `socat`。請參閱 [sandboxing prerequisites](/docs/zh-TW/sandboxing)。

351

352<h3 id="command-options">

353 命令選項

354</h3>

355

356此表涵蓋執行計數、模型、評分、成本、工具授予、mocks 和輸出的選項。執行 `claude plugin eval --help` 以獲得完整列表，其中還包括 `--case`、`--tag`、`--eval-dir`、`--no-scaffold`、`--report` 和 `--verbose`。

357

358| Option | Default | Effect |

359| :------------------------- | :----------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

360| `--runs <n>` | Each case's `runs`, else 3 | Runs per case per arm |

361| `-j`, `--concurrency <n>` | `1` | Run up to this many agent runs at once, from 1 to 8. They share your account's rate limit, so this shortens wall-clock time rather than raising throughput past that limit. Results keep case order |

362| `--model <model>` | Each case's `model`, else `ANTHROPIC_MODEL` if set, else Claude Code's default | Model for the agent under test. Pin it in CI so a model rollout isn't mistaken for a plugin regression |

363| `--judge-model <model>` | A small fast model | Model for `llm` and `baseline` graders |

364| `--ablation <mode>` | `with-without` when a plugin resolves, else `none` | Whether to also run each case without the plugin to measure what it adds. `none` runs one arm; `with-without` adds the no-plugin baseline |

365| `--threshold <0..1>` | `1.0` | A case passes when its with-arm score is at least this. Any case below it makes the command exit 1 |

366| `--max-cost-usd <usd>` | No ceiling | A ceiling on the run's list-price cost estimate, not on plan usage. Checked before each run starts. Once spent, nothing further starts; runs already in flight finish, so spend can pass the ceiling by those runs. If any run is left unstarted, the command exits 2 with partial results |

367| `--allow-tools <tools...>` | None | Grant tools beyond the read-only set. See [Grant tools](#grant-tools) |

368| `--scaffold` | Off | Run each case's [`scaffold_script`](#add-setup-or-history-with-case-yaml) |

369| `--trust-plugin` | Off | Skip the first-run trust prompt for a plugin whose code and suite you'd run yourself. Pass it in CI so the job is never refused by or left waiting at the prompt. See [What a run can access](#security) |

370| `--mocks <mode>` | `record` | `record` answers MCP tool calls from [mocks](#mock-mcp-servers), doesn't start the plugin's real servers, and saves agent-mock answers for replay. `off` ignores mocks and starts the plugin's real MCP servers |

371| `--allow-real-servers` | Off | With `--mocks record`, also start the plugin's real MCP servers for servers that have no mock |

372| `--json [path]` | Off | Print the [result document](#json-result) to stdout, or write it to a path ending in `.json`. The run is quiet: no progress lines or summary table |

373| `--output-dir <dir>` | `<eval dir>/results/<timestamp>/` | Where `aggregate-result.json` and `report.html` go |

374| `--no-publish` | | Keep the HTML report local. See [HTML report](#html-report) |

375| `--publish-report` | | Publish the report even where it would stay local by default, such as a run a Claude Code session started |

376| `--keep-temp` | Off | Keep every run's sandbox directory and print its path, for debugging what Claude produced |

377

378<h3 id="run-evals-in-ci">

379 在 CI 中執行 evals

380</h3>

381

382在您的 CI 工作中，使用 `--json` 執行套件以寫入結果以進行存檔，並根據退出代碼使建置失敗。傳遞 `--trust-plugin` 以便工作永遠不會在 [first-run trust prompt](#security) 處等待，固定兩個模型以便分數在一段時間內可比較，保持報告本地，並設定成本上限作為上限：

383

384```bash theme={null}

385claude plugin eval . \

386 --trust-plugin \

387 --json results.json \

388 --threshold 0.8 \

389 --model claude-sonnet-5 \

390 --judge-model claude-haiku-4-5 \

391 --no-publish \

392 --max-cost-usd 20

393```

394

395工作的退出代碼告訴您發生了什麼：

396

397| Exit code | Meaning |

398| :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

399| 0 | Every case scored at or above `--threshold` and every case file loaded |

400| 1 | A case scored below the threshold, a case file failed to load, no cases were found, a run couldn't be started, the plugin directory isn't trusted and `--trust-plugin` wasn't passed, or an option was invalid |

401| 2 | Partial run: the `--max-cost-usd` ceiling was hit, or your credential was rejected before or at the first run. `results.json` is still written with `partial: true` and the reason |

402| 130 | Interrupted. Partial results are written |

403| 143 | Terminated, such as by a CI timeout |

404

405寫入或發佈 HTML 報告的問題永遠不會改變退出代碼。若要查看案例評分低的原因，請在本地執行它而不使用 `--json`，以便列印每次執行的進度和評分器行。

406

407CI 執行器需要 Claude Code 安裝和 [credentials in the environment](/docs/zh-TW/authentication)，例如 `ANTHROPIC_API_KEY`。沒有 `--trust-plugin`，其簽出目錄 Claude Code 還不信任的工作在沒有終端時被拒絕，退出代碼 1，或在執行器分配一個時在提示處等待。`claude plugin eval init` 需要終端來詢問您的問題；在 CI 中，執行 `claude plugin eval init --bare <name>` 以獲得空白範本。

408

409若要保持成本可預測，請為快速每次變更套件提供僅不呼叫評判的評分器，在您不需要 `Δ` 的地方使用 `--ablation none`，並將 `partial: true` 文件和具有 `skippedPaidGraders` 的執行排除在您繪製的任何趨勢之外。

410

411<h2 id="read-the-results">

412 讀取結果

413</h2>

414

415每次執行至少一個案例會在 eval 目錄內寫入 `results/<timestamp>/` 目錄，包含 `aggregate-result.json` 和 `report.html`。對於 plugin 下的路徑目標；對於您命名的 plugin，它在您的目前目錄下，如 [target table](#choose-what-to-evaluate) 所示。摘要表、JSON 和報告都呈現相同的結果資料。

416

417<h3 id="html-report">

418 HTML report

419</h3>

420

421`report.html` 是一個單一的自包含檔案，不進行外部請求，因此您可以將其附加到 CI 工作或從磁碟開啟它。這個範例是使用 `--threshold 0.8` 執行三案例套件的報告頂部；顯示的成本是列表價格估計，會因模型和案例數量而異：

422

423<img src="https://mintcdn.com/claude-code/qq7LHDi_F0aeFHgk/images/plugin-eval-report.png?fit=max&auto=format&n=qq7LHDi_F0aeFHgk&q=85&s=106eb6e6a70a6565f891ea3a4564f87d" alt="eval 報告的頂部：一條判決行讀取「Plugin effect: +33.3 pts vs baseline, improved 2, flat 1, regressed 0 of 3 cases」，五個摘要磚塊分別用於套件分數、消融差異、基準分數、通過閾值的案例和完美執行，然後是第一個案例及其差異、分數條和一次執行，其兩個評分器都顯示通過" width="1360" height="1032" data-path="images/plugin-eval-report.png" />

424

425從上到下讀取：

426

427* **判決行和磚塊**回答 plugin 是否在整個套件中有幫助。套件分數是每個案例 with-plugin 分數的平均值，Ablation Δ 是該分數高於或低於基準分數的距離，Cases 計算有多少個達到閾值。Perfect runs 是 with-plugin 執行的比例，其中每個評分器都通過。

428* **每個案例卡**顯示案例自己的 `Δ` 和 with-plugin 分數，在閾值處有一個刻度。`Δ` 為負的案例在左邊緣獲得紅色，因此當您捲動時迴歸會突出顯示。

429* **在案例內**，with-plugin 執行首先出現，基準執行之後。每次執行列出其評分器及通過或失敗晶片。失敗的評分器已經展開並附帶其解釋，`llm` 評分器也顯示法官的投票和它被顯示的證據，這是您發現執行分數低原因的地方。不計入分數的評分器，例如 `tool_used: Skill`，帶有 `plugin-fired indicator` 徽章。

430* **Prompt 和 Graders**，在執行下方，顯示案例的 prompt 和每個評分器的評分標準或模式，因此閱讀報告而不查看套件的人可以看到被要求的內容和什麼被視為良好。

431

432如果您使用 claude.ai 訂閱登入並且 [artifacts](/docs/zh-TW/artifacts) 可用於您的帳戶，Claude Code 也會將報告發佈為私人 artifact 並列印 `Published: <url>`。傳遞 `--no-publish` 以保持本地。如果沒有 `Published:` 行出現，例如使用 API 金鑰驗證，本地檔案是報告。

433

434Claude Code 工作階段啟動的執行，例如當您要求 Claude 為您執行套件時，也保持本地，其 `Report:` 行說 `kept local`。將 `--publish-report` 新增到該命令以發佈它。

435

436<h3 id="json-result">

437 JSON result

438</h3>

439

440`aggregate-result.json` 和 `--json` 輸出是版本化文件，具有 `schemaVersion: 1` 供 CI 指令碼解析。欄位名稱是 camelCase，新欄位在不重新命名現有欄位的情況下新增，因此編寫您的指令碼以忽略它不識別的欄位。

441

442這些是把關指令碼通常讀取的欄位。文件還包含套件設定、每個評分器定義和每次執行評分器結果及解釋和證據：

443

444| Field | Meaning |

445| :------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

446| `partial`, `partialReason` | `true` with `cost_ceiling`, `interrupted`, or `auth_failed` when the suite didn't finish. Leave partial results out of trend charts |

447| `aggregates.overallScore` | Mean case score across the suite |

448| `aggregates.casesPassed`, `aggregates.casesTotal` | Cases at or above `--threshold`, and the total |

449| `aggregates.meanDelta` | Mean `Δ` across cases, under the two-arm mode |

450| `cases[].name` | Case name |

451| `cases[].aggregates.score` | Mean with-arm run score for the case |

452| `cases[].aggregates.delta` | With-arm score minus without-arm score. Omitted when the arms aren't comparable |

453| `cases[].arms.with[].error` | `null`, or why a run ended abnormally, such as `timed out after 300s`. A run that started but ended badly is still graded on what it produced, so a non-null error doesn't imply score 0 |

454| `cases[].arms.with[].aborted` | Present when a [mock](#mock-mcp-servers)'s `expect:` or `abort_when` stopped the run, with `server`, `tool`, and `reason`. The run scores 0 and `error` stays `null` |

455| `cases[].arms.with[].skippedPaidGraders` | `true` when the cost ceiling skipped this run's judge graders, so its score isn't comparable |

456| `costUsd`, `durationSeconds`, `claudeVersion` | Estimated cost at list price including judge calls, wall-clock seconds, and the Claude Code version that ran the suite |

457

458<h2 id="security">

459 What a run can access

460</h2>

461

462`claude plugin eval` 載入目標 plugin 的 skills 和 hooks，並在您的機器上以您的身份執行其 eval 套件。將其指向 plugin 與 `claude --plugin-dir` 相同的信任決定，因此僅評估您信任的 plugins。本節中描述的隔離限制了被測試代理可以到達的內容；它不是針對 plugin 自己程式碼的邊界，通過套件的套件對 plugin 是否安全沒有說明。

463

464<h3 id="trust-the-plugin-directory">

465 Trust the plugin directory

466</h3>

467

468第一次針對目錄執行 `claude plugin eval` 時，Claude Code 會詢問 `Trust this plugin directory?`，除非您已在互動式 `claude` 工作階段中在那裡接受信任提示。在 git 儲存庫內，回答是信任整個儲存庫，對於互動式工作階段也是如此。當 stdin 或 stdout 不是終端時，或在 `--json` 下，執行無法詢問並被拒絕，退出代碼 1；傳遞 `--trust-plugin` 以自己斷言信任，僅對您會在自己的機器上執行的 plugin。您命名而不是作為路徑給出的目標（意味著已安裝的 plugin 或 skills-directory plugin）跳過提示。

469

470plugin 和套件的某些部分僅在您為該執行傳遞其標誌時執行：案例的 [`scaffold_script`](#add-setup-or-history-with-case-yaml) 使用 `--scaffold`、[tools beyond the read-only set](#grant-tools) 使用 `--allow-tools`，以及 plugin 的 [real MCP servers](#mock-mcp-servers) 使用 `--allow-real-servers` 或 `--mocks off`。案例的 `allowed_tools` 和 skill 自己的 `allowed-tools` frontmatter 無法擴展它們中的任何一個。當 plugin 發佈您未編寫的 hooks，或您啟動其真實 MCP 伺服器時，除非您在隔離環境（例如容器或 CI 執行器）中執行它，否則將其分數視為建議，因為 hooks 和伺服器在代理沙箱外執行，可能會觸及評分器讀取的檔案。

471

472<h3 id="how-runs-are-isolated">

473 How runs are isolated

474</h3>

475

476每次執行都獲得一次性主目錄、工作目錄和 Claude Code 設定，被測試代理在那裡以 `claude -p` 子程序執行，僅載入您的 plugin。在編寫案例時牢記這些後果：

477

478* **沒有個人或專案級別載入。** 您的使用者設定、hooks、`CLAUDE.md` 檔案、MCP 伺服器、其他已安裝的 plugins、記憶和 skills 不存在，沒有專案範圍的 `.claude/` 或 `.mcp.json` 在沙箱上方被讀取。您的大部分 shell 環境也被扣留；僅 [allowlist](#prompt-md-fields) 和 `EVAL_*` 變數到達執行。如果 plugin 需要設定，請在 plugin 中發佈它，在 `scaffold_script` 中建立它，或傳遞 `EVAL_*` 變數。

479* **受管理的原則仍然可以限制執行。** 管理員部署到機器的 [managed settings](/docs/zh-TW/managed-settings) 中的限制適用於執行內，因此受管理機器上的結果可能因該原則而與非受管理機器不同。

480* **Artifact 工具已關閉。** 發佈 [artifact](/docs/zh-TW/artifacts) 的 skill 只能在該步驟之前評分其產生的內容。

481* **案例定義對代理隱藏。** 執行無法讀取 eval 目錄，因此 Claude 無法看到案例的提示、其評分器或同級案例。

482* **shell 命令外沒有網路沙箱。** 您授予的 shell 命令在沙箱的網路規則下執行。`WebFetch(domain:…)` 授予直接到達該網域，plugin 自己的 hooks 和您啟動的任何真實 MCP 伺服器可以到達任何主機。

483

484<h2 id="eval-suite-reference">

485 Eval suite reference

486</h2>

487

488eval 套件可以包含的所有內容都位於 plugin 的 eval 目錄 `evals/` 下，除非您 [configured another](#use-a-different-eval-directory)。此樹顯示 `claude plugin eval` 在那裡讀取或寫入的每個檔案；案例存在只需要 `prompt.md` 或 `case.yaml`：

489

490```text theme={null}

491evals/

492├── <case>/ # one directory per case; nest under a non-case directory to group

493│ ├── prompt.md # frontmatter: case and run fields; body: the prompt

494│ ├── case.yaml # optional: context.* fields, or the whole case in one file

495│ ├── graders/

496│ │ └── <name>.md # one grader per file; frontmatter: type and options; body: rubric

497│ ├── mocks/ # optional: mocks for this case only, same layout as below

498│ └── <fixtures, scripts, transcripts referenced by case.yaml>

499├── mocks/ # optional: suite-wide MCP mocks

500│ ├── <server>/

501│ │ ├── <tool>.md # one mocked tool; body: the tool result

502│ │ ├── _server.md # optional: one agent that answers several tools

503│ │ ├── _tools.json # optional: saved tools/list response for real descriptions and schemas

504│ │ └── fixtures/ # files inserted with {{file:fixtures/...}}

505│ └── .replay/<server>/ # adopted agent-mock recordings, answered without a model call

506└── results/<timestamp>/ # written by each run; add results/ to .gitignore

507 ├── aggregate-result.json

508 ├── report.html

509 └── mock-recordings/ # agent-mock answers from clean runs, with ADOPT.txt

510```

511

512<h3 id="prompt-md-fields">

513 prompt.md frontmatter

514</h3>

515

516`prompt.md` frontmatter 接受這些欄位。未知鍵是錯誤：

517

518| Field | Default | Purpose |

519| :--------------------- | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

520| `schema_version` | `"1.1"`，為您設定 | 案例格式版本。寫成 `prompt.md` 的案例會自動取得它，所以您很少設定它 |

521| `name` | 目錄名稱 | 案例名稱。`--case` globs 符合它，報告以它為鍵 |

522| `description` | | 供人類使用。在執行時不使用 |

523| `tags` | `[]` | `--tag` 篩選的標籤。如果任何標籤符合，案例就會執行 |

524| `plugins` | 最近的封閉 plugin | 在測試中的 plugin 目錄，相對於案例目錄。當自動偵測找不到您的 plugin 時，設定 `plugins: ["../.."]`；請參閱 [the plugin didn't load](#the-baseline-arm-shows-no-plugin-or-delta-is-zero) |

525| `runs` | `3` | 每個 arm 的執行次數，1 到 50。`--runs` 覆蓋它 |

526| `expected_outcome` | | 供人類使用。在執行時不使用 |

527| `model` | 子工作階段的預設值 | 被測試代理的模型。`--model` 覆蓋它 |

528| `max_turns` | `10` | 回合上限，最多 200。達到它會被記錄為執行錯誤，通常會降低分數，所以請慷慨設定 |

529| `timeout_seconds` | `300` | 每次執行的牆鐘上限，最多 3600 |

530| `allowed_tools` | `[]` | 案例想要的工具，例如 `[Read, Glob, Grep, Skill]`。唯讀工具在此列出時被授予；對於其他任何東西，請參閱 [Grant tools](#grant-tools) |

531| `append_system_prompt` | | 附加到子工作階段系統提示的文字 |

532| `env` | `{}` | 子工作階段的額外環境變數。鍵必須符合 `EVAL_[A-Z0-9_]*`；任何其他鍵都會導致執行失敗。執行只從您的 shell 繼承一個允許清單：基本項目如 `PATH` 和語言環境、代理和憑證設定、選擇和驗證您的模型提供者的變數、大多數 `ANTHROPIC_*` 和 `CLAUDE_CODE_*` 設定，以及 `EVAL_*`。要將任何其他東西交給 plugin，例如工具鏈設定，請將其匯出為 `EVAL_*` 變數 |

533

534<h3 id="case-yaml-fields">

535 case.yaml fields

536</h3>

537

538`case.yaml` 以 YAML 描述相同案例並新增指向其他檔案的欄位。它需要 `schema_version: "1.1"` 和 `name`。`prompt.md` 欄位 `description`、`tags`、`plugins`、`runs` 和 `expected_outcome` 在頂層；`model`、`max_turns`、`timeout_seconds`、`allowed_tools`、`append_system_prompt` 和 `env` 在 `execution:` 下。當兩個檔案都存在時，`prompt.md` frontmatter 覆蓋匹配的 `case.yaml` 欄位，`prompt.md` 主體是提示，`graders/*.md` 在 `case.yaml` 中列出的任何評分器之後新增。

539

540這些欄位僅存在於 `case.yaml` 中：

541

542| Field | Purpose |

543| :------------------------ | :--------------------------------------------------------------------------------------------------------------------------- |

544| `context.scaffold_script` | 案例目錄中的 Bash 指令碼，在 Claude 啟動前在空工作區中執行，以建立 fixture 檔案或 git 儲存庫。它只在您傳遞 [`--scaffold`](#add-setup-or-history-with-case-yaml) 時執行 |

545| `context.history_file` | 案例目錄中的 `.jsonl` 文字記錄以繼續。案例的提示變成下一個使用者回合 |

546| `context.add_dirs` | 案例目錄內的目錄，Claude 可能在執行期間讀取，被授予唯讀 |

547| `execution.prompt` | 提示，當您將整個案例保留在 `case.yaml` 中並省略 `prompt.md` 時 |

548| `graders` | 評分器清單，每個都有一個 `name` 加上 `graders/*.md` 檔案在 frontmatter 中採用的相同鍵。對於 `llm` 評分器，將評分標準放在 `criteria` 中 |

549

550<h3 id="grader-frontmatter">

551 Grader frontmatter

552</h3>

553

554`graders/` 下的每個評分器檔案在 frontmatter 中採用這些鍵，加上其類型的選項。評分器的名稱是沒有 `.md` 的檔案名稱：

555

556| Key | Default | Purpose |

557| :------- | :------ | :------------------------------------------------------------------------------------------------------------------------- |

558| `type` | 必需 | [grader types](#grader-types) 之一 |

559| `weight` | `1` | 執行分數中的相對權重。任何正數 |

560| `arm` | 未設定 | `with-only` 在 [two-arm run](#compare-against-a-no-plugin-baseline) 中排除評分器的評分；`both` 強制 `tool_used: Skill` 評分器在兩個 arm 中都被評分 |

561

562<h4 id="what-a-grader-can-look-at">

563 What a grader can look at

564</h4>

565

566`regex` 評分器採用 `target`，`llm` 評分器採用 `focus`。兩者都接受相同的值：

567

568| Value | What the grader sees |

569| :------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------- |

570| `last_message` | Claude 的最終回應文字。這是預設值 |

571| `trace` | 工作階段為 JSON，每行一條訊息。`regex` 評分器看到每條訊息；`llm` 評分器看到前 12 條和最後 12 條。其中的引號和換行符是 JSON 轉義的，所以 regex 符合 `\"` 而不是 `"` |

572| `files` | Claude 在執行期間建立的路徑清單，每行一個。不是它們的內容，也不是 scaffold 建立或 Claude 只修改的檔案 |

573| `{ source: file, path: <path> }` | 執行後工作區中一個檔案的內容。使用此來評分 plugin 產生的內容。PNG、JPEG、GIF 或 WebP 檔案會作為影像顯示給 `llm` 評分器。`llm` 評分器拒絕其他二進位檔案，例如 `.pptx` 或 PDF；將它們渲染為影像或寫出為文字並評分 |

574| `mock_calls` | Claude 對 [mocked MCP tool](#mock-mcp-servers) 進行的每次呼叫，及其輸入和 mock 的答案 |

575

576<h4 id="grader-types">

577 Grader types

578</h4>

579

580下面的每種評分器類型列出其選項和何時通過：

581

582| Type | Options | Passes when |

583| :------------ | :--------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------ |

584| `regex` | `pattern`、`flags`、`match`、`target` | JavaScript regex `pattern` 在目標中被找到。設定 `match: not_contains` 以要求缺失或 `match: "count:N"` 以要求恰好 N 個符合。在 `flags: i` 中放置不區分大小寫；不支援內聯 `(?i)` |

585| `tool_used` | `tool`、`input_match`、`min`、`max` | 對 `tool` 的呼叫次數，其 JSON 編碼的輸入符合可選的 `input_match` regex，介於 `min`（預設 1）和 `max`（預設無限制）之間。要聲稱工具從未被呼叫，請同時設定 `min: 0` 和 `max: 0` |

586| `tool_order` | `before`、`after` | 兩個工具都被呼叫，第一個符合的 `before` 呼叫先於第一個符合的 `after` 呼叫。每個都是工具名稱或 `{ tool, input_match }` |

587| `file_exists` | `path`、`exists` | Claude 建立的檔案符合 `path` glob，或沒有符合 `exists: false` 的。只有在執行期間建立的檔案計數 |

588| `llm` | `criteria`、`focus` | 評分器模型在至少三票中的兩票對評分標準投票通過。在 `.md` 佈局中，檔案主體是評分標準 |

589| `baseline` | `baseline_file`、`criteria` | 評分器發現執行至少與 `baseline_file`（案例目錄中的 `.jsonl`）的參考文字記錄一樣好地滿足評分標準 |

590

591<h3 id="mock-files">

592 Mock files

593</h3>

594

595`mocks/<server>/` 下的 `<tool>.md` 檔案回答一個工具。其主體是工具結果，具有 `{{input.<field>}}` 和 `{{file:fixtures/<name>}}` 替換。其 frontmatter 接受這些鍵：

596

597| Key | Default | Purpose |

598| :----------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------- |

599| `type` | `fixed` | `fixed` 按原樣返回主體。`agent` 將主體視為小型模型的指示，該模型為執行播放伺服器並將較早的呼叫視為歷史 |

600| `expect` | 未設定 | 從點分輸入路徑到類型名稱（例如 `string`、`number`、`boolean`、`array` 或 `object`）、`/regex/`、字面值或允許的字面值清單的對應。違反它的呼叫會以分數 0 中止執行，並報告為 `aborted`，包含伺服器、工具和原因 |

601| `error` | `false` | 僅 `fixed`。將主體作為工具錯誤返回 |

602| `abort_when` | 未設定 | 僅 `agent`。散文列出代理可能中止執行的唯一條件 |

603

604兩個可選檔案位於伺服器目錄中的工具檔案旁邊：

605

606* **`_server.md`**：一個單一的 `type: agent` mock，回答多個工具，在其 `tools:` frontmatter 鍵中列出。相同工具的 `<tool>.md` 優先。在個別 `<tool>.md` 上放置 `expect:` 保護，而不是這裡

607* **`_tools.json`**：來自真實伺服器的已保存 `tools/list` 回應，因此 mocked 工具帶有其真實描述和輸入架構，而不是寬鬆的佔位符

608

609案例自己的 `mocks/` 目錄使用相同的佈局並逐檔案覆蓋套件的 mocks。

610

611<h2 id="troubleshooting">

612 Troubleshooting

613</h2>

614

615這些是作者最常遇到的問題，按您看到的內容鍵入。

616

617<h3 id="plugin-eval-is-currently-in-early-access">

618 "plugin eval is currently in early access"

619</h3>

620

621您的建置早於命令的正式發佈。執行 `claude update`，然後在新工作階段中再次執行命令。

622

623<h3 id="plugin-eval-is-currently-unavailable">

624 "plugin eval is currently unavailable"

625</h3>

626

627Anthropic 已在伺服器端關閉命令。您的機器上沒有任何內容將其打開；執行 `claude update` 並稍後在新工作階段中重試。

628

629<h3 id="is-not-a-trusted-plugin-directory-and-this-run-cannot-stop-to-ask-you-about-it">

630 "is not a trusted plugin directory, and this run cannot stop to ask you about it"

631</h3>

632

633這是針對目錄的第一次執行，Claude Code 還不信任，並且因為 stdin 或 stdout 不是終端或您傳遞了 `--json` 而無法詢問。在終端中執行 `claude plugin eval <dir>` 一次並回答提示，或如果您信任 plugin 的程式碼和套件，請傳遞 `--trust-plugin`。請參閱 [What a run can access](#security)。

634

635<h3 id="no-eval-cases-found">

636 "No eval cases found"

637</h3>

638

639eval 目錄下沒有 `<case>/prompt.md` 或 `<case>/case.yaml` 存在，或您的 `--case` 和 `--tag` 篩選器沒有匹配任何案例。從 plugin 根目錄執行，或執行 `claude plugin eval init` 以建立套件。

640

641<h3 id="the-baseline-arm-shows-no-plugin-or-delta-is-zero">

642 The baseline arm shows no plugin, or delta is zero

643</h3>

644

645如果摘要沒有 `W/OUT` 列，或案例失敗並顯示「ablation requested but no plugin resolved」，則沒有為案例找到 plugin。將 `plugins: ["../.."]` 新增到案例，給出從案例目錄到 plugin 目錄的路徑。

646

647如果 plugin 確實載入並且 `Δ` 仍然接近零，您的 `tool_used: Skill` 評分器失敗，這通常是真實發現，意味著 skill 的 `description` 不會在提示的措辭上觸發。調整描述並重新執行相同的套件。

648

649<h3 id="everything-scores-zero-although-the-right-files-were-produced">

650 Everything scores zero although the right files were produced

651</h3>

652

653您的評分器目標 `files`（建立的路徑列表），當您指的是檔案的內容時。使用 `{ source: file, path: <path> }` 作為 `target` 或 `focus`。另外，`file_exists` 僅計算執行期間建立的檔案，因此 scaffold 建立或 Claude 僅編輯的檔案對它不可見；評分其內容，或在 `Edit` 上使用 `tool_used`。

654

655<h3 id="a-regex-over-the-trace-doesn’t-match-text-i-can-see">

656 A regex over the trace doesn't match text I can see

657</h3>

658

659預設 `target` 是 `last_message`，不是 trace。當您確實目標 `trace` 時，它是每行 JSON，因此引號顯示為 `\"`。正規表達式使用 JavaScript 語法，因此在 `flags` 中放置 `i` 而不是編寫 `(?i)`。

660

661<h3 id="tools-are-denied-mcp-tools-are-missing-or-bash-won’t-run">

662 Tools are denied, MCP tools are missing, or Bash won't run

663</h3>

664

665超過唯讀集的任何內容都需要您的授予，例如 `--allow-tools Bash Write`。您的個人 MCP 伺服器永遠不會在執行中載入。plugin 自己的伺服器不會啟動，除非您 [opt in](#mock-mcp-servers)，其工具也需要 `--allow-tools "mcp__plugin_<plugin>_<server>__*"` 授予；mocked 工具不需要任何一個。

666

667<h3 id="the-run-exits-1-but-the-results-look-fine">

668 The run exits 1 but the results look fine

669</h3>

670

671預設 `--threshold` 是 1.0，因此當任何案例評分低於完美時，命令退出 1。設定與您的標準相符的閾值。退出 1 也涵蓋案例檔案無法載入，在表格上方的 stderr 上報告。

672

673<h3 id="json-output-path-must-end-in-json">

674 "--json output path must end in .json"

675</h3>

676

677您將目標放在 `--json` 之後，因此它被讀取為輸出路徑。將目標放在首位，如 `claude plugin eval . --json`，或給 `--json` 一個明確的 `.json` 路徑。

678

679<h3 id="a-grader-shows-passed-false-under-a-run-that-scored-1-0">

680 A grader shows passed: false under a run that scored 1.0

681</h3>

682

683該評分器在兩個 arm 執行中按設計從分數中排除，其 `scored` 欄位為 `false`。請參閱 [Compare against a no-plugin baseline](#compare-against-a-no-plugin-baseline)。

684

685<h3 id="runs-fail-with-a-usage-limit-or-rate-limit-error-partway-through">

686 Runs fail with a usage-limit or rate-limit error partway through

687</h3>

688

689如果您的帳戶在套件執行時達到其方案的使用限制或 API 速率限制，每次後續執行都會以該錯誤結束，根據其產生的內容進行評分，通常評分為 0。套件仍然完成並未標記為 `partial`，因此結果可能看起來像迴歸。在信任分數之前檢查 `NOTES` 列或 JSON 中的 `cases[].arms.with[].error` 以獲取限制訊息，然後在限制重置後重新執行，如果您需要保持在其下方，則使用 `--runs 1` 或 `--case` 篩選器。

690

691<h3 id="runs-time-out-or-hit-the-turn-cap">

692 Runs time out or hit the turn cap

693</h3>

694

695預設值是 10 轉和 300 秒。在案例中提高 `max_turns` 和 `timeout_seconds` 以進行需要更多的任務，並使用 `--max-cost-usd` 作為成本上限而不是緊密的每次執行限制。

696

697<h2 id="see-also">

698 See also

699</h2>

700

701* [Create plugins](/docs/zh-TW/plugins)：建立您正在測試的 plugin，並在開發期間使用 `--plugin-dir` 載入它

702* [Plugins reference](/docs/zh-TW/plugins-reference#plugin-eval)：`plugin eval` 和 `plugin eval init` 命令項目以及資訊清單的 `experimental.evals` 鍵

703* [Skills](/docs/zh-TW/skills)：skill 的描述如何決定 Claude 何時呼叫它，這是檢查 skill 是否觸發的案例測量的內容

704* [Sandboxing](/docs/zh-TW/sandboxing)：當您授予 Bash 執行時適用的 OS 級沙箱

705* [Create and distribute a plugin marketplace](/docs/zh-TW/plugin-marketplaces)：一旦其套件通過，發佈 plugin

plugin-hints.md +1 −1

Details

36在環境變數上設定發出條件，以便標記不太可能在人類直接執行您的 CLI 時出現，然後將標籤寫入 stderr 的單獨一行。選擇要檢查的變數：36在環境變數上設定發出條件，以便標記不太可能在人類直接執行您的 CLI 時出現，然後將標籤寫入 stderr 的單獨一行。選擇要檢查的變數：

37 37

38* `CLAUDECODE`：在每個 Claude Code 版本上設定，因此可以到達最多的工作階段。它也在 Claude Code 啟動的 tmux 工作階段和 stdio MCP 伺服器子程序中設定，IDE 擴充功能在其整合終端中設定它，人類可能在那裡直接執行您的 CLI。38* `CLAUDECODE`：在每個 Claude Code 版本上設定，因此可以到達最多的工作階段。它也在 Claude Code 啟動的 tmux 工作階段和 stdio MCP 伺服器子程序中設定，IDE 擴充功能在其整合終端中設定它，人類可能在那裡直接執行您的 CLI。

39* `CLAUDE_CODE_CHILD_SESSION`：僅在 Claude Code 本身產生的子程序中設定，例如工具呼叫、hook 命令和[狀態列](/docs/zh-TW/statusline)命令，因此標籤通常不會到達人類終端。在工作階段內啟動的長期程序（例如 tmux 伺服器）會捕獲該變數，因此稍後從該程序啟動的 shell 仍會顯示原始標籤。需要 Claude Code v2.1.172 或更新版本，因此舊版本上的工作階段會遺漏提示。39* `CLAUDE_CODE_CHILD_SESSION`：僅在 Claude Code 本身產生的子程序中設定，例如工具呼叫、hook 命令和[狀態列](/docs/zh-TW/statusline)命令，因此標籤通常不會到達人類終端。在工作階段內啟動的長期程序（例如 tmux 伺服器）會捕獲該變數，因此稍後從該程序啟動的 shell 仍會顯示原始標籤。

40 40

41以下範例在 `CLAUDECODE` 上設定條件以達到最大覆蓋範圍，並為官方市場中名為 `example-cli` 的外掛程式發出提示：41以下範例在 `CLAUDECODE` 上設定條件以達到最大覆蓋範圍，並為官方市場中名為 `example-cli` 的外掛程式發出提示：

42 42

plugins.md +4 −1

Details

2344. Test coverage2344. Test coverage

235```235```

236 236

237安裝外掛程式後，檢查安裝摘要：如果它報告 `Run /reload-plugins to activate.`，請執行該命令以載入 Skills。如需完整的 Skill 編寫指南（包括漸進式揭露和工具限制），請參閱 [Agent Skills](/docs/zh-TW/skills)。237安裝外掛程式後，檢查安裝摘要：如果它報告 `Run /reload-plugins to activate.`，請參閱 [Apply plugin changes without restarting](/docs/zh-TW/discover-plugins#apply-plugin-changes-without-restarting) 以在您目前的工作階段中載入 Skills。如需完整的 Skill 編寫指南（包括漸進式揭露和工具限制），請參閱 [Agent Skills](/docs/zh-TW/skills)。

238 238

239<h3 id="add-lsp-servers-to-your-plugin">239<h3 id="add-lsp-servers-to-your-plugin">

240 將 LSP 伺服器新增至您的外掛程式240 將 LSP 伺服器新增至您的外掛程式

340 若要測試外掛程式及其依賴的外掛程式，請參閱 [Test a plugin and its dependency locally](/docs/zh-TW/plugin-dependencies#test-a-plugin-and-its-dependency-locally)。340 若要測試外掛程式及其依賴的外掛程式，請參閱 [Test a plugin and its dependency locally](/docs/zh-TW/plugin-dependencies#test-a-plugin-and-its-dependency-locally)。

341</Tip>341</Tip>

342 342

343使用 `--plugin-dir` 嘗試外掛程式可以告訴您它是否能夠運作。若要找出 Claude 實際上多常使用它並獲得正確的結果，請使用 [`claude plugin eval`](/docs/zh-TW/plugin-evals) 針對一組測試提示執行它。每個提示會在載入和不載入外掛程式的情況下執行多次，因此您可以看到外掛程式的貢獻，並在您變更它或新模型發佈時捕捉迴歸。

344

343若要從一個位置載入多個外掛程式，請傳遞包含它們的資料夾，例如 `--plugin-dir ./plugins`。載入外掛程式資料夾需要 Claude Code v2.1.265 或更新版本。Claude Code 讀取資料夾的頂層以決定哪些外掛程式載入，在互動式工作階段中，它也會監視資料夾以進行後續變更：345若要從一個位置載入多個外掛程式，請傳遞包含它們的資料夾，例如 `--plugin-dir ./plugins`。載入外掛程式資料夾需要 Claude Code v2.1.265 或更新版本。Claude Code 讀取資料夾的頂層以決定哪些外掛程式載入，在互動式工作階段中，它也會監視資料夾以進行後續變更：

344 346

345* **載入的內容**：如果資料夾的頂層沒有資訊清單或外掛程式元件，Claude Code 會將其視為外掛程式資料夾。每個具有 `.claude-plugin/plugin.json` 資訊清單的直接子資料夾都會作為單獨的外掛程式載入。Claude Code 會跳過資料夾中的所有其他內容，而不報告錯誤，包括沒有資訊清單的外掛程式。347* **載入的內容**：如果資料夾的頂層沒有資訊清單或外掛程式元件，Claude Code 會將其視為外掛程式資料夾。每個具有 `.claude-plugin/plugin.json` 資訊清單的直接子資料夾都會作為單獨的外掛程式載入。Claude Code 會跳過資料夾中的所有其他內容，而不報告錯誤，包括沒有資訊清單的外掛程式。

515 對於 plugin 開發人員517 對於 plugin 開發人員

516</h3>518</h3>

517 519

520* [使用 evals 測試 plugins](/docs/zh-TW/plugin-evals)：測量您的 plugin 所做的變更並在 CI 上進行把關

518* [建立和分發市場](/docs/zh-TW/plugin-marketplaces)：打包和共享您的 plugins521* [建立和分發市場](/docs/zh-TW/plugin-marketplaces)：打包和共享您的 plugins

519* [Plugins 參考](/docs/zh-TW/plugins-reference)：完整的技術規格522* [Plugins 參考](/docs/zh-TW/plugins-reference)：完整的技術規格

520* 深入探討特定的 plugin 元件：523* 深入探討特定的 plugin 元件：

plugins-reference.md +135 −67

Details

121 121

122Plugin hooks 回應與 [使用者定義的 hooks](/docs/zh-TW/hooks) 相同的生命週期事件：122Plugin hooks 回應與 [使用者定義的 hooks](/docs/zh-TW/hooks) 相同的生命週期事件：

123 123

124| Event | When it fires |124| 事件 | 何時觸發 |

125| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |125| :-------------------- | :-------------------------------------------------------------------------------------------------------------------- |

127| `Setup` | When you start Claude Code with `--init-only`, or with `--init` or `--maintenance` in `-p` mode. For one-time preparation in CI or scripts |127| `Setup` | 當您使用 `--init-only` 啟動 Claude Code，或在 `-p` 模式中使用 `--init` 或 `--maintenance` 時。用於 CI 或指令碼中的一次性準備 |

132| `PermissionDenied` | When auto mode denies a tool call, including denials without a classifier verdict. Use JSON `hookSpecificOutput.retry: true` to tell the model it may retry the denied tool call. Claude Code ignores `retry` when the classifier produced no verdict |132| `PermissionDenied` | 當自動模式拒絕工具呼叫時，包括沒有分類器判決的拒絕。使用 JSON `hookSpecificOutput.retry: true` 告訴模型它可能重試被拒絕的工具呼叫。Claude Code 在分類器未產生判決時忽略 `retry` |

145| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |145| `InstructionsLoaded` | 當 CLAUDE.md 或 `.claude/rules/*.md` 檔案被載入到上下文時。在工作階段開始時以及在工作階段期間延遲載入檔案時觸發 |

150| `WorktreeCreate` | When a worktree is being created via `--worktree`, `isolation: "worktree"`, or for a background session. Replaces default git behavior |150| `WorktreeCreate` | 當透過 `--worktree`、`isolation: "worktree"` 建立 worktree 時，或用於背景工作階段時。取代預設的 git 行為 |

159 159

160**Hook 類型**：160**Hook 類型**：

161 161

488 "lspServers": "./.lsp.json",488 "lspServers": "./.lsp.json",

489 "experimental": {489 "experimental": {

490 "themes": "./themes/",490 "themes": "./themes/",

491 "monitors": "./monitors.json"491 "monitors": "./monitors.json",

492 "evals": "quality/evals"

492 },493 },

493 "dependencies": [494 "dependencies": [

494 "helper-lib",495 "helper-lib",

564</h3>565</h3>

565 566

566| 欄位 | 類型 | 說明 | 範例 |567| 欄位 | 類型 | 說明 | 範例 |

567| :---------------------- | :-------------------- | :------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |568| :---------------------- | :-------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |

580| `dependencies` | array | 此 plugin 所需的其他 plugin，可選擇使用 semver 版本限制。請參閱[限制 plugin 相依性版本](/docs/zh-TW/plugin-dependencies) | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |582| `dependencies` | array | 此 plugin 所需的其他 plugin，可選擇使用 semver 版本限制。請參閱[限制 plugin 相依性版本](/docs/zh-TW/plugin-dependencies) | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |

998claude plugin init <name> [options]1000claude plugin init <name> [options]

999```1001```

1000 1002

1001**引數：**1003該命令接受這些引數：

1002 1004

1003* `<name>`：外掛程式名稱。成為技能命名空間和 `~/.claude/skills/` 下的目錄名稱，因此不能包含空格或路徑分隔符。1005* `<name>`：外掛程式名稱。成為技能命名空間和 `~/.claude/skills/` 下的目錄名稱，因此不能包含空格或路徑分隔符。

1004 1006

1005**選項：**1007該命令接受這些選項：

1006 1008

1007| 選項 | 說明 | 預設值 |1009| 選項 | 說明 | 預設值 |

1008| :----------------------- | :------------------------------------------------------------------------------ | :---------------------- |1010| :----------------------- | :------------------------------------------------------------------------------ | :---------------------- |

1015 1017

1016**別名：** `new`1018`claude plugin new` 是此命令的別名。

1017 1019

1018每個 `--with` 值都會為該元件新增一個入門檔案，準備好編輯：1020每個 `--with` 值都會為該元件新增一個入門檔案，準備好編輯：

1019 1021

1029 1031

1030建立框架的外掛程式使用 `@skills-dir` 來源，而不是市集。管理員可以使用 `strictKnownMarketplaces` 或在[受管設定](/docs/zh-TW/plugin-marketplaces#managed-marketplace-restrictions)中新增 `{"source": "skills-dir"}` 至 `blockedMarketplaces` 來封鎖此來源。當被封鎖時，`plugin init` 會在寫入前失敗。1032建立框架的外掛程式使用 `@skills-dir` 來源，而不是市集。管理員可以使用 `strictKnownMarketplaces` 或在[受管設定](/docs/zh-TW/plugin-marketplaces#managed-marketplace-restrictions)中新增 `{"source": "skills-dir"}` 至 `blockedMarketplaces` 來封鎖此來源。當被封鎖時，`plugin init` 會在寫入前失敗。

1031 1033

1032**範例：**1034這些範例顯示常見的叫用方式：

1033 1035

1034```bash theme={null}1036```bash theme={null}

1035# 建立最小外掛程式的框架1037# 建立最小外掛程式的框架

1052claude plugin install <plugin> [options]1054claude plugin install <plugin> [options]

1053```1055```

1054 1056

1055**引數：**1057該命令接受這些引數：

1056 1058

1057* `<plugin>`：外掛程式名稱或 `plugin-name@marketplace-name` 以指定特定市集1059* `<plugin>`：外掛程式名稱或 `plugin-name@marketplace-name` 以指定特定市集

1058 1060

1059**選項：**1061該命令接受這些選項：

1060 1062

1061| 選項 | 說明 | 預設值 |1063| 選項 | 說明 | 預設值 |

1062| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----- |1064| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----- |

1065| `-y, --yes` | 接受外掛程式市集宣告的命令，無需確認提示：產生具有 [`command` 來源](/docs/zh-TW/plugin-marketplaces#command-sources)的外掛程式的命令，或驗證封存下載的 [`headersHelper`](/docs/zh-TW/plugin-marketplaces#authenticate-archive-downloads)。接受 `headersHelper` 需要 Claude Code v2.1.238 或更新版本。Claude Code 仍會先列印命令。當 stdin 或 stdout 不是 TTY 時為必需。在 Claude Code 工作階段內無效，因此請從您自己的終端執行命令 | |1067| `-y, --yes` | 接受外掛程式市集宣告的命令，無需確認提示：產生具有 [`command` 來源](/docs/zh-TW/plugin-marketplaces#command-sources)的外掛程式的命令，或驗證封存下載的 [`headersHelper`](/docs/zh-TW/plugin-marketplaces#authenticate-archive-downloads)。接受 `headersHelper` 需要 Claude Code v2.1.238 或更新版本。Claude Code 仍會先列印命令。當 stdin 或 stdout 不是 TTY 時為必需。在 Claude Code 工作階段內無效，因此請從您自己的終端執行命令 | |

1068| `--json` | 將結果列印為 stdout 最後一行的一個 JSON 物件，供指令碼使用。請參閱 [JSON 結果格式](#plugin-json-result)。需要 Claude Code v2.1.268 或更新版本 | |

1067 1070

1068範圍決定已安裝外掛程式新增至哪個設定檔。例如，`--scope project` 會寫入 .claude/settings.json 中的 `enabledPlugins`，使外掛程式可供複製專案存放庫的所有人使用。1071範圍決定已安裝外掛程式新增至哪個設定檔。例如，`--scope project` 會寫入 .claude/settings.json 中的 `enabledPlugins`，使外掛程式可供複製專案存放庫的所有人使用。

1069 1072

1070**範例：**1073<span id="plugin-json-result" />使用 `--json` 時，stdout 的最後一行是一個 JSON 物件。只解析該行，因為 Claude Code 會在其前面列印市集宣告的任何命令。三個欄位始終存在：

1074

1075* `command`：執行的子命令，例如 `install`

1076* `outcome`：`ok` 或 `failed`

1077* `message`：結果的人類可讀說明

1078

1079其他欄位，例如 `pluginId`、`scope` 和 `failureCode`，僅在適用時出現。`plugin uninstall`、`plugin update`、`plugin enable` 和 `plugin disable` 上的 `--json` 選項會列印具有該子命令自己欄位的相同物件。使用錯誤（例如無效的 `--scope`）不會列印結果行，並以 stderr 上的原因退出 1。

1080

1081這些範例顯示常見的叫用方式：

1071 1082

1072```bash theme={null}1083```bash theme={null}

1073# 安裝至使用者範圍（預設）1084# 安裝至使用者範圍（預設）

1090claude plugin uninstall <plugin> [options]1101claude plugin uninstall <plugin> [options]

1091```1102```

1092 1103

1093**引數：**1104該命令接受這些引數：

1094 1105

1095* `<plugin>`：外掛程式名稱或 `plugin-name@marketplace-name`1106* `<plugin>`：外掛程式名稱或 `plugin-name@marketplace-name`

1096 1107

1097**選項：**1108該命令接受這些選項：

1098 1109

1099| 選項 | 說明 | 預設值 |1110| 選項 | 說明 | 預設值 |

1100| :-------------------- | :------------------------------------------------------- | :----- |1111| :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------- | :----- |

1116| `--json` | 將結果列印為 stdout 最後一行的一個 JSON 物件，格式與 [`plugin install --json`](#plugin-json-result) 相同。無法與 `--prune` 結合。需要 Claude Code v2.1.268 或更新版本 | |

1106 1118

1107**別名：** `remove`、`rm`1119`claude plugin remove` 和 `claude plugin rm` 是此命令的別名。

1108 1120

1109根據預設，從最後剩餘的範圍解除安裝也會刪除外掛程式的 `${CLAUDE_PLUGIN_DATA}` 目錄。使用 `--keep-data` 保留它，例如在測試新版本後重新安裝時。1121根據預設，從最後剩餘的範圍解除安裝也會刪除外掛程式的 `${CLAUDE_PLUGIN_DATA}` 目錄。使用 `--keep-data` 保留它，例如在測試新版本後重新安裝時。

1110 1122

1122claude plugin prune [options]1134claude plugin prune [options]

1123```1135```

1124 1136

1125**選項：**1137該命令接受這些選項：

1126 1138

1127| 選項 | 說明 | 預設值 |1139| 選項 | 說明 | 預設值 |

1128| :-------------------- | :---------------------------------- | :----- |1140| :-------------------- | :---------------------------------- | :----- |

1133 1145

1134**別名：** `autoremove`1146`claude plugin autoremove` 是此命令的別名。

1135 1147

1136該命令列出孤立的相依性，並在移除前要求確認。若要在一個步驟中移除外掛程式並清理其相依性，請執行 `claude plugin uninstall <plugin> --prune`。1148該命令列出孤立的相依性，並在移除前要求確認。若要在一個步驟中移除外掛程式並清理其相依性，請執行 `claude plugin uninstall <plugin> --prune`。

1137 1149

1145claude plugin enable <plugin> [options]1157claude plugin enable <plugin> [options]

1146```1158```

1147 1159

1148**引數：**1160該命令接受這些引數：

1149 1161

1150* `<plugin>`：外掛程式名稱或 `plugin-name@marketplace-name`1162* `<plugin>`：外掛程式名稱或 `plugin-name@marketplace-name`

1151 1163

1152**選項：**1164該命令接受這些選項：

1153 1165

1154| 選項 | 說明 | 預設值 |1166| 選項 | 說明 | 預設值 |

1155| :-------------------- | :------------------------------------------------------------- | :--- |1167| :-------------------- | :---------------------------------------------------------------------------------------------------------------- | :--- |

1169| `--json` | 將結果列印為 stdout 最後一行的一個 JSON 物件，格式與 [`plugin install --json`](#plugin-json-result) 相同。需要 Claude Code v2.1.268 或更新版本 | |

1158 1171

1159<h3 id="plugin-disable">1172<h3 id="plugin-disable">

1166claude plugin disable [plugin] [options]1179claude plugin disable [plugin] [options]

1167```1180```

1168 1181

1169**引數：**1182該命令接受這些引數：

1170 1183

1171* `[plugin]`：外掛程式名稱或 `plugin-name@marketplace-name`。使用 `--all` 時為選用。1184* `[plugin]`：外掛程式名稱或 `plugin-name@marketplace-name`。使用 `--all` 時為選用。

1172 1185

1173**選項：**1186該命令接受這些選項：

1174 1187

1175| 選項 | 說明 | 預設值 |1188| 選項 | 說明 | 預設值 |

1176| :-------------------- | :------------------------------------------------------------- | :--- |1189| :-------------------- | :---------------------------------------------------------------------------------------------------------------- | :--- |

1192| `--json` | 將結果列印為 stdout 最後一行的一個 JSON 物件，格式與 [`plugin install --json`](#plugin-json-result) 相同。需要 Claude Code v2.1.268 或更新版本 | |

1180 1194

1181<h3 id="plugin-update">1195<h3 id="plugin-update">

1188claude plugin update <plugin> [options]1202claude plugin update <plugin> [options]

1189```1203```

1190 1204

1191**引數：**1205該命令接受這些引數：

1192 1206

1193* `<plugin>`：外掛程式名稱或 `plugin-name@marketplace-name`1207* `<plugin>`：外掛程式名稱或 `plugin-name@marketplace-name`

1194 1208

1195**選項：**1209該命令接受這些選項：

1196 1210

1197| 選項 | 說明 | 預設值 |1211| 選項 | 說明 | 預設值 |

1198| :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----- |1212| :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----- |

1200| `-y, --yes` | 接受外掛程式市集宣告的命令，無需確認提示：產生具有 [`command` 來源](/docs/zh-TW/plugin-marketplaces#command-sources)的外掛程式的命令，或驗證封存下載的 [`headersHelper`](/docs/zh-TW/plugin-marketplaces#authenticate-archive-downloads)。接受 `headersHelper` 需要 Claude Code v2.1.238 或更新版本。Claude Code 仍會先列印命令。當 stdin 或 stdout 不是 TTY 時為必需。在 Claude Code 工作階段內無效，因此請從您自己的終端執行命令 | |1214| `-y, --yes` | 接受外掛程式市集宣告的命令，無需確認提示：產生具有 [`command` 來源](/docs/zh-TW/plugin-marketplaces#command-sources)的外掛程式的命令，或驗證封存下載的 [`headersHelper`](/docs/zh-TW/plugin-marketplaces#authenticate-archive-downloads)。接受 `headersHelper` 需要 Claude Code v2.1.238 或更新版本。Claude Code 仍會先列印命令。當 stdin 或 stdout 不是 TTY 時為必需。在 Claude Code 工作階段內無效，因此請從您自己的終端執行命令 | |

1215| `--json` | 將結果列印為 stdout 最後一行的一個 JSON 物件，格式與 [`plugin install --json`](#plugin-json-result) 相同。需要 Claude Code v2.1.268 或更新版本 | |

1202 1217

1203<Note>1218<Note>

1216claude plugin list [options]1231claude plugin list [options]

1217```1232```

1218 1233

1219**選項：**1234該命令接受這些選項：

1220 1235

1221| 選項 | 說明 | 預設值 |1236| 選項 | 說明 | 預設值 |

1222| :------------ | :----------------------- | :-- |1237| :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-- |

1226 1241

1242claude plugin details <name>1257claude plugin details <name>

1243```1258```

1244 1259

1245**引數：**1260該命令接受這些引數：

1246 1261

1247* `<name>`：外掛程式名稱或 `plugin-name@marketplace-name`1262* `<name>`：外掛程式名稱或 `plugin-name@marketplace-name`

1248 1263

1249**選項：**1264該命令接受這些選項：

1250 1265

1251| 選項 | 說明 | 預設值 |1266| 選項 | 說明 | 預設值 |

1252| :----------- | :----- | :-- |1267| :----------- | :----- | :-- |

1297claude plugin validate <path> [options]1312claude plugin validate <path> [options]

1298```1313```

1299 1314

1300**引數：**1315該命令接受這些引數：

1301 1316

1302* `<path>`：外掛程式目錄或市集目錄的路徑。請參閱[驗證沒有資訊清單的外掛程式或目錄](/docs/zh-TW/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest)以了解外掛程式執行涵蓋的檔案。1317* `<path>`：外掛程式目錄或市集目錄的路徑。請參閱[驗證沒有資訊清單的外掛程式或目錄](/docs/zh-TW/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest)以了解外掛程式執行涵蓋的檔案。

1303 1318

1304**選項：**1319該命令接受這些選項：

1305 1320

1306| 選項 | 說明 | 預設值 |1321| 選項 | 說明 | 預設值 |

1307| :----------- | :---------------------------------------------------------------------- | :-- |1322| :----------- | :---------------------------------------------------------------------- | :-- |

1321 1336

1322在互動式工作階段中，`/plugin validate <path>` 會內嵌執行相同的檢查。1337在互動式工作階段中，`/plugin validate <path>` 會內嵌執行相同的檢查。

1323 1338

1339<h3 id="plugin-eval">

1340 plugin eval

1341</h3>

1342

1343執行外掛程式的[評估案例](/docs/zh-TW/plugin-evals)並報告評分結果。需要 Claude Code v2.1.269 或更新版本。每個案例都是一個提示加評分者；Claude Code 在隔離的工作階段中執行它多次，只載入目標外掛程式，預設情況下也不載入外掛程式，以便報告顯示差異。請參閱[使用評估測試外掛程式](/docs/zh-TW/plugin-evals)以了解案例格式、評分者、結果和 CI 使用。

1344

1345```bash theme={null}

1346claude plugin eval [target] [options]

1347```

1348

1349選用的 `target` 是外掛程式目錄、單個 `prompt.md` 或 `case.yaml` 檔案、已安裝的外掛程式作為 `name` 或 `name@marketplace`，或 `name@skills-dir`，預設為目前目錄。將其放在 `--tag`、`--allow-tools` 和 `--json` 之前。

1350

1351此表列出大多數執行使用的選項。執行 `claude plugin eval --help` 以取得完整集合，包括 `--case`、`--tag`、`--output-dir`、`--report`、`--allow-real-servers`、`--keep-temp` 和 `--verbose`。

1352

1353| 選項 | 說明 | 預設值 |

1354| :------------------------- | :--------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------- |

1355| `--runs <n>` | 每個案例每個臂的執行次數 | 每個案例的 `runs`，否則 3 |

1356| `-j, --concurrency <n>` | 同時執行的代理工作階段，1 到 8。它們共享您的速率限制 | `1` |

1357| `--model <model>` | 受測代理的模型 | 每個案例的 `model`，否則 `ANTHROPIC_MODEL`（如果設定），否則 Claude Code 的預設值 |

1358| `--judge-model <model>` | `llm` 和 `baseline` 評分者的模型 | 一個小型快速模型 |

1359| `--ablation <mode>` | `none` 或 `with-without`。請參閱[與無外掛程式基線比較](/docs/zh-TW/plugin-evals#compare-against-a-no-plugin-baseline) | 當外掛程式解析時為 `with-without`，否則為 `none` |

1360| `--threshold <0..1>` | 如果任何案例評分低於此值，退出 1 | `1.0` |

1361| `--max-cost-usd <usd>` | 一旦支出達到此值，停止下一次執行，退出 2，並報告部分結果 | 無上限 |

1362| `--allow-tools <tools...>` | 授予超過唯讀集合的工具，例如 `Bash`、`Write`、`Edit` 或 `"mcp__plugin_<plugin>_<server>__*"`。請參閱[授予工具](/docs/zh-TW/plugin-evals#grant-tools) | |

1363| `--scaffold` | 執行每個案例的 [`scaffold_script`](/docs/zh-TW/plugin-evals#add-setup-or-history-with-case-yaml) | 關閉 |

1364| `--trust-plugin` | 跳過首次執行信任提示，用於 CI。請參閱[執行可以存取的內容](/docs/zh-TW/plugin-evals#security) | 關閉 |

1365| `--mocks <mode>` | `record` 或 `off`。請參閱[模擬 MCP 伺服器](/docs/zh-TW/plugin-evals#mock-mcp-servers) | `record` |

1366| `--eval-dir <dir>` | 保存案例的外掛程式下方的目錄 | 資訊清單的 `experimental.evals`，否則 `evals` |

1367| `--json [path]` | 將[結果文件](/docs/zh-TW/plugin-evals#json-result)列印至 stdout，或將其寫入 `.json` 路徑 | |

1368| `--no-publish` | 保持 HTML 報告本機 | |

1369| `-h, --help` | 顯示命令說明 | |

1370

1371當每個案例都符合閾值時，命令退出 0，在失敗案例、載入錯誤或不受信任的外掛程式目錄時退出 1，在部分執行時退出 2，中斷時退出 130，終止時退出 143。請參閱[在 CI 中執行評估](/docs/zh-TW/plugin-evals#run-evals-in-ci)。

1372

1373<h3 id="plugin-eval-init">

1374 plugin eval init

1375</h3>

1376

1377為目前目錄中的外掛程式建立評估套件。需要 Claude Code v2.1.269 或更新版本。在終端中，這會啟動一個編寫訪談，讀取外掛程式、提議案例和評分者、試驗它們，並寫入檔案。使用 `--bare` 或沒有終端時，它會改為寫入一個空白的單案例範本。從互動式 Claude Code 工作階段內執行時，它會列印該工作階段要遵循的訪談說明，而不是寫入範本。請參閱[建立您的第一個評估套件](/docs/zh-TW/plugin-evals#create-your-first-eval-suite)。

1378

1379```bash theme={null}

1380claude plugin eval init [name] [options]

1381```

1382

1383選用的 `name` 是案例名稱：訪談不需要一個，而 `--bare` 和無終端範本路徑需要一個。它接受這些選項：

1384

1385| 選項 | 說明 | 預設值 |

1386| :------------------ | :---------------------------------------------------- | :------------------------------------ |

1387| `--bare` | 改為為 `<name>` 寫入空白 `prompt.md` 和 `graders/criteria.md` | |

1388| `-i, --interactive` | 需要訪談。沒有終端時失敗，而不是寫入範本 | |

1389| `--eval-dir <dir>` | 目前目錄下方寫入案例的目錄 | 資訊清單的 `experimental.evals`，否則 `evals` |

1390| `-h, --help` | 顯示命令說明 | |

1391

1324<h3 id="plugin-tag">1392<h3 id="plugin-tag">

1325 plugin tag1393 plugin tag

1326</h3>1394</h3>

1331claude plugin tag [path] [options]1399claude plugin tag [path] [options]

1332```1400```

1333 1401

1334**引數：**1402該命令接受這些引數：

1335 1403

1336* `[path]`：外掛程式目錄的路徑。預設為目前目錄。1404* `[path]`：外掛程式目錄的路徑。預設為目前目錄。

1337 1405

1338**選項：**1406該命令接受這些選項：

1339 1407

1340| 選項 | 說明 | 預設值 |1408| 選項 | 說明 | 預設值 |

1341| :-------------------- | :----------------------- | :------- |1409| :-------------------- | :----------------------- | :------- |

prompt-caching.md +230 −112

Details

4 4

5# Claude Code 如何使用 prompt caching5# Claude Code 如何使用 prompt caching

6 6

7> Claude Code 自動管理 prompt caching。了解為什麼模型切換會觸發緩慢的未快取轉換、`/compact` 的成本、為什麼 CLAUDE.md 編輯在會話中期不適用，以及如何檢查快取命中率。7> Claude Code 會自動管理 prompt caching。了解為什麼模型切換會觸發緩慢的未快取回應、`/compact` 的成本、為什麼 CLAUDE.md 編輯在工作階段中途不適用，以及如何檢查您的快取命中率。

8 8

9Prompt caching 使 Claude Code 更快速且更具成本效益。沒有快取的情況下，API 會在每次轉換時重新處理您的完整歷史記錄。有了快取，它會重複使用已經處理過的內容，只對變更的部分進行新工作。9Prompt caching 讓 Claude Code 更快速且更具成本效益。沒有快取的情況下，API 會在每一回合重新處理您的完整歷史記錄。有了快取，它會重複使用已經處理過的內容，以[快取代幣費率](https://platform.claude.com/docs/en/about-claude/pricing)計費重新讀取，並且只完整處理已變更的部分。

10 10

11Claude Code 會為您處理 prompt caching，除非您[禁用它](#disable-prompt-caching)。了解 prompt caching 的工作原理仍然很有用，因為某些操作會使快取失效，使下一個回應變得更慢且更昂貴，同時它重新建立快取。本頁涵蓋哪些操作會這樣做、為什麼某些設定需要等待重新啟動才能應用，以及當使用量看起來很高時如何檢查快取效能。11Claude Code 會為您自動處理 prompt caching，除非您[停用它](#disable-prompt-caching)。了解 prompt caching 的運作方式仍然很有用，因為某些操作會使快取失效，並在重建時使下一個回應變得更慢且更昂貴。本頁面涵蓋哪些操作會這樣做、為什麼某些設定需要等待重新啟動才能套用，以及當使用量看起來很高時如何檢查快取效能。

12 12

13<h2 id="how-the-cache-is-organized">13<h2 id="how-the-cache-is-organized">

14 快取的組織方式14 快取的組織方式

15</h2>15</h2>

16 16

17每次您在 Claude Code 中發送訊息時，它都會發出新的 API 請求。模型在請求之間不記得任何內容，因此 Claude Code 會重新發送完整的上下文：系統提示、您的專案上下文、每個先前的訊息和工具結果，以及您的新訊息。新內容會附加在末尾，這意味著每個請求的大部分內容與前一個請求相同。Prompt caching 是 API 避免重新處理未變更部分的方式。17每次您在 Claude Code 中傳送訊息時，它都會發出新的 API 請求。模型在請求之間不會記住任何內容，因此 Claude Code 會重新傳送完整的上下文：系統提示、您的專案上下文、每個先前的訊息和工具結果，以及您的新訊息。新內容會附加在末尾，這表示每個請求的大部分內容與前一個請求相同。Prompt caching 是 API 避免重新處理未變更部分的方式。

18 18

19API 通過將每個請求的開始部分（稱為前綴）與最近處理過的內容進行匹配來進行快取。在正常轉換中，前綴是整個先前的請求，只有最新的交換是新的。匹配是精確的，因此前綴中任何地方的變更都會重新計算其後的所有內容。沒有按檔案或按段的快取。請參閱 API 參考中的[prompt caching 如何工作](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-caching#how-prompt-caching-works)以了解基礎機制。19API 透過將每個請求的開始部分（稱為前綴）與最近處理的內容進行比對來進行快取。在正常的回合中，前綴是整個先前的請求，只有最新的交換是新的。比對是精確的，因此前綴中任何地方的變更都會重新計算其後的所有內容。沒有按檔案或按區段的快取。請參閱 API 參考中的 [prompt caching 如何運作](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#how-prompt-caching-works)以了解基礎機制。

20 20

21<img src="https://mintcdn.com/claude-code/VbDJw--l6T9a9Wvm/images/prompt-caching-prefix.svg?fit=max&auto=format&n=VbDJw--l6T9a9Wvm&q=85&s=f2e8f0b8298a50305fe428ca3f1d1594" className="dark:hidden" alt="四個轉換顯示為不斷增長的水平條。每個轉換的請求包含前一個轉換的所有內容加上附加在末尾的最新交換。在第二和第三個轉換中，未變更的前綴從快取中讀取，只有新的交換被處理。在第四個轉換中，系統提示已變更，因此前綴不再匹配，整個請求被重新處理並寫入。" width="720" height="454" data-path="images/prompt-caching-prefix.svg" />21<img src="https://mintcdn.com/claude-code/VbDJw--l6T9a9Wvm/images/prompt-caching-prefix.svg?fit=max&auto=format&n=VbDJw--l6T9a9Wvm&q=85&s=f2e8f0b8298a50305fe428ca3f1d1594" className="dark:hidden" alt="四個回合顯示為不斷增長的水平條。每個回合的請求包含前一個回合的所有內容加上末尾附加的最新交換。在第二和第三個回合中，未變更的前綴從快取中讀取，只有新的交換被處理。在第四個回合中，系統提示已變更，因此前綴不再比對，整個請求被重新處理並寫入。" width="720" height="454" data-path="images/prompt-caching-prefix.svg" />

22 22

23<img src="https://mintcdn.com/claude-code/_xqph1dUOslCOwsj/images/prompt-caching-prefix-dark.svg?fit=max&auto=format&n=_xqph1dUOslCOwsj&q=85&s=297dc1c639f0915cae858d0c4b6f3be5" className="hidden dark:block" alt="四個轉換顯示為不斷增長的水平條。每個轉換的請求包含前一個轉換的所有內容加上附加在末尾的最新交換。在第二和第三個轉換中，未變更的前綴從快取中讀取，只有新的交換被處理。在第四個轉換中，系統提示已變更，因此前綴不再匹配，整個請求被重新處理並寫入。" width="720" height="454" data-path="images/prompt-caching-prefix-dark.svg" />23<img src="https://mintcdn.com/claude-code/_xqph1dUOslCOwsj/images/prompt-caching-prefix-dark.svg?fit=max&auto=format&n=_xqph1dUOslCOwsj&q=85&s=297dc1c639f0915cae858d0c4b6f3be5" className="hidden dark:block" alt="四個回合顯示為不斷增長的水平條。每個回合的請求包含前一個回合的所有內容加上末尾附加的最新交換。在第二和第三個回合中，未變更的前綴從快取中讀取，只有新的交換被處理。在第四個回合中，系統提示已變更，因此前綴不再比對，整個請求被重新處理並寫入。" width="720" height="454" data-path="images/prompt-caching-prefix-dark.svg" />

24 24

~~25為了充分利用前綴匹配，Claude Code 會組織每個請求，使轉換之間很少變更的內容首先出現：~~25為了充分利用前綴比對，Claude Code 會組織每個請求，使得在回合之間很少變更的內容優先出現：

26 26

~~27| 層 | 內容 | 變更時機 |~~27| 層級 | 內容 | 變更時機 |

~~28| ----- | -------------------- | -------------------------------- |~~28| ----- | ----------------------- | ----------------------------------- |

~~31| 對話 | 您的訊息、Claude 的回應、工具結果 | 每次轉換 |~~31| 對話 | 您的訊息、Claude 的回應、工具結果 | 每個回合 |

32 32

33對對話層的變更會保留系統提示和專案上下文的快取。對系統提示的變更會使所有內容失效，因為所有後續內容現在位於不同的前綴後面。第三列提供常見觸發器而不是詳盡列表，下面的部分涵蓋完整集合，包括在會話開始時固定的輸出風格等內容。33對對話層的變更會保留系統提示和專案上下文的快取。對系統提示的變更會使所有內容失效，因為所有後續內容現在位於不同的前綴後面。第三欄提供常見的觸發器，而不是詳盡的清單，下面的章節涵蓋完整的集合。

34 34

35前綴匹配規則解釋了本頁上的大多數行為。例如，[Plan Mode](/docs/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 和[技能加載](/docs/zh-TW/skills)將其指令附加為對話訊息，因此快取的前綴保持完整。35前綴比對規則解釋了此頁面上的大多數行為。例如，[Plan Mode](/docs/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 和 [skill loading](/docs/zh-TW/skills) 會將其指示附加為對話訊息，因此快取的前綴保持完整。

36 36

~~37兩個設定根本不是提示文本的一部分，因此它們不會出現在層表中，但兩者都是快取金鑰的一部分：~~37有兩個設定不會出現在層級表中，但仍會影響保留的快取內容：

38 38

~~39* **Model**：每個模型都有自己的快取。切換模型會重新計算整個請求，即使內容相同。請參閱下面的[切換模型](#switching-models)。~~39* **Model**：每個模型都有自己的快取。切換模型會重新計算整個請求，即使內容相同。請參閱下面的 [Switching models](#switching-models)。

40* **Effort level**：同一模型的每個努力級別都有自己的快取。在會話中期變更它會重新計算整個請求，Claude Code 會要求您在應用變更前確認。請參閱下面的[變更努力級別](#changing-effort-level)。40* **Effort level**：在大多數模型上，每個 effort level 都有自己的快取，因此在工作階段中途變更 effort 會重新計算整個請求。在具有 API 金鑰或 Claude 訂閱的 Fable 5.1 上，快取預設保持完整。請參閱下面的 [Changing effort level](#changing-effort-level)。

41 41

42<Tip>42<Tip>

~~43 在會話開始時選擇您的模型和努力級別，然後在任務之間的自然中斷處保存 `/compact`。您在任務中期進行的變更越少，快取命中率就越高。~~43 在工作階段的開始選擇您的模型和 effort level，然後在任務之間的自然中斷處保存 `/compact`。您在任務中途進行的變更越少，快取命中率就越高。

44</Tip>44</Tip>

45 45

46<h3 id="where-the-cache-lives">46<h3 id="where-the-cache-lives">

~~47 快取位置~~47 快取的位置

48</h3>48</h3>

49 49

~~50快取發生在伺服器端，在提供您的模型的任何基礎設施中。位置取決於您如何進行身份驗證：~~50快取發生在伺服器端，在提供您的模型的任何基礎設施中。位置取決於您的身份驗證方式：

51 51

52* **API 金鑰、Claude 訂閱或 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws)**：快取位於 Anthropic 的基礎設施中，通過 [Claude API](https://platform.claude.com/docs) 訪問52* **API 金鑰、Claude 訂閱或 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws)**：快取位於 Anthropic 的基礎設施中，透過 [Claude API](https://platform.claude.com/docs) 存取

~~53* **Amazon Bedrock 或 Google Cloud 的 Agent Platform**：快取位於您的雲端提供商的服務基礎設施中~~53* **Amazon Bedrock 或 Google Cloud 的 Agent Platform**：快取位於您的雲端提供者的提供基礎設施中

~~54* **Microsoft Foundry**：請求路由到 Anthropic 的基礎設施~~54* **Microsoft Foundry**：取決於部署的 [hosting option](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)。在 Azure 部署上託管的部署在 Azure 基礎設施上提供；在 Anthropic 部署上託管的部署在 Anthropic 的基礎設施上提供

~~55* **自訂 `ANTHROPIC_BASE_URL` 或 [LLM gateway](/docs/zh-TW/llm-gateway)**：快取位於您的請求轉發到的位置，快取是否工作取決於閘道~~55* **自訂 `ANTHROPIC_BASE_URL` 或 [LLM gateway](/docs/zh-TW/llm-gateway)**：快取位於您的請求被轉發的位置，快取是否有效取決於閘道

56 56

57有關每個提供商存儲和處理的內容，請參閱[資料使用](/docs/zh-TW/data-usage)。無論快取位於何處，條目在一段時間不活動後過期，[下面的快取生命週期](#cache-lifetime)涵蓋 TTL 以及如何延長它。57Claude Code 也會在對話中途附加系統上下文，例如檔案變更通知，並在每個提供者和連線上標記該區塊以進行快取，除非您設定 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/zh-TW/llm-gateway-protocol#disable-pre-release-capabilities)，在這種情況下該區塊會以未快取的方式傳送。

59在提供者自己的端點、Amazon Bedrock 及其 [Mantle endpoint](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint)、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，快取該區塊的方式與 Claude API 相同。

61當您的請求通過 [LLM gateway](/docs/zh-TW/llm-gateway)、自訂 `ANTHROPIC_BASE_URL` 或雲端提供者基礎 URL 覆蓋（例如 [`ANTHROPIC_BEDROCK_BASE_URL`](/docs/zh-TW/env-vars)）時，保留的快取取決於閘道如何處理 Claude Code 傳送的 [`cache_control` 標記](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#explicit-cache-breakpoints)：

63* **原封不動地轉發它們**：該區塊和您的對話快取方式與在提供者自己的端點上相同。

64* **以命名 `cache_control` 的 `400` 錯誤拒絕標記的請求**：Claude Code 會重新傳送請求，將標記從區塊移到您的最後一條對話訊息上，並在對話的其餘部分保持在那裡。該區塊計費為未快取的輸入；您的對話保持快取。

65* **在返回成功時移除標記**：您的整個對話歷史記錄在每個回合上計費為未快取的輸入。將區塊形式的系統內容轉換為純字串的閘道會以相同的方式丟棄標記。

67有關每個提供者儲存和處理的內容，請參閱 [data usage](/docs/zh-TW/data-usage)。無論快取位於何處，條目在一段時間不活動後過期，下面的 [Cache lifetime](#cache-lifetime) 涵蓋 TTL 以及如何延長它。

58 68

59<h2 id="actions-that-invalidate-the-cache">69<h2 id="actions-that-invalidate-the-cache">

~~60 使快取失效的操作~~70 使快取失效的動作

61</h2>71</h2>

62 72

63這些操作會導致下一個請求錯過部分或全部快取。您會看到一次較慢、更昂貴的轉換，之後新的前綴會被快取。一旦您知道它們有成本，大多數都可以在任務中期避免。模型切換可能看起來是免費的，直到您注意到隨後的較慢轉換。73這些動作會導致下一個請求遺漏部分或全部快取。您會看到一次較慢、成本較高的回合，之後新的前綴會被快取。一旦您知道它們有成本，大多數動作在任務進行中是可以避免的。模型切換可能感覺沒有成本，直到您注意到隨後的較慢回合。

64 74

65* [切換模型](#switching-models)75* [切換模型](#switching-models)

66* [變更努力程度](#changing-effort-level)76* [變更努力程度](#changing-effort-level)

69* [啟用或停用外掛程式](#enabling-or-disabling-a-plugin)79* [啟用或停用外掛程式](#enabling-or-disabling-a-plugin)

70* [拒絕整個工具](#denying-an-entire-tool)80* [拒絕整個工具](#denying-an-entire-tool)

71* [壓縮對話](#compacting-the-conversation)81* [壓縮對話](#compacting-the-conversation)

82* [累積許多影像](#accumulating-many-images)

72* [升級 Claude Code](#upgrading-claude-code)83* [升級 Claude Code](#upgrading-claude-code)

73 84

74<h3 id="switching-models">85<h3 id="switching-models">

75 切換模型86 切換模型

76</h3>87</h3>

77 88

78每個模型都有自己的快取。使用 [`/model`](/docs/zh-TW/model-config#setting-your-model) 切換意味著下一個請求讀取整個對話歷史記錄而沒有快取命中，即使內容相同。89每個模型都有自己的快取。使用 [`/model`](/docs/zh-TW/model-config#setting-your-model) 切換意味著下一個請求會讀取整個對話歷史記錄而沒有快取命中，即使內容相同。

91當您在終端執行 `/model` 時，Claude Code 會要求您確認切換，但僅限於快取仍然溫暖時。快取在 Claude Code 在此對話中最後一次傳送請求或 Claude 最後一次回應後的一個[快取 TTL](#cache-lifetime) 內保持溫暖。一旦該時間過去，快取就會過期，因此 Claude Code 會在不詢問的情況下進行切換。

93在 v2.1.238 之前，Claude Code 沒有檢查快取 TTL，即使在快取過期後也會詢問。

95您也可以使用 [PreModelSwitch hook](/docs/zh-TW/hooks#premodelswitch-decision-control) 要求此確認或跳過它。

79 96

80[`opusplan` 模型設定](/docs/zh-TW/model-config#opusplan-model-setting)在 Plan Mode 期間解析為 Opus，在執行期間解析為 Sonnet，因此每個 Plan Mode 切換都是模型切換並啟動新的快取。97[`opusplan` 模型設定](/docs/zh-TW/model-config#opusplan-model-setting)在計畫模式期間解析為 Opus，在執行期間解析為 Sonnet，因此每次計畫模式切換都是模型切換並啟動新的快取。

81 98

82[Fable 5 上的自動模型回退](/docs/zh-TW/model-config#automatic-model-fallback)也是模型切換。當安全分類器標記請求時，Claude Code 會在預設 Opus 模型上重新執行它，會話會在那裡繼續。99[自動模型回退](/docs/zh-TW/model-config#automatic-model-fallback)在 Fable 模型和 Opus 5 上也是模型切換。當安全分類器在具有回退模型的類別中標記請求時，Claude Code 會在該模型上重新執行請求，並且工作階段會在那裡繼續。

100

101當技能或命令的前置資料命名一個[`model`](/docs/zh-TW/skills#frontmatter-reference)不同於工作階段目前模型時，該回合也是模型切換：下一個請求會讀取整個對話歷史記錄而沒有快取命中。工作階段模型會在您的下一個提示時繼續。`context: fork` 技能會設定[分叉子代理的模型](/docs/zh-TW/skills#run-skills-in-a-subagent)。

83 102

84<h3 id="changing-effort-level">103<h3 id="changing-effort-level">

85 變更努力程度104 變更努力程度

86</h3>105</h3>

87 106

88快取由[努力程度](/docs/zh-TW/model-config#adjust-effort-level)以及模型作為鍵，因此使用 `/effort` 切換意味著下一個請求讀取整個對話歷史記錄而沒有快取命中。一旦對話開始，Claude Code 會在應用會使快取失效的努力程度變更之前顯示確認對話框。解析為已生效的相同程度的變更（例如明確設定模型的預設值）會跳過對話框並保持快取。107在大多數模型上，在工作階段中途變更[努力程度](/docs/zh-TW/model-config#adjust-effort-level)意味著下一個請求會讀取整個對話歷史記錄而沒有快取命中。當快取仍然溫暖時，Claude Code 會要求您先確認變更。

108

109在具有 API 金鑰或 Claude 訂閱的 Fable 5.1 上，變更努力程度會保留快取，Claude Code 會在不詢問的情況下套用新的程度。這不適用於 Amazon Bedrock、Google Cloud 的 Agent Platform 或 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway)，或當您設定 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/zh-TW/llm-gateway-protocol#disable-pre-release-capabilities) 或您的組織具有 HIPAA 設定時。

110

111在 v2.1.260 之前，在具有 API 金鑰或 Claude 訂閱的 Fable 5.1 上變更努力程度也會使快取失效。

89 112

90<h3 id="turning-on-fast-mode">113<h3 id="turning-on-fast-mode">

91 開啟快速模式114 開啟快速模式

92</h3>115</h3>

93 116

94啟用[快速模式](/docs/zh-TW/fast-mode)會新增一個請求標頭，該標頭是快取鍵的一部分，因此下一個請求讀取整個對話歷史記錄而沒有快取命中。這些未快取的輸入令牌按[快速模式費率](/docs/zh-TW/fast-mode#understand-the-cost-tradeoff)計費，這就是為什麼在會話開始時開啟它的成本比在長會話深處開啟它的成本要低。從非 Opus 模型啟用快速模式也會[切換您的模型](#switching-models)，這本身會啟動新的快取。117啟用[快速模式](/docs/zh-TW/fast-mode)會新增一個請求標頭，該標頭是快取金鑰的一部分，因此 Claude Code 傳送的第一個啟用快速模式的請求會讀取整個對話歷史記錄而沒有快取命中。Claude Code 在回合開始時設定該標頭一次，並為整個回合保留它，因此當您在 Claude 工作時開啟快速模式時，標頭的快取遺漏會在您下一個回合的第一個請求時發生。這些未快取的輸入令牌按[快速模式費率](/docs/zh-TW/fast-mode#understand-the-cost-tradeoff)計費，這就是為什麼在工作階段開始時開啟它的成本比在長工作階段深處開啟它的成本要低。如果您目前的模型不支援快速模式，啟用快速模式也會[切換您的模型](#switching-models)，該切換本身會從執行回合中的下一個請求開始啟動新的快取。

95 118

96成本每個對話應用一次。在第一個快速模式轉換之後，Claude Code 會繼續發送標頭，並且只改變請求的速度設定，這不是快取鍵的一部分。關閉快速模式、[在速率限制後自動回退到標準速度](/docs/zh-TW/fast-mode#handle-rate-limits)，以及稍後重新開啟它都會保持快取。`/clear` 和 `/compact` 會重設此設定，因為它們無論如何都會在這些點重新建立快取。119成本每個對話應用一次。在第一個快速模式回合之後，Claude Code 會繼續傳送標頭，並且僅改變請求的速度設定，這不是快取金鑰的一部分。關閉快速模式、[達到速率限制後自動回退到標準速度](/docs/zh-TW/fast-mode#handle-rate-limits)以及稍後重新開啟都會保留快取。如果您[在工作階段中途用完使用額度](/docs/zh-TW/fast-mode#handle-rate-limits)，Claude Code 會以相同方式在標準速度下重試每個被拒絕的快速模式請求，因此此回退也會保留快取。`/clear` 和 `/compact` 會重設此設定，因為它們無論如何都會在這些點重建快取。

97 120

98<h3 id="connecting-or-disconnecting-an-mcp-server">121<h3 id="connecting-or-disconnecting-an-mcp-server">

99 連接或斷開 MCP 伺服器122 連接或斷開 MCP 伺服器

100</h3>123</h3>

101 124

102工具定義位於系統提示層中，因此當請求之間的工具定義集合變更時，快取會失效。切換[顧問工具](/docs/zh-TW/advisor)是例外：其定義位於快取中斷點之後，因此啟用或停用 `/advisor` 會保持快取的前綴完整。[MCP 伺服器](/docs/zh-TW/mcp)變更是否執行此操作取決於其工具是否由[工具搜尋](/docs/zh-TW/mcp#scale-with-mcp-tool-search)延遲或載入到前綴中：125工具定義位於系統提示層，因此當請求中的工具定義集合在回合之間變更時，快取會失效。切換[顧問工具](/docs/zh-TW/advisor)是一個例外：其定義位於快取中斷點之後，因此啟用或停用 `/advisor` 會保留快取的前綴完整。[MCP 伺服器](/docs/zh-TW/mcp)變更是否執行此操作取決於其工具是否由[工具搜尋](/docs/zh-TW/mcp#scale-with-mcp-tool-search)延遲或載入到前綴中：

103 126

104* **延遲工具**，在支援的模型上為預設值：伺服器連接、斷開連接或變更其工具列表只會附加新內容，不會擾亂已快取的任何內容。127* **延遲工具**，在支援的模型上為預設值：伺服器連接、斷開或變更其工具清單只會附加新內容，不會擾亂已快取的任何內容。

105* **載入到前綴中的工具**：對它們的任何變更都會使快取失效。這發生在[工具搜尋不可用或已停用](/docs/zh-TW/mcp#configure-tool-search)時，例如在 Google Cloud 的 Agent Platform 上或使用自訂 `ANTHROPIC_BASE_URL` 閘道時。它也發生在標記為 [`alwaysLoad`](/docs/zh-TW/mcp#exempt-a-server-from-deferral) 的伺服器或工具上，以及由[基於閾值的載入](/docs/zh-TW/mcp#configure-tool-search)保持在前面的定義上。128* **載入到前綴中的工具**：對它們的任何變更都會使快取失效。這發生在[工具搜尋不可用或已停用](/docs/zh-TW/mcp#configure-tool-search)時，例如在早於 Claude 4.5 世代的 Google Cloud Agent Platform 模型上、使用自訂 `ANTHROPIC_BASE_URL` 閘道或在 Microsoft Foundry [部署在 Azure 上](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)一旦 Claude Code 偵測到部署拒絕工具搜尋時。它也發生在標記為 [`alwaysLoad`](/docs/zh-TW/mcp#exempt-a-server-from-deferral) 的伺服器或工具上，以及由[基於閾值的載入](/docs/zh-TW/mcp#configure-tool-search)保留在前面的定義上。

106 129

107當工具載入到前綴中時，失效的最常見原因是伺服器在會話中期連接或斷開連接，這可能在沒有您採取任何操作的情況下發生：stdio 伺服器的進程退出、HTTP 會話過期，或伺服器[在暫時性故障後自動重新連接](/docs/zh-TW/mcp#automatic-reconnection)。連接的伺服器也可以推送[動態工具更新](/docs/zh-TW/mcp#dynamic-tool-updates)來變更其工具列表。130當工具載入到前綴中時，失效最常見的原因是伺服器在工作階段中途連接或斷開，這可能在沒有您採取任何動作的情況下發生：stdio 伺服器的程序退出、HTTP 工作階段過期或伺服器[在暫時性故障後自動重新連接](/docs/zh-TW/mcp#automatic-reconnection)。連接的伺服器也可以推送[動態工具更新](/docs/zh-TW/mcp#dynamic-tool-updates)來變更其工具清單。

108 131

109編輯您的 MCP 配置本身不會變更快取。新配置只有在重新啟動後才會生效，這是伺服器連接或斷開連接的時候。132編輯您的 MCP 設定本身不會變更快取。新設定只有在重新啟動後才會生效，這是伺服器連接或斷開的時候。

110 133

111<h3 id="enabling-or-disabling-a-plugin">134<h3 id="enabling-or-disabling-a-plugin">

112 啟用或停用外掛程式135 啟用或停用外掛程式

113</h3>136</h3>

114 137

115[外掛程式](/docs/zh-TW/plugins)捆綁多個元件類型，變更的成本取決於外掛程式提供的元件。Skills、commands、agents、hooks、LSP 伺服器、monitors 和 themes 永遠不會使快取失效：它們添加到請求的任何內容都會附加在現有對話之後，因此下一個請求為新內容付費，但仍然從快取中讀取它之前的所有內容。138當您啟用或停用[外掛程式](/docs/zh-TW/plugins)時，變更的成本取決於外掛程式提供的元件類型。下面的案例涵蓋每個元件類型、Claude Code 何時套用變更，以及在同一工作階段中再次停用外掛程式時會發生什麼。

139

140<h4 id="plugin-components-that-keep-the-cache">

141 保留快取的外掛程式元件

142</h4>

143

144Claude Code 永遠不會使外掛程式的技能、命令、代理、hooks、監視器或主題的快取失效。它會在現有對話之後附加其內容，因此下一個請求會為該內容付費，並且仍然會從快取中讀取其之前的所有內容。

145

146<h4 id="plugins-that-provide-mcp-servers">

147 提供 MCP 伺服器的外掛程式

148</h4>

116 149

117例外是提供 [MCP 伺服器](/docs/zh-TW/plugins-reference#mcp-servers)的外掛程式。啟用或停用一個遵循與[連接或斷開 MCP 伺服器](#connecting-or-disconnecting-an-mcp-server)相同的規則：當伺服器的工具被延遲時快取會保留，當它們載入到前綴中時下一個請求會重新讀取整個對話。150當您啟用或停用提供 [MCP 伺服器](/docs/zh-TW/plugins-reference#mcp-servers) 的外掛程式時，Claude Code 會遵循與[連接或斷開 MCP 伺服器](#connecting-or-disconnecting-an-mcp-server)相同的規則：

118 151

119外掛程式變更在您運行 [`/reload-plugins`](/docs/zh-TW/discover-plugins#apply-plugin-changes-without-restarting) 或啟動新會話時應用。成本（無論是附加公告還是完整重新讀取）會在重新載入後的第一個轉換時顯示，而不是在您運行 `/plugin install`、`/plugin enable` 或 `/plugin disable` 時。自 v2.1.163 起，當重新載入會觸發完整重新讀取時，`/reload-plugins` 會顯示警告並不應用重新載入。傳遞 `--force` 以強制應用。152* 如果 Claude Code 延遲伺服器的工具，它會保留快取。

153* 如果 Claude Code 將它們載入到前綴中，下一個請求會重新讀取整個對話。

120 154

121停用您在會話中較早啟用的外掛程式會恢復先前的請求形狀。如果該前綴仍在其[快取生命週期](#cache-lifetime)內，下一個請求會讀取較舊的快取項目，而不是重新建立。155<h4 id="code-intelligence-plugins">

156 程式碼智慧外掛程式

157</h4>

158

159當您啟用[程式碼智慧外掛程式](/docs/zh-TW/discover-plugins#code-intelligence)時，Claude 會取得 [LSP 工具](/docs/zh-TW/tools-reference#lsp-tool-behavior)。

160

161<h4 id="when-plugin-changes-apply">

162 外掛程式變更何時套用

163</h4>

164

165您在 `/plugin` 功能表中所做的變更會通過 [`/reload-plugins`](/docs/zh-TW/discover-plugins#apply-plugin-changes-without-restarting) 進行，Claude Code 會在您關閉功能表時為您執行。您會支付成本，無論是附加的公告還是完整重新讀取，都是在變更套用後的第一個回合。Claude Code 也可以自行套用變更：

166

167* 對於具有 `command` 來源的外掛程式，Claude Code [可以自行重新載入外掛程式](/docs/zh-TW/plugin-marketplaces#when-claude-code-re-runs-the-command)。

168* 當您[從 `/plugin` 介面安裝外掛程式](/docs/zh-TW/discover-plugins#install-plugins)時，Claude Code 可以在安裝期間啟動它。安裝摘要會告訴您它是否執行了此操作。

169* 當您在 v2.1.246 或更新版本上使用 `/cd` [移動工作階段](/docs/zh-TW/permissions#move-the-session-to-another-directory)時，Claude Code 會在移動過程中套用新目錄的設定啟用的外掛程式，而不會出現保留 `/reload-plugins` 的完整重新讀取警告。

170* 在互動式工作階段中，當您在使用 `--plugin-dir` 傳遞的[外掛程式資料夾](/docs/zh-TW/plugins#test-your-plugins-locally)中新增或移除外掛程式時，變更會立即套用。如果套用它會觸發完整重新讀取，Claude Code 會改為保留變更並顯示通知以執行 `/reload-plugins`。需要 Claude Code v2.1.265 或更新版本。

171

172當 `/reload-plugins` 執行且重新載入會觸發完整重新讀取時，Claude Code 會顯示警告且不套用重新載入。執行 `/reload-plugins --force` 以無論如何套用它。

173

174`/reload-plugins` 也在沒有互動式終端的工作階段中執行，例如桌面應用程式、Agent SDK 和[非互動式模式](/docs/zh-TW/headless)搭配 `-p`，當您直接將其輸入工作階段時。需要 Claude Code v2.1.260 或更新版本。

175

176在這些工作階段中，重新載入會套用除了外掛程式 MCP 伺服器變更之外的所有內容，這些變更[在您的下一個工作階段中生效](/docs/zh-TW/discover-plugins#apply-plugin-changes-without-restarting)，因此永遠不會在工作階段中途造成完整重新讀取的成本。

177

178<h4 id="plugins-you-enable-and-then-disable-in-one-session">

179 您在一個工作階段中啟用然後停用的外掛程式

180</h4>

181

182當您停用您在工作階段中較早啟用的外掛程式時，Claude Code 會還原先前的請求形狀。如果該前綴仍在其[快取生命週期](#cache-lifetime)內，下一個請求會讀取較舊的快取項目，而不是重建。

122 183

123<h3 id="denying-an-entire-tool">184<h3 id="denying-an-entire-tool">

124 拒絕整個工具185 拒絕整個工具

125</h3>186</h3>

126 187

127添加裸工具名稱（如 `Bash` 或 `WebFetch`）作為[拒絕規則](/docs/zh-TW/permissions#manage-permissions)會將該工具從 Claude 的上下文中完全移除。內建工具定義載入到系統提示層中，因此在會話中期添加或移除其中一個規則會使快取失效。無論您通過 `/permissions` 添加它還是通過[直接編輯設定檔](/docs/zh-TW/settings#when-edits-take-effect)，變更都會在下一個轉換時生效。188新增裸工具名稱（如 `Bash` 或 `WebFetch`）作為[拒絕規則](/docs/zh-TW/permissions#manage-permissions)會將該工具從 Claude 的內容中完全移除。Claude Code 將內建工具定義載入到系統提示層，因此在工作階段中途新增或移除其中一個規則會使快取失效。Claude Code 會在下一個請求時套用變更，無論您是通過 `/permissions` 新增規則還是通過[直接編輯設定檔](/docs/zh-TW/settings#when-edits-take-effect)。這包括您在回合中途通過 `/permissions` 新增的規則。

128 189

129只有裸工具名稱、等效的 `Bash(*)` 形式或[工具名稱 glob](/docs/zh-TW/permissions#tool-name-wildcards)（如 `"*"`）才有此效果。匹配只有 MCP 工具的 glob（例如 `"mcp__*"`）會以相同方式移除這些工具，但當匹配的工具被[延遲](#connecting-or-disconnecting-an-mcp-server)時（預設值）會保持快取完整，因為延遲定義從未在快取的前綴中。作用域拒絕規則（如 `Bash(rm *)`）以及所有允許和詢問規則都不會改變 Claude 看到的工具。Claude Code 在 Claude 嘗試呼叫時檢查它們，保持前綴完整。190只有在工具名稱位置相符的拒絕規則才有此效果：裸工具名稱、等效的 `Bash(*)` 形式或[工具名稱 glob](/docs/zh-TW/permissions#tool-name-wildcards)（如 `"*"`）。與只有 MCP 工具相符的 glob（如 `"mcp__*"`）會以相同方式移除這些工具，但當相符的工具[延遲](#connecting-or-disconnecting-an-mcp-server)（預設值）時會保留快取，因為延遲定義從未在快取的前綴中。範圍拒絕規則（如 `Bash(rm *)`）以及所有允許和詢問規則都不會變更 Claude 看到的工具。Claude Code 在 Claude 嘗試呼叫時檢查它們，保留前綴完整。

130 191

131<h3 id="compacting-the-conversation">192<h3 id="compacting-the-conversation">

132 壓縮對話193 壓縮對話

133</h3>194</h3>

134 195

135[壓縮](/docs/zh-TW/context-window#what-survives-compaction)用摘要替換您的訊息歷史記錄。根據設計，這會使對話層失效，因為下一個請求有一個新的、更短的歷史記錄，不與舊的共享前綴。Claude Code 重複使用系統提示層並從磁碟重新載入專案上下文，只有在 CLAUDE.md 和記憶自會話開始以來未變更時才快取命中。196[壓縮](/docs/zh-TW/context-window#what-survives-compaction)會用摘要取代您的訊息歷史記錄。根據設計，這會使對話層失效，因為下一個請求具有新的、較短的歷史記錄，不與舊歷史記錄共享前綴。Claude Code 會重複使用系統提示層，除非對話是[在保留會以其他方式變更的系統提示的同時繼續](#resuming-a-session)；在這種情況下，第一次壓縮會切換到目前提示，該層會重建一次。它會從磁碟重新載入專案內容，只有在工作階段開始以來 CLAUDE.md 和記憶未變更時才會快取命中。

197

198為了產生摘要，Claude Code 會傳送一個單獨的請求，其中包含與您的對話相同的系統提示、工具和歷史記錄，加上作為最終使用者訊息附加的摘要指令。當快取溫暖時，該請求會從快取讀取您的前綴，因此工作階段中途的 `/compact` 成本是內容大小建議的一小部分，並且大部分時間花在產生摘要上。

136 199

137為了生成摘要，Claude Code 發送一個一次性請求，其系統提示、工具和歷史記錄與您的對話相同，加上作為最終使用者訊息附加的摘要指令。因為它共享您的前綴，該請求讀取現有快取而不是重新處理完整歷史記錄。壓縮的大部分時間用於生成摘要，而不是快取未命中。隨後的轉換只為更短的摘要重新建立對話快取，因此壓縮後的轉換不是緩慢的部分。200在超過[快取生命週期](#cache-lifetime)的中斷後，沒有快取可讀取，因此摘要請求會將完整歷史記錄重新處理為未快取的輸入。這就是為什麼當您[繼續舊工作階段](/docs/zh-TW/sessions#resume-from-a-summary)時 `/compact` 成本最高。在溫暖和冷的情況下，壓縮後的回合只會為更短的摘要重建對話快取，因此該回合不是較慢的部分。

138 201

139<Tip>202<Tip>

140 當您丟棄的上下文是您不再需要的內容時，壓縮對您有利。為了選擇其開銷何時發生，在工作中的自然中斷處（例如任務之間）運行 `/compact`，而不是等待自動壓縮在任務中期觸發。如果您走上了一條想要完全放棄的路徑，請改為[`/rewind`](#rewinding-the-conversation)到較早的轉換。重新開始會截斷回到已經快取的前綴，而不是像壓縮那樣建立新的。203 當您捨棄的內容是您不再需要的內容時，壓縮對您有利。為了選擇其開銷何時發生，請在工作的自然中斷處（例如任務之間）執行 `/compact`，而不是等待自動壓縮在任務中途觸發。如果您走上了想要完全放棄的路徑，請改為[`/rewind`](#rewinding-the-conversation)到較早的回合。重新開始會截斷回到已快取的前綴，而不是像壓縮那樣建立新的前綴。

141</Tip>204</Tip>

142 205

206<h3 id="accumulating-many-images">

207 累積許多影像

208</h3>

209

210API 限制每個請求可以攜帶多少影像和 PDF。如需目前的數字，請參閱 API 文件中的[請求限制](https://platform.claude.com/docs/en/build-with-claude/vision#request-limits)。Claude Code 也會限制請求中影像和 PDF 的總大小，因此大型螢幕擷取畫面會以比小型螢幕擷取畫面更少的影像數量達到限制。

211

212當下一個請求會超過任一限制時，Claude Code 會從其傳送的內容中移除一批最舊的影像和 PDF，這會為更多內容騰出空間，然後才需要再次移除任何內容。Claude 無法再看到移除的影像。如果 Claude 稍後需要其中一個，請再次共享它。

213

214移除影像會變更保存它們的訊息，因此下一個請求會從這些訊息中最早的訊息開始重新處理對話。因為 Claude Code 一次移除一批，您會看到每批一個較慢的回合，而不是每個新螢幕擷取畫面一個。

215

143<h3 id="upgrading-claude-code">216<h3 id="upgrading-claude-code">

144 升級 Claude Code217 升級 Claude Code

145</h3>218</h3>

146 219

147新的 Claude Code 版本通常會更新系統提示或工具定義，因此升級後的第一個請求會從頂部重新建立快取。[自動更新](/docs/zh-TW/setup#auto-updates)在後台下載新版本，但在下次啟動時應用它們，從不在會話中期，因此您會看到這是重新啟動後的未快取第一個轉換，而不是會話期間的驚喜。設定 `DISABLE_AUTOUPDATER=1` 以控制何時應用升級。220新的 Claude Code 版本通常會更新系統提示或工具定義，因此您在升級後開始的第一個對話會從頭開始建立其快取。[自動更新](/docs/zh-TW/setup#auto-updates)會在背景下載新版本，但在下一次啟動時套用它們，永遠不會在工作階段中途，因此您會看到這是重新啟動後的未快取第一個回合，而不是工作階段期間的驚喜。設定 `DISABLE_AUTOUPDATER=1` 以控制何時套用升級。

148 221

149<Note>222<Note>

150 在升級後[恢復會話](/docs/zh-TW/sessions#resume-a-session)會重新處理整個對話歷史記錄而沒有快取命中，因為歷史記錄現在位於不同的系統提示後面。成本隨著恢復的對話有多長而擴展，因此回到長會話的第一個轉換可能是您發送的最昂貴的請求。223 如需繼續您在升級前開始的對話的成本，請參閱[繼續工作階段](#resuming-a-session)。

151</Note>224</Note>

152 225

153<h2 id="actions-that-keep-the-cache">226<h2 id="actions-that-keep-the-cache">

154 保留快取的操作227 保留快取的動作

155</h2>228</h2>

156 229

157這些操作要麼附加到對話的末尾，要麼根本不觸及請求。其中一些，例如編輯 CLAUDE.md 或變更輸出風格，也是為什麼設定變更需要等待重新啟動才能應用的原因。230這些動作要麼附加到對話的末尾，要麼根本不觸及請求。其中一些動作（例如編輯 CLAUDE.md）保留快取的原因與變更在執行中的工作階段中不會生效直到 `/clear`、`/compact` 或重新啟動的原因相同。

158 231

159* [編輯您的儲存庫中的檔案](#editing-files-in-your-repository)232* [編輯您的儲存庫中的檔案](#editing-files-in-your-repository)

160* [在會話中期編輯 CLAUDE.md](#editing-claude-md-mid-session)233* [在工作階段中編輯 CLAUDE.md](#editing-claude-md-mid-session)

161* [變更輸出風格](#changing-output-style)

162* [變更權限模式](#changing-permission-mode)234* [變更權限模式](#changing-permission-mode)

163* [調用技能和命令](#invoking-skills-and-commands)235* [變更輸出樣式](#changing-output-style)

164* [運行 `/recap`](#running-%2Frecap)236* [叫用技能和命令](#invoking-skills-and-commands)

165* [重新開始對話](#rewinding-the-conversation)237* [執行 `/recap`](#running-%2Frecap)

238* [倒帶對話](#rewinding-the-conversation)

166* [生成子代理](#subagents-and-the-cache)239* [生成子代理](#subagents-and-the-cache)

167 240

168<h3 id="editing-files-in-your-repository">241<h3 id="editing-files-in-your-repository">

169 編輯您的儲存庫中的檔案242 編輯您的儲存庫中的檔案

170</h3>243</h3>

171 244

172檔案內容只有在 Claude 讀取它們時才進入上下文，讀取會附加到對話。編輯 Claude 之前讀過的檔案不會追溯變更歷史記錄中的較早讀取。相反，Claude Code 附加一個 `<system-reminder>` 注意到檔案已變更，如果需要，Claude 會重新讀取它。245檔案內容只有在 Claude 讀取時才會進入上下文，而讀取會附加到對話中。編輯 Claude 之前讀過的檔案不會追溯性地改變歷史記錄中的早期讀取。相反，Claude Code 會附加一個 `<system-reminder>` 注意到檔案已變更，如果需要，Claude 會重新讀取它。

173 246

174<h3 id="editing-claude-md-mid-session">247<h3 id="editing-claude-md-mid-session">

175 在會話中期編輯 CLAUDE.md248 在工作階段中編輯 CLAUDE.md

176</h3>249</h3>

177 250

178您的專案根目錄和使用者級別 CLAUDE.md 檔案在會話開始時讀取一次並保存在記憶中。在會話中期編輯它們不會使快取失效，但編輯也不會應用。Claude 繼續使用在會話開始時加載的版本。新內容在下一個 `/clear`、`/compact` 或重新啟動時加載。251您的專案根目錄和使用者層級 CLAUDE.md 檔案在工作階段開始時讀取一次並保存在記憶體中。在工作階段中編輯它們不會使快取失效，但編輯也不會應用。Claude 繼續使用在工作階段開始時載入的版本。新內容在下一次 `/clear`、`/compact` 或重新啟動時載入。

179 252

180[子目錄中的嵌套 CLAUDE.md 檔案](/docs/zh-TW/memory)和[帶有 `paths:` frontmatter 的規則](/docs/zh-TW/memory#path-specific-rules)稍後加載，當 Claude 首次讀取匹配檔案時。在它加載之前編輯一個確實會生效。加載後，內容是對話歷史記錄的一部分，因此會話中期的編輯不會追溯變更它。253[子目錄中的巢狀 CLAUDE.md 檔案](/docs/zh-TW/memory)和[具有 `paths:` frontmatter 的規則](/docs/zh-TW/memory#path-specific-rules)稍後載入，當 Claude 首次讀取匹配的檔案時。在它載入之前編輯它確實會生效。載入後，內容是對話歷史記錄的一部分，因此在工作階段中編輯不會追溯性地改變它。

181 254

182<h3 id="changing-output-style">255<h3 id="changing-permission-mode">

183 變更輸出風格256 變更權限模式

184</h3>257</h3>

185 258

186[輸出風格](/docs/zh-TW/output-styles)是系統提示的一部分，Claude Code 在會話開始時讀取一次。通過 `/config` 或 `outputStyle` 設定在會話中期變更它不會使快取失效，但變更也不會應用。Claude 繼續使用在會話開始時加載的風格。新風格在下一個 `/clear` 或重新啟動時加載。259在[權限模式](/docs/zh-TW/permission-modes)之間切換，例如從手動切換到接受編輯，不會改變系統提示或工具定義，因此模式變更是快取安全的。例外是使用 [`opusplan`](/docs/zh-TW/model-config#opusplan-model-setting) 模型設定的計畫模式，它在您進入或離開計畫模式時在 Opus 和 Sonnet 之間切換模型。這使得模式切換成為[模型切換](#switching-models)。

187 260

188<h3 id="changing-permission-mode">261<h3 id="changing-output-style">

189 變更權限模式262 變更輸出樣式

190</h3>263</h3>

191 264

192在[權限模式](/docs/zh-TW/permission-modes)之間切換，例如從預設切換到接受編輯，不會變更系統提示或工具定義，因此模式變更是快取安全的。例外是使用 [`opusplan`](/docs/zh-TW/model-config#opusplan-model-setting) 模型設定的 Plan Mode，它在進入或離開 Plan Mode 時在 Opus 和 Sonnet 之間切換模型。這使模式切換成為[模型切換](#switching-models)。265當您在工作階段中使用 `/config` 或 `outputStyle` 設定切換[輸出樣式](/docs/zh-TW/output-styles)時，Claude 從您的下一條訊息開始使用新樣式。Claude Code 將新樣式的指示作為對話中的訊息傳遞，因此該請求仍然從快取中讀取系統提示和較早的對話。

266

267在 v2.1.251 之前，在工作階段中切換樣式會保留快取，但在您執行 `/clear` 或開始新工作階段之前不會應用。

193 268

194<h3 id="invoking-skills-and-commands">269<h3 id="invoking-skills-and-commands">

195 調用技能和命令270 叫用技能和命令

196</h3>271</h3>

197 272

198[技能](/docs/zh-TW/skills)和[命令](/docs/zh-TW/commands)在調用點將其指令注入為使用者訊息。對話中較早的任何內容都不會變更。273[技能](/docs/zh-TW/skills)和[命令](/docs/zh-TW/commands)在叫用點將其指示作為使用者訊息注入。對話中較早的任何內容都不會改變。frontmatter 命名 `model` 的技能或命令可以是該輪的[模型切換](#switching-models)。

199 274

200<h3 id="running-/recap">275<h3 id="running-/recap">

201 運行 `/recap`276 執行 `/recap`

202</h3>277</h3>

203 278

204[`/recap`](/docs/zh-TW/interactive-mode#session-recap) 生成一個摘要以在您的終端中顯示。與 `/compact` 不同，它將摘要附加為命令輸出而不是替換您的訊息歷史記錄，因此快取的前綴保持完整。279[`/recap`](/docs/zh-TW/interactive-mode#session-recap) 生成一個摘要以在您的終端中顯示。與 `/compact` 不同，它將摘要附加為命令輸出，而不是替換您的訊息歷史記錄，因此快取的前綴保持完整。

205 280

206<h3 id="rewinding-the-conversation">281<h3 id="rewinding-the-conversation">

207 重新開始對話282 倒帶對話

208</h3>283</h3>

209 284

210[`/rewind`](/docs/zh-TW/checkpointing) 將您的對話截斷回到較早的轉換。剩餘的歷史記錄是快取在該點建立時的相同內容，系統提示和專案上下文層未變更，因此下一個請求命中較早的快取條目。自那時以來的每個轉換都通過該前綴讀取，即使原始轉換比 TTL 更久遠，也保持條目溫暖。285[`/rewind`](/docs/zh-TW/checkpointing) 將您的對話截斷回較早的輪次。剩餘的歷史記錄是快取在該點建立時的相同內容，系統提示和專案上下文層保持不變，因此下一個請求會命中較早的快取項目。自那時以來的每一輪都已讀過該前綴，即使原始輪次比 TTL 更久遠，也保持了該項目的活躍狀態。

286

287將檔案檢查點與對話一起還原對快取沒有單獨的影響。檔案內容只有在 Claude 讀取時才會進入上下文，與[編輯您的儲存庫中的檔案](#editing-files-in-your-repository)相同。

288

289<h2 id="resuming-a-session">

290 復原工作階段

291</h2>

292

293當您[復原工作階段](/docs/zh-TW/sessions#resume-a-session)時，Claude Code 會重新傳送整個對話，而請求會從快取中讀取其前綴中未變更且仍在[快取生命週期](#cache-lifetime)內的任何部分。本頁頂部的圖層表說明每個圖層的變更內容。

211 294

212恢復檔案檢查點與對話一起對快取沒有單獨的影響。檔案內容只有在 Claude 讀取它們時才進入上下文，與[編輯您的儲存庫中的檔案](#editing-files-in-your-repository)相同。295系統提示會在[Claude Code 升級](#upgrading-claude-code)後或在復原時使用不同的[`--append-system-prompt`](/docs/zh-TW/cli-reference#system-prompt-flags)文字時變更。根據預設，復原的對話會保留其開始時的系統提示，因此其歷史記錄仍位於相同提示後面，變更會在對話壓縮或新對話中生效。[復原對話中的系統提示旗標](/docs/zh-TW/cli-reference#system-prompt-flags-in-resumed-conversations)涵蓋 `--system-prompt-snapshot off` 和裸模式，其中此規則不適用。

213 296

214<h2 id="cache-lifetime">297<h2 id="cache-lifetime">

215 快取生命週期298 快取生命週期

216</h2>299</h2>

217 300

218快取的前綴在一段時間不活動後過期。每個命中快取的請求都會重置計時器，因此只要您繼續工作，快取就會保持溫暖。在足夠長的間隙之後，下一個請求會重新計算完整輸入並重新建立快取，這就是為什麼在步開後回來的第一個轉換可能會明顯變慢。301快取的前綴在一段時間的不活動後會過期。每個命中快取的請求都會重置計時器，因此只要您持續工作，快取就會保持溫暖。經過足夠長的間隔後，下一個請求會重新計算完整輸入並重新建立快取，這就是為什麼在離開後回來的第一個轉向可能會明顯變慢。

219 302

220生存時間 (TTL) 控制快取存活的間隙有多長。API 提供兩個：五分鐘 TTL 和[一小時 TTL](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-caching#1-hour-cache-duration)，它通過更長的中斷保持快取溫暖，但[以更高的速率計費快取寫入](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-caching#pricing)。Claude Code 根據您如何進行身份驗證為您選擇 TTL，您可以使用環境變數覆蓋它。303在 Pro 或 Max 方案上，當您在長時間中斷後恢復大型工作階段時，Claude Code [提供從摘要恢復](/docs/zh-TW/sessions#resume-from-a-summary)，以便後續請求不會攜帶完整歷史記錄。

221 304

222<h3 id="on-a-claude-subscription">305生存時間 (TTL) 控制快取存活的間隔長度。API 提供兩種：五分鐘 TTL 和[一小時 TTL](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration)，後者可在較長的中斷期間保持快取溫暖，但[以更高的速率計費快取寫入](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing)。較長的 TTL 在您讓工作階段閒置並返回時很有幫助，因為您可以跳過過期前綴所需的重新處理。對於從不閒置超過五分鐘的短工作突發，成本更高，因為更高的寫入速率適用，而較長的快取生命週期未被使用。

223 在 Claude 訂閱上306

307<h3 id="which-ttl-each-request-gets">

308 每個請求獲得的 TTL

224</h3>309</h3>

225 310

226在 Claude 訂閱上，Claude Code 自動請求一小時 TTL。使用量包含在您的計畫中，而不是按令牌計費，因此更長的 TTL 對您沒有額外成本，只會影響快取保持溫暖的時間。311Claude Code 按請求決定 TTL，每個請求都屬於以下兩個固定桶之一：

227 312

228如果您已超過計畫的使用量限制，Claude Code 正在使用[使用額度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)，您將被計費該使用量，因此 Claude Code 會自動將 TTL 降低到五分鐘。313* **主要對話**：您的互動式轉向、非互動式 `-p` 執行和 Agent SDK 轉向，加上 Claude Code 與它們內聯執行的幫助程式

314* **其他所有內容**：Claude Code 在該對話之外進行的請求，例如[子代理](/docs/zh-TW/sub-agents)、[工作流程](/docs/zh-TW/workflows)、進程內[隊友](/docs/zh-TW/agent-teams)、分支、壓縮和工作階段標題

229 315

230<h3 id="on-an-api-key-or-third-party-provider">316除非您自己選擇 TTL，否則 Claude Code 僅在您方案的包含使用量內的 Claude 訂閱上請求一小時 TTL。在那裡，它為主要對話請求一小時，加上 Anthropic 在伺服器端控制的一小組幫助程式請求。此表格提供兩種計費方式下每個桶的預設 TTL。

231 在 API 金鑰或第三方提供商上

232</h3>

233 317

234在 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`。318| 請求桶 | Claude 訂閱，在方案使用量內 | 使用額度、API 金鑰或雲端提供者 |

319| ------ | --------------------------- | ----------------- |

320| 主要對話 | 一小時 | 五分鐘 |

321| 其他所有內容 | 五分鐘，除了伺服器控制的幫助程式請求外，它們獲得一小時 | 五分鐘 |

235 322

236在 Amazon Bedrock 上，prompt caching 支援、最小可快取前綴長度和一小時 TTL 可用性都因模型而異。如果快取令牌計數保持為零，請檢查 Amazon Bedrock 文件中的[支援的模型、區域和限制](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html#prompt-caching-models)。323一旦您超過方案的使用量限制，Claude Code 會使用[使用額度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)，您將為該使用量計費，因此 Claude Code 會將主要對話降低到更便宜的五分鐘 TTL。要在那裡保持一小時 TTL，[自己選擇 TTL](#choose-the-ttl-yourself)。

237 324

238<h3 id="override-the-ttl">325<h3 id="choose-the-ttl-yourself">

239 覆蓋 TTL326 自己選擇 TTL

240</h3>327</h3>

241 328

242設定 `FORCE_PROMPT_CACHING_5M=1` 以強制五分鐘 TTL，無論身份驗證如何。當您調試快取行為、比較兩個 TTL 或覆蓋在[受管設定](/docs/zh-TW/settings#settings-files)中設定的 `ENABLE_PROMPT_CACHING_1H` 時，這很有用。329您可以為任一桶設定 TTL。每個控制項採用 `5m` 或 `1h`，Claude Code 會忽略任何其他值。

330

331* **主要對話**：[`promptCacheTtl`](/docs/zh-TW/settings-reference#promptcachettl) 設定，或 `CLAUDE_CODE_PROMPT_CACHE_TTL` [環境變數](/docs/zh-TW/env-vars)

332* **其他所有內容**：[`subagentPromptCacheTtl`](/docs/zh-TW/settings-reference#subagentpromptcachettl) 設定，或 `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL` 環境變數

333

334兩個設定和兩個環境變數都需要 Claude Code v2.1.242 或更新版本。如果您使用 API 金鑰登入或使用雲端提供者，請將 `promptCacheTtl` 設定為 `1h` 以為主要對話提供一小時快取。其外的請求保持五分鐘預設值，直到您也為該桶選擇 TTL。

335

336當多個控制項適用時，Claude Code 按此順序採用第一個匹配項：

337

3381. `FORCE_PROMPT_CACHING_5M=1`，為兩個桶強制五分鐘

3392. 桶的環境變數

3403. 桶的設定

3414. 對於子代理的請求，子代理的 [`experimental` frontmatter 欄位](/docs/zh-TW/sub-agents#supported-frontmatter-fields)中的 `cacheTtl` 值，需要 Claude Code v2.1.248 或更新版本。當您的 Claude 訂閱使用使用額度時，Claude Code 會忽略那裡的 `1h`

3425. `ENABLE_PROMPT_CACHING_1H=1`，為兩個桶請求一小時

3436. [請求桶的預設值](#which-ttl-each-request-gets)

344

345當您調試快取行為、比較兩個 TTL 或覆蓋在[受管設定](/docs/zh-TW/managed-settings)中設定的較長 TTL 時，設定 `FORCE_PROMPT_CACHING_5M=1`。

346

347要確認您的主要對話的快取寫入使用了哪個 TTL，請執行 `claude -p "hello" --output-format json` 並讀取結果中的 `usage.cache_creation`。Claude Code 在 `ephemeral_1h_input_tokens` 下報告一小時快取寫入，在 `ephemeral_5m_input_tokens` 下報告五分鐘快取寫入。

348

349通過您使用 `ANTHROPIC_BASE_URL` 設定的 LLM 閘道，部分一小時請求在 `anthropic-beta` 標頭中傳輸，因此請配置閘道以[原封不動地轉發該標頭](/docs/zh-TW/llm-gateway-protocol#request-headers)。一小時 TTL 不可通過[Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway#availability-and-limitations)使用。在 Amazon Bedrock 上，prompt caching 支援、最小可快取前綴長度和一小時 TTL 可用性都因模型而異。如果快取令牌計數保持為零，請檢查 Amazon Bedrock 文件中的[支援的模型、區域和限制](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html#prompt-caching-models)。

243 350

244<h2 id="cache-scope">351<h2 id="cache-scope">

245 快取範圍352 快取範圍

246</h2>353</h2>

247 354

248在 Claude Code 中，快取有效地限定在一台機器和目錄。系統提示嵌入工作目錄、平台、shell、OS 版本和自動記憶路徑，因此在不同目錄中的兩個會話建立不同的前綴並錯過彼此的快取。這包括同一儲存庫的 worktrees，因為每個 worktree 都有自己的工作目錄。355在 Claude Code 中，快取實際上是限定在一台機器和一個目錄的範圍內。每個對話都會帶有工作目錄、平台、shell 和作業系統版本，系統提示會命名您的自動記憶路徑，因此在不同目錄中的兩個工作階段會建立不同的前綴並且會錯過彼此的快取。這包括同一個儲存庫的 worktrees，因為每個 worktree 都有自己的工作目錄。

249 356

250您在同一目錄中並行運行的會話建立匹配的前綴並讀取彼此的快取。順序會話只有在啟動時的 git 狀態快照匹配時才共享前綴，因為系統提示也捕獲分支和最近的提交。357您在同一目錄中並行執行的工作階段會建立相符的前綴並讀取彼此的快取。順序工作階段只有在啟動時取得的 git 狀態快照相符時才會共享前綴，因為每個對話也會帶有該快照中的分支和最近的提交。

251 358

252基礎 API 快取更廣泛。快取在組織之間隔離，在某些提供商上，[在組織內的工作區之間隔離](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-caching#cache-storage-and-sharing)。在這些邊界內，任何兩個具有相同模型和前綴的請求讀取相同的快取。對於運行自動化流程艦隊的 Agent SDK 呼叫者，請參閱[改進跨使用者和機器的 prompt caching](/docs/zh-TW/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines)以抑制系統提示的按機器部分並跨機器共享快取。359底層 API 快取的範圍更廣。快取在組織之間是隔離的，在某些提供者上，[在組織內的工作區之間隔離](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#cache-storage-and-sharing)。在這些邊界內，任何兩個具有相同模型和前綴的請求都會讀取相同的快取。對於執行自動化程序群隊的 Agent SDK 呼叫者，請參閱[改善跨使用者和機器的提示快取](/docs/zh-TW/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines)以抑制系統提示的每台機器部分並在機器之間共享快取。

253 360

254<h2 id="check-cache-performance">361<h2 id="check-cache-performance">

255 檢查快取效能362 檢查快取效能

256</h2>363</h2>

257 364

258快取效能顯示為 API 在每個回應上報告的兩個令牌計數。最直接的方式是觀看它們實時是[狀態行指令碼](/docs/zh-TW/statusline)，它讀取 `current_usage` 物件：365快取效能會在 API 對每個回應報告的兩個權杖計數中顯示。最直接的方式是使用[狀態列指令碼](/docs/zh-TW/statusline)來監看 `current_usage` 物件：

366

367| 欄位 | 意義 |

368| ----------------------------- | ----------------------------- |

369| `cache_creation_input_tokens` | 在此輪次寫入快取的權杖，按快取寫入費率計費 |

370| `cache_read_input_tokens` | 在此輪次從快取提供的權杖，按標準輸入費率的約 10% 計費 |

259 371

260| 欄位 | 含義 |372高讀取與建立比率表示快取運作良好。如果建立在輪次之間保持高位，表示您的前綴中有所變更。[使快取失效的動作](#actions-that-invalidate-the-cache)章節列出常見原因。

261| ----------------------------- | ------------------------------- |

262| `cache_creation_input_tokens` | 在此轉換上寫入快取的令牌，按快取寫入速率計費 |

263| `cache_read_input_tokens` | 在此轉換上從快取提供的令牌，按標準輸入速率的大約 10% 計費 |

264 373

265高讀取與建立比率意味著快取工作良好。如果建立在轉換之間保持高位，您的前綴中有些東西在變更。[使快取失效的操作](#actions-that-invalidate-the-cache)部分列出了常見原因。374如需每個工作階段的摘要，請執行 `/usage`。在主要對話的第一個回應之後，Claude Code 會在工作階段區塊中新增[`Prompt cache (main)` 行](/docs/zh-TW/costs#prompt-cache-statistics)，顯示工作階段的命中率、未命中計數，以及快取目前是否為熱狀態。狀態列指令碼可以從 [`prompt_cache` 物件](/docs/zh-TW/statusline#prompt-cache-fields)讀取相同的數字。兩者都需要 Claude Code v2.1.251 或更新版本。

266 375

267為了在整個組織中獲得可見性，OpenTelemetry 匯出器報告每個使用者和會話的快取讀取和建立令牌。請參閱[監控使用](/docs/zh-TW/monitoring-usage)以了解指標和事件屬性參考。376當 Claude Code 能夠識別時，`Prompt cache (main)` 行也會命名最後一次未命中的可能原因，例如 `likely cause: tool definitions changed`。可能原因文字需要 Claude Code v2.1.260 或更新版本。

377

378如需整個組織的可見性，OpenTelemetry 匯出器會報告每個使用者和工作階段的快取讀取和建立權杖。請參閱[監控使用情況](/docs/zh-TW/monitoring-usage)以取得度量和事件屬性參考。

268 379

269<h2 id="subagents-and-the-cache">380<h2 id="subagents-and-the-cache">

270 子代理和快取381 子代理與快取

271</h2>382</h2>

272 383

273[子代理](/docs/zh-TW/sub-agents)開始自己的對話，具有自己的系統提示和工具集，與父代分開。它建立自己的快取，在第一次呼叫時沒有快取命中，並在自己的轉換中預熱。子代理使用五分鐘 TTL，即使在訂閱上，因為自動一小時 TTL 適用於主對話。384[子代理](/docs/zh-TW/sub-agents)會以自己的系統提示和工具集開始新的對話，與父代理分開。它的第一個請求不會讀取父代理的快取，因為兩個前綴不同，並且它會在自己的轉換過程中預熱自己的快取。子代理位於主對話[TTL 時間桶](#which-ttl-each-request-gets)之外，因此即使在訂閱上也能獲得五分鐘，直到您[選擇更長的時間](#choose-the-ttl-yourself)。

385

386父代理的快取不受影響。從父代理的角度來看，子代理的呼叫和結果會附加到對話中，保持父代理的前綴完整。

387

388相比之下，[分支](/docs/zh-TW/sub-agents#fork-the-current-conversation)會完全繼承父代理的系統提示、工具和對話歷史，因此它的第一個請求會讀取父代理的快取。

274 389

275父代的快取不受影響。從父代的角度來看，子代理的呼叫和結果附加到對話，保留父代的前綴完整。390其他請求也可以讀取較早請求快取的前綴：

276 391

277[分支](/docs/zh-TW/sub-agents#fork-the-current-conversation)相比之下，完全繼承父代的系統提示、工具和對話歷史記錄，因此其第一個請求讀取父代的快取。[壓縮對話](#compacting-the-conversation)中描述的壓縮摘要呼叫使用相同的前綴共享方法。392* **工作階段副本**：您[使用 `/fork` 複製的工作階段](/docs/zh-TW/agent-view#copy-the-session-with-%2Ffork)會在複製的對話末尾收到其隔離指令作為訊息，因此原始對話建立的快取保持完整。

393* **壓縮**：[壓縮對話](#compacting-the-conversation)中描述的摘要化呼叫使用相同的前綴共享方法。

394* **已恢復的子代理**：當 Claude [恢復子代理](/docs/zh-TW/sub-agents#resume-subagents)時，已恢復執行的第一個請求可以讀取原始執行預熱的快取。

395* **工作流扇出**：在[工作流扇出](/docs/zh-TW/workflows#prompt-caching-in-a-fan-out)中，Claude Code 預設會將除第一個代理外的所有代理保留最多 5 秒，因此它們的第一個請求可以讀取第一個代理快取的前綴。

278 396

279<h2 id="disable-prompt-caching">397<h2 id="disable-prompt-caching">

280 禁用 prompt caching398 停用 prompt caching

281</h2>399</h2>

282 400

283禁用快取在使用特定模型或提供商調試快取行為時偶爾很有用。要關閉它，請將以下環境變數之一設定為 `1`：401在針對特定模型或提供者除錯 caching 行為時，停用 caching 偶爾會很有用。若要將其關閉，請將以下其中一個環境變數設定為 `1`：

284 402

285| 變數 | 效果 |403| 變數 | 效果 |

286| ------------------------------- | ------------ |404| ------------------------------- | -------------------- |

~~292~~ 410

293要在整個組織中設定快取策略，請將這些或[TTL 變數](#cache-lifetime)中的任何一個放在[受管設定](/docs/zh-TW/settings#settings-files)的 `env` 區塊中。為了正常使用，請保持快取啟用。411若要在整個組織中設定 caching 原則，請將這些變數或 [TTL 變數](#cache-lifetime) 中的任何一個放在[受管設定](/docs/zh-TW/managed-settings)的 `env` 區塊中。在正常使用時，請保持 caching 啟用。

294 412

295<h2 id="related-resources">413<h2 id="related-resources">

296 相關資源414 相關資源

quickstart.md +13 −13

Details

27 步驟 1：安裝 Claude Code27 步驟 1：安裝 Claude Code

28</h2>28</h2>

29 29

~~30To install Claude Code, use one of the following methods:~~30若要安裝 Claude Code，請使用下列其中一種方法：

31 31

32<Tabs>32<Tabs>

~~33 <Tab title="Native Install (Recommended)">~~33 <Tab title="原生安裝（建議）">

~~34 **macOS, Linux, WSL:**~~34 **macOS、Linux、WSL：**

35 35

36 ```bash theme={null}36 ```bash theme={null}

37 curl -fsSL https://claude.ai/install.sh | bash37 curl -fsSL https://claude.ai/install.sh | bash

38 ```38 ```

39 39

~~40 **Windows PowerShell:**~~40 **Windows PowerShell：**

41 41

42 ```powershell theme={null}42 ```powershell theme={null}

43 irm https://claude.ai/install.ps1 | iex43 irm https://claude.ai/install.ps1 | iex

44 ```44 ```

45 45

~~46 **Windows CMD:**~~46 **Windows CMD：**

47 47

48 ```batch theme={null}48 ```batch theme={null}

49 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd49 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

50 ```50 ```

51 51

52 If you see `The token '&&' is not a valid statement separator`, you're in PowerShell, not CMD. If you see `'irm' is not recognized as an internal or external command`, you're in CMD, not PowerShell. Your prompt shows `PS C:\` when you're in PowerShell and `C:\` without the `PS` when you're in CMD.52 如果您看到 `The token '&&' is not a valid statement separator`，表示您在 PowerShell 中，而非 CMD。如果您看到 `'irm' is not recognized as an internal or external command`，表示您在 CMD 中，而非 PowerShell。當您在 PowerShell 中時，提示符會顯示 `PS C:\`，而在 CMD 中時會顯示 `C:\`（不含 `PS`）。

53 53

54 If the install command fails with `syntax error near unexpected token '<'`, a `403`, or another curl error, see [Troubleshoot installation](/docs/en/troubleshoot-install#find-your-error) to match the error to a fix and for alternative install methods.54 如果安裝命令失敗並出現 `syntax error near unexpected token '<'`、`403` 或其他 curl 錯誤，請參閱[疑難排解安裝](/docs/zh-TW/troubleshoot-install#find-your-error)以將錯誤與修正相對應，並查看替代安裝方法。

55 55

56 [Git for Windows](https://git-scm.com/downloads/win) is recommended on native Windows so Claude Code can use the Bash tool. If Git for Windows is not installed, Claude Code uses PowerShell as the shell tool instead. WSL setups do not need Git for Windows.56 建議在原生 Windows 上安裝 [Git for Windows](https://git-scm.com/downloads/win)，以便 Claude Code 可以使用 Bash 工具。如果未安裝 Git for Windows，Claude Code 會改用 PowerShell 作為殼層工具。WSL 設定不需要 Git for Windows。

57 57

58 <Info>58 <Info>

~~59 Native installations automatically update in the background to keep you on the latest version.~~59 原生安裝會在背景自動更新，以保持您使用最新版本。

60 </Info>60 </Info>

61 </Tab>61 </Tab>

62 62

65 brew install --cask claude-code65 brew install --cask claude-code

66 ```66 ```

67 67

68 Homebrew offers two casks. `claude-code` tracks the stable release channel, which is typically about a week behind and skips releases with major regressions. `claude-code@latest` tracks the latest channel and receives new versions as soon as they ship.68 Homebrew 提供兩個 casks。`claude-code` 追蹤穩定版本通道，通常比最新版本晚約一週，並跳過有重大迴歸的版本。`claude-code@latest` 追蹤最新通道，並在新版本發佈時立即接收。

69 69

70 <Info>70 <Info>

71 Homebrew installations do not auto-update. Run `brew upgrade claude-code` or `brew upgrade claude-code@latest`, depending on which cask you installed, to get the latest features and security fixes.71 Homebrew 安裝不會自動更新。執行 `brew upgrade claude-code` 或 `brew upgrade claude-code@latest`（取決於您安裝的 cask），以取得最新功能和安全修正。

72 </Info>72 </Info>

73 </Tab>73 </Tab>

74 74

78 ```78 ```

79 79

80 <Info>80 <Info>

~~81 WinGet installations do not auto-update. Run `winget upgrade Anthropic.ClaudeCode` periodically to get the latest features and security fixes.~~81 WinGet 安裝不會自動更新。定期執行 `winget upgrade Anthropic.ClaudeCode` 以取得最新功能和安全修正。

82 </Info>82 </Info>

83 </Tab>83 </Tab>

84</Tabs>84</Tabs>

85 85

~~86You can also install with [apt, dnf, or apk](/docs/en/setup#install-with-linux-package-managers) on Debian, Fedora, RHEL, and Alpine.~~86您也可以在 Debian、Fedora、RHEL 和 Alpine 上使用 [apt、dnf 或 apk](/docs/zh-TW/setup#install-with-linux-package-managers) 進行安裝。

87 87

88若要確認安裝成功，請執行：88若要確認安裝成功，請執行：

89 89

remote-control.md +17 −13

Details

132 檢查連接狀態132 檢查連接狀態

133</h3>133</h3>

134 134

135在互動式終端機會話中，當連接啟動時，`/rc active` 指示器會位於輸入框下方的頁尾中，如果終端機太窄無法容納則會隱藏。指示器文字是 claude.ai 上會話的連結。使用向下箭頭鍵選擇它並按 Enter 鍵，或再次執行 `/remote-control`，以開啟狀態面板，其中包含會話 URL 和 QR 碼，您可以使用它從[另一個裝置連接](#connect-from-another-device)。狀態面板也提供斷開連接選項。選擇它以關閉 Remote Control；您的本地會話會繼續在終端機中執行。135在互動式終端機會話中，當連接啟動時，`/rc active` 指示器會顯示，如果終端機太窄無法容納則會隱藏。使用[全螢幕呈現](/docs/zh-TW/fullscreen)時，它位於啟動標題中的工作目錄行末尾，沒有它時，位於輸入框下方的頁尾。

136 136

137如果連接失敗，Claude Code 會顯示一個通知，說明失敗原因，並將指示器切換到保留在頁尾的失敗狀態。要再次讀取原因，使用向下箭頭鍵選擇指示器並按 Enter 鍵。要重新連接，執行 `/remote-control`，除非[原因說會話在其他地方被接管或結束，或伺服器找不到它](#session-ended-elsewhere)。137指示器文字是 claude.ai 上會話的連結。執行 `/remote-control` 再次以開啟狀態面板，其中包含會話 URL 和 QR 碼，您可以使用它從[另一個裝置連接](#connect-from-another-device)。當指示器在頁尾時，您也可以使用向下箭頭鍵選擇指示器並按 Enter 鍵以開啟面板。面板也提供斷開連接選項，可關閉 Remote Control，同時您的本地會話會繼續在終端機中執行。

138 138

139在重新連接之前讀取原因。<span id="session-ended-elsewhere" />當會話從另一個裝置、應用程式或 Claude Code 會話被接管或結束，或伺服器找不到它時，原因會說明是哪一個，Claude Code 會省略其通常的執行 `/remote-control` 的建議：139如果連接失敗，Claude Code 會顯示一個通知，說明失敗原因，將失敗原因的警告行新增到對話中，並將指示器切換到保留在原位的失敗狀態。要重新連接，執行 `/remote-control`，除非[原因說會話在其他地方被接管或結束，或伺服器找不到它](#session-ended-elsewhere)。

140

141在重新連接之前讀取原因。當會話從另一個裝置、應用程式或 Claude Code 會話被接管或結束，或伺服器找不到它時，原因會說明是哪一個，Claude Code 會省略其通常的執行 `/remote-control` 的建議：

142

143<span id="session-ended-elsewhere" />

140 144

141* **另一個裝置或 Claude Code 會話接管了會話**：只有在您想從該裝置奪回它時才執行 `/remote-control`。145* **另一個裝置或 Claude Code 會話接管了會話**：只有在您想從該裝置奪回它時才執行 `/remote-control`。

142* **您從另一個裝置或應用程式結束或封存了會話**：只有在您想要它回來時才執行 `/remote-control`；Claude Code 會重新開啟已封存的會話。146* **您從另一個裝置或應用程式結束或封存了會話**：只有在您想要它回來時才執行 `/remote-control`；Claude Code 會重新開啟已封存的會話。

241 245

242您的本地 Claude Code 會話僅發出出站 HTTPS 請求，永遠不會在您的機器上開啟入站連接埠。當您啟動 Remote Control 時，它會向 Anthropic API 註冊並輪詢工作。當您從另一個裝置連接時，伺服器會透過串流連接在網頁或行動用戶端與您的本地會話之間路由訊息。246您的本地 Claude Code 會話僅發出出站 HTTPS 請求，永遠不會在您的機器上開啟入站連接埠。當您啟動 Remote Control 時，它會向 Anthropic API 註冊並輪詢工作。當您從另一個裝置連接時，伺服器會透過串流連接在網頁或行動用戶端與您的本地會話之間路由訊息。

243 247

244所有流量都透過 TLS 上的 Anthropic API 傳輸，與任何 Claude Code 會話相同的傳輸安全性。連接使用多個短期認證，每個認證的範圍限定為單一目的並獨立過期。248所有流量都透過 TLS 上的 Anthropic API 傳輸，與任何 Claude Code 會話相同的傳輸安全性。連接使用多個短期認證，每個認證的範圍限定為單一目的並獨立過期。當 `claude remote-control` 伺服器的註冊認證過期時，伺服器會再次向 Anthropic API 註冊並繼續為其會話提供服務。

245 249

246Remote Control 連接時，會話記錄（包括您的訊息、Claude 的回應和工具活動）會儲存在 Anthropic 伺服器上。儲存的記錄可讓對話在您的裝置間保持同步，並讓會話在網路中斷後重新連接。執行和檔案系統存取保留在您的機器上，儲存的記錄會根據[資料使用](/docs/zh-TW/data-usage)政策保留。250Remote Control 連接時，會話記錄（包括您的訊息、Claude 的回應和工具活動）會儲存在 Anthropic 伺服器上。儲存的記錄可讓對話在您的裝置間保持同步，並讓會話在網路中斷後重新連接。執行和檔案系統存取保留在您的機器上，儲存的記錄會根據[資料使用](/docs/zh-TW/data-usage)政策保留。

247 251

518 選擇正確的方法522 選擇正確的方法

519</h2>523</h2>

520 524

521Claude Code offers several ways to work when you're not at your terminal. They differ in what triggers the work, where Claude runs, and how much you need to set up.525Claude Code 提供了多種方式讓您在不在終端機時進行工作。它們在觸發工作的方式、Claude 執行的位置以及您需要設定的程度上有所不同。

522 526

523| | Trigger | Claude runs on | Setup | Best for |527| | 觸發 | Claude 執行位置 | 設定 | 最適合 |

524| :------------------------------------------------------- | :--------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------ |528| :---------------------------------------------------------- | :------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------ | :------------------------ |

527| [Channels](/docs/en/channels) | Push events from a chat app like Telegram or Discord, or your own server | Your machine (CLI) | [Install a channel plugin](/docs/en/channels#quickstart) or [build your own](/docs/en/channels-reference) | Reacting to external events like CI failures or chat messages |531| [Channels](/docs/zh-TW/channels) | 從聊天應用程式 (如 Telegram 或 Discord) 或您自己的伺服器推送事件 | 您的機器 (CLI) | [安裝頻道外掛程式](/docs/zh-TW/channels#quickstart) 或 [建立您自己的](/docs/zh-TW/channels-reference) | 對外部事件 (如 CI 失敗或聊天訊息) 做出反應 |

529| [Self-hosted environments](/docs/en/self-hosted-environments) | Start a [cloud session](/docs/en/claude-code-on-the-web) and pick your organization's environment | Your organization's infrastructure | [Deploy runners](/docs/en/self-hosted-environments-quickstart), on Team and Enterprise plans | Cloud sessions that must run inside your network |533| [Self-hosted environments](/docs/zh-TW/self-hosted-environments) | 啟動 [雲端工作階段](/docs/zh-TW/claude-code-on-the-web) 並選擇您組織的環境 | 您組織的基礎設施 | [部署執行器](/docs/zh-TW/self-hosted-environments-quickstart)，在 Team 和 Enterprise 方案上 | 必須在您的網路內執行的雲端工作階段 |

531 535

532<h2 id="related-resources">536<h2 id="related-resources">

533 相關資源537 相關資源

sandbox-environments.md +1 −1

Details

181 181

182[Claude Code on the web](/docs/zh-TW/claude-code-on-the-web) 在隔離的、由 Anthropic 管理的虛擬機中執行每個會話。網路代理強制執行預設允許清單，單獨的代理在沙箱外保持您的 GitHub 令牌，同時在其內部為儲存庫存取發出範圍限定的認證。您的組織路由到[自託管環境](/docs/zh-TW/self-hosted-environments)的會話在您配置的基礎設施上執行，其中隔離、出站控制和 git 認證是您部署的責任。182[Claude Code on the web](/docs/zh-TW/claude-code-on-the-web) 在隔離的、由 Anthropic 管理的虛擬機中執行每個會話。網路代理強制執行預設允許清單，單獨的代理在沙箱外保持您的 GitHub 令牌，同時在其內部為儲存庫存取發出範圍限定的認證。您的組織路由到[自託管環境](/docs/zh-TW/self-hosted-environments)的會話在您配置的基礎設施上執行，其中隔離、出站控制和 git 認證是您部署的責任。

183 183

184當您想要完整的虛擬機隔離而無需自己配置基礎設施，或當您從沒有本地開發環境的設備委派任務時，使用此方法。它需要 Claude 訂閱。當您從網路介面啟動會話時，您還需要連接的 GitHub 帳戶，以便沙箱可以複製您的儲存庫。當您使用 `--cloud` 從 CLI 啟動時，如果未連接 GitHub，Claude Code 可以改為[捆綁並上傳您的本地儲存庫](/docs/zh-TW/claude-code-on-the-web#send-local-repositories-without-github)。有關計劃可用性和 GitHub 身份驗證選項，請參閱 [Claude Code on the web](/docs/zh-TW/claude-code-on-the-web)。184當您想要完整的虛擬機隔離而無需自己配置基礎設施，或當您從沒有本地開發環境的設備委派任務時，使用此方法。它需要 Claude 訂閱。當您從網路介面啟動會話時，您還需要連接的 GitHub 帳戶，以便沙箱可以複製您的儲存庫。當您使用 `--cloud` 從 CLI 啟動時，Claude Code 可以[捆綁並上傳您的本地儲存庫](/docs/zh-TW/claude-code-on-the-web#send-local-repositories-without-github)。有關計劃可用性和 GitHub 身份驗證選項，請參閱 [Claude Code on the web](/docs/zh-TW/claude-code-on-the-web)。

185 185

186<h2 id="enforce-isolation-across-an-organization">186<h2 id="enforce-isolation-across-an-organization">

187 在整個組織中強制執行隔離187 在整個組織中強制執行隔離

sandboxing.md +6 −0

Details

52 52

53在面板中選擇模式時，Claude Code 會將其儲存到您專案的本地設定 `.claude/settings.local.json`，這適用於目前專案。Claude Code 在那裡儲存設定時會將該檔案新增到您的全域 gitignore。若要在所有專案中啟用沙箱，請在 `~/.claude/settings.json` 的使用者設定中將 [`sandbox.enabled`](/docs/zh-TW/settings-reference#sandbox-enabled) 設定為 `true`。若要為組織中的每個開發人員強制執行沙箱化，請使用 [managed settings](#enforce-sandboxing-with-managed-settings)。53在面板中選擇模式時，Claude Code 會將其儲存到您專案的本地設定 `.claude/settings.local.json`，這適用於目前專案。Claude Code 在那裡儲存設定時會將該檔案新增到您的全域 gitignore。若要在所有專案中啟用沙箱，請在 `~/.claude/settings.json` 的使用者設定中將 [`sandbox.enabled`](/docs/zh-TW/settings-reference#sandbox-enabled) 設定為 `true`。若要為組織中的每個開發人員強制執行沙箱化，請使用 [managed settings](#enforce-sandboxing-with-managed-settings)。

54 54

55若要在一個工作階段中變更沙箱而不寫入設定檔，請使用 [`--settings`](/docs/zh-TW/settings#change-a-setting-for-one-session) 啟動 Claude Code。例如，此命令啟動一個沙箱化工作階段，其中 Claude 無法在沙箱外重試被阻止的命令：

57```bash theme={null}

58claude --settings '{"sandbox": {"enabled": true, "allowUnsandboxedCommands": false}}'

59```

55<Warning>61<Warning>

56 預設情況下，如果沙箱因缺少依賴項或不支援的平台而無法啟動，Claude Code 會顯示警告並在沒有沙箱化的情況下執行命令。若要改為將其設為硬失敗，請將 [`sandbox.failIfUnavailable`](/docs/zh-TW/settings-reference#sandbox-failifunavailable) 設定為 `true`。這適用於需要沙箱化作為安全閘道的受管部署。62 預設情況下，如果沙箱因缺少依賴項或不支援的平台而無法啟動，Claude Code 會顯示警告並在沒有沙箱化的情況下執行命令。若要改為將其設為硬失敗，請將 [`sandbox.failIfUnavailable`](/docs/zh-TW/settings-reference#sandbox-failifunavailable) 設定為 `true`。這適用於需要沙箱化作為安全閘道的受管部署。

57</Warning>63</Warning>

scheduled-tasks.md +15 −15

Details

8 8

9排程任務讓 Claude 按間隔自動重新執行提示。使用它們來輪詢部署、監督 PR、檢查長時間執行的建置，或在工作階段稍後提醒自己執行某些操作。若要改為對事件發生時做出反應而不是輪詢，請參閱 [Channels](/docs/zh-TW/channels)：您的 CI 可以直接將失敗推送到工作階段中。若要保持工作階段逐輪執行直到符合條件而不是按間隔執行，請參閱 [`/goal`](/docs/zh-TW/goal)。9排程任務讓 Claude 按間隔自動重新執行提示。使用它們來輪詢部署、監督 PR、檢查長時間執行的建置，或在工作階段稍後提醒自己執行某些操作。若要改為對事件發生時做出反應而不是輪詢，請參閱 [Channels](/docs/zh-TW/channels)：您的 CI 可以直接將失敗推送到工作階段中。若要保持工作階段逐輪執行直到符合條件而不是按間隔執行，請參閱 [`/goal`](/docs/zh-TW/goal)。

10 10

11任務的範圍限於工作階段：它們存在於目前的對話中，當您啟動新的對話時就會停止。使用 `--resume` 或 `--continue` 繼續會恢復任何尚未[過期](#seven-day-expiry)的任務：在過去 7 天內建立的重複執行任務，或排程時間尚未到達的一次性任務。對於獨立於任何工作階段而存在的排程，請使用 [Routines](/docs/zh-TW/routines) 在雲端建立例行程序、設定 [Desktop 排程任務](/docs/zh-TW/desktop-scheduled-tasks)，或使用 [GitHub Actions](/docs/zh-TW/github-actions)。11任務的範圍限於工作階段：它們存在於目前的對話中，當您啟動新的對話時就會停止。使用 `--resume` 或 `--continue` 繼續會恢復任何尚未[過期](#seven-day-expiry)的任務，除了[限制](#limitations)下列出的任務。對於獨立於任何工作階段而存在的排程，請使用 [Routines](/docs/zh-TW/routines) 在雲端建立例行程序、設定 [Desktop 排程任務](/docs/zh-TW/desktop-scheduled-tasks)，或使用 [GitHub Actions](/docs/zh-TW/github-actions)。

12 12

13<h2 id="compare-scheduling-options">13<h2 id="compare-scheduling-options">

14 比較排程選項14 比較排程選項

15</h2>15</h2>

16 16

~~17Claude Code offers three ways to schedule recurring or one-off work:~~17Claude Code 提供三種方式來排程定期或一次性的工作：

18 18

~~22| Requires machine on | No | Yes | Yes |~~22| 需要機器開啟 | 否 | 是 | 是 |

~~23| Requires open session | No | No | Yes |~~23| 需要開啟的工作階段 | 否 | 否 | 是 |

~~25| Access to local files | No (fresh clone) | Yes | Yes |~~25| 存取本機檔案 | 否（全新複製） | 是 | 是 |

~~28| Customizable schedule | Via `/schedule` in the CLI | Yes | Yes |~~28| 可自訂排程 | 透過 CLI 中的 `/schedule` | 是 | 是 |

~~29| Minimum interval | 1 hour | 1 minute | 1 minute |~~29| 最小間隔 | 1 小時 | 1 分鐘 | 1 分鐘 |

30 30

31<Tip>31<Tip>

33</Tip>33</Tip>

34 34

35<h2 id="run-a-prompt-repeatedly-with-/loop">35<h2 id="run-a-prompt-repeatedly-with-/loop">

237 237

238* 任務只在 Claude Code 執行且閒置時執行。關閉終端或讓工作階段退出會停止它們執行。[將工作階段放在背景執行](/docs/zh-TW/agent-view#from-inside-a-session)會將 `/loop` 任務帶到背景工作階段，該工作階段會持續執行而無需終端。238* 任務只在 Claude Code 執行且閒置時執行。關閉終端或讓工作階段退出會停止它們執行。[將工作階段放在背景執行](/docs/zh-TW/agent-view#from-inside-a-session)會將 `/loop` 任務帶到背景工作階段，該工作階段會持續執行而無需終端。

239* 沒有錯過執行的追趕。如果任務的排程時間在 Claude 忙於長時間執行的請求時經過，它會在 Claude 變為閒置時執行一次，而不是每個錯過的間隔執行一次。239* 沒有錯過執行的追趕。如果任務的排程時間在 Claude 忙於長時間執行的請求時經過，它會在 Claude 變為閒置時執行一次，而不是每個錯過的間隔執行一次。

240* 啟動新的對話會清除所有工作階段範圍的任務。使用 `claude --resume` 或 `claude --continue` 繼續會恢復尚未[過期](#seven-day-expiry)的重複執行任務，以及排程時間尚未到達的一次性任務。背景 Bash 和監視任務在繼續時永遠不會被恢復。240* 啟動新的對話會清除所有工作階段範圍的任務。當您使用 `claude --resume` 或 `claude --continue` 繼續工作階段時，Claude Code 會復原使用 `CronCreate` 排程的任務，除了已[過期](#seven-day-expiry)的重複執行任務和排程時間已經過去的一次性任務。自我調整的 `/loop`（[不會被復原](#let-claude-choose-the-interval)），因此請再次執行 `/loop` 以重新啟動它。背景 Bash 和監視任務在繼續時永遠不會被復原。

241* 當[功能旗標擷取關閉](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)時，Claude Code 會將您要求跨工作階段保留的任務儲存在專案的 `.claude` 目錄中。當該目錄或其中的任務檔案是符號連結時，Claude Code 會傳回錯誤，而不是排程任務。241* 當[功能旗標擷取關閉](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)時，Claude Code 會將您要求跨工作階段保留的任務儲存在專案的 `.claude` 目錄中。當該目錄或其中的任務檔案是符號連結時，Claude Code 會傳回錯誤，而不是排程任務。

242 242

243對於需要無人值守執行的 cron 驅動自動化：243對於需要無人值守執行的 cron 驅動自動化：

security-guidance.md +1 −5

Details

43* `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 新增市場，然後重試安裝。43* `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 新增市場，然後重試安裝。

44* [外掛程式在市場中找不到](/docs/zh-TW/discover-plugins#install-plugins)：檢查外掛程式名稱。44* [外掛程式在市場中找不到](/docs/zh-TW/discover-plugins#install-plugins)：檢查外掛程式名稱。

45 45

~~46檢查安裝摘要。如果它報告 `Run /reload-plugins to activate.`，請在不重新啟動的情況下套用待處理的變更：~~46檢查安裝摘要。如果它報告 `Run /reload-plugins to activate.`，請參閱 [在不重新啟動的情況下套用外掛程式變更](/docs/zh-TW/discover-plugins#apply-plugin-changes-without-restarting) 以在您目前的工作階段中啟用外掛程式。

~~48```text theme={null}~~

~~49/reload-plugins~~

~~50```~~

51 47

52<h3 id="enable-in-cloud-sessions-and-shared-repositories">48<h3 id="enable-in-cloud-sessions-and-shared-repositories">

53 在雲端工作階段和共享儲存庫中啟用49 在雲端工作階段和共享儲存庫中啟用

self-hosted-environments.md +164 −0 created

Details

1> ## Documentation Index

2> 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.

5# 自託管環境

7> 在您控制的基礎設施上執行 Claude Code 雲端工作階段：設定自託管環境、部署執行器，並將工作階段路由到您自己的運算資源。

9<Note>

10 自託管環境在 Team 和 Enterprise 方案上處於公開測試版，預設為關閉。請參閱[可用性和限制](#availability-and-limitations)以了解啟用路徑和排除項目。

11</Note>

13自託管環境在您的組織運營的基礎設施上執行 Claude Code 雲端工作階段。[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)是指在開發者機器以外的任何地方執行的工作階段：開發者可以從 claude.ai、行動和桌面應用程式、終端機（使用 [`claude --cloud`](/docs/zh-TW/claude-code-on-the-web#from-terminal-to-web)）和[排程例行工作](/docs/zh-TW/routines)啟動這些工作階段，預設情況下它們在 Anthropic 的基礎設施上執行。在自託管環境中，這些相同的工作階段在您的網路內執行，開發者體驗基本相同，除了[可用性和限制](#availability-and-limitations)中的差異以及部署頁面的[已知問題](/docs/zh-TW/self-hosted-environments-deploy#known-issues-and-limitations)。

15如果您的團隊不使用雲端工作階段，這裡沒有任何需要設定的內容：終端機或 IDE 中的工作階段始終在開發者自己的機器上執行。如果您想在自己的常駐機器上執行 Claude Code 並從其他裝置驅動它，請使用[遠端控制](/docs/zh-TW/remote-control)，該功能也可在 Pro 和 Max 方案上使用。當您準備好設定時，請直接前往[快速入門](/docs/zh-TW/self-hosted-environments-quickstart)；如果您想先檢查安全狀況，請從[部署到生產環境](/docs/zh-TW/self-hosted-environments-deploy)開始。本頁的其餘部分說明自託管的工作原理以及何時選擇它。

17<h2 id="how-self-hosted-environments-work">

18 自託管環境的工作原理

19</h2>

21自託管有三個部分：

23* **環境**：雲端工作階段可以被發送到的命名目的地。您的組織在 claude.ai 管理設定中建立環境，每個環境都會分組一組執行器。

24* **執行器**：在您網路內的主機上執行的程式。執行器執行工作階段；其概念與自託管 CI 執行器相同。

25* **工作階段**：開發者啟動的一個 Claude Code 任務。

27當開發者啟動雲端工作階段時，工作階段啟動 UI 會顯示一個環境選擇器，列出 Anthropic 託管的環境以及您的組織建立的任何環境。如果他們選擇您的環境，Anthropic 的控制平面會將工作階段放在您環境的佇列上，執行器會認領它、複製開發者選擇的儲存庫，並在您的主機上啟動 Claude Code 程序來執行它。執行器使用您設定的認證向您的 git 主機進行身份驗證；[設定 git](/docs/zh-TW/self-hosted-environments-deploy#configure-git) 涵蓋了各種選項。工作階段從您網路內部到達您的內部服務，當它是內部的時，也以相同方式到達您的 git 主機；到 Anthropic 的流量、佇列輪詢、工作階段的事件流和模型推理是對 `api.anthropic.com` 的出站 HTTPS，以及工作階段可以到達的進一步主機的簡短清單在[網路需求](/docs/zh-TW/self-hosted-environments-deploy#network-requirements)中。Anthropic 永遠不會連接到您的網路。

29<div style={{maxWidth: "640px", margin: "0 auto"}}>

30 <Frame>

31 <img src="https://mintcdn.com/claude-code/Y0sJ2uDoOVbOVZrQ/images/self-hosted-network-paths.svg?fit=max&auto=format&n=Y0sJ2uDoOVbOVZrQ&q=85&s=8056103fc1c5564c7f0ef219d260b99d" className="dark:hidden" alt="自託管環境的架構圖：您的網路邊界包含一個執行器、其內部的兩個 Claude Code 工作階段程序和您的 git 主機，外部有 api.anthropic.com 持有佇列、工作階段流和推理。執行器輪詢佇列並到達 git 主機，每個工作階段程序開啟自己的流、推理和 git 連接，每個連接都是從您的網路出站，沒有入站。" width="680" height="320" data-path="images/self-hosted-network-paths.svg" />

33 <img src="https://mintcdn.com/claude-code/Y0sJ2uDoOVbOVZrQ/images/self-hosted-network-paths-dark.svg?fit=max&auto=format&n=Y0sJ2uDoOVbOVZrQ&q=85&s=fec6aef3b0740d80eaf6d6a7000a2233" className="hidden dark:block" alt="自託管環境的架構圖：您的網路邊界包含一個執行器、其內部的兩個 Claude Code 工作階段程序和您的 git 主機，外部有 api.anthropic.com 持有佇列、工作階段流和推理。執行器輪詢佇列並到達 git 主機，每個工作階段程序開啟自己的流、推理和 git 連接，每個連接都是從您的網路出站，沒有入站。" width="680" height="320" data-path="images/self-hosted-network-paths-dark.svg" />

34 </Frame>

35</div>

37圖表中的兩個 Claude Code 方塊是工作階段程序：一個執行器同時執行兩個工作階段，達到其設定的容量。執行器一次為一個[擁有者](#key-concepts)服務，並在認領其第一個工作階段時鎖定到該擁有者，因此簽出的程式碼永遠不會在擁有者之間混合；[執行器生命週期](#runner-lifecycle)涵蓋了該規則。

39您可以自己啟動執行器並保持它們執行，或執行[自動擴展協調器](/docs/zh-TW/self-hosted-environments-configuration#on-demand-runners)，這是您託管的第二個程序，它在工作階段佇列時啟動執行器；每個執行器在其工作完成時自行退出。無論哪種方式，您都只需設定一次環境，它就會出現在每個支援的表面上的選擇器中。

41<h2 id="availability-and-limitations">

42 可用性和限制

43</h2>

45在規劃推出之前，請檢查這些內容：

47* **方案**：Team 和 Enterprise 組織的公開測試版。自託管環境預設為關閉；[擁有者](/docs/zh-TW/cloud-environments#organization-shared-environments)在[**雲端環境**管理頁面](https://claude.ai/admin-settings/cloud-environments)上開啟**允許自託管環境**，這需要為組織啟用 [Claude Code on the web](/docs/zh-TW/claude-code-on-the-web)。

48* **零資料保留**：對於啟用了[零資料保留](/docs/zh-TW/zero-data-retention)的組織不可用。

49* **模型推理**：工作階段使用 Anthropic API，推理無法透過 [Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry](/docs/zh-TW/third-party-integrations) 或 [LLM 閘道](/docs/zh-TW/llm-gateway)路由。

50* **表面**：從 [Claude Code on the web](/docs/zh-TW/claude-code-on-the-web)、行動和桌面應用程式、[排程例行工作](/docs/zh-TW/routines) 和終端機啟動的工作階段，使用 [`claude --cloud`](/docs/zh-TW/claude-code-on-the-web#from-terminal-to-web) 或 [`--environment` 分派](/docs/zh-TW/self-hosted-environments-testing#run-the-test-loop)，可以在自託管環境中執行。[Claude Tag](https://claude.com/docs/claude-tag/overview) 工作階段也可以在其中執行，但 Claude 在這些工作階段中還無法使用[存取套件](https://claude.com/docs/claude-tag/concepts/glossary#access-bundle)。[Claude Security](/docs/zh-TW/claude-security) 和 [Code Review](/docs/zh-TW/code-review) 工作階段還沒有路由到它們。對這兩個表面的支援將單獨跟進。

51* **儲存庫**：工作階段從 GitHub 簽出儲存庫；請參閱 [GitHub 身份驗證選項](/docs/zh-TW/claude-code-on-the-web#github-authentication-options)。

52* **計費**：自託管環境中的工作階段消耗您組織的 Claude Code 使用量，與 Anthropic 託管環境中的工作階段相同。

54<h2 id="why-self-host">

55 為什麼要自託管

56</h2>

58大多數團隊最好由 Anthropic 託管的環境服務，這些環境不需要基礎設施來執行或維護。自託管適用於網路、工具或合規要求要求在其控制的基礎設施上保持工作階段執行的團隊。如果是這樣，請為其帶來的操作所有權做好計劃：您構建和維護執行器映像、操作艦隊並控制其網路。

60作為交換，自託管為您提供網路存取、自訂工具和合規控制：

62* **網路存取**：工作階段在您的網路內執行，可以到達內部服務、資料庫和登錄，而無需將它們暴露給公網

63* **自訂工具**：在執行器映像中預先安裝編譯器、SDK 和內部 CLI，以便每個工作階段都準備好構建

64* **合規**：儲存庫簽出和構建工件保留在您控制的基礎設施上。工作階段內容仍然會發送到 `api.anthropic.com` 進行模型推理。

66<h2 id="environments-runners-and-sessions">

67 環境、執行器和工作階段

68</h2>

70環境在 claude.ai 管理設定中的**雲端環境**頁面上進行管理；執行器是您在自己的基礎設施上啟動和管理的程序。

72<h3 id="key-concepts">

73 關鍵概念

74</h3>

76這些術語在整個自託管頁面中出現：

78| 術語 | 它是什麼 |

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

80| 環境 | 您的執行器的命名分組，在 claude.ai 設定中建立。工作階段被路由到環境，而不是單個執行器。 |

81| 環境祕密 | 執行器用來向環境進行身份驗證和註冊的單一共享認證。在環境建立時顯示一次，在管理 UI 中標記為**環境金鑰**。 |

82| 執行器 | 您部署的長期程序。執行器向環境註冊、接收執行器令牌並輪詢工作階段。 |

83| 工作階段 | 一個 Claude Code 任務，從 claude.ai、行動應用程式或其他 Anthropic 表面（例如排程例行工作或代理）啟動。每個工作階段作為執行器生成的子 Claude Code 程序執行。 |

85在 API 欄位、令牌聲明和度量名稱中，環境顯示為 `pool`，環境 ID 是 `pool_id`。[參考](/docs/zh-TW/self-hosted-environments-reference)映射了兩種拼寫，包括已棄用的 `pool` 標誌名稱。

87執行器一次為一個擁有者服務。執行器認領的第一個工作階段將執行器鎖定到該工作階段的擁有者，執行器隨後只為該擁有者執行工作階段，達到設定的容量。擁有者是誰取決於工作階段如何啟動：

89* **使用者啟動的工作階段**：擁有者是該使用者的帳戶。

90* **Claude Tag 頻道工作階段**：Claude 執行它們時沒有附加使用者帳戶，因此擁有者是啟動工作階段的 [Claude Tag 代理](https://claude.com/docs/claude-tag/concepts/glossary#agent-identity)。該代理啟動的每個頻道工作階段都有相同的擁有者，無論誰發送了 Slack 訊息，因此當您以 `--capacity` 大於 1 或正 `--drain-grace-sec` 執行它時，鎖定到它的執行器為不同人員啟動的工作階段服務。鎖定到使用者的執行器永遠不會認領這些，鎖定到 Claude Tag 代理的執行器永遠不會認領使用者的工作階段。

92因此，最小艦隊大小是您預期同時活躍的擁有者數量，計算使用者和 Claude Tag 代理。

94<h3 id="session-lifecycle">

95 工作階段生命週期

96</h3>

98當開發者啟動工作階段並選擇您的環境時，Anthropic 的控制平面將工作階段放在環境的佇列上。從那裡：

1001. 具有可用容量的執行器認領工作階段並持有其租約。

1012. 執行器將儲存庫複製到其工作目錄並生成子 Claude Code 程序。

1023. 子程序在執行器保持輪詢時透過 HTTPS 流回事件；每次輪詢都會刷新租約並充當心跳。

1034. 如果執行器停止輪詢約 60 秒，伺服器會將工作階段重新佇列到另一個執行器。

104

105執行器為每個輪詢請求提供 10 秒。當請求超時、丟失或執行器無法解析的回應時，執行器會繼續為其活躍工作階段服務，並在一兩秒後重試，而不是等待下一個排程的輪詢。例如，用自己的頁面回答輪詢的攔截代理會產生執行器無法解析的回應。每次另一個請求以其中一種方式失敗時，執行器會將下一次重試前的間隔加倍，最多 20 秒，並在租約即將過期時縮短間隔。

106

107<h3 id="runner-lifecycle">

108 執行器生命週期

109</h3>

110

111執行器認領的第一個工作階段將執行器鎖定到該工作階段的擁有者，執行器為該擁有者執行最多 `--capacity` 個並行工作階段。當執行器有活躍工作階段且未收到關閉信號或達到其退休時間時，執行器會繼續認領鎖定擁有者的佇列工作。一旦它們完成會發生什麼取決於 [`--drain-grace-sec`](/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags)：

112

113* **在預設值 `0` 時**：執行器在其活躍工作階段完成後立即退出，無需輪詢更多工作，因此您部署它的協調器（例如 Kubernetes）可以使用新磁碟重新啟動它，準備為任何擁有者服務。

114* **在正值時**：執行器在退出前繼續輪詢鎖定擁有者的佇列那麼多秒。

115

116此生命週期隔離每個擁有者的簽出程式碼，無需執行器在擁有者之間刪除磁碟狀態。

117

118您的基礎設施停止執行器的方式決定您是否需要 `--retire-at`。傳遞 `SIGTERM` 的終止不需要標誌：執行器按照[關閉時序](/docs/zh-TW/self-hosted-environments-deploy#shutdown-timing)所述進行排水，或當您設定 [`--defer-shutdown-max-min`](/docs/zh-TW/self-hosted-environments-deploy#defer-the-drain-past-the-first-signal) 時保持為其已持有的工作階段服務。如果您的基礎設施改為在已知的掛鐘時間銷毀主機而不發送信號，或寬限期太短而無法排水，例如沙箱生命週期上限或現貨實例回收，請傳遞 `--retire-at <epoch-seconds>` 設定為該時間前幾分鐘。在退休時間：

119

1201. 執行器停止接受新工作。

1212. 執行器透過 [`--release-idle-session-min`](/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags) 標誌使用的相同發佈路徑發佈每個活躍工作階段，因此當使用者發送下一條訊息時，工作階段在新執行器上恢復。執行器何時發佈每個工作階段取決於其狀態：

122 * 執行器在工作階段進行中時立即發佈該工作階段，一旦該輪次完成。

123 * 當輪次完成並留下執行中的背景任務時，執行器最多等待 60 秒，然後發佈工作階段，即使它們仍在執行中。如果任務已完成但讀取其結果的後續輪次尚未執行，執行器會保持工作階段直到該輪次完成，並等待不超過 [`SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS`](/docs/zh-TW/self-hosted-environments-reference#environment-variable-only-settings) 以便該輪次開始。

1243. 執行器在所有工作階段都被發佈後以 0 退出。

125

126超過終止的輪次仍然會丟失；[關閉時序](/docs/zh-TW/self-hosted-environments-deploy#shutdown-timing)涵蓋了調整邊距的大小。沒有 `--retire-at`，無信號主機終止與崩潰無法區分：控制平面記錄丟失的工作者而不是乾淨的發佈，工作階段重新佇列到另一個執行器。

127

128<h3 id="network-paths">

129 網路路徑

130</h3>

131

132執行器及其工作階段進行多種出站連接，不需要來自 Anthropic 的入站連接：

133

134* **控制平面**：執行器輪詢 `api.anthropic.com` 以獲取工作並發佈設定進度和失敗事件，全部出站 HTTPS。輪詢充當執行器的心跳。

135* **SCM 連接器**：可選的協調器 [SCM 連接器](/docs/zh-TW/self-hosted-environments-reference#scm-connector-flags) 隧道是唯一的 WebSocket 連接。

136* **Git**：執行器透過 HTTPS 或 SSH 從您的 git 主機複製和推送，使用您的部署提供的認證進行身份驗證；[設定 git](/docs/zh-TW/self-hosted-environments-deploy#configure-git) 涵蓋了各種選項，包括每個工作階段鑄造的認證和 [Anthropic git 代理](/docs/zh-TW/self-hosted-environments-deploy#use-the-anthropic-git-proxy)，它透過 `api.anthropic.com` 路由 git。

137* **工作階段子程序**：子 Claude Code 程序持有工作階段的事件流到 `api.anthropic.com`，並為模型推理和工作階段期間執行的 git 命令進行自己的出站呼叫。請參閱[網路需求](/docs/zh-TW/self-hosted-environments-deploy#network-requirements)以取得完整的出站清單。[上面的圖表](#how-self-hosted-environments-work)顯示了這些路徑，除了可選的 SCM 連接器。

138

139模型推理使用 Anthropic API。控制平面將 API 端點傳遞給每個工作階段，工作階段使用 Anthropic 發行的、工作階段範圍的 OAuth 令牌進行身份驗證，因此推理無法在自託管環境中透過 [Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry](/docs/zh-TW/third-party-integrations) 或 [LLM 閘道](/docs/zh-TW/llm-gateway)路由。

140

141支援公司出站代理。執行器和可選的[自動擴展協調器](/docs/zh-TW/self-hosted-environments-configuration#on-demand-runners)遵守[網路設定](/docs/zh-TW/network-config)中描述的代理和 mTLS 環境變數，例如 `HTTPS_PROXY` 和 `NO_PROXY`；在每個程序的環境中設定它們。這些變數涵蓋控制平面呼叫、協調器的 [SCM 連接器](/docs/zh-TW/self-hosted-environments-reference#scm-connector-flags) WebSocket 和 HTTPS 遠端的內建複製，工作階段從執行器繼承它們。工作階段流使用透過 HTTPS 的伺服器發送事件，因此路徑中的代理不得緩衝回應。

142

143如果您的代理還需要 `Proxy-Authorization` 標頭，執行器可以將其新增到它開啟到代理的每個連接；請參閱[向出站代理進行身份驗證](/docs/zh-TW/self-hosted-environments-deploy#authenticate-to-an-egress-proxy)。

144

145<h2 id="what-stays-on-your-infrastructure">

146 保留在您的基礎設施上的內容

147</h2>

148

149儲存庫簽出、構建工件、祕密和工作階段建立或修改的任何檔案都保留在您配置的機器上。對話本身，包括提示、回應和工具結果，會發送到 `api.anthropic.com` 進行模型推理，Anthropic 儲存工作階段記錄，以便您可以從另一個[支援的表面](#availability-and-limitations)恢復工作階段。

150

151自託管環境將工作階段執行移到您的網路中。控制平面仍然是 Anthropic 託管的：工作階段協調、佇列和 claude.ai 介面繼續在 Anthropic 的基礎設施上執行。

152

153<h2 id="get-started">

154 開始使用

155</h2>

156

157自託管環境頁面按您正在做的事情組織：

158

159* [快速入門](/docs/zh-TW/self-hosted-environments-quickstart)：安裝 Claude Code、建立環境、啟動執行器並路由您的第一個工作階段

160* [部署到生產環境](/docs/zh-TW/self-hosted-environments-deploy)：安全強化、網路出站、git 認證、Kubernetes 和 Compose 配方、已知問題和故障排除

161* [自訂工作階段](/docs/zh-TW/self-hosted-environments-configuration)：每個工作階段認證的包裝器指令碼、生命週期掛鉤、按需執行器、MCP 伺服器和權限

162* [端到端測試](/docs/zh-TW/self-hosted-environments-testing)：CI 煙霧測試，在您推廣執行器映像之前驗證它

163* [參考](/docs/zh-TW/self-hosted-environments-reference)：每個 CLI 標誌、環境變數、度量和健康端點

164* [驗證工作階段身份](/docs/zh-TW/self-hosted-environments-identity)：在授予存取權限之前，從您自己的服務驗證工作階段令牌

self-hosted-environments-configuration.md +435 −0 created

Details

1> ## Documentation Index

2> 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.

5# 在自託管環境中自訂會話

7> 使用包裝指令碼在自託管環境會話中自訂每個會話的認證、生命週期掛鉤和按需執行器生成。

9<Note>

10 自託管環境在 Team 和 Enterprise 方案上處於公開測試版；[擁有者](/docs/zh-TW/cloud-environments#organization-shared-environments)可以在[**雲端環境**管理頁面](https://claude.ai/admin-settings/cloud-environments)上開啟**允許自託管環境**來啟用它們。本頁面假設您已有一個可運作的執行器；請參閱[快速入門](/docs/zh-TW/self-hosted-environments-quickstart)以了解設定，以及[部署到生產環境](/docs/zh-TW/self-hosted-environments-deploy)以了解艦隊配方。

11</Note>

13[自託管環境](/docs/zh-TW/self-hosted-environments)在您自己的基礎設施上執行 Claude Code [雲端會話](/docs/zh-TW/claude-code-on-the-web)，由您部署的執行器程序執行。在沒有設定的情況下，該執行器會複製會話的儲存庫、生成 Claude Code，然後進行清理。本頁面適用於操作執行器的平台工程師：它涵蓋了當預設值不適用時的擴展點，從每個會話的認證佈建到完全替換簽出。包裝指令碼和掛鉤在執行器主機上作為可執行檔案執行，該主機是 Linux 或 macOS，本頁面上的範例假設使用 POSIX shell。

15本頁面上的一些掛鉤環境變數仍然使用 `pool`，例如 `CLAUDE_RUNNER_POOL_ID`；CLI 旗標和環境變數名稱使用 `environment`，例如 `--environment-secret-file`。

17<h2 id="wrapper-scripts">

18 包裝指令碼

19</h2>

21當每個會話需要執行器無法自行完成的設定時，請使用包裝指令碼：佈建限定於會話建立者的短期認證、匯出環境特定的祕密、準備語言工具鏈，或在子程序周圍應用資源限制。執行器每個會話啟動一次您的包裝指令碼，而不是 Claude Code 二進位檔案。透過 `exec` 進入 `$CLAUDE_RUNNER_CLAUDE_BIN`（執行器自己的二進位檔案）來結束包裝指令碼，以便訊號和結束代碼正確傳播。

23在啟動執行器時，將 `--exec-path` 或 `SELF_HOSTED_RUNNER_EXEC_PATH` 指向包裝指令碼：

25```bash theme={null}

26claude self-hosted-runner --environment-secret-file /etc/claude/environment-secret --exec-path /etc/claude/session-wrapper.sh

27```

29執行器在包裝指令碼的環境中設定以下內容：

31| 變數 | 說明 |

32| :---------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

33| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | 會話 JWT，前綴為 `sk-ant-cc-`。其 `act` 聲明識別會話建立者，包含建立者的電子郵件和上游身份提供者主體（如果建立表面記錄了它們）。該值是生成時的權杖；重新整理會透過子程序的 stdin 到達，因此包裝指令碼只會看到初始值。請參閱[驗證會話身份](/docs/zh-TW/self-hosted-environments-identity)。 |

34| `CCR_SESSION_ACCOUNT_EMAIL` | 會話建立者的電子郵件，由執行器從權杖的 `act.email` 聲明中預先提取，無需簽名驗證。適合用於標籤，例如提交預告片。當電子郵件限制認證發行時，驗證權杖並從中讀取聲明；請參閱[佈建限定於會話建立者的認證](#provision-credentials-scoped-to-the-session-creator)。當權杖不包含建立者電子郵件時未設定。視為個人可識別資訊。 |

35| `CLAUDE_RUNNER_CLIENT_PLATFORM` | 建立會話的用戶端表面，例如 `web_claude_ai`、`desktop_app`、`ios`、`claude_code_cli` 或 `scheduled_trigger`。Anthropic 在會話建立時記錄該值一次，因此包裝指令碼和每個生命週期掛鉤都會看到相同的值。僅將其用於採用分析和標籤，不用作授權訊號。當會話沒有記錄或識別的表面時未設定，因此在 `set -u` 下將其參考為 `${CLAUDE_RUNNER_CLIENT_PLATFORM:-}`。需要 Claude Code v2.1.229 或更新版本。 |

36| `CLAUDE_RUNNER_CLAUDE_BIN` | 執行器自己的 Claude Code 二進位檔案的絕對路徑。以 `exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"` 結束您的包裝指令碼，以移交給固定的二進位檔案，而無需硬編碼安裝路徑。 |

37| `CLAUDE_CODE_REMOTE_SESSION_ID` | 標記形式為 `cse_...` 的會話 ID。這是[生命週期掛鉤](#lifecycle-hooks)以 `CLAUDE_RUNNER_SESSION_ID`（`session_...` 形式）看到的相同會話；UUID 變數在兩者之間匹配，將 `cse_` 前綴替換為 `session_` 會產生會話 URL 中顯示的 ID。 |

38| `CLAUDE_CODE_REMOTE_SESSION_UUID` | 規範 UUID 形式的相同會話 ID，適用於以 UUID 為鍵的系統。 |

39| `CLAUDE_SESSION_INGRESS_TOKEN_FILE` | 保存目前會話 JWT 的每個會話檔案的絕對路徑，在權杖重新整理時保持最新。Shell 子程序在下載使用者新增到會話的附件時從中讀取其 `Authorization` 標頭。`exec` 會自動保留該變數；重建子程序環境的包裝指令碼必須帶上該變數，否則附件下載會無聲地停止工作。 |

40| `CLAUDE_CONFIG_DIR` | 每個會話的 Claude 設定目錄，在會話開始時從執行器在啟動時擷取的執行器主機設定快照中寫入；請參閱[權限和工具核准](#permissions-and-tool-approval)。此處的寫入隔離到此會話。 |

41| `ANTHROPIC_BASE_URL` | 子程序將使用的 API 基礎 URL，由控制平面按會話傳遞，通常為 `https://api.anthropic.com`。不要覆蓋它：會話的推理認證是 Anthropic 發行的 OAuth 權杖，其他提供者不接受，因此自託管環境中的推理無法路由到其他地方。 |

42| `CLAUDE_CODE_OAUTH_TOKEN` | 子程序用於模型推理的短期 OAuth 存取權杖，限定於模型推理和檔案上傳，生命週期約為 30 分鐘。執行器在過期前重新鑄造它，並透過子程序的 stdin 傳遞輪換，因此不[保持 stdin 連接](#keep-stdin-and-file-descriptor-3-attached)的包裝指令碼只會看到初始值。不要依賴您的組織 IP 允許清單來限制此權杖的使用：將其視為持有人認證，如果洩露，大約 30 分鐘內仍可使用，不要記錄它、將其寫入磁碟或在會話容器外轉發它。 |

44包裝指令碼也會繼承子程序的其餘受管環境，包括任何伺服器提供的環境變數。`exec` 會自動傳播所有內容；如果您的包裝指令碼以另一種方式生成子程序，請轉發完整環境。

46<h3 id="keep-stdin-and-file-descriptor-3-attached">

47 保持 stdin 和檔案描述符 3 連接

48</h3>

50子程序的 stdin 是執行器的控制通道。權杖輪換和會話結束訊號會在其上到達。執行器也會在檔案描述符 3 上開啟一個管道，並從中讀取子程序的活動訊號以驅動閒置和啟動逾時。純 `exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"` 會自動保留兩者。

52如果您的包裝指令碼使用裸 `&` 在背景中執行子程序，它會切斷子程序的 stdin：會話看起來健康，直到初始 OAuth 權杖的大約 30 分鐘生命週期過期，然後每個 API 呼叫都會失敗，並出現 `401 authentication_error`。如果您的包裝指令碼必須在背景中執行子程序，例如保持拆卸陷阱活著，請在檔案描述符 4 或更高版本上儲存 stdin，並明確重新連接它：

54```bash theme={null}

55exec 4<&0

56"$CLAUDE_RUNNER_CLAUDE_BIN" "$@" <&4 4<&- &

57CHILD=$!

58trap 'teardown' EXIT

59wait "$CHILD"

60```

62不要在包裝指令碼中關閉或重複使用檔案描述符 3。重定向子程序的 stdout 和 stderr 是可以的。

64<h3 id="provision-credentials-scoped-to-the-session-creator">

65 佈建限定於會話建立者的認證

66</h3>

68使用 `decode-token` 子命令從會話 JWT 讀取聲明。它從引數、`CLAUDE_CODE_SESSION_ACCESS_TOKEN` 或 stdin 讀取權杖，按該順序；請參閱[驗證會話內的權杖](/docs/zh-TW/self-hosted-environments-identity#verify-the-token-inside-the-session)以了解它檢查的內容。下面的範例解碼建立者身份，將其交換為短期 AWS 認證，並執行進入 Claude Code：

70```bash theme={null}

71#!/bin/bash

72# Key on the stable Anthropic user ID and require a human creator.

73CREATOR_SUB=$("$CLAUDE_RUNNER_CLAUDE_BIN" self-hosted-runner decode-token \

74 | jq -re '.act.sub // "" | select(startswith("user:"))') \

75 || { echo "decode-token: verification failed or no human creator" >&2; exit 1; }

77creds=$(your-sts-helper assume-role --subject "$CREATOR_SUB") \

78 || { echo "credential exchange failed" >&2; exit 1; }

79eval "$creds"

81exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"

82```

84在提取的聲明限制授權決定時，使用 `jq -re` 而不是 `jq -r`，以便缺少的聲明以非零狀態退出，而不是將字面字串 `null` 傳遞到下游。由組織服務身份（例如機器人和代理會話）建立的會話帶有 `agent:` 主體而不是 `user:`，因此此範例拒絕它們；如果您的環境提供這些會話，請明確決定包裝指令碼是否為它們回退到預設認證，而不是退出。當您的認證交換需要 SSO 主體或電子郵件時，讀取 `.act.attested_by.sub` 或 `.act.email` 並處理它們的缺失：權杖只在建立表面記錄它們時才帶有它們，[CLI 分派的會話](/docs/zh-TW/self-hosted-environments-testing#run-the-test-loop)可能兩者都缺少。有關完整的聲明參考和來自執行器外部服務的驗證，請參閱[驗證會話身份](/docs/zh-TW/self-hosted-environments-identity)。

86<h2 id="lifecycle-hooks">

87 生命週期掛鉤

88</h2>

90生命週期掛鉤用您自己的指令碼替換執行器每個會話管道的階段。使用 `--hooks-dir <path>` 或 `SELF_HOSTED_RUNNER_HOOKS_DIR` 將執行器指向掛鉤目錄。執行器尋找具有眾所周知名稱的可執行檔案；任何不存在的掛鉤都會回退到內建行為，因此您只需編寫所需的掛鉤。掛鉤以執行器自己的權限執行，會話子程序共享該 UID，因此請將掛鉤目錄掛載為唯讀，或將其烘焙到映像中，以便會話代碼無法修改它；請參閱[強化部分](/docs/zh-TW/self-hosted-environments-deploy#harden-your-deployment)。

92這些掛鉤不同於[Claude Code 掛鉤](/docs/zh-TW/hooks)，後者在會話內執行；生命週期掛鉤在執行器上執行，圍繞會話。

94<h3 id="checkout">

95 checkout

96</h3>

98每個儲存庫執行一次，代替執行器的內建複製和擷取。使用掛鉤從讀取通過鏡像複製、從存檔植入工作樹，或應用每個會話的 git 驗證。執行器設定：

100| 變數 | 說明 |

101| :--------------------------------- | :--------------------------------------------------------------------- |

102| `CLAUDE_RUNNER_REPO_URL` | 要複製的儲存庫 URL，在應用任何 `--git-host-rewrite` 和 `--git-ssh-rewrite` 之後 |

103| `CLAUDE_RUNNER_REPO_REF` | 要簽出的修訂版本：分支、標籤或提交 SHA，如會話要求的那樣。空表示儲存庫的預設分支。 |

104| `CLAUDE_RUNNER_CHECKOUT_PATH` | 工作樹必須留下的絕對路徑 |

105| `CLAUDE_RUNNER_SESSION_ID` | 標記形式為 `session_...` 的會話 ID，用於記錄和相關性 |

106| `CLAUDE_RUNNER_SESSION_UUID` | 規範 UUID 形式的相同會話 ID |

107| `CLAUDE_RUNNER_API_BASE_URL` | 用於會話範圍呼叫的 Anthropic API 基礎 URL |

108| `CLAUDE_RUNNER_CLIENT_PLATFORM` | 建立會話的用戶端表面，例如 `web_claude_ai`、`desktop_app` 或 `ios`。當會話沒有記錄或識別的表面時未設定。 |

109| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | 會話存取權杖，用於會話範圍的 API 呼叫 |

110

111指令碼必須在 `CLAUDE_RUNNER_CHECKOUT_PATH` 留下一個工作樹，簽出在要求的修訂版本。分離的 HEAD 是可以的；執行器在頂部建立會話的工作分支。執行器之後驗證路徑包含 `.git`；如果您的掛鉤具體化非 git 來源（例如 Perforce 或解包的 tarball），請在執行器的環境中設定 `CLAUDE_RUNNER_SKIP_GIT_VERIFY=1` 以跳過該檢查。基於 Git 的流程（例如工作分支建立和推送結果）需要 git 簽出，因此使用 [`post-session` 掛鉤](#post-session)從非 git 樹匯出結果。

112

113執行器不會將 git 認證傳遞給掛鉤。相反，從會話的身份鑄造每個會話的複製認證：根據[驗證來自您的服務的權杖](/docs/zh-TW/self-hosted-environments-identity#verify-the-token-from-your-service)中所述，使用標準 JWT 庫針對 `CLAUDE_RUNNER_API_BASE_URL` 下的 JWKS 端點驗證 `CLAUDE_CODE_SESSION_ACCESS_TOKEN`，然後讓您的認證服務為權杖的 `act` 聲明中的身份發行短期複製認證。`CLAUDE_RUNNER_CLAUDE_BIN` 未在簽出掛鉤環境中設定，因此 `decode-token` 子命令在此不可用。回退到主機已有的任何 git 驗證（例如 SSH 代理、認證助手或 `.netrc`）也是一個選項。

114

115當掛鉤以非零狀態退出，或以 0 退出而沒有在後面留下可用的簽出時，執行器執行的操作取決於儲存庫：

116

117* **會話推送結果的儲存庫**：執行器失敗會話，在非零退出時將指令碼的 stderr 尾部呈現給使用者。

118* **會話只從中讀取的儲存庫**，例如新增到執行中會話的儲存庫：執行器記錄帶有失敗詳細資訊的 `[runner:warn]` 行，向會話發佈 `Skipped` 步驟，移除掛鉤在簽出路徑留下的任何內容，並繼續處理其餘儲存庫。當執行器無法立即移除路徑時，它會在會話結束時重試移除。如果跳過使會話完全沒有儲存庫，執行器仍然會失敗會話。

119

120在 v2.1.228 之前，執行器在任何儲存庫的掛鉤失敗時失敗會話，因此掛鉤無法提供的唯讀儲存庫在會話在每個新執行器上恢復時再次失敗會話。

121

122執行器在會話結束後移除簽出路徑。

123

124<h3 id="post-session">

125 post-session

126</h3>

127

128在 Claude Code 子程序退出後、執行器拆卸工作區之前，每個會話執行一次。此掛鉤是您保存未提交工作的唯一機會：在 `--capacity` 高於 1 時，執行器在掛鉤返回後立即刪除每個會話的工作樹，在 `--capacity 1` 時重複使用的[規範複製](/docs/zh-TW/self-hosted-environments-deploy#reuse-a-pre-warmed-checkout)在下一個會話開始時硬重設，因此未提交的追蹤變更在任何一條路徑上都不會存活。典型用途是推送未提交變更的快照分支、存檔日誌或向您自己的系統發出會話結束事件。

129

130掛鉤在每個會話結束時觸發，其中生成了子程序，無論原因如何；下面的 `CLAUDE_RUNNER_EXIT_REASON` 值列舉了這些情況。當執行器突然終止時（例如 VM 搶佔或電源故障）無法觸發；如果您需要針對突然終止的保證，請改為使用 Claude Code `PostToolUse` 掛鉤從會話內定期快照。執行器設定：

131

132| 變數 | 說明 |

133| :--------------------------------- | :--------------------------------------------------------------------------------------------------- |

134| `CLAUDE_RUNNER_SESSION_ID` | 標記形式為 `session_...` 的會話 ID |

135| `CLAUDE_RUNNER_SESSION_UUID` | 規範 UUID 形式的相同會話 ID |

136| `CLAUDE_RUNNER_EXIT_REASON` | 會話如何結束；請參閱表格下方的值 |

137| `CLAUDE_RUNNER_WORKSPACE_PATHS` | 會話工作樹的冒號分隔絕對路徑。零儲存庫會話為空。 |

138| `CLAUDE_RUNNER_DEBUG_LOG_PATH` | 會話的偵錯日誌的路徑，在掛鉤執行時仍在磁碟上 |

139| `CLAUDE_RUNNER_API_BASE_URL` | 用於會話範圍呼叫的 Anthropic API 基礎 URL |

140| `CLAUDE_RUNNER_CLIENT_PLATFORM` | 建立會話的用戶端表面，例如 `web_claude_ai`、`desktop_app` 或 `ios`。當會話沒有記錄或識別的表面時未設定。需要 Claude Code v2.1.229 或更新版本。 |

141| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | 會話存取權杖，用於會話範圍的 API 呼叫 |

142

143`CLAUDE_RUNNER_EXIT_REASON` 採用四個值之一：

144

145* `completed`：會話乾淨地結束。Claude Code 程序正常退出，或會話在仍在執行時被存檔或刪除。

146* `failed`：Claude Code 程序崩潰，或在它啟動後設定失敗。

147* `interrupted`：執行器停止了會話。它釋放會話以釋放插槽、會話在啟動時逾時、伺服器將會話移出此執行器、執行器正在排水，或會話超過其 [`--kill-session-after-min`](/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags) 限制。

148* `abandoned`：保留給另一個執行器聲稱的會話。掛鉤目前在該情況下不觸發。

149

150[會話生命週期計數器](/docs/zh-TW/self-hosted-environments-reference#session-lifecycle-counter-semantics)將釋放、啟動逾時和伺服器移動計為 `completed` 而不是 `interrupted`，因為執行器乾淨地交回了插槽。如果您將掛鉤收據與計數器進行比較，請預期該差異。

151

152掛鉤的結束狀態永遠不會影響會話結果；失敗被記錄並忽略。執行器在每個會話結束（包括執行器關閉）時等待最多 `--post-session-hook-timeout-sec`（預設 60 秒）。此範例將未提交的工作保存到救援分支：

153

154```bash theme={null}

155#!/usr/bin/env bash

156set -u

157IFS=':'

158# Pin config the session could have planted in the checkout's .git/config:

159# -c overrides beat repo-local settings, blocking session-written fsmonitor,

160# hook-path, and gpg-program config from executing code with the hook's

161# privileges. Repo-local credential.helper, core.sshCommand, and pushurl

162# still apply; if the hook holds credentials the session didn't, pin the

163# push URL and helper too (see the note below the script).

164g() { git -c core.fsmonitor=false -c core.hooksPath=/dev/null \

165 -c commit.gpgsign=false "$@"; }

166for ws in $CLAUDE_RUNNER_WORKSPACE_PATHS; do

167 cd "$ws" 2>/dev/null || continue

168 [ -z "$(g status --porcelain 2>/dev/null)" ] && continue

169 g add -A

170 g commit -q -m "runner snapshot: $CLAUDE_RUNNER_SESSION_ID ($CLAUDE_RUNNER_EXIT_REASON)" || continue

171 g push -q origin "HEAD:refs/heads/rescue/$CLAUDE_RUNNER_SESSION_ID" || true

172done

173```

174

175掛鉤使用執行器主機自己環境中可用的任何 git 認證進行推送。在[映像中無認證的姿態](/docs/zh-TW/self-hosted-environments-deploy#configure-git)下，包括內建複製通過 Anthropic git 代理時，沒有任何認證，因此在推送前在掛鉤內鑄造短期推送認證：將掛鉤在 `CLAUDE_CODE_SESSION_ACCESS_TOKEN` 中接收的會話權杖與您自己的權杖服務交換，如[驗證會話身份](/docs/zh-TW/self-hosted-environments-identity)所述進行驗證。當掛鉤持有會話沒有的認證時，也要固定它推送的位置：將 `origin` 替換為操作員提供的 URL，並傳遞 `-c credential.helper=` 加上您自己的助手，以便會話寫入的儲存庫本地設定無法重定向經過認證的推送。

176

177<h4 id="hook-timing-when-the-runner-releases-a-session">

178 執行器釋放會話時的掛鉤計時

179</h4>

180

181已釋放的會話可以在另一個執行器上恢復。在 v2.1.236 或更新版本的執行器上，會話在釋放時執行的操作決定了它是否可以在此掛鉤完成之前在另一個執行器上恢復：

182

183* **在轉換後閒置，或在啟動時逾時**：執行器停止子程序並執行此掛鉤至完成。只有這樣它才會釋放會話。在掛鉤執行時發送的使用者訊息無法在掛鉤完成之前在另一個執行器上恢復會話。

184* **等待使用者回答提示，例如權限提示**：執行器首先釋放會話，然後執行此掛鉤。在掛鉤執行時發送的使用者訊息可以在掛鉤完成之前在另一個執行器上恢復會話。

185

186這適用於執行器釋放會話的任何時間：在閒置逾時、在 [`--retire-at`](/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags) 時間，以及在 v2.1.260 或更新版本的執行器上，在會話的 [`--kill-session-after-min`](/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags) 限制。轉換已結束且僅持有背景任務的會話在此計為閒置。在 v2.1.236 之前，執行器在兩種情況下都首先釋放會話，然後執行此掛鉤。

187

188在 `SIGTERM` 排水期間，執行器持有會話租約直到掛鉤完成；請參閱[關閉計時](/docs/zh-TW/self-hosted-environments-deploy#shutdown-timing)。

189

190<h3 id="command">

191 command

192</h3>

193

194在簽出後每個會話執行一次，代替內建的子程序生成。掛鉤接收與[包裝指令碼](#wrapper-scripts)相同的環境，應該以相同的方式 `exec` 進入 `"$CLAUDE_RUNNER_CLAUDE_BIN"`。使用 `command` 掛鉤將所有自訂保留在一個掛鉤目錄中；當包裝指令碼在其他地方時使用 `--exec-path`。如果也設定了 `--exec-path`，旗標優先，`command` 掛鉤被忽略。

195

196始終 `exec` 執行器自己的二進位檔案，而不是 PATH 解析的 `claude`；否則您會破壞[版本固定](/docs/zh-TW/self-hosted-environments-deploy#pin-the-version)。

197

198<h2 id="on-demand-runners">

199 隨需啟動的執行器

200</h2>

201

202您可以不使用固定的執行器群組，而是每個工作階段啟動一個執行器。協調器是一個獨立的、無狀態的子命令，它會輪詢 Anthropic 以取得啟動請求，每個沒有可用執行器的已排隊工作階段一個請求，並為每個請求執行您的 `spawn-runner` hook。您的 hook 會將工作負載提交到您的平台：Kubernetes Job、EC2 執行個體、Nomad dispatch。

203

204隨需啟動的執行器改善了認證衛生。在固定群組上，環境祕密存在於每個執行器主機上，這與執行使用者工作階段的主機相同。使用協調器，環境祕密只保留在協調器主機上，該主機永遠不會執行使用者程式碼；每個啟動的執行器都會收到一個一次性工作單，它只註冊一個執行器，然後過期。

205

206若要啟動協調器，請傳遞環境祕密和包含可執行 `spawn-runner` 指令碼的 hooks 目錄：

207

208```bash theme={null}

209claude self-hosted-runner orchestrator \

210 --environment-secret-file /etc/claude/environment-secret \

211 --hooks-dir /etc/claude/hooks

212```

213

214協調器在輪詢之間不保留任何狀態，因此您可以針對同一環境執行兩個或多個副本以實現可用性。每個啟動請求由伺服器端的恰好一個副本聲稱。所有副本必須使用相同的 `--expected-spawn-seconds` 值；請參閱 [hook 合約](#the-spawn-runner-hook)。

215

216<h3 id="the-spawn-runner-hook">

217 spawn-runner hook

218</h3>

219

220協調器為每個啟動請求執行一次 `${hooks-dir}/spawn-runner`。hook 必須非同步提交工作，不等待執行器啟動，並在 `--hook-timeout` 內返回，預設為 60 秒。hook 接收：

221

222| 變數 | 說明 |

223| :------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

224| `CLAUDE_RUNNER_WORK_ORDER_FILE` | 包含已簽署工作單 JWT 的暫存檔案路徑，新執行器使用此 JWT 進行註冊。hook 退出後刪除。不要記錄檔案的內容。 |

225| `CLAUDE_RUNNER_ORDER_ID` | 不透明的冪等性金鑰，每個啟動請求唯一，對 Kubernetes 資源名稱安全。將其用作您的佈建程式的去重金鑰。 |

226| `CLAUDE_RUNNER_SESSION_ID` | 此請求所針對的工作階段。對於預熱請求為空，預熱請求會在設定 [`--min-idle`](/docs/zh-TW/self-hosted-environments-reference#orchestrator-cli-flags) 時在任何特定工作階段之前啟動待命執行器，因此不要假設變數已設定。 |

227| `CLAUDE_RUNNER_SESSION_UUID` | 相同的工作階段 ID，採用規範 UUID 形式。對於預熱請求為空。 |

228| `CLAUDE_RUNNER_ATTEMPT` | 此工作階段已有多少個啟動請求。對於預熱請求為 `0`。 |

229| `CLAUDE_RUNNER_ORDER_SERVER_TIME` | 來自輪詢回應的 HTTP `Date` 標頭的伺服器時間。當 hook 驗證工作單 JWT 的 `exp` 時，請與此值進行比較，而不是本地時鐘，以容許時間偏差。當閘道省略標頭時為空。 |

230| `CLAUDE_RUNNER_POOL_ID` | 新執行器應加入的環境的 ID，採用 `ccpool_...` 形式 |

231| `CLAUDE_RUNNER_ACCOUNT_ID` | 排隊工作階段的帳戶的標記 ID，用於按帳戶路由、配額或退款。不可用時為空，Claude Tag 頻道工作階段始終為空，這些工作階段沒有帳戶排隊。 |

232| `CLAUDE_RUNNER_ACCOUNT_EMAIL` | 排隊工作階段的帳戶的電子郵件。不可用時為空。將電子郵件視為個人可識別資訊，不要記錄它。 |

233| `CLAUDE_RUNNER_PRIMARY_REPO_URL` | 工作階段的第一個 git 來源的 URL，用於路由到預先準備了該儲存庫的執行器。工作階段沒有 git 來源時為空。 |

234| `CLAUDE_RUNNER_PRIMARY_REPO_REVISION` | 工作階段的第一個 git 來源的修訂版本：分支、SHA 或標籤。未指定時為空。 |

235| `CLAUDE_RUNNER_REPO_SOURCES` | 所有工作階段的 git 來源的 `{url, revision}` 的 JSON 陣列，用於在次要儲存庫上路由的 hook。沒有來源時為空。 |

236| `CLAUDE_RUNNER_CORRELATION_ID` | 在工作階段建立時提供的相關 ID，回顯以便 hook 可以將此工作單對應到建立工作階段的請求。工作階段沒有時為空。 |

237| `CLAUDE_RUNNER_CLIENT_PLATFORM` | 建立工作階段的用戶端表面，例如 `web_claude_ai`、`desktop_app`、`ios` 或 `scheduled_trigger`，用於採用分析。當工作階段沒有記錄或識別的表面時未設定，對於預熱請求也未設定；使用 `[ -n "${CLAUDE_RUNNER_CLIENT_PLATFORM:-}" ]` 檢查它，在 `set -u` 下保持安全。 |

238

239啟動的執行器使用工作單代替環境祕密進行註冊：

240

241* **使用工作單啟動它**：將 [`--environment-secret-file`](/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags) 指向包含工作單 JWT 的檔案，或將 `SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET` 設定為 JWT 值。

242* **在 hook 退出前複製 JWT**：協調器在 hook 退出後刪除工作單檔案，因此將 JWT 複製到您提交的工作負載中，例如啟動的 Job 上的 Kubernetes Secret，而不是透過檔案路徑。

243* **在啟動的執行器上使用 `--capacity 1`**：工作階段綁定的工作單恰好註冊一個綁定到該工作階段的執行器，因此更高的容量會新增永遠不會接收工作的插槽，執行器在啟動時會記錄警告。

244* **預熱工作單註冊未綁定**：待命執行器未綁定到工作階段，並像固定群組執行器一樣聲稱已排隊的工作。

245

246合約有四個佈建程式無關的規則：

247

2481. **在 `CLAUDE_RUNNER_ORDER_ID` 上保持冪等性。** 重新傳遞相同的請求最多必須啟動一個執行器。從 ID 衍生確定性資源名稱，並讓您的平台拒絕重複項。

2492. **不要重試工作負載。** 一個訂單 ID 最多意味著建立一個工作負載。如果執行器永遠不註冊，Anthropic 會在 `--expected-spawn-seconds` 後使用新的訂單 ID 重新請求。

2503. **使用退出代碼合約。** 退出 0 表示已提交。退出 1 表示可重試的失敗；工作階段退避並被重新提供。退出 2 或更高表示不可重試；工作階段被阻止再次啟動，直到 [Owner](/docs/zh-TW/cloud-environments#organization-shared-environments) 在環境的 **Activity** 標籤中選擇 **Retry**。在非零退出時，hook 的 stderr 的尾部會作為失敗原因出現在那裡，因此將可操作的錯誤寫入 stderr，永遠不要寫入祕密。對於預熱請求，沒有工作階段失敗：協調器只在本地記錄非零退出，伺服器在租約後重新請求啟動。

2514. **將 `--expected-spawn-seconds` 設定為至少您的 p99 啟動時間。** 這是伺服器端租約。所有協調器副本必須使用相同的值。

252

253hook 寫入 stdout 或 stderr 的所有內容都會出現在協調器的日誌中，認證會自動編輯。如果工作階段保持排隊，請檢查協調器的 `/healthz` 主體以取得佇列計數，然後在 [**Cloud environments** 管理頁面](https://claude.ai/admin-settings/cloud-environments) 上開啟您環境的 **Activity** 標籤：在那裡展開失敗的工作階段以查看其啟動錯誤，並選擇 **Retry** 以重新請求它。

254

255<h2 id="mcp-servers">

256 MCP 伺服器

257</h2>

258

259要在每個會話中提供 [MCP 伺服器](/docs/zh-TW/mcp)，請在映像構建時使用與桌面安裝上使用的相同 `claude mcp add` 命令添加它們。如果您的執行器是裸程序而不是容器，請在主機上以執行器的使用者身份執行相同的命令，然後重新啟動執行器：它在啟動時讀取主機設定一次。`--scope user` 旗標是必需的；預設本地範圍寫入執行器不植入會話的每個目錄鍵下。例如，在您的 Dockerfile 中：

260

261```dockerfile theme={null}

262RUN claude mcp add --scope user sidecar -- /usr/local/bin/mcp-sidecar

263RUN claude mcp add --scope user --transport http internal http://mcp-gateway.svc.cluster.local:8080

264```

265

266執行器在啟動時快照主機的設定一次。快照從主機的 `.claude.json` 擷取 `mcpServers` 鍵，該鍵位於 `~/.claude/` 旁邊而不是內部，執行器僅將該鍵植入每個會話的隔離設定；帳戶狀態和專案歷史被丟棄。要確認伺服器到達會話，請在環境上啟動會話並要求 Claude 列出其 MCP 工具；執行器也會為任何擷取的條目記錄啟動警告，其 `type` 它無法識別並丟棄該條目，因此您可以看到為什麼該伺服器在會話中缺失。當設定 `SELF_HOSTED_RUNNER_HOST_CONFIG_DIR` 時，執行器改為從該目錄讀取 `.claude.json`，因此將變數指向空目錄也會禁用 MCP 植入。

267

268Claude Code 也從其他來源載入 MCP 伺服器：

269

270* 企業範圍[受管 MCP 檔案](/docs/zh-TW/managed-mcp)在其標準系統路徑：Linux 執行器主機上的 `/etc/claude-code/managed-mcp.json`，macOS 主機上的 `/Library/Application Support/ClaudeCode/managed-mcp.json`。將其用於鎖定的艦隊，其中只有管理員列出的伺服器可能載入。請參閱[使用 managed-mcp.json 的獨佔控制](/docs/zh-TW/managed-mcp#exclusive-control-with-managed-mcp-json)以了解優先順序規則。當此檔案在執行器主機上時，Claude Code 跳過 Anthropic 的控制平面傳遞給會話的 MCP 伺服器，包括 claude.ai 連接器，並在會話子程序的 stderr 上命名它們，執行器在 `debug` 日誌級別記錄。在 v2.1.229 之前，這些會話在啟動時以 `You cannot dynamically configure MCP servers when an enterprise MCP config is present` 退出。

271* 執行器主機上[受管設定](/docs/zh-TW/managed-settings)中的 [`managedMcpServers`](/docs/zh-TW/settings-reference#managedmcpservers) 鍵：提供 HTTP 和 SSE 伺服器而不取得獨佔控制，因此來自其他來源的伺服器仍然載入。需要 Claude Code v2.1.259 或更新版本。

272* `<repo>/.mcp.json`：專案範圍。將檔案提交到儲存庫；其伺服器在雲端會話中自動核准。

273

274當為您的組織啟用連接器傳遞時，Anthropic 的控制平面將您在 claude.ai 上設定的連接器傳遞給透過伺服器提供的 MCP 設定路由的互動建立的會話，通過 `api.anthropic.com`。以程式設計方式建立的會話（例如 [CLI 分派](/docs/zh-TW/self-hosted-environments-testing#run-the-test-loop)）不接收連接器傳遞；改為透過本部分列出的其他來源之一為它們提供 MCP 伺服器。子程序的 OAuth 權杖不帶有直接擷取連接器的範圍，因此子程序不會自行嘗試該擷取；傳遞是伺服器驅動的。

275

276`settings.json` 不帶有 MCP 伺服器定義，設定架構中沒有頂級 `mcpServers` 欄位。在受管設定中，使用 [`managedMcpServers`](/docs/zh-TW/settings-reference#managedmcpservers) 鍵提供伺服器。

277

278會話繼承執行器的環境，因此在那裡設定 [`ENABLE_TOOL_SEARCH`](/docs/zh-TW/mcp#scale-with-mcp-tool-search) 以控制執行器生成的每個會話的 MCP 工具搜尋；MCP 頁面涵蓋了這些值。

279

280<h2 id="prompt-sessions-to-push-their-work">

281 提示會話推送其工作

282</h2>

283

284Anthropic 託管的會話執行 [`Stop` 掛鉤](/docs/zh-TW/hooks#stop)，Claude Code 掛鉤在 Claude 完成回應時執行，提示 Claude 提交並推送其工作。執行器不安裝一個。沒有它，以未提交變更結束的會話只在執行器的磁碟上留下該工作，claude.ai/code 中的**建立 PR** 按鈕保持非活動狀態，直到分支存在於遠端。

285

286下面的參考實現有兩個部分。將設定塊合併到執行器主機上的 `~/.claude/settings.json` 中，執行器將其植入每個會話，並將指令碼保存為執行器主機上的 `~/.claude/hooks/stop-hook-nudge.sh` 並使其可執行：

287

288```json theme={null}

289{

290 "hooks": {

291 "Stop": [

292 {

293 "hooks": [

294 {

295 "type": "command",

296 "timeout": 10,

297 "command": "\"$CLAUDE_CONFIG_DIR/hooks/stop-hook-nudge.sh\""

298 }

299 ]

300 }

301 ]

302 }

303}

304```

305

306```sh theme={null}

307#!/bin/sh

308# Stop-hook reference implementation for self-hosted runners.

309#

310# Nudges Claude once per turn if the project directory has uncommitted

311# changes OR unpushed commits, so work isn't lost when an idle session

312# is released and so the "Create PR" button on claude.ai/code lights up.

313#

314# Runner-level (no repo changes): drop this file at ~/.claude/hooks/ on

315# the runner host and merge the accompanying Stop-hook settings block

316# into ~/.claude/settings.json — the runner seeds both into every session.

317# Repo-level alternative: commit to <repo>/.claude/hooks/ and change the

318# settings.json command path to $CLAUDE_PROJECT_DIR/.claude/hooks/.

319#

320# stdin: hook JSON payload (see https://code.claude.com/docs/en/hooks)

321# stdout: {"decision":"block","reason":"..."} to nudge, or nothing to allow stop.

322

323# Re-entry guard: the harness sets stop_hook_active=true when re-invoking

324# the Stop hook after a block. Bail so we only nudge once per turn. The

325# harness emits compact JSON (no space after the colon), which this

326# pattern relies on; use jq if you need a whitespace-tolerant check.

327in=$(cat)

328case "$in" in *'"stop_hook_active":true'*) exit 0 ;; esac

329

330d="$CLAUDE_PROJECT_DIR"

331

332# Not a git repo → nothing to nudge.

333git -C "$d" rev-parse --git-dir >/dev/null 2>&1 || exit 0

334

335# No remote → "push to the remote" is unsatisfiable; bail.

336[ -z "$(git -C "$d" remote 2>/dev/null)" ] && exit 0

337

338# Uncommitted changes (staged, unstaged, or untracked). Exclude .claude/

339# entirely — operator-seeded settings and CLI-written runtime state

340# (scheduler lock, worktrees, routine state) live there and neither is

341# "uncommitted work" the model needs to push.

342s=$(git -C "$d" status --porcelain -- . ':(exclude).claude/' 2>/dev/null)

343if [ -n "$s" ]; then

344 printf '{"decision":"block","reason":"There are uncommitted changes in the repository. Please commit and push these changes to the remote branch."}'

345 exit 0

346fi

347

348# Unpushed commits. Count commits on HEAD not reachable from any

349# remote-tracking ref or FETCH_HEAD. This works uniformly for:

350# - init+fetch checkouts (runner default: only FETCH_HEAD exists)

351# - clone-based checkouts (origin/* exist)

352# - the runner default: the child starts on the session's outcome

353# branch, which the runner creates after checkout

354# - detached HEAD, when a custom setup skips that branch creation

355# With no reference point at all (never fetched), stay silent rather

356# than false-positive on a read-only turn.

357base=""

358git -C "$d" rev-parse --verify -q FETCH_HEAD >/dev/null && base="FETCH_HEAD"

359if [ -z "$base" ] && [ -z "$(git -C "$d" for-each-ref --count=1 refs/remotes/origin 2>/dev/null)" ]; then

360 exit 0

361fi

362# shellcheck disable=SC2086 # $base is either "" or "FETCH_HEAD", intentional word-split

363unpushed=$(git -C "$d" rev-list HEAD --not $base --remotes=origin --count 2>/dev/null) || unpushed=0

364if [ "$unpushed" -gt 0 ]; then

365 branch=$(git -C "$d" symbolic-ref --short -q HEAD)

366 if [ -n "$branch" ]; then

367 # $branch is attacker-influenced — git-check-ref-format(1) allows `"`

368 # in ref names. `\` is forbidden (rule 10) but escaped anyway as cheap

369 # defense-in-depth.

370 # Escape JSON metacharacters before interpolating into the hand-built

371 # payload so a branch like x","continue":false can't inject keys into

372 # the hook-output JSON the harness parses. $unpushed is safe — the

373 # -gt guard above rejects anything that isn't a plain integer.

374 branch_esc=$(printf '%s' "$branch" | sed 's/\\/\\\\/g; s/"/\\"/g')

375 printf '{"decision":"block","reason":"There are %s unpushed commit(s) on branch '\''%s'\''. Please push these changes to the remote repository."}' "$unpushed" "$branch_esc"

376 else

377 printf '{"decision":"block","reason":"There are %s unpushed commit(s) on a detached HEAD. Please create a branch and push it to the remote repository."}' "$unpushed"

378 fi

379 exit 0

380fi

381

382exit 0

383```

384

385掛鉤在會話結束前提示 Claude 提交並推送，當目錄不是 git 儲存庫或沒有遠端時保持沉默。

386

387<h2 id="permissions-and-tool-approval">

388 權限和工具核准

389</h2>

390

391自託管會話沒有連接的終端，因此未回答的權限提示會延遲轉換，直到使用者在 UI 中回應。Anthropic 的控制平面使用工作負載發送每個會話的工具清單和權限規則；預設設定預先核准常規工具呼叫（包括 `Bash`），雲端會話[預先核准檔案編輯，無論模式如何](/docs/zh-TW/permission-modes#switch-permission-modes)。沒有任何東西預先核准的呼叫會透過會話 UI 提示。

392

393<Note>

394 僅在環境的會話容器執行[預設拒絕網路出口](/docs/zh-TW/self-hosted-environments-deploy#default-deny-egress)和[強化部分](/docs/zh-TW/self-hosted-environments-deploy#harden-your-deployment)中其餘部分的環境上固定自動模式。常規工具呼叫（包括 `Bash` 網路請求）在預設預先核准的工具集和自動模式中都無需人工干預執行，因此網路邊界是限制這些呼叫可以到達的位置。

395</Note>

396

397要無論控制平面發送什麼都將提示保持在最低限度，請從您的包裝指令碼或 [`command` 掛鉤](#command)固定[自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)。自動模式讓會話無需常規權限提示執行：單獨的分類器模型在它們執行前審查操作並阻止它拒絕的操作，明確的詢問規則仍然強制提示；權限模式頁面涵蓋分類器檢查的內容。執行器在呼叫包裝指令碼前附加伺服器計算的旗標，對於單值旗標（例如 `--permission-mode`），解析器尊重最後出現的旗標，因此您在 `"$@"` 後附加的旗標覆蓋伺服器發送的值：

398

399```bash theme={null}

400#!/bin/bash

401exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@" --permission-mode auto

402```

403

404要改為預先核准特定工具，請附加 `--allowed-tools` 和您的規則，例如 `--allowed-tools "Bash(bazel *) Bash(yarn *) mcp__internal__*"`。列表旗標（例如 `--allowed-tools` 和 `--disallowed-tools`）在出現時累積而不是覆蓋，因此您的規則應用在控制平面發送的任何規則之上。要縮小，請附加 `--disallowed-tools`，即使另一個規則允許工具也會拒絕工具。

405

406<h3 id="how-each-session’s-config-is-assembled">

407 如何組合每個會話的設定

408</h3>

409

410執行器為每個會話提供自己的設定目錄，從執行器在啟動時擷取的主機 `~/.claude/` 的記憶體內快照植入：`settings.json`、`CLAUDE.md`、掛鉤、代理、命令和技能在您的執行器映像中應用於每個會話作為使用者級基線。因為快照在啟動時進行，執行中主機上的設定變更僅在執行器重新啟動後生效。設定 `SELF_HOSTED_RUNNER_HOST_CONFIG_DIR` 以從不同路徑植入，或將其指向空目錄以禁用植入。

411

412儲存庫提交的 `.claude/settings.json` 作為專案設定分層。會話也從執行器映像中的標準系統路徑讀取 [`managed-settings.json`](/docs/zh-TW/settings#where-settings-live)。其鍵是否與[伺服器受管設定](/docs/zh-TW/server-managed-settings)一起應用遵循 [Claude Code 如何組合受管來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)：預設情況下，當您的組織傳遞任何伺服器受管鍵時，會話忽略執行器映像的檔案，除了 [Claude Code 從每個管理來源讀取的鍵](/docs/zh-TW/managed-settings#keys-read-from-every-admin-source)，例如 `env` 塊、沙箱鎖、沙箱二進位路徑和 `forceRemoteSettingsRefresh`。請參閱[設定優先順序](/docs/zh-TW/settings#settings-precedence)。

413

414當 Anthropic 的控制平面為會話提供 [Claude Code 掛鉤](/docs/zh-TW/hooks)時，執行器將它們安裝在旁邊，而不是在您自己的設定上。需要 Claude Code v2.1.229 或更新版本。

415

416* **它們著陸的位置**：執行器將每個提供的掛鉤指令碼寫入會話設定目錄的保留 `hooks/.ccr-launcher/` 子目錄，並在單獨的設定檔案中註冊指令碼，該檔案使用 `--settings` 傳遞給會話，保留植入的 `settings.json` 和您自己的指令碼在 `hooks/<name>` 不變。執行器為每個會話重建保留子目錄，不將主機內容在 `~/.claude/hooks/.ccr-launcher/` 植入會話。

417* **誰編寫它們**：控制平面從其自己部署中的固定常數填充指令碼，永遠不從每個會話或第三方輸入。

418* **什麼仍然管理它們**：透過 `--settings` 傳遞的掛鉤進入普通合併掛鉤設定，而不是受管層，因此您的受管設定仍然適用。`disableAllHooks` 禁用它們，它們不在 [`allowManagedHooksOnly`](/docs/zh-TW/settings-reference#allowmanagedhooksonly) 保持載入的類別中。

419

420<h3 id="repository-committed-permission-rules">

421 儲存庫提交的權限規則

422</h3>

423

424不要在儲存庫提交的 `permissions.allow` 中放置裸 `"Edit"`、`"Write"` 或 `"NotebookEdit"` 條目。裸檔案工具規則匹配工具，無論路徑如何，授予主機上任何地方的寫入，而不僅僅是工作區，因此執行器的寫入範圍限制保護標誌會話；使用 [`--confine-repo-settings enforce`](/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags) 它拒絕生成會話而不是記錄並繼續。請參閱[強化部分](/docs/zh-TW/self-hosted-environments-deploy#harden-your-deployment)。

425

426儲存庫根本不需要檔案工具規則：雲端會話[預先核准檔案編輯，無論模式如何](/docs/zh-TW/permission-modes#switch-permission-modes)。如果您確實提交規則，請將其限定於工作區，例如 `"Edit(/**)"`；單個前導斜杠相對於專案根目錄，這是會話的工作區。裸檔案工具規則在操作員的主機級 `settings.json` 中很好，因為該檔案不是儲存庫提交的。

427

428`defaultMode` 為 `auto` 僅從映像寬或使用者級設定檔案中尊重，因此簽出的儲存庫無法授予自己自動模式。有關雲端會話接受的模式和完整規則語法，請參閱[權限模式](/docs/zh-TW/permission-modes)。

429

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

431 接下來

432</h2>

433

434* [參考](/docs/zh-TW/self-hosted-environments-reference)：每個 CLI 旗標、環境變數和度量

435* [驗證會話身份](/docs/zh-TW/self-hosted-environments-identity)：驗證來自執行器外部服務的會話權杖

self-hosted-environments-deploy.md +541 −0 created

Details

1> ## Documentation Index

2> 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.

5# 將自託管環境部署到生產環境

7> 在生產環境中執行自託管執行器：安全強化、網路出站流量控制、Git 認證、Kubernetes 和 Compose 配方，以及故障排除。

9<Note>

10 自託管環境在 Team 和 Enterprise 方案上處於公開測試版；[可用性和限制](/docs/zh-TW/self-hosted-environments#availability-and-limitations)涵蓋啟用路徑。本頁面涵蓋在生產環境中執行執行器群；請參閱[快速入門](/docs/zh-TW/self-hosted-environments-quickstart)以了解您的第一個執行器和工作階段。

11</Note>

13[自託管環境](/docs/zh-TW/self-hosted-environments)在您部署在網路內的執行器上執行 Claude Code [雲端工作階段](/docs/zh-TW/claude-code-on-the-web)，在生產環境中，這些工作階段代表所有可以向環境分派工作階段的人執行模型導向的程式碼。本頁面適用於將正常運作的環境帶入生產環境的操作員。它按部署順序進行：在連接真實系統之前要鎖定什麼、執行器群需要的出站流量、工作階段如何向您的 Git 主機進行身份驗證、部署配方本身，以及當工作階段出現故障時要檢查什麼。

15<h2 id="harden-your-deployment">

16 強化您的部署

17</h2>

19自託管執行器代表所有可以向其環境分派工作階段的人在您的基礎設施上執行任意的、模型導向的程式碼。這是您 Anthropic 組織的任何成員，以及任何可以在所有者路由到環境的範圍內啟動 [Claude Tag](https://claude.com/docs/claude-tag/overview) 頻道工作階段的人。在將環境連接到生產系統之前，請逐項進行：

21* **臨時的、每個工作階段的容器**：在新鮮容器或 VM 中執行每個執行器程序，該容器或 VM 在程序退出時被銷毀，使用 `--capacity 1` 和預設的 `--drain-grace-sec 0`，以便每個容器恰好服務一個工作階段。在更高的容量或正的清空寬限期下，一個容器服務來自同一[鎖定所有者](/docs/zh-TW/self-hosted-environments#key-concepts)的多個工作階段；請參閱[執行器生命週期](/docs/zh-TW/self-hosted-environments#runner-lifecycle)。不要在執行器重新啟動之間重複使用檔案系統，除非在刻意的[預熱簽出](#reuse-a-pre-warmed-checkout)設定中，並且永遠不要跨所有者。

22* **映像中沒有廣泛的認證**：不要包含長期的 SSH 金鑰、雲端提供商認證或授予超過工作階段需要的個人存取令牌。在工作階段期間使用的薄荷認證，例如推送或 API 令牌，從您的[包裝器指令碼](/docs/zh-TW/self-hosted-environments-configuration#wrapper-scripts)按工作階段進行。對於在包裝器執行之前發生的初始複製，使用 [`checkout` 生命週期鉤子](/docs/zh-TW/self-hosted-environments-configuration#checkout)或 [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy)；請參閱[配置 Git](#configure-git)。

23* **將環境祕密保留在執行工作階段的主機之外**：環境祕密可以註冊執行器並拾取在環境上排隊的任何工作階段。在固定群中，它存在於每個執行器主機上，任何工作階段的程式碼都可以讀取祕密檔案。優先使用[按需執行器](/docs/zh-TW/self-hosted-environments-configuration#on-demand-runners)，其中祕密保留在協調器主機上，該主機永遠不執行使用者程式碼，每個執行器接收單次使用的工作單據，該單據恰好註冊一個執行器。在固定群中，將環境祕密檔案視為可由每個工作階段讀取，並在任何懷疑的工作階段洩露後輪換祕密。

24* **預設拒絕網路出站流量**：在每個環境上限制執行器和工作階段容器的出站流量在您自己的網路邊界；[預設拒絕出站流量](#default-deny-egress)涵蓋允許什麼以及為什麼。

25* **最小權限主機 IAM**：附加到執行器主機的計算身份，例如執行個體設定檔或節點服務帳戶，應僅授予執行器本身需要的內容。工作階段應通過您的包裝器指令碼而不是繼承主機的身份來獲得自己的認證。

26* **阻止工作階段的雲端中繼資料端點**：將工作階段保留在主機身份之外需要阻止它們對雲端中繼資料端點的存取，子網級出站流量原則不會攔截連結本地中繼資料流量，因此在容器本身中阻止它：

28 * IMDSv2，跳數限制為 1

29 * GKE Workload Identity，具有中繼資料隱藏

30 * 工作階段容器網路命名空間中 `169.254.169.254` 的明確拒絕

32 該阻止也適用於您的包裝器指令碼和生命週期鉤子，因為它們共享容器。使用[工作階段 JWT](/docs/zh-TW/self-hosted-environments-identity)對您自己的令牌服務進行身份驗證，通過允許列表出站流量，或使用基於檔案的 Web 身份，例如 Amazon EKS 上的 IAM Roles for Service Accounts (IRSA)。

33* **每個執行器的檔案系統隔離**：每個執行器程序獲得自己的工作目錄，主機上沒有其他程序可以讀取或寫入。使 `--hooks-dir`、包裝器指令碼和主機的 `~/.claude/` 對工作階段唯讀，無論是內置在映像中還是以唯讀方式掛載。

34* **分派沒有每個環境的存取控制**：您 Anthropic 組織的任何成員都可以向其任何環境分派工作階段。如果所有者[將 Claude Tag 頻道路由到環境](/docs/zh-TW/cloud-environments#set-the-environment-a-claude-tag-channel-uses)，[Claude Tag 存取設定](https://claude.com/docs/claude-tag/admins/restrict-access#restrict-who-can-use-claude)允許的任何人都可以啟動在那裡執行的頻道工作階段。預設情況下，這是連接的 Slack 工作區中的任何人，無論是否有 Claude 帳戶。將每個執行器主機視為可由所有可以向其分派的人進行程式碼執行，並且只在執行器主機上放置所有這些人都被允許讀取的資料和認證。[`--lock-to-account`](/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags)限制給定主機執行哪個帳戶的工作階段，但它不會縮小誰可以分派到環境中。要使自託管環境成為唯一的選擇器選項，[所有者](/docs/zh-TW/cloud-environments#organization-shared-environments)可以從[**雲端環境**頁面](https://claude.ai/admin-settings/cloud-environments)隱藏整個組織的 Anthropic 託管環境。

35* **強制執行儲存庫設定防護**：使用 [`--confine-repo-settings`](/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags)選擇防護模式。預設的 `warn` 記錄違規並仍然生成工作階段，`enforce` 拒絕工作階段，`off` 禁用掃描。執行器掃描每個儲存庫的已提交設定以查找：

37 * 在該工作階段自己的工作區之外解析的授予：`additionalDirectories` 項目、`permissions.allow` 中的 `Edit`、`Write` 或 `NotebookEdit` 規則，或 `sandbox.filesystem.allowWrite` 或 `allowRead` 項目

38 * 非空的 `env` 塊

39 * 操作員姿態覆蓋，例如 `sandbox.enabled: false`

41 防護無論 [`--trust-workspace`](/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags)如何都會執行，並且不涵蓋儲存庫鉤子、`.mcp.json` 或 Bash 規則；請參閱[權限和工具批准](/docs/zh-TW/self-hosted-environments-configuration#permissions-and-tool-approval)以了解這些授予應該在哪裡。

43<Note>

44 您組織的 IP 允許列表預設不涵蓋自託管執行器流量。不要依賴它作為執行器或工作階段流量的網路控制；改為在您自己的網路邊界應用預設拒絕出站流量，如果您想要為您的組織強制執行 IP 允許列表，請聯繫您的 Anthropic 帳戶團隊。

45</Note>

47<h2 id="network-requirements">

48 網路要求

49</h2>

51執行器及其生成的工作階段子項進行出站連接到以下主機。將工作階段容器出站流量限制為這些主機和工作階段需要到達的特定內部服務；[預設拒絕出站流量](#default-deny-egress)涵蓋如何以及為什麼。

53這些主機始終是必需的：

55| 主機 | 連接埠 | 用途 |

56| :------------------------------------------------- | :------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

57| `api.anthropic.com` | 443、HTTPS；WSS 僅用於 SCM 連接器 | 執行器控制平面和工作階段串流、模型推理、功能旗標、產品分析、[JWKS](/docs/zh-TW/self-hosted-environments-identity)金鑰提取、提交簽名、設定 `--use-anthropic-git-proxy` 時的 Git 代理，以及設定 `--scm-connector-host` 時協調器的 [SCM 連接器](/docs/zh-TW/self-hosted-environments-reference#scm-connector-flags)隧道 |

58| 您的 Git 主機，例如 `github.com` 或您的 GitHub Enterprise 主機 | 443 或 22 | 複製和推送儲存庫。如果執行器使用 `--use-anthropic-git-proxy`（將 Git 流量路由通過 `api.anthropic.com`）則不需要。 |

60這些主機是否需要取決於您的配置：

62| 主機 | 連接埠 | 何時需要 |

63| :----------------------------------- | :-- | :------------------------------------------------------------------------------------------------------------------------------------ |

64| `downloads.claude.ai` | 443 | 在安裝時，當您使用原生安裝程式在主機上安裝或更新 Claude Code 時；`install.sh` 指令碼本身是從 `claude.ai` 提供的。在工作階段執行時，僅當工作階段從官方 Anthropic 市場安裝外掛程式時。 |

65| `storage.googleapis.com` | 443 | 在工作階段執行時，用於 `/plugin` 中顯示的外掛程式安裝計數和中繼資料。 |

66| `code.claude.com` 和 `claude.com` | 443 | 內置 claude-code-guide 代理的文件查詢和工作階段期間預先批准的 WebFetch 請求。阻止這些主機只會影響文件查詢。 |

67| `*.frame.claudeusercontent.com` | 443 | 僅當[工件工具](/docs/zh-TW/artifacts#availability)對您組織中的工作階段可用時；預設值因方案而異，根據那裡的可用性表。在執行器上設定 `CLAUDE_CODE_DISABLE_ARTIFACT=1` 以保持工具禁用，無論組織設定如何。 |

68| `registry.npmjs.org` | 443 | 當工作階段安裝外掛程式時，用於提取 npm 源外掛程式套件和安裝外掛程式的 Node.js 依賴項，或當 `npx` 啟動的 MCP 伺服器執行時 |

69| `http-intake.logs.us5.datadoghq.com` | 443 | Anthropic 操作指標。僅當設定 `CLAUDE_CODE_BYOC_ENABLE_DATADOG=1` 時；在自託管環境中預設關閉。 |

70| `browser-intake-us5-datadoghq.com` | 443 | Anthropic 錯誤報告上傳，僅在為工作階段帳戶啟用[錯誤報告](/docs/zh-TW/data-usage#telemetry-services)時發送。由 `DISABLE_ERROR_REPORTING=1` 或 `DISABLE_TELEMETRY=1` 抑制。 |

72執行器不會到達 `statsig.anthropic.com`、`*.sentry.io`、`claude.ai` 或 `platform.claude.com`。這些主機出現在一些較舊的企業網路檢查清單中，但您不需要為執行器或工作階段流量允許列表它們：功能旗標提取進入 `api.anthropic.com`，執行器使用環境祕密而不是互動式 OAuth 進行身份驗證。兩個主機端流確實到達 `claude.ai`，因此從其出站流量允許的主機執行它們，而不是擴大工作階段容器出站流量：單行安裝程式在安裝時從 `claude.ai` 提取 `install.sh`，互動式 `claude auth login`（[引導式設定](/docs/zh-TW/self-hosted-environments-quickstart#set-up-an-environment-and-runner)、`doctor` 的已登入模式和 [CI 分派](/docs/zh-TW/self-hosted-environments-testing#authenticate-from-ci)使用）通過 `claude.ai`、`claude.com` 和 `platform.claude.com` 登入。`mcp-proxy.anthropic.com` 也不是必需的：自託管工作階段不使用它，當為您的組織啟用時，將您的組織 claude.ai 連接器傳遞到工作階段通過 `api.anthropic.com` 路由。請參閱 [MCP 伺服器](/docs/zh-TW/self-hosted-environments-configuration#mcp-servers)。

74<h3 id="default-deny-egress">

75 預設拒絕出站流量

76</h3>

78在網路區段或命名空間中部署執行器和工作階段容器，其出站流量限制為[網路要求表](#network-requirements)中的主機、您的 Git 主機和工作階段需要到達的特定內部服務。該產品無法驗證或強制執行此操作，因此在每個環境上的您自己的網路邊界應用它。工作階段程式碼是模型導向的，可以嘗試連接到任意主機；網路層的預設拒絕出站流量限制這些嘗試可以到達的位置。這無論權限模式如何都適用：預設預先批准的工具集已包括 `Bash`，因此 shell 出站流量在沒有[自動模式](/docs/zh-TW/self-hosted-environments-configuration#permissions-and-tool-approval)的情況下執行而不提示。

80有關每個工作階段發出的遙測詳細資訊以及如何關閉它，請參閱[遙測](/docs/zh-TW/self-hosted-environments-reference#telemetry)。

82<h3 id="authenticate-to-an-egress-proxy">

83 向出站代理進行身份驗證

84</h3>

86某些企業出站代理在每個連接上需要 `Proxy-Authorization` 標頭。該標頭中的令牌通常輪換得太快，無法寫入您在 `HTTPS_PROXY` 中設定的代理 URL。像往常一樣將 `HTTPS_PROXY` 或 `HTTP_PROXY` 設定為您的代理 URL，然後設定 `--proxy-authorization-command` 或 `--proxy-authorization-file` 以告訴執行器從何處讀取標頭值。兩個旗標都需要 Claude Code v2.1.238 或更新版本。

88<h4 id="choose-where-the-proxy-authorization-value-comes-from">

89 選擇 `Proxy-Authorization` 值的來源

90</h4>

92選擇與您如何產生 `Proxy-Authorization` 令牌相符的旗標：

94* **[`--proxy-authorization-command <command>`](/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags)**：為您按需生成的令牌選擇此項。執行器執行 shell 命令並使用其修剪的 stdout 作為標頭值，例如 `Bearer <token>`。

95* **[`--proxy-authorization-file <path>`](/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags)**：為另一個程序在原位輪換的令牌選擇此項。執行器讀取檔案並使用其修剪的內容作為標頭值。

97<h4 id="configurations-the-runner-refuses-to-start-with">

98 執行器拒絕啟動的配置

99</h4>

100

101每個旗標也有環境變數形式，在[執行器 CLI 旗標參考](/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags)中列在其旁邊。在執行器聯繫您的代理或控制平面之前，它檢查旗標及其變數，並在三種情況下拒絕啟動：

102

103* **兩個旗標都設定**：一個旗標加上另一個旗標的環境變數計為設定兩個。

104* **沒有代理 URL**：`HTTPS_PROXY` 和 `HTTP_PROXY` 都不包含 `http://` 或 `https://` URL。執行器以大寫或小寫讀取兩個變數，不查詢 `ALL_PROXY`。

105* **任一旗標傳遞給協調器子命令**：`self-hosted-runner orchestrator` 不接受旗標或其環境變數。改為將旗標傳遞給協調器啟動的每個執行器。

106

107<h4 id="what-the-runner-changes-while-a-proxy-authorization-flag-is-set">

108 設定代理授權旗標時執行器更改的內容

109</h4>

110

111設定任一旗標後，執行器啟動自己的偵聽器並通過該偵聽器發送來自自己、其生命週期鉤子和其工作階段的代理流量。偵聽器在前往您的代理的途中添加 `Proxy-Authorization` 標頭。

112

113* **偵聽器**：偵聽器是 `127.0.0.1` 上的轉發代理。執行器在向控制平面註冊之前啟動偵聽器，如果偵聽器無法啟動則在啟動時退出。

114* **代理變數**：執行器重寫您設定的 `HTTPS_PROXY` 和 `HTTP_PROXY` 中的任一個，使其指向偵聽器。該重寫的值到達執行器本身、其生命週期鉤子和它執行的每個工作階段。

115* **令牌輪換**：輪換的令牌無需重新啟動即可生效。對於偵聽器打開到您的代理的每個連接，執行器再次執行您的命令或讀取您的檔案並將結果添加為標頭。

116* **工作階段環境**：工作階段僅通過偵聽器到達您的代理。在每個工作階段的環境中，執行器移除 `ALL_PROXY`、移除您未設定的 `HTTPS_PROXY` 或 `HTTP_PROXY` 的任何拼寫，並將 `NO_PROXY` 固定到執行器自己的值。

117* **日誌**：執行器永遠不會記錄標頭值。

118

119<h2 id="configure-git">

120 配置 Git

121</h2>

122

123執行器管理儲存庫簽出但預設不配置 Git 身份或認證。您控制執行器的映像和程序環境，因此您控制 Git 配置。選擇兩種方法之一：

124

125* **讓執行器配置 Git**：使用 `--configure-git` 啟動執行器，以使其寫入 Anthropic 託管工作階段使用的相同身份和提交簽名配置

126* **在映像中提供 Git 配置**：自己設定身份和推送認證，例如在您自己的機器人身份下提交

127

128執行器主機上的 Git 版本下限：[`--configure-git`](#let-the-runner-configure-git) SSH 提交簽名需要 Git 2.34 或更新版本，[`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy) 需要 2.32 或更新版本，從 [`--push-outcome-on-release`](/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags) 推送的分支恢復工作階段需要 2.29 或更新版本。如果您省略所有三個並自己管理 Git 身份，Git 2.24 就足夠了。

129

130<h3 id="let-the-runner-configure-git">

131 讓執行器配置 Git

132</h3>

133

134使用 `--configure-git` 啟動執行器，或設定 `SELF_HOSTED_RUNNER_CONFIGURE_GIT=1`，以使其在啟動時寫入全域 Git 配置：

135

136* `user.name = Claude` 和 `user.email = noreply@anthropic.com`，與 Anthropic 託管工作階段相符

137* SSH 格式提交和標籤簽名，通過執行器管理的填充程式路由，該填充程式使用工作階段自己的認證通過 Anthropic 的簽名服務簽名每個提交。簽名可在 GitHub 上針對 Anthropic 的已發佈 SSH 簽名金鑰進行驗證。

138* `push.negotiate = true`，因此 Git 在打包推送之前詢問您的 Git 主機它已經擁有哪些提交。需要 Claude Code v2.1.257 或更新版本。

139* `core.hooksPath` 指向執行器管理的鉤子目錄。其 `commit-msg` 和 `prepare-commit-msg` 鉤子為每個提交添加 `Co-authored-by:` 預告片，用於工作階段的建立者，從 [`CCR_SESSION_ACCOUNT_EMAIL`](/docs/zh-TW/self-hosted-environments-configuration#wrapper-scripts) 構建，當該變數未設定時省略。如果您的映像已設定 `core.hooksPath`，執行器保留您的設定，跳過安裝這些鉤子，並列印 `[runner:git]` 警告。

140

141提交簽名需要 Git 2.34 或更新版本；執行器在啟動時檢查並在您的 Git 較舊時以錯誤退出。此旗標不配置推送認證，您仍在映像中提供。

142

143<h3 id="ship-git-config-in-your-image">

144 在映像中提供 Git 配置

145</h3>

146

147Git 身份對任何提交都是必需的。在您的 Dockerfile 中系統範圍設定它，以便配置無論執行器程序以哪個使用者身份執行都適用：

148

149```dockerfile theme={null}

150RUN git config --system user.name "Claude" && \

151 git config --system user.email "noreply@anthropic.com"

152```

153

154沒有身份，`git commit` 失敗並顯示 `Please tell me who you are`，工作階段無法取得進展。您可以改用自己的機器人身份；執行器不會覆蓋這些值。

155

156不要將長期或廣泛範圍的推送認證烘焙到共享執行器映像中：映像中的認證可用於映像執行的每個工作階段，無論誰啟動它。相反，使用工作階段 JWT 從您的[包裝器指令碼](/docs/zh-TW/self-hosted-environments-configuration#wrapper-scripts)按工作階段薄荷短期、最小範圍的令牌，使用從工作階段 JWT 解碼的工作階段建立者的身份。將其與臨時的每個工作階段容器配對，這需要 `--capacity 1`，因此沒有認證超過薄荷它的工作階段；請參閱[強化部分](#harden-your-deployment)。

157

158如果您必須在映像級別配置推送認證，例如對於唯讀部署金鑰，請盡可能緊密地限制它們：

159

160* SSH 部署金鑰限制為一個儲存庫，帶有 `url.<base>.insteadOf` 重寫

161* 返回最小範圍令牌的 `credential.helper`

162* `GIT_SSH_COMMAND` 指向狹隘範圍的金鑰

163

164您配置的任何機制都必須無需提示即可工作，因為執行器的內置複製和提取禁用 Git、SSH 和 Git Credential Manager 否則會顯示的提示：

165

166* 執行器設定 `GIT_TERMINAL_PROMPT=0`，因此 Git 不會要求使用者名稱或密碼。

167* 執行器使用 `BatchMode=yes` 執行 SSH，附加到您的 `GIT_SSH_COMMAND`（如果您設定了），因此 SSH 不會要求密碼短語或主機確認。

168* 執行器設定 `GCM_INTERACTIVE=never`，因此 Git Credential Manager 不會打開登入對話框。

169* 執行器清除 `core.askPass`，因此如果您使用 askpass 幫助程式，請改為通過 `GIT_ASKPASS` 環境變數設定它。

170

171如果您的 Git 主機拒絕認證，或您沒有配置認證，執行器會重試幾次，然後失敗儲存庫準備。執行器不會將這些設定傳遞到工作階段的環境中。

172

173如果簽出目錄由與執行器程序不同的 uid 擁有，Git 拒絕對其進行操作；添加 `safe.directory`：

174

175```dockerfile theme={null}

176RUN git config --system --add safe.directory '*'

177```

178

179<h3 id="use-the-anthropic-git-proxy">

180 使用 Anthropic Git 代理

181</h3>

182

183使用 `--use-anthropic-git-proxy` 啟動執行器，或設定 `CLAUDE_RUNNER_USE_GIT_PROXY=1`，以使其通過 Anthropic 的 Git 代理複製，使用工作階段自己的短期令牌進行身份驗證。對於普通使用者工作階段，代理使用為工作階段建立者儲存的 GitHub 或 GitHub Enterprise OAuth 令牌；對於機器人和代理工作階段，它使用您的組織的 GitHub App 安裝令牌。無論哪種方式，執行器映像都不需要任何 Git 認證：沒有 SSH 金鑰、沒有認證幫助程式、沒有 `.netrc`。這是 Anthropic 託管環境使用的相同身份驗證路徑。

184

185代理需要 `--capacity 1`，因為代理 URL 是每個工作階段的，Git 2.32 或更新版本，因為較舊的 Git 忽略代理用來隔離工作階段的配置機制。如果任一要求未滿足，執行器拒絕啟動。因為代理從 Anthropic 端提取，您的 Git 主機必須可從 Anthropic 基礎設施到達，與 Anthropic 託管工作階段相同的要求；對於僅在您的網路內可路由的 Git 主機，改用 [`checkout` 生命週期鉤子](/docs/zh-TW/self-hosted-environments-configuration#checkout)。每個執行器程序一次處理一個工作階段，因此執行更多副本以實現並行性。啟用代理後，`--git-host-rewrite` 和 `--git-ssh-rewrite` 無效：代理 URL 指向 `api.anthropic.com`，而不是您的 Git 主機。

186

187執行器也會在註冊時向 Anthropic 報告選擇加入，在啟動時列印 `Registering as opted in to Anthropic-managed git (--use-anthropic-git-proxy)`。選擇加入執行器上的每個工作階段隨後使用 Anthropic 管理的 Git 或每個工作階段的代理 URL。當工作階段使用每個工作階段的代理 URL 時，執行器記錄一行 `[runner:warn]` 說明這一點。

188

189<h3 id="rewrite-git-urls-for-private-networks">

190 為私有網路重寫 Git URL

191</h3>

192

193儲存庫 URL 從控制平面作為 HTTPS 到達，帶有您的 Git 主機的主機名；對於 GitHub Enterprise，這是您在 claude.ai 上的 Claude Code 管理設定中為 [GitHub Enterprise 整合](/docs/zh-TW/github-enterprise-server)配置的主機名。兩個可重複的旗標在複製之前重寫這些 URL：

194

195* `--git-host-rewrite <from>=<to>`：用於分割視界 DNS，其中 Anthropic 通過外部主機名到達您的 Git 主機，但執行器必須使用內部主機名

196* `--git-ssh-rewrite <host>`：用於僅接受 SSH 的 Git 主機，將 `https://<host>/owner/repo` 重寫為 `git@<host>:owner/repo`

197

198主機重寫首先執行，因此如果您需要兩者，請在 `--git-ssh-rewrite` 中列出內部主機名。為了完全控制簽出，使用 [`checkout` 生命週期鉤子](/docs/zh-TW/self-hosted-environments-configuration#checkout)。

199

200<h2 id="build-the-runner-image">

201 構建執行器映像

202</h2>

203

204Anthropic 不發佈預構建的執行器映像。在 `claude` 二進位檔案周圍構建您自己的，分層您的儲存庫需要的任何工具鏈：語言執行時、編譯器、套件管理器和 [MCP](/docs/zh-TW/mcp) 邊車。

205

206下面的配方使用 `--capacity 4`，因此一個容器服務來自同一鎖定所有者的最多四個並發工作階段。這不提供[強化部分](#harden-your-deployment)中的每個工作階段容器隔離：在將環境連接到生產系統之前，要麼以 `--capacity 1` 執行配方，每個工作階段一個容器，要麼使用[按需執行器](/docs/zh-TW/self-hosted-environments-configuration#on-demand-runners)，它也將環境祕密保留在執行工作階段的主機之外。

207

208此 Dockerfile 是一個最小的起點：

209

210```dockerfile theme={null}

211FROM debian:bookworm-slim

212ARG CLAUDE_CODE_VERSION

213RUN apt-get update && apt-get install -y --no-install-recommends git curl ca-certificates openssh-client \

214 && rm -rf /var/lib/apt/lists/*

215RUN curl -fsSL "https://downloads.claude.ai/claude-code-releases/${CLAUDE_CODE_VERSION:?set with --build-arg CLAUDE_CODE_VERSION}/linux-x64/claude" \

216 -o /usr/local/bin/claude && chmod +x /usr/local/bin/claude

217RUN git config --system user.name "Claude" \

218 && git config --system user.email "noreply@anthropic.com" \

219 && git config --system --add safe.directory '*'

220ENTRYPOINT ["claude"]

221```

222

223如果您的節點是 ARM，將 `linux-x64` 交換為 `linux-arm64`，或在 Alpine 等 musl 基礎映像上交換為 `linux-x64-musl` 或 `linux-arm64-musl`；請參閱 [Alpine Linux 設定](/docs/zh-TW/setup#alpine-linux-and-musl-based-distributions)以了解 musl 映像需要的額外套件。URL 是標準 Claude Code 發佈位置，因此您可以根據[二進位檔案完整性和程式碼簽名](/docs/zh-TW/setup#binary-integrity-and-code-signing)中描述的發佈的已簽名清單驗證下載的二進位檔案。使用 Claude Code 版本 2.1.224 或更新版本構建映像，然後將其推送到您的登錄檔並在下面的配方中引用它：

224

225```bash theme={null}

226docker build --build-arg CLAUDE_CODE_VERSION=2.1.224 -t <your-registry>/claude-runner:latest .

227```

228

229<h2 id="size-cpu-and-memory-for-sessions">

230 為工作階段調整 CPU 和記憶體大小

231</h2>

232

233為執行器執行的工作階段而不是執行器程序本身調整執行器的容器或主機大小。執行器本身輪詢工作、準備每個工作階段的簽出、執行您的[生命週期鉤子](/docs/zh-TW/self-hosted-environments-configuration#lifecycle-hooks)，以及啟動和監督工作階段程序。負載來自工作階段：每個都是 Claude Code 程序加上它啟動的任何內容，例如構建、測試套件、套件安裝和 [MCP 伺服器](/docs/zh-TW/mcp)。

234

235對於一個工作階段，從以下值開始，表示為 Kubernetes 請求和限制或您的平台的等效項，並將它們視為起點而不是要求：

236

237* **記憶體**：請求和限制各 4 GiB，滿足 Claude Code [系統要求](/docs/zh-TW/setup#system-requirements)中的 4 GB 最小值。保持兩者相等，以便調度器考慮容器的完整記憶體。當容器達到其記憶體限制時，核心會殺死其中的程序，這可能會結束工作階段中途。

238* **CPU**：2 個 CPU 的請求和 4 個 CPU 的限制，因此工作階段可以在構建期間突發超過請求。核心在其 CPU 限制處限制容器，而不是殺死其中的程序，因此限制處的工作階段執行速度較慢但保持執行。

239

240在 Kubernetes 容器規格中，使用以下 `resources` 塊設定這些起始值：

241

242```yaml theme={null}

243resources:

244 requests:

245 cpu: "2"

246 memory: 4Gi

247 limits:

248 cpu: "4"

249 memory: 4Gi

250```

251

252構建和測試通常是工作階段負載中最大和最可變的部分，因此執行您的儲存庫的代表性構建，測量其峰值 CPU 和記憶體，並提高任何在該峰值之上沒有為 Claude Code 程序留下空間的起始值。

253

254執行器使用 `--capacity` 來限制它一次執行多少個工作階段。它不在它們之間分割 CPU 或記憶體，因此執行器上的工作階段共享容器的 CPU 和記憶體。要限制一個工作階段的份額，從您的[包裝器指令碼](/docs/zh-TW/self-hosted-environments-configuration#wrapper-scripts)應用限制。因此，給一個容器什麼取決於它一次服務多少個工作階段：

255

256* **每個執行器一個工作階段**：給每個容器一個工作階段的值。在 `--capacity 1` 使用此調整大小，[強化部分](#harden-your-deployment)推薦，以及[按需執行器](/docs/zh-TW/self-hosted-environments-configuration#on-demand-runners)，您在工作流程的 [`spawn-runner` 鉤子](/docs/zh-TW/self-hosted-environments-configuration#the-spawn-runner-hook)提交的工作負載上設定值，例如 Kubernetes Job 的 pod 範本。

257* **每個執行器多個工作階段**：在 `--capacity` 高於 1 時，將一個工作階段的值乘以容量，因為最多那麼多工作階段可以在容器中同時執行。[Kubernetes](#kubernetes) 和 [Docker Compose](#docker-compose) 配方執行 `--capacity 4`，沒有 CPU 或記憶體限制，因此添加為您執行的容量調整大小的限制。

258

259<h2 id="kubernetes">

260 Kubernetes

261</h2>

262

263執行器預設在連接埠 8080 上提供 `GET /healthz`，可使用 `--health-port` 配置，因此 Kubernetes 探針無需額外設定即可工作。端點在程序活著時返回 `200`，因此下面的探針檢測死程序，而不是卡住的程序；要捕捉停止輪詢的執行器，請在 [`/metrics`](/docs/zh-TW/self-hosted-environments-reference#prometheus-metrics) 的 `last_poll_age_seconds` 系列上發出警報。下面的 Deployment 從 Kubernetes Secret 掛載環境祕密，將活躍度和就緒探針指向 `/healthz`，並設定 90 秒的終止寬限期。請參閱[關閉時序](#shutdown-timing)以了解為什麼寬限期很重要。

264

265清單在執行器容器上設定沒有 CPU 或記憶體 `resources`。添加為您執行的容量調整大小的塊，如[為工作階段調整 CPU 和記憶體大小](#size-cpu-and-memory-for-sessions)所述。

266

267```yaml theme={null}

268apiVersion: apps/v1

269kind: Deployment

270metadata:

271 name: claude-runner

272 namespace: claude-runners

273spec:

274 replicas: 3

275 selector:

276 matchLabels:

277 app: claude-runner

278 template:

279 metadata:

280 labels:

281 app: claude-runner

282 app.kubernetes.io/part-of: claude-code-self-hosted-runner

283 spec:

284 terminationGracePeriodSeconds: 90

285 containers:

286 - name: runner

287 image: <your-registry>/claude-runner:latest

288 args:

289 - self-hosted-runner

290 - --environment-secret-file

291 - /etc/claude/environment-secret

292 - --capacity

293 - "4"

294 volumeMounts:

295 - name: environment-secret

296 mountPath: /etc/claude

297 readOnly: true

298 ports:

299 - name: health

300 containerPort: 8080

301 readinessProbe:

302 httpGet:

303 path: /healthz

304 port: 8080

305 initialDelaySeconds: 5

306 periodSeconds: 10

307 livenessProbe:

308 httpGet:

309 path: /healthz

310 port: 8080

311 initialDelaySeconds: 30

312 periodSeconds: 30

313 volumes:

314 - name: environment-secret

315 secret:

316 secretName: claude-runner-environment-secret

317```

318

319上面的 Deployment 位於 `claude-runners` 命名空間中。首先建立命名空間：

320

321```bash theme={null}

322kubectl create namespace claude-runners

323```

324

325從保存您在管理 UI 的[**複製環境金鑰**步驟](/docs/zh-TW/self-hosted-environments-quickstart#set-up-an-environment-and-runner)中複製的值的本地檔案建立支持 Secret，以便祕密永遠不會出現在您的 shell 歷史記錄中。執行 `(umask 077 && cat > ./environment-secret)`，貼上祕密，按 Enter，然後按 Ctrl-D。然後建立 Secret 並刪除檔案：

326

327```bash theme={null}

328kubectl create secret generic claude-runner-environment-secret -n claude-runners --from-file=environment-secret=./environment-secret

329```

330

331<h2 id="docker-compose">

332 Docker Compose

333</h2>

334

335下面的 Compose 服務在執行器退出時重新啟動它，涵蓋崩潰和清空後的正常退出。Docker 重新啟動原則重新啟動同一容器及其可寫層，因此執行器以重複使用的檔案系統而不是[強化姿態](#harden-your-deployment)推薦的新鮮檔案系統回來；為評估使用此配方，對於生產環境，要麼每次執行時重新建立容器，要麼使用執行此操作的協調器。

336

337```yaml theme={null}

338services:

339 claude-runner:

340 image: <your-registry>/claude-runner:latest

341 command:

342 - self-hosted-runner

343 - --environment-secret-file

344 - /run/secrets/environment-secret

345 - --capacity

346 - "4"

347 secrets:

348 - environment-secret

349 restart: always

350 stop_grace_period: 90s

351

352secrets:

353 environment-secret:

354 file: ./environment-secret

355```

356

357<h2 id="shutdown-timing">

358 關閉時序

359</h2>

360

361在 `SIGTERM` 上，執行器停止接受新工作，除非您設定 [`--defer-shutdown-max-min`](#defer-the-drain-past-the-first-signal)，否則等待最多 `--drain-wait-sec`（預設為零）以完成進行中的轉向，終止每個工作階段的程序樹，並執行 [`post-session` 生命週期鉤子](/docs/zh-TW/self-hosted-environments-configuration#post-session)。該程序樹包括 Claude 仍在工作階段中執行的命令。

362

363完整清空路徑需要最多 `--session-stop-grace-sec` + `--drain-wait-sec` + `--post-session-hook-timeout-sec`，加上 15 秒的固定程序清理開銷，加上設定 [`--push-outcome-on-release`](/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags) 時的 30 秒。在預設值下為 80 秒，執行器在啟動時記錄總計。工作階段在此一個預算下並行清空，因此總計不會隨 `--capacity` 增長。

364

365在預設 `--drain-wait-sec 0` 下，滾動重新啟動中斷進行中的轉向；每個工作階段在另一個執行器上恢復，丟失未推送的工作，如[已知問題](#additional-limitations)下所述。設定 `--drain-wait-sec`，並提高寬限期以匹配，以讓轉向首先完成。

366

367在整個路徑中，執行器以零容量持續向控制平面進行心跳，因此工作階段租約不會過期並在 `post-session` 鉤子仍在寫出未提交的工作時重新排隊到另一個執行器。心跳在執行器取消註冊之前停止。

368

369在主機停止執行器之前，至少給執行器它在啟動時記錄的總計。您在哪裡設定這取決於您的主機如何停止：

370

371* **使用 `SIGTERM` 寬限期**：在 Kubernetes 上設定 `terminationGracePeriodSeconds`，在 Docker Compose 上設定 `stop_grace_period`，或您的協調器的等效項至少為該總計。Kubernetes 預設 30 秒短於執行器的清空路徑，因此 Kubernetes 在執行器完成清空之前停止 pod。

372* **使用 [`--retire-at`](/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags)**：在退休時間和主機停止時間之間調整邊距以涵蓋典型轉向、加上[執行器生命週期](/docs/zh-TW/self-hosted-environments#runner-lifecycle)描述的背景任務保持、加上該相同總計。在每次啟動時計算退休時間，例如 `date +%s` 加上執行器的預期生命週期。

373* **使用 [`--defer-shutdown-max-min`](#defer-the-drain-past-the-first-signal)**：向清空路徑總計添加兩個更多部分。第一個是您配置的分鐘數。第二個是[延遲清空超過第一個信號](#defer-the-drain-past-the-first-signal)描述的發佈後寬限期，預設值為 75 秒。設定旗標後，執行器也在啟動時列印組合圖形，在清空路徑總計之後。

374

375<h3 id="defer-the-drain-past-the-first-signal">

376 延遲清空超過第一個信號

377</h3>

378

379如果您想要重新啟動的執行器繼續服務它持有的工作階段最多 `n` 分鐘，而不是在第一個信號上清空它們，請設定 [`--defer-shutdown-max-min <n>`](/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags)。在第一個 `SIGTERM` 或 `SIGINT` 上，執行器停止接受新工作並繼續服務它持有的工作階段。它保持輪詢，以便控制平面不會重新排隊這些工作階段。需要 Claude Code v2.1.238 或更新版本。

380

381<h4 id="what-happens-to-the-sessions-the-runner-holds-after-the-first-signal">

382 第一個信號後執行器持有的工作階段會發生什麼

383</h4>

384

385在信號後的前兩個階段中，執行器釋放工作階段，釋放的工作階段在其使用者發送下一條訊息時在新執行器上恢復。從第一個信號開始計數，執行器通過三個階段移動：

386

387* **在前 `n` 分鐘內**：執行器正常服務其工作階段並繼續強制執行 `--startup-timeout-min` 和 `--kill-session-after-min`。如果您也設定 [`--release-idle-session-min`](/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags)，執行器釋放任何使用者已閒置該長時間的工作階段；沒有它，閒置工作階段保留在執行器上。

388* **當 `n` 分鐘用完時**：執行器釋放它仍然持有的每個工作階段，閒置或不閒置。執行器等待中途轉向的轉向結束，並為該轉向的背景任務再等待最多 60 秒，然後釋放該工作階段。

389* **當發佈後寬限期用完時**：執行器清空它仍然持有的任何工作階段，控制平面立即將每個清空的工作階段重新排隊到另一個執行器。發佈後寬限期在 `n` 分鐘用完時開始，預設值為 75 秒。如果您將 `--drain-wait-sec` 設定為 60 秒以上，發佈後寬限期改為 `--drain-wait-sec` 加 15 秒。

390

391在任何階段，執行器在不持有任何工作階段時立即以 0 退出。第二個信號縮短階段：執行器立即清空，就像在沒有 `--defer-shutdown-max-min` 的第一個信號上一樣。一旦清空進行中，下一個信號強制退出執行器。這無論第二個信號還是發佈後寬限期用完啟動清空。

392

393<h4 id="size-the-stop-timeout">

394 調整停止超時大小

395</h4>

396

397給您的主機停止超時至少三個部分的總和：您配置的 `n` 分鐘、發佈後寬限期和[關閉時序](#shutdown-timing)描述的完整清空路徑。使用預設設定發佈後寬限期為 75 秒，清空路徑為 80 秒，因此允許 `n` 分鐘加 155 秒。執行器在設定 `--defer-shutdown-max-min` 時在啟動時列印此總和。

398

399如果停止超時在執行器完成之前用完，主機會殺死執行器。它仍然持有的工作階段不會獲得 `post-session` 鉤子。執行器不取消註冊，控制平面約一分鐘後重新排隊工作階段。如果您無法給停止超時該總和，請保留 `--defer-shutdown-max-min` 未設定，以便執行器改為在第一個信號上清空。

400

401<h3 id="what-reaches-a-running-post-session-hook">

402 什麼到達執行中的 post-session 鉤子

403</h3>

404

405`post-session` 鉤子和 Claude 工作階段子項各自在自己的 POSIX 程序組中執行，與執行器的分開，因此停止機制以不同方式到達它們：

406

407* **執行器已在清空時的 `SIGTERM`**：立即強制退出執行器，跳過清空路徑的任何剩餘部分。沒有 [`--defer-shutdown-max-min`](#defer-the-drain-past-the-first-signal)，這是執行器接收的第二個 `SIGTERM`。沒有信號到達中途執行的 `post-session` 鉤子，因此在採用孤兒的裸主機上，它自己完成，但不受監督：其超時預算不再適用，寫入關閉的日誌管道可以用 `SIGPIPE` 殺死它，因此需要在那裡存活強制退出的鉤子應將其自己的輸出重定向到檔案。在此頁面上的容器配方中，執行器是容器的 PID 1，其退出結束容器，在 systemd 的預設 `KillMode=control-group` 下，cgroup 範圍的殺死到達鉤子，如**Cgroup 範圍的殺死**項所述；在兩者中，將強制退出視為對鉤子致命並改為依賴寬限期。

408* **程序組範圍的信號**，例如包裝器指令碼中的 `kill -- -<pid>`、shell 工作控制或組範圍的看門狗：到達執行器和中途 `checkout` 鉤子子程序，該子程序故意保持組附加，但不是中途執行的 `post-session` 鉤子或工作階段子項。

409* **Cgroup 範圍的殺死**，例如 systemd 的預設 `KillMode=control-group` 或 `terminationGracePeriodSeconds` 過期時 Kubernetes 傳遞到整個容器的 `SIGKILL`：到達所有內容，包括鉤子。程序組隔離不保護這些，這就是為什麼寬限期必須涵蓋完整清空路徑。

410* **鉤子自己的超時**：當鉤子超過 `--post-session-hook-timeout-sec` 時，執行器向鉤子的整個程序組發送 `SIGTERM`，然後 2 秒後發送 `SIGKILL`，因此鉤子分叉的工作者（例如 tar、rsync 或 git）與包裝器 shell 一起終止，而不是作為孤兒存活。執行器的監督在鉤子的 stdio 關閉後結束：重定向其自己的輸出到檔案並超過 `SIGTERM` 階段的工作者超出執行器的範圍。

411

412當清空開始時，以及在強制退出時，執行器記錄仍在執行多少 `post-session` 鉤子，因此您可以區分安靜清空和中途快照的清空。

413

414<h2 id="keep-the-base-directory-and-capacity-identical-across-runners">

415 在執行器之間保持基本目錄和容量相同

416</h2>

417

418如果執行器在工作階段中途死亡，伺服器重新排隊工作階段，環境中的另一個執行器拾取它。該執行器從其自己的 `--base-dir` 和 `--capacity` 派生簽出路徑：`--capacity 1` 直接在 `--base-dir` 下簽出，`--capacity` 高於 1 改用每個工作階段的工作樹。當同一環境中的執行器對任一旗標使用不同的值時，恢復的工作階段的工作目錄會更改，代理之前記錄的絕對路徑（在編輯、工具呼叫或其自己的筆記中）指向不再存在的位置。

419

420在環境中的每個執行器上使用相同的 `--base-dir` 和 `--capacity`，並且不要使用每個主機的值，例如執行個體 ID 或主機名。

421

422基本目錄預設為 `/workspace`，除了 [`--base-dir` 參考行](/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags)記錄的例外。執行器需要對其的寫入存取。在啟動時，在註冊之前，執行器建立目錄並確認它可以寫入它，當它無法時以 `cannot create or write to base directory` 退出。以 root 身份啟動的執行器自己建立預設 `/workspace`。對於非 root 執行器，在啟動執行器之前建立目錄並給執行器的使用者所有權，或將 `--base-dir` 指向該使用者已擁有的目錄。

423

424<h2 id="reuse-a-pre-warmed-checkout">

425 重複使用預熱簽出

426</h2>

427

428對於大型儲存庫，複製可能主導工作階段啟動。在 `--capacity 1` 且沒有 [`checkout` 鉤子](/docs/zh-TW/self-hosted-environments-configuration#checkout) 的情況下，執行器在 `<base-dir>/<repo-owner>/<repo>` 保持每個儲存庫的一個規範複製並在工作階段之間重複使用它：它提取請求的 ref、分離 `HEAD` 並硬重置為它，當變化不多時幾乎是瞬間的。要跳過冷複製，以兩種方式之一提供複製：

429

430* **在映像中複製**：在該路徑將複製構建到您的執行器映像中。每個新容器然後以預熱複製啟動，而不重複使用磁碟。

431* **在持久卷上複製**：在您使用 [`--lock-to-account`](/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags) 預鎖定到一個使用者帳戶的執行器上，將 `--base-dir` 指向持久卷，因此磁碟只服務該帳戶。預鎖定的執行器永遠不會拾取 Claude Tag 頻道工作階段，因此此選項不適用於服務它們的執行器。

432

433重複使用路徑做什麼和不保證什麼：

434

435* **任何複製形狀都有效**：路徑上的完整、淺或單分支複製按原樣使用。執行器在提取到現有複製時永遠不會傳遞 `--depth`，因此完整預熱保持其完整歷史記錄，淺複製保持淺。`CLAUDE_RUNNER_FETCH_DEPTH`（`full`、`0` 或數字；預設 50）僅控制執行器在不存在複製時進行的冷複製。

436* **追蹤的變化重置，未追蹤的檔案持續**：每個工作階段從硬重置開始，該重置擦除前一個工作階段的追蹤修改，但執行器永遠不執行 `git clean`，因此鎖定所有者的早期工作階段的未追蹤檔案保留在樹中。

437* **使用 Git 代理，重置變成簽出**：使用 [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy)，執行器在每個工作階段之前清理複製的 `.git/`，保持物件存儲、refs 和淺狀態，但刪除索引，因此每個工作階段支付完整工作樹簽出而不是幾乎瞬間的重置；它仍然永遠不重新複製。子模組預熱在代理下不受支援。

438* **長複製不需要解決方法**：執行器使用 120 秒無進度看門狗和 30 分鐘硬上限限制每個 Git 操作，而不是平面超時，因此保持報告進度的慢冷複製完成。

439

440<h2 id="pin-the-version">

441 固定版本

442</h2>

443

444每個工作階段的子 Claude Code 程序執行執行器自己的二進位檔案，執行器在它生成的工作階段內關閉自動更新，因此每個工作階段執行您在主機上安裝或構建到映像中的版本。主機級更新在執行器下次啟動時生效。

445

446* **將群保持在一個版本上**：使用固定版本構建映像，或在裸主機上安裝特定版本並[禁用自動更新](/docs/zh-TW/setup#disable-auto-updates)

447* **升級**：安裝較新版本或重建映像，然後重新啟動執行器

448* **外掛程式**：外掛程式市場也不自動更新；在執行器的環境中設定 `FORCE_AUTOUPDATE_PLUGINS=1` 以讓外掛程式自動更新，同時二進位檔案保持固定

449

450<h2 id="scale-the-fleet">

451 擴展群

452</h2>

453

454您的協調器決定何時添加或移除執行器。由於[每個執行器一個所有者鎖](/docs/zh-TW/self-hosted-environments#runner-lifecycle)，最小副本計數是您期望同時活躍的使用者和 Claude Tag 代理的數量；`--capacity` 控制一個所有者的工作階段內的並行性，而不是跨所有者。

455

456有兩種擴展方法可用：

457

458* **固定群**：執行靜態執行器副本集並在每個執行器服務的 [Prometheus 指標](/docs/zh-TW/self-hosted-environments-reference#prometheus-metrics)上擴展

459* **按需執行器**：執行 `claude self-hosted-runner orchestrator` 子命令，它輪詢 Anthropic 以查找沒有可用執行器排隊的工作階段，並調用您的 `spawn-runner` 鉤子為每個工作階段啟動一個。請參閱[按需執行器](/docs/zh-TW/self-hosted-environments-configuration#on-demand-runners)。

460

461<h2 id="known-issues-and-limitations">

462 已知問題和限制

463</h2>

464

465以下是此版本中的限制，其中存在解決方法。

466

467<h3 id="connector-traffic-leaves-your-network">

468 連接器流量離開您的網路

469</h3>

470

471Anthropic 從其自己的基礎設施而不是從您的執行器呼叫連接器工具。連接器工具是 claude.ai 連接器，例如 GitHub、Slack 和 Linear。當 Claude 在自託管工作階段中使用連接器時，該流量通過 `api.anthropic.com` 而不是源自您的網路邊界內。

472

473要將連接器保留在自託管工作階段之外，使用 [`allowedMcpServers` 和 `deniedMcpServers` 原則設定](/docs/zh-TW/managed-mcp#policy-based-control-with-allowlists-and-denylists)進行篩選。Claude Code 將這些設定應用於 Anthropic 傳遞的連接器以及您從執行器主機播種的伺服器和使用者添加的伺服器，因此如果您為其他伺服器部署允許列表，Claude Code 也會阻止傳遞的連接器。要在 URL 型允許列表旁邊保持連接器可用，添加與傳遞連接器的 Anthropic 代理路徑相符的項目：

474

475* `https://api.anthropic.com/v2/ccr-sessions/*`

476* `https://api.anthropic.com/v1/code/sessions/*`

477* `https://api.anthropic.com/v1/code/mcp/*`

478

479如果工具流量必須保留在您的網路內，改為在執行器映像上執行等效工具作為本地 MCP 伺服器。請參閱 [MCP 伺服器](/docs/zh-TW/self-hosted-environments-configuration#mcp-servers)。

480

481<h3 id="some-sessions-don’t-count-as-idle">

482 某些工作階段不計為閒置

483</h3>

484

485持有永遠不完成的背景任務的工作階段不計為閒置，因此 `--release-idle-session-min` 不會釋放該工作階段的插槽。等待從執行中工具呼叫內部請求的批准的工作階段也不計為閒置。始終將 `--kill-session-after-min` 與其一起設定作為硬後擋，以便沒有工作階段可以無限期地持有插槽。

486

487`--kill-session-after-min` 是失控工作階段的後擋。在 v2.1.260 或更新版本上的執行器上，達到限制的工作階段不會立即終止。執行器給它一個寬限窗口，預設 15 分鐘，您可以使用 [`SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS`](/docs/zh-TW/self-hosted-environments-reference#environment-variable-only-settings) 更改：

488

489* 如果工作階段等待其使用者，或其轉向已結束並且它僅持有背景任務，執行器立即釋放它。工作階段在其使用者發送下一條訊息時恢復。

490* 如果轉向仍在執行，執行器等待轉向完成，或工作階段下一次等待其使用者，然後釋放它。

491* 如果工作階段在寬限窗口結束時仍在執行器上，執行器終止它，任何執行中轉向的工作都會丟失。等待從執行中工具呼叫內部請求的批准的轉向是工作階段超過窗口的一種方式。

492

493釋放的工作階段從新複製恢復，因此它未推送的工作無論如何都消失了；請參閱[恢復的工作階段丟失未推送的工作](#additional-limitations)。在 v2.1.260 之前，執行器在限制處終止每個工作階段，最多等待寬限窗口以完成執行中的轉向。

494

495將該旗標設定為高於您預期的最長工作階段時間，例如 `--kill-session-after-min 480` 為 8 小時。要從進入閒置的對話中釋放插槽，改用 `--release-idle-session-min`。

496

497<h3 id="additional-limitations">

498 其他限制

499</h3>

500

501* **恢復的工作階段丟失未推送的工作**：當工作階段被釋放或其執行器重新啟動，使用者發送另一條訊息時，工作階段在新執行器上恢復，該執行器從其啟動分支再次複製儲存庫，因此工作階段未推送的工作消失。設定 [`--push-outcome-on-release`](/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags) 以使執行器在釋放之前進行最佳努力推送工作階段的結果分支，以便恢復的工作階段從這些提交開始；這保留已提交的工作，而不是髒工作樹。在啟用它之前，限制誰可以推送到源遠端上的 `claude/*` refs，例如使用分支規則集：在恢復時，執行器提取先前推送的分支而不驗證誰推送了它，因此任何有權推送到這些 refs 的人都可以將內容放入恢復的工作區。執行器也在恢復時丟棄每個工作階段的配置，意味著工作階段的 Claude 配置目錄和工作階段寫入的任何 shell 狀態；`--push-outcome-on-release` 不涵蓋這些。

502* **私有儲存庫無法在工作階段中途添加**：在自託管執行器上，在工作階段啟動後添加到工作階段的儲存庫不會使用認證複製，因此添加失敗。在建立工作階段時選擇工作階段需要的每個儲存庫。

503* **某些連接器不出現在自託管工作階段中**：您在 claude.ai Settings 中尚未連接的連接器不在自託管工作階段中列出，工作階段不會提示您連接它。首先在 Settings 中連接它，然後啟動新工作階段。將連接器添加到已執行的工作階段也不會使其工具可用於 Claude；啟動新工作階段以拾取新添加的連接器。

504

505<h3 id="report-an-issue">

506 報告問題

507</h3>

508

509對於自託管環境的問題，請聯繫您的 Anthropic 帳戶團隊。

510

511<h2 id="troubleshooting">

512 故障排除

513</h2>

514

515為了進行引導式診斷，在執行器主機上執行 doctor 子命令。doctor 子命令啟動互動式 Claude Code 工作階段，附加執行器的日誌和狀態。首先在該主機上使用 `claude auth login` 登入，以便工作階段可以查詢您的環境、其執行器和其排隊的工作階段。沒有該登入，例如當主機使用 API 金鑰進行身份驗證時，它限制為本地健康端點、指標和執行器的日誌，並且僅在您使用 `--log-file` 啟動執行器時讀取日誌。

516

517```bash theme={null}

518claude self-hosted-runner doctor

519```

520

521常見問題：

522

523* **執行器不出現在環境中**：確認主機可以通過 HTTPS 到達 `api.anthropic.com`，環境祕密是最新的，主機時鐘在真實時間的五分鐘內；更大的偏差導致身份驗證失敗。執行器在身份驗證失敗時記錄 `[runner:fatal]` 及拒絕原因。

524* **執行器在啟動時以 `cannot create or write to base directory` 退出**：執行器無法建立或寫入 `--base-dir`，預設為 `/workspace`。修復目錄的所有權或將 `--base-dir` 指向可寫路徑，如[在執行器之間保持基本目錄和容量相同](#keep-the-base-directory-and-capacity-identical-across-runners)中所述。如果執行器改為記錄 `[runner:fatal]` 說基本目錄檢查超時，目錄在掛起的 NFS 或 CSI 掛載上。檢查掛載健康而不是權限。執行器在打開 `--log-file` 之前將這兩個啟動失敗列印到 stderr，因此在終端或您的平台的容器日誌中尋找它們，而不是日誌檔案。在 v2.1.225 之前，執行器在啟動時沒有檢查基本目錄，此配置錯誤在拾取後失敗工作階段。

525* **工作階段保持排隊**：每個線上執行器可能被鎖定到不同的所有者。檢查每個執行器的 `claude_code_self_hosted_runner_locked_account` [指標](/docs/zh-TW/self-hosted-environments-reference#prometheus-metrics)或其 `[runner:health]` 日誌行的 `locked_account` 欄位以查看誰持有它。兩者僅在執行器被發佈攜帶 `act.email` 聲明的工作階段令牌後顯示所有者的電子郵件，Claude Tag 代理的工作階段永遠不會這樣做。沒有聲明，執行器不發出 `locked_account` 系列並記錄 `locked_account=yes`，這告訴您執行器被鎖定但不知道到哪個所有者。添加副本，或等待現有執行器清空並重新啟動。如果環境使用按需執行器，改為檢查協調器；請參閱[按需執行器](/docs/zh-TW/self-hosted-environments-configuration#on-demand-runners)。

526* **工作階段在拾取後立即失敗**：在 claude.ai/code 中打開工作階段以查看錯誤。最常見的原因是執行器映像中缺少 [Git 認證](#configure-git)和未安裝的構建工具。不可寫的基本目錄在啟動時停止執行器，而不是失敗工作階段。請參閱此清單中的**執行器在啟動時以 `cannot create or write to base directory` 退出**項。

527* **工作階段無法通過身份驗證出站代理到達網路**：當您使用 [`--proxy-authorization-command` 或 `--proxy-authorization-file`](#authenticate-to-an-egress-proxy) 設定的來源失敗、在 30 秒後超時或產生空值時，執行器以 `502 Bad Gateway` 回答該連接並記錄原因。執行器在該日誌中編輯命令的 stderr，永遠不記錄標頭值。使用 `--proxy-authorization-command`，自己在主機上執行命令以確認它在 stdout 上列印整個標頭值。如果執行器改為在啟動時以 `could not start the proxy-authorization listener` 退出，它無法打開其環回偵聽器。

528* **執行器記錄 `Poll failed` 行包含 `rejecting the malformed poll response`**：執行器接收到工作輪詢回應，其主體不是隊列的預期 JSON，最常見的原因是執行器和 `api.anthropic.com` 之間的某些內容（例如攔截代理或強制入口網站）以自己的頁面回答。執行器拒絕回應，在 `claude_code_self_hosted_runner_poll_errors_total` [指標](/docs/zh-TW/self-hosted-environments-reference#prometheus-metrics)的 `transport` 種類下計數，並在[工作階段生命週期](/docs/zh-TW/self-hosted-environments#session-lifecycle)中描述的失敗輪詢時間表上重試。執行器保持服務其活躍工作階段。配置代理以從 `api.anthropic.com` 無更改地傳遞回應。在 v2.1.246 之前，執行器將此類回應讀取為空工作隊列，這可能結束其活躍工作階段或使其退出。

529* **工作階段的分支不再存在於遠端**：對於工作階段僅從中讀取的 Git 來源，執行器跳過該來源並在其餘來源上繼續。對於工作階段推送結果的來源，已刪除的分支（通常因為它被合併並自動刪除）使工作階段失敗，並出現命名儲存庫和分支的錯誤，要求您恢復分支並重試。當跳過會使其沒有儲存庫時，執行器使用相同的錯誤使工作階段失敗。在 v2.1.228 之前，此類工作階段在空目錄中啟動。

530* **工作階段需要幾分鐘才能啟動**：初始複製通常主導。觀看 `claude_code_self_hosted_runner_session_init_duration_seconds` [指標](/docs/zh-TW/self-hosted-environments-reference#prometheus-metrics)以確認，並使用[預熱簽出](#reuse-a-pre-warmed-checkout)或較小的 `CLAUDE_RUNNER_FETCH_DEPTH` 切割複製。

531* **Pod 在清空中途被殺死**：將 `terminationGracePeriodSeconds` 提高到至少執行器在啟動時記錄的值。請參閱[關閉時序](#shutdown-timing)。

532

533日誌初始化後，執行器將其生命週期日誌（包括 `[runner:fatal]` 行）寫入 stdout，將調試輸出寫入 stderr，全部作為純文字行而不是 JSON。上面故障排除項中描述的啟動失敗在該點之前列印到 stderr。使用 `--log-file` 捕捉兩個流，這也讓 `self-hosted-runner doctor` 尾隨它們，或使用您的平台的日誌收集。每個工作階段的子程序寫入單獨的調試日誌。失敗時執行器保留日誌，在執行器日誌中列印日誌的路徑，並在 claude.ai/code 中的工作階段旁邊顯示日誌的尾部。

534

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

536 下一步

537</h2>

538

539* [自訂工作階段](/docs/zh-TW/self-hosted-environments-configuration)：包裝器指令碼、生命週期鉤子、按需執行器、MCP 伺服器和權限

540* [端到端測試](/docs/zh-TW/self-hosted-environments-testing)：在推廣新執行器映像之前從 CI 驗證它

541* [參考](/docs/zh-TW/self-hosted-environments-reference)：每個 CLI 旗標、環境變數和指標

self-hosted-environments-identity.md +270 −0 created

Details

1> ## Documentation Index

2> 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.

5# 在自託管環境中驗證工作階段身分

7> 驗證 CLAUDE_CODE_SESSION_ACCESS_TOKEN JWT，以便您網路上的服務可以信任來自自託管環境中工作階段的請求。

9<Note>

10 自託管環境在 Team 和 Enterprise 方案上處於公開測試版；[擁有者](/docs/zh-TW/cloud-environments#organization-shared-environments)可以在[**雲端環境**管理頁面](https://claude.ai/admin-settings/cloud-environments)上開啟**允許自託管環境**來啟用它們。本頁面涵蓋工作階段身分驗證；請參閱[快速入門](/docs/zh-TW/self-hosted-environments-quickstart)以了解設定，以及[部署到生產環境](/docs/zh-TW/self-hosted-environments-deploy)以了解艦隊配方。

11</Note>

13[自託管環境](/docs/zh-TW/self-hosted-environments)讓 [Claude Code on the web](/docs/zh-TW/claude-code-on-the-web) 工作階段在您操作的基礎設施上執行，而不是在 Anthropic 的基礎設施上執行。由於工作階段在您的網路內執行，Claude 可以直接呼叫您的內部服務。這些服務需要一種方式來確認請求來自您環境中的 Claude Code 工作階段，並識別建立該工作階段的使用者或服務身分。

15自託管環境中的每個工作階段都會在 `CLAUDE_CODE_SESSION_ACCESS_TOKEN` 環境變數中收到一個簽署的 JSON Web Token (JWT)。工作階段會像任何持有人認證一樣呈現令牌；例如，Claude 執行的指令碼可以使用 `curl -H "Authorization: Bearer $CLAUDE_CODE_SESSION_ACCESS_TOKEN"` 呼叫您的服務。Anthropic 簽署令牌並在公開 JWKS 端點發佈驗證金鑰。您的服務會擷取這些金鑰、驗證簽章，並讀取宣告以決定要授予什麼存取權限。

17<h2 id="the-session-token">

18 工作階段令牌

19</h2>

21在您編寫驗證程式碼之前，請了解令牌建立的內容以及您的 JWT 程式庫將看到的形狀。

23<h3 id="what-the-token-proves">

24 令牌證明的內容

25</h3>

27有效的令牌建立了一些事實，並刻意不建立其他事實：

29* **證明**：Anthropic 為特定環境中的特定工作階段簽發了令牌，以及工作階段的建立方式：由您組織中的使用者建立，或由您組織的服務身份建立，這是 [Claude Tag 頻道工作階段](https://claude.com/docs/claude-tag/concepts/agent-identity)的啟動方式

30* **不證明**：執行者主機上的哪個程序呈現它。令牌位於工作階段內的環境變數中，因此 Claude 執行的任何程式碼以及工作階段啟動的任何工具或 MCP 伺服器都可以讀取並呈現它。

32對您的服務有兩個後果：

34* 根據您的環境 ID（在[**雲端環境**管理頁面](https://claude.ai/admin-settings/cloud-environments)上與您的環境一起顯示的 `ccpool_...` 值）驗證 `aud` 聲明，以拒絕簽發給任何其他組織環境的令牌。

35* 將您從令牌衍生的認證範圍限制在單個編碼工作階段應該能夠執行的操作，而不是工作階段建立者可以執行的所有操作。請參閱[範圍衍生認證](#scope-derived-credentials)。

37<h3 id="token-format">

38 令牌格式

39</h3>

41`CLAUDE_CODE_SESSION_ACCESS_TOKEN` 的值具有 `sk-ant-cc-` 前綴，後面跟著標準的三部分 JWT：

43```text theme={null}

44sk-ant-cc-<base64url header>.<base64url payload>.<base64url signature>

45```

47在將值傳遞給 JWT 程式庫之前，請移除前綴。簽發給 Anthropic 託管雲端工作階段的令牌改為帶有 `sk-ant-si-` 前綴，並由不同的金鑰集簽署，因此拒絕任何不以 `sk-ant-cc-` 開頭的值。

49簽名演算法是 `ES256`，這是 P-256 曲線上的 ECDSA，使用 SHA-256。令牌標頭帶有一個 `kid`，用於識別 JWKS 中的哪個金鑰簽署了它。

51<h2 id="verify-the-token">

52 驗證令牌

53</h2>

55驗證在兩個地方之一執行。您網路上的服務根據 Anthropic 發佈的金鑰對令牌進行密碼學驗證，工作階段內的包裝指令碼可以改為使用執行者二進位檔案的內建解碼器。

57<h3 id="verify-the-token-from-your-service">

58 從您的服務驗證令牌

59</h3>

61Anthropic 在公開、未經驗證的端點發佈驗證金鑰：

63```text theme={null}

64https://api.anthropic.com/v1/code/.well-known/jwks.json

65```

67回應是標準的 [JSON Web Key Set](https://www.rfc-editor.org/rfc/rfc7517)。Anthropic 定期輪換簽署金鑰，輪換前的金鑰會在集合中保留足夠長的時間，以便它們簽署的令牌繼續驗證，因此不要固定單個金鑰。端點設定 `Cache-Control: public, max-age=300`，因此快取金鑰集並每五分鐘重新取得一次是安全的。

69根據這些檢查驗證每個傳入令牌：

71<Steps>

72 <Step title="檢查前綴">

73 如果值不以 `sk-ant-cc-` 開頭，則拒絕該值，然後移除該前綴。其餘部分是標準的緊湊 JWT。

74 </Step>

76 <Step title="驗證簽名">

77 取得 JWKS，選擇其 `kid` 與令牌標頭相符的金鑰，並驗證 `ES256` 簽名。拒絕其 `alg` 標頭不是 `ES256` 的令牌。如果令牌到達時帶有您快取的金鑰集中沒有的 `kid`，在拒絕它之前重新取得 JWKS 一次：輪換後，新令牌使用您快取的集合還沒有的金鑰簽署。

78 </Step>

80 <Step title="驗證簽發者">

81 如果 `iss` 不完全是 `ccr`，則拒絕令牌。

82 </Step>

84 <Step title="根據您的環境驗證對象">

85 `aud` 聲明是一個陣列。除非它包含您的環境 ID（形式為 `ccpool_...`），否則拒絕令牌。環境 ID 顯示在[**雲端環境**管理頁面](https://claude.ai/admin-settings/cloud-environments)上您環境的詳細對話框中，並在任何環境的工作階段令牌中顯示為 `ccr:pool_id` 聲明。此檢查是將令牌範圍限制在您的環境並拒絕簽發給其他組織的令牌的內容。

86 </Step>

88 <Step title="驗證角色">

89 如果 `ccr:role` 不完全是 `session_worker`，則拒絕令牌。為自託管環境簽發的其他令牌（例如環境祕密、執行者令牌和工作訂單）由相同的金鑰集簽署，但帶有不同的角色。

90 </Step>

92 <Step title="驗證過期">

93 如果 `exp` 在過去，則拒絕令牌。Anthropic 預設簽發工作階段令牌的生命週期為四小時，最多八小時。執行者在過期前重新整理令牌，並將新值推送到工作階段，因此 Claude 在重新整理後啟動的子程序會繼承它。因此，一個工作階段在其生命週期內可以向您的服務呈現多個不同的有效令牌。

94 </Step>

96 <Step title="讀取身份">

97 建立使用者的身份在 `act` 聲明中：`act.sub` 是他們的 Anthropic 使用者 ID，採用前綴形式 `user:<id>`，而 `act.email`（當建立表面記錄了一個時）是他們的電子郵件地址。您組織的服務身份建立的工作階段（包括 Claude Tag 頻道工作階段）改為在 `act.sub` 中帶有 `agent:` 主體，因此只有當 `act.sub` 帶有 `user:` 前綴時才將工作階段視為使用者建立的，而不是測試身份聲明是否不存在。請參閱[聲明參考](#claims-reference)以了解完整結構和平面重複聲明。

98 </Step>

99</Steps>

100

101這些檢查直接對應到標準 JWT 程式庫。下面的範例使用 [`jose`](https://www.npmjs.com/package/jose) 在 Node.js 中實現完整序列，它處理 JWKS 取得、快取和 `kid` 選擇，以及在 Python 中使用 [`PyJWT`](https://pyjwt.readthedocs.io/) 及其內建 JWKS 用戶端。

102

103<Tabs>

104 <Tab title="Node.js (jose)">

105 ```typescript theme={null}

106 import { createRemoteJWKSet, jwtVerify } from "jose";

107

108 const JWKS = createRemoteJWKSet(

109 new URL("https://api.anthropic.com/v1/code/.well-known/jwks.json")

110 );

111

112 const PREFIX = "sk-ant-cc-";

113 const EXPECTED_POOL_ID = "ccpool_...";

114

115 export async function verifySessionToken(raw: string) {

116 if (!raw.startsWith(PREFIX)) {

117 throw new Error("not a self-hosted runner session token");

118 }

119 const jwt = raw.slice(PREFIX.length);

120

121 const { payload } = await jwtVerify(jwt, JWKS, {

122 issuer: "ccr",

123 audience: EXPECTED_POOL_ID,

124 algorithms: ["ES256"],

125 });

126

127 if (payload["ccr:role"] !== "session_worker") {

128 throw new Error("token is not a session_worker token");

129 }

130

131 const act = payload.act as { email?: string; sub?: string };

132 return {

133 sessionId: payload["ccr:session_id"] as string,

134 poolId: payload["ccr:pool_id"] as string,

135 orgId: payload["ccr:org_id"] as string,

136 creatorEmail: act?.email,

137 creatorSub: act?.sub,

138 };

139 }

140 ```

141 </Tab>

142

143 <Tab title="Python (PyJWT)">

144 ```python theme={null}

145 import jwt

146 from jwt import PyJWKClient

147

148 JWKS_URL = "https://api.anthropic.com/v1/code/.well-known/jwks.json"

149 PREFIX = "sk-ant-cc-"

150 EXPECTED_POOL_ID = "ccpool_..."

151

152 jwks = PyJWKClient(JWKS_URL)

153

154

155 def verify_session_token(raw: str) -> dict:

156 if not raw.startswith(PREFIX):

157 raise ValueError("not a self-hosted runner session token")

158 token = raw.removeprefix(PREFIX)

159

160 signing_key = jwks.get_signing_key_from_jwt(token)

161 payload = jwt.decode(

162 token,

163 signing_key.key,

164 algorithms=["ES256"],

165 issuer="ccr",

166 audience=EXPECTED_POOL_ID,

167 )

168

169 if payload.get("ccr:role") != "session_worker":

170 raise ValueError("token is not a session_worker token")

171

172 act = payload.get("act") or {}

173 return {

174 "session_id": payload["ccr:session_id"],

175 "pool_id": payload["ccr:pool_id"],

176 "org_id": payload["ccr:org_id"],

177 "creator_email": act.get("email"),

178 "creator_sub": act.get("sub"),

179 }

180 ```

181 </Tab>

182</Tabs>

183

184<h3 id="verify-the-token-inside-the-session">

185 在工作階段內驗證令牌

186</h3>

187

188[包裝指令碼](/docs/zh-TW/self-hosted-environments-configuration#wrapper-scripts)在工作階段內執行，在 Claude 啟動之前。它們可以執行執行者二進位檔案的 `self-hosted-runner decode-token` 子命令，而不是呼叫 JWT 程式庫。子命令從位置引數、`CLAUDE_CODE_SESSION_ACCESS_TOKEN` 或管道 stdin 讀取令牌（按該順序），然後移除前綴、根據 JWKS 端點驗證簽名、檢查過期，並將聲明列印為 JSON。子命令僅執行簽名和過期檢查；它不檢查 `iss`、`aud` 或 `ccr:role`。當您的包裝器的驗證決定取決於這些聲明時，從列印的 JSON 讀取它們並明確比較它們。

189

190此命令提取建立者身份，優先選擇 SSO 提供者的主體，然後是電子郵件地址，然後是建立者的 `act.sub` 主體 `user:<id>` 或 `agent:<id>`：

191

192```bash theme={null}

193"$CLAUDE_RUNNER_CLAUDE_BIN" self-hosted-runner decode-token | jq -re '.act.attested_by.sub // .act.email // .act.sub'

194```

195

196包裝器在 `CLAUDE_RUNNER_CLAUDE_BIN` 中接收執行者自身二進位檔案的絕對路徑；使用該路徑而不是 PATH 解析的 `claude`，以便解碼在執行者本身使用的相同二進位檔案上執行。

197

198使用 `jq -re` 而不是 `jq -r`，以便遺漏的聲明導致非零退出。僅使用 `-r`，遺漏的聲明會列印字面字串 `null` 並以零退出，這會無聲地將壞值傳遞到下游。僅當 JWKS 端點無法到達的離線檢查時，才將 `--no-verify` 傳遞給 `decode-token`。

199

200<h2 id="claims-reference">

201 聲明參考

202</h2>

203

204下表列出了與驗證相關的工作階段令牌聲明。從 `ccr:*` 命名空間和 `act` 鏈讀取身份；平面 `account_email`、`organization_uuid` 和 `account_uuid` 聲明是可能被移除的向後相容性重複項。您組織的服務身份建立的工作階段（包括 Claude Tag 頻道工作階段）在 `act.sub` 中帶有 `agent:` 主體，並省略 `act.email`、`ccr:account_id`、`account_email` 和 `account_uuid`。兩個電子郵件聲明對於使用者建立的工作階段也是可選的：Anthropic 僅在建立請求的認證帶有電子郵件時才在工作階段建立時記錄它們，從 CLI 分派的工作階段可能兩者都缺少，因此根據 `act.sub` 或 `ccr:account_id` 而不是電子郵件來識別身份。令牌也可以帶有超出此表的其他聲明；忽略您不認識的聲明。

205

206| 聲明 | 類型 | 描述 |

207| :------------------ | :--- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

208| `iss` | 字串 | 始終為 `ccr`。 |

209| `sub` | 字串 | `ccr:session:<session_id>`。 |

210| `aud` | 字串陣列 | 始終包含 `anthropic-api`。對於自託管環境中的工作階段，陣列也包含您的環境 ID，例如 `ccpool_...`。驗證環境 ID，而不是 `anthropic-api`。 |

211| `exp` | 數字 | 過期時間為 Unix 時間戳。四小時預設生命週期，八小時最大值。 |

212| `iat` | 數字 | 簽發時間為 Unix 時間戳。 |

213| `jti` | 字串 | 唯一令牌識別碼。 |

214| `ccr:role` | 字串 | 對於工作階段令牌始終為 `session_worker`。 |

215| `ccr:session_id` | 字串 | 工作階段 ID。與 `sub` 的後綴相同的值。 |

216| `ccr:pool_id` | 字串 | 您的環境 ID。與出現在 `aud` 中的值相同。 |

217| `ccr:org_id` | 字串 | 您的 Anthropic 組織 ID。 |

218| `ccr:account_id` | 字串 | 建立使用者的 Anthropic 帳戶 ID：`act.sub` 的值，不帶 `user:` 前綴，一個標記的 `user_...` ID。與 [spawn-runner hook](/docs/zh-TW/self-hosted-environments-configuration#the-spawn-runner-hook) 的 `CLAUDE_RUNNER_ACCOUNT_ID` 帶有的值相同，以及 [`--lock-to-account`](/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags) 接受的值，因此三者作為相等的字串進行比較。 |

219| `account_email` | 字串 | `act.email` 的重複；每當 `act.email` 不存在時就不存在。 |

220| `organization_uuid` | 字串 | 您的 Anthropic 組織 UUID。 |

221| `account_uuid` | 字串 | 建立使用者的 Anthropic 帳戶 UUID。 |

222| `act` | 物件 | [RFC 8693](https://www.rfc-editor.org/rfc/rfc8693) 委派鏈。請參閱 [The `act` chain](#the-act-chain)。 |

223

224<h3 id="the-act-chain">

225 The `act` chain

226</h3>

227

228`act` 聲明記錄了從建立工作階段的使用者或服務身份到[環境](/docs/zh-TW/self-hosted-environments#key-concepts)（其祕密允許執行者）以及建立該祕密的身份的完整委派路徑。建立者是最外層的參與者，因此 `act.sub` 直接識別他們。

229

230| 路徑 | 描述 |

231| :---------------- | :------------------------------------------------------------------------------------------------------------------- |

232| `act.sub` | 建立使用者的 Anthropic 使用者 ID，形式為 `user:<id>`，或當您組織的服務身份建立工作階段時為 `agent:<id>`，就像它對 Claude Tag 頻道工作階段所做的那樣。 |

233| `act.email` | 建立使用者的電子郵件地址，當在工作階段建立時記錄了一個時。不要要求它；根據 `act.sub` 識別。 |

234| `act.attested_by` | 上游身份提供者對建立使用者的證明，當可用時。`act.attested_by.sub` 是您的 SSO 提供者（例如 Google 或 Okta）簽發的主體。在對應到您自己系統中的身份時，優先選擇這個而不是 `act.email`。 |

235| `act.act` | 生成工作階段的執行者。`act.act.sub` 是 `ccr:runner:<runner_id>`。 |

236| `act.act.act` | 環境。`act.act.act.sub` 是 `ccr:pool:<pool_id>`。 |

237| `act.act.act.act` | 建立執行者註冊的環境祕密的身份。鏈在此結束。 |

238

239<h2 id="scope-derived-credentials">

240 範圍衍生認證

241</h2>

242

243工作階段令牌識別建立工作階段的使用者或服務身份，但不要將其視為等同於該建立者直接登入。令牌位於工作階段內的環境變數中，因此 Claude 執行的任何程式碼以及工作階段啟動的任何工具或 MCP 伺服器都可以讀取並呈現它。

244

245驗證也是離線的：根據 JWKS 驗證的令牌在其 `exp` 之前保持有效，無論自那時以來工作階段發生了什麼，Anthropic 不會為工作階段令牌發佈撤銷源。相應地綁定您從令牌衍生的任何內容。

246

247當您的服務將令牌交換為內部認證時，簽發範圍限制在一個編碼工作階段應該到達的內容的認證：

248

249* **限制功能**：授予工作階段編碼任務所需的資源的讀取和寫入存取權限，而不是建立者在其他地方持有的管理功能。

250* **限制生命週期**：將衍生認證綁定到令牌的 `exp` 或更短。

251* **作為工作階段進行審計**：記錄 `ccr:session_id` 和 `jti` 以及建立者身份，以便您可以將操作追蹤回特定工作階段。

252

253<h2 id="related-environment-variables">

254 相關環境變數

255</h2>

256

257建立者身份也以純環境變數的形式出現在兩個永遠不驗證令牌的表面上：

258

259* **[`spawn-runner` hook](/docs/zh-TW/self-hosted-environments-configuration#the-spawn-runner-hook)，在協調器上**：hook 在任何執行者存在於佇列工作階段之前執行，並在 `CLAUDE_RUNNER_ACCOUNT_EMAIL` 和 `CLAUDE_RUNNER_ACCOUNT_ID` 等變數中接收建立者身份。協調器從工作訂單（授權生成一個執行者的簽署單次使用令牌）讀取它們，而不驗證工作訂單的簽名本身；聲明是受信任的，因為工作訂單通過協調器與 Anthropic 的連線到達，環境祕密對其進行驗證。

260* **[包裝指令碼](/docs/zh-TW/self-hosted-environments-configuration#wrapper-scripts)，在工作階段內**：包裝器接收 `CCR_SESSION_ACCOUNT_EMAIL`，建立者的電子郵件從令牌預先提取，無需簽名驗證。該變數適合用於標籤，例如提交預告片，而不是用於驗證決定。

261

262使用純變數進行協調器端決定，例如選擇機器映像。當下游服務需要獨立的密碼學證明而不是信任執行者的環境時，使用 `CLAUDE_CODE_SESSION_ACCESS_TOKEN`。

263

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

265 接下來

266</h2>

267

268* [自託管環境](/docs/zh-TW/self-hosted-environments)：環境、執行者和工作階段模型；[快速入門](/docs/zh-TW/self-hosted-environments-quickstart)和[部署到生產環境](/docs/zh-TW/self-hosted-environments-deploy)包含設定和操作

269* [自訂工作階段](/docs/zh-TW/self-hosted-environments-configuration)：使用令牌的包裝指令碼，以及 `spawn-runner` hook

270* [參考](/docs/zh-TW/self-hosted-environments-reference)：CLI 旗標、環境變數和指標

self-hosted-environments-quickstart.md +128 −0 created

Details

1> ## Documentation Index

2> 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.

5# 自託管環境快速入門

7> 設定您的第一個自託管環境：安裝 Claude Code、建立環境、啟動執行器，並將工作階段路由到該環境。

9<Note>

10 自託管環境在 Team 和 Enterprise 方案上處於公開測試版；[可用性和限制](/docs/zh-TW/self-hosted-environments#availability-and-limitations)涵蓋啟用路徑。本頁面讓您的第一個工作階段執行；請參閱[自託管環境](/docs/zh-TW/self-hosted-environments)了解它們是什麼，以及[部署到生產環境](/docs/zh-TW/self-hosted-environments-deploy)以進行強化和艦隊配方。

11</Note>

13[自託管環境](/docs/zh-TW/self-hosted-environments)在您的組織運營的基礎設施上執行 Claude Code [雲端工作階段](/docs/zh-TW/claude-code-on-the-web)，由您部署的執行器程序執行。本快速入門設定您的第一個環境，這是最小的可行設定：單一主機上的一個執行器，執行一個測試工作階段。有兩個步驟：[建立環境、啟動執行器並將工作階段路由到該環境](#set-up-an-environment-and-runner)，然後[從您的終端傳送後續訊息到執行中的工作階段](#send-a-follow-up-message-to-a-running-session)。您將在兩個介面之間移動：claude.ai 用於建立環境、檢查其狀態和路由工作階段，以及主機上的終端用於執行器執行的所有操作。

15完成後，您將在[**雲端環境**管理頁面](https://claude.ai/admin-settings/cloud-environments)上擁有一個環境、一個輪詢工作的執行器，以及在您的主機上執行的工作階段。在連接真實存放庫或內部系統之前，請完成[部署到生產環境](/docs/zh-TW/self-hosted-environments-deploy)，其中涵蓋安全態勢、出口控制、git 認證和編排。

17<h2 id="prerequisites">

18 先決條件

19</h2>

21<h3 id="organization-and-roles">

22 組織和角色

23</h3>

25claude.ai 端需要：

27* **允許自託管環境**由[擁有者](/docs/zh-TW/cloud-environments#organization-shared-environments)在[**雲端環境**管理頁面](https://claude.ai/admin-settings/cloud-environments)上開啟；在開啟之前，**新增**按鈕不會出現。如果您不持有該角色，持有該角色的人可以建立環境並將其密鑰交給您；本頁面上的執行器和終端步驟不需要 claude.ai 角色，而在步驟檢查管理 UI 中的狀態時，執行器自己的日誌行會給您相同的信號。

28* 您的組織的 [GitHub 連接](/docs/zh-TW/claude-code-on-the-web#github-authentication-options)，以便開發人員在啟動工作階段時可以選擇存放庫。

30<h3 id="host-and-network">

31 主機和網路

32</h3>

34執行器主機需要：

36* 具有到 `api.anthropic.com` 的出站 HTTPS、到 `claude.ai` 和下面安裝步驟重定向到的下載主機，以及到您的 git 主機以進行複製的 Linux 或 macOS 主機或容器；[網路需求表](/docs/zh-TW/self-hosted-environments-deploy#network-requirements)有完整清單。Windows 不支援作為執行器主機；改為在 Linux 容器中執行執行器。開發人員工作站不受影響，因為工作階段從瀏覽器中的 claude.ai 啟動。

37* 與實時同步的時鐘，例如使用 NTP。當時鐘偏差超過五分鐘時，驗證失敗；請參閱[疑難排解](/docs/zh-TW/self-hosted-environments-deploy#troubleshooting)。

39<h3 id="software-on-the-runner-host">

40 執行器主機上的軟體

41</h3>

43在啟動之前在主機上安裝：

45* **Claude Code v2.1.224 或更新版本**，使用任何[標準安裝方法](/docs/zh-TW/setup)。執行器是標準 `claude` 二進位檔的一部分，較早版本無法識別 `self-hosted-runner` 子命令。原生安裝程式的預設 `latest` 頻道在發佈後立即提供每個版本；`stable` 頻道、Homebrew `claude-code` cask 和穩定 apt、dnf 和 apk 存放庫延遲約一週。若要固定您的艦隊執行的確切版本，請參閱[安裝特定版本](/docs/zh-TW/setup#install-a-specific-version)。對於容器映像，請參閱[部署到生產環境](/docs/zh-TW/self-hosted-environments-deploy#build-the-runner-image)中的 Dockerfile。

46* **Git 2.24 或更新版本**。部署頁面上的某些 git 選項需要較新的版本；[設定 git](/docs/zh-TW/self-hosted-environments-deploy#configure-git)說明每個下限。

48確認主機已準備好：

50```bash theme={null}

51claude self-hosted-runner --help

52```

54準備好的主機會列印執行器的使用文字，列出 `--environment-secret-file` 等旗標。在 2.1.224 之前的版本上，該命令會改為列印一般 `claude --help` 輸出；使用 `claude update` 升級或從 `latest` 頻道重新安裝。

56<h2 id="set-up-an-environment-and-runner">

57 設定環境和執行器

58</h2>

60Claude Code 包含引導式設定：一個互動式 Claude Code 工作階段，引導您在管理 UI 中建立環境、使用您保存的密鑰檔案啟動本機執行器、確認執行器註冊，並將速查表寫入 `./runner-setup/CHEAT-SHEET.md`。在您已使用持有擁有者角色的帳戶使用 `claude auth login` 登入的機器上執行它；它不適用於 API 金鑰或第三方模型提供者。在無法進行互動式工作階段的主機上，改為使用下面的手動步驟。首先確認[版本檢查](#software-on-the-runner-host)已通過：在 2.1.224 之前的版本上，此命令會啟動一個普通的 Claude 工作階段，將這些詞作為提示，而不是引導式設定。若要啟動引導式設定，請執行設定子命令並按照提示進行：

62```bash theme={null}

63claude self-hosted-runner setup

64```

66若要改為手動設定：

68<Steps>

69 <Step title="建立環境">

70 前往管理設定中的[**雲端環境**頁面](https://claude.ai/admin-settings/cloud-environments)。在**自託管環境**下，選擇**新增**，命名環境，然後選擇**建立**。在精靈的第二步，選擇**複製環境金鑰**以複製環境密鑰，管理 UI 將其標記為環境金鑰。claude.ai 只顯示一次密鑰，您之後無法檢索它；它在建立後 365 天過期。環境的 `ccpool_...` ID 在其詳細對話方塊中保持可見；您需要它用於[令牌驗證](/docs/zh-TW/self-hosted-environments-identity)中的 `aud` 檢查，以及用於從 CI [分派測試工作階段](/docs/zh-TW/self-hosted-environments-testing#run-the-test-loop)。

72 如果您遺失密鑰或需要輪換它，請從環境的**設定**標籤建立新密鑰，將新密鑰推出到您的執行器，然後撤銷舊密鑰。持有已撤銷密鑰的執行器在下一次驗證輪詢時失敗並退出，記錄 `poll auth failed`，您的編排器使用新密鑰重新啟動它們。

73 </Step>

75 <Step title="啟動執行器">

76 建立密鑰目錄。此步驟和下一步需要 root 用於 `/etc/claude` 路徑；執行器程序可以讀取的任何路徑都有效，因此如果您使用不同的路徑，請一起調整兩個命令和 `--environment-secret-file` 值。

78 ```bash theme={null}

79 mkdir -p /etc/claude

80 ```

82 將環境密鑰寫入檔案。下面的命令從您的終端讀取，以便密鑰保持在 shell 歷史記錄之外：貼上您複製的值，按 Enter，然後按 Ctrl-D，子 shell 的 `umask` 使檔案只能由其擁有者讀取。

84 ```bash theme={null}

85 (umask 077 && cat > /etc/claude/environment-secret)

86 ```

88 選擇基本目錄，將下面執行器命令中的 `<writable-dir>` 替換為執行器可以寫入或建立的絕對路徑。執行器在啟動時建立目錄，然後簽出存放庫並在其下建立每個工作階段的目錄。沒有 `--base-dir`，它使用 `/workspace`，這只在該目錄已存在且可寫或您以 root 身份啟動執行器時有效。

90 如果執行器無法建立或寫入路徑，它在啟動時會以命名目錄的錯誤退出，而不是註冊。請參閱[疑難排解](/docs/zh-TW/self-hosted-environments-deploy#troubleshooting)。

92 然後使用 `--environment-secret-file` 和 `--base-dir` 啟動執行器。執行器向您的環境註冊並開始輪詢工作。如果執行器退出，請手動重新啟動它。生產部署在編排器下執行執行器，該編排器重新啟動已退出的執行器，通常每次重新啟動時使用新的檔案系統；[重複使用預先準備的簽出](/docs/zh-TW/self-hosted-environments-deploy#reuse-a-pre-warmed-checkout)涵蓋支援的持久磁碟設定。

94 ```bash theme={null}

95 claude self-hosted-runner --environment-secret-file '/etc/claude/environment-secret' --base-dir '<writable-dir>'

96 ```

97 </Step>

99 <Step title="驗證執行器出現">

100 返回[**雲端環境**頁面](https://claude.ai/admin-settings/cloud-environments)。您的環境狀態在執行器啟動後幾秒內從**未部署執行器**變更為**健康**；開啟環境並選擇**活動**以查看執行器本身。

101 </Step>

102

103 <Step title="將工作階段路由到環境">

104 在 claude.ai/code 啟動工作階段，並從環境選擇器中選擇您的環境，其中自託管環境與 Anthropic 託管的環境並排出現。執行器使用主機已有的任何 git 認證進行複製，因此選擇此主機已可以複製的存放庫，或公開存放庫；生產中私有存放庫的認證選項在[設定 git](/docs/zh-TW/self-hosted-environments-deploy#configure-git)。下一個可用的執行器會拾取佇列中的工作階段，並記錄 `Picked up session <session-id>` 以及其活動計數和容量，因此您可以從執行器自己的輸出確認哪個主機接收了工作階段。在 [claude.ai/code](https://claude.ai/code) 觀看工作階段工作並閱讀 Claude 的回覆。如果工作階段保持佇列狀態，請參閱[疑難排解](/docs/zh-TW/self-hosted-environments-deploy#troubleshooting)。

105 </Step>

106</Steps>

107

108執行器在其活動工作階段完成後按設計退出；請參閱[執行器生命週期](/docs/zh-TW/self-hosted-environments#runner-lifecycle)。對於生產環境，在編排器下部署它，該編排器在退出時重新啟動它。請參閱[部署到生產環境](/docs/zh-TW/self-hosted-environments-deploy)。

109

110<h2 id="send-a-follow-up-message-to-a-running-session">

111 傳送後續訊息到執行中的工作階段

112</h2>

113

114一旦工作階段在您的環境上執行，從任何您使用 `claude auth login` 登入的機器上的 `claude` CLI 傳送後續訊息；該命令不需要從啟動工作階段的機器執行。該命令發佈一條訊息：

115

116```bash theme={null}

117claude -p "your message" --cloud <session-id>

118```

119

120對於 `<session-id>`，傳遞裸 `session_...` 或 `cse_...` ID 或工作階段的 claude.ai/code URL。成功傳送會列印 `Sent to cloud session.` 以及工作階段 ID 和檢視連結。接受的 ID 形式、JSON 輸出、帳戶和原則需求，以及錯誤參考在[從 CLI 傳送後續訊息](/docs/zh-TW/claude-code-on-the-web#send-follow-ups-from-the-cli)上，因為該命令對 Anthropic 託管的工作階段的工作方式相同。

121

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

123 接下來的步驟

124</h2>

125

126* [部署到生產環境](/docs/zh-TW/self-hosted-environments-deploy)：強化部署、控制出口、設定 git 認證，並在 Kubernetes 或 Compose 下執行艦隊

127* [自訂工作階段](/docs/zh-TW/self-hosted-environments-configuration)：包裝器指令碼、生命週期掛鉤、隨需執行器、MCP 伺服器和權限

128* [端到端測試](/docs/zh-TW/self-hosted-environments-testing)：一個 CI 煙霧測試，分派工作階段並讀取 Claude 的回覆

self-hosted-environments-reference.md +341 −0 created

Details

1> ## Documentation Index

2> 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.

5# 自託管環境參考

7> 自託管執行器和協調器的完整參考：CLI 旗標、環境變數和 Prometheus 指標。

9<Note>

10 自託管環境在 Team 和 Enterprise 方案上處於公開測試版；[擁有者](/docs/zh-TW/cloud-environments#organization-shared-environments)可以在 [**Cloud environments** 管理頁面](https://claude.ai/admin-settings/cloud-environments)上開啟 **Allow self-hosted environments** 來啟用它們。本頁面是旗標和指標參考；請參閱 [快速入門](/docs/zh-TW/self-hosted-environments-quickstart)以了解設定，以及 [部署到生產環境](/docs/zh-TW/self-hosted-environments-deploy)以了解艦隊配方。

11</Note>

13本頁面是您在[自託管環境](/docs/zh-TW/self-hosted-environments)中執行的兩個程序的參考：執行器在您的主機上執行 Claude Code [雲端工作階段](/docs/zh-TW/claude-code-on-the-web)，以及可選的自動擴展協調器，它在工作階段佇列時啟動執行器。每個都有自己的旗標表。兩者都在 Linux 或 macOS 主機上執行，預設值如 `/workspace` 和 `~/.claude` 假設。執行 `claude self-hosted-runner --help` 以取得您已安裝版本上的權威清單。

15指標序列和一些 API 欄位仍然使用 `pool` 來表示這些頁面所稱的環境；兩個術語都命名相同的東西。環境 ID 是 `pool_id` 欄位，形式為 `ccpool_...`：無論這些頁面在何處顯示 `pool` 識別碼，它都命名環境。CLI 旗標和環境變數將其拼寫為 `environment`，例如 `--environment-secret-file`；已棄用的 `pool` 拼寫仍然有效，如 [`--environment-secret-file` 列](#runner-cli-flags)所述。

17<h2 id="runner-cli-flags">

18 執行器 CLI 旗標

19</h2>

21大多數旗標都有對應的環境變數。當兩者都設定時，旗標優先。持續時間旗標在 CLI 上採用分鐘或秒，但配對的環境變數始終以毫秒為單位，由 `_MS` 後綴表示，預設列顯示旗標的單位：`--exit-if-unused-min 10` 等同於 `SELF_HOSTED_RUNNER_IDLE_SHUTDOWN_MS=600000`，而 Helm 值如 `SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS: "15"` 表示 15 毫秒，而不是 15 分鐘的預設值。

23| 旗標 | 環境變數 | 預設值 | 說明 |

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

26| `--base-dir <path>` | `SELF_HOSTED_RUNNER_BASE_DIR` | `/workspace`；Windows 上無 | 用於存放庫簽出和每個工作階段工作目錄的目錄。執行器需要對此路徑或其父目錄的寫入存取。執行器在啟動時建立目錄，當無法建立或寫入時以 `cannot create or write to base directory` 退出。在 v2.1.225 之前，執行器在第一個工作階段啟動時建立目錄，因此無法使用的路徑會導致工作階段失敗而不是啟動失敗。在 Windows 上（不是支援的執行器主機），沒有預設值：除非您傳遞旗標或設定變數，否則執行器在啟動時退出。在環境中的每個執行器上使用相同的值。請參閱[在執行器之間保持基礎目錄和容量相同](/docs/zh-TW/self-hosted-environments-deploy#keep-the-base-directory-and-capacity-identical-across-runners)。 |

27| `--capacity <n>` | 無 | `1` | 此執行器處理的最大並行工作階段。所有工作階段都屬於同一個鎖定的[擁有者](/docs/zh-TW/self-hosted-environments#key-concepts)。在環境中的每個執行器上使用相同的值；請參閱[在執行器之間保持基礎目錄和容量相同](/docs/zh-TW/self-hosted-environments-deploy#keep-the-base-directory-and-capacity-identical-across-runners)。 |

29| `--configure-git` | `SELF_HOSTED_RUNNER_CONFIGURE_GIT=1` | 關閉 | 在啟動時，寫入全域 git 身份、啟用 Anthropic 提交簽署、開啟 git push 協商，並安裝附加 `Co-authored-by:` 預告片的提交掛鉤。Push 協商需要 Claude Code v2.1.257 或更新版本。請參閱[配置 git](/docs/zh-TW/self-hosted-environments-deploy#configure-git)。 |

30| `--confine-repo-settings <mode>` | `SELF_HOSTED_RUNNER_CONFINE_REPO_SETTINGS` | `warn` | 設定防護的模式，當存放庫的已提交設定嘗試授予對該工作階段自己的工作區之外的寫入或讀取存取、設定環境變數或覆蓋操作員的沙箱或掛鉤姿態時，該防護會標記工作階段，例如 `sandbox.enabled: false` 或 `disableAllHooks`。預設 `warn` 記錄違規並仍然啟動工作階段，`enforce` 拒絕工作階段，`off` 停用掃描。請參閱[強化您的部署](/docs/zh-TW/self-hosted-environments-deploy#harden-your-deployment)。 |

32| `--defer-shutdown-max-min <n>` | `SELF_HOSTED_RUNNER_DEFER_SHUTDOWN_MAX_MS` | `0` | 在第一個 `SIGTERM` 或 `SIGINT` 上，繼續為已附加的工作階段提供服務而不是排空它們，然後在 N 分鐘後釋放仍然附加的任何內容並退出。在設定此項之前提高主機的停止逾時。請參閱[將排空延遲到第一個信號之後](/docs/zh-TW/self-hosted-environments-deploy#defer-the-drain-past-the-first-signal)。`0` 停用。需要 Claude Code v2.1.238 或更新版本。 |

33| `--drain-grace-sec <n>` | `SELF_HOSTED_RUNNER_DRAIN_GRACE_MS` | `0` | 在執行器接收到關閉信號或達到其退休時間之前，控制執行器在其活動工作階段完成後何時退出：`0` 立即退出而不輪詢更多內容，正值使執行器保持活動並首先重新輪詢鎖定擁有者的佇列該許多秒，代價是[強化部分](/docs/zh-TW/self-hosted-environments-deploy#harden-your-deployment)中描述的每個工作階段容器隔離。在您使用 [`--defer-shutdown-max-min`](/docs/zh-TW/self-hosted-environments-deploy#defer-the-drain-past-the-first-signal) 延遲的第一個信號之後，執行器在不持有任何工作階段時立即退出，無論您在此設定什麼。 |

34| `--drain-wait-sec <n>` | `SELF_HOSTED_RUNNER_DRAIN_WAIT_MS` | `0` | 排空開始後（除非您設定 [`--defer-shutdown-max-min`](/docs/zh-TW/self-hosted-environments-deploy#defer-the-drain-past-the-first-signal)，否則在 `SIGTERM` 上），等待最多 N 秒讓每個工作階段的進行中轉向和背景工作完成，然後終止子程序。在此等待期間，執行器將剛完成的背景工作計為仍在執行，直到讀取其結果的後續轉向開始，最多 [`SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS`](#environment-variable-only-settings) 視窗。 |

35| `--environment-secret-file <path>` | `SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET` | 必需 | 包含環境祕密的檔案路徑，或對於由[協調器](/docs/zh-TW/self-hosted-environments-configuration#on-demand-runners)產生的執行器，單次使用工作訂單 JWT。`SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET` 直接攜帶祕密值，而不是檔案路徑。較舊的 `--pool-secret-file` 旗標和 `SELF_HOSTED_RUNNER_POOL_SECRET` 變數仍然有效並列印棄用通知到 stderr；早於 2.1.216 的預覽程式執行器組建只識別那些較舊的名稱。 |

38| `--git-host-rewrite <from>=<to>` | 無 | 未設定 | 在複製之前將 `https://<from>/...` 來源 URL 重寫為 `https://<to>/...`，用於分割視界 DNS。可重複；僅旗標。 |

39| `--git-ssh-rewrite <host>` | 無 | 未設定 | 在複製之前將 `https://<host>/...` 來源 URL 重寫為 `git@<host>:...`，用於僅限 SSH 的 git 主機。可重複；僅旗標。 |

42| `--kill-session-after-min <n>` | `SELF_HOSTED_RUNNER_MAX_LIFETIME_MS` | `0` | 將工作階段限制為 N 分鐘牆上時間，作為卡住工作階段的安全限制。在 v2.1.260 或更新版本上，執行器釋放達到限制的工作階段，以便它可以在其使用者的下一條訊息上繼續，並且只有在它在 [`SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS`](#environment-variable-only-settings) 寬限期結束時仍在執行器上時才終止它。在 v2.1.260 之前，執行器在限制時終止工作階段。請參閱[某些工作階段不計為閒置](/docs/zh-TW/self-hosted-environments-deploy#some-sessions-don%E2%80%99t-count-as-idle)以了解詳細資訊以及如何選擇值。`0` 停用。 |

47| `--proxy-authorization-command <command>` | `SELF_HOSTED_RUNNER_PROXY_AUTHORIZATION_COMMAND` | 未設定 | 執行器為每個到您的出口代理的連線執行的 Shell 命令，使用其修剪的 stdout 作為 `Proxy-Authorization` 標頭值。需要 `HTTPS_PROXY` 或 `HTTP_PROXY`，不能與 `--proxy-authorization-file` 結合。請參閱[驗證到出口代理](/docs/zh-TW/self-hosted-environments-deploy#authenticate-to-an-egress-proxy)。需要 Claude Code v2.1.238 或更新版本。 |

48| `--proxy-authorization-file <path>` | `SELF_HOSTED_RUNNER_PROXY_AUTHORIZATION_FILE` | 未設定 | 執行器為每個到您的出口代理的連線讀取的檔案，使用其修剪的內容作為 `Proxy-Authorization` 標頭值。對於另一個程序就地輪換的權杖，使用此旗標。與 `--proxy-authorization-command` 具有相同的要求，不能與其結合。請參閱[驗證到出口代理](/docs/zh-TW/self-hosted-environments-deploy#authenticate-to-an-egress-proxy)。需要 Claude Code v2.1.238 或更新版本。 |

49| `--push-outcome-on-release` | `SELF_HOSTED_RUNNER_PUSH_OUTCOME_ON_RELEASE` | 關閉 | 在執行器啟動的工作階段結束（例如排空或閒置釋放）時，在刪除工作區之前將追蹤的結果分支推送到 `origin`，以便進行中的提交在重新啟動後存活。盡力而為；將關閉預算增加 30 秒，並需要 git 2.29 或更新版本以從推送的分支繼續。在啟用之前限制推送存取到 `claude/*` 參考；請參閱[已繼續的工作階段會遺失未推送的工作](/docs/zh-TW/self-hosted-environments-deploy#additional-limitations)。通過 `checkout` 生命週期掛鉤簽出的存放庫不會被推送；改為從 [`post-session` 掛鉤](/docs/zh-TW/self-hosted-environments-configuration#post-session)快照這些。 |

50| `--release-idle-session-min <n>` | `SELF_HOSTED_RUNNER_SESSION_IDLE_MS` | `0` | 在轉向完成或工作階段等待使用者操作後，在 N 分鐘的不活動後釋放工作階段槽。仍在進行中轉向的工作階段（包括持有永不完成的背景工作或從執行中工具呼叫內部請求的批准的工作階段）不計為閒置；與 `--kill-session-after-min` 配對作為硬後擋。在工作階段的背景工作完成後，執行器將工作階段視為忙碌，直到讀取結果的後續轉向開始，最多 [`SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS`](#environment-variable-only-settings) 視窗。在執行器接收到關閉信號或達到其退休時間之前，留下執行器沒有活動工作階段的釋放會啟動與正常排空相同的退出路徑，由 `--drain-grace-sec` 管理。在您使用 [`--defer-shutdown-max-min`](/docs/zh-TW/self-hosted-environments-deploy#defer-the-drain-past-the-first-signal) 延遲的第一個信號之後，執行器在釋放使其不持有任何工作階段時立即退出。`0` 停用。 |

51| `--retire-at <epoch-seconds>` | `SELF_HOSTED_RUNNER_RETIRE_AT` | 未設定 | 在絕對 Unix 時間戳記（秒）時退休執行器，用於在已知時間終止執行器的基礎設施；[執行器生命週期](/docs/zh-TW/self-hosted-environments#runner-lifecycle)描述釋放序列以及如何調整邊距。2001 年之前或 5138 年之後的值被旗標拒絕，被環境變數忽略。 |

53| `--startup-timeout-min <n>` | `SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS` | `15` | 如果子程序在產生後 N 分鐘內未在[活動頻道](/docs/zh-TW/self-hosted-environments-configuration#keep-stdin-and-file-descriptor-3-attached)上發出初始化信號，則釋放工作階段槽。由子程序的初始化信號清除，而不是普通輸出，之後 `--release-idle-session-min` 接管。`0` 停用。 |

54| `--trust-workspace [bool]` | `SELF_HOSTED_RUNNER_TRUST_WORKSPACE` | 開啟 | 為每個工作階段的存放庫路徑播種持久化信任，以便尊重存放庫提交的 `permissions.allow` 和 `additionalDirectories`。設定 `false` 以放棄存放庫提交的權限授予，並改為在主機設定的 `settings.json` 中配置允許規則；存放庫提交的 `sandbox.*` 設定無論如何仍然適用，這就是為什麼[存放庫設定防護](/docs/zh-TW/self-hosted-environments-deploy#harden-your-deployment)無論此旗標如何都掃描它們。 |

55| `--use-anthropic-git-proxy` | `CLAUDE_RUNNER_USE_GIT_PROXY=1` | 關閉 | 通過 [Anthropic git proxy](/docs/zh-TW/self-hosted-environments-deploy#use-the-anthropic-git-proxy) 而不是客戶管理的 git 驗證進行複製。需要 `--capacity 1` 和 git 2.32 或更新版本；執行器否則拒絕啟動。取代重寫旗標。 |

57大多數持續時間旗標都有最大值，選擇以將每個逾時保持在執行時間的 32 位元計時器上限內，大約 24.85 天。`--*-min` 旗標上限為 10080 分鐘，7 天；`--drain-grace-sec` 為 604800 秒，也是 7 天；`--drain-wait-sec` 為 86400 秒，24 小時。`--session-stop-grace-sec` 和 `--post-session-hook-timeout-sec` 無上限。超過上限的行為因表面而異：

59* **旗標**：啟動失敗並出現錯誤。

60* **環境變數**：執行器將值夾住到計時器上限，而不是拒絕它。

62<h2 id="orchestrator-cli-flags">

63 協調器 CLI 旗標

64</h2>

66`self-hosted-runner orchestrator` 子命令（產生[按需執行器](/docs/zh-TW/self-hosted-environments-configuration#on-demand-runners)）接受 `--api-url`、`--environment-secret-file`、`--hooks-dir`、`--health-port` 和 `--log-level`，具有與執行器相同的預設值，以及執行器旗標具有的相同環境變數，除了 `--hooks-dir` 是必需的且必須包含 `spawn-runner` 掛鉤。它也採用自己的旗標：

68| 旗標 | 預設值 | 說明 |

69| :------------------------------- | :---- | :----------------------------------------------------------------------------------------------------- |

70| `--hook-concurrency <n>` | `4` | 最大 `spawn-runner` 掛鉤並行執行。也限制每次輪詢聲稱多少個產生請求。 |

71| `--hook-timeout <sec>` | `60` | 在此許多秒後終止掛鉤的程序樹。逾時加上其 5 秒終止寬限期必須保持在 `--expected-spawn-seconds` 以下；協調器在啟動時強制執行此項。 |

72| `--expected-spawn-seconds <sec>` | `120` | 產生的執行器的預期 p99 啟動時間，在伺服器強制的範圍 10 到 3600 內。在每次輪詢時作為伺服器端租約發送；如果沒有執行器在其經過前註冊，工作階段會以新訂單 ID 重新提供。所有副本必須共享此值。 |

73| `--min-idle <n>` | `0` | 通過主動產生待命執行器來保持至少 N 個閒置工作階段槽空閒。`0` 停用預熱。與執行器的 `--exit-if-unused-min` 配對，以便多餘的待命執行器回收自己。 |

74| `--debug-dir <path>` | 未設定 | 將每個產生請求的工作訂單和掛鉤 stderr 寫入磁碟。僅用於偵錯；永遠不要在生產環境中設定。 |

76<h3 id="scm-connector-flags">

77 SCM 連接器旗標

78</h3>

80協調器可以與 Anthropic 的控制平面保持常設 WebSocket 連線，以便託管的預工作階段流程（例如存放庫選擇器和分支或參考解析器）可以到達只能從您的網路內部路由的 GitHub Enterprise Server 主機。除非您設定 `--scm-connector-host`，否則連接器保持關閉。

82| 旗標 | 預設值 | 說明 |

83| :------------------------------------------------------ | :-------------------------- | :------------------------------------------------------------------------- |

84| `--scm-connector-host <host[:port]>` | 未設定 | 要轉發請求的 GitHub Enterprise Server 主機名稱。連接埠預設為 `443`。設定此旗標會啟用連接器。 |

85| `--scm-connector-id <n>` | 與 `--scm-connector-host` 必需 | 您組織的 GitHub Enterprise Server 連線的數字 ID。當您啟用連接器時，請聯絡您的 Anthropic 帳戶團隊以取得該值。 |

86| `--scm-connector-provider <slug>` | `ghe` | 識別提供者的路徑段，符合 `^[a-z0-9-]{1,32}$`。 |

87| `--scm-connector-ca-file <path>` | 未設定 | 額外的 CA 套件（PEM 格式），用於到 GitHub Enterprise Server 主機的 TLS 連線。 |

88| `--scm-connector-host-rewrite <from>=<to_host:to_port>` | 未設定 | 僅用於端到端測試：重定向 TCP 連線，同時將主機標頭和 TLS SNI 保持為 `--scm-connector-host`。 |

90連接器使用協調器的現有環境祕密進行驗證並自動重新連線：在連線中斷時使用指數退避，或當控制平面因另一個協調器副本已持有它而關閉連線時使用固定 30 秒延遲。

92<h2 id="environment-variable-only-settings">

93 僅環境變數設定

94</h2>

96這些執行器設定僅從環境讀取，涵蓋大多數部署保留在預設值的行為：

98| 環境變數 | 預設值 | 說明 |

99| :----------------------------------------- | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

100| `SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS` | `30000` | 執行器在背景工作完成後考慮工作階段忙碌的時間，而讀取結果的後續轉向尚未開始。[`--drain-wait-sec` 和 `--release-idle-session-min` 列](#runner-cli-flags)描述排空和閒置釋放時保持適用的位置，[執行器生命週期](/docs/zh-TW/self-hosted-environments#runner-lifecycle)描述它在 `--retire-at` 退休時適用的位置。`0` 或無法使用的值回退到預設值，因此無法關閉保持。需要 Claude Code v2.1.228 或更新版本。 |

101| `SELF_HOSTED_RUNNER_HOST_CONFIG_DIR` | `~/.claude` | 捕獲到執行器啟動快照中並播種到每個工作階段的 `CLAUDE_CONFIG_DIR` 的目錄；磁碟上的變更在執行器重新啟動後適用。設定變數也會移動執行器讀取 `.claude.json` 的位置以進行 [MCP 播種](/docs/zh-TW/self-hosted-environments-configuration#mcp-servers)，因此設定它（包括其自己的預設值）會重新定位該查詢；指向空目錄以完全停用播種。 |

102| `SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS` | `900000` | 執行器在工作階段達到其 `--kill-session-after-min` 限制後等待的時間，以便執行中的轉向完成或釋放完成，然後才終止工作階段 |

103| `SELF_HOSTED_RUNNER_SIGKILL_GRACE_MS` | `30000` | 執行器等待作業系統將 `SIGKILL` 傳遞到卡在不可中斷 I/O 中的子程序的時間，然後自己退出。下限為 `--post-session-hook-timeout-sec` 加 15 秒，以及設定 `--push-outcome-on-release` 時的 30 秒，因此有效最小值在預設值為 75 秒。 |

104| `CLAUDE_RUNNER_FETCH_DEPTH` | `50` | 新複製的 git 提取深度。設定正整數，或 `full` 或 `0` 以進行完整提取。工作區中已存在的存放庫保持其現有深度。 |

105| `CLAUDE_RUNNER_SKIP_GIT_VERIFY` | 未設定 | 當 `1` 時，在 `checkout` 掛鉤執行後跳過 `.git` 存在檢查。當您的掛鉤具體化非 git 來源時設定此項。 |

106| `FORCE_AUTOUPDATE_PLUGINS` | 未設定 | 當 `1` 時，即使二進位檔被固定，也讓外掛程式市場自動更新 |

107| `CLAUDE_CODE_DISABLE_ARTIFACT` | 未設定 | 當 `1` 時，無論組織的管理員設定如何，都在工作階段中停用 Artifact 工具，並放棄 `*.frame.claudeusercontent.com` 出口要求 |

108

109<h2 id="telemetry">

110 遙測

111</h2>

112

113工作階段子程序將操作遙測傳送給 Anthropic，除非您將其關閉。不會傳送任何程式碼或存放庫內容。在執行器程序上設定遙測變數；執行器在應用伺服器提供的環境變數後重新聲稱它們，因此操作員的設定始終優先。

114

115一個控制項特定於自託管環境：`CLAUDE_CODE_BYOC_ENABLE_DATADOG=1` 選擇加入 Datadog 操作指標，在自託管環境中預設為關閉。一般 Claude Code 遙測控制項 `DISABLE_TELEMETRY`、`DO_NOT_TRACK`、`DISABLE_ERROR_REPORTING` 和 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 適用於工作階段子程序，如[環境變數參考](/docs/zh-TW/env-vars)中所述。`DISABLE_GROWTHBOOK` 相關但不同：設定 `DISABLE_GROWTHBOOK=1` 停用功能旗標提取，遙測保持開啟，除非也設定了 `DISABLE_TELEMETRY`。

116

117`CLAUDE_CODE_ENABLE_TELEMETRY` 無關：它啟用 OpenTelemetry 匯出到您自己的收集器，如[監控](/docs/zh-TW/monitoring-usage)中所述，不控制 Anthropic 的分析。

118

119<h2 id="health-endpoint">

120 健康端點

121</h2>

122

123執行器在配置的健康連接埠上提供 `GET /healthz`。只要程序活著，無論輪詢迴圈處於什麼狀態，回應都是 `200 OK`，因此此端點上的 HTTP 探測只檢測死程序。JSON 主體描述當前狀態：

124

125```json theme={null}

126{

127 "status": "ok",

128 "runner_id": "ccrunner_...",

129 "active_sessions": 2,

130 "last_poll_at": "2026-03-31T18:04:11.220Z",

131 "last_poll_age_ms": 842

132}

133```

134

135在自訂探測中使用 `last_poll_age_ms` 作為活躍信號；無限增長的值表示輪詢迴圈卡住。`last_poll_at` 和 `last_poll_age_ms` 都是 `null`，直到第一次輪詢完成。

136

137協調器在其健康連接埠上提供自己的 `/healthz`。其端點始終返回 `200`，主體攜帶報告最近輪詢是否成功的 `connected` 欄位，加上 `queue_counts` 中的每個狀態產生佇列計數。在 `connected` 上而不是狀態碼上閘讀就緒和警報。

138

139當配置[SCM 連接器](#scm-connector-flags)時，協調器的 `/healthz` 主體也攜帶 `scm_connector_connected` 和一個 `scm_connector` 物件，其中包含 `connected`、`last_connected_at`、`last_error`、`reconnects` 和 `requests_forwarded`。當未設定 `--scm-connector-host` 時，兩個欄位都是 `null`。

140

141<h2 id="prometheus-metrics">

142 Prometheus 指標

143</h2>

144

145每個執行器在與 `/healthz` 相同的連接埠上的 `GET /metrics` 上提供 Prometheus 指標。關鍵序列：

146

147| 序列 | 備註 |

148| :-------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

149| `claude_code_self_hosted_runner_info{runner_id,version,client_label}` | 始終 `1`；對艦隊清單和版本漂移檢測有用 |

150| `claude_code_self_hosted_runner_capacity` | 配置的 `--capacity` |

151| `claude_code_self_hosted_runner_active_sessions` | 目前執行的工作階段 |

152| `claude_code_self_hosted_runner_locked_account{email}` | 一旦執行器鎖定到使用者並發出攜帶 `act.email` 聲稱的工作階段權杖，就會出現。該序列在鎖定到 Claude Tag 代理的執行器上不存在，其工作階段權杖不攜帶 `act.email`。標籤值是帳戶電子郵件；如果您的指標存放區可廣泛讀取，在抓取時放棄或雜湊標籤，例如使用 Prometheus `metric_relabel_configs`。 |

153| `claude_code_self_hosted_runner_last_poll_age_seconds` | 自上次成功輪詢以來的秒數。如果超過 60，則發出警報。 |

154| `claude_code_self_hosted_runner_poll_errors_total{error_kind}` | 按類型累積 PollWork 失敗：`transport`、`timeout`、`5xx`、`429` 或 `4xx`。所有五個序列都從程序啟動開始存在；在 `rate(...[5m]) > 0` 時發出警報。 |

155| `claude_code_self_hosted_runner_sessions_started_total{client_platform}` | 在執行器的生命週期內產生的工作階段子程序，每個工作階段來源一個序列，例如 `web_claude_ai`、`ios`、`android`、`desktop_app` 或 `claude_code_cli`，或當伺服器未傳送時 `unknown`。Slack 工作階段根據哪個 Slack 整合建立它們而攜帶 `claude_in_slack` 或 `claude-in-slack`，因此使用正規表達式選擇器（例如 `{client_platform=~"claude[-_]in[-_]slack"}` 匹配兩者。使用 `sum()` 表示艦隊總計。 |

156| `claude_code_self_hosted_runner_sessions_completed_total{client_platform}` | 乾淨結束的工作階段，標籤方式相同。比普通乾淨退出更廣泛：請參閱[工作階段生命週期計數器語義](#session-lifecycle-counter-semantics)以了解計數的內容。 |

157| `claude_code_self_hosted_runner_sessions_failed_total{client_platform}` | 以失敗結束的工作階段，標籤方式相同。相同的警告：請參閱[工作階段生命週期計數器語義](#session-lifecycle-counter-semantics)。 |

158| `claude_code_self_hosted_runner_sessions_interrupted_total{client_platform}` | 執行器因操作原因而不是工作階段結果終止的工作階段，標籤方式相同。請參閱[工作階段生命週期計數器語義](#session-lifecycle-counter-semantics)。 |

159| `claude_code_self_hosted_runner_initializing_sessions` | 目前處於初始化階段的工作階段，從指派到子程序的初始化事件 |

160| `claude_code_self_hosted_runner_session_init_duration_seconds` | 工作階段初始化持續時間的直方圖 |

161| `claude_code_self_hosted_runner_session_init_errors_total` | 在達到初始化前失敗的工作階段：簽出掛鉤失敗、git 準備、權杖問題或初始化前子程序崩潰 |

162| `claude_code_self_hosted_runner_session_start_hook_errors_total` | 報告錯誤結果的 `SessionStart` 掛鉤，每個失敗的掛鉤執行一個 |

163| `claude_code_self_hosted_runner_session_idle_seconds{session_id,client_platform}` | 每個工作階段的工作階段閒置以來秒數的量表。對於終止卡在未回答權限提示上的工作階段很有用。 |

164

165協調器在與其 `/healthz` 相同的連接埠上的 `GET /metrics` 上提供自己的序列：

166

167| 序列 | 備註 |

168| :-------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |

169| `claude_code_self_hosted_orchestrator_info{version,pool_id,orchestrator_uuid,hostname}` | 始終 `1` |

170| `claude_code_self_hosted_orchestrator_connected` | 當最近輪詢成功時為 `1`；在任何失敗輪詢後下降到 `0`，無論失敗類型如何 |

171| `claude_code_self_hosted_orchestrator_last_poll_age_seconds` | 自上次輪詢嘗試以來的秒數，成功或失敗，與執行器的同名指標不同，後者測量自上次成功以來；與 `connected` 配對以捕獲失敗的輪詢。協調器的輪詢迴圈等待掛鉤執行，因此在 `--hook-timeout` 加邊距（預設值約 90 秒）上方發出警報，而不是平面 60。 |

172| `claude_code_self_hosted_orchestrator_poll_errors_total{error_kind}` | 按類型累積 PollSpawnHints 失敗：`transport`、`timeout`、`5xx`、`429` 或 `4xx`。所有五個序列都從程序啟動開始存在；在 `rate(...[5m]) > 0` 時發出警報。 |

173| `claude_code_self_hosted_orchestrator_queue_pending_sessions` | 現在可聲稱的產生請求 |

174| `claude_code_self_hosted_orchestrator_queue_backing_off_sessions` | 在可重試掛鉤失敗後退避重試的產生請求 |

175| `claude_code_self_hosted_orchestrator_queue_circuit_broken_sessions` | 被阻止的產生請求，直到擁有者從環境的**活動**標籤重試它們；如果高於零則發出警報 |

176| `claude_code_self_hosted_orchestrator_pool_pending_sessions` | 等待此環境中執行器的總工作階段。環境範圍的聚合，在每個協調器實例上相同：在實例之間使用 `MAX` 而不是 `SUM`。 |

177| `claude_code_self_hosted_orchestrator_pool_active_sessions` | 目前指派給此環境中活著執行器的工作階段。環境範圍的聚合，在每個協調器實例上相同：在實例之間使用 `MAX` 而不是 `SUM`。 |

178| `claude_code_self_hosted_orchestrator_spawn_hooks_total{result}` | 累積 `spawn-runner` 掛鉤結果：`ok`、`retryable`、`non_retryable`。計數協調器掛鉤呼叫，而不是執行器產生的工作階段子程序：不可與 `sessions_started_total` 比較，因為容量高於 1、暖池和為同一工作階段再次產生的執行器都使兩者分歧。 |

179| `claude_code_self_hosted_orchestrator_spawn_hook_duration_seconds` | 掛鉤持續時間的直方圖 |

180| `claude_code_self_hosted_orchestrator_warm_hints_dispatched_total` | 自程序啟動以來分派的待命產生請求 |

181| `claude_code_self_hosted_orchestrator_session_queue_wait_seconds` | 每個工作階段在佇列中等待的秒數的直方圖，然後協調器聲稱它進行產生，從控制平面與每個工作階段的產生請求一起傳送的佇列等待時間戳記記錄。用於 p50/p99 佇列時間警報。預熱產生不被取樣。 |

182| `claude_code_self_hosted_orchestrator_clock_skew_seconds` | 本地減去伺服器時鐘偏差；診斷，一旦測量就存在 |

183| `claude_code_self_hosted_orchestrator_scm_connector_connected` | 當 [SCM 連接器](#scm-connector-flags) 的 WebSocket 開啟時為 `1`；在撥號或退避時為 `0`。當未設定 `--scm-connector-host` 時不存在。 |

184| `claude_code_self_hosted_orchestrator_scm_connector_requests_forwarded_total` | 自程序啟動以來代理到配置的 SCM 主機的累積 HTTP 請求。當未設定 `--scm-connector-host` 時不存在。 |

185

186對於自動擴展，選擇與您的擴展風格相符的序列並在其進入擴展器之前閘它：

187

188* **佇列深度擴展**：將 `claude_code_self_hosted_orchestrator_pool_pending_sessions` 饋送到您的 HPA 或 KEDA 擴展器，而不是 `queue_pending_sessions`。

189* **容量擴展**：根據執行器的 `active_sessions` 與 `capacity` 的比率進行擴展。

190* **在 `connected` 上閘**：使用 `claude_code_self_hosted_orchestrator_connected == 1` 每個實例過濾查詢，以便斷開連線副本的陳舊值不會饋送擴展器。

191

192在完整輪詢中斷期間，每個副本都斷開連線，閘查詢返回無資料。HPA 在缺少指標時保持當前副本計數，但 KEDA 的 Prometheus 擴展器在其預設 `ignoreNullValues: "true"` 將空結果讀取為零並縮小；在 ScaledObject 上設定 `ignoreNullValues: "false"`，可選擇使用 `fallback` 副本下限。

193

194以下 Prometheus Operator `PodMonitor` 涵蓋兩個程序。它通過 `app.kubernetes.io/part-of: claude-code-self-hosted-runner` 標籤和 [Kubernetes 配方](/docs/zh-TW/self-hosted-environments-deploy#kubernetes)設定的命名 `health` 連接埠選擇 Pod；調整命名空間以符合您的部署：

195

196```yaml theme={null}

197# Claude Code 自託管執行器 + 協調器的範例 Prometheus Operator PodMonitor。

198# 調整命名空間和標籤選擇器以符合您的部署。執行器和協調器都在其

199# --health-port（預設 8080）上提供 /metrics。

200apiVersion: monitoring.coreos.com/v1

201kind: PodMonitor

202metadata:

203 name: claude-code-self-hosted-runner

204 namespace: monitoring

205spec:

206 namespaceSelector:

207 matchNames:

208 - claude-runners

209 selector:

210 matchExpressions:

211 # 符合 Kubernetes 配方中的執行器部署，加上任何

212 # 按相同方式標籤的按需執行器工作和協調器 Pod

213 # 並給予命名的 'health' containerPort。

214 - key: app.kubernetes.io/part-of

215 operator: In

216 values: [claude-code-self-hosted-runner]

217 podMetricsEndpoints:

218 - port: health

219 path: /metrics

220 interval: 30s

221```

222

223這些範例警報規則是起點；為您的艦隊大小調整閾值：

224

225```yaml theme={null}

226# Claude Code 自託管執行器 + 協調器的範例 Prometheus 警報規則。

227# 為您的艦隊大小和 SLO 調整閾值。

228groups:

229 - name: claude-code-self-hosted-runner

230 rules:

231 - alert: ClaudeRunnerPollStale

232 expr: claude_code_self_hosted_runner_last_poll_age_seconds > 60

233 for: 2m

234 labels: {severity: warning}

235 annotations:

236 summary: "執行器 {{ $labels.pod }} 已超過 60 秒未輪詢"

237 - alert: ClaudeRunnerVersionDrift

238 expr: count(count by (version) (claude_code_self_hosted_runner_info)) > 1

239 for: 30m

240 labels: {severity: info}

241 annotations:

242 summary: "執行器執行混合版本"

243 - alert: ClaudeRunnerInitErrorsHigh

244 expr: increase(claude_code_self_hosted_runner_session_init_errors_total[10m]) > 3

245 for: 5m

246 labels: {severity: warning}

247 annotations:

248 summary: "執行器 {{ $labels.pod }}：10 分鐘內 >3 個工作階段初始化失敗（簽出掛鉤 / git / 權杖 / 初始化前崩潰）"

249 - alert: ClaudeRunnerPollErrors

250 expr: sum by (pod) (rate(claude_code_self_hosted_runner_poll_errors_total[5m])) > 0

251 for: 2m

252 labels: {severity: warning}

253 annotations:

254 summary: "執行器 {{ $labels.pod }}：PollWork 失敗（5 分鐘內 {{ $value | humanize }}/s）"

255 - alert: ClaudeRunnerSessionStartHookErrors

256 expr: increase(claude_code_self_hosted_runner_session_start_hook_errors_total[10m]) > 3

257 for: 5m

258 labels: {severity: warning}

259 annotations:

260 summary: "執行器 {{ $labels.pod }}：10 分鐘內 >3 個 SessionStart 掛鉤失敗"

261

262 - name: claude-code-self-hosted-orchestrator

263 rules:

264 - alert: ClaudeOrchestratorDisconnected

265 expr: claude_code_self_hosted_orchestrator_connected == 0

266 for: 2m

267 labels: {severity: critical}

268 annotations:

269 summary: "協調器 {{ $labels.pod }} 無法到達 Anthropic 控制平面"

270 - alert: ClaudeOrchestratorPollStale

271 expr: claude_code_self_hosted_orchestrator_last_poll_age_seconds > 90

272 for: 2m

273 labels: {severity: warning}

274 annotations:

275 summary: "協調器 {{ $labels.pod }} 已超過 90 秒未輪詢（輪詢迴圈等待掛鉤執行）"

276 - alert: ClaudeOrchestratorCircuitBroken

277 expr: claude_code_self_hosted_orchestrator_queue_circuit_broken_sessions > 0

278 for: 1m

279 labels: {severity: critical}

280 annotations:

281 summary: "{{ $value }} 個工作階段斷路 — spawn-runner 掛鉤重複不可重試；修復基礎設施然後從活動標籤重試"

282 - alert: ClaudeOrchestratorPollErrors

283 expr: sum by (pod) (rate(claude_code_self_hosted_orchestrator_poll_errors_total[5m])) > 0

284 for: 2m

285 labels: {severity: warning}

286 annotations:

287 summary: "協調器 {{ $labels.pod }}：PollSpawnHints 失敗（5 分鐘內 {{ $value | humanize }}/s）"

288 - alert: ClaudeOrchestratorSpawnHookFailing

289 expr: sum by (pod) (increase(claude_code_self_hosted_orchestrator_spawn_hooks_total{result!="ok"}[5m])) > 3

290 for: 5m

291 labels: {severity: warning}

292 annotations:

293 summary: "協調器 {{ $labels.pod }}：5 分鐘內 >3 個 spawn-runner 掛鉤失敗"

294```

295

296<h3 id="pass-through-session-child-metrics">

297 傳遞工作階段子程序指標

298</h3>

299

300每個工作階段在其自己的子程序中執行，具有自己的 OpenTelemetry 指標；在 `--capacity` 高於 1 時，執行器重寫這些子程序指標的公開方式。在執行器主機上設定 `OTEL_METRICS_EXPORTER=prometheus` 並在工作階段的環境中設定 `CLAUDE_CODE_ENABLE_TELEMETRY=1`（例如從您的[包裝指令碼](/docs/zh-TW/self-hosted-environments-configuration#wrapper-scripts)或執行器自己的環境，工作階段繼承），重新公開每個子程序的計數器和量表工具在執行器自己的 `/metrics` 端點上，與執行器的序列一起。執行器將子程序的匯出器重寫為通過 OTLP 推送到健康連接埠上的僅環回接收器，使用 `session_id` 和 `client_platform` 標籤標記每個序列，並在該工作階段結束時驅逐工作階段的序列。直方圖不傳遞，子程序指標的名稱會與執行器自己的前綴衝突被放棄。

301

302在預設 `--capacity 1` 時，重寫不適用：工作階段的子程序如常在連接埠 9464 上綁定自己的 Prometheus 端點。

303

304<h3 id="session-lifecycle-counter-semantics">

305 工作階段生命週期計數器語義

306</h3>

307

308`sessions_started_total`、`sessions_completed_total`、`sessions_failed_total` 和 `sessions_interrupted_total` 計數器按工作階段如何結束對其進行分類。每個產生的工作階段子程序在產生時增加 `sessions_started_total`，並在退出時恰好增加其他三個中的一個，因此 `sessions_started_total` 減去其他三個的總和等於目前執行的工作階段子程序數。

309

310* `completed`：工作階段乾淨結束。這涵蓋子程序以代碼 `0` 自行退出、工作階段在子程序仍連線時被存檔或刪除，以及執行器乾淨地交回槽：在閒置逾時、退休時間或 `--kill-session-after-min` 限制時釋放工作階段；啟動逾時；或輪詢迴圈在子程序退出前注意到的伺服器端取消指派。增加 `sessions_completed_total`。

311* `failed`：子程序以非零代碼自行退出，要麼是崩潰，要麼是產生後的設定失敗。增加 `sessions_failed_total`。

312* `interrupted`：執行器因既不是工作階段成功也不是執行器故障的操作原因終止子程序，例如排空，或終止在 [`SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS`](#environment-variable-only-settings) 寬限期結束後其 `--kill-session-after-min` 限制仍在執行器上的工作階段。Kubernetes 滾動重新啟動傳送 `SIGTERM` 是排空的一個範例。增加 `sessions_interrupted_total`。

313

314在 v2.1.260 之前，執行器終止達到其 `--kill-session-after-min` 限制的每個工作階段並在 `sessions_interrupted_total` 中計數。

315

316[`post-session` 掛鉤](/docs/zh-TW/self-hosted-environments-configuration#post-session)的 `CLAUDE_RUNNER_EXIT_REASON` 以不同方式分類乾淨交接。掛鉤將釋放、啟動逾時和伺服器取消指派報告為 `interrupted`，因為執行器停止了子程序。這些計數器記錄與 `completed` 相同的事件，因為槽被乾淨地交回。

317

318如果您直接根據 `sessions_completed_total` 協調掛鉤收據，您會低估完成。使用掛鉤以獲得每個工作階段的保證，並使用計數器以獲得聚合速率。

319

320在一次性環境上，`--capacity 1` 與預設 `--drain-grace-sec 0`，每個執行器程序在其一個工作階段結束後片刻退出。`sessions_completed_total`、`sessions_failed_total` 和 `sessions_interrupted_total` 僅在工作階段結束時增加，就在該退出之前，因此每 15 到 60 秒進行一次 Prometheus 抓取很少在執行器的序列消失前捕獲增加；這三個工作階段結束計數器是本部分其餘部分所指的終端計數器。`sessions_started_total` 在產生時增加並在工作階段的生命週期內保持可見，因此它可靠地顯示，但在一次性環境上它讀取更接近「目前執行的工作階段」而不是累積計數。

321

322改為使用此表中的序列以達到相應的目標，而不是終端計數器：

323

324| 目標 | 使用 |

325| :-- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

326| 吞吐量 | `claude_code_self_hosted_orchestrator_spawn_hooks_total{result="ok"}`，長期協調器上的計數器，每個成功的 `spawn-runner` 掛鉤增加一次並在 `rate()` 下保持有意義。它計數掛鉤呼叫而不是工作階段，因此預熱和為同一工作階段重複產生使其與工作階段計數分歧。 |

327| 利用率 | `sum(claude_code_self_hosted_runner_active_sessions)` 對 `sum(claude_code_self_hosted_runner_capacity)`，兩個量表在每次抓取時有效，無論執行器生命週期如何 |

328| 待辦項 | `claude_code_self_hosted_orchestrator_pool_pending_sessions` 用於佇列深度，以及 `claude_code_self_hosted_orchestrator_queue_circuit_broken_sessions`，如果高於零則發出警報 |

329| 失敗 | `claude_code_self_hosted_runner_sessions_failed_total`，盡力而為：產生後的真實崩潰確實增加它，`rate()` 在執行器上有意義，這些執行器以 `--drain-grace-sec` 高於 `0` 的方式超越其工作階段。一次性環境與其他終端計數器具有相同的抓取視窗問題，因此將您看到的任何非零值視為值得調查。產生前的失敗，例如簽出掛鉤失敗、git 準備或權杖問題，僅出現在 `session_init_errors_total` 中。 |

330

331`orchestrator_*` 列僅存在於執行[按需協調器](/docs/zh-TW/self-hosted-environments-configuration#on-demand-runners)的環境上。在固定艦隊上，其執行器以 `--drain-grace-sec` 高於 `0` 的方式超越其工作階段，使用 `sum(rate(claude_code_self_hosted_runner_sessions_started_total[5m]))` 表示吞吐量；在一次性艦隊上，該序列與終端計數器具有相同的抓取視窗問題，因此改為依賴佇列工作階段計數。在環境的**活動**標籤上檢查待辦項，在[**雲端環境**管理頁面](https://claude.ai/admin-settings/cloud-environments)上：執行器不匯出佇列深度序列。

332

333對於每個工作階段結果報告，改為使用 [`post-session` 掛鉤](/docs/zh-TW/self-hosted-environments-configuration#post-session)：它在每個工作階段結束時觸發，其中產生了子程序，除了突然執行器終止（例如 VM 搶佔），根據[掛鉤自己的合約](/docs/zh-TW/self-hosted-environments-configuration#post-session)。

334

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

336 下一步

337</h2>

338

339* [自託管環境](/docs/zh-TW/self-hosted-environments)：環境、執行器和工作階段模型；[快速入門](/docs/zh-TW/self-hosted-environments-quickstart)和[部署到生產環境](/docs/zh-TW/self-hosted-environments-deploy)保持設定和操作

340* [自訂工作階段](/docs/zh-TW/self-hosted-environments-configuration)：包裝指令碼、生命週期掛鉤和按需執行器

341* [驗證工作階段身份](/docs/zh-TW/self-hosted-environments-identity)：工作階段權杖、其聲稱以及如何驗證它

self-hosted-environments-testing.md +269 −0 created

Details

1> ## Documentation Index

2> 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.

5# 端對端測試自託管環境

7> 從 CI 驗證自託管執行器映像：使用 CLI 分派工作階段、透過 Stop hook 讀取 Claude 的回覆，並編寫完整迴圈的指令碼。

9<Note>

10 自託管環境在 Team 和 Enterprise 方案上處於公開測試版；[可用性和限制](/docs/zh-TW/self-hosted-environments#availability-and-limitations)涵蓋啟用路徑。本頁面是 CI 測試配方；請參閱[快速入門](/docs/zh-TW/self-hosted-environments-quickstart)以了解設定，以及[部署到生產環境](/docs/zh-TW/self-hosted-environments-deploy)以了解艦隊配方。

11</Note>

13在[自託管環境](/docs/zh-TW/self-hosted-environments)中，Claude Code [雲端工作階段](/docs/zh-TW/claude-code-on-the-web)在您建置和維護的執行器映像上執行。在將新映像推出到生產環境之前，請從指令碼針對測試環境驅動完整工作階段：建立工作階段、讀取 Claude 的回覆、傳送後續追蹤，並讀取該回覆。這是 CI 煙霧測試的形式，可驗證您的執行器映像、git 存取和任何自訂工具，然後再推廣變更。

15此配方假設您已經[設定環境和執行器](/docs/zh-TW/self-hosted-environments-quickstart#set-up-an-environment-and-runner)，並且您的 CI 工作在與測試指令碼相同的主機上啟動執行器程序，這是測試新執行器映像的自然設定。您在執行器上安裝的 Stop hook 會將每個回合的最終回覆寫入本機檔案，指令碼從該處讀取它，因此對 Anthropic API 的唯一呼叫是兩個分派本身。如果您的測試執行器位於不同的基礎結構上，請參閱[遠端測試執行器](#remote-test-runners)。

17<h2 id="install-the-capture-hook-on-your-test-runner">

18 在測試執行器上安裝擷取 hook

19</h2>

21讀回透過 Claude Code [Stop hook](/docs/zh-TW/hooks#stop) 進行：當 Claude 完成一個回合時，hook 會在其 stdin JSON 中接收最終助手訊息作為 `last_assistant_message`，並將其附加到 `$E2E_REPLY_DIR/<session_id>.txt`。以與[commit-nudge Stop hook](/docs/zh-TW/self-hosted-environments-configuration#prompt-sessions-to-push-their-work)相同的方式安裝它，在執行器主機的 `~/.claude/` 上，執行器會將其植入每個工作階段。

23<h3 id="save-the-hook-files">

24 儲存 hook 檔案

25</h3>

27在執行器主機上儲存以下兩個檔案：

29* 設定區塊：合併到執行器主機上的 `~/.claude/settings.json`

30* 指令碼：在執行器主機上儲存為 `~/.claude/hooks/e2e-stop-hook-capture.sh` 並使其可執行

32```json theme={null}

33{

34 "hooks": {

35 "Stop": [

36 {

37 "hooks": [

38 {

39 "type": "command",

40 "timeout": 10,

41 "command": "\"$CLAUDE_CONFIG_DIR/hooks/e2e-stop-hook-capture.sh\""

42 }

43 ]

44 }

45 ]

46 }

47}

48```

50```sh theme={null}

51#!/bin/sh

52# Stop hook for testing a self-hosted environment end to end: writes each

53# turn's final assistant reply to $E2E_REPLY_DIR/<session_id>.txt so a

54# co-located test driver can read it without calling the Anthropic API.

55# Install on the TEST runner only. Requires jq.

57# No-op unless the driver is listening. Never fail the turn.

58[ -n "${E2E_REPLY_DIR:-}" ] && [ -d "$E2E_REPLY_DIR" ] || exit 0

60# CLAUDE_CODE_REMOTE_SESSION_ID is exported in cse_... form; the session

61# id the dispatch CLI prints is in session_... form. Same id, different

62# prefix.

63sid=$(printf '%s' "${CLAUDE_CODE_REMOTE_SESSION_ID:-}" | sed 's/^cse_/session_/')

64[ -n "$sid" ] || exit 0

66# last_assistant_message is absent when the final assistant turn had no

67# text, such as a tool-use-only turn. The `// empty` filter makes that a

68# zero-byte write rather than the literal string "null".

69jq -r '.last_assistant_message // empty' >> "$E2E_REPLY_DIR/$sid.txt" 2>/dev/null

70exit 0

71```

73<h3 id="before-you-start-the-runner">

74 在啟動執行器之前

75</h3>

77hook 依賴的兩件事：

79* 在啟動執行器之前安裝它。執行器在啟動時會快照 `~/.claude/`，因此添加到執行中執行器的 hook 只有在重新啟動後才會生效。

80* 將 `E2E_REPLY_DIR` 匯出到執行器程序。當變數未設定或目錄不存在時，hook 是無操作的，因此在啟動執行器的任何地方設定它，例如 systemd 單位、pod 規格或 CI 步驟。下面的測試指令碼也需要它。

82僅在為測試環境提供服務的執行器上安裝此 hook。每當 `E2E_REPLY_DIR` 存在時，它會將每個工作階段的最終回覆寫入磁碟，這在一次性 CI 執行器上是無害的，但不是要帶入生產環境執行器映像的東西，其中變數可能會被意外設定。

84<h2 id="run-the-test-loop">

85 執行測試迴圈

86</h2>

88The `--environment` 和 `--ref` 分派旗標需要執行指令碼的機器上的 Claude Code v2.1.224 或更新版本，與執行器本身的下限相同。安裝 hook 並在此主機上啟動執行器後，測試指令碼：

901. 使用 `claude -p "<prompt>" --environment <environment-id> --output-format json` 在測試環境上建立工作階段，從 git 簽出執行，以便 CLI 可以從 `origin` 遠端自動偵測存放庫。可選的 `--ref <branch>` 將工作階段的簽出基於命名的 ref，而不是本機 HEAD。該命令建立工作階段、列印包含 `session_id` 的一行 JSON，並在不等待 Claude 回覆的情況下退出。

912. 等待回覆出現在 `$E2E_REPLY_DIR/<session_id>.txt` 中，由執行器上的 Stop hook 在回合完成後寫入。

923. 使用 `claude -p "<message>" --cloud <session_id> --output-format json` 傳送後續訊息（請參閱[傳送後續訊息到執行中的工作階段](/docs/zh-TW/claude-code-on-the-web#send-follow-ups-from-the-cli)），它將使用者事件發佈到現有工作階段並退出。

934. 以與步驟 2 相同的方式等待後續訊息的回覆。

95<h3 id="environment-dispatch-behavior">

96 `--environment` 分派行為

97</h3>

99Claude Code 建立工作階段、列印工作階段 ID 和指向它的連結，然後退出。

100

101該旗標優先於 [`remote.defaultEnvironmentId`](/docs/zh-TW/settings-reference#remote-defaultenvironmentid) 設定。它不支援 `--output-format stream-json`，並且不能與恢復、附加到或預先配置工作階段的旗標結合，例如 `--resume`、`--continue`、`--teleport`、`--session-id` 或 `--init-only`。`--cloud` 在使用工作階段 ID 或 URL 時被拒絕，在非互動式執行中當它帶有描述時。裸 `--cloud` 被視為不存在。從終端機，您可以傳遞任務作為 `--cloud` 描述，而不是位置提示。

102

103<h2 id="example-script">

104 範例指令碼

105</h2>

106

107下面的指令碼針對 `$CLAUDE_TEST_ENVIRONMENT_ID`（您的測試環境的 `ccpool_...` ID，顯示在管理頁面上環境的詳細對話框中或由[建立環境呼叫](#create-a-dedicated-test-environment)返回）執行完整迴圈，並在每個回覆中斷言哨兵短語。從您希望工作階段在其中工作的存放庫的 git 簽出執行它，在此主機上啟動執行器後，安裝擷取 hook 並匯出 `E2E_REPLY_DIR`。

108

109```bash theme={null}

110#!/usr/bin/env bash

111# End-to-end test against a self-hosted environment, using Stop-hook read-back.

112# Prereqs: `claude auth login` has been run on this machine (see "Authenticate

113# from CI" below); jq is installed; CLAUDE_TEST_ENVIRONMENT_ID names an

114# environment whose runner is the one on this host, with the capture hook

115# installed and E2E_REPLY_DIR in its environment.

116

117set -euo pipefail

118

119: "${CLAUDE_TEST_ENVIRONMENT_ID:=${CLAUDE_TEST_POOL_ID:-}}" # CLAUDE_TEST_POOL_ID is the legacy spelling

120: "${CLAUDE_TEST_ENVIRONMENT_ID:?set CLAUDE_TEST_ENVIRONMENT_ID to a ccpool_... id served by a runner on this host}"

121: "${E2E_REPLY_DIR:?set E2E_REPLY_DIR to the directory the Stop hook on your test runner writes to, and export it to the runner process}"

122: "${TEST_REPO_REF:=main}"

123

124[ -d "$E2E_REPLY_DIR" ] || {

125 echo "FAIL: E2E_REPLY_DIR ($E2E_REPLY_DIR) does not exist. The Stop hook on the runner needs it." >&2

126 exit 1

127}

128

129# Waits until $E2E_REPLY_DIR/<session_id>.txt contains $2, or fails after

130# 90 seconds. Tune the timeout to your environment's cold-start time. The

131# file is written by the Stop hook on the runner.

132await_reply() {

133 local expect="$2" f="$E2E_REPLY_DIR/$1.txt"

134 local deadline=$(($(date +%s) + 90))

135 while :; do

136 if [ -f "$f" ] && grep -qF -- "$expect" "$f"; then

137 return

138 fi

139 [ "$(date +%s)" -lt "$deadline" ] || {

140 echo "FAIL: '$expect' not in $f within 90s. The Stop hook on the runner did not write it." >&2

141 echo "-- $E2E_REPLY_DIR contents --" >&2; ls -la "$E2E_REPLY_DIR" >&2

142 [ -f "$f" ] && { echo "-- $f --" >&2; cat "$f" >&2; }

143 exit 1

144 }

145 sleep 1

146 done

147}

148

149# 1. Create the session on the test environment. Run from a git checkout

150# so the CLI can auto-detect the repo. --ref pins the checkout to a named

151# ref regardless of local HEAD.

152TURN1="e2e-probe-$(date +%s)-$$: say exactly 'ok: custom tools are reachable' and nothing else"

153EXPECT1="ok: custom tools are reachable"

154create_json=$(claude -p "$TURN1" --environment "$CLAUDE_TEST_ENVIRONMENT_ID" \

155 --ref "$TEST_REPO_REF" --output-format json)

156echo "create: $create_json"

157SESSION_ID=$(jq -er '.session_id' <<<"$create_json")

158

159# 2. Wait for the turn-1 reply.

160await_reply "$SESSION_ID" "$EXPECT1"

161echo "turn-1 reply ok"

162

163# 3. Post a follow-up via the CLI.

164TURN2="e2e-probe-followup-$(date +%s): say exactly 'ok: follow-up delivered' and nothing else"

165EXPECT2="ok: follow-up delivered"

166followup_json=$(claude -p "$TURN2" --cloud "$SESSION_ID" --output-format json)

167echo "followup: $followup_json"

168jq -e '.ok == true' <<<"$followup_json" >/dev/null

169

170# 4. Wait for the turn-2 reply.

171await_reply "$SESSION_ID" "$EXPECT2"

172echo "turn-2 reply ok"

173

174echo "PASS: test-environment round-trip (session $SESSION_ID)"

175```

176

177將 `TURN1`/`TURN2` 提示和 `EXPECT1`/`EXPECT2` 哨兵替換為任何練習您的設定的內容，例如要求 Claude 執行您的自訂 MCP 工具之一並斷言其輸出。

178

179<h2 id="remote-test-runners">

180 遠端測試執行器

181</h2>

182

183如果您的測試執行器位於不同的基礎結構上，例如您的 CI 工作無法與之共享檔案系統的持久 Kubernetes 艦隊，請將 Stop hook 中的檔案寫入交換為 POST 到您的驅動程式監聽的端點：

184

185```sh theme={null}

186#!/bin/sh

187# Variant of the capture hook for runners on separate infrastructure.

188# Set E2E_REPLY_URL on the runner to an endpoint the driver controls.

189[ -n "${E2E_REPLY_URL:-}" ] || exit 0

190sid=$(printf '%s' "${CLAUDE_CODE_REMOTE_SESSION_ID:-}" | sed 's/^cse_/session_/')

191[ -n "$sid" ] || exit 0

192jq -r '.last_assistant_message // empty' | \

193 curl -fsS -X POST --data-binary @- "$E2E_REPLY_URL/$sid" >/dev/null 2>&1

194exit 0

195```

196

197在驅動程式端，執行任何接受 POST 並保留回覆直到測試要求它的東西，例如 CI 工作內的小型 HTTP 監聽器或您已經執行的 webhook 接收器。hook 在您的基礎結構上執行，因此端點只需要可從您的執行器到達。

198

199<h2 id="authenticate-from-ci">

200 從 CI 進行驗證

201</h2>

202

203`claude -p ... --environment` 和 `claude -p ... --cloud` 都使用 claude.ai OAuth 令牌進行驗證；API 金鑰（例如 `sk-ant-xxxxx`）不被接受用於任一呼叫。兩種方法使令牌在 CI 中可用。

204

205<h3 id="long-lived-ci-host">

206 長期 CI 主機

207</h3>

208

209在執行指令碼的機器上使用專用自動化使用者帳戶以互動方式執行一次 `claude auth login`。Claude Code 在 macOS 上將令牌儲存在 OS 金鑰鏈中，或在 Linux 和 Windows 上儲存在 `~/.claude/.credentials.json` 中。在 macOS 主機上，其金鑰鏈無法寫入（如 SSH 工作階段中的典型情況，其中登入金鑰鏈保持鎖定），Claude Code 也會將令牌儲存在 `~/.claude/.credentials.json` 中。請參閱[認證管理](/docs/zh-TW/authentication#credential-management)。

210

211CLI 在每次呼叫時自動重新整理短期存取令牌，但基礎重新整理令牌授予從初始登入起限制為 30 天，因此每 30 天在該主機上以互動方式重新執行一次 `claude auth login`。

212

213<h3 id="ephemeral-ci-runners">

214 短期 CI 執行器

215</h3>

216

217目前沒有長期 CI 令牌。授予遠端工作階段控制的範圍 `user:sessions:claude_code` 在伺服器端限制為 30 天，因此 `claude setup-token`（它鑄造一年推論專用令牌）不涵蓋它。[環境祕密](/docs/zh-TW/self-hosted-environments-quickstart#set-up-an-environment-and-runner)也不被接受，因為它只授權執行器向環境註冊，而不是建立工作階段。

218

219若要在短期執行器上佈建儲存的登入，請設定 [`CLAUDE_CODE_OAUTH_REFRESH_TOKEN` 和 `CLAUDE_CODE_OAUTH_SCOPES`](/docs/zh-TW/env-vars#variables)，以便 `claude auth login` 交換令牌而無需瀏覽器；相同的 30 天上限適用於重新整理授予。如果您需要不受人類帳戶約束的機器身份路徑，請聯絡您的 Anthropic 帳戶團隊。

220

221<h2 id="create-a-dedicated-test-environment">

222 建立專用測試環境

223</h2>

224

225以程式設計方式建立和刪除環境，以便每個 CI 執行都獲得乾淨的環境；您的 CI 工作啟動的執行器註冊到新環境中。下面的建立和刪除呼叫是 claude.ai 上的**雲端環境**管理頁面使用的相同端點，它們需要 `anthropic-beta: ccr-byoc-2025-07-29` 標頭。

226

227<h3 id="mint-the-admin-token">

228 鑄造管理員令牌

229</h3>

230

231`$ADMIN_TOKEN` 是持有 Owner 角色的帳戶的 claude.ai OAuth 存取令牌，以與[從 CI 進行驗證](#authenticate-from-ci)相同的方式鑄造：

232

233* **鑄造它**：使用持有 Owner 角色的帳戶執行 `claude auth login`，然後從[長期 CI 主機](#long-lived-ci-host)說 Claude Code 儲存它的地方讀取目前的存取令牌。

234* **每次執行時新鮮讀取它**：CLI 輪換存取令牌，相同的 30 天重新整理授予上限適用，因此不要儲存副本。

235* **透過 stdin 傳遞它**：如範例所示，以便令牌永遠不會進入 curl 的引數清單或您的建置日誌。

236

237<h3 id="create-the-environment">

238 建立環境

239</h3>

240

241在不回顯的情況下擷取回應：`pool_secret` 是可以將執行器註冊到環境中的長期認證，因此將其儲存為遮罩 CI 祕密並僅列印環境 ID。保持令牌不在程序清單中的 `-H @-` 形式需要 curl 7.55 或更新版本；較舊的 curl 將 `@-` 視為文字標頭並在沒有授權的情況下傳送請求。

242

243```bash theme={null}

244create=$(curl -fsS -X POST -H @- \

245 -H "anthropic-beta: ccr-byoc-2025-07-29" -H "anthropic-version: 2023-06-01" \

246 -H "content-type: application/json" \

247 -d '{"name":"ci-test-environment"}' \

248 https://api.anthropic.com/v1/code/runners/self-hosted/pools \

249 <<<"Authorization: Bearer $ADMIN_TOKEN")

250ENVIRONMENT_ID=$(jq -er .pool.pool_id <<<"$create")

251ENVIRONMENT_SECRET=$(jq -er .pool_secret <<<"$create")

252```

253

254在[Owner 為組織開啟**允許自託管環境**](/docs/zh-TW/self-hosted-environments#availability-and-limitations)之前，呼叫失敗，出現 `403` `permission_error`，讀取 `self-hosted runners are disabled by your organization's policy`。

255

256在此主機上啟動執行器，使用 `SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET=$ENVIRONMENT_SECRET`，加上擷取 hook 和 `E2E_REPLY_DIR`，根據[在測試執行器上安裝擷取 hook](#install-the-capture-hook-on-your-test-runner)，然後執行測試指令碼。

257

258<h3 id="delete-the-environment">

259 刪除環境

260</h3>

261

262執行完成時刪除環境，以便每個 CI 執行都從乾淨開始：

263

264```bash theme={null}

265curl -fsS -X DELETE -H @- \

266 -H "anthropic-beta: ccr-byoc-2025-07-29" -H "anthropic-version: 2023-06-01" \

267 "https://api.anthropic.com/v1/code/runners/self-hosted/pools/$ENVIRONMENT_ID" \

268 <<<"Authorization: Bearer $ADMIN_TOKEN"

269```

server-managed-settings.md +2 −0

Details

291* 如果您登出並重新登入，或切換到另一個組織，稍後返回，Claude Code 在這些設定保持不變時不會再次顯示對話方塊，除非另一個帳戶在同一設定目錄中為該組織核准了它們。291* 如果您登出並重新登入，或切換到另一個組織，稍後返回，Claude Code 在這些設定保持不變時不會再次顯示對話方塊，除非另一個帳戶在同一設定目錄中為該組織核准了它們。

292* 如果您使用不同的帳戶登入同一個組織，Claude Code 即使設定保持不變也會再次顯示對話方塊。該帳戶的核准會取代前一個，因此當您切換回去時，Claude Code 會再次顯示對話方塊。292* 如果您使用不同的帳戶登入同一個組織，Claude Code 即使設定保持不變也會再次顯示對話方塊。該帳戶的核准會取代前一個，因此當您切換回去時，Claude Code 會再次顯示對話方塊。

293 293

294`sandbox.credentials` 或 `sandbox.network.tlsTerminate` 的核准也涵蓋這些相同傳遞設定中的 [`sandbox.network.allowedDomains`](/docs/zh-TW/settings-reference#sandbox-network-alloweddomains) 項目，因為兩個設定都作用於該允許清單。當您的管理員新增或移除其中一個項目時，對話方塊會再次出現，即使 `sandbox.network.allowedDomains` 本身不需要核准。

295

294Claude Code 無法總是顯示對話方塊。下面的每個案例都說明當它無法顯示時哪些設定會套用，以及您何時會再次看到對話方塊：296Claude Code 無法總是顯示對話方塊。下面的每個案例都說明當它無法顯示時哪些設定會套用，以及您何時會再次看到對話方塊：

295 297

296* **無法顯示對話方塊的互動工作階段**：Claude Code 不會套用傳遞的設定，並保留最後核准的設定。對話方塊會在下一個可以顯示它的工作階段中出現。需要 Claude Code v2.1.211 或更新版本。298* **無法顯示對話方塊的互動工作階段**：Claude Code 不會套用傳遞的設定，並保留最後核准的設定。對話方塊會在下一個可以顯示它的工作階段中出現。需要 Claude Code v2.1.211 或更新版本。

settings.md +1 −1

Details

794| [`syncClaudeAiSkills`](/docs/zh-TW/settings-reference#syncclaudeaiskills) | 來自任何受管來源、`--settings`、`~/.claude/settings.json` 或 `.claude/settings.local.json` 的 `false` | 即使獲勝的受管來源設定 `true` 也被尊重；`.claude/settings.json` 中的 `false` 被忽略 |794| [`syncClaudeAiSkills`](/docs/zh-TW/settings-reference#syncclaudeaiskills) | 來自任何受管來源、`--settings`、`~/.claude/settings.json` 或 `.claude/settings.local.json` 的 `false` | 即使獲勝的受管來源設定 `true` 也被尊重；`.claude/settings.json` 中的 `false` 被忽略 |

795| [`maxEffortLevel`](/docs/zh-TW/settings-reference#maxeffortlevel) | 來自任何範圍的較低上限，包括 `--settings` | 即使 Claude Code 應用的受管設定設定較高上限也被尊重；最低上限適用。需要 Claude Code v2.1.267 或更新版本 |795| [`maxEffortLevel`](/docs/zh-TW/settings-reference#maxeffortlevel) | 來自任何範圍的較低上限，包括 `--settings` | 即使 Claude Code 應用的受管設定設定較高上限也被尊重；最低上限適用。需要 Claude Code v2.1.267 或更新版本 |

796 796

797在自己內部執行 Claude Code 並設定 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-TW/env-vars) 的應用程式也是例外。Claude Code 將該應用程式的模型設定優先於來自每個受管來源的 `model`、`fallbackModel` 和 `modelOverrides` 金鑰，以及受管 `env` 區塊中的模型選擇變數，例如 `ANTHROPIC_MODEL` 和 `ANTHROPIC_DEFAULT_*_MODEL` 系列。Claude Code 保持受管 [`availableModels`](/docs/zh-TW/settings-reference#availablemodels) 允許清單生效，除非應用程式提供自己的。797在自己內部執行 Claude Code 並設定 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-TW/env-vars) 的應用程式也是例外。Claude Code 將該應用程式的模型設定優先於來自每個受管來源的 `model`、`fallbackModel`、`modelPicker` 和 `modelOverrides` 金鑰，以及受管 `env` 區塊中的模型選擇變數，例如 `ANTHROPIC_MODEL` 和 `ANTHROPIC_DEFAULT_*_MODEL` 系列。Claude Code 保持受管 [`availableModels`](/docs/zh-TW/settings-reference#availablemodels) 允許清單生效，除非應用程式提供自己的。

798 798

799<h2 id="settings-in-cloud-sessions">799<h2 id="settings-in-cloud-sessions">

800 雲端工作階段中的設定800 雲端工作階段中的設定

settings-example.md +396 −0 created

Details

1> ## Documentation Index

2> 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.

5# 設定檔範例

7> 開發者、團隊和組織的實際 settings.json 檔案：複製其中一個，保留您想要的鍵，並變更數值。

9本頁面包含三個 `settings.json` 檔案範例，每個對應一個您儲存設定的位置：

11* 開發者的 `~/.claude/settings.json`

12* 團隊的 `.claude/settings.json`，提交到版本庫

13* 組織的 `managed-settings.json`

15每個檔案都是該讀者的合理檔案，因此您可以看到結構並複製您想要的部分。它們都不是建議的基準。每個數值都來自 [設定參考](/docs/zh-TW/settings-reference) 上的鍵項目，其中包含其類型、預設值和可以設定的位置。

17每個範例有兩個標籤。**可複製的設定檔** 是您儲存的檔案。**每個鍵的作用** 是相同的檔案，每個鍵上方有註解；Claude Code 不接受設定檔中的註解，因此請從第一個標籤複製。

19<h2 id="your-own-settings">

20 您自己的設定

21</h2>

23一位開發者的個人設定。它選擇一個模型和努力程度，調整終端機，並預先批准一個唯讀命令和一個檔案讀取。未列出的所有內容都保持其預設值。這樣的檔案放在 `~/.claude/settings.json` 中，適用於您開啟的每個專案。

25<Tabs>

26 <Tab title="可複製的設定檔">

27 將此儲存為 `~/.claude/settings.json`。這是有效的 JSON，沒有註解，因此您可以直接貼上並刪除您不想要的鍵。

29 ```json ~/.claude/settings.json theme={null}

30 {

31 "model": "claude-sonnet-5",

32 "effortLevel": "xhigh",

33 "editorMode": "vim",

34 "theme": "light-daltonized",

35 "statusLine": {

36 "type": "command",

37 "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'",

38 "padding": 2

39 },

40 "spinnerTipsEnabled": false,

41 "preferredNotifChannel": "terminal_bell",

42 "permissions": {

43 "allow": [

44 "Bash(git diff *)",

45 "Read(~/.zshrc)"

46 ]

47 },

48 "autoUpdatesChannel": "stable",

49 "cleanupPeriodDays": 20

50 }

51 ```

52 </Tab>

54 <Tab title="每個鍵的作用">

55 相同的檔案，每個鍵上方有註解。在此閱讀；從另一個標籤複製，因為 Claude Code 不接受設定檔中的註解。

57 ```jsonc ~/.claude/settings.json theme={null}

58 {

59 // 在 Sonnet 5 上開始每個工作階段

60 "model": "claude-sonnet-5",

61 // 在沒有儲存級別的模型上進行比預設高級別更深入的推理；/effort 為每個模型儲存一個級別，--effort 為單個工作階段設定一個級別

62 "effortLevel": "xhigh",

63 // 提示中的 Vim 快捷鍵

64 "editorMode": "vim",

65 // 色盲友善的淺色主題

66 "theme": "light-daltonized",

67 // 提示下方的狀態列：模型名稱和已使用的內容

68 "statusLine": {

69 "type": "command",

70 "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'",

71 "padding": 2

72 },

73 // 隱藏在微調器下旋轉的提示

74 "spinnerTipsEnabled": false,

75 // 為通知（例如完成的任務或等待的權限提示）響鈴終端機鈴聲

76 "preferredNotifChannel": "terminal_bell",

77 // 讓 Claude Code 執行 git diff 並讀取您的 .zshrc，無需詢問

78 "permissions": {

79 "allow": [

80 "Bash(git diff *)",

81 "Read(~/.zshrc)"

82 ]

83 },

84 // 從穩定通道取得更新

85 "autoUpdatesChannel": "stable",

86 // 刪除超過 20 天的工作階段記錄和其他本機工作階段資料

87 "cleanupPeriodDays": 20

88 }

89 ```

90 </Tab>

91</Tabs>

93<h2 id="a-teams-shared-settings">

94 團隊的共享設定

95</h2>

97一個團隊的共享設定，提交到版本庫，以便每個複製它的人都獲得相同的權限、hooks、遙測和外掛程式市集。在版本庫的頂部將這樣的檔案儲存在 `.claude/settings.json`。提交之前需要了解的事項：

99* **雲端工作階段也會讀取它。** Claude Code 網頁版上的 [雲端工作階段](/docs/zh-TW/settings#settings-in-cloud-sessions) 從版本庫的複製開始，因此提交的檔案也適用於此。

100* **允許規則等待信任。** 允許規則和 `extraKnownMarketplaces` 項目在每個人 [信任此資料夾本身](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust) 後生效，不僅是父資料夾；拒絕和詢問規則在每個工作階段中適用，無論是否信任。

101* **hook 是版本庫中的指令碼。** 此檔案的 hook 執行 `.claude/hooks/block-rm.sh`；[hook 如何解析](/docs/zh-TW/hooks#how-a-hook-resolves) 說明如何編寫它。

102* **規則匹配所寫的命令和路徑。** `Bash(git push *)` 不匹配 [`git -C . push`](/docs/zh-TW/permissions#bash-rule-limits)。`Read(./.env)` 本身會停止檔案工具和命名檔案的命令，例如 `cat .env`，但不會停止 [`grep -r` 在目錄上執行](/docs/zh-TW/permissions#read-and-edit)；此檔案中的 `sandbox` 區塊關閉了該間隙，因為沙箱 [新增您的 `Read` 拒絕路徑](/docs/zh-TW/settings-reference#sandbox-filesystem-denyread) 到每個沙箱化命令無法讀取的內容。

103

104<Tabs>

105 <Tab title="可複製的設定檔">

106 將此儲存為版本庫頂部的 `.claude/settings.json` 並提交。這是有效的 JSON，沒有註解，因此您可以直接貼上並刪除您不想要的鍵。

107

108 ```json .claude/settings.json theme={null}

109 {

110 "permissions": {

111 "allow": [

112 "Bash(npm run *)"

113 ],

114 "ask": [

115 "Bash(git push *)"

116 ],

117 "deny": [

118 "Read(./.env)",

119 "Read(./.env.*)",

120 "Read(./secrets/**)"

121 ]

122 },

123 "env": {

124 "CLAUDE_CODE_ENABLE_TELEMETRY": "1",

125 "OTEL_METRICS_EXPORTER": "otlp",

126 "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",

127 "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4317"

128 },

129 "hooks": {

130 "PreToolUse": [

131 {

132 "matcher": "Bash",

133 "hooks": [

134 {

135 "type": "command",

136 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh"

137 }

138 ]

139 }

140 ]

141 },

142 "extraKnownMarketplaces": {

143 "acme-tools": {

144 "source": {

145 "source": "github",

146 "repo": "acme-corp/claude-plugins"

147 }

148 }

149 },

150 "enabledPlugins": {

151 "code-formatter@acme-tools": true

152 },

153 "sandbox": {

154 "enabled": true,

155 "filesystem": {

156 "allowWrite": [

157 "/tmp/build"

158 ]

159 },

160 "network": {

161 "allowedDomains": [

162 "registry.npmjs.org",

163 "*.example.com"

164 ]

165 }

166 },

167 "plansDirectory": "./plans"

168 }

169 ```

170 </Tab>

171

172 <Tab title="每個鍵的作用">

173 相同的檔案，每個鍵上方有註解。在此閱讀；從另一個標籤複製，因為 Claude Code 不接受設定檔中的註解。

174

175 ```jsonc .claude/settings.json theme={null}

176 {

177 "permissions": {

178 // 執行 npm 指令碼，無需詢問

179 "allow": [

180 "Bash(npm run *)"

181 ],

182 // 在 git push 命令前確認

183 "ask": [

184 "Bash(git push *)"

185 ],

186 // 拒絕檔案工具和檔案讀取命令讀取環境檔案和 secrets 資料夾

187 "deny": [

188 "Read(./.env)",

189 "Read(./.env.*)",

190 "Read(./secrets/**)"

191 ]

192 },

193 // 透過 gRPC 將 OpenTelemetry 指標傳送到團隊的收集器；將端點替換為您的收集器 URL

194 "env": {

195 "CLAUDE_CODE_ENABLE_TELEMETRY": "1",

196 "OTEL_METRICS_EXPORTER": "otlp",

197 "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",

198 "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4317"

199 },

200 // 在每個 Bash 命令前，執行版本庫中可以阻止它的指令碼

201 "hooks": {

202 "PreToolUse": [

203 {

204 "matcher": "Bash",

205 "hooks": [

206 {

207 "type": "command",

208 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh"

209 }

210 ]

211 }

212 ]

213 },

214 // 在每個複製上註冊團隊的外掛程式市集

215 "extraKnownMarketplaces": {

216 "acme-tools": {

217 "source": {

218 "source": "github",

219 "repo": "acme-corp/claude-plugins"

220 }

221 }

222 },

223 // 啟用該市集中的一個外掛程式；來自外部來源（例如 GitHub 版本庫）的外掛程式仍需要每個人安裝一次

224 "enabledPlugins": {

225 "code-formatter@acme-tools": true

226 },

227 // 沙箱命令：可寫的建置目錄；npm 和 example.com 預先允許，其他主機仍會提示

228 "sandbox": {

229 "enabled": true,

230 "filesystem": {

231 "allowWrite": [

232 "/tmp/build"

233 ]

234 },

235 "network": {

236 "allowedDomains": [

237 "registry.npmjs.org",

238 "*.example.com"

239 ]

240 }

241 },

242 // 將計畫檔案保留在版本庫內

243 "plansDirectory": "./plans"

244 }

245 ```

246 </Tab>

247</Tabs>

248

249<h2 id="an-organizations-managed-settings">

250 組織的受管設定

251</h2>

252

253一個 `managed-settings.json` 檔案，顯示受管鍵的形狀，每個都有一個合理的數值。這不是建議的政策：選擇符合您自己要求的鍵並設定您自己的數值。該範例設定這些鍵：

254

255* `forceLoginMethod` 和 `forceLoginOrgUUID` 固定登入方法和組織

256* `availableModels` 和 `enforceAvailableModels` 限制工作階段可以使用的模型

257* `permissions.deny` 拒絕兩個檔案讀取和 `curl` 命令 [如 Claude 所寫](/docs/zh-TW/permissions#bash-rule-limits)，`disableBypassPermissionsMode` 移除繞過權限模式

258* [`allowManagedPermissionRulesOnly`](/docs/zh-TW/settings-reference#allowmanagedpermissionrulesonly) 和 [`allowManagedMcpServersOnly`](/docs/zh-TW/settings-reference#allowmanagedmcpserversonly) 使受管權限和 MCP 允許清單成為唯一適用的清單

259* `allowedMcpServers` 透過 URL 固定 MCP 伺服器

260* `strictKnownMarketplaces` 允許一個外掛程式市集

261* `sandbox` 沙箱化命令，具有固定的網路允許清單且無沙箱外重試

262* `requiredMinimumVersion` 設定最低 Claude Code 版本

263* `cleanupPeriodDays` 將工作階段記錄和其他本機資料的保留期縮短至七天

264* `companyAnnouncements` 在啟動時顯示訊息

265

266管理員將這樣的檔案部署為 `managed-settings.json`，或透過 MDM 或 [伺服器受管設定](/docs/zh-TW/server-managed-settings) 部署相同的 JSON。一個部署的檔案適用於它到達的每台機器或帳戶。要為一個群組提供不同的數值，請將不同的檔案或設定檔部署到該群組，因為 [伺服器受管設定尚不支援每個群組的政策](/docs/zh-TW/server-managed-settings#current-limitations)。

267

268<Tabs>

269 <Tab title="可複製的設定檔">

270 將此部署為 `managed-settings.json`，或透過 MDM 或 claude.ai 主控台部署相同的 JSON。這是有效的 JSON，沒有註解；將範例組織 UUID、伺服器 URL 和市集替換為您自己的，並刪除您不想要的鍵。

271

272 ```json managed-settings.json theme={null}

273 {

274 "forceLoginMethod": "claudeai",

275 "forceLoginOrgUUID": [

276 "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

277 ],

278 "availableModels": [

279 "opus",

280 "sonnet"

281 ],

282 "enforceAvailableModels": true,

283 "permissions": {

284 "deny": [

285 "Bash(curl *)",

286 "Read(./.env)",

287 "Read(./secrets/**)"

288 ],

289 "disableBypassPermissionsMode": "disable"

290 },

291 "allowManagedPermissionRulesOnly": true,

292 "allowedMcpServers": [

293 {

294 "serverUrl": "https://api.githubcopilot.com/*"

295 }

296 ],

297 "allowManagedMcpServersOnly": true,

298 "strictKnownMarketplaces": [

299 {

300 "source": "github",

301 "repo": "acme-corp/approved-plugins"

302 }

303 ],

304 "sandbox": {

305 "enabled": true,

306 "failIfUnavailable": true,

307 "allowUnsandboxedCommands": false,

308 "network": {

309 "allowedDomains": [

310 "registry.npmjs.org",

311 "github.com"

312 ],

313 "allowManagedDomainsOnly": true

314 }

315 },

316 "requiredMinimumVersion": "2.1.150",

317 "cleanupPeriodDays": 7,

318 "companyAnnouncements": [

319 "Welcome to Acme Corp! Review our code guidelines at docs.example.com"

320 ]

321 }

322 ```

323 </Tab>

324

325 <Tab title="每個鍵的作用">

326 相同的檔案，每個鍵上方有註解。在此閱讀；從另一個標籤複製，因為 Claude Code 不接受設定檔中的註解。

327

328 ```jsonc managed-settings.json theme={null}

329 {

330 // 僅 claude.ai 登入，且僅在此組織中

331 "forceLoginMethod": "claudeai",

332 "forceLoginOrgUUID": [

333 "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

334 ],

335 // 僅 Opus 和 Sonnet 模型；使用 enforceAvailableModels，預設選項也遵守清單

336 "availableModels": [

337 "opus",

338 "sonnet"

339 ],

340 "enforceAvailableModels": true,

341 "permissions": {

342 // 在每台機器上拒絕 curl 命令和讀取專案的 .env 檔案和 secrets 資料夾

343 "deny": [

344 "Bash(curl *)",

345 "Read(./.env)",

346 "Read(./secrets/**)"

347 ],

348 // 從每個工作階段移除繞過權限模式

349 "disableBypassPermissionsMode": "disable"

350 },

351 // 忽略來自使用者、專案和本機設定的權限規則

352 "allowManagedPermissionRulesOnly": true,

353 // 僅 GitHub MCP 伺服器，透過 URL 而非名稱匹配，因為使用者可以

354 // 將任何伺服器命名為 "github"。不匹配的使用者新增伺服器不會載入，包括

355 // 當清單僅有 URL 項目時的每個 stdio 伺服器。下面的 allowManagedMcpServersOnly

356 // 鍵使此受管清單成為唯一適用的允許清單

357 "allowedMcpServers": [

358 {

359 "serverUrl": "https://api.githubcopilot.com/*"

360 }

361 ],

362 "allowManagedMcpServersOnly": true,

363 // 外掛程式只能來自此市集

364 "strictKnownMarketplaces": [

365 {

366 "source": "github",

367 "repo": "acme-corp/approved-plugins"

368 }

369 ],

370 // 沙箱化 Claude 執行的每個命令，如果無法設定沙箱則拒絕啟動，

371 // 並且永遠不讓被阻止的命令在沙箱外重試；網路

372 // 限制為 npm 和 GitHub，使用者無法新增網域

373 "sandbox": {

374 "enabled": true,

375 "failIfUnavailable": true,

376 "allowUnsandboxedCommands": false,

377 "network": {

378 "allowedDomains": [

379 "registry.npmjs.org",

380 "github.com"

381 ],

382 "allowManagedDomainsOnly": true

383 }

384 },

385 // 拒絕在 2.1.150 之前的版本上啟動

386 "requiredMinimumVersion": "2.1.150",

387 // 在 7 天後刪除工作階段記錄和其他本機工作階段資料

388 "cleanupPeriodDays": 7,

389 // 每個使用者在啟動時看到的訊息

390 "companyAnnouncements": [

391 "Welcome to Acme Corp! Review our code guidelines at docs.example.com"

392 ]

393 }

394 ```

395 </Tab>

396</Tabs>

settings-reference.md +6509 −0 created

Details

Diff Too Large View Raw

setup.md +15 −13

Details

41 初次使用終端機？請參閱[終端機指南](/docs/zh-TW/terminal-guide)以取得逐步說明。41 初次使用終端機？請參閱[終端機指南](/docs/zh-TW/terminal-guide)以取得逐步說明。

42</Tip>42</Tip>

43 43

~~44To install Claude Code, use one of the following methods:~~44若要安裝 Claude Code，請使用下列其中一種方法：

45 45

46<Tabs>46<Tabs>

~~47 <Tab title="Native Install (Recommended)">~~47 <Tab title="原生安裝（建議）">

~~48 **macOS, Linux, WSL:**~~48 **macOS、Linux、WSL：**

49 49

50 ```bash theme={null}50 ```bash theme={null}

51 curl -fsSL https://claude.ai/install.sh | bash51 curl -fsSL https://claude.ai/install.sh | bash

52 ```52 ```

53 53

~~54 **Windows PowerShell:**~~54 **Windows PowerShell：**

55 55

56 ```powershell theme={null}56 ```powershell theme={null}

57 irm https://claude.ai/install.ps1 | iex57 irm https://claude.ai/install.ps1 | iex

58 ```58 ```

59 59

~~60 **Windows CMD:**~~60 **Windows CMD：**

61 61

62 ```batch theme={null}62 ```batch theme={null}

63 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd63 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

64 ```64 ```

65 65

66 If you see `The token '&&' is not a valid statement separator`, you're in PowerShell, not CMD. If you see `'irm' is not recognized as an internal or external command`, you're in CMD, not PowerShell. Your prompt shows `PS C:\` when you're in PowerShell and `C:\` without the `PS` when you're in CMD.66 如果您看到 `The token '&&' is not a valid statement separator`，表示您在 PowerShell 中，而非 CMD。如果您看到 `'irm' is not recognized as an internal or external command`，表示您在 CMD 中，而非 PowerShell。當您在 PowerShell 中時，提示符會顯示 `PS C:\`，而在 CMD 中時會顯示 `C:\`（不含 `PS`）。

67 67

68 If the install command fails with `syntax error near unexpected token '<'`, a `403`, or another curl error, see [Troubleshoot installation](/docs/en/troubleshoot-install#find-your-error) to match the error to a fix and for alternative install methods.68 如果安裝命令失敗並出現 `syntax error near unexpected token '<'`、`403` 或其他 curl 錯誤，請參閱[疑難排解安裝](/docs/zh-TW/troubleshoot-install#find-your-error)以將錯誤與修正相對應，並查看替代安裝方法。

69 69

70 [Git for Windows](https://git-scm.com/downloads/win) is recommended on native Windows so Claude Code can use the Bash tool. If Git for Windows is not installed, Claude Code uses PowerShell as the shell tool instead. WSL setups do not need Git for Windows.70 建議在原生 Windows 上安裝 [Git for Windows](https://git-scm.com/downloads/win)，以便 Claude Code 可以使用 Bash 工具。如果未安裝 Git for Windows，Claude Code 會改用 PowerShell 作為殼層工具。WSL 設定不需要 Git for Windows。

71 71

72 <Info>72 <Info>

~~73 Native installations automatically update in the background to keep you on the latest version.~~73 原生安裝會在背景自動更新，以保持您使用最新版本。

74 </Info>74 </Info>

75 </Tab>75 </Tab>

76 76

79 brew install --cask claude-code79 brew install --cask claude-code

80 ```80 ```

81 81

82 Homebrew offers two casks. `claude-code` tracks the stable release channel, which is typically about a week behind and skips releases with major regressions. `claude-code@latest` tracks the latest channel and receives new versions as soon as they ship.82 Homebrew 提供兩個 casks。`claude-code` 追蹤穩定版本通道，通常比最新版本晚約一週，並跳過有重大迴歸的版本。`claude-code@latest` 追蹤最新通道，並在新版本發佈時立即接收。

83 83

84 <Info>84 <Info>

85 Homebrew installations do not auto-update. Run `brew upgrade claude-code` or `brew upgrade claude-code@latest`, depending on which cask you installed, to get the latest features and security fixes.85 Homebrew 安裝不會自動更新。執行 `brew upgrade claude-code` 或 `brew upgrade claude-code@latest`（取決於您安裝的 cask），以取得最新功能和安全修正。

86 </Info>86 </Info>

87 </Tab>87 </Tab>

88 88

92 ```92 ```

93 93

94 <Info>94 <Info>

~~95 WinGet installations do not auto-update. Run `winget upgrade Anthropic.ClaudeCode` periodically to get the latest features and security fixes.~~95 WinGet 安裝不會自動更新。定期執行 `winget upgrade Anthropic.ClaudeCode` 以取得最新功能和安全修正。

96 </Info>96 </Info>

97 </Tab>97 </Tab>

98</Tabs>98</Tabs>

99 99

100You can also install with [apt, dnf, or apk](/docs/en/setup#install-with-linux-package-managers) on Debian, Fedora, RHEL, and Alpine.100您也可以在 Debian、Fedora、RHEL 和 Alpine 上使用 [apt、dnf 或 apk](/docs/zh-TW/setup#install-with-linux-package-managers) 進行安裝。

101 101

102安裝完成後，在您要使用的專案中開啟終端機並啟動 Claude Code：102安裝完成後，在您要使用的專案中開啟終端機並啟動 Claude Code：

103 103

296}296}

297```297```

298 298

299在原生或 npm 安裝上，透過執行 `claude doctor` 並檢查 `Auto-updates` 行是否顯示 `disabled (set by env: DISABLE_AUTOUPDATER)` 而不是 `enabled` 來確認變更已生效。

300

299`DISABLE_AUTOUPDATER` 只會停止背景檢查；`claude update` 和 `claude install` 仍然有效。若要阻止所有更新路徑（包括手動更新），請改為設定 [`DISABLE_UPDATES`](/docs/zh-TW/env-vars)。當您透過自己的通道發佈 Claude Code 並需要使用者保持在您提供的版本上時，請使用此選項。301`DISABLE_AUTOUPDATER` 只會停止背景檢查；`claude update` 和 `claude install` 仍然有效。若要阻止所有更新路徑（包括手動更新），請改為設定 [`DISABLE_UPDATES`](/docs/zh-TW/env-vars)。當您透過自己的通道發佈 Claude Code 並需要使用者保持在您提供的版本上時，請使用此選項。

300 302

301<h3 id="update-manually">303<h3 id="update-manually">

skills.md +24 −15

Details

28 28

29大多數捆綁技能在每個工作階段中都可用。少數技能取決於特定功能：例如 `/workflow-authoring` 只有在[動態工作流程](/docs/zh-TW/workflows)啟用時才可用。29大多數捆綁技能在每個工作階段中都可用。少數技能取決於特定功能：例如 `/workflow-authoring` 只有在[動態工作流程](/docs/zh-TW/workflows)啟用時才可用。

30 30

~~31若要關閉捆綁技能，請使用 [`disableBundledSkills`](/docs/zh-TW/settings-reference#disablebundledskills) 設定，它會停用除 `/doctor` 外的所有捆綁技能。~~31若要關閉捆綁技能，請使用 [`disableBundledSkills`](/docs/zh-TW/settings-reference#disablebundledskills) 設定。

32 32

33<Note>33<Note>

34 在 Claude Code v2.1.205 及更新版本中，當 `disableBundledSkills` 開啟時，[`/doctor`](/docs/zh-TW/commands#all-commands) 設定檢查仍可輸入。若要隱藏它，請設定 `DISABLE_DOCTOR_COMMAND` 環境變數或 [`skillOverrides`](#override-skill-visibility-from-settings) 項目 `"doctor": "off"`。在 v2.1.205 之前，`/doctor` 是內建命令而非捆綁技能。34 在 Claude Code v2.1.205 及更新版本中，當 `disableBundledSkills` 開啟時，[`/doctor`](/docs/zh-TW/commands#all-commands) 設定檢查仍可輸入。若要隱藏它，請設定 `DISABLE_DOCTOR_COMMAND` 環境變數或 [`skillOverrides`](#override-skill-visibility-from-settings) 項目 `"doctor": "off"`。在 v2.1.205 之前，`/doctor` 是內建命令而非捆綁技能。

136 136

137* **符號連結資料夾**：enterprise、personal 或 project 位置中的 `<skill-name>` 項目可以是指向磁碟上其他位置的符號連結。Claude Code 從目標讀取 `SKILL.md` 並載入技能一次，即使多個位置指向同一目標。Plugin 技能[以不同方式處理符號連結](/docs/zh-TW/plugins-reference#share-files-within-a-marketplace-with-symlinks)。137* **符號連結資料夾**：enterprise、personal 或 project 位置中的 `<skill-name>` 項目可以是指向磁碟上其他位置的符號連結。Claude Code 從目標讀取 `SKILL.md` 並載入技能一次，即使多個位置指向同一目標。Plugin 技能[以不同方式處理符號連結](/docs/zh-TW/plugins-reference#share-files-within-a-marketplace-with-symlinks)。

138* **保留名稱**：不要將技能資料夾命名為 `synced`，無論大小寫如何。Claude Code 使用 `~/.claude/skills/synced/` 來[儲存從 claude.ai 下載的技能](#where-synced-skills-load)，並跳過您在 enterprise、personal 和 project 位置中以該名稱編寫的技能。138* **保留名稱**：不要將技能資料夾命名為 `synced`，無論大小寫如何。Claude Code 使用 `~/.claude/skills/synced/` 來[儲存從 claude.ai 下載的技能](#where-synced-skills-load)，並跳過您在 enterprise、personal 和 project 位置中以該名稱編寫的技能。

139* **命令檔案**：`.claude/commands/` 中的 Markdown 檔案是較舊的格式，仍然有效。它支援相同的 [frontmatter](#frontmatter-reference)，除了 `name` 和 `paths`，您可以按其檔案名稱叫用它。對於新工作，建議使用技能，因為技能也支援[支援檔案](#add-supporting-files)。139* **命令檔案**：`.claude/commands/` 中的 Markdown 檔案是較舊的格式，仍然有效。它支援相同的 [frontmatter](#frontmatter-reference)，除了 `name` 和 `paths`。若要找到您輸入以叫用它的名稱，請參閱[技能如何取得其命令名稱](#how-a-skill-gets-its-command-name)。對於新工作，建議使用技能，因為技能也支援[支援檔案](#add-supporting-files)。

140* **技能資料夾作為 plugin**：將 `.claude-plugin/plugin.json` 新增到技能資料夾，它會載入為名為 `<name>@skills-dir` 的 [plugin](/docs/zh-TW/plugins-reference#skills-directory-plugins)，因此可以捆綁代理、hooks 和 MCP 伺服器。在專案的 `.claude/skills/` 中，這需要先接受工作區信任對話。140* **技能資料夾作為 plugin**：將 `.claude-plugin/plugin.json` 新增到技能資料夾，它會載入為名為 `<name>@skills-dir` 的 [plugin](/docs/zh-TW/plugins-reference#skills-directory-plugins)，因此可以捆綁代理、hooks 和 MCP 伺服器。在專案的 `.claude/skills/` 中，這需要先接受工作區信任對話。

141 141

142<h3 id="discovery-from-parent-and-nested-directories">142<h3 id="discovery-from-parent-and-nested-directories">

234 234

235Claude Code 標籤同步技能，以便您可以判斷它們的來源。`/skills` 功能表和 `/context` 在 `claude.ai sync` 下分組同步技能，`/` 命令功能表將它們標記為來自 claude.ai。235Claude Code 標籤同步技能，以便您可以判斷它們的來源。`/skills` 功能表和 `/context` 在 `claude.ai sync` 下分組同步技能，`/` 命令功能表將它們標記為來自 claude.ai。

236 236

237比較名稱時，Claude Code 忽略大小寫、間距和不可見字元，並將相容性形式（如全寬字母和破折號變體）視為其純等效項，因此同步的 `Commit` 無法與本機 `commit` 並排載入。名稱僅因來自另一個字母表的相似字母而異，計為不同名稱，`claude.ai sync` 標籤是您區分兩者的方式。237比較名稱時，Claude Code 忽略大小寫、間距和不可見字元，並將相容性形式（如全寬字母和破折號變體）視為其純等效項，因此同步的 `Commit` 無法與本機 `commit` 並排載入。名稱僅因來自另一個字母表的相似字母而異，計為不同名稱，`claude.ai sync` 標籤是您區分兩者的方式。這些檢查和標籤需要 Claude Code v2.1.228 或更新版本。

238 238

239<h4 id="how-claude-code-handles-the-frontmatter-of-a-synced-skill">239<h4 id="how-claude-code-handles-the-frontmatter-of-a-synced-skill">

240 Claude Code 如何處理同步技能的 frontmatter240 Claude Code 如何處理同步技能的 frontmatter

243Claude Code 對同步技能的 frontmatter 應用兩個規則：243Claude Code 對同步技能的 frontmatter 應用兩個規則：

244 244

245* Claude Code 在每種工作階段中都遵守 frontmatter，因此 `allowed-tools` 授予會通過正常的[權限流程](/docs/zh-TW/permissions)。245* Claude Code 在每種工作階段中都遵守 frontmatter，因此 `allowed-tools` 授予會通過正常的[權限流程](/docs/zh-TW/permissions)。

246* Claude Code 清理技能提供的顯示文字，例如其描述。它移除控制字元，在到達 Claude 的文字（例如描述）中，它也會逸出角括號，以便文字無法模仿 Claude Code 的內部格式。246* Claude Code 清理技能提供的顯示文字，例如其描述。它移除控制字元，在到達 Claude 的文字（例如描述）中，它也會逸出角括號，以便文字無法模仿 Claude Code 的內部格式。此清理需要 Claude Code v2.1.228 或更新版本。

247 247

248<h4 id="how-claude-code-handles-the-body-of-a-synced-skill">248<h4 id="how-claude-code-handles-the-body-of-a-synced-skill">

249 Claude Code 如何處理同步技能的主體249 Claude Code 如何處理同步技能的主體

253 253

254* 在雲端工作階段中，主體保持本機技能具有的行為，因為工作階段在隔離容器中執行。254* 在雲端工作階段中，主體保持本機技能具有的行為，因為工作階段在隔離容器中執行。

255* 在您桌面上的 Cowork 工作階段中，主體保持本機技能具有的行為，除了 Claude Code 將每個 `!` 命令列替換為 [`disableSkillShellExecution` 預留位置](#inject-dynamic-context)，就像它對您在那裡提供的每個技能所做的一樣。255* 在您桌面上的 Cowork 工作階段中，主體保持本機技能具有的行為，除了 Claude Code 將每個 `!` 命令列替換為 [`disableSkillShellExecution` 預留位置](#inject-dynamic-context)，就像它對您在那裡提供的每個技能所做的一樣。

256* 在您機器上的任何其他工作階段中，Claude Code 不執行 [`!` 命令](#inject-dynamic-context)，不附加 `@` 參考命名的檔案（就像它對本機技能所做的一樣），也不替換 `${CLAUDE_PROJECT_DIR}` 和 `${CLAUDE_SESSION_ID}` 預留位置，因此 `@` 參考和兩個預留位置都作為字面文字到達 Claude。`!` 命令列也作為字面文字到達 Claude，或當 `disableSkillShellExecution` 開啟時作為該預留位置。256* 在您機器上的任何其他工作階段中，Claude Code 不執行 [`!` 命令](#inject-dynamic-context)，不附加 `@` 參考命名的檔案（就像它對本機技能所做的一樣），也不替換 `${CLAUDE_PROJECT_DIR}` 和 `${CLAUDE_SESSION_ID}` 預留位置，因此 `@` 參考和兩個預留位置都作為字面文字到達 Claude。`!` 命令列也作為字面文字到達 Claude，或當 `disableSkillShellExecution` 開啟時作為該預留位置。此處理需要 Claude Code v2.1.228 或更新版本。

257 257

258<h3 id="live-change-detection">258<h3 id="live-change-detection">

259 在工作階段期間編輯技能259 在工作階段期間編輯技能

271 271

272* **Personal 或 project 技能**：刪除技能的目錄，`~/.claude/skills/<skill-name>/` 或 `.claude/skills/<skill-name>/`。Claude Code [在目前工作階段中將其從 `/skills` 中移除](#live-change-detection)；Claude Code 已從其載入的內容遵循[技能內容生命週期](#skill-content-lifecycle)。272* **Personal 或 project 技能**：刪除技能的目錄，`~/.claude/skills/<skill-name>/` 或 `.claude/skills/<skill-name>/`。Claude Code [在目前工作階段中將其從 `/skills` 中移除](#live-change-detection)；Claude Code 已從其載入的內容遵循[技能內容生命週期](#skill-content-lifecycle)。

273* **Enterprise 技能**：管理員從[受管設定目錄](/docs/zh-TW/managed-settings#delivery-mechanisms)內的 `.claude/skills/` 刪除技能的目錄，例如 Linux 上的 `/etc/claude-code/.claude/skills/<skill-name>/`。273* **Enterprise 技能**：管理員從[受管設定目錄](/docs/zh-TW/managed-settings#delivery-mechanisms)內的 `.claude/skills/` 刪除技能的目錄，例如 Linux 上的 `/etc/claude-code/.claude/skills/<skill-name>/`。

274* **Plugin 技能**：從 `/plugin` 功能表停用或解除安裝提供它的 plugin，或使用 `/plugin uninstall <plugin-name>@<marketplace-name>`。Claude Code 在您執行 `/reload-plugins` 或重新啟動後卸載 plugin 的技能；請參閱[不重新啟動即可應用 plugin 變更](/docs/zh-TW/discover-plugins#apply-plugin-changes-without-restarting)。274* **Plugin 技能**：從 `/plugin` 功能表停用或解除安裝提供它的 plugin，或使用 `/plugin uninstall <plugin-name>@<marketplace-name>`。Claude Code 在[變更套用](/docs/zh-TW/discover-plugins#apply-plugin-changes-without-restarting)時或當您重新啟動時卸載 plugin 的技能。

275* **從 claude.ai 同步的技能**：在您[啟用它](#skills-in-cowork-and-cloud-sessions)的相同位置為您的 claude.ai 帳戶關閉該技能。Claude Code 在下次[同步您的技能](#where-synced-skills-load)時將其從 `~/.claude/skills/synced/` 中移除。如果您改為手動刪除目錄，下次同步會在技能在 claude.ai 上保持啟用時再次下載它。275* **從 claude.ai 同步的技能**：在您[啟用它](#skills-in-cowork-and-cloud-sessions)的相同位置為您的 claude.ai 帳戶關閉該技能。Claude Code 在下次[同步您的技能](#where-synced-skills-load)時將其從 `~/.claude/skills/synced/` 中移除。如果您改為手動刪除目錄，下次同步會在技能在 claude.ai 上保持啟用時再次下載它。

276* **捆綁技能**：將 [`disableBundledSkills`](#bundled-skills) 設定為 `true` 以關閉除 `/doctor` 外的每個捆綁技能，或在 [`skillOverrides`](#override-skill-visibility-from-settings) 中將一個技能設定為 `"off"` 以隱藏它。276* **捆綁技能**：將 [`disableBundledSkills`](#bundled-skills) 設定為 `true` 以關閉捆綁技能，或在 [`skillOverrides`](#override-skill-visibility-from-settings) 中將一個技能設定為 `"off"` 以隱藏它。

277 277

278若要保留 personal 或 project 技能但停止 Claude 自動叫用它，請在其 frontmatter 中設定 [`disable-model-invocation: true`](#control-who-invokes-a-skill)，或在 [`skillOverrides`](#override-skill-visibility-from-settings) 中設定 `"user-invocable-only"`（當您不想編輯檔案時）。278若要保留 personal 或 project 技能但停止 Claude 自動叫用它，請在其 frontmatter 中設定 [`disable-model-invocation: true`](#control-who-invokes-a-skill)，或在 [`skillOverrides`](#override-skill-visibility-from-settings) 中設定 `"user-invocable-only"`（當您不想編輯檔案時）。

279 279

397下表顯示了每個佈局的命令名稱來自何處：397下表顯示了每個佈局的命令名稱來自何處：

398 398

399| Skill 位置 | 命令名稱來源 | 範例 |399| Skill 位置 | 命令名稱來源 | 範例 |

400| :------------------------------------------------------------- | :------------------------------------- | :--------------------------------------------------------------------------------------------------------------------- |400| :------------------------------------------------------------- | :-------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------- |

404| `.claude/commands/` 的子目錄中的檔案 | 相對於 `commands/` 的子目錄路徑，每個 `/` 替換為 `:`，然後是不含副檔名的檔案名稱 | `.claude/commands/frontend/component.md` → `/frontend:component` |

405| Plugin 根 `SKILL.md` | Frontmatter `name`，以 plugin 目錄名稱作為後備 | `my-plugin/SKILL.md` 搭配 `name: review` → `/my-plugin:review`。請參閱[路徑行為規則](/docs/zh-TW/plugins-reference#path-behavior-rules) |406| Plugin 根 `SKILL.md` | Frontmatter `name`，以 plugin 目錄名稱作為後備 | `my-plugin/SKILL.md` 搭配 `name: review` → `/my-plugin:review`。請參閱[路徑行為規則](/docs/zh-TW/plugins-reference#path-behavior-rules) |

406 407

630 注入動態內容631 注入動態內容

631</h3>632</h3>

632 633

633`` !`<command>` `` 語法在技能內容傳送給 Claude 之前執行 shell 命令。命令輸出會取代佔位符，所以 Claude 會收到實際資料，而不是命令本身。當技能從您的 claude.ai 帳戶[同步](#how-claude-code-handles-the-body-of-a-synced-skill)時，Claude Code 不會在您的機器上執行這些命令。634`` !`<command>` `` 語法在技能內容傳送給 Claude 之前執行 shell 命令。命令輸出會取代佔位符，所以 Claude 會收到實際資料，而不是命令本身。當技能從您的 claude.ai 帳戶[同步](#how-claude-code-handles-the-body-of-a-synced-skill)時，Claude Code 不會在您的機器上執行這些命令。此限制需要 Claude Code v2.1.228 或更新版本。

634 635

635此技能透過使用 GitHub CLI 擷取即時 PR 資料來總結拉取請求。`` !`gh pr diff` `` 和其他命令會先執行，其輸出會插入到提示中：636此技能透過使用 GitHub CLI 擷取即時 PR 資料來總結拉取請求。`` !`gh pr diff` `` 和其他命令會先執行，其輸出會插入到提示中：

636 637

668 669

669若要為來自使用者、專案、外掛程式或[其他目錄](#skills-from-additional-directories)來源的技能和自訂命令停用此行為，請在[設定](/docs/zh-TW/settings)中設定 `"disableSkillShellExecution": true`。每個命令都會被替換為 `[shell command execution disabled by policy]` 而不是被執行。捆綁和受管理的技能不受影響。此設定在[受管理設定](/docs/zh-TW/managed-settings)中最有用，使用者無法覆寫它。670若要為來自使用者、專案、外掛程式或[其他目錄](#skills-from-additional-directories)來源的技能和自訂命令停用此行為，請在[設定](/docs/zh-TW/settings)中設定 `"disableSkillShellExecution": true`。每個命令都會被替換為 `[shell command execution disabled by policy]` 而不是被執行。捆綁和受管理的技能不受影響。此設定在[受管理設定](/docs/zh-TW/managed-settings)中最有用，使用者無法覆寫它。

670 671

671當命令出現在從您的 claude.ai 帳戶[同步的技能](#how-synced-skills-behave)中時，Claude Code 永遠不會在您的機器上執行這些命令，無論此設定如何。[Claude Code 如何處理同步技能的主體](#how-claude-code-handles-the-body-of-a-synced-skill)說明了在每種工作階段中 Claude 會收到什麼來取代命令。672當命令出現在從您的 claude.ai 帳戶[同步的技能](#how-synced-skills-behave)中時，Claude Code 永遠不會在您的機器上執行這些命令，無論此設定如何。此限制需要 Claude Code v2.1.228 或更新版本。[Claude Code 如何處理同步技能的主體](#how-claude-code-handles-the-body-of-a-synced-skill)說明了在每種工作階段中 Claude 會收到什麼來取代命令。

672 673

673<Tip>674<Tip>

674 若要在技能執行時要求更深入的推理，請在技能內容中的任何地方包含 `ultrathink`。請參閱[使用 ultrathink 進行一次性深入推理](/docs/zh-TW/model-config#use-ultrathink-for-one-off-deep-reasoning)。675 若要在技能執行時要求更深入的推理，請在技能內容中的任何地方包含 `ultrathink`。請參閱[使用 ultrathink 進行一次性深入推理](/docs/zh-TW/model-config#use-ultrathink-for-one-off-deep-reasoning)。

716 在子代理中執行技能717 在子代理中執行技能

717</h3>718</h3>

718 719

719當您希望技能在隔離環境中執行時，請在 frontmatter 中新增 `context: fork`。技能內容會成為驅動子代理的提示。它將無法存取您的對話歷史記錄。720當您希望技能在隔離環境中執行時，請在 frontmatter 中新增 `context: fork`。Claude Code 會啟動在 `agent` 欄位中設定的類型的新子代理，並將技能內容作為其提示提供。子代理看不到您的對話歷史記錄，所以技能的指示必須獨立存在。

721

722<Note>

723 儘管名稱如此，具有 `context: fork` 的技能不會在[目前對話的分叉](/docs/zh-TW/sub-agents#fork-the-current-conversation)中執行，這會將您迄今為止討論的所有內容交給子代理。當工作取決於該歷史記錄時，請分叉對話而不是使用 `context: fork`。

724</Note>

720 725

721分叉的子代理在[背景](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)中執行：您可以在它執行時繼續工作，其結果在完成時到達您的對話。在 frontmatter 中設定 `background: false` 以改為在呼叫技能的回合中等待結果。在 v2.1.218 之前，分叉技能總是阻止回合直到它們完成。726分叉的子代理在[背景](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)中執行：您可以在它執行時繼續工作，其結果在完成時到達您的對話。在 frontmatter 中設定 `background: false` 以改為在呼叫技能的回合中等待結果。在 v2.1.218 之前，分叉技能總是阻止回合直到它們完成。

722 727

866 871

867兩者的檢查都是基線比較。收集幾個真實的提示，在有技能可用的新會話中運行每一個，然後在[禁用](#override-skill-visibility-from-settings)它的情況下再運行一次，並比較結果。新會話很重要，因為編寫技能時留下的上下文會掩蓋書面指示中的漏洞。872兩者的檢查都是基線比較。收集幾個真實的提示，在有技能可用的新會話中運行每一個，然後在[禁用](#override-skill-visibility-from-settings)它的情況下再運行一次，並比較結果。新會話很重要，因為編寫技能時留下的上下文會掩蓋書面指示中的漏洞。

868 873

874兩個工具可以自動化該比較。對於在[外掛](/docs/zh-TW/plugins)中發布的技能，[`claude plugin eval`](/docs/zh-TW/plugin-evals)在隔離的會話中運行每個提示，有和沒有外掛，使用你定義的或它為你編寫的評分器進行評分，並在低於閾值時以非零值退出，以便你可以在 CI 上進行控制。對於在 Claude Code 對話中迭代單個技能，下面的 skill-creator 外掛運行類似的迴圈，使用其自己的 `evals/evals.json` 格式。這兩種格式不可互換。

875

869<h3 id="run-evals-with-skill-creator">876<h3 id="run-evals-with-skill-creator">

870 使用 skill-creator 運行評估877 使用 skill-creator 運行評估

871</h3>878</h3>

881* `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 新增市場，然後重試安裝。888* `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 新增市場，然後重試安裝。

882* 外掛[在市場中找不到](/docs/zh-TW/discover-plugins#install-plugins)：檢查外掛名稱。889* 外掛[在市場中找不到](/docs/zh-TW/discover-plugins#install-plugins)：檢查外掛名稱。

883 890

884如果安裝摘要報告 `Run /reload-plugins to activate.`，執行該命令以在目前會話中啟用外掛的技能。然後要求 Claude 評估現有技能，例如 `evaluate my summarize-changes skill with skill-creator`。外掛會引導你完成編寫測試案例並運行迴圈：891如果安裝摘要報告 `Run /reload-plugins to activate.`，Claude Code 會為你運行該重新載入。如果重新載入警告你的下一則訊息會重新讀取對話，請運行 `/reload-plugins --force` 以在目前會話中啟用外掛的技能。然後要求 Claude 評估現有技能，例如 `evaluate my summarize-changes skill with skill-creator`。外掛會引導你完成編寫測試案例並運行迴圈：

885 892

886* **測試案例**：在技能目錄內的 `evals/evals.json` 中儲存提示、輸入檔案和預期行為893* **測試案例**：在技能目錄內的 `evals/evals.json` 中儲存提示、輸入檔案和預期行為

887* **隔離運行**：為每個測試案例生成一個[子代理](/docs/zh-TW/sub-agents)，以便每次運行都以乾淨的上下文開始，並記錄權杖計數和持續時間894* **隔離運行**：為每個測試案例生成一個[子代理](/docs/zh-TW/sub-agents)，以便每次運行都以乾淨的上下文開始，並記錄權杖計數和持續時間

11113. 嘗試重新表述您的請求以更密切地符合描述11183. 嘗試重新表述您的請求以更密切地符合描述

11124. 如果 skill 可由使用者叫用，請使用 `/skill-name` 直接叫用它11194. 如果 skill 可由使用者叫用，請使用 `/skill-name` 直接叫用它

1113 1120

1114如果 frontmatter YAML 格式不正確，Claude Code 會以空的中繼資料載入 skill 主體，因此 `/skill-name` 仍然有效，但 Claude 沒有 `description` 可進行比對。執行 `--debug` 以查看解析錯誤。1121如果 frontmatter YAML 格式不正確，Claude Code 會以空的中繼資料載入 skill 主體，因此 `/skill-name` 仍然有效，但 Claude 無法對您的 `description` 進行比對。使用 `--debug` 執行以查看解析錯誤。

1122

1123如果 skill 隨附在 plugin 中，您可以測量它在實際提示中觸發的頻率，而不是逐一檢查：使用 [`tool_used: Skill` grader](/docs/zh-TW/plugin-evals#create-your-first-eval-suite) 撰寫評估案例，並在每次描述變更後使用 `claude plugin eval` 執行它。

1115 1124

1116若要找到 frontmatter 無法解析的 `SKILL.md` 檔案，請在 skills 目錄上執行 [`claude plugin validate`](/docs/zh-TW/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest)，例如針對專案 skills 執行 `claude plugin validate .claude/skills`，或針對個人 skills 執行 `claude plugin validate ~/.claude/skills`。需要 Claude Code v2.1.233 或更新版本。1125若要找到 frontmatter 無法解析的 `SKILL.md` 檔案，請在 skills 目錄上執行 [`claude plugin validate`](/docs/zh-TW/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest)，例如針對專案 skills 執行 `claude plugin validate .claude/skills`，或針對個人 skills 執行 `claude plugin validate ~/.claude/skills`。需要 Claude Code v2.1.233 或更新版本。

1117 1126

1128 Skill 描述被截斷1137 Skill 描述被截斷

1129</h3>1138</h3>

1130 1139

1131Claude Code 會將 skill 名稱和描述的清單載入到上下文中，以便 Claude 知道有哪些可用項目。清單始終包含每個 skill 名稱，但如果您有許多 skills，Claude Code 會縮短描述以符合清單的字元預算，這可能會移除 Claude 需要比對您的請求的關鍵字。預算按模型上下文視窗的 1% 進行調整。當清單超出預算時，Claude Code 會從您叫用最少的 skills 開始刪除描述，因此您使用最多的 skills 會保留其完整文字。1140Claude Code 會將 skill 名稱和描述的清單載入到上下文中，以便 Claude 知道有哪些可用的。清單始終包含每個 skill 名稱，但如果您有許多 skills，Claude Code 會縮短描述以符合清單的字元預算，這可能會移除 Claude 需要比對您的請求的關鍵字。預算按模型上下文視窗的 1% 進行調整。當清單超出預算時，Claude Code 會從您叫用最少的 skills 開始刪除描述，因此您使用最多的 skills 會保留其完整文字。

1132 1141

1133執行 `/doctor` 以估計清單的上下文成本及其最大貢獻者。若要找到值得關閉的 skills，請執行 [`/skill-doctor`](#find-unused-skills)。當清單超出其預算時，Claude Code 也會將警告寫入偵錯日誌，可透過 [`--debug`](/docs/zh-TW/cli-reference#cli-flags) 查看。1142執行 `/doctor` 以估計清單的上下文成本及其最大貢獻者。若要找到值得關閉的 skills，請執行 [`/skill-doctor`](#find-unused-skills)。當清單超出其預算時，Claude Code 也會將警告寫入偵錯日誌，可透過 [`--debug`](/docs/zh-TW/cli-reference#cli-flags) 查看。

1134 1143

1135`/context` 中的 Skills 列會報告套用預算後清單的大小，因此它與模型接收的內容相符。在 v2.1.196 之前，該列會計算每個描述的完整文字，並可能顯示的值比設定的預算大好幾倍。1144`/context` 中的 Skills 列會報告套用預算後清單的大小，因此它與模型接收的內容相符。在 v2.1.196 之前，該列會計算每個描述的完整文字，並且可能顯示的值比設定的預算大好幾倍。

1136 1145

1137若要提高預算，請設定 [`skillListingBudgetFraction`](/docs/zh-TW/settings-reference#skilllistingbudgetfraction) 設定（例如 `0.02` = 2%）或 `SLASH_COMMAND_TOOL_CHAR_BUDGET` 環境變數為固定字元計數。若要為其他 skills 釋放預算，請在 [`skillOverrides`](#override-skill-visibility-from-settings) 中將低優先順序項目設定為 `"name-only"`，以便它們在沒有描述的情況下列出。您也可以在來源處修剪 `description` 和 `when_to_use` 文字：將關鍵使用案例放在首位，因為每個項目的組合文字上限為 1,536 個字元，無論預算如何。上限可透過 [`skillListingMaxDescChars`](/docs/zh-TW/settings-reference#skilllistingmaxdescchars) 進行設定。1146若要提高預算，請設定 [`skillListingBudgetFraction`](/docs/zh-TW/settings-reference#skilllistingbudgetfraction) 設定（例如 `0.02` = 2%）或 `SLASH_COMMAND_TOOL_CHAR_BUDGET` 環境變數為固定字元計數。若要為其他 skills 釋放預算，請在 [`skillOverrides`](#override-skill-visibility-from-settings) 中將低優先順序項目設定為 `"name-only"`，以便它們在沒有描述的情況下列出。您也可以在來源處修剪 `description` 和 `when_to_use` 文字：將關鍵使用案例放在首位，因為每個項目的組合文字上限為 1,536 個字元，無論預算如何。上限可透過 [`skillListingMaxDescChars`](/docs/zh-TW/settings-reference#skilllistingmaxdescchars) 進行設定。

1138 1147

sub-agents.md +4 −2

Details

304| `name` | 是 | 使用小寫字母和連字號的唯一識別碼。[Hooks](/docs/zh-TW/hooks#subagentstart) 將此值作為 `agent_type` 接收。檔案名稱不必相符。名稱不能包含 `:`，這是為 [plugin-scoped identifiers](/docs/zh-TW/plugins) 保留的，例如 `my-plugin:reviewer`。Claude Code 不會載入名稱包含一個的檔案，並將錯誤記錄到除錯日誌。在 v2.1.218 之前，此類名稱被接受 |304| `name` | 是 | 使用小寫字母和連字號的唯一識別碼。[Hooks](/docs/zh-TW/hooks#subagentstart) 將此值作為 `agent_type` 接收。檔案名稱不必相符。名稱不能包含 `:`，這是為 [plugin-scoped identifiers](/docs/zh-TW/plugins) 保留的，例如 `my-plugin:reviewer`。Claude Code 不會載入名稱包含一個的檔案，並將錯誤記錄到除錯日誌。在 v2.1.218 之前，此類名稱被接受 |

305| `description` | 是 | Claude 何時應委派給此 subagent |305| `description` | 是 | Claude 何時應委派給此 subagent |

306| `tools` | 否 | [Tools](#available-tools) subagent 可以使用。如果省略，繼承 subagents 可用的每個工具。如果清單中沒有條目解析為工具，subagent 通常 [fails to launch](/docs/zh-TW/errors#agent-would-be-spawned-with-zero-tools) 並出現命名條目的錯誤。若要將 Skills 預載入上下文，請使用 `skills` 欄位而不是在此列出 `Skill` |306| `tools` | 否 | [Tools](#available-tools) subagent 可以使用。如果省略，繼承 subagents 可用的每個工具。如果清單中沒有條目解析為工具，subagent 通常 [fails to launch](/docs/zh-TW/errors#agent-would-be-spawned-with-zero-tools) 並出現命名條目的錯誤。若要將 Skills 預載入上下文，請使用 `skills` 欄位而不是在此列出 `Skill` |

307| `disallowedTools` | 否 | 要拒絕的工具，從繼承或指定的清單中移除 |307| `disallowedTools` | 否 | 要拒絕的工具，從繼承或指定的清單中移除。具有指定符的條目（例如 `Bash(git push *)`）仍然 [removes the whole tool](#available-tools) |

308| `model` | 否 | [Model](#choose-a-model) 使用：`sonnet`、`opus`、`haiku`、`fable`、完整模型 ID（例如，`claude-opus-5`）或 `inherit`。當您省略它時，Claude Code 在 [subagent model order](#choose-a-model) 中選擇模型 |308| `model` | 否 | [Model](#choose-a-model) 使用：`sonnet`、`opus`、`haiku`、`fable`、完整模型 ID（例如，`claude-opus-5`）或 `inherit`。當您省略它時，Claude Code 在 [subagent model order](#choose-a-model) 中選擇模型 |

309| `permissionMode` | 否 | [Permission mode](#permission-modes)：`default`、`acceptEdits`、`auto`、`dontAsk`、`bypassPermissions`、`plan` 或 `manual` 作為 `default` 的別名。`manual` 別名需要 Claude Code v2.1.200 或更高版本。針對 [plugin subagents](#choose-the-subagent-scope) 被忽略 |309| `permissionMode` | 否 | [Permission mode](#permission-modes)：`default`、`acceptEdits`、`auto`、`dontAsk`、`bypassPermissions`、`plan` 或 `manual` 作為 `default` 的別名。`manual` 別名需要 Claude Code v2.1.200 或更高版本。針對 [plugin subagents](#choose-the-subagent-scope) 被忽略 |

310| `maxTurns` | 否 | subagent 停止前的最大代理轉數。當 subagent 達到限制時，Claude Code 傳回其輸出標記為部分，Claude 可以 [resume it](#resume-subagents) 以繼續。部分標記需要 Claude Code v2.1.246 或更高版本 |310| `maxTurns` | 否 | subagent 停止前的最大代理轉數。當 subagent 達到限制時，Claude Code 傳回其輸出標記為部分，Claude 可以 [resume it](#resume-subagents) 以繼續。部分標記需要 Claude Code v2.1.246 或更高版本 |

427 可用工具427 可用工具

428</h4>428</h4>

429 429

430Subagents 繼承主要對話中可用的 [built-in tools](/docs/zh-TW/tools-reference) 和 MCP 工具，由兩個過濾器縮小：第一個從每個 subagent 移除工具的簡短清單，第二個減少在 [background](#run-subagents-in-foreground-or-background) 中執行的 subagents 的內建工具集，這是預設值。[Forks](#fork-the-current-conversation) 跳過兩個過濾器，並接收主要對話的確切工具池。第一個過濾器移除這些工具，即使在 `tools` 欄位中列出：430Subagents 繼承主要對話中可用的 [built-in tools](/docs/zh-TW/tools-reference) 和 MCP 工具，由兩個過濾器縮小：第一個從每個 subagent 移除工具的簡短清單，第二個減少在 [background](#run-subagents-in-foreground-or-background) 中執行的 subagents 的內建工具集，這是預設值。在 macOS、Linux 和 WSL 上，當主要對話沒有 Glob 和 Grep 工具時，subagent 也可以接收它們，如 [Glob tool behavior](/docs/zh-TW/tools-reference#glob-tool-behavior) 下所述。[Forks](#fork-the-current-conversation) 跳過兩個過濾器，並接收主要對話的確切工具池。第一個過濾器移除這些工具，即使在 `tools` 欄位中列出：

431 431

432* `Agent`，當 subagent 在 [depth limit](#let-subagents-spawn-their-own-subagents) 時；在 [fork](#fork-the-current-conversation) 中工具保持列出但傳回錯誤而不是產生432* `Agent`，當 subagent 在 [depth limit](#let-subagents-spawn-their-own-subagents) 時；在 [fork](#fork-the-current-conversation) 中工具保持列出但傳回錯誤而不是產生

433* `AskUserQuestion`433* `AskUserQuestion`

481---481---

482```482```

483 483

484一個 `disallowedTools` 條目具有指定符，例如 `Bash(git push *)`，仍然從 subagent 移除整個工具，而不僅僅是匹配的命令。若要保留 Bash 並阻止特定命令，請在您的設定中新增 [Bash deny rule](/docs/zh-TW/permissions#bash)，例如 `Bash(git push *)` 到 `permissions.deny`。規則適用於主要對話和 subagents。

485

484<h4 id="restrict-which-subagents-can-be-spawned">486<h4 id="restrict-which-subagents-can-be-spawned">

485 限制可以產生的 subagents487 限制可以產生的 subagents

486</h4>488</h4>

third-party-integrations.md +1 −6

Details

227 投資於文件和記憶227 投資於文件和記憶

228</h3>228</h3>

229 229

230我們強烈建議投資於文件，以便 Claude Code 能夠理解您的程式碼庫。組織可以在多個層級部署 CLAUDE.md 檔案：230我們強烈建議投資於文件，以便 Claude Code 能夠理解您的程式碼庫。組織可以在多個層級部署 CLAUDE.md 檔案。請參閱[CLAUDE.md 檔案可以存放的位置](/docs/zh-TW/memory#choose-where-to-put-claude-md-files)和[如何部署組織範圍的 CLAUDE.md](/docs/zh-TW/memory#deploy-organization-wide-claude-md)。

~~231~~

232* **組織範圍**：部署到系統目錄，例如 `/Library/Application Support/ClaudeCode/CLAUDE.md`（macOS）、`/etc/claude-code/CLAUDE.md`（Linux 和 WSL）或 `C:\Program Files\ClaudeCode\CLAUDE.md`（Windows），以實現公司範圍的標準

233* **儲存庫層級**：在儲存庫根目錄中建立 `CLAUDE.md` 檔案，包含專案架構、建置命令和貢獻指南。將這些檔案簽入原始碼控制，以便所有使用者受益

~~234~~

235在[記憶和 CLAUDE.md 檔案](/docs/zh-TW/memory)中瞭解更多資訊。

236 231

237<h3 id="simplify-deployment">232<h3 id="simplify-deployment">

238 簡化部署233 簡化部署

tools-reference.md +34 −28

Details

50| `SendUserFile` | 從工作階段傳送檔案給您，帶有可選的標題，以便生成的報告、圖表、螢幕擷取畫面或內建成品到達您的裝置，而不是僅在文字記錄中提及。從 v2.1.196 開始，可選的 `display` 輸入控制呈現：`render` 在用戶端中內聯開啟檔案，`attach` 僅顯示下載卡，未設定時用戶端根據檔案型別決定。當[遠端控制](/docs/zh-TW/remote-control)用戶端連接或工作階段在受管雲端環境（例如 [Claude Code on the web](/docs/zh-TW/claude-code-on-the-web)）中執行時可用。傳遞透過 Anthropic 託管的基礎設施執行，因此該工具在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用 | 否 |50| `SendUserFile` | 從工作階段傳送檔案給您，帶有可選的標題，以便生成的報告、圖表、螢幕擷取畫面或內建成品到達您的裝置，而不是僅在文字記錄中提及。從 v2.1.196 開始，可選的 `display` 輸入控制呈現：`render` 在用戶端中內聯開啟檔案，`attach` 僅顯示下載卡，未設定時用戶端根據檔案型別決定。當[遠端控制](/docs/zh-TW/remote-control)用戶端連接或工作階段在受管雲端環境（例如 [Claude Code on the web](/docs/zh-TW/claude-code-on-the-web)）中執行時可用。傳遞透過 Anthropic 託管的基礎設施執行，因此該工具在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用 | 否 |

51| `ShareOnboardingGuide` | 上傳 `ONBOARDING.md` 並返回隊友可以在 Claude Code 中開啟的分享連結。在指南寫入後從 `/team-onboarding` 呼叫。適用於 Pro、Max、Team 和 Enterprise 方案上的 claude.ai 訂閱者 | 是 |51| `ShareOnboardingGuide` | 上傳 `ONBOARDING.md` 並返回隊友可以在 Claude Code 中開啟的分享連結。在指南寫入後從 `/team-onboarding` 呼叫。適用於 Pro、Max、Team 和 Enterprise 方案上的 claude.ai 訂閱者 | 是 |

52| `Skill` | 在主對話中執行[技能](/docs/zh-TW/skills#control-who-invokes-a-skill) | 是 |52| `Skill` | 在主對話中執行[技能](/docs/zh-TW/skills#control-who-invokes-a-skill) | 是 |

53| `TaskCreate` | 在任務清單中建立新任務。Claude Code 在[任務工具可用性](#task-tool-availability)下列出的模型上將其排除，除非您選擇加入 | 否 |53| `TaskCreate` | 在任務清單中建立新任務。預設情況下僅在[任務工具可用性](#task-tool-availability)下列出的模型上提供，在其他模型上當您選擇加入時提供 | 否 |

54| `TaskGet` | 檢索特定任務的完整詳細資訊。Claude Code 在[任務工具可用性](#task-tool-availability)下列出的模型上將其排除，除非您選擇加入 | 否 |54| `TaskGet` | 檢索特定任務的完整詳細資訊。預設情況下僅在[任務工具可用性](#task-tool-availability)下列出的模型上提供，在其他模型上當您選擇加入時提供 | 否 |

55| `TaskList` | 列出所有任務及其目前狀態。Claude Code 在[任務工具可用性](#task-tool-availability)下列出的模型上將其排除，除非您選擇加入 | 否 |55| `TaskList` | 列出所有任務及其目前狀態。預設情況下僅在[任務工具可用性](#task-tool-availability)下列出的模型上提供，在其他模型上當您選擇加入時提供 | 否 |

56| `TaskOutput` | 檢索來自背景任務的輸出。已棄用，改為在任務的輸出檔案路徑上使用 `Read`。當沒有任務符合 ID 時，錯誤會列出執行中的背景代理（按 ID 和說明）。在 v2.1.203 之前，錯誤僅命名遺失的 ID | 否 |56| `TaskOutput` | 檢索來自背景任務的輸出。已棄用，改為在任務的輸出檔案路徑上使用 `Read`。當沒有任務符合 ID 時，錯誤會列出執行中的背景代理（按 ID 和說明）。在 v2.1.203 之前，錯誤僅命名遺失的 ID | 否 |

57| `TaskStop` | 按 ID 停止執行中的背景任務。它也接受[代理團隊隊友](/docs/zh-TW/agent-teams)或按代理 ID 或名稱命名的背景代理。在 v2.1.198 之前，它僅接受背景任務 ID。當沒有任務符合 ID 時，錯誤會列出執行中的背景代理（按 ID 和說明），包括另一個代理生成的代理。在 v2.1.203 之前，錯誤列出執行中的隊友和命名代理，但不列出另一個代理生成的背景代理，因此無法從主對話中識別或停止它們 | 否 |57| `TaskStop` | 按 ID 停止執行中的背景任務。它也接受[代理團隊隊友](/docs/zh-TW/agent-teams)或按代理 ID 或名稱命名的背景代理。在 v2.1.198 之前，它僅接受背景任務 ID。當沒有任務符合 ID 時，錯誤會列出執行中的背景代理（按 ID 和說明），包括另一個代理生成的代理。在 v2.1.203 之前，錯誤列出執行中的隊友和命名代理，但不列出另一個代理生成的背景代理，因此無法從主對話中識別或停止它們 | 否 |

58| `TaskUpdate` | 更新任務狀態、依賴項、詳細資訊或刪除任務。Claude Code 在[任務工具可用性](#task-tool-availability)下列出的模型上將其排除，除非您選擇加入 | 否 |58| `TaskUpdate` | 更新任務狀態、依賴項、詳細資訊或刪除任務。預設情況下僅在[任務工具可用性](#task-tool-availability)下列出的模型上提供，在其他模型上當您選擇加入時提供 | 否 |

59| `TodoWrite` | 管理工作階段任務檢查清單。預設情況下禁用，改為使用 `TaskCreate`、`TaskGet`、`TaskList` 和 `TaskUpdate`。設定 `CLAUDE_CODE_ENABLE_TASKS=0` 以在[具有任務追蹤工具的工作階段](#task-tool-availability)中重新啟用它 | 否 |59| `TodoWrite` | 管理工作階段任務檢查清單。預設情況下禁用，改為使用 `TaskCreate`、`TaskGet`、`TaskList` 和 `TaskUpdate`。設定 `CLAUDE_CODE_ENABLE_TASKS=0` 以在[具有任務追蹤工具的工作階段](#task-tool-availability)中重新啟用它 | 否 |

60| `ToolSearch` | 當[工具搜尋](/docs/zh-TW/mcp#scale-with-mcp-tool-search)啟用時，搜尋並載入延遲工具 | 否 |60| `ToolSearch` | 當[工具搜尋](/docs/zh-TW/mcp#scale-with-mcp-tool-search)啟用時，搜尋並載入延遲工具 | 否 |

61| `WaitForMcpServers` | 等待一個或多個仍在背景連接的 [MCP 伺服器](/docs/zh-TW/mcp)，以便請求可以使用它們的工具而無需重新啟動工作階段。當需要的伺服器尚未連接時，Claude 會呼叫它。僅在[工具搜尋](/docs/zh-TW/mcp#scale-with-mcp-tool-search)禁用時出現，因為啟用時 `ToolSearch` 處理等待 | 否 |61| `WaitForMcpServers` | 等待一個或多個仍在背景連接的 [MCP 伺服器](/docs/zh-TW/mcp)，以便請求可以使用它們的工具而無需重新啟動工作階段。當需要的伺服器尚未連接時，Claude 會呼叫它。僅在[工具搜尋](/docs/zh-TW/mcp#scale-with-mcp-tool-search)禁用時出現，因為啟用時 `ToolSearch` 處理等待 | 否 |

73* 在設定中的 [`permissions.allow`](/docs/zh-TW/settings-reference#permissions-allow) 和 [`permissions.deny`](/docs/zh-TW/settings-reference#permissions-deny)，以及 `/permissions` 介面73* 在設定中的 [`permissions.allow`](/docs/zh-TW/settings-reference#permissions-allow) 和 [`permissions.deny`](/docs/zh-TW/settings-reference#permissions-deny)，以及 `/permissions` 介面

74* 在 `--allowedTools` 和 `--disallowedTools` [CLI 旗標](/docs/zh-TW/cli-reference)74* 在 `--allowedTools` 和 `--disallowedTools` [CLI 旗標](/docs/zh-TW/cli-reference)

75* 在 Agent SDK 的 [`allowedTools` 和 `disallowedTools`](/docs/zh-TW/agent-sdk/permissions#allow-and-deny-rules) 選項75* 在 Agent SDK 的 [`allowedTools` 和 `disallowedTools`](/docs/zh-TW/agent-sdk/permissions#allow-and-deny-rules) 選項

~~76* 在 [subagent 的 `tools` 或 `disallowedTools`](/docs/zh-TW/sub-agents#supported-frontmatter-fields) frontmatter~~

77* 在 [skill 的 `allowed-tools`](/docs/zh-TW/skills#frontmatter-reference) frontmatter76* 在 [skill 的 `allowed-tools`](/docs/zh-TW/skills#frontmatter-reference) frontmatter

78* 在 hook 的 [`if` 條件](/docs/zh-TW/hooks-guide#filter-by-tool-name-and-arguments-with-the-if-field)77* 在 hook 的 [`if` 條件](/docs/zh-TW/hooks-guide#filter-by-tool-name-and-arguments-with-the-if-field)

79 78

197 196

198[前景子代理](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)啟動的命令在該子代理給出最終回應時停止。主對話或背景子代理啟動的命令在最終回應後繼續執行。在使用 `-p` 旗標的非互動模式中，[背景命令在執行的最終結果後不久結束](/docs/zh-TW/headless#background-tasks-at-exit)。197[前景子代理](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)啟動的命令在該子代理給出最終回應時停止。主對話或背景子代理啟動的命令在最終回應後繼續執行。在使用 `-p` 旗標的非互動模式中，[背景命令在執行的最終結果後不久結束](/docs/zh-TW/headless#background-tasks-at-exit)。

199 198

200當命令在未完成的情況下達到其逾時時，Claude Code 會將其移至背景而不是停止它。Claude 在命令繼續時繼續工作。Claude Code 將相同的生命週期規則套用到移動的命令，就像任何其他背景命令一樣，因此它仍然在該子代理的最終回應時結束前景子代理的命令。設定 [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1`](/docs/zh-TW/env-vars#variables) 會停用自動背景化以及其餘的背景工作功能。199當命令在未完成的情況下達到其逾時時，Claude Code 會將其移至背景而不是停止它，除非命令以 `sleep` 開頭。Claude 在命令繼續時繼續工作。Claude Code 將相同的生命週期規則套用到移動的命令，就像任何其他背景命令一樣，因此它仍然在該子代理的最終回應時結束前景子代理的命令。設定 [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1`](/docs/zh-TW/env-vars#variables) 會停用自動背景化以及其餘的背景工作功能。

~~201~~

202Claude Code 永遠不會自動背景化三種命令。它在逾時時停止它們：

~~203~~

204* 以 `sleep` 開頭的命令。

205* 在其中任何地方執行 `git` 的命令。

206* Claude Code 無法完全解析為簡單命令的複合命令。Claude Code 將參數擴展（例如 `${VAR}`）視為無法解析，因此它會在逾時時停止以 `; exit "${PIPESTATUS[0]}"` 結尾的命令，即使該命令的其餘部分可解析。

207 200

208移至背景的命令的結果說明發生了什麼：201移至背景的命令的結果說明發生了什麼：

209 202

292 Glob 工具行為285 Glob 工具行為

293</h2>286</h2>

294 287

295Glob 工具按名稱模式尋找檔案。它支援標準 glob 語法，包括 `**` 用於遞迴目錄匹配：288Glob 工具按名稱模式尋找檔案。在 Windows 上，它是預設工具集的一部分。在 macOS、Linux 和 WSL 上，Claude Code 會將 Glob 和 [Grep](#grep-tool-behavior) 排除在預設工具集之外，Claude 改為透過 Bash 工具使用 `find` 和 `grep` 進行搜尋。在 Claude 的 shell 中，這兩個命令會執行 `bfs` 和 `ugrep` 的嵌入版本，搜尋會透過 `Bash` 呼叫到達您的 hooks 和權限規則。

289

290在 macOS、Linux 和 WSL 上，您可以在以下情況下取回 Glob 和 Grep 工具：

291

292* 您在啟動工作階段時在 [`--tools` 或 `--allowedTools`](/docs/zh-TW/cli-reference#cli-flags) 中命名 `Glob` 或 `Grep`，或在等效的 [Agent SDK](/docs/zh-TW/agent-sdk/overview) 選項中命名。使用 `--tools` 時，您會取得列出的工具，在 `--allowedTools` 中命名任一工具會同時復原兩者。設定檔中的允許規則沒有此效果。

293* 權限 [拒絕規則](/docs/zh-TW/permissions#match-all-uses-of-a-tool)、`--disallowedTools` 旗標或 [`--restricted`](/docs/zh-TW/cli-reference#cli-flags) 會從工作階段中移除 `Bash`。

294* [子代理](/docs/zh-TW/sub-agents#available-tools) 在其 `tools` 欄位中列出 `Glob` 或 `Grep` 並排除 `Bash`。列出的工具僅針對該子代理返回，或當它透過 [`--agent`](/docs/zh-TW/sub-agents#invoke-subagents-explicitly) 或 `agent` 設定作為主工作階段代理執行時，針對整個工作階段返回。

295

296Glob 支援標準 glob 語法，包括 `**` 用於遞迴目錄匹配：

296 297

297* `**/*.js` 符合任何深度的所有 `.js` 檔案298* `**/*.js` 符合任何深度的所有 `.js` 檔案

298* `src/**/*.ts` 符合 `src/` 下的所有 `.ts` 檔案299* `src/**/*.ts` 符合 `src/` 下的所有 `.ts` 檔案

310 Grep 工具行為311 Grep 工具行為

311</h2>312</h2>

312 313

313Grep 工具搜尋檔案內容中的模式。[Glob](#glob-tool-behavior) 按名稱尋找檔案，而 Grep 在檔案內尋找行。314Grep 工具搜尋檔案內容中的模式。[Glob](#glob-tool-behavior) 按名稱尋找檔案，而 Grep 在檔案內尋找行。在 macOS、Linux 和 WSL 上，Grep 在與 Glob 相同的條件下預設不存在。請參閱 [Glob 工具行為](#glob-tool-behavior)，了解何時兩種工具都可用。

314 315

315Grep 是基於 [ripgrep](https://github.com/BurntSushi/ripgrep) 建立的，並使用 ripgrep 的正規表達式語法，而不是 POSIX grep。包含正規表達式元字元的模式需要逃脫。例如，在 Go 程式碼中尋找 `interface{}` 需要使用模式 `interface\{\}`。316Grep 是基於 [ripgrep](https://github.com/BurntSushi/ripgrep) 建立的，並使用 ripgrep 的正規表達式語法，而不是 POSIX grep。包含正規表達式元字元的模式需要逃脫。例如，在 Go 程式碼中尋找 `interface{}` 需要使用模式 `interface\{\}`。

316 317

581 Task 工具可用性582 Task 工具可用性

582</h2>583</h2>

583 584

584在 Claude Code v2.1.233 及更新版本中，除非您選擇加入，否則以下工具在 Opus 4.8、Sonnet 5、Fable 5、Mythos 5 或這些系列的更新版本上不可用：`TodoWrite`、`TaskCreate`、`TaskGet`、`TaskUpdate` 和 `TaskList`。這些模型可以在沒有書面檢查清單的情況下追蹤多步驟工作，而工具的定義和提醒會佔用上下文，因此 Claude Code 會將其排除。沒有這些工具，Claude 在工作時不會向[任務清單](/docs/zh-TW/interactive-mode#task-list)添加任何內容。在任何其他模型上，例如 Opus 4.7，Claude Code 預設提供四個 Task 工具，只有當您設定 [`CLAUDE_CODE_ENABLE_TASKS=0`](/docs/zh-TW/env-vars) 時才提供 `TodoWrite`。585Task 追蹤工具 `TaskCreate`、`TaskGet`、`TaskUpdate`、`TaskList` 和 `TodoWrite` 預設僅在 Claude 3.x 模型、Opus 4 至 4.7、Sonnet 4 至 4.6 和 Haiku 4.5 上可用。只要工具可用，您就會獲得四個 Task 工具，或當您設定 [`CLAUDE_CODE_ENABLE_TASKS=0`](/docs/zh-TW/env-vars) 時改為 `TodoWrite`。

586

587在所有其他模型上，Claude Code 會排除這些工具，除非您選擇加入。同樣的情況也適用於 Claude Code 無法識別的模型 ID，例如透過 [LLM 閘道](/docs/zh-TW/llm-gateway)提供的自訂模型名稱。在較新的模型上，Claude 可以在沒有書面檢查清單的情況下追蹤多步驟工作，而工具的定義和提醒會佔用上下文。沒有這些工具，Claude 在工作時不會向[任務清單](/docs/zh-TW/interactive-mode#task-list)添加任何內容。

585 588

586如果您想在列出的其中一個模型上使用這些工具，請執行以下其中一項操作：589如果您想在預設情況下沒有這些工具的模型上使用它們，請執行以下其中一項操作：

587 590

588* 在啟動 Claude Code 之前匯出 [`CLAUDE_CODE_ENABLE_TODO_TOOLS=1`](/docs/zh-TW/env-vars)，例如 `CLAUDE_CODE_ENABLE_TODO_TOOLS=1 claude`。Claude Code 隨後會在每個模型和每個提供者上提供相同的工具591* 在啟動 Claude Code 之前匯出 [`CLAUDE_CODE_ENABLE_TODO_TOOLS=1`](/docs/zh-TW/env-vars)，例如 `CLAUDE_CODE_ENABLE_TODO_TOOLS=1 claude`。Claude Code 隨後會在每個模型和每個提供者上提供相同的工具

589* 在 [`--allowedTools`](/docs/zh-TW/cli-reference#cli-flags) 中命名其中一個工具，例如 `claude --allowedTools TaskCreate`592* 在 [`--allowedTools`](/docs/zh-TW/cli-reference#cli-flags) 中命名其中一個工具，例如 `claude --allowedTools TaskCreate`

594 597

595Claude Code 只有在您的工作階段具有工具時才會向子代理提供工具，即使子代理執行不同的模型也是如此。同程序[代理團隊](/docs/zh-TW/agent-teams)隊友會以相同方式跟隨您的工作階段，而在其自己的[分割窗格](/docs/zh-TW/agent-teams#choose-a-display-mode)中的隊友會作為單獨的 Claude Code 程序執行，因此其自己的模型會決定。沒有 Task 工具，代理會透過訊息而不是[共用任務清單](/docs/zh-TW/agent-teams#assign-and-claim-tasks)與其團隊協調。598Claude Code 只有在您的工作階段具有工具時才會向子代理提供工具，即使子代理執行不同的模型也是如此。同程序[代理團隊](/docs/zh-TW/agent-teams)隊友會以相同方式跟隨您的工作階段，而在其自己的[分割窗格](/docs/zh-TW/agent-teams#choose-a-display-mode)中的隊友會作為單獨的 Claude Code 程序執行，因此其自己的模型會決定。沒有 Task 工具，代理會透過訊息而不是[共用任務清單](/docs/zh-TW/agent-teams#assign-and-claim-tasks)與其團隊協調。

596 599

600此處描述的預設集合適用於 Claude Code v2.1.268 及更新版本。

601

597<h2 id="webfetch-tool-behavior">602<h2 id="webfetch-tool-behavior">

598 WebFetch 工具行為603 WebFetch 工具行為

599</h2>604</h2>

600 605

601WebFetch 接受一個 URL 和一個描述要提取內容的提示。它會擷取頁面，當伺服器返回 HTML 時將回應轉換為 Markdown，並使用一個小型、快速的模型針對內容執行提示。對於大多數擷取，Claude 會收到該模型的答案，而不是原始頁面。轉換步驟無法設定。606WebFetch 接受一個 URL 和一個描述要提取內容的提示。它會擷取頁面，當伺服器返回 HTML 時將回應轉換為 Markdown，並使用一個小型、快速的模型針對內容執行提示。對於大多數擷取，Claude 會收到該模型的答案，而不是原始頁面。轉換步驟無法設定。

602 607

603這使得 WebFetch 在設計上是有損的。提取提示決定了什麼內容會到達 Claude，因此說頁面未提及某事的結果可能只是意味著提示沒有詢問該內容。要求 Claude 使用更具體的提示再次擷取，或透過 Bash 使用 `curl` 來取得未處理的頁面。608這使得 WebFetch 在設計上是有損的。提取提示決定了什麼會到達 Claude，所以一個說頁面沒有提及某事的結果可能只是意味著提示沒有詢問它。要求 Claude 使用更具體的提示再次擷取，或透過 Bash 使用 `curl` 來取得未處理的頁面。

604 609

605有幾個行為會影響 Claude 收到的回應：610有幾個行為會影響 Claude 收到的回應：

606 611

607* HTTP URL 會自動升級為 HTTPS。612* HTTP URL 會自動升級為 HTTPS。

608* 大型頁面會在處理前被截斷至固定字元限制。613* 大型頁面會在處理前被截斷至固定字元限制。

609* WebFetch 預設會快取每個回應 15 分鐘，因此重複擷取相同 URL 會快速返回。在 Claude Code v2.1.233 或更新版本上，設定 [`CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS`](/docs/zh-TW/env-vars#variables) 以變更 WebFetch 保留每個回應的時間長度。614* WebFetch 預設會快取每個回應 15 分鐘，所以重複擷取相同 URL 會快速返回。在 Claude Code v2.1.233 或更新版本上，設定 [`CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS`](/docs/zh-TW/env-vars#variables) 以變更 WebFetch 保留每個回應的時間長度。

610* 當 URL 重新導向至不同的主機時，WebFetch 會返回一個文字結果，命名原始 URL 和重新導向目標，而不是跟隨它。Claude 隨後會使用第二個 WebFetch 呼叫擷取新 URL。615* 一個頁面如果在五分鐘內未完成下載（包括 WebFetch 跟隨的任何重新導向），會因為截止時間錯誤而失敗。在 Claude Code v2.1.268 或更新版本上，設定 [`CLAUDE_CODE_WEBFETCH_DEADLINE_MS`](/docs/zh-TW/env-vars#variables) 以變更限制，或設定為 `0` 以移除它。

611* 當提取步驟遇到超載的 API 時，Claude Code 會使用退避策略重試；仍然失敗的擷取會返回錯誤結果。在 v2.1.212 之前，API 錯誤文字可能會作為提取的頁面內容到達 Claude。616* 當 URL 重新導向到不同的主機時，WebFetch 會返回一個文字結果，命名原始 URL 和重新導向目標，而不是跟隨它。Claude 隨後會使用第二個 WebFetch 呼叫擷取新 URL。

617* 當提取步驟遇到過載的 API 時，Claude Code 會以退避方式重試它；仍然失敗的擷取會返回錯誤結果。在 v2.1.212 之前，API 錯誤文字可能會作為提取的頁面內容到達 Claude。

612 618

613在手動和 `acceptEdits` [權限模式](/docs/zh-TW/permission-modes)中，WebFetch 會在擷取前提示，除非您的 [權限規則](/docs/zh-TW/permissions#manage-permissions)已允許或拒絕該網域，以及一組內建的預先核准文件網域可以在不提示的情況下擷取。無論您的規則允許什麼，擷取也必須先通過 [WebFetch 網域安全檢查](/docs/zh-TW/data-usage#webfetch-domain-safety-check)；該部分涵蓋檢查發送的內容和跳過它的設定。提示提供三個選項：619在手動和 `acceptEdits` [權限模式](/docs/zh-TW/permission-modes)中，WebFetch 會在擷取前提示，除非您的 [權限規則](/docs/zh-TW/permissions#manage-permissions)已允許或拒絕該域名，以及一組內建的預先批准文件域名可以無提示擷取。無論您的規則允許什麼，擷取也必須先通過 [WebFetch 域名安全檢查](/docs/zh-TW/data-usage#webfetch-domain-safety-check)；該部分涵蓋檢查發送的內容和跳過它的設定。提示提供三個選項：

614 620

615* **是**：僅核准此擷取。下一個 WebFetch 呼叫會再次提示，即使是針對相同網域。621* **是**：僅批准此擷取。下一個 WebFetch 呼叫會再次提示，即使是相同的域名。

616* **是，且不再詢問 `<domain>`**：核准擷取並將 `WebFetch(domain:...)` 允許規則儲存至該儲存庫的 `.claude/settings.local.json` 以供該網域使用。請參閱 [已儲存的核准如何持續](/docs/zh-TW/permissions#permission-system)。當您的組織設定 [`allowManagedPermissionRulesOnly`](/docs/zh-TW/permissions#managed-only-settings) 時，Claude Code 會隱藏此選項。622* **是，且不再詢問 `<domain>`**：批准擷取並將 `WebFetch(domain:...)` 允許規則保存到該域名的 `.claude/settings.local.json` 以供該儲存庫使用。請參閱 [已保存的批准如何持續](/docs/zh-TW/permissions#permission-system)。當您的組織設定 [`allowManagedPermissionRulesOnly`](/docs/zh-TW/permissions#managed-only-settings) 時，Claude Code 會隱藏此選項。

617* **否，並告訴 Claude 應該如何不同地進行**：拒絕擷取。623* **否，並告訴 Claude 應該如何不同地做**：拒絕擷取。

618 624

619若要事先允許網域而不提示，請新增允許規則，例如 `WebFetch(domain:example.com)`；`WebFetch(domain:*)` 允許每個網域。`auto` 和 `bypassPermissions` [權限模式](/docs/zh-TW/permissions#permission-modes)會跳過提示，除非明確的 `ask` 規則符合網域。625若要提前允許域名而不提示，請新增允許規則，例如 `WebFetch(domain:example.com)`；`WebFetch(domain:*)` 允許每個域名。`auto` 和 `bypassPermissions` [權限模式](/docs/zh-TW/permissions#permission-modes)會跳過提示，除非明確的 `ask` 規則符合該域名。

620 626

621`deny`、`ask` 或 `allow` 中的明確 `WebFetch(domain:...)` 規則優先於預先核准的集合，因此您可以封鎖預先核准的網域或要求提示。627`deny`、`ask` 或 `allow` 中的明確 `WebFetch(domain:...)` 規則優先於預先批准的集合，所以您可以阻止預先批准的域名或要求提示。

622 628

623WebFetch 設定一個以 `Claude-User` 開頭的 `User-Agent` 標頭，以及一個 `Accept` 標頭，優先選擇 Markdown 而不是 HTML，以便支援內容協商的伺服器可以直接返回 Markdown。629WebFetch 設定一個以 `Claude-User` 開頭的 `User-Agent` 標頭，以及一個 `Accept` 標頭，優先使用 Markdown 而不是 HTML，以便支援內容協商的伺服器可以直接返回 Markdown。

624 630

625沙箱化命令不會繼承 WebFetch 的內建預先核准文件網域集合。若要讓沙箱化命令在不提示的情況下到達網域，請將網域新增至 [`allowedDomains`](/docs/zh-TW/settings-reference#sandbox-network-alloweddomains) 或使用 `WebFetch(domain:...)` 規則允許它，[沙箱也會遵守](/docs/zh-TW/sandboxing#network-isolation)。WebFetch 不會反過來讀取沙箱允許清單，因此將網域新增至沙箱或組織網路允許清單不會阻止 WebFetch 提示它。631沙箱化命令不會繼承 WebFetch 的內建預先批准文件域名集合。若要讓沙箱化命令無提示地到達域名，請將域名新增到 [`allowedDomains`](/docs/zh-TW/settings-reference#sandbox-network-alloweddomains) 或使用 `WebFetch(domain:...)` 規則允許它，[沙箱也會遵守](/docs/zh-TW/sandboxing#network-isolation)。WebFetch 不會反過來讀取沙箱允許清單，所以將域名新增到沙箱或組織網路允許清單不會阻止 WebFetch 提示它。

626 632

627<h2 id="websearch-tool-behavior">633<h2 id="websearch-tool-behavior">

628 WebSearch 工具行為634 WebSearch 工具行為

troubleshooting.md +19 −0

Details

24 24

25如果您不確定哪個適用，請在 Claude Code 內執行 `/doctor` 以自動檢查您的安裝、設定、擴充功能和上下文使用情況；它會提議可以在您確認後套用的修復。如果 `claude` 根本無法啟動，請改為從您的 shell 執行 `claude doctor`。執行 `/mcp` 以檢查 MCP 伺服器狀態。25如果您不確定哪個適用，請在 Claude Code 內執行 `/doctor` 以自動檢查您的安裝、設定、擴充功能和上下文使用情況；它會提議可以在您確認後套用的修復。如果 `claude` 根本無法啟動，請改為從您的 shell 執行 `claude doctor`。執行 `/mcp` 以檢查 MCP 伺服器狀態。

26 26

27***

29title: "效能和穩定性"

30description: "涵蓋與資源使用、回應性和搜尋行為相關的問題。"

31-------------------------------------

27<h2 id="performance-and-stability">33<h2 id="performance-and-stability">

28 效能和穩定性34 效能和穩定性

29</h2>35</h2>

110 116

111若要讓管道化命令直接到達剪貼簿，請將 `pbcopy *`、`wl-copy *` 或 `xclip *` 新增到 [`excludedCommands`](/docs/zh-TW/settings-reference#sandbox-excludedcommands)，以便命令在沙箱外執行。117若要讓管道化命令直接到達剪貼簿，請將 `pbcopy *`、`wl-copy *` 或 `xclip *` 新增到 [`excludedCommands`](/docs/zh-TW/settings-reference#sandbox-excludedcommands)，以便命令在沙箱外執行。

112 118

119<h3 id="copied-text-doesn’t-reach-your-local-clipboard-over-ssh">

120 複製的文字無法透過 SSH 到達您的本機剪貼簿

121</h3>

122

123當 Claude Code 在遠端機器上透過 SSH 執行時，它無法在您的本機機器上執行剪貼簿工具。在 tmux 外，當您在[全螢幕渲染](/docs/zh-TW/fullscreen)中選取文字或執行 `/copy` 時，Claude Code 會改為將文字作為 OSC 52 逸出序列傳送到您的終端。您的終端決定是否將其放在您的剪貼簿上。`/copy` 報告 `Copied to clipboard`，無論文字是否到達，在 tmux 外選取通知讀取 `sent N chars via OSC 52`。

124

125某些終端不會對 OSC 52 採取行動。iTerm2 會忽略它，直到您開啟**Settings > General > Selection > Applications in terminal may access clipboard**，而 macOS Terminal.app 不支援它。

126

127若要在沒有 OSC 52 的情況下取得文字：

128

129* 按住您的終端的原生選取鍵同時拖曳，然後使用您的終端的常用快捷方式複製，例如 `Cmd+C`。該鍵在 Terminal.app 中是 `Fn`，在 iTerm2 中是 `Option`。[保持原生文字選取](/docs/zh-TW/fullscreen#keep-native-text-selection)列出其他終端的鍵。

130* 在遠端機器上設定 [`CLAUDE_CODE_DISABLE_MOUSE=1`](/docs/zh-TW/env-vars)，以便您的終端為整個工作階段處理選取。

131

113<h3 id="search-and-discovery-issues">132<h3 id="search-and-discovery-issues">

114 搜尋和發現問題133 搜尋和發現問題

115</h3>134</h3>

vs-code.md +32 −6

Details

56 56

57 開啟 Claude Code 的其他方式：57 開啟 Claude Code 的其他方式：

58 58

59 * **活動列**：點擊左側邊欄中的 Spark 圖示以開啟工作階段清單。點擊任何工作階段以將其開啟為完整編輯器標籤，或開始新的工作階段。此圖示在活動列中始終可見。59 * **活動列**：點擊左側邊欄中的 Spark 圖示以開啟工作階段清單。點擊任何工作階段以將其開啟至您的[偏好位置](#extension-settings)，或開始新的工作階段。此圖示在活動列中始終可見。

60 * **命令面板**：`Cmd+Shift+P`（Mac）或 `Ctrl+Shift+P`（Windows/Linux），輸入「Claude Code」，然後選擇一個選項，例如「在新標籤中開啟」60 * **命令面板**：`Cmd+Shift+P`（Mac）或 `Ctrl+Shift+P`（Windows/Linux），輸入「Claude Code」，然後選擇一個選項，例如「在新標籤中開啟」

61 * **狀態列**：如果您已將 [`preferredLocation`](#extension-settings) 設定為 `sidebar`，或使用**Claude Code: Open in Side Bar** 開啟 Claude，請點擊視窗右下角的 **✱ Claude Code**。即使沒有開啟檔案，這也能運作。61 * **狀態列**：如果您已將 [`preferredLocation`](#extension-settings) 設定為 `sidebar`，或使用**Claude Code: Open in Side Bar** 開啟 Claude，請點擊視窗右下角的 **✱ Claude Code**。即使沒有開啟檔案，這也能運作。

62 62

110 * **Manual**：Claude 在檔案編輯和大多數 shell 命令前詢問權限。110 * **Manual**：Claude 在檔案編輯和大多數 shell 命令前詢問權限。

111 * **Plan**：Claude 描述它將執行的操作，並在進行變更前等待批准。VS Code 會自動將計畫作為完整 Markdown 文件開啟，您可以在其中新增內嵌註解以在 Claude 開始前提供回饋。111 * **Plan**：Claude 描述它將執行的操作，並在進行變更前等待批准。VS Code 會自動將計畫作為完整 Markdown 文件開啟，您可以在其中新增內嵌註解以在 Claude 開始前提供回饋。

112 * **Edit automatically**：Claude 進行編輯而不詢問。112 * **Edit automatically**：Claude 進行編輯而不詢問。

113* **Model**：從命令菜單中選擇 **Switch model…** 以在會話中途變更模型。您也可以點擊提示框底部的模型名稱以開啟相同的選擇器。當目前的模型支援[努力等級](/docs/zh-TW/model-config#adjust-effort-level)時，選擇器也會顯示 **Effort** 列。模型名稱按鈕和 **Effort** 列需要 Claude Code v2.1.257 或更新版本。113* **Model**：從命令菜單中選擇 **Switch model…** 以在會話中途變更模型。您也可以點擊提示框底部的模型名稱以開啟相同的選擇器。當目前的模型支援[努力等級](/docs/zh-TW/model-config#adjust-effort-level)時，選擇器也會顯示 **Effort** 列和模型名稱按鈕會顯示選定的等級。模型名稱按鈕和 **Effort** 列需要 Claude Code v2.1.257 或更新版本。

114* **Command menu**：點擊 `/` 或輸入 `/` 以開啟命令菜單。選項包括附加檔案、切換模型和切換延伸思考。Customize 部分提供對 MCP 伺服器、slash commands、輸出樣式、hooks、記憶、權限和外掛程式的存取。帶有終端機圖示的項目會在整合終端機中開啟。114* **Command menu**：點擊 `/` 或輸入 `/` 以開啟命令菜單。選項包括附加檔案、切換模型和切換延伸思考。Customize 部分提供對 MCP 伺服器、slash commands、輸出樣式、hooks、記憶、權限和外掛程式的存取。帶有終端機圖示的項目會在整合終端機中開啟。

115 * 若要瀏覽 `/usage` 或 [`/remote-control`](/docs/zh-TW/remote-control) 等命令，請在 Customize 部分中選擇 **Slash commands**。對話方塊會列出它們並提供篩選框。選擇一個以執行它。在提示框中輸入 `/` 仍會內嵌建議命令。需要 Claude Code v2.1.257 或更新版本。115 * 若要瀏覽 `/usage` 或 [`/remote-control`](/docs/zh-TW/remote-control) 等命令，請在 Customize 部分中選擇 **Slash commands**。對話方塊會列出它們並提供篩選框。選擇一個以執行它。在提示框中輸入 `/` 仍會內嵌建議命令。需要 Claude Code v2.1.257 或更新版本。

116 * 在 Customize 部分中選擇 **Output styles** 以選擇[輸出樣式](/docs/zh-TW/output-styles)，包括您的自訂樣式。需要 Claude Code v2.1.257 或更新版本。116 * 在 Customize 部分中選擇 **Output styles** 以選擇[輸出樣式](/docs/zh-TW/output-styles)，包括您的自訂樣式。需要 Claude Code v2.1.257 或更新版本。

141 141

142當您在編輯器中選擇文字時，Claude 可以自動看到您的反白程式碼。提示框頁尾顯示選擇了多少行。按 `Option+K`（Mac）/ `Alt+K`（Windows/Linux）以插入帶有檔案路徑和行號的 @-mention（例如 `@app.ts#5-10`）。點擊選擇指示器以切換 Claude 是否可以看到您的反白文字 - 眼睛斜線圖示表示選擇對 Claude 隱藏。142當您在編輯器中選擇文字時，Claude 可以自動看到您的反白程式碼。提示框頁尾顯示選擇了多少行。按 `Option+K`（Mac）/ `Alt+K`（Windows/Linux）以插入帶有檔案路徑和行號的 @-mention（例如 `@app.ts#5-10`）。點擊選擇指示器以切換 Claude 是否可以看到您的反白文字 - 眼睛斜線圖示表示選擇對 Claude 隱藏。

143 143

144您也可以在將檔案拖入提示框時按住 `Shift` 以將它們新增為附件。點擊任何附件上的 X 以將其從內容中移除。144若要附加影像，請從您的剪貼簿將其貼到提示框中。您也可以在將檔案拖入提示框時按住 `Shift` 以將它們新增為附件。點擊任何附件上的 X 以將其從內容中移除。

145 145

146<h3 id="resume-past-conversations">146<h3 id="resume-past-conversations">

147 恢復過去的對話147 恢復過去的對話

148</h3>148</h3>

149 149

150點擊 Claude Code 面板頂部的 **Session history** 按鈕以存取您的對話歷史。您可以按關鍵字搜尋或按時間瀏覽。點擊任何對話以使用完整的訊息歷史恢復它。如需有關恢復會話的更多資訊，請參閱[管理會話](/docs/zh-TW/sessions)。150點擊 Claude Code 面板頂部的 **Session history** 按鈕以存取您的對話歷史。您可以按關鍵字搜尋或按時間瀏覽。

151

152點擊任何對話以使用完整的訊息歷史恢復它。如果對話已在目前視窗的另一個標籤中開啟，點擊它會切換到該標籤。如需有關恢復會話的更多資訊，請參閱[管理會話](/docs/zh-TW/sessions)。

151 153

152* **Session titles**：新會話根據您的第一條訊息接收 AI 生成的標題。154* **Session titles**：新會話根據您的第一條訊息接收 AI 生成的標題。

153* **Rename and archive**：將滑鼠懸停在會話上以顯示這些操作。重新命名以給它一個描述性標題，或存檔以將其移動到清單底部的 **Archived sessions** 群組。155* **Rename and archive**：將滑鼠懸停在會話上以顯示這些操作。重新命名以給它一個描述性標題，或存檔以將其移動到清單底部的 **Archived sessions** 群組。

274* **為此專案安裝**：與專案協作者共享（專案範圍）276* **為此專案安裝**：與專案協作者共享（專案範圍）

275* **本機安裝**：僅供您使用，僅在此儲存庫中（本機範圍）277* **本機安裝**：僅供您使用，僅在此儲存庫中（本機範圍）

276 278

279<h3 id="share-a-plugin-install-link">

280 分享 plugin 安裝連結

281</h3>

282

283若要直接將某人導向安裝特定 plugin，請提供擴充功能的 `install-plugin` URL。開啟它會啟動或聚焦 VS Code、開啟 Claude Code 面板，並在該 plugin 的範圍選擇上開啟**管理 plugins** 對話框。在該人選擇範圍之前，不會安裝任何內容。如果 Claude Code 中尚未設定該 plugin 的 marketplace，對話框會先要求他們新增它。

284

285```text theme={null}

286vscode://anthropic.claude-code/install-plugin?plugin=code-review&marketplace=anthropics/claude-plugins-official

287```

288

289該 URL 採用兩個查詢參數：

290

291| 參數 | 描述 |

292| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

293| `plugin` | plugin 的名稱，如其 marketplace 所列。必需。 |

294| `marketplace` | plugin 的來源，採用 [Marketplaces 標籤](#manage-marketplaces) 接受的任何形式，例如 GitHub `owner/repo` 或 git URL。如果包含 `&` 等字元，請進行 URL 編碼。省略時預設為 `anthropics/claude-plugins-official`。 |

295

296兩種情況在對話框中以訊息結束，而不是範圍選擇：

297

298* **marketplace 未按該名稱列出 plugin**：對話框報告找不到該 plugin。根據 marketplace 的清單檢查 `plugin` 值。

299* **plugin 已安裝**：對話框會說明這一點，且不會進行任何變更。

300

301GitHub README、議題和某些其他 Markdown 主機會移除其方案不是 `http` 或 `https` 的連結，因此 `vscode://` 連結在那裡呈現為純文字。將 URL 放在這些主機上的程式碼區塊中，如 [連結呈現為純文字而不是可點擊的](/docs/zh-TW/deep-links#the-link-renders-as-plain-text-instead-of-being-clickable) 針對 `claude-cli://` 連結所描述的那樣。

302

277<h3 id="manage-marketplaces">303<h3 id="manage-marketplaces">

278 管理 marketplaces304 管理 marketplaces

279</h3>305</h3>

284* 點擊重新整理圖示以更新 marketplace 的 plugin 清單310* 點擊重新整理圖示以更新 marketplace 的 plugin 清單

285* 點擊垃圾桶圖示以移除 marketplace311* 點擊垃圾桶圖示以移除 marketplace

286 312

287進行變更後，橫幅會提示您重新啟動 Claude Code 以套用變更。313您在對話框中進行的 plugin 變更會立即套用到該 VS Code 視窗中開啟的 Claude Code 工作階段。如果您開啟對話框的工作階段無法重新載入其 plugins，對話框會提供重試或在該工作階段中重新啟動 Claude 的選項。

288 314

289<Note>315<Note>

290 VS Code 中的 plugin 管理在幕後使用相同的 CLI 命令。您在擴充功能中設定的 plugins 和 marketplaces 也可在 CLI 中使用，反之亦然。316 VS Code 中的 plugin 管理在幕後使用相同的 CLI 命令。您在擴充功能中設定的 plugins 和 marketplaces 也可在 CLI 中使用，反之亦然。

390vscode://anthropic.claude-code/open?prompt=review%20my%20changes416vscode://anthropic.claude-code/open?prompt=review%20my%20changes

391```417```

392 418

393若要啟動終端機工作階段而不是 VS Code 標籤頁，請使用 CLI 的 `claude-cli://` 處理程式。請參閱[從連結啟動工作階段](/docs/zh-TW/deep-links)。419該擴充功能也會處理 `vscode://anthropic.claude-code/install-plugin`，它會[在一個外掛程式上開啟外掛程式對話](#share-a-plugin-install-link)。若要啟動終端機工作階段而不是 VS Code 標籤頁，請使用 CLI 的 `claude-cli://` 處理程式。請參閱[從連結啟動工作階段](/docs/zh-TW/deep-links)。

394 420

395<h2 id="configure-settings">421<h2 id="configure-settings">

396 設定設定422 設定設定

web-quickstart.md +21 −5

Details

70 </Step>70 </Step>

71 71

72 <Step title="Sign in with GitHub">72 <Step title="Sign in with GitHub">

73 登入後，claude.ai/code 會提示您連接 GitHub。按照提示，claude.ai/code 會將您送到 GitHub 的授權頁面。批准授權請求，GitHub 會將您返回到 claude.ai/code。雲端會話適用於現有的 GitHub 儲存庫，並可以存取您的 GitHub 帳戶可以看到的任何儲存庫。若要啟動新項目，請先[在 GitHub 上建立空儲存庫](https://github.com/new)。73 登入後，claude.ai/code 會提示您連接 GitHub。按照提示，claude.ai/code 會將您送到 GitHub 的授權頁面。批准授權請求，GitHub 會將您返回到 claude.ai/code。雲端會話適用於現有的 GitHub 儲存庫。若要啟動新項目，請先[在 GitHub 上建立空儲存庫](https://github.com/new)。

74 74

75 當 Quick web setup 關閉時（在 Team 和 Enterprise 方案上預設為關閉），claude.ai/code 會要求您在儲存庫上安裝 Claude GitHub App，除非已安裝。如果您想要[Auto-fix](/docs/zh-TW/claude-code-on-the-web#auto-fix-pull-requests)（允許 Claude 回應 CI 失敗並審查這些儲存庫中的提取請求上的評論），請安裝它；否則點擊**Skip**。無論哪種方式，會話都可以存取相同的儲存庫。75 透過此連接，會話可以複製任何公開儲存庫，但只有在 Claude GitHub App 安裝在私有儲存庫上時，才能在私有儲存庫中工作。[在每個 GitHub 帳戶或組織上安裝應用程式](https://github.com/apps/claude/installations/new)，其私有儲存庫您想要使用。在 GitHub 組織上，組織擁有者可能需要批准安裝。安裝應用程式也會啟用[自動修復](/docs/zh-TW/claude-code-on-the-web#auto-fix-pull-requests)，這讓 Claude 可以回應 CI 失敗並審查這些儲存庫中提取請求上的評論。

77 如果上線流程在此時提示您安裝應用程式，而您寧願稍後再做，請點擊**Skip**。

76 </Step>78 </Step>

77 79

78 <Step title="設定您的預設環境">80 <Step title="設定您的預設環境">

91 從您的終端連接93 從您的終端連接

92</h3>94</h3>

93 95

94如果您已經使用 GitHub CLI (`gh`)，您可以在不打開瀏覽器的情況下設定 Claude Code on the web。這需要 [Claude Code CLI](/docs/zh-TW/quickstart)。當您執行 `/web-setup` 時，Claude Code 會讀取您的本地 `gh` 令牌，將其連結到您的 claude.ai 帳戶，並在您沒有雲端環境時建立**Default**雲端環境。在 Team 和 Enterprise 方案上，`/web-setup` 僅在擁有者開啟[Quick web setup](/docs/zh-TW/claude-code-on-the-web#github-authentication-options)後才可用。96如果您已經使用 GitHub CLI (`gh`)，您可以在不打開瀏覽器的情況下設定 Claude Code on the web。這需要 [Claude Code CLI](/docs/zh-TW/quickstart)。在 Team 和 Enterprise 方案上，`/web-setup` 僅在擁有者開啟[Quick web setup](/docs/zh-TW/claude-code-on-the-web#github-authentication-options)後才可用。

98當您執行 `/web-setup` 時，Claude Code 會讀取 `gh auth token` 列印的令牌，要求您確認，並將令牌傳送給 Anthropic。Anthropic 使用您的 claude.ai 帳戶加密儲存它，您的雲端會話使用它進行 GitHub 存取，直到您[移除它](#remove-the-web-setup-token)。雲端會話可以存取該令牌可以存取的任何儲存庫，無需 Claude GitHub App 安裝。

100如果您已經在瀏覽器中連接了 GitHub，`/web-setup` 會警告您繼續會為您的雲端會話取代該連接。

95 101

96<Note>102<Note>

97 啟用了[零資料保留](/docs/zh-TW/zero-data-retention)的組織無法使用 `/web-setup` 或其他雲端會話功能。如果未安裝或驗證 GitHub CLI，Claude Code 會改為開啟瀏覽器上線流程。103 啟用了[零資料保留](/docs/zh-TW/zero-data-retention)的組織無法使用 `/web-setup` 或其他雲端會話功能。如果未安裝或驗證 GitHub CLI，Claude Code 會改為開啟瀏覽器上線流程。

117 /web-setup123 /web-setup

118 ```124 ```

119 125

120 這會將您的 `gh` 令牌同步到您的 Claude 帳戶。成功時，Claude Code 會列印 `Connected as <your-github-username>` 並在您的瀏覽器中開啟 [claude.ai/code](https://claude.ai/code)。如果您還沒有雲端環境，`/web-setup` 會建立一個具有 Trusted 網路存取且沒有設定指令碼的環境。您可以[稍後編輯環境或新增變數](/docs/zh-TW/cloud-environments#configure-your-environment)。一旦 `/web-setup` 完成，您可以使用 [`--cloud`](/docs/zh-TW/claude-code-on-the-web#from-terminal-to-web) 從您的終端啟動雲端會話，或使用 [`/schedule`](/docs/zh-TW/routines) 設定定期任務。126 確認提示以將您的 `gh` 令牌傳送到您的 Claude 帳戶。成功時，Claude Code 會列印 `Connected as <your-github-username>` 並在您的瀏覽器中開啟 [claude.ai/code](https://claude.ai/code)。如果您還沒有雲端環境，`/web-setup` 會建立一個具有 Trusted 網路存取且沒有設定指令碼的環境。您可以[稍後編輯環境或新增變數](/docs/zh-TW/cloud-environments#configure-your-environment)。一旦 `/web-setup` 完成，您可以使用 [`--cloud`](/docs/zh-TW/claude-code-on-the-web#from-terminal-to-web) 從您的終端啟動雲端會話，或使用 [`/schedule`](/docs/zh-TW/routines) 設定定期任務。

121 </Step>127 </Step>

122</Steps>128</Steps>

123 129

130<h4 id="remove-the-web-setup-token">

131 移除 `/web-setup` 令牌

132</h4>

133

134若要從您的 Claude 帳戶移除令牌，請在 [claude.ai/customize/connectors](https://claude.ai/customize/connectors) 斷開 GitHub 連接。斷開連接會刪除您的雲端會話使用的 GitHub 認證，無論它們來自瀏覽器還是 `/web-setup`，因此雲端會話會失去 GitHub 存取權，直到您再次連接。您的本地 `gh` 保持登入狀態，令牌在 GitHub 上保持有效。

135

136若要使令牌本身失效，請在 GitHub 上撤銷它。如果您透過瀏覽器登入 `gh`，令牌屬於 GitHub 上[**Settings > Applications > Authorized OAuth Apps**](https://github.com/settings/applications)下的**GitHub CLI**項目，撤銷該項目也會在您的機器上登出 GitHub CLI。雲端會話隨後會失去 GitHub 存取權，直到您再次執行 `gh auth login` 和 `/web-setup`。

137

124<h2 id="start-a-task">138<h2 id="start-a-task">

125 啟動任務139 啟動任務

126</h2>140</h2>

204 連接 GitHub 後沒有儲存庫出現218 連接 GitHub 後沒有儲存庫出現

205</h3>219</h3>

206 220

207雲端會話可以使用連接的 GitHub 帳戶可以看到的任何儲存庫，無論 Claude GitHub App 安裝在哪些儲存庫上。如果儲存庫遺失，請驗證連接的 GitHub 帳戶在 GitHub 上是否有權存取它。如果您還想要儲存庫的[自動修復](/docs/zh-TW/claude-code-on-the-web#auto-fix-pull-requests)，請在其上安裝應用程式：在 github.com 上，打開**設定 → 應用程式 → Claude → 配置**並驗證儲存庫是否列在**儲存庫存取**下。私有儲存庫需要與公開儲存庫相同的授權。221如果您在瀏覽器中連接了 GitHub，會話可以複製任何公開儲存庫，但私有儲存庫只有在 Claude GitHub App 安裝在擁有它的帳戶或組織上，且安裝的儲存庫存取包括它時才會出現。[安裝 Claude GitHub App](https://github.com/apps/claude/installations/new)，或要求組織擁有者安裝或批准它。

222

223如果您使用 `/web-setup` 連接，會話可以存取您的 `gh` 權杖可以存取的每個儲存庫。在您的 shell 中執行 `gh repo view OWNER/REPO` 以檢查您的 GitHub CLI 登入是否可以看到該儲存庫，如果您自連接以來已切換 `gh` 帳戶，請再次執行 `/web-setup`。

208 224

209<h3 id="the-page-only-shows-a-github-login-button">225<h3 id="the-page-only-shows-a-github-login-button">

210 頁面只顯示 GitHub 登入按鈕226 頁面只顯示 GitHub 登入按鈕

whats-new/2026-w29.md +70 −0 created

Details

1> ## Documentation Index

2> 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.

5# 第 29 週 · 2026 年 7 月 13–17 日

7> 透過 MCP 連接器將即時資料拉入已發佈的成品中，並在新的螢幕閱讀器模式中使用 Claude Code 搭配螢幕閱讀器。

9<div className="digest-meta">

10 <span>版本 <a href="/docs/en/changelog#2-1-207">v2.1.207 → v2.1.212</a></span>

11 <span>2 項功能 · 7 月 13–17 日</span>

12</div>

14<div className="digest-feature">

15 <div className="digest-feature-header">

16 <span className="digest-feature-title">成品呼叫您的 MCP 連接器</span>

17 <span className="digest-feature-pill">web</span>

18 </div>

20 <p className="digest-feature-lede">已發佈的成品現在可以在每次有人檢視時呼叫 MCP 連接器，因此儀表板會顯示即時資料，並可按需執行動作，而不是建立該成品的工作階段中的快照。每次呼叫都會透過檢視帳戶自己的連線執行，檢視者在頁面首次連接器呼叫前會核准存取。本週還新增了公開分享連結、Team 和 Enterprise 方案上的編輯者角色，以及從 Claude Tag 工作階段建立的成品。</p>

22 <Frame>

23 <video autoPlay muted loop playsInline className="w-full" src="https://mintcdn.com/claude-code/ItzF3QVI6L0QypjJ/images/whats-new/artifacts-mcp.mp4?fit=max&auto=format&n=ItzF3QVI6L0QypjJ&q=85&s=ff8b81ed52b26c773899dc28cec959e6" data-path="images/whats-new/artifacts-mcp.mp4" />

24 </Frame>

26 <p className="digest-feature-try">在您的提示中命名連接器和您想要的資料：</p>

28 ```text title="Claude Code" wrap theme={null}

29 Build a dashboard artifact of open pull requests that pulls the live list through my GitHub connector when the page loads.

30 ```

32 <a className="digest-feature-link" href="/docs/zh-TW/artifacts#pull-live-data-with-mcp-connectors">使用 MCP 連接器拉取即時資料</a>

33</div>

35<div className="digest-feature">

36 <div className="digest-feature-header">

37 <span className="digest-feature-title">螢幕閱讀器模式</span>

38 <span className="digest-feature-pill">CLI</span>

39 </div>

41 <p className="digest-feature-lede">螢幕閱讀器模式將視覺終端介面替換為純文字、線性文字：不使用方框、旋轉器和就地重繪，Claude Code 會列印標籤行，螢幕閱讀器（例如 VoiceOver 或 NVDA）會依序讀取，因此您可以核准權限並從頭到尾檢視輸出。使用旗標按工作階段開啟、使用 <code>CLAUDE\_AX\_SCREEN\_READER</code> 環境變數按 shell 開啟，或使用 <code>axScreenReader</code> 設定在所有地方開啟。</p>

43 <p className="digest-feature-try">在螢幕閱讀器模式中啟動工作階段：</p>

45 ```bash terminal theme={null}

46 claude --ax-screen-reader

47 ```

49 <a className="digest-feature-link" href="/docs/zh-TW/accessibility#turn-on-screen-reader-mode">開啟螢幕閱讀器模式</a>

50</div>

52<div className="digest-wins">

53 <p className="digest-wins-title">其他改進</p>

55 <div className="digest-wins-grid">

56 <div><code>/fork</code> 現在會將您的對話複製到新的背景工作階段中，在 <code>claude agents</code> 中有自己的列，同時您可以繼續工作；它過去啟動的工作階段內分叉子代理現在是 <code>/subtask</code></div>

57 <div><a href="/docs/zh-TW/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry">自動模式</a>在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上不再需要 <code>CLAUDE\_CODE\_ENABLE\_AUTO\_MODE</code> 選擇加入；管理員可以使用 <code>disableAutoMode</code> 將其關閉</div>

58 <div>執行時間超過兩分鐘的 MCP 工具呼叫現在會自動移至背景，以便工作階段保持可用；使用 <code>CLAUDE\_CODE\_MCP\_AUTO\_BACKGROUND\_MS</code> 調整或停用閾值</div>

59 <div>新的 <code>claude auto-mode reset</code> 會還原預設自動模式設定，`--yes` 會略過確認提示</div>

60 <div>新的 <a href="/docs/zh-TW/corporate-launcher">企業啟動器</a>支援：<code>CLAUDE\_CODE\_PROCESS\_WRAPPER</code> 或 <code>processWrapper</code> 設定會透過必要的包裝器可執行檔執行 Claude Code 從其自己的二進位檔啟動的程序，例如背景服務和代理檢視工作階段</div>

61 <div><code>vimInsertModeRemaps</code> 設定會將兩鍵插入模式序列（例如 <code>jj</code>）對應到 vim 模式中的 Escape</div>

62 <div>`--forward-subagent-text` 和 <code>CLAUDE\_CODE\_FORWARD\_SUBAGENT\_TEXT</code> 在 <a href="/docs/zh-TW/headless">stream-json 輸出</a>中包含子代理文字和思考區塊</div>

63 <div>工作階段範圍的上限會停止失控迴圈：WebSearch 呼叫和子代理生成各預設為 200，可使用 <code>CLAUDE\_CODE\_MAX\_WEB\_SEARCHES\_PER\_SESSION</code> 和 <code>CLAUDE\_CODE\_MAX\_SUBAGENTS\_PER\_SESSION</code> 調整</div>

64 <div>「一律允許」權限規則會儲存在存放庫根目錄，因此在 git worktree 中授予的核准會在工作階段和 worktree 中持續</div>

65 <div>Amazon Bedrock、Google Cloud 的 Agent Platform 和 AWS 上的 Claude Platform 現在預設為 Claude Opus 4.8</div>

66 <div>摺疊的工具摘要行會顯示即時經過時間計數器，因此長時間執行的工具呼叫會明顯計時，而不是看起來卡住</div>

67 </div>

68</div>

70[v2.1.207–v2.1.212 的完整變更日誌 →](/docs/en/changelog#2-1-207)

whats-new/2026-w30.md +91 −0 created

Details

1> ## Documentation Index

2> 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.

5# 第 30 週 · 7 月 20–24 日，2026 年

7> Opus 5 成為預設的 Opus 模型，Claude Code Desktop 新增 iOS Simulator 窗格，Claude Security plugin 掃描您的程式碼以尋找漏洞。

9<div className="digest-meta">

10 <span>版本 <a href="/docs/en/changelog#2-1-214">v2.1.214 → v2.1.219</a></span>

11 <span>3 項功能 · 7 月 20–24 日</span>

12</div>

14<div className="digest-feature">

15 <div className="digest-feature-header">

16 <span className="digest-feature-title">Claude Opus 5</span>

17 <span className="digest-feature-pill">新模型</span>

18 </div>

20 <p className="digest-feature-lede">Claude Opus 5 是 Claude Code 中新的預設 Opus 模型。它是 Max、Team Premium、Enterprise 隨用隨付以及 Anthropic API 上的預設模型，也是 AWS 上的 Claude Platform、Amazon Bedrock 和 Google Cloud 的 Agent Platform 上的預設模型。在 Anthropic API 以及 Max、Team 和 Enterprise 方案上，Opus 5 以 <a href="/docs/zh-TW/model-config#extended-context">1M 權杖內容視窗</a>執行；在 Amazon Bedrock 和 Google Cloud 的 Agent Platform 上，請選擇 1M 模型變體。快速模式以每 MTok $10/$50 的價格移至 Opus 5。需要 v2.1.219 或更新版本。</p>

22 <Frame>

23 <video autoPlay muted loop playsInline className="w-full" src="https://mintcdn.com/claude-code/N3yEaTYPXMXFrF6k/images/whats-new/opus-5.mp4?fit=max&auto=format&n=N3yEaTYPXMXFrF6k&q=85&s=8536b1cb3180e539008f39930403e47b" data-path="images/whats-new/opus-5.mp4" />

24 </Frame>

26 <p className="digest-feature-try">按名稱切換至 Opus 5，或從模型選擇器中選擇：</p>

28 ```text Claude Code theme={null}

29 > /model claude-opus-5

30 ```

32 <a className="digest-feature-link" href="/docs/zh-TW/model-config#available-models">模型設定</a>

33</div>

35<div className="digest-feature">

36 <div className="digest-feature-header">

37 <span className="digest-feature-title">Claude Code Desktop 中的 iOS Simulator</span>

38 <span className="digest-feature-pill">Desktop</span>

39 </div>

41 <p className="digest-feature-lede">macOS 上的 Claude Code Desktop 獲得 iOS Simulator 窗格，在 Pro、Max 和 Team 方案上公開測試版。當 Claude 在模擬器中建置、啟動或檢查您的應用程式時，窗格會在對話旁邊開啟並即時串流裝置螢幕，因此您可以觀看 Claude 點選應用程式以驗證其變更，或自己驅動裝置。需要安裝 iOS 平台的 Xcode，以及 Claude Desktop v1.24012.0 或更新版本。</p>

43 <Frame>

44 <img className="w-full" src="https://mintcdn.com/claude-code/N3yEaTYPXMXFrF6k/images/whats-new/ios-simulator.jpg?fit=max&auto=format&n=N3yEaTYPXMXFrF6k&q=85&s=6c88418ed14ed0fb12cc1af75b17f2ee" alt="Claude Code Desktop 顯示 iOS Simulator 窗格，在對話旁邊顯示 iPhone 應用程式" width="2048" height="1152" data-path="images/whats-new/ios-simulator.jpg" />

45 </Frame>

47 <p className="digest-feature-try">要求 Claude 執行或測試您的應用程式，窗格會在應用程式啟動時開啟：</p>

49 ```text Claude Code theme={null}

50 > Build the app and run it in the simulator to check the onboarding flow.

51 ```

53 <a className="digest-feature-link" href="/docs/zh-TW/desktop-ios-simulator#run-your-app-in-the-simulator">在模擬器中測試 iOS 應用程式</a>

54</div>

56<div className="digest-feature">

57 <div className="digest-feature-header">

58 <span className="digest-feature-title">Claude Security plugin</span>

59 <span className="digest-feature-pill">plugin</span>

60 </div>

62 <p className="digest-feature-lede">Claude Security plugin 在 Claude Code 工作階段內執行您程式碼庫的多代理漏洞掃描：代理對應您的架構、建置威脅模型、搜尋漏洞，並在將報告寫入 <code>CLAUDE-SECURITY-\<timestamp>/</code> 目錄之前獨立審查每項發現。掃描整個儲存庫或僅掃描分支的差異、提取請求或單一提交，然後將您選擇的發現轉換為已審查的修補程式，由您自己應用。</p>

64 <p className="digest-feature-try">從官方 Anthropic marketplace 安裝 plugin，執行 <code>/reload-plugins</code>，然後使用 <code>/claude-security</code> 開始掃描：</p>

66 ```text Claude Code theme={null}

67 > /plugin install claude-security@claude-plugins-official

68 ```

70 <a className="digest-feature-link" href="/docs/zh-TW/claude-security#scan-and-fix-your-codebase">掃描並修復您的程式碼庫</a>

71</div>

73<div className="digest-wins">

74 <p className="digest-wins-title">其他成果</p>

76 <div className="digest-wins-grid">

77 <div><a href="/docs/zh-TW/code-review#review-a-diff-locally"><code>/code-review</code></a> 現在以具有自己內容視窗的背景子代理身份執行，因此審查工作不會進入您的對話，發現會在完成時到達</div>

78 <div><code>/verify</code>、<code>/code-review</code> 和 <code>/deep-research</code> 僅在您叫用時執行；Claude 不再自行啟動它們</div>

79 <div><a href="/docs/zh-TW/interactive-mode#emoji-shortcodes">Emoji 快速代碼</a>在提示輸入中自動完成：輸入 <code>:heart:</code> 以插入 emoji，或在 <code>:</code> 後輸入兩個或更多字元以獲得建議；使用 <code>emojiCompletionEnabled</code> 關閉它</div>

80 <div>具有 <code>context: fork</code> 的 Skills <a href="/docs/zh-TW/skills#run-skills-in-a-subagent">預設在背景執行</a>，而 skill 的 frontmatter 中的 <code>background: false</code> 會在同一輪中等待結果</div>

81 <div>工作階段預設最多同時執行 20 個子代理；使用 <code>CLAUDE\_CODE\_MAX\_CONCURRENT\_SUBAGENTS</code> 變更<a href="/docs/zh-TW/sub-agents#concurrent-subagent-limit">限制</a></div>

82 <div>`--max-budget-usd` 現在對子代理強制執行上限：一旦支出達到上限，Claude 就無法啟動更多，執行中的背景子代理會停止</div>

83 <div>新的 <a href="/docs/zh-TW/sandboxing#disable-filesystem-isolation"><code>sandbox.filesystem.disabled</code></a> 設定會跳過檔案系統隔離，同時保持網路出口控制</div>

84 <div>在自動模式中，危險 <code>rm</code> 命令、背景工作和可疑 Windows 路徑的檢查不再開啟權限對話框；自動模式分類器會改為判決它們</div>

85 <div>Bash 權限檢查在更多 shell 形式上失敗關閉，包括檔案描述符重新導向、<code>\[\[ ]]</code> 比較中的 Zsh 變數下標、可能執行不安全選項的 <code>help</code> 和 <code>man</code> 叫用，以及超過 10,000 個字元的命令</div>

86 <div><a href="/docs/zh-TW/fast-mode">快速模式</a>不再支援 Opus 4.7：<code>/fast</code> 現在適用於 Opus 5 和 Opus 4.8</div>

87 <div>長時間執行的工具呼叫會發出定期進度心跳，而不是保持沉默</div>

88 </div>

89</div>

91[v2.1.214–v2.1.219 的完整變更日誌 →](/docs/en/changelog#2-1-214)

whats-new/2026-w32.md +103 −0 created

Details

1> ## Documentation Index

2> 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.

5# 第 32 週 · 2026 年 8 月 3–7 日

7> Claude Code 工作階段可以互相傳送訊息、自託管環境在您的基礎設施上執行雲端工作階段，以及自動模式成為預設權限模式。

9<div className="digest-meta">

10 <span>版本 <a href="/docs/en/changelog#2-1-220">v2.1.220 → v2.1.224</a></span>

11 <span>3 項功能 · 8 月 3–7 日</span>

12</div>

14<div className="digest-feature">

15 <div className="digest-feature-header">

16 <span className="digest-feature-title">跨工作階段傳訊</span>

17 <span className="digest-feature-pill">v2.1.224</span>

18 </div>

20 <p className="digest-feature-lede">您的 Claude Code 工作階段現在可以互相傳送訊息。Claude 使用 <code>ListAgents</code> 工具發現您的其他工作階段，並使用 <code>SendMessage</code> 傳送訊息，可以在您要求時傳送，也可以自動傳送，例如在一個工作階段中的變更影響另一個工作階段的工作時。訊息是 Claude 為另一個工作階段撰寫的文字，絕不是您的對話歷史記錄或檔案。適用於 macOS 和 Linux。需要 v2.1.224 或更新版本。</p>

22 <Frame>

23 <video autoPlay muted loop playsInline className="w-full" src="https://mintcdn.com/claude-code/N3yEaTYPXMXFrF6k/images/whats-new/cross-session-messaging.mp4?fit=max&auto=format&n=N3yEaTYPXMXFrF6k&q=85&s=8f33c3390f78660a4a26dc980f46159f" data-path="images/whats-new/cross-session-messaging.mp4" />

24 </Frame>

26 <p className="digest-feature-try">在同一台機器上開啟兩個工作階段，要求其中一個傳遞一些內容：</p>

28 ```text title="Claude Code" wrap theme={null}

29 Tell the session working on the payments API that users.name is now users.display_name

30 ```

32 <p className="digest-feature-try">一旦 Claude 讀取訊息，另一個工作階段會顯示 <code>Message from</code> 列；按 <code>Ctrl+O</code> 展開它。若要查看 Claude 可以到達哪些工作階段，請執行 <code>/list-agents</code>。</p>

34 <a className="digest-feature-link" href="/docs/zh-TW/cross-session-messaging#message-another-session">傳訊給另一個工作階段</a>

35</div>

37<div className="digest-feature">

38 <div className="digest-feature-header">

39 <span className="digest-feature-title">自託管環境</span>

40 <span className="digest-feature-pill">v2.1.224</span>

41 </div>

43 <p className="digest-feature-lede">自託管環境在您組織自己的基礎設施上執行 Claude Code 雲端工作階段，在 Team 和 Enterprise 方案上處於公開測試版。在您的機器或容器上執行 <code>claude self-hosted-runner</code> 將它們轉變為執行器。當有人在從 claude.ai、行動或桌面應用程式或 `claude --cloud` 啟動工作階段時選擇您的環境，該工作階段會在您的網路內執行，可以存取您的內部服務。擁有者首先在 <a href="https://claude.ai/admin-settings/cloud-environments">管理設定</a>中開啟 <strong>允許自託管環境</strong>。</p>

45 <Frame>

46 <img className="w-full" src="https://mintcdn.com/claude-code/N3yEaTYPXMXFrF6k/images/whats-new/self-hosted-environments.jpg?fit=max&auto=format&n=N3yEaTYPXMXFrF6k&q=85&s=ae9152cb1670c8af517d1aee57689b14" alt="自託管環境管理頁面，列出環境（例如 linux-dev 和 macos-prod）及其狀態和活躍工作階段計數" width="2048" height="1152" data-path="images/whats-new/self-hosted-environments.jpg" />

47 </Frame>

49 <p className="digest-feature-try">以擁有者身份登入，執行引導式設定，它會引導您建立環境並啟動執行器：</p>

51 ```bash terminal theme={null}

52 claude self-hosted-runner setup

53 ```

55 <p className="digest-feature-try">執行器註冊後，環境在管理設定中顯示 <strong>健康</strong>。</p>

57 <a className="digest-feature-link" href="/docs/zh-TW/self-hosted-environments-quickstart#set-up-an-environment-and-runner">自託管環境快速入門</a>

58</div>

60<div className="digest-feature">

61 <div className="digest-feature-header">

62 <span className="digest-feature-title">自動模式成為預設</span>

63 <span className="digest-feature-pill">CLI</span>

64 </div>

66 <p className="digest-feature-lede">從 8 月 14 日開始，自動模式是 Pro、Max 和 Team 方案上新工作階段的預設權限模式。如果您自己設定了預設模式，它會保持不變，除非您接受一次性切換提示，而您的組織管理的預設模式不會改變。您仍然可以隨時切換模式。已在這些方案上生效：自動模式進行的分類器呼叫不再計入您的使用限制。</p>

68 <p className="digest-feature-try">在切換前讓每個工作階段都以自動模式啟動，請在您的使用者設定中將其設定為預設值：</p>

70 ```json ~/.claude/settings.json {3} theme={null}

71 {

72 "permissions": {

73 "defaultMode": "auto"

74 }

75 }

76 ```

78 <p className="digest-feature-try">新工作階段隨後在狀態列中顯示 <code>auto mode on</code>。</p>

80 <a className="digest-feature-link" href="/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode">自動模式需求和控制</a>

81</div>

83<div className="digest-wins">

84 <p className="digest-wins-title">其他改進</p>

86 <div className="digest-wins-grid">

87 <div>VS Code 擴充功能獲得 <a href="/docs/zh-TW/vs-code#extension-settings">焦點檢視</a>，它在每個回合後面隱藏工具活動；從命令選單或使用 <code>Ctrl+Alt+F</code>（Mac 上為 <code>Ctrl+Option+F</code>）切換它</div>

88 <div>沙箱認證檔案在 Linux 和 WSL2 上接受 <a href="/docs/zh-TW/sandboxing#mask-credential-files"><code>mode: "mask"</code></a>，因此沙箱化命令讀取哨兵副本，而沙箱代理在出口時替換實際值；認證遮罩也獲得 <code>extract</code>、JWT 感知 <code>decode</code> 和 AWS SigV4 重新簽署選項</div>

89 <div>市場可以使用新的 <a href="/docs/zh-TW/plugin-marketplaces#zip-archives"><code>archive</code> 來源</a>將外掛程式分發為 zip 封存，透過 HTTPS 下載並具有可選的 SHA-256 釘選，因此安裝無需 git 或 npm</div>

90 <div><code>/review</code> 現在是 <a href="/docs/zh-TW/code-review#review-a-diff-locally"><code>/code-review</code></a> 的別名，<code>/code-review</code> 沒有努力等級時會重複使用您上次輸入的等級</div>

91 <div>您使用 <a href="/docs/zh-TW/agent-view#copy-the-session-with-%2Ffork"><code>/fork</code></a> 複製的工作階段現在在其自己的 worktree 中進行程式碼變更，而不是原始工作階段的簽出</div>

92 <div>您從 <a href="/docs/zh-TW/discover-plugins#install-plugins"><code>/plugin</code></a> 安裝的外掛程式在當前工作階段中啟動（如果安全的話）；安裝摘要報告 <code>Plugin is now active.</code> 或告訴您執行 <code>/reload-plugins</code></div>

93 <div><a href="/docs/zh-TW/agent-view#how-file-edits-are-isolated">背景工作階段</a>在 worktree 中變更程式碼現在在完成前提交並推送，僅在任務要求時開啟草稿拉取請求，並遵循您 <code>CLAUDE.md</code> 中的 git 指示</div>

94 <div>每個工作階段 200 個子代理的上限已移除，因此長時間執行的工作階段不再拒絕新的子代理；<a href="/docs/zh-TW/sub-agents#concurrent-subagent-limit">並行</a>和深度限制仍然適用</div>

95 <div>存放庫的簽入設定不再能開啟 <a href="/docs/zh-TW/remote-control#enable-remote-control-for-all-sessions">遠端控制自動連線</a>；改為在您的使用者或受管設定中設定 <code>remoteControlAtStartup</code>，而專案和本機設定只能將其關閉</div>

96 <div><a href="/docs/zh-TW/worktrees#how-claude-code-enforces-isolation">Worktree 隔離</a>現在不僅阻止檔案編輯，還阻止 Bash 命令和 git 重新導向到達主簽出，在每個工作階段類型和工作階段的子代理中</div>

97 <div>Bash 命令不再能隱藏自身的一部分免於權限檢查，而製表符或不可見的 Unicode 填充不再隱藏命令的一部分免於核准對話框</div>

98 <div>PreToolUse 自動允許鉤子不再在 Claude Code 的內部側任務（例如摘要和壓縮）中繞過工具限制</div>

99 <div><a href="/docs/zh-TW/ultraplan">Ultraplan</a> 研究預覽已移除，包括 <code>/ultraplan</code> 命令和 <code>ultraplan</code> 關鍵字；改為使用計畫模式或網路上的 Claude Code</div>

100 </div>

101</div>

102

103[v2.1.220–v2.1.224 的完整變更日誌 →](/docs/en/changelog#2-1-220)

whats-new/2026-w33.md +87 −0 created

Details

1> ## Documentation Index

2> 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.

5# 第 33 週 · 2026 年 8 月 10–14 日

7> Claude Code Desktop 在使用限制重設後自動繼續，Fork 模式預設開啟，GitLab 合併請求和市集加入 GitHub。

9<div className="digest-meta">

10 <span>版本 <a href="/docs/en/changelog#2-1-225">v2.1.225 → v2.1.233</a></span>

11 <span>3 項功能 · 8 月 10–14 日</span>

12</div>

14<div className="digest-feature">

15 <div className="digest-feature-header">

16 <span className="digest-feature-title">Desktop 上使用限制重設後自動繼續</span>

17 <span className="digest-feature-pill">Desktop</span>

18 </div>

20 <p className="digest-feature-lede">當您在 Claude Code Desktop 的 Code 分頁中達到工作階段限制時，限制卡片現在提供 <strong>限制重設時自動繼續</strong> 核取方塊。勾選它，Desktop 應用程式會在重設後重試中斷的回合。卡片會顯示重試時間。每週限制卡片不提供此選項。</p>

22 <Frame>

23 <video autoPlay muted loop playsInline className="w-full" src="https://mintcdn.com/claude-code/2SnAdpL4dJ18nKb3/images/whats-new/desktop-auto-continue.mp4?fit=max&auto=format&n=2SnAdpL4dJ18nKb3&q=85&s=1937f489695feaea715e48ecfd7e62cd" data-path="images/whats-new/desktop-auto-continue.mp4" />

24 </Frame>

26 <p className="digest-feature-try">下次出現工作階段限制卡片時，勾選 <strong>限制重設時自動繼續</strong> 並保持工作階段開啟。卡片會顯示 <code>自動繼續於</code> 後面跟著重設時間，一旦限制重設，回合就會自動繼續。</p>

28 <a className="digest-feature-link" href="/docs/zh-TW/errors#youve-hit-your-session-limit">達到使用限制時該怎麼辦</a>

29</div>

31<div className="digest-feature">

32 <div className="digest-feature-header">

33 <span className="digest-feature-title">Fork 模式預設開啟</span>

34 <span className="digest-feature-pill">v2.1.232</span>

35 </div>

37 <p className="digest-feature-lede">Fork 模式現在在互動式工作階段中預設開啟。Claude 可以請求 <code>fork</code> 子代理類型，它繼承完整的對話和提示快取，而不是從頭開始，所以您不必為側邊任務重新解釋背景。Claude 在互動式工作階段中產生的子代理（除了代理團隊隊友產生的子代理外）也預設在背景中執行。</p>

39 <p className="digest-feature-try">使用需要您迄今為止討論的所有內容的任務自行啟動 fork：</p>

41 ```text Claude Code theme={null}

42 > /subtask draft unit tests for the parser changes so far

43 ```

45 <p className="digest-feature-try">fork 會出現在您的提示下方的面板中，其結果在完成時會到達您的對話。若要關閉 fork 模式，請設定 <code>CLAUDE\_CODE\_FORK\_SUBAGENT=0</code>。</p>

47 <a className="digest-feature-link" href="/docs/zh-TW/sub-agents#turn-fork-mode-on-or-off">開啟或關閉 fork 模式</a>

48</div>

50<div className="digest-feature">

51 <div className="digest-feature-header">

52 <span className="digest-feature-title">GitLab 合併請求和市集</span>

53 <span className="digest-feature-pill">v2.1.232</span>

54 </div>

56 <p className="digest-feature-lede">外掛程式市集複製裸 <code>gitlab.com</code> URL，包括巢狀子群組。在 v2.1.233 或更新版本上，將 GitLab 合併請求 URL 傳遞給 <code>--worktree</code> 以從中建立分支，<code>claude agents</code> 檢視會將連結到合併請求的工作階段標記為 <code>!N</code>。Claude Code 也會編輯 GitLab 權杖系列（例如 <code>glpat-</code> 和 <code>glrt-</code>），並以與保護 <code>gh</code> 相同的方式保護 <code>glab</code> CLI 的設定存放區。</p>

58 <p className="digest-feature-try">在從合併請求建立分支的 worktree 中啟動工作階段：</p>

60 ```bash terminal theme={null}

61 claude --worktree https://gitlab.com/group/project/-/merge_requests/42

62 ```

64 <p className="digest-feature-try">當 <code>origin</code> 在 gitlab.com 上時，Claude Code 會擷取 <code>merge-requests/42/head</code> 並在其自己的 worktree 中的該分支上開啟工作階段。</p>

66 <a className="digest-feature-link" href="/docs/zh-TW/worktrees#branch-from-a-pull-request">從提取或合併請求建立 worktree 分支</a>

67</div>

69<div className="digest-wins">

70 <p className="digest-wins-title">其他成果</p>

72 <div className="digest-wins-grid">

73 <div>在提示中輸入 <code>@</code> 以<a href="/docs/zh-TW/cross-session-messaging#message-another-session">提及另一個 Claude 工作階段</a>的名稱，Claude 會使用 <code>SendMessage</code> 直接向其傳送訊息；完全符合一個即時工作階段的裸名稱現在無需確認步驟即可傳遞</div>

74 <div>一台機器上的互動式工作階段保持<a href="/docs/zh-TW/cross-session-messaging#see-which-sessions-claude-can-reach">唯一名稱</a>：如果您使用另一個即時工作階段已使用的名稱啟動或重新命名工作階段，Claude Code 會為您的工作階段提供 <code>name-word-word</code> 變體並告知您</div>

75 <div>外掛程式市集接受 <a href="/docs/zh-TW/plugin-marketplaces#command-sources"><code>command</code> 來源</a>：本機命令會列印外掛程式目錄，Claude Code 會在每個工作階段中重新解析並應用，無需重新啟動</div>

76 <div>在 Linux 和 WSL 上，將 <a href="/docs/zh-TW/tools-reference#memory-limit-on-linux-and-wsl"><code>CLAUDE\_CODE\_TOOL\_MEMORY\_LIMIT</code></a> 設定為 <code>4G</code> 之類的大小，以限制 Bash 和 PowerShell 工具命令可以使用的記憶體</div>

77 <div>任務追蹤工具（例如 <code>TaskCreate</code>、<code>TaskUpdate</code> 和 <code>TodoWrite</code>）<a href="/docs/zh-TW/tools-reference#task-tool-availability">在 Opus 4.8、Sonnet 5、Fable 5、Mythos 5 及更新版本的這些系列上不再可用</a>；設定 <code>CLAUDE\_CODE\_ENABLE\_TODO\_TOOLS=1</code> 以重新啟用它們</div>

78 <div><a href="/docs/zh-TW/code-review#review-a-diff-locally"><code>/code-review</code></a> 在高、超高和最大努力級別現在像其他級別一樣在背景代理中執行</div>

79 <div><a href="/docs/zh-TW/discover-plugins#install-plugins"><code>/plugin install plugin\@marketplace</code></a> 首先重新整理市集，因此新發佈的外掛程式無需手動市集更新即可安裝</div>

80 <div>設定接受 <a href="/docs/zh-TW/settings-reference#marketplace-key-aliases"><code>additionalMarketplaces</code> 和 <code>allowedMarketplaces</code></a> 作為 <code>extraKnownMarketplaces</code> 和 <code>strictKnownMarketplaces</code> 的別名</div>

81 <div>在較新的模型上，Claude 可以<a href="/docs/zh-TW/tools-reference#write-tool-behavior">使用 Write 工具覆寫現有檔案</a>，無需在此工作階段中先讀取它，符合 Edit 工具的規則；較舊的模型需要讀取</div>

82 <div>VS Code 擴充功能可以<a href="/docs/zh-TW/vs-code#organize-sessions-into-groups">將工作階段清單組織成群組</a>：按右鍵以建立、重新命名或刪除群組，並使用 Cmd/Ctrl- 或 Shift-點擊以一次移動多個工作階段</div>

83 <div>如果您的組織透過<a href="/docs/zh-TW/claude-apps-gateway-spend-limits">具有支出限制的 Claude 應用程式閘道</a>路由 Claude Code，Claude Code 會在您達到限制時顯示限制期間、其重設時間和操作員的訊息</div>

84 </div>

85</div>

87[v2.1.225–v2.1.233 的完整變更日誌 →](/docs/en/changelog#2-1-225)

whats-new/2026-w34.md +105 −0 created

Details

1> ## Documentation Index

2> 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.

5# 第 34 週 · 2026 年 8 月 17–21 日

7> 使用 /design 技能草擬可編輯的 UI 畫板、設定簡潔輸出風格，以及從手機在您的機器上啟動 Claude Code 工作階段。

9<div className="digest-meta">

10 <span>版本 <a href="/docs/en/changelog#2-1-234">v2.1.234 → v2.1.239</a></span>

11 <span>3 項功能 · 8 月 17–21 日</span>

12</div>

14<div className="digest-feature">

15 <div className="digest-feature-header">

16 <span className="digest-feature-title">/design</span>

17 <span className="digest-feature-pill">研究預覽</span>

18 </div>

20 <p className="digest-feature-lede"><code>/design</code> 技能將 Claude Design 的畫板工作流程帶入 CLI 和 Claude Code Desktop，以成品為基礎。使用簡短說明執行它，Claude 會發佈一個可編輯畫板的畫布供您的 UI 使用。選擇一個、調整它，然後讓 Claude 實現它。適用於 Pro、Max、Team 和 Enterprise。需要 v2.1.234 或更新版本。</p>

22 <Frame>

23 <video autoPlay muted loop playsInline className="w-full" src="https://mintcdn.com/claude-code/2SnAdpL4dJ18nKb3/images/whats-new/design-skill.mp4?fit=max&auto=format&n=2SnAdpL4dJ18nKb3&q=85&s=0b376a94227c14a4204af89c4c9fd7ac" data-path="images/whats-new/design-skill.mp4" />

24 </Frame>

26 <p className="digest-feature-try">描述您想要設計的內容，讓 Claude 草擬選項：</p>

28 ```text Claude Code theme={null}

29 > /design redesign the composer based on what people actually use it for

30 ```

32 <p className="digest-feature-try">Claude 列印已發佈畫布的連結。開啟它、選擇一個畫板，然後告訴 Claude 要實現哪個選項。</p>

34 <a className="digest-feature-link" href="/docs/zh-TW/artifacts#availability">成品可用的位置</a>

35</div>

37<div className="digest-feature">

38 <div className="digest-feature-header">

39 <span className="digest-feature-title">簡潔輸出風格</span>

40 <span className="digest-feature-pill">v2.1.237</span>

41 </div>

43 <p className="digest-feature-lede">簡潔是一種新的內建輸出風格。Claude 以結果開頭並跳過前言和敘述，同時以與預設風格相同的徹底方式進行工作。當您要求解釋或更多詳細資訊時，Claude 會完整回答。錯誤報告、安全警告和破壞性操作的確認保持其完整內容。</p>

45 <Frame>

46 <video autoPlay muted loop playsInline className="w-full" src="https://mintcdn.com/claude-code/2SnAdpL4dJ18nKb3/images/whats-new/concise-output-style.mp4?fit=max&auto=format&n=2SnAdpL4dJ18nKb3&q=85&s=dfb40ec8921ed1bc82eb629042a8ec17" data-path="images/whats-new/concise-output-style.mp4" />

47 </Frame>

49 <p className="digest-feature-try">在 <code>/config</code> 中的 <strong>輸出風格</strong> 下開啟它，或在您的設定檔中設定它：</p>

51 ```json ~/.claude/settings.json {2} theme={null}

52 {

53 "outputStyle": "Concise"

54 }

55 ```

57 <p className="digest-feature-try">執行 <code>/clear</code> 或啟動新工作階段，Claude 的回覆以結果開頭。</p>

59 <a className="digest-feature-link" href="/docs/zh-TW/output-styles#built-in-output-styles">內建輸出風格</a>

60</div>

62<div className="digest-feature">

63 <div className="digest-feature-header">

64 <span className="digest-feature-title">從手機在您的機器上啟動工作階段</span>

65 <span className="digest-feature-pill">行動</span>

66 </div>

68 <p className="digest-feature-lede">任何執行 <code>claude remote-control</code> 的機器現在都會在 Claude 應用程式的 Code 標籤頂部顯示為裝置卡片。Remote Control 也已不再處於研究預覽。</p>

70 <Frame>

71 <img className="w-full" src="https://mintcdn.com/claude-code/2SnAdpL4dJ18nKb3/images/whats-new/remote-control-phone-start.jpg?fit=max&auto=format&n=2SnAdpL4dJ18nKb3&q=85&s=9f0ebedab23aa0e1732cc37782573907" alt="Claude 行動應用程式中的 Code 標籤，其中 Devices 部分在工作階段清單上方顯示連接的 MacBook 作為裝置卡片" width="1206" height="895" data-path="images/whats-new/remote-control-phone-start.jpg" />

72 </Frame>

74 <p className="digest-feature-try">在您想要連接的機器上啟動 Remote Control，然後在手機上開啟 Code 標籤：</p>

76 ```bash terminal theme={null}

77 claude remote-control

78 ```

80 <p className="digest-feature-try">您的機器在 Code 標籤頂部顯示為裝置卡片。點擊它以選擇目錄並在該處啟動工作階段。</p>

82 <a className="digest-feature-link" href="/docs/zh-TW/remote-control#start-a-remote-control-session">啟動 Remote Control 工作階段</a>

83</div>

85<div className="digest-wins">

86 <p className="digest-wins-title">其他成果</p>

88 <div className="digest-wins-grid">

89 <div>Claude Code 現在會在 claude.ai 使用限制重設時自動繼續您的工作階段；從 <code>/config</code> 中的 <strong>在使用限制時自動繼續</strong> 列關閉它</div>

90 <div>選用的 <a href="/docs/zh-TW/interactive-mode#check-spelling-as-you-type"><code>spellcheck</code> 設定</a> 在您輸入時在提示輸入中為拼寫錯誤的單字加上底線，使用您安裝的 <code>aspell</code>、<code>hunspell</code> 或 <code>ispell</code></div>

91 <div>在具有開啟 GitLab 合併請求的分支上，使用透過 <code>glab auth login</code> 驗證的 <code>glab</code> CLI，頁尾會顯示一個 <a href="/docs/zh-TW/interactive-mode#gitlab-merge-requests"><code>MR !N</code> 徽章</a>，其顏色取決於合併請求是草稿、開啟還是可合併</div>

92 <div>從手機或 claude.ai/code 變更工作量級別，它會 <a href="/docs/zh-TW/remote-control#what-connected-devices-see">套用到您機器上的工作階段</a>；由 Desktop 或 VS Code 託管的 Remote Control 工作階段也會向連接的裝置顯示工作階段的目前權限模式</div>

93 <div>您可以在 Claude 工作時開啟 <a href="/docs/zh-TW/permissions#manage-permissions"><code>/permissions</code></a> 或執行 <code>/add-dir \<path></code>；權限規則變更適用於目前回合的其餘部分</div>

94 <div>當背景工作讓 <a href="/docs/zh-TW/goal#background-work-defers-evaluation"><code>/goal</code></a> 等待時，Claude 在 30 分鐘後檢查它們，而不是無限期等待，並持續檢查，在工作階段閒置時以更長的間隔檢查；設定 <code>CLAUDE\_CODE\_GOAL\_CHECKIN\_MINUTES=0</code> 以選擇退出</div>

95 <div>您自己的提示現在在文字記錄中呈現 markdown，具有突出顯示的程式碼區塊、內嵌程式碼和清單，與回覆的方式相同</div>

96 <div>新的 <a href="/docs/zh-TW/model-config#set-a-default-model-for-new-sessions"><code>ANTHROPIC\_DEFAULT\_MODEL</code></a> 環境變數設定新工作階段啟動的模型；<code>/model</code> 選擇仍會覆蓋它並在重新啟動時保持</div>

97 <div>使用 <code>SendMessage</code> 上的 <code>notify\_when\_idle</code> 輸入，Claude 可以要求同一機器上的另一個 Claude Code 工作階段 <a href="/docs/zh-TW/cross-session-messaging#get-a-notice-when-another-session-goes-idle">在它下次閒置時傳送一個通知</a></div>

98 <div>將 <a href="/docs/zh-TW/interactive-mode#make-ctrl-w-delete-back-to-whitespace"><code>keybindingFlavor</code></a> 設定為 <code>"readline"</code>，使提示中的 <code>Ctrl+W</code> 刪除回到前一個空白字元，如 Bash 所做的那樣，而不是在標點符號（例如 <code>/</code>）處停止</div>

99 <div>在原生 Windows 上，您的 Claude Code 工作階段現在可以 <a href="/docs/zh-TW/cross-session-messaging#availability">使用 <code>SendMessage</code> 相互傳訊</a> 並使用 <code>ListAgents</code> 相互尋找，如同在 macOS 和 Linux 上一樣</div>

100 <div>自託管執行器接受 `--defer-shutdown-max-min`，它 <a href="/docs/zh-TW/self-hosted-environments-deploy#defer-the-drain-past-the-first-signal">在 SIGTERM 後的設定分鐘數內繼續為附加工作階段提供服務</a></div>

101 <div>自託管執行器接受 `--proxy-authorization-command` 或 `--proxy-authorization-file` 為 <a href="/docs/zh-TW/self-hosted-environments-deploy#authenticate-to-an-egress-proxy">需要一個的出口代理提供新的 `Proxy-Authorization` 標頭</a></div>

102 </div>

103</div>

104

105[v2.1.234–v2.1.239 的完整變更日誌 →](/docs/en/changelog#2-1-234)

workflows.md +1 −1

Details

348 348

349主體是具有頂級 `await` 的純 JavaScript。`agent()` 生成一個子代理，`pipeline()` 為清單中的每個項目執行一個，而 `parallel()` 同時執行一組代理任務並等待所有任務完成。349主體是具有頂級 `await` 的純 JavaScript。`agent()` 生成一個子代理，`pipeline()` 為清單中的每個項目執行一個，而 `parallel()` 同時執行一組代理任務並等待所有任務完成。

350 350

351如果您停止 `agent()` 呼叫中途或它遇到無法恢復的 API 錯誤，該呼叫會解析為 `null`。`pipeline()` 在結果陣列中保留該 `null`，這就是為什麼範例以 `.filter(Boolean)` 結尾以刪除這些項目。351如果您停止 `agent()` 呼叫中途或它遇到無法恢復的 API 錯誤，該呼叫會解析為 `null`。在[自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)中，分類器可以在子代理啟動之前阻止 `agent()` 呼叫。被阻止的呼叫會解析為 `null` 並在執行的進度檢視中顯示原因。`pipeline()` 在結果陣列中保留每個 `null`，這就是為什麼範例以 `.filter(Boolean)` 結尾以刪除這些項目。

352 352

353如果您在 `agent()` 呼叫上傳遞 `schema`，該子代理會傳回與形狀相符的 JSON 而不是散文。Claude Code 在啟動子代理之前檢查架構：當它可以證明架構自相矛盾時，呼叫會失敗並出現錯誤，命名矛盾，子代理永遠不會啟動。它可以證明的一個矛盾是 `additionalProperties: false` 排除的 `required` 鍵。353如果您在 `agent()` 呼叫上傳遞 `schema`，該子代理會傳回與形狀相符的 JSON 而不是散文。Claude Code 在啟動子代理之前檢查架構：當它可以證明架構自相矛盾時，呼叫會失敗並出現錯誤，命名矛盾，子代理永遠不會啟動。它可以證明的一個矛盾是 `additionalProperties: false` 排除的 `required` 鍵。

354 354

Documentation 2026-09-11 23:01 UTC to 2026-09-12 03:02 UTC