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 +21 −14

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

3789};3794};

3790```3795```

3791 3796

3792將程式碼審查發現報告為結構化清單，以便 Claude Code 可以呈現它們而不是將其列印為文字。`level` 是審查執行的工作量級別。發現按最嚴重優先排序，每次呼叫最多 32 個，當沒有發現存活時陣列為空。需要 Claude Code v2.1.196 或更新版本。3797將程式碼審查發現報告為結構化清單，以便 Claude Code 可以呈現它們而不是將其列印為文字。發現按最嚴重優先排序，每次呼叫最多 32 個，當沒有發現存活時陣列為空。需要 Claude Code v2.1.196 或更新版本。

3798

3799`level` 為選擇性欄位，保存 Claude 為此審查回報的 effort 等級。Claude Code 不會將其與審查實際執行時的等級進行比較，因此兩者可能不同。

3793 3800

3794每個發現包含這些欄位：3801每個發現包含這些欄位：

3795 3802

4839};4846};

4840```4847```

4841 4848

4842傳回報告的發現數、審查執行的工作量級別以及為結果本體回顯的發現。需要 Claude Code v2.1.196 或更新版本。回顯的 `short_summary` 欄位需要 Claude Code v2.1.212 或更新版本。4849傳回報告的發現數、Claude 傳遞的 `level` 值以及為結果本體回顯的發現。需要 Claude Code v2.1.196 或更新版本。回顯的 `short_summary` 欄位需要 Claude Code v2.1.212 或更新版本。

4843 4850

4844<h3 id="artifact-2">4851<h3 id="artifact-2">

4845 Artifact4852 Artifact

5273 5280

5274`source` 說明伺服器定義的來源，具有與 [`McpServerProvenance`](#mcpserverprovenance) 的 `source` 相同的值和信任規則。該欄位需要 Agent SDK v0.3.274 或更新版本，在較早版本上不存在。5281`source` 說明伺服器定義的來源，具有與 [`McpServerProvenance`](#mcpserverprovenance) 的 `source` 相同的值和信任規則。該欄位需要 Agent SDK v0.3.274 或更新版本，在較早版本上不存在。

5275 5282

5276`_meta` 在 `tools` 項目上攜帶該工具的 `_meta` 的 MCP Apps 成員，因此您的應用程式可以找到 `ui://` 資源以使用 [`readMcpResource()`](#query-object) 呈現。Claude Code 傳遞 `ui` 物件和已棄用的平面 `ui/resourceUri` 字串，並保留所有其他金鑰。在 `ui` 內，`resourceUri` 是 `ui://` 字串，`visibility` 是當伺服器設定時 `"model"` 和 `"app"` 的陣列，任何其他成員原封不動地傳遞。Claude Code 在值格式不正確時捨棄任一金鑰，並從未宣告任一金鑰的工具中省略 `_meta`。該欄位僅在初始化訊息的 [`capabilities`](#sdksystemmessage) 包含 `mcp_tool_ui_meta_v1` 時存在，並需要 TypeScript Agent SDK v0.3.280 或更新版本。5283`_meta` 在 `tools` 項目上攜帶該工具的 `_meta` 的 MCP Apps 成員，因此您的應用程式可以找到 `ui://` 資源以使用 [`readMcpResource()`](#query-object) 呈現。Claude Code 傳遞 `ui` 物件和已棄用的平面 `ui/resourceUri` 字串，並扣留所有其他金鑰，不予傳遞。在 `ui` 內，`resourceUri` 是 `ui://` 字串，`visibility` 是當伺服器設定時 `"model"` 和 `"app"` 的陣列，任何其他成員原封不動地傳遞。Claude Code 在值格式不正確時捨棄任一金鑰，並從未宣告任一金鑰的工具中省略 `_meta`。該欄位僅在初始化訊息的 [`capabilities`](#sdksystemmessage) 包含 `mcp_tool_ui_meta_v1` 時存在，並需要 TypeScript Agent SDK v0.3.280 或更新版本。

5277 5284

5278<h3 id="mcpserverstatusconfig">5285<h3 id="mcpserverstatusconfig">

5279 `McpServerStatusConfig`5286 `McpServerStatusConfig`

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

5461```5468```

5462 5469

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` 區塊。5470可選的 `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 5471

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

5466 `SpawnedProcess`5473 `SpawnedProcess`

5531 5538

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

5533 5540

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

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

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

5537 5544

5538承諾在新增的 stdio、HTTP 和 SSE 伺服器連線或失敗後解決，因此來自已連線伺服器的工具在下一回合可用。5545承諾在新增的 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

authentication.md +1 −1

Details

12 登入 Claude Code12 登入 Claude Code

13</h2>13</h2>

14 14

15[安裝 Claude Code](/docs/zh-TW/setup#install-claude-code) 後，在您的終端機中執行 `claude`。首次啟動時，Claude Code 會為您開啟瀏覽器視窗以供登入。如果您已設定 `ANTHROPIC_API_KEY` 環境變數，Claude Code 會略過登入提示，改為要求您核准該金鑰。15[安裝 Claude Code](/docs/zh-TW/setup#install-claude-code) 後，在您的終端機中執行 `claude`。首次啟動時，Claude Code 會為您開啟瀏覽器視窗以供登入。如果您已設定 `ANTHROPIC_API_KEY` 環境變數，且在 Claude Code 詢問是否使用該金鑰時予以核准，Claude Code 就會略過登入提示。

16 16

17如果瀏覽器未自動開啟，請按 `c` 將登入 URL 複製到您的剪貼簿，然後將其貼到您的瀏覽器中。17如果瀏覽器未自動開啟，請按 `c` 將登入 URL 複製到您的剪貼簿，然後將其貼到您的瀏覽器中。

18 18

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 +5 −3

Details

416* **隔離的虛擬機器**：每個工作階段在隔離的 Anthropic 管理的 VM 中執行。您的組織路由到[自託管環境](/docs/zh-TW/self-hosted-environments)的工作階段改為在您自己的基礎設施上執行，其中隔離是您的部署的責任416* **隔離的虛擬機器**：每個工作階段在隔離的 Anthropic 管理的 VM 中執行。您的組織路由到[自託管環境](/docs/zh-TW/self-hosted-environments)的工作階段改為在您自己的基礎設施上執行，其中隔離是您的部署的責任

417* <span id="default-allowed-domains" />**網路存取控制**：在 Anthropic 託管的環境中，網路存取預設受限，可以禁用。請參閱[網路存取](/docs/zh-TW/cloud-environments#network-access)以了解存取層級、[預設允許的網域](/docs/zh-TW/cloud-environments#default-allowed-domains)，以及不通過允許清單的流量。在自託管環境中，您在自己的網路邊界限制工作階段出口。當以禁用的網路存取執行時，Claude Code 仍然可以與 Anthropic API 通訊，這可能允許資料離開 VM。417* <span id="default-allowed-domains" />**網路存取控制**：在 Anthropic 託管的環境中，網路存取預設受限，可以禁用。請參閱[網路存取](/docs/zh-TW/cloud-environments#network-access)以了解存取層級、[預設允許的網域](/docs/zh-TW/cloud-environments#default-allowed-domains)，以及不通過允許清單的流量。在自託管環境中，您在自己的網路邊界限制工作階段出口。當以禁用的網路存取執行時，Claude Code 仍然可以與 Anthropic API 通訊，這可能允許資料離開 VM。

418* **認證保護**：在 Anthropic 託管的環境中，git 認證和簽署金鑰保持在沙箱外，代理使用限定認證代表工作階段進行驗證。在自託管環境中，您的部署提供 git 認證；請參閱[配置 git](/docs/zh-TW/self-hosted-environments-deploy#configure-git)418* **認證保護**：在 Anthropic 託管的環境中，git 認證和簽署金鑰保持在沙箱外，代理使用限定認證代表工作階段進行驗證。在自託管環境中，您的部署提供 git 認證；請參閱[配置 git](/docs/zh-TW/self-hosted-environments-deploy#configure-git)

419* **API 認證**：在 Pro 和 Max 計畫的 Anthropic 託管環境中，您[新增到雲端環境](/docs/zh-TW/cloud-environments#add-api-credentials)的金鑰保持在沙箱外，以相同的方式附加到匹配的請求，在它們離開工作階段後。自託管環境沒有 API 認證，Team 和 Enterprise 計畫還沒有419* **網路機密**：在 Pro 和 Max 計畫的 Anthropic 託管環境中，您[新增到雲端環境](/docs/zh-TW/cloud-environments#add-api-credentials)的金鑰同樣保持在沙箱外，並在符合的請求離開工作階段後附加到這些請求上。自託管環境沒有網路機密，Team 和 Enterprise 計畫目前也尚未提供

420* **安全分析**：程式碼在隔離的工作階段環境內進行分析和修改，然後建立 PR420* **安全分析**：程式碼在隔離的工作階段環境內進行分析和修改，然後建立 PR

421 421

422<h2 id="troubleshooting">422<h2 id="troubleshooting">

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

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

164 icon: 'folder',164 icon: 'folder',

165 color: '#9B7BC4',165 color: '#9B7BC4',

166 oneLiner: 'Topic-scoped instructions, optionally gated by file paths',166 oneLiner: 'Topic-scoped instructions, optionally gated by file paths',

167 when: <>Rules without <C>paths:</C> load at session start. Rules with <C>paths:</C> load when a matching file enters context</>,167 when: <>Rules without <C>paths:</C> load at session start. Rules with <C>paths:</C> load when Claude reads, writes, or edits a matching file</>,

168 description: [<>Project instructions split into topic files that can load conditionally based on file paths. A rule without <C>paths:</C> frontmatter loads at session start like CLAUDE.md; a rule with <C>paths:</C> loads only when Claude reads, writes, or edits a matching file.</>, <>Like CLAUDE.md, rules are guidance Claude reads, not configuration Claude Code enforces. For guaranteed behavior use <A href="/docs/en/hooks">hooks</A> or <A href="/docs/en/permissions">permissions</A>.</>],168 description: [<>Project instructions split into topic files that can load conditionally based on file paths. A rule without <C>paths:</C> frontmatter loads at session start like CLAUDE.md; a rule with <C>paths:</C> loads only when Claude reads, writes, or edits a matching file.</>, <>Like CLAUDE.md, rules are guidance Claude reads, not configuration Claude Code enforces. For guaranteed behavior use <A href="/docs/en/hooks">hooks</A> or <A href="/docs/en/permissions">permissions</A>.</>],

169 tips: [<>Use <C>paths:</C> frontmatter with globs to scope rules to directories or file types</>, <>Subdirectories work: <C>.claude/rules/frontend/react.md</C> is discovered automatically</>, 'When CLAUDE.md approaches 200 lines, start splitting into rules'],169 tips: [<>Use <C>paths:</C> frontmatter with globs to scope rules to directories or file types</>, <>Subdirectories work: <C>.claude/rules/frontend/react.md</C> is discovered automatically</>, 'When CLAUDE.md approaches 200 lines, start splitting into rules'],

170 docsLink: '/en/memory#organize-rules-with-claude/rules/',170 docsLink: '/en/memory#organize-rules-with-claude/rules/',

176 color: '#9B7BC4',176 color: '#9B7BC4',

177 badge: 'committed',177 badge: 'committed',

178 oneLiner: 'Test conventions scoped to test files',178 oneLiner: 'Test conventions scoped to test files',

179 when: <>Loaded when Claude reads a file matching the <C>paths:</C> globs below</>,179 when: <>Loaded when Claude reads, writes, or edits a file matching the <C>paths:</C> globs below</>,

180 description: <>An example rule that only loads when Claude is working on test files. The <C>paths:</C> globs in the frontmatter define which files trigger it; here, anything ending in .test.ts or .test.tsx. For other files, this rule is not loaded into context.</>,180 description: <>An example rule that only loads when Claude is working on test files. The <C>paths:</C> globs in the frontmatter define which files trigger it; here, anything ending in .test.ts or .test.tsx. For other files, this rule is not loaded into context.</>,

181 example: `---181 example: `---

182paths:182paths:

197 color: '#9B7BC4',197 color: '#9B7BC4',

198 badge: 'committed',198 badge: 'committed',

199 oneLiner: 'API conventions scoped to backend code',199 oneLiner: 'API conventions scoped to backend code',

200 when: <>Loaded when Claude reads a file matching the <C>paths:</C> glob below</>,200 when: <>Loaded when Claude reads, writes, or edits a file matching the <C>paths:</C> glob below</>,

201 description: <>A second example showing a rule scoped to backend code. The <C>paths:</C> glob matches files under src/api/, so these conventions load only when Claude is editing API routes.</>,201 description: <>A second example showing a rule scoped to backend code. The <C>paths:</C> glob matches files under src/api/, so these conventions load only when Claude is working on API routes.</>,

202 example: `---202 example: `---

203paths:203paths:

204 - "src/api/**/*.ts"204 - "src/api/**/*.ts"

605 icon: 'folder',605 icon: 'folder',

606 color: '#9B7BC4',606 color: '#9B7BC4',

607 oneLiner: 'User-level rules that apply to every project',607 oneLiner: 'User-level rules that apply to every project',

608 when: <>Rules without <C>paths:</C> load at session start. Rules with <C>paths:</C> load when a matching file enters context</>,608 when: <>Rules without <C>paths:</C> load at session start. Rules with <C>paths:</C> load when Claude reads, writes, or edits a matching file</>,

609 description: 'Same as project .claude/rules/ but applies everywhere. Use this for conventions you want across all your work, like personal code style or commit message format.',609 description: 'Same as project .claude/rules/ but applies everywhere. Use this for conventions you want across all your work, like personal code style or commit message format.',

610 docsLink: '/en/memory#organize-rules-with-claude/rules/',610 docsLink: '/en/memory#organize-rules-with-claude/rules/',

611 children: []611 children: []

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

claude-projects.md +7 −7

Details

58* **執行緒**：工作者。每個都是一個單獨的工作階段，有自己的上下文視窗，完成一項工作並在完成時報告回對話。雲端執行緒在自己的分支上工作，並在工作需要時打開提取請求。58* **執行緒**：工作者。每個都是一個單獨的工作階段，有自己的上下文視窗，完成一項工作並在完成時報告回對話。雲端執行緒在自己的分支上工作，並在工作需要時打開提取請求。

59* **每個雲端執行緒開始時的內容**：59* **每個雲端執行緒開始時的內容**：

60 * project 的儲存庫和檔案，加上其 [指示和記憶](#give-a-project-standing-context)60 * project 的儲存庫和檔案，加上其 [指示和記憶](#give-a-project-standing-context)

~~61 * `CLAUDE.md` 和 [project 每個儲存庫](#what-threads-pick-up-from-your-repositories) 中的 skills，以及在有一個儲存庫的 project 中，該儲存庫的權限規則和 hooks~~61 * `CLAUDE.md` 和 [project 每個儲存庫](#what-threads-pick-up-from-your-repositories) 中的 skill，以及在有一個儲存庫的 project 中，該儲存庫的權限規則和 hook

~~62 * 您 claude.ai 帳戶上的 [connectors](#get-skills-plugins-connectors-and-tools-into-threads)~~62 * 您 claude.ai 帳戶上的 [連接器](#get-skills-plugins-connectors-and-tools-into-threads)

~~63 * 一個 [雲端環境](#choose-an-environment-for-threads)，設定其網路存取、環境變數、API 認證和已安裝的工具~~63 * 一個 [雲端環境](#choose-an-environment-for-threads)，設定其網路存取、環境變數、網路密鑰和已安裝的工具

64* **Overview 窗格**：您在其中 [一次看到所有執行緒](#see-what-needs-you-in-overview) 以及其中哪些需要您。其他標籤是 **Library** 用於您添加的檔案和執行緒產生的檔案，**Pull requests** 用於執行緒開啟的提取請求，**Routines** 用於 project 中的排程工作。64* **Overview 窗格**：您在其中 [一次看到所有執行緒](#see-what-needs-you-in-overview) 以及其中哪些需要您。其他標籤是 **Library** 用於您添加的檔案和執行緒產生的檔案，**Pull requests** 用於執行緒開啟的提取請求，**Routines** 用於 project 中的排程工作。

65 65

66雲端執行緒不會從您自己機器上的 Claude Code 設定中選擇任何內容。[將 skills、plugins、connectors 和工具放入執行緒](#get-skills-plugins-connectors-and-tools-into-threads) 涵蓋了如何給予它們否則會缺少的內容。66雲端執行緒不會從您自己機器上的 Claude Code 設定中選擇任何內容。[將 skills、plugins、connectors 和工具放入執行緒](#get-skills-plugins-connectors-and-tools-into-threads) 涵蓋了如何給予它們否則會缺少的內容。

92 92

93* **方案**：您在 Pro 或 Max 上，**Projects** 在您的側邊欄中顯示。93* **方案**：您在 Pro 或 Max 上，**Projects** 在您的側邊欄中顯示。

94* **GitHub，如果 project 將在程式碼上工作**：您的程式碼在 github.com 上而不是 GitHub Enterprise Server、GitLab 或 Bitbucket 上，您連接的 GitHub 帳戶對其有推送存取權，Claude GitHub App 已安裝在其上。如果您使用 [`/web-setup`](/docs/zh-TW/web-quickstart#connect-from-your-terminal) 連接了 GitHub，該令牌讓您的其他雲端工作階段到達儲存庫，但對於需要 Claude GitHub App 的 project 執行緒來說還不夠。[設定 GitHub 存取](#set-up-github-access) 有步驟。94* **GitHub，如果 project 將在程式碼上工作**：您的程式碼在 github.com 上而不是 GitHub Enterprise Server、GitLab 或 Bitbucket 上，您連接的 GitHub 帳戶對其有推送存取權，Claude GitHub App 已安裝在其上。如果您使用 [`/web-setup`](/docs/zh-TW/web-quickstart#connect-from-your-terminal) 連接了 GitHub，該令牌讓您的其他雲端工作階段到達儲存庫，但對於需要 Claude GitHub App 的 project 執行緒來說還不夠。[設定 GitHub 存取](#set-up-github-access) 有步驟。

95* **網路、認證和工具**：這些來自 project 的 [雲端環境](#choose-an-environment-for-threads)。預設環境已經到達 [常見套件登錄](/docs/zh-TW/cloud-environments#default-allowed-domains)，因此只有在工作需要其他網域、秘密或未預先安裝的工具時才檢查此項。如果工作需要 MCP 伺服器，檢查它是否在您的 [claude.ai connectors](https://claude.ai/customize/connectors) 中顯示為已連接。95* **網路、秘密和工具**：對於雲端執行緒，這些來自 project 的 [雲端環境](#choose-an-environment-for-threads)。預設環境已經到達 [常見套件登錄](/docs/zh-TW/cloud-environments#default-allowed-domains)，因此只有在工作需要其他網域、秘密或未預先安裝的工具時才檢查此項。如果工作需要 MCP 伺服器，檢查它是否在您的 [claude.ai connectors](https://claude.ai/customize/connectors) 中顯示為已連接。

96 96

97<h3 id="start-a-new-project-from-scratch">97<h3 id="start-a-new-project-from-scratch">

98 從頭開始啟動新 project98 從頭開始啟動新 project

396 為執行緒選擇環境396 為執行緒選擇環境

397</h3>397</h3>

398 398

399每個新雲端執行緒在專案的[雲端環境](/docs/zh-TW/cloud-environments)中啟動。環境設定執行緒可以到達哪些網域、它們有哪些環境變數、哪些 API 認證被新增到它們的請求，以及設定指令碼在 Claude 啟動前安裝什麼。雲端執行緒使用預設的 Anthropic 託管環境，直到您在**專案設定 > 環境**中選擇一個。399每個新雲端執行緒都在專案的[雲端環境](/docs/zh-TW/cloud-environments)中啟動。環境會設定執行緒可以連線到哪些網域、它們擁有哪些環境變數、哪些網路密鑰會被加入到它們的請求中，以及設定指令碼在 Claude 啟動前安裝什麼。在您於**專案設定 > 環境**中選擇環境之前，雲端執行緒使用預設的 Anthropic 託管環境。

400 400

401如果雲端執行緒需要到達內部 API 或私有套件登錄，或需要您的機器通常持有的令牌，請變更環境而不是專案：請參閱[網路存取](/docs/zh-TW/cloud-environments#network-access)、[新增 API 認證](/docs/zh-TW/cloud-environments#add-api-credentials)和[設定指令碼](/docs/zh-TW/cloud-environments#setup-scripts)。401如果雲端執行緒需要連線到內部 API 或私有套件登錄，或需要您的機器通常持有的 token，請變更環境而不是專案：請參閱[網路存取](/docs/zh-TW/cloud-environments#network-access)、[新增網路密鑰](/docs/zh-TW/cloud-environments#add-api-credentials)和[設定指令碼](/docs/zh-TW/cloud-environments#setup-scripts)。

402 402

403<h3 id="get-skills-plugins-connectors-and-tools-into-threads">403<h3 id="get-skills-plugins-connectors-and-tools-into-threads">

404 將技能、外掛程式、連接器和工具引入執行緒404 將技能、外掛程式、連接器和工具引入執行緒

590</h2>590</h2>

591 591

592* [在雲端使用 Claude Code](/docs/zh-TW/claude-code-on-the-web)：每個執行緒後面的雲端工作階段如何工作，包括 GitHub 存取選項和提取請求上的 auto-fix592* [在雲端使用 Claude Code](/docs/zh-TW/claude-code-on-the-web)：每個執行緒後面的雲端工作階段如何工作，包括 GitHub 存取選項和提取請求上的 auto-fix

593* [配置雲端環境](/docs/zh-TW/cloud-environments)：更改執行緒可以在網路上到達的內容、給予它們環境變數和 API 認證，以及使用設定指令碼安裝工具593* [設定雲端環境](/docs/zh-TW/cloud-environments)：變更雲端執行緒可在網路上存取的內容、為其提供環境變數和網路密鑰，以及使用設定指令碼安裝工具

594* [使用 routines 自動化工作](/docs/zh-TW/routines)：routines 的時間表、觸發器和管理，包括 Claude 從 project 建立的594* [使用 routines 自動化工作](/docs/zh-TW/routines)：routines 的時間表、觸發器和管理，包括 Claude 從 project 建立的

595* [使用代理檢視管理多個代理](/docs/zh-TW/agent-view)：當工作需要只有您的機器才能到達的工具或服務時，在您自己的機器上執行和跟蹤多個工作階段595* [使用代理檢視管理多個代理](/docs/zh-TW/agent-view)：當工作需要只有您的機器才能到達的工具或服務時，在您自己的機器上執行和跟蹤多個工作階段

596* [Projects 重新設計：從資料夾到對話](https://claude.com/blog/projects-redesigned)：啟動公告，帶有使 project 成為與 Claude 對話的思考596* [Projects 重新設計：從資料夾到對話](https://claude.com/blog/projects-redesigned)：啟動公告，帶有使 project 成為與 Claude 對話的思考

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` |

cloud-environments.md +68 −50

Details

10 雲端環境適用於 [雲端工作階段](/docs/zh-TW/claude-code-on-the-web)，該功能適用於 Pro、Max 和 Team 方案，以及具有 [premium seats 或 Chat + Claude Code seats](https://support.claude.com/en/articles/11845131-use-claude-code-with-your-team-or-enterprise-plan) 的 Enterprise 使用者。10 雲端環境適用於 [雲端工作階段](/docs/zh-TW/claude-code-on-the-web)，該功能適用於 Pro、Max 和 Team 方案，以及具有 [premium seats 或 Chat + Claude Code seats](https://support.claude.com/en/articles/11845131-use-claude-code-with-your-team-or-enterprise-plan) 的 Enterprise 使用者。

11</Note>11</Note>

12 12

13每個 [雲端工作階段](/docs/zh-TW/claude-code-on-the-web) 都在雲端環境中執行。您可以設定環境以允許或拒絕 [網路存取](#access-levels)、[為工作階段設定環境變數](#set-environment-variables)，在 Pro 和 Max 方案上儲存工作階段使用的 [API 認證](#add-api-credentials) 而不會看到它們，以及在 Claude 開始工作前執行 [設定指令碼](#setup-scripts)。13每個 [雲端工作階段](/docs/zh-TW/claude-code-on-the-web) 都在雲端環境中執行。您可以設定環境以允許或拒絕 [網路存取](#access-levels)、[為工作階段設定環境變數](#set-environment-variables)，在 Pro 和 Max 方案上儲存工作階段可使用但無法看到的 [網路機密](#add-api-credentials)，以及在 Claude 開始工作前執行 [設定指令碼](#setup-scripts)。

14 14

15相同的環境適用於您啟動雲端工作階段的任何地方：[Desktop 應用程式](/docs/zh-TW/desktop)、[Claude 行動應用程式](/docs/zh-TW/mobile)、您的瀏覽器在 [claude.ai/code](https://claude.ai/code)、終端機搭配 [`claude --cloud`](/docs/zh-TW/claude-code-on-the-web#from-terminal-to-cloud)、[routines](/docs/zh-TW/routines) 和 [Claude Tag](https://claude.com/docs/claude-tag/overview)。這些介面中的每一個也可以路由到 [自託管環境](/docs/zh-TW/self-hosted-environments)。[可用性和限制](/docs/zh-TW/self-hosted-environments#availability-and-limitations) 涵蓋當 Claude Tag 工作階段在其中執行時 Claude 尚無法使用的內容。15相同的環境適用於您啟動雲端工作階段的任何地方：[Desktop 應用程式](/docs/zh-TW/desktop)、[Claude 行動應用程式](/docs/zh-TW/mobile)、您的瀏覽器在 [claude.ai/code](https://claude.ai/code)、終端機搭配 [`claude --cloud`](/docs/zh-TW/claude-code-on-the-web#from-terminal-to-cloud)、[routines](/docs/zh-TW/routines) 和 [Claude Tag](https://claude.com/docs/claude-tag/overview)。這些介面中的每一個也可以路由到 [自託管環境](/docs/zh-TW/self-hosted-environments)。[可用性和限制](/docs/zh-TW/self-hosted-environments#availability-and-limitations) 涵蓋當 Claude Tag 工作階段在其中執行時 Claude 尚無法使用的內容。

16 16

58 <Step title="新增或編輯環境">58 <Step title="新增或編輯環境">

59 選擇**雲端**以列出您的環境。然後選擇**新增雲端環境**，或將滑鼠懸停在現有環境上，然後選擇右側出現的設定圖示。59 選擇**雲端**以列出您的環境。然後選擇**新增雲端環境**，或將滑鼠懸停在現有環境上，然後選擇右側出現的設定圖示。

60 60

61 對話框包括名稱、網路存取層級、環境變數和設定指令碼。當您在 Pro 或 Max 方案上編輯現有的雲端環境時，對話框還包括 [API 認證](#add-api-credentials)。61 對話框包括名稱、網路存取層級、環境變數和設定指令碼。當您在 Pro 或 Max 方案上編輯現有的雲端環境時，對話框還包括[網路機密](#add-api-credentials)。

62 62

63 <Frame>63 <Frame>

64 <img src="https://mintcdn.com/claude-code/ZFId6l95856c5LSw/images/cloud-environment-dialog.png?fit=max&auto=format&n=ZFId6l95856c5LSw&q=85&s=30d4478b31d1f879f7ee287ddab32505" alt="新增雲端環境對話框。名稱欄位，預留位置為「預設」；網路存取選擇器設定為「信任」，並包含網路政策和存取層級的連結；環境變數框顯示 .env 格式的預留位置文字，並附註值對使用該環境的任何人都可見；設定指令碼框描述為 Bash 指令碼，在新工作階段啟動時執行，在 Claude Code 啟動前執行；以及「取消」和「建立環境」按鈕。" width="874" height="1372" data-path="images/cloud-environment-dialog.png" />64 <img src="https://mintcdn.com/claude-code/ZFId6l95856c5LSw/images/cloud-environment-dialog.png?fit=max&auto=format&n=ZFId6l95856c5LSw&q=85&s=30d4478b31d1f879f7ee287ddab32505" alt="新增雲端環境對話框。名稱欄位，預留位置為「預設」；網路存取選擇器設定為「信任」，並包含網路政策和存取層級的連結；環境變數框顯示 .env 格式的預留位置文字，並附註值對使用該環境的任何人都可見；設定指令碼框描述為 Bash 指令碼，在新工作階段啟動時執行，在 Claude Code 啟動前執行；以及「取消」和「建立環境」按鈕。" width="874" height="1372" data-path="images/cloud-environment-dialog.png" />

91 91

92雲端工作階段在啟動時也會自行設定一些變數。對於 [`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`](/docs/zh-TW/claude-code-on-the-web#manage-context)，工作階段設定的值會覆蓋您在此新增的值，因此在此新增該金鑰沒有效果。92雲端工作階段在啟動時也會自行設定一些變數。對於 [`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`](/docs/zh-TW/claude-code-on-the-web#manage-context)，工作階段設定的值會覆蓋您在此新增的值，因此在此新增該金鑰沒有效果。

93 93

94使用該環境的任何人都可以讀取這些值。在 Pro 和 Max 方案上，改為使用 [API 認證](#add-api-credentials)來取得代理程式可以附加到請求的金鑰。[永遠不會取得認證的請求](#requests-that-never-get-the-credential)列在那裡。94使用該環境的任何人都可以讀取這些值。在 Pro 和 Max 方案上，對於 agent 代理伺服器可以附加到請求的金鑰，請改用[網路機密](#add-api-credentials)。[永遠不會取得機密的請求](#requests-that-never-get-the-credential)列在那裡。

95 95

96<h3 id="add-api-credentials">96<h3 id="add-api-credentials">

~~97 新增 API 認證~~97 新增網路機密

98</h3>98</h3>

99 99

100API 認證是您儲存在雲端環境上的 API 金鑰或權杖，以便 Claude 可以從環境中的任何工作階段呼叫該 API，而無需查看金鑰。Anthropic 的代理程式會在每個請求離開工作階段的 VM 後，將金鑰新增到您列出的主機的請求中。金鑰永遠不會到達 Claude、它執行的命令或工作階段的環境變數。100網路機密是您儲存在雲端環境上的 API 金鑰或 token，以便 Claude 可以從環境中的任何工作階段呼叫該 API，而無需看到金鑰。Anthropic 的 agent 代理伺服器會在每個請求離開工作階段的 VM 後，將金鑰新增到您列出的主機的請求中。金鑰永遠不會到達 Claude、它執行的命令或工作階段的環境變數。

101 101

102API 認證在 Pro 和 Max 方案上可用。它們在 Team 或 Enterprise 方案上尚不可用，因此 **API 認證**區段不會出現在這些方案的環境對話框中。102網路機密在 Pro 和 Max 方案上可用。它們在 Team 或 Enterprise 方案上尚不可用，因此**網路機密**區段不會出現在這些方案的環境對話框中。

103 103

104<h4 id="requirements">104<h4 id="requirements">

105 需求105 需求

106</h4>106</h4>

107 107

108其中兩個決定您是否可以新增認證，另外兩個決定代理程式在新增後是否可以使用它：108其中兩個決定您是否可以新增機密，另外兩個決定 agent 代理伺服器在新增後是否可以使用它：

109 109

110* **角色**：您的 claude.ai 組織中的組織管理員角色110* **角色**：您的 claude.ai 組織中的組織管理員角色

111 * 在 Team 和 Enterprise 上，擁有者持有它，管理員沒有111 * 在 Team 和 Enterprise 上，擁有者持有它，管理員沒有

112 * 在 Pro 和 Max 上，您在自己的組織中持有它112 * 在 Pro 和 Max 上，您在自己的組織中持有它

113* **環境類型**：已存在的 Anthropic 託管雲端環境。[自託管環境](/docs/zh-TW/self-hosted-environments)沒有 API 認證113* **環境類型**：已存在的 Anthropic 託管雲端環境。[自託管環境](/docs/zh-TW/self-hosted-environments)沒有網路機密

114* **API 可達性**：API 接受來自網際網路的連線，因為請求來自 Anthropic 的網路114* **API 可達性**：API 接受來自網際網路的連線，因為請求來自 Anthropic 的網路

115* **加密金鑰**：如果您的組織使用客戶管理的加密金鑰，您無法儲存認證115* **加密金鑰**：如果您的組織使用客戶管理的加密金鑰，您無法儲存網路機密

116 116

117<h4 id="add-a-credential">117<h4 id="add-a-credential">

118 新增認證118 新增機密

119</h4>119</h4>

120 120

121您一次新增一個憑證，新增後無法編輯憑證。若要變更憑證的主機或值，請刪除它並再次新增。121您一次新增一個機密，新增後無法編輯機密。若要變更機密的主機或值，請刪除它並再次新增。

122 122

123<Steps>123<Steps>

124 <Step title="開啟環境的 API 憑證">124 <Step title="開啟環境的網路機密">

125 在 [claude.ai/code](https://claude.ai/code) [開啟環境進行編輯](#configure-your-environment)。在**編輯環境**對話框中，找到 **API 憑證**區段。您會看到環境上已有的憑證，每個都顯示它適用的主機。125 在 [claude.ai/code](https://claude.ai/code) [開啟環境進行編輯](#configure-your-environment)。在**編輯環境**對話框中，找到**網路機密**區段。您會看到環境上已有的機密，每個都顯示它適用的主機。

126 </Step>126 </Step>

127 127

128 <Step title="新增憑證">128 <Step title="新增機密">

129 選擇**新增憑證**並填寫表單。保留預設的**憑證類型** **Bearer**，用於在請求標頭中傳輸的 API 金鑰，並填寫這些欄位：129 選擇**新增機密**並填寫表單。保留預設的**憑證類型** **Bearer**，用於在請求標頭中傳輸的 API 金鑰，並填寫這些欄位：

130 130

131 * **名稱**：認證的標籤，例如 `Internal billing API`131 * **名稱**：機密的標籤，例如 `Internal billing API`

132 * **允許的網站**：API 的主機，例如 `api.example.com`。前導 `*.` 符合每個子網域132 * **允許的網站**：API 的主機，例如 `api.example.com`。前導 `*.` 符合每個子網域

133 * **自訂標頭**：標頭的一列，該標頭攜帶金鑰。該列以 `Authorization` 作為標頭的**名稱**和 `Bearer` 作為其**前綴**開始；將金鑰本身貼上為**值**。對於採用裸值的標頭（如 `X-Api-Key`），變更名稱並清除前綴133 * **自訂標頭**：標頭的一列，該標頭攜帶金鑰。該列以 `Authorization` 作為標頭的**名稱**和 `Bearer` 作為其**前綴**開始；將金鑰本身貼上為**值**。對於採用裸值的標頭（如 `X-Api-Key`），變更名稱並清除前綴

134 134

135 對於以其他方式進行身份驗證的 API，請選擇不同的**認證類型**。清單與 [Claude Tag](https://claude.com/docs/claude-tag/overview)（Team 和 Enterprise 方案的 Slack 整合）為[連線](https://claude.com/docs/claude-tag/admins/add-connections)提供的清單相同。135 對於以其他方式進行身分驗證的 API，請選擇不同的**憑證類型**。清單與 [Claude Tag](https://claude.com/docs/claude-tag/overview)（Team 和 Enterprise 方案的 Slack 整合）為[連線](https://claude.com/docs/claude-tag/admins/add-connections)提供的清單相同。

136 </Step>136 </Step>

137 137

138 <Step title="儲存認證">138 <Step title="儲存機密">

139 選擇**連線**。認證出現在清單中，其主機已儲存，無需對話框的**儲存變更**按鈕。儲存後，您無法再次檢視該值。139 選擇**連線**。機密連同其主機出現在清單中，無需對話框的**儲存變更**按鈕即已儲存。儲存後，您無法再次檢視該值。

140 </Step>140 </Step>

141</Steps>141</Steps>

142 142

143若要確認認證有效，請在環境中啟動工作階段並要求 Claude 呼叫 API，例如使用 `curl`。API 的回應就像金鑰在請求中一樣，金鑰不會出現在工作階段的環境變數或任何檔案中。如果清單將認證標記為**未傳送**，其下方的註記會說明原因和解決方法。兩個主機重疊但不完全相符的認證不會獲得標記，代理程式只會傳送其中一個。143若要確認機密有效，請在環境中啟動工作階段並要求 Claude 呼叫 API，例如使用 `curl`。API 的回應就像金鑰在請求中一樣，金鑰不會出現在工作階段的環境變數或任何檔案中。如果清單將機密標記為**未傳送**，其下方的註記會說明原因和解決方法。兩個主機重疊但不完全相符的機密不會獲得標記，agent 代理伺服器只會傳送其中一個。

144 144

145<h4 id="which-requests-get-the-credential">145<h4 id="which-requests-get-the-credential">

146 哪些請求會取得認證146 哪些請求會取得機密

147</h4>147</h4>

148 148

149當請求的主機符合您在該認證上列出的主機之一時，代理程式會將認證附加到請求。工作階段可以到達這些主機，即使環境的[網路存取層級](#access-levels)否則不允許，除了[永遠不會取得認證的主機](#requests-that-never-get-the-credential)。認證適用於在環境中執行的每個工作階段，無論誰啟動它，直到您刪除它。149當請求的主機符合您在該機密上列出的主機之一時，agent 代理伺服器會將機密附加到請求。工作階段可以到達這些主機，即使環境的[網路存取層級](#access-levels)否則不允許，除了[永遠不會取得機密的主機](#requests-that-never-get-the-credential)。機密適用於在環境中執行的每個工作階段，無論誰啟動它，直到您刪除它。

150 150

151<h4 id="requests-that-never-get-the-credential">151<h4 id="requests-that-never-get-the-credential">

152 永遠不會取得認證的請求152 永遠不會取得機密的請求

153</h4>153</h4>

154 154

155代理程式永遠不會將您新增的認證附加到這些請求：155agent 代理伺服器永遠不會將您新增的機密附加到這些請求：

156 156

157* **GitHub**：[GitHub 代理程式](#github-proxy)改為驗證對 GitHub 的請求，因此您不需要為其提供 API 認證157* **GitHub**：[GitHub 代理伺服器](#github-proxy)改為驗證對 GitHub 的請求，因此您不需要為其提供網路機密

158* **Anthropic API 和公開套件登錄**：`api.anthropic.com`、`registry.npmjs.org`、`jsr.io`、`npm.jsr.io`、`pypi.org`、`files.pythonhosted.org`、`index.crates.io` 和 `proxy.golang.org`158* **Anthropic API 和公開套件登錄**：`api.anthropic.com`、`registry.npmjs.org`、`jsr.io`、`npm.jsr.io`、`pypi.org`、`files.pythonhosted.org`、`index.crates.io` 和 `proxy.golang.org`

159* **設定指令碼請求**：Claude Code 在啟動時連線到代理程式，在[設定指令碼](#setup-scripts)執行後159* **設定指令碼請求**：Claude Code 在啟動時連線到代理程式，在[設定指令碼](#setup-scripts)執行後

160* **Claude Code 的遙測匯出**：Claude Code 自行傳送其[遙測匯出](/docs/zh-TW/monitoring-usage#telemetry-from-cloud-sessions-and-claude-tag)，而不是透過它執行的命令，該請求不會通過代理程式160* **Claude Code 的遙測匯出**：Claude Code 自行傳送其[遙測匯出](/docs/zh-TW/monitoring-usage#telemetry-from-cloud-sessions-and-claude-tag)，而不是透過它執行的命令，該請求不會通過代理程式

179 179

180* 已在環境中執行的工作階段會繼續工作。180* 已在環境中執行的工作階段會繼續工作。

181* 環境從選擇器和 `/remote-env` 中消失，因此您無法為新工作階段選擇它。181* 環境從選擇器和 `/remote-env` 中消失，因此您無法為新工作階段選擇它。

182* 環境上的 API 認證在其執行中的工作階段中保持附加。在封存前刪除您不再需要的任何認證。182* 環境上的網路機密在其執行中的工作階段中保持附加。在封存前刪除您不再需要的任何機密。

183* 沒有新工作階段可以在任何表面上的封存環境中啟動。如果環境是您儲存的 [CLI 預設](#select-an-environment-from-the-cli)，當您的清單有一個時，Claude Code 會在 Anthropic 託管環境中啟動 CLI 雲端工作階段，否則在清單中不是[遠端控制橋接環境](#the-default-environment)的第一個環境中啟動。任何明確使用環境設定的內容，例如[例行程序](/docs/zh-TW/routines#environments-and-network-access)，無法在其中啟動新工作階段。將其指向另一個環境。183* 沒有新工作階段可以在任何表面上的封存環境中啟動。如果環境是您儲存的 [CLI 預設](#select-an-environment-from-the-cli)，當您的清單有一個時，Claude Code 會在 Anthropic 託管環境中啟動 CLI 雲端工作階段，否則在清單中不是[遠端控制橋接環境](#the-default-environment)的第一個環境中啟動。任何明確使用環境設定的內容，例如[例行程序](/docs/zh-TW/routines#environments-and-network-access)，無法在其中啟動新工作階段。將其指向另一個環境。

184 184

185<h3 id="organization-shared-environments">185<h3 id="organization-shared-environments">

197 197

198擁有者在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 分別選擇組織的[預設環境](#the-default-environment)。198擁有者在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 分別選擇組織的[預設環境](#the-default-environment)。

199 199

200每個成員在共用環境中的工作階段都會讀取其變數，因此不要在其中包含機密。[API 認證](#add-api-credentials)（為工作階段提供它們無法讀取的金鑰）在 Team 或 Enterprise 方案上尚不可用。200每個成員在共用環境中的工作階段都會讀取其變數，因此不要在其中包含機密。[網路機密](#add-api-credentials)（為工作階段提供它們無法讀取的金鑰）在 Team 或 Enterprise 方案上尚不可用。

201 201

202<h3 id="set-the-environment-a-claude-tag-channel-uses">202<h3 id="set-the-environment-a-claude-tag-channel-uses">

203 設定 Claude Tag 頻道使用的環境203 設定 Claude Tag 頻道使用的環境

239 239

240* GitHub，透過其[單獨的代理](#github-proxy)240* GitHub，透過其[單獨的代理](#github-proxy)

241* 您啟用的 [MCP 連接器](#network-access)，其流量通過 Anthropic 的伺服器241* 您啟用的 [MCP 連接器](#network-access)，其流量通過 Anthropic 的伺服器

242* 您在環境的 [API 認證](#add-api-credentials)上列出的主機，除了[永遠不會取得認證的主機](#requests-that-never-get-the-credential)242* 您在環境的[網路密鑰](#add-api-credentials)上列出的主機，除了[永遠不會取得密鑰的主機](#requests-that-never-get-the-credential)

243* Anthropic API，用於 Claude Code 自己的請求，即使在 **None** 時，如[安全性和隔離](/docs/zh-TW/claude-code-on-the-web#security-and-isolation)下所述243* Anthropic API，用於 Claude Code 自己的請求，即使在 **None** 時，如[安全性和隔離](/docs/zh-TW/claude-code-on-the-web#security-and-isolation)下所述

244 244

245<h3 id="allow-specific-domains">245<h3 id="allow-specific-domains">

254registry.example.com254registry.example.com

255```255```

256 256

257此環境中的工作階段現在可以到達 `api.example.com`、`internal.example.com` 的任何子網域和 `registry.example.com`，以及透過工作階段網路沒有其他網域。[GitHub 流量](#github-proxy)、[MCP 連接器流量](#network-access)和對環境 [API 認證](#add-api-credentials)主機的請求（除了[永遠不會取得認證的主機](#requests-that-never-get-the-credential)）不通過此允許清單。前導 `*.` 符合每個子網域。若要也保留[Trusted 網域](#default-allowed-domains)，請勾選 **Also include default list of common package managers**；取消勾選以僅允許您列出的內容。257此環境中的工作階段現在可以到達 `api.example.com`、`internal.example.com` 的任何子網域和 `registry.example.com`，以及透過工作階段網路沒有其他網域。[GitHub 流量](#github-proxy)、[MCP 連接器流量](#network-access)和對環境[網路密鑰](#add-api-credentials)主機的請求（除了[永遠不會取得密鑰的主機](#requests-that-never-get-the-credential)）不通過此允許清單。前導 `*.` 符合每個子網域。若要也保留[Trusted 網域](#default-allowed-domains)，請勾選 **Also include default list of common package managers**；取消勾選以僅允許您列出的內容。

258 258

259如果您的組織使用[成品](/docs/zh-TW/artifacts#availability)，工作階段讀取它們不需要 `*.frame.claudeusercontent.com` 在清單中。當清單省略該主機時，Claude Code 改為透過工作階段與 Anthropic 的連線讀取成品內容。在兩種情況下將主機保留在允許清單中：259如果您的組織使用[成品](/docs/zh-TW/artifacts#availability)，工作階段讀取它們不需要 `*.frame.claudeusercontent.com` 在清單中。當清單省略該主機時，Claude Code 改為透過工作階段與 Anthropic 的連線讀取成品內容。在兩種情況下將主機保留在允許清單中：

260 260

292 雲端工作階段中可用的功能292 雲端工作階段中可用的功能

293</h2>293</h2>

294 294

295在 Anthropic 代管的環境中，每個工作階段都會取得一個執行 Ubuntu 24.04 on x86\_64 的全新虛擬機器 (VM)，無論您自己的作業系統和 CPU 架構為何，您的儲存庫已複製且常見工具鏈已預先安裝。當依賴項提供預編譯的二進位檔案（例如具有原生擴充功能的 Ruby gems 或預先建置的 Python wheels）時，請使用其 x86\_64 Linux 建置以符合 VM。本節涵蓋 Anthropic 代管的預設值、內建的 GitHub 工具、如何[執行測試和服務](#run-tests-start-services-and-add-packages)、每個 VM 取得的[資源限制](#resource-limits)，以及[時間限制](#time-limits)對長時間執行的工作。295在 Anthropic 代管的環境中，每個工作階段都會取得一個執行 Ubuntu 24.04 on x86\_64 的全新虛擬機器 (VM)，無論您自己的作業系統和 CPU 架構為何，您的儲存庫已複製且常見工具鏈已預先安裝。當相依套件提供預編譯的二進位檔案（例如具有原生擴充功能的 Ruby gems 或預先建置的 Python wheels）時，請使用其 x86\_64 Linux 建置以符合 VM。本節涵蓋 Anthropic 代管的預設值、內建的 GitHub 工具、如何[執行測試和服務](#run-tests-start-services-and-add-packages)、每個 VM 取得的[資源限制](#resource-limits)，以及[時間限制](#time-limits)對長時間執行的工作。

296 296

297<Note>297<Note>

298 您的組織路由到[自我代管環境](/docs/zh-TW/self-hosted-environments)的工作階段改為在您自己的執行器上執行，使用您的執行器映像提供的工具。298 您的組織路由到[自我代管環境](/docs/zh-TW/self-hosted-environments)的工作階段改為在您自己的執行器上執行，使用您的執行器映像提供的工具。

307| | 在雲端工作階段中可用 | 原因 |307| | 在雲端工作階段中可用 | 原因 |

308| :- | :- | :- |308| :- | :- | :- |

309| 您儲存庫的 `CLAUDE.md` | 是 | 複製的一部分 |309| 您儲存庫的 `CLAUDE.md` | 是 | 複製的一部分 |

310| 您儲存庫的 `.claude/settings.json` hooks 和權限規則 | 是，在具有一個儲存庫的工作階段中 | 複製的一部分。具有多個儲存庫的工作階段（包括[專案](/docs/zh-TW/claude-projects#what-threads-pick-up-from-your-repositories)執行緒）在複製上方開始，不讀取它們 |310| 您儲存庫的 `.claude/settings.json` hook 和權限規則 | 是，在具有一個儲存庫的工作階段中 | 複製的一部分。具有多個儲存庫的工作階段（包括[專案](/docs/zh-TW/claude-projects#what-threads-pick-up-from-your-repositories)執行緒）在複製上方開始，不讀取它們 |

312| 您儲存庫的 `.claude/rules/` | 是 | 複製的一部分 |312| 您儲存庫的 `.claude/rules/` | 是 | 複製的一部分 |

313| 您儲存庫的 `.claude/skills/`、`.claude/agents/`、`.claude/commands/` | 是 | 複製的一部分 |313| 您儲存庫的 `.claude/skills/`、`.claude/agents/`、`.claude/commands/` | 是 | 複製的一部分 |

314| 在您儲存庫的 `.claude/settings.json` 中宣告的外掛程式和市集 | 否 | 雲端工作階段不會安裝儲存庫在 [`enabledPlugins`](/docs/zh-TW/settings-reference#enabledplugins) 下開啟的外掛程式，包括來自它在 [`extraKnownMarketplaces`](/docs/zh-TW/settings-reference#extraknownmarketplaces) 下列出的市集的外掛程式 |314| 在您儲存庫的 `.claude/settings.json` 中宣告的外掛程式和市集 | 否 | 雲端工作階段不會安裝儲存庫在 [`enabledPlugins`](/docs/zh-TW/settings-reference#enabledplugins) 下開啟的外掛程式，包括來自它在 [`extraKnownMarketplaces`](/docs/zh-TW/settings-reference#extraknownmarketplaces) 下列出的市集的外掛程式 |

315| 您的組織的[伺服器管理的設定](/docs/zh-TW/server-managed-settings) | 是，除了在 [Claude Tag](https://claude.com/docs/claude-tag/overview) 工作階段中 | 在工作階段開始時從 Anthropic 的伺服器擷取。請參閱[表面涵蓋範圍](/docs/zh-TW/model-config#surface-coverage)以了解 `availableModels` 如何在雲端工作階段中強制執行。透過 MDM 或受管設定檔部署到您的裝置的設定不適用，因為工作階段在 Anthropic 管理的 VM 上執行；在[自我代管環境](/docs/zh-TW/self-hosted-environments)中，工作階段也會根據[Claude Code 如何結合受管來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)讀取執行器映像中的受管設定檔 |315| 您的組織的[伺服器管理的設定](/docs/zh-TW/server-managed-settings) | 是，除了在 [Claude Tag](https://claude.com/docs/claude-tag/overview) 工作階段中 | 在工作階段開始時從 Anthropic 的伺服器擷取。請參閱[使用介面涵蓋範圍](/docs/zh-TW/model-config#surface-coverage)以了解 `availableModels` 如何在雲端工作階段中強制執行。透過 MDM 或受管設定檔部署到您的裝置的設定不適用，因為工作階段在 Anthropic 管理的 VM 上執行；在[自我代管環境](/docs/zh-TW/self-hosted-environments)中，工作階段也會根據[Claude Code 如何結合受管來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)讀取執行器映像中的受管設定檔 |

316| 您的使用者 `~/.claude/CLAUDE.md` | 否 | 位於您的機器上，不在儲存庫中 |316| 您的使用者 `~/.claude/CLAUDE.md` | 否 | 位於您的機器上，不在儲存庫中。請參閱[在不提交到儲存庫的情況下新增個人偏好設定](#add-personal-preferences-without-committing-to-the-repo) |

317| 您的使用者 `~/.claude/skills/`、`~/.claude/agents/`、`~/.claude/commands/` | 否 | 位於您的機器上，不在儲存庫中。改為將它們提交到儲存庫的 `.claude/` 目錄。雲端工作階段會自動載入您在 claude.ai 上啟用的技能 |317| 您的使用者 `~/.claude/skills/`、`~/.claude/agents/`、`~/.claude/commands/` | 否 | 位於您的機器上，不在儲存庫中。改為將它們提交到儲存庫的 `.claude/` 目錄。雲端工作階段會自動載入您在 claude.ai 上啟用的 skill |

318| 僅在您的使用者設定中啟用的外掛程式 | 否 | 使用者範圍的 `enabledPlugins` 位於您機器上的 `~/.claude/settings.json` 中 |318| 僅在您的使用者設定中啟用的外掛程式 | 否 | 使用者範圍的 `enabledPlugins` 位於您機器上的 `~/.claude/settings.json` 中 |

319| 您使用 `claude mcp add` 在預設本機範圍或使用者範圍新增的 MCP 伺服器 | 否 | 這些寫入您機器上的 `~/.claude.json`，不是儲存庫。使用 `claude mcp add --scope project` 新增伺服器，它會寫入儲存庫的 [`.mcp.json`](/docs/zh-TW/mcp#project-scope)，並提交該檔案。具有一個儲存庫的工作階段會載入它 |319| 您使用 `claude mcp add` 在預設本機範圍或使用者範圍新增的 MCP 伺服器 | 否 | 這些寫入您機器上的 `~/.claude.json`，不是儲存庫。使用 `claude mcp add --scope project` 新增伺服器，它會寫入儲存庫的 [`.mcp.json`](/docs/zh-TW/mcp#project-scope)，並提交該檔案。具有一個儲存庫的工作階段會載入它 |

320| 您儲存庫的 `.claude/settings.json` `env` 區塊中的傳輸變數，例如 `NODE_EXTRA_CA_CERTS` 和[mTLS 用戶端憑證變數](/docs/zh-TW/network-config#mtls-authentication) | 否 | 代管環境管理工作階段的 API 連線，因此 Claude Code 會忽略這些金鑰，並在工作階段的偵錯日誌中記錄每個被忽略的金鑰 |320| 您儲存庫的 `.claude/settings.json` `env` 區塊中的傳輸變數，例如 `NODE_EXTRA_CA_CERTS` 和[mTLS 用戶端憑證變數](/docs/zh-TW/network-config#mtls-authentication) | 否 | 代管環境管理工作階段的 API 連線，因此 Claude Code 會忽略這些金鑰，並在工作階段的偵錯日誌中記錄每個被忽略的金鑰 |

321| Claude 呼叫的服務的 API 金鑰和權杖 | 在 Pro 和 Max 方案上，作為 [API 認證](#add-api-credentials) | 您在環境上新增金鑰一次，代理程式代理會將其附加到您列出的主機的請求。代理程式代理[無法附加](#requests-that-never-get-the-credential)的金鑰，或 Team 或 Enterprise 方案上的任何金鑰，都保留在環境變數中 |321| Claude 呼叫的服務的 API 金鑰和 token | 在 Pro 和 Max 方案上，作為[網路機密](#add-api-credentials) | 您在環境上新增金鑰一次，agent 代理伺服器會將其附加到您列出的主機的請求。agent 代理伺服器[無法附加](#requests-that-never-get-the-credential)的金鑰，或 Team 或 Enterprise 方案上的任何金鑰，都保留在環境變數中 |

322| 像 AWS SSO 這樣的互動式驗證 | 否 | 不支援。SSO 需要無法在雲端工作階段中執行的瀏覽器型登入 |322| 像 AWS SSO 這樣的互動式驗證 | 否 | 不支援。SSO 需要無法在雲端工作階段中執行的瀏覽器型登入 |

323 323

324若要在雲端工作階段中提供您自己的設定，請將其提交到儲存庫。324若要在雲端工作階段中提供您自己的設定，請將其提交到儲存庫。

325 325

326任何使用環境的人都可以讀取其環境變數和設定指令碼。**環境變數**下的對話方塊註記會說明這一點，並警告不要在那裡放置機密。在 Pro 和 Max 方案上，改為將代理程式代理可以附加的金鑰儲存為 [API 認證](#add-api-credentials)。326任何使用環境的人都可以讀取其環境變數和設定指令碼。**環境變數**下的對話方塊註記會說明這一點，並警告不要在那裡放置機密。在 Pro 和 Max 方案上，改為將 agent 代理伺服器可以附加的金鑰儲存為[網路機密](#add-api-credentials)。

327

328<h4 id="add-personal-preferences-without-committing-to-the-repo">

329 在不提交到儲存庫的情況下新增個人偏好設定

330</h4>

331

332在 Anthropic 代管的環境中，新增一個寫入 `~/.claude/CLAUDE.md` 的[設定指令碼](#setup-scripts)，用於存放您不想放入共用儲存庫的偏好設定。Claude Code 會在工作階段中將該檔案載入為[使用者指令](/docs/zh-TW/memory#choose-where-to-put-claude-md-files)。此範例設定了提交訊息的偏好：

333

334```bash theme={null}

335#!/bin/bash

336mkdir -p ~/.claude

337cat > ~/.claude/CLAUDE.md <<'EOF'

338Use conventional commit messages.

339EOF

340```

341

342請將指令碼放在您自己的其中一個環境上，而不是[共用環境](#organization-shared-environments)。

343

344在下一個雲端工作階段中執行 `/context`，並確認 `/root/.claude/CLAUDE.md` 出現在 **Memory files** 下。

327 345

328<h3 id="installed-tools">346<h3 id="installed-tools">

329 已安裝的工具347 已安裝的工具

345| **Databases** | PostgreSQL 16、Redis 7.0 |363| **Databases** | PostgreSQL 16、Redis 7.0 |

346| **Utilities** | git、gh、jq、yq、ripgrep、tmux、vim、nano |364| **Utilities** | git、gh、jq、yq、ripgrep、tmux、vim、nano |

347 365

348¹ Bun 已安裝，但在套件擷取時有已知的[代理相容性問題](#install-dependencies-with-a-sessionstart-hook)。366¹ Bun 已安裝，但在套件擷取時有已知的[代理伺服器相容性問題](#install-dependencies-with-a-sessionstart-hook)。

349 367

350若要取得此表中大多數工具的版本，請要求 Claude 在雲端工作階段中執行 `check-tools`。這是安裝在工作階段 VM 上的 shell 命令，不是您使用 `/` 輸入的命令；您要求 Claude 是因為 [Claude 為您執行所有 VM 命令](#run-tests-start-services-and-add-packages)。對於它不報告的工具，例如 Ruby、PHP、bun、PostgreSQL 或 Redis，請要求 Claude 執行該工具自己的版本命令，例如 `psql --version`。368若要取得此表中大多數工具的版本，請要求 Claude 在雲端工作階段中執行 `check-tools`。這是安裝在工作階段 VM 上的 shell 命令，不是您使用 `/` 輸入的命令；您要求 Claude 是因為 [Claude 為您執行所有 VM 命令](#run-tests-start-services-and-add-packages)。對於它不報告的工具，例如 Ruby、PHP、bun、PostgreSQL 或 Redis，請要求 Claude 執行該工具自己的版本命令，例如 `psql --version`。

351 369

354此清單外的工具鏈（例如 .NET SDK）即使其套件登錄在[預設允許清單](#default-allowed-domains)上也不會預先安裝。使用[設定指令碼](#setup-scripts)安裝它們。372此清單外的工具鏈（例如 .NET SDK）即使其套件登錄在[預設允許清單](#default-allowed-domains)上也不會預先安裝。使用[設定指令碼](#setup-scripts)安裝它們。

355 373

356<h3 id="work-with-github-issues-and-pull-requests">374<h3 id="work-with-github-issues-and-pull-requests">

357 使用 GitHub 問題和提取要求375 使用 GitHub issue 和 pull request

358</h3>376</h3>

359 377

360雲端工作階段包括內建的 GitHub 工具，讓 Claude 可以讀取問題、列出提取要求、擷取差異和發佈評論，無需任何設定。這些工具透過[GitHub 代理](#github-proxy)進行驗證，使用您在 [GitHub 驗證選項](/docs/zh-TW/claude-code-on-the-web#github-authentication-options)下設定的任何方法，因此您的權杖永遠不會進入容器。378雲端工作階段包括內建的 GitHub 工具，讓 Claude 可以讀取 issue、列出 pull request、擷取差異和發佈評論，無需任何設定。這些工具透過 [GitHub 代理伺服器](#github-proxy)進行身分驗證，使用您在 [GitHub 驗證選項](/docs/zh-TW/claude-code-on-the-web#github-authentication-options)下設定的任何方法，因此您的 token 永遠不會進入容器。

361 379

362您可以在[環境設定](#set-environment-variables)中自己設定 `GH_TOKEN` 或 `GITHUB_TOKEN`，或將兩者都保留未設定，讓 [GitHub 代理](#github-proxy)為您進行驗證：380您可以在[環境設定](#set-environment-variables)中自己設定 `GH_TOKEN` 或 `GITHUB_TOKEN`，或將兩者都保留未設定，讓 [GitHub 代理伺服器](#github-proxy)為您進行身分驗證：

363 381

364* 如果您設定了權杖，它會原封不動地傳遞到容器，因此您的指令碼和 GitHub 的 [`gh` CLI](https://cli.github.com) 會直接使用它。382* 如果您設定了 token，它會原封不動地傳遞到容器，因此您的指令碼和 GitHub 的 [`gh` CLI](https://cli.github.com) 會直接使用它。

365* 如果您都沒有設定，且 [GitHub 代理](#github-proxy) 正在為您的工作階段處理驗證，兩個變數在 Claude 執行的命令中都讀取為佔位符字串 `proxy-injected`，代理會在出站 GitHub 請求上替換您的真實認證。`gh` 無需您自己的權杖即可運作，但直接讀取 `GITHUB_TOKEN` 的指令碼會取得佔位符，而不是可用的權杖。383* 如果您都沒有設定，且 [GitHub 代理伺服器](#github-proxy)正在為您的工作階段處理身分驗證，兩個變數在 Claude 執行的命令中都讀取為佔位符字串 `proxy-injected`，代理伺服器會在出站 GitHub 請求上替換您的真實憑證。`gh` 無需您自己的 token 即可運作，但直接讀取 `GITHUB_TOKEN` 的指令碼會取得佔位符，而不是可用的 token。

366 384

367您設定的權杖是一個普通的環境變數，因此任何使用環境的人都可以讀取它；代理路徑將認證保留在環境設定和工作階段 VM 之外。385您設定的 token 是一個普通的環境變數，因此任何使用環境的人都可以讀取它；代理伺服器路徑將憑證保留在環境設定和工作階段 VM 之外。

368 386

369若要檢查哪種情況適用於您的工作階段，請要求 Claude 執行 `echo $GH_TOKEN`。387若要檢查哪種情況適用於您的工作階段，請要求 Claude 執行 `echo $GH_TOKEN`。

370 388

374 將輸出連結回工作階段392 將輸出連結回工作階段

375</h3>393</h3>

376 394

377每個雲端工作階段在 claude.ai 上都有一個文字記錄 URL，工作階段可以從 `CLAUDE_CODE_REMOTE_SESSION_ID` 環境變數讀取其自己的 ID。使用此功能在 PR 主體、提交訊息、Slack 貼文或產生的報告中放置可追蹤的連結，以便審查者可以開啟產生它們的執行。395每個雲端工作階段在 claude.ai 上都有一個逐字稿 URL，工作階段可以從 `CLAUDE_CODE_REMOTE_SESSION_ID` 環境變數讀取其自己的 ID。使用此功能在 PR 主體、提交訊息、Slack 貼文或產生的報告中放置可追蹤的連結，以便審查者可以開啟產生它們的執行。

378 396

379Claude 在雲端工作階段中建立的提交包括 `Claude-Session: <url>` git 預告片，PR 主體包括工作階段 URL 在其自己的行上。若要省略預告片和 PR 主體連結，請將 [`attribution.sessionUrl`](/docs/zh-TW/settings-reference#attribution-sessionurl) 設定為 `false`。397Claude 在雲端工作階段中建立的提交包括 `Claude-Session: <url>` git trailer，PR 主體包括工作階段 URL 在其自己的行上。若要省略 trailer 和 PR 主體連結，請將 [`attribution.sessionUrl`](/docs/zh-TW/settings-reference#attribution-sessionurl) 設定為 `false`。

380 398

381若要在提交或 PR 以外的內容中包含工作階段連結，例如 Claude 發佈的 Slack 訊息或它寫入的報告檔案，請讓 Claude 執行以下命令並使用其輸出。該命令將環境變數值中的 `cse_` 前置詞轉換為文字記錄 URL 預期的 `session_` 前置詞：399若要在提交或 PR 以外的內容中包含工作階段連結，例如 Claude 發佈的 Slack 訊息或它寫入的報告檔案，請讓 Claude 執行以下命令並使用其輸出。該命令將環境變數值中的 `cse_` 前置詞轉換為逐字稿 URL 預期的 `session_` 前置詞：

382 400

383```bash theme={null}401```bash theme={null}

384echo "https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID/#cse_/session_}"402echo "https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID/#cse_/session_}"

388 執行測試、啟動服務和新增套件406 執行測試、啟動服務和新增套件

389</h3>407</h3>

390 408

391您無法進入工作階段 VM 的 shell。Claude 為您執行每個命令，因此請將本節中的工作表述為提示中的請求。409您無法進入工作階段 VM 的 shell。Claude 為您執行每個命令，因此請將本節中的工作表述為提示詞中的請求。

392 410

393<h4 id="run-tests">411<h4 id="run-tests">

394 執行測試412 執行測試

395</h4>413</h4>

396 414

397Claude 會在處理工作時執行測試。在您的提示中要求它，例如「修復 `tests/` 中失敗的測試」或「在每次變更後執行 pytest」。隨[預先安裝的工具鏈](#installed-tools)提供的測試執行器（例如 pytest 和 cargo test）無需額外設定即可運作。您的專案宣告為依賴項的執行器（例如 jest）會隨您的依賴項一起安裝。415Claude 會在處理工作時執行測試。在您的提示詞中要求它，例如「修復 `tests/` 中失敗的測試」或「在每次變更後執行 pytest」。隨[預先安裝的工具鏈](#installed-tools)提供的測試執行器（例如 pytest 和 cargo test）無需額外設定即可運作。您的專案宣告為相依性的執行器（例如 jest）會隨您的相依套件一起安裝。

398 416

399<h4 id="start-services">417<h4 id="start-services">

400 啟動服務418 啟動服務

430* 16 GB 的 RAM448* 16 GB 的 RAM

431* 30 GB 的磁碟449* 30 GB 的磁碟

432 450

433VM 可能會停止需要明顯更多記憶體的工作，例如大型建置工作或記憶體密集型測試。對於超出這些限制的工作負載，請使用[遠端控制](/docs/zh-TW/remote-control)在您自己的硬體上執行 Claude Code，或在[自我代管環境](/docs/zh-TW/self-hosted-environments)中執行雲端工作階段，該環境位於您的組織操作的計算上。451VM 可能會停止需要明顯更多記憶體的工作，例如大型建置工作或記憶體密集型測試。對於超出這些限制的工作負載，請使用 [Remote Control](/docs/zh-TW/remote-control) 在您自己的硬體上執行 Claude Code，或在[自我代管環境](/docs/zh-TW/self-hosted-environments)中執行雲端工作階段，該環境位於您的組織操作的計算上。

434 452

435<h3 id="time-limits">453<h3 id="time-limits">

436 時間限制454 時間限制

441* **Claude 執行的命令**：雲端環境不會設定自己的命令逾時，因此 Bash 工具的預設值適用。Claude 預設等待前景命令 2 分鐘，最多可要求 10 分鐘。459* **Claude 執行的命令**：雲端環境不會設定自己的命令逾時，因此 Bash 工具的預設值適用。Claude 預設等待前景命令 2 分鐘，最多可要求 10 分鐘。

442 460

443 當命令達到其[逾時](/docs/zh-TW/tools-reference#timeout-and-output-limits)時，Claude Code [將其移到背景](/docs/zh-TW/tools-reference#foreground-commands-that-move-to-the-background)，而不是停止它，除非命令以 `sleep` 開頭。以這種方式移動的命令可以繼續執行最多 30 分鐘，然後 Claude Code 在其[背景時間限制](/docs/zh-TW/tools-reference#time-limit-for-background-commands)處停止它。將 `BASH_DEFAULT_TIMEOUT_MS` 設定為 `1800000` 毫秒以上會延長該限制以及前景預設值。461 當命令達到其[逾時](/docs/zh-TW/tools-reference#timeout-and-output-limits)時，Claude Code [將其移到背景](/docs/zh-TW/tools-reference#foreground-commands-that-move-to-the-background)，而不是停止它，除非命令以 `sleep` 開頭。以這種方式移動的命令可以繼續執行最多 30 分鐘，然後 Claude Code 在其[背景時間限制](/docs/zh-TW/tools-reference#time-limit-for-background-commands)處停止它。將 `BASH_DEFAULT_TIMEOUT_MS` 設定為 `1800000` 毫秒以上會延長該限制以及前景預設值。

444* **SessionStart hooks**：Claude Code 在 600 秒後取消 `command` hook，除非您在 hook 項目上設定 [`timeout`](/docs/zh-TW/hooks#common-fields)（以秒為單位）。Claude Code 不會對您使用 [`async: true`](/docs/zh-TW/hooks#run-hooks-in-the-background) 執行的 hook 強制執行逾時。462* **SessionStart hook**：Claude Code 在 600 秒後取消 `command` hook，除非您在 hook 項目上設定 [`timeout`](/docs/zh-TW/hooks#common-fields)（以秒為單位）。Claude Code 不會對您使用 [`async: true`](/docs/zh-TW/hooks#run-hooks-in-the-background) 執行的 hook 強制執行逾時。

445* **設定指令碼**：花費超過大約五分鐘的指令碼不會被快取。[指令碼需求](#script-requirements)涵蓋如何保持在該時間以下。463* **設定指令碼**：花費超過大約五分鐘的指令碼不會被快取。[指令碼需求](#script-requirements)涵蓋如何保持在該時間以下。

446* **閒置工作階段**：在幾分鐘沒有活動後，工作階段的 VM 會暫停並保存其檔案，稍後可以回收暫停的 VM。[設定環境變數](#set-environment-variables)描述工作階段在每種情況下會取得什麼，[環境已過期](/docs/zh-TW/claude-code-on-the-web#environment-expired)涵蓋如何重新開啟其 VM 已被回收的工作階段。464* **閒置工作階段**：在幾分鐘沒有活動後，工作階段的 VM 會暫停並保存其檔案，稍後可以回收暫停的 VM。[設定環境變數](#set-environment-variables)描述工作階段在每種情況下會取得什麼，[環境已過期](/docs/zh-TW/claude-code-on-the-web#environment-expired)涵蓋如何重新開啟其 VM 已被回收的工作階段。

447 465

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`，它會將對話替換為結構化摘要。大多數啟動內容會自動重新載入；下表顯示每個機制會發生什麼。

costs.md +1 −1

Details

394* **對複雜任務使用 plan mode**：在實作之前，按 Shift+Tab 循環切換至 [plan mode](/docs/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode)。Claude 探索程式碼庫並提出一個方法供您核准，防止當初始方向錯誤時進行昂貴的返工。394* **對複雜任務使用 plan mode**：在實作之前，按 Shift+Tab 循環切換至 [plan mode](/docs/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode)。Claude 探索程式碼庫並提出一個方法供您核准，防止當初始方向錯誤時進行昂貴的返工。

395* **及早修正方向**：如果 Claude 開始朝著錯誤的方向前進，按 Escape 立即停止。使用 `/rewind` 或雙擊 Escape 將對話和程式碼還原到先前的檢查點。395* **及早修正方向**：如果 Claude 開始朝著錯誤的方向前進，按 Escape 立即停止。使用 `/rewind` 或雙擊 Escape 將對話和程式碼還原到先前的檢查點。

396* **提供驗證目標**：在您的提示詞中包含測試案例、貼上螢幕截圖或定義預期輸出。當 Claude 可以驗證自己的工作時，它會在您需要請求修復之前捕捉問題。396* **提供驗證目標**：在您的提示詞中包含測試案例、貼上螢幕截圖或定義預期輸出。當 Claude 可以驗證自己的工作時，它會在您需要請求修復之前捕捉問題。

397* **增量測試**：寫一個檔案、測試它，然後繼續。這能在問題修復成本仍低時及早捕捉問題。397* **增量測試**：寫一個檔案、測試它，然後繼續。這能及早捕捉問題。

398 398

399<h2 id="background-token-usage">399<h2 id="background-token-usage">

400 背景 token 使用400 背景 token 使用

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

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 重試或等待時您看到的內容

2299 2300

2300**該怎麼辦：**2301**該怎麼辦：**

2301 2302

2302* 在貼上之前調整影像大小。API 接受單個影像最長邊最多 8000 像素的影像，或當許多影像在上下文中時最多 2000 像素。2303* 在貼上之前調整影像大小。API 接受單個影像最長邊最多 8000 像素的影像，或當上下文中有超過 20 張影像時最多 3000 像素。

2303* 拍攝相關區域的更緊密螢幕截圖，而不是整個螢幕2304* 拍攝相關區域的更緊密螢幕截圖，而不是整個螢幕

2304 2305

2305<h3 id="unable-to-resize-image">2306<h3 id="unable-to-resize-image">

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* 重新措辭您的最後一則訊息，或採取不同的方法

fast-mode.md +1 −1

Details

88 88

89快速模式定價在整個 1M token 上下文視窗中是固定的。如需與標準 Opus 費率進行比較，請參閱 [Claude 定價參考](https://platform.claude.com/docs/zh-TW/about-claude/pricing)。89快速模式定價在整個 1M token 上下文視窗中是固定的。如需與標準 Opus 費率進行比較，請參閱 [Claude 定價參考](https://platform.claude.com/docs/zh-TW/about-claude/pricing)。

90 90

91當您在對話中首次啟用快速模式時，您需要為整個對話上下文支付完整的快速模式未快取輸入 token 價格。對話進行得越深入，成本就越高，因此從一開始就啟用快速模式會更便宜。成本每個對話只適用一次，因此稍後關閉並再次開啟快速模式不會重複計費。如需了解機制，請參閱[快速模式如何與 prompt cache 互動](/docs/zh-TW/prompt-caching#turning-on-fast-mode)。91當您在對話中首次啟用快速模式時，您需要為整個對話上下文支付完整的快速模式未快取輸入 token 價格。對話進行得越深入，這筆費用就越高，因此在對話開始時就啟用快速模式，這筆費用最低。此費用每個對話只收取一次，因此稍後關閉並再次開啟快速模式不會重複計費。如需了解機制，請參閱[快速模式如何與提示快取互動](/docs/zh-TW/prompt-caching#turning-on-fast-mode)。

92 92

93<h3 id="see-where-fast-mode-spend-appears">93<h3 id="see-where-fast-mode-spend-appears">

94 查看快速模式支出出現的位置94 查看快速模式支出出現的位置

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

keybindings.md +3 −2

Details

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

306| `footer:close` | x | 停止選定的 [agent](/docs/zh-TW/sub-agents#observe-and-steer-running-forks) 或 [工作流程](/docs/zh-TW/workflows#manage-runs)，若其已不再執行，則關閉其列 |

306| `footer:dismiss` | (未綁定) | 將按鍵綁定到此動作沒有效果，命名它的 `keybindings.json` 保持有效。在 v2.1.281 之前，Backspace 和 Delete 被綁定到它，並從頁尾中關閉選定的成品連結。 |307| `footer:dismiss` | (未綁定) | 將按鍵綁定到此動作沒有效果，命名它的 `keybindings.json` 保持有效。在 v2.1.281 之前，Backspace 和 Delete 被綁定到它，並從頁尾中關閉選定的成品連結。 |

307 308

308當選定頁尾項目時，例如提示下方代理面板中的列，即使您在 `Chat` 上下文中將 `Enter` 重新綁定到 `chat:queueSubmit` 或 `chat:newline`，按 `Enter` 也會開啟它。309當選定頁尾項目時，例如提示下方代理面板中的列，即使您在 `Chat` 上下文中將 `Enter` 重新綁定到 `chat:queueSubmit` 或 `chat:newline`，按 `Enter` 也會開啟它。

llm-gateway-connect.md +8 −1

Details

216* **由管理員分發**：如果您的組織已[部署配置](/docs/zh-TW/llm-gateway-rollout#distribute-through-managed-settings)，桌面應用程式通過閘道路由，無需您進行任何設定216* **由管理員分發**：如果您的組織已[部署配置](/docs/zh-TW/llm-gateway-rollout#distribute-through-managed-settings)，桌面應用程式通過閘道路由，無需您進行任何設定

217* **本地配置**：對於沒有管理員分發配置的裝置，打開說明 → 疑難排解 → 啟用開發人員模式，這會使用開發人員功能表重新啟動應用程式。然後打開開發人員 → 配置第三方推論並輸入您的閘道基礎 URL。管理員分發的配置優先，並使此表單為唯讀217* **本地配置**：對於沒有管理員分發配置的裝置，打開說明 → 疑難排解 → 啟用開發人員模式，這會使用開發人員功能表重新啟動應用程式。然後打開開發人員 → 配置第三方推論並輸入您的閘道基礎 URL。管理員分發的配置優先，並使此表單為唯讀

218 218

219啟用閘道配置後，桌面應用程式僅在您的本機上運行會話：環境選擇器不提供 SSH 會話或 Anthropic 託管的雲端環境，[遠端控制](/docs/zh-TW/remote-control)不可用。若要通過閘道在遠端主機上使用 Claude Code，請在該主機上運行 CLI，並在那裡設定[`ANTHROPIC_BASE_URL` 和閘道認證](#set-the-base-url-and-credential)。219啟用閘道設定後，環境選擇器不會提供 Anthropic 託管的雲端環境，且 [Remote Control](/docs/zh-TW/remote-control) 無法使用。

220

221在閘道設定下，SSH 工作階段目前為 beta 版，且需要 Claude Desktop v1.40609.0 或更新版本。連線前，請檢查允許清單和閘道的位址：

222

223* **允許的主機**：SSH 工作階段預設為關閉。若要開啟，您或您的管理員需在第三方推論設定的 [`sshHostAllowlist`](https://claude.com/docs/third-party/claude-desktop/configuration#sshhostallowlist) 鍵中列出允許的主機

224* **閘道位址**：遠端機器會自行連線到閘道，因此位於您電腦上 `localhost` 的閘道無法用於 SSH 工作階段

225

226請參閱 [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions)。您也可以在遠端主機上執行 CLI，並在該處設定 [`ANTHROPIC_BASE_URL` 和閘道憑證](#set-the-base-url-and-credential)。

220 227

221如果桌面應用程式顯示 `Gateway was unreachable`，應用程式在啟動時無法到達配置的基礎 URL；使用上面的 [curl 測試](#verify-the-connection)檢查 URL 和網路路徑。228如果桌面應用程式顯示 `Gateway was unreachable`，應用程式在啟動時無法到達配置的基礎 URL；使用上面的 [curl 測試](#verify-the-connection)檢查 URL 和網路路徑。

222 229

managed-mcp.md +17 −5

Details

347 `serverUrl` 項目如何比對347 `serverUrl` 項目如何比對

348</h4>348</h4>

349 349

350URL 支援在模式中的任何地方使用 `*` 萬用字元，包括 scheme。主機名稱比對不區分大小寫，並忽略尾隨 FQDN 點，因此 `https://Mcp.Example.com/*` 比對 `https://mcp.example.com/api`。路徑保持區分大小寫。350URL 支援 `*` 萬用字元，包括以 `*` 作為整個 scheme。主機名稱比對不區分大小寫，並忽略尾隨 FQDN 點，因此 `https://Mcp.Example.com/*` 比對 `https://mcp.example.com/api`。路徑保持區分大小寫。如果未指定連接埠，主機名稱的寫法會決定模式僅比對該 scheme 的預設連接埠，還是比對每個連接埠：

351

352* **完整寫出的主機名稱**：僅限預設連接埠，`https` 為 443，`http` 為 80

353* **包含 `*` 的主機名稱**：每個連接埠

351 354

352下表顯示常見模式允許的內容：355下表顯示常見模式允許的內容：

353 356

354| 模式 | 允許 |357| 模式 | 允許 |

355| :- | :- |358| :- | :- |

356| `https://mcp.example.com/*` | 特定網域上的所有路徑 |359| `https://mcp.example.com/*` | 特定網域上的所有路徑，僅限連接埠 443 |

358| `https://*.example.com/*` | `example.com` 的任何子網域 |361| `https://mcp.example.com:8443/*` | 該網域上的所有路徑，僅限連接埠 8443 |

362| `https://mcp.example.com:*/*` | 該網域上的所有路徑，任何連接埠，包括 443 |

363| `https://*.example.com/*` | `example.com` 的任何子網域，任何連接埠 |

359| `http://localhost:*/*` | localhost 上的任何連接埠 |364| `http://localhost:*/*` | localhost 上的任何連接埠 |

360| `*://mcp.example.com/*` | 任何配置到特定網域 |365| `*://mcp.example.com/*` | 透過任何 scheme 連線到特定網域，每個 scheme 僅限其預設連接埠 |

366

367`deniedMcpServers` 中的項目以相同方式比對連接埠，因此請根據您需要阻止的連接埠和 scheme，為 `staging.example.com` 選擇項目：

368

369* `https://staging.example.com/*`：僅阻止該主機上連接埠 443 的 `https` 伺服器，因此不會阻止位於 `https://staging.example.com:8443/api` 的伺服器

370* `https://staging.example.com:*/*`：阻止該主機上所有連接埠的 `https` 伺服器

371* `*://staging.example.com:*/*`：阻止該主機的任何 scheme 及任何連接埠

361 372

362<h4 id="how-policy-entries-expand">373<h4 id="how-policy-entries-expand">

363 `serverCommand` 和 `serverUrl` 項目中的環境變數374 `serverCommand` 和 `serverUrl` 項目中的環境變數

529 | :- | :- |540 | :- | :- |

543 | `https://staging.example.com:8443/api` 上的 HTTP 伺服器 | 允許：比對允許清單 URL 模式，[此連接埠上沒有拒絕清單比對](#how-serverurl-entries-match) |

533</Accordion>545</Accordion>

534 546

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)當指示未被遵循時

monitoring-usage.md +1 −1

Details

551* **伺服器受管設定**：將它們新增至組織的[伺服器受管設定](/docs/zh-TW/server-managed-settings)的 `env` 區塊。Claude Code 在[伺服器受管設定適用](/docs/zh-TW/model-config#surface-coverage)的任何位置啟動時會擷取這些設定，包括使用者的機器和 Claude Tag 頻道工作階段以外的雲端工作階段。Claude Tag 工作階段不會接收伺服器受管設定，因此此路由不會設定它們。551* **伺服器受管設定**：將它們新增至組織的[伺服器受管設定](/docs/zh-TW/server-managed-settings)的 `env` 區塊。Claude Code 在[伺服器受管設定適用](/docs/zh-TW/model-config#surface-coverage)的任何位置啟動時會擷取這些設定，包括使用者的機器和 Claude Tag 頻道工作階段以外的雲端工作階段。Claude Tag 工作階段不會接收伺服器受管設定，因此此路由不會設定它們。

552* **環境的變數**：將它們新增至雲端環境的[環境變數](/docs/zh-TW/cloud-environments#set-environment-variables)，以僅設定在該環境中執行的工作階段。這是到達 Claude Tag 工作階段的路由。552* **環境的變數**：將它們新增至雲端環境的[環境變數](/docs/zh-TW/cloud-environments#set-environment-variables)，以僅設定在該環境中執行的工作階段。這是到達 Claude Tag 工作階段的路由。

553 553

554任何使用環境的人都可以讀取其變數，因此不要在其中放置認證，例如 `OTEL_EXPORTER_OTLP_HEADERS` 中的收集器權杖。環境上的 [API 認證](/docs/zh-TW/cloud-environments#add-api-credentials)也無法幫助，因為 Claude Code 自己的遙測匯出是[永遠不會取得認證的請求](/docs/zh-TW/cloud-environments#requests-that-never-get-the-credential)之一。如果收集器需要認證，請改為透過伺服器受管設定設定整個匯出，因為當您在該處設定認證時，[Claude Code 會移除在受管設定外設定的端點變數](#how-managed-settings-lock-the-otlp-destination)。554任何使用環境的人都可以讀取其變數，因此不要在其中放置憑證，例如 `OTEL_EXPORTER_OTLP_HEADERS` 中的收集器 token。環境上的[網路密鑰](/docs/zh-TW/cloud-environments#add-api-credentials)也無法幫助，因為 Claude Code 自己的遙測匯出是[永遠不會取得密鑰的請求](/docs/zh-TW/cloud-environments#requests-that-never-get-the-credential)之一。如果收集器需要憑證，請改為透過伺服器受管設定設定整個匯出，因為當您在該處設定憑證時，[Claude Code 會移除在受管設定外設定的端點變數](#how-managed-settings-lock-the-otlp-destination)。

555 555

556在為雲端工作階段設定遙測時，請記住這些限制：556在為雲端工作階段設定遙測時，請記住這些限制：

557 557

overview.md +6 −4

Details

28 curl -fsSL https://claude.ai/install.sh | bash28 curl -fsSL https://claude.ai/install.sh | bash

29 ```29 ```

30 30

31 在 Windows 上，當您在 PowerShell 中時，提示字元會顯示 `PS C:\`，而在 CMD 中時會顯示 `C:\`（不含 `PS`）。

31 **Windows PowerShell：**33 **Windows PowerShell：**

32 34

33 ```powershell theme={null}35 ```powershell theme={null}

42 44

43 當安裝程式完成時，請開啟新的終端機視窗並執行 `claude --version`。正常的安裝會列印版本號碼。如果您的殼層說找不到 `claude` 或無法識別，安裝目錄還未在您的 PATH 上：請參閱[修正您的 PATH](/docs/zh-TW/troubleshoot-install#command-not-found-claude-after-installation)。45 當安裝程式完成時，請開啟新的終端機視窗並執行 `claude --version`。正常的安裝會列印版本號碼。如果您的殼層說找不到 `claude` 或無法識別，安裝目錄還未在您的 PATH 上：請參閱[修正您的 PATH](/docs/zh-TW/troubleshoot-install#command-not-found-claude-after-installation)。

44 46

45 如果您看到 `The token '&&' is not a valid statement separator`，表示您在 PowerShell 中，而非 CMD。如果您看到 `'irm' is not recognized as an internal or external command`，表示您在 CMD 中，而非 PowerShell。當您在 PowerShell 中時，提示符會顯示 `PS C:\`，而在 CMD 中時會顯示 `C:\`（不含 `PS`）。47 如果您看到 `The token '&&' is not a valid statement separator`，表示您在 PowerShell 中，而非 CMD。如果您看到 `'irm' is not recognized as an internal or external command`，表示您在 CMD 中，而非 PowerShell。

46 48

47 如果安裝命令失敗並出現 `syntax error near unexpected token '<'`、`403` 或其他 curl 錯誤，請參閱[疑難排解安裝](/docs/zh-TW/troubleshoot-install#find-your-error)以將錯誤與修正相對應，並查看替代安裝方法。49 如果安裝命令失敗並出現 `syntax error near unexpected token '<'`、`403` 或其他任何錯誤，請參閱[疑難排解安裝](/docs/zh-TW/troubleshoot-install#find-your-error)以將錯誤與修正相對應，並查看替代安裝方法。

48 50

49 建議在原生 Windows 上安裝 [Git for Windows](https://git-scm.com/downloads/win)，以便 Claude Code 可以使用 Bash 工具。如果未安裝 Git for Windows，Claude Code 會改用 PowerShell 作為殼層工具。WSL 設定不需要 Git for Windows。51 建議在原生 Windows 上安裝 [Git for Windows](https://git-scm.com/downloads/win)，以便 Claude Code 可以使用 Bash 工具。如果未安裝 Git for Windows，Claude Code 會改用 PowerShell 作為殼層工具。WSL 設定不需要 Git for Windows。

50 52

85 claude87 claude

86 ```88 ```

87 89

88 首次使用時，系統會提示您登入。如果您已設定 `ANTHROPIC_API_KEY` 環境變數，Claude Code 會跳過登入提示，改為要求您核准該金鑰。就這麼簡單！[繼續進行快速入門 →](/docs/zh-TW/quickstart)90 Claude Code 會在首次使用時提示您登入。如果您已設定 `ANTHROPIC_API_KEY` 環境變數，且在 Claude Code 詢問是否使用該金鑰時予以核准，Claude Code 便會跳過登入提示。[繼續進行快速入門 →](/docs/zh-TW/quickstart)

89 91

90 <Tip>92 <Tip>

91 請參閱[進階設定](/docs/zh-TW/setup)以了解安裝選項、手動更新或卸載說明。如果遇到問題，請造訪[安裝疑難排解](/docs/zh-TW/troubleshoot-install)。93 請參閱[進階設定](/docs/zh-TW/setup)以了解安裝選項、手動更新或卸載說明。如果遇到問題，請造訪[安裝疑難排解](/docs/zh-TW/troubleshoot-install)。

171 </Accordion>173 </Accordion>

172 174

173 <Accordion title="使用說明、skills 和 hooks 進行自訂" icon="sliders">175 <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)，儲存學習內容，跨工作階段而無需您編寫任何內容。176 [`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 177

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

177 179

plugin-evals.md +6 −2

Details

77 claude plugin eval init77 claude plugin eval init

78 ```78 ```

79 79

80 如果 Claude Code 還不信任此目錄，它首先會詢問 `Trust this plugin directory?`；回答 `y`。然後開啟互動式 Claude Code 工作階段。Claude 讀取您的 plugin 並詢問您好的結果是什麼樣子，提議應該和不應該觸發 plugin 的提示，為每個設計評分器，試驗它們一次以檢查它們的行為，並在 `evals/` 下為每個提示編寫一個案例目錄，每個都以其提示命名。當 Claude 告訴您套件已準備好時，使用 `/exit` 或 Ctrl+D 退出該工作階段以返回您的 shell。80 如果 Claude Code 還不信任此目錄，它首先會詢問 `Trust this plugin directory?`；回答 `y`。

82 然後開啟互動式 Claude Code 工作階段。Claude 讀取您的 plugin 並詢問您好的結果是什麼樣子，提議應該和不應該觸發 plugin 的提示詞，為每個設計評分器，試驗它們一次以檢查它們的行為，並在 `evals/` 下為每個提示詞編寫一個案例目錄，每個都以其提示詞命名。

84 當 Claude 告訴您套件已準備好時，使用 `/exit` 或 Ctrl+D 退出該工作階段以返回您的 shell。

81 85

82 如果您已經在 plugin 根目錄開啟了 Claude Code 工作階段，您可以改為要求 Claude 在該對話中執行 `claude plugin eval init`。Claude 執行命令，然後在該對話中詢問您相同的問題。86 如果您已經在 plugin 根目錄開啟了 Claude Code 工作階段，您可以改為要求 Claude 在該對話中執行 `claude plugin eval init`。Claude 執行命令，然後在該對話中詢問您相同的問題。

83 87

116 120

117 最常見的第一個發現是 `Δ` 接近零，案例的 `tool_used: Skill` 評分器失敗，這意味著 Claude 在自然措辭上沒有選擇您的 skill。調整 skill 的 [`description`](/docs/zh-TW/skills#frontmatter-reference)，再次執行 `claude plugin eval .`，並進行比較。121 最常見的第一個發現是 `Δ` 接近零，案例的 `tool_used: Skill` 評分器失敗，這意味著 Claude 在自然措辭上沒有選擇您的 skill。調整 skill 的 [`description`](/docs/zh-TW/skills#frontmatter-reference)，再次執行 `claude plugin eval .`，並進行比較。

118 122

119 若要廉價地迭代單個案例，執行單個 arm 一次。單次執行是有噪音的，因此在信任任何變更之前，請在預設三次執行時確認任何變更。使用一個 arm，表格顯示 `SCORE` 和 `PASS%` 列而不是 `WITH`、`W/OUT` 和 `Δ`：123 若要以較少的執行次數迭代單個案例，執行單個 arm 一次。單次執行是有噪音的，因此在信任任何變更之前，請在預設三次執行時確認任何變更。使用一個 arm，表格顯示 `SCORE` 和 `PASS%` 列而不是 `WITH`、`W/OUT` 和 `Δ`：

120 124

121 ```bash theme={null}125 ```bash theme={null}

122 claude plugin eval . --case <case-name> --runs 1 --ablation none126 claude plugin eval . --case <case-name> --runs 1 --ablation none

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

prompt-caching.md +2 −2

Details

310 310

311在 Pro 或 Max 方案上，當您在長時間中斷後恢復大型工作階段時，Claude Code [提供從摘要恢復](/docs/zh-TW/sessions#resume-from-a-summary)，以便後續請求不會攜帶完整歷史記錄。311在 Pro 或 Max 方案上，當您在長時間中斷後恢復大型工作階段時，Claude Code [提供從摘要恢復](/docs/zh-TW/sessions#resume-from-a-summary)，以便後續請求不會攜帶完整歷史記錄。

312 312

313生存時間 (TTL) 控制快取存活的間隔長度。API 提供兩種：五分鐘 TTL 和[一小時 TTL](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration)，後者可在較長的中斷期間保持快取溫暖，但[以更高的速率計費快取寫入](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing)。較長的 TTL 在您讓工作階段閒置並返回時很有幫助，因為您可以跳過過期前綴所需的重新處理。對於從不閒置超過五分鐘的短工作突發，成本更高，因為更高的寫入速率適用，而較長的快取生命週期未被使用。313生存時間 (TTL) 控制快取存活的間隔長度。API 提供兩種：五分鐘 TTL 和[一小時 TTL](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration)，後者可在較長的中斷期間保持快取溫暖，但[以更高的費率計費快取寫入](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing)。較長的 TTL 在您讓工作階段閒置並返回時很有幫助，因為您可以跳過過期前綴所需的重新處理。對於從不閒置超過五分鐘的短工作突發，成本更高，因為更高的寫入費率適用，而較長的快取生命週期未被使用。

314 314

315<h3 id="which-ttl-each-request-gets">315<h3 id="which-ttl-each-request-gets">

316 每個請求獲得的 TTL316 每個請求獲得的 TTL

328| 主要對話 | 一小時 | 五分鐘 |328| 主要對話 | 一小時 | 五分鐘 |

329| 其他所有內容 | 五分鐘，除了伺服器控制的幫助程式請求外，它們獲得一小時 | 五分鐘 |329| 其他所有內容 | 五分鐘，除了伺服器控制的幫助程式請求外，它們獲得一小時 | 五分鐘 |

330 330

331一旦您超過方案的使用量限制，Claude Code 會使用[使用額度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)，您將為該使用量計費，因此 Claude Code 會將主要對話降低到更便宜的五分鐘 TTL。要在那裡保持一小時 TTL，[自己選擇 TTL](#choose-the-ttl-yourself)。331一旦您超過方案的用量上限，Claude Code 會使用[用量點數](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)，您將為該使用量計費，因此 Claude Code 會將主要對話降低到五分鐘 TTL，其快取寫入的計費費率較低。要在那裡保持一小時 TTL，[自己選擇 TTL](#choose-the-ttl-yourself)。

332 332

333<h3 id="choose-the-ttl-yourself">333<h3 id="choose-the-ttl-yourself">

334 自己選擇 TTL334 自己選擇 TTL

prompt-library.md +1 −1

Details

1342 },1342 },

1343 "review-your-changes-before": {1343 "review-your-changes-before": {

1344 title: "在提交前審查您的變更",1344 title: "在提交前審查您的變更",

1345 teaches: "在問題仍然便宜時捕捉問題。Claude 完整讀取已變更的檔案，而不僅僅是差異行，因此它會發現快速自我審查會遺漏的問題。",1345 teaches: "趁問題修復起來還不費工時就先發現它們。Claude 完整讀取已變更的檔案，而不僅僅是差異行，因此它會發現快速自我審查會遺漏的問題。",

1346 next: "執行 `/code-review` 以在一個命令中進行相同檢查",1346 next: "執行 `/code-review` 以在一個命令中進行相同檢查",

1347 prompt: "審查我尚未提交的變更，並在我提交前標出任何看起來有風險的地方"1347 prompt: "審查我尚未提交的變更，並在我提交前標出任何看起來有風險的地方"

1348 },1348 },

quickstart.md +58 −92

Details

4 4

5# 快速入門5# 快速入門

6 6

~~7> 歡迎使用 Claude Code！~~7> 在終端機中安裝 Claude Code、登入，並使用 CLI 探索您的程式碼庫及進行第一次程式碼變更。

8 8

~~9本快速入門指南將在幾分鐘內讓您使用 AI 驅動的編碼協助。完成後，您將了解如何使用 Claude Code 進行常見的開發任務。~~9本快速入門介紹在終端機中使用 Claude Code：安裝 CLI、從第一個工作階段登入，以及在您自己的專案中將其用於常見的開發任務。

10 10

11<h2 id="before-you-begin">11<h2 id="before-you-begin">

12 開始前12 開始前

14 14

15確保您擁有：15確保您擁有：

16 16

~~17* 已開啟的終端或命令提示字元~~17* 已開啟的終端機或命令提示字元

~~18 * 如果您從未使用過終端，請查看[終端指南](/docs/zh-TW/terminal-guide)~~

19* 一個可以使用的程式碼專案18* 一個可以使用的程式碼專案

20* 一個 [Claude 訂閱](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=quickstart_prereq)（Pro、Max、Team 或 Enterprise）、[Claude Console](https://platform.claude.com/) 帳戶，或透過[支援的雲端提供商](/docs/zh-TW/third-party-integrations)存取19* 一個 [Claude 訂閱](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=quickstart_prereq)（Pro、Max、Team 或 Enterprise）、[Claude Console](https://platform.claude.com/) 帳戶，或透過[支援的雲端提供商](/docs/zh-TW/third-party-integrations)存取

21 20

22<Note>21<Note>

23 本指南涵蓋終端 CLI。Claude Code 也可在[網頁](https://claude.ai/code)、[桌面應用程式](/docs/zh-TW/desktop)、[VS Code](/docs/zh-TW/vs-code) 和 [JetBrains IDE](/docs/zh-TW/jetbrains)、[Slack](/docs/zh-TW/slack) 中使用，以及透過 [GitHub Actions](/docs/zh-TW/github-actions) 和 [GitLab](/docs/zh-TW/gitlab-ci-cd) 進行 CI/CD。請參閱[所有介面](/docs/zh-TW/overview#use-claude-code-everywhere)。22 以下情況在其他頁面中說明：

24 * **從未使用過終端機**：請從[終端機指南](/docs/zh-TW/terminal-guide)開始

25 * **想在終端機以外的地方使用 Claude Code**：Claude Code 也可在[網頁](https://claude.ai/code)、[桌面應用程式](/docs/zh-TW/desktop)、[VS Code](/docs/zh-TW/vs-code) 和 [JetBrains IDE](/docs/zh-TW/jetbrains)、[Slack](/docs/zh-TW/slack) 中使用，以及透過 [GitHub Actions](/docs/zh-TW/github-actions) 和 [GitLab](/docs/zh-TW/gitlab-ci-cd) 在 CI/CD 中使用。請參閱[所有介面](/docs/zh-TW/overview#use-claude-code-everywhere)。

24</Note>26</Note>

25 27

26<h2 id="step-1-install-claude-code">28<h2 id="step-1-install-claude-code">

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

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

35 37

~~36 ```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}~~38 ```bash theme={null}

37 curl -fsSL https://claude.ai/install.sh | bash39 curl -fsSL https://claude.ai/install.sh | bash

38 ```40 ```

39 41

42 在 Windows 上，當您在 PowerShell 中時，提示字元會顯示 `PS C:\`，而在 CMD 中時會顯示 `C:\`（不含 `PS`）。

40 **Windows PowerShell：**44 **Windows PowerShell：**

41 45

~~42 ```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}~~46 ```powershell theme={null}

43 irm https://claude.ai/install.ps1 | iex47 irm https://claude.ai/install.ps1 | iex

44 ```48 ```

45 49

46 **Windows CMD：**50 **Windows CMD：**

47 51

~~48 ```batch theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}~~52 ```batch theme={null}

49 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd53 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

50 ```54 ```

51 55

52 當安裝程式完成時，請開啟新的終端機視窗並執行 `claude --version`。正常的安裝會列印版本號碼。如果您的殼層說找不到 `claude` 或無法識別，安裝目錄還未在您的 PATH 上：請參閱[修正您的 PATH](/docs/zh-TW/troubleshoot-install#command-not-found-claude-after-installation)。56 當安裝程式完成時，請開啟新的終端機視窗並執行 `claude --version`。正常的安裝會列印版本號碼。如果您的殼層說找不到 `claude` 或無法識別，安裝目錄還未在您的 PATH 上：請參閱[修正您的 PATH](/docs/zh-TW/troubleshoot-install#command-not-found-claude-after-installation)。

53 57

54 如果您看到 `The token '&&' is not a valid statement separator`，表示您在 PowerShell 中，而非 CMD。如果您看到 `'irm' is not recognized as an internal or external command`，表示您在 CMD 中，而非 PowerShell。當您在 PowerShell 中時，提示符會顯示 `PS C:\`，而在 CMD 中時會顯示 `C:\`（不含 `PS`）。58 如果您看到 `The token '&&' is not a valid statement separator`，表示您在 PowerShell 中，而非 CMD。如果您看到 `'irm' is not recognized as an internal or external command`，表示您在 CMD 中，而非 PowerShell。

55 59

56 如果安裝命令失敗並出現 `syntax error near unexpected token '<'`、`403` 或其他 curl 錯誤，請參閱[疑難排解安裝](/docs/zh-TW/troubleshoot-install#find-your-error)以將錯誤與修正相對應，並查看替代安裝方法。60 如果安裝命令失敗並出現 `syntax error near unexpected token '<'`、`403` 或其他任何錯誤，請參閱[疑難排解安裝](/docs/zh-TW/troubleshoot-install#find-your-error)以將錯誤與修正相對應，並查看替代安裝方法。

57 61

58 建議在原生 Windows 上安裝 [Git for Windows](https://git-scm.com/downloads/win)，以便 Claude Code 可以使用 Bash 工具。如果未安裝 Git for Windows，Claude Code 會改用 PowerShell 作為殼層工具。WSL 設定不需要 Git for Windows。62 建議在原生 Windows 上安裝 [Git for Windows](https://git-scm.com/downloads/win)，以便 Claude Code 可以使用 Bash 工具。如果未安裝 Git for Windows，Claude Code 會改用 PowerShell 作為殼層工具。WSL 設定不需要 Git for Windows。

59 63

63 </Tab>67 </Tab>

64 68

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

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

67 brew install --cask claude-code71 brew install --cask claude-code

68 ```72 ```

69 73

75 </Tab>79 </Tab>

76 80

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

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

79 winget install Anthropic.ClaudeCode83 winget install Anthropic.ClaudeCode

80 ```84 ```

81 85

95 99

96此命令會列印版本號碼，後面跟著 `(Claude Code)`。100此命令會列印版本號碼，後面跟著 `(Claude Code)`。

97 101

~~98<h2 id="step-2-log-in-to-your-account">~~102<h2 id="step-2-start-your-first-session">

~~99 步驟 2：登入您的帳戶~~103 步驟 2：開始您的第一個工作階段

100</h2>104</h2>

101 105

102Claude Code 需要帳戶才能使用。使用 `claude` 命令啟動互動式工作階段，首次使用時系統會提示您登入：106在任何專案目錄中開啟終端機，然後啟動 Claude Code：

103 107

104```bash theme={null}108```bash theme={null}

109cd /path/to/your/project

105claude110claude

106```111```

107 112

108對於 Claude 訂閱或 Console 帳戶，請按照提示在瀏覽器中完成驗證。如果您已設定 `ANTHROPIC_API_KEY` 環境變數，Claude Code 會略過登入提示，改為要求您核准該金鑰。若要稍後切換帳戶或重新驗證，請在執行中的工作階段內輸入 `/login`：113將 `/path/to/your/project` 替換為您要處理的專案路徑。

~~109~~

110```text wrap theme={null}

111/login

112```

~~113~~

114您可以使用以下任何帳戶類型登入：

~~115~~

116* [Claude Pro、Max、Team 或 Enterprise](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=quickstart_login)（推薦）

117* [Claude Console](https://platform.claude.com/)（具有預付額度的 API 存取）。首次登入時，Console 中會自動建立「Claude Code」工作區以進行集中成本追蹤。

118* [Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry](/docs/zh-TW/third-party-integrations)（企業雲端提供商）

119* 自行託管的 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway)（如果您的組織執行一個的話）：您的管理員會預先設定閘道 URL，`/login` 會直接在 **Cloud gateway** 畫面上開啟，供您使用公司 SSO 登入

~~120~~

121登入後，您的認證將被儲存，您無需再次登入。深入瞭解 [認證管理](/docs/zh-TW/authentication#credential-management)。

122 114

123<h2 id="step-3-start-your-first-session">115Claude Code 會在首次使用時提示您登入。若使用 Claude 訂閱或 Console 帳戶，請依照提示在瀏覽器中完成身分驗證。如果您已設定 `ANTHROPIC_API_KEY` 環境變數，且在 Claude Code 詢問是否使用該金鑰時予以核准，Claude Code 便會略過登入提示。

124 步驟 3：啟動您的第一個工作階段

125</h2>

126 116

127在任何專案目錄中開啟您的終端並啟動 Claude Code：117您可以使用下列任一種帳戶類型登入：

128 118

129```bash theme={null}119* [Claude Pro、Max、Team 或 Enterprise](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=quickstart_login)（建議）

130cd /path/to/your/project120* [Claude Console](https://platform.claude.com/)（使用預付額度的 API 存取）。首次登入時，系統會自動在 Console 中建立一個「Claude Code」工作區，以便集中追蹤費用。

131claude121* [Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry](/docs/zh-TW/third-party-integrations)（企業雲端供應商）

132```122* 自行託管的 [Claude apps 閘道](/docs/zh-TW/claude-apps-gateway)（如果您的組織有執行的話）：您的管理員會預先設定閘道 URL，而 `/login` 會直接開啟 **Cloud gateway** 畫面，供您使用企業 SSO 登入

133 123

134將 `/path/to/your/project` 替換為您要處理的專案路徑。124登入後，您的憑證會被儲存，之後不需要再次登入。如需了解更多資訊，請參閱[憑證管理](/docs/zh-TW/authentication#credential-management)。

135 125

136您將看到 Claude Code 提示，其中顯示版本、目前的模型和工作目錄。輸入 `/help` 以查看可用命令，或輸入 `/resume` 以繼續之前的對話。126Claude Code 提示字元會出現，其上方會顯示版本、目前的模型及工作目錄。輸入 `/help` 以查看可用的命令，或輸入 `/resume` 以繼續先前的對話。若之後要切換帳戶或重新進行身分驗證，請在執行中的工作階段內輸入 `/login`。

137 127

138<h2 id="step-4-ask-your-first-question">128<h2 id="step-3-ask-your-first-question">

139 步驟 4：提出您的第一個問題129 步驟 3：提出您的第一個問題

140</h2>130</h2>

141 131

142讓我們從了解您的程式碼庫開始。嘗試以下命令之一：132試試以下其中一個命令：

143 133

144```text wrap theme={null}134```text wrap theme={null}

145what does this project do?135what does this project do?

159explain the folder structure149explain the folder structure

160```150```

161 151

162您也可以詢問 Claude 其自身的功能：152您也可以詢問 Claude 關於其自身功能的問題：

163 153

164```text wrap theme={null}154```text wrap theme={null}

165what can Claude Code do?155what can Claude Code do?

174```164```

175 165

176<Note>166<Note>

177 Claude Code 會根據需要讀取您的專案檔案。您無需手動新增內容。167 Claude Code 會視需要讀取您的專案檔案。無需手動新增上下文。

178</Note>168</Note>

179 169

180<h2 id="step-5-make-your-first-code-change">170<h2 id="step-4-make-your-first-code-change">

181 步驟 5：進行您的第一次程式碼變更171 步驟 4：進行您的第一次程式碼變更

182</h2>172</h2>

183 173

184現在讓 Claude Code 進行一些實際的編碼。嘗試一個簡單的任務：174試試一個小任務：

185 175

186```text wrap theme={null}176```text wrap theme={null}

187add a hello world function to the main file177add a hello world function to the main file

188```178```

189 179

190Claude Code 找到適當的檔案並向您顯示變更。如果它在進行變更前詢問，請選擇 **是** 以批准。180Claude Code 會找到適當的檔案並向您顯示變更內容。如果它在進行變更前詢問，請選擇 **Yes** 以核准。

~~191~~

192使用 Claude Code v2.1.283 或更新版本，auto mode 是互動式終端工作階段的[內建起始權限模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)：分類器會檢查動作而不是由您檢查，Claude 可以在不詢問的情況下編輯大多數檔案並執行大多數命令。在較早的版本上，auto mode 僅在 Pro、Max 和 Team 方案上是內建的起始權限模式。對於您安裝或升級後立即開始的工作階段，請參閱[安裝或升級後的第一個工作階段](/docs/zh-TW/env-vars#first-session-after-an-install-or-upgrade)。

193 181

194<Note>182工作階段的[權限模式](/docs/zh-TW/permission-modes)決定了 Claude 可以在不先詢問您的情況下執行哪些動作。隨時按下 `Shift+Tab` 即可切換您目前所在工作階段的權限模式。

195 您的設定或您的組織可以設定不同的起始權限模式。[工作階段開始時的權限模式](/docs/zh-TW/permission-modes#which-mode-a-session-starts-in) 列出了相關內容。隨時按 `Shift+Tab` 以切換您所在工作階段的權限模式。

196</Note>

197 183

198<h2 id="step-6-use-git-with-claude-code">184<h2 id="step-5-use-git-with-claude-code">

199 步驟 6：使用 Git 與 Claude Code185 步驟 5：搭配 Claude Code 使用 Git

200</h2>186</h2>

201 187

202Claude Code 使 Git 操作變得對話式：188Claude Code 讓 Git 操作變得像對話一樣自然：

203 189

204```text wrap theme={null}190```text wrap theme={null}

205what files have I changed?191what files have I changed?

209commit my changes with a descriptive message195commit my changes with a descriptive message

210```196```

211 197

212您也可以提示進行更複雜的 Git 操作：198您也可以透過提示詞執行更複雜的 Git 操作：

213 199

214```text wrap theme={null}200```text wrap theme={null}

215create a new branch called feature/quickstart201create a new branch called feature/quickstart

223help me resolve merge conflicts209help me resolve merge conflicts

224```210```

225 211

226<h2 id="step-7-fix-a-bug-or-add-a-feature">212<h2 id="step-6-fix-a-bug-or-add-a-feature">

227 步驟 7：修復錯誤或新增功能213 步驟 6：修正錯誤或新增功能

228</h2>214</h2>

229 215

230Claude 擅長除錯和功能實現。216以自然語言描述您想要的內容：

~~231~~

232用自然語言描述您想要的內容：

233 217

234```text wrap theme={null}218```text wrap theme={null}

235add input validation to the user registration form219add input validation to the user registration form

236```220```

237 221

238或修復現有問題：222或修正現有問題：

239 223

240```text wrap theme={null}224```text wrap theme={null}

241there's a bug where users can submit empty forms - fix it225there's a bug where users can submit empty forms - fix it

242```226```

243 227

244Claude Code 將：228<h2 id="step-7-test-out-other-common-workflows">

~~245~~ 229 步驟 7：試用其他常見工作流程

246* 定位相關程式碼

247* 理解上下文

248* 實現解決方案

249* 如果可用，執行測試

~~250~~

251<h2 id="step-8-test-out-other-common-workflows">

252 步驟 8：測試其他常見工作流程

253</h2>230</h2>

254 231

255有許多方式可以與 Claude 合作：232與 Claude 協作的方式有很多種：

256 233

257**重構程式碼**234**重構程式碼**

258 235

260refactor the authentication module to use async/await instead of callbacks237refactor the authentication module to use async/await instead of callbacks

261```238```

262 239

263**編寫測試**240**撰寫測試**

264 241

265```text wrap theme={null}242```text wrap theme={null}

266write unit tests for the calculator functions243write unit tests for the calculator functions

279```256```

280 257

281<Tip>258<Tip>

282 像與有幫助的同事交談一樣與 Claude 交談。描述您想要達成的目標，它將幫助您實現。259 像與一位樂於助人的同事交談一樣與 Claude 對話。描述您想要達成的目標，它就會協助您實現。

283</Tip>260</Tip>

284 261

285<h2 id="essential-commands">262<h2 id="essential-commands">

357 334

358現在您已經學習了基礎知識，請探索更多進階功能：335現在您已經學習了基礎知識，請探索更多進階功能：

359 336

360<CardGroup cols={2}>337* [Claude Code 如何運作](/docs/zh-TW/how-claude-code-works)：了解代理式迴圈、內建工具以及 Claude Code 如何與您的專案互動

361 <Card title="Claude Code 如何運作" icon="microchip" href="/docs/zh-TW/how-claude-code-works">338* [最佳實踐](/docs/zh-TW/best-practices)：透過有效的提示和專案設定獲得更好的結果

362 了解代理迴圈、內建工具以及 Claude Code 如何與您的專案互動339* [常見工作流程](/docs/zh-TW/common-workflows)：常見任務的逐步指南

363 </Card>340* [擴展 Claude Code](/docs/zh-TW/features-overview)：使用 CLAUDE.md、skill、hook、MCP 等進行自訂

~~364~~

365 <Card title="最佳實踐" icon="star" href="/docs/zh-TW/best-practices">

366 透過有效的提示和專案設定獲得更好的結果

367 </Card>

~~368~~

369 <Card title="常見工作流程" icon="graduation-cap" href="/docs/zh-TW/common-workflows">

370 常見任務的逐步指南

371 </Card>

372 341

373 <Card title="擴展 Claude Code" icon="puzzle-piece" href="/docs/zh-TW/features-overview">342請參閱[進階設定](/docs/zh-TW/setup)以了解安裝選項、手動更新或解除安裝說明。

374 使用 CLAUDE.md、skills、hooks、MCP 等進行自訂

375 </Card>

376</CardGroup>

377 343

378<h2 id="getting-help">344<h2 id="getting-help">

379 獲取幫助345 獲取幫助

380</h2>346</h2>

381 347

382* **在 Claude Code 中**：輸入 `/help` 或詢問「how do I」問題348* **在 Claude Code 中**：輸入 `/help` 或詢問「how do I」問題

383* **文件**：您在這裡！瀏覽其他指南349* **文件**：瀏覽本網站上的其他指南

384* **課程**：參加 [Claude Code 101](https://academy.claude.com/courses/claude-code-101) 和其他免費自學課程，位於 [Claude Academy](https://academy.claude.com/)350* **課程**：參加 [Claude Code 101](https://academy.claude.com/courses/claude-code-101) 和其他免費自學課程，位於 [Claude Academy](https://academy.claude.com/)

385* **社群**：加入 [Discord 伺服器](https://www.anthropic.com/discord) 以獲取提示和支援351* **社群**：加入 [Discord 伺服器](https://www.anthropic.com/discord) 以獲取提示和支援

remote-control.md +1 −1

Details

365</h2>365</h2>

366 366

367* **每個互動程序一個遠端工作階段**：在伺服器模式之外，每個 Claude Code 實例一次只支援一個遠端工作階段。使用[伺服器模式](#start-a-remote-control-session)從單一程序執行多個並行工作階段。367* **每個互動程序一個遠端工作階段**：在伺服器模式之外，每個 Claude Code 實例一次只支援一個遠端工作階段。使用[伺服器模式](#start-a-remote-control-session)從單一程序執行多個並行工作階段。

368* **本機程序必須保持執行**：Remote Control 以本機程序的形式執行。如果您關閉終端機、結束 Desktop 應用程式或 VS Code，或以其他方式停止 `claude` 程序，工作階段將離線，直到您[將其恢復](#resume-sessions-after-stopping-the-server)。若要在您從 SSH 中斷連線後讓工作階段在遠端機器上保持執行，請在 `tmux` 或 `screen` 內啟動它。368* **本機程序必須保持執行**：Remote Control 以本機程序的形式執行。如果您關閉終端機、結束 Desktop 應用程式或 VS Code，或以其他方式停止 `claude` 程序，工作階段將離線，直到您[將其恢復](#resume-sessions-after-stopping-the-server)。如果您從遠端機器上的終端機執行 `claude`，請在 `tmux` 或 `screen` 內啟動它，以便在您從 SSH 中斷連線後讓工作階段保持執行。

369* **伺服器模式中的已損毀工作階段**：如果由 `claude remote-control` 提供服務的工作階段損毀，請從已連線的裝置向其傳送訊息。Claude Code 會再次提供服務。您不必重新啟動伺服器。需要 Claude Code v2.1.238 或更新版本。369* **伺服器模式中的已損毀工作階段**：如果由 `claude remote-control` 提供服務的工作階段損毀，請從已連線的裝置向其傳送訊息。Claude Code 會再次提供服務。您不必重新啟動伺服器。需要 Claude Code v2.1.238 或更新版本。

370* **已連線工作階段上的 HTTP 403 拒絕**：一旦互動工作階段已連線，當您的機器與 Anthropic 伺服器之間的某個位置以 HTTP 403 回應時（在 VPN 或網路變更後可能發生），Claude Code 會重試最多三分鐘。如果拒絕持續更久，Claude Code 會中斷連線，原因會指出拒絕的內容：網路邊界，或您自己網路上的代理伺服器、VPN 或防火牆。370* **已連線工作階段上的 HTTP 403 拒絕**：一旦互動工作階段已連線，當您的機器與 Anthropic 伺服器之間的某個位置以 HTTP 403 回應時（在 VPN 或網路變更後可能發生），Claude Code 會重試最多三分鐘。如果拒絕持續更久，Claude Code 會中斷連線，原因會指出拒絕的內容：網路邊界，或您自己網路上的代理伺服器、VPN 或防火牆。

371* **延長的網路中斷**：如果您的機器已開啟但無法連線到網路，您接下來的操作取決於模式：371* **延長的網路中斷**：如果您的機器已開啟但無法連線到網路，您接下來的操作取決於模式：

routines.md +1 −1

Details

93 為例行工作選擇 [cloud environment](/docs/zh-TW/cloud-environments)。環境控制雲端工作階段可以存取的內容：93 為例行工作選擇 [cloud environment](/docs/zh-TW/cloud-environments)。環境控制雲端工作階段可以存取的內容：

94 94

95 * **Network access**：設定每次執行期間可用的網際網路存取級別95 * **Network access**：設定每次執行期間可用的網際網路存取級別

96 * **Environment variables**：提供 Claude 在每次執行期間可以使用的值。它們 [對使用該環境的任何人都可見](/docs/zh-TW/cloud-environments#what-carries-over-from-your-setup)，因此在 Pro 和 Max 方案上，將 Claude 在執行期間呼叫的 API 的金鑰儲存為 [API credentials](/docs/zh-TW/cloud-environments#add-api-credentials)。該部分也列出了永遠不會獲得認證的請求96 * **Environment variables**：提供 Claude 在每次執行期間可以使用的值。這些值[對使用該環境的任何人都可見](/docs/zh-TW/cloud-environments#what-carries-over-from-your-setup)，因此在 Pro 和 Max 方案上，請改將 Claude 在執行期間呼叫的 API 金鑰儲存為 [網路機密](/docs/zh-TW/cloud-environments#add-api-credentials)。該章節也列出了永遠不會取得機密的請求

97 * **Setup script**：安裝例行工作需要的相依性和工具。結果是 [cached](/docs/zh-TW/cloud-environments#environment-caching)，因此指令碼不會在每個工作階段上重新執行97 * **Setup script**：安裝例行工作需要的相依性和工具。結果是 [cached](/docs/zh-TW/cloud-environments#environment-caching)，因此指令碼不會在每個工作階段上重新執行

98 98

99 提供了 **Default** 環境，具有 **Trusted** 網路存取，它只允許 [default allowlist](/docs/zh-TW/cloud-environments#default-allowed-domains) 的套件登錄、雲端提供者 API、容器登錄和常見開發網域透過工作階段的網路。您新增到例行工作的連接器透過 Anthropic 的伺服器存取其服務，因此不需要更改允許清單。如果您的例行工作需要直接存取您自己的服務或該清單外的網域，請在執行前編輯環境的 [network access](/docs/zh-TW/cloud-environments#network-access)。若要使用單獨的環境，請先 [create one](/docs/zh-TW/cloud-environments#configure-your-environment)。99 提供了 **Default** 環境，具有 **Trusted** 網路存取，它只允許 [default allowlist](/docs/zh-TW/cloud-environments#default-allowed-domains) 的套件登錄、雲端提供者 API、容器登錄和常見開發網域透過工作階段的網路。您新增到例行工作的連接器透過 Anthropic 的伺服器存取其服務，因此不需要更改允許清單。如果您的例行工作需要直接存取您自己的服務或該清單外的網域，請在執行前編輯環境的 [network access](/docs/zh-TW/cloud-environments#network-access)。若要使用單獨的環境，請先 [create one](/docs/zh-TW/cloud-environments#configure-your-environment)。

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 |

setup.md +5 −3

Details

49 curl -fsSL https://claude.ai/install.sh | bash49 curl -fsSL https://claude.ai/install.sh | bash

50 ```50 ```

51 51

52 在 Windows 上，當您在 PowerShell 中時，提示字元會顯示 `PS C:\`，而在 CMD 中時會顯示 `C:\`（不含 `PS`）。

52 **Windows PowerShell：**54 **Windows PowerShell：**

53 55

54 ```powershell theme={null}56 ```powershell theme={null}

63 65

64 當安裝程式完成時，請開啟新的終端機視窗並執行 `claude --version`。正常的安裝會列印版本號碼。如果您的殼層說找不到 `claude` 或無法識別，安裝目錄還未在您的 PATH 上：請參閱[修正您的 PATH](/docs/zh-TW/troubleshoot-install#command-not-found-claude-after-installation)。66 當安裝程式完成時，請開啟新的終端機視窗並執行 `claude --version`。正常的安裝會列印版本號碼。如果您的殼層說找不到 `claude` 或無法識別，安裝目錄還未在您的 PATH 上：請參閱[修正您的 PATH](/docs/zh-TW/troubleshoot-install#command-not-found-claude-after-installation)。

65 67

66 如果您看到 `The token '&&' is not a valid statement separator`，表示您在 PowerShell 中，而非 CMD。如果您看到 `'irm' is not recognized as an internal or external command`，表示您在 CMD 中，而非 PowerShell。當您在 PowerShell 中時，提示符會顯示 `PS C:\`，而在 CMD 中時會顯示 `C:\`（不含 `PS`）。68 如果您看到 `The token '&&' is not a valid statement separator`，表示您在 PowerShell 中，而非 CMD。如果您看到 `'irm' is not recognized as an internal or external command`，表示您在 CMD 中，而非 PowerShell。

67 69

68 如果安裝命令失敗並出現 `syntax error near unexpected token '<'`、`403` 或其他 curl 錯誤，請參閱[疑難排解安裝](/docs/zh-TW/troubleshoot-install#find-your-error)以將錯誤與修正相對應，並查看替代安裝方法。70 如果安裝命令失敗並出現 `syntax error near unexpected token '<'`、`403` 或其他任何錯誤，請參閱[疑難排解安裝](/docs/zh-TW/troubleshoot-install#find-your-error)以將錯誤與修正相對應，並查看替代安裝方法。

69 71

70 建議在原生 Windows 上安裝 [Git for Windows](https://git-scm.com/downloads/win)，以便 Claude Code 可以使用 Bash 工具。如果未安裝 Git for Windows，Claude Code 會改用 PowerShell 作為殼層工具。WSL 設定不需要 Git for Windows。72 建議在原生 Windows 上安裝 [Git for Windows](https://git-scm.com/downloads/win)，以便 Claude Code 可以使用 Bash 工具。如果未安裝 Git for Windows，Claude Code 會改用 PowerShell 作為殼層工具。WSL 設定不需要 Git for Windows。

71 73

204 206

205Claude Code 需要 Pro、Max、Team、Enterprise 或 Console 帳戶。免費的 claude.ai 方案不包括 Claude Code 存取權。您也可以透過第三方 API 提供者（如 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai) 或 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)）使用 Claude Code。207Claude Code 需要 Pro、Max、Team、Enterprise 或 Console 帳戶。免費的 claude.ai 方案不包括 Claude Code 存取權。您也可以透過第三方 API 提供者（如 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai) 或 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)）使用 Claude Code。

206 208

207安裝後，執行 `claude` 並按照瀏覽器提示登入。如果設定了 `ANTHROPIC_API_KEY` 環境變數，Claude Code 會提示您一次以核准該金鑰，而不是開啟瀏覽器。請參閱[驗證](/docs/zh-TW/authentication)以了解所有帳戶類型和團隊設定選項。209安裝後，執行 `claude` 並按照瀏覽器提示登入。如果您已設定 `ANTHROPIC_API_KEY` 環境變數，並在 Claude Code 詢問是否使用該金鑰時予以核准，Claude Code 便會略過登入提示。請參閱[身分驗證](/docs/zh-TW/authentication)以了解所有帳戶類型和團隊設定選項。

208 210

209<h2 id="update-claude-code">211<h2 id="update-claude-code">

210 更新 Claude Code212 更新 Claude Code

sub-agents.md +3 −3

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

1281 1281

1282因為 fork 的系統提示和工具定義與父級相同，其第一個請求重複使用父級的 [prompt cache](/docs/zh-TW/prompt-caching#subagents-and-the-cache)。這使得 forking 比為需要相同上下文的任務產生新 subagent 更便宜。1282因為 fork 的系統提示詞和工具定義與父級相同，其第一個請求重複使用父級的[提示快取](/docs/zh-TW/prompt-caching#subagents-and-the-cache)。由於這種重複使用，對於需要相同上下文的任務，fork 的成本比新的 subagent 更低。

1283 1283

1284當 Claude 透過 Agent 工具產生 fork 時，它可以傳遞 `isolation: "worktree"`，以便 fork 的檔案編輯被寫入單獨的 git worktree 而不是您的簽出。Fork 無法產生進一步的 forks。1284當 Claude 透過 Agent 工具產生 fork 時，它可以傳遞 `isolation: "worktree"`，以便 fork 的檔案編輯被寫入單獨的 git worktree 而不是您的簽出。Fork 無法產生進一步的 forks。

1285 1285

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 19:00 UTC