Documentation — Spybara

agent-sdk/hooks.md +71 −71

Details

15* **追蹤會話生命週期**以管理狀態、清理資源或傳送通知15* **追蹤會話生命週期**以管理狀態、清理資源或傳送通知

16 16

17<h2 id="how-hooks-work">17<h2 id="how-hooks-work">

~~18 Hooks 如何工作~~18 Hook 如何運作

19</h2>19</h2>

20 20

21<Steps>21<Steps>

22 <Step title="事件觸發">22 <Step title="事件觸發">

23 代理執行期間發生某事，SDK 觸發事件：工具即將被呼叫（`PreToolUse`）、工具返回結果（`PostToolUse`）、子代理啟動或停止、代理空閒或執行完成。請參閱[完整事件列表](#available-hooks)。23 agent 執行期間發生某事，SDK 觸發事件：工具即將被呼叫（`PreToolUse`）、工具返回結果（`PostToolUse`）、subagent 啟動或停止、agent 閒置或執行完成。請參閱[完整事件列表](#available-hooks)。

24 </Step>24 </Step>

25 25

~~26 <Step title="SDK 收集已註冊的 hooks">~~26 <Step title="SDK 收集已註冊的 hook">

27 SDK 檢查為該事件類型註冊的 hooks。這包括您在 `options.hooks` 中傳遞的回調 hooks 和來自設定檔案的 shell 命令 hooks，當相應的 [`settingSources`](/docs/zh-TW/agent-sdk/typescript#settingsource) 或 [`setting_sources`](/docs/zh-TW/agent-sdk/python#settingsource) 項目啟用時（預設 `query()` 選項就是這樣）。27 SDK 檢查為該事件類型註冊的 hook。這包括您在 `options.hooks` 中傳遞的回呼 hook，以及當相應的 [`settingSources`](/docs/zh-TW/agent-sdk/typescript#settingsource) 或 [`setting_sources`](/docs/zh-TW/agent-sdk/python#settingsource) 項目啟用時（預設 `query()` 選項即為啟用）來自設定檔的 shell 命令 hook。

28 </Step>28 </Step>

29 29

~~30 <Step title="匹配器篩選哪些 hooks 執行">~~30 <Step title="matcher 篩選哪些 hook 執行">

31 如果 hook 有 [`matcher`](#matchers) 模式（例如 `"Write|Edit"`），SDK 會針對事件的目標（例如工具名稱）測試它。沒有匹配器的 hooks 會針對該類型的每個事件執行。31 如果 hook 有 [`matcher`](#matchers) 模式（例如 `"Write|Edit"`），SDK 會針對事件的目標（例如工具名稱）測試它。沒有 matcher 的 hook 會針對該類型的每個事件執行。

32 </Step>32 </Step>

33 33

~~34 <Step title="回調函數執行">~~34 <Step title="回呼函式執行">

~~35 每個匹配的 hook 的[回調函數](#callback-functions)接收有關正在發生的事情的輸入：工具名稱、其參數、會話 ID 和其他事件特定的詳細資訊。~~35 每個相符 hook 的[回呼函式](#callback-functions)會接收有關正在發生之事的輸入：工具名稱、其引數、工作階段 ID 以及其他事件特定的詳細資訊。

36 </Step>36 </Step>

37 37

~~38 <Step title="您的回調返回決定">~~38 <Step title="您的回呼返回決定">

39 執行任何操作（記錄、API 呼叫、驗證）後，您的回調返回[輸出物件](#outputs)，告訴代理該做什麼：允許操作、阻止它、修改輸入或將上下文注入對話。39 執行任何操作（日誌、API 呼叫、驗證）後，您的回呼會返回[輸出物件](#outputs)，告訴 agent 該做什麼：允許操作、阻止它、修改輸入或將上下文注入對話。

40 </Step>40 </Step>

41</Steps>41</Steps>

42 42

43以下範例將這些步驟組合在一起。它註冊一個 `PreToolUse` hook（步驟 1），帶有 `"Write|Edit"` 匹配器（步驟 3），因此回調只針對檔案寫入工具觸發。觸發時，回調接收工具的輸入（步驟 4），檢查檔案路徑是否針對 `.env` 檔案，並返回 `permissionDecision: "deny"` 以阻止操作（步驟 5）：43以下範例將這些步驟組合在一起。它註冊一個 `PreToolUse` hook（步驟 1），帶有 `"Write|Edit"` matcher（步驟 3），因此回呼只針對檔案寫入工具觸發。觸發時，回呼接收工具的輸入（步驟 4），檢查檔案路徑是否指向 `.env` 檔案，並返回 `permissionDecision: "deny"` 以阻止操作（步驟 5）：

44 44

45<CodeGroup>45<CodeGroup>

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

54 )54 )

55 55

56 56

~~57 # 定義一個接收工具呼叫詳細資訊的 hook 回調~~57 # 定義一個接收工具呼叫詳細資訊的 hook 回呼

58 async def protect_env_files(input_data, tool_use_id, context):58 async def protect_env_files(input_data, tool_use_id, context):

~~59 # 從工具的輸入參數中提取檔案路徑~~59 # 從工具的輸入引數中提取檔案路徑

60 file_path = input_data["tool_input"].get("file_path", "")60 file_path = input_data["tool_input"].get("file_path", "")

61 file_name = file_path.split("/")[-1]61 file_name = file_path.split("/")[-1]

62 62

~~63 # 如果針對 .env 檔案，阻止操作~~63 # 如果指向 .env 檔案，阻止操作

64 if file_name == ".env":64 if file_name == ".env":

65 return {65 return {

66 "hookSpecificOutput": {66 "hookSpecificOutput": {

78 options = ClaudeAgentOptions(78 options = ClaudeAgentOptions(

79 hooks={79 hooks={

80 # 為 PreToolUse 事件註冊 hook80 # 為 PreToolUse 事件註冊 hook

~~81 # 匹配器篩選為僅 Write 和 Edit 工具呼叫~~81 # matcher 篩選為僅 Write 和 Edit 工具呼叫

82 "PreToolUse": [HookMatcher(matcher="Write|Edit", hooks=[protect_env_files])]82 "PreToolUse": [HookMatcher(matcher="Write|Edit", hooks=[protect_env_files])]

83 }83 }

84 )84 )

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

98 import { query, HookCallback, PreToolUseHookInput } from "@anthropic-ai/claude-agent-sdk";98 import { query, HookCallback, PreToolUseHookInput } from "@anthropic-ai/claude-agent-sdk";

99 99

100 // 使用 HookCallback 類型定義 hook 回調100 // 使用 HookCallback 類型定義 hook 回呼

101 const protectEnvFiles: HookCallback = async (input, toolUseID, { signal }) => {101 const protectEnvFiles: HookCallback = async (input, toolUseID, { signal }) => {

102 // 將輸入轉換為特定 hook 類型以確保類型安全102 // 將輸入轉換為特定 hook 類型以確保類型安全

103 const preInput = input as PreToolUseHookInput;103 const preInput = input as PreToolUseHookInput;

107 const filePath = toolInput?.file_path as string;107 const filePath = toolInput?.file_path as string;

108 const fileName = filePath?.split("/").pop();108 const fileName = filePath?.split("/").pop();

109 109

110 // 如果針對 .env 檔案，阻止操作110 // 如果指向 .env 檔案，阻止操作

111 if (fileName === ".env") {111 if (fileName === ".env") {

112 return {112 return {

113 hookSpecificOutput: {113 hookSpecificOutput: {

127 options: {127 options: {

128 hooks: {128 hooks: {

129 // 為 PreToolUse 事件註冊 hook129 // 為 PreToolUse 事件註冊 hook

130 // 匹配器篩選為僅 Write 和 Edit 工具呼叫130 // matcher 篩選為僅 Write 和 Edit 工具呼叫

131 PreToolUse: [{ matcher: "Write|Edit", hooks: [protectEnvFiles] }]131 PreToolUse: [{ matcher: "Write|Edit", hooks: [protectEnvFiles] }]

132 }132 }

133 }133 }

140 ```140 ```

141</CodeGroup>141</CodeGroup>

142 142

143當您執行任一指令碼時，Claude 嘗試建立 `.env` 檔案，hook 拒絕工具呼叫，Claude 的最終回應說明它無法建立 `.env` 檔案。143當您執行任一指令碼時，Claude 會嘗試建立 `.env` 檔案，而 hook 會拒絕該工具呼叫。

144 144

145<h2 id="available-hooks">145<h2 id="available-hooks">

146 可用的 hooks146 可用的 hooks

179| `ConfigChange` | 否 | 是 | 設定檔案變更 | 動態重新載入設定 |179| `ConfigChange` | 否 | 是 | 設定檔案變更 | 動態重新載入設定 |

180| `InstructionsLoaded` | 否 | 是 | `CLAUDE.md` 或規則檔案載入到上下文中 | 審計哪些指令檔案載入 |180| `InstructionsLoaded` | 否 | 是 | `CLAUDE.md` 或規則檔案載入到上下文中 | 審計哪些指令檔案載入 |

181| `WorktreeCreate` | 否 | 是 | Git worktree 已建立 | 追蹤隔離的工作區 |181| `WorktreeCreate` | 否 | 是 | Git worktree 已建立 | 追蹤隔離的工作區 |

182| `WorktreeRemove` | 否 | 是 | Git worktree 已移除 | 清理工作區資源 |182| `WorktreeRemove` | 否 | 是 | 正在移除由 `WorktreeCreate` hook 建立的 worktree | 清理工作區資源 |

183| `CwdChanged` | 否 | 是 | 會話期間工作目錄變更 | 按目錄重新載入環境變數 |183| `CwdChanged` | 否 | 是 | 會話期間工作目錄變更 | 按目錄重新載入環境變數 |

184| `FileChanged` | 否 | 是 | 監視的檔案被修改、建立或刪除 | 當專案檔案變更時重新載入設定 |184| `FileChanged` | 否 | 是 | 監視的檔案被修改、建立或刪除 | 當專案檔案變更時重新載入設定 |

185| `DirectoryAdded` | 否 | 是 | 會話期間新增工作目錄 | 為中途新增的儲存庫安裝相依性 |185| `DirectoryAdded` | 否 | 是 | 會話期間新增工作目錄 | 為中途新增的儲存庫安裝相依性 |

186 186

187<h2 id="configure-hooks">187<h2 id="configure-hooks">

188 配置 hooks188 設定 hook

189</h2>189</h2>

190 190

191要配置 hook，請在代理選項的 `hooks` 欄位中傳遞它（Python 中的 `ClaudeAgentOptions`，TypeScript 中的 `options` 物件）。此程式碼片段假設您已經定義了 hook 回調，例如上面範例中 Python 的 `protect_env_files` 或 TypeScript 的 `protectEnvFiles`：191要設定 hook，請在 agent 選項的 `hooks` 欄位中傳遞它（Python 中的 `ClaudeAgentOptions`，TypeScript 中的 `options` 物件）。此程式碼片段假設您已經定義了 hook 回調，例如上面範例中 Python 的 `protect_env_files` 或 TypeScript 的 `protectEnvFiles`：

192 192

193<CodeGroup>193<CodeGroup>

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

219`hooks` 選項是一個字典（Python）或物件（TypeScript），其中：219`hooks` 選項是一個字典（Python）或物件（TypeScript），其中：

220 220

221* **鍵**：[hook 事件名稱](#available-hooks)，例如 `'PreToolUse'`、`'PostToolUse'` 和 `'Stop'`221* **鍵**：[hook 事件名稱](#available-hooks)，例如 `'PreToolUse'`、`'PostToolUse'` 和 `'Stop'`

222* **值**：[匹配器](#matchers)的陣列，每個都包含可選的篩選模式和您的[回調函數](#callback-functions)222* **值**：[matcher](#matchers) 的陣列，每個都包含可選的篩選模式和您的[回調函數](#callback-functions)

223 223

224<h3 id="matchers">224<h3 id="matchers">

225 匹配器225 Matcher

226</h3>226</h3>

227 227

228使用匹配器篩選您的回調何時觸發。`matcher` 欄位根據 hook 事件類型匹配不同的值。例如，工具型 hooks 匹配工具名稱，而 `Notification` hooks 匹配通知類型。228使用 matcher 篩選您的回調何時觸發。`matcher` 欄位根據 hook 事件類型比對不同的值。例如，工具型 hook 比對工具名稱，而 `Notification` hook 比對通知類型。

229 229

230SDK 匹配器遵循與[設定檔案中的匹配器](/docs/zh-TW/hooks#matcher-patterns)相同的規則。該部分記錄了精確字串和正規表達式評估路徑、其版本要求，以及每個事件類型的匹配器值。230SDK matcher 遵循與[設定檔中的 matcher](/docs/zh-TW/hooks#matcher-patterns) 相同的規則。該部分記錄了精確字串和正規表達式評估路徑、其版本要求，以及每個事件類型的 matcher 值。

231 231

232| 選項 | 類型 | 預設值 | 描述 |232| 選項 | 類型 | 預設值 | 描述 |

233| - | - | - | - |233| - | - | - | - |

234| `matcher` | `string` | `undefined` | 針對事件的篩選欄位匹配的模式，遵循[設定檔案中匹配器的規則](/docs/zh-TW/hooks#matcher-patterns)。對於工具 hooks，這是工具名稱。內建工具包括 `Bash`、`Read`、`Write`、`Edit`、`Glob`、`Grep`、`WebFetch`、`Agent` 等（請參閱[工具輸入類型](/docs/zh-TW/agent-sdk/typescript#tool-input-types)以取得完整列表）。MCP 工具使用模式 `mcp__<server>__<action>`，其中 `<server>` 是您在 `mcpServers` 配置中使用的鍵。 |234| `matcher` | `string` | `undefined` | 針對事件的篩選欄位比對的模式，遵循[設定檔中 matcher 的規則](/docs/zh-TW/hooks#matcher-patterns)。對於工具 hook，這是工具名稱。內建工具包括 `Bash`、`Read`、`Write`、`Edit`、`Glob`、`Grep`、`WebFetch`、`Agent` 等（請參閱[工具輸入類型](/docs/zh-TW/agent-sdk/typescript#tool-input-types)以取得完整列表）。MCP 工具使用模式 `mcp__<server>__<action>`，其中 `<server>` 是您在 `mcpServers` 設定中使用的鍵。 |

237 237

238盡可能使用 `matcher` 模式來針對特定工具。帶有 `'Bash'` 的匹配器只針對 Bash 命令執行，而省略模式會針對事件的每次出現執行您的回調。故意省略它以記錄您的會話進行的每個工具呼叫。238盡可能使用 `matcher` 模式來針對特定工具。帶有 `'Bash'` 的 matcher 只針對 Bash 命令執行，而省略模式會針對事件的每次出現執行您的回調。故意省略它以記錄您的工作階段進行的每個工具呼叫。

239 239

240<h3 id="callback-functions">240<h3 id="callback-functions">

241 回調函數241 回調函數

245 輸入245 輸入

246</h4>246</h4>

247 247

248每個 hook 回調接收三個參數：248每個 hook 回調接收三個引數：

249 249

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

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

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

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

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

255 255

256<h4 id="outputs">256<h4 id="outputs">

257 輸出257 輸出

259 259

260您的回調返回一個具有兩類欄位的物件：260您的回調返回一個具有兩類欄位的物件：

261 261

262* **頂級欄位**在每個事件上被接受：`systemMessage` 向使用者顯示訊息，`continue`（Python 中的 `continue_`）決定此 hook 後代理是否繼續執行。某些事件會捨棄它們或將它們傳遞到其他地方。每個[事件的部分](/docs/zh-TW/hooks#hook-events)在 hooks 頁面上說明它們的位置。262* **頂級欄位**在每個事件上被接受：`systemMessage` 向使用者顯示訊息，`continue`（Python 中的 `continue_`）決定此 hook 後 agent 是否繼續執行。某些事件會捨棄它們或將它們傳遞到其他地方。每個[事件的部分](/docs/zh-TW/hooks#hook-events)在 hook 頁面上說明它們的位置。

263* **`hookSpecificOutput`** 控制目前操作。內部的欄位取決於 hook 事件類型：263* **`hookSpecificOutput`** 控制目前操作。內部的欄位取決於 hook 事件類型：

264 * 對於 `PreToolUse` hook，這是您設定 `permissionDecision`（`"allow"`、`"deny"`、`"ask"` 或 `"defer"`）、`permissionDecisionReason` 和 `updatedInput` 的地方。如果您返回 `"defer"`，該回合會以一則 `stop_reason` 為 `"tool_deferred"` 的結果訊息結束，以便您可以[稍後繼續該呼叫](/docs/zh-TW/hooks#defer-a-tool-call-for-later)。264 * 對於 `PreToolUse` hook，這是您設定 `permissionDecision`（`"allow"`、`"deny"`、`"ask"` 或 `"defer"`）、`permissionDecisionReason` 和 `updatedInput` 的地方。如果您返回 `"defer"`，該回合會以一則 `stop_reason` 為 `"tool_deferred"` 的結果訊息結束，以便您可以[稍後繼續該呼叫](/docs/zh-TW/hooks#defer-a-tool-call-for-later)。

265 * 對於 `PostToolUse` hook，您可以設定 `additionalContext` 以將資訊附加到工具結果。要在 Claude 看到之前替換工具的輸出，請設定 `updatedToolOutput`，這適用於兩個 SDK 中的任何工具。較舊的 `updatedMCPToolOutput` 欄位僅替換 MCP 工具輸出，已被棄用。265 * 對於 `PostToolUse` hook，您可以設定 `additionalContext` 以將資訊附加到工具結果。要在 Claude 看到之前替換工具的輸出，請設定 `updatedToolOutput`，這適用於兩個 SDK 中的任何工具。較舊的 `updatedMCPToolOutput` 欄位僅替換 MCP 工具輸出。

266 * 在 TypeScript SDK 中，`PostToolUse` 回調也可以返回 `classifierContext`，這是關於工具呼叫結果的簡短說明，用於[自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)權限分類器。因為您的回調在您應用程式自己的程序中執行，分類器可能會將您在說明中轉達的使用者陳述視為使用者意圖。該欄位需要 TypeScript Agent SDK v0.3.236 或更新版本。[為自動模式分類器註解結果](/docs/zh-TW/hooks#annotate-a-result-for-the-auto-mode-classifier)涵蓋長度上限、僅同步規則，以及不要在說明中放入的內容。266 * 在 TypeScript SDK 中，`PostToolUse` 回調也可以返回 `classifierContext`，這是關於工具呼叫結果的簡短說明，用於[自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)權限分類器。因為您的回調在您應用程式自己的程序中執行，分類器可能會將您在說明中轉達的使用者陳述視為使用者意圖。該欄位需要 TypeScript Agent SDK v0.3.236 或更新版本。[為自動模式分類器註解結果](/docs/zh-TW/hooks#annotate-a-result-for-the-auto-mode-classifier)涵蓋長度上限、僅同步規則，以及不要在說明中放入的內容。

267 267

268返回 `{}` 以允許操作而不進行變更。SDK 回調 hooks 使用與 [Claude Code shell 命令 hooks](/docs/zh-TW/hooks#json-output) 相同的 JSON 輸出格式，其記錄每個欄位和事件特定選項。對於 SDK 類型定義，請參閱 [TypeScript](/docs/zh-TW/agent-sdk/typescript#synchookjsonoutput) 和 [Python](/docs/zh-TW/agent-sdk/python#synchookjsonoutput) SDK 參考。268返回 `{}` 以允許操作而不進行變更。SDK 回調 hook 使用與 [Claude Code shell 命令 hook](/docs/zh-TW/hooks#json-output) 相同的 JSON 輸出格式，其記錄每個欄位和事件特定選項。對於 SDK 類型定義，請參閱 [TypeScript](/docs/zh-TW/agent-sdk/typescript#synchookjsonoutput) 和 [Python](/docs/zh-TW/agent-sdk/python#synchookjsonoutput) SDK 參考。

269 269

270<Note>270<Note>

271 當多個 hooks 或權限規則適用時，`deny` 優先於 `defer`，`defer` 優先於 `ask`，`ask` 優先於 `allow`。如果任何 hook 返回 `deny`，操作將被阻止，無論其他 hooks 如何。271 當多個 hook 或權限規則適用時，`deny` 優先於 `defer`，`defer` 優先於 `ask`，`ask` 優先於 `allow`。如果任何 hook 返回 `deny`，操作將被阻止，無論其他 hook 如何。

272</Note>272</Note>

273 273

274<h4 id="asynchronous-output">274<h4 id="asynchronous-output">

275 非同步輸出275 非同步輸出

276</h4>276</h4>

277 277

278預設情況下，代理在您的 hook 返回前等待。如果您的 hook 執行副作用，例如記錄或傳送 webhook，並且不需要影響代理的行為，您可以改為返回非同步輸出。這告訴代理立即繼續，無需等待 hook 完成。在此程式碼片段中，Python 中的 `send_to_logging_service` 和 TypeScript 中的 `sendToLoggingService` 代表您定義的任何記錄函數：278預設情況下，agent 在您的 hook 返回前等待。如果您的 hook 執行副作用，例如日誌記錄或傳送 webhook，並且不需要影響 agent 的行為，您可以改為返回非同步輸出。這告訴 agent 立即繼續，無需等待 hook 完成。在此程式碼片段中，Python 中的 `send_to_logging_service` 和 TypeScript 中的 `sendToLoggingService` 代表您定義的任何日誌記錄函數：

279 279

280<CodeGroup>280<CodeGroup>

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

296 296

297| 欄位 | 類型 | 描述 |297| 欄位 | 類型 | 描述 |

298| - | - | - |298| - | - | - |

301 301

302<Note>302<Note>

303 非同步輸出無法阻止、修改或將上下文注入操作，因為代理已經繼續。僅將它們用於副作用，例如記錄、指標或通知。303 非同步輸出無法阻止、修改或將上下文注入操作，因為 agent 已經繼續。僅將它們用於副作用，例如日誌記錄、指標或通知。

304</Note>304</Note>

305 305

306<h2 id="examples">306<h2 id="examples">

802</h3>802</h3>

803 803

804* 驗證 hook 事件名稱正確且區分大小寫（`PreToolUse`，而不是 `preToolUse`）804* 驗證 hook 事件名稱正確且區分大小寫（`PreToolUse`，而不是 `preToolUse`）

805* 檢查您的匹配器模式是否與工具名稱完全匹配805* 檢查您的 matcher 模式是否與工具名稱完全匹配

806* 確保 hook 在 `options.hooks` 中的正確事件類型下806* 確保 hook 在 `options.hooks` 中的正確事件類型下

807* 對於支援匹配器的非工具 hooks，如 `Notification` 和 `SubagentStop`，匹配器匹配不同的欄位，而 `Stop` 完全忽略匹配器（請參閱[匹配器模式](/docs/zh-TW/hooks#matcher-patterns)）807* 對於支援 matcher 的非工具 hook，如 `Notification` 和 `SubagentStop`，matcher 匹配不同的欄位，而 `Stop` 完全忽略 matcher（請參閱 [matcher 模式](/docs/zh-TW/hooks#matcher-patterns)）

808* 當代理達到 [`max_turns`](/docs/zh-TW/agent-sdk/python#claudeagentoptions) 限制時，hooks 可能不會觸發，因為會話在 hooks 可以執行前結束808* 當 agent 達到 [`max_turns`](/docs/zh-TW/agent-sdk/python#claudeagentoptions) 限制時，hook 可能不會觸發，因為工作階段在 hook 可以執行前結束

809 809

810<h3 id="matcher-not-filtering-as-expected">810<h3 id="matcher-not-filtering-as-expected">

811 匹配器未按預期篩選811 Matcher 未按預期篩選

812</h3>812</h3>

813 813

814匹配器只匹配工具名稱，不匹配檔案路徑或其他參數。要按檔案路徑篩選，請在您的 hook 內檢查 `tool_input.file_path`：814Matcher 只匹配工具名稱，不匹配檔案路徑或其他引數。要按檔案路徑篩選，請在您的 hook 內檢查 `tool_input.file_path`：

815 815

816```typescript theme={null}816```typescript theme={null}

817const myHook: HookCallback = async (input, toolUseID, { signal }) => {817const myHook: HookCallback = async (input, toolUseID, { signal }) => {

825```825```

826 826

827<h3 id="hook-timeout">827<h3 id="hook-timeout">

828 Hook 超時828 Hook 逾時

829</h3>829</h3>

830 830

831Claude Code 以超時時間執行每個回調，您可以在其 `HookMatcher` 上使用 `timeout` 欄位以秒為單位設定。當您未設定時，Claude Code 使用事件的預設值：大多數事件為 600 秒，`UserPromptSubmit`、`PreModelSwitch` 和 `PostModelSwitch` 為 30 秒，`MessageDisplay` 為 10 秒。Claude Code 在關閉期間執行 `SessionEnd` 回調，使用較短的 [SessionEnd 超時預算](/docs/zh-TW/hooks#sessionend-input)，預設為 1.5 秒。831Claude Code 以逾時時間執行每個回調，您可以在其 `HookMatcher` 上使用 `timeout` 欄位以秒為單位設定。當您未設定時，Claude Code 使用事件的預設值：大多數事件為 600 秒，`UserPromptSubmit`、`PreModelSwitch` 和 `PostModelSwitch` 為 30 秒，`MessageDisplay` 為 10 秒。Claude Code 在關閉期間執行 `SessionEnd` 回調，使用較短的 [SessionEnd 逾時預算](/docs/zh-TW/hooks#sessionend-input)，預設為 1.5 秒。

832 832

833當回調超過其超時時間時，Claude Code 取消它並捨棄其輸出，會話繼續而不是掛起。接下來發生的情況取決於事件：833當回調超過其逾時時間時，Claude Code 取消它並捨棄其輸出，工作階段繼續而不是掛起。接下來發生的情況取決於事件：

834 834

835* `PreToolUse`：Claude Code 不執行工具呼叫，Claude 收到工具結果，說明 hook 未在超時前回應，轉換繼續。如果另一個 `PreToolUse` hook 返回明確拒絕，Claude 改為收到該拒絕而不是超時錯誤。在 v2.1.210 之前，Claude Code 將超時報告給 Claude 作為使用者拒絕，這使無人值守會話停止並等待輸入。835* `PreToolUse`：Claude Code 不執行工具呼叫，Claude 收到工具結果，說明 hook 未在逾時前回應，回合繼續。如果另一個 `PreToolUse` hook 返回明確拒絕，Claude 改為收到該拒絕而不是逾時錯誤。在 v2.1.210 之前，Claude Code 將逾時報告給 Claude 作為使用者拒絕，這使無人值守工作階段停止並等待輸入。

836* `PostToolUse` 和 `PostToolUseFailure`：Claude Code 保留工具結果，轉換繼續。836* `PostToolUse` 和 `PostToolUseFailure`：Claude Code 保留工具結果，回合繼續。

837* `UserPromptSubmit` 和 [`UserPromptExpansion`](/docs/zh-TW/hooks#userpromptexpansion)：Claude Code 以命名 hook 和超時的訊息阻止提示，會話繼續。因為這些事件上的回調可以充當政策閘門，Claude Code 永遠不會讓超時的提示通過未篩選。在 v2.1.208 之前，當這些事件上的回調超時時，Claude Code 以 `error_during_execution` 結束查詢。837* `UserPromptSubmit` 和 [`UserPromptExpansion`](/docs/zh-TW/hooks#userpromptexpansion)：Claude Code 以指出 hook 名稱和逾時的訊息阻止提示詞，工作階段繼續。因為這些事件上的回調可以充當政策閘門，Claude Code 永遠不會讓逾時的提示詞未經篩選就通過。在 v2.1.208 之前，當這些事件上的回調逾時時，Claude Code 以 `error_during_execution` 結束查詢。

838* `Stop` 和 `SubagentStop`：超時的回調計為不返回任何決定。代理或子代理停止，如同該回調已允許它，而您其他 hooks 在事件上的決定仍然適用。在 Claude Code v2.1.273 之前，超時的 `Stop` 或 `SubagentStop` 回調計為失敗的 hook 執行，Claude Code 捨棄您其他 hooks 在事件上的決定。838* `Stop` 和 `SubagentStop`：逾時的回調計為不返回任何決定。Agent 或 subagent 停止，如同該回調已允許它，而您其他 hook 在該事件上的決定仍然適用。在 Claude Code v2.1.273 之前，逾時的 `Stop` 或 `SubagentStop` 回調計為失敗的 hook 執行，Claude Code 捨棄您其他 hook 在該事件上的決定。

839* `SessionStart`：超時的回調計為不返回任何輸出，會話繼續，使用您其他 `SessionStart` hooks 的輸出。839* `SessionStart`：逾時的回調計為不返回任何輸出，工作階段繼續，使用您其他 `SessionStart` hook 的輸出。

840* `PreModelSwitch`：Claude Code 阻止模型切換。未回答的 hook 尚未批准切換。840* `PreModelSwitch`：Claude Code 阻止模型切換。未回答的 hook 尚未核准切換。

841* 其他事件，如 `Notification`、`PreCompact` 和 `PostModelSwitch`：Claude Code 記錄失敗並繼續。841* 其他事件，如 `Notification`、`PreCompact` 和 `PostModelSwitch`：Claude Code 記錄失敗並繼續。

842 842

843主會話中 `Stop` 或 `SessionStart` 回調首次超時時，Claude Code 也會新增 [`SDKInformationalMessage`](/docs/zh-TW/agent-sdk/typescript#sdkinformationalmessage) 到訊息流，說明驅動會話的應用程式未回應。稍後的超時在您的應用程式保持無回應時不會重複該訊息。843主工作階段中 `Stop` 或 `SessionStart` 回調首次逾時時，Claude Code 也會新增 [`SDKInformationalMessage`](/docs/zh-TW/agent-sdk/typescript#sdkinformationalmessage) 到訊息流，說明驅動工作階段的應用程式未回應。稍後的逾時在您的應用程式保持無回應時不會重複該訊息。

844 844

845如果您在回調待處理時中斷查詢，Claude Code 取消待處理的工具呼叫。在 v2.1.208 之前，如果您在待處理的 `PreToolUse` 回調期間中斷，工具呼叫仍可能繼續進行。845如果您在回調待處理時中斷查詢，Claude Code 取消待處理的工具呼叫。在 v2.1.208 之前，如果您在待處理的 `PreToolUse` 回調期間中斷，工具呼叫仍可能繼續進行。

846 846

847如果您的回調需要更多時間，請在其 `HookMatcher` 上設定更高的 `timeout`。在 TypeScript 中，使用第三個回調參數中的 `AbortSignal` 以在超時觸發時優雅地處理取消。847如果您的回調需要更多時間，請在其 `HookMatcher` 上設定更高的 `timeout`。在 TypeScript 中，使用第三個回調引數中的 `AbortSignal` 以在逾時觸發時優雅地處理取消。

848 848

849<h3 id="tool-blocked-unexpectedly">849<h3 id="tool-blocked-unexpectedly">

850 工具意外被阻止850 工具意外被阻止

851</h3>851</h3>

852 852

853* 檢查所有 `PreToolUse` hooks 是否返回 `permissionDecision: 'deny'`853* 檢查所有 `PreToolUse` hook 是否返回 `permissionDecision: 'deny'`

854* 將記錄新增到您的 hooks 以查看它們返回的 `permissionDecisionReason`854* 將日誌新增到您的 hook 以查看它們返回的 `permissionDecisionReason`

855* 驗證匹配器模式不會太寬泛：空匹配器匹配所有工具855* 驗證 matcher 模式不會太寬泛：空 matcher 匹配所有工具

856 856

857<h3 id="modified-input-not-applied">857<h3 id="modified-input-not-applied">

858 修改的輸入未應用858 修改的輸入未應用

870 };870 };

871 ```871 ```

872 872

873* 不要將 `updatedInput` 與 `permissionDecision: 'defer'` 配對，這會捨棄修改的輸入。省略 `permissionDecision` 是可以的：修改的輸入仍通過正常權限評估應用。您也可以返回 `'allow'` 以自動批准修改的輸入或 `'ask'` 以向使用者顯示以供批准873* 不要將 `updatedInput` 與 `permissionDecision: 'defer'` 配對，這會捨棄修改的輸入。省略 `permissionDecision` 是可以的：修改的輸入仍通過正常權限評估應用。您也可以返回 `'allow'` 以自動核准修改的輸入或 `'ask'` 以向使用者顯示以供核准

874 874

875* 在 `hookSpecificOutput` 中包括 `hookEventName` 以識別輸出適用於哪個 hook 類型875* 在 `hookSpecificOutput` 中包括 `hookEventName` 以識別輸出適用於哪個 hook 類型

876 876

877<h3 id="session-hooks-not-available-in-python">877<h3 id="session-hooks-not-available-in-python">

878 Python 中不可用會話 hooks878 Python 中不可用工作階段 hook

879</h3>879</h3>

880 880

881`SessionStart` 和 `SessionEnd` 可以在 TypeScript 中註冊為 SDK 回調 hooks，但在 Python SDK 中不可用，因為其 `HookEvent` 類型省略它們。在 Python 中，它們僅作為[shell 命令 hooks](/docs/zh-TW/hooks#hook-events)在設定檔案中定義，例如 `.claude/settings.json`。要從您的 SDK 應用程式載入 shell 命令 hooks，請使用 [`setting_sources`](/docs/zh-TW/agent-sdk/python#settingsource) 或 [`settingSources`](/docs/zh-TW/agent-sdk/typescript#settingsource) 包括適當的設定來源：881`SessionStart` 和 `SessionEnd` 可以在 TypeScript 中註冊為 SDK 回調 hook，但在 Python SDK 中不可用，因為其 `HookEvent` 類型省略它們。在 Python 中，它們僅作為[shell 命令 hook](/docs/zh-TW/hooks#hook-events)在設定檔中定義，例如 `.claude/settings.json`。您的 SDK 應用程式載入哪些設定檔取決於 [`setting_sources`](/docs/zh-TW/agent-sdk/python#settingsource) 或 [`settingSources`](/docs/zh-TW/agent-sdk/typescript#settingsource)。如果您設定了該選項，請包括存放 hook 的來源：

882 882

883<CodeGroup>883<CodeGroup>

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

897要改為執行初始化邏輯作為 Python SDK 回調，請使用 `client.receive_response()` 的第一條訊息作為您的觸發器。897要改為執行初始化邏輯作為 Python SDK 回調，請使用 `client.receive_response()` 的第一條訊息作為您的觸發器。

898 898

899<h3 id="subagent-permission-prompts-multiplying">899<h3 id="subagent-permission-prompts-multiplying">

900 子代理權限提示倍增900 Subagent 權限提示倍增

901</h3>901</h3>

902 902

903生成多個子代理時，每個子代理可能會分別請求其自身工具呼叫的權限。要避免重複提示，請使用 `PreToolUse` hooks 自動批准特定工具，或配置權限規則，子代理[從父對話繼承](/docs/zh-TW/sub-agents#permission-modes)。903生成多個 subagent 時，每個 subagent 可能會分別請求其自身工具呼叫的權限。要避免重複提示，請使用 `PreToolUse` hook 自動核准特定工具，或設定權限規則，subagent 會[從父對話繼承](/docs/zh-TW/sub-agents#permission-modes)這些規則。

904 904

905<h3 id="recursive-hook-loops-with-subagents">905<h3 id="recursive-hook-loops-with-subagents">

906 子代理的遞迴 hook 迴圈906 Subagent 的遞迴 hook 迴圈

907</h3>907</h3>

908 908

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

910 910

911* 使用共享變數或會話狀態來追蹤您是否已在子代理內911* 使用共享變數或工作階段狀態來追蹤您是否已在 subagent 內

912* 將 hooks 範圍限制為僅針對頂級代理會話執行912* 將 hook 範圍限制為僅針對頂級 agent 工作階段執行

913 913

914<h3 id="systemmessage-not-appearing-in-output">914<h3 id="systemmessage-not-appearing-in-output">

915 systemMessage 未出現在輸出中915 systemMessage 未出現在輸出中

916</h3>916</h3>

917 917

918`systemMessage` 欄位向使用者顯示訊息，而不是模型。在 Claude Code v2.1.227 或更新版本上，hook 的 `systemMessage` 可以在訊息流中呈現為 [`SDKInformationalMessage`](/docs/zh-TW/agent-sdk/typescript#sdkinformationalmessage)。它是否呈現取決於事件。每個[事件的部分](/docs/zh-TW/hooks#hook-events)在 hooks 頁面上說明輸出如何呈現。要改為將上下文傳遞給模型，請返回 [`additionalContext`](/docs/zh-TW/hooks#add-context-for-claude)。918`systemMessage` 欄位向使用者顯示訊息，而不是模型。在 Claude Code v2.1.227 或更新版本上，hook 的 `systemMessage` 可以在訊息流中呈現為 [`SDKInformationalMessage`](/docs/zh-TW/agent-sdk/typescript#sdkinformationalmessage)。它是否呈現取決於事件。hooks 頁面上每個[事件的部分](/docs/zh-TW/hooks#hook-events)說明輸出如何呈現。要改為將上下文傳遞給模型，請返回 [`additionalContext`](/docs/zh-TW/hooks#add-context-for-claude)。

919 919

920在 v2.1.227 之前，SDK 僅針對 `SessionStart` 和 `Setup` hooks 在訊息流中呈現 hook 輸出。對於任何其他事件，輸出僅出現在 [`includeHookEvents`](/docs/zh-TW/agent-sdk/typescript#options)（Python 中的 `include_hook_events`）新增的生命週期事件中。該選項的條目涵蓋每個 hook 事件產生的生命週期事件。920在 v2.1.227 之前，SDK 僅針對 `SessionStart` 和 `Setup` hook 在訊息流中呈現 hook 輸出。對於任何其他事件，輸出僅出現在 [`includeHookEvents`](/docs/zh-TW/agent-sdk/typescript#options)（Python 中的 `include_hook_events`）新增的生命週期事件中。該選項的條目涵蓋每個 hook 事件產生的生命週期事件。

921 921

922如果您需要可靠地將 hook 決定呈現給您的應用程式，請分別記錄它們或使用專用輸出頻道。922如果您需要可靠地將 hook 決定呈現給您的應用程式，請分別記錄它們或使用專用輸出頻道。

923 923

agent-sdk/python.md +6 −5

Details

194 `ToolAnnotations`194 `ToolAnnotations`

195</h4>195</h4>

196 196

197tool 的行為提示，作為 [`tool()`](#tool) 的 `annotations` 引數傳遞。`ToolAnnotations` 擴展 MCP SDK 的 `mcp.types.ToolAnnotations`，具有 `maxResultSizeChars` 欄位，您可以用 camelCase 或 snake\_case 寫入每個提示：`ToolAnnotations(readOnlyHint=True)` 和 `ToolAnnotations(read_only_hint=True)` 是等效的。您也可以在 SDK 接受註解的任何地方傳遞純 `mcp.types.ToolAnnotations`。197tool 的行為提示，作為 [`tool()`](#tool) 的 `annotations` 引數傳遞。`ToolAnnotations` 擴展 MCP SDK 的 `mcp.types.ToolAnnotations`，具有 `maxResultSizeChars` 欄位，您可以用 camelCase 或 snake\_case 寫入每個提示：`ToolAnnotations(readOnlyHint=True)` 和 `ToolAnnotations(read_only_hint=True)` 是等效的。若要從物件讀回提示，請使用您已安裝的 `mcp` 套件所宣告的拼寫：在 `mcp` 1.x 上使用 `.readOnlyHint`，在 2.x 上使用 `.read_only_hint`，而 `.maxResultSizeChars` 在兩者上皆可使用。您也可以在 SDK 接受註解的任何地方傳遞純 `mcp.types.ToolAnnotations`。

198 198

199snake\_case 名稱和類型化的 `maxResultSizeChars` 欄位需要 Python Agent SDK 0.2.140 或更新版本。版本 0.1.31 到 0.2.139 重新匯出 `mcp.types.ToolAnnotations` 不變。在版本 0.1.55 到 0.2.139 上，您仍然可以將 `maxResultSizeChars` 作為關鍵字引數傳遞：MCP 類別接受額外欄位，SDK 將值轉發給 Claude Code。199snake\_case 名稱和類型化的 `maxResultSizeChars` 欄位需要 Python Agent SDK 0.2.140 或更新版本。版本 0.1.31 到 0.2.139 重新匯出 `mcp.types.ToolAnnotations` 不變。在版本 0.1.55 到 0.2.139 上，您仍然可以將 `maxResultSizeChars` 作為關鍵字引數傳遞：MCP 類別接受額外欄位，SDK 將值轉發給 Claude Code。

200 200

1467 1467

1468選用的 `display` 欄位控制思考文字是否傳回 `"summarized"` 或 `"omitted"`。在 Claude Opus 4.7 及更新版本上，API 預設值為 `"omitted"`，因此設定 `"summarized"` 以在 [`ThinkingBlock`](#thinkingblock) 輸出中接收思考內容。Claude Code 不會將 `display` 傳送至 Amazon Bedrock 或 Google Cloud 的 Agent Platform，因此在這些提供者上，即使您將 `display` 設定為 `"summarized"`，Opus 4.7 及更新版本也會傳回空的 `ThinkingBlock` 輸出。1468選用的 `display` 欄位控制思考文字是否傳回 `"summarized"` 或 `"omitted"`。在 Claude Opus 4.7 及更新版本上，API 預設值為 `"omitted"`，因此設定 `"summarized"` 以在 [`ThinkingBlock`](#thinkingblock) 輸出中接收思考內容。Claude Code 在傳送至部分提供者（例如 Amazon Bedrock 和 Google Cloud 的 Agent Platform）的請求中會省略 `display`。在這些提供者上，即使您將 `display` 設定為 `"summarized"`，Opus 4.7 及更新版本也會傳回空的 `ThinkingBlock` 輸出。

1469 1469

1470因為這些是 `TypedDict` 類別，它們在執行時是純字典。將它們建構為字典常值或呼叫類別作為建構函式；兩者都會產生 `dict`。使用 `config["budget_tokens"]` 存取欄位，而不是 `config.budget_tokens`：1470因為這些是 `TypedDict` 類別，它們在執行時是純字典。將它們建構為字典常值或呼叫類別作為建構函式；兩者都會產生 `dict`。使用 `config["budget_tokens"]` 存取欄位，而不是 `config.budget_tokens`：

1471 1471

1875| `maxOutputTokens` | `int` | 此模型的最大輸出令牌限制。 |1875| `maxOutputTokens` | `int` | 此模型的最大輸出令牌限制。 |

1876| `canonicalModel` | `str` | 用於定價查詢的規範模型 ID。可能與項目所鍵入的原始模型字串不同，例如提供者特定的 ID 或別名。並非總是存在。 |1876| `canonicalModel` | `str` | 用於定價查詢的規範模型 ID。可能與項目所鍵入的原始模型字串不同，例如提供者特定的 ID 或別名。並非總是存在。 |

1877| `provider` | `str` | 提供此模型的 API 提供者，例如 `firstParty`、`bedrock`、`vertex`、`foundry`、`anthropicAws`、`mantle` 或 `gateway`。並非總是存在。 |1877| `provider` | `str` | 提供此模型的 API 提供者，例如 `firstParty`、`bedrock`、`vertex`、`foundry`、`anthropicAws`、`mantle` 或 `gateway`。並非總是存在。 |

1878| `costBasis` | `str` | 為此模型最新請求定價的價格表：`list` 表示牌價，`managed` 表示 [`modelPricing`](/docs/zh-TW/settings-reference#modelpricing) 表，或當兩者皆不符合模型 ID 時為 `unknown`。並非總是存在，且未在 TypedDict 上宣告，因此使用 `.get()` 讀取它。需要 Claude Code v2.1.246 或更新版本。 |

1878 1879

1879<h3 id="streamevent">1880<h3 id="streamevent">

1880 `StreamEvent`1881 `StreamEvent`

2166 """Base error for Claude SDK."""2167 """Base error for Claude SDK."""

2167```2168```

2168 2169

2169當單次 `query()` 以錯誤結果結束時（例如轉數限制錯誤），SDK 會在產生最終結果訊息後引發 [`ResultError`](#resulterror)。Python Agent SDK 0.2.140 版本之前引發的是不屬於 `ClaudeSDKError` 子類別的純 `Exception`。2170當單次 `query()` 以錯誤結果結束時（例如轉數限制錯誤），SDK 會引發 [`ResultError`](#resulterror)。

2170 2171

2171<h3 id="clinotfounderror">2172<h3 id="clinotfounderror">

2172 `CLINotFoundError`2173 `CLINotFoundError`

2216 `ResultError`2217 `ResultError`

2217</h3>2218</h3>

2218 2219

2219當 Claude Code 程序因執行結束時出現錯誤結果（例如轉數限制錯誤或 API 錯誤）而結束時，在最終 [`ResultMessage`](#resultmessage) 之後引發。`ResultError` 是 `ProcessError` 的子類別，因此現有的 `except ProcessError` 處理程式也會捕捉它。其屬性包含該結果訊息的欄位，因此您可以根據執行失敗的原因進行分支，而無需解析訊息文字。需要 Python Agent SDK 0.2.140 或更新版本。2220當 Claude Code 程序因執行以錯誤的[結果訊息](#resultmessage)結束（例如轉數限制錯誤或 API 錯誤）而退出時引發。`ResultError` 是 `ProcessError` 的子類別，因此現有的 `except ProcessError` 處理程式也會捕捉它。其屬性包含該結果訊息的欄位，因此您可以根據執行失敗的原因進行分支，而無需解析訊息文字。需要 Python Agent SDK 0.2.140 或更新版本。

2220 2221

2221```python theme={null}2222```python theme={null}

2222class ResultError(ProcessError):2223class ResultError(ProcessError):

2649 hookEventName: Literal["PostToolUse"]2650 hookEventName: Literal["PostToolUse"]

2650 additionalContext: NotRequired[str]2651 additionalContext: NotRequired[str]

2651 updatedToolOutput: NotRequired[Any]2652 updatedToolOutput: NotRequired[Any]

2652 updatedMCPToolOutput: NotRequired[Any] # Deprecated: use updatedToolOutput, which works for all tools2653 updatedMCPToolOutput: NotRequired[Any] # MCP tools only. Prefer updatedToolOutput, which works for all tools

2653 2654

2654 2655

2655class PostToolUseFailureHookSpecificOutput(TypedDict):2656class PostToolUseFailureHookSpecificOutput(TypedDict):

agent-sdk/structured-outputs.md +2 −2

Details

60 60

61要使用結構化輸出，定義一個 [JSON Schema](https://json-schema.org/understanding-json-schema/about) 來描述您想要的資料形狀，然後通過 `outputFormat` 選項（TypeScript）或 `output_format` 選項（Python）將其傳遞給 `query()`。當代理完成時，結果訊息包含一個 `structured_output` 欄位，其中包含與您的架構相匹配的驗證資料。61要使用結構化輸出，定義一個 [JSON Schema](https://json-schema.org/understanding-json-schema/about) 來描述您想要的資料形狀，然後通過 `outputFormat` 選項（TypeScript）或 `output_format` 選項（Python）將其傳遞給 `query()`。當代理完成時，結果訊息包含一個 `structured_output` 欄位，其中包含與您的架構相匹配的驗證資料。

62 62

~~63下面的範例要求代理研究 Anthropic 並返回公司名稱、成立年份和總部作為結構化輸出。~~63在執行本頁的範例之前，請依照[快速入門](/docs/zh-TW/agent-sdk/quickstart#setup)安裝 Claude Agent SDK。下面的範例要求 agent 研究 Anthropic 並返回公司名稱、成立年份和總部作為結構化輸出。

64 64

65<CodeGroup>65<CodeGroup>

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

390 錯誤處理390 錯誤處理

391</h2>391</h2>

392 392

393結構化輸出生成可能會失敗，當代理無法生成與您的架構相匹配的有效 JSON 時。這通常發生在架構對於任務過於複雜、任務本身不明確或代理在嘗試修復驗證錯誤時達到重試限制時。它也可能在沒有任何驗證失敗的情況下發生：[模型回退](/docs/zh-TW/model-config#automatic-model-fallback)可以在中途收回已完成的輸出，如果沒有重試替換它，運行將以相同的錯誤結束。在調試您的架構之前，請檢查結果訊息上的 `errors` 清單以區分這兩個原因。393當 agent 無法生成與您的 schema 相符的有效 JSON 時，結構化輸出生成可能會失敗。這通常發生在 schema 對於任務過於複雜、任務本身不明確，或 agent 在嘗試修復驗證錯誤時達到重試限制時。它也可能在沒有任何驗證失敗的情況下發生：[模型備援](/docs/zh-TW/model-config#automatic-model-fallback)可以在串流中途收回已完成的輸出，如果沒有重試替換它，執行將以相同的錯誤結束。在對您的 schema 進行除錯之前，請檢查錯誤結果訊息上的 `errors` 清單以區分這兩個原因。

394 394

395發生錯誤時，結果訊息有一個 `subtype` 指示出了什麼問題：395發生錯誤時，結果訊息有一個 `subtype` 指示出了什麼問題：

396 396

agent-sdk/typescript.md +16 −11

Details

171```typescript theme={null}171```typescript theme={null}

172import { prewarm } from "@anthropic-ai/claude-agent-sdk";172import { prewarm } from "@anthropic-ai/claude-agent-sdk";

173 173

174// 在應用程式啟動時，在會話的資料夾已知之前174// 在應用程式啟動時，尚未得知工作階段的資料夾之前

175const spare = await prewarm({ options: { maxTurns: 3 } });175const spare = await prewarm({ options: { maxTurns: 3 } });

176 176

177// 稍後，當使用者在資料夾中啟動會話時177// 稍後，當使用者在某個資料夾中開始工作階段時

178const claimedQuery = spare.claim({178const claimedQuery = spare.claim({

179 prompt: "What files are here?",179 prompt: "What files are here?",

180 options: { cwd: "/path/to/project" },180 options: { cwd: "/path/to/project" },

181});181});

182 182

183spare.claimed.catch((error: Error) => {183spare.claimed.catch((error: Error) => {

184 // 除非消息以 "option_not_applied" 開頭，否則提示未運行：184 // 除非訊息以 "option_not_applied" 開頭，否則提示詞並未執行：

185 // 改用 query() 啟動此會話185 // 請改用 query() 啟動此工作階段

186 console.error("Claim failed:", error.message);186 console.error("Claim failed:", error.message);

187});187});

188 188

189for await (const message of claimedQuery) {189try {

190 for await (const message of claimedQuery) {

190 console.log(message);191 console.log(message);

192 }

193} catch (error) {

194 // claim 遭拒後，claimed query 會在產出錯誤結果後擲出例外

195 console.error(`Session ended with an error: ${error}`);

191}196}

192```197```

193 198

718| `reconnectMcpServer(serverName)` | 依名稱重新連線 MCP 伺服器。如果該名稱也符合 `.mcp.json` 或 `~/.claude.json` 等設定檔中的項目，Claude Code 會重新連線您透過 [`mcpServers`](#options) 或 `setMcpServers()` 設定的伺服器，而非設定檔中的項目。此解析順序需要 Claude Code v2.1.257 或更新版本 |723| `reconnectMcpServer(serverName)` | 依名稱重新連線 MCP 伺服器。如果該名稱也符合 `.mcp.json` 或 `~/.claude.json` 等設定檔中的項目，Claude Code 會重新連線您透過 [`mcpServers`](#options) 或 `setMcpServers()` 設定的伺服器，而非設定檔中的項目。此解析順序需要 Claude Code v2.1.257 或更新版本 |

719| `toggleMcpServer(serverName, enabled)` | 依名稱啟用或停用 MCP 伺服器，名稱解析方式與 `reconnectMcpServer()` 相同。停用伺服器會將其中斷連線並移除其工具。關於每種伺服器所需的 Claude Code 版本，請參閱 [`toggleMcpServer()`](#togglemcpserver) |724| `toggleMcpServer(serverName, enabled)` | 依名稱啟用或停用 MCP 伺服器，名稱解析方式與 `reconnectMcpServer()` 相同。停用伺服器會將其中斷連線並移除其工具。關於每種伺服器所需的 Claude Code 版本，請參閱 [`toggleMcpServer()`](#togglemcpserver) |

720| `setMcpServers(servers)` | 動態取代此工作階段的 MCP 伺服器集合。會以 [`McpSetServersResult`](#mcpsetserversresult) 解析，指出新增和移除了哪些伺服器，以及任何錯誤 |725| `setMcpServers(servers)` | 取代此方法所管理的 MCP 伺服器：透過它新增的伺服器以及[程序內 SDK 伺服器](#createsdkmcpserver)。會以 [`McpSetServersResult`](#mcpsetserversresult) 解析，其中指出新增和移除了哪些伺服器以及任何錯誤；該章節說明哪些其他伺服器會保持連線 |

721| `readMcpResource(serverName, uri)` | *Alpha.* 從已連線的 MCP 伺服器讀取一個 MCP Apps `ui://` 資源，讓您的應用程式能呈現工具的小工具。會以 [`SDKControlMcpReadResourceResponse`](#sdkcontrolmcpreadresourceresponse) 解析。需要 TypeScript Agent SDK v0.3.280 或更新版本 |726| `readMcpResource(serverName, uri)` | *Alpha.* 從已連線的 MCP 伺服器讀取一個 MCP Apps `ui://` 資源，讓您的應用程式能呈現工具的小工具。會以 [`SDKControlMcpReadResourceResponse`](#sdkcontrolmcpreadresourceresponse) 解析。需要 TypeScript Agent SDK v0.3.280 或更新版本 |

844 849

845`options.cwd` 為必填。認領也可以設定 `additionalDirectories`、`model`、`permissionMode`、`maxThinkingTokens`、`settings` 中的旗標設定覆蓋層、`appendSystemPrompt`、`title`、`agents`，以及 `env` 中的每個工作階段 token。850`options.cwd` 為必填。認領也可以設定 `additionalDirectories`、`model`、`permissionMode`、`maxThinkingTokens`、`settings` 中的旗標設定覆蓋層、`appendSystemPrompt`、`title`、`agents`，以及 `env` 中的每個工作階段 token。

846 851

847Claude Code 可能會拒絕認領，例如資料夾不存在，或該資料夾的專案設定設定了 `env`、`agent` 或 `model`。當 `claimed` 以開頭為 `option_not_applied` 的訊息拒絕時，工作階段正在沒有您要求的 `model` 或 `maxThinkingTokens` 的情況下執行。若為其他任何拒絕，您的提示詞都尚未執行，因此請改用 `query()` 啟動工作階段。852Claude Code 可能會拒絕認領，例如資料夾不存在，或其專案設定設定了 `env`、`agent` 或 `model`。遭拒之後，`claim()` 已傳送的提示詞會收到一個文字開頭為 `not_claimed` 的錯誤結果，之後傳回的查詢會擲出例外。請將查詢的迴圈包在 try 區塊中，以便在擲出例外後繼續。當 `claimed` 以開頭為 `option_not_applied` 的訊息拒絕時，工作階段正在沒有您所要求之 `model` 或 `maxThinkingTokens` 的情況下執行。在任何其他拒絕之後，您的提示詞都尚未執行，因此請改用 `query()` 啟動工作階段。

848 853

849<h3 id="sdkcontrolinitializeresponse">854<h3 id="sdkcontrolinitializeresponse">

850 `SDKControlInitializeResponse`855 `SDKControlInitializeResponse`

1337| `mcpServer` | `{ name: string; source: string }` | 對於 `mcp__*` 工具，提供該工具的 MCP 伺服器以及該伺服器定義的來源，欄位與 [`McpServerProvenance`](#mcpserverprovenance) 相同。其他工具則不包含此項。需要 Agent SDK v0.3.274 或更新版本 |1342| `mcpServer` | `{ name: string; source: string }` | 對於 `mcp__*` 工具，提供該工具的 MCP 伺服器以及該伺服器定義的來源，欄位與 [`McpServerProvenance`](#mcpserverprovenance) 相同。其他工具則不包含此項。需要 Agent SDK v0.3.274 或更新版本 |

5460 | { type: "disabled" }; // No extended thinking5465 | { type: "disabled" }; // No extended thinking

5461```5466```

5462 5467

5463可選的 `display` 欄位控制思考文字是否以 `"summarized"` 或 `"omitted"` 傳回。在 Claude Opus 4.7 及更新版本上，API 預設為 `"omitted"`，因此設定 `"summarized"` 以在 `thinking` 區塊中接收思考內容。Claude Code 不會將 `display` 傳送至 Amazon Bedrock 或 Google Cloud 的 Agent Platform，因此在這些提供者上，Opus 4.7 及更新版本即使在您將 `display` 設定為 `"summarized"` 時也會傳回空 `thinking` 區塊。5468可選的 `display` 欄位控制思考文字是否以 `"summarized"` 或 `"omitted"` 傳回。在 Claude Opus 4.7 及更新版本上，API 預設為 `"omitted"`，因此設定 `"summarized"` 以在 `thinking` 區塊中接收思考內容。Claude Code 在傳送至某些提供者（例如 Amazon Bedrock 和 Google Cloud 的 Agent Platform）的請求中會省略 `display`。在這些提供者上，Opus 4.7 及更新版本即使在您將 `display` 設定為 `"summarized"` 時也會傳回空 `thinking` 區塊。

5464 5469

5465<h3 id="spawnedprocess">5470<h3 id="spawnedprocess">

5466 `SpawnedProcess`5471 `SpawnedProcess`

5531 5536

5532當您呼叫 `setMcpServers()` 時，Claude Code 應用這些規則：5537當您呼叫 `setMcpServers()` 時，Claude Code 應用這些規則：

5533 5538

5534* **呼叫未命名的伺服器**：Claude Code 保持外掛提供的伺服器執行。需要 Agent SDK v0.3.210 或更新版本。5539* **呼叫未命名的伺服器**：在[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)之外，Claude Code 會中斷先前 `setMcpServers()` 呼叫所新增的伺服器以及進程內 SDK 伺服器的連線，並在 `removed` 中列出它們。其他伺服器會持續執行，且不會列在 `removed` 中，其中包括來自 [`mcpServers`](#options) 選項的 stdio、HTTP 和 SSE 伺服器、來自設定檔的伺服器，以及外掛提供的伺服器。

5535* **呼叫命名的伺服器**：除了 CLI 在啟動時啟動的內建伺服器外，Claude Code 只在其設定與您傳遞的設定不同時才替換執行中的伺服器。5540* **呼叫命名的伺服器**：對於先前 `setMcpServers()` 呼叫所新增的 stdio、HTTP 或 SSE 伺服器，Claude Code 只在其設定與您傳遞的設定不同時才替換它。已以該名稱註冊的進程內 SDK 伺服器會保持不變，因此若要替換它，請在一次呼叫中將其省略，並在下一次呼叫中新增它。

5536* **CLI 在啟動時啟動的內建伺服器**：如果呼叫命名一個，Claude Code 會捨棄該項目並在 `errors` 中報告它。5541* **CLI 在啟動時啟動的內建伺服器**：如果呼叫命名一個，Claude Code 會捨棄該項目並在 `errors` 中報告它。

5537 5542

5538承諾在新增的 stdio、HTTP 和 SSE 伺服器連線或失敗後解決，因此來自已連線伺服器的工具在下一回合可用。5543承諾在新增的 stdio、HTTP 和 SSE 伺服器連線或失敗後解決，因此來自已連線伺服器的工具在下一回合可用。

agent-view.md +1 −0

Details

819| `claude rm <id> --discard-unpushed <commit>@<worktree-id>` | 刪除因未推送提交而拒絕刪除的工作階段，捨棄 worktree 及其分支和提交。傳遞拒絕列印的確切值；請參閱 [刪除工作階段會移除什麼](#what-deleting-a-session-removes)。需要 v2.1.260 或更新版本 |819| `claude rm <id> --discard-unpushed <commit>@<worktree-id>` | 刪除因未推送提交而拒絕刪除的工作階段，捨棄 worktree 及其分支和提交。傳遞拒絕列印的確切值；請參閱 [刪除工作階段會移除什麼](#what-deleting-a-session-removes)。需要 v2.1.260 或更新版本 |

820| `claude rm <id> --force-remove-worktree <worktree-id>` | 刪除因 git 或 `WorktreeRemove` hook 無法移除其 worktree 而拒絕刪除的工作階段，無論如何刪除 worktree 目錄並在儲存庫中保留其分支。傳遞拒絕列印的確切值；請參閱 [刪除工作階段會移除什麼](#what-deleting-a-session-removes)。需要 v2.1.268 或更新版本 |820| `claude rm <id> --force-remove-worktree <worktree-id>` | 刪除因 git 或 `WorktreeRemove` hook 無法移除其 worktree 而拒絕刪除的工作階段，無論如何刪除 worktree 目錄並在儲存庫中保留其分支。傳遞拒絕列印的確切值；請參閱 [刪除工作階段會移除什麼](#what-deleting-a-session-removes)。需要 v2.1.268 或更新版本 |

822| `claude daemon logs` | 追蹤 supervisor 的日誌檔案 [`~/.claude/daemon.log`](#where-state-is-stored)，在新行出現時列印出來，直到您按下 `Ctrl+C` |

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

823 824

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

agents.md +1 −1

Details

20 20

21還有三個工具支援此工作，但它們本身不是執行代理的方式：21還有三個工具支援此工作，但它們本身不是執行代理的方式：

22 22

23* [Worktrees](/docs/zh-TW/worktrees) 為每個工作階段提供單獨的 git 簽出，因此平行工作階段永遠不會編輯相同的檔案。將它們用於您自己執行的工作階段。代理檢視會自動將每個分派的工作階段 [移動到自己的 worktree 中](/docs/zh-TW/agent-view#how-file-edits-are-isolated)，您生成的子代理也可以各自獲得一個。23* [Worktrees](/docs/zh-TW/worktrees) 為每個工作階段提供單獨的 git 簽出，因此平行工作階段各自編輯自己的檔案副本。將它們用於您自己執行的工作階段。從 agent 檢視分派的工作階段會 [在編輯檔案之前移動到自己的 worktree 中](/docs/zh-TW/agent-view#how-file-edits-are-isolated)，您生成的 subagent 也可以各自獲得一個。

24* [跨工作階段訊息傳遞](/docs/zh-TW/cross-session-messaging) 讓 Claude 列出並訊息傳遞您在此機器上、另一台機器上或 [網路上的 Claude Code](/docs/zh-TW/claude-code-on-the-web) 上的其他 Claude Code 工作階段，因此您自己執行的工作階段可以在彼此之間傳遞發現和狀態。24* [跨工作階段訊息傳遞](/docs/zh-TW/cross-session-messaging) 讓 Claude 列出並訊息傳遞您在此機器上、另一台機器上或 [網路上的 Claude Code](/docs/zh-TW/claude-code-on-the-web) 上的其他 Claude Code 工作階段，因此您自己執行的工作階段可以在彼此之間傳遞發現和狀態。

25* [`/batch`](/docs/zh-TW/commands) 是一個 [skill](/docs/zh-TW/skills)，讓 Claude 將一個大型變更分成 5 到 30 個 worktree 隔離的子代理。這是子代理和 worktrees 的打包使用，不是單獨的協調風格。25* [`/batch`](/docs/zh-TW/commands) 是一個 [skill](/docs/zh-TW/skills)，讓 Claude 將一個大型變更分成 5 到 30 個 worktree 隔離的子代理。這是子代理和 worktrees 的打包使用，不是單獨的協調風格。

26 26

amazon-bedrock.md +1 −1

Details

681 681

682Amazon Bedrock 以二進位事件串流格式串流 `InvokeModelWithResponseStream` 回應，標頭為 `Content-Type: application/vnd.amazon.eventstream`。Claude Code 和 Amazon Bedrock 之間的閘道或代理必須按照 Amazon Bedrock 傳送的方式轉發回應主體及其標頭，包括 `Content-Type`。682Amazon Bedrock 以二進位事件串流格式串流 `InvokeModelWithResponseStream` 回應，標頭為 `Content-Type: application/vnd.amazon.eventstream`。Claude Code 和 Amazon Bedrock 之間的閘道或代理必須按照 Amazon Bedrock 傳送的方式轉發回應主體及其標頭，包括 `Content-Type`。

683 683

684如果閘道將 `Content-Type` 改寫為另一個值，Claude Code 會拒絕回應，並出現以 `Bedrock streaming response has content-type` 開頭的錯誤，命名它收到的值。常見的改寫是 `text/event-stream`，來自將串流重新發出為伺服器發送事件的整合。684如果閘道將 `Content-Type` 改寫為另一個值，Claude Code 會拒絕回應，並出現以 `Bedrock streaming response has content-type` 開頭的錯誤，命名它收到的值。常見的改寫是 `text/event-stream`，來自將串流重新發出為伺服器發送事件的整合。關於錯誤訊息中提到的 `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` 變數，請參閱 [Bedrock streaming response has an unexpected content-type](/docs/zh-TW/errors#bedrock-streaming-response-has-an-unexpected-content-type)。

685 685

686如果閘道改為刪除或清空標頭，Claude Code 會假設主體是 Amazon Bedrock 的事件串流並解碼它，因此閘道未修改地傳遞的主體會繼續串流。686如果閘道改為刪除或清空標頭，Claude Code 會假設主體是 Amazon Bedrock 的事件串流並解碼它，因此閘道未修改地傳遞的主體會繼續串流。

687 687

auto-mode-config.md +1 −1

Details

351}351}

352```352```

353 353

354取得 AI 對您自訂 `allow`、`soft_deny` 和 `hard_deny` 規則的回饋：354取得 AI 對您自訂 `allow`、`soft_deny`、`hard_deny` 和 `environment` 項目的回饋：

355 355

356```bash theme={null}356```bash theme={null}

357claude auto-mode critique357claude auto-mode critique

chrome.md +1 −1

Details

343 343

344| 錯誤 | 原因 | 修復 |344| 錯誤 | 原因 | 修復 |

345| - | - | - |345| - | - | - |

346| 「瀏覽器擴充功能未連接」 | 原生訊息主機無法到達擴充功能，或您組織的 IP 允許清單拒絕了與 `bridge.claudeusercontent.com` 的連接 | 重新啟動 Chrome 和 Claude Code，然後執行 `/chrome` 以重新連接。如果您的組織使用 IP 允許清單且錯誤仍然存在，請參閱[組織 IP 允許清單與代理伺服器出口流量](/docs/zh-TW/network-config#organization-ip-allowlists-and-proxy-egress) |346| 「瀏覽器擴充功能未連接」 | 原生訊息主機無法到達擴充功能，或您組織的 IP 允許清單拒絕了與 `bridge.claudeusercontent.com` 的連接 | 檢查擴充功能是否已登入與 Claude Code 相同的 claude.ai 帳戶，重新啟動 Chrome 和 Claude Code，然後執行 `/chrome` 以重新連接。如果您的組織使用 IP 允許清單且錯誤仍然存在，請參閱[組織 IP 允許清單與代理伺服器出口流量](/docs/zh-TW/network-config#organization-ip-allowlists-and-proxy-egress) |

claude-apps-gateway.md +20 −18

Details

57 快速入門57 快速入門

58</h2>58</h2>

59 59

60此快速入門走最小路徑：在您的 IdP 中註冊 OAuth 用戶端，寫入 `gateway.yaml`，使用 Docker Compose 與 Postgres 一起執行閘道，並驗證端到端登入。它使用 Amazon Bedrock 上游；Claude Platform on AWS、Google Cloud 的 Agent Platform、Microsoft Foundry 和 Anthropic API 同樣受支援，只需如[配置參考](/docs/zh-TW/claude-apps-gateway-config#upstreams)所示交換 `upstreams` 區塊。最後，您有一個開發人員可以 `/login` 的閘道。60此快速入門走最小路徑：在您的 IdP 中註冊 OAuth 用戶端，寫入 `gateway.yaml`，使用 Docker Compose 與 Postgres 一起執行閘道，並驗證端到端登入。它使用 Amazon Bedrock 上游；Claude Platform on AWS、Google Cloud 的 Agent Platform、Microsoft Foundry 和 Anthropic API 同樣受支援，只需如[設定參考](/docs/zh-TW/claude-apps-gateway-config#upstreams)所示交換 `upstreams` 區塊。最後，您有一個開發人員可以 `/login` 的閘道。

61 61

62<Note>62<Note>

63 **在您的私有網路上部署。** Claude Code 只連接到地址為私有的閘道。這是一個安全防護，因為受信任的閘道可以推送在開發人員機器上執行命令的設定。將閘道放在內部負載平衡器或 VPN 後面，並給它一個只解析為私有 IP 的主機名。如果您的內部網路是從您的組織擁有的公開 IPv4 空間編號的，請參閱[允許閘道在您擁有的公開地址空間上](#allow-a-gateway-on-public-address-space-you-own)。63 **在您的私有網路上部署。** Claude Code 只連接到地址為私有的閘道。這是一個安全防護，因為受信任的閘道可以推送在開發人員機器上執行命令的設定。將閘道放在內部負載平衡器或 VPN 後面，並給它一個只解析為私有 IP 的主機名。如果您的內部網路是從您的組織擁有的公開 IPv4 空間編號的，請參閱[允許閘道在您擁有的公開地址空間上](#allow-a-gateway-on-public-address-space-you-own)。

73| - | - |73| - | - |

74| Claude Code v2.1.195 或更新版本 | `claude gateway` 子命令和閘道登入流程在 v2.1.195 中發布。較早的公開版本不包含它們。執行閘道伺服器的機器和每個開發人員的機器都必須是 v2.1.195 或更新版本；執行 `claude update` 以取得最新版本。[Claude Platform on AWS 上游](/docs/zh-TW/claude-apps-gateway-config#claude-platform-on-aws)在閘道伺服器上需要 Claude Code v2.1.198 或更新版本。 |74| Claude Code v2.1.195 或更新版本 | `claude gateway` 子命令和閘道登入流程在 v2.1.195 中發布。較早的公開版本不包含它們。執行閘道伺服器的機器和每個開發人員的機器都必須是 v2.1.195 或更新版本；執行 `claude update` 以取得最新版本。[Claude Platform on AWS 上游](/docs/zh-TW/claude-apps-gateway-config#claude-platform-on-aws)在閘道伺服器上需要 Claude Code v2.1.198 或更新版本。 |

75| OpenID Connect (OIDC) 身份提供商 | Okta、Microsoft Entra ID、Google Workspace、Keycloak 或 Dex，或任何其他符合 OIDC 的 IdP，例如 PingFederate。閘道針對它執行標準 OIDC 發現和授權碼流程。不支援 SAML 和 LDAP。 |75| OpenID Connect (OIDC) 身份提供商 | Okta、Microsoft Entra ID、Google Workspace、Keycloak 或 Dex，或任何其他符合 OIDC 的 IdP，例如 PingFederate。閘道針對它執行標準 OIDC 發現和授權碼流程。不支援 SAML 和 LDAP。 |

76| PostgreSQL 14 或更新版本 | 支援裝置登入流程，其中瀏覽器回呼寫入，輪詢 CLI 讀取，加上速率限制計數器。任何受管 Postgres 都可以，包括最小層級。在未配置支出限制的情況下，閘道儲存幾 KB 的短期身份驗證狀態；使用[支出限制](/docs/zh-TW/claude-apps-gateway-spend-limits)，它還持有應備份的耐久支出、稽核和身份表。建議透過 `?sslmode=require` 使用 TLS。 |76| PostgreSQL 11 或更新版本 | 支援裝置登入流程和速率限制計數器。受管 PostgreSQL 服務皆可使用，包括最小層級；請參閱[支援哪些資料庫](/docs/zh-TW/claude-apps-gateway-deploy#postgres)。使用[支出限制](/docs/zh-TW/claude-apps-gateway-spend-limits)時，它還持有應備份的耐久支出、稽核和身份表。建議透過 `?sslmode=require` 使用 TLS。PostgreSQL 11、12 和 13 在閘道伺服器上需要 Claude Code v2.1.290 或更新版本。PostgreSQL 專案已不再維護這些版本，因此請盡可能使用較新的版本。 |

~~77| 模型上游 | Amazon Bedrock 認證、Claude Platform on AWS 認證、Google Cloud 認證、Microsoft Foundry 資源或 Anthropic API 金鑰。支援多個上游和故障轉移。 |~~77| 模型上游 | Amazon Bedrock 憑證、Claude Platform on AWS 憑證、Google Cloud 憑證、Microsoft Foundry 資源或 Anthropic API 金鑰。支援多個上游和故障轉移。 |

78| HTTPS | 閘道必須可從開發人員筆記型電腦和用於登入的任何瀏覽器透過 `https://` 到達；閘道在同一監聽器上提供裝置驗證頁面。透過 `listen.tls` 提供 TLS 憑證，或在 TLS 終止入口後執行並設定 `listen.public_url` 為外部來源（兩種情況下都是如此）。純 `http://` 來源僅在閘道主機為環回時接受：`localhost`、`127.0.0.1` 或 `::1`。 |78| HTTPS | 閘道必須可從開發人員筆記型電腦和用於登入的任何瀏覽器透過 `https://` 到達；閘道在同一監聽器上提供裝置驗證頁面。透過 `listen.tls` 提供 TLS 憑證，或在 TLS 終止入口後執行，並在兩種情況下都將 `listen.public_url` 設定為外部來源。在 `/login` 處，Claude Code 僅在閘道主機為環回時接受純 `http://` 來源：`localhost`、`127.0.0.1` 或 `::1`。 |

79| 私有網路地址 | 在 `/login` 處，Claude Code 要求閘道的主機名或 IP 地址僅解析為私有地址：RFC 1918、連結本地、CGNAT `100.64.0.0/10`、IPv6 ULA `fc00::/7` 或環回。對於您託管的閘道，任何公開地址都會被拒絕；請參閱部署指南中的[威脅模型](/docs/zh-TW/claude-apps-gateway-deploy#threat-model-summary)。如果開發人員機器透過公司代理路由 HTTPS，登入還要求代理主機解析為私有地址；如果不是，將閘道主機新增到 `NO_PROXY`，以便 CLI 直接連接。如果您的內部網路是從您的組織擁有的公開 IPv4 空間編號的，[宣告這些區塊](#allow-a-gateway-on-public-address-space-you-own)，以便 `/login` 接受那裡的閘道。 |79| 私有網路地址 | 在 `/login` 處，Claude Code 要求閘道的主機名或 IP 地址僅解析為私有地址：RFC 1918、連結本地、CGNAT `100.64.0.0/10`、IPv6 ULA `fc00::/7` 或環回。對於您託管的閘道，任何位於您所宣告區塊之外的公開地址都會被拒絕；請參閱部署指南中的[威脅模型](/docs/zh-TW/claude-apps-gateway-deploy#threat-model-summary)。如果開發人員機器透過公司代理伺服器路由 HTTPS，登入還要求代理伺服器主機解析為私有地址；如果不是，將閘道主機新增到 `NO_PROXY`，以便 CLI 直接連接。如果您的內部網路是從您的組織擁有的公開 IPv4 空間編號的，[宣告這些區塊](#allow-a-gateway-on-public-address-space-you-own)，以便 `/login` 接受那裡的閘道。 |

80| Linux 執行時 | 閘道伺服器僅在原生 Linux 二進位檔上執行。macOS 適用於本地開發。Windows 不支援作為伺服器平台。 |80| Linux 執行時 | 閘道伺服器僅在原生 Linux 二進位檔上執行。macOS 適用於本地開發。Windows 不支援作為伺服器平台。 |

81 81

82<h3 id="steps">82<h3 id="steps">

89 </Step>89 </Step>

90 90

91 <Step title="佈建 PostgreSQL 資料庫">91 <Step title="佈建 PostgreSQL 資料庫">

92 任何 Postgres 14 或更新版本都可以，包括最小受管層級。閘道在啟動時執行自己的架構遷移，因此資料庫角色需要建立和更改表的權限；請參閱 [`store`](/docs/zh-TW/claude-apps-gateway-config#store)。92 使用 PostgreSQL 11 或更新版本。最小的受管層級即已足夠。閘道在啟動時執行自己的 schema 遷移，因此資料庫角色需要建立和更改表的權限；請參閱 [`store`](/docs/zh-TW/claude-apps-gateway-config#store)。

93 </Step>93 </Step>

94 94

95 <Step title="寫入 gateway.yaml">95 <Step title="寫入 gateway.yaml">

96 機密透過 `${ENV_VAR}` 擴展讀取，因此檔案本身可以存在於版本控制中。使用在您的網路上解析為私有 IP 的 `public_url` 主機名，因為 `/login` 拒絕公開地址。最小配置有五個部分，其他每個欄位都有預設值：96 機密透過 `${ENV_VAR}` 擴展讀取，因此檔案本身可以存在於版本控制中。使用在您的網路上解析為私有 IP 的 `public_url` 主機名，因為 `/login` 拒絕公開地址。最小設定有五個部分，其他每個欄位都有預設值：

97 97

98 ```yaml gateway.yaml theme={null}98 ```yaml gateway.yaml theme={null}

99 listen:99 listen:

120 upstreams:120 upstreams:

121 - provider: bedrock121 - provider: bedrock

122 region: us-east-1122 region: us-east-1

123 auth: {} # 空：AWS 預設認證鏈123 auth: {} # 空：AWS 預設憑證鏈

124 # (IRSA、EC2/ECS 任務角色、環境變數、~/.aws)124 # (IRSA、EC2/ECS 任務角色、環境變數、~/.aws)

125 125

126 # 模型會自動按上游轉換。內建目錄126 # 模型會自動按上游轉換。內建目錄

130 auto_include_builtin_models: true130 auto_include_builtin_models: true

131 ```131 ```

132 132

133 此配置足以使用預設 Amazon Bedrock 模型目錄進行有效的登入迴圈。執行後，透過 [`managed.policies`](/docs/zh-TW/claude-apps-gateway-config#managed) 新增按群組 RBAC 和受管設定、透過 [`telemetry`](/docs/zh-TW/claude-apps-gateway-config#telemetry) 的遙測扇出，以及多上游故障轉移、佈建輸送量 ARN 或非美國區域，透過 [`models`](/docs/zh-TW/claude-apps-gateway-config#models)。133 此設定足以使用預設 Amazon Bedrock 模型目錄進行有效的登入迴圈。執行後，透過 [`managed.policies`](/docs/zh-TW/claude-apps-gateway-config#managed) 新增按群組 RBAC 和受管設定、透過 [`telemetry`](/docs/zh-TW/claude-apps-gateway-config#telemetry) 的遙測扇出，以及多上游故障轉移、佈建輸送量 ARN 或非美國區域，透過 [`models`](/docs/zh-TW/claude-apps-gateway-config#models)。

134 134

135 <Note>135 <Note>

136 Amazon Bedrock 上游需要一個 AWS 主體，具有 `bedrock:InvokeModel` 和 `bedrock:InvokeModelWithResponseStream` 在 `inference-profile/us.anthropic.*` ARN 和基礎 `foundation-model/anthropic.*` ARN 上。它也需要 Anthropic 的一次性使用案例表單從 Bedrock 主控台的模型目錄提交給帳戶。136 Amazon Bedrock 上游需要一個 AWS 主體，具有 `bedrock:InvokeModel` 和 `bedrock:InvokeModelWithResponseStream` 在 `inference-profile/us.anthropic.*` ARN 和基礎 `foundation-model/anthropic.*` ARN 上。它也需要 Anthropic 的一次性使用案例表單從 Bedrock 主控台的模型目錄提交給帳戶。

137 137

138 透過 EKS 上的 IRSA、ECS 任務角色或 EC2 執行個體設定檔提供認證，而不是靜態金鑰。[`upstreams` 參考](/docs/zh-TW/claude-apps-gateway-config#upstreams)具有完整的 IAM 詳細資訊、跨雲認證矩陣和其他提供商的 `auth` 區塊。138 透過 EKS 上的 IRSA、ECS 任務角色或 EC2 執行個體設定檔提供憑證，而不是靜態金鑰。[`upstreams` 參考](/docs/zh-TW/claude-apps-gateway-config#upstreams)具有完整的 IAM 詳細資訊、跨雲憑證矩陣和其他提供商的 `auth` 區塊。

139 </Note>139 </Note>

140 </Step>140 </Step>

141 141

152 OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}152 OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}

153 GATEWAY_JWT_SECRET: ${GATEWAY_JWT_SECRET}153 GATEWAY_JWT_SECRET: ${GATEWAY_JWT_SECRET}

154 GATEWAY_POSTGRES_URL: postgres://gw:pw@postgres/gateway154 GATEWAY_POSTGRES_URL: postgres://gw:pw@postgres/gateway

155 # AWS 認證：在生產中，省略這些並使用執行個體155 # AWS 憑證：在生產中，省略這些並使用執行個體

156 # 角色。對於本地 Compose 測試，傳遞您自己的：156 # 角色。對於本地 Compose 測試，傳遞您自己的：

157 AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}157 AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}

158 AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}158 AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}

170 volumes: { pgdata: }170 volumes: { pgdata: }

171 ```171 ```

172 172

173 閘道是一個單一 Linux 二進位檔，讀取配置，連接到 Postgres 並應用其架構遷移，針對您的 IdP 執行 OIDC 發現，建立上游用戶端，並開始監聽。啟動對配置、Postgres 連接、OIDC 發現和上游用戶端構造是失敗關閉的。如果其中任何一個無法到達或配置錯誤，閘道會以錯誤退出，而不是以降級狀態提供流量。173 閘道是一個單一 Linux 二進位檔，讀取設定，連接到 Postgres 並套用其 schema 遷移，針對您的 IdP 執行 OIDC 發現，建立上游用戶端，並開始監聽。

174 174

175 成功啟動不驗證推理路徑，因為 Amazon Bedrock 和 Google Cloud 的 Agent Platform 執行個體認證在第一個請求時解析，而不是在啟動時。175 啟動對設定、Postgres 連接、OIDC 發現和上游用戶端建構是失敗關閉的。如果其中任何一個無法到達或設定錯誤，閘道會以錯誤退出，而不是以降級狀態提供流量。

176 176

177 監視 stderr 以了解啟動序列。日誌行使用格式 `[gateway] <timestamp> <level> <message>`，稽核事件是帶有 `evt` 欄位的單行 JSON，啟動橫幅（下面省略）在遷移和監聽行之間列印。新資料庫為每個架構遷移列印一個 `migration N applied` 行；已遷移的資料庫不列印任何行。您應該按順序看到：177 成功啟動不驗證推理路徑，因為 Amazon Bedrock 和 Google Cloud 的 Agent Platform 執行個體憑證在第一個請求時解析，而不是在啟動時。

178

179 監視 stderr 以了解啟動序列。日誌行使用格式 `[gateway] <timestamp> <level> <message>`，稽核事件是帶有 `evt` 欄位的單行 JSON，啟動橫幅（下面省略）在遷移和監聽行之間列印。新資料庫為每個 schema 遷移列印一個 `migration N applied` 行；已遷移的資料庫不列印任何行。您應該按順序看到：

178 180

179 ```text theme={null}181 ```text theme={null}

180 {"ts":"2026-06-10T17:03:21.114Z","evt":"config.load","path":"/etc/claude/gateway.yaml","sha256":"…"}182 {"ts":"2026-06-10T17:03:21.114Z","evt":"config.load","path":"/etc/claude/gateway.yaml","sha256":"…"}

192 * 無法到達的 Postgres194 * 無法到達的 Postgres

193 * 沒有 DDL 權限的 Postgres 角色195 * 沒有 DDL 權限的 Postgres 角色

194 * 無法到達或無效的 OIDC 發現文件196 * 無法到達或無效的 OIDC 發現文件

195 * 配置架構違規，帶有違規欄位路徑197 * 設定 schema 違規，帶有違規欄位路徑

196 198

197 修復它並重新啟動。199 修復它並重新啟動。

198 200

204 206

205 示例使用閘道的公開 URL；對於沒有入口的本地 Compose 設定，在前兩個檢查中替換 `http://localhost:8080`。第三個檢查開啟 `verification_uri_complete`，它從 `public_url` 建立，因此對於本地 Compose，在 `gateway.yaml` 中設定 `public_url: http://localhost:8080`，並在步驟 1 的 OAuth 用戶端上新增 `http://localhost:8080/oauth/callback` 作為第二個重定向 URI，因為閘道從 `public_url` 建立 IdP `redirect_uri`。驗證連結然後在您的本地瀏覽器中開啟。207 示例使用閘道的公開 URL；對於沒有入口的本地 Compose 設定，在前兩個檢查中替換 `http://localhost:8080`。第三個檢查開啟 `verification_uri_complete`，它從 `public_url` 建立，因此對於本地 Compose，在 `gateway.yaml` 中設定 `public_url: http://localhost:8080`，並在步驟 1 的 OAuth 用戶端上新增 `http://localhost:8080/oauth/callback` 作為第二個重定向 URI，因為閘道從 `public_url` 建立 IdP `redirect_uri`。驗證連結然後在您的本地瀏覽器中開啟。

206 208

207 在 Windows PowerShell 中，執行 `curl.exe`；裸 `curl` 是 `Invoke-WebRequest` 的別名，拒絕這些標誌。209 在 Windows PowerShell 中，執行 `curl.exe`；裸 `curl` 是 `Invoke-WebRequest` 的別名，拒絕這些旗標。

208 210

209 首先，獲取發現文件，確認閘道已啟動、配置有效且所有啟動檢查已通過：211 首先，取得發現文件，確認閘道已啟動、設定有效且所有啟動檢查已通過：

210 212

211 ```bash theme={null}213 ```bash theme={null}

212 curl -s https://claude-gateway.internal.example.com/.well-known/oauth-authorization-server | jq214 curl -s https://claude-gateway.internal.example.com/.well-known/oauth-authorization-server | jq

251 </Step>253 </Step>

252 254

253 <Step title="登入開發人員">255 <Step title="登入開發人員">

254 最後一步發生在開發人員機器上，而不是伺服器上。在該機器的[受管設定檔](/docs/zh-TW/managed-settings#delivery-mechanisms)中將 `forceLoginMethod` 設定為 `"gateway"` 並將 `forceLoginGatewayUrl` 設定為您的閘道的 `public_url`，然後執行 `/login`，在**雲端閘道**螢幕上按 Enter，並完成瀏覽器登入。下面的[設定閘道 URL](#set-the-gateway-url) 涵蓋大規模分發兩個金鑰。256 最後一步發生在開發人員機器上，而不是伺服器上。在該機器的[受管設定檔](/docs/zh-TW/managed-settings#delivery-mechanisms)中將 `forceLoginMethod` 設定為 `"gateway"` 並將 `forceLoginGatewayUrl` 設定為您的閘道的 `public_url`，然後執行 `/login`，在**雲端閘道**螢幕上按 Enter，並完成瀏覽器登入。下面的[設定閘道 URL](#set-the-gateway-url) 涵蓋如何將這兩個設定鍵分發到每台開發人員機器。

255 </Step>257 </Step>

256</Steps>258</Steps>

257 259

claude-apps-gateway-config.md +3 −3

Details

156閘道僅在啟動時讀取一次金鑰和憑證，因此變更的檔案僅在重新啟動後才會生效。請依照以下順序輪換，以確保沒有任何 token 請求出示 IdP 沒有的憑證：156閘道僅在啟動時讀取一次金鑰和憑證，因此變更的檔案僅在重新啟動後才會生效。請依照以下順序輪換，以確保沒有任何 token 請求出示 IdP 沒有的憑證：

157 157

1581. 將新憑證上傳到 IdP，與舊憑證並存。1581. 將新憑證上傳到 IdP，與舊憑證並存。

1592. 替換 `gateway.yaml` 載入的金鑰和憑證檔案，然後重新啟動閘道。1592. 替換 `gateway.yaml` 載入的金鑰和憑證檔案，然後重新啟動閘道。如果您執行多個副本，可以使用[滾動重新啟動](/docs/zh-TW/claude-apps-gateway-deploy#upgrades)，因為在您移除舊憑證之前，IdP 同時擁有兩個憑證。

1603. 從 IdP 移除舊憑證。1603. 在每個副本都重新啟動後，從 IdP 移除舊憑證。

161 161

162<h4 id="idp-requests-through-a-forward-proxy">162<h4 id="idp-requests-through-a-forward-proxy">

163 透過轉發代理伺服器的 IdP 請求163 透過轉發代理伺服器的 IdP 請求

225 225

226| 欄位 | 必需 | 說明 |226| 欄位 | 必需 | 說明 |

227| - | - | - |227| - | - | - |

228| `postgres_url` | 是 | `postgres://` 或 `postgresql://` URL。必需：裝置授權會合點（瀏覽器回呼寫入且輪詢 CLI 讀取）需要跨副本狀態。閘道在啟動時和升級時執行自己的 schema 遷移，因此角色需要在目標 schema 上建立和更改資料表的權限。請參閱[升級](/docs/zh-TW/claude-apps-gateway-deploy#upgrades)和 [Postgres](/docs/zh-TW/claude-apps-gateway-deploy#postgres)。 |228| `postgres_url` | 是 | 僅含一個主機的 `postgres://` 或 `postgresql://` URL，而不是以逗號分隔的清單。閘道在啟動時和升級時執行自己的 schema 遷移，因此角色需要在目標 schema 上建立和更改資料表的權限。請參閱[升級](/docs/zh-TW/claude-apps-gateway-deploy#upgrades)和 [Postgres](/docs/zh-TW/claude-apps-gateway-deploy#postgres)。 |

229| `username` | 否 | 覆寫 `postgres_url` 中的使用者 |229| `username` | 否 | 覆寫 `postgres_url` 中的使用者 |

230| `password` | 否 | 資料庫憑證。在此設定它而不是在 `postgres_url` 中，以便憑證保持在 URL 之外。接受任何字元並優先於 URL 中的憑證。 |230| `password` | 否 | 資料庫憑證。在此設定它而不是在 `postgres_url` 中，以便憑證保持在 URL 之外。接受任何字元並優先於 URL 中的憑證。 |

231| `max_connections` | 否 | 每個副本的 Postgres 連線池大小。預設 `5`，這是保守的且對共享資料庫友善。啟用[支出限制](#admin)後，熱路徑每個推論請求執行幾個操作，因此在負載下為專用資料庫提高它，並保持副本 × 此值低於資料庫的 `max_connections`。 |231| `max_connections` | 否 | 每個副本的 Postgres 連線池大小。預設 `5`，這是保守的且對共享資料庫友善。啟用[支出限制](#admin)後，熱路徑每個推論請求執行幾個操作，因此在負載下為專用資料庫提高它，並保持副本 × 此值低於資料庫的 `max_connections`。 |

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

Details

249 Postgres249 Postgres

250</h3>250</h3>

251 251

252閘道將其狀態儲存在 PostgreSQL 資料庫中：

253

254* **資料庫**：PostgreSQL 本身，自行託管或受管理皆可，需為[最低版本](/docs/zh-TW/claude-apps-gateway#prerequisites)或更新版本。僅實作 Postgres 協定的資料庫（例如分散式 SQL 資料庫）不受支援。

255* **位址**：`store.postgres_url` 接受一個主機。如果資料庫有多個節點，請使用位於它們前方的位址，例如您的受管理服務的端點、負載平衡器或虛擬 IP。設定比容錯移轉耗時更長的[就緒性寬限期](#readiness-grace-period)。

256

252閘道保持五個資料表加上 `_migrations` 表，全部由其啟動時遷移建立：257閘道保持五個資料表加上 `_migrations` 表，全部由其啟動時遷移建立：

253 258

254| 表 | 內容 | 保留 |259| 表 | 內容 | 保留 |

398| 啟動結束，顯示命名 `store.postgres_url` 的設定驗證錯誤 | 未設定 Postgres；gateway 需要 Postgres | 設定 `store.postgres_url`。對於本機開發，請使用一次性容器：`docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`。 |403| 啟動結束，顯示命名 `store.postgres_url` 的設定驗證錯誤 | 未設定 Postgres；gateway 需要 Postgres | 設定 `store.postgres_url`。對於本機開發，請使用一次性容器：`docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`。 |

404| 啟動結束：`store.postgres_url in <path> is not a URL the gateway can read`，或在 v2.1.290 之前僅顯示 `Invalid URL` 或 `URI error` | 無法剖析該 URL，例如因為它列出了多個主機，或其密碼含有未編碼的 `/`、`?`、`#` 或 `%` | 只指定[一個主機](#postgres)，並將密碼移至 [`store.password`](/docs/zh-TW/claude-apps-gateway-config#store) |

400| 啟動結束，在 `config.load` 後出現 OIDC 探索錯誤 | `oidc.issuer` 無法到達，或 TLS 鏈不受信任 | 檢查發行者是否可從 pod 到達並提供 `/.well-known/openid-configuration`。為私有 PKI 設定 `ca_cert_pem`。如果 pod 只能透過轉送代理伺服器到達 IdP，請設定 [`oidc.use_proxy: true`](/docs/zh-TW/claude-apps-gateway-config#idp-requests-through-a-forward-proxy)；在 v2.1.227 之前的版本上，改為給 pod 一條到 IdP 每個端點的直接路由。如果 pod 也無法解析 IdP 的主機名稱，或代理伺服器拒絕 `CONNECT` 到 IP 位址，請參閱[僅透過代理伺服器的出口](/docs/zh-TW/claude-apps-gateway-config#proxy-only-egress)，這需要 v2.1.277 或更新版本。 |406| 啟動結束，在 `config.load` 後出現 OIDC 探索錯誤 | `oidc.issuer` 無法到達，或 TLS 鏈不受信任 | 檢查發行者是否可從 pod 到達並提供 `/.well-known/openid-configuration`。為私有 PKI 設定 `ca_cert_pem`。如果 pod 只能透過轉送代理伺服器到達 IdP，請設定 [`oidc.use_proxy: true`](/docs/zh-TW/claude-apps-gateway-config#idp-requests-through-a-forward-proxy)；在 v2.1.227 之前的版本上，改為給 pod 一條到 IdP 每個端點的直接路由。如果 pod 也無法解析 IdP 的主機名稱，或代理伺服器拒絕 `CONNECT` 到 IP 位址，請參閱[僅透過代理伺服器的出口](/docs/zh-TW/claude-apps-gateway-config#proxy-only-egress)，這需要 v2.1.277 或更新版本。 |

402| 日誌：`could not connect to Postgres at boot, attempt 1 of 3` | 當 gateway 啟動時資料庫無法到達，例如在冷執行個體上，其網路仍在啟動中 | 如果 gateway 隨後完成啟動，則無需採取任何行動。當資料庫無法到達時，gateway 在結束前嘗試連線三次，間隔兩秒。如果它結束時顯示 `could not connect to Postgres`，請檢查 `store.postgres_url` 和到資料庫的網路路徑。如果嘗試逾時而不是被拒絕，請提高 [`store.connect_timeout_seconds`](/docs/zh-TW/claude-apps-gateway-config#store) 以給每個嘗試更長的時間。 |408| 日誌：`could not connect to Postgres at boot, attempt 1 of 3` | 當 gateway 啟動時資料庫無法到達，例如在冷執行個體上，其網路仍在啟動中 | 如果 gateway 隨後完成啟動，則無需採取任何行動。當資料庫無法到達時，gateway 在結束前嘗試連線三次，間隔兩秒。如果它結束時顯示 `could not connect to Postgres`，請檢查 `store.postgres_url`（包括確認它只指定一個主機）以及到資料庫的網路路徑。如果嘗試逾時而不是被拒絕，請提高 [`store.connect_timeout_seconds`](/docs/zh-TW/claude-apps-gateway-config#store) 以給每個嘗試更長的時間。 |

403| `/oauth/callback` 顯示「Sign-in could not be completed」 | 電子郵件網域被拒絕、id\_token 驗證失敗，或 `email_verified` 明確為 `false`，gateway 始終拒絕且無法覆寫 | 檢查 `allowed_email_domains` 以及 IdP 是否傳回已驗證的 `email` 宣告。對於 `email_verified: false`，修正 IdP 端驗證。如果您的 IdP 在不同的宣告名稱下發出電子郵件，請設定 `oidc.email_claim`。 |409| `/oauth/callback` 顯示「Sign-in could not be completed」 | 電子郵件網域被拒絕、id\_token 驗證失敗，或 `email_verified` 明確為 `false`，gateway 始終拒絕且無法覆寫 | 檢查 `allowed_email_domains` 以及 IdP 是否傳回已驗證的 `email` 宣告。對於 `email_verified: false`，修正 IdP 端驗證。如果您的 IdP 在不同的宣告名稱下發出電子郵件，請設定 `oidc.email_claim`。 |

404| 日誌：`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 token 宣告。Entra：在應用程式註冊上新增 `email` 作為選用宣告。PingFederate：啟用發出 `email` 的 OpenID Connect 原則。如果 IdP 從 userinfo 端點提供 `email` 但不會在 id\_token 中包含它，例如 Okta 組織授權伺服器，請設定 `oidc.userinfo_fallback: true`。 |410| 日誌：`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 token 宣告。Entra：在應用程式註冊上新增 `email` 作為選用宣告。PingFederate：啟用發出 `email` 的 OpenID Connect 原則。如果 IdP 從 userinfo 端點提供 `email` 但不會在 id\_token 中包含它，例如 Okta 組織授權伺服器，請設定 `oidc.userinfo_fallback: true`。 |

405| 日誌：`refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …)`，開發者每 `session.ttl_hours` 看到 `Cloud gateway session expired` | IdP 接受了重新整理 token 但沒有隨之傳回 id\_token，所以 gateway 詢問了 IdP 的 userinfo 端點以取得使用者的宣告。IdP 在那裡拒絕了重新整理的存取 token。gateway 回應 `temporarily_unavailable`，所以 Claude Code 保留重新整理 token 但無法更新工作階段。v2.1.260 之前的 gateway 版本記錄相同的行，但沒有 `(at …)` 詳細資訊。 | 設定 [`oidc.scope_on_refresh: true`](/docs/zh-TW/claude-apps-gateway-config#oidc)（在 gateway v2.1.260 或更新版本中可用），以便重新整理請求再次要求 `openid`。某些 IdP（例如 Okta）僅在被要求時才在重新整理時傳回 id\_token。在 PingFederate 上，改為在 **Applications > OAuth > OpenID Connect Policy Management** 下啟用 **Return ID Token On Refresh Grant**。該金鑰不會改變 PingFederate 的行為。對於仍然省略它的其他 IdP，檢查 userinfo 端點是否接受由重新整理發出的存取 token。作為臨時解決方案，提高 [`session.ttl_hours`](/docs/zh-TW/claude-apps-gateway-config#session)。請參閱[身分提供者設定](#identity-provider-setup)以了解取消佈建權衡。 |411| 日誌：`refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …)`，開發者每 `session.ttl_hours` 看到 `Cloud gateway session expired` | IdP 接受了重新整理 token 但沒有隨之傳回 id\_token，所以 gateway 詢問了 IdP 的 userinfo 端點以取得使用者的宣告。IdP 在那裡拒絕了重新整理的存取 token。gateway 回應 `temporarily_unavailable`，所以 Claude Code 保留重新整理 token 但無法更新工作階段。v2.1.260 之前的 gateway 版本記錄相同的行，但沒有 `(at …)` 詳細資訊。 | 設定 [`oidc.scope_on_refresh: true`](/docs/zh-TW/claude-apps-gateway-config#oidc)（在 gateway v2.1.260 或更新版本中可用），以便重新整理請求再次要求 `openid`。某些 IdP（例如 Okta）僅在被要求時才在重新整理時傳回 id\_token。在 PingFederate 上，改為在 **Applications > OAuth > OpenID Connect Policy Management** 下啟用 **Return ID Token On Refresh Grant**。該金鑰不會改變 PingFederate 的行為。對於仍然省略它的其他 IdP，檢查 userinfo 端點是否接受由重新整理發出的存取 token。作為臨時解決方案，提高 [`session.ttl_hours`](/docs/zh-TW/claude-apps-gateway-config#session)。請參閱[身分提供者設定](#identity-provider-setup)以了解取消佈建權衡。 |

claude-apps-gateway-on-aws.md +13 −11

Details

136 --policy-name bedrock-invoke --policy-document file://bedrock-invoke.json136 --policy-name bedrock-invoke --policy-document file://bedrock-invoke.json

137 ```137 ```

138 138

139 ECS 也需要執行角色，ECS 代理本身使用它從 ECR 提取映像並注入稍後建立的 Secrets Manager 值。它與 gateway 的 AWS SDK 在執行時使用的任務角色分開：139 ECS 也需要執行角色，ECS agent 本身使用它從 ECR 提取映像並注入稍後建立的 Secrets Manager 值。它與 gateway 的 AWS SDK 在執行時使用的任務角色分開：

140 140

141 ```bash theme={null}141 ```bash theme={null}

142 aws iam create-role --role-name claude-gateway-execution \142 aws iam create-role --role-name claude-gateway-execution \

169 </Step>169 </Step>

170 170

171 <Step title="佈建 Amazon RDS for PostgreSQL">171 <Step title="佈建 Amazon RDS for PostgreSQL">

172 實例在私有子網中執行，沒有公開地址，儲存加密已開啟。引擎版本固定為 Postgres 16，滿足 gateway 支援的 PostgreSQL 14 下限，並保證下面的參數群組系列與實例相符。172 實例在私有子網中執行 Postgres 16，沒有公開地址，儲存加密已開啟。

173 173

174 首先，建立將資料庫放在私有子網中的子網群組，以及具有 `rds.force_ssl=1` 的參數群組，以便伺服器拒絕純文字連接。引擎版本固定一次，因為參數群組的系列必須與實例執行的引擎主要版本相符：174 首先，建立將資料庫放在私有子網中的子網群組，以及具有 `rds.force_ssl=1` 的參數群組，以便伺服器拒絕純文字連接。引擎版本固定一次，因為參數群組的系列必須與實例執行的引擎主要版本相符：

175 175

218 </Step>218 </Step>

219 219

220 <Step title="寫入 gateway.yaml">220 <Step title="寫入 gateway.yaml">

221 `upstreams` 區塊使用 `auth: {}` 指向 Bedrock，因此 gateway 透過 ECS 上的任務角色或 EKS 上的 IRSA 角色從 AWS 預設認證鏈進行驗證。有關每個欄位，請參閱[設定參考](/docs/zh-TW/claude-apps-gateway-config)。221 `upstreams` 區塊使用 `auth: {}` 指向 Bedrock，因此 gateway 透過 ECS 上的任務角色或 EKS 上的 IRSA 角色從 AWS 預設憑證鏈進行驗證。有關每個欄位，請參閱[設定參考](/docs/zh-TW/claude-apps-gateway-config)。

222 222

223 兩個 `listen` 欄位描述什麼位於 gateway 前面：223 兩個 `listen` 欄位描述什麼位於 gateway 前面：

224 224

225 * `public_url`：外部 `https://` 來源，非環回繫結時必需；請參閱 [`listen` 參考](/docs/zh-TW/claude-apps-gateway-config#listen)。gateway 僅從此值建置 IdP `redirect_uri` 和其發現文件，絕不從 `X-Forwarded-*` 標頭建置。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 而不是負載平衡器的。226 * `trusted_proxies`：前端的來源範圍。gateway 僅當 TCP 對等體在此清單中時才接受 `X-Forwarded-For`，然後在受信任的躍點之後遍歷鏈，因此每 IP 登入速率限制和稽核事件記錄開發人員 IP 而不是負載平衡器的。

227 227

228 在兩個軌道上，前端都是內部 ALB，無論是直接建立還是由 AWS Load Balancer Controller 建立，ALB 的節點從其附加到的子網中取得地址，因此將 `trusted_proxies` 設定為這些子網的 CIDR。這信任這些子網中的每個主機作為代理。保持 ALB 的入站來源（您的公司 CIDR）不與它們重疊，並且不要與可能透過 `X-Forwarded-For` 欺騙客戶端 IP 的不受信任的工作負載共享子網。228 在兩個軌道上，前端都是內部 ALB，無論是直接建立還是由 AWS Load Balancer Controller 建立，ALB 的節點從其附加到的子網中取得地址，因此將 `trusted_proxies` 設定為這些子網的 CIDR。這信任這些子網中的每個主機作為代理伺服器。保持 ALB 的入站來源（您的公司 CIDR）不與它們重疊，並且不要與可能透過 `X-Forwarded-For` 欺騙客戶端 IP 的不受信任的工作負載共享子網。

229 229

230 ALB 的客戶端連接埠保留屬性 `routing.http.xff_client_port.enabled` 可以保持任一設定：開啟時，ALB 將客戶端寫為 `203.0.113.7:54321` 或 `[2001:db8::1]:54321`，gateway 讀取兩者並刪除連接埠。230 ALB 的客戶端連接埠保留屬性 `routing.http.xff_client_port.enabled` 可以保持任一設定：開啟時，ALB 將客戶端寫為 `203.0.113.7:54321` 或 `[2001:db8::1]:54321`，gateway 讀取兩者並刪除連接埠。

231 231

261 - provider: bedrock261 - provider: bedrock

262 region: <your-region> # 符合 $AWS_REGION 以便 IAM262 region: <your-region> # 符合 $AWS_REGION 以便 IAM

263 # 原則的 ARN 涵蓋它263 # 原則的 ARN 涵蓋它

264 auth: {} # AWS 預設認證鏈：264 auth: {} # AWS 預設憑證鏈：

265 # ECS 任務角色，或 EKS 上的 IRSA265 # ECS 任務角色，或 EKS 上的 IRSA

266 ```266 ```

267 267

288 字面 `--secret-string` 引數在每個命令執行時在程序表和稽核/EDR 日誌中可見。在共享或受監控的主機上，將值放在 `0600` 檔案中，改為傳遞 `--secret-string file://<path>`。套件的 `setup.sh` 以相同方式將機密值保持在程序 argv 之外，將 `0600` 臨時檔案傳遞給 `--cli-input-json`。288 字面 `--secret-string` 引數在每個命令執行時在程序表和稽核/EDR 日誌中可見。在共享或受監控的主機上，將值放在 `0600` 檔案中，改為傳遞 `--secret-string file://<path>`。套件的 `setup.sh` 以相同方式將機密值保持在程序 argv 之外，將 `0600` 臨時檔案傳遞給 `--cli-input-json`。

289 </Note>289 </Note>

290 290

291 與機密不同，`gateway.yaml` 本身不包含機密值，因為每個認證在啟動時透過 [`${VAR}` 或 `${file:...}` 擴展](/docs/zh-TW/claude-apps-gateway-config#secret-expansion)解析。一切如何到達容器因軌道而異：291 與機密不同，`gateway.yaml` 本身不包含機密值，因為每個憑證在啟動時透過 [`${VAR}` 或 `${file:...}` 擴展](/docs/zh-TW/claude-apps-gateway-config#secret-expansion)解析。一切如何到達容器因軌道而異：

292 292

293 * 在 ECS 上，下一步的建置將 `gateway.yaml` 複製到映像中的 `/etc/claude/gateway.yaml`，任務定義透過其 `secrets` 欄位將三個機密注入為環境變數，因此 YAML 參考 `${GATEWAY_JWT_SECRET}`、`${OIDC_CLIENT_SECRET}` 和 `${GATEWAY_POSTGRES_URL}`。293 * 在 ECS 上，下一步的建置將 `gateway.yaml` 複製到映像中的 `/etc/claude/gateway.yaml`，任務定義透過其 `secrets` 欄位將三個機密注入為環境變數，因此 YAML 參考 `${GATEWAY_JWT_SECRET}`、`${OIDC_CLIENT_SECRET}` 和 `${GATEWAY_POSTGRES_URL}`。

294 * 在 EKS 上，從 ConfigMap 掛載 `gateway.yaml` 和機密作為 `/secrets` 中的檔案，參考為 `${file:/secrets/...}`。使用 External Secrets Operator 或 Secrets Store CSI 驅動程式的 AWS 提供者從 Secrets Manager 來源 Kubernetes Secrets，或使用 `kubectl` 直接建立它們。294 * 在 EKS 上，從 ConfigMap 掛載 `gateway.yaml` 和機密作為 `/secrets` 中的檔案，參考為 `${file:/secrets/...}`。使用 External Secrets Operator 或 Secrets Store CSI 驅動程式的 AWS 提供者從 Secrets Manager 來源 Kubernetes Secrets，或使用 `kubectl` 直接建立它們。

400 400

401 新增 HTTPS 監聽器。`--ssl-policy` 固定現代 TLS 下限，因為省略它會回到舊版 `ELBSecurityPolicy-2016-08` 預設值，仍然接受 TLS 1.0/1.1。401 新增 HTTPS 監聽器。`--ssl-policy` 固定現代 TLS 下限，因為省略它會回到舊版 `ELBSecurityPolicy-2016-08` 預設值，仍然接受 TLS 1.0/1.1。

402 402

403 ALB 預設在 60 秒後沒有資料的連接關閉。gateway 的保活 ping 保持串流在該預設值內，因此提高逾時在 ping 頻率上方增加邊距；[故障排除](#troubleshooting)行關於掉落的串流涵蓋機制和較舊的 gateway。下面的命令新增監聽器並提高逾時：403 ALB 預設在 60 秒後沒有資料的連接關閉。gateway 的保活 ping 保持串流在該預設值內，因此提高逾時在 ping 頻率上方增加邊距；[疑難排解](#troubleshooting)行關於掉落的串流涵蓋機制和較舊的 gateway。下面的命令新增監聽器並提高逾時：

404 404

405 ```bash theme={null}405 ```bash theme={null}

406 aws elbv2 create-listener --load-balancer-arn "$ALB_ARN" \406 aws elbv2 create-listener --load-balancer-arn "$ALB_ARN" \

424 --load-balancers "targetGroupArn=$TG_ARN,containerName=gateway,containerPort=8080"424 --load-balancers "targetGroupArn=$TG_ARN,containerName=gateway,containerPort=8080"

425 ```425 ```

426 426

427 60 秒的寬限期給冷任務時間拉取映像、連接到儲存並在 ECS 開始計算針對部署的失敗之前回答其第一個健康檢查。目標群組在 `GET /readyz` 上的健康檢查驗證儲存是否可到達，因此無法到達 Postgres 的任務永遠不會進入輪換。為了保持任務通過短資料庫中斷（例如 RDS 容錯移轉）的健康檢查，請設定 `store.readiness_grace_seconds`，如[中斷行為](/docs/zh-TW/claude-apps-gateway-deploy#outage-behavior)所述，其中也涵蓋 `/healthz` 替代方案。427 60 秒的寬限期給冷任務時間拉取映像、連接到儲存並在 ECS 開始計算針對部署的失敗之前回答其第一個健康檢查。

428

429 目標群組在 `GET /readyz` 上的健康檢查驗證儲存是否可到達，因此無法到達 Postgres 的任務永遠不會進入輪換。為了保持任務通過短資料庫中斷（例如 RDS 容錯移轉）的健康檢查，請設定 `store.readiness_grace_seconds`，如[中斷行為](/docs/zh-TW/claude-apps-gateway-deploy#outage-behavior)所述，其中也涵蓋 `/healthz` 替代方案。

428 430

429 任務在沒有公開 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 仍然需要網際網路出站。431 任務在沒有公開 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 仍然需要網際網路出站。

430 432

436 <Tab title="EKS">438 <Tab title="EKS">

437 此軌道需要在本地安裝 `kubectl` 和 `eksctl`，以及具有 IAM OIDC 提供者和已安裝 AWS Load Balancer Controller 的現有 EKS 叢集。叢集必須在 `$VPC_ID` 上，以便 pod 可以到達 RDS 私有端點，`claude-gateway-db` 安全群組必須允許叢集的 pod 或節點安全群組而不是 `$GW_SG`。439 此軌道需要在本地安裝 `kubectl` 和 `eksctl`，以及具有 IAM OIDC 提供者和已安裝 AWS Load Balancer Controller 的現有 EKS 叢集。叢集必須在 `$VPC_ID` 上，以便 pod 可以到達 RDS 私有端點，`claude-gateway-db` 安全群組必須允許叢集的 pod 或節點安全群組而不是 `$GW_SG`。

438 440

439 在 EKS 上，gateway 透過 IRSA 而不是 ECS 角色從 Bedrock 獲得其認證。IAM 步驟中的 `ecs-tasks.amazonaws.com` 信任原則在此不適用；IRSA 需要一個信任原則在叢集的 OIDC 提供者上聯合的角色，範圍為 `system:serviceaccount:claude-gateway:gateway`。`eksctl create iamserviceaccount` 在一個步驟中建立該角色、附加原則並使用角色 ARN 註釋 Kubernetes 服務帳戶。將 IAM 步驟中的兩個原則文件轉換為它可以附加的受管原則：441 在 EKS 上，gateway 透過 IRSA 而不是 ECS 角色取得其 Bedrock 憑證。IAM 步驟中的 `ecs-tasks.amazonaws.com` 信任原則在此不適用；IRSA 需要一個信任原則在叢集的 OIDC 提供者上聯合的角色，範圍為 `system:serviceaccount:claude-gateway:gateway`。`eksctl create iamserviceaccount` 在一個步驟中建立該角色、附加原則並使用角色 ARN 註釋 Kubernetes 服務帳戶。將 IAM 步驟中的兩個原則文件轉換為它可以附加的受管原則：

440 442

441 ```bash theme={null}443 ```bash theme={null}

442 BEDROCK_POLICY_ARN="$(aws iam create-policy --policy-name claude-gateway-bedrock-invoke \444 BEDROCK_POLICY_ARN="$(aws iam create-policy --policy-name claude-gateway-bedrock-invoke \

467 * `alb.ingress.kubernetes.io/inbound-cidrs: <your-corporate-cidr>`，因此控制器管理的前端安全群組僅允許您的公司網路代替其 `0.0.0.0/0` 預設值469 * `alb.ingress.kubernetes.io/inbound-cidrs: <your-corporate-cidr>`，因此控制器管理的前端安全群組僅允許您的公司網路代替其 `0.0.0.0/0` 預設值

468 * `alb.ingress.kubernetes.io/certificate-arn` 與 ACM 憑證470 * `alb.ingress.kubernetes.io/certificate-arn` 與 ACM 憑證

469 * `alb.ingress.kubernetes.io/ssl-policy: ELBSecurityPolicy-TLS13-1-2-2021-06`，因此監聽器不會回到接受 TLS 1.0 和 1.1 的舊版預設原則471 * `alb.ingress.kubernetes.io/ssl-policy: ELBSecurityPolicy-TLS13-1-2-2021-06`，因此監聽器不會回到接受 TLS 1.0 和 1.1 的舊版預設原則

470 * `alb.ingress.kubernetes.io/load-balancer-attributes: idle_timeout.timeout_seconds=3600`，在 gateway 的串流保活上方的邊距；請參閱[故障排除](#troubleshooting)472 * `alb.ingress.kubernetes.io/load-balancer-attributes: idle_timeout.timeout_seconds=3600`，在 gateway 的串流保活上方的邊距；請參閱[疑難排解](#troubleshooting)

471 473

472 使用 IRSA，AWS SDK 讀取投影的服務帳戶權杖並與 AWS STS 交換它，因此 pod 永遠不需要 EC2 實例中繼資料服務；出站 NetworkPolicy 可能會為 gateway pod 阻止 `169.254.169.254`。下面[故障排除](#troubleshooting)中的節點躍點限制問題僅適用於跳過 IRSA 並依賴節點實例角色的叢集。474 使用 IRSA，AWS SDK 讀取投影的服務帳戶權杖並與 AWS STS 交換它，因此 pod 永遠不需要 EC2 實例中繼資料服務；出站 NetworkPolicy 可能會為 gateway pod 阻止 `169.254.169.254`。下面[疑難排解](#troubleshooting)中的節點躍點限制問題僅適用於跳過 IRSA 並依賴節點實例角色的叢集。

473 </Tab>475 </Tab>

474 </Tabs>476 </Tabs>

475 </Step>477 </Step>

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

Details

442`claude --cloud` 和 `claude --teleport` 需要使用 claude.ai 帳戶登入。如果您使用 API 金鑰進行身分驗證，或您儲存的帳戶詳細資訊已過期，您會看到以下其中一項：442`claude --cloud` 和 `claude --teleport` 需要使用 claude.ai 帳戶登入。如果您使用 API 金鑰進行身分驗證，或您儲存的帳戶詳細資訊已過期，您會看到以下其中一項：

443 443

444* `Unable to get organization UUID`444* `Unable to get organization UUID`

445* 表示 API 金鑰身分驗證不足的訊息445* ``Cloud sessions need a claude.ai sign-in. Run `claude auth login` (or /login in a local session), then try again.``

446* 在不提供工作階段 ID 的情況下執行 `claude --teleport` 時，工作階段選擇器中出現 `Error loading Claude Code sessions`446* 在不提供工作階段 ID 的情況下執行 `claude --teleport` 時，工作階段選擇器中出現 `Error loading Claude Code sessions`

447 447

448執行 `/login` 以使用您的 claude.ai 帳戶登入，然後重試命令。如果錯誤改為指出您的提供者名稱，請參閱[錯誤表](#errors-when-sending-to-a-cloud-session)：雲端工作階段無法透過第三方提供者使用。448在您的 shell 中執行 [`claude auth login`](/docs/zh-TW/cli-reference#cli-commands) 以使用您的 claude.ai 帳戶登入，然後重試命令。在執行中的工作階段內，`/login` 的作用相同。如果錯誤改為指出您的提供者名稱，請參閱[錯誤表](#errors-when-sending-to-a-cloud-session)：雲端工作階段無法透過第三方提供者使用。

449

450從 v2.1.274 到 v2.1.289，登入訊息為 `Claude Code cloud sessions require authentication with a Claude.ai account. API key authentication is not sufficient. Please run /login to authenticate, or check your authentication status with /status.`

449 451

450<h3 id="remote-control-session-expired-or-access-denied">452<h3 id="remote-control-session-expired-or-access-denied">

451 遠端控制工作階段已過期或存取被拒絕453 遠端控制工作階段已過期或存取被拒絕

claude-directory.md +3 −3

Details

34 oneLiner: 'Project instructions Claude reads every session',34 oneLiner: 'Project instructions Claude reads every session',

35 when: 'Loaded into context at the start of every session',35 when: 'Loaded into context at the start of every session',

36 description: 'Project-specific instructions that shape how Claude works in this repository. Put your conventions, common commands, and architectural context here so Claude operates with the same assumptions your team does.',36 description: 'Project-specific instructions that shape how Claude works in this repository. Put your conventions, common commands, and architectural context here so Claude operates with the same assumptions your team does.',

37 tips: ['Target under 200 lines. Longer files still load in full but may reduce adherence', <>CLAUDE.md loads into every session. If something only matters for specific tasks, move it to a <A href="/docs/en/skills">skill</A> or a path-scoped <A href="/docs/en/memory#organize-rules-with-claude/rules/">rule</A> so it loads only when needed</>, 'List the commands you run most, like build, test, and format, so Claude knows them without you spelling them out each time', <>Run <C>/memory</C> to open and edit CLAUDE.md from within a session</>, <>Also works at <C>.claude/CLAUDE.md</C> if you prefer to keep the project root clean</>, <>If your repo already has an <C>AGENTS.md</C> for other coding agents, Claude Code <A href="/docs/en/memory#agents-md">can read that</A> on its own or alongside CLAUDE.md</>],37 tips: ['Target under 200 lines. Longer files still load in full but may reduce adherence', <>CLAUDE.md loads into every session. If something only matters for specific tasks, move it to a <A href="/docs/en/skills">skill</A> or a path-scoped <A href="/docs/en/memory#organize-rules-with-claude/rules/">rule</A> so it loads only when needed</>, 'List the commands you run most, like build, test, and format, so Claude knows them without you spelling them out each time', <>Run <C>/memory</C> to open and edit CLAUDE.md from within a session</>, <>Also works at <C>.claude/CLAUDE.md</C> if you prefer to keep the project root clean</>, <>If your repo already has an <C>AGENTS.md</C> for other coding agents, Claude Code <A href="/docs/en/memory#agents-md">can read that</A> in place of a <C>CLAUDE.md</C></>],

38 exampleIntro: 'This example is for a TypeScript and React project. It lists the build and test commands, the framework conventions Claude should follow, and project-specific rules like export style and file layout.',38 exampleIntro: 'This example is for a TypeScript and React project. It lists the build and test commands, the framework conventions Claude should follow, and project-specific rules like export style and file layout.',

39 example: `# Project conventions39 example: `# Project conventions

40 40

1434 1434

1435在 Windows 上，`~/.claude` 解析為 `%USERPROFILE%\.claude`。如果您設定了 [`CLAUDE_CONFIG_DIR`](/docs/zh-TW/env-vars)，此頁面上的每個 `~/.claude` 路徑都會改為位於該目錄下。1435在 Windows 上，`~/.claude` 解析為 `%USERPROFILE%\.claude`。如果您設定了 [`CLAUDE_CONFIG_DIR`](/docs/zh-TW/env-vars)，此頁面上的每個 `~/.claude` 路徑都會改為位於該目錄下。

1436 1436

1437大多數使用者只編輯 `CLAUDE.md` 和 `settings.json`。如果您的儲存庫已經有一個 `AGENTS.md` 供其他編碼代理使用，Claude Code [可以自行讀取](/docs/zh-TW/memory#agents-md)或與 `CLAUDE.md` 一起讀取。目錄的其餘部分是可選的：根據需要新增 skills、rules 或 subagents。1437大多數使用者只編輯 `CLAUDE.md` 和 `settings.json`。如果您的儲存庫已經有一個供其他程式設計 agent 使用的 `AGENTS.md`，Claude Code [可以讀取該檔案](/docs/zh-TW/memory#agents-md)來取代 `CLAUDE.md`。目錄的其餘部分是可選的：根據需要新增 skills、rules 或 subagents。

1438 1438

1439<h2 id="explore-the-directory">1439<h2 id="explore-the-directory">

1440 探索目錄1440 探索目錄

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

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

1458| 已安裝的外掛 | `~/.claude/plugins` | 複製的市集、已安裝的外掛版本、`installed_plugins.json` 安裝記錄，以及各外掛資料，由 `claude plugin` 命令管理。從您的 claude.ai 帳戶[同步的外掛](/docs/zh-TW/plugins/loading#synced-plugins)會下載到 `~/.claude/plugins/synced/`。對於從市集[`command` 來源](/docs/zh-TW/plugins/marketplace-reference#command-plugin-source)以連結模式安裝的外掛，Claude Code 會在此儲存連結而不是副本，外掛的檔案保留在命令列印的目錄中。`command` 來源需要 Claude Code v2.1.229 或更新版本。在您從本機路徑新增的市集中以相對路徑列出的外掛，也會從其來源目錄[就地載入](/docs/zh-TW/plugins/loading#find-plugins-on-disk)，而不是從快取副本載入。請參閱[外掛快取](/docs/zh-TW/plugins/loading#find-plugins-on-disk)以了解孤立版本如何被清理。 |1458| 已安裝的外掛 | `~/.claude/plugins` | 複製的市集、已安裝的外掛版本、`installed_plugins.json` 安裝記錄，以及各外掛資料，由 `claude plugin` 命令管理。從您的 claude.ai 帳戶[同步的外掛](/docs/zh-TW/plugins/loading#synced-plugins)會下載到 `~/.claude/plugins/synced/`。對於從市集[`command` 來源](/docs/zh-TW/plugins/marketplace-reference#command-plugin-source)以連結模式安裝的外掛，Claude Code 會在此儲存連結而不是副本，外掛的檔案保留在命令列印的目錄中。`command` 來源需要 Claude Code v2.1.229 或更新版本。在您從本機路徑新增的市集中以相對路徑列出的外掛，也會從其來源目錄[就地載入](/docs/zh-TW/plugins/loading#find-plugins-on-disk)，而不是從快取副本載入。請參閱[外掛快取](/docs/zh-TW/plugins/loading#find-plugins-on-disk)以了解孤立版本如何被清理。 |

1459 1459

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

cli-reference.md +2 −0

Details

32| `claude auto-mode defaults` | 以 JSON 格式列印內建 [自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 分類器規則。使用 `claude auto-mode config` 查看應用了設定的有效設定。使用 `--label <prefix>` 僅列印標籤以該前綴開頭的規則，不區分大小寫。需要 Claude Code v2.1.208 或更新版本 | `claude auto-mode defaults --label 'Git Destructive'` |32| `claude auto-mode defaults` | 以 JSON 格式列印內建 [自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 分類器規則。使用 `claude auto-mode config` 查看應用了設定的有效設定。使用 `--label <prefix>` 僅列印標籤以該前綴開頭的規則，不區分大小寫。需要 Claude Code v2.1.208 或更新版本 | `claude auto-mode defaults --label 'Git Destructive'` |

33| `claude auto-mode reset` | 透過從使用者設定檔案中移除 `autoMode` 部分來還原預設 [自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 設定。在寫入前提示確認；傳遞 `-y`/`--yes` 以跳過提示。來自 [受管設定](/docs/zh-TW/server-managed-settings) 或 `--settings` 旗標的規則仍然適用。需要 Claude Code v2.1.212 或更新版本。請參閱 [檢查預設值和您的有效設定](/docs/zh-TW/auto-mode-config#inspect-the-defaults-and-your-effective-config) | `claude auto-mode reset --yes` |33| `claude auto-mode reset` | 透過從使用者設定檔案中移除 `autoMode` 部分來還原預設 [自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 設定。在寫入前提示確認；傳遞 `-y`/`--yes` 以跳過提示。來自 [受管設定](/docs/zh-TW/server-managed-settings) 或 `--settings` 旗標的規則仍然適用。需要 Claude Code v2.1.212 或更新版本。請參閱 [檢查預設值和您的有效設定](/docs/zh-TW/auto-mode-config#inspect-the-defaults-and-your-effective-config) | `claude auto-mode reset --yes` |

34| `claude daemon logs` | 追蹤背景工作階段 [監督程序](/docs/zh-TW/agent-view#the-supervisor-process) 的日誌檔案 `~/.claude/daemon.log`，在新行出現時將其列印出來，直到您按下 `Ctrl+C` | `claude daemon logs` |

35| `claude daemon run` | 在此終端機的前景中執行背景工作階段 [監督程序](/docs/zh-TW/agent-view#the-supervisor-process)，並列印其日誌 | `claude daemon run` |

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

context-window.md +1 −1

Details

1586 1586

1587該工作階段展示了一個現實的流程，包含代表性的權杖計數：1587該工作階段展示了一個現實的流程，包含代表性的權杖計數：

1588 1588

1589* **在您輸入任何內容之前**：CLAUDE.md、自動記憶、MCP 工具名稱和技能描述都會載入到上下文中。[AGENTS.md 檔案](/docs/zh-TW/memory#agents-md)也可以載入，無論是單獨載入還是與 CLAUDE.md 一起載入。您自己的設定可能會在此處添加更多內容，例如[輸出風格](/docs/zh-TW/output-styles)或來自 [`--append-system-prompt`](/docs/zh-TW/cli-reference) 的文字。1589* **在您輸入任何內容之前**：CLAUDE.md、自動記憶、MCP 工具名稱和 skill 描述都會載入到上下文中。[AGENTS.md 檔案](/docs/zh-TW/memory#agents-md)可以取代 CLAUDE.md 載入。您自己的設定可能會在此處添加更多內容，例如[輸出風格](/docs/zh-TW/output-styles)或來自 [`--append-system-prompt`](/docs/zh-TW/cli-reference) 的文字。

1590* **當 Claude 工作時**：每次檔案讀取都會增加上下文，[路徑範圍規則](/docs/zh-TW/memory#path-specific-rules)會自動與匹配的檔案一起載入，並且[PostToolUse hook](/docs/zh-TW/hooks-guide) 會在每次編輯後觸發。1590* **當 Claude 工作時**：每次檔案讀取都會增加上下文，[路徑範圍規則](/docs/zh-TW/memory#path-specific-rules)會自動與匹配的檔案一起載入，並且[PostToolUse hook](/docs/zh-TW/hooks-guide) 會在每次編輯後觸發。

1591* **後續提示**：[子代理](/docs/zh-TW/sub-agents)在其自己的獨立上下文視窗中處理研究，因此大型檔案讀取不會進入您的視窗。只有摘要和一個小的中繼資料預告片會返回。1591* **後續提示**：[子代理](/docs/zh-TW/sub-agents)在其自己的獨立上下文視窗中處理研究，因此大型檔案讀取不會進入您的視窗。只有摘要和一個小的中繼資料預告片會返回。

1592* **在逐步解說的最後**：您執行 `/compact`，它會將對話替換為結構化摘要。大多數啟動內容會自動重新載入；下表顯示每個機制會發生什麼。1592* **在逐步解說的最後**：您執行 `/compact`，它會將對話替換為結構化摘要。大多數啟動內容會自動重新載入；下表顯示每個機制會發生什麼。

desktop.md +1 −1

Details

1092若要查看您執行的桌面應用程式版本：1092若要查看您執行的桌面應用程式版本：

1093 1093

1094* **macOS**：點擊選單列中的 **Claude**，然後點擊 **About Claude**1094* **macOS**：點擊選單列中的 **Claude**，然後點擊 **About Claude**

1095* **Windows**：點擊 **Help**，然後點擊 **About**1095* **Windows**：點擊 **Help**，然後點擊 **About Claude**

1096 1096

1097點擊版本號以將其複製到您的剪貼簿。1097點擊版本號以將其複製到您的剪貼簿。

1098 1098

desktop-ios-simulator.md +1 −1

Details

92* 使用 **Cmd+S** 儲存螢幕擷圖或使用 **Cmd+R** 儲存螢幕錄製，使用窗格的擷取按鈕或快捷鍵；檔案會儲存到您的桌面92* 使用 **Cmd+S** 儲存螢幕擷圖或使用 **Cmd+R** 儲存螢幕錄製，使用窗格的擷取按鈕或快捷鍵；檔案會儲存到您的桌面

93* 透過按一下 **Detach simulator** 停止串流裝置而不關閉它，這會將窗格返回其 **Attach simulator** 狀態93* 透過按一下 **Detach simulator** 停止串流裝置而不關閉它，這會將窗格返回其 **Attach simulator** 狀態

94 94

95若要調整來自模擬器的影片串流，請開啟窗格的 **Display** 功能表。如果窗格對您的 Mac 造成負擔，請降低 **Frame rate** 或 **Resolution**。這兩項設定會變更窗格顯示裝置的方式，而不是應用程式的執行方式。95如果窗格顯示 **Display** 功能表，請使用它來調整來自模擬器的影片串流。如果窗格對您的 Mac 造成負擔，請降低 **Frame rate** 或 **Resolution**。這兩項設定會變更窗格顯示裝置的方式，而不是應用程式的執行方式。

96 96

97您和 Claude 驅動相同的裝置，因此您的點選會變更 Claude 看到的應用程式狀態。要讓 Claude 檢查特定螢幕，請透過點選導航到它，然後要求。當 Claude 驅動裝置時，窗格會在螢幕上方顯示 **Claude is using this device** 徽章；在徽章清除之前暫停點選，以便結果反映應用程式而不是您的輸入。97您和 Claude 驅動相同的裝置，因此您的點選會變更 Claude 看到的應用程式狀態。要讓 Claude 檢查特定螢幕，請透過點選導航到它，然後要求。當 Claude 驅動裝置時，窗格會在螢幕上方顯示 **Claude is using this device** 徽章；在徽章清除之前暫停點選，以便結果反映應用程式而不是您的輸入。

98 98

env-vars.md +1 −0

Details

354| `CLAUDE_CODE_PERFORCE_MODE` | 設為 `1` 可啟用感知 Perforce 的寫入保護。設定後，若目標檔案缺少擁有者寫入位元，Edit、Write 與 NotebookEdit 會失敗並提示 `p4 edit <file>`；Perforce 會清除已同步檔案的此位元，直到以 `p4 edit` 開啟為止。這可防止 Claude Code 繞過 Perforce 的變更追蹤 |354| `CLAUDE_CODE_PERFORCE_MODE` | 設為 `1` 可啟用感知 Perforce 的寫入保護。設定後，若目標檔案缺少擁有者寫入位元，Edit、Write 與 NotebookEdit 會失敗並提示 `p4 edit <file>`；Perforce 會清除已同步檔案的此位元，直到以 `p4 edit` 開啟為止。這可防止 Claude Code 繞過 Perforce 的變更追蹤 |

356| `CLAUDE_CODE_PLUGIN_DIRS` | 要為工作階段載入的外掛目錄，每個目錄的載入方式都與 [`--plugin-dir`](/docs/zh-TW/plugins/cli-reference#flags-that-load-a-plugin-for-one-session) 旗標相同。在 Unix 上以 `:` 分隔多個路徑，在 Windows 上以 `;` 分隔。每個路徑請使用絕對路徑或以 `~` 開頭，因為 Claude Code 會略過相對路徑。需要 Claude Code v2.1.280 或更新版本。請參閱[為單一工作階段載入外掛](/docs/zh-TW/plugins/create#load-a-directory-or-archive-for-one-session) |356| `CLAUDE_CODE_PLUGIN_DIRS` | 要為工作階段載入的外掛目錄，每個目錄的載入方式都與 [`--plugin-dir`](/docs/zh-TW/plugins/cli-reference#flags-that-load-a-plugin-for-one-session) 旗標相同。在 Unix 上以 `:` 分隔多個路徑，在 Windows 上以 `;` 分隔。每個路徑請使用絕對路徑或以 `~` 開頭，因為 Claude Code 會略過相對路徑。需要 Claude Code v2.1.280 或更新版本。請參閱[為單一工作階段載入外掛](/docs/zh-TW/plugins/create#load-a-directory-or-archive-for-one-session) |

357| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | 控制 Claude Code 是否會在 [mod](/docs/zh-TW/plugins/mods/overview) 的檔案變更時重新載入該 mod。重新載入適用於您使用 `--plugin-dir` 從目錄載入的 mod，且在互動式工作階段中預設為開啟。設定為 `1` 可同時在非互動式工作階段中開啟，設定為 `0` 則在所有工作階段中關閉。需要 Claude Code v2.1.287 或更新版本。請參閱 [mod 設定與環境變數](/docs/zh-TW/plugins/mods/reference#settings-and-environment-variables) |

357| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 複製或重新整理外掛市集的逾時時間（毫秒）（預設：120000）。對於大型儲存庫或緩慢的網路連線，請提高此值。請參閱 [Git clone timed out](/docs/zh-TW/plugins/troubleshooting#git-clone-timed-out-after-120s) |358| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 複製或重新整理外掛市集的逾時時間（毫秒）（預設：120000）。對於大型儲存庫或緩慢的網路連線，請提高此值。請參閱 [Git clone timed out](/docs/zh-TW/plugins/troubleshooting#git-clone-timed-out-after-120s) |

358| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 設為 `1` 可在市集重新整理無法連線至遠端或無法向遠端完成身分驗證時，略過重新複製的嘗試並繼續使用現有的市集 checkout。適用於重新複製也會以相同方式失敗的離線或實體隔離環境。請參閱[市集更新在離線環境中失敗](/docs/zh-TW/plugins/troubleshooting#marketplace-updates-keep-failing-offline) |359| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 設為 `1` 可在市集重新整理無法連線至遠端或無法向遠端完成身分驗證時，略過重新複製的嘗試並繼續使用現有的市集 checkout。適用於重新複製也會以相同方式失敗的離線或實體隔離環境。請參閱[市集更新在離線環境中失敗](/docs/zh-TW/plugins/troubleshooting#marketplace-updates-keep-failing-offline) |

359| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | 設為 `1` 可透過 HTTPS 而非 SSH 複製 GitHub `owner/repo` 簡寫來源。適用於外掛安裝與更新，以及 `/plugin marketplace add` 與 `update`。適用於 CI runner、容器或任何未針對 `github.com` 設定 SSH 金鑰的環境 |360| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | 設為 `1` 可透過 HTTPS 而非 SSH 複製 GitHub `owner/repo` 簡寫來源。適用於外掛安裝與更新，以及 `/plugin marketplace add` 與 `update`。適用於 CI runner、容器或任何未針對 `github.com` 設定 SSH 金鑰的環境 |

errors.md +2 −3

Details

197| `Cloud sessions cannot be created from a --restricted session` | [命令列錯誤](#cloud-sessions-cannot-be-created-from-a-restricted-session) |197| `Cloud sessions cannot be created from a --restricted session` | [命令列錯誤](#cloud-sessions-cannot-be-created-from-a-restricted-session) |

198| `Cloud sessions are disabled by your organization's policy` | [命令列錯誤](#cloud-sessions-are-disabled-by-your-organizations-policy) |198| `Cloud sessions are disabled by your organization's policy` | [命令列錯誤](#cloud-sessions-are-disabled-by-your-organizations-policy) |

199| `Couldn't verify your organization's policy for cloud sessions` | [命令列錯誤](#cloud-sessions-are-disabled-by-your-organizations-policy) |199| `Couldn't verify your organization's policy for cloud sessions` | [命令列錯誤](#cloud-sessions-are-disabled-by-your-organizations-policy) |

200| `Cloud sessions need a claude.ai sign-in` | [無法取得組織 UUID](/docs/zh-TW/claude-code-on-the-web#unable-to-get-organization-uuid) |

387* Claude Code 偵測到的連線在您的電腦進入睡眠狀態時在請求中途被中斷。Claude Code 將其計為上述規則下的連線中斷；一旦重試標籤命名了具體原因，它會讀作 `Connection lost while your computer was asleep`，如果回合在 Claude 完成思考但在任何文字或工具呼叫之前結束，訊息會讀作 `Your computer went to sleep before a response was produced`。388* Claude Code 偵測到的連線在您的電腦進入睡眠狀態時在請求中途被中斷。Claude Code 將其計為上述規則下的連線中斷；一旦重試標籤命名了具體原因，它會讀作 `Connection lost while your computer was asleep`，如果回合在 Claude 完成思考但在任何文字或工具呼叫之前結束，訊息會讀作 `Your computer went to sleep before a response was produced`。

388* 停滯的回應串流，當回應標頭已到達但 Claude 回應的任何部分都未到達，或當 Claude 完成思考但尚未開始任何文字或工具呼叫時：Claude Code 會中止停滯的連線，並最多重新發出一次請求，不在上述 10 次嘗試預算內。如果在 Claude 完成思考但在任何文字或工具呼叫之前回應停滯第二次，Claude Code 會以 `The response stalled before a response was produced` 結束回合。389* 停滯的回應串流，當回應標頭已到達但 Claude 回應的任何部分都未到達，或當 Claude 完成思考但尚未開始任何文字或工具呼叫時：Claude Code 會中止停滯的連線，並最多重新發出一次請求，不在上述 10 次嘗試預算內。如果在 Claude 完成思考但在任何文字或工具呼叫之前回應停滯第二次，Claude Code 會以 `The response stalled before a response was produced` 結束回合。

389* 串流請求 API 從未以回應標頭回答，在 [first-byte deadline 執行](/docs/zh-TW/network-config#streaming-idle-watchdogs) 的連線上：Claude Code 在截止時間中止它，並在重試預算內最多每個模型請求重新發送一次，然後如果該嘗試也未獲得回答，則以 [No response from API](#no-response-from-api) 結束回合。在其他連線上，請求會等待 `API_TIMEOUT_MS`。當您設定 `CLAUDE_CODE_RETRY_WATCHDOG` 時，一次重試上限不適用。390* 串流請求 API 從未以回應標頭回答，在 [first-byte deadline 執行](/docs/zh-TW/network-config#streaming-idle-watchdogs) 的連線上：Claude Code 在截止時間中止它，並在重試預算內最多每個模型請求重新發送一次，然後如果該嘗試也未獲得回答，則以 [No response from API](#no-response-from-api) 結束回合。在其他連線上，請求會等待 `API_TIMEOUT_MS`。當您設定 `CLAUDE_CODE_RETRY_WATCHDOG` 時，一次重試上限不適用。

391* 在 Claude 完成思考或開始任何文字或工具呼叫之前，被 API 輸出內容過濾器停止的串流回應。Claude Code 會在重試預算內重新發送請求一次，如果過濾器也停止了第二個回應，則顯示 [Output blocked by content filtering policy](#output-blocked-by-content-filtering-policy)。

390* 暫時性 429 節流，但不是閘道的支出限制 `429`，這不是節流；請參閱 [Spend limit reached](#spend-limit-reached)。392* 暫時性 429 節流，但不是閘道的支出限制 `429`，這不是節流；請參閱 [Spend limit reached](#spend-limit-reached)。

391 * 當您使用 claude.ai 訂閱登入時，這包括不帶有您方案配額標頭的 429 節流。在 v2.1.199 之前，Claude Code 僅針對 API 金鑰和 Enterprise 登入重試這些節流。393 * 當您使用 claude.ai 訂閱登入時，這包括不帶有您方案配額標頭的 429 節流。在 v2.1.199 之前，Claude Code 僅針對 API 金鑰和 Enterprise 登入重試這些節流。

392* 因為輸入加上 `max_tokens` 超過上下文限制而被拒絕的請求。以相同方式重新發送它會以相同方式失敗，所以 Claude Code 會以縮減的 `max_tokens` 重試，並在兩種情況下停止重試並改為壓縮：394* 因為輸入加上 `max_tokens` 超過上下文限制而被拒絕的請求。以相同方式重新發送它會以相同方式失敗，所以 Claude Code 會以縮減的 `max_tokens` 重試，並在兩種情況下停止重試並改為壓縮：

405* [Amazon Bedrock 串流回應具有意外的 content-type](#bedrock-streaming-response-has-an-unexpected-content-type)，因為重寫回應的閘道或代理伺服器會以相同方式重寫重試。需要 Claude Code v2.1.208 或更新版本。407* [Amazon Bedrock 串流回應具有意外的 content-type](#bedrock-streaming-response-has-an-unexpected-content-type)，因為重寫回應的閘道或代理伺服器會以相同方式重寫重試。需要 Claude Code v2.1.208 或更新版本。

406* 失敗的串流請求的非串流重試獲得成功狀態但 [body 中沒有 Claude API 訊息](#api-returned-an-empty-or-malformed-response)。Claude Code 以該錯誤結束回合。408* 失敗的串流請求的非串流重試獲得成功狀態但 [body 中沒有 Claude API 訊息](#api-returned-an-empty-or-malformed-response)。Claude Code 以該錯誤結束回合。

407* 您的組織的原則檢查拒絕的請求，其表現為帶有拒絕訊息的 `API Error:` 行。您的組織管理員使用 [Inference hooks](https://platform.claude.com/docs/en/manage-claude/inference-hooks)（Claude Enterprise 功能）設定檢查，訊息以他們設定的指示結尾，或預設告訴您聯絡他們。Claude Code 不會將被拒絕的請求重新發送到相同的模型或 [備援模型](/docs/zh-TW/model-config#fallback-model-chains)，因為拒絕是關於請求的內容而不是模型。在 v2.1.239 之前，Claude Code 可能會在向您顯示拒絕之前，以非串流方式或在設定的備援模型上重新發送被拒絕的請求。409* 您的組織的原則檢查拒絕的請求，其表現為帶有拒絕訊息的 `API Error:` 行。您的組織管理員使用 [Inference hooks](https://platform.claude.com/docs/en/manage-claude/inference-hooks)（Claude Enterprise 功能）設定檢查，訊息以他們設定的指示結尾，或預設告訴您聯絡他們。Claude Code 不會將被拒絕的請求重新發送到相同的模型或 [備援模型](/docs/zh-TW/model-config#fallback-model-chains)，因為拒絕是關於請求的內容而不是模型。在 v2.1.239 之前，Claude Code 可能會在向您顯示拒絕之前，以非串流方式或在設定的備援模型上重新發送被拒絕的請求。

408* 被 API 輸出內容過濾器封鎖的回應。Claude Code 會立即顯示 [Output blocked by content filtering policy](#output-blocked-by-content-filtering-policy)，且不會重試或重新發送該請求。

409 410

410<h3 id="what-you-see-while-claude-code-retries-or-waits">411<h3 id="what-you-see-while-claude-code-retries-or-waits">

411 當 Claude Code 重試或等待時您看到的內容412 當 Claude Code 重試或等待時您看到的內容

2905API Error: Output blocked by content filtering policy2906API Error: Output blocked by content filtering policy

2906```2907```

2907 2908

2908Claude Code 會在封鎖抵達時立即顯示錯誤，並在此結束請求。它不會重試請求、以非串流方式重新發送，或切換到[備援模型](/docs/zh-TW/model-config#fallback-model-chains)。在 v2.1.285 之前，Claude Code 可能會重新發送並重試被封鎖的請求，有時長達數分鐘，才向您顯示錯誤。

~~2909~~

2910**該怎麼辦：**2909**該怎麼辦：**

2911 2910

2912* 重新措辭您的最後一則訊息，或採取不同的方法2911* 重新措辭您的最後一則訊息，或採取不同的方法

glossary.md +1 −1

Details

130 130

131您為 Claude 撰寫的持久指示的 markdown 檔案，在每個工作階段開始時作為系統提示之後的使用者訊息載入。將專案慣例、架構筆記和「始終執行 X」規則放在此處。專案根目錄 CLAUDE.md 在[壓縮](#compaction)後保留，並在之後從磁碟重新讀取。131您為 Claude 撰寫的持久指示的 markdown 檔案，在每個工作階段開始時作為系統提示之後的使用者訊息載入。將專案慣例、架構筆記和「始終執行 X」規則放在此處。專案根目錄 CLAUDE.md 在[壓縮](#compaction)後保留，並在之後從磁碟重新讀取。

132 132

133您可以在專案範圍的 `./CLAUDE.md` 或 `./.claude/CLAUDE.md`、使用者範圍的 `~/.claude/CLAUDE.md` 或作為組織的[受管原則](#managed-settings)放置 CLAUDE.md。所有發現的檔案都會連接到內容中，而不是相互覆蓋，順序從最廣泛的範圍到最具體的範圍。Claude Code 也可以載入專案的 [AGENTS.md](#agents-md) 檔案，單獨或與 CLAUDE.md 一起。133您可以在專案範圍的 `./CLAUDE.md` 或 `./.claude/CLAUDE.md`、使用者範圍的 `~/.claude/CLAUDE.md` 或作為組織的[受管原則](#managed-settings)放置 CLAUDE.md。所有發現的檔案都會連接到上下文中，而不是相互覆蓋，順序從最廣泛的範圍到最具體的範圍。Claude Code 也可以載入專案的 [AGENTS.md](#agents-md) 檔案來取代 CLAUDE.md。

134 134

135深入瞭解：[CLAUDE.md files](/docs/zh-TW/memory#claude-md-files)135深入瞭解：[CLAUDE.md files](/docs/zh-TW/memory#claude-md-files)

136 136

google-vertex-ai.md +2 −2

Details

210export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1210export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1

211```211```

212 212

213大多數模型版本都有對應的 `VERTEX_REGION_CLAUDE_*` 變數。請參閱[環境變數參考](/docs/zh-TW/env-vars)以取得完整清單。檢查 [Google Cloud 的 Agent Platform Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) 以判斷哪些模型支援全域端點與僅限區域端點。213大多數模型版本都有對應的 `VERTEX_REGION_CLAUDE_*` 變數。請參閱[環境變數參考](/docs/zh-TW/env-vars#variables)以取得完整清單。檢查 [Google Cloud 的 Agent Platform Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) 以判斷哪些模型支援全域端點與僅限區域端點。

214 214

215如果區域值的格式不像區域或位置名稱，Claude Code 會將其視為未設定。例如，Claude Code 會將包含斜線、點或空格的值視為未設定。Claude Code 會針對每個變數回退到不同的來源：215如果區域值的格式不像區域或位置名稱，Claude Code 會將其視為未設定。例如，Claude Code 會將包含斜線、點或空格的值視為未設定。Claude Code 會針對每個變數回退到不同的來源：

216 216

366* 驗證模型在您指定的位置中可用。某些模型僅在 `global` 或多區域位置（例如 `eu` 和 `us`）上提供，不在特定區域中366* 驗證模型在您指定的位置中可用。某些模型僅在 `global` 或多區域位置（例如 `eu` 和 `us`）上提供，不在特定區域中

367* 如果使用 `CLOUD_ML_REGION=global`，請檢查您的模型是否在 [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) 中的「支援的功能」下支援全球端點。對於不支援全球端點的模型，請執行下列其中一項：367* 如果使用 `CLOUD_ML_REGION=global`，請檢查您的模型是否在 [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) 中的「支援的功能」下支援全球端點。對於不支援全球端點的模型，請執行下列其中一項：

368 * 透過 `ANTHROPIC_MODEL` 或 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 指定支援的模型，或368 * 透過 `ANTHROPIC_MODEL` 或 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 指定支援的模型，或

369 * 使用 `VERTEX_REGION_<MODEL_NAME>` 環境變數設定區域或多區域位置369 * 使用該模型的 `VERTEX_REGION_CLAUDE_*` 變數設定區域或多區域位置，這些變數列於[環境變數參考](/docs/zh-TW/env-vars#variables)中

370 370

371如果您遇到 429 錯誤：371如果您遇到 429 錯誤：

372 372

hooks.md +4 −5

Details

63| `DirectoryAdded` | 當工作目錄在工作階段中期透過 `/add-dir` 或 SDK `register_repo_root` 控制請求新增時 |63| `DirectoryAdded` | 當工作目錄在工作階段中期透過 `/add-dir` 或 SDK `register_repo_root` 控制請求新增時 |

64| `FileChanged` | 當監視的檔案在磁碟上變更時。`matcher` 欄位指定要監視的檔案名稱 |64| `FileChanged` | 當監視的檔案在磁碟上變更時。`matcher` 欄位指定要監視的檔案名稱 |

65| `WorktreeCreate` | 當透過 `--worktree`、`isolation: "worktree"` 建立 worktree 時，或用於背景工作階段時。取代預設的 git 行為 |65| `WorktreeCreate` | 當透過 `--worktree`、`isolation: "worktree"` 建立 worktree 時，或用於背景工作階段時。取代預設的 git 行為 |

67| `PreCompact` | 在上下文壓縮之前 |67| `PreCompact` | 在上下文壓縮之前 |

68| `PostCompact` | 在上下文壓縮完成後 |68| `PostCompact` | 在上下文壓縮完成後 |

69| `PreModelSwitch` | 在 Claude Code 應用您或用戶端要求的模型切換之前。可以阻止切換 |69| `PreModelSwitch` | 在 Claude Code 應用您或用戶端要求的模型切換之前。可以阻止切換 |

3273 WorktreeRemove3273 WorktreeRemove

3274</h3>3274</h3>

3275 3275

3276在移除 worktree 時執行。這是 [WorktreeCreate](#worktreecreate) 對應的清理事件。此事件會在以下情況觸發：3276當 Claude Code 清理由您的 [`WorktreeCreate`](#worktreecreate) hook 所建立的 worktree 時執行。此事件在以下情況觸發：

3277 3277

3278* 您結束 `--worktree` 工作階段並選擇移除它3278* 您結束 `--worktree` 工作階段並選擇移除 worktree

3279* 具有 `isolation: "worktree"` 的 subagent 完成3279* 您刪除在該 worktree 中執行的[背景工作階段](/docs/zh-TW/agent-view#what-deleting-a-session-removes)

3280* 您刪除一個其 worktree 由 hook 建立的[背景工作階段](/docs/zh-TW/agent-view#what-deleting-a-session-removes)

3281 3280

3282對於基於 git 的 worktree，Claude Code 會透過 `git worktree remove` 自動處理清理。如果您設定了 WorktreeCreate hook，請搭配 WorktreeRemove hook 來控制其所建立 worktree 的清理：3281對於基於 git 的 worktree，Claude Code 會透過 `git worktree remove` 自動處理清理。如果您設定了 WorktreeCreate hook，請搭配 WorktreeRemove hook 來控制其所建立 worktree 的清理：

3283 3282

hooks-guide.md +1 −1

Details

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

Details

76* **您的專案。** 您目錄和子目錄中的檔案，以及其他地方經您許可的檔案。76* **您的專案。** 您目錄和子目錄中的檔案，以及其他地方經您許可的檔案。

77* **您的終端機。** 您可以執行的任何命令：建置工具、git、套件管理器、系統公用程式、指令碼。如果您可以從命令列執行，Claude 也可以。77* **您的終端機。** 您可以執行的任何命令：建置工具、git、套件管理器、系統公用程式、指令碼。如果您可以從命令列執行，Claude 也可以。

78* **您的 git 狀態。** 目前分支、未提交的變更和最近的提交歷史。78* **您的 git 狀態。** 目前分支、未提交的變更和最近的提交歷史。

79* **您的 [CLAUDE.md](/docs/zh-TW/memory)。** 一個 markdown 檔案，您可以在其中儲存專案特定的指示、慣例和 Claude 應該在每個會話中知道的上下文。如果您的儲存庫有用於其他編碼代理的 AGENTS.md，Claude [可以自行讀取](/docs/zh-TW/memory#agents-md)或與 CLAUDE.md 一起讀取。79* **您的 [CLAUDE.md](/docs/zh-TW/memory)。** 一個 markdown 檔案，您可以在其中儲存專案特定的指示、慣例和 Claude 應該在每個工作階段中知道的上下文。如果您的儲存庫有供其他編碼 agent 使用的 AGENTS.md，Claude [可以讀取該檔案](/docs/zh-TW/memory#agents-md)來取代 CLAUDE.md。

80* **[自動記憶](/docs/zh-TW/memory#auto-memory)。** Claude 在您工作時自動儲存的學習內容，例如您的偏好。MEMORY.md 的前 200 行或 25KB（以先到者為準）在每個會話開始時載入。80* **[自動記憶](/docs/zh-TW/memory#auto-memory)。** Claude 在您工作時自動儲存的學習內容，例如您的偏好。MEMORY.md 的前 200 行或 25KB（以先到者為準）在每個會話開始時載入。

81* **您設定的擴展。** 用於外部服務的 [MCP servers](/docs/zh-TW/mcp)、用於工作流程的 [skills](/docs/zh-TW/skills)、用於委派工作的 [subagents](/docs/zh-TW/sub-agents)，以及用於瀏覽器互動的 [Claude in Chrome](/docs/zh-TW/chrome)。81* **您設定的擴展。** 用於外部服務的 [MCP servers](/docs/zh-TW/mcp)、用於工作流程的 [skills](/docs/zh-TW/skills)、用於委派工作的 [subagents](/docs/zh-TW/sub-agents)，以及用於瀏覽器互動的 [Claude in Chrome](/docs/zh-TW/chrome)。

82 82

memory.md +2 −2

Details

8 8

9每個 Claude Code 工作階段都以全新的內容視窗開始。兩個機制可以跨工作階段傳遞知識：9每個 Claude Code 工作階段都以全新的內容視窗開始。兩個機制可以跨工作階段傳遞知識：

10 10

~~11* **CLAUDE.md 檔案**：您撰寫的指示，為 Claude 提供持久內容。Claude 也可以讀取儲存庫的 [`AGENTS.md` 檔案](#agents-md)，單獨使用或與 CLAUDE.md 一起使用~~11* **CLAUDE.md 檔案**：您撰寫的指示，為 Claude 提供持久上下文。Claude 也可以讀取儲存庫的 [`AGENTS.md` 檔案](#agents-md)來取代 CLAUDE.md

12* **自動記憶**：Claude 根據您的更正和偏好自己撰寫的筆記12* **自動記憶**：Claude 根據您的更正和偏好自己撰寫的筆記

13 13

14本頁涵蓋如何：14本頁涵蓋如何：

15 15

16* [撰寫和組織 CLAUDE.md 檔案](#claude-md-files)16* [撰寫和組織 CLAUDE.md 檔案](#claude-md-files)

~~17* [使用現有的 AGENTS.md](#agents-md) 作為您的專案指示，單獨使用或與 CLAUDE.md 一起使用~~17* [使用現有的 AGENTS.md](#agents-md) 作為您的專案指示

18* [使用 `.claude/rules/` 將規則範圍限定於特定檔案類型](#organize-rules-with-claude/rules/)18* [使用 `.claude/rules/` 將規則範圍限定於特定檔案類型](#organize-rules-with-claude/rules/)

19* [設定自動記憶](#auto-memory)，讓 Claude 自動記筆記19* [設定自動記憶](#auto-memory)，讓 Claude 自動記筆記

20* [疑難排解](#troubleshoot-memory-issues)當指示未被遵循時20* [疑難排解](#troubleshoot-memory-issues)當指示未被遵循時

overview.md +1 −1

Details

171 </Accordion>171 </Accordion>

172 172

173 <Accordion title="使用說明、skills 和 hooks 進行自訂" icon="sliders">173 <Accordion title="使用說明、skills 和 hooks 進行自訂" icon="sliders">

174 [`CLAUDE.md`](/docs/zh-TW/memory) 是您新增到專案根目錄的 markdown 檔案，Claude Code 在每個工作階段開始時都會讀取。使用它來設定編碼標準、架構決策、首選程式庫和審查檢查清單。如果您的儲存庫已經有用於其他編碼代理的 `AGENTS.md`，Claude Code [可以自行讀取](/docs/zh-TW/memory#agents-md)或與 `CLAUDE.md` 一起讀取。Claude 也會在工作時建立[自動記憶](/docs/zh-TW/memory#auto-memory)，儲存學習內容，跨工作階段而無需您編寫任何內容。174 [`CLAUDE.md`](/docs/zh-TW/memory) 是您新增到專案根目錄的 markdown 檔案，Claude Code 在每個工作階段開始時都會讀取。使用它來設定編碼標準、架構決策、首選程式庫和審查檢查清單。如果您的儲存庫已經有用於其他編碼 agent 的 `AGENTS.md`，Claude Code [可以讀取該檔案](/docs/zh-TW/memory#agents-md)來取代 `CLAUDE.md`。Claude 也會在工作時建立[自動記憶](/docs/zh-TW/memory#auto-memory)，儲存學習內容，跨工作階段而無需您編寫任何內容。

175 175

176 建立[skills](/docs/zh-TW/skills) 以封裝您的團隊可以共享的可重複工作流程，例如 `/review-pr` 或 `/deploy-staging`。176 建立[skills](/docs/zh-TW/skills) 以封裝您的團隊可以共享的可重複工作流程，例如 `/review-pr` 或 `/deploy-staging`。

177 177

plugins/components.md +1 −1

Details

733You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.733You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.

734```734```

735 735

736此 agent 命名為 `my-plugin:security-reviewer`，使用者可以使用 `@agent-my-plugin:security-reviewer` [明確叫用它](/docs/zh-TW/sub-agents#invoke-subagents-explicitly)。名稱形式是 `<plugin>:<name>`，其中 `<name>` 來自 frontmatter，或沒有時來自檔案名稱。736此 agent 命名為 `my-plugin:security-reviewer`，使用者可以使用 `@agent-my-plugin:security-reviewer` [明確叫用它](/docs/zh-TW/sub-agents#invoke-subagents-explicitly)。名稱形式是 `<plugin>:<name>`，其中 `<name>` 來自 frontmatter 的 `name` 欄位，或在該欄位缺少時來自檔案名稱。

737 737

738`agents` manifest 鍵取代 `agents/` 掃描。738`agents` manifest 鍵取代 `agents/` 掃描。

739 739

plugins/mods/interface.md +5 −3

Details

428 428

429| 元素 | 它繪製的內容 | 位置 |429| 元素 | 它繪製的內容 | 位置 |

430| :- | :- | :- |430| :- | :- | :- |

431| `Box` | 彈性容器。採用佈局屬性，例如 `flexDirection`、`columnGap`、`padding`、`borderStyle` 和 `width`。 | 到處 |431| `Box` | 彈性容器。採用佈局 prop，例如 `flexDirection`、`columnGap`、`padding`、[`borderStyle`](/docs/zh-TW/plugins/mods/reference#box-border-styles) 和 `width`。 | 到處 |

432| `Text` | 樣式文字。採用 `color`、`bold`、`dimColor`、`italic` 和 `wrap`。`color` 是主題鍵或顏色，例如 `'red'`。`wrap` 是 `'wrap'`、`'truncate'`、`'truncate-start'`、`'truncate-middle'` 或 `'truncate-end'`。 | 到處 |432| `Text` | 樣式文字。採用 `color`、`bold`、`dimColor`、`italic` 和 `wrap`。`color` 是主題鍵或顏色，例如 `'red'`。`wrap` 是 `'wrap'`、`'truncate'`、`'truncate-start'`、`'truncate-middle'` 或 `'truncate-end'`。 | 到處 |

433| `Button` | 呼叫 `onPress` 的控制項 | 到處 |433| `Button` | 呼叫 `onPress` 的控制項 | 到處 |

434| `Link`, `Code`, `Markdown` | 具有 `href` 和可選 `label` 的連結、程式碼區塊和格式化為 Claude 回覆方式的文字。`Markdown` 在 `text` 屬性中而不是在 `children` 中採用其內容，並在您傳遞 `onLinkPress` 時需要 `key`。 | 到處 |434| `Link`, `Code`, `Markdown` | 具有 `href` 和可選 `label` 的連結、程式碼區塊和格式化為 Claude 回覆方式的文字。`Markdown` 在 `text` 屬性中而不是在 `children` 中採用其內容，並在您傳遞 `onLinkPress` 時需要 `key`。 | 到處 |

563許多窗格是一個文字欄位，下面有一個清單。本部分中的範例是一個筆記窗格：您輸入一個筆記並按 Enter 新增它，每個筆記都有一個 `x` 按鈕來刪除它。新增兩個筆記後，終端機會以這種方式繪製窗格：563許多窗格是一個文字欄位，下面有一個清單。本部分中的範例是一個筆記窗格：您輸入一個筆記並按 Enter 新增它，每個筆記都有一個 `x` 按鈕來刪除它。新增兩個筆記後，終端機會以這種方式繪製窗格：

564 564

565```text theme={null}565```text theme={null}

566╭──────────────────────────────────────────────────────────╮566╭────────────────────────────────────────────────────────✕─╮

567│ Note: Type a note and press Enter ⏎ add ✕ │567│ Note: Type a note and press Enter ⏎ add │

568│ x buy milk │568│ x buy milk │

569│ x call bob │569│ x call bob │

570╰──────────────────────────────────────────────────────────╯570╰──────────────────────────────────────────────────────────╯

571```571```

572 572

573頂部邊框上的 `✕` 是 Claude Code 本身用於關閉窗格的標記。

574

573範例使用以下技術：575範例使用以下技術：

574 576

575* **取得輸入的文字**：`Input` 在使用者按 Enter 時使用欄位的文字呼叫 `onSubmit(value)`，並在每次更改時呼叫 `onInput(value)`577* **取得輸入的文字**：`Input` 在使用者按 Enter 時使用欄位的文字呼叫 `onSubmit(value)`，並在每次更改時呼叫 `onInput(value)`

plugins/mods/reference.md +23 −2

Details

242若要讓樹狀結構符合其位置，請在 hook 中讀取下列 prop：242若要讓樹狀結構符合其位置，請在 hook 中讀取下列 prop：

243 243

244* **`Pane` 或橫帶的寬度**：依 `e.props.bodyColumns` 繪製244* **`Pane` 或橫帶的寬度**：依 `e.props.bodyColumns` 繪製

245* **逐字稿旁 `Pane` 的高度**：當 `e.props.placement` 為 `'dock'` 時，`e.props.scroll.bodyRows` 是窗格擁有的列數245* **逐字稿旁 `Pane` 的高度**：當 `e.props.placement` 為 `'dock'` 時，`e.props.scroll.bodyRows` 是窗格可供您的樹狀結構使用的列數

246* **提示詞上方 `Pane` 的高度**：當 `e.props.placement` 為 `'inline'` 時，窗格會隨您的樹狀結構增高，直到上限為止，而 `bodyRows` 即為該上限。[`$.ui.open` 的 `rows` 欄位](/docs/zh-TW/plugins/mods/interface#open-a-pane-at-the-right-time)可要求不同的上限。246* **提示詞上方 `Pane` 的高度**：當 `e.props.placement` 為 `'inline'` 時，窗格會隨您的樹狀結構增高，直到上限為止，而 `bodyRows` 即為該上限。[`$.ui.open` 的 `rows` 欄位](/docs/zh-TW/plugins/mods/interface#open-a-pane-at-the-right-time)可要求不同的上限。

247 247

248高於窗格的樹狀結構會整體捲動。248高於窗格的樹狀結構會整體捲動。

255 255

256| 元素 | 主要 prop | 終端機 | Desktop |256| 元素 | 主要 prop | 終端機 | Desktop |

257| :- | :- | :-: | :-: |257| :- | :- | :-: | :-: |

258| [`Box`](/docs/zh-TW/plugins/mods/interface#build-a-tree-from-elements) | `key`、flex 版面配置、`gap`、`padding`、`margin`、`width`、`height`、`borderStyle`、`backgroundColor`、`position`、`hover` | ✓ | ✓ |258| [`Box`](/docs/zh-TW/plugins/mods/interface#build-a-tree-from-elements) | `key`、flex 版面配置、`gap`、`padding`、`margin`、`width`、`height`、[`borderStyle`](#box-border-styles)、`backgroundColor`、`position`、`hover` | ✓ | ✓ |

259| [`Text`](/docs/zh-TW/plugins/mods/interface#build-a-tree-from-elements) | `color`、`backgroundColor`、`bold`、`italic`、`underline`、`dimColor`、`inverse`、`wrap` | ✓ | ✓ |259| [`Text`](/docs/zh-TW/plugins/mods/interface#build-a-tree-from-elements) | `color`、`backgroundColor`、`bold`、`italic`、`underline`、`dimColor`、`inverse`、`wrap` | ✓ | ✓ |

260| [`Button`](/docs/zh-TW/plugins/mods/interface#respond-to-presses-and-typing) | `key`、`label`、`onPress`、`hotkey`、`plain`、`dimColor`、`autoFocus`、`action` | ✓ | ✓ |260| [`Button`](/docs/zh-TW/plugins/mods/interface#respond-to-presses-and-typing) | `key`、`label`、`onPress`、`hotkey`、`plain`、`dimColor`、`autoFocus`、`action` | ✓ | ✓ |

261| `Link` | `href`、`label` | ✓ | ✓ |261| `Link` | `href`、`label` | ✓ | ✓ |

270 270

271更多 `Button` 規則：`action` 指定 Claude Code 本身的某個[快捷鍵動作](/docs/zh-TW/keybindings)，當使用者對該動作的綁定為組合鍵或修飾鍵時，該綁定會按下此按鈕。橫帶中按鈕上的數字 `hotkey`，在使用者於空白提示詞中單獨輸入該數字並停頓時也會觸發。當同一次繪製中有兩個按鈕指定相同的 `hotkey` 時，由後者取得。`autoFocus` 在任何控制項上都只接受 `true`，因此若要關閉，請省略此 prop。271更多 `Button` 規則：`action` 指定 Claude Code 本身的某個[快捷鍵動作](/docs/zh-TW/keybindings)，當使用者對該動作的綁定為組合鍵或修飾鍵時，該綁定會按下此按鈕。橫帶中按鈕上的數字 `hotkey`，在使用者於空白提示詞中單獨輸入該數字並停頓時也會觸發。當同一次繪製中有兩個按鈕指定相同的 `hotkey` 時，由後者取得。`autoFocus` 在任何控制項上都只接受 `true`，因此若要關閉，請省略此 prop。

272 272

273<h3 id="box-border-styles">

274 `Box` 框線樣式

275</h3>

276

277若要在 `Box` 周圍繪製框線，請將其 `borderStyle` 設為下列其中一個名稱，例如 `borderStyle: 'round'`。每一列說明終端機針對該名稱所繪製的內容，並顯示框線的上緣。

278

279| `borderStyle` | 終端機繪製的內容 | 上緣 |

280| :- | :- | :- |

281| `'single'` | 直角的細線 | `┌──┐` |

282| `'double'` | 雙線 | `╔══╗` |

283| `'round'` | 圓角的細線 | `╭──╮` |

284| `'bold'` | 粗線 | `┏━━┓` |

285| `'singleDouble'` | 上下為細線，左右兩側為雙線 | `╓──╖` |

286| `'doubleSingle'` | 上下為雙線，左右兩側為細線 | `╒══╕` |

287| `'classic'` | ASCII 字元 `+`、`-` 和 `\|` | `+--+` |

288| `'arrow'` | 指向 `Box` 內部的箭頭 | `↘↓↓↙` |

289| `'dashed'` | 轉角留白的虛線 | `╌╌` |

290| `'quote'` | 左側一條豎條 `▎`，其他三側為空白儲存格 | 空白 |

291

292若 `Box` 的 `borderStyle` 指定為其他任何名稱，例如 `'rounded'`，則繪製時不會有框線。

293

273<h2 id="limits">294<h2 id="limits">

274 限制295 限制

275</h2>296</h2>

plugins/troubleshooting.md +1 −0

Details

17 17

18 * **為什麼範圍、快取和優先順序的行為方式如此**：閱讀 [外掛程式載入參考](/docs/zh-TW/plugins/loading)18 * **為什麼範圍、快取和優先順序的行為方式如此**：閱讀 [外掛程式載入參考](/docs/zh-TW/plugins/loading)

19 * **查找旗標、欄位或命令**：使用 [外掛程式命令參考](/docs/zh-TW/plugins/cli-reference)、[清單參考](/docs/zh-TW/plugins/manifest-reference) 或 [市集參考](/docs/zh-TW/plugins/marketplace-reference)19 * **查找旗標、欄位或命令**：使用 [外掛程式命令參考](/docs/zh-TW/plugins/cli-reference)、[清單參考](/docs/zh-TW/plugins/manifest-reference) 或 [市集參考](/docs/zh-TW/plugins/marketplace-reference)

20 * **出現 `hooks module not loaded` 或 `hooks module did not load` 訊息**：該外掛程式是一個 [mod](/docs/zh-TW/plugins/mods/overview)，因此請閱讀 [mod 無法載入](/docs/zh-TW/plugins/mods/troubleshoot#the-mod-doesn’t-load)

20</Note>21</Note>

21 22

22搜尋您看到的確切訊息。每個訊息都列在產生它的階段下，這不一定是您執行的命令。例如，安裝可能因為市集遺失而失敗，所以該訊息在 [新增市集](#add-a-marketplace) 下。23搜尋您看到的確切訊息。每個訊息都列在產生它的階段下，這不一定是您執行的命令。例如，安裝可能因為市集遺失而失敗，所以該訊息在 [新增市集](#add-a-marketplace) 下。

quickstart.md +5 −5

Details

33 <Tab title="原生安裝（建議）">33 <Tab title="原生安裝（建議）">

34 **macOS、Linux、WSL：**34 **macOS、Linux、WSL：**

35 35

~~36 ```bash theme={null} theme={null} theme={null} theme={null} theme={null} 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} theme={null} theme={null} theme={null} theme={null} 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} theme={null} theme={null} theme={null} theme={null} 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

63 </Tab>63 </Tab>

64 64

65 <Tab title="Homebrew">65 <Tab title="Homebrew">

~~66 ```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}~~66 ```bash theme={null}

67 brew install --cask claude-code67 brew install --cask claude-code

68 ```68 ```

69 69

75 </Tab>75 </Tab>

76 76

77 <Tab title="WinGet">77 <Tab title="WinGet">

~~78 ```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}~~78 ```powershell theme={null}

79 winget install Anthropic.ClaudeCode79 winget install Anthropic.ClaudeCode

80 ```80 ```

81 81

self-hosted-environments-testing.md +2 −2

Details

104 範例指令碼104 範例指令碼

105</h2>105</h2>

106 106

107下面的指令碼針對 `$CLAUDE_TEST_ENVIRONMENT_ID`（您的測試環境的 `ccpool_...` ID，顯示在管理頁面上環境的詳細對話框中或由[建立環境呼叫](#create-a-dedicated-test-environment)返回）執行完整迴圈，並在每個回覆中斷言哨兵短語。從您希望工作階段在其中工作的存放庫的 git 簽出執行它，在此主機上啟動執行器後，安裝擷取 hook 並匯出 `E2E_REPLY_DIR`。107下面的指令碼針對 `$CLAUDE_TEST_ENVIRONMENT_ID`（您的測試環境的 `ccpool_...` ID，顯示在管理頁面上環境的詳細對話框中或由[建立環境呼叫](#create-a-dedicated-test-environment)返回）執行完整迴圈，並在每個回覆中斷言哨兵短語。從您希望工作階段在其中工作的儲存庫的 git 簽出執行它，在此主機上啟動執行器後，安裝擷取 hook 並匯出 `E2E_REPLY_DIR`。請先依照[從 CI 進行驗證](#authenticate-from-ci)中的說明，在執行指令碼的機器上使用 claude.ai 帳戶登入。若未登入，第一次分派會失敗並出現錯誤，例如 `Unable to get organization UUID for cloud session creation`。

108 108

109```bash theme={null}109```bash theme={null}

110#!/usr/bin/env bash110#!/usr/bin/env bash

174echo "PASS: test-environment round-trip (session $SESSION_ID)"174echo "PASS: test-environment round-trip (session $SESSION_ID)"

175```175```

176 176

177將 `TURN1`/`TURN2` 提示和 `EXPECT1`/`EXPECT2` 哨兵替換為任何練習您的設定的內容，例如要求 Claude 執行您的自訂 MCP 工具之一並斷言其輸出。177將 `TURN1`/`TURN2` 提示詞和 `EXPECT1`/`EXPECT2` 哨兵替換為任何能測試您的設定的內容，例如要求 Claude 執行您的自訂 MCP 工具之一並斷言其輸出。

178 178

179<h2 id="remote-test-runners">179<h2 id="remote-test-runners">

180 遠端測試執行器180 遠端測試執行器

server-managed-settings.md +1 −1

Details

43 <Step title="開啟管理員主控台">43 <Step title="開啟管理員主控台">

44 在 claude.ai 主控台中，前往 [**Organization settings > Claude Code > Managed settings**](https://claude.ai/admin-settings/claude-code)。44 在 claude.ai 主控台中，前往 [**Organization settings > Claude Code > Managed settings**](https://claude.ai/admin-settings/claude-code)。

45 45

46 如果連結將您重新導向至不同的 Organization settings 頁面，而不是 Claude Code 頁面，表示您的帳戶沒有所需的角色。管理員和其他非擁有者角色無法檢視或編輯受管設定，因此請要求您組織中的擁有者或主要擁有者進行變更。請參閱[存取控制](#access-control)。46 在 Team 或 Enterprise 組織中，如果頁面顯示您沒有存取權，請要求[擁有者或主要擁有者](#access-control)進行變更。

47 </Step>47 </Step>

48 48

49 <Step title="定義您的設定">49 <Step title="定義您的設定">

sessions.md +3 −3

Details

83* 終端機：`claude --continue`、`claude --resume <session-id>` 或 `claude --resume <name>`（當名稱符合一個 session 時），不帶 `-p`。Claude Code 會復原 session 所在的權限模式，除了表格中的情況。傳遞 `--permission-mode` 或 `--dangerously-skip-permissions` 以覆蓋復原的模式。83* 終端機：`claude --continue`、`claude --resume <session-id>` 或 `claude --resume <name>`（當名稱符合一個 session 時），不帶 `-p`。Claude Code 會復原 session 所在的權限模式，除了表格中的情況。傳遞 `--permission-mode` 或 `--dangerously-skip-permissions` 以覆蓋復原的模式。

84* 非互動式：`claude -p --resume` 或 `claude -p --continue`。Claude Code 會在新 `claude -p` 執行會啟動的權限模式中啟動執行，除了在[下面的條件](#resume-in-plan-mode-with-p)下以 Plan Mode 結束的 session 會在 Plan Mode 中恢復。84* 非互動式：`claude -p --resume` 或 `claude -p --continue`。Claude Code 會在新 `claude -p` 執行會啟動的權限模式中啟動執行，除了在[下面的條件](#resume-in-plan-mode-with-p)下以 Plan Mode 結束的 session 會在 Plan Mode 中恢復。

85* VS Code：擴充功能的對話面板。表格僅涵蓋以 Plan Mode 結束的對話；對於其餘部分，請參閱[恢復過去的對話](/docs/zh-TW/vs-code#resume-past-conversations)。85* VS Code：擴充功能的對話面板。表格僅涵蓋以 Plan Mode 結束的對話；對於其餘部分，請參閱[恢復過去的對話](/docs/zh-TW/vs-code#resume-past-conversations)。

86* 啟動時的 Session 選擇器：您從[session 選擇器](#use-the-session-picker)選擇的 session，無論您是使用 `claude --resume` 單獨開啟它、`claude --from-pr` 還是符合多個 session 的名稱。Claude Code 不會復原儲存的權限模式。它會在從相同命令列啟動新 session 時所在的權限模式中啟動 session。86* 啟動時的工作階段選擇器：您從[工作階段選擇器](#use-the-session-picker)選擇的工作階段，無論您是單獨使用 `claude --resume`、使用 `claude --from-pr`，還是使用符合多個工作階段的名稱來開啟選擇器。Claude Code 會以從相同命令列啟動新工作階段時的權限模式啟動該工作階段，但以 plan mode 結束的工作階段會在 plan mode 中恢復，除非您傳遞 `--permission-mode`、`--dangerously-skip-permissions` 或 `--fork-session`。不會復原其他已儲存的權限模式。

~~87* `/resume` 在 session 內，帶或不帶引數：Claude Code 不會復原儲存的權限模式。您切換到的對話會在您目前 session 所在的權限模式中繼續。~~87* 在工作階段內使用 `/resume`，帶或不帶引數：您切換到的對話會以您目前工作階段所在的權限模式繼續，但以 plan mode 結束的對話會在 plan mode 中恢復，即使您是以 `--permission-mode` 或 `--dangerously-skip-permissions` 啟動 Claude Code。如果該對話在本次 Claude Code 執行中稍早已開啟過，例如您一開始所在的對話，或您以 `/clear` 或 `/resume` 離開的對話，它則會改為以您目前的權限模式繼續。

88 88

89在非互動式和 VS Code 路徑上復原 Plan Mode 需要 Claude Code v2.1.246 或更新版本。每一列命名 session 結束時所在的權限模式、您透過哪個終端機、非互動式和 VS Code 路徑恢復它，以及 Claude Code 在恢復的 session 中啟動的權限模式。89在非互動式和 VS Code 路徑上復原 Plan Mode 需要 Claude Code v2.1.246 或更新版本。每一列命名 session 結束時所在的權限模式、您透過哪個終端機、非互動式和 VS Code 路徑恢復它，以及 Claude Code 在恢復的 session 中啟動的權限模式。

90 90

92| :- | :- | :- |92| :- | :- | :- |

93| `bypassPermissions` | 終端機 | 新 session 會啟動的權限模式。要再次[略過權限](/docs/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode)，請在啟動時使用其啟動旗標之一或 [user、`--settings` 或受管設定](/docs/zh-TW/settings-reference#permissions-defaultmode)中的 `permissions.defaultMode: "bypassPermissions"` 啟用它 |93| `bypassPermissions` | 終端機 | 新 session 會啟動的權限模式。要再次[略過權限](/docs/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode)，請在啟動時使用其啟動旗標之一或 [user、`--settings` 或受管設定](/docs/zh-TW/settings-reference#permissions-defaultmode)中的 `permissions.defaultMode: "bypassPermissions"` 啟用它 |

~~94| `plan` | 終端機 | 新 session 會啟動的權限模式 |~~94| `plan` | 終端機 | plan mode。使用 `--fork-session` 時，則為新工作階段會啟動的權限模式 |

95| `auto` | 終端機 | `auto`，僅當您的帳戶仍符合 [auto mode 要求](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)時 |95| `auto` | 終端機 | `auto`，僅當您的帳戶仍符合 [auto mode 要求](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)時 |

96| Manual | 終端機 | Manual，當新 session 會從[內建預設](/docs/zh-TW/permission-modes#which-mode-a-session-starts-in)以 auto mode 啟動時。當設定檔案中的 `defaultMode` [生效](/docs/zh-TW/permission-modes#which-mode-a-session-starts-in)時，Claude Code 會在該模式中啟動恢復的 session |96| Manual | 終端機 | Manual，當新 session 會從[內建預設](/docs/zh-TW/permission-modes#which-mode-a-session-starts-in)以 auto mode 啟動時。當設定檔案中的 `defaultMode` [生效](/docs/zh-TW/permission-modes#which-mode-a-session-starts-in)時，Claude Code 會在該模式中啟動恢復的 session |

sub-agents.md +2 −2

Details

310 310

311| 欄位 | 必需 | 描述 |311| 欄位 | 必需 | 描述 |

312| :- | :- | :- |312| :- | :- | :- |

313| `name` | 是 | 唯一識別碼，例如 `code-reviewer` 或 `reviewer-v2`。[Hooks](/docs/zh-TW/hooks#subagentstart) 將此值作為 `agent_type` 接收。檔案名稱不必匹配。名稱不能包含 `:`，它保留用於[plugin 範圍識別碼](/docs/zh-TW/plugins/overview)，例如 `my-plugin:reviewer`。Claude Code 不載入名稱包含一個的檔案，並將錯誤記錄到偵錯日誌。在 v2.1.218 之前，此類名稱被接受 |313| `name` | 是 | 最多 256 個字元的唯一識別碼，例如 `code-reviewer` 或 `reviewer-v2`。[Hook](/docs/zh-TW/hooks#subagentstart) 會以 `agent_type` 接收此值。檔案名稱不必相符。名稱不能包含 `:`，它保留給[外掛範圍識別碼](/docs/zh-TW/plugins/overview)使用，例如 `my-plugin:reviewer` |

314| `description` | 是 | Claude 應何時委派給此子代理 |314| `description` | 是 | Claude 應何時委派給此子代理 |

315| `tools` | 否 | 子代理可以使用的[工具](#available-tools)，作為逗號分隔的字串，例如 `Read, Grep, Bash` 或 YAML 列表。如果省略，繼承子代理可用的每個工具。如果列表中沒有條目解析為工具，子代理通常[無法啟動](/docs/zh-TW/errors#agent-would-be-spawned-with-zero-tools)並出現錯誤，命名未解析的條目。若要將 Skills 預載入上下文，請使用 `skills` 欄位而不是在此列出 `Skill` |315| `tools` | 否 | 子代理可以使用的[工具](#available-tools)，作為逗號分隔的字串，例如 `Read, Grep, Bash` 或 YAML 列表。如果省略，繼承子代理可用的每個工具。如果列表中沒有條目解析為工具，子代理通常[無法啟動](/docs/zh-TW/errors#agent-would-be-spawned-with-zero-tools)並出現錯誤，命名未解析的條目。若要將 Skills 預載入上下文，請使用 `skills` 欄位而不是在此列出 `Skill` |

316| `disallowedTools` | 否 | 要拒絕的工具，從繼承或指定的列表中移除。與 `tools` 相同的格式。具有指定符的條目（例如 `Bash(git push *)`）仍然[移除整個工具](#available-tools) |316| `disallowedTools` | 否 | 要拒絕的工具，從繼承或指定的列表中移除。與 `tools` 相同的格式。具有指定符的條目（例如 `Bash(git push *)`）仍然[移除整個工具](#available-tools) |

348 348

349* **沒有 `name`**：Claude Code 將檔案視為保存在代理旁邊的文件。349* **沒有 `name`**：Claude Code 將檔案視為保存在代理旁邊的文件。

350* **不是檔案第一行的開啟 `---`**：Claude Code 讀取檔案為沒有 frontmatter，並將其視為文件。350* **不是檔案第一行的開啟 `---`**：Claude Code 讀取檔案為沒有 frontmatter，並將其視為文件。

351* **以 `-` 開頭或包含 `:` 的 `name`**：Claude Code 跳過檔案並將錯誤寫入偵錯日誌。請參閱上表中的 `name` 列。351* **`name` 以 `-` 開頭、包含 `:`，或超過 256 個字元**：Claude Code 會略過該檔案，並將錯誤寫入除錯日誌。

352* **有 `name` 但沒有 `description`**：Claude Code 跳過檔案並將原因寫入偵錯日誌。352* **有 `name` 但沒有 `description`**：Claude Code 跳過檔案並將原因寫入偵錯日誌。

353* **不解析的 YAML**：Claude Code 不從檔案讀取任何欄位，跳過它，並將解析錯誤寫入偵錯日誌。353* **不解析的 YAML**：Claude Code 不從檔案讀取任何欄位，跳過它，並將解析錯誤寫入偵錯日誌。

354 354

vs-code.md +1 −1

Details

606| `environmentVariables` | `[]` | 為 Claude 程序設定環境變數。使用 Claude Code 設定以改為共享設定。[`CLAUDE_CONFIG_DIR`](/docs/zh-TW/env-vars) 項目僅在其值為絕對路徑時才會套用；擴充功能不會展開 `~`，並會忽略相對路徑值。 |606| `environmentVariables` | `[]` | 為 Claude 程序設定環境變數。使用 Claude Code 設定以改為共享設定。[`CLAUDE_CONFIG_DIR`](/docs/zh-TW/env-vars) 項目僅在其值為絕對路徑時才會套用；擴充功能不會展開 `~`，並會忽略相對路徑值。 |

609| `claudeProcessWrapper` | - | 用於啟動 Claude 程序的可執行檔。當存在時，組合的二進位路徑會作為引數傳遞。如果擴充功能組建不包含您平台的二進位檔，請將其設定為單獨安裝的 `claude` 二進位檔。在包裝的設定中，對話以 Manual 模式開始，除非您設定 `initialPermissionMode` 或在較早的對話中選擇了 Manual、Edit automatically 或 Auto，因為擴充功能會在那裡略過設定和內建預設步驟；請參閱[切換權限模式](/docs/zh-TW/permission-modes#switch-permission-modes)。啟動時出現「不支援的平台」錯誤表示您的平台沒有組合的二進位檔；請參閱[哪些平台有預先建置的二進位檔](/docs/zh-TW/troubleshoot-install#native-binary-not-found-after-npm-install)。 |609| `claudeProcessWrapper` | - | 用於啟動 Claude 程序的可執行檔。當存在時，組合的二進位路徑會作為引數傳遞。如果擴充功能建置不包含您平台的二進位檔，請將其設定為單獨安裝的 `claude` 二進位檔。 |

610 610

611<h2 id="use-a-screen-reader">611<h2 id="use-a-screen-reader">

612 使用螢幕閱讀器612 使用螢幕閱讀器

worktrees.md +3 −1

Details

6 6

7> 在獨立的 git worktrees 中隔離平行的 Claude Code 會話，使變更不會相互衝突。涵蓋 `--worktree` 旗標、子代理隔離、`.worktreeinclude`、清理和非 git VCS hooks。7> 在獨立的 git worktrees 中隔離平行的 Claude Code 會話，使變更不會相互衝突。涵蓋 `--worktree` 旗標、子代理隔離、`.worktreeinclude`、清理和非 git VCS hooks。

8 8

9[git worktree](https://git-scm.com/docs/git-worktree) 是一個獨立的工作目錄，具有自己的檔案和分支，但與主要檢出共享相同的儲存庫歷史記錄和遠端。在自己的 worktree 中執行每個 Claude Code 會話意味著一個會話中的編輯永遠不會觸及另一個會話中的檔案，因此一個會話可以建置功能，而第二個會話可以修復錯誤。9[git worktree](https://git-scm.com/docs/git-worktree) 是一個獨立的工作目錄，具有自己的檔案和分支，但與主要檢出共享相同的儲存庫歷史記錄和遠端。在各自的 worktree 中執行每個 Claude Code 工作階段，可為其提供一份獨立的檔案副本進行編輯，因此一個工作階段可以建置功能，而第二個工作階段可以修復錯誤。

10 10

11<Note>11<Note>

12 Worktrees 需要 git 儲存庫；對於其他版本控制系統，請[配置 hooks 以取代 git 邏輯](#non-git-version-control)。在[桌面應用程式](/docs/zh-TW/desktop#work-in-parallel-with-sessions)中，當您啟動會話時選擇 **worktree** 選項，為其提供自己的 worktree。12 Worktrees 需要 git 儲存庫；對於其他版本控制系統，請[配置 hooks 以取代 git 邏輯](#non-git-version-control)。在[桌面應用程式](/docs/zh-TW/desktop#work-in-parallel-with-sessions)中，當您啟動會話時選擇 **worktree** 選項，為其提供自己的 worktree。

104* **Git 重定向**：Claude Code 會阻止將 git 重定向到主要檢出的 Bash 或 Monitor 命令。重定向可以透過 `git -C`、`--git-dir`、`GIT_DIR` 或 `GIT_WORK_TREE` 變數，或在執行 git 之前 `cd` 到主要檢出。104* **Git 重定向**：Claude Code 會阻止將 git 重定向到主要檢出的 Bash 或 Monitor 命令。重定向可以透過 `git -C`、`--git-dir`、`GIT_DIR` 或 `GIT_WORK_TREE` 變數，或在執行 git 之前 `cd` 到主要檢出。

105* **命令形狀**：當 Claude Code 無法從命令文字驗證命令執行的任何 git 保持在 worktree 內時，Claude Code 會阻止 Bash 或 Monitor 命令。例如，當命令名稱在執行時計算、語法無法解析，或像 `${!name}` 或 `${ command; }` 這樣的展開可能執行文字中未明確說明的命令時，就會發生這種情況。Claude Code 會告訴 Claude 如何重寫被拒絕的命令，例如將其分割成純粹的、獨立的命令。您無法關閉此檢查。105* **命令形狀**：當 Claude Code 無法從命令文字驗證命令執行的任何 git 保持在 worktree 內時，Claude Code 會阻止 Bash 或 Monitor 命令。例如，當命令名稱在執行時計算、語法無法解析，或像 `${!name}` 或 `${ command; }` 這樣的展開可能執行文字中未明確說明的命令時，就會發生這種情況。Claude Code 會告訴 Claude 如何重寫被拒絕的命令，例如將其分割成純粹的、獨立的命令。您無法關閉此檢查。

106 106

107這些檢查會讀取編輯所針對的路徑、命令執行所在的目錄，以及命令的文字。它們都不會追蹤 shell 命令寫入了哪些檔案，因此未在主要檢出中執行 git 卻寫入主要檢出的命令（例如 `cp` 或 shell 重定向）不會被這些檢查拒絕。Claude Code 會將該命令視為任何其他 shell 命令處理，因此它是直接執行還是向您顯示權限提示，取決於您的[權限模式](/docs/zh-TW/permission-modes)和規則。

108

107檢查適用於您啟動 Claude Code 的儲存庫。它們也涵蓋連結 worktree 連結自的主要檢出。對於 PowerShell 命令，Claude Code 只應用工作目錄檢查。109檢查適用於您啟動 Claude Code 的儲存庫。它們也涵蓋連結 worktree 連結自的主要檢出。對於 PowerShell 命令，Claude Code 只應用工作目錄檢查。

108 110

109Claude 將每次拒絕視為命名 worktree 並說明如何進行的工具錯誤。如需被拒絕的命令，請參閱[拒絕訊息的含義以及如何清除它](/docs/zh-TW/errors#command-blocked-by-the-worktree-isolation-checks)。111Claude 將每次拒絕視為命名 worktree 並說明如何進行的工具錯誤。如需被拒絕的命令，請參閱[拒絕訊息的含義以及如何清除它](/docs/zh-TW/errors#command-blocked-by-the-worktree-isolation-checks)。

Documentation 2026-10-06 23:59 UTC to 2026-10-07 09:59 UTC