Documentation 2026-10-28 23:57 UTC to 2026-10-29 23:57 UTC

75| :- | :- | :- |75| :- | :- | :- |

76| `"project"` | 專案 `settings.json` 和 hooks；專案 CLAUDE.md 和 `.claude/rules/*.md`；專案 skills、commands 和 subagents | `<cwd>/.claude/` 用於 `settings.json` 和 hooks；`<cwd>` 和每個父目錄用於 CLAUDE.md 和 rules；`<cwd>` 和每個父目錄直到儲存庫根目錄用於 skills、commands 和 subagents，加上您透過 `additionalDirectories` 或 `add_dirs` 選項傳遞的每個目錄的 `.claude/skills/`、`.claude/commands/` 和 `.claude/agents/` 資料夾，SDK 會將其作為 [`--add-dir`](https://code.claude.com/docs/zh-TW/permissions#additional-directories-grant-file-access-not-configuration) 傳遞給 Claude Code |76| `"project"` | 專案 `settings.json` 和 hooks；專案 CLAUDE.md 和 `.claude/rules/*.md`；專案 skills、commands 和 subagents | `<cwd>/.claude/` 用於 `settings.json` 和 hooks；`<cwd>` 和每個父目錄用於 CLAUDE.md 和 rules；`<cwd>` 和每個父目錄直到儲存庫根目錄用於 skills、commands 和 subagents，加上您透過 `additionalDirectories` 或 `add_dirs` 選項傳遞的每個目錄的 `.claude/skills/`、`.claude/commands/` 和 `.claude/agents/` 資料夾，SDK 會將其作為 [`--add-dir`](https://code.claude.com/docs/zh-TW/permissions#additional-directories-grant-file-access-not-configuration) 傳遞給 Claude Code |

77| `"user"` | 使用者 `settings.json`；使用者 CLAUDE.md 和 `~/.claude/rules/*.md`；使用者 skills、commands 和 subagents | `~/.claude/` 用於 `settings.json`、CLAUDE.md 和 rules；`~/.claude/skills/`、`~/.claude/commands/` 和 `~/.claude/agents/` 用於 skills、commands 和 subagents |77| `"user"` | 使用者 `settings.json`；使用者 CLAUDE.md 和 `~/.claude/rules/*.md`；使用者 skills、commands 和 subagents | `~/.claude/` 用於 `settings.json`、CLAUDE.md 和 rules；`~/.claude/skills/`、`~/.claude/commands/` 和 `~/.claude/agents/` 用於 skills、commands 和 subagents |

78| `"local"` | CLAUDE.local.md、`.claude/settings.local.json` | `<cwd>/.claude/` 用於 `settings.local.json`；`<cwd>` 和每個父目錄用於 CLAUDE.local.md |78| `"local"` | CLAUDE.local.md、`.claude/settings.local.json` | `<cwd>/.claude/` 用於 `settings.local.json`，當 `<cwd>` 位於 git 儲存庫內時，該檔案[也可以從儲存庫的根目錄載入](https://code.claude.com/docs/zh-TW/settings.md#where-claude-code-keeps-the-local-file-in-a-git-repository)；`<cwd>` 和每個父目錄用於 CLAUDE.local.md |

79 79 

80省略 `settingSources` 等同於 `["user", "project", "local"]`。80省略 `settingSources` 等同於 `["user", "project", "local"]`。

81 81 

82`cwd` 選項決定 SDK 在何處尋找專案層級輸入。專案 `settings.json` 和 hooks 僅從 `<cwd>/.claude/` 載入，沒有父目錄回退。82`cwd` 選項決定 SDK 在何處尋找專案層級輸入。專案 `settings.json` 僅從 `<cwd>/.claude/` 載入，不會改用父目錄。

83 83 

84### settingSources 不控制的內容84### settingSources 不控制的內容

85 85 

3322 3322 

3323### TaskStop3323### TaskStop

3324 3324 

3325**工具名稱：** `TaskStop`。先前的名稱 `KillShell` 和 `KillBash` 仍被接受為別名。3325**工具名稱：** `TaskStop`。您仍可在權限規則、hook matcher，以及 `tools`、`allowed_tools` 和 `disallowed_tools` 選項中使用先前的名稱 `KillShell` 和 `KillBash`。

3326 3326 

3327**輸入：**3327**輸入：**

3328 3328 

258 258 

259### 雙寫架構259### 雙寫架構

260 260 

261Claude Code 子進程始終首先將每批轉錄條目寫入本地磁碟，然後 SDK 將相同的批次轉發到您的存儲的 `append()`，因此存儲是本地轉錄的鏡像，而不是替代品。哪個副本在運行後保留取決於運行的啟動方式：261Claude Code 子程序始終先將每批逐字稿條目寫入本機磁碟，然後 SDK 將相同的批次轉發到您的儲存區的 `append()`，因此儲存區是本機逐字稿的鏡像，而不是替代品。哪個副本在執行結束後保留，取決於執行的啟動方式：

262 262 

263* **新會話，或當存儲對該會話沒有任何內容時的恢復**：您設定目錄下的本地轉錄在運行後保留，存儲接收一份副本。263* **新工作階段，或當儲存區對該工作階段沒有任何內容時的恢復**：您設定目錄下的本機逐字稿在執行結束後保留，儲存區接收一份副本。

264* **從存儲[恢復的運行](#resume-from-the-store)**：本地副本在運行結束時被刪除，因此存儲持有唯一的持久副本。264* **[從儲存區恢復](#resume-from-the-store)的執行**：本機副本在執行結束時被刪除，因此儲存區持有唯一的持久副本。

265 265 

266如果您不希望新會話在本地磁碟上留下轉錄，請在 `options.env` 中將 `CLAUDE_CONFIG_DIR` 設定為臨時目錄。從存儲恢復的運行已經刪除其本地副本，因此不需要此類設定。在 TypeScript 中，也將 `process.env` 展開到 `env` 中，因為 [`env` 選項](https://code.claude.com/docs/zh-TW/agent-sdk/typescript#options) 會替換子進程環境。266如果您不希望新工作階段在本機磁碟上留下逐字稿，請在 `options.env` 中將 `CLAUDE_CONFIG_DIR` 設定為一個新的私有臨時目錄。從儲存區恢復的執行已經會刪除其本機副本，因此不需要此類設定。在 TypeScript 中，也請將 `process.env` 展開到 `env` 中，因為 [`env` 選項](https://code.claude.com/docs/zh-TW/agent-sdk/typescript#options)會替換子程序環境。

267 267 

268如果您的應用程式通過設定目錄中的檔案進行登入，例如 OAuth 認證或您的使用者 `settings.json` 中的 `apiKeyHelper`，請先將這些檔案複製到臨時目錄中，或改為在 `env` 中設定 `ANTHROPIC_API_KEY`。否則運行會失敗並顯示 `Not logged in`。268如果您將 `CLAUDE_CONFIG_DIR` 設定為臨時目錄，並透過 [claude.ai 登入](https://code.claude.com/docs/zh-TW/authentication.md#credential-management)或您的使用者 `settings.json` 中的 [`apiKeyHelper`](https://code.claude.com/docs/zh-TW/settings-reference#apikeyhelper) 進行登入，執行會失敗並顯示 `Not logged in`。若要為執行進行身分驗證，請設定長期 token、設定 API 金鑰，或複製您的設定檔：

269 269 

270兩個選項與鏡像衝突，如果您將其中任何一個與存儲結合，SDK 會在啟動時拋出異常：270* **長期 token**：如果您以自己的 Claude 訂閱親自執行 agent，請在 `env` 中將 `CLAUDE_CODE_OAUTH_TOKEN` 設定為來自 [`claude setup-token`](https://code.claude.com/docs/zh-TW/authentication#generate-a-long-lived-token) 的 token。該 token 只能用於發出模型請求，因此您的 [claude.ai 連接器](https://code.claude.com/docs/zh-TW/mcp.md#use-mcp-servers-from-claude-ai)在該次執行中無法使用。

271* **API 金鑰**：在 `env` 中設定 `ANTHROPIC_API_KEY`。

272* **設定檔**：如果您透過常用設定目錄中的檔案進行登入，例如 OAuth 憑證或您的使用者 `settings.json` 中的 `apiKeyHelper`，請將這些檔案複製到臨時目錄中。

271 273 

272* **TypeScript 中的 `persistSession: false`**：關閉鏡像所基於的本地寫入。Python SDK 沒有等效的選項。274有兩個選項與鏡像衝突，如果您將其中任何一個與儲存區結合使用，SDK 會在啟動時擲出例外：

273* **檔案檢查點**，TypeScript 中的 `enableFileCheckpointing` 或 Python 中的 `enable_file_checkpointing`：將其檔案備份直接寫入本地磁碟，SDK 不會將其鏡像到存儲。

274 275 

275### 從存儲恢復276* **TypeScript 中的 `persistSession: false`**：關閉鏡像所依據的本機寫入。Python SDK 沒有等效的選項。

277* **檔案檢查點功能**，TypeScript 中的 `enableFileCheckpointing` 或 Python 中的 `enable_file_checkpointing`：將其檔案備份直接寫入本機磁碟，SDK 不會將其鏡像到儲存區。

276 278 

277當您傳遞 `resume`，或 TypeScript 中的 `continue: true` 或 Python 中的 `continue_conversation=True`，以及存儲時，SDK 在生成子進程之前會向存儲詢問轉錄：279### 從儲存區恢復

278 280 

279* **`resume`**：SDK 詢問您傳遞的會話 ID。281當您將 `resume`，或 TypeScript 中的 `continue: true` 或 Python 中的 `continue_conversation=True`，與儲存區一起傳遞時，SDK 會在產生子程序之前向儲存區索取逐字稿：

280* **`continue: true`** 或 **`continue_conversation=True`**：SDK 詢問存儲的最新會話。

281 282 

282當存儲返回轉錄時，SDK 將其寫入臨時設定目錄，運行子進程時 `CLAUDE_CONFIG_DIR` 指向該目錄，並在運行結束時刪除該目錄。該運行寫入的本地轉錄會隨之刪除，這就是為什麼存儲在此路徑上持有唯一的持久副本。283* **`resume`**：SDK 索取您所傳遞 ID 的工作階段。

284* **`continue: true`** 或 **`continue_conversation=True`**：SDK 索取儲存區中最新的工作階段。

283 285 

284SDK 還使用來自您真實設定目錄的檔案來初始化臨時目錄。它複製的內容因語言而異：286當儲存區傳回逐字稿時，SDK 將其寫入臨時設定目錄，在 `CLAUDE_CONFIG_DIR` 指向該目錄的情況下執行子程序，並在執行結束時刪除該目錄。該次執行寫入的本機逐字稿會隨之刪除，這就是為什麼在此路徑上儲存區持有唯一的持久副本。

285 287 

286* **TypeScript**：認證、`.claude.json` 和您的使用者 `settings.json`。從 `settings.json` 中，它會移除在臨時設定目錄下表現不佳的鍵：`enabledPlugins`、`extraKnownMarketplaces`、其 [`additionalMarketplaces`](https://code.claude.com/docs/zh-TW/settings-reference#extraknownmarketplaces) 別名，以及檔案 `env` 區塊中的任何 `CLAUDE_CONFIG_DIR`。在 Agent SDK v0.3.232 之前，SDK 沒有移除別名。在設定中配置的驗證，例如 [`apiKeyHelper`](https://code.claude.com/docs/zh-TW/settings-reference#apikeyhelper)，在您從存儲恢復時有效。在 Agent SDK v0.3.222 之前，TypeScript SDK 只複製認證和 `.claude.json`。288SDK 還會使用來自您真實設定目錄的檔案來初始化臨時目錄。它複製的內容因語言而異：

287* **Python**：僅限認證和 `.claude.json`，因此通過您的使用者 `settings.json` 中的 `apiKeyHelper` 進行驗證的應用程式在從存儲恢復時會失敗並顯示 `Not logged in`。受管或專案設定中的 `apiKeyHelper` 仍然有效，因為 Claude Code 從 `CLAUDE_CONFIG_DIR` 不影響的位置讀取這些檔案。

288 289 

289當存儲對該會話沒有任何內容時，SDK 改為在您的真實設定目錄下運行，結果取決於您傳遞的選項：290* **TypeScript**：憑證、`.claude.json` 和您的使用者 `settings.json`。從 `settings.json` 中，它會移除在臨時設定目錄下運作異常的鍵：`enabledPlugins`、`extraKnownMarketplaces`、其 [`additionalMarketplaces`](https://code.claude.com/docs/zh-TW/settings-reference#extraknownmarketplaces) 別名，以及檔案 `env` 區塊中的任何 `CLAUDE_CONFIG_DIR`。在 Agent SDK v0.3.232 之前，SDK 不會移除該別名。在設定中設定的驗證，例如 [`apiKeyHelper`](https://code.claude.com/docs/zh-TW/settings-reference#apikeyhelper)，在您從儲存區恢復時可正常運作。在 Agent SDK v0.3.222 之前，TypeScript SDK 只複製憑證和 `.claude.json`。

291* **Python**：僅限憑證和 `.claude.json`，因此透過您的使用者 `settings.json` 中的 `apiKeyHelper` 進行驗證的應用程式，在從儲存區恢復時會失敗並顯示 `Not logged in`。受管或專案設定中的 `apiKeyHelper` 仍然有效，因為 Claude Code 從 `CLAUDE_CONFIG_DIR` 不影響的位置讀取這些檔案。

290 292 

291* **`resume`**：兩個 SDK 都將 ID 傳遞給子進程，子進程完全按照沒有存儲的 `resume` 方式恢復本地轉錄。293當儲存區對該工作階段沒有任何內容時，SDK 改為在您的真實設定目錄下執行，結果取決於您傳遞的選項：

292* **TypeScript 中的 `continue: true`**：SDK 啟動新會話。

293* **Python 中的 `continue_conversation=True`**：SDK 從最新的本地會話繼續。

294 294 

295### 鏡像寫入是盡力而為295* **`resume`**：兩個 SDK 都將 ID 傳遞給子程序，子程序會完全如同沒有儲存區時的 `resume` 一樣恢復本機逐字稿。

296* **TypeScript 中的 `continue: true`**：SDK 啟動新工作階段。

297* **Python 中的 `continue_conversation=True`**：SDK 從最新的本機工作階段繼續。

296 298 

297如果 `append()` 拒絕，SDK 會以短暫的退避重試該批次最多兩次，總共最多三次嘗試。超時的呼叫不會重試，因為原始呼叫可能仍然會到達。如果批次仍然失敗，SDK 會記錄錯誤，向迭代器發出 `{ type: "system", subtype: "mirror_error" }` 訊息，丟棄批次，並繼續查詢。因為重試的批次可以重新傳遞已經到達的條目，請在您的 `append()` 實現中按 `entry.uuid` 進行去重。299### 鏡像寫入採盡力而為

298 300 

299存儲中斷不會中斷代理，因為子進程首先在本地寫入。如果您需要檢測存儲資料遺失，請監視 `mirror_error`。在[從存儲恢復](#resume-from-the-store)的運行上，丟棄的批次在運行結束後沒有倖存的副本。301如果 `append()` 拒絕，SDK 會以短暫的退避再重試該批次最多兩次，總共最多嘗試三次。逾時的呼叫不會重試，因為原始呼叫可能仍會送達。如果批次仍然失敗，SDK 會將錯誤寫入日誌，向迭代器發出 `{ type: "system", subtype: "mirror_error" }` 訊息，捨棄該批次，並繼續查詢。由於重試的批次可能重新傳遞已經送達的條目，請在您的 `append()` 實作中依 `entry.uuid` 進行去重。

300 302 

301### `getSessionMessages` 返回後壓縮鏈303儲存區中斷不會中斷 agent，因為子程序會先在本機寫入。如果您需要偵測儲存區資料遺失，請監控 `mirror_error`。在[從儲存區恢復](#resume-from-the-store)的執行中，被捨棄的批次在執行結束後不會留下任何副本。

302 304 

303`getSessionMessages({ sessionStore })` 返回代理在恢復時會看到的連結訊息鏈。自動壓縮後，較早的轉向被摘要替換，因此存儲持有 503 個原始條目的會話可能從 `getSessionMessages` 返回 18 條訊息。對於完整的原始歷史記錄，包括壓縮前的轉向和中繼資料條目，請直接呼叫 `store.load(key)`。305### `getSessionMessages` 傳回壓縮後的鏈

306 

307`getSessionMessages({ sessionStore })` 傳回 agent 在恢復時會看到的連結訊息鏈。自動壓縮後，較早的回合會被摘要取代，因此儲存區持有 503 個原始條目的工作階段，可能從 `getSessionMessages` 傳回 18 則訊息。若要取得完整的原始歷史記錄，包括壓縮前的回合和中繼資料條目，請直接呼叫 `store.load(key)`。

304 308 

305### `forkSession` 不是位元組副本309### `forkSession` 不是位元組副本

306 310 

307`forkSession({ sessionStore })` 讀取來源條目，重寫每個 `sessionId` 欄位並重新映射訊息 UUID，然後在新鍵下附加轉換後的條目。適配器層級的副本或 `CopyObject` 快捷方式會產生仍然參考舊會話 ID 的轉錄，因此 SDK 不使用它。311`forkSession({ sessionStore })` 讀取來源條目，重寫每個 `sessionId` 欄位並重新對應訊息 UUID，然後在新鍵下附加轉換後的條目。轉接器層級的複製或 `CopyObject` 捷徑會產生仍然參照舊工作階段 ID 的逐字稿，因此 SDK 不使用這種方式。

308 312 

309### 子代理轉錄313### Subagent 逐字稿

310 314 

311子代理轉錄在 `subpath: "subagents/agent-<id>"` 下鏡像。`listSubagents({ sessionStore })` 要求適配器實現 `listSubkeys`；`getSubagentMessages({ sessionStore })` 在可用時使用它，但在未定義時回退到直接子路徑。恢復也呼叫 `listSubkeys` 來還原子代理檔案；沒有它，只有主轉錄被具體化。315Subagent 逐字稿會鏡像在 `subpath: "subagents/agent-<id>"` 下。`listSubagents({ sessionStore })` 要求轉接器實作 `listSubkeys`；`getSubagentMessages({ sessionStore })` 在可用時會使用它，但在未定義時會改用直接子路徑。恢復也會呼叫 `listSubkeys` 來還原 subagent 檔案；若沒有它，只有主逐字稿會被具體化。

312 316 

313### 保留317### 保留

314 318 

315SDK 永遠不會自行從您的存儲中刪除。保留是適配器的責任：根據您的合規要求實現 TTL、S3 生命週期原則或排程清理。`CLAUDE_CONFIG_DIR` 下的本地轉錄由 `cleanupPeriodDays` 設定獨立清掃，遵循[保留清掃規則](https://code.claude.com/docs/zh-TW/claude-directory.md#cleaned-up-automatically)。[從存儲恢復](#resume-from-the-store)的運行不會留下本地轉錄，因此對於這些運行，您的存儲保留是唯一的保留。319SDK 永遠不會自行從您的儲存區中刪除資料。保留是轉接器的責任：請根據您的合規要求，使用後端的到期或生命週期機制，或執行排程清理。

320 

321`CLAUDE_CONFIG_DIR` 下的本機逐字稿由 `cleanupPeriodDays` 設定獨立清除，遵循[保留清除規則](https://code.claude.com/docs/zh-TW/claude-directory.md#cleaned-up-automatically)。[從儲存區恢復](#resume-from-the-store)的執行不會留下本機逐字稿，因此對於這些執行，您儲存區的保留機制就是唯一的保留機制。

316 322 

317## 支持於323## 支持於

318 324 

730 730 

731只有部分鍵會在工作階段中途生效：731只有部分鍵會在工作階段中途生效：

732 732 

733* **在下一個回合套用**：`effortLevel`、`ultracode`、`permissions`、`hooks`、`skillOverrides`、`fastMode`、`agent`。切換 `agent` 也會在下一個回合套用該 agent 的模型覆寫和 hook。其系統提示詞會在下一個回合套用，或在[重複使用已記錄系統提示詞](https://code.claude.com/docs/zh-TW/agent-sdk/modifying-system-prompts.md#change-the-prompt-of-an-existing-session)的工作階段中，於工作階段壓縮後套用。733* **於下一個回合套用**：`ultracode`、`permissions`、`hooks`、`skillOverrides`、`fastMode`、`agent`。切換 `agent` 也會在下一個回合套用該 agent 的模型覆寫和 hook。其系統提示詞會在下一個回合套用。在[重複使用已記錄系統提示詞](https://code.claude.com/docs/zh-TW/agent-sdk/modifying-system-prompts.md#change-the-prompt-of-an-existing-session)的工作階段中，會在工作階段壓縮後套用。

734* **在目前回合期間套用**：`model`。若您在 Claude 處理某個回合時切換 `model`，Claude 正在產生的回應會以舊模型完成，而該回合的其餘部分（從 Claude Code 對模型發出的下一次呼叫開始）會使用新模型。subagent 會保留自己的模型。在 v2.1.212 之前，回合中途的切換會等到下一個回合才生效。734* **在目前回合期間套用**：`model`。若您在 Claude 處理某個回合時切換 `model`，Claude 正在產生的回應會以舊模型完成，而該回合的其餘部分（從 Claude Code 對模型發出的下一次呼叫開始）會使用新模型。subagent 會保留自己的模型。在 v2.1.212 之前，回合中途的切換會等到下一個回合才生效。

735* **最遲於下一個回合套用**：`effortLevel`。等級從 Claude Code 對模型的下一次呼叫開始套用。如果[變更 effort 會保留提示快取](https://code.claude.com/docs/zh-TW/prompt-caching.md#changing-effort-level)，例如在使用 API 金鑰或 Claude 訂閱的 Claude Opus 5.5 上，則預期會改為在下一個回合生效。

735* **在工作階段中途無效**：系統提示詞選項。這些選項在啟動時只解析一次，因此即使呼叫成功，執行中的工作階段仍會保留原始值。若要變更它們，請啟動新的工作階段。736* **在工作階段中途無效**：系統提示詞選項。這些選項在啟動時只解析一次，因此即使呼叫成功，執行中的工作階段仍會保留原始值。若要變更它們，請啟動新的工作階段。

736 737 

737`effortLevel` 接受 [effort 等級](https://code.claude.com/docs/zh-TW/model-config.md#adjust-effort-level)名稱。它也接受 `"ultracode"`，這會在開啟 [ultracode](https://code.claude.com/docs/zh-TW/workflows.md#let-claude-decide-with-ultracode) 的情況下請求 `xhigh` effort。`applyFlagSettings()` 宣告 `effortLevel` 時未包含該值，因此在 TypeScript 中請傳入 `{ ultracode: true, effortLevel: "xhigh" }` 以獲得相同結果，或僅傳入 [`ultracode`](https://code.claude.com/docs/zh-TW/settings-reference#ultracode) 鍵，以在工作階段目前的 effort 等級下開啟 ultracode。`ultracode` 值需要 Claude Code v2.1.203 或更新版本，且只有 `applyFlagSettings()` 接受，設定檔中的 `effortLevel` 鍵不接受此值。在 v2.1.284 之前，單獨使用 `ultracode` 鍵也會將等級設為 `xhigh`。738`effortLevel` 接受 [effort 等級](https://code.claude.com/docs/zh-TW/model-config.md#adjust-effort-level)名稱。它也接受 `"ultracode"`，這會在開啟 [ultracode](https://code.claude.com/docs/zh-TW/workflows.md#let-claude-decide-with-ultracode) 的情況下請求 `xhigh` effort。`applyFlagSettings()` 宣告 `effortLevel` 時未包含該值，因此在 TypeScript 中請傳入 `{ ultracode: true, effortLevel: "xhigh" }` 以獲得相同結果，或僅傳入 [`ultracode`](https://code.claude.com/docs/zh-TW/settings-reference#ultracode) 鍵，以在工作階段目前的 effort 等級下開啟 ultracode。`ultracode` 值需要 Claude Code v2.1.203 或更新版本，且只有 `applyFlagSettings()` 接受，設定檔中的 `effortLevel` 鍵不接受此值。在 v2.1.284 之前，單獨使用 `ultracode` 鍵也會將等級設為 `xhigh`。

738 739 

739這些值會寫入旗標設定層，並合併覆蓋在 `query()` 的內嵌 `settings` 選項於啟動時所設定的值之上。這與[本頁優先順序章節](#settings-precedence)所稱的程式化選項屬於同一層級。740這些值會寫入旗標設定層，並合併覆蓋在 `query()` 的內嵌 `settings` 選項於啟動時所設定的內容之上。這與[本頁優先順序章節](#settings-precedence)所稱的程式化選項是同一層級。`effortLevel` 是例外：您傳遞的等級會取代來自 `--effort` 或設定（包括受管設定）的等級，如 [effort 解析順序](https://code.claude.com/docs/zh-TW/model-config.md#adjust-effort-level)所示。

740 741 

741連續呼叫會對頂層鍵進行淺層合併。第二次以 `{ permissions: {...} }` 呼叫時，會取代前一次呼叫的整個 `permissions` 物件，而不是深層合併進去。742連續呼叫會對頂層鍵進行淺層合併。第二次以 `{ permissions: {...} }` 呼叫時，會取代前一次呼叫的整個 `permissions` 物件，而不是深層合併進去。

742 743 

13272. 專案設定（`.claude/settings.json`）13282. 專案設定（`.claude/settings.json`）

13283. 使用者設定（`~/.claude/settings.json`）13293. 使用者設定（`~/.claude/settings.json`）

1329 1330 

1330以程式方式指定的選項（例如 `agents`、`allowedTools` 和 `settings`）會覆寫使用者、專案和本機的檔案系統設定。受管政策設定優先於以程式方式指定的選項。1331`agents`、`allowedTools` 與 `settings` 等程式化選項會覆寫使用者、專案與本機檔案系統設定。若受管政策設定與程式化選項設定了相同的鍵，則套用受管值，但有例外，例如傳給 [`applyFlagSettings()`](#applyflagsettings) 的 `effortLevel`。

1331 1332 

1332### `PermissionMode`1333### `PermissionMode`

1333 1334 

2095`terminal_slash_commands` 指名 `slash_commands` 中介面綁定於本機終端機的項目，例如 `exit`。您可以像傳送 `slash_commands` 中的任何其他項目一樣傳送它們；此欄位的存在是為了讓遠端或行動用戶端能將它們從命令選單中隱藏。此欄位僅在非空時存在，需要 Agent SDK v0.3.229 或更新版本。2096`terminal_slash_commands` 指名 `slash_commands` 中介面綁定於本機終端機的項目，例如 `exit`。您可以像傳送 `slash_commands` 中的任何其他項目一樣傳送它們；此欄位的存在是為了讓遠端或行動用戶端能將它們從命令選單中隱藏。此欄位僅在非空時存在，需要 Agent SDK v0.3.229 或更新版本。

2096 2097 

2097* 每個 `mcp_servers` 項目上的 `source`：伺服器定義的來源，其值與 [`McpServerStatus`](#mcpserverstatus) 的 `source` 相同。需要 Agent SDK v0.3.274 或更新版本。2098* 每個 `mcp_servers` 項目上的 `source`：伺服器定義的來源，其值與 [`McpServerStatus`](#mcpserverstatus) 的 `source` 相同。需要 Agent SDK v0.3.274 或更新版本。

2098* `effort`：Claude Code 在工作階段下一個請求上傳送的 [effort 等級](https://code.claude.com/docs/zh-TW/model-config.md#adjust-effort-level)，若不傳送則為 `null`。Claude Code 只會在傳送給 [Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md) 用戶端的 init 訊息上設定此欄位，並會從您應用程式讀取的 init 訊息中省略它。需要 Agent SDK v0.3.234 或更新版本。2099* `effort`：為工作階段下一個回合設定的 [effort 等級](https://code.claude.com/docs/zh-TW/model-config.md#adjust-effort-level)，或在 Claude Code 未送出任何等級時為 `null`。Claude Code 只在其傳送給 [Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md) 用戶端的 init 訊息上設定此欄位，並在您的應用程式讀取的 init 訊息中省略它。需要 Agent SDK v0.3.234 或更新版本。

2099 2100 

2100`capabilities` 陣列指名此 CLI 實作的協定行為，讓您可以進行功能偵測，而不是比較 `claude_code_version` 字串。這是一個開放集合：請忽略您不認識的值，並檢查您所依賴之行為對應的特定功能。此欄位需要 Claude Code v2.1.205 或更新版本，在較早的 CLI 上不存在。2101`capabilities` 陣列指名此 CLI 實作的協定行為，讓您可以進行功能偵測，而不是比較 `claude_code_version` 字串。這是一個開放集合：請忽略您不認識的值，並檢查您所依賴之行為對應的特定功能。此欄位需要 Claude Code v2.1.205 或更新版本，在較早的 CLI 上不存在。

2101 2102 

369| 要求 | 可用時間 |369| 要求 | 可用時間 |

370| :- | :- |370| :- | :- |

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

372| 驗證 | 工作階段由 claude.ai 帳戶支援：在 CLI 或桌面應用程式中使用 `/login` 登入。Claude Tag 工作階段透過代理程式的身分登入，因此不需要任何步驟。使用 API 金鑰、[閘道令牌](https://code.claude.com/docs/zh-TW/llm-gateway)或雲端提供者認證的工作階段無法發佈。 |372| 身分驗證 | 工作階段由 claude.ai 帳戶支援：在 CLI 或桌面應用程式中使用 `/login` 登入。Claude Tag 工作階段不需要登入步驟。使用 API 金鑰、[閘道 token](https://code.claude.com/docs/zh-TW/llm-gateway) 或雲端提供者憑證的工作階段無法發佈。 |

373| 模型提供者 | Anthropic API。在 [Amazon Bedrock](https://code.claude.com/docs/zh-TW/amazon-bedrock.md)、[Google Cloud 的 Agent Platform](https://code.claude.com/docs/zh-TW/google-vertex-ai.md) 或 [Microsoft Foundry](https://code.claude.com/docs/zh-TW/microsoft-foundry.md) 上不可用。 |373| 模型提供者 | Anthropic API。在 [Amazon Bedrock](https://code.claude.com/docs/zh-TW/amazon-bedrock.md)、[Google Cloud 的 Agent Platform](https://code.claude.com/docs/zh-TW/google-vertex-ai.md) 或 [Microsoft Foundry](https://code.claude.com/docs/zh-TW/microsoft-foundry.md) 上不可用。 |

374| 組織政策 | 客戶管理的加密金鑰 (CMEK)、HIPAA 和[零資料保留](https://code.claude.com/docs/zh-TW/zero-data-retention.md)未為組織啟用。 |374| 組織政策 | 客戶管理的加密金鑰 (CMEK)、HIPAA 和[零資料保留](https://code.claude.com/docs/zh-TW/zero-data-retention.md)未為組織啟用。 |

375| 使用介面 | Claude Code CLI，或 Claude 桌面應用程式版本 1.13576.0 或更新版本。[Claude Tag](https://claude.com/docs/claude-tag/overview) 工作階段在 Claude Tag 和 artifact 都為組織啟用時也可以發佈 artifact。由 [`claude remote-control`](https://code.claude.com/docs/zh-TW/remote-control) 提供服務的工作階段，在由您自己啟動該工作階段時可以發佈 artifact。需要 Claude Code v2.1.281 或更新版本。在 [Agent SDK](https://code.claude.com/docs/zh-TW/agent-sdk/overview.md)、GitHub Action 和 MCP 伺服器情境中預設關閉，當您從自己的終端機或指令碼以 [`-p`](https://code.claude.com/docs/zh-TW/headless) 執行 Claude Code 時，以及設定 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](https://code.claude.com/docs/zh-TW/env-vars) 時亦同。 |375| 使用介面 | Claude Code CLI，或 Claude 桌面應用程式版本 1.13576.0 或更新版本。[Claude Tag](https://claude.com/docs/claude-tag/overview) 工作階段在 Claude Tag 和 artifact 都為組織啟用時也可以發佈 artifact。由 [`claude remote-control`](https://code.claude.com/docs/zh-TW/remote-control) 提供服務的工作階段，在由您自己啟動該工作階段時可以發佈 artifact。需要 Claude Code v2.1.281 或更新版本。在 [Agent SDK](https://code.claude.com/docs/zh-TW/agent-sdk/overview.md)、GitHub Action 和 MCP 伺服器情境中預設關閉，當您從自己的終端機或指令碼以 [`-p`](https://code.claude.com/docs/zh-TW/headless) 執行 Claude Code 時，以及設定 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](https://code.claude.com/docs/zh-TW/env-vars) 時亦同。 |

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

28* **Claude Console**：使用您的 Console 認證登入。您的管理員必須先 [邀請您](#claude-console-authentication)。您可以在有或沒有 [建立 API 金鑰](#sign-in-without-an-api-key) 的情況下登入。28* **Claude Console**：使用您的 Console 認證登入。您的管理員必須先 [邀請您](#claude-console-authentication)。您可以在有或沒有 [建立 API 金鑰](#sign-in-without-an-api-key) 的情況下登入。

29* **雲端提供商**：如果您的組織使用 [Amazon Bedrock](https://code.claude.com/docs/zh-TW/amazon-bedrock.md)、[Google Cloud 的 Agent Platform](https://code.claude.com/docs/zh-TW/google-vertex-ai.md) 或 [Microsoft Foundry](https://code.claude.com/docs/zh-TW/microsoft-foundry.md)，請在執行 `claude` 之前設定所需的環境變數，或在登入提示符處選擇 **3rd-party platform**，這會為 Bedrock 和 Vertex AI 啟動互動式設定精靈。不需要瀏覽器登入。29* **雲端提供商**：如果您的組織使用 [Amazon Bedrock](https://code.claude.com/docs/zh-TW/amazon-bedrock.md)、[Google Cloud 的 Agent Platform](https://code.claude.com/docs/zh-TW/google-vertex-ai.md) 或 [Microsoft Foundry](https://code.claude.com/docs/zh-TW/microsoft-foundry.md)，請在執行 `claude` 之前設定所需的環境變數，或在登入提示符處選擇 **3rd-party platform**，這會為 Bedrock 和 Vertex AI 啟動互動式設定精靈。不需要瀏覽器登入。

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

31 31 

32管理員可以指示開發人員使用哪種登入方法，並要求 claude.ai 登入屬於特定組織；請參閱 [限制登入到您的組織](#restrict-login-to-your-organization)。32管理員可以指示開發人員使用哪種登入方法，並要求 claude.ai 登入屬於特定組織；請參閱 [限制登入到您的組織](#restrict-login-to-your-organization)。

33 33 

353 353 

354| 功能 | 它的作用 | 適合 |354| 功能 | 它的作用 | 適合 |

355| - | - | - |355| - | - | - |

356| [網路上的 Claude Code](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md) | 在新鮮雲端沙箱中執行任務，從 GitHub 複製 | 委派您稍後檢查的自包含非同步工作 |356| [雲端工作階段](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md) | 在新鮮雲端沙箱中執行任務，從 GitHub 複製 | 委派您稍後檢查的自包含非同步工作 |

357| [Slack 中的 Claude](https://code.claude.com/docs/zh-TW/slack.md) | 從頻道或執行緒中的 `@Claude` 提及產生雲端工作階段 | 直接從團隊對話內容啟動任務 |357| [Slack 中的 Claude](https://code.claude.com/docs/zh-TW/slack.md) | 從頻道或執行緒中的 `@Claude` 提及產生雲端工作階段 | 直接從團隊對話內容啟動任務 |

358| 標準 [MCP 伺服器](https://code.claude.com/docs/zh-TW/mcp.md) | Claude 在任務期間查詢它；沒有任何東西被推送到工作階段 | 讓 Claude 按需存取讀取或查詢系統 |358| 標準 [MCP 伺服器](https://code.claude.com/docs/zh-TW/mcp.md) | Claude 在任務期間查詢它；沒有任何東西被推送到工作階段 | 讓 Claude 按需存取讀取或查詢系統 |

359| [遠端控制](https://code.claude.com/docs/zh-TW/remote-control.md) | 您從 claude.ai 或 Claude 行動應用程式驅動您的本地工作階段 | 在遠離您的桌子時引導進行中的工作階段 |359| [Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md) | 您從 claude.ai 或 Claude 行動應用程式驅動您的本地工作階段 | 在遠離您的桌子時引導進行中的工作階段 |

360 360 

361Channels 通過將來自非 Claude 來源的事件推送到您已執行的本地工作階段，填補該清單中的空白。361Channels 通過將來自非 Claude 來源的事件推送到您已執行的本地工作階段，填補該清單中的空白。

362 362 

368一旦您有 channel 執行，請探索這些相關功能：368一旦您有 channel 執行，請探索這些相關功能：

369 369 

370* [建立您自己的 channel](https://code.claude.com/docs/zh-TW/channels-reference.md)，用於尚未有外掛程式的系統370* [建立您自己的 channel](https://code.claude.com/docs/zh-TW/channels-reference.md)，用於尚未有外掛程式的系統

371* [遠端控制](https://code.claude.com/docs/zh-TW/remote-control.md)，從您的手機驅動本地工作階段，而不是將事件轉發到其中371* [Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md)，從您的手機驅動本地工作階段，而不是將事件轉發到其中

372* [工作階段範圍的排程任務](https://code.claude.com/docs/zh-TW/scheduled-tasks.md)，按計時器輪詢，而不是對推送事件做出反應372* [工作階段範圍的排程任務](https://code.claude.com/docs/zh-TW/scheduled-tasks.md)，按計時器輪詢，而不是對推送事件做出反應

107>107>

108> 預設啟用 Chrome 會增加上下文使用量，因為瀏覽器工具及其指示會一直處於載入狀態。如果您發現上下文消耗增加，請關閉此設定，僅在需要時連接：在 CLI 中使用 `--chrome`，或在 VS Code 提示詞輸入框中輸入 [`@browser`](https://code.claude.com/docs/zh-TW/vs-code#automate-browser-tasks-with-chrome)。108> 預設啟用 Chrome 會增加上下文使用量，因為瀏覽器工具及其指示會一直處於載入狀態。如果您發現上下文消耗增加，請關閉此設定，僅在需要時連接：在 CLI 中使用 `--chrome`，或在 VS Code 提示詞輸入框中輸入 [`@browser`](https://code.claude.com/docs/zh-TW/vs-code#automate-browser-tasks-with-chrome)。

109 109 

110### 回應啟動對話方塊

111 

112如果啟動 `claude` 時出現「Claude in Chrome extension detected」對話方塊，您的回答會變更[**預設啟用**設定](#enable-chrome-by-default)：

113 

114* **Yes, use my browser**：開啟此設定並連接此工作階段

115* **No, keep browser tools off**，或按 Esc：關閉此設定，且 Claude Code 將不再提議設定 Chrome

116 

117若要為之後的工作階段變更您的回答，請執行 `/chrome`。

118 

110### 管理網站權限119### 管理網站權限

111 120 

112網站層級的權限繼承自 Chrome 擴充功能。請在 Chrome 擴充功能設定中管理權限，以控制 Claude 可以在哪些網站上瀏覽、點擊和輸入。在[自動模式](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode)中，當自動模式分類器本身核准了對某個網站的瀏覽器呼叫時，擴充功能會針對該次呼叫略過其自身的逐網站檢查，除非您的權限規則拒絕 Claude in Chrome 存取任何網站。121網站層級的權限繼承自 Chrome 擴充功能。請在 Chrome 擴充功能設定中管理權限，以控制 Claude 可以在哪些網站上瀏覽、點擊和輸入。在[自動模式](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode)中，當自動模式分類器本身核准了對某個網站的瀏覽器呼叫時，擴充功能會針對該次呼叫略過其自身的逐網站檢查，除非您的權限規則拒絕 Claude in Chrome 存取任何網站。

35* **遙測**：每個設定的目的地接收[OpenTelemetry Protocol (OTLP) 指標](https://code.claude.com/docs/zh-TW/monitoring-usage.md)，預設包含 token 計數、模型、使用者身分和延遲，日誌和追蹤則可按目的地選擇加入。35* **遙測**：每個設定的目的地接收[OpenTelemetry Protocol (OTLP) 指標](https://code.claude.com/docs/zh-TW/monitoring-usage.md)，預設包含 token 計數、模型、使用者身分和延遲，日誌和追蹤則可按目的地選擇加入。

36* **上游路由**：用戶端向閘道使用 Anthropic Messages API，閘道為每個上游進行轉換，無論是 Amazon Bedrock、[AWS 上的 Claude Platform](https://code.claude.com/docs/zh-TW/claude-platform-on-aws.md)、Google Cloud 的 Agent Platform、Microsoft Foundry 或 Anthropic API，並在它們之間進行故障轉移。您可以變更區域、提供商或故障轉移順序，而開發人員無需察覺或重新設定。36* **上游路由**：用戶端向閘道使用 Anthropic Messages API，閘道為每個上游進行轉換，無論是 Amazon Bedrock、[AWS 上的 Claude Platform](https://code.claude.com/docs/zh-TW/claude-platform-on-aws.md)、Google Cloud 的 Agent Platform、Microsoft Foundry 或 Anthropic API，並在它們之間進行故障轉移。您可以變更區域、提供商或故障轉移順序，而開發人員無需察覺或重新設定。

37 37 

38![圖表顯示 Claude Code 用戶端和 Claude Desktop 的 Chat、Cowork 和 Code 標籤透過 HTTPS 和持有人 token 連接到您基礎設施內的自行託管 Claude 應用程式閘道，該閘道透過您的 IdP 讓使用者登入，在 PostgreSQL 中儲存身分驗證狀態，將遙測轉發到您的 OTLP 收集器，並將推理轉發到 Amazon Bedrock、AWS 上的 Claude Platform、Google Cloud、Microsoft Foundry 或 Anthropic API](https://mintcdn.com/claude-code/VbyXug8hBU9UK6oT/images/claude-gateway-architecture.svg?fit=max\&auto=format\&n=VbyXug8hBU9UK6oT\&q=85\&s=9e4f1190fc56718144190a3db61c63af)38![圖表顯示 Claude Code 用戶端和 Claude Desktop 透過 HTTPS 和持有人 token 連接到您基礎設施內的自行託管 Claude 應用程式閘道，該閘道透過您的 IdP 讓使用者登入，在 PostgreSQL 中儲存身分驗證狀態，將遙測中繼到您的 OTLP 收集器，並將推理轉發到 Amazon Bedrock、AWS 上的 Claude Platform、Google Cloud、Microsoft Foundry 或 Anthropic API](https://mintcdn.com/claude-code/VbyXug8hBU9UK6oT/images/claude-gateway-architecture.svg?fit=max\&auto=format\&n=VbyXug8hBU9UK6oT\&q=85\&s=9e4f1190fc56718144190a3db61c63af)

39 39 

40> [!NOTE]40> [!NOTE]

41>41>

350 350 

351### 將原則傳遞給 Claude Desktop 工作階段351### 將原則傳遞給 Claude Desktop 工作階段

352 352 

353Claude Desktop 以內嵌的 Claude Code 工作階段執行其 Cowork 和 Code 分頁（以及啟用時的 Chat 分頁），並透過閘道傳送它們的模型請求。它會將原則傳遞給每個這類工作階段，而原則是依據閘道在 `/user/bootstrap` 提供給它的設定所建立：模型允許清單、停用的工具，以及從相符原則的 `cli` 或 `code` 區塊推導出的對外連線允許清單，再加上 [`desktop` 覆蓋層](https://code.claude.com/docs/zh-TW/claude-apps-gateway-config#claude-desktop-overlay)。353Claude Desktop 的 Cowork 和 Code 分頁，以及啟用時的 Chat，皆在內嵌的 Claude Code 工作階段上執行，並透過閘道傳送其模型請求。它會將原則傳遞給每個工作階段，這些原則是根據閘道在 `/user/bootstrap` 提供給它的設定所建構而成：包括從所符合原則的 `cli` 或 `code` 區塊衍生而來的模型允許清單、已停用的工具及輸出允許清單，以及 [`desktop` 覆蓋設定](https://code.claude.com/docs/zh-TW/claude-apps-gateway-config#claude-desktop-overlay)。

354 354 

355該區塊的其他鍵，例如 hook、`env`，以及 `Bash(npm *)` 這類有範圍限定的權限規則，會送達透過 `/login` 登入的用戶端。在 `code` 之下時，當 [Code 分頁的條件](https://code.claude.com/docs/zh-TW/claude-apps-gateway-config.md#apply-code-settings-in-the-code-tab)成立，它們也會送達 Code 分頁的工作階段。它們不會送達 Cowork 或 Chat 工作階段。Claude Desktop 從自己的受管設定讀取閘道 URL，並以自己的流程登入，與[設定閘道 URL](#set-the-gateway-url) 中的 `forceLoginMethod` 和 `forceLoginGatewayUrl` 鍵分開。355該區塊的其他鍵，例如 hook、`env`，以及 `Bash(npm *)` 這類有範圍限定的權限規則，會送達透過 `/login` 登入的用戶端。在 `code` 之下時，當 [Code 分頁的條件](https://code.claude.com/docs/zh-TW/claude-apps-gateway-config.md#apply-code-settings-in-the-code-tab)成立，它們也會送達 Code 分頁的工作階段。它們不會送達 Cowork 或 Chat 工作階段。Claude Desktop 從自己的受管設定讀取閘道 URL，並以自己的流程登入，與[設定閘道 URL](#set-the-gateway-url) 中的 `forceLoginMethod` 和 `forceLoginGatewayUrl` 鍵分開。

356 356 

480 480 

481Claude Desktop 會透過閘道的身分識別提供者，以相同的瀏覽器 SSO 步驟讓開發人員登入，然後從閘道而非 Anthropic 擷取其設定。模型存取與原則遵循與 CLI 相同的各群組規則。同時使用 CLI 和 Claude Desktop 的開發人員需分別登入兩者；兩者之間不共用閘道工作階段。481Claude Desktop 會透過閘道的身分識別提供者，以相同的瀏覽器 SSO 步驟讓開發人員登入，然後從閘道而非 Anthropic 擷取其設定。模型存取與原則遵循與 CLI 相同的各群組規則。同時使用 CLI 和 Claude Desktop 的開發人員需分別登入兩者；兩者之間不共用閘道工作階段。

482 482 

483連接後，Claude Desktop 會透過閘道傳送每個已啟用分頁的模型請求。預設會顯示 Cowork 和 Code 分頁。若也要開啟 Chat 分頁，請在 Claude Desktop 的[受管設定](https://claude.com/docs/third-party/claude-desktop/configuration)中將 `chatTabEnabled` 設為 `true`，或在執行 Claude Code v2.1.227 或更新版本的閘道上，於原則的 [`desktop` 區塊](https://code.claude.com/docs/zh-TW/claude-apps-gateway-config#claude-desktop-overlay)中設定。483連接後，Claude Desktop 會透過閘道傳送每個已啟用分頁的模型請求。預設會顯示 Cowork 和 Code 分頁。若也要讓 Chat 可用，請在執行 Claude Code v2.1.227 或更新版本的閘道上，於原則的 [`desktop` 區塊](https://code.claude.com/docs/zh-TW/claude-apps-gateway-config#claude-desktop-overlay)中將 `chatTabEnabled` 設為 `true`。開啟 Cowork 時，Claude Desktop 便會在同一個分頁中一併顯示 Chat 和 Cowork。

484 484 

485### CI 管線與遠端電腦485### CI 管線與遠端電腦

486 486 

523| 推理轉發 (Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform、Microsoft Foundry、Anthropic) | 可用 | 具有按上游模型轉換和故障轉移。Amazon Bedrock 上游使用 `bedrock-runtime` 端點和 AWS 預設憑證鏈。[Amazon Bedrock Mantle 上游](https://code.claude.com/docs/zh-TW/claude-apps-gateway-config.md#amazon-bedrock-mantle-endpoint)需要閘道伺服器上的 Claude Code v2.1.283 或更新版本，而 [Claude Platform on AWS 上游](https://code.claude.com/docs/zh-TW/claude-apps-gateway-config.md#claude-platform-on-aws)需要 v2.1.198 或更新版本。 |523| 推理轉發 (Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform、Microsoft Foundry、Anthropic) | 可用 | 具有按上游模型轉換和故障轉移。Amazon Bedrock 上游使用 `bedrock-runtime` 端點和 AWS 預設憑證鏈。[Amazon Bedrock Mantle 上游](https://code.claude.com/docs/zh-TW/claude-apps-gateway-config.md#amazon-bedrock-mantle-endpoint)需要閘道伺服器上的 Claude Code v2.1.283 或更新版本，而 [Claude Platform on AWS 上游](https://code.claude.com/docs/zh-TW/claude-apps-gateway-config.md#claude-platform-on-aws)需要 v2.1.198 或更新版本。 |

524| 1M token 上下文視窗 | 可用 | Fable 模型、Sonnet 5 及更新版本，以及 Opus 4.7 及更新版本預設以 1M 視窗執行；請參閱[擴展上下文](https://code.claude.com/docs/zh-TW/model-config.md#extended-context)。Fable 和 Opus 模型的 1M 預設需要開發人員機器上的 Claude Code v2.1.287 或更新版本 |524| 1M token 上下文視窗 | 可用 | Fable 模型、Sonnet 5 及更新版本，以及 Opus 4.7 及更新版本預設以 1M 視窗執行；請參閱[擴展上下文](https://code.claude.com/docs/zh-TW/model-config.md#extended-context)。Fable 和 Opus 模型的 1M 預設需要開發人員機器上的 Claude Code v2.1.287 或更新版本 |

525| 按 IdP 群組的模型存取和受管設定 | 可用 | 模型存取在伺服器端強制執行；受管設定按 IdP 群組傳遞，由 CLI 在[受管設定層級](https://code.claude.com/docs/zh-TW/settings.md#settings-precedence)應用 |525| 按 IdP 群組的模型存取和受管設定 | 可用 | 模型存取在伺服器端強制執行；受管設定按 IdP 群組傳遞，由 CLI 在[受管設定層級](https://code.claude.com/docs/zh-TW/settings.md#settings-precedence)應用 |

526| Claude Desktop | 可用（需要選擇加入） | 閘道在 `/user/bootstrap` 提供 Claude Desktop 的設定，一旦原則[使用 `desktop` 金鑰選擇加入](https://code.claude.com/docs/zh-TW/claude-apps-gateway-config#claude-desktop-overlay)，Claude Desktop 從其 Cowork 和 Code 標籤以及從 Chat 標籤（當您啟用它時）發送模型請求透過閘道。若要開啟 Chat 標籤，請參閱[連接 Claude Desktop](#connect-claude-desktop)。需要閘道伺服器上的 Claude Code v2.1.203 或更新版本。 |526| Claude Desktop | 可用（需要選擇加入） | 一旦原則[使用 `desktop` 金鑰選擇加入](https://code.claude.com/docs/zh-TW/claude-apps-gateway-config#claude-desktop-overlay)，閘道便會在 `/user/bootstrap` 提供 Claude Desktop 的設定，而 Claude Desktop 會透過閘道發送其模型請求。若要開啟 Chat，請參閱[連接 Claude Desktop](#connect-claude-desktop)。需要閘道伺服器上的 Claude Code v2.1.203 或更新版本。 |

527| 遙測扇出 (OTLP/HTTP) | 可用 | 按匯出標識戳記；protobuf 和 JSON 編碼 |527| 遙測扇出 (OTLP/HTTP) | 可用 | 按匯出標識戳記；protobuf 和 JSON 編碼 |

528| OIDC 身份提供者 | 可用 | 任何符合 OIDC 的 IdP；閘道執行標準 OIDC 探索和授權碼流程。請參閱[身份提供者設定](https://code.claude.com/docs/zh-TW/claude-apps-gateway-deploy.md#identity-provider-setup)以了解各 IdP 的設定 |528| OIDC 身份提供者 | 可用 | 任何符合 OIDC 的 IdP；閘道執行標準 OIDC 探索和授權碼流程。請參閱[身份提供者設定](https://code.claude.com/docs/zh-TW/claude-apps-gateway-deploy.md#identity-provider-setup)以了解各 IdP 的設定 |

529| 按使用者和按群組支出限制 | 可用 | 請參閱[支出限制](https://code.claude.com/docs/zh-TW/claude-apps-gateway-spend-limits.md) |529| 按使用者和按群組支出限制 | 可用 | 請參閱[支出限制](https://code.claude.com/docs/zh-TW/claude-apps-gateway-spend-limits.md) |

201 201 

202使用以下任何方式將雲端工作階段拉入您的終端機：202使用以下任何方式將雲端工作階段拉入您的終端機：

203 203 

204* **使用 `--teleport`**：從命令列執行 `claude --teleport` 以取得互動式工作階段選擇器，或 `claude --teleport <session-id>` 以直接繼續特定工作階段。如果您有未提交的變更，系統會提示您先將它們隱藏。204* **使用 `--teleport`**：從命令列執行 `claude --teleport` 以取得互動式工作階段選擇器，或 `claude --teleport <session-id>` 以直接繼續特定工作階段。如果您有未提交的變更，系統會提示您先將它們隱藏。[`--resume`](https://code.claude.com/docs/zh-TW/sessions#resume-a-session) 會從此機器的本機歷史記錄重新開啟對話，不會列出雲端工作階段。

205* **使用 `/teleport`**：在現有 CLI 工作階段內執行 `/teleport` 或 `/tp` 以開啟相同的工作階段選擇器，無需重新啟動 Claude Code。205* **使用 `/teleport`**：在現有 CLI 工作階段內執行 `/teleport` 或 `/tp` 以開啟相同的工作階段選擇器，無需重新啟動 Claude Code。

206* **從 `/tasks`**：執行 `/tasks` 以查看您的背景工作階段，然後按 `t` 以 teleport 進入其中一個。206* **從 `/tasks`**：執行 `/tasks` 以查看您的背景工作階段，然後按 `t` 以 teleport 進入其中一個。

207* **從 claude.ai/code**：從工作階段功能表選擇 **Open in > Terminal** 以複製可以貼到您的終端機的命令。207* **從 claude.ai/code**：從工作階段功能表選擇 **Open in > Terminal** 以複製可以貼到您的終端機的命令。

208* **從雲端工作階段內**：輸入 `/teleport`，Claude Code 會回覆確切的 `claude --teleport <session-id>` 命令，準備從儲存庫的簽出執行。需要工作階段環境中的 Claude Code v2.1.223 或更新版本。208* **從雲端工作階段內**：輸入 `/teleport`，Claude Code 會回覆確切的 `claude --teleport <session-id>` 命令，準備從儲存庫的簽出執行。需要工作階段環境中的 Claude Code v2.1.223 或更新版本。

209 209 

210當您 teleport 工作階段時，Claude 會驗證您在正確的儲存庫中，擷取並簽出雲端工作階段的分支，並將完整的對話歷史記錄載入您的終端機。終端機會取得工作階段的自己副本：那裡的新工作保持本機，不會出現在 claude.ai 上的雲端工作階段或 Claude 行動應用程式中。若要在 teleport 後繼續從您的手機控制，請在本機工作階段中啟動 [`/remote-control`](https://code.claude.com/docs/zh-TW/remote-control)。210當您 teleport 工作階段時，Claude 會驗證您在正確的儲存庫中，擷取並簽出雲端工作階段的分支，並將對話載入您的終端機。

211 211 

212`--teleport` 與 `--resume` 不同。`--resume` 從此機器的本機歷史記錄重新開啟對話，不列出雲端工作階段；`--teleport` 拉入雲端工作階段及其分支。212> [!NOTE]

213>

214> 如果 Claude Code 已[壓縮](https://code.claude.com/docs/zh-TW/context-window.md#what-survives-compaction)雲端工作階段（在長時間的工作階段中會自動執行），它所摘要的較早訊息不會複製到您的終端機。Claude 會從摘要繼續。若要閱讀原始訊息，請在 claude.ai 或 Claude 行動應用程式上的雲端工作階段中向上捲動。

215 

216終端機會取得工作階段的自己副本：那裡的新工作保持本機，不會出現在 claude.ai 上的雲端工作階段或 Claude 行動應用程式中。若要在 teleport 後繼續從您的手機控制，請在本機工作階段中啟動 [`/remote-control`](https://code.claude.com/docs/zh-TW/remote-control)。

213 217 

214#### Teleport 需求218#### Teleport 需求

215 219 

495* **速率限制**：雲端工作階段與您帳戶內所有其他 Claude 和 Claude Code 使用共享速率限制。並行執行多個任務會按比例消耗更多速率限制。499* **速率限制**：雲端工作階段與您帳戶內所有其他 Claude 和 Claude Code 使用共享速率限制。並行執行多個任務會按比例消耗更多速率限制。

496* **時間限制**：Claude 執行的命令和 SessionStart hooks 有您可以變更的預設逾時，且設定指令碼只有在大約五分鐘內完成時才會被快取。請參閱[時間限制](https://code.claude.com/docs/zh-TW/cloud-environments.md#time-limits)500* **時間限制**：Claude 執行的命令和 SessionStart hooks 有您可以變更的預設逾時，且設定指令碼只有在大約五分鐘內完成時才會被快取。請參閱[時間限制](https://code.claude.com/docs/zh-TW/cloud-environments.md#time-limits)

497* **儲存庫驗證**：您只能在驗證到相同帳戶時將雲端工作階段拉入您的終端機501* **儲存庫驗證**：您只能在驗證到相同帳戶時將雲端工作階段拉入您的終端機

498* **平台限制**：儲存庫複製和拉取請求建立需要 GitHub。自託管 [GitHub Enterprise Server](https://code.claude.com/docs/zh-TW/github-enterprise-server.md) 執行個體支援 Team 和 Enterprise 計畫。您可以透過設定 `CCR_FORCE_BUNDLE=1`，將 GitLab、Bitbucket 或其他非 GitHub 儲存庫作為[本機捆綁](#send-local-repositories-without-github)發送到雲端工作階段，但工作階段無法將結果推送回該遠端502* **平台限制**：在 Anthropic 託管環境中複製儲存庫以及建立 pull request 需要 GitHub。自託管 [GitHub Enterprise Server](https://code.claude.com/docs/zh-TW/github-enterprise-server.md) 執行個體支援 Team 和 Enterprise 計畫。您可以透過設定 `CCR_FORCE_BUNDLE=1`，將 GitLab、Bitbucket 或其他非 GitHub 儲存庫作為[本機捆綁](#send-local-repositories-without-github)發送到雲端工作階段，但工作階段無法將結果推送回該遠端

503 * **自託管環境**：若儲存庫位於其他 git 主機上，請參閱[使用 `--environment` 啟動工作階段的需求](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy#start-a-session-on-a-repository-outside-github)。

499* **組織 IP 允許清單**：雲端工作階段從 Anthropic 管理的基礎設施而不是您的網路呼叫 Anthropic API，而[自託管環境](https://code.claude.com/docs/zh-TW/self-hosted-environments)中的工作階段從您自己的網路呼叫它。如果您的組織啟用了 [IP 允許清單](https://support.claude.com/en/articles/13200993-restrict-access-to-claude-with-ip-allowlisting)，每個 Anthropic 託管的雲端工作階段都會失敗，出現身分驗證錯誤。504* **組織 IP 允許清單**：雲端工作階段從 Anthropic 管理的基礎設施而不是您的網路呼叫 Anthropic API，而[自託管環境](https://code.claude.com/docs/zh-TW/self-hosted-environments)中的工作階段從您自己的網路呼叫它。如果您的組織啟用了 [IP 允許清單](https://support.claude.com/en/articles/13200993-restrict-access-to-claude-with-ip-allowlisting)，每個 Anthropic 託管的雲端工作階段都會失敗，出現身分驗證錯誤。

500 * **Code Review 和排程任務**：這同樣適用於 [Code Review](https://code.claude.com/docs/zh-TW/code-review.md)，以及在 Anthropic 託管環境中執行的[雲端排程任務](https://code.claude.com/docs/zh-TW/routines.md)。路由到自託管環境的排程任務會從您自己的網路呼叫 API。505 * **Code Review 和排程任務**：這同樣適用於 [Code Review](https://code.claude.com/docs/zh-TW/code-review.md)，以及在 Anthropic 託管環境中執行的[雲端排程任務](https://code.claude.com/docs/zh-TW/routines.md)。路由到自託管環境的排程任務會從您自己的網路呼叫 API。

501 * **取得豁免**：聯絡 [Anthropic 支援](https://support.claude.com/)，以從您組織的 IP 允許清單中豁免 Anthropic 託管的服務。506 * **取得豁免**：聯絡 [Anthropic 支援](https://support.claude.com/)，以從您組織的 IP 允許清單中豁免 Anthropic 託管的服務。

8 8 

9Claude Code 從您的專案目錄和主目錄中的 `~/.claude` 讀取指令、設定、skills、subagents 和記憶。將專案檔案提交到 git 以與您的團隊共享；`~/.claude` 中的檔案是個人設定，適用於您的所有專案。9Claude Code 從您的專案目錄和主目錄中的 `~/.claude` 讀取指令、設定、skills、subagents 和記憶。將專案檔案提交到 git 以與您的團隊共享；`~/.claude` 中的檔案是個人設定，適用於您的所有專案。

10 10 

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

12 12 

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

14 14 

76| [`agents/*.md`](#ce-agents) | 專案和全域 | ✓ | Subagent 定義及其自己的提示和工具 | [Subagents](https://code.claude.com/docs/zh-TW/sub-agents.md) |76| [`agents/*.md`](#ce-agents) | 專案和全域 | ✓ | Subagent 定義及其自己的提示和工具 | [Subagents](https://code.claude.com/docs/zh-TW/sub-agents.md) |

77| [`workflows/*.js`](#ce-workflows) | 專案和全域 | ✓ | Claude 撰寫並從 `/workflows` 儲存的動態工作流程指令碼；每個檔案都會變成 `/<name>` 命令 | [Dynamic workflows](https://code.claude.com/docs/zh-TW/workflows.md) |77| [`workflows/*.js`](#ce-workflows) | 專案和全域 | ✓ | Claude 撰寫並從 `/workflows` 儲存的動態工作流程指令碼；每個檔案都會變成 `/<name>` 命令 | [Dynamic workflows](https://code.claude.com/docs/zh-TW/workflows.md) |

78| [`agent-memory/<name>/`](#ce-agent-memory) | 專案和全域 | ✓ | Subagents 的持久記憶 | [Persistent memory](https://code.claude.com/docs/zh-TW/sub-agents.md#enable-persistent-memory) |78| [`agent-memory/<name>/`](#ce-agent-memory) | 專案和全域 | ✓ | Subagents 的持久記憶 | [Persistent memory](https://code.claude.com/docs/zh-TW/sub-agents.md#enable-persistent-memory) |

79| [`~/.claude.json`](#ce-claude-json) | 僅全域 | | 應用程式狀態、帳戶詳細資料、UI 切換、個人 MCP 伺服器 | [Global config](https://code.claude.com/docs/zh-TW/settings-reference.md#global-config-settings) |79| [`~/.claude.json`](#ce-claude-json) | 僅全域 | | 應用程式狀態、帳戶詳細資料、UI 切換、個人 MCP 伺服器。若此檔案不存在，Claude Code 會在您啟動工作階段或執行子命令（例如 `claude auth status`）時建立它，但執行 `--version` 或 `--help` 時不會建立。 | [Global config](https://code.claude.com/docs/zh-TW/settings-reference.md#global-config-settings) |

80| [`projects/<project>/memory/`](#ce-global-projects) | 僅全域 | | 自動記憶：Claude 在工作階段間對自己的筆記 | [Auto memory](https://code.claude.com/docs/zh-TW/memory.md#auto-memory) |80| [`projects/<project>/memory/`](#ce-global-projects) | 僅全域 | | 自動記憶：Claude 在工作階段間對自己的筆記 | [Auto memory](https://code.claude.com/docs/zh-TW/memory.md#auto-memory) |

81| [`keybindings.json`](#ce-keybindings) | 僅全域 | | 自訂快捷鍵 | [Keybindings](https://code.claude.com/docs/zh-TW/keybindings.md) |81| [`keybindings.json`](#ce-keybindings) | 僅全域 | | 自訂快捷鍵 | [Keybindings](https://code.claude.com/docs/zh-TW/keybindings.md) |

82| [`themes/*.json`](#ce-themes) | 僅全域 | | 自訂色彩主題 | [Custom themes](https://code.claude.com/docs/zh-TW/terminal-config.md#create-a-custom-theme) |82| [`themes/*.json`](#ce-themes) | 僅全域 | | 自訂色彩主題 | [Custom themes](https://code.claude.com/docs/zh-TW/terminal-config.md#create-a-custom-theme) |

411 411 

412Project 比單個工作階段更快地使用您的限制，特別是在 Pro 方案上，您應該期望在執行一個的日子裡更快到達您的限制。project 的這些部分使用您的方案：412Project 比單個工作階段更快地使用您的限制，特別是在 Pro 方案上，您應該期望在執行一個的日子裡更快到達您的限制。project 的這些部分使用您的方案：

413 413 

414* **執行中的執行緒**：每個都是一個完整的工作階段，多個可以同時執行。沒有固定數字；Claude 啟動工作需要的數量，您 [要求](#tune-how-claude-runs-a-project) 的限制是偏好而不是上限。強制執行的限制是每天跨您的 projects 200 個新執行緒。414* **執行中的執行緒**：每個都是一個完整的工作階段，多個可以同時執行。沒有固定數字；Claude 會依工作需要啟動相應數量的執行緒，您 [要求](#tune-how-claude-runs-a-project) 的限制是偏好而不是上限。強制執行的限制是每天跨您的 projects 500 個新執行緒。

415* **對話**：Claude 使用自己的令牌讀取執行緒報告的內容並決定下一步做什麼。415* **對話**：Claude 使用自己的令牌讀取執行緒報告的內容並決定下一步做什麼。

416* **執行緒監視提取請求**：空閒執行緒在 CI 失敗或審查評論到達其提取請求時喚醒並再次使用您的方案。要停止它，在執行緒中要求它停止監視提取請求。416* **執行緒監視提取請求**：空閒執行緒在 CI 失敗或審查評論到達其提取請求時喚醒並再次使用您的方案。要停止它，在執行緒中要求它停止監視提取請求。

417 417 

25 25 

26> [!NOTE]26> [!NOTE]

27>27>

28> [Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md) 工作階段將網頁和行動介面連接到您自己機器上的工作階段，該工作階段使用您機器的網路和檔案，而不是雲端環境。Claude Tag 頻道工作階段僅使用組織層級環境，可以是 [共用環境](#organization-shared-environments) 或 [自託管環境](https://code.claude.com/docs/zh-TW/self-hosted-environments)。28> [Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md) 工作階段將網頁和行動介面連接到您自己機器上的工作階段，該工作階段使用您機器的網路和檔案，而不是雲端環境。若要選擇 Claude Tag 頻道使用的環境，請參閱 [設定 Claude Tag 頻道使用的環境](#set-the-environment-a-claude-tag-channel-uses)。

29 29 

30## Default 環境30## Default 環境

31 31 

64| PRs reviewed | 所選時間範圍內每日審查的 pull request 數量 |64| PRs reviewed | 所選時間範圍內每日審查的 pull request 數量 |

65| Code Review cost | 本月至今的 Code Review 支出 |65| Code Review cost | 本月至今的 Code Review 支出 |

66| Feedback | 因開發人員已處理問題而自動解決的審查留言數量 |66| Feedback | 因開發人員已處理問題而自動解決的審查留言數量 |

67| Code Review findings | 所選時間範圍內，Claude 已發布之審查中每日[依嚴重程度等級分類的發現項目](https://code.claude.com/docs/zh-TW/code-review-pull-requests.md#severity-levels)數量 |

67| Repository breakdown | 各儲存庫已審查的 PR 數量、已解決的留言數量與審查執行次數，並附有估算費用與各 PR 檢視 |68| Repository breakdown | 各儲存庫已審查的 PR 數量、已解決的留言數量與審查執行次數，並附有估算費用與各 PR 檢視 |

68 69 

69只有在選取當月時，Code Review cost 卡片才會顯示金額。分析中的費用數字可能與您的帳單不同。Repository breakdown 的費用是以牌價估算，未計入任何折扣或點數，且僅涵蓋 Claude 已在 pull request 上發布的審查。如需與帳單一致的支出資訊，請參閱您的 Anthropic 帳單。70只有在選取當月時，Code Review cost 卡片才會顯示金額。分析中的費用數字可能與您的帳單不同。Repository breakdown 的費用是以牌價估算，未計入任何折扣或點數，且僅涵蓋 Claude 已在 pull request 上發布的審查。如需與帳單一致的支出資訊，請參閱您的 Anthropic 帳單。

111| `/mcp [reconnect (<server>\|all)\|enable\|disable [<server>\|all]]` | 管理 MCP 伺服器連線和 OAuth 身分驗證。運行時不帶引數以打開互動式清單，或傳遞 `reconnect`、`enable` 或 `disable` 與伺服器名稱或 `all`，以在不打開清單的情況下變更連線狀態。`reconnect all` 會[重試每個失敗或需要身分驗證的伺服器](https://code.claude.com/docs/zh-TW/mcp.md#retry-failed-servers-yourself)。在非互動模式 (`-p`) 中，不帶引數運行它會列印伺服器狀態的文字摘要而不是打開清單 |111| `/mcp [reconnect (<server>\|all)\|enable\|disable [<server>\|all]]` | 管理 MCP 伺服器連線和 OAuth 身分驗證。運行時不帶引數以打開互動式清單，或傳遞 `reconnect`、`enable` 或 `disable` 與伺服器名稱或 `all`，以在不打開清單的情況下變更連線狀態。`reconnect all` 會[重試每個失敗或需要身分驗證的伺服器](https://code.claude.com/docs/zh-TW/mcp.md#retry-failed-servers-yourself)。在非互動模式 (`-p`) 中，不帶引數運行它會列印伺服器狀態的文字摘要而不是打開清單 |

112| `/memory` | 編輯 `CLAUDE.md` 檔案、啟用或停用[自動記憶](https://code.claude.com/docs/zh-TW/memory.md#auto-memory)以及檢視自動記憶項目 |112| `/memory` | 編輯 `CLAUDE.md` 檔案、啟用或停用[自動記憶](https://code.claude.com/docs/zh-TW/memory.md#auto-memory)以及檢視自動記憶項目 |

113| `/mobile` | 顯示 QR 碼以下載 Claude 行動應用程式。別名：`/ios`、`/android` |113| `/mobile` | 顯示 QR 碼以下載 Claude 行動應用程式。別名：`/ios`、`/android` |

114| `/model [model]` | 切換 AI 模型並將其保存為新工作階段的預設值。對於支援它的模型，使用左/右箭頭以[調整 effort 等級](https://code.claude.com/docs/zh-TW/model-config.md#adjust-effort-level)。沒有引數時，打開選擇器；在行上按 `s` 以僅為目前工作階段切換。請參閱[何時 Claude Code 要求您確認切換](https://code.claude.com/docs/zh-TW/prompt-caching.md#switching-models)。一旦您確認切換（如果 Claude Code 要求），Claude Code 會應用變更而不等待目前回應完成。在 v2.1.242 之前，Claude Code 從它從 Anthropic 擷取的功能旗標決定是在回合中途運行命令還是將其排隊直到該回合完成，並始終在不[擷取功能旗標](https://code.claude.com/docs/zh-TW/env-vars.md#features-that-need-feature-flag-fetching)的工作階段中排隊，例如在[第三方提供者](https://code.claude.com/docs/zh-TW/third-party-integrations.md)上。也可在非互動模式 (`-p`) 中使用模型引數而不是選擇器，其中它僅應用於目前工作階段且不保存為您的預設值；需要 Claude Code v2.1.205 或更新版本 |114| `/model [model]` | 切換 AI 模型並將其保存為新工作階段的預設值。對於支援它的模型，使用左/右箭頭以[調整 effort 等級](https://code.claude.com/docs/zh-TW/model-config.md#adjust-effort-level)。沒有引數時，打開選擇器；在行上按 `s` 以僅為目前工作階段切換。請參閱[新模型何時開始生效](https://code.claude.com/docs/zh-TW/interactive-mode.md#when-claude-code-sends-what-you-queued)。在 v2.1.242 之前，它可能會等待。使用 `-p` 時，傳遞模型引數，該引數不會保存為您的預設值；需要 v2.1.205 或更新版本 |

115| `/output-style [style]` | 列出[輸出風格](https://code.claude.com/docs/zh-TW/output-styles.md)或切換到一個，例如 `/output-style concise`。請參閱[變更您的輸出風格](https://code.claude.com/docs/zh-TW/output-styles.md#change-your-output-style)。需要 Claude Code v2.1.269 或更新版本 |115| `/output-style [style]` | 列出[輸出風格](https://code.claude.com/docs/zh-TW/output-styles.md)或切換到一個，例如 `/output-style concise`。請參閱[變更您的輸出風格](https://code.claude.com/docs/zh-TW/output-styles.md#change-your-output-style)。需要 Claude Code v2.1.269 或更新版本 |

116| `/passes` | 與朋友分享免費一週的 Claude Code。僅在您的帳戶符合條件時可見 |116| `/passes` | 與朋友分享免費一週的 Claude Code。僅在您的帳戶符合條件時可見 |

117| `/permissions` | 管理工具權限的允許、詢問和拒絕規則。打開互動式對話框，您可以按範圍檢視規則、添加或移除規則、管理工作目錄以及檢查[最近的自動模式拒絕](https://code.claude.com/docs/zh-TW/auto-mode-config.md#review-denials)。您也可以從對話框的 **Auto mode** 標籤檢視和編輯[自動模式分類器規則](https://code.claude.com/docs/zh-TW/auto-mode-config.md#edit-rules-from-permissions)。當您在 Claude 回應時運行它時，Claude Code 會立即打開對話框並從 Claude 在同一回合中的下一個工具呼叫開始應用您的變更。在 v2.1.234 之前，Claude Code 會將命令排隊直到該回合完成。別名：`/allowed-tools` |117| `/permissions` | 管理工具權限的允許、詢問和拒絕規則。打開互動式對話框，您可以按範圍檢視規則、添加或移除規則、管理工作目錄以及檢查[最近的自動模式拒絕](https://code.claude.com/docs/zh-TW/auto-mode-config.md#review-denials)。您也可以從對話框的 **Auto mode** 標籤檢視和編輯[自動模式分類器規則](https://code.claude.com/docs/zh-TW/auto-mode-config.md#edit-rules-from-permissions)。當您在 Claude 回應時運行它時，Claude Code 會立即打開對話框並從 Claude 在同一回合中的下一個工具呼叫開始應用您的變更。在 v2.1.234 之前，Claude Code 會將命令排隊直到該回合完成。別名：`/allowed-tools` |

130| `/remote-control` | 使此工作階段可從 claude.ai 進行 [Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md)。在登出時運行它會列印 Remote Control 需要 claude.ai 訂閱並告訴您如何登入。別名：`/rc` |130| `/remote-control` | 使此工作階段可從 claude.ai 進行 [Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md)。在登出時運行它會列印 Remote Control 需要 claude.ai 訂閱並告訴您如何登入。別名：`/rc` |

131| `/remote-env` | 為您從 CLI 啟動的雲端工作階段選擇預設[雲端環境](https://code.claude.com/docs/zh-TW/cloud-environments.md#select-an-environment-from-the-cli) |131| `/remote-env` | 為您從 CLI 啟動的雲端工作階段選擇預設[雲端環境](https://code.claude.com/docs/zh-TW/cloud-environments.md#select-an-environment-from-the-cli) |

132| `/rename [name]` | 重新命名目前工作階段並在提示詞欄上顯示名稱。沒有名稱時，從對話歷史記錄自動生成一個。也可在非互動模式 (`-p`) 中使用。從每個重新命名的使用介面，包括 claude.ai 和桌面應用程式，Claude Code 會用空格替換新名稱中的控制和不可見字元，並將名稱上限設為 200 個字元。如果移除不可見字元後名稱為空，Claude Code 會拒絕它並顯示 `That name is empty once invisible characters are removed. Usage: /rename <name>`。字元替換和長度上限需要 Claude Code v2.1.221 或更新版本 |132| `/rename [name]` | 重新命名目前工作階段並在提示詞欄上顯示名稱。沒有名稱時，從對話歷史記錄自動生成一個。也可在非互動模式 (`-p`) 中使用。從每個重新命名的使用介面，包括 claude.ai 和桌面應用程式，Claude Code 會用空格替換新名稱中的控制和不可見字元，並將名稱上限設為 200 個字元。如果移除不可見字元後名稱為空，Claude Code 會拒絕它並顯示 `That name is empty once invisible characters are removed. Usage: /rename <name>`。字元替換和長度上限需要 Claude Code v2.1.221 或更新版本 |

133| `/restart` | 重新啟動 Claude Code 並恢復此工作階段，以應用已安裝的更新。當更新安裝後頁尾提供此選項時運行它。需要 Pro 或 Max 方案，以及在 macOS 或 Linux（非 WSL）上的原生安裝。需要 Claude Code v2.1.288 或更新版本。別名：`/update` |

133| `/resume [session]` | 按 ID 或名稱恢復對話，或打開工作階段選擇器。[背景工作階段](https://code.claude.com/docs/zh-TW/agent-view.md)在選擇器中以 `bg` 標記出現。恢復仍在運行的工作階段時，無論是從選擇器或按 ID 或名稱，都會[打開該工作階段](https://code.claude.com/docs/zh-TW/sessions.md#resume-a-running-background-session)：您目前的對話會移到背景，此終端機會附加到運行中的工作階段。在空提示詞上按 `←` 可返回 agent view，其中也會列出您離開的對話。在 v2.1.285 之前，Claude Code 會拒絕，並告訴您使用 `claude attach` 打開該工作階段或先停止它。別名：`/continue` |134| `/resume [session]` | 按 ID 或名稱恢復對話，或打開工作階段選擇器。[背景工作階段](https://code.claude.com/docs/zh-TW/agent-view.md)在選擇器中以 `bg` 標記出現。恢復仍在運行的工作階段時，無論是從選擇器或按 ID 或名稱，都會[打開該工作階段](https://code.claude.com/docs/zh-TW/sessions.md#resume-a-running-background-session)：您目前的對話會移到背景，此終端機會附加到運行中的工作階段。在空提示詞上按 `←` 可返回 agent view，其中也會列出您離開的對話。在 v2.1.285 之前，Claude Code 會拒絕，並告訴您使用 `claude attach` 打開該工作階段或先停止它。別名：`/continue` |

134| `/review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [--max-findings n\|all\|default] [pr#\|branch\|path]` | [`/code-review`](https://code.claude.com/docs/zh-TW/code-review-local) 的別名：檢查目前差異或您傳遞的 PR 編號、分支或路徑，例如 `/review 1234`，並採用相同的 effort 等級和旗標。沒有給定等級時，檢查重複使用您最後輸入的 `low` 到 `max` 等級；有關確切規則，請參閱[使用 `/code-review` 在本地檢查](https://code.claude.com/docs/zh-TW/code-review-local)。對於深度雲端檢查，使用 [`/code-review ultra`](https://code.claude.com/docs/zh-TW/ultrareview)。在 v2.1.223 之前，`/review` 是一個單獨的命令，按編號對 GitHub pull request 進行單次通過、唯讀檢查，在運行時不帶引數時列出打開的 PR 以選擇；從 v2.1.186 到 v2.1.201，它運行與 `/code-review medium` 相同的多 agent 引擎 |135| `/review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [--max-findings n\|all\|default] [pr#\|branch\|path]` | [`/code-review`](https://code.claude.com/docs/zh-TW/code-review-local) 的別名：檢查目前差異或您傳遞的 PR 編號、分支或路徑，例如 `/review 1234`，並採用相同的 effort 等級和旗標。沒有給定等級時，檢查重複使用您最後輸入的 `low` 到 `max` 等級；有關確切規則，請參閱[使用 `/code-review` 在本地檢查](https://code.claude.com/docs/zh-TW/code-review-local)。對於深度雲端檢查，使用 [`/code-review ultra`](https://code.claude.com/docs/zh-TW/ultrareview)。在 v2.1.223 之前，`/review` 是一個單獨的命令，按編號對 GitHub pull request 進行單次通過、唯讀檢查，在運行時不帶引數時列出打開的 PR 以選擇；從 v2.1.186 到 v2.1.201，它運行與 `/code-review medium` 相同的多 agent 引擎 |

135| `/rewind` | 倒帶對話和/或程式碼到上一個點，或從選定的訊息進行摘要。請參閱[檢查點功能](https://code.claude.com/docs/zh-TW/checkpointing.md)。別名：`/checkpoint`、`/undo` |136| `/rewind` | 倒帶對話和/或程式碼到上一個點，或從選定的訊息進行摘要。請參閱[檢查點功能](https://code.claude.com/docs/zh-TW/checkpointing.md)。別名：`/checkpoint`、`/undo` |

375 375 

376## 背景 token 使用376## 背景 token 使用

377 377 

378Claude Code 即使在閒置時也會為某些背景功能使用 token：378工作階段回顧與閒置壓縮可能會在您閒置時使用 token。請參閱[工作階段回顧](https://code.claude.com/docs/zh-TW/interactive-mode.md#session-recap)與[閒置壓縮](https://code.claude.com/docs/zh-TW/settings-reference.md#idlecompaction)，了解各自的執行時機以及如何關閉。

379 

380* **對話總結**：為 `claude --resume` 功能總結先前對話的背景工作

381* **命令處理**：某些命令（例如 `/usage`）可能會產生檢查狀態的請求

382 

383這些背景程序即使沒有主動互動也會消耗少量 token（通常每個工作階段不到 \$0.04）。

384 379 

385當啟用提示建議時，Claude Code 也會在 Claude 回應後向您的工作階段使用的模型發送簡短請求，以[建議您的下一個提示](https://code.claude.com/docs/zh-TW/interactive-mode.md#prompt-suggestions)。該請求會重複使用對話的提示快取，因此主要是快取讀取加上少數輸出 token。Claude Code [在您的帳戶接近或達到使用限制時會跳過此功能](https://code.claude.com/docs/zh-TW/interactive-mode.md#when-claude-code-skips-suggestions)。若要停止這些請求，[請關閉提示建議](https://code.claude.com/docs/zh-TW/interactive-mode.md#turn-prompt-suggestions-off)。380當啟用提示建議時，Claude Code 也會在 Claude 回應後向您的工作階段使用的模型發送簡短請求，以[建議您的下一個提示](https://code.claude.com/docs/zh-TW/interactive-mode.md#prompt-suggestions)。該請求會重複使用對話的提示快取，因此主要是快取讀取加上少數輸出 token。Claude Code [在您的帳戶接近或達到使用限制時會跳過此功能](https://code.claude.com/docs/zh-TW/interactive-mode.md#when-claude-code-skips-suggestions)。若要停止這些請求，[請關閉提示建議](https://code.claude.com/docs/zh-TW/interactive-mode.md#turn-prompt-suggestions-off)。

386 381 

108 108 

109### 從 shell 開啟連結109### 從 shell 開啟連結

110 110 

111您也可以從 shell 指令碼、別名或自動化中開啟深層連結，而不是點擊它。使用連結作為參數呼叫您作業系統的 URL 開啟命令。這些命令依賴於 Claude Code [在您於機器上傳送互動式工作階段的第一個提示時註冊](#registration-and-supported-platforms)的處理程式。111您也可以從 shell 指令碼、別名或自動化中開啟深層連結，而不是點擊它。使用連結作為引數呼叫您作業系統的 URL 開啟命令。這些命令依賴於 Claude Code 在機器上[註冊](#registration-and-supported-platforms)的處理程式。

112 112 

113**macOS**113**macOS**

114 114 

148 148 

149## 註冊和支援的平台149## 註冊和支援的平台

150 150 

151Claude Code 在您第一次在 macOS、Linux 和 Windows 上傳送互動式工作階段的第一個提示詞時，向您的作業系統註冊 `claude-cli://` 處理程式。啟動 `claude` 並在不傳送提示詞的情況下退出不會註冊處理程式。您不需要執行單獨的安裝命令。註冊只寫入使用者級別的位置：151當您執行下列任一操作時，Claude Code 會在 macOS、Linux 和 Windows 上向您的作業系統註冊 `claude-cli://` 處理程式：

152 

153* 在互動式 `claude` 工作階段中傳送任何內容，例如訊息或 `/help`。僅啟動工作階段而未傳送任何內容不會註冊處理程式。

154* 在您已[信任](https://code.claude.com/docs/zh-TW/permissions.md#project-allow-rules-and-workspace-trust)的資料夾中以 [agent 檢視](https://code.claude.com/docs/zh-TW/agent-view.md)啟動 Claude Code，例如使用 `claude agents`

155 

156您不需要執行單獨的安裝命令。註冊只寫入使用者級別的位置：

152 157 

153| 平台 | 處理程式位置 |158| 平台 | 處理程式位置 |

154| - | - |159| - | - |

172 177 

173### 點擊連結沒有反應178### 點擊連結沒有反應

174 179 

175處理程式可能尚未註冊。註冊發生在您傳送互動式工作階段的第一個提示時，而不是在工作階段啟動時。在該機器上啟動一個互動式 `claude` 工作階段，傳送任何提示，退出，然後再試一次連結。如果您在沒有桌面環境的 Linux 上，`xdg-open` 可能沒有任何東西可以分派。180處理程式可能尚未註冊。在互動式工作階段中，註冊發生在您傳送內容時，而不是在工作階段啟動時。在該機器上啟動一個互動式 `claude` 工作階段，傳送任何提示詞，退出，然後再試一次連結。如果您在沒有桌面環境的 Linux 上，`xdg-open` 可能沒有任何東西可以分派。

176 181 

177### 在 Linux 上找不到 xdg-open182### 在 Linux 上找不到 xdg-open

178 183 

1930* **Windows**：透過位於 `SOFTWARE\Policies\Claude` 的登錄進行設定1930* **Windows**：透過位於 `SOFTWARE\Policies\Claude` 的登錄進行設定

1931* **Linux**：透過位於 `/etc/claude-desktop/managed-settings.json`、由 root 擁有的檔案進行設定，該檔案以 JSON 物件保存原則鍵。如果 root 以外的任何人可以寫入該檔案或其資料夾，Desktop 會拒絕使用該檔案。它與 Claude Code 的[受管設定檔案](https://code.claude.com/docs/zh-TW/managed-settings.md)是不同的檔案。1931* **Linux**：透過位於 `/etc/claude-desktop/managed-settings.json`、由 root 擁有的檔案進行設定，該檔案以 JSON 物件保存原則鍵。如果 root 以外的任何人可以寫入該檔案或其資料夾，Desktop 會拒絕使用該檔案。它與 Claude Code 的[受管設定檔案](https://code.claude.com/docs/zh-TW/managed-settings.md)是不同的檔案。

1932 1932 

1933#### 將登入限制為您的組織

1934 

1935若要限制哪些 claude.ai 組織可以登入 Claude Desktop，請在 Claude Desktop 原則中設定 `forceLoginOrgUUID`。

1936 

1937此鍵需要 Claude Desktop v1.2581.0 或更新版本。

1938 

1939在 Linux 上，僅設定此鍵的原則檔案內容如下：

1940 

1941```json /etc/claude-desktop/managed-settings.json theme={null}

1942{

1943 "forceLoginOrgUUID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

1944}

1945```

1946 

1947請將預留位置替換為您的 claude.ai 組織 ID，該 ID 顯示在 [claude.ai 管理設定](https://claude.ai/admin-settings/organization)中。它與 Claude Code 的 [`forceLoginOrgUUID`](https://code.claude.com/docs/zh-TW/settings-reference#forceloginorguuid) 設定所使用的 ID 相同。有關設定此鍵的 macOS 和 Windows 範例，請參閱適用於 HIPAA-ready 組織的 Cowork 指南中的[部署 Claude Desktop 原則](https://claude.com/docs/cowork/hipaa-setup#deploy-the-claude-desktop-policy)。

1948 

1949如果您在 Claude Code 的[受管設定](https://code.claude.com/docs/zh-TW/managed-settings.md)中設定 `forceLoginMethod` 和 `forceLoginOrgUUID`，並不會改變 Claude Desktop 的登入畫面。

1950 

1933### 網路存取需求1951### 網路存取需求

1934 1952 

1935Desktop 從 Anthropic CDN 主機載入其應用程式程式碼和使用者內容。1953Desktop 從 Anthropic CDN 主機載入其應用程式程式碼和使用者內容。

428| `CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS` | [工作流程](https://code.claude.com/docs/zh-TW/workflows.md) agent 在送出自己的第一個請求之前，等待具有相同前綴的同層 agent 開始第一個回應的時間上限（毫秒）。當扇出啟動多個共用[提示快取前綴](https://code.claude.com/docs/zh-TW/workflows.md#prompt-caching-in-a-fan-out)的 agent 時，Claude Code 會將第一個以外的所有 agent 暫停最多這段時間，讓其餘 agent 讀取已快取的前綴，而不是各自在未快取的情況下處理。預設值為 `5000`。設定為 `0` 可停用等待。設定 `DISABLE_PROMPT_CACHING` 時，agent 永遠不會等待。需要 Claude Code v2.1.229 或更新版本 |428| `CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS` | [工作流程](https://code.claude.com/docs/zh-TW/workflows.md) agent 在送出自己的第一個請求之前，等待具有相同前綴的同層 agent 開始第一個回應的時間上限（毫秒）。當扇出啟動多個共用[提示快取前綴](https://code.claude.com/docs/zh-TW/workflows.md#prompt-caching-in-a-fan-out)的 agent 時，Claude Code 會將第一個以外的所有 agent 暫停最多這段時間，讓其餘 agent 讀取已快取的前綴，而不是各自在未快取的情況下處理。預設值為 `5000`。設定為 `0` 可停用等待。設定 `DISABLE_PROMPT_CACHING` 時，agent 永遠不會等待。需要 Claude Code v2.1.229 或更新版本 |

429| `CLAUDE_CODE_YOU_SHOULD_KNOW_DEBUG` | 設為 `1` 可在提示詞上方，為 [You should know mod](https://code.claude.com/docs/zh-TW/interactive-mode.md#you-should-know-suggestions) 在此工作階段中進行的最近三次檢查各顯示一行。可用於在沒有出現任何提示時，確認該 mod 是否正在進行檢查。需要 Claude Code v2.1.287 或更新版本 |429| `CLAUDE_CODE_YOU_SHOULD_KNOW_DEBUG` | 設為 `1` 可在提示詞上方，為 [You should know mod](https://code.claude.com/docs/zh-TW/interactive-mode.md#you-should-know-suggestions) 在此工作階段中進行的最近三次檢查各顯示一行。可用於在沒有出現任何提示時，確認該 mod 是否正在進行檢查。需要 Claude Code v2.1.287 或更新版本 |

430| `CLAUDE_CONFIG_DIR` | 覆寫設定目錄（預設：`~/.claude`）。所有設定、工作階段歷史記錄與外掛都儲存在此路徑下。關於憑證，請參閱 [Claude Code 儲存憑證的位置](https://code.claude.com/docs/zh-TW/authentication.md#credential-management)。適用於並行執行多個帳戶：例如 `alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'`。請在您的 shell、使用者設定或受管設定中設定。在設定檔中，請寫入[絕對路徑](#in-settings-files)。在[專案與本機設定](https://code.claude.com/docs/zh-TW/settings-reference.md#variables-claude-code-ignores-in-env)中會被忽略 |430| `CLAUDE_CONFIG_DIR` | 覆寫設定目錄（預設：`~/.claude`）。所有設定、工作階段歷史記錄與外掛都儲存在此路徑下。關於憑證，請參閱 [Claude Code 儲存憑證的位置](https://code.claude.com/docs/zh-TW/authentication.md#credential-management)。適用於並行執行多個帳戶：例如 `alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'`。請在您的 shell、使用者設定或受管設定中設定。在設定檔中，請寫入[絕對路徑](#in-settings-files)。在[專案與本機設定](https://code.claude.com/docs/zh-TW/settings-reference.md#variables-claude-code-ignores-in-env)中會被忽略 |

431| `CLAUDE_EFFORT` | 在 Bash 工具子程序與 hook 命令中自動設定為子程序啟動時生效的 [effort 等級](https://code.claude.com/docs/zh-TW/model-config.md#adjust-effort-level)：`low`、`medium`、`high`、`xhigh` 或 `max`。與傳遞給 [hook](https://code.claude.com/docs/zh-TW/hooks.md) 的 `effort.level` 欄位相符。僅在目前模型支援 effort 參數時設定 |431| `CLAUDE_EFFORT` | 在 Bash 工具子程序和 hook 命令中，自動設定為子程序啟動時的 [effort 等級](https://code.claude.com/docs/zh-TW/model-config.md#adjust-effort-level)設定：`low`、`medium`、`high`、`xhigh` 或 `max`。與傳遞給 [hook](https://code.claude.com/docs/zh-TW/hooks.md) 的 `effort.level` 欄位相符。僅在目前模型支援 effort 參數時才會設定 |

432| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 設定為 `1` 可強制啟用位元組層級串流閒置監視器，設定為 `0` 可強制停用。`0` 也會在執行[首位元組期限](https://code.claude.com/docs/zh-TW/network-config.md#streaming-idle-watchdogs)的連線上關閉該期限。未設定時，此監視器預設會針對直接 Anthropic API 與 [Claude Platform on AWS](https://code.claude.com/docs/zh-TW/claude-platform-on-aws.md) 連線，以及透過 `ANTHROPIC_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 連到的[閘道](https://code.claude.com/docs/zh-TW/gateways.md)連線上的串流回應啟用；在 v2.1.222 之前，它不會在這些閘道連線上執行，因此即使 keep-alive ping 持續抵達，事件層級監視器仍可能在那裡回報停滯。關於逾時以及各計時器如何交互作用，請參閱[串流閒置監視器](https://code.claude.com/docs/zh-TW/network-config.md#streaming-idle-watchdogs) |432| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 設定為 `1` 可強制啟用位元組層級串流閒置監視器，設定為 `0` 可強制停用。`0` 也會在執行[首位元組期限](https://code.claude.com/docs/zh-TW/network-config.md#streaming-idle-watchdogs)的連線上關閉該期限。未設定時，此監視器預設會針對直接 Anthropic API 與 [Claude Platform on AWS](https://code.claude.com/docs/zh-TW/claude-platform-on-aws.md) 連線，以及透過 `ANTHROPIC_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 連到的[閘道](https://code.claude.com/docs/zh-TW/gateways.md)連線上的串流回應啟用；在 v2.1.222 之前，它不會在這些閘道連線上執行，因此即使 keep-alive ping 持續抵達，事件層級監視器仍可能在那裡回報停滯。關於逾時以及各計時器如何交互作用，請參閱[串流閒置監視器](https://code.claude.com/docs/zh-TW/network-config.md#streaming-idle-watchdogs) |

433| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | 設定為 `1` 可在 Amazon Bedrock `vnd.amazon.eventstream` 回應上啟用位元組層級串流閒置監視器，這也會在 Bedrock 串流請求上啟用[首位元組期限](https://code.claude.com/docs/zh-TW/network-config.md#streaming-idle-watchdogs)。預設為關閉。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 設定逾時 |433| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | 設定為 `1` 可在 Amazon Bedrock `vnd.amazon.eventstream` 回應上啟用位元組層級串流閒置監視器，這也會在 Bedrock 串流請求上啟用[首位元組期限](https://code.claude.com/docs/zh-TW/network-config.md#streaming-idle-watchdogs)。預設為關閉。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 設定逾時 |

434| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 設定為 `0` 可強制停用事件層級串流閒置監視器，設定為 `1` 可強制啟用。未設定時，此監視器預設對所有提供者開啟。在 v2.1.196 之前，未設定時的預設值在直接 Anthropic API 上由伺服器控制，在其他提供者上則為關閉。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 設定逾時；關於與此監視器一同執行的其他停滯計時器，請參閱[串流閒置監視器](https://code.claude.com/docs/zh-TW/network-config.md#streaming-idle-watchdogs) |434| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 設定為 `0` 可強制停用事件層級串流閒置監視器，設定為 `1` 可強制啟用。未設定時，此監視器預設對所有提供者開啟。在 v2.1.196 之前，未設定時的預設值在直接 Anthropic API 上由伺服器控制，在其他提供者上則為關閉。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 設定逾時；關於與此監視器一同執行的其他停滯計時器，請參閱[串流閒置監視器](https://code.claude.com/docs/zh-TW/network-config.md#streaming-idle-watchdogs) |

575* 在 [Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md#requirements) 無法使用時，[傳送訊息給此機器以外的工作階段](https://code.claude.com/docs/zh-TW/cross-session-messaging.md#message-sessions-on-other-machines)。關閉擷取時，此機器上工作階段之間的訊息傳送仍可運作575* 在 [Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md#requirements) 無法使用時，[傳送訊息給此機器以外的工作階段](https://code.claude.com/docs/zh-TW/cross-session-messaging.md#message-sessions-on-other-machines)。關閉擷取時，此機器上工作階段之間的訊息傳送仍可運作

576* 執行 [`claude import` 或 `/import` 命令](https://code.claude.com/docs/zh-TW/cli-reference#cli-commands)576* 執行 [`claude import` 或 `/import` 命令](https://code.claude.com/docs/zh-TW/cli-reference#cli-commands)

577* 執行 [`/skill-doctor`](https://code.claude.com/docs/zh-TW/skills#find-unused-skills)，或在 `/plugin` 的 **Stats** 分頁中開啟其報告577* 執行 [`/skill-doctor`](https://code.claude.com/docs/zh-TW/skills#find-unused-skills)，或在 `/plugin` 的 **Stats** 分頁中開啟其報告

578* 在 Pro 和 Max 方案上執行 [`/restart`](https://code.claude.com/docs/zh-TW/commands)

578* 將您的 claude.ai 帳戶所啟用的 [skills](https://code.claude.com/docs/zh-TW/skills.md#where-synced-skills-load) 和[外掛](https://code.claude.com/docs/zh-TW/plugins/loading.md#synced-plugins)同步到您的終端機工作階段579* 將您的 claude.ai 帳戶所啟用的 [skills](https://code.claude.com/docs/zh-TW/skills.md#where-synced-skills-load) 和[外掛](https://code.claude.com/docs/zh-TW/plugins/loading.md#synced-plugins)同步到您的終端機工作階段

579* 啟用 [You should know mod](https://code.claude.com/docs/zh-TW/interactive-mode.md#you-should-know-suggestions)580* 啟用 [You should know mod](https://code.claude.com/docs/zh-TW/interactive-mode.md#you-should-know-suggestions)

580* 使用 [advisor 工具](https://code.claude.com/docs/zh-TW/advisor.md#requirements)581* 使用 [advisor 工具](https://code.claude.com/docs/zh-TW/advisor.md#requirements)

277| `Windows reported an error (EBADF) when Claude Code read this session's transcript file` | [命令列錯誤](#windows-reported-an-error-ebadf) |277| `Windows reported an error (EBADF) when Claude Code read this session's transcript file` | [命令列錯誤](#windows-reported-an-error-ebadf) |

278| `Cannot switch renderers in this session` | [命令列錯誤](#cannot-switch-renderers-in-this-session) |278| `Cannot switch renderers in this session` | [命令列錯誤](#cannot-switch-renderers-in-this-session) |

279| `Cannot switch renderers while work is running in the background` | [命令列錯誤](#cannot-switch-renderers-in-this-session) |279| `Cannot switch renderers while work is running in the background` | [命令列錯誤](#cannot-switch-renderers-in-this-session) |

280| `Can't restart while work is running in the background — wait for it to finish (or stop it via /tasks), then try again.` | [命令列錯誤](#cant-restart-while-work-is-running-or-remote-control-is-connected) |

281| `Can't restart while Remote Control is connected. To use the installed version, exit and start Claude Code again, then run /resume.` | [命令列錯誤](#cant-restart-while-work-is-running-or-remote-control-is-connected) |

280| `Claude Code couldn't restart` | [命令列錯誤](#claude-code-couldnt-restart) |282| `Claude Code couldn't restart` | [命令列錯誤](#claude-code-couldnt-restart) |

281| `Couldn't open Claude Desktop` | [命令列錯誤](#couldnt-open-claude-desktop) |283| `Couldn't open Claude Desktop` | [命令列錯誤](#couldnt-open-claude-desktop) |

282| `Failed to open Claude Desktop. Please try opening it manually.` | [命令列錯誤](#couldnt-open-claude-desktop) |284| `Failed to open Claude Desktop. Please try opening it manually.` | [命令列錯誤](#couldnt-open-claude-desktop) |

858 860 

859### The prompt to confirm went unanswered861### The prompt to confirm went unanswered

860 862 

861如果您的帳戶需要 [Fable 用量點數同意](https://code.claude.com/docs/zh-TW/model-config.md#fable-and-usage-credits)，Claude Code 會要求您在 Fable 請求計費用量點數之前確認。當同意提示在無人回應的情況下關閉時，Claude Code 會以以下其中一條訊息結束回合：863當 [Fable 用量點數同意提示](https://code.claude.com/docs/zh-TW/model-config.md#fable-and-usage-credits)在無人回應的情況下關閉時，Claude Code 會以以下其中一條訊息結束回合：

862 864 

863```text theme={null}865```text theme={null}

864Fable limit reached · continuing on Fable 5.1 uses usage credits, and the prompt to confirm went unanswered — nothing was sent · answer it where this session is running, or /model to change866Fable limit reached · continuing on Fable 5.1 uses usage credits, and the prompt to confirm went unanswered — nothing was sent · answer it where this session is running, or /model to change

3298* **`Error: Workspace not trusted. <folder> is your home directory`**：由於對家目錄的信任永遠不會被儲存，先在那裡執行 `claude` 並沒有幫助。請改從專案目錄執行 `claude ultrareview`（事先在那裡執行一次 `claude` 以接受信任對話框），或附加 `--trust-workspace`。3300* **`Error: Workspace not trusted. <folder> is your home directory`**：由於對家目錄的信任永遠不會被儲存，先在那裡執行 `claude` 並沒有幫助。請改從專案目錄執行 `claude ultrareview`（事先在那裡執行一次 `claude` 以接受信任對話框），或附加 `--trust-workspace`。

3299* **`No answer in time.` 後接 `Error: Workspace not trusted`**：`Trust <folder>? [y/N]` 問題在 5 分鐘內未獲回答。請再次執行 `claude ultrareview` 並回答它。3301* **`No answer in time.` 後接 `Error: Workspace not trusted`**：`Trust <folder>? [y/N]` 問題在 5 分鐘內未獲回答。請再次執行 `claude ultrareview` 並回答它。

3300* **`Ultrareview did not start: <folder> is not trusted`**：您在 `Trust <folder>? [y/N]` 問題中拒絕了，例如回答 `n` 或按下 Enter。若要啟動審查，請再次執行 `claude ultrareview` 並回答 `y`。3302* **`Ultrareview did not start: <folder> is not trusted`**：您在 `Trust <folder>? [y/N]` 問題中拒絕了，例如回答 `n` 或按下 Enter。若要啟動審查，請再次執行 `claude ultrareview` 並回答 `y`。

3301* **``Ultrareview did not start: `--trust-workspace` takes no value``**：`--trust-workspace` 後面接了旗標以外的東西，例如 PR 編號或 `false`。如果您不信任該資料夾，請省略此旗標。若要在此次執行中信任它，請將 PR 編號或基礎分支放在旗標之前：`claude ultrareview 1234 --trust-workspace`。3303* **``Ultrareview did not start: `--trust-workspace` takes no value``**：`--trust-workspace` 後面接了非旗標的內容，例如 PR 編號或 `false`。如果您不信任該資料夾，請省略此旗標。若要在本次執行中信任它，請將 PR 編號或基底分支放在旗標之前：`claude ultrareview 1234 --trust-workspace`。

3302 3304 

3303在 v2.1.309 之前，`claude ultrareview` 不接受 `--trust-workspace`。3305在 v2.1.309 之前，`claude ultrareview` 不接受 `--trust-workspace`。

3304 3306 

3590 3592 

3591以下同類字串會在命令執行之前就觸發：3593以下同類字串會在命令執行之前就觸發：

3592 3594 

3593* `Shell command permission check failed for pattern "..."`：命令的權限檢查不允許它。[注入命令的權限檢查](https://code.claude.com/docs/zh-TW/skills.md#permission-checks-on-injected-commands)說明了在各權限模式下哪些結果會中止，以及如何以 `allowed-tools` 預先核准命令3595* `Shell command permission check failed for pattern "..."`：該命令的權限檢查不允許它執行。[注入命令的權限檢查](https://code.claude.com/docs/zh-TW/skills.md#permission-checks-on-injected-commands)說明了在各權限模式下哪些結果會中止，以及如何使用 `allowed-tools` 預先核准命令

3594* ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found``：skill 的 frontmatter 在沒有 bash 的機器上要求使用 bash。請安裝 Git for Windows，或將 frontmatter 改為 `shell: powershell`。請參閱[注入命令如何執行](https://code.claude.com/docs/zh-TW/skills.md#how-injected-commands-run)3596* ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found``：該 skill 的 frontmatter 要求 bash，但電腦上沒有 bash。請安裝 Git for Windows，或將 frontmatter 改為 `shell: powershell`。請參閱[注入命令的執行方式](https://code.claude.com/docs/zh-TW/skills.md#how-injected-commands-run)

3595 3597 

3596**處理方式：**3598**處理方式：**

3597 3599 

3744 3746 

3745* **您沒有傳入基底分支**：Claude Code 與儲存庫的預設分支進行比較，並建議您明確傳入基底分支，如上例所示3747* **您沒有傳入基底分支**：Claude Code 與儲存庫的預設分支進行比較，並建議您明確傳入基底分支，如上例所示

3746* **您傳入的基底分支已存在於您的複製中**：提示內容為 ``Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)``3748* **您傳入的基底分支已存在於您的複製中**：提示內容為 ``Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)``

3747* **您傳入的基礎分支不在您的複製中**：Claude Code 在比較之前先從 origin 擷取了該分支。提示內容為 ``<branch> was fetched from origin but shares no history with HEAD. If another branch is your real base, pass it explicitly (`/code-review ultra <branch>`)``；當 Claude Code 無法判斷您的複製是否為淺層複製時，則會改為建議 `git fetch --unshallow origin`。在 v2.1.221 之前，對於每個擷取的基礎分支，提示都會建議 `git fetch --unshallow origin`，而在完整的複製上，該命令會以 `fatal: --unshallow on a complete repository does not make sense` 失敗。3749* **您傳入的基礎分支不在您的複製中**：Claude Code 在比較前會先從 origin 擷取該分支。提示內容為 ``<branch> was fetched from origin but shares no history with HEAD. If another branch is your real base, pass it explicitly (`/code-review ultra <branch>`)``；當 Claude Code 無法判斷您的複製是否為淺層複製時，則會改為建議 `git fetch --unshallow origin`。在 v2.1.221 之前，提示會對每個擷取的基礎分支都建議 `git fetch --unshallow origin`，而在完整的複製上，該命令會失敗並顯示 `fatal: --unshallow on a complete repository does not make sense`。

3748 3750 

3749**處理方式：**3751**處理方式：**

3750 3752 

3974 3976 

3975* 在未帶有這些限制而啟動的工作階段中，執行 `/tui fullscreen`，或執行 `/tui default` 切換回來。Claude Code 會在該處儲存 [`tui` 設定](https://code.claude.com/docs/zh-TW/settings-reference#tui)3977* 在未帶有這些限制而啟動的工作階段中，執行 `/tui fullscreen`，或執行 `/tui default` 切換回來。Claude Code 會在該處儲存 [`tui` 設定](https://code.claude.com/docs/zh-TW/settings-reference#tui)

3976 3978 

3979### Can't restart while work is running or Remote Control is connected

3980 

3981Claude Code 沒有重新啟動，您的工作階段會維持原狀繼續執行。請依照訊息中的修正方式處理。

3982 

3977### Claude Code couldn't restart3983### Claude Code couldn't restart

3978 3984 

3979當此訊息表示您的對話已儲存時，代表對話已寫入磁碟，您可以從中斷處繼續。Claude Code 當時正在自行重新啟動，例如在您執行 [`/tui`](https://code.claude.com/docs/zh-TW/fullscreen#enable-fullscreen-rendering) 後切換至或切換出全螢幕渲染，但無法啟動新程序，因此以狀態 1 結束：3985當此訊息表示您的對話已儲存時，代表對話已寫入磁碟，您可以從中斷處繼續。Claude Code 當時正在自行重新啟動，例如在您執行 [`/tui`](https://code.claude.com/docs/zh-TW/fullscreen#enable-fullscreen-rendering) 後切換至或切換出全螢幕渲染，但無法啟動新程序，因此以狀態 1 結束：

168 168 

169> [!WARNING]169> [!WARNING]

170>170>

171> Claude Code 在使用小型快速模型的任何地方都會讀取 `ANTHROPIC_DEFAULT_HAIKU_MODEL`，不僅僅是用於 `/goal` 評估。當你設定它時，Claude Code 也會將 [`haiku` 別名](https://code.claude.com/docs/zh-TW/model-config#model-aliases)解析為該模型，並在其上執行[背景功能](https://code.claude.com/docs/zh-TW/costs.md#background-token-usage)，例如對話摘要。171> Claude Code 在使用小型快速模型的任何地方都會讀取 `ANTHROPIC_DEFAULT_HAIKU_MODEL`，不僅僅是用於 `/goal` 評估。當您設定它時，Claude Code 也會將 [`haiku` 別名](https://code.claude.com/docs/zh-TW/model-config#model-aliases)解析為該模型，並在其上執行工作階段標題產生和其他一些背景任務。

172 172 

173評估器在你的工作階段配置的任何提供者上執行。它不呼叫工具，因此只能判斷 Claude 已在對話中呈現的內容。173評估器在你的工作階段配置的任何提供者上執行。它不呼叫工具，因此只能判斷 Claude 已在對話中呈現的內容。

174 174 

26 26 

27| 時機 | 執行事項 |27| 時機 | 執行事項 |

28| :- | :- |28| :- | :- |

29| 套用設定之前 | [準備電腦](#prepare-computers-before-the-hipaa-configuration-is-applied)：檢查開發人員的連線方式、更新應用程式、允許網路存取，並部署受管設定 |29| 套用設定之前 | [準備電腦](#prepare-computers-before-the-hipaa-configuration-is-applied)：檢查開發人員的連線方式、更新應用程式、允許網路存取、部署受管設定，並限制 Claude Desktop 登入 |

30| 套用之後 | Code 分頁會保持關閉，直到擁有者（Owner）重新開啟。[在電腦上確認設定](#confirm-the-configuration-on-a-computer) |30| 套用之後 | Code 分頁會保持關閉，直到擁有者（Owner）重新開啟。[在電腦上確認設定](#confirm-the-configuration-on-a-computer) |

31| 持續進行 | [管理本機工作階段資料](#manage-local-session-data) |31| 持續進行 | [管理本機工作階段資料](#manage-local-session-data) |

32 32 

161 161 

162若要了解您的 BAA 是否涵蓋在沒有 HIPAA 設定的情況下執行的工作階段，請參閱[在 HIPAA-ready Enterprise 方案上使用 Claude Code（本機模式）和 Cowork（本機模式）](https://support.claude.com/en/articles/17318731)。162若要了解您的 BAA 是否涵蓋在沒有 HIPAA 設定的情況下執行的工作階段，請參閱[在 HIPAA-ready Enterprise 方案上使用 Claude Code（本機模式）和 Cowork（本機模式）](https://support.claude.com/en/articles/17318731)。

163 163 

164### 限制 Claude Desktop 登入

165 

166如果開發人員使用 Claude Desktop 的 Code 分頁，也請在 Claude Desktop 政策中設定 `forceLoginOrgUUID`，如[將登入限制為您的組織](https://code.claude.com/docs/zh-TW/desktop.md#restrict-sign-in-to-your-organization)所述。在受管設定中部署 `forceLoginMethod` 和 `forceLoginOrgUUID` 不會變更 Claude Desktop 的登入畫面。

167 

164## 在電腦上確認設定168## 在電腦上確認設定

165 169 

166在設定套用至您的組織後，請在一台受管電腦上執行此檢查。170在設定套用至您的組織後，請在一台受管電腦上執行此檢查。

735| `cwd` | 叫用 hook 時的目前工作目錄 |735| `cwd` | 叫用 hook 時的目前工作目錄 |

736| `scratchpad_dir` | 工作階段的 [暫存目錄](https://code.claude.com/docs/zh-TW/claude-directory.md#session-scratchpad-directory) 的路徑，Claude 在其中保存臨時工作檔案。當工作階段沒有暫存或臨時目錄不可用時不存在。需要 Claude Code v2.1.257 或更新版本 |736| `scratchpad_dir` | 工作階段的 [暫存目錄](https://code.claude.com/docs/zh-TW/claude-directory.md#session-scratchpad-directory) 的路徑，Claude 在其中保存臨時工作檔案。當工作階段沒有暫存或臨時目錄不可用時不存在。需要 Claude Code v2.1.257 或更新版本 |

737| `permission_mode` | 目前 [權限模式](https://code.claude.com/docs/zh-TW/permissions.md#permission-modes)：`"default"`、`"plan"`、`"acceptEdits"`、`"auto"`、`"dontAsk"` 或 `"bypassPermissions"`。標記為**手動**的模式以 `"default"` 到達，永遠不會以 `"manual"` 到達，因此匹配 `"default"` 的指令碼繼續工作。並非所有事件都接收此欄位。檢查每個 [hook 事件](#hook-events) 部分中的 JSON 範例 |737| `permission_mode` | 目前 [權限模式](https://code.claude.com/docs/zh-TW/permissions.md#permission-modes)：`"default"`、`"plan"`、`"acceptEdits"`、`"auto"`、`"dontAsk"` 或 `"bypassPermissions"`。標記為**手動**的模式以 `"default"` 到達，永遠不會以 `"manual"` 到達，因此匹配 `"default"` 的指令碼繼續工作。並非所有事件都接收此欄位。檢查每個 [hook 事件](#hook-events) 部分中的 JSON 範例 |

738| `effort` | 物件，其 `level` 欄位保存執行 hook 時生效的 [effort 等級](https://code.claude.com/docs/zh-TW/model-config.md#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。如果您設定的等級是活躍模型不支援的，`level` 會報告 Claude Code 實際執行的等級；[調整 effort 等級](https://code.claude.com/docs/zh-TW/model-config.md#adjust-effort-level) 說明它如何選擇該等級。該物件與 [狀態列](https://code.claude.com/docs/zh-TW/statusline.md#available-data) `effort` 欄位相符。存在於在工具使用上下文中觸發的事件，例如 `PreToolUse`、`PostToolUse`、`Stop` 和 `SubagentStop`，當目前模型支援 effort 參數時。該等級也可作為 `$CLAUDE_EFFORT` 環境變數提供給 hook 命令和 Bash 工具。 |738| `effort` | 物件，其 `level` 為執行 hook 時的 [effort 等級](https://code.claude.com/docs/zh-TW/model-config.md#adjust-effort-level) 設定，包括 skill、subagent 或 `ultrathink` 的等級：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。在支援 effort 的模型上，存在於 `PreToolUse`、`PostToolUse`、`Stop`、`SubagentStop` 以及其他具有工具使用上下文的事件中。如果模型不支援您的等級，`level` 為實際執行的等級。您變更的等級可能會在它[開始生效](https://code.claude.com/docs/zh-TW/model-config.md#when-a-new-effort-level-starts)之前就顯示在此處。`$CLAUDE_EFFORT` 保存相同的等級。 |

739| `hook_event_name` | 觸發的事件名稱 |739| `hook_event_name` | 觸發的事件名稱 |

740 740 

741`agent_id` 和 `agent_type` 會告訴您的指令碼 hook 是在哪個 agent 中觸發的，例如 subagent、[同一程序內的隊友](https://code.claude.com/docs/zh-TW/agent-teams.md#choose-a-display-mode)，或您透過 `--agent` 選擇的 agent：741`agent_id` 和 `agent_type` 會告訴您的指令碼 hook 是在哪個 agent 中觸發的，例如 subagent、[同一程序內的隊友](https://code.claude.com/docs/zh-TW/agent-teams.md#choose-a-display-mode)，或您透過 `--agent` 選擇的 agent：

1898| `query` | string | `"react hooks best practices"` | 搜尋查詢 |1898| `query` | string | `"react hooks best practices"` | 搜尋查詢 |

1899| `allowed_domains` | array | `["docs.example.com"]` | 選用：只包含來自這些網域的結果 |1899| `allowed_domains` | array | `["docs.example.com"]` | 選用：只包含來自這些網域的結果 |

1900| `blocked_domains` | array | `["spam.example.com"]` | 選用：排除來自這些網域的結果 |1900| `blocked_domains` | array | `["spam.example.com"]` | 選用：排除來自這些網域的結果 |

1901| `mode` | string | `"extended"` | 選用：搜尋類型。`"standard"` 會要求較輕量的搜尋，`"extended"` 則要求完整搜尋。有些工作階段不會傳送 `mode`，而未帶此欄位的呼叫會執行完整搜尋。需要 Claude Code v2.1.282 或更新版本 |

1901 1902 

1902##### Agent1903##### Agent

1903 1904 

1968 1969 

1969當 hook 回傳 `"ask"` 時，向使用者顯示的權限提示會包含一個標籤，指出該 hook 的來源：來自任何設定檔或 agent frontmatter 的 hook 為 `[settings]`，外掛的 hook 為 `[plugin:<name>]`，來自 skill frontmatter 的 hook 則為 `[skill]`。這有助於使用者了解是哪個設定來源在要求確認。1970當 hook 回傳 `"ask"` 時，向使用者顯示的權限提示會包含一個標籤，指出該 hook 的來源：來自任何設定檔或 agent frontmatter 的 hook 為 `[settings]`，外掛的 hook 為 `[plugin:<name>]`，來自 skill frontmatter 的 hook 則為 `[skill]`。這有助於使用者了解是哪個設定來源在要求確認。

1970 1971 

1971hook 的 `"ask"` 在[自動模式](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode)中也會強制顯示權限提示：分類器仍可拒絕工具呼叫，但無法在不經提示的情況下核准該呼叫。

1972 

1973```json theme={null}1972```json theme={null}

1974{1973{

1975 "hookSpecificOutput": {1974 "hookSpecificOutput": {

1988>1987>

1989> PreToolUse 先前使用頂層的 `decision` 和 `reason` 欄位，但這些欄位在此事件中已棄用。請改用 `hookSpecificOutput.permissionDecision` 和 `hookSpecificOutput.permissionDecisionReason`。已棄用的值 `"approve"` 和 `"block"` 分別對應到 `"allow"` 和 `"deny"`。PostToolUse 和 Stop 等其他事件則繼續以頂層 `decision` 和 `reason` 作為其目前的格式。1988> PreToolUse 先前使用頂層的 `decision` 和 `reason` 欄位，但這些欄位在此事件中已棄用。請改用 `hookSpecificOutput.permissionDecision` 和 `hookSpecificOutput.permissionDecisionReason`。已棄用的值 `"approve"` 和 `"block"` 分別對應到 `"allow"` 和 `"deny"`。PostToolUse 和 Stop 等其他事件則繼續以頂層 `decision` 和 `reason` 作為其目前的格式。

1990 1989 

1990#### 自動模式中的 PreToolUse `ask` 決策

1991 

1992在[自動模式](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode)中，PreToolUse hook 的 `"ask"` 通常會將工具呼叫送往權限提示，而[分類器](https://code.claude.com/docs/zh-TW/permission-modes.md#how-the-classifier-evaluates-actions)不會對其做出決定。有些呼叫則會走不同的路徑：

1993 

1994* **同樣被 Claude Code 自身檢查標記的呼叫**：這些包括寫入[受保護路徑](https://code.claude.com/docs/zh-TW/permission-modes.md#protected-paths)，以及要求[在沙箱外執行](https://code.claude.com/docs/zh-TW/sandboxing.md#the-unsandboxed-retry-escape-hatch)的命令。分類器可能會在任何提示出現之前拒絕這類呼叫。如果分類器核准，該呼叫通常仍會送往提示。

1995* **`SubagentHandback` 呼叫**：此工具用於傳遞 subagent 的報告。它不會顯示任何提示，且即使分類器反對，呼叫仍會執行。

1996 

1997若要停止 `SubagentHandback` 呼叫，請回傳 `"deny"`。Claude Code 接著會告知 subagent（最多三次）其報告未傳遞，並請它再次呼叫該工具。如果您的 hook 持續拒絕，subagent 會在未透過此工具傳遞報告的情況下結束，而等待它的對話會收到一則說明此情況的通知。

1998 

1991#### 需要使用者互動的工具1999#### 需要使用者互動的工具

1992 2000 

1993`AskUserQuestion` 和 `ExitPlanMode` 需要使用者互動。在使用 `-p` 旗標的[非互動模式](https://code.claude.com/docs/zh-TW/headless.md)中，只有當執行具有可接收提示的[權限主機](https://code.claude.com/docs/zh-TW/headless.md#turn-off-permission-prompts-in-unattended-runs)（例如 Agent SDK 的 `canUseTool` 回呼）時，Claude Code 才會提供這些工具。2001`AskUserQuestion` 和 `ExitPlanMode` 需要使用者互動。在使用 `-p` 旗標的[非互動模式](https://code.claude.com/docs/zh-TW/headless.md)中，只有當執行具有可接收提示的[權限主機](https://code.claude.com/docs/zh-TW/headless.md#turn-off-permission-prompts-in-unattended-runs)（例如 Agent SDK 的 `canUseTool` 回呼）時，Claude Code 才會提供這些工具。

395 395 

396Claude Code 會在您傳送某些命令時立即執行它們，而不是排隊，其中包括 `/model`、`/effort` 和 `/fast`。這三個命令各自改變一個設定：模型、effort 等級或快速模式。Claude Code 是否將新設定應用於 Claude 已在進行的回合，或僅從您的下一回合開始，因命令而異：396Claude Code 會在您傳送某些命令時立即執行它們，而不是排隊，其中包括 `/model`、`/effort` 和 `/fast`。這三個命令各自改變一個設定：模型、effort 等級或快速模式。Claude Code 是否將新設定應用於 Claude 已在進行的回合，或僅從您的下一回合開始，因命令而異：

397 397 

398* [`/model`](https://code.claude.com/docs/zh-TW/model-config#setting-your-model)：一旦您確認 [快取警告](https://code.claude.com/docs/zh-TW/prompt-caching.md#switching-models)（如果 Claude Code 顯示的話），Claude Code 會將您的變更應用於該回合中它進行的下一個請求398* [`/model`](https://code.claude.com/docs/zh-TW/model-config#setting-your-model)：一旦您確認 [快取警告](https://code.claude.com/docs/zh-TW/prompt-caching.md#switching-models)（如果 Claude Code 顯示的話），Claude Code 會從該回合中它進行的下一個請求開始使用新模型

399* `/effort`：您傳送的下一則訊息會以新等級執行。若要 [在 Claude 已在進行的回合中開始套用](https://code.claude.com/docs/zh-TW/model-config.md#when-a-new-effort-level-starts)，請在 Claude 執行工具呼叫時排隊一則訊息399* `/effort`：您傳送的下一則訊息會以新等級執行。若要 [在 Claude 已在進行的回合中開始套用](https://code.claude.com/docs/zh-TW/model-config.md#when-a-new-effort-level-starts)，請在 Claude 執行工具呼叫時排隊一則訊息

400* [`/fast`](https://code.claude.com/docs/zh-TW/fast-mode#toggle-fast-mode)：Claude Code 保留回合開始時啟用的快速模式設定，因此您的速度變更從您的下一回合開始應用。如果您目前的模型不支援快速模式，開啟它也會 [切換您的模型](https://code.claude.com/docs/zh-TW/prompt-caching.md#turning-on-fast-mode)，Claude Code 會從該回合中的下一個請求開始使用新模型400* [`/fast`](https://code.claude.com/docs/zh-TW/fast-mode#toggle-fast-mode)：Claude Code 保留回合開始時啟用的快速模式設定，因此您的速度變更從您的下一回合開始應用。如果您目前的模型不支援快速模式，開啟它也會 [切換您的模型](https://code.claude.com/docs/zh-TW/prompt-caching.md#turning-on-fast-mode)，Claude Code 會從該回合中的下一個請求開始使用新模型

401 401 

761 761 

762* **您傳送提示詞**：Claude Code 會傳送您的提示詞而不是等待。如果您的提示詞也達到上限，它會保留在對話中，且 Claude Code 會再次開始等待。762* **您傳送提示詞**：Claude Code 會傳送您的提示詞而不是等待。如果您的提示詞也達到上限，它會保留在對話中，且 Claude Code 會再次開始等待。

763* **您退出 Claude Code**：當您繼續工作階段時，等待不會重新啟動。763* **您退出 Claude Code**：當您繼續工作階段時，等待不會重新啟動。

764* **對話轉手**：您使用 `/login` 切換帳戶、清除或倒帶對話、`/resume` 另一個工作階段、使用 `/teleport` 拉取一個、使用 `/tui` 重新啟動，或將工作階段交給 Claude Desktop、背景工作階段或雲端。764* **對話轉手**：您使用 `/login` 切換帳戶、清除或倒帶對話、`/resume` 另一個工作階段、使用 `/teleport` 拉取一個、使用 `/tui` 或 [`/restart`](https://code.claude.com/docs/zh-TW/commands#all-commands) 重新啟動，或將工作階段交給 Claude Desktop、背景工作階段或雲端。

765* **設定關閉，或重設超過 24 小時**：這只會結束 Claude Code 自行啟動的等待。您從 `/rate-limit-options` 選擇的等待會繼續倒數。765* **設定關閉，或重設超過 24 小時**：這只會結束 Claude Code 自行啟動的等待。您從 `/rate-limit-options` 選擇的等待會繼續倒數。

766* **繼續被阻止**：一個 [`UserPromptSubmit` hook](https://code.claude.com/docs/zh-TW/hooks#userpromptsubmit) 阻止繼續提示，或在到達模型之前失敗，會結束等待。Claude Code 會告訴您繼續未執行。傳送提示以繼續。766* **繼續被阻止**：一個 [`UserPromptSubmit` hook](https://code.claude.com/docs/zh-TW/hooks#userpromptsubmit) 阻止繼續提示，或在到達模型之前失敗，會結束等待。Claude Code 會告訴您繼續未執行。傳送提示以繼續。

767 767 

92 92 

93視您的方案和席位等級而定，Fable 的使用量可能會計入[用量點數](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)，而非使用您方案內含的限額。在此情況下，`/model` 選擇器會在 Fable 列上顯示「Requires usage credits」。若要管理用量點數，請參閱[為您的訂閱新增用量點數](https://code.claude.com/docs/zh-TW/costs.md#add-usage-credits-to-your-subscription)。93視您的方案和席位等級而定，Fable 的使用量可能會計入[用量點數](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)，而非使用您方案內含的限額。在此情況下，`/model` 選擇器會在 Fable 列上顯示「Requires usage credits」。若要管理用量點數，請參閱[為您的訂閱新增用量點數](https://code.claude.com/docs/zh-TW/costs.md#add-usage-credits-to-your-subscription)。

94 94 

95在互動式工作階段中，Claude Code 會在 Fable 請求計入用量點數之前顯示同意提示。採用組織計費的 Enterprise 方案成員不會看到此提示。您可以選擇使用用量點數繼續使用 Fable，或切換至您的預設模型。您也可以關閉此提示：95在互動式工作階段中，Claude Code 可能會顯示 Fable 用量點數同意提示。採用組織計費的 Enterprise 方案成員不會看到此提示。您可以選擇使用用量點數繼續使用 Fable，或切換至您的預設模型。您也可以關閉此提示：

96 96 

97* 當您使用 `/model` 選擇 Fable 模型時，會保留目前的模型。97* 當您使用 `/model` 選擇 Fable 模型時，會保留目前的模型。

98* 在工作階段進行中，Claude Code 會以您的預設模型繼續該回合。98* 在工作階段進行中，Claude Code 會以您的預設模型繼續該回合。

544* **您自己的變更**：一旦您選擇 effort 等級、在 `/model` 中挑選模型，或稍後恢復工作階段，被標記請求的等級就不再沿用。544* **您自己的變更**：一旦您選擇 effort 等級、在 `/model` 中挑選模型，或稍後恢復工作階段，被標記請求的等級就不再沿用。

545* **為單一回合設定的 effort**：如果您以 `ultrathink` 提高了被標記的回合，或 skill 的 `effort` frontmatter 設定了其等級，該等級會套用於該回合。之後的回合則以 [effort 解析順序](#adjust-effort-level)為備援模型給出的等級執行。545* **為單一回合設定的 effort**：如果您以 `ultrathink` 提高了被標記的回合，或 skill 的 `effort` frontmatter 設定了其等級，該等級會套用於該回合。之後的回合則以 [effort 解析順序](#adjust-effort-level)為備援模型給出的等級執行。

546 546 

547在工作階段中，執行 `/effort status` 以查看目前生效的等級，或執行 `/effort` 以變更等級。547若要查看備援後為您的工作階段設定的等級，請執行 `/effort status`。若要變更，請執行 `/effort`。

548 548 

549#### 檢查觸發備援的原因549#### 檢查觸發備援的原因

550 550 

607 607 

608Claude Code 依下列順序解析工作階段的 effort 等級，採用第一個適用的項目：608Claude Code 依下列順序解析工作階段的 effort 等級，採用第一個適用的項目：

609 609 

6101. 明確的選擇：[`CLAUDE_CODE_EFFORT_LEVEL`](https://code.claude.com/docs/zh-TW/env-vars#variables) 環境變數、以 `--effort` 啟動，或在工作階段中使用 `/effort`（[非互動式的 `/effort` 影響範圍較窄](#non-interactive-effort)）6101. [`CLAUDE_CODE_EFFORT_LEVEL`](https://code.claude.com/docs/zh-TW/env-vars#variables) 環境變數

6112. 您的設定：您為模型儲存的等級或 [`effortLevel`](https://code.claude.com/docs/zh-TW/settings-reference#effortlevel) 鍵，兩者之間以及各設定檔之間的優先順序說明於 [`modelSettings`](https://code.claude.com/docs/zh-TW/settings-reference#modelsettings)6112. 您在工作階段中選擇的等級，例如透過 `/effort`、`/model` 選擇器或 [`applyFlagSettings()`](https://code.claude.com/docs/zh-TW/agent-sdk/typescript#applyflagsettings)

6123. 模型的預設 effort：所有支援 effort 的模型都預設為 `high`，但 Opus 5.5、Sonnet 5.5 和 Haiku 5.5 預設為 `medium`、Opus 4.7 預設為 `xhigh`，而當您的組織為其[組織預設模型](#organization-default-model)設定預設 effort 等級時，該等級就是您執行該模型時的預設值6123. 以 `--effort` 啟動

6134. 您的設定：您為模型儲存的等級或 [`effortLevel`](https://code.claude.com/docs/zh-TW/settings-reference#effortlevel) 鍵，兩者之間以及各設定檔之間的優先順序說明於 [`modelSettings`](https://code.claude.com/docs/zh-TW/settings-reference#modelsettings)

6145. 模型的預設 effort：所有支援 effort 的模型都預設為 `high`，但 Opus 5.5、Sonnet 5.5 和 Haiku 5.5 預設為 `medium`，Opus 4.7 預設為 `xhigh`。如果您的組織為其[組織預設模型](#organization-default-model)設定了預設 effort 等級，該等級就是您執行該模型時的預設值。

613 615 

614自動模型備援後適用的等級，請參閱[備援後的 effort 等級](#effort-level-after-a-fallback)。616自動模型備援後適用的等級，請參閱[備援後的 effort 等級](#effort-level-after-a-fallback)。

615 617 

687您可以透過下列任一方式變更 effort：689您可以透過下列任一方式變更 effort：

688 690 

689* **`/effort`**：不帶引數執行 `/effort` 以開啟互動式滑桿，在 `/effort` 後接等級名稱以直接設定，或執行 `/effort auto` 以清除您為目前模型儲存的等級691* **`/effort`**：不帶引數執行 `/effort` 以開啟互動式滑桿，在 `/effort` 後接等級名稱以直接設定，或執行 `/effort auto` 以清除您為目前模型儲存的等級

690* **在 `/model` 中**：選擇模型時，使用左/右方向鍵調整 effort 滑桿692* **在 `/model` 中**：選擇模型時，使用左/右方向鍵調整 effort 滑桿。新等級最遲會從您的下一則訊息開始生效。在那之前，Claude 可能會繼續以舊等級工作，即使是在新模型上也一樣。當[優先順序高於您所選等級的來源](#adjust-effort-level)（例如 `CLAUDE_CODE_EFFORT_LEVEL`）適用時，Claude 會改以該來源的等級工作。

691* **`--effort` 旗標**：啟動 Claude Code 時傳入等級名稱，為單一工作階段設定693* **`--effort` 旗標**：啟動 Claude Code 時傳入等級名稱，為單一工作階段設定

692* **環境變數**：將 `CLAUDE_CODE_EFFORT_LEVEL` 設定為等級名稱。若要讓 Claude Code [不傳送 effort 等級](#send-no-effort-level)，請改為將其設定為 `auto` 或 `unset`694* **環境變數**：將 `CLAUDE_CODE_EFFORT_LEVEL` 設定為等級名稱。若要讓 Claude Code [不傳送 effort 等級](#send-no-effort-level)，請改為將其設定為 `auto` 或 `unset`

693* **設定**：在 [`modelSettings`](https://code.claude.com/docs/zh-TW/settings-reference#modelsettings) 中設定各模型的等級，或將 [`effortLevel`](https://code.claude.com/docs/zh-TW/settings-reference#effortlevel) 設定為 `low`、`medium`、`high` 或 `xhigh`，作為沒有設定等級之模型的預設值。這兩個鍵都不接受 `max` 作為等級，而 `ultracode` 有自己的 [`ultracode`](https://code.claude.com/docs/zh-TW/settings-reference#ultracode) 鍵695* **設定**：在 [`modelSettings`](https://code.claude.com/docs/zh-TW/settings-reference#modelsettings) 中設定各模型的等級，或將 [`effortLevel`](https://code.claude.com/docs/zh-TW/settings-reference#effortlevel) 設定為 `low`、`medium`、`high` 或 `xhigh`，作為沒有設定等級之模型的預設值。這兩個鍵都不接受 `max` 作為等級，而 `ultracode` 有自己的 [`ultracode`](https://code.claude.com/docs/zh-TW/settings-reference#ultracode) 鍵

694* **從已連線的裝置**：在 [Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md#what-connected-devices-see) 工作階段中，從手機或瀏覽器上的 effort 控制項選擇等級。該等級僅適用於目前的工作階段。需要 Claude Code v2.1.234 或更新版本696* **從已連線的裝置**：在 [Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md#what-connected-devices-see) 工作階段中，從手機或瀏覽器上的 effort 控制項選擇等級。該等級僅適用於目前的工作階段。需要 Claude Code v2.1.234 或更新版本

695* **Skill 和 subagent frontmatter**：在 [skill](https://code.claude.com/docs/zh-TW/skills.md#frontmatter-reference) 或 [subagent](https://code.claude.com/docs/zh-TW/sub-agents.md#supported-frontmatter-fields) markdown 檔案中設定 `effort`，以在該 skill 或 subagent 執行時覆寫 effort 等級697* **Skill 和 subagent frontmatter**：在 [skill](https://code.claude.com/docs/zh-TW/skills.md#frontmatter-reference) 或 [subagent](https://code.claude.com/docs/zh-TW/sub-agents.md#supported-frontmatter-fields) markdown 檔案中設定 `effort`，以在該 skill 或 subagent 執行時覆寫 effort 等級

696 698 

697Frontmatter effort 會在該 skill 或 subagent 處於作用中時適用，覆寫工作階段等級，但不會覆寫環境變數。[`maxEffortLevel`](https://code.claude.com/docs/zh-TW/settings-reference#maxeffortlevel) 或[組織 effort 上限](#organization-effort-limits)仍會限制 skill 或 subagent 執行時的等級。699Skill 的 `effort` 會適用至其執行所在回合結束為止，或在使用 `context: fork` 時適用於分叉出的 subagent 執行期間。Subagent 的 `effort` 會在 subagent 執行期間適用，除非[其呼叫方式覆寫了它](https://code.claude.com/docs/zh-TW/sub-agents.md#choose-an-effort-level)。當其中任一者適用時，skill 或 subagent 會以其等級執行，無論您啟動時、儲存或選擇的是哪個等級。如果設定了 `CLAUDE_CODE_EFFORT_LEVEL`，則改為套用該等級。

698 700 

699如果您在[受管設定](https://code.claude.com/docs/zh-TW/managed-settings.md)中設定 `effortLevel`，Claude Code 會在 [effort 解析順序](#adjust-effort-level)的設定步驟套用它，使用者仍可使用 `/effort` 或 `--effort` 變更等級。若要讓使用者維持在某個等級或以下，請設定 [`maxEffortLevel`](https://code.claude.com/docs/zh-TW/settings-reference#maxeffortlevel)。701[`maxEffortLevel`](https://code.claude.com/docs/zh-TW/settings-reference#maxeffortlevel) 或[組織 effort 上限](#organization-effort-limits)仍會限制 skill 或 subagent 執行時的等級。如果您在[受管設定](https://code.claude.com/docs/zh-TW/managed-settings.md)中設定 `effortLevel`，Claude Code 會在 [effort 解析順序](#adjust-effort-level)的設定步驟套用它，使用者仍可使用 `/effort` 或 `--effort` 變更等級。若要讓使用者維持在某個等級或以下，請設定 [`maxEffortLevel`](https://code.claude.com/docs/zh-TW/settings-reference#maxeffortlevel)。

700 702 

701#### 檢查您設定的 effort 等級703#### 檢查您設定的 effort 等級

702 704 

703選擇支援的模型時，effort 滑桿會出現在 `/model` 中。工作階段標頭中的等級（例如「with low effort」）來自您的 effort 設定，即使 Claude [仍以舊等級工作](#when-a-new-effort-level-starts)也是如此。頁尾也會在啟動時以及等級變更時短暫顯示 effort 等級。705選擇支援的模型時，effort 滑桿會出現在 `/model` 中。工作階段標頭中的等級（例如「with low effort」）來自您的 effort 設定，即使 Claude [仍以舊等級工作](#when-a-new-effort-level-starts)也是如此。頁尾也會在啟動時以及您變更等級時，短暫顯示為您工作階段設定的等級。

704 706 

705#### 新 effort 等級何時開始生效707#### 新 effort 等級何時開始生效

706 708 

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

557 557 

558* **讓工作階段到達收集器**：Claude Code 透過工作階段的網路傳送匯出，因此它是否到達 `OTEL_EXPORTER_OTLP_ENDPOINT` 中的主機取決於環境的[網路存取層級](https://code.claude.com/docs/zh-TW/cloud-environments.md#access-levels)。如果工作階段無法在您選擇的層級到達收集器的網域，請[將網域新增至環境的允許清單](https://code.claude.com/docs/zh-TW/cloud-environments.md#allow-specific-domains)，因為沒有伺服器受管設定會將網域新增至環境的網路允許清單。558* **讓工作階段到達收集器**：Claude Code 透過工作階段的網路傳送匯出，因此它是否到達 `OTEL_EXPORTER_OTLP_ENDPOINT` 中的主機取決於環境的[網路存取層級](https://code.claude.com/docs/zh-TW/cloud-environments.md#access-levels)。如果工作階段無法在您選擇的層級到達收集器的網域，請[將網域新增至環境的允許清單](https://code.claude.com/docs/zh-TW/cloud-environments.md#allow-specific-domains)，因為沒有伺服器受管設定會將網域新增至環境的網路允許清單。

559* **Claude Tag 頻道使用組織層級環境**：頻道工作階段在組織層級環境中執行，而不是成員的個人環境，因此請在設定為組織預設或釘選到頻道的[共用環境](https://code.claude.com/docs/zh-TW/cloud-environments.md#organization-shared-environments)上進行允許清單和任何環境變數變更。559* **Claude Tag 頻道**：請在設定為組織預設或釘選到頻道的[共用環境](https://code.claude.com/docs/zh-TW/cloud-environments.md#organization-shared-environments)上進行允許清單和任何環境變數變更。

560* **Cowork 單獨設定**：如[表面涵蓋表](https://code.claude.com/docs/zh-TW/model-config.md#surface-coverage)所示，Cowork 工作階段不會接收伺服器受管設定，因此伺服器受管 `env` 區塊不會設定其遙測。560* **Cowork 單獨設定**：如[表面涵蓋表](https://code.claude.com/docs/zh-TW/model-config.md#surface-coverage)所示，Cowork 工作階段不會接收伺服器受管設定，因此伺服器受管 `env` 區塊不會設定其遙測。

561 561 

562### 將遙測歸因於雲端工作階段562### 將遙測歸因於雲端工作階段

1468* `period_days`：合併後設定中的 `cleanupPeriodDays` 值（以天為單位），若無任何來源設定則為 `30`。在 skipped 事件中，為清理原本會使用的值，依 Claude Code 可讀取的設定來源計算1468* `period_days`：合併後設定中的 `cleanupPeriodDays` 值（以天為單位），若無任何來源設定則為 `30`。在 skipped 事件中，為清理原本會使用的值，依 Claude Code 可讀取的設定來源計算

1469* `used_default`：當沒有任何可讀取的設定來源設定 `cleanupPeriodDays` 時為 `"true"`，否則為 `"false"`。在 complete 事件中，`"true"` 表示套用了 30 天的預設值1469* `used_default`：當沒有任何可讀取的設定來源設定 `cleanupPeriodDays` 時為 `"true"`，否則為 `"false"`。在 complete 事件中，`"true"` 表示套用了 30 天的預設值

1470* `skip_reason`：Claude Code 暫停清理的原因。僅在 `result` 為 `"skipped"` 時存在：1470* `skip_reason`：Claude Code 暫停清理的原因。僅在 `result` 為 `"skipped"` 時存在：

1471 * `"user_source_disabled"`：使用者設定被排除（例如透過 [`--setting-sources`](https://code.claude.com/docs/zh-TW/cli-reference#cli-flags) 旗標或 SDK 的 [`settingSources`](https://code.claude.com/docs/zh-TW/agent-sdk/typescript#options) 選項），且沒有任何已啟用的來源提供 `cleanupPeriodDays`1471 * `"user_source_disabled"`：使用者設定被排除，例如透過 [`--setting-sources`](https://code.claude.com/docs/zh-TW/cli-reference#cli-flags) 旗標或 SDK 的 [`settingSources`](https://code.claude.com/docs/zh-TW/agent-sdk/typescript#options) 選項，且沒有已啟用的來源提供 `cleanupPeriodDays`

1472 * `"settings_unknowable"`：某個設定檔無法讀取或剖析，因此 `cleanupPeriodDays` 或 `desktopSessionCleanupPeriodDays` 可能被設為 Claude Code 看不到的值1472 * `"settings_unknowable"`：某個設定檔無法讀取或剖析，因此 `cleanupPeriodDays` 或 `desktopSessionCleanupPeriodDays` 可能被設定為 Claude Code 看不到的值

1473 * `"settings_invalid_key_set"`：設定有驗證錯誤，且明確設定了 `cleanupPeriodDays` 或 `desktopSessionCleanupPeriodDays`，因此改用預設值可能會違背該設定而刪除或保留檔案1473 * `"settings_invalid_key_set"`：設定有驗證錯誤，且明確設定了 `cleanupPeriodDays` 或 `desktopSessionCleanupPeriodDays`，因此改用預設值可能會違背該設定而刪除或保留檔案

1474 * `"remote_settings_unknowable"`：第三方部署上 Claude Desktop 的 Code 分頁中的工作階段請求了[伺服器受管設定](https://code.claude.com/docs/zh-TW/server-managed-settings.md)。它未收到可用的回應，因此 `cleanupPeriodDays` 可能被設定為 Claude Code 看不到的值

1474* `transcripts_deleted`：清理所刪除的工作階段逐字稿（即最上層的 `~/.claude/projects/*/*.jsonl` 檔案）數量1475* `transcripts_deleted`：清理所刪除的工作階段逐字稿（即最上層的 `~/.claude/projects/*/*.jsonl` 檔案）數量

1475* `transcripts_exempted_desktop`：超過保留期間但依 [Claude Desktop 與 Cowork 規則](https://code.claude.com/docs/zh-TW/claude-directory.md#cleaned-up-automatically)被清理保留的逐字稿數量。這些不會計入 `files_past_cutoff`。需要 Claude Code v2.1.248 或更新版本1476* `transcripts_exempted_desktop`：超過保留期間但依 [Claude Desktop 與 Cowork 規則](https://code.claude.com/docs/zh-TW/claude-directory.md#cleaned-up-automatically)被清理保留的逐字稿數量。這些不會計入 `files_past_cutoff`。需要 Claude Code v2.1.248 或更新版本

1476* `session_files_deleted`：工作階段檔案清理所刪除的項目數量：逐字稿加上每個工作階段的附屬檔案，例如 sidecar、錄製內容與工具結果1477* `session_files_deleted`：工作階段檔案清理所刪除的項目數量：逐字稿加上每個工作階段的附屬檔案，例如 sidecar、錄製內容與工具結果

338| 使用 CronCreate 等工具排程、並在使用者下一次輸入前到期的週期性工作 | 當時不會啟動回合。該工作會失去那一次執行，並保留其排程。 | 無需任何動作 |338| 使用 CronCreate 等工具排程、並在使用者下一次輸入前到期的週期性工作 | 當時不會啟動回合。該工作會失去那一次執行，並保留其排程。 | 無需任何動作 |

339| 來自您的 mod 所啟動之監視器的事件 | 監視器會持續執行。監視器在使用者下一次輸入前產生的事件會被捨棄，但監視器結束的通知除外，該通知會在該輸入之後送達。 | 無法採取任何動作 |339| 來自您的 mod 所啟動之監視器的事件 | 監視器會持續執行。監視器在使用者下一次輸入前產生的事件會被捨棄，但監視器結束的通知除外，該通知會在該輸入之後送達。 | 無法採取任何動作 |

340| 您的 mod 產生、之後以 `$.session.send` 恢復，並在使用者下一次輸入前完成的 subagent | 其完成通知會等待，並在該輸入之後進入對話 | 無需任何動作 |340| 您的 mod 產生、之後以 `$.session.send` 恢復，並在使用者下一次輸入前完成的 subagent | 其完成通知會等待，並在該輸入之後進入對話 | 無需任何動作 |

341| 來自 `$.tool.call`、在使用者停止回合時已在執行，並在使用者下一次輸入前達到其逾時的前景 Bash 或 PowerShell 命令 | 在逾時時被停止，而非[移至背景](https://code.claude.com/docs/zh-TW/tools-reference.md#foreground-commands-that-move-to-the-background)。呼叫以設定了 `isError` 的結果解析，且輸出包含這一行 `Ended instead of moving to the background: plugins' input is held, by a Stop or by the host's limits.` | 在使用者下一次輸入之後，依照[重試被拒絕或被捨棄的呼叫](#retry-a-refused-or-dropped-call)所示再次執行 |

341 342 

342當排程工作到期或監視器在使用者下一次輸入前產生事件時，使用者可能會看到 [`Stopped:` 快顯通知](https://code.claude.com/docs/zh-TW/plugins/mods/troubleshoot#stopped-type-a-message-to-continue)。343當排程工作到期或監視器在使用者下一次輸入前產生事件時，使用者可能會看到 [`Stopped:` 快顯通知](https://code.claude.com/docs/zh-TW/plugins/mods/troubleshoot#stopped-type-a-message-to-continue)。

343 344 

94 94 

95在大多數模型上，在工作階段中途變更 [effort 等級](https://code.claude.com/docs/zh-TW/model-config.md#adjust-effort-level)意味著下一個請求會讀取整個對話歷史記錄而沒有快取命中。當快取仍然溫暖時，Claude Code 會要求您先確認變更。95在大多數模型上，在工作階段中途變更 [effort 等級](https://code.claude.com/docs/zh-TW/model-config.md#adjust-effort-level)意味著下一個請求會讀取整個對話歷史記錄而沒有快取命中。當快取仍然溫暖時，Claude Code 會要求您先確認變更。

96 96 

97在具有 API 金鑰或 Claude 訂閱的 Opus 5.5、Sonnet 5.5、Haiku 5.5 和 Fable 5.1 上，變更 effort 會保留快取，Claude Code 會在不詢問的情況下套用新的等級。這不適用於 Amazon Bedrock、Google Cloud 的 Agent Platform 或 [Claude 應用程式閘道](https://code.claude.com/docs/zh-TW/claude-apps-gateway)，或當您設定 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](https://code.claude.com/docs/zh-TW/llm-gateway-protocol#disable-pre-release-capabilities) 或您的組織具有 HIPAA 設定時。97在具有 API 金鑰或 Claude 訂閱的 Opus 5.5、Sonnet 5.5、Haiku 5.5 和 Fable 5.1 上，變更 effort 時會保留快取。Claude Code 會在不詢問的情況下[套用新的等級](https://code.claude.com/docs/zh-TW/model-config.md#when-a-new-effort-level-starts)。在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 [Claude 應用程式閘道](https://code.claude.com/docs/zh-TW/claude-apps-gateway)上，或當您設定 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](https://code.claude.com/docs/zh-TW/llm-gateway-protocol#disable-pre-release-capabilities) 或您的組織具有 HIPAA 設定時，其運作方式與大多數模型相同。

98 98 

99在 v2.1.260 之前，在具有 API 金鑰或 Claude 訂閱的 Fable 5.1 上變更 effort 也會使快取失效。99在 v2.1.260 之前，在具有 API 金鑰或 Claude 訂閱的 Fable 5.1 上變更 effort 也會使快取失效。

100 100 

565 565 

566在 macOS 上，當被拒絕的路徑經過符號連結時（例如 `~/.claude` 是連結到 dotfiles 儲存庫的符號連結），沙箱也會拒絕該路徑的實際位置。這涵蓋沙箱本身的拒絕項目，以及您以字面形式寫下的 `denyWrite` 和 `denyRead` 項目。566在 macOS 上，當被拒絕的路徑經過符號連結時（例如 `~/.claude` 是連結到 dotfiles 儲存庫的符號連結），沙箱也會拒絕該路徑的實際位置。這涵蓋沙箱本身的拒絕項目，以及您以字面形式寫下的 `denyWrite` 和 `denyRead` 項目。

567 567 

568包含 `*`、`?` 或 `[` 的 `denyWrite` 項目，當這些字元中第一個出現者之前的某個資料夾是符號連結時，也同樣涵蓋在內。例如，`~/.claude/*.json` 也會在 `~/.claude` 的實際位置下被拒絕。

569 

568### 網路隔離570### 網路隔離

569 571 

570沙箱化命令沒有直接連到網路的路徑：572沙箱化命令沒有直接連到網路的路徑：

40* **零資料保留和 HIPAA**：對於啟用了[零資料保留](https://code.claude.com/docs/zh-TW/zero-data-retention.md)或套用了 [HIPAA 設定](https://code.claude.com/docs/zh-TW/hipaa-setup.md)的組織不可用。40* **零資料保留和 HIPAA**：對於啟用了[零資料保留](https://code.claude.com/docs/zh-TW/zero-data-retention.md)或套用了 [HIPAA 設定](https://code.claude.com/docs/zh-TW/hipaa-setup.md)的組織不可用。

41* **模型推理**：除非您將執行器設定為[將模型請求傳送至 Amazon Bedrock 或 Google Cloud 的 Agent Platform](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration.md#send-model-requests-to-bedrock-or-agent-platform)，否則工作階段會使用 Anthropic API。在這兩種情況下，工作階段內容都會傳送至 Anthropic。在以此方式設定的執行器上，[伺服器管理的設定](https://code.claude.com/docs/zh-TW/server-managed-settings.md)和來自 claude.ai 的組織政策不會套用到工作階段。41* **模型推理**：除非您將執行器設定為[將模型請求傳送至 Amazon Bedrock 或 Google Cloud 的 Agent Platform](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration.md#send-model-requests-to-bedrock-or-agent-platform)，否則工作階段會使用 Anthropic API。在這兩種情況下，工作階段內容都會傳送至 Anthropic。在以此方式設定的執行器上，[伺服器管理的設定](https://code.claude.com/docs/zh-TW/server-managed-settings.md)和來自 claude.ai 的組織政策不會套用到工作階段。

42* **使用介面**：從 [claude.ai/code](https://claude.ai/code)、行動和桌面應用程式、[雲端排程任務](https://code.claude.com/docs/zh-TW/routines.md)和終端機啟動的工作階段，使用 [`claude --cloud`](https://code.claude.com/docs/zh-TW/claude-code-on-the-web#from-terminal-to-cloud) 或 [`--environment` 分派](https://code.claude.com/docs/zh-TW/self-hosted-environments-testing#run-the-test-loop)，可以在自託管環境中執行。[Claude Tag](https://claude.com/docs/claude-tag/overview) 工作階段也可以在其中執行，但 Claude 在這些工作階段中還無法使用[存取套件](https://claude.com/docs/claude-tag/concepts/glossary#access-bundle)。[Claude Security](https://code.claude.com/docs/zh-TW/claude-security.md) 和 [Code Review](https://code.claude.com/docs/zh-TW/code-review.md) 工作階段還沒有路由到它們。對這兩個使用介面的支援將單獨跟進。42* **使用介面**：從 [claude.ai/code](https://claude.ai/code)、行動和桌面應用程式、[雲端排程任務](https://code.claude.com/docs/zh-TW/routines.md)和終端機啟動的工作階段，使用 [`claude --cloud`](https://code.claude.com/docs/zh-TW/claude-code-on-the-web#from-terminal-to-cloud) 或 [`--environment` 分派](https://code.claude.com/docs/zh-TW/self-hosted-environments-testing#run-the-test-loop)，可以在自託管環境中執行。[Claude Tag](https://claude.com/docs/claude-tag/overview) 工作階段也可以在其中執行，但 Claude 在這些工作階段中還無法使用[存取套件](https://claude.com/docs/claude-tag/concepts/glossary#access-bundle)。[Claude Security](https://code.claude.com/docs/zh-TW/claude-security.md) 和 [Code Review](https://code.claude.com/docs/zh-TW/code-review.md) 工作階段還沒有路由到它們。對這兩個使用介面的支援將單獨跟進。

43* **儲存庫**：工作階段從 GitHub 簽出儲存庫；請參閱 [GitHub 身份驗證選項](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md#github-authentication-options)。對於 GitHub Enterprise Server 主機，請參閱其[網路需求](https://code.claude.com/docs/zh-TW/github-enterprise-server.md#network-requirements)。43* **儲存庫**：工作階段從 GitHub 或 GitHub Enterprise Server 簽出儲存庫。使用 `--environment` 分派啟動的工作階段也可以使用其他 Git 主機：

44 * **GitHub**：請參閱 [GitHub 身分驗證選項](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md#github-authentication-options)。

45 * **GitHub Enterprise Server**：請參閱其[網路需求](https://code.claude.com/docs/zh-TW/github-enterprise-server.md#network-requirements)。

46 * **其他 Git 主機**：請參閱[使用 `--environment` 啟動工作階段的需求](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy#start-a-session-on-a-repository-outside-github)。

44* **計費**：自託管環境中的工作階段消耗您組織的 Claude Code 使用量，與 Anthropic 託管環境中的工作階段相同。47* **計費**：自託管環境中的工作階段消耗您組織的 Claude Code 使用量，與 Anthropic 託管環境中的工作階段相同。

45 48 

46## 為什麼要自託管49## 為什麼要自託管

113 116 

114* **控制平面**：執行器輪詢 `api.anthropic.com` 以獲取工作並發佈設定進度和失敗事件，全部出站 HTTPS。輪詢充當執行器的心跳。117* **控制平面**：執行器輪詢 `api.anthropic.com` 以獲取工作並發佈設定進度和失敗事件，全部出站 HTTPS。輪詢充當執行器的心跳。

115* **Git**：執行器透過 HTTPS 或 SSH 從您的 git 主機複製和推送，使用您的部署提供的憑證進行身份驗證。請參閱[設定 git](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#configure-git) 以了解各種選項，包括每個工作階段鑄造的憑證。使用 [Anthropic git 代理伺服器](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#use-the-anthropic-git-proxy)時，github.com 上儲存庫的 git 流量會改為經由 `api.anthropic.com`。118* **Git**：執行器透過 HTTPS 或 SSH 從您的 git 主機複製和推送，使用您的部署提供的憑證進行身份驗證。請參閱[設定 git](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#configure-git) 以了解各種選項，包括每個工作階段鑄造的憑證。使用 [Anthropic git 代理伺服器](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#use-the-anthropic-git-proxy)時，github.com 上儲存庫的 git 流量會改為經由 `api.anthropic.com`。

116* **工作階段子程序**：子 Claude Code 程序持有工作階段到 `api.anthropic.com` 的事件串流，並為模型推理和工作階段期間執行的 git 命令進行自己的出站呼叫。在使用 [Anthropic 管理的 git](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#use-the-anthropic-git-proxy) 的工作階段中，子程序會透過它開啟到 `api.anthropic.com` 的 WebSocket 連接，傳送其針對 github.com 的 `git` 和 `gh` 流量。119* **工作階段子程序**：子 Claude Code 程序持有工作階段到 `api.anthropic.com` 的事件串流，並為模型推理和工作階段期間執行的 git 命令進行自己的出站呼叫。在使用 [Anthropic 管理的 git](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#use-the-anthropic-git-proxy) 的工作階段中，子程序會開啟到 `api.anthropic.com` 的 WebSocket 連接，承載來自 `git` 和 `gh` 的 github.com 流量。

117* **SCM 連接器**：可選的協調器 [SCM 連接器](https://code.claude.com/docs/zh-TW/self-hosted-environments-reference.md#scm-connector-flags)無法使用，因此其隧道不會開啟。該隧道是到 `api.anthropic.com` 的 WebSocket 連接。120* **SCM 連接器**：可選的協調器 [SCM 連接器](https://code.claude.com/docs/zh-TW/self-hosted-environments-reference.md#scm-connector-flags)無法使用，因此其隧道不會開啟。該隧道是到 `api.anthropic.com` 的 WebSocket 連接。

118 121 

119請參閱[網路需求](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#network-requirements)以取得完整的出站清單。[上面的圖表](#how-self-hosted-environments-work)顯示了這些路徑，除了可選的 SCM 連接器和 Anthropic 管理的 git 連接。122請參閱[網路需求](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#network-requirements)以取得完整的出站清單。[上面的圖表](#how-self-hosted-environments-work)顯示了這些路徑，除了可選的 SCM 連接器和 Anthropic 管理的 git 連接。

42| `CLAUDE_CODE_REMOTE_MCP_CONFIG` | `CLAUDE_CONFIG_DIR` 中某個檔案的路徑，該檔案保存 Anthropic 控制平面為此工作階段傳遞的 MCP 伺服器定義。如果您的包裝指令碼會重建子程序的環境，請帶上此變數。若缺少此變數，當控制平面更新所傳遞的伺服器時，子程序會關閉您的包裝指令碼以 [`--mcp-config`](https://code.claude.com/docs/zh-TW/cli-reference#cli-flags) 新增、但不在該更新中的任何 stdio、HTTP 或 SSE 伺服器。需要 Claude Code v2.1.299 或更新版本。 |42| `CLAUDE_CODE_REMOTE_MCP_CONFIG` | `CLAUDE_CONFIG_DIR` 中某個檔案的路徑，該檔案保存 Anthropic 控制平面為此工作階段傳遞的 MCP 伺服器定義。如果您的包裝指令碼會重建子程序的環境，請帶上此變數。若缺少此變數，當控制平面更新所傳遞的伺服器時，子程序會關閉您的包裝指令碼以 [`--mcp-config`](https://code.claude.com/docs/zh-TW/cli-reference#cli-flags) 新增、但不在該更新中的任何 stdio、HTTP 或 SSE 伺服器。需要 Claude Code v2.1.299 或更新版本。 |

43| `ANTHROPIC_BASE_URL` | 子程序將使用的 API 基礎 URL，由控制平面按工作階段傳遞，通常為 `https://api.anthropic.com`。不要覆寫它：工作階段的推理憑證是 Anthropic 發行的 OAuth token，其他提供者不接受。 |43| `ANTHROPIC_BASE_URL` | 子程序將使用的 API 基礎 URL，由控制平面按工作階段傳遞，通常為 `https://api.anthropic.com`。不要覆寫它：工作階段的推理憑證是 Anthropic 發行的 OAuth token，其他提供者不接受。 |

44| `CLAUDE_CODE_OAUTH_TOKEN` | 子程序用於模型推理的短期 OAuth 存取 token，生命週期約為 30 分鐘。執行器在過期前重新鑄造它，並透過子程序的 stdin 傳遞輪換，因此未[保持 stdin 連接](#keep-stdin-and-file-descriptor-3-attached)的包裝指令碼只會看到初始值。不要依賴您組織的 IP 允許清單來限制此 token 的使用：請將其視為持有人憑證，如果洩露，大約 30 分鐘內仍可使用，不要將其寫入日誌、寫入磁碟或在工作階段容器外轉發它。 |44| `CLAUDE_CODE_OAUTH_TOKEN` | 子程序用於模型推理的短期 OAuth 存取 token，生命週期約為 30 分鐘。執行器在過期前重新鑄造它，並透過子程序的 stdin 傳遞輪換，因此未[保持 stdin 連接](#keep-stdin-and-file-descriptor-3-attached)的包裝指令碼只會看到初始值。不要依賴您組織的 IP 允許清單來限制此 token 的使用：請將其視為持有人憑證，如果洩露，大約 30 分鐘內仍可使用，不要將其寫入日誌、寫入磁碟或在工作階段容器外轉發它。 |

45| `CLAUDE_RUNNER_ALIVE_EVERY_MS` | 執行器設定當[回合在子程序初始化之前開始](https://code.claude.com/docs/zh-TW/self-hosted-environments-reference.md#session-startup-timeout)時，子程序回報其仍存活的頻率（以毫秒為單位）。如果您的包裝指令碼會重建子程序的環境，請帶上此變數，否則執行器可能會在該回合期間釋放工作階段，並記錄 `no child output for <n> — releasing`。執行器和子程序都需要 v2.1.309 或更新版本。 |

45 46 

46包裝指令碼也會繼承子程序的其餘受管環境，包括任何伺服器提供的環境變數。`exec` 會自動傳播所有內容；如果您的包裝指令碼以另一種方式生成子程序，請轉發完整環境。47包裝指令碼也會繼承子程序的其餘受管環境，包括任何伺服器提供的環境變數。`exec` 會自動傳播所有內容；如果您的包裝指令碼以另一種方式生成子程序，請轉發完整環境。

47 48 

307| `CLAUDE_RUNNER_ATTEMPT` | 用於日誌的每工作階段計數器。它不是重試次數，也不是請求次數。預熱請求時為 `0`，但某個工作階段的請求也可能帶有 `0`。 |308| `CLAUDE_RUNNER_ATTEMPT` | 用於日誌的每工作階段計數器。它不是重試次數，也不是請求次數。預熱請求時為 `0`，但某個工作階段的請求也可能帶有 `0`。 |

308| `CLAUDE_RUNNER_ORDER_SERVER_TIME` | 取自輪詢回應 HTTP `Date` 標頭的伺服器時間。當 hook 驗證工作單 JWT 的 `exp` 時，請與此值比較而非本機時鐘，以容忍時鐘偏差。若閘道省略了該標頭則為空值。 |309| `CLAUDE_RUNNER_ORDER_SERVER_TIME` | 取自輪詢回應 HTTP `Date` 標頭的伺服器時間。當 hook 驗證工作單 JWT 的 `exp` 時，請與此值比較而非本機時鐘，以容忍時鐘偏差。若閘道省略了該標頭則為空值。 |

309| `CLAUDE_RUNNER_POOL_ID` | 新 runner 應加入的環境 ID，格式為 `ccpool_...` |310| `CLAUDE_RUNNER_POOL_ID` | 新 runner 應加入的環境 ID，格式為 `ccpool_...` |

310| `CLAUDE_RUNNER_ACCOUNT_ID` | 將該工作階段排入佇列之帳戶的帶標籤 ID。請將其用於依帳戶路由、配額或成本分攤，而非作為去重金鑰。無法取得時為空值；對於 Claude Tag 頻道工作階段則一律為空值，因為沒有任何帳戶將其排入佇列。 |311| `CLAUDE_RUNNER_ACCOUNT_ID` | 將該工作階段排入佇列之帳戶的帶標籤 ID。請將其用於依帳戶路由、配額或成本分攤，而非作為去重金鑰。無法取得時為空值。 |

311| `CLAUDE_RUNNER_ACCOUNT_EMAIL` | 將該工作階段排入佇列之帳戶的電子郵件。無法取得時為空值。請將此電子郵件視為個人識別資訊，不要記錄它。 |312| `CLAUDE_RUNNER_ACCOUNT_EMAIL` | 將該工作階段排入佇列之帳戶的電子郵件。無法取得時為空值。請將此電子郵件視為個人識別資訊，不要記錄它。 |

312| `CLAUDE_RUNNER_PRIMARY_REPO_URL` | 工作階段第一個 git 來源的 URL，用於路由到已預熱該儲存庫的 runner。工作階段沒有 git 來源時為空值。 |313| `CLAUDE_RUNNER_PRIMARY_REPO_URL` | 工作階段第一個 git 來源的 URL，用於路由到已預熱該儲存庫的 runner。工作階段沒有 git 來源時為空值。 |

313| `CLAUDE_RUNNER_PRIMARY_REPO_REVISION` | 工作階段第一個 git 來源的修訂版本：分支、SHA、標籤或完整參照名稱。未指定時為空值。 |314| `CLAUDE_RUNNER_PRIMARY_REPO_REVISION` | 工作階段第一個 git 來源的修訂版本：分支、SHA、標籤或完整參照名稱。未指定時為空值。 |

381 382 

382| 旗標（含範例值） | 傳給 | 作用 |383| 旗標（含範例值） | 傳給 | 作用 |

383| :- | :- | :- |384| :- | :- | :- |

384| `--release-idle-session-min 30` | 您的 hook 啟動的每個 runner | runner 會在閒置達該分鐘數後釋放其工作階段，然後以 0 結束。該工作階段會在其使用者傳送下一則訊息時繼續，但[尚未推送的工作將會遺失](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#additional-limitations)。對於工作階段留下仍在執行的程序，請[保留該工作階段](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#keep-an-idle-session-while-its-processes-run)。 |385| `--release-idle-session-min 30` | 您的 hook 啟動的每個 runner | runner 會在閒置達該分鐘數後釋放其工作階段，然後以 0 結束。該工作階段會在其使用者傳送下一則訊息時繼續，但[尚未推送的工作將會遺失](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#resumed-sessions-lose-unpushed-work)。對於工作階段留下仍在執行的程序，請[保留該工作階段](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#keep-an-idle-session-while-its-processes-run)。 |

385| `--kill-session-after-min 480` | 您的 hook 啟動的每個 runner | 將每個工作階段限制在該分鐘數內，作為[不計為閒置之工作階段](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#some-sessions-don’t-count-as-idle)的防線，因此請將其設定為高於您預期最長的工作階段 |386| `--kill-session-after-min 480` | 您的 hook 啟動的每個 runner | 將每個工作階段限制在該分鐘數內，作為[不計為閒置之工作階段](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#some-sessions-don’t-count-as-idle)的防線，因此請將其設定為高於您預期最長的工作階段 |

386| `--exit-if-unused-min 60` | 待命 runner，即您的 hook 為預熱請求所啟動的 runner | 從未接手工作階段的待命 runner 會在該分鐘數後結束。若您設定了 [`--min-idle`](https://code.claude.com/docs/zh-TW/self-hosted-environments-reference#orchestrator-cli-flags)，除非該待命 runner 屬於多餘，否則您會得到一個替代者，因此請使用遠高於啟動時間的值。 |387| `--exit-if-unused-min 60` | 待命 runner，即您的 hook 為預熱請求所啟動的 runner | 從未接手工作階段的待命 runner 會在該分鐘數後結束。若您設定了 [`--min-idle`](https://code.claude.com/docs/zh-TW/self-hosted-environments-reference#orchestrator-cli-flags)，除非該待命 runner 屬於多餘，否則您會得到一個替代者，因此請使用遠高於啟動時間的值。 |

387 388 

761 762 

762* **git 身分**：在執行器映像中設定 `user.name` 與 `user.email`，或使用 [`--configure-git`](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy#let-the-runner-configure-git) 啟動執行器763* **git 身分**：在執行器映像中設定 `user.name` 與 `user.email`，或使用 [`--configure-git`](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy#let-the-runner-configure-git) 啟動執行器

763* **推送憑證**：使用 [Anthropic 管理的 git](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#use-the-anthropic-git-proxy)，或依照[在映像中附帶 git 設定](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#ship-git-config-in-your-image)所述提供憑證764* **推送憑證**：使用 [Anthropic 管理的 git](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#use-the-anthropic-git-proxy)，或依照[在映像中附帶 git 設定](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#ship-git-config-in-your-image)所述提供憑證

764* **針對恢復的工作階段**：在環境中的每個執行器上設定 [`--push-outcome-on-release`](https://code.claude.com/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags)。如此一來，恢復的工作階段便會從 Claude 推送到該工作階段分支的提交開始。關於此旗標的限制，請參閱[恢復的工作階段會遺失未推送的工作](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#additional-limitations)。765* **針對恢復的工作階段**：在環境中的每個執行器上設定 [`--push-outcome-on-release`](https://code.claude.com/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags)。如此一來，恢復的工作階段便會從 Claude 推送到該工作階段分支的提交開始。關於此旗標的限制，請參閱[恢復的工作階段會遺失未推送的工作](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#resumed-sessions-lose-unpushed-work)。

765 766 

766Stop hook 每個回合最多只會提示一次。若提交或推送失敗，該回合仍會結束。請在工作階段中尋找 git 的錯誤訊息，並修正其指出的問題。767Stop hook 每個回合最多只會提示一次。若提交或推送失敗，該回合仍會結束。請在工作階段中尋找 git 的錯誤訊息，並修正其指出的問題。

767 768 

63 63 

64| 主機 | 連接埠 | 何時需要 |64| 主機 | 連接埠 | 何時需要 |

65| :- | :- | :- |65| :- | :- | :- |

66| `api.github.com` | 443 | 無論是否使用 `--use-anthropic-git-proxy`，當執行器映像包含 [GitHub CLI](#github-api-access-with-the-github-cli) 且您為工作階段提供 github.com 憑證（例如 `GH_TOKEN`）時 |

66| `downloads.claude.ai` | 443 | 在安裝時，當您使用原生安裝程式在主機上安裝或更新 Claude Code 時；`install.sh` 指令碼本身是從 `claude.ai` 提供的。在工作階段執行時，僅當工作階段從官方 Anthropic 市場安裝外掛程式時。 |67| `downloads.claude.ai` | 443 | 在安裝時，當您使用原生安裝程式在主機上安裝或更新 Claude Code 時；`install.sh` 指令碼本身是從 `claude.ai` 提供的。在工作階段執行時，僅當工作階段從官方 Anthropic 市場安裝外掛程式時。 |

67| `storage.googleapis.com` | 443 | 在工作階段執行時，用於 `/plugin` 中顯示的外掛程式安裝計數和中繼資料。 |68| `storage.googleapis.com` | 443 | 在工作階段執行時，用於 `/plugin` 中顯示的外掛程式安裝計數和中繼資料。 |

68| `code.claude.com` 和 `claude.com` | 443 | 內置 claude-code-guide 代理的文件查詢和工作階段期間預先批准的 WebFetch 請求。阻止這些主機只會影響文件查詢。 |69| `code.claude.com` 和 `claude.com` | 443 | 內置 claude-code-guide 代理的文件查詢和工作階段期間預先批准的 WebFetch 請求。阻止這些主機只會影響文件查詢。 |

167 168 

168* 執行器設定 `GIT_TERMINAL_PROMPT=0`，因此 Git 不會要求使用者名稱或密碼。169* 執行器設定 `GIT_TERMINAL_PROMPT=0`，因此 Git 不會要求使用者名稱或密碼。

169* 執行器使用 `BatchMode=yes` 執行 SSH，附加到您的 `GIT_SSH_COMMAND`（如果您設定了），因此 SSH 不會要求密碼短語或主機確認。170* 執行器使用 `BatchMode=yes` 執行 SSH，附加到您的 `GIT_SSH_COMMAND`（如果您設定了），因此 SSH 不會要求密碼短語或主機確認。

170* 執行器設定 `GCM_INTERACTIVE=never`，因此 Git Credential Manager 不會打開登入對話框。171* 執行器設定 `GCM_INTERACTIVE=never`，因此 Git Credential Manager 不會打開登入對話框。在 v2.1.229 之前，儲存庫準備可能會卡在 Git Credential Manager 的提示上。

171* 執行器清除 `core.askPass`，因此如果您使用 askpass 幫助程式，請改為通過 `GIT_ASKPASS` 環境變數設定它。172* 執行器清除 `core.askPass`，因此如果您使用 askpass 幫助程式，請改為通過 `GIT_ASKPASS` 環境變數設定它。

172 173 

173如果您的 Git 主機拒絕認證，或您沒有配置認證，執行器會重試幾次，然後失敗儲存庫準備當儲存庫是工作階段推送結果的儲存庫時。對於工作階段僅從中讀取的儲存庫，[Troubleshooting](#troubleshooting) 涵蓋執行器何時改為跳過它。執行器不會將這些設定傳遞到工作階段的環境中。174如果您的 Git 主機拒絕認證，或您沒有配置認證，執行器會重試幾次，然後失敗儲存庫準備當儲存庫是工作階段推送結果的儲存庫時。對於工作階段僅從中讀取的儲存庫，[Troubleshooting](#troubleshooting) 涵蓋執行器何時改為跳過它。執行器不會將這些設定傳遞到工作階段的環境中。

287* **`jq`**：如果您希望 `--jq` 能運作，請在映像中安裝 `jq`288* **`jq`**：如果您希望 `--jq` 能運作，請在映像中安裝 `jq`

288* **[`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](https://code.claude.com/docs/zh-TW/env-vars)**：如果工作階段環境設定了它，Claude Code 不會提供內建的 `gh`，該工作階段就沒有 `gh`289* **[`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](https://code.claude.com/docs/zh-TW/env-vars)**：如果工作階段環境設定了它，Claude Code 不會提供內建的 `gh`，該工作階段就沒有 `gh`

289 290 

290當映像包含 GitHub CLI 時，工作階段會使用它。291#### 使用 GitHub CLI 存取 GitHub API

292 

293如果您的執行器映像包含供工作階段使用的 GitHub CLI，請讓您的[包裝指令碼](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration.md#provision-credentials-scoped-to-the-session-creator)為每個工作階段替工作階段建立者產生短期、最小範圍的 `GH_TOKEN`。當 `gh` 位於 Claude Code 啟動時的 `PATH` 上，工作階段會使用該 `gh`，而不會有[內建的 `gh`](#github-api-access-without-the-github-cli)。有了該 token，該 `gh` 會以 token 授予的任何存取權連線到 GitHub，且不經過 Anthropic 管理的 Git，因此請允許 [`api.github.com`](#network-requirements)。

294 

295使用 Anthropic 管理的 Git 時，請將 GitHub CLI 排除在映像之外，以改用內建的 `gh`。

291 296 

292#### 使用 Anthropic 管理的 Git 信任私有憑證授權單位297#### 使用 Anthropic 管理的 Git 信任私有憑證授權單位

293 298 

343 348 

344主機重寫首先執行，因此如果您需要兩者，請在 `--git-ssh-rewrite` 中列出內部主機名。為了完全控制簽出，使用 [`checkout` 生命週期鉤子](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration#checkout)。349主機重寫首先執行，因此如果您需要兩者，請在 `--git-ssh-rewrite` 中列出內部主機名。為了完全控制簽出，使用 [`checkout` 生命週期鉤子](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration#checkout)。

345 350 

351### 在 GitHub 以外的儲存庫上啟動工作階段

352 

353若要在 GitHub 以外 Git 主機的儲存庫上執行工作階段，請從您的終端機，在該儲存庫的簽出中啟動工作階段。首先請檢查執行器的 Git 憑證、網路和 Git 代理伺服器、儲存庫的位址，以及您的分支：

354 

355* **Git 憑證和網路**：為 `https://<host>/<owner>/<name>`（執行器複製的位址）[提供](#ship-git-config-in-your-image)[無需提示即可運作](#git-must-work-without-a-prompt)的憑證，並讓執行器能夠連線到您的 Git 主機，如[網路需求](#network-requirements)所列。對於僅接受 SSH 的 Git 主機，請參閱 [`--git-ssh-rewrite`](#rewrite-git-urls-for-private-networks)。

356* **Git 代理伺服器**：如果該環境的執行器使用 Anthropic Git 代理伺服器，請[將其關閉](#turn-the-anthropic-git-proxy-off)。

357* **儲存庫位址**：檢查簽出的 `origin` remote。其主機必須是網域名稱，例如 `git.example.com`，且其路徑必須為 `<owner>/<name>` 的形式。巢狀路徑（例如 `group/subgroup/name`）無法通過。

358* **分支**：將您目前所在的分支推送到您的 Git 主機，因為執行器會複製該分支。

359 

360在簽出中，依照[從 CI 進行身分驗證](https://code.claude.com/docs/zh-TW/self-hosted-environments-testing.md#authenticate-from-ci)所述登入 claude.ai 後，使用 [`--environment`](https://code.claude.com/docs/zh-TW/self-hosted-environments-testing#run-the-test-loop) 和您環境的 `ccpool_...` ID 執行 `claude -p`：

361 

362```bash theme={null}

363claude -p "Fix the login bug" --environment ccpool_abc123 --output-format json

364```

365 

366建立工作階段後，命令會列印一行以 `{"ok":true` 開頭的 JSON。如果 `origin` remote 不符合要求，命令會失敗並顯示 `requires a git source, but no GitHub remote was detected`。

367 

368請在您的 Git 主機上審查並合併工作階段所[推送](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration.md#prompt-sessions-to-push-their-work)的分支。

369 

346## 構建執行器映像370## 構建執行器映像

347 371 

348Anthropic 不發佈預構建的執行器映像。在 `claude` 二進位檔案周圍構建您自己的，分層您的儲存庫需要的任何工具鏈：語言執行時、編譯器、套件管理器和 [MCP](https://code.claude.com/docs/zh-TW/mcp.md) 邊車。372Anthropic 不發佈預構建的執行器映像。在 `claude` 二進位檔案周圍構建您自己的，分層您的儲存庫需要的任何工具鏈：語言執行時、編譯器、套件管理器和 [MCP](https://code.claude.com/docs/zh-TW/mcp.md) 邊車。

617 641 

618### 在重新啟動前讓執行中的回合完成642### 在重新啟動前讓執行中的回合完成

619 643 

620若要在滾動重新啟動前讓執行中的回合完成，請設定 `--drain-wait-sec`，並將停止逾時提高至至少該等待時間加 80 秒。在預設等待時間 `0` 下，重新啟動會中斷任何仍在執行的回合，而工作階段會在另一個執行器上恢復，但不包含其[未推送的工作](#additional-limitations)。644若要在滾動重新啟動前讓執行中的回合完成，請設定 `--drain-wait-sec`，並將停止逾時提高至至少該等待時間加 80 秒。在預設等待時間 `0` 下，重新啟動會中斷任何仍在執行的回合，而工作階段會在另一個執行器上恢復，但不包含其[未推送的工作](#resumed-sessions-lose-unpushed-work)。

621 645 

622* **`--drain-wait-sec`**：大約設為您想讓其完成的回合與背景任務所需的時間。這是上限：若它們提前完成，等待就會提早結束。646* **`--drain-wait-sec`**：大約設為您想讓其完成的回合與背景任務所需的時間。這是上限：若它們提前完成，等待就會提早結束。

623* **您的停止逾時**：Kubernetes 中的 `terminationGracePeriodSeconds`、Docker Compose 中的 `stop_grace_period`。例如，使用 `--drain-wait-sec 120` 時，請將 [Kubernetes](#kubernetes) 或 [Docker Compose](#docker-compose) 配方中的 `90` 替換為 `200`。647* **您的停止逾時**：Kubernetes 中的 `terminationGracePeriodSeconds`、Docker Compose 中的 `stop_grace_period`。例如，使用 `--drain-wait-sec 120` 時，請將 [Kubernetes](#kubernetes) 或 [Docker Compose](#docker-compose) 配方中的 `90` 替換為 `200`。

735 759 

736若要釋放閒置工作階段，請使用 [`--release-idle-session-min`](https://code.claude.com/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags) 並搭配以分鐘為單位的該時間來啟動每個執行器，例如 `--release-idle-session-min 30`。執行器隨後會釋放任何閒置達該時間的工作階段，無論是由排程任務還是由人員啟動的，除非您[為其留下仍在執行的程序而保留它](#keep-an-idle-session-while-its-processes-run)。760若要釋放閒置工作階段，請使用 [`--release-idle-session-min`](https://code.claude.com/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags) 並搭配以分鐘為單位的該時間來啟動每個執行器，例如 `--release-idle-session-min 30`。執行器隨後會釋放任何閒置達該時間的工作階段，無論是由排程任務還是由人員啟動的，除非您[為其留下仍在執行的程序而保留它](#keep-an-idle-session-while-its-processes-run)。

737 761 

738* **未推送的工作**：已釋放的工作階段會在其下一則訊息時恢復，但不包含其尚未推送的工作。若要保留其提交，請參閱[恢復的工作階段會遺失未推送的工作](#additional-limitations)。762* **未推送的工作**：已釋放的工作階段會在其下一則訊息時恢復，但不包含其尚未推送的工作。若要保留其提交，請參閱[恢復的工作階段會遺失未推送的工作](#resumed-sessions-lose-unpushed-work)。

739* **執行器結束**：釋放其最後一個工作階段的執行器會開始[正常結束](#when-the-runner-exits)。請讓您的監督程式在全新的檔案系統上重新啟動它，如[強化您的部署](#harden-your-deployment)所述。763* **執行器結束**：釋放其最後一個工作階段的執行器會開始[正常結束](#when-the-runner-exits)。請讓您的監督程式在全新的檔案系統上重新啟動它，如[強化您的部署](#harden-your-deployment)所述。

740* **從不進入閒置狀態的工作階段**：也請設定 [`--kill-session-after-min`](https://code.claude.com/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags)，因為[某些工作階段不被視為閒置](#some-sessions-don’t-count-as-idle)764* **從不進入閒置狀態的工作階段**：也請設定 [`--kill-session-after-min`](https://code.claude.com/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags)，因為[某些工作階段不被視為閒置](#some-sessions-don’t-count-as-idle)

741 765 

811* 如果轉向仍在執行，執行器等待轉向完成，或工作階段下一次等待其使用者，然後釋放它。835* 如果轉向仍在執行，執行器等待轉向完成，或工作階段下一次等待其使用者，然後釋放它。

812* 如果工作階段在寬限窗口結束時仍在執行器上，執行器終止它，任何執行中轉向的工作都會丟失。等待從執行中工具呼叫內部請求的批准的轉向是工作階段超過窗口的一種方式。836* 如果工作階段在寬限窗口結束時仍在執行器上，執行器終止它，任何執行中轉向的工作都會丟失。等待從執行中工具呼叫內部請求的批准的轉向是工作階段超過窗口的一種方式。

813 837 

814釋放的工作階段從新複製恢復，因此它未推送的工作無論如何都消失了；請參閱[恢復的工作階段丟失未推送的工作](#additional-limitations)。在 v2.1.260 之前，執行器在限制處終止每個工作階段，最多等待寬限窗口以完成執行中的轉向。838釋放的工作階段從新複製恢復，因此它未推送的工作無論如何都消失了；請參閱[恢復的工作階段遺失未推送的工作](#resumed-sessions-lose-unpushed-work)。在 v2.1.260 之前，執行器在限制處終止每個工作階段，最多等待寬限窗口以完成執行中的回合。

815 839 

816將該旗標設定為高於您預期的最長工作階段時間，例如 `--kill-session-after-min 480` 為 8 小時。要從進入閒置的對話中釋放插槽，改用 `--release-idle-session-min`。840將該旗標設定為高於您預期的最長工作階段時間，例如 `--kill-session-after-min 480` 為 8 小時。要從進入閒置的對話中釋放插槽，改用 `--release-idle-session-min`。

817 841 

842### 恢復的工作階段遺失未推送的工作

843 

844在新的執行器上恢復的工作階段會遺失其尚未推送的工作，因為該執行器會從其起始分支再次複製儲存庫。

845 

846若要保留已提交的工作，請在環境中的每個執行器上設定 [`--push-outcome-on-release`](https://code.claude.com/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags)。具有此旗標的執行器會在釋放之前盡力推送工作階段的結果分支，恢復的工作階段便會從這些提交開始。沒有此旗標的執行器會從其起始分支恢復工作階段。推送會使用執行器主機本身的 git 憑證，包括在使用 [Anthropic 管理的 git](#use-the-anthropic-git-proxy) 的執行器上。

847 

848> [!WARNING]

849>

850> 設定此旗標之前，請限制誰可以推送到來源遠端上的 `claude/*` refs。在恢復時，執行器會提取先前推送的分支，而不驗證是誰推送的。

851 

852即使已設定此旗標，仍請以其他方式保存以下工作：

853 

854* **未提交的變更**：這些仍會遺失。請參閱[提示工作階段推送其工作](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration.md#prompt-sessions-to-push-their-work)。

855* **透過 [`checkout` 生命週期 hook](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration#checkout) 簽出的儲存庫**：這些不會被推送。請從 [`post-session` hook](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration#post-session) 建立它們的快照。

856* **有人封存或刪除的工作階段中的提交，或有人從工作階段選單釋放其執行器的工作階段中的提交**：不要依賴此旗標的推送。若要保存它們，請從 [`post-session` hook](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration#post-session) 將 `HEAD` 推送到救援分支。該處的範例只會在建立快照提交之後才推送，因此請讓您的版本在沒有任何未提交變更時也進行推送。

857 

818### 其他限制858### 其他限制

819 859 

820* **恢復的工作階段丟失未推送的工作**：新的執行器會從其起始分支再次複製儲存庫，因此工作階段未推送的工作會消失。

821 * **若要保留已提交的工作**：在環境中的每個執行器上設定 [`--push-outcome-on-release`](https://code.claude.com/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags)，因為沒有此旗標的執行器會從其起始分支恢復工作階段。具有此旗標的執行器會在釋放之前盡力推送工作階段的結果分支，恢復的工作階段便會從這些提交開始。推送會使用執行器主機本身的 git 憑證，包括在使用 [Anthropic 管理的 git](#use-the-anthropic-git-proxy) 的執行器上。

822 * **使用 `checkout` hook 時**：透過 [`checkout` 生命週期 hook](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration#checkout) 簽出的儲存庫不會被推送。請改為從 [`post-session` hook](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration#post-session) 建立這些儲存庫的快照。

823 * **啟用旗標之前**：限制誰可以推送到來源遠端上的 `claude/*` refs。在恢復時，執行器會提取先前推送的分支，而不驗證是誰推送的。

824 * **未提交的變更仍會遺失**：若要提示 Claude 在完成回應時提交並推送，請參閱[提示工作階段推送其工作](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration.md#prompt-sessions-to-push-their-work)

825* **因執行器遺失而中斷的命令可能會再次執行**：當工作階段在另一個執行器上恢復時，Claude 會看到被中斷的工具呼叫，其結果表示該呼叫的結果未知。860* **因執行器遺失而中斷的命令可能會再次執行**：當工作階段在另一個執行器上恢復時，Claude 會看到被中斷的工具呼叫，其結果表示該呼叫的結果未知。

826* **工作階段中途新增的儲存庫可能無法複製**：Claude 透過 HTTPS 使用 `git clone` 複製它。在未使用 [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy) 的執行器上，如果主機上沒有任何項目能讀取該儲存庫，複製會因 git 身分驗證錯誤而失敗。在可行的情況下，請在建立工作階段時選擇工作階段需要的每個儲存庫。861* **工作階段中途新增的儲存庫可能無法複製**：Claude 透過 HTTPS 使用 `git clone` 複製它。在未使用 [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy) 的執行器上，如果主機上沒有任何項目能讀取該儲存庫，複製會因 git 身分驗證錯誤而失敗。在可行的情況下，請在建立工作階段時選擇工作階段需要的每個儲存庫。

827 * **工作階段恢復時**：[`checkout` hook](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration#checkout) 也會針對新增的儲存庫執行，且 [`CLAUDE_RUNNER_REPO_REF`](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration#checkout) 為空，因此請讓您的 hook 能處理此情況。862 * **工作階段恢復時**：[`checkout` hook](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration#checkout) 也會針對新增的儲存庫執行，且 [`CLAUDE_RUNNER_REPO_REF`](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration#checkout) 為空，因此請讓您的 hook 能處理此情況。

828* **某些連接器不出現在自託管工作階段中**：您在 claude.ai Settings 中尚未連接的連接器不在自託管工作階段中列出，工作階段不會提示您連接它。首先在 Settings 中連接它，然後啟動新工作階段。將連接器添加到已執行的工作階段也不會使其工具可用於 Claude；啟動新工作階段以拾取新添加的連接器。863* **某些連接器不出現在自託管工作階段中**：您在 claude.ai Settings 中尚未連接的連接器不在自託管工作階段中列出，工作階段不會提示您連接它。首先在 Settings 中連接它，然後啟動新工作階段。將連接器添加到已執行的工作階段也不會使其工具可用於 Claude；啟動新工作階段以拾取新添加的連接器。

829* **當有人封存或刪除工作階段，或從工作階段的選單釋放其執行器時**：不要依賴 [`--push-outcome-on-release`](https://code.claude.com/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags) 的推送。若要在這些情況下保存提交，請從 [`post-session` hook](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration#post-session) 將 `HEAD` 推送到救援分支。如果您以該處的範例為起點，請讓它在沒有任何未提交變更時也進行推送，因為該範例只會在建立快照提交之後才推送。

830 864 

831### 報告問題865### 報告問題

832 866 

64 64 

65**2. 驗證簽名**65**2. 驗證簽名**

66 66 

67取得 JWKS，選擇其 `kid` 與令牌標頭相符的金鑰，並驗證 `ES256` 簽名。拒絕其 `alg` 標頭不是 `ES256` 的令牌。如果令牌到達時帶有您快取的金鑰集中沒有的 `kid`，在拒絕它之前重新取得 JWKS 一次：輪換後，新令牌使用您快取的集合還沒有的金鑰簽署。67取得 JWKS，選擇其 `kid` 與 token 標頭相符的金鑰，並驗證 `ES256` 簽名。拒絕其 `alg` 標頭不是 `ES256` 的 token。如果 token 到達時帶有您快取的金鑰集中沒有的 `kid`，在拒絕它之前重新取得 JWKS 一次：輪換後，新 token 使用您快取的集合還沒有的金鑰簽署。

68 68 

69**3. 驗證簽發者**69**3. 驗證簽發者**

70 70 

71如果 `iss` 不完全是 `ccr`，則拒絕令牌。71如果 `iss` 不完全是 `ccr`，則拒絕 token。

72 72 

73**4. 根據您的環境驗證對象**73**4. 根據您的環境驗證對象**

74 74 

75`aud` 聲明是一個陣列。除非它包含您的環境 ID（形式為 `ccpool_...`），否則拒絕令牌。環境 ID 顯示在[**雲端環境**管理頁面](https://claude.ai/admin-settings/cloud-environments)上您環境的詳細對話框中，並在任何環境的工作階段令牌中顯示為 `ccr:pool_id` 聲明。此檢查是將令牌範圍限制在您的環境並拒絕簽發給其他組織的令牌的內容。75`aud` 聲明是一個陣列。除非它包含您的環境 ID（形式為 `ccpool_...`），否則拒絕 token。環境 ID 顯示在[**雲端環境**管理頁面](https://claude.ai/admin-settings/cloud-environments)上您環境的詳細對話框中，並在任何環境的工作階段 token 中顯示為 `ccr:pool_id` 聲明。此檢查是將 token 範圍限制在您的環境並拒絕簽發給其他組織的 token 的內容。

76 76 

77**5. 驗證角色**77**5. 驗證角色**

78 78 

79如果 `ccr:role` 不完全是 `session_worker`，則拒絕令牌。為自託管環境簽發的其他令牌（例如環境祕密、執行者令牌和工作訂單）由相同的金鑰集簽署，但帶有不同的角色。79如果 `ccr:role` 不完全是 `session_worker`，則拒絕 token。為自託管環境簽發的其他 token（例如環境祕密、執行者 token 和工作訂單）由相同的金鑰集簽署，但帶有不同的角色。

80 80 

81**6. 驗證過期**81**6. 驗證過期**

82 82 

83如果 `exp` 在過去，則拒絕令牌。Anthropic 預設簽發工作階段令牌的生命週期為四小時，最多八小時。執行者在過期前重新整理令牌，並將新值推送到工作階段，因此 Claude 在重新整理後啟動的子程序會繼承它。因此，一個工作階段在其生命週期內可以向您的服務呈現多個不同的有效令牌。83如果 `exp` 在過去，則拒絕 token。Anthropic 預設簽發工作階段 token 的生命週期為四小時，最多八小時。執行者在過期前重新整理 token，並將新值推送到工作階段，因此 Claude 在重新整理後啟動的子程序會繼承它。因此，一個工作階段在其生命週期內可以向您的服務呈現多個不同的有效 token。

84 84 

85**7. 讀取身份**85**7. 讀取身份**

86 86 

87建立使用者的身份在 `act` 聲明中：`act.sub` 是他們的 Anthropic 使用者 ID，採用前綴形式 `user:<id>`，而 `act.email`（當建立表面記錄了一個時）是他們的電子郵件地址。您組織的服務身份建立的工作階段（包括 Claude Tag 頻道工作階段）改為在 `act.sub` 中帶有 `agent:` 主體，因此只有當 `act.sub` 帶有 `user:` 前綴時才將工作階段視為使用者建立的，而不是測試身份聲明是否不存在。請參閱[聲明參考](#claims-reference)以了解完整結構和平面重複聲明。87建立使用者的身份在 `act` 聲明中。`act.sub` 是他們的 Anthropic 使用者 ID，採用前綴形式 `user:<id>`，而 `act.email`（當建立的使用介面記錄了一個時）是他們的電子郵件地址。您組織的服務身份建立的工作階段改為帶有 `agent:` 主體。只有當 `act.sub` 帶有 `user:` 前綴時，才將工作階段視為使用者建立的，而不是測試身份聲明是否不存在。

88 

89請參閱[聲明參考](#claims-reference)以了解完整結構和平面重複聲明。

88 90 

89這些檢查直接對應到標準 JWT 程式庫。下面的範例使用 [`jose`](https://www.npmjs.com/package/jose) 在 Node.js 中實現完整序列，它處理 JWKS 取得、快取和 `kid` 選擇，以及在 Python 中使用 [`PyJWT`](https://pyjwt.readthedocs.io/) 及其內建 JWKS 用戶端。91這些檢查直接對應到標準 JWT 程式庫。下面的範例使用 [`jose`](https://www.npmjs.com/package/jose) 在 Node.js 中實現完整序列，它處理 JWKS 取得、快取和 `kid` 選擇，以及在 Python 中使用 [`PyJWT`](https://pyjwt.readthedocs.io/) 及其內建 JWKS 用戶端。

90 92 

185 187 

186## 聲明參考188## 聲明參考

187 189 

188下表列出了與驗證相關的工作階段令牌聲明。從 `ccr:*` 命名空間和 `act` 鏈讀取身份；平面 `account_email`、`organization_uuid` 和 `account_uuid` 聲明是可能被移除的向後相容性重複項。您組織的服務身份建立的工作階段（包括 Claude Tag 頻道工作階段）在 `act.sub` 中帶有 `agent:` 主體，並省略 `act.email`、`ccr:account_id`、`account_email` 和 `account_uuid`。兩個電子郵件聲明對於使用者建立的工作階段也是可選的：Anthropic 僅在建立請求的認證帶有電子郵件時才在工作階段建立時記錄它們，從 CLI 分派的工作階段可能兩者都缺少，因此根據 `act.sub` 或 `ccr:account_id` 而不是電子郵件來識別身份。令牌也可以帶有超出此表的其他聲明；忽略您不認識的聲明。190從 `ccr:*` 命名空間和 `act` 鏈讀取身份；平面 `account_email`、`organization_uuid` 和 `account_uuid` 聲明是可能被移除的向後相容性重複項。您組織的服務身份建立的工作階段在 `act.sub` 中帶有 `agent:` 主體，並省略 `act.email`、`ccr:account_id`、`account_email` 和 `account_uuid`。

191 

192兩個電子郵件聲明對於使用者建立的工作階段也是可選的。Anthropic 僅在建立請求的憑證帶有電子郵件時才在工作階段建立時記錄它們，從 CLI 分派的工作階段可能兩者都缺少。請根據 `act.sub` 或 `ccr:account_id` 而不是電子郵件來識別身份。Token 也可以帶有超出此表的其他聲明；忽略您不認識的聲明。下表列出了與驗證相關的工作階段 token 聲明。

189 193 

190| 聲明 | 類型 | 描述 |194| 聲明 | 類型 | 描述 |

191| :- | :- | :- |195| :- | :- | :- |

211 215 

212| 路徑 | 描述 |216| 路徑 | 描述 |

213| :- | :- |217| :- | :- |

214| `act.sub` | 建立使用者的 Anthropic 使用者 ID，形式為 `user:<id>`，或當您組織的服務身份建立工作階段時為 `agent:<id>`，就像它對 Claude Tag 頻道工作階段所做的那樣。 |218| `act.sub` | 建立使用者的 Anthropic 使用者 ID，形式為 `user:<id>`，或當您組織的服務身份建立工作階段時為 `agent:<id>`。 |

215| `act.email` | 建立使用者的電子郵件地址，當在工作階段建立時記錄了一個時。不要要求它；根據 `act.sub` 識別。 |219| `act.email` | 建立使用者的電子郵件地址，當在工作階段建立時記錄了一個時。不要要求它；根據 `act.sub` 識別。 |

216| `act.attested_by` | 保留給上游身份提供者對建立使用者的證明。預期此欄位不存在，且不要依賴它。根據 `act.sub` 識別。若您需要地址，請在 `act.email` 存在時讀取它。 |220| `act.attested_by` | 保留給上游身份提供者對建立使用者的證明。預期此欄位不存在，且不要依賴它。根據 `act.sub` 識別。若您需要地址，請在 `act.email` 存在時讀取它。 |

217| `act.act` | 生成工作階段的執行者。`act.act.sub` 是 `ccr:runner:<runner_id>`。 |221| `act.act` | 生成工作階段的執行者。`act.act.sub` 是 `ccr:runner:<runner_id>`。 |

48| `--post-session-hook-timeout-sec <n>` | `SELF_HOSTED_RUNNER_POST_SESSION_HOOK_TIMEOUT_MS` | `60` | [`post-session` 掛鉤](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration#post-session)在每個工作階段結束時的預算，包括執行器關閉 |48| `--post-session-hook-timeout-sec <n>` | `SELF_HOSTED_RUNNER_POST_SESSION_HOOK_TIMEOUT_MS` | `60` | [`post-session` 掛鉤](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration#post-session)在每個工作階段結束時的預算，包括執行器關閉 |

49| `--proxy-authorization-command <command>` | `SELF_HOSTED_RUNNER_PROXY_AUTHORIZATION_COMMAND` | 未設定 | 執行器為每個到您的出口代理的連線執行的 Shell 命令，使用其修剪的 stdout 作為 `Proxy-Authorization` 標頭值。需要 `HTTPS_PROXY` 或 `HTTP_PROXY`，不能與 `--proxy-authorization-file` 結合。請參閱[驗證到出口代理](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#authenticate-to-an-egress-proxy)。需要 Claude Code v2.1.238 或更新版本。 |49| `--proxy-authorization-command <command>` | `SELF_HOSTED_RUNNER_PROXY_AUTHORIZATION_COMMAND` | 未設定 | 執行器為每個到您的出口代理的連線執行的 Shell 命令，使用其修剪的 stdout 作為 `Proxy-Authorization` 標頭值。需要 `HTTPS_PROXY` 或 `HTTP_PROXY`，不能與 `--proxy-authorization-file` 結合。請參閱[驗證到出口代理](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#authenticate-to-an-egress-proxy)。需要 Claude Code v2.1.238 或更新版本。 |

50| `--proxy-authorization-file <path>` | `SELF_HOSTED_RUNNER_PROXY_AUTHORIZATION_FILE` | 未設定 | 執行器為每個到您的出口代理的連線讀取的檔案，使用其修剪的內容作為 `Proxy-Authorization` 標頭值。對於另一個程序就地輪換的權杖，使用此旗標。與 `--proxy-authorization-command` 具有相同的要求，不能與其結合。請參閱[驗證到出口代理](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#authenticate-to-an-egress-proxy)。需要 Claude Code v2.1.238 或更新版本。 |50| `--proxy-authorization-file <path>` | `SELF_HOSTED_RUNNER_PROXY_AUTHORIZATION_FILE` | 未設定 | 執行器為每個到您的出口代理的連線讀取的檔案，使用其修剪的內容作為 `Proxy-Authorization` 標頭值。對於另一個程序就地輪換的權杖，使用此旗標。與 `--proxy-authorization-command` 具有相同的要求，不能與其結合。請參閱[驗證到出口代理](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#authenticate-to-an-egress-proxy)。需要 Claude Code v2.1.238 或更新版本。 |

51| `--push-outcome-on-release` | `SELF_HOSTED_RUNNER_PUSH_OUTCOME_ON_RELEASE` | 關閉 | 在執行器因排空或閒置釋放等原因主動結束工作階段時，在刪除工作區之前將追蹤的結果分支推送到 `origin`，以便進行中的提交在重新啟動後存活。盡力而為；將關閉預算增加 30 秒，並需要 git 2.29 或更新版本以從推送的分支繼續。在啟用之前限制推送存取到 `claude/*` 參考；請參閱[已繼續的工作階段會遺失未推送的工作](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#additional-limitations)。通過 `checkout` 生命週期掛鉤簽出的存放庫不會被推送；改為從 [`post-session` 掛鉤](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration#post-session)快照這些。 |51| `--push-outcome-on-release` | `SELF_HOSTED_RUNNER_PUSH_OUTCOME_ON_RELEASE` | 關閉 | 在執行器因排空或閒置釋放等原因主動結束工作階段時，執行器會在刪除工作區之前，將含有新提交的主要工作階段分支推送到 `origin`。盡力而為；將關閉預算增加 30 秒。需要 git 2.29 或更新版本才能從這些分支繼續。將推送存取限制在 `claude/*` 參考；請參閱[已繼續的工作階段會遺失未推送的工作](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#resumed-sessions-lose-unpushed-work)。`checkout` hook 的儲存庫不會被推送；請從 [`post-session` hook](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration#post-session) 快照這些儲存庫。 |

52| `--release-idle-session-min <n>` | `SELF_HOSTED_RUNNER_SESSION_IDLE_MS` | `0` | 在回合完成或工作階段等待使用者操作後，經過 N 分鐘的不活動即釋放工作階段槽。[某些工作階段不計為閒置](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#some-sessions-don’t-count-as-idle)，因此請與 `--kill-session-after-min` 搭配使用。已完成的背景任務最多會在 [`SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS`](#environment-variable-only-settings) 視窗內讓工作階段保持忙碌。若要延遲釋放，請設定 [`--hold-idle-file`](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy#keep-an-idle-session-while-its-processes-run)。`0` 停用。 |52| `--release-idle-session-min <n>` | `SELF_HOSTED_RUNNER_SESSION_IDLE_MS` | `0` | 在回合完成或工作階段等待使用者操作後，經過 N 分鐘的不活動即釋放工作階段槽。[某些工作階段不計為閒置](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#some-sessions-don’t-count-as-idle)，因此請與 `--kill-session-after-min` 搭配使用。已完成的背景任務最多會在 [`SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS`](#environment-variable-only-settings) 視窗內讓工作階段保持忙碌。若要延遲釋放，請設定 [`--hold-idle-file`](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy#keep-an-idle-session-while-its-processes-run)。`0` 停用。 |

53| `--remove-session-state [bool]` | `SELF_HOSTED_RUNNER_REMOVE_SESSION_STATE` | 關閉 | 當工作階段在此執行器上結束時，移除 `<base-dir>/_sessions/` 下的工作階段的每個工作階段目錄，無論結果如何。[重複使用預先加熱的簽出](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#reuse-a-pre-warmed-checkout)描述它們持有的內容以及當它們保留時誰可以讀取它們。移除是盡力而為：當執行器被終止或在清理執行之前達到其排空期限時，每個工作階段目錄保留在原位。啟用旗標後，失敗或中斷的工作階段的偵錯日誌不會保留在磁碟上。需要 Claude Code v2.1.268 或更新版本。 |53| `--remove-session-state [bool]` | `SELF_HOSTED_RUNNER_REMOVE_SESSION_STATE` | 關閉 | 當工作階段在此執行器上結束時，移除 `<base-dir>/_sessions/` 下的工作階段的每個工作階段目錄，無論結果如何。[重複使用預先加熱的簽出](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#reuse-a-pre-warmed-checkout)描述它們持有的內容以及當它們保留時誰可以讀取它們。移除是盡力而為：當執行器被終止或在清理執行之前達到其排空期限時，每個工作階段目錄保留在原位。啟用旗標後，失敗或中斷的工作階段的偵錯日誌不會保留在磁碟上。需要 Claude Code v2.1.268 或更新版本。 |

54| `--retire-at <epoch-seconds>` | `SELF_HOSTED_RUNNER_RETIRE_AT` | 未設定 | 在絕對 Unix 時間戳記（秒）時退休執行器，用於在已知時間終止執行器的基礎設施；[執行器生命週期](https://code.claude.com/docs/zh-TW/self-hosted-environments#runner-lifecycle)描述釋放序列以及如何調整邊距。2001 年之前或 5138 年之後的值被旗標拒絕，被環境變數忽略。 |54| `--retire-at <epoch-seconds>` | `SELF_HOSTED_RUNNER_RETIRE_AT` | 未設定 | 在絕對 Unix 時間戳記（秒）時退休執行器，用於在已知時間終止執行器的基礎設施；[執行器生命週期](https://code.claude.com/docs/zh-TW/self-hosted-environments#runner-lifecycle)描述釋放序列以及如何調整邊距。2001 年之前或 5138 年之後的值被旗標拒絕，被環境變數忽略。 |

4846 4846 

4847### `disableDeepLinkRegistration`4847### `disableDeepLinkRegistration`

4848 4848 

4849停止 Claude Code 向作業系統註冊 `claude-cli://` 協定處理程式，否則在您傳送互動工作階段的第一個提示後會執行此操作。[深層連結](https://code.claude.com/docs/zh-TW/deep-links.md)讓外部工具使用預先填入的提示開啟 Claude Code 工作階段。在協定處理程式註冊受限或單獨管理的環境中設定此項。4849停止 Claude Code 向作業系統註冊 `claude-cli://` 協定處理程式。[深層連結](https://code.claude.com/docs/zh-TW/deep-links.md)讓外部工具使用預先填入的提示詞開啟 Claude Code 工作階段。在協定處理程式註冊受限或單獨管理的環境中設定此項。

4850 4850 

4851* **範圍**：[`任何檔案`](#scopes)4851* **範圍**：[`任何檔案`](#scopes)

4852* **類型**：字串 `"disable"`4852* **類型**：字串 `"disable"`

5801 5801 

5802啟動每個互動式 CLI 工作階段時，[Chrome 整合](https://code.claude.com/docs/zh-TW/chrome.md)預設開啟，無需每次都傳遞 `--chrome`。如果您執行 [`claude remote-control`](https://code.claude.com/docs/zh-TW/remote-control)，它為您的其中一個[專案](https://code.claude.com/docs/zh-TW/claude-projects.md)執行緒啟動的工作階段也會遵循此金鑰，除了在 `bypassPermissions` 模式中。在 Claude Code v2.1.287 或更新版本中，此金鑰也適用於 [VS Code 擴充功能](https://code.claude.com/docs/zh-TW/vs-code.md#automate-browser-tasks-with-chrome)中的工作階段：請參閱[預設啟用 Chrome](https://code.claude.com/docs/zh-TW/chrome.md#enable-chrome-by-default)。5802啟動每個互動式 CLI 工作階段時，[Chrome 整合](https://code.claude.com/docs/zh-TW/chrome.md)預設開啟，無需每次都傳遞 `--chrome`。如果您執行 [`claude remote-control`](https://code.claude.com/docs/zh-TW/remote-control)，它為您的其中一個[專案](https://code.claude.com/docs/zh-TW/claude-projects.md)執行緒啟動的工作階段也會遵循此金鑰，除了在 `bypassPermissions` 模式中。在 Claude Code v2.1.287 或更新版本中，此金鑰也適用於 [VS Code 擴充功能](https://code.claude.com/docs/zh-TW/vs-code.md#automate-browser-tasks-with-chrome)中的工作階段：請參閱[預設啟用 Chrome](https://code.claude.com/docs/zh-TW/chrome.md#enable-chrome-by-default)。

5803 5803 

5804執行 `/chrome` 並選擇**預設啟用**會為您設定此金鑰。會在 `/config` 中顯示為**預設啟用 Chrome 中的 Claude**。5804執行 `/chrome` 並選擇 **Enabled by default** 會為您設定此設定鍵，回應[「Claude in Chrome extension detected」對話框](https://code.claude.com/docs/zh-TW/chrome.md#answer-the-startup-dialog)也會如此。會在 `/config` 中顯示為 **Claude in Chrome enabled by default**。

5805 5805 

5806* **範圍**：[`全域設定`](#scopes)5806* **範圍**：[`全域設定`](#scopes)

5807* **類型**：布林值5807* **類型**：布林值

39 39 

40**macOS、Linux、WSL：**40**macOS、Linux、WSL：**

41 41 

42```bash theme={null}42```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

43curl -fsSL https://claude.ai/install.sh | bash43curl -fsSL https://claude.ai/install.sh | bash

44```44```

45 45 

47 47 

48**Windows PowerShell：**48**Windows PowerShell：**

49 49 

50```powershell theme={null}50```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

51irm https://claude.ai/install.ps1 | iex51irm https://claude.ai/install.ps1 | iex

52```52```

53 53 

54**Windows CMD：**54**Windows CMD：**

55 55 

56```batch theme={null}56```batch theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

57curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd57curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

58```58```

59 59 

71 71 

72**Homebrew**72**Homebrew**

73 73 

74```bash theme={null}74```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

75brew install --cask claude-code75brew install --cask claude-code

76```76```

77 77 

83 83 

84**WinGet**84**WinGet**

85 85 

86```powershell theme={null}86```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

87winget install Anthropic.ClaudeCode87winget install Anthropic.ClaudeCode

88```88```

89 89 

458 458 

459### 使用 npm 安裝459### 使用 npm 安裝

460 460 

461> [!NOTE]

462>

463> 如果 `npm --version` 在您的 shell 中列印以 `12` 開頭的版本，請改為依照[修正 npm 12 安裝](https://code.claude.com/docs/zh-TW/troubleshoot-install.md#fix-an-npm-12-install)進行操作。請勿使用 `sudo` 安裝。Claude Code 在自我更新時會以不使用 `sudo` 的方式執行 npm，因此需要 `sudo` 的安裝無法自動更新。

464 

461您也可以將 Claude Code 安裝為全域 npm 套件。npm 套件需要 [Node.js 22 或更新版本](https://nodejs.org/en/download)。在較舊的 Node.js 版本上，npm 在安裝期間列印 `EBADENGINE` 警告而不是失敗；安裝完成且 `claude` 仍然執行，因為該套件下載不使用您的 Node.js 的原生二進位檔案。465您也可以將 Claude Code 安裝為全域 npm 套件。npm 套件需要 [Node.js 22 或更新版本](https://nodejs.org/en/download)。在較舊的 Node.js 版本上，npm 在安裝期間列印 `EBADENGINE` 警告而不是失敗；安裝完成且 `claude` 仍然執行，因為該套件下載不使用您的 Node.js 的原生二進位檔案。

462 466 

463```bash theme={null}467```bash theme={null}

404| `allowed-tools` | 否 | Claude 在調用此 skill 的回合中可以使用而無需請求許可的工具。當您發送下一條訊息時，授予清除。接受以空格或逗號分隔的字串或 YAML 列表。請參閱[為 skill 預先批准工具](#pre-approve-tools-for-a-skill)。 |404| `allowed-tools` | 否 | Claude 在調用此 skill 的回合中可以使用而無需請求許可的工具。當您發送下一條訊息時，授予清除。接受以空格或逗號分隔的字串或 YAML 列表。請參閱[為 skill 預先批准工具](#pre-approve-tools-for-a-skill)。 |

405| `disallowed-tools` | 否 | 此 skill 處於活動狀態時從 Claude 的可用工具池中移除的工具。用於不應呼叫某些工具的自主 skills，例如背景迴圈的 `AskUserQuestion`。接受以空格或逗號分隔的字串或 YAML 列表。當您發送下一條訊息時，限制清除。與拒絕規則一樣，當任何其他工具保持時，該欄位無法移除[`EndConversation`](https://code.claude.com/docs/zh-TW/tools-reference#endconversation-tool-behavior)。 |405| `disallowed-tools` | 否 | 此 skill 處於活動狀態時從 Claude 的可用工具池中移除的工具。用於不應呼叫某些工具的自主 skills，例如背景迴圈的 `AskUserQuestion`。接受以空格或逗號分隔的字串或 YAML 列表。當您發送下一條訊息時，限制清除。與拒絕規則一樣，當任何其他工具保持時，該欄位無法移除[`EndConversation`](https://code.claude.com/docs/zh-TW/tools-reference#endconversation-tool-behavior)。 |

406| `model` | 否 | 此 skill 處於活動狀態時要使用的模型。覆蓋適用於目前回合的其餘部分，不會保存到設定。當您發送下一個提示時，工作階段模型恢復。接受與[`/model`](https://code.claude.com/docs/zh-TW/model-config)相同的值，或 `inherit` 以保持活動模型。您組織的[`availableModels`](https://code.claude.com/docs/zh-TW/model-config#restrict-model-selection)允許清單排除的值不被使用，工作階段保持其目前模型。在[自動模式](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode)中，以及在[計畫模式中，當分類器檢查命令時](https://code.claude.com/docs/zh-TW/permission-modes.md#analyze-before-you-edit-with-plan-mode)，自動模式不支援的模型也不被使用，工作階段保持其目前模型。使用 `context: fork` 時，該值設定[分叉子代理的模型](#run-skills-in-a-subagent)，排除的值遵循[與子代理模型覆蓋相同的規則](https://code.claude.com/docs/zh-TW/model-config.md#restrict-model-selection)。 |406| `model` | 否 | 此 skill 處於活動狀態時要使用的模型。覆蓋適用於目前回合的其餘部分，不會保存到設定。當您發送下一個提示時，工作階段模型恢復。接受與[`/model`](https://code.claude.com/docs/zh-TW/model-config)相同的值，或 `inherit` 以保持活動模型。您組織的[`availableModels`](https://code.claude.com/docs/zh-TW/model-config#restrict-model-selection)允許清單排除的值不被使用，工作階段保持其目前模型。在[自動模式](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode)中，以及在[計畫模式中，當分類器檢查命令時](https://code.claude.com/docs/zh-TW/permission-modes.md#analyze-before-you-edit-with-plan-mode)，自動模式不支援的模型也不被使用，工作階段保持其目前模型。使用 `context: fork` 時，該值設定[分叉子代理的模型](#run-skills-in-a-subagent)，排除的值遵循[與子代理模型覆蓋相同的規則](https://code.claude.com/docs/zh-TW/model-config.md#restrict-model-selection)。 |

407| `effort` | 否 | 此 skill 處於活動狀態時的[effort 等級](https://code.claude.com/docs/zh-TW/model-config.md#adjust-effort-level)。覆寫工作階段 effort 等級。省略時，等級依[effort 解析順序](https://code.claude.com/docs/zh-TW/model-config.md#adjust-effort-level)決定。選項：`low`、`medium`、`high`、`xhigh`、`max`；可用等級取決於模型。 |407| `effort` | 否 | 目前回合其餘部分的[effort 等級](https://code.claude.com/docs/zh-TW/model-config.md#adjust-effort-level)。覆寫工作階段 effort 等級，但不覆寫 [`CLAUDE_CODE_EFFORT_LEVEL`](https://code.claude.com/docs/zh-TW/env-vars#variables) 環境變數。使用 `context: fork` 時，該值改為設定分叉 subagent 的 effort 等級。省略時，等級依[effort 解析順序](https://code.claude.com/docs/zh-TW/model-config.md#adjust-effort-level)決定。選項：`low`、`medium`、`high`、`xhigh`、`max`；可用等級取決於模型。 |

408| `context` | 否 | 設定為 `fork` 以在分叉子代理上下文中運行。請參閱[在子代理中運行 skills](#run-skills-in-a-subagent)。 |408| `context` | 否 | 設定為 `fork` 以在分叉子代理上下文中運行。請參閱[在子代理中運行 skills](#run-skills-in-a-subagent)。 |

409| `agent` | 否 | 設定 `context: fork` 時要使用的子代理類型。 |409| `agent` | 否 | 設定 `context: fork` 時要使用的子代理類型。 |

410| `background` | 否 | 僅適用於 `context: fork`。設定為 `false` 以在調用 skill 的回合中等待分叉 subagent 的結果，而不是[在背景中運行它](#run-skills-in-a-subagent)。預設值：`true`。 |410| `background` | 否 | 僅適用於 `context: fork`。設定為 `false` 以在調用 skill 的回合中等待分叉 subagent 的結果，而不是[在背景中運行它](#run-skills-in-a-subagent)。預設值：`true`。 |

200 200 

201### 來自 Claude Tag 頻道的工作階段無法啟動201### 來自 Claude Tag 頻道的工作階段無法啟動

202 202 

203此項目適用於使用 [Claude Tag](https://claude.com/docs/claude-tag/overview) 的工作區，其中 Claude 在頻道中以您組織的共享身分工作，而不是以任何成員的帳戶工作。如果您在 [claude.ai/code](https://claude.ai/code) 建立了頻道的雲端環境，它屬於您的個人帳戶，Claude 無法在個人環境中啟動頻道工作階段。Claude Code 會立即使工作階段失敗，重試也無法幫助。203此項目適用於使用 [Claude Tag](https://claude.com/docs/claude-tag/overview) 的工作區。如果您在 [claude.ai/code](https://claude.ai/code) 建立了頻道的雲端環境，它屬於您的個人帳戶，Claude 無法在個人環境中啟動頻道工作階段。Claude Code 會立即使工作階段失敗，重試也無法幫助。

204 204 

205如果您是擁有者且環境是您自己的，請從環境選擇器[與組織共享](https://code.claude.com/docs/zh-TW/cloud-environments.md#organization-shared-environments)。否則，擁有者應從[管理設定](https://claude.ai/admin-settings)中的**雲端環境**頁面將其重新建立為組織共享環境。205如果您是擁有者且環境是您自己的，請從環境選擇器[與組織共享](https://code.claude.com/docs/zh-TW/cloud-environments.md#organization-shared-environments)。否則，擁有者應從[管理設定](https://claude.ai/admin-settings)中的**雲端環境**頁面將其重新建立為組織共享環境。

206 206 

188| `context_window.current_usage` | 上一次 API 呼叫的 token 數量，說明請見 [上下文視窗欄位](#context-window-fields) |188| `context_window.current_usage` | 上一次 API 呼叫的 token 數量，說明請見 [上下文視窗欄位](#context-window-fields) |

189| `exceeds_200k_tokens` | 最近一次 API 回應的 token 總數（輸入、快取與輸出 token 的總和）是否超過 200k。這是固定的門檻值，與實際上下文視窗大小無關。 |189| `exceeds_200k_tokens` | 最近一次 API 回應的 token 總數（輸入、快取與輸出 token 的總和）是否超過 200k。這是固定的門檻值，與實際上下文視窗大小無關。 |

190| `fast_mode` | 工作階段是否啟用了 [快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md) |190| `fast_mode` | 工作階段是否啟用了 [快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md) |

191| `effort.level` | 目前的推理投入程度（`low`、`medium`、`high`、`xhigh` 或 `max`）。反映工作階段的即時值，包括工作階段中途透過 `/effort` 所做的變更。當目前模型不支援 effort 參數時不存在 |191| `effort.level` | 為工作階段設定的推理 effort 等級（`low`、`medium`、`high`、`xhigh` 或 `max`），而非由 skill、subagent 或 `ultrathink` 設定的等級。若您設定了模型不支援的等級，此處會顯示 Claude Code 實際改用執行的等級。您變更的等級即使在[開始生效](https://code.claude.com/docs/zh-TW/model-config.md#when-a-new-effort-level-starts)之前也會顯示於此。若在 `CLAUDE_CODE_EFFORT_LEVEL` 中設定了等級，此處會顯示該等級。當目前模型不支援 effort 參數時不存在 |

192| `thinking.enabled` | 工作階段是否啟用了延伸思考 |192| `thinking.enabled` | 工作階段是否啟用了延伸思考 |

193| `rate_limits.five_hour.used_percentage`, `rate_limits.seven_day.used_percentage` | 5 小時或 7 天速率限制的已使用百分比，範圍為 0 到 100 |193| `rate_limits.five_hour.used_percentage`, `rate_limits.seven_day.used_percentage` | 5 小時或 7 天速率限制的已使用百分比，範圍為 0 到 100 |

194| `rate_limits.five_hour.resets_at`, `rate_limits.seven_day.resets_at` | 5 小時或 7 天速率限制視窗重設時的 Unix epoch 秒數 |194| `rate_limits.five_hour.resets_at`, `rate_limits.seven_day.resets_at` | 5 小時或 7 天速率限制視窗重設時的 Unix epoch 秒數 |

72 72 

73當 Claude 完成任務或暫停以等待權限提示，且您似乎不在終端機前時，它會觸發通知事件。請參閱[各通知類型何時觸發](https://code.claude.com/docs/zh-TW/hooks.md#notification)以了解確切的時機。將此顯示為終端機鈴聲或桌面通知可讓您在長時間任務執行時切換到其他工作。73當 Claude 完成任務或暫停以等待權限提示，且您似乎不在終端機前時，它會觸發通知事件。請參閱[各通知類型何時觸發](https://code.claude.com/docs/zh-TW/hooks.md#notification)以了解確切的時機。將此顯示為終端機鈴聲或桌面通知可讓您在長時間任務執行時切換到其他工作。

74 74 

75根據預設，Claude Code 僅在 Ghostty、Kitty 和 iTerm2 中傳送桌面通知。在其他終端機中，將 [`preferredNotifChannel`](https://code.claude.com/docs/zh-TW/settings-reference#preferrednotifchannel) 設定為 `"terminal_bell"` 以改為響起終端機鈴聲，或設定[通知 hook](#play-a-sound-with-a-notification-hook) 以取得自訂音效或命令。下列設定項目會開啟終端機鈴聲：75根據預設，Claude Code 在某些終端機中會傳送桌面通知，在其他終端機中則會傳送鈴聲字元或不傳送任何內容：

76 

77* **Ghostty、Kitty 和 iTerm2**：桌面通知，其中 iTerm2 僅在您開啟其警示設定後才會顯示。

78* **Apple Terminal**：沒有聲音；當 Claude Code 發現最前方 Terminal 視窗的描述檔中「Audible bell」為關閉時，會傳送靜音鈴聲字元，否則不傳送任何內容。如果該描述檔的「Visual bell」或 Dock 彈跳選項為開啟，該鈴聲字元會顯示為視窗閃爍，或在 Terminal 位於背景時顯示為 Dock 彈跳。

79* **其他終端機**：不傳送任何內容。

80 

81若要讓 Claude Code 無論終端機或描述檔為何都傳送鈴聲字元，請將 [`preferredNotifChannel`](https://code.claude.com/docs/zh-TW/settings-reference#preferrednotifchannel) 設定為 `"terminal_bell"`。在 Apple Terminal 中，還需在 **Settings > Profiles > Advanced** 下開啟 **Audible bell** 才能聽到它。下列設定項目會設定此頻道：

76 82 

77```json ~/.claude/settings.json theme={null}83```json ~/.claude/settings.json theme={null}

78{84{

995 995 

996### WSL 中的 npm 安裝錯誤996### WSL 中的 npm 安裝錯誤

997 997 

998如果您在 WSL 內使用 `npm install -g` 安裝了 Claude Code，這些問題適用。如果您使用了[原生安裝程式](https://code.claude.com/docs/zh-TW/setup.md)，請跳過此部分。998如果您在 WSL 內使用 `npm install -g` 安裝了 Claude Code，這些問題適用。如果您使用了[原生安裝程式](https://code.claude.com/docs/zh-TW/setup.md)，請跳過此部分。在 npm 12 上，請依照[修正 npm 12 安裝](#fix-an-npm-12-install)中的說明進行安裝。

999 999 

1000**OS 或平台偵測問題。** 如果 npm 在安裝期間報告平台不相符，WSL 可能正在使用 Windows `npm`。首先執行 `npm config set os linux`，然後使用 `npm install -g @anthropic-ai/claude-code --force` 安裝。不要使用 `sudo`。1000**OS 或平台偵測問題。** 如果 npm 在安裝期間報告平台不相符，WSL 可能正在使用 Windows `npm`。首先執行 `npm config set os linux`，然後使用 `npm install -g @anthropic-ai/claude-code --force` 安裝。不要使用 `sudo`。

1001 1001 

1037 1037 

1038### npm 安裝後找不到原生二進位檔1038### npm 安裝後找不到原生二進位檔

1039 1039 

1040`@anthropic-ai/claude-code` npm 套件以每個平台的可選相依性（如 `@anthropic-ai/claude-code-darwin-arm64`）下載原生二進位檔。npm 然後執行套件的 postinstall 指令碼，該指令碼將該二進位檔複製到位置作為 `claude` 命令；在它執行之前，`claude` 是佔位符指令碼。如果下載或 postinstall 步驟被跳過，佔位符保留在位置，在 macOS 和 Linux 上執行 `claude` 列印：1040`@anthropic-ai/claude-code` npm 套件以每個平台的可選相依性（如 `@anthropic-ai/claude-code-darwin-arm64`）下載原生二進位檔。在 `@anthropic-ai/claude-code` 套件的 postinstall 步驟執行並以該二進位檔取代佔位符之前，`claude` 是佔位符指令碼。如果下載或 postinstall 步驟被跳過，佔位符保留在位置，在 macOS 和 Linux 上執行 `claude` 列印：

1041 1041 

1042```text theme={null}1042```text theme={null}

1043Error: claude native binary not installed.1043Error: claude native binary not installed.

1056 1056 

1057檢查以下原因：1057檢查以下原因：

1058 1058 

1059* **npm 12 預設會跳過 postinstall 步驟。** 當您使用 npm 12 安裝或更新 Claude Code 時，npm 仍會完成安裝，但不會執行該步驟。請參閱[修正 npm 12 安裝](#fix-an-npm-12-install)。

1059* **可選相依性已停用。** 從您的 npm 安裝命令中移除 `--omit=optional`、從 pnpm 移除 `--no-optional` 或從 yarn 移除 `--ignore-optional`，並檢查 `.npmrc` 是否未設定 `optional=false`。然後重新安裝。原生二進位檔僅作為可選相依性提供，因此如果跳過它，沒有 JavaScript 備援，重新執行 `install.cjs` 無法放置從未下載的二進位檔。1060* **可選相依性已停用。** 從您的 npm 安裝命令中移除 `--omit=optional`、從 pnpm 移除 `--no-optional` 或從 yarn 移除 `--ignore-optional`，並檢查 `.npmrc` 是否未設定 `optional=false`。然後重新安裝。原生二進位檔僅作為可選相依性提供，因此如果跳過它，沒有 JavaScript 備援，重新執行 `install.cjs` 無法放置從未下載的二進位檔。

1060* **安裝指令碼已停用。** `--ignore-scripts` 和某些 pnpm 設定跳過 postinstall 步驟，但仍然下載平台套件。執行 `node node_modules/@anthropic-ai/claude-code/install.cjs`，如訊息所建議，或不使用旗標重新安裝。如果 postinstall 根本無法在您的環境中執行，`node node_modules/@anthropic-ai/claude-code/cli-wrapper.cjs` 找到下載的套件並啟動它，代價是每次啟動時額外的 Node 程序。如果包裝器改為列印 `Could not find native binary package`，平台套件從未下載，因此首先修復上面的可選相依性原因。1061* **安裝指令碼已停用。** `--ignore-scripts` 和某些 pnpm 設定跳過 postinstall 步驟，但仍然下載平台套件。執行 `node node_modules/@anthropic-ai/claude-code/install.cjs`，如訊息所建議，或不使用旗標重新安裝。如果 postinstall 根本無法在您的環境中執行，`node node_modules/@anthropic-ai/claude-code/cli-wrapper.cjs` 找到下載的套件並啟動它，代價是每次啟動時額外的 Node 程序。如果包裝器改為列印 `Could not find native binary package`，平台套件從未下載，因此首先修復上面的可選相依性原因。

1061* **不支援的平台。** 預建二進位檔針對 `darwin-arm64`、`darwin-x64`、`linux-x64`、`linux-arm64`、`linux-x64-musl`、`linux-arm64-musl`、`win32-x64` 和 `win32-arm64` 發佈。Claude Code 不為其他平台提供二進位檔；請參閱[系統需求](https://code.claude.com/docs/zh-TW/setup.md#system-requirements)。在 FreeBSD 上，安裝程式報告平台為不支援。在 v2.1.205 之前，它將 FreeBSD 視為 Linux 並下載了無法執行的二進位檔。1062* **不支援的平台。** 預建二進位檔針對 `darwin-arm64`、`darwin-x64`、`linux-x64`、`linux-arm64`、`linux-x64-musl`、`linux-arm64-musl`、`win32-x64` 和 `win32-arm64` 發佈。Claude Code 不為其他平台提供二進位檔；請參閱[系統需求](https://code.claude.com/docs/zh-TW/setup.md#system-requirements)。在 FreeBSD 上，安裝程式報告平台為不支援。在 v2.1.205 之前，它將 FreeBSD 視為 Linux 並下載了無法執行的二進位檔。

1062* **公司 npm 鏡像缺少平台套件。** 確保您的登錄鏡像除了元套件外，還鏡像所有八個 `@anthropic-ai/claude-code-*` 平台套件。1063* **公司 npm 鏡像缺少平台套件。** 確保您的登錄鏡像除了元套件外，還鏡像所有八個 `@anthropic-ai/claude-code-*` 平台套件。

1063 1064 

1065#### 修正 npm 12 安裝

1066 

1067如果 `claude` 在 npm 安裝或更新後列印 `Error: claude native binary not installed.`，或在 Windows 上 shell 無法執行它，請執行 `npm --version`。以 `12` 開頭的版本表示，除非您的 npm 設定允許，否則 npm 已跳過 Claude Code 的 postinstall 步驟，而該步驟負責將二進位檔放到位置。若為其他任何版本，請檢查[其他原因](#native-binary-not-found-after-npm-install)。

1068 

1069若要修正 npm 12 安裝，請切換到原生安裝程式或允許該步驟：

1070 

1071* **切換到原生安裝程式**：[使用原生安裝程式安裝](https://code.claude.com/docs/zh-TW/setup.md#install-claude-code)，然後[解除安裝 npm 套件](https://code.claude.com/docs/zh-TW/setup.md#uninstall-with-npm)。之後更新不會使用 npm，因此錯誤不會再出現。

1072* **繼續使用 npm**：對於全域 npm 安裝，請將 Claude Code 新增至您使用者 npm 設定中的 `allow-scripts`。之後 npm 會在每次後續的安裝和更新時執行 Claude Code 的安裝指令碼，在 `package.json` 未設定 `allowScripts` 的專案安裝中也會執行。

1073 

1074 對於位於 `~/.claude/local` 的本機安裝，請使用原生安裝程式。如果您的 `package.json` 指令碼會呼叫 `npm install`，而您使用 pnpm 9、pnpm 10、Yarn 1 或其他會將此設定傳遞給它們的工具來執行這些指令碼，也請使用原生安裝程式。在 npm 12.1 及更新版本上，一旦儲存此設定，這些安裝可能會以 `EALLOWSCRIPTS` 失敗。

1075 

1076 1. 如果 `npm --version` 列印 12.0.x，請將 npm 更新到 12.1 或更新版本，例如使用 `npm install -g npm@latest`。在 12.0.x 上，一旦儲存此設定，由 `npx` 工具或 `npm run` 指令碼啟動的專案安裝可能會以 `EALLOWSCRIPTS` 失敗。

1077 

1078 2. 執行 `npm config get allow-scripts` 並記下它列出的任何套件，因為下一個命令會取代整個值。儲存設定時將這些套件放在引號內，例如 `"allow-scripts=@anthropic-ai/claude-code,<package>"`：

1079 

1080 ```bash theme={null}

1081 npm config set "allow-scripts=@anthropic-ai/claude-code" --location=user

1082 ```

1083 

1084 3. 重新安裝：

1085 

1086 ```bash theme={null}

1087 npm install -g @anthropic-ai/claude-code

1088 ```

1089 

1090 如果此步驟或步驟 1 以 `EACCES` 失敗，請切換到原生安裝程式，而不是使用 `sudo` 重新執行。Claude Code 自行更新時會在不使用 `sudo` 的情況下執行 npm，因此自動更新也會以相同方式失敗。

1091 

1092 4. 如果 `claude --version` 未列印版本號，請檢查[其他原因](#native-binary-not-found-after-npm-install)。

1093 

1094 若要復原，請重新設定不含 `@anthropic-ai/claude-code` 的清單，或使用 `npm config delete allow-scripts --location=user` 移除整個清單。在 npm 12 上，錯誤會在您下次更新後再次出現。

1095 

1064### npm `ENOTEMPTY` 錯誤在更新或重新安裝期間1096### npm `ENOTEMPTY` 錯誤在更新或重新安裝期間

1065 1097 

1066當您在現有安裝上執行 `npm install -g @anthropic-ai/claude-code` 時，npm 在移動舊套件目錄時可能失敗：1098當您在現有安裝上執行 `npm install -g @anthropic-ai/claude-code` 時，npm 在移動舊套件目錄時可能失敗：

1094Remove-Item -Recurse -Force "$(npm root -g)/@anthropic-ai/claude-code", "$(npm root -g)/@anthropic-ai/.claude-code-*"1126Remove-Item -Recurse -Force "$(npm root -g)/@anthropic-ai/claude-code", "$(npm root -g)/@anthropic-ai/.claude-code-*"

1095```1127```

1096 1128 

1097然後重新安裝：1129然後重新安裝。在 npm 12 上，請遵循[修正 npm 12 安裝](#fix-an-npm-12-install)。否則，請執行：

1098 1130 

1099```bash theme={null}1131```bash theme={null}

1100npm install -g @anthropic-ai/claude-code1132npm install -g @anthropic-ai/claude-code

133 133 

134## 追蹤執行中的審查134## 追蹤執行中的審查

135 135 

136審查通常需要 15 到 25 分鐘。審查作為背景任務執行，因此您可以繼續在工作階段中工作或啟動其他命令。如果您選擇[將發現結果發佈到 pull request](#post-findings-to-the-pull-request)，請保持工作階段開啟，直到審查完成；如果工作階段先結束，Claude Code 將不會發佈任何內容。136審查通常需要 5 到 15 分鐘。審查作為背景任務執行，因此您可以繼續在工作階段中工作或啟動其他命令。如果您選擇[將發現結果發佈到 pull request](#post-findings-to-the-pull-request)，請保持工作階段開啟，直到審查完成；如果工作階段先結束，Claude Code 將不會發佈任何內容。

137 137 

138使用 `/tasks` 查看執行中和已完成的審查、開啟審查的詳細檢視，或停止進行中的審查。如果您停止審查，Claude Code 會封存雲端工作階段，且不會返回部分發現。138使用 `/tasks` 查看執行中和已完成的審查、開啟審查的詳細檢視，或停止進行中的審查。如果您停止審查，Claude Code 會封存雲端工作階段，且不會返回部分發現。

139 139 

211| 目標 | 您的工作差異、拉取請求、分支或路徑 | 您的工作差異或拉取請求 |211| 目標 | 您的工作差異、拉取請求、分支或路徑 | 您的工作差異或拉取請求 |

212| 執行位置 | 在您的工作階段中本地執行 | 在雲端沙箱中遠端執行 |212| 執行位置 | 在您的工作階段中本地執行 | 在雲端沙箱中遠端執行 |

213| 深度 | 隨著努力引數調整 | 具有獨立驗證的多代理程式艦隊 |213| 深度 | 隨著努力引數調整 | 具有獨立驗證的多代理程式艦隊 |

214| 持續時間 | 幾秒到幾分鐘 | 大約 15 到 25 分鐘 |214| 持續時間 | 幾秒到幾分鐘 | 大約 5 到 15 分鐘 |

215| 成本 | 計入正常使用量 | 免費執行次數，然後大約 $5 至 $25 每次審查作為使用額度 |215| 成本 | 計入正常使用量 | 免費執行次數，然後大約 $5 至 $25 每次審查作為使用額度 |

216| 最適合 | 迭代時的快速反饋 | 合併前對實質性變更的信心 |216| 最適合 | 迭代時的快速反饋 | 合併前對實質性變更的信心 |

217 217