Documentation — Spybara

admin-setup.md +14 −14

Details

48 48

49受管設定定義組織政策。Claude Code 按優先順序檢查下表中的四個來源。[Claude Code 如何合併受管來源](/docs/zh-TW/managed-settings#precedence-within-the-managed-tier)說明其中哪些適用、政策協助程式變更的內容，以及如何組成每個來源。該表是決策地圖。49受管設定定義組織政策。Claude Code 按優先順序檢查下表中的四個來源。[Claude Code 如何合併受管來源](/docs/zh-TW/managed-settings#precedence-within-the-managed-tier)說明其中哪些適用、政策協助程式變更的內容，以及如何組成每個來源。該表是決策地圖。

50 50

~~51| 機制 | 傳遞 | 優先級 | 平台 |~~51| 機制 | 傳遞 | 優先順序 | 平台 |

52| :- | :- | :- | :- |52| :- | :- | :- | :- |

53| Server-managed | claude.ai 管理員控制台，或用於閘道登入的自託管 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway) | 最高 | 全部 |53| Server-managed | claude.ai 管理員控制台，或用於閘道登入的自託管 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway) | 最高 | 全部 |

54| plist / registry policy | macOS：`com.anthropic.claudecode` plist<br />Windows：`HKLM\SOFTWARE\Policies\ClaudeCode` | 高 | macOS、Windows |54| plist / registry policy | macOS：`com.anthropic.claudecode` plist<br />Windows：`HKLM\SOFTWARE\Policies\ClaudeCode` | 高 | macOS、Windows |

55| File-based managed | macOS：`/Library/Application Support/ClaudeCode/managed-settings.json`<br />Linux 和 WSL：`/etc/claude-code/managed-settings.json`<br />Windows：`C:\Program Files\ClaudeCode\managed-settings.json` | 中 | 全部 |55| File-based managed | macOS：`/Library/Application Support/ClaudeCode/managed-settings.json`<br />Linux 和 WSL：`/etc/claude-code/managed-settings.json`<br />Windows：`C:\Program Files\ClaudeCode\managed-settings.json` | 中 | 全部 |

56| Windows user registry | `HKCU\SOFTWARE\Policies\ClaudeCode` | 最低 | 僅 Windows |56| Windows user registry | `HKCU\SOFTWARE\Policies\ClaudeCode` | 最低 | 僅 Windows |

57 57

58Claude Code 在啟動時擷取 server-managed 設定，並在會話期間每小時重新整理一次，無需部署端點基礎設施。透過 claude.ai 管理員控制台傳遞需要 Claude for Teams 或 Enterprise 計畫。在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上的部署可以透過執行 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway) 獲得相同的遠端傳遞，或改用其中一個基於檔案或作業系統級別的機制。58Claude Code 在啟動時擷取 server-managed 設定，並在工作階段期間每小時重新整理一次，無需部署端點基礎設施。透過 claude.ai 管理員控制台傳遞需要 Claude for Teams 或 Enterprise 計畫。在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上的部署可以透過執行 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway) 獲得相同的遠端傳遞，或改用其中一個基於檔案或作業系統級別的機制。

59 59

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

61 61

62plist 和 HKLM 登錄位置適用於任何提供者，並且由於需要管理員權限才能寫入，因此可以抵抗篡改。Windows 使用者登錄中的 HKCU 無需提升即可寫入，因此將其視為便利預設值而不是執行通道。62plist 和 HKLM 登錄位置適用於任何提供者，並且由於需要管理員權限才能寫入，因此可以抵抗篡改。Windows 使用者登錄中的 HKCU 無需提升即可寫入，因此將其視為便利預設值而不是執行通道。

63 63

66無論您選擇哪種機制，受管值都優先於使用者和專案設定，除了少數安全敏感的[例外](/docs/zh-TW/settings#exceptions-to-managed-settings-precedence)。陣列設定（例如 `permissions.allow` 和 `permissions.deny`）會合併來自所有來源的項目，因此開發人員可以擴展受管清單但無法從中移除。對於 `fallbackModel`、`availableModels` 和 [`modelPicker`](/docs/zh-TW/settings-reference#modelpicker)，受管值會取代較低層級而不是合併。66無論您選擇哪種機制，受管值都優先於使用者和專案設定，除了少數安全敏感的[例外](/docs/zh-TW/settings#exceptions-to-managed-settings-precedence)。陣列設定（例如 `permissions.allow` 和 `permissions.deny`）會合併來自所有來源的項目，因此開發人員可以擴展受管清單但無法從中移除。對於 `fallbackModel`、`availableModels` 和 [`modelPicker`](/docs/zh-TW/settings-reference#modelpicker)，受管值會取代較低層級而不是合併。

67 67

68<h3 id="wsl-sessions-in-claude-code-desktop">68<h3 id="wsl-sessions-in-claude-code-desktop">

~~69 Claude Code Desktop 中的 WSL 會話~~69 Claude Code Desktop 中的 WSL 工作階段

70</h3>70</h3>

71 71

72在 Windows 上，[Claude Code Desktop 可以在 WSL 2 發行版內執行 Code 會話](/docs/zh-TW/desktop-wsl)。會話的 Claude Code 程序在發行版內執行，因此它透過上述 WSL 探索路徑解析受管設定：除非部署了 `wslInheritsWindowsSettings: true`，否則僅限 Windows 的來源無法到達它。72在 Windows 上，[Claude Code Desktop 可以在 WSL 2 發行版內執行 Code 工作階段](/docs/zh-TW/desktop-wsl)。工作階段的 Claude Code 程序在發行版內執行，因此它透過上述 WSL 探索路徑解析受管設定：除非部署了 `wslInheritsWindowsSettings: true`，否則僅限 Windows 的來源無法到達它。

73 73

74Claude Desktop 在偵測到裝置為組織受管的裝置上預設關閉 WSL 會話，例如當 `C:\Program Files\ClaudeCode\managed-settings.json` 存在時。若要開啟它們，請部署 Windows 登錄政策，這需要 Claude Desktop v1.19367.0 或更新版本：74Claude Desktop 在偵測到裝置為組織受管的裝置上預設關閉 WSL 工作階段，例如當 `C:\Program Files\ClaudeCode\managed-settings.json` 存在時。若要開啟它們，請部署 Windows 登錄政策，這需要 Claude Desktop v1.19367.0 或更新版本：

75 75

76* 在 `HKLM\SOFTWARE\Policies\Claude` 下建立名為 `disableWslSessions` 的值，並將其設定為 `REG_SZ` 字串 `false` 或 `REG_DWORD` `0`。此值位於 Claude Desktop 政策金鑰下，與包含受管設定的 `ClaudeCode` 金鑰分開。在 HKLM 下部署該值，這需要管理員權限才能寫入。HKCU 下的值不會啟用 WSL 會話。76* 在 `HKLM\SOFTWARE\Policies\Claude` 下建立名為 `disableWslSessions` 的值，並將其設定為 `REG_SZ` 字串 `false` 或 `REG_DWORD` `0`。此值位於 Claude Desktop 政策金鑰下，與包含受管設定的 `ClaudeCode` 金鑰分開。在 HKLM 下部署該值，這需要管理員權限才能寫入。HKCU 下的值不會啟用 WSL 工作階段。

~~77* 如果您部署 `C:\Program Files\ClaudeCode\managed-settings.json`，請保留它。一旦 HKLM 下的 `disableWslSessions` 為 `false`，Desktop 即使該檔案存在也允許 WSL 會話。~~77* 如果您部署 `C:\Program Files\ClaudeCode\managed-settings.json`，請保留它。一旦 HKLM 下的 `disableWslSessions` 為 `false`，Desktop 即使該檔案存在也允許 WSL 工作階段。

78 78

~~79Desktop 在每次 WSL 會話啟動時讀取政策，因此您無需在部署後重新啟動應用程式。~~79Desktop 在每次 WSL 工作階段啟動時讀取政策，因此您無需在部署後重新啟動應用程式。

80 80

81如果裝置仍然拒絕 WSL 會話，請在該裝置上的 Claude Desktop 中開啟 **Help > Troubleshooting > Show Logs in Explorer**，這會將其日誌資料夾的副本儲存到 Downloads。在該副本中搜尋 `main.log` 以查找 `[wslPolicyGate] denying WSL session`。拒絕的原因在括號中，例如 `(cli-file-present)`。如果 Claude Desktop 是使用 `.exe` 安裝程式安裝的，您也可以在 `%APPDATA%\Claude\logs\main.log` 讀取即時檔案。81如果裝置仍然拒絕 WSL 工作階段，請在該裝置上的 Claude Desktop 中開啟 **Help > Troubleshooting > Show Logs in File Explorer**，這會將其日誌資料夾的副本儲存到 Downloads。在該副本中搜尋 `main.log` 以查找 `[wslPolicyGate] denying WSL session`。拒絕的原因在括號中，例如 `(cli-file-present)`。

82 82

~~83啟用 WSL 會話後，將您的受管設定擴展到它們：~~83啟用 WSL 工作階段後，將您的受管設定擴展到它們：

84 84

~~85* 透過 HKLM 登錄或 `C:\Program Files\ClaudeCode` 檔案部署 `wslInheritsWindowsSettings: true`，以便 WSL 會話繼承與主機會話相同的政策。~~85* 透過 HKLM 登錄或 `C:\Program Files\ClaudeCode` 檔案部署 `wslInheritsWindowsSettings: true`，以便 WSL 工作階段繼承與主機工作階段相同的政策。

86* 透過在 WSL 會話內執行 `/status` 進行驗證，並讀取 `Setting sources` 行。若要解釋它列出的內容，請參閱[在 /status 中讀取來源](/docs/zh-TW/managed-settings#read-the-source-in-/status)。86* 透過在 WSL 工作階段內執行 `/status` 進行驗證，並讀取 `Setting sources` 行。若要解釋它列出的內容，請參閱[在 /status 中讀取來源](/docs/zh-TW/managed-settings#read-the-source-in-/status)。

87 87

88WSL 2 公用程式 VM 內的程序對 Windows 端端點偵測感應器不可見。若要觀察發行版內的程序和檔案活動，請檢查您的端點偵測廠商的 WSL 指南，以取得您可以在發行版內執行的 Linux 感應器及其需要的排除項目。Claude Code 的 [OpenTelemetry 工具執行遙測](/docs/zh-TW/monitoring-usage)對 WSL 和原生會話的發出方式相同。88WSL 2 公用程式 VM 內的程序對 Windows 端端點偵測感應器不可見。若要觀察發行版內的程序和檔案活動，請檢查您的端點偵測廠商的 WSL 指南，以取得您可以在發行版內執行的 Linux 感應器及其需要的排除項目。Claude Code 的 [OpenTelemetry 工具執行遙測](/docs/zh-TW/monitoring-usage)對 WSL 和原生工作階段的發出方式相同。

89 89

90<h2 id="decide-what-to-enforce">90<h2 id="decide-what-to-enforce">

91 決定要執行什麼91 決定要執行什麼

advisor.md +8 −8

Details

87Claude Code 在該工作階段中使用旗標而不是 `advisorModel` 設定。它不會在 `claude --help` 中列出 `--advisor`。如果以下任何情況成立，Claude Code 會在啟動時以錯誤退出：87Claude Code 在該工作階段中使用旗標而不是 `advisorModel` 設定。它不會在 `claude --help` 中列出 `--advisor`。如果以下任何情況成立，Claude Code 會在啟動時以錯誤退出：

88 88

89* 工作階段的主要模型不支援顧問89* 工作階段的主要模型不支援顧問

~~90* 要求的模型（例如 Haiku）無法充當顧問~~90* 要求的模型（例如 Haiku 4.5）無法充當顧問

91* 您組織的 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection) 允許清單排除了要求的模型91* 您組織的 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection) 允許清單排除了要求的模型

92* 您要求了 Fable，而您的帳戶仍需要[用量點數同意](#fable-advisor-and-usage-credits)92* 您要求了 Fable，而您的帳戶仍需要[用量點數同意](#fable-advisor-and-usage-credits)

93 93

103 103

104| 主要模型 | 接受的顧問 |104| 主要模型 | 接受的顧問 |

105| - | - |105| - | - |

106| Haiku 4.5 | Fable、Opus、Sonnet |106| Haiku 4.5 | Fable、Opus、Sonnet、Haiku 5.5 |

107| Sonnet 4.6 | Fable、Opus、Sonnet |107| Sonnet 4.6 | Fable、Opus、Sonnet、Haiku 5.5 |

108| Opus 4.6 | Fable、Opus、Sonnet 5 或更新版本 |108| Opus 4.6 | Fable、Opus、Sonnet 5 或更新版本、Haiku 5.5 |

109| Sonnet 5 | Fable、Opus 4.7 或更新版本、Sonnet 5 或更新版本 |109| Sonnet 5 或 Haiku 5.5 | Fable、Opus 4.7 或更新版本、Sonnet 5 或更新版本、Haiku 5.5 |

110| Opus 4.7 或 Opus 4.8 | Fable、Opus 4.7 或更新版本、Sonnet 5.5 |110| Opus 4.7 或 Opus 4.8 | Fable、Opus 4.7 或更新版本、Sonnet 5.5 |

111| Sonnet 5.5 | Fable、Opus 5 或更新版本、Sonnet 5.5 |111| Sonnet 5.5 | Fable、Opus 5 或更新版本、Sonnet 5.5 |

112| Opus 5 或 Opus 5.5 | Fable、Opus 5 或更新版本 |112| Opus 5 或 Opus 5.5 | Fable、Opus 5 或更新版本 |

113| Fable 5 | Fable 5.1 或 Fable 5 |113| Fable 5 | Fable 5.1 或 Fable 5 |

114| Fable 5.1 | Fable 5.1 |114| Fable 5.1 | Fable 5.1 |

115 115

116Fable 5.1 需要 Claude Code v2.1.257 或更新版本。Fable 模型需要 [Fable 存取權](/docs/zh-TW/model-config#work-with-fable)。以 Sonnet 5.5 作為 Opus 4.7 或 Opus 4.8 主要模型的顧問，需要 Claude Code v2.1.287 或更新版本。116Fable 5.1 需要 Claude Code v2.1.257 或更新版本。Fable 模型需要 [Fable 存取權](/docs/zh-TW/model-config#work-with-fable)。以 Sonnet 5.5 作為 Opus 4.7 或 Opus 4.8 主要模型的顧問，需要 Claude Code v2.1.287 或更新版本。以 Haiku 5.5 作為主要模型或顧問，需要 Claude Code v2.1.293 或更新版本。

117 117

118將顧問設定為 `fable`、`opus` 或 `sonnet`。這些別名會解析為 Claude Code 為每個模型系列[內建的預設版本](/docs/zh-TW/model-config#model-aliases)，會隨著新的 Claude Code 版本發佈而更新。您也可以傳遞完整的模型 ID，例如 `claude-opus-5-5`。Haiku 可以呼叫顧問，但不能充當顧問。118將顧問設定為 `fable`、`opus` 或 `sonnet`。這些別名會解析為 Claude Code 為每個模型系列[內建的預設版本](/docs/zh-TW/model-config#model-aliases)，會隨著新的 Claude Code 版本發佈而更新。您也可以傳遞完整的模型 ID，例如 `claude-opus-5-5` 或 `claude-haiku-5-5`。Haiku 4.5 可以呼叫顧問，但不能充當顧問。

119 119

120子代理繼承已設定的顧問，並針對其自身模型應用相同的配對檢查。120子代理繼承已設定的顧問，並針對其自身模型應用相同的配對檢查。

121 121

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

203 203

204* **僅限 Anthropic API**：顧問是伺服器執行的工具。它在 Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用。透過配置有 `ANTHROPIC_BASE_URL` 的 [LLM 閘道](/docs/zh-TW/llm-gateway)，可用性取決於閘道是否將請求完整轉發到 Anthropic API。如果閘道或其上游無法識別顧問工具，請參閱[自動重試和錯誤轉發](/docs/zh-TW/llm-gateway-protocol#automatic-retry-and-error-forwarding)以了解 Claude Code 如何回應。204* **僅限 Anthropic API**：顧問是伺服器執行的工具。它在 Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用。透過配置有 `ANTHROPIC_BASE_URL` 的 [LLM 閘道](/docs/zh-TW/llm-gateway)，可用性取決於閘道是否將請求完整轉發到 Anthropic API。如果閘道或其上游無法識別顧問工具，請參閱[自動重試和錯誤轉發](/docs/zh-TW/llm-gateway-protocol#automatic-retry-and-error-forwarding)以了解 Claude Code 如何回應。

205* **支援的主要模型**：Fable、Opus 4.6 或更新版本、Sonnet 4.6 或更新版本，或 Haiku 4.5。請參閱[選擇顧問模型](#choose-an-advisor-model)以了解每個顧問接受的模型。205* **支援的主要模型**：Fable、Opus 4.6 或更新版本、Sonnet 4.6 或更新版本、Haiku 4.5，或 Haiku 5.5。請參閱[選擇顧問模型](#choose-an-advisor-model)以了解每個顧問接受的模型。

206* **功能旗標擷取**：Claude Code 透過從 Anthropic 擷取的功能旗標來開啟顧問。在設定了關閉旗標擷取的變數（例如 `DISABLE_TELEMETRY`）的工作階段中，顧問保持關閉。請參閱[需要功能旗標擷取的功能](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)。206* **功能旗標擷取**：Claude Code 透過從 Anthropic 擷取的功能旗標來開啟顧問。在設定了關閉旗標擷取的變數（例如 `DISABLE_TELEMETRY`）的工作階段中，顧問保持關閉。請參閱[需要功能旗標擷取的功能](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)。

207 207

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

agent-sdk/hooks.md +71 −71

Details

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

16 16

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

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

19</h2>19</h2>

20 20

21<Steps>21<Steps>

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

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

24 </Step>24 </Step>

25 25

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

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

28 </Step>28 </Step>

29 29

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

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

32 </Step>32 </Step>

33 33

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

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

36 </Step>36 </Step>

37 37

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

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

40 </Step>40 </Step>

41</Steps>41</Steps>

42 42

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

44 44

45<CodeGroup>45<CodeGroup>

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

54 )54 )

55 55

56 56

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

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

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

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

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

62 62

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

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

65 return {65 return {

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

78 options = ClaudeAgentOptions(78 options = ClaudeAgentOptions(

79 hooks={79 hooks={

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

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

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

83 }83 }

84 )84 )

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

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

99 99

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

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

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

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

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

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

109 109

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

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

112 return {112 return {

113 hookSpecificOutput: {113 hookSpecificOutput: {

127 options: {127 options: {

128 hooks: {128 hooks: {

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

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

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

132 }132 }

133 }133 }

140 ```140 ```

141</CodeGroup>141</CodeGroup>

142 142

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

144 144

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

146 可用的 hooks146 可用的 hooks

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

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

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

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

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

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

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

186 186

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

188 配置 hooks188 設定 hook

189</h2>189</h2>

190 190

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

192 192

193<CodeGroup>193<CodeGroup>

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

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

220 220

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

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

223 223

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

225 匹配器225 Matcher

226</h3>226</h3>

227 227

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

229 229

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

231 231

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

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

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

237 237

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

239 239

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

241 回調函數241 回調函數

245 輸入245 輸入

246</h4>246</h4>

247 247

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

249 249

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

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

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

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

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

255 255

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

257 輸出257 輸出

259 259

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

261 261

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

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

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

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

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

267 267

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

269 269

270<Note>270<Note>

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

272</Note>272</Note>

273 273

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

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

276</h4>276</h4>

277 277

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

279 279

280<CodeGroup>280<CodeGroup>

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

296 296

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

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

301 301

302<Note>302<Note>

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

304</Note>304</Note>

305 305

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

802</h3>802</h3>

803 803

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

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

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

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

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

809 809

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

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

812</h3>812</h3>

813 813

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

815 815

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

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

825```825```

826 826

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

828 Hook 超時828 Hook 逾時

829</h3>829</h3>

830 830

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

832 832

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

834 834

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

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

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

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

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

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

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

842 842

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

844 844

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

846 846

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

848 848

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

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

851</h3>851</h3>

852 852

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

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

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

856 856

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

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

870 };870 };

871 ```871 ```

872 872

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

874 874

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

876 876

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

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

879</h3>879</h3>

880 880

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

882 882

883<CodeGroup>883<CodeGroup>

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

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

898 898

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

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

901</h3>901</h3>

902 902

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

904 904

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

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

907</h3>907</h3>

908 908

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

910 910

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

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

913 913

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

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

916</h3>916</h3>

917 917

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

919 919

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

921 921

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

923 923

agent-sdk/python.md +84 −83

Details

194 `ToolAnnotations`194 `ToolAnnotations`

195</h4>195</h4>

196 196

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

198 198

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

200 200

805| :- | :- | :- |805| :- | :- | :- |

806| `name` | `str` | 工具的唯一識別碼 |806| `name` | `str` | 工具的唯一識別碼 |

807| `description` | `str` | 人類可讀的說明 |807| `description` | `str` | 人類可讀的說明 |

811 811

919| 屬性 | 類型 | 預設值 | 說明 |919| 屬性 | 類型 | 預設值 | 說明 |

920| :- | :- | :- | :- |920| :- | :- | :- | :- |

921| `tools` | `list[str] \| ToolsPreset \| None` | `None` | 工具設定。使用 `{"type": "preset", "preset": "claude_code"}` 以取得 Claude Code 的預設工具 |921| `tools` | `list[str] \| ToolsPreset \| None` | `None` | 工具設定。使用 `{"type": "preset", "preset": "claude_code"}` 以取得 Claude Code 的預設工具 |

922| `allowed_tools` | `list[str]` | `[]` | 無需提示即可自動核准的工具。這不會限制 Claude 只使用這些工具。如果您在此處命名其中一個[任務追蹤工具](/docs/zh-TW/agent-sdk/todo-tracking#model-availability)，Claude Code 也會選擇加入工作階段。其他未列出的工具會進入 `permission_mode` 和 `can_use_tool`。使用 `disallowed_tools` 來封鎖工具。請參閱[權限](/docs/zh-TW/agent-sdk/permissions#allow-and-deny-rules) |922| `allowed_tools` | `list[str]` | `[]` | 無需提示即可自動核准的工具。這不會限制 Claude 只使用這些工具。如果您在此處命名其中一個[任務追蹤工具](/docs/zh-TW/agent-sdk/todo-tracking#model-availability)，Claude Code 也會為工作階段選擇加入。其他未列出的工具會進入 `permission_mode` 和 `can_use_tool`。使用 `disallowed_tools` 來封鎖工具。請參閱[權限](/docs/zh-TW/agent-sdk/permissions#allow-and-deny-rules) |

923| `system_prompt` | `str \| SystemPromptPreset \| SystemPromptCustom \| SystemPromptFile \| None` | `None` | 系統提示設定。傳遞字串以取得自訂提示、`{"type": "preset", "preset": "claude_code"}` 以取得 Claude Code 的系統提示（含選用的 `"append"`）、`{"type": "custom", "prompt": "..."}` 以取得也可以設定 `"snapshot"` 的自訂提示，或 `{"type": "file", "path": "..."}` 以從磁碟載入大型提示。請參閱 [`SystemPromptPreset`](#systempromptpreset)、[`SystemPromptCustom`](#systempromptcustom) 和 [`SystemPromptFile`](#systempromptfile) |923| `system_prompt` | `str \| SystemPromptPreset \| SystemPromptCustom \| SystemPromptFile \| None` | `None` | 系統提示詞設定。傳遞字串以取得自訂提示詞、`{"type": "preset", "preset": "claude_code"}` 以取得 Claude Code 的系統提示詞（含選用的 `"append"`）、`{"type": "custom", "prompt": "..."}` 以取得也可以設定 `"snapshot"` 的自訂提示詞，或 `{"type": "file", "path": "..."}` 以從磁碟載入大型提示詞。請參閱 [`SystemPromptPreset`](#systempromptpreset)、[`SystemPromptCustom`](#systempromptcustom) 和 [`SystemPromptFile`](#systempromptfile) |

924| `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | MCP 伺服器設定或設定檔的路徑 |924| `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | MCP 伺服器設定或設定檔的路徑 |

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

932| `disallowed_tools` | `list[str]` | `[]` | 要拒絕的工具。裸名稱（例如 `"Bash"`）會從 Claude 的內容中移除工具。範圍規則（例如 `"Bash(rm *)"`）會保留工具可用，並在每個權限模式（包括 `bypassPermissions`）中拒絕符合的呼叫，針對[如所寫](/docs/zh-TW/permissions#bash-rule-limits)的命令。請參閱[權限](/docs/zh-TW/agent-sdk/permissions#allow-and-deny-rules) |932| `disallowed_tools` | `list[str]` | `[]` | 要拒絕的工具。裸名稱（例如 `"Bash"`）會從 Claude 的上下文中移除工具。範圍規則（例如 `"Bash(rm *)"`）會保留工具可用，並在每個權限模式（包括 `bypassPermissions`）中拒絕符合的呼叫，針對[如所寫](/docs/zh-TW/permissions#bash-rule-limits)的命令。請參閱[權限](/docs/zh-TW/agent-sdk/permissions#allow-and-deny-rules) |

937| `output_format` | `dict[str, Any] \| None` | `None` | 結構化回應的輸出格式（例如 `{"type": "json_schema", "schema": {...}}`）。請參閱[結構化輸出](/docs/zh-TW/agent-sdk/structured-outputs)以取得詳細資訊 |937| `output_format` | `dict[str, Any] \| None` | `None` | 結構化回應的輸出格式（例如 `{"type": "json_schema", "schema": {...}}`）。請參閱[結構化輸出](/docs/zh-TW/agent-sdk/structured-outputs)以取得詳細資訊 |

939| `cwd` | `str \| Path \| None` | `None` | 目前的工作目錄 |939| `cwd` | `str \| Path \| None` | `None` | 目前的工作目錄 |

943| `env` | `dict[str, str]` | `{}` | 合併在繼承程序環境之上的環境變數。請參閱[環境變數](/docs/zh-TW/env-vars)以取得基礎 CLI 讀取的變數，以及[處理緩慢或停滯的 API 回應](#handle-slow-or-stalled-api-responses)以取得逾時相關變數。設定 `CLAUDE_AGENT_SDK_CLIENT_APP` 以在 User-Agent 標頭中識別您的應用程式 |943| `env` | `dict[str, str]` | `{}` | 合併在繼承程序環境之上的環境變數。請參閱[環境變數](/docs/zh-TW/env-vars)以取得基礎 CLI 讀取的變數，以及[處理緩慢或停滯的 API 回應](#handle-slow-or-stalled-api-responses)以取得逾時相關變數。設定 `CLAUDE_AGENT_SDK_CLIENT_APP` 以在 User-Agent 標頭中識別您的應用程式 |

944| `extra_args` | `dict[str, str \| None]` | `{}` | 要直接傳遞給 CLI 的其他 CLI 引數 |944| `extra_args` | `dict[str, str \| None]` | `{}` | 要直接傳遞給 CLI 的其他 CLI 引數 |

948| `can_use_tool` | [`CanUseTool`](#canusetool) ` \| None` | `None` | 工具權限回呼，僅在[權限流程](/docs/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated)進入提示時叫用。不會針對由 `allowed_tools`、允許規則或 `permission_mode` 自動核准的呼叫叫用。允許規則不會預先核准[任何模式都不自動核准的動作](/docs/zh-TW/permission-modes#actions-no-mode-auto-approves)。請參閱 [`CanUseTool`](#canusetool) 以取得詳細資訊 |948| `can_use_tool` | [`CanUseTool`](#canusetool) ` \| None` | `None` | 工具權限回呼，僅在[權限流程](/docs/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated)進入提示時叫用。不會針對由 `allowed_tools`、允許規則或 `permission_mode` 自動核准的呼叫叫用。允許規則不會預先核准[任何模式都不自動核准的動作](/docs/zh-TW/permission-modes#actions-no-mode-auto-approves)。請參閱 [`CanUseTool`](#canusetool) 以取得詳細資訊 |

953| `forward_subagent_text` | `bool` | `False` | 在訊息串流中轉發子代理文字和思考區塊。沒有此選項，Claude Code 會發出子代理 `tool_use` 和 `tool_result` 區塊，但不會發出文字或思考。需要 Python Agent SDK 0.2.140 或更新版本 |953| `forward_subagent_text` | `bool` | `False` | 在訊息串流中轉發 subagent 文字和思考區塊。沒有此選項時，Claude Code 會省略在[前景](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)執行之 subagent 的文字和思考區塊。關於巢狀 subagent、具有 `context: fork` 的 skill，以及各自所需的 Claude Code 版本，請參閱[追蹤 subagent 訊息](/docs/zh-TW/headless#follow-subagent-messages)。需要 Python Agent SDK 0.2.140 或更新版本 |

954| `verbatim_prompts` | `bool` | `False` | 按照所寫內容傳遞每個提示。SDK 會使用 `client_composed` 設定為 `True` 傳送每個使用者訊息。請參閱 [`client_composed`](/docs/zh-TW/agent-sdk/typescript#sdkusermessage) 以了解 Claude Code 在這些訊息上會跳過的內容。當您的提示文字包含終端使用者未輸入的內容時，請使用此選項。如需按轉控制，請將其關閉，並改為在個別串流訊息上設定 `"client_composed": True`。啟用此選項時，SDK 會覆寫您設定的任何 `client_composed` 值。需要 Python Agent SDK 0.2.158 或更新版本以及 Claude Code v2.1.248 或更新版本；與這些 SDK 版本搭配的 CLI 滿足 Claude Code 需求 |954| `verbatim_prompts` | `bool` | `False` | 按照所寫內容傳遞每個提示詞。SDK 會使用 `client_composed` 設定為 `True` 傳送每個使用者訊息。請參閱 [`client_composed`](/docs/zh-TW/agent-sdk/typescript#sdkusermessage) 以了解 Claude Code 在這些訊息上會跳過的內容。當您的提示詞文字包含終端使用者未輸入的內容時，請使用此選項。如需按回合控制，請將其關閉，並改為在個別串流訊息上設定 `"client_composed": True`。啟用此選項時，SDK 會覆寫您設定的任何 `client_composed` 值。需要 Python Agent SDK 0.2.158 或更新版本以及 Claude Code v2.1.248 或更新版本；與這些 SDK 版本搭配的 CLI 滿足 Claude Code 需求 |

961| `setting_sources` | `list[SettingSource] \| None` | `None`（CLI 預設值：所有來源） | 控制要載入哪些檔案系統設定。傳遞 `[]` 以停用使用者、專案和本機設定。設定 `skills` 且此欄位未設定時，僅載入使用者和專案來源。明確設定 `setting_sources` 以保留本機設定。端點管理的原則無論如何都會載入；當工作階段使用組織認證在[合格設定](/docs/zh-TW/server-managed-settings#platform-availability)上進行驗證時，會擷取伺服器管理的設定。如需無論此選項如何都會讀取的輸入，請參閱[settingSources 不控制的內容](/docs/zh-TW/agent-sdk/claude-code-features#what-settingsources-does-not-control) |961| `setting_sources` | `list[SettingSource] \| None` | `None`（CLI 預設值：所有來源） | 控制要載入哪些檔案系統設定。傳遞 `[]` 以停用使用者、專案和本機設定。設定 `skills` 且此欄位未設定時，僅載入使用者和專案來源。明確設定 `setting_sources` 以保留本機設定。端點管理的原則無論如何都會載入；當工作階段使用組織憑證在[合格組態](/docs/zh-TW/server-managed-settings#platform-availability)上進行驗證時，會擷取伺服器管理的設定。如需無論此選項如何都會讀取的輸入，請參閱[settingSources 不控制的內容](/docs/zh-TW/agent-sdk/claude-code-features#what-settingsources-does-not-control) |

962| `skills` | `list[str] \| Literal["all"] \| None` | `None` | 工作階段可用的技能。傳遞 `"all"` 以啟用每個發現的技能，或傳遞技能名稱清單。僅傳遞確切名稱。SDK 在啟動 Claude Code 程序之前會以 `ValueError` 拒絕格式不正確和萬用字元形式的名稱；此檢查需要 Python Agent SDK 0.2.129 或更新版本。設定時，SDK 會自動將 Skill 工具新增至 `allowed_tools`。如果您也傳遞 `tools`，請在該清單中包含 `"Skill"`。請參閱[技能](/docs/zh-TW/agent-sdk/skills) |962| `skills` | `list[str] \| Literal["all"] \| None` | `None` | 工作階段可用的 skill。傳遞 `"all"` 以啟用每個發現的 skill，或傳遞 skill 名稱清單。僅傳遞確切名稱。SDK 在啟動 Claude Code 程序之前會以 `ValueError` 拒絕格式不正確和萬用字元形式的名稱；此檢查需要 Python Agent SDK 0.2.129 或更新版本。設定時，SDK 會自動將 Skill 工具新增至 `allowed_tools`。如果您也傳遞 `tools`，請在該清單中包含 `"Skill"`。請參閱 [Skill](/docs/zh-TW/agent-sdk/skills) |

968| `load_timeout_ms` | `int` | `60000` | 在繼續具體化期間，`session_store.load()` 和 `list_subkeys()` 的每次呼叫逾時（以毫秒為單位） |968| `load_timeout_ms` | `int` | `60000` | 在繼續具體化期間，`session_store.load()` 和 `list_subkeys()` 的每次呼叫逾時（以毫秒為單位） |

969| `task_budget` | `TaskBudget \| None` | `None` | API 端權杖預算。使用 `task-budgets-2026-03-13` 測試版標頭作為 `output_config.task_budget` 傳送。傳遞 `{"total": <int>}`。 |969| `task_budget` | `TaskBudget \| None` | `None` | API 端 token 預算。使用 `task-budgets-2026-03-13` 測試版標頭作為 `output_config.task_budget` 傳送。傳遞 `{"total": <int>}`。 |

970 970

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

972 處理緩慢或停滯的 API 回應972 處理緩慢或停滯的 API 回應

986)986)

987```987```

988 988

989* `API_TIMEOUT_MS`：Anthropic 用戶端上的每個要求逾時（以毫秒為單位）。預設 `600000`。適用於主迴圈和所有子代理。989* `API_TIMEOUT_MS`：Anthropic 用戶端上的每個請求逾時（以毫秒為單位）。預設 `600000`。適用於主迴圈和所有 subagent。

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

991* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：子代理的停滯監視程式。當串流監視程式開啟時，預設值為 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 加上 5 分鐘，總計 `600000`，除非您提高該變數。關閉串流監視程式時，預設值為 `600000`。在 v2.1.257 之前，預設值始終為 `600000`。991* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：subagent 的停滯監視程式。當串流監視程式開啟時，預設值為 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 加上 5 分鐘，總計 `600000`，除非您提高該變數。關閉串流監視程式時，預設值為 `600000`。在 v2.1.257 之前，預設值始終為 `600000`。

992 992

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

994* `CLAUDE_ENABLE_STREAM_WATCHDOG` 搭配 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`：串流監視程式，當標頭已到達但回應本文停止串流時中止要求。監視程式預設對所有提供者開啟；設定 `CLAUDE_ENABLE_STREAM_WATCHDOG=0` 以停用它。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` 預設為 `300000` 並固定到該最小值。中止後，[自動重試](/docs/zh-TW/errors#automatic-retries)涵蓋 Claude Code 根據回應進度的情況。994* `CLAUDE_ENABLE_STREAM_WATCHDOG` 搭配 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`：串流監視程式，當標頭已到達但回應本文停止串流時中止請求。監視程式預設對所有提供者開啟；設定 `CLAUDE_ENABLE_STREAM_WATCHDOG=0` 以停用它。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` 預設為 `300000` 並固定到該最小值。中止後，[自動重試](/docs/zh-TW/errors#automatic-retries)說明 Claude Code 會根據回應的進度採取什麼行動。

995 995

996 當監視程式等待 `ANTHROPIC_BASE_URL` 後面的閘道保持開啟的回應（帶有保活 ping）時，設定 `include_partial_messages` 的主機會繼續接收 `ping` [`StreamEvent`](#streamevent) 訊息。將這些框架讀取為活躍性，而不是在沉默時逾時工作階段。在 v2.1.257 之前，框架在最後一個真實串流事件後 5 分鐘停止。996 當監視程式等待 `ANTHROPIC_BASE_URL` 後面的閘道以保活 ping 保持開啟的回應時，設定 `include_partial_messages` 的主機會繼續接收 `ping` [`StreamEvent`](#streamevent) 訊息。將這些框架讀取為活躍性，而不是在沉默時讓工作階段逾時。在 v2.1.257 之前，框架在最後一個真實串流事件後 5 分鐘停止。

997 997

998<h3 id="outputformat">998<h3 id="outputformat">

999 `OutputFormat`999 `OutputFormat`

1018 `SystemPromptPreset`1018 `SystemPromptPreset`

1019</h3>1019</h3>

1020 1020

1021使用 Claude Code 的預設系統提示（含選用新增項目）的設定。1021使用 Claude Code 的預設系統提示詞（含選用新增項目）的設定。

1022 1022

1023```python theme={null}1023```python theme={null}

1024class SystemPromptPreset(TypedDict):1024class SystemPromptPreset(TypedDict):

1031 1031

1032| 欄位 | 必要 | 說明 |1032| 欄位 | 必要 | 說明 |

1033| :- | :- | :- |1033| :- | :- | :- |

1034| `type` | 是 | 必須為 `"preset"` 以使用預設系統提示 |1034| `type` | 是 | 必須為 `"preset"` 以使用預設系統提示詞 |

1035| `preset` | 是 | 必須為 `"claude_code"` 以使用 Claude Code 的系統提示 |1035| `preset` | 是 | 必須為 `"claude_code"` 以使用 Claude Code 的系統提示詞 |

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

1037| `exclude_dynamic_sections` | 否 | 將每個工作階段的內容（例如工作目錄、git 儲存庫旗標和自動記憶體路徑）從系統提示移至第一個使用者訊息。改善跨使用者和機器的提示快取重複使用。請參閱[修改系統提示](/docs/zh-TW/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |1037| `exclude_dynamic_sections` | 否 | 將每個使用者的上下文（例如自動記憶位置）從系統提示詞移至第一個使用者訊息。改善跨使用者和機器的提示快取重複使用。請參閱[修改系統提示詞](/docs/zh-TW/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |

1038| `snapshot` | 否 | 設定為 `False` 以在每個要求上重建系統提示，而不是[重複使用工作階段在其第一個要求上記錄的提示](/docs/zh-TW/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session)。需要 `claude-agent-sdk` v0.2.153 或更新版本 |1038| `snapshot` | 否 | 設定為 `False` 以在每個請求上重建系統提示詞，而不是[重複使用工作階段在其第一個請求上記錄的提示詞](/docs/zh-TW/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session)。需要 `claude-agent-sdk` v0.2.153 或更新版本 |

1039 1039

1040<h3 id="systempromptcustom">1040<h3 id="systempromptcustom">

1041 `SystemPromptCustom`1041 `SystemPromptCustom`

1042</h3>1042</h3>

1043 1043

1044物件形式的自訂系統提示，等同於傳遞字串作為 `system_prompt`，也可以設定 `snapshot`。需要 `claude-agent-sdk` v0.2.153 或更新版本。1044物件形式的自訂系統提示詞，等同於傳遞字串作為 `system_prompt`，也可以設定 `snapshot`。需要 `claude-agent-sdk` v0.2.153 或更新版本。

1045 1045

1046```python theme={null}1046```python theme={null}

1047class SystemPromptCustom(TypedDict):1047class SystemPromptCustom(TypedDict):

1053| 欄位 | 必要 | 說明 |1053| 欄位 | 必要 | 說明 |

1054| :- | :- | :- |1054| :- | :- | :- |

1055| `type` | 是 | 必須為 `"custom"` |1055| `type` | 是 | 必須為 `"custom"` |

1056| `prompt` | 是 | 系統提示文字。作為命令列引數傳遞給 CLI，因此[命令列長度限制](#systempromptfile)適用 |1056| `prompt` | 是 | 系統提示詞文字。作為命令列引數傳遞給 CLI，因此[命令列長度限制](#systempromptfile)適用 |

1057| `snapshot` | 否 | 與 [`SystemPromptPreset.snapshot`](#systempromptpreset) 相同，套用至 `prompt` |1057| `snapshot` | 否 | 與 [`SystemPromptPreset.snapshot`](#systempromptpreset) 相同，套用至 `prompt` |

1058 1058

1059<h3 id="systempromptfile">1059<h3 id="systempromptfile">

1060 `SystemPromptFile`1060 `SystemPromptFile`

1061</h3>1061</h3>

1062 1062

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

1064 1064

1065```python theme={null}1065```python theme={null}

1066class SystemPromptFile(TypedDict):1066class SystemPromptFile(TypedDict):

1070 1070

1071| 欄位 | 必要 | 說明 |1071| 欄位 | 必要 | 說明 |

1072| :- | :- | :- |1072| :- | :- | :- |

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

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

1075 1075

1076<h3 id="settingsource">1076<h3 id="settingsource">

1077 `SettingSource`1077 `SettingSource`

1078</h3>1078</h3>

1079 1079

1080控制 SDK 載入設定的檔案系統設定來源。1080控制 SDK 從哪些基於檔案系統的設定來源載入設定。

1081 1081

1082```python theme={null}1082```python theme={null}

1083SettingSource = Literal["user", "project", "local"]1083SettingSource = Literal["user", "project", "local"]

1087| :- | :- | :- |1087| :- | :- | :- |

1091 1091

1092<h4 id="default-behavior">1092<h4 id="default-behavior">

1093 預設行為1093 預設行為

1094</h4>1094</h4>

1095 1095

1096當 `setting_sources` 被省略或為 `None` 且 `skills` 未設定時，`query()` 載入與 Claude Code CLI 相同的檔案系統設定：使用者、專案和本機。設定 `skills` 時，[`setting_sources`](#claudeagentoptions) 列描述目前的預設值。端點管理的原則在所有情況下都會載入；當工作階段使用組織認證在[合格設定](/docs/zh-TW/server-managed-settings#platform-availability)上進行驗證時，會擷取伺服器管理的設定。如需詳細資訊，請參閱[settingSources 不控制的內容](/docs/zh-TW/agent-sdk/claude-code-features#what-settingsources-does-not-control)。1096當 `setting_sources` 被省略或為 `None` 且 `skills` 未設定時，`query()` 載入與 Claude Code CLI 相同的檔案系統設定：使用者、專案和本機。設定 `skills` 時，[`setting_sources`](#claudeagentoptions) 列描述目前的預設值。端點管理的原則在所有情況下都會載入；當工作階段使用組織憑證在[合格組態](/docs/zh-TW/server-managed-settings#platform-availability)上進行驗證時，會擷取伺服器管理的設定。如需詳細資訊，請參閱[settingSources 不控制的內容](/docs/zh-TW/agent-sdk/claude-code-features#what-settingsources-does-not-control)。

1097 1097

1098<h4 id="why-use-setting_sources">1098<h4 id="why-use-setting_sources">

1099 為什麼使用 setting\_sources1099 為什麼使用 setting\_sources

1174asyncio.run(main())1174asyncio.run(main())

1175```1175```

1176 1176

1177若要載入 CLAUDE.md 專案指示，請在 `setting_sources` 中包含 `"project"`。請參閱[修改系統提示](/docs/zh-TW/agent-sdk/modifying-system-prompts#claude-md-files-for-project-level-instructions)以了解 CLAUDE.md 載入如何與系統提示選項互動。1177若要載入 CLAUDE.md 專案指示，請在 `setting_sources` 中包含 `"project"`。請參閱[修改系統提示詞](/docs/zh-TW/agent-sdk/modifying-system-prompts#claude-md-files-for-project-level-instructions)以了解 CLAUDE.md 載入如何與系統提示詞選項互動。

1178 1178

1179<h4 id="settings-precedence">1179<h4 id="settings-precedence">

1180 設定優先順序1180 設定優先順序

1181</h4>1181</h4>

1182 1182

1183載入多個來源時，設定會與此優先順序合併（從高到低）：1183載入多個來源時，設定會依此優先順序合併（從高到低）：

1184 1184

11851. 本機設定（`.claude/settings.local.json`）11851. 本機設定（`.claude/settings.local.json`）

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

1192 `AgentDefinition`1192 `AgentDefinition`

1193</h3>1193</h3>

1194 1194

1195以程式設計方式定義的子代理設定。1195以程式設計方式定義的 subagent 設定。

1196 1196

1197```python theme={null}1197```python theme={null}

1198@dataclass1198@dataclass

1214 1214

1215| 欄位 | 必要 | 說明 |1215| 欄位 | 必要 | 說明 |

1216| :- | :- | :- |1216| :- | :- | :- |

1217| `description` | 是 | 何時使用此代理的自然語言說明 |1217| `description` | 是 | 何時使用此 agent 的自然語言說明 |

1218| `prompt` | 是 | 代理的系統提示 |1218| `prompt` | 是 | agent 的系統提示詞 |

1219| `tools` | 否 | 允許的工具名稱陣列。如果省略，繼承[子代理可用的每個工具](/docs/zh-TW/sub-agents#available-tools) |1219| `tools` | 否 | 允許的工具名稱陣列。如果省略，繼承[subagent 可用的每個工具](/docs/zh-TW/sub-agents#available-tools) |

1220| `disallowedTools` | 否 | 要從代理的工具集中移除的工具名稱陣列。也接受 MCP 伺服器層級的模式：`mcp__server` 或 `mcp__server__*` 移除該伺服器的每個工具，`mcp__*` 移除任何伺服器的每個 MCP 工具 |1220| `disallowedTools` | 否 | 要從 agent 的工具集中移除的工具名稱陣列。也接受 MCP 伺服器層級的模式：`mcp__server` 或 `mcp__server__*` 移除該伺服器的每個工具，`mcp__*` 移除任何伺服器的每個 MCP 工具 |

1221| `model` | 否 | 此代理的模型覆寫。接受別名（例如 `"sonnet"`、`"opus"`、`"haiku"` 或 `"inherit"`）或完整模型 ID。省略時，Claude Code 會在[子代理模型順序](/docs/zh-TW/sub-agents#choose-a-model)中選擇模型 |1221| `model` | 否 | 此 agent 的模型覆寫。接受別名（例如 `"sonnet"`、`"opus"`、`"haiku"` 或 `"inherit"`）或完整模型 ID。省略時，Claude Code 會依[subagent 模型順序](/docs/zh-TW/sub-agents#choose-a-model)選擇模型 |

1222| `skills` | 否 | 技能名稱清單，在啟動時預先載入代理的內容。未列出的技能仍可透過 Skill 工具叫用 |1222| `skills` | 否 | 在啟動時預先載入 agent 上下文的 skill 名稱清單。未列出的 skill 仍可透過 Skill 工具叫用 |

1223| `memory` | 否 | 此代理的記憶來源：`"user"`、`"project"` 或 `"local"` |1223| `memory` | 否 | 此 agent 的記憶來源：`"user"`、`"project"` 或 `"local"` |

1224| `mcpServers` | 否 | 此代理可用的 MCP 伺服器。每個項目是伺服器名稱或內嵌 `{name: config}` 字典 |1224| `mcpServers` | 否 | 此 agent 可用的 MCP 伺服器。每個項目是伺服器名稱或內嵌 `{name: config}` 字典 |

1225| `initialPrompt` | 否 | 當此代理作為主執行緒代理執行時自動提交為第一個使用者轉 |1225| `initialPrompt` | 否 | 當此 agent 作為主執行緒 agent 執行時，自動提交為第一個使用者回合 |

1226| `maxTurns` | 否 | 代理停止前的最大代理轉數 |1226| `maxTurns` | 否 | agent 停止前的最大 agent 回合數 |

1227| `background` | 否 | 叫用時以非封鎖背景工作執行此代理 |1227| `background` | 否 | 叫用時以非封鎖背景任務執行此 agent |

1228| `effort` | 否 | 此代理的推理努力等級。接受命名等級或整數。請參閱 [`EffortLevel`](#effortlevel) |1228| `effort` | 否 | 此 agent 的推理 effort 等級。接受命名等級或整數。請參閱 [`EffortLevel`](#effortlevel) |

1229| `permissionMode` | 否 | 此代理內工具執行的權限模式。[子代理繼承規則](/docs/zh-TW/agent-sdk/permissions#available-modes)決定何時適用。請參閱 [`PermissionMode`](#permissionmode) |1229| `permissionMode` | 否 | 此 agent 內工具執行的權限模式。[subagent 繼承規則](/docs/zh-TW/agent-sdk/permissions#available-modes)決定何時適用。請參閱 [`PermissionMode`](#permissionmode) |

1230 1230

1231<Note>1231<Note>

1232 `AgentDefinition` 欄位名稱使用 camelCase，例如 `disallowedTools`、`permissionMode` 和 `maxTurns`。這些名稱直接對應至與 TypeScript SDK 共用的線路格式。這與 `ClaudeAgentOptions` 不同，後者對等頂層欄位（例如 `disallowed_tools` 和 `permission_mode`）使用 Python snake\_case。因為 `AgentDefinition` 是資料類別，傳遞 snake\_case 關鍵字會在建構時引發 `TypeError`。1232 `AgentDefinition` 欄位名稱使用 camelCase，例如 `disallowedTools`、`permissionMode` 和 `maxTurns`。這些名稱直接對應至與 TypeScript SDK 共用的線路格式。這與 `ClaudeAgentOptions` 不同，後者對等頂層欄位（例如 `disallowed_tools` 和 `permission_mode`）使用 Python snake\_case。因為 `AgentDefinition` 是資料類別，傳遞 snake\_case 關鍵字會在建構時引發 `TypeError`。

1244 "acceptEdits", # 自動接受檔案編輯1244 "acceptEdits", # 自動接受檔案編輯

1245 "plan", # 規劃模式 - 探索而不編輯1245 "plan", # 規劃模式 - 探索而不編輯

1246 "dontAsk", # 拒絕任何未預先核准的內容，而不是提示1246 "dontAsk", # 拒絕任何未預先核准的內容，而不是提示

1247 "bypassPermissions", # 略過權限檢查；明確要求規則仍會提示（謹慎使用）1247 "bypassPermissions", # 略過權限檢查；明確的 ask 規則仍會提示（謹慎使用）

1248 "auto", # 模型分類器核准或拒絕權限提示1248 "auto", # 模型分類器會審查 shell 命令和網路請求等動作

1249]1249]

1250```1250```

1251 1251

1253 `EffortLevel`1253 `EffortLevel`

1254</h3>1254</h3>

1255 1255

1256用於指導思考深度的努力等級。1256用於指導思考深度的 effort 等級。

1257 1257

1258```python theme={null}1258```python theme={null}

1259EffortLevel = Literal[1259EffortLevel = Literal[

1260 "low", # 最少思考，最快回應1260 "low", # 最少思考，最快回應

1261 "medium", # 適度思考1261 "medium", # 適度思考

1262 "high", # 深度推理1262 "high", # 深度推理

1263 "xhigh", # 延伸推理；在不支援的模型上回退到「high」1263 "xhigh", # 延伸推理；在不支援的模型上改用「high」

1264 "max", # 最大努力1264 "max", # 最大 effort

1265]1265]

1266```1266```

1267 1267

1285 1285

1286傳回 `PermissionResult`（`PermissionResultAllow` 或 `PermissionResultDeny`）。1286傳回 `PermissionResult`（`PermissionResultAllow` 或 `PermissionResultDeny`）。

1287 1287

1288回呼是互動式權限提示的 SDK 替代品：僅在[權限評估流程](/docs/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated)解決為提示時叫用。由 `allowed_tools` 項目、設定允許規則或權限模式（例如 `acceptEdits` 或 `bypassPermissions`）預先核准的工具呼叫永遠不會叫用它。若要限制每個工具呼叫，請改用 [`PreToolUse` Hook](/docs/zh-TW/agent-sdk/hooks)。1288回呼是互動式權限提示的 SDK 替代品：僅在[權限評估流程](/docs/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated)解決為提示時叫用。由 `allowed_tools` 項目、設定允許規則或權限模式（例如 `acceptEdits` 或 `bypassPermissions`）預先核准的工具呼叫永遠不會叫用它。若要限制每個工具呼叫，請改用 [`PreToolUse` hook](/docs/zh-TW/agent-sdk/hooks)。

1289 1289

1290允許規則不會預先核准[任何模式都不自動核准的動作](/docs/zh-TW/permission-modes#actions-no-mode-auto-approves)；請參閱[權限如何評估](/docs/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated)以了解其中哪些到達回呼以及在 `dontAsk` 和 `auto` 模式中發生的情況。1290允許規則不會預先核准[任何模式都不自動核准的動作](/docs/zh-TW/permission-modes#actions-no-mode-auto-approves)；請參閱[權限如何評估](/docs/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated)以了解其中哪些到達回呼以及在 `dontAsk` 和 `auto` 模式中發生的情況。

1291 1291

1293 `ToolPermissionContext`1293 `ToolPermissionContext`

1294</h3>1294</h3>

1295 1295

1296傳遞至工具權限回呼的內容資訊。1296傳遞至工具權限回呼的上下文資訊。

1297 1297

1298```python theme={null}1298```python theme={null}

1299@dataclass1299@dataclass

1315| `suggestions` | `list[PermissionUpdate]` | 來自 CLI 的權限更新建議。Bash 提示包含具有 `localSettings` 目的地的建議，因此在 `updated_permissions` 中傳回它會將規則寫入 `.claude/settings.local.json` 並跨工作階段保存。 |1315| `suggestions` | `list[PermissionUpdate]` | 來自 CLI 的權限更新建議。Bash 提示包含具有 `localSettings` 目的地的建議，因此在 `updated_permissions` 中傳回它會將規則寫入 `.claude/settings.local.json` 並跨工作階段保存。 |

1462| 變體 | 欄位 | 說明 |1462| 變體 | 欄位 | 說明 |

1463| :- | :- | :- |1463| :- | :- | :- |

1467 1467

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

1469 1469

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

1471 1471

1485 `TaskBudget`1485 `TaskBudget`

1486</h3>1486</h3>

1487 1487

1488API 端任務預算（以權杖為單位），與 `ClaudeAgentOptions` 中的 `task_budget` 欄位搭配使用。1488API 端任務預算（以 token 為單位），與 `ClaudeAgentOptions` 中的 `task_budget` 欄位搭配使用。

1489 1489

1490```python theme={null}1490```python theme={null}

1491class TaskBudget(TypedDict):1491class TaskBudget(TypedDict):

1494 1494

1495| 欄位 | 類型 | 說明 |1495| 欄位 | 類型 | 說明 |

1496| :- | :- | :- |1496| :- | :- | :- |

1497| `total` | `int` | 任務的總權杖預算 |1497| `total` | `int` | 任務的總 token 預算 |

1498 1498

1499因為這是 `TypedDict`，將其作為純字典傳遞，例如 `ClaudeAgentOptions(task_budget={"total": 50000})`。1499因為這是 `TypedDict`，將其作為純字典傳遞，例如 `ClaudeAgentOptions(task_budget={"total": 50000})`。

1500 1500

1633 `ContextUsageResponse`1633 `ContextUsageResponse`

1634</h3>1634</h3>

1635 1635

1636來自 [`ClaudeSDKClient.get_context_usage()`](#methods) 的回應。這是 Claude Code 為互動式工作階段中的 `/context` 命令呈現的相同承載，因此除了權杖計數外，它還帶有顯示欄位，例如 `color` 和 `gridRows`，Claude Code 使用這些欄位來繪製 `/context` 使用量網格。1636來自 [`ClaudeSDKClient.get_context_usage()`](#methods) 的回應。這是 Claude Code 為互動式工作階段中的 `/context` 命令呈現的相同 payload，因此除了 token 計數外，它還帶有顯示欄位，例如 `color` 和 `gridRows`，Claude Code 使用這些欄位來繪製 `/context` 使用量網格。

1637 1637

1638Claude Code 透過向[權杖計數](https://platform.claude.com/docs/en/build-with-claude/token-counting) API 傳送多個要求來建立此承載。這些要求不會出現在訊息串流中，因此讀取串流的成本追蹤不會看到它們。在 Anthropic API 上，權杖計數不計費。1638Claude Code 透過向 [token 計數](https://platform.claude.com/docs/en/build-with-claude/token-counting) API 傳送多個請求來建立此 payload。這些請求不會出現在訊息串流中，因此讀取串流的成本追蹤不會看到它們。在 Anthropic API 上，token 計數不計費。

1639 1639

1640```python theme={null}1640```python theme={null}

1641class ContextUsageResponse(TypedDict):1641class ContextUsageResponse(TypedDict):

1660 apiUsage: NotRequired[dict[str, Any] | None]1660 apiUsage: NotRequired[dict[str, Any] | None]

1661```1661```

1662 1662

1663每個 `ContextUsageCategory` 項目帶有 `name`、`tokens`、`color` 和選用的 `isDeferred` 旗標。`totalTokens` 是工作階段的目前內容使用量，`maxTokens` 是測量使用量的視窗。該視窗是模型的內容視窗，或當適用時較低的自動壓縮視窗，`rawMaxTokens` 帶有與 `maxTokens` 相同的值。`apiUsage` 保留最新 API 回應的使用量，而不是工作階段的執行總計。Claude Code 保留選用的 `deferredBuiltinTools`、`systemTools` 和 `systemPromptSections` 鍵未設定，因此即使類型宣告它們，也應該預期它們不存在。1663每個 `ContextUsageCategory` 項目帶有 `name`、`tokens`、`color` 和選用的 `isDeferred` 旗標。`totalTokens` 是工作階段目前的上下文使用量，`maxTokens` 是測量該使用量所依據的視窗。該視窗是模型的上下文視窗，或適用時較低的自動壓縮視窗，`rawMaxTokens` 帶有與 `maxTokens` 相同的值。`apiUsage` 保留最新 API 回應的使用量，而不是工作階段的執行總計。Claude Code 會讓選用的 `deferredBuiltinTools`、`systemTools` 和 `systemPromptSections` 鍵保持未設定，因此即使類型宣告了它們，也應該預期它們不存在。

1664 1664

1665<h3 id="sdkpluginconfig">1665<h3 id="sdkpluginconfig">

1666 `SdkPluginConfig`1666 `SdkPluginConfig`

1667</h3>1667</h3>

1668 1668

1669在 SDK 中載入外掛程式的設定。1669在 SDK 中載入外掛的設定。

1670 1670

1671```python theme={null}1671```python theme={null}

1672class SdkPluginConfig(TypedDict):1672class SdkPluginConfig(TypedDict):

1676 1676

1677| 欄位 | 類型 | 說明 |1677| 欄位 | 類型 | 說明 |

1678| :- | :- | :- |1678| :- | :- | :- |

1680| `path` | `str` | 外掛程式目錄的絕對或相對路徑 |1680| `path` | `str` | 外掛目錄的絕對或相對路徑 |

1681 1681

1682**範例：**1682**範例：**

1683 1683

1688]1688]

1689```1689```

1690 1690

1691如需建立和使用外掛程式的完整資訊，請參閱[外掛程式](/docs/zh-TW/agent-sdk/plugins)。1691如需建立和使用外掛的完整資訊，請參閱[外掛](/docs/zh-TW/agent-sdk/plugins)。

1692 1692

1693<h2 id="message-types">1693<h2 id="message-types">

1694 消息類型1694 消息類型

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

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

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

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

1878 1879

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

1880 `StreamEvent`1881 `StreamEvent`

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

2167```2168```

2168 2169

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

2170 2171

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

2172 `CLINotFoundError`2173 `CLINotFoundError`

2216 `ResultError`2217 `ResultError`

2217</h3>2218</h3>

2218 2219

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

2220 2221

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

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

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

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

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

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

2653 2654

2654 2655

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

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

Details

60 60

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

62 62

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

64 64

65<CodeGroup>65<CodeGroup>

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

390 錯誤處理390 錯誤處理

391</h2>391</h2>

392 392

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

394 394

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

396 396

agent-sdk/typescript.md +211 −203

Details

6 6

7> TypeScript Agent SDK 的完整 API 參考，包括所有函數、類型和介面。7> TypeScript Agent SDK 的完整 API 參考，包括所有函數、類型和介面。

8 8

~~9<script src="/docs/components/typescript-sdk-type-links.js" defer />~~

11<h2 id="installation">9<h2 id="installation">

12 安裝10 安裝

13</h2>11</h2>

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

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

173 171

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

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

176 174

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

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

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

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

181});179});

182 180

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

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

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

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

187});185});

188 186

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

188 for await (const message of claimedQuery) {

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

190 }

191} catch (error) {

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

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

191}194}

192```195```

193 196

527```530```

528 531

529<h2 id="types">532<h2 id="types">

530 類型533 型別

531</h2>534</h2>

532 535

533<h3 id="options">536<h3 id="options">

536 539

537`query()` 函式的設定物件。540`query()` 函式的設定物件。

538 541

539| 屬性 | 類型 | 預設值 | 說明 |542| 屬性 | 型別 | 預設值 | 說明 |

540| :- | :- | :- | :- |543| :- | :- | :- | :- |

542| `additionalDirectories` | `string[]` | `[]` | Claude 可存取的其他目錄。SDK 會將每個項目以 `--add-dir` 傳遞給 Claude Code，因此搭配 `project` 設定來源時，Claude Code 也會[載入該目錄的 skill、命令和 subagent](/docs/zh-TW/permissions#additional-directories-grant-file-access-not-configuration) |545| `additionalDirectories` | `string[]` | `[]` | Claude 可以存取的其他目錄。SDK 會將每個項目以 `--add-dir` 傳遞給 Claude Code，因此在使用 `project` 設定來源時，Claude Code 也會[載入該目錄的 skill、命令和 subagent](/docs/zh-TW/permissions#additional-directories-grant-file-access-not-configuration) |

546| `allowDangerouslySkipPermissions` | `boolean` | `false` | 啟用略過權限。使用 `permissionMode: 'bypassPermissions'` 時（無論是在啟動時或稍後透過 `setPermissionMode()`）必須設定。關於它如何與 `permissionMode: 'plan'` 互動，請參閱 [plan mode](/docs/zh-TW/agent-sdk/permissions#plan-mode-plan) |549| `allowDangerouslySkipPermissions` | `boolean` | `false` | 啟用略過權限。使用 `permissionMode: 'bypassPermissions'` 時必須設定，無論是在啟動時或之後透過 `setPermissionMode()` 設定。關於它如何與 `permissionMode: 'plan'` 互動，請參閱 [plan mode](/docs/zh-TW/agent-sdk/permissions#plan-mode-plan) |

547| `allowedTools` | `string[]` | `[]` | 無需提示即自動核准的工具。這不會將 Claude 限制為僅能使用這些工具。如果您在此列出任一[任務追蹤工具](/docs/zh-TW/agent-sdk/todo-tracking#model-availability)，Claude Code 也會讓工作階段啟用該功能。其他未列出的工具則交由 `permissionMode` 和 `canUseTool` 處理。請使用 `disallowedTools` 來封鎖工具。請參閱[權限](/docs/zh-TW/agent-sdk/permissions#allow-and-deny-rules) |550| `allowedTools` | `string[]` | `[]` | 無需提示即自動核准的工具。這不會將 Claude 限制為只能使用這些工具。如果您在此處指定其中一個[任務追蹤工具](/docs/zh-TW/agent-sdk/todo-tracking#model-availability)，Claude Code 也會為工作階段啟用該功能。其他未列出的工具會交由 `permissionMode` 和 `canUseTool` 處理。使用 `disallowedTools` 封鎖工具。請參閱[權限](/docs/zh-TW/agent-sdk/permissions#allow-and-deny-rules) |

549| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | 自訂權限函式，僅在[權限流程](/docs/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated)進入提示時才會叫用。對於由 `allowedTools`、允許規則或 `permissionMode` 自動核准的呼叫不會叫用。允許規則不會預先核准[任何模式都不會自動核准的動作](/docs/zh-TW/permission-modes#actions-no-mode-auto-approves)。詳情請參閱 [`CanUseTool`](#canusetool) |552| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | 自訂權限函式，僅在[權限流程](/docs/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated)落到提示時才會呼叫。對於由 `allowedTools`、允許規則或 `permissionMode` 自動核准的呼叫，不會呼叫此函式。允許規則不會預先核准[沒有任何模式會自動核准的動作](/docs/zh-TW/permission-modes#actions-no-mode-auto-approves)。詳情請參閱 [`CanUseTool`](#canusetool) |

554| `disallowedTools` | `string[]` | `[]` | 要拒絕的工具。像 `"Bash"` 這樣的單純名稱會將該工具從 Claude 的上下文中移除。像 `"Bash(rm *)"` 這樣帶有範圍的規則會保留該工具可用，並在每種權限模式（包括 `bypassPermissions`）中拒絕符合的呼叫，比對依據為命令的[書寫形式](/docs/zh-TW/permissions#bash-rule-limits)。請參閱[權限](/docs/zh-TW/agent-sdk/permissions#allow-and-deny-rules) |557| `disallowedTools` | `string[]` | `[]` | 要拒絕的工具。像 `"Bash"` 這樣的單純名稱會從 Claude 的上下文中移除該工具。像 `"Bash(rm *)"` 這樣具範圍的規則會讓該工具保持可用，並在每個權限模式（包括 `bypassPermissions`）中，針對[依其撰寫方式](/docs/zh-TW/permissions#bash-rule-limits)的命令拒絕符合的呼叫。請參閱[權限](/docs/zh-TW/agent-sdk/permissions#allow-and-deny-rules) |

557| `env` | `Record<string, string \| undefined>` | `process.env` | 環境變數。設定後會取代子程序環境，而非與 `process.env` 合併，因此請傳入 `{ ...process.env, YOUR_VAR: 'value' }` 以保留 `PATH` 等繼承的變數。此模式的範例請參閱[處理緩慢或停滯的 API 回應](#handle-slow-or-stalled-api-responses)，底層 CLI 讀取的變數請參閱[環境變數](/docs/zh-TW/env-vars)。設定 `CLAUDE_AGENT_SDK_CLIENT_APP` 可在 User-Agent 標頭中識別您的應用程式 |560| `env` | `Record<string, string \| undefined>` | `process.env` | 環境變數。設定後，這會取代子程序環境，而不是與 `process.env` 合併，因此請傳遞 `{ ...process.env, YOUR_VAR: 'value' }` 以保留繼承的變數，例如 `PATH`。此模式的範例請參閱[處理緩慢或停滯的 API 回應](#handle-slow-or-stalled-api-responses)，底層 CLI 讀取的變數請參閱[環境變數](/docs/zh-TW/env-vars)。設定 `CLAUDE_AGENT_SDK_CLIENT_APP` 以在 User-Agent 標頭中識別您的應用程式 |

560| `extraArgs` | `Record<string, string \| null>` | `{}` | 其他引數 |563| `extraArgs` | `Record<string, string \| null>` | `{}` | 其他引數 |

563| `forwardSubagentText` | `boolean` | `false` | 將 subagent 的文字和思考區塊以設定了 `parent_tool_use_id` 的 assistant 和 user 訊息轉送，讓使用端能呈現巢狀逐字稿。若未設定此選項，Claude Code 會發出 subagent 的 `tool_use` 和 `tool_result` 區塊，但不包含文字或思考。在 Claude Code v2.1.219 及更新版本中，會轉送每個巢狀深度的 subagent 訊息；在 v2.1.219 之前，只會出現深度為 1 的 subagent 訊息。由分岔 skill 所產生之 subagent 的訊息，以及巢狀分岔 skill 的訊息，需要 v2.1.275 或更新版本 |566| `forwardSubagentText` | `boolean` | `false` | 將 subagent 的文字和思考區塊轉發為設定了 `parent_tool_use_id` 的 assistant 和 user 訊息，讓取用端可以呈現巢狀逐字稿。若沒有此選項，Claude Code 會省略在[前景](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)執行之 subagent 的文字和思考區塊。關於巢狀 subagent、具有 `context: fork` 的 skill，以及各自所需的 Claude Code 版本，請參閱[追蹤 subagent 訊息](/docs/zh-TW/headless#follow-subagent-messages) |

564| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | 事件的 hook 回呼 |567| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | 事件的 hook 回呼 |

565| `includeHookEvents` | `boolean` | `false` | 在訊息串流中包含 hook 生命週期事件，形式為 [`SDKHookStartedMessage`](#sdkhookstartedmessage)、[`SDKHookProgressMessage`](#sdkhookprogressmessage) 和 [`SDKHookResponseMessage`](#sdkhookresponsemessage)。`SessionStart` 和 `Setup` hook 的生命週期事件一律包含，不需要此選項。某些 hook 事件（例如 `Notification`、`SessionEnd`、`PreCompact` 和 `PostCompact`）即使設定此選項也永遠不會產生 `SDKHookStartedMessage`。對於這些事件，當執行超過一秒的命令 hook 產生輸出時，Claude Code 仍會發出 `SDKHookProgressMessage`，且僅在[於背景執行](/docs/zh-TW/hooks#run-hooks-in-the-background)的 hook 完成時發出 `SDKHookResponseMessage` |568| `includeHookEvents` | `boolean` | `false` | 在訊息串流中包含 hook 生命週期事件，形式為 [`SDKHookStartedMessage`](#sdkhookstartedmessage)、[`SDKHookProgressMessage`](#sdkhookprogressmessage) 和 [`SDKHookResponseMessage`](#sdkhookresponsemessage)。`SessionStart` 和 `Setup` hook 的生命週期事件一律會包含，不需要此選項。某些 hook 事件（例如 `Notification`、`SessionEnd`、`PreCompact` 和 `PostCompact`）即使有此選項也永遠不會產生 `SDKHookStartedMessage`。對於這些事件，當執行超過一秒的命令 hook 產生輸出時，Claude Code 仍會發出 `SDKHookProgressMessage`，且只有在[於背景執行](/docs/zh-TW/hooks#run-hooks-in-the-background)的 hook 完成時才會發出 `SDKHookResponseMessage` |

568| `managedSettings` | `Settings` | `undefined` | 您的主機程序提供給所產生工作階段的政策層級設定。在具有管理員部署之受管設定的機器上，除非管理員最高優先順序的受管來源設定了 `parentSettingsBehavior: 'merge'`，否則 Claude Code 會忽略這些設定；且當 [`policyHelper`](/docs/zh-TW/settings-reference#policyhelper) 提供受管設定時，永遠不會合併它們。合併的值會通過僅允許限制性設定的篩選器；[限制父層設定](/docs/zh-TW/claude-apps-gateway#restrict-parent-settings)說明篩選器允許的內容以及 `allowManaged*Only` 鎖定。設定了 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-TW/env-vars) 的主機，則會直接從此 payload 讀取三個鍵：在 Claude Code v2.1.222 或更新版本中的[模型設定](/docs/zh-TW/model-config#restrict-model-selection)、在 v2.1.246 或更新版本中當沒有受管來源設定它時的 [`modelPricing`](/docs/zh-TW/settings-reference#modelpricing)，以及在 v2.1.247 或更新版本中的 `ENABLE_TOOL_SEARCH` env 項目 |571| `managedSettings` | `Settings` | `undefined` | 您的主機程序提供給所產生工作階段的政策層級設定。在有管理員部署受管設定的機器上，除非管理員的最高優先順序受管來源設定了 `parentSettingsBehavior: 'merge'`，否則 Claude Code 會忽略這些設定，且在 [`policyHelper`](/docs/zh-TW/settings-reference#policyhelper) 提供受管設定時永遠不會合併它們。合併的值會通過僅限限制性的篩選器；[限制父層設定](/docs/zh-TW/claude-apps-gateway#restrict-parent-settings)說明了篩選器允許的內容以及 `allowManaged*Only` 鎖定。設定了 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-TW/env-vars) 的主機則會改為直接從此 payload 讀取三個鍵：在 Claude Code v2.1.222 或更新版本上的[模型設定](/docs/zh-TW/model-config#restrict-model-selection)、在 v2.1.246 或更新版本上沒有任何受管來源設定它時的 [`modelPricing`](/docs/zh-TW/settings-reference#modelpricing)，以及在 v2.1.247 或更新版本上的 `ENABLE_TOOL_SEARCH` env 項目 |

572| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | MCP 伺服器設定 |575| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | MCP 伺服器設定 |

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

575| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | 定義 agent 結果的輸出格式。詳情請參閱[結構化輸出](/docs/zh-TW/agent-sdk/structured-outputs) |578| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | 定義 agent 結果的輸出格式。詳情請參閱[結構化輸出](/docs/zh-TW/agent-sdk/structured-outputs) |

576| `outputStyle` | `string` | `undefined` | 並非 `Options` 欄位。請改在內嵌的 [`settings`](/docs/zh-TW/settings) 物件或設定檔中設定 `outputStyle`。請參閱[啟用輸出風格](/docs/zh-TW/agent-sdk/modifying-system-prompts#activate-an-output-style) |579| `outputStyle` | `string` | `undefined` | 不是 `Options` 欄位。請改為在內嵌 [`settings`](/docs/zh-TW/settings) 物件或設定檔中設定 `outputStyle`。請參閱[啟用輸出風格](/docs/zh-TW/agent-sdk/modifying-system-prompts#activate-an-output-style) |

580| `permissionPrompts` | `'host' \| 'none'` | `'host'` | 由誰回應權限提示：`'host'` 會將其轉送至您的 [`canUseTool`](#canusetool) 回呼或 `permissionPromptToolName` 工具，而 `'none'` 會[拒絕原本會觸發提示的呼叫](/docs/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated)。需要 Claude Code v2.1.259 或更新版本 |583| `permissionPrompts` | `'host' \| 'none'` | `'host'` | 由誰回答權限提示：`'host'` 會將它們路由到您的 [`canUseTool`](#canusetool) 回呼或 `permissionPromptToolName` 工具，而 `'none'` 會[拒絕原本會觸發提示的呼叫](/docs/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated)。需要 Claude Code v2.1.259 或更新版本 |

584| `projectConfigRoot` | `string` | `undefined` | `cwd` 作為其 worktree 之受信任 checkout 的絕對路徑。Claude Code 會從此目錄而非 `cwd` 讀取專案設定、`.mcp.json` 以及專案 `.claude/` 中的命令、agent、skill、工作流程、routine 和輸出風格，並將 `CLAUDE_PROJECT_DIR` 設為此目錄。hook、`apiKeyHelper` 等輔助腳本以及 stdio MCP 伺服器會以此目錄作為工作目錄啟動。`CLAUDE.md` 檔案和 `.claude/rules/` 仍從 `cwd` 載入。需要 Claude Code v2.1.275 或更新版本 |587| `projectConfigRoot` | `string` | `undefined` | 受信任 checkout 的絕對路徑，`cwd` 是它的 worktree。Claude Code 會從此目錄而不是 `cwd` 讀取專案設定、`.mcp.json`，以及專案 `.claude/` 中的命令、agent、skill、工作流程、routine 和輸出風格，並將 `CLAUDE_PROJECT_DIR` 設為此目錄。hook、輔助指令碼（例如 `apiKeyHelper`）以及 stdio MCP 伺服器會以此目錄作為工作目錄啟動。`CLAUDE.md` 檔案和 `.claude/rules/` 仍從 `cwd` 載入。需要 Claude Code v2.1.275 或更新版本 |

585| `promptSuggestions` | `boolean` | `false` | 啟用提示詞建議。每個回合結束後，Claude Code 會發出一則 `prompt_suggestion` 訊息，其中包含預測的下一個使用者提示詞。某些回合 Claude Code 不會產生建議，例如當您的帳戶接近或已達用量上限時。請參閱[Claude Code 何時略過建議](/docs/zh-TW/interactive-mode#when-claude-code-skips-suggestions) |588| `promptSuggestions` | `boolean` | `false` | 啟用提示詞建議。在一個回合之後，Claude Code 會發出 `prompt_suggestion` 訊息，其中包含預測的下一個使用者提示詞。Claude Code 在某些回合不會產生建議，例如當您的帳戶接近或已達到用量上限時。請參閱 [Claude Code 何時略過建議](/docs/zh-TW/interactive-mode#when-claude-code-skips-suggestions) |

587| `resumeDropsTurn` | `string` | `undefined` | 搭配 `resumeSessionAt` 使用：截斷式恢復打算捨棄之回合的提示詞 UUID。當捨棄範圍包含任何無法歸屬於該回合的內容（例如已吸收的佇列訊息或任務通知）時，Claude Code 會拒絕恢復，並在拒絕訊息中指出 `--resume-drops-turn` 旗標。只有 Agent SDK 和 print 模式的恢復會讀取這組參數。需要 Claude Code v2.1.223 或更新版本 |590| `resumeDropsTurn` | `string` | `undefined` | 搭配 `resumeSessionAt` 使用：截斷式繼續打算捨棄之回合的提示詞 UUID。當捨棄的範圍包含任何無法歸屬於該回合的內容（例如被吸收的佇列訊息或任務通知）時，Claude Code 會拒絕繼續，並在拒絕訊息中指出 `--resume-drops-turn` 旗標。只有 Agent SDK 和 print 模式的繼續會讀取這一組值。需要 Claude Code v2.1.223 或更新版本 |

594| `settingSources` | [`SettingSource`](#settingsource)`[]` | CLI 預設值（所有來源） | 控制要載入哪些檔案系統設定。傳入 `[]` 以停用使用者、專案和本機設定。[端點受管政策](/docs/zh-TW/managed-settings#delivery-mechanisms)無論如何都會載入；當工作階段在[符合資格的設定](/docs/zh-TW/server-managed-settings#platform-availability)上以組織憑證進行驗證時，會擷取伺服器受管設定。請參閱[使用 Claude Code 功能](/docs/zh-TW/agent-sdk/claude-code-features#what-settingsources-does-not-control) |597| `settingSources` | [`SettingSource`](#settingsource)`[]` | CLI 預設值（所有來源） | 控制要載入哪些檔案系統設定。傳遞 `[]` 以停用使用者、專案和本機設定。[端點受管政策](/docs/zh-TW/managed-settings#delivery-mechanisms)無論如何都會載入；當工作階段在[符合資格的設定](/docs/zh-TW/server-managed-settings#platform-availability)上以組織憑證進行驗證時，會擷取伺服器受管設定。請參閱[使用 Claude Code 功能](/docs/zh-TW/agent-sdk/claude-code-features#what-settingsources-does-not-control) |

595| `skills` | `string[] \| 'all'` | `undefined` | 工作階段可用的 skill。傳入 `'all'` 以啟用所有探索到的 skill，或傳入 skill 名稱清單。僅傳入確切名稱。在 Agent SDK v0.3.221 或更新版本中，SDK 會在啟動 Claude Code 程序前，以錯誤拒絕格式錯誤和萬用字元形式的名稱。設定後，SDK 會自動將 Skill 工具加入 `allowedTools`。如果您也傳入 `tools`，請在該清單中包含 `'Skill'`。請參閱 [Skills](/docs/zh-TW/agent-sdk/skills) |598| `skills` | `string[] \| 'all'` | `undefined` | 工作階段可用的 skill。傳遞 `'all'` 以啟用每個探索到的 skill，或傳遞 skill 名稱清單。只能傳遞確切名稱。在 Agent SDK v0.3.221 或更新版本上，SDK 會在啟動 Claude Code 程序之前，以錯誤拒絕格式錯誤和萬用字元形式的名稱。設定後，SDK 會自動將 Skill 工具加入 `allowedTools`。如果您也傳遞了 `tools`，請在該清單中包含 `'Skill'`。請參閱 [Skills](/docs/zh-TW/agent-sdk/skills) |

599| `systemPrompt` | `string \| string[] \| { type: 'custom'; prompt: string \| string[]; snapshot?: boolean } \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean; snapshot?: boolean }` | `undefined`（最精簡提示詞） | 系統提示詞設定。傳入字串以使用自訂提示詞，或傳入 `{ type: 'preset', preset: 'claude_code' }` 以使用 Claude Code 的系統提示詞。傳入字串陣列，並在靜態部分與每個請求部分之間放置匯出的 `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` 常數，即可[快取自訂提示詞的靜態部分](/docs/zh-TW/agent-sdk/modifying-system-prompts#cache-the-static-part-of-a-custom-prompt)。使用預設集物件形式時，加入 `append` 以額外指令擴充它，並設定 `excludeDynamicSections: true` 將每個工作階段的上下文移至第一則使用者訊息，以[在不同機器間更有效地重用提示快取](/docs/zh-TW/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines)。設定 `snapshot: false` 可在每個請求時重建提示詞，而非[重用工作階段在第一個請求時記錄的提示詞](/docs/zh-TW/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session)。若要在自訂提示詞上設定 `snapshot`，請傳入 `{ type: 'custom', prompt }` 形式。`{ type: 'custom' }` 形式和 `snapshot` 欄位需要 TypeScript Agent SDK v0.3.257 或更新版本 |602| `systemPrompt` | `string \| string[] \| { type: 'custom'; prompt: string \| string[]; snapshot?: boolean } \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean; snapshot?: boolean }` | `undefined`（最精簡提示詞） | 系統提示詞設定。傳遞字串作為自訂提示詞，或傳遞 `{ type: 'preset', preset: 'claude_code' }` 以使用 Claude Code 的系統提示詞。傳遞字串陣列，並在靜態部分與每個請求的部分之間放置匯出的 `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` 常數，以[快取自訂提示詞的靜態部分](/docs/zh-TW/agent-sdk/modifying-system-prompts#cache-the-static-part-of-a-custom-prompt)。使用 preset 物件形式時，加入 `append` 以額外的指令擴充它，並設定 `excludeDynamicSections: true` 將每個工作階段的上下文移至第一則使用者訊息，以[在不同機器間更好地重複使用提示快取](/docs/zh-TW/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines)。設定 `snapshot: false` 以在每次請求時重建提示詞，而不是[重複使用工作階段在第一次請求時記錄的提示詞](/docs/zh-TW/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session)。若要在自訂提示詞上設定 `snapshot`，請傳遞 `{ type: 'custom', prompt }` 形式。`{ type: 'custom' }` 形式和 `snapshot` 欄位需要 TypeScript Agent SDK v0.3.257 或更新版本 |

600| `taskBudget` | `{ total: number }` | `undefined` | *Alpha.* 以 token 計的 API 端任務預算。設定後，模型會得知其剩餘的 token 預算，以便調整工具使用步調並在達到上限前收尾 |603| `taskBudget` | `{ total: number }` | `undefined` | *Alpha.* 以 token 計算的 API 端任務預算。設定後，模型會被告知其剩餘的 token 預算，以便調整工具使用的步調並在達到上限前收尾 |

601| `thinking` | [`ThinkingConfig`](#thinkingconfig) | 支援的模型為 `{ type: 'adaptive' }` | 控制 Claude 的思考／推理行為。選項請參閱 [`ThinkingConfig`](#thinkingconfig) |604| `thinking` | [`ThinkingConfig`](#thinkingconfig) | 支援的模型為 `{ type: 'adaptive' }` | 控制 Claude 的思考/推理行為。選項請參閱 [`ThinkingConfig`](#thinkingconfig) |

603| `toolAliases` | `Record<string, string>` | `undefined` | 將內建工具名稱對應至 MCP 工具名稱，讓 Claude 呼叫您的 MCP 實作來取代內建工具。例如 `{ Bash: 'mcp__workspace__bash' }` |606| `toolAliases` | `Record<string, string>` | `undefined` | 將內建工具名稱對應到 MCP 工具名稱，讓 Claude 呼叫您的 MCP 實作來取代內建工具。例如 `{ Bash: 'mcp__workspace__bash' }` |

605| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | 工具設定。傳入工具名稱陣列，或使用預設集以取得 Claude Code 的預設工具 |608| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | 工具設定。傳遞工具名稱陣列，或使用 preset 以取得 Claude Code 的預設工具 |

606| `verbatimPrompts` | `boolean` | `false` | 依原樣傳送每個提示詞。SDK 會以 `client_composed: true` 傳送每則使用者訊息。關於 Claude Code 對這些訊息略過哪些處理，請參閱 [`client_composed`](#sdkusermessage)。當您的提示詞文字包含非終端使用者輸入的內容時，請使用此選項。若要逐回合控制，請保持關閉，並改為在個別串流訊息上設定 `client_composed`。需要 TypeScript Agent SDK v0.3.280 或更新版本以及 Claude Code v2.1.248 或更新版本；這些 SDK 版本隨附的 Claude Code 版本即符合 Claude Code 的需求 |609| `verbatimPrompts` | `boolean` | `false` | 依原樣傳遞每個提示詞。SDK 會以 `client_composed: true` 傳送每則使用者訊息。關於 Claude Code 在這些訊息上略過的內容，請參閱 [`client_composed`](#sdkusermessage)。當您的提示詞文字包含終端使用者未輸入的內容時，請使用此選項。若要針對每個回合進行控制，請保持此選項關閉，並改為在個別串流訊息上設定 `client_composed`。需要 TypeScript Agent SDK v0.3.280 或更新版本以及 Claude Code v2.1.248 或更新版本；這些 SDK 版本所隨附的 Claude Code 版本即可滿足 Claude Code 的需求 |

607 610

608<h4 id="handle-slow-or-stalled-api-responses">611<h4 id="handle-slow-or-stalled-api-responses">

609 處理緩慢或停滯的 API 回應612 處理緩慢或停滯的 API 回應

610</h4>613</h4>

611 614

612CLI 子程序會讀取數個控制 API 逾時和停滯偵測的環境變數。請透過 `env` 選項傳入這些變數：615CLI 子程序會讀取數個控制 API 逾時和停滯偵測的環境變數。請透過 `env` 選項傳遞它們：

613 616

614```typescript theme={null}617```typescript theme={null}

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

627});630});

628```631```

629 632

630* `API_TIMEOUT_MS`：Anthropic 用戶端上每個請求的逾時，以毫秒為單位。預設為 `600000`。適用於主迴圈和所有 subagent。633* `API_TIMEOUT_MS`：Anthropic 用戶端上每個請求的逾時時間，以毫秒為單位。預設為 `600000`。適用於主迴圈和所有 subagent。

631* `CLAUDE_CODE_MAX_RETRIES`：API 重試的最大次數。預設為 `10`，上限為 `15`。每次重試都有自己的 `API_TIMEOUT_MS` 時間範圍，因此最壞情況下的實際耗時約為 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 加上退避時間。對於需要撐過較長中斷時間的無人值守執行，請設定 [`CLAUDE_CODE_RETRY_WATCHDOG=1`](/docs/zh-TW/errors#tune-retry-behavior)：它會無限期重試暫時性的容量錯誤，且在 Claude Code v2.1.199 或更新版本中，會將其他暫時性錯誤的預設值提高至 `300`，並移除此變數的上限。634* `CLAUDE_CODE_MAX_RETRIES`：API 重試的最大次數。預設為 `10`，上限為 `15`。每次重試都有各自的 `API_TIMEOUT_MS` 時間範圍，因此最壞情況下的實際耗時約為 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 加上退避時間。對於需要撐過較長中斷時間的無人值守執行，請設定 [`CLAUDE_CODE_RETRY_WATCHDOG=1`](/docs/zh-TW/errors#tune-retry-behavior)：它會無限期重試暫時性的容量錯誤，並且在 Claude Code v2.1.199 或更新版本上，將其他暫時性錯誤的預設值提高到 `300`，並移除此變數的上限。

632* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：subagent 的停滯看門狗。當串流看門狗開啟時，預設值為 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 加上 5 分鐘，除非您提高該變數，否則即為 `600000`。當串流看門狗關閉時，預設值為 `600000`。在 v2.1.257 之前，預設值一律為 `600000`。635* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：subagent 的停滯監控器。當串流監控器開啟時，預設值為 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 加上 5 分鐘，除非您提高該變數，否則為 `600000`。串流監控器關閉時，預設值為 `600000`。在 v2.1.257 之前，預設值一律為 `600000`。

633 636

634 計時器會在每個串流事件時重設。發生停滯時，Claude Code 會中止該 subagent 並向父層回報停滯。對於背景 subagent，它還會將任務標記為失敗，並附上任何部分結果。637 每次串流事件發生時計時器都會重設。發生停滯時，Claude Code 會中止該 subagent 並向父層回報停滯。對於背景 subagent，它也會將任務標記為失敗並附上任何部分結果。

635* `CLAUDE_ENABLE_STREAM_WATCHDOG` 搭配 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`：串流看門狗，會在標頭已送達但回應主體停止串流時中止請求。所有提供者的看門狗預設皆為開啟；設定 `CLAUDE_ENABLE_STREAM_WATCHDOG=0` 可將其停用。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` 預設為 `300000`，且會被限制在該最小值。中止之後，[自動重試](/docs/zh-TW/errors#automatic-retries)說明 Claude Code 會根據回應已進展到什麼程度採取哪些動作。638* `CLAUDE_ENABLE_STREAM_WATCHDOG` 搭配 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`：串流監控器，會在標頭已送達但回應主體停止串流時中止請求。此監控器對所有供應商預設為開啟；設定 `CLAUDE_ENABLE_STREAM_WATCHDOG=0` 可停用。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` 預設為 `300000`，且最小值被限制為該值。中止之後，Claude Code 會依據回應已進行的程度採取的行動，請參閱[自動重試](/docs/zh-TW/errors#automatic-retries)。

636 639

637 當看門狗等待一個由 `ANTHROPIC_BASE_URL` 後方的閘道以 keep-alive ping 維持開啟的回應時，設定了 `includePartialMessages` 的主機會持續收到 `ping` [串流事件](#sdkpartialassistantmessage)，因此請將這些訊框視為存活訊號，而不要因為沒有內容就讓工作階段逾時。在 v2.1.257 之前，這些訊框會在最後一個實際串流事件後 5 分鐘停止。640 當監控器在等待一個由 `ANTHROPIC_BASE_URL` 背後的閘道以 keep-alive ping 保持開啟的回應時，設定了 `includePartialMessages` 的主機會持續收到 `ping` [串流事件](#sdkpartialassistantmessage)，因此請將這些框架視為存活訊號，而不是因為沉默而讓工作階段逾時。在 v2.1.257 之前，這些框架會在最後一個實際串流事件的 5 分鐘後停止。

638 641

639<h3 id="query-object">642<h3 id="query-object">

640 `Query` 物件643 `Query` 物件

641</h3>644</h3>

642 645

643`query()` 函式所傳回的介面。646`query()` 函式回傳的介面。

644 647

645```typescript theme={null}648```typescript theme={null}

646interface Query extends AsyncGenerator<SDKMessage, void> {649interface Query extends AsyncGenerator<SDKMessage, void> {

696 699

697| 方法 | 說明 |700| 方法 | 說明 |

698| :- | :- |701| :- | :- |

699| `interrupt()` | 中斷查詢。僅在串流輸入模式中可用。當 CLI 在 [`SDKSystemMessage.capabilities`](#sdksystemmessage) 中宣告 `interrupt_receipt_v1` 能力時，會以 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) 解析，列出中斷送達時仍待處理的訊息。在 v2.1.205 之前的 CLI 上會解析為 `undefined` |702| `interrupt()` | 中斷查詢。僅在串流輸入模式下可用。當 CLI 在 [`SDKSystemMessage.capabilities`](#sdksystemmessage) 中宣告 `interrupt_receipt_v1` 功能時，會以 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) 解析，其中列出中斷到達時尚待處理的訊息。在 v2.1.205 之前的 CLI 上會解析為 `undefined` |

700| `rewindFiles(userMessageId, options?)` | 將檔案還原至指定使用者訊息時的狀態。傳入 `{ dryRun: true }` 以預覽變更。需要 `enableFileCheckpointing: true`。請參閱[檔案檢查點功能](/docs/zh-TW/agent-sdk/file-checkpointing) |703| `rewindFiles(userMessageId, options?)` | 將檔案還原到指定使用者訊息時的狀態。傳遞 `{ dryRun: true }` 以預覽變更。需要 `enableFileCheckpointing: true`。請參閱[檔案檢查點功能](/docs/zh-TW/agent-sdk/file-checkpointing) |

703| `setMaxThinkingTokens()` | *已棄用：* 請改用 `thinking` 選項。變更最大思考 token 數。傳入 `null` 會將思考重設為工作階段預設值：工作階段中途的覆寫會被清除，而對於已停用思考的工作階段，思考仍維持關閉 |706| `setMaxThinkingTokens()` | *已棄用：* 請改用 `thinking` 選項。變更最大思考 token 數。傳遞 `null` 會將思考重設為工作階段預設值：工作階段中途的覆寫會被清除，而已停用思考的工作階段會維持關閉 |

705| `updateSettings(source, settings)` | 將一個允許清單中的鍵寫入專案的本機設定檔或您的使用者設定檔，讓該值在之後的工作階段中持續保留。請參閱 [`updateSettings()`](#updatesettings)。需要 TypeScript SDK v0.3.257 或更新版本（隨附 Claude Code v2.1.257） |708| `updateSettings(source, settings)` | 將一個允許清單中的鍵寫入專案的本機設定檔或您的使用者設定檔，讓該值在之後的工作階段中保留。請參閱 [`updateSettings()`](#updatesettings)。需要 TypeScript SDK v0.3.257 或更新版本，其隨附 Claude Code v2.1.257 |

707| `reinitialize()` | 將 `initialize` 控制請求重新傳送至執行中的 CLI，並傳回全新的結果，而非快取的首次連線結果。請在傳輸中斷後使用，例如在斷線後重新連接工作階段時，讓待處理的權限請求再次送達您的 `canUseTool` 回呼。請讓回呼對每個請求 ID 具有冪等性，因為回應遺失的請求會再次被分派。需要 Claude Code v2.1.195 或更新版本 |710| `reinitialize()` | 重新將 `initialize` 控制請求傳送給正在執行的 CLI，並回傳新的結果，而不是快取的首次連線結果。在傳輸中斷之後使用，例如在中斷連線後重新附加到工作階段時，讓待處理的權限請求再次送達您的 `canUseTool` 回呼。請讓回呼針對每個請求 ID 具有冪等性，因為回應遺失的請求會被再次分派。需要 Claude Code v2.1.195 或更新版本 |

708| `supportedCommands()` | 傳回可用的命令。從 Agent SDK v0.3.216 起，此清單會反映工作階段中途的命令變更；請參閱 [`SDKCommandsChangedMessage`](#sdkcommandschangedmessage) |711| `supportedCommands()` | 回傳可用的命令。從 Agent SDK v0.3.216 起，此清單會反映工作階段中途的命令變更；請參閱 [`SDKCommandsChangedMessage`](#sdkcommandschangedmessage) |

712| `getContextUsage(opts?)` | 傳回 [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse)，依類別、skill 和工具細分工作階段的上下文視窗使用量。使用預設的 `detail` 時，它與互動式工作階段中 `/context` 顯示的資料相同，透過不會出現在訊息串流中的 token 計數 API 請求計算；請參閱[這些請求的處理方式](#sdkcontrolgetcontextusageresponse)。[`detail` 選項](#sdkcontrolgetcontextusageresponse)需要 Agent SDK v0.3.257 或更新版本 |715| `getContextUsage(opts?)` | 回傳 [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse)，依類別、skill 和工具細分工作階段的上下文視窗使用量。使用預設的 `detail` 時，這與互動式工作階段中 `/context` 顯示的資料相同，是以不會出現在訊息串流中的 token 計數 API 請求計算而得；請參閱[這些請求的處理方式](#sdkcontrolgetcontextusageresponse)。[`detail` 選項](#sdkcontrolgetcontextusageresponse)需要 Agent SDK v0.3.257 或更新版本 |

713| `readFile(path, options?)` | 從工作階段的檔案系統讀取檔案。Claude Code 會以 `cwd` 為基準解析路徑；[`readFile()` 可以讀取哪些檔案](#what-readfile-can-read)列出它所提供的檔案。傳入 `{ maxBytes }` 可變更讀取上限（預設 1 MB，最高 10 MB），對於圖片等二進位檔案則傳入 `{ encoding: 'base64' }`。會以 [`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse) 解析，或在權限遭拒、檔案不存在或傳輸錯誤時解析為 `null`。需要 TypeScript SDK v0.2.121 或更新版本 |716| `readFile(path, options?)` | 從工作階段的檔案系統讀取檔案。Claude Code 會相對於 `cwd` 解析路徑；[`readFile()` 可以讀取的內容](#what-readfile-can-read)列出了它會提供的檔案。傳遞 `{ maxBytes }` 以變更讀取上限（預設 1 MB，最高 10 MB），二進位檔案（例如圖片）則傳遞 `{ encoding: 'base64' }`。會以 [`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse) 解析，或在權限遭拒、檔案不存在或傳輸錯誤時解析為 `null`。需要 TypeScript SDK v0.2.121 或更新版本 |

714| `reloadPlugins(options?)` | 從磁碟重新載入外掛，讓您在工作階段中途安裝或編輯的外掛能套用到執行中的工作階段。會以 [`SDKControlReloadPluginsResponse`](#sdkcontrolreloadpluginsresponse) 解析，列出工作階段的命令、subagent、外掛和 MCP 伺服器狀態。需要 Agent SDK v0.2.85 或更新版本。[`holdOnCacheImpact` 選項](#sdkcontrolreloadpluginsresponse)需要 Agent SDK v0.3.268 或更新版本 |717| `reloadPlugins(options?)` | 從磁碟重新載入外掛，讓您在工作階段中途安裝或編輯的外掛能送達正在執行的工作階段。會以 [`SDKControlReloadPluginsResponse`](#sdkcontrolreloadpluginsresponse) 解析，其中列出工作階段的命令、subagent、外掛和 MCP 伺服器狀態。需要 Agent SDK v0.2.85 或更新版本。[`holdOnCacheImpact` 選項](#sdkcontrolreloadpluginsresponse)需要 Agent SDK v0.3.268 或更新版本 |

715| `reloadSkills()` | 從磁碟重新載入 skill，讓您在工作階段中途新增或編輯的 skill 可供執行中的工作階段使用。會以 [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) 解析，列出重新載入後可用的 skill。需要 Agent SDK v0.3.163 或更新版本 |718| `reloadSkills()` | 從磁碟重新載入 skill，讓您在工作階段中途新增或編輯的 skill 可供正在執行的工作階段使用。會以 [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) 解析，其中列出重新載入後可用的 skill。需要 Agent SDK v0.3.163 或更新版本 |

716| `reloadOutputStyles()` | 從磁碟重新讀取[輸出風格](/docs/zh-TW/output-styles)，讓您在工作階段中途新增或編輯的風格檔案可供執行中的工作階段使用。會以 [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse) 解析，列出重新載入後可用的風格名稱。需要 Agent SDK v0.3.261 或更新版本 |719| `reloadOutputStyles()` | 從磁碟重新讀取[輸出風格](/docs/zh-TW/output-styles)，讓您在工作階段中途新增或編輯的風格檔案可供正在執行的工作階段使用。會以 [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse) 解析，其中列出重新載入後可用的風格名稱。需要 Agent SDK v0.3.261 或更新版本 |

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

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

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

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

725 728

726<h4 id="applyflagsettings">729<h4 id="applyflagsettings">

727 `applyFlagSettings()`730 `applyFlagSettings()`

728</h4>731</h4>

729 732

730在不重新啟動查詢的情況下，變更執行中工作階段的[設定](/docs/zh-TW/settings)。當某個沒有專用設定方法的設定需要在工作階段中途變更時使用，例如在 agent 讀取不受信任的輸入後收緊 `permissions`。`setModel()` 和 `setPermissionMode()` 是這兩個鍵的專用設定方法；`applyFlagSettings()` 則是接受任何設定鍵子集的通用形式，在此傳入 `model` 的行為與 `setModel()` 相同。733在不重新啟動查詢的情況下變更正在執行之工作階段的[設定](/docs/zh-TW/settings)。當某個沒有專用 setter 的設定需要在工作階段中途變更時使用，例如在 agent 讀取不受信任的輸入後收緊 `permissions`。`setModel()` 和 `setPermissionMode()` 是這兩個鍵的專用 setter；`applyFlagSettings()` 則是接受任何設定鍵子集的通用形式，在此傳遞 `model` 的行為與 `setModel()` 相同。

731 734

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

733 736

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

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

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

737 740

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

739 742

740這些值會寫入旗標設定層，並合併覆寫 `query()` 的內嵌 `settings` 選項在啟動時所設定的內容。這與[本頁優先順序章節](#settings-precedence)所稱的程式化選項是同一層級。743這些值會寫入旗標設定層，並合併在 `query()` 的內嵌 `settings` 選項於啟動時所設定的內容之上。這與[本頁優先順序章節](#settings-precedence)所稱的程式化選項屬於同一層級。

741 744

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

743 746

744若要清除您以 `applyFlagSettings()` 設定的鍵，請為該鍵傳入 `null`。大多數鍵接著會先退回 `query()` 的 `settings` 選項在啟動時設定的值，再退回較低優先順序的來源。清除的 `model` 會重設為 [Claude Code 的預設模型](/docs/zh-TW/model-config)，即使設定檔設定了 `model` 亦然。傳入 `undefined` 沒有效果，因為 JSON 序列化會將其捨棄。747若要清除您以 `applyFlagSettings()` 設定的鍵，請為該鍵傳遞 `null`。大多數鍵接著會先退回 `query()` 的 `settings` 選項在啟動時設定的值，再退回優先順序較低的來源。清除後的 `model` 會重設為 [Claude Code 的預設模型](/docs/zh-TW/model-config)，即使設定檔中設定了 `model` 也是如此。傳遞 `undefined` 沒有作用，因為 JSON 序列化會捨棄它。

745 748

746除了 `model` 之外，還有三個鍵會重設工作階段狀態，而非退回其他值：749除了 `model` 之外，還有三個鍵會重設工作階段狀態，而不是退回其他來源：

747 750

748* `effortLevel: null` 會讓工作階段回到模型的預設 effort 等級，而非 `query()` 的 `effort` 選項或設定檔中的 `effortLevel`。751* `effortLevel: null` 會將工作階段恢復為模型的預設 effort 等級，而不是 `query()` 的 `effort` 選項或設定檔中的 `effortLevel`。

749* `agent: null` 會從下一個回合開始以不使用 agent 的方式執行主執行緒，而非還原 `query()` 的 `agent` 選項或設定檔中的 `agent`。如果被清除的 agent 套用了它自己的模型，工作階段會回到啟動時解析的模型。752* `agent: null` 會從下一個回合開始以不使用任何 agent 的方式執行主執行緒，而不是恢復 `query()` 的 `agent` 選項或設定檔中的 `agent`。如果被清除的 agent 曾套用它自己的模型，工作階段會回到它在啟動時解析的模型。

750* `ultracode: null` 會關閉 ultracode（與 `false` 相同），而非還原設定檔中的 `ultracode` 值。工作階段會保留目前的 effort 等級，因此若要變更，請在同一次呼叫中傳入 `effortLevel`。753* `ultracode: null` 會關閉 ultracode（與 `false` 相同），而不是恢復設定檔中的 `ultracode` 值。工作階段會保留目前的 effort 等級，因此若要變更，請在同一次呼叫中傳遞 `effortLevel`。

751 754

752僅在串流輸入模式中可用，與 `setModel()` 和 `setPermissionMode()` 的限制相同。755僅在串流輸入模式下可用，與 `setModel()` 和 `setPermissionMode()` 的限制相同。

753 756

754以下範例在工作階段中途切換使用中的模型，然後清除覆寫，讓模型重設為 [Claude Code 的預設模型](/docs/zh-TW/model-config)。757以下範例在工作階段中途切換使用中的模型，然後清除覆寫，讓模型重設為 [Claude Code 的預設模型](/docs/zh-TW/model-config)。

755 758

766```769```

767 770

768<Note>771<Note>

769 `applyFlagSettings()` 僅適用於 TypeScript。Python SDK 未提供對應的方法。772 `applyFlagSettings()` 僅限 TypeScript。Python SDK 沒有提供對應的方法。

770</Note>773</Note>

771 774

772<h4 id="updatesettings">775<h4 id="updatesettings">

773 `updateSettings()`776 `updateSettings()`

774</h4>777</h4>

775 778

776將一個允許清單中的鍵寫入磁碟上的設定檔，讓該值在之後載入該來源的工作階段中持續保留。每個來源接受一個鍵，值為字串：779將一個允許清單中的鍵寫入磁碟上的設定檔，讓該值在之後載入該來源的工作階段中保留。每個來源接受一個鍵，值為字串：

777 780

778* **`"localSettings"`**：接受 `outputStyle`，並將其合併至專案的本機設定檔 `.claude/settings.local.json`。新的風格會在工作階段的下一個請求生效。781* **`"localSettings"`**：接受 `outputStyle`，並將其合併到專案的本機設定檔 `.claude/settings.local.json`。新的風格會在工作階段的下一個請求時生效。

779* **`"userSettings"`**：接受 `effortLevel`，並將其儲存為工作階段目前模型的預設 [effort 等級](/docs/zh-TW/model-config#adjust-effort-level)，存放於您使用者設定檔中的 [`modelSettings`](/docs/zh-TW/settings-reference#modelsettings) 下。傳入 `max` 不會寫入任何內容，因為 `max` 僅限工作階段使用。無論哪種情況，執行中的工作階段都會保留目前的 effort 等級，因此若您也想變更它，請呼叫 [`applyFlagSettings()`](#applyflagsettings)。此來源需要 TypeScript SDK v0.3.277 或更新版本（隨附 Claude Code v2.1.277）。782* **`"userSettings"`**：接受 `effortLevel`，並將其儲存為工作階段目前模型的預設 [effort 等級](/docs/zh-TW/model-config#adjust-effort-level)，位於您使用者設定檔中的 [`modelSettings`](/docs/zh-TW/settings-reference#modelsettings) 下。傳遞 `max` 不會寫入任何內容，因為 `max` 僅限工作階段使用。無論如何，正在執行的工作階段都會保留目前的 effort 等級，因此若您也想變更它，請呼叫 [`applyFlagSettings()`](#applyflagsettings)。此來源需要 TypeScript SDK v0.3.277 或更新版本，其隨附 Claude Code v2.1.277。

780 783

781當請求帶有任何其他鍵、工作階段透過遠端傳輸執行，或工作階段的 [`settingSources`](#options) 排除了您指定的來源時，呼叫會被拒絕。不支援刪除鍵。784當請求帶有任何其他鍵、工作階段透過遠端傳輸執行，或工作階段的 [`settingSources`](#options) 排除了您指定的來源時，呼叫會被拒絕。不支援刪除鍵。

782 785

784 `toggleMcpServer()`787 `toggleMcpServer()`

785</h4>788</h4>

786 789

787停用伺服器會將其中斷連線，並從工作階段中移除其工具。對於您在工作階段中途新增的伺服器以及處理程序內伺服器，這取決於您的 Claude Code 版本：790停用伺服器會中斷其連線並從工作階段中移除其工具。對於您在工作階段中途新增的伺服器以及處理程序內伺服器，這取決於您的 Claude Code 版本：

788 791

789* 您在工作階段中途以 `setMcpServers()` 新增的 stdio、SSE 或 HTTP 伺服器：移除其工具需要 Claude Code v2.1.285 或更新版本。792* 您在工作階段中途以 `setMcpServers()` 新增的 stdio、SSE 或 HTTP 伺服器：移除其工具需要 Claude Code v2.1.285 或更新版本。

790* 您以 [`createSdkMcpServer()`](#createsdkmcpserver) 建立的處理程序內伺服器，無論您是透過 `mcpServers` 或 `setMcpServers()` 傳入：將其中斷連線並移除其工具需要 Claude Code v2.1.286 或更新版本。停用此類伺服器也會讓其仍在執行中的工具呼叫失敗，因此 Claude 會立即針對每個呼叫收到錯誤結果，而不必等待您的處理常式傳回。793* 您以 [`createSdkMcpServer()`](#createsdkmcpserver) 建立的處理程序內伺服器，無論您是在 `mcpServers` 中傳遞還是透過 `setMcpServers()` 傳遞：中斷其連線並移除其工具需要 Claude Code v2.1.286 或更新版本。停用這類伺服器也會使其仍在執行的工具呼叫失敗，因此 Claude 會立即收到每個呼叫的錯誤結果，而不需等待您的處理常式回傳。

791 794

792<h3 id="warmquery">795<h3 id="warmquery">

793 `WarmQuery`796 `WarmQuery`

794</h3>797</h3>

795 798

796由 [`startup()`](#startup) 傳回的控制代碼。子程序已產生並初始化完成，因此在此控制代碼上呼叫 `query()` 會將提示詞直接寫入已就緒的程序，沒有啟動延遲。799由 [`startup()`](#startup) 回傳的控制代碼。子程序已經產生並初始化完成，因此在此控制代碼上呼叫 `query()` 會將提示詞直接寫入已就緒的程序，沒有啟動延遲。

797 800

798```typescript theme={null}801```typescript theme={null}

799interface WarmQuery extends AsyncDisposable {802interface WarmQuery extends AsyncDisposable {

808 811

809| 方法 | 說明 |812| 方法 | 說明 |

810| :- | :- |813| :- | :- |

813 816

814`WarmQuery` 實作了 `AsyncDisposable`，因此可搭配 `await using` 使用以自動清理。817`WarmQuery` 實作了 `AsyncDisposable`，因此可以搭配 `await using` 使用以自動清理。

815 818

816<h3 id="spareprocess">819<h3 id="spareprocess">

817 `SpareProcess`820 `SpareProcess`

818</h3>821</h3>

819 822

820*Alpha.* 由 [`prewarm()`](#prewarm) 傳回的控制代碼：一個已啟動但尚未繫結至工作階段、且只能被認領一次的 Claude Code 程序。需要 TypeScript Agent SDK v0.3.282 或更新版本。823*Alpha.* 由 [`prewarm()`](#prewarm) 回傳的控制代碼：一個已啟動但尚未繫結到工作階段的 Claude Code 程序，可以認領一次。需要 TypeScript Agent SDK v0.3.282 或更新版本。

821 824

822```typescript theme={null}825```typescript theme={null}

823interface SpareProcess extends AsyncDisposable {826interface SpareProcess extends AsyncDisposable {

837 840

838| 成員 | 說明 |841| 成員 | 說明 |

839| :- | :- |842| :- | :- |

840| `claim({ prompt, options })` | 將備用程序繫結至 `options.cwd` 中的工作階段，並傳送其第一則訊息。與 `query()` 一樣同步傳回 [`Query`](#query-object)。只能呼叫一次 |843| `claim({ prompt, options })` | 將備用程序繫結到 `options.cwd` 中的工作階段並傳送其第一則訊息。與 `query()` 一樣同步回傳 [`Query`](#query-object)。只能呼叫一次 |

841| `claimed` | 當 Claude Code 接受認領時，以工作階段的工作目錄和 ID 解析。當 Claude Code 拒絕認領、程序先行結束或被關閉時會拒絕，而當工作階段在沒有您要求的 `model` 或 `maxThinkingTokens` 的情況下執行時，則會以開頭為 `option_not_applied` 的訊息拒絕 |844| `claimed` | 在 Claude Code 接受認領後，以工作階段的工作目錄和 ID 解析。當 Claude Code 拒絕認領、程序先行結束或被關閉時會拒絕；當工作階段在沒有您要求的 `model` 或 `maxThinkingTokens` 的情況下執行時，會以開頭為 `option_not_applied` 的訊息拒絕 |

844 847

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

846 849

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

848 851

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

850 `SDKControlInitializeResponse`853 `SDKControlInitializeResponse`

851</h3>854</h3>

852 855

853`initializationResult()` 的傳回類型。包含工作階段初始化資料。856`initializationResult()` 的回傳型別。包含工作階段初始化資料。

854 857

855```typescript theme={null}858```typescript theme={null}

856type SDKControlInitializeResponse = {859type SDKControlInitializeResponse = {

874};877};

875```878```

876 879

877`hooks_applied` 回報 Claude Code 是否註冊了 `initialize` 請求所攜帶的 `hooks`。SDK 會在工作階段啟動時傳送該請求一次，並在每次呼叫 [`reinitialize()`](#query-object) 時再次傳送。此欄位需要 Agent SDK v0.3.238 或更新版本。880`hooks_applied` 回報 Claude Code 是否已註冊 `initialize` 請求所帶的 `hooks`。SDK 會在工作階段啟動時傳送該請求一次，並在每次呼叫 [`reinitialize()`](#query-object) 時再次傳送。此欄位需要 Agent SDK v0.3.238 或更新版本。

878 881

879當請求未攜帶 hook 時，Claude Code 會省略此欄位。當請求攜帶了 hook 時，其值取決於該請求是否為工作階段的第一次 initialize，以及對於重複的請求而言，它是如何送達工作階段的：882當請求未帶任何 hook 時，Claude Code 會省略此欄位。當請求帶有 hook 時，其值取決於該請求是否為工作階段的第一次 initialize，以及對於重複的 initialize，它如何送達工作階段：

880 883

881* `true`：Claude Code 已註冊這些 hook。工作階段的第一次 initialize 會傳回此值。透過 CLI 的 stdin 傳送的重複 initialize 也會傳回 `true`。在這種情況下，新請求中的 hook 會取代先前註冊的 hook。884* `true`：Claude Code 已註冊這些 hook。工作階段的第一次 initialize 會回傳此值。透過 CLI 的 stdin 傳送的重複 initialize 也會回傳 `true`。在這種情況下，新請求中的 hook 會取代先前註冊的 hook。

882* `false`：Claude Code 忽略了這些 hook。傳送至遠端工作階段的重複 initialize 會傳回此值，因此加入工作階段的第二個用戶端無法取代第一個用戶端所註冊的 hook。885* `false`：Claude Code 忽略了這些 hook。傳送到遠端工作階段的重複 initialize 會回傳此值，因此加入工作階段的第二個用戶端無法取代第一個用戶端註冊的 hook。

883 886

884在 Agent SDK v0.3.238 之前，回應從不攜帶此欄位，且 Claude Code 會在每次重複 initialize 時忽略 `hooks`。887在 Agent SDK v0.3.238 之前，回應從不帶有此欄位，且 Claude Code 在每次重複 initialize 時都會忽略 `hooks`。

885 888

886請求的 `sdkMcpServerManifests` 欄位與回應的 `sdk_mcp_manifests_parked` 欄位是供您以 [`createSdkMcpServer()`](#createsdkmcpserver) 建立的程序內 [SDK MCP 伺服器](/docs/zh-TW/agent-sdk/custom-tools)使用。您的應用程式不需要設定或讀取這兩個欄位。889請求的 `sdkMcpServerManifests` 欄位和回應的 `sdk_mcp_manifests_parked` 欄位，是用於您以 [`createSdkMcpServer()`](#createsdkmcpserver) 建立的處理程序內 [SDK MCP 伺服器](/docs/zh-TW/agent-sdk/custom-tools)。您的應用程式不需要設定或讀取這兩個欄位。

887 890

888回應一律會回報 `fast_mode_state`，且當有因素阻擋[快速模式](/docs/zh-TW/fast-mode)時，`fast_mode_disabled_reason` 會隨之攜帶原因代碼，讓您能說明被阻擋的狀態，而不必重新推導可用性。這兩項行為都需要 Claude Code v2.1.219 或更新版本。在 v2.1.219 之前，當快速模式無法使用時，回應會省略 `fast_mode_state`，且從不攜帶原因。關於原因代碼及其意義，請參閱結果訊息上的 [`fast_mode_disabled_reason`](#sdkresultmessage)。891回應一律會回報 `fast_mode_state`，而當有某些因素阻擋[快速模式](/docs/zh-TW/fast-mode)時，`fast_mode_disabled_reason` 會一併帶有原因代碼，讓您可以說明被阻擋的狀態，而不必重新推導可用性。這兩種行為都需要 Claude Code v2.1.219 或更新版本。在 v2.1.219 之前，回應會在快速模式不可用時省略 `fast_mode_state`，且從不帶有原因。關於原因代碼及其意義，請參閱結果訊息上的 [`fast_mode_disabled_reason`](#sdkresultmessage)。

889 892

890成功的 `initialize` 的控制回應包裝也會攜帶 `pending_permission_requests` 陣列。此欄位位於回應包裝本身，而非上述 `SDKControlInitializeResponse` payload 中。每個項目都是完整的 `control_request` 訊息，其 `{ type: "control_request", request_id, request }` 形狀與工作階段執行時為權限請求所串流的形狀相同。893成功的 `initialize` 的控制回應包裝也帶有一個 `pending_permission_requests` 陣列。此欄位位於回應包裝本身，而不在上述 `SDKControlInitializeResponse` payload 中。每個項目都是一則完整的 `control_request` 訊息，其 `{ type: "control_request", request_id, request }` 形狀與工作階段在執行期間串流權限請求時相同。

891 894

892此陣列列出這個 Claude Code 程序已發出但尚未解決的權限請求。SDK 會為您讀取此陣列，並將每個項目分派至您的 [`canUseTool`](#canusetool) 回呼，這與 [`reinitialize()`](#query-object) 在傳輸中斷後觸發的重新傳遞相同。請以冪等方式處理重複的請求 ID，因為某個項目可能重複了回呼在連線中斷前已收到的請求。895此陣列列出此 Claude Code 程序已發出但尚未解決的權限請求。SDK 會為您讀取此陣列，並將每個項目分派給您的 [`canUseTool`](#canusetool) 回呼，這與 [`reinitialize()`](#query-object) 在傳輸中斷後觸發的重新傳遞相同。請以冪等方式處理重複的請求 ID，因為某個項目可能會重複回呼在連線中斷前就已收到的請求。

893 896

894在成功的 `initialize` 回應上，此陣列一律存在，且當此程序沒有未解決的權限請求時為空。需要 Claude Code v2.1.268 或更新版本。較早的版本可能會省略此欄位，因此如果您自行剖析傳輸協定，請將缺少此欄位視為較舊的 CLI，而非視為沒有任何待處理項目的證明。897此陣列一律會出現在成功的 `initialize` 回應中，當此程序沒有未解決的權限請求時則為空。需要 Claude Code v2.1.268 或更新版本。較早的版本可能會省略此欄位，因此如果您自行剖析傳輸協定，請將缺少此欄位視為較舊的 CLI，而不是證明沒有任何待處理的請求。

895 898

896<h3 id="sdkcontrolinterruptresponse">899<h3 id="sdkcontrolinterruptresponse">

897 `SDKControlInterruptResponse`900 `SDKControlInterruptResponse`

898</h3>901</h3>

899 902

900中斷回執：在 [`SDKSystemMessage.capabilities`](#sdksystemmessage) 中宣告 `interrupt_receipt_v1` 能力的 CLI 上，[`interrupt()`](#query-object) 所解析的值。需要 Claude Code v2.1.205 或更新版本。較早的 CLI 會以空的成功 payload 回應中斷，因此 `interrupt()` 會解析為 `undefined`。903中斷回執：在 [`SDKSystemMessage.capabilities`](#sdksystemmessage) 中宣告 `interrupt_receipt_v1` 功能的 CLI 上，[`interrupt()`](#query-object) 所解析的值。需要 Claude Code v2.1.205 或更新版本。較早的 CLI 會以空的成功 payload 回應中斷，因此 `interrupt()` 會解析為 `undefined`。

901 904

902```typescript theme={null}905```typescript theme={null}

903type SDKControlInterruptResponse = {906type SDKControlInterruptResponse = {

906};909};

907```910```

908 911

909`still_queued` 列出中斷送達時仍待處理之使用者訊息的 UUID：仍在佇列中的訊息，加上 Claude Code 已為下一個回合從佇列中取出的任何訊息。一旦工作階段的第一個回合已開始，除非您先取消，否則 Claude Code 會在中斷後處理所列出的訊息，且可能將數則訊息合併為一個回合。如果您在第一個回合開始前中斷，Claude Code 會在該回合一開始就將其中止，而該回合中所列出的訊息不會得到回應。912`still_queued` 列出中斷到達時尚待處理之使用者訊息的 UUID：仍在佇列中的訊息，以及 Claude Code 已從佇列中取出準備用於下一個回合的任何訊息。一旦工作階段的第一個回合已經開始，除非您先取消，否則 Claude Code 會在中斷後處理所列出的訊息，並可能將數則訊息合併為一個回合。如果您在第一個回合開始之前中斷，Claude Code 會在該回合一開始就將其中止，而該回合中所列出的訊息不會得到回應。

910 913

911請使用此回執來決定是否要重新傳送任何內容。您未取消的所列訊息無論是否得到回應都會進入對話，因此重新傳送會讓 Claude 收到兩次。914請使用此回執來決定是否要重新傳送任何內容。您未取消的已列出訊息無論是否得到回應，都會進入對話，因此重新傳送它會將其傳遞給 Claude 兩次。

912 915

913請在考量以下注意事項的前提下解讀此清單：916解讀此清單時請注意以下事項：

914 917

915* 只有以 UUID 加入佇列的訊息才會出現。空陣列並不代表沒有其他內容會執行。918* 只有以 UUID 加入佇列的訊息才會出現。空陣列並不代表沒有其他內容會執行。

916* 只會列出主執行緒的訊息。傳送給 subagent 的訊息不在範圍內。919* 只會列出主執行緒的訊息。傳給 subagent 的訊息不在範圍內。

917* 清單可能包含您的用戶端從未傳送的 UUID，例如[排程任務](/docs/zh-TW/scheduled-tasks)觸發。請忽略您無法辨識的 UUID，而不要將其視為錯誤。920* 此清單可能包含您的用戶端從未傳送的 UUID，例如[排程任務](/docs/zh-TW/scheduled-tasks)觸發。請忽略您無法識別的 UUID，而不要將其視為錯誤。

918 921

919直接驅動 CLI 控制協定（而非透過 `interrupt()`）的用戶端，可以在 `interrupt` 控制請求上設定 `cancel_queued: true`。Claude Code v2.1.219 及更新版本會在 [`SDKSystemMessage.capabilities`](#sdksystemmessage) 中以 `interrupt_cancel_queued_v1` 能力宣告支援；較舊的 CLI 會忽略此欄位，並照常讓佇列中的訊息執行。此類中斷也會取消原本會列在 `still_queued` 下的每則訊息：回執會改將它們列在 `cancelled` 下，`still_queued` 為空，且它們都不會執行。922直接驅動 CLI 控制協定（而不是透過 `interrupt()`）的用戶端，可以在 `interrupt` 控制請求上設定 `cancel_queued: true`。Claude Code v2.1.219 及更新版本會在 [`SDKSystemMessage.capabilities`](#sdksystemmessage) 中以 `interrupt_cancel_queued_v1` 功能宣告支援；較舊的 CLI 會忽略此欄位，並讓佇列中的訊息照常執行。這樣的中斷也會取消原本會列在 `still_queued` 下的每則訊息：回執會改為將它們列在 `cancelled` 下，`still_queued` 為空，且它們都不會執行。

920 923

921`cancelled` 清單與 `still_queued` 具有相同的注意事項。`interrupt()` 方法從不傳送 `cancel_queued`，因此它所解析的回執不會攜帶 `cancelled`。924`cancelled` 清單與 `still_queued` 具有相同的注意事項。`interrupt()` 方法從不傳送 `cancel_queued`，因此它所解析的回執不會帶有 `cancelled`。

922 925

923回執是在處理中斷當下擷取的快照，且在正常中斷時，它會在被中斷回合的 [`SDKResultMessage`](#sdkresultmessage) 之前送達。請讀取回執，而不要在該結果之後檢查佇列：迴圈會立即開始下一個佇列中的回合，因此您在結果之後檢查的佇列已經改變了。926此回執是在處理中斷的那一刻所擷取的快照，而在正常的中斷中，它會在被中斷回合的 [`SDKResultMessage`](#sdkresultmessage) 之前送達。請讀取回執，而不要在該結果之後檢查佇列：迴圈會立即開始下一個佇列中的回合，因此您在結果之後檢查的佇列已經改變了。

924 927

925<h3 id="sdkcontrolgetcontextusageresponse">928<h3 id="sdkcontrolgetcontextusageresponse">

926 `SDKControlGetContextUsageResponse`929 `SDKControlGetContextUsageResponse`

927</h3>930</h3>

928 931

929[`getContextUsage()`](#query-object) 的傳回類型。使用預設的 `detail` 時，這與 Claude Code 在互動式工作階段中為 `/context` 命令所呈現的 payload 相同，因此除了 token 計數之外，它還攜帶 `color` 和 `gridRows` 等顯示欄位，供 Claude Code 繪製 `/context` 使用量格線。932[`getContextUsage()`](#query-object) 的回傳型別。使用預設的 `detail` 時，這與 Claude Code 在互動式工作階段中為 `/context` 命令呈現的 payload 相同，因此除了 token 計數之外，它還帶有 `color` 和 `gridRows` 等顯示欄位，Claude Code 用它們來繪製 `/context` 使用量網格。

930 933

931此方法的選用 `detail` 引數用於選擇 Claude Code 如何計算每個類別。`detail` 引數需要 Agent SDK v0.3.257 或更新版本。934此方法的選用 `detail` 引數決定 Claude Code 如何計算每個類別。`detail` 引數需要 Agent SDK v0.3.257 或更新版本。

932 935

933* **`'full'`**：預設值。Claude Code 會以 [token 計數](https://platform.claude.com/docs/en/build-with-claude/token-counting) API 請求計算每個類別。這些請求不會出現在訊息串流中，因此讀取串流的成本追蹤不會看到它們。在 Anthropic API 上，token 計數不會計費。936* **`'full'`**：預設值。Claude Code 會以 [token 計數](https://platform.claude.com/docs/en/build-with-claude/token-counting) API 請求計算每個類別。這些請求不會出現在訊息串流中，因此讀取串流的成本追蹤不會看到它們。在 Anthropic API 上，token 計數不收費。

934* **`'summary'`**：傳入 `{ detail: 'summary' }`，改從上一個回應的用量和本機估算取得答案。不會發出 token 計數請求，且各類別的數字為近似值。937* **`'summary'`**：傳遞 `{ detail: 'summary' }` 以改為從上一個回應的用量和本機估算取得答案。不會發出任何 token 計數請求，且各類別的數字為近似值。

935 938

936當您以提示詞傳送 `/context` 而非呼叫此方法時，Claude Code 會將 [`SDKContextUsage`](#sdkcontextusage) payload 附加到傳遞結果之 assistant 訊息的 `context_usage` 欄位。該欄位需要 Agent SDK v0.3.232 或更新版本。939當您將 `/context` 作為提示詞傳送而不是呼叫此方法時，Claude Code 會將 [`SDKContextUsage`](#sdkcontextusage) payload 附加到傳遞結果之 assistant 訊息的 `context_usage` 欄位。該欄位需要 Agent SDK v0.3.232 或更新版本。

937 940

938```typescript theme={null}941```typescript theme={null}

939type SDKControlGetContextUsageResponse = {942type SDKControlGetContextUsageResponse = {

1032 1035

1033請從集合欄位讀取 token 歸屬：1036請從集合欄位讀取 token 歸屬：

1034 1037

1035* `categories` 保存各類別的總計。每個項目的 `kind` 會以與 [`SDKContextUsageCategory`](#sdkcontextusagecategory) 相同的值為該列分類。請依據此欄位分類各列，而非依據顯示用的 `name`。此欄位需要 Agent SDK v0.3.268 或更新版本。1038* `categories` 保存各類別的總計。每個項目的 `kind` 會以與 [`SDKContextUsageCategory`](#sdkcontextusagecategory) 相同的值對該列進行分類。請依據它來分類各列，而不是依據顯示用的 `name`。此欄位需要 Agent SDK v0.3.268 或更新版本。

1036* `mcpTools` 和 `agents` 將 token 歸屬至個別 MCP 工具和 subagent。1039* `mcpTools` 和 `agents` 將 token 歸屬到個別的 MCP 工具和 subagent。

1037* `memoryFiles` 列出每個已載入的記憶檔案及其成本。1040* `memoryFiles` 列出每個已載入的記憶檔案及其成本。

1038* `skills.skillFrontmatter` 將 skill 清單的 token 歸屬至每個被納入的 skill。每個 skill 的計數衡量的是 Claude Code 實際傳送的該 skill 清單項目，可能比 skill 完整的 frontmatter 短。比較 `skills.totalSkills` 與 `skills.includedSkills`，即可得知是否每個探索到的 skill 都納入了清單。1041* `skills.skillFrontmatter` 將 skill 清單的 token 歸屬到每個包含的 skill。每個 skill 的計數衡量的是 Claude Code 實際傳送的該 skill 清單項目，可能比 skill 的完整 frontmatter 短。比較 `skills.totalSkills` 與 `skills.includedSkills`，即可得知是否每個探索到的 skill 都已納入清單。

1039 1042

1040`totalTokens` 是工作階段目前的上下文使用量，而 `maxTokens` 是衡量該使用量所依據的視窗。該視窗為模型的上下文視窗，或在適用時為較低的自動壓縮視窗。`rawMaxTokens` 攜帶與 `maxTokens` 相同的值，而 `percentage` 是 `totalTokens` 佔該視窗的四捨五入百分比。`apiUsage` 保存最新 API 回應的用量，而非工作階段的累計總量。1043`totalTokens` 是工作階段目前的上下文使用量，而 `maxTokens` 是衡量該使用量所依據的視窗。該視窗是模型的上下文視窗，或在適用時為較低的自動壓縮視窗。`rawMaxTokens` 帶有與 `maxTokens` 相同的值，而 `percentage` 是 `totalTokens` 佔該視窗的四捨五入百分比。`apiUsage` 保存的是最新 API 回應的用量，而不是工作階段的累計總量。

1041 1044

1042Claude Code 不會設定選用的 `deferredBuiltinTools`、`systemTools` 和 `systemPromptSections` 診斷資料，因此即使類型有宣告，也請預期它們不存在。1045Claude Code 不會設定選用的 `deferredBuiltinTools`、`systemTools` 和 `systemPromptSections` 診斷欄位，因此即使型別宣告了它們，也請預期它們不存在。

1043 1046

1044<h3 id="sdkcontrolreadfileresponse">1047<h3 id="sdkcontrolreadfileresponse">

1045 `SDKControlReadFileResponse`1048 `SDKControlReadFileResponse`

1046</h3>1049</h3>

1047 1050

1048[`readFile()`](#query-object) 的傳回類型。1051[`readFile()`](#query-object) 的回傳型別。

1049 1052

1050```typescript theme={null}1053```typescript theme={null}

1051type SDKControlReadFileResponse = {1054type SDKControlReadFileResponse = {

1056};1059};

1057```1060```

1058 1061

1059`contents` 保存檔案文字，或在您要求 `encoding: 'base64'` 時保存 base64 資料；在該情況下，回應的 `encoding` 欄位會設為 `'base64'`。`absPath` 是解析後的絕對路徑。當檔案長度超過 `maxBytes` 上限且內容在該限制處被截斷時，會設定 `truncated`。1062`contents` 保存檔案文字，或在您要求 `encoding: 'base64'` 時保存 base64 資料；在這種情況下，回應的 `encoding` 欄位會設為 `'base64'`。`absPath` 是解析後的絕對路徑。當檔案超過 `maxBytes` 上限且內容在該限制處被截斷時，會設定 `truncated`。

1060 1063

1061<h4 id="what-readfile-can-read">1064<h4 id="what-readfile-can-read">

1062 `readFile()` 可以讀取哪些檔案1065 `readFile()` 可以讀取的內容

1063</h4>1066</h4>

1064 1067

1065`readFile()` 所提供的檔案範圍比 Read 工具更窄：1068`readFile()` 提供的檔案範圍比 Read 工具更窄：

1066 1069

1067* 位於工作階段某個工作目錄（例如 `cwd` 和 `additionalDirectories`）內的一般檔案1070* 位於工作階段某個工作目錄（例如 `cwd` 和 `additionalDirectories`）內的一般檔案

1068* 少數 Claude Code 為該工作階段所建立的自有檔案，例如工具結果1071* Claude Code 為該工作階段所保存的少數自有檔案，例如工具結果

1069 1072

1070`Read` 的拒絕和詢問規則仍會封鎖符合的路徑，且範圍廣泛的 `Read` 允許規則並不會讓 `readFile()` 能存取檔案系統的其餘部分。對於任何其他情況，呼叫會解析為 `null`。1073`Read` 的拒絕和詢問規則仍會封鎖符合的路徑，而廣泛的 `Read` 允許規則並不會將檔案系統的其餘部分開放給 `readFile()`。對於其他任何內容，呼叫都會解析為 `null`。

1071 1074

1072<h3 id="sdkcontrolreloadpluginsresponse">1075<h3 id="sdkcontrolreloadpluginsresponse">

1073 `SDKControlReloadPluginsResponse`1076 `SDKControlReloadPluginsResponse`

1074</h3>1077</h3>

1075 1078

1076[`reloadPlugins()`](#query-object) 的傳回類型。1079[`reloadPlugins()`](#query-object) 的回傳型別。

1077 1080

1078```typescript theme={null}1081```typescript theme={null}

1079type SDKControlReloadPluginsResponse = {1082type SDKControlReloadPluginsResponse = {

1098 1101

1099集合欄位描述呼叫之後的工作階段：1102集合欄位描述呼叫之後的工作階段：

1100 1103

1101* `commands`、`agents` 和 `mcpServers`：工作階段的命令、subagent 和 MCP 伺服器狀態，形狀與 `supportedCommands()`、`supportedAgents()` 和 `mcpServerStatus()` 所傳回的相同。`supportedAgents()` 會持續傳回初始化時擷取的清單，因此若要取得重新載入後的集合，請讀取此處的 `agents`1104* `commands`、`agents` 和 `mcpServers`：工作階段的命令、subagent 和 MCP 伺服器狀態，其形狀與 `supportedCommands()`、`supportedAgents()` 和 `mcpServerStatus()` 回傳的相同。`supportedAgents()` 會持續回傳初始化時擷取的清單，因此若要取得重新載入後的集合，請讀取此處的 `agents`

1102* `plugins`：每個已載入的外掛及其 `name` 和安裝 `path`。`version` 重複外掛資訊清單所宣告的內容，且由外掛作者控制，因此在信任之前請先驗證。當資訊清單未宣告時會省略此欄位1105* `plugins`：每個已載入的外掛及其 `name` 和安裝 `path`。`version` 重複外掛資訊清單所宣告的內容，由外掛作者控制，因此請在信任之前先驗證。當資訊清單未宣告時會省略

1103* `error_count`：載入外掛時發生的錯誤數1106* `error_count`：載入外掛時發生的錯誤數量

1104 1107

1105將 `{ holdOnCacheImpact: true }` 傳入 `reloadPlugins()`，即可暫緩會使對話提示快取失效的重新載入，而不套用它。Claude Code 會執行互動式 `/reload-plugins` 命令在[警告快取成本](/docs/zh-TW/prompt-caching#enabling-or-disabling-a-plugin)之前所進行的檢查。此選項需要 Agent SDK v0.3.268 或更新版本。早於 v2.1.268 的 Claude Code 執行檔（例如您以 `pathToClaudeCodeExecutable` 指向的執行檔）會忽略此選項並套用重新載入。1108將 `{ holdOnCacheImpact: true }` 傳遞給 `reloadPlugins()`，以暫緩會使對話提示快取失效的重新載入，而不是套用它。Claude Code 會執行互動式 `/reload-plugins` 命令在[警告快取成本](/docs/zh-TW/prompt-caching#enabling-or-disabling-a-plugin)之前所進行的檢查。此選項需要 Agent SDK v0.3.268 或更新版本。早於 v2.1.268 的 Claude Code 執行檔（例如您以 `pathToClaudeCodeExecutable` 指向的執行檔）會忽略此選項並套用重新載入。

1106 1109

1107當您傳入此選項時，請讀取 `held` 以了解發生了什麼：1110當您傳遞此選項時，請讀取 `held` 以了解發生了什麼：

1108 1111

1109* `true`：重新載入未套用，集合欄位描述的是工作階段目前仍維持的狀態。`cache_impact` 說明套用後會變更什麼。若仍要套用，請在不帶此選項的情況下再次呼叫 `reloadPlugins()`。1112* `true`：重新載入未套用，集合欄位描述的是工作階段目前仍維持的狀態。`cache_impact` 說明套用後會有哪些變更。若仍要套用，請在不帶此選項的情況下再次呼叫 `reloadPlugins()`。

1110* `false`：檢查未發現快取影響，且重新載入已套用。1113* `false`：檢查未發現快取影響，且重新載入已套用。

1111* 不存在：您未傳入此選項，或 Claude Code 執行檔早於 v2.1.268 並已套用重新載入。1114* 不存在：您未傳遞此選項，或 Claude Code 執行檔早於 v2.1.268 並已套用重新載入。

1112 1115

1113`cache_impact` 僅在 `held: true` 時存在。`mcp_servers_added` 和 `mcp_servers_removed` 以帶範圍的 `plugin:<plugin>:<server>` 名稱，指出重新載入會註冊或移除的外掛 MCP 伺服器。這些名稱由外掛作者撰寫，因此在顯示之前請先驗證。`lsp_tool_change` 說明套用後會新增或移除 LSP 工具，若兩者皆非則為 `null`。`may-` 形式表示檢查無法完整看到待處理的外掛集合。1116`cache_impact` 只會與 `held: true` 一起出現。`mcp_servers_added` 和 `mcp_servers_removed` 以具範圍的 `plugin:<plugin>:<server>` 名稱，指出重新載入會註冊或移除的外掛 MCP 伺服器。這些名稱由外掛作者撰寫，因此在顯示之前請先驗證。`lsp_tool_change` 說明套用後是否會新增或移除 LSP 工具，若兩者皆不會則為 `null`。`may-` 形式表示檢查無法完整看到待處理的外掛集合。

1114 1117

1115<h3 id="sdkcontrolreloadskillsresponse">1118<h3 id="sdkcontrolreloadskillsresponse">

1116 `SDKControlReloadSkillsResponse`1119 `SDKControlReloadSkillsResponse`

1117</h3>1120</h3>

1118 1121

1119[`reloadSkills()`](#query-object) 的傳回類型。1122[`reloadSkills()`](#query-object) 的回傳型別。

1120 1123

1121```typescript theme={null}1124```typescript theme={null}

1122type SDKControlReloadSkillsResponse = {1125type SDKControlReloadSkillsResponse = {

1124};1127};

1125```1128```

1126 1129

1127`skills` 以與 `supportedCommands()` 所傳回相同的 [`SlashCommand`](#slashcommand) 形狀，列出重新載入後可用的 skill。1130`skills` 列出重新載入後可用的 skill，其 [`SlashCommand`](#slashcommand) 形狀與 `supportedCommands()` 回傳的相同。

1128 1131

1129<h3 id="sdkcontrolreloadoutputstylesresponse">1132<h3 id="sdkcontrolreloadoutputstylesresponse">

1130 `SDKControlReloadOutputStylesResponse`1133 `SDKControlReloadOutputStylesResponse`

1131</h3>1134</h3>

1132 1135

1133[`reloadOutputStyles()`](#query-object) 的傳回類型。1136[`reloadOutputStyles()`](#query-object) 的回傳型別。

1134 1137

1135```typescript theme={null}1138```typescript theme={null}

1136type SDKControlReloadOutputStylesResponse = {1139type SDKControlReloadOutputStylesResponse = {

1144 `SDKControlMcpReadResourceResponse`1147 `SDKControlMcpReadResourceResponse`

1145</h3>1148</h3>

1146 1149

1147[`readMcpResource()`](#query-object) 的傳回類型，攜帶 MCP 伺服器的 `resources/read` 結果。需要 TypeScript Agent SDK v0.3.280 或更新版本。1150[`readMcpResource()`](#query-object) 的回傳型別，帶有 MCP 伺服器的 `resources/read` 結果。需要 TypeScript Agent SDK v0.3.280 或更新版本。

1148 1151

1149```typescript theme={null}1152```typescript theme={null}

1150type SDKControlMcpReadResourceResponse = {1153type SDKControlMcpReadResourceResponse = {

1158};1161};

1159```1162```

1160 1163

1161請傳入 `readMcpResource()` 由 `mcpServerStatus()` 所回報的伺服器名稱，以及一個 `ui://` URI，例如工具在其 [`_meta`](#mcpserverstatus) 中宣告的 `ui.resourceUri`。對於任何其他 URI 配置、您的應用程式自行託管的 [SDK MCP 伺服器](#createsdkmcpserver)，以及未連線的伺服器，呼叫都會被拒絕。當初始化訊息的 [`capabilities`](#sdksystemmessage) 包含 `mcp_read_resource_v1` 時即可使用。1164請將 `mcpServerStatus()` 所回報的伺服器名稱和一個 `ui://` URI 傳遞給 `readMcpResource()`，例如工具在其 [`_meta`](#mcpserverstatus) 中宣告的 `ui.resourceUri`。對於任何其他 URI 配置、您的應用程式自行託管的 [SDK MCP 伺服器](#createsdkmcpserver)，以及未連線的伺服器，呼叫都會被拒絕。當初始化訊息的 [`capabilities`](#sdksystemmessage) 包含 `mcp_read_resource_v1` 時即可使用。

1162 1165

1163每個 `contents` 項目都是伺服器所傳送的一個內容項目，但會移除 `com.anthropic/` 前綴下的任何 `_meta` 鍵，該前綴保留給 Claude Code 使用。`blob` 保存二進位項目的 base64 資料，而 `_meta` 是該項目自己的 `_meta`，MCP Apps 伺服器會在其中放置資源的 `ui.csp` 和 `ui.permissions`。1166每個 `contents` 項目都是伺服器所傳送的一個內容項目，但會移除 `com.anthropic/` 前綴下的任何 `_meta` 鍵，該前綴保留給 Claude Code 使用。`blob` 保存二進位項目的 base64 資料，而 `_meta` 是該項目本身的 `_meta`，MCP Apps 伺服器會在其中放置資源的 `ui.csp` 和 `ui.permissions`。

1164 1167

1165這些內容是不受信任的第三方 HTML，因此請在沙箱中呈現它們。1168這些內容是不受信任的第三方 HTML，因此請在沙箱中呈現。

1166 1169

1167<h3 id="agentdefinition">1170<h3 id="agentdefinition">

1168 `AgentDefinition`1171 `AgentDefinition`

1193| 欄位 | 必填 | 說明 |1196| 欄位 | 必填 | 說明 |

1194| :- | :- | :- |1197| :- | :- | :- |

1195| `description` | 是 | 以自然語言描述何時使用此 agent |1198| `description` | 是 | 以自然語言描述何時使用此 agent |

1196| `tools` | 否 | 允許的工具名稱陣列。若省略，則繼承每個[可供 subagent 使用的工具](/docs/zh-TW/sub-agents#available-tools)。若要將 Skills 預先載入 agent 的上下文，請使用 `skills` 欄位，而非在此列出 `'Skill'` |1199| `tools` | 否 | 允許的工具名稱陣列。若省略，則繼承每個[可供 subagent 使用的工具](/docs/zh-TW/sub-agents#available-tools)。若要將 Skills 預先載入 agent 的上下文，請使用 `skills` 欄位，而不是在此列出 `'Skill'` |

1197| `disallowedTools` | 否 | 要明確禁止此 agent 使用的工具名稱陣列。也接受 MCP 伺服器層級的模式：`mcp__server` 或 `mcp__server__*` 會移除該伺服器的所有工具，而 `mcp__*` 會移除任何伺服器的所有 MCP 工具 |1200| `disallowedTools` | 否 | 要為此 agent 明確禁止的工具名稱陣列。也接受 MCP 伺服器層級的模式：`mcp__server` 或 `mcp__server__*` 會移除該伺服器的每個工具，而 `mcp__*` 會移除任何伺服器的每個 MCP 工具 |

1198| `prompt` | 是 | agent 的系統提示詞 |1201| `prompt` | 是 | agent 的系統提示詞 |

1199| `model` | 否 | 此 agent 的模型覆寫。接受 `'fable'`、`'opus'`、`'sonnet'`、`'haiku'`、`'inherit'` 等別名，或完整的模型 ID。`'inherit'` 會使用主要模型。若省略，Claude Code 會依照 [subagent 模型順序](/docs/zh-TW/sub-agents#choose-a-model)選擇模型 |1202| `model` | 否 | 此 agent 的模型覆寫。接受別名，例如 `'fable'`、`'opus'`、`'sonnet'`、`'haiku'`、`'inherit'`，或完整的模型 ID。`'inherit'` 會使用主要模型。若省略，Claude Code 會依照 [subagent 模型順序](/docs/zh-TW/sub-agents#choose-a-model)選擇模型 |

1200| `mcpServers` | 否 | 此 agent 的 MCP 伺服器規格 |1203| `mcpServers` | 否 | 此 agent 的 MCP 伺服器規格 |

1201| `skills` | 否 | 要預先載入 agent 上下文的 skill 名稱陣列 |1204| `skills` | 否 | 要預先載入 agent 上下文的 skill 名稱陣列 |

1202| `initialPrompt` | 否 | 當此 agent 作為主執行緒 agent 執行時，自動提交為第一個使用者回合 |1205| `initialPrompt` | 否 | 當此 agent 作為主執行緒 agent 執行時，自動提交為第一個使用者回合 |

1203| `maxTurns` | 否 | 停止前的最大 agentic 回合數（API 往返次數） |1206| `maxTurns` | 否 | 停止前的最大 agentic 回合數（API 往返次數） |

1204| `background` | 否 | 被叫用時，以非阻塞的背景任務執行此 agent |1207| `background` | 否 | 被呼叫時，將此 agent 作為非阻塞的背景任務執行 |

1205| `omitClaudeMd` | 否 | 當此 agent 作為 subagent 執行時，在不載入使用者、專案和本機 CLAUDE.md 檔案的情況下執行；受管政策檔案仍會載入。適用於從 Agent 工具提示詞取得所需一切的 agent。當此 agent 作為主執行緒 agent 執行時會忽略。需要 TypeScript Agent SDK v0.3.271 或更新版本 |1208| `omitClaudeMd` | 否 | 當此 agent 作為 subagent 執行時，不載入使用者、專案和本機的 CLAUDE.md 檔案；受管政策檔案仍會載入。適用於從 Agent 工具提示詞取得所需一切的 agent。當此 agent 作為主執行緒 agent 執行時會忽略。需要 TypeScript Agent SDK v0.3.271 或更新版本 |

1206| `memory` | 否 | 此 agent 的記憶來源：`'user'`、`'project'` 或 `'local'` |1209| `memory` | 否 | 此 agent 的記憶來源：`'user'`、`'project'` 或 `'local'` |

1207| `effort` | 否 | 此 agent 的推理 effort 等級。接受具名等級或整數 |1210| `effort` | 否 | 此 agent 的推理 effort 等級。接受具名等級或整數 |

1208| `permissionMode` | 否 | 此 agent 內工具執行的權限模式。[subagent 繼承規則](/docs/zh-TW/agent-sdk/permissions#available-modes)決定其何時適用。請參閱 [`PermissionMode`](#permissionmode) |1211| `permissionMode` | 否 | 此 agent 內工具執行的權限模式。[subagent 繼承規則](/docs/zh-TW/agent-sdk/permissions#available-modes)決定何時套用。請參閱 [`PermissionMode`](#permissionmode) |

1209| `criticalSystemReminder_EXPERIMENTAL` | 否 | 實驗性：加入系統提示詞的關鍵提醒 |1212| `criticalSystemReminder_EXPERIMENTAL` | 否 | 實驗性：加入系統提示詞中的重要提醒 |

1210 1213

1211<h3 id="agentmcpserverspec">1214<h3 id="agentmcpserverspec">

1212 `AgentMcpServerSpec`1215 `AgentMcpServerSpec`

1224 `SettingSource`1227 `SettingSource`

1225</h3>1228</h3>

1226 1229

1227控制 SDK 從哪些以檔案系統為基礎的設定來源載入設定。1230控制 SDK 從哪些基於檔案系統的設定來源載入設定。

1228 1231

1229```typescript theme={null}1232```typescript theme={null}

1230type SettingSource = "user" | "project" | "local";1233type SettingSource = "user" | "project" | "local";

1233| 值 | 說明 | 位置 |1236| 值 | 說明 | 位置 |

1234| :- | :- | :- |1237| :- | :- | :- |

1238 1241

1239<h4 id="default-behavior">1242<h4 id="default-behavior">

1240 預設行為1243 預設行為

1241</h4>1244</h4>

1242 1245

1243當 `settingSources` 被省略或為 `undefined` 時，`query()` 會載入與 Claude Code CLI 相同的檔案系統設定：使用者、專案和本機。請參閱 [settingSources 不控制的項目](/docs/zh-TW/agent-sdk/claude-code-features#what-settingsources-does-not-control)，了解無論此選項為何都會被讀取的輸入，以及如何停用它們。1246當省略 `settingSources` 或其值為 `undefined` 時，`query()` 會載入與 Claude Code CLI 相同的檔案系統設定：使用者、專案與本機設定。關於無論此選項為何都會被讀取的輸入，以及如何停用它們，請參閱 [settingSources 不控制的項目](/docs/zh-TW/agent-sdk/claude-code-features#what-settingsources-does-not-control)。

1244 1247

1245<h4 id="why-use-settingsources">1248<h4 id="why-use-settingsources">

1246 為何使用 settingSources1249 為何使用 settingSources

1258});1261});

1259```1262```

1260 1263

1261**僅載入特定的設定來源：**1264**僅載入特定設定來源：**

1262 1265

1263```typescript theme={null}1266```typescript theme={null}

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

1272});1275});

1273```1276```

1274 1277

1275若要載入 CLAUDE.md 專案指令，請在 `settingSources` 中包含 `"project"`。請參閱[修改系統提示詞](/docs/zh-TW/agent-sdk/modifying-system-prompts#claude-md-files-for-project-level-instructions)，了解 CLAUDE.md 的載入如何與系統提示詞選項互動。1278若要載入 CLAUDE.md 專案指令，請在 `settingSources` 中包含 `"project"`。關於 CLAUDE.md 的載入如何與系統提示詞選項互動，請參閱[修改系統提示詞](/docs/zh-TW/agent-sdk/modifying-system-prompts#claude-md-files-for-project-level-instructions)。

1276 1279

1277<h4 id="settings-precedence">1280<h4 id="settings-precedence">

1278 設定優先順序1281 設定優先順序

1279</h4>1282</h4>

1280 1283

1281當載入多個來源時，設定會依以下優先順序合併（由高到低）：1284當載入多個來源時，設定會依以下優先順序合併（由高至低）：

1282 1285

12831. 本機設定（`.claude/settings.local.json`）12861. 本機設定（`.claude/settings.local.json`）

12842. 專案設定（`.claude/settings.json`）12872. 專案設定（`.claude/settings.json`）

12853. 使用者設定（`~/.claude/settings.json`）12883. 使用者設定（`~/.claude/settings.json`）

1286 1289

1287程式化選項（例如 `agents`、`allowedTools` 和 `settings`）會覆寫使用者、專案和本機檔案系統設定。受管理的政策設定優先於程式化選項。1290`agents`、`allowedTools` 與 `settings` 等程式化選項會覆寫使用者、專案與本機的檔案系統設定。受管理的政策設定優先於程式化選項。

1288 1291

1289<h3 id="permissionmode">1292<h3 id="permissionmode">

1290 `PermissionMode`1293 `PermissionMode`

1306 1309

1307用於控制工具使用的自訂權限函式型別。1310用於控制工具使用的自訂權限函式型別。

1308 1311

1309此函式是 SDK 中互動式權限提示的替代方案：只有在[權限評估流程](/docs/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated)判定需要提示時才會被呼叫。已由 `allowedTools` 項目、設定中的允許規則或權限模式（例如 `acceptEdits` 或 `bypassPermissions`）核准的工具呼叫，永遠不會呼叫此函式。若要管控每一個工具呼叫，請改用 [`PreToolUse` hook](/docs/zh-TW/agent-sdk/hooks)。1312此函式是 SDK 中互動式權限提示的替代方案：只有在[權限評估流程](/docs/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated)判定為需要提示時才會被呼叫。已由 `allowedTools` 項目、設定中的允許規則，或權限模式（例如 `acceptEdits` 或 `bypassPermissions`）核准的工具呼叫，永遠不會呼叫此函式。若要對每個工具呼叫進行把關，請改用 [`PreToolUse` hook](/docs/zh-TW/agent-sdk/hooks)。

1310 1313

1311允許規則不會預先核准[任何模式都不會自動核准的動作](/docs/zh-TW/permission-modes#actions-no-mode-auto-approves)；請參閱[權限的評估方式](/docs/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated)，了解其中哪些會到達回呼函式，以及在 `dontAsk` 和 `auto` 模式下會發生什麼情況。1314允許規則不會預先核准[任何模式都不會自動核准的動作](/docs/zh-TW/permission-modes#actions-no-mode-auto-approves)；關於其中哪些動作會送達回呼函式，以及在 `dontAsk` 與 `auto` 模式下會發生什麼情況，請參閱[權限的評估方式](/docs/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated)。

1312 1315

1313```typescript theme={null}1316```typescript theme={null}

1314type CanUseTool = (1317type CanUseTool = (

1331 1334

1332| 選項 | 型別 | 說明 |1335| 選項 | 型別 | 說明 |

1333| :- | :- | :- |1336| :- | :- | :- |

1335| `suggestions` | [`PermissionUpdate`](#permissionupdate)`[]` | 建議的權限更新，讓使用者不會再次因此工具而收到提示。Bash 提示會包含一個 [destination](#permissionupdatedestination) 為 `localSettings` 的建議，因此在 `updatedPermissions` 中回傳它會將規則寫入 `.claude/settings.local.json`，並跨工作階段保留。 |1338| `suggestions` | [`PermissionUpdate`](#permissionupdate)`[]` | 建議的權限更新，讓使用者不會再次因此工具而收到提示。Bash 提示會包含一個[目的地](#permissionupdatedestination)為 `localSettings` 的建議，因此在 `updatedPermissions` 中回傳它會將規則寫入 `.claude/settings.local.json`，並跨工作階段保留。 |

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

1344 1347

1345回呼函式通常會透過回傳 [`PermissionResult`](#permissionresult) 來處理請求，SDK 會將其作為 `control_response` 透過其傳輸通道寫回。只有在您的應用程式已透過自己的通道為此請求傳送了 `control_response`（並回傳 `requestId`）時，才應回傳 `null`；此時 SDK 會略過將回應寫入其傳輸通道。在其他任何情況下回傳 `null`，都會使工具呼叫無限期地處於封鎖狀態，因為永遠不會傳送 `control_response`，而權限提示也不會逾時。1348回呼函式通常透過回傳 [`PermissionResult`](#permissionresult) 來處理請求，SDK 會將其作為 `control_response` 透過其傳輸層寫回。只有在您的應用程式已透過自己的管道為此請求傳送 `control_response`（並回傳 `requestId`）時，才應回傳 `null`；此時 SDK 會略過將回應寫入其傳輸層。在其他任何情況下回傳 `null`，都會使工具呼叫無限期遭到阻擋，因為永遠不會傳送 `control_response`，而權限提示不會逾時。

1346 1349

1347`requestId` 選項和 `null` 回傳值需要 Claude Code v2.1.199 或更新版本。1350`requestId` 選項與 `null` 回傳值需要 Claude Code v2.1.199 或更新版本。

1348 1351

1349<h3 id="permissionresult">1352<h3 id="permissionresult">

1350 `PermissionResult`1353 `PermissionResult`

1480| :- | :- | :- |1483| :- | :- | :- |

1484 1487

1485**範例：**1488**範例：**

1486 1489

1491];1494];

1492```1495```

1493 1496

1494如需建立和使用外掛的完整資訊，請參閱[外掛](/docs/zh-TW/agent-sdk/plugins)。1497關於建立與使用外掛的完整資訊，請參閱[外掛](/docs/zh-TW/agent-sdk/plugins)。

1495 1498

1496<h2 id="message-types">1499<h2 id="message-types">

1497 訊息類型1500 訊息類型

3789};3792};

3790```3793```

3791 3794

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

3796

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

3793 3798

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

3795 3800

4839};4844};

4840```4845```

4841 4846

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

4843 4848

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

4845 Artifact4850 Artifact

5273 5278

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

5275 5280

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

5277 5282

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

5279 `McpServerStatusConfig`5284 `McpServerStatusConfig`

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

5461```5466```

5462 5467

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

5464 5469

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

5466 `SpawnedProcess`5471 `SpawnedProcess`

5531 5536

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

5533 5538

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

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

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

5537 5542

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

5852 tasks: {5857 tasks: {

5853 task_id: string;5858 task_id: string;

5854 task_type: string;5859 task_type: string;

5860 subagent_type?: string;

5855 description: string;5861 description: string;

5856 ambient?: boolean;5862 ambient?: boolean;

5857 }[];5863 }[];

5860};5866};

5861```5867```

5862 5868

5869`subagent_type` 在 [`task_type`](#sdktaskstartedmessage) 為 `"local_agent"` 的項目上命名 subagent 類型，例如 `general-purpose` 或自訂 subagent 的名稱。該欄位需要 Agent SDK v0.3.293 或更新版本。

5870

5863<h3 id="sdkthinkingtokensmessage">5871<h3 id="sdkthinkingtokensmessage">

5864 `SDKThinkingTokensMessage`5872 `SDKThinkingTokensMessage`

5865</h3>5873</h3>

agent-view.md +1 −0

Details

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

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

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

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

823 824

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

agents.md +1 −1

Details

20 20

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

22 22

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

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

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

26 26

amazon-bedrock.md +2 −2

Details

188 188

189快取涵蓋上述所有認證選項，除了 Amazon Bedrock API 金鑰（不使用提供者鏈）。若要改為在每個要求上解析鏈，請設定 [`CLAUDE_CODE_SKIP_AWS_CRED_CACHE=1`](/docs/zh-TW/env-vars)。189快取涵蓋上述所有認證選項，除了 Amazon Bedrock API 金鑰（不使用提供者鏈）。若要改為在每個要求上解析鏈，請設定 [`CLAUDE_CODE_SKIP_AWS_CRED_CACHE=1`](/docs/zh-TW/env-vars)。

190 190

191鏈的每次解析在 60 秒後逾時。如果鏈中的步驟停滯，例如等待無法接收的輸入的 `credential_process` 協助程式，要求會失敗並出現 [`AWS default-chain credential resolve timed out`](/docs/zh-TW/errors#aws-default-chain-credential-resolve-timed-out)。如果您的鏈執行合法需要更長時間的互動式登入，例如透過 `aws-vault` 之類的包裝程式進行瀏覽器型 SSO 搭配 MFA，請使用 [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/zh-TW/env-vars) 以毫秒為單位提高限制。在 v2.1.207 之前，停滯的認證解析會讓要求無限期等待。191填入快取的解析會在 60 秒後逾時。如果鏈中的步驟停滯，例如等待無法接收的輸入的 `credential_process` 協助程式，請求會失敗並出現 [`AWS default-chain credential resolve timed out`](/docs/zh-TW/errors#aws-default-chain-credential-resolve-timed-out)。如果您的鏈執行合法需要更長時間的互動式登入，例如透過 `aws-vault` 之類的包裝程式進行瀏覽器型 SSO 搭配 MFA，請使用 [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/zh-TW/env-vars) 以毫秒為單位提高限制。設定 `CLAUDE_CODE_SKIP_AWS_CRED_CACHE=1` 時，每個 API 請求都會在沒有此限制的情況下解析鏈。

192 192

193除了使用 Amazon Bedrock API 金鑰進行驗證外，[設定精靈](#sign-in-with-bedrock)會對它在驗證您的認證時進行的每個 AWS 呼叫，以及在每個模型檢查之前的認證查詢應用相同的限制。在認證驗證期間，超過限制的檢查會失敗並出現 [`Timed out after 60s waiting for AWS`](/docs/zh-TW/errors#bedrock-setup-verification-timed-out-waiting-for-aws)。193除了使用 Amazon Bedrock API 金鑰進行驗證外，[設定精靈](#sign-in-with-bedrock)會對它在驗證您的認證時進行的每個 AWS 呼叫，以及在每個模型檢查之前的認證查詢應用相同的限制。在認證驗證期間，超過限制的檢查會失敗並出現 [`Timed out after 60s waiting for AWS`](/docs/zh-TW/errors#bedrock-setup-verification-timed-out-waiting-for-aws)。

194 194

681 681

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

683 683

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

685 685

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

687 687

authentication.md +1 −1

Details

12 登入 Claude Code12 登入 Claude Code

13</h2>13</h2>

14 14

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

16 16

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

18 18

auto-mode-config.md +1 −1

Details

351}351}

352```352```

353 353

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

355 355

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

357claude auto-mode critique357claude auto-mode critique

chrome.md +1 −1

Details

343 343

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

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

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

claude-apps-gateway.md +20 −18

Details

57 快速入門57 快速入門

58</h2>58</h2>

59 59

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

61 61

62<Note>62<Note>

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

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

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

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

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

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

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

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

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

81 81

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

89 </Step>89 </Step>

90 90

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

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

93 </Step>93 </Step>

94 94

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

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

97 97

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

99 listen:99 listen:

120 upstreams:120 upstreams:

121 - provider: bedrock121 - provider: bedrock

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

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

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

125 125

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

130 auto_include_builtin_models: true130 auto_include_builtin_models: true

131 ```131 ```

132 132

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

134 134

135 <Note>135 <Note>

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

137 137

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

139 </Note>139 </Note>

140 </Step>140 </Step>

141 141

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

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

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

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

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

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

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

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

171 ```171 ```

172 172

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

174 174

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

176 176

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

178

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

178 180

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

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

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

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

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

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

196 198

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

198 200

204 206

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

206 208

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

208 210

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

210 212

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

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

251 </Step>253 </Step>

252 254

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

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

255 </Step>257 </Step>

256</Steps>258</Steps>

257 259

claude-apps-gateway-config.md +50 −9

Details

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

157 157

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

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

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

161 161

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

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

225 225

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

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

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

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

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

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

374| 其他任何地方 | 透過 `AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY` 和 `AWS_SESSION_TOKEN` 環境變數傳遞憑證，或在 `auth:` 中使用 `${VAR}` 擴展明確設定它們 |374| 其他任何地方 | 透過 `AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY` 和 `AWS_SESSION_TOKEN` 環境變數傳遞憑證，或在 `auth:` 中使用 `${VAR}` 擴展明確設定它們 |

375| 地區 | `region:` 是 API 端點地區。跨地區推論設定檔無論您選擇哪一個，都會跨地理位置 (US、EU、APAC) 路由。對於非美國地區或佈建輸送量 ARN，新增具有正確每上游 ID 的 [`models:`](#models) 區塊。 |375| 地區 | `region:` 是 API 端點地區。跨地區推論設定檔無論您選擇哪一個，都會跨地理位置 (US、EU、APAC) 路由。對於非美國地區或佈建輸送量 ARN，新增具有正確每上游 ID 的 [`models:`](#models) 區塊。 |

376 376

377<a id="apply-an-amazon-bedrock-guardrail" />

378

377<h5 id="apply-an-amazon-bedrock-guardrail">379<h5 id="apply-an-amazon-bedrock-guardrail">

378 應用 Amazon Bedrock 防護欄380 應用 Amazon Bedrock 防護欄

379</h5>381</h5>

919 921

920 兩個傳播時鐘適用：922 兩個傳播時鐘適用：

921 923

922 * **原則內容**：編輯原則並重新部署在連接的用戶端的下一個受管設定輪詢時到達，在一小時內，除了[只在下一次啟動時適用的變更](/docs/zh-TW/server-managed-settings#fetch-and-caching-behavior)924 * **原則內容**：編輯原則並重新部署在連接的 Claude Code 用戶端的下一個受管設定輪詢時到達，在一小時內，除了[只在下一次啟動時適用的變更](/docs/zh-TW/server-managed-settings#fetch-and-caching-behavior)

923 * **群組成員資格**：變更使用者的群組成員資格會變更哪個原則匹配他們。這在下一個工作階段重新鑄造時生效，意味著下一個無聲重新整理，受 `session.ttl_hours` 限制。925 * **群組成員資格**：變更使用者的群組成員資格會變更哪個原則匹配他們。這在下一個工作階段重新鑄造時生效，意味著下一個無聲重新整理，受 `session.ttl_hours` 限制。

926

927 Claude Desktop 依循[其自己的排程](#when-a-policy-change-reaches-claude-desktop)。

924</Note>928</Note>

925 929

926<h4 id="start-sessions-on-a-model-the-policy-allows">930<h4 id="start-sessions-on-a-model-the-policy-allows">

1084 需要 gateway 伺服器上的 Claude Code v2.1.203 或更新版本，以及明確的選擇加入：除非匹配使用者的原則攜帶 `desktop` 金鑰，否則 `/user/bootstrap` 返回 404。空的 `desktop: {}` 選擇加入原則，`match: {}` 基礎層上的 `desktop` 金鑰選擇加入每個繼承它的原則。稽核日誌將每個請求記錄為 `desktop_bootstrap.serve` 或 `desktop_bootstrap.denied`。1088 需要 gateway 伺服器上的 Claude Code v2.1.203 或更新版本，以及明確的選擇加入：除非匹配使用者的原則攜帶 `desktop` 金鑰，否則 `/user/bootstrap` 返回 404。空的 `desktop: {}` 選擇加入原則，`match: {}` 基礎層上的 `desktop` 金鑰選擇加入每個繼承它的原則。稽核日誌將每個請求記錄為 `desktop_bootstrap.serve` 或 `desktop_bootstrap.denied`。

1085</Note>1089</Note>

1086 1090

1087gateway 從匹配原則的 `cli` 區塊和頂層 gateway 設定衍生大部分回應：1091如果您不部署 Claude Desktop，完全從您的原則中省略 `desktop`；gateway 隨後為每個使用者從 `/user/bootstrap` 返回 404。

1092

1093<h5 id="settings-the-gateway-derives-for-claude-desktop">

1094 gateway 為 Claude Desktop 衍生的設定

1095</h5>

1096

1097gateway 從匹配原則的 `cli` 區塊和頂層 gateway 設定衍生大部分啟動回應：

1088 1098

1089* 模型清單，來自 `availableModels`。[Claude Desktop 中的延伸上下文](#extended-context-in-claude-desktop)涵蓋每個模型的 1M 上下文選項1099* 模型清單，來自 `availableModels`。[Claude Desktop 中的延伸上下文](#extended-context-in-claude-desktop)涵蓋每個模型的 1M 上下文選項

1090* 禁用的工具，來自裸工具名稱 `permissions.deny` 項目。如果您在原則的 `desktop` 區塊中設定 `disabledBuiltinTools`，gateway 提供您的值和衍生清單的聯集，因此您可以透過此方式禁用更多工具，但無法重新啟用您透過 `permissions.deny` 禁用的工具1100* 禁用的工具，來自裸工具名稱 `permissions.deny` 項目。如果您在原則的 `desktop` 區塊中設定 `disabledBuiltinTools`，gateway 提供您的值和衍生清單的聯集，因此您可以透過此方式禁用更多工具，但無法重新啟用您透過 `permissions.deny` 禁用的工具

1097 1107

1098gateway 省略沒有 Claude Desktop 等效項的金鑰，例如 `hooks` 和範圍權限規則（如 `Bash(npm *)`），來自啟動回應。1108gateway 省略沒有 Claude Desktop 等效項的金鑰，例如 `hooks` 和範圍權限規則（如 `Bash(npm *)`），來自啟動回應。

1099 1109

1100在 `cli` 旁邊新增選用的 `desktop` 區塊以直接設定 Claude Desktop 設定。從 Claude Desktop 的[受管設定參考](https://claude.com/docs/third-party/claude-desktop/configuration)寫入設定為平面金鑰名稱。省略 Claude Desktop 只從 MDM 或本機檔案讀取的金鑰，例如 `bootstrapUrl`；gateway 在啟動時拒絕它們。在 v2.1.232 之前，gateway 接受固定的 11 個功能閘道金鑰清單，例如 `chatTabEnabled` 和 `disableAutoUpdates`，並在啟動時拒絕每個其他金鑰。在 v2.1.227 之前，gateway 也在啟動時拒絕 `chatTabEnabled` 和 `chatAdvancedFileAnalysisEnabled`。1110<h5 id="set-claude-desktop-settings-directly">

1111 直接設定 Claude Desktop 設定

1112</h5>

1113

1114在 `cli` 旁邊新增選用的 `desktop` 區塊以直接設定 Claude Desktop 設定。從 Claude Desktop 的[受管設定參考](https://claude.com/docs/third-party/claude-desktop/configuration)寫入設定為平面金鑰名稱。省略 Claude Desktop 只從 MDM 或本機檔案讀取的金鑰，例如 `bootstrapUrl`；gateway 在啟動時拒絕它們。

1115

1116此範例為 `eng-contractors` 群組設定三個 Claude Desktop 金鑰，並搭配其 `cli` 設定：

1101 1117

1102```yaml theme={null}1118```yaml theme={null}

1103managed:1119managed:

1112 banner: { text: "Contractor build: internal use only" }1128 banner: { text: "Contractor build: internal use only" }

1113```1129```

1114 1130

1115每個金鑰都是選用的；Claude Desktop 為您省略的任何金鑰應用自己的預設值。gateway 在啟動時根據 Claude Desktop 本身使用的設定 schema 驗證每個 `desktop` 區塊，因此錯誤會在 gateway 啟動時顯示為命名金鑰的錯誤，而不是到達每個連接的桌面。當區塊包含以下內容時，gateway 在啟動時失敗：1131每個金鑰都是選用的；Claude Desktop 為您省略的任何金鑰應用自己的預設值。

1132

1133<h5 id="what-the-gateway-rejects-at-boot">

1134 gateway 在啟動時拒絕的內容

1135</h5>

1136

1137gateway 在啟動時根據 Claude Desktop 本身使用的設定 schema 驗證每個 `desktop` 區塊，因此錯誤會在 gateway 啟動時顯示為命名金鑰的錯誤，而不是到達每個連接的桌面。當區塊包含以下內容時，gateway 在啟動時失敗：

1116 1138

1117* 未知金鑰1139* 未知金鑰

1118* 已識別的金鑰，其值 Claude Desktop 會拒絕或無聲丟棄，例如空值或巢狀項目內的拼寫錯誤的子金鑰。在 v2.1.260 之前，gateway 無聲丟棄 `managedMcpServers` 或 `orgPluginSettings` 項目的巢狀物件內的拼寫錯誤欄位，而不是在啟動時失敗。1140* 已識別的金鑰，其值 Claude Desktop 會拒絕或無聲丟棄，例如空值或巢狀項目內的拼寫錯誤的子金鑰。在 v2.1.260 之前，gateway 無聲丟棄 `managedMcpServers` 或 `orgPluginSettings` 項目的巢狀物件內的拼寫錯誤欄位，而不是在啟動時失敗。

1121 1143

1122如果您使用已棄用的值或項目形狀，例如沒有 `transport` 的 `managedMcpServers` 項目，gateway 啟動並記錄命名替換的警告。1144如果您使用已棄用的值或項目形狀，例如沒有 `transport` 的 `managedMcpServers` 項目，gateway 啟動並記錄命名替換的警告。

1123 1145

1146在 v2.1.232 之前，gateway 接受固定的 11 個功能閘道金鑰清單，例如 `chatTabEnabled` 和 `disableAutoUpdates`，並在啟動時拒絕每個其他金鑰。在 v2.1.227 之前，gateway 也在啟動時拒絕 `chatTabEnabled` 和 `chatAdvancedFileAnalysisEnabled`。

1147

1148<h5 id="keys-that-need-a-later-gateway-or-claude-desktop-version">

1149 需要較新 gateway 或 Claude Desktop 版本的金鑰

1150</h5>

1151

1124gateway 根據與其安裝版本捆綁的 schema 驗證 `desktop` 區塊，如同 `cli` 區塊。要傳遞較新 Claude Desktop 版本引入的設定，請先升級 gateway。例如，`userPluginMarketplacesEnabled` 和 `userPluginUploadsEnabled` 需要 gateway 伺服器上的 Claude Code v2.1.260 或更新版本以及成員機器上的 Claude Desktop 1.37937.0 或更新版本。1152gateway 根據與其安裝版本捆綁的 schema 驗證 `desktop` 區塊，如同 `cli` 區塊。要傳遞較新 Claude Desktop 版本引入的設定，請先升級 gateway。例如，`userPluginMarketplacesEnabled` 和 `userPluginUploadsEnabled` 需要 gateway 伺服器上的 Claude Code v2.1.260 或更新版本以及成員機器上的 Claude Desktop 1.37937.0 或更新版本。

1125 1153

1126`blockReadsOutsideWorkingDirectories`、`disableBypassPermissionsMode`、`configRecheckIntervalMinutes` 和 `sshClientPath` 需要 gateway 伺服器上的 Claude Code v2.1.281 或更新版本。Microsoft 365 `managedMcpServers` 項目的 `microsoftAuthBroker` 的 `required` 值和 `continuousAccessEvaluation` 欄位也是如此。早於 `required` 值的 Claude Desktop 版本將其讀取為 `disabled`，因此只在每個成員的 Claude Desktop 支援它之後設定 `required`。Claude Desktop 的[受管設定參考](https://claude.com/docs/third-party/claude-desktop/configuration)列出首次讀取每個金鑰的版本。1154`blockReadsOutsideWorkingDirectories`、`disableBypassPermissionsMode`、`configRecheckIntervalMinutes` 和 `sshClientPath` 需要 gateway 伺服器上的 Claude Code v2.1.281 或更新版本。Microsoft 365 `managedMcpServers` 項目的 `microsoftAuthBroker` 的 `required` 值和 `continuousAccessEvaluation` 欄位也是如此。早於 `required` 值的 Claude Desktop 版本將其讀取為 `disabled`，因此只在每個成員的 Claude Desktop 支援它之後設定 `required`。Claude Desktop 的[受管設定參考](https://claude.com/docs/third-party/claude-desktop/configuration)列出首次讀取每個金鑰的版本。

1127 1155

1128如果您在原則的 `desktop` 區塊中設定 `orgPluginSettings`，gateway 以 Claude Desktop 1.15200.0 及更新版本讀取的陣列形式提供它。較舊的桌面忽略陣列並強制執行沒有外掛工具原則，因此在依賴它之前將成員更新到 1.15200.0 或更新版本。1156如果您在原則的 `desktop` 區塊中設定 `orgPluginSettings`，gateway 以 Claude Desktop 1.15200.0 及更新版本讀取的陣列形式提供它。較舊的桌面忽略陣列並強制執行沒有外掛工具原則，因此在依賴它之前將成員更新到 1.15200.0 或更新版本。

1129 1157

1130gateway 從原則的 `desktop` 區塊未設定的金鑰填充 `match: {}` 全部捕捉的 `desktop` 區塊，與它填充原則的 `cli` 區塊的方式相同。如果您在基礎和角色原則中都設定 `disabledBuiltinTools` 或 `builtinToolPolicy`，gateway 保留基礎的限制：1158<h5 id="how-a-role-policy-inherits-the-base-desktop-block">

1159 角色原則如何繼承基礎 `desktop` 區塊

1160</h5>

1161

1162對於原則的 `desktop` 區塊未設定的金鑰，gateway 從 `match: {}` 全部捕捉的 `desktop` 區塊填入，與它從基礎填入原則 `cli` 區塊的方式相同。如果您在基礎和角色原則中都設定 `disabledBuiltinTools` 或 `builtinToolPolicy`，gateway 保留基礎的限制：

1131 1163

1132* `disabledBuiltinTools`：gateway 使用基礎清單和原則清單的聯集1164* `disabledBuiltinTools`：gateway 使用基礎清單和原則清單的聯集

1133* `builtinToolPolicy`：如果您在基礎中將工具設定為 `allow` 以外的值，gateway 保留該值，即使您在角色原則中為相同工具設定 `allow`1165* `builtinToolPolicy`：如果您在基礎中將工具設定為 `allow` 以外的值，gateway 保留該值，即使您在角色原則中為相同工具設定 `allow`

1134 1166

1135對於每個其他金鑰，如果您在角色原則中設定它，gateway 使用角色原則的值。gateway 整體替換陣列或巢狀物件（例如 `banner`），因此如果您在角色原則中設定 `banner.text`，gateway 丟棄基礎的 `banner.backgroundColor`。1167對於每個其他金鑰，如果您在角色原則中設定它，gateway 使用角色原則的值。gateway 整體替換陣列或巢狀物件（例如 `banner`），因此如果您在角色原則中設定 `banner.text`，gateway 丟棄基礎的 `banner.backgroundColor`。

1136 1168

1137如果您不部署 Claude Desktop，完全從您的原則中省略 `desktop`；gateway 隨後為每個使用者從 `/user/bootstrap` 返回 404。1169<h5 id="when-a-policy-change-reaches-claude-desktop">

1170 Claude Desktop 何時套用原則變更

1171</h5>

1172

1173在您以變更後的原則重新部署 gateway 後，Claude Desktop 大多數設定只會在下次啟動時套用：

1174

1175* **已關閉**：Claude Desktop 在啟動時擷取啟動回應，因此變更從下次啟動開始套用

1176* **已開啟**：Claude Desktop 預設每 10 分鐘檢查一次回應是否變更，並在不重新啟動的情況下套用少數設定。對於其餘設定，例如 [`skillCreationEnabled`](https://claude.com/docs/third-party/claude-desktop/configuration#skillcreationenabled)，使用者會在側邊欄看到 **Relaunch Claude Desktop** 卡片，並保留先前的設定，直到重新啟動應用程式為止。預設 24 小時後，Claude Desktop 會顯示重新啟動對話框，並在閒置 2 分鐘後自行重新啟動

1177

1178若要縮短這 24 小時，請在原則的 `desktop` 區塊中設定 [`relaunchEnforcementHours`](https://claude.com/docs/third-party/claude-desktop/configuration#relaunchenforcementhours)。您需要 gateway 伺服器上的 Claude Code v2.1.260 或更新版本，以及成員機器上的 Claude Desktop 1.40609.0 或更新版本。設為 `0` 時，Claude Desktop 一發現變更就會顯示對話框。

1138 1179

1139<h4 id="extended-context-in-claude-desktop">1180<h4 id="extended-context-in-claude-desktop">

1140 Claude Desktop 中的延伸上下文1181 Claude Desktop 中的延伸上下文

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

Details

249 Postgres249 Postgres

250</h3>250</h3>

251 251

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

253

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

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

256

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

253 258

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

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

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

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

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

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

404| 日誌：`token exchange failed request_id=<id>: id_token missing email claim` | IdP 預設不在 id\_token 中包含 `email`。此拒絕僅在設定 `allowed_email_domains` 時觸發；沒有它，遺漏的電子郵件會建立沒有電子郵件的工作階段 | 設定 IdP 在 id\_token 中發出 `email`。Okta：將 `email` 新增到自訂授權伺服器的 ID token 宣告。Entra：在應用程式註冊上新增 `email` 作為選用宣告。PingFederate：啟用發出 `email` 的 OpenID Connect 原則。如果 IdP 從 userinfo 端點提供 `email` 但不會在 id\_token 中包含它，例如 Okta 組織授權伺服器，請設定 `oidc.userinfo_fallback: true`。 |410| 日誌：`token exchange failed request_id=<id>: id_token missing email claim` | IdP 預設不在 id\_token 中包含 `email`。此拒絕僅在設定 `allowed_email_domains` 時觸發；沒有它，遺漏的電子郵件會建立沒有電子郵件的工作階段 | 設定 IdP 在 id\_token 中發出 `email`。Okta：將 `email` 新增到自訂授權伺服器的 ID token 宣告。Entra：在應用程式註冊上新增 `email` 作為選用宣告。PingFederate：啟用發出 `email` 的 OpenID Connect 原則。如果 IdP 從 userinfo 端點提供 `email` 但不會在 id\_token 中包含它，例如 Okta 組織授權伺服器，請設定 `oidc.userinfo_fallback: true`。 |

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

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

Details

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

137 ```137 ```

138 138

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

140 140

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

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

169 </Step>169 </Step>

170 170

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

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

173 173

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

175 175

218 </Step>218 </Step>

219 219

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

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

222 222

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

224 224

225 * `public_url`：外部 `https://` 來源，非環回繫結時必需；請參閱 [`listen` 參考](/docs/zh-TW/claude-apps-gateway-config#listen)。gateway 僅從此值建置 IdP `redirect_uri` 和其發現文件，絕不從 `X-Forwarded-*` 標頭建置。225 * `public_url`：外部 `https://` 來源，非環回繫結時必需；請參閱 [`listen` 參考](/docs/zh-TW/claude-apps-gateway-config#listen)。gateway 僅從此值建置 IdP `redirect_uri` 和其發現文件，絕不從 `X-Forwarded-*` 標頭建置。

226 * `trusted_proxies`：前端的來源範圍。gateway 僅當 TCP 對等體在此清單中時才接受 `X-Forwarded-For`，然後在受信任的躍點之後遍歷鏈，因此每 IP 登入速率限制和稽核事件記錄開發人員 IP 而不是負載平衡器的。226 * `trusted_proxies`：前端的來源範圍。gateway 僅當 TCP 對等體在此清單中時才接受 `X-Forwarded-For`，然後在受信任的躍點之後遍歷鏈，因此每 IP 登入速率限制和稽核事件記錄開發人員 IP 而不是負載平衡器的。

227 227

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

229 229

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

231 231

261 - provider: bedrock261 - provider: bedrock

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

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

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

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

266 ```266 ```

267 267

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

289 </Note>289 </Note>

290 290

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

292 292

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

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

400 400

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

402 402

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

404 404

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

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

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

425 ```425 ```

426 426

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

428

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

428 430

429 任務在沒有公開 IP 的私有子網中執行，因此所有出站流量（到 Bedrock、您的 IdP、Secrets Manager、ECR 和 CloudWatch Logs）都透過 NAT 閘道。為了保持 Bedrock 流量不走公開路徑，建立 `bedrock-runtime` 介面 VPC 端點並將上游的 `base_url` 指向它，如 [Bedrock 上游參考](/docs/zh-TW/claude-apps-gateway-config#amazon-bedrock)所示；IdP 仍然需要網際網路出站。431 任務在沒有公開 IP 的私有子網中執行，因此所有出站流量（到 Bedrock、您的 IdP、Secrets Manager、ECR 和 CloudWatch Logs）都透過 NAT 閘道。為了保持 Bedrock 流量不走公開路徑，建立 `bedrock-runtime` 介面 VPC 端點並將上游的 `base_url` 指向它，如 [Bedrock 上游參考](/docs/zh-TW/claude-apps-gateway-config#amazon-bedrock)所示；IdP 仍然需要網際網路出站。

430 432

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

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

438 440

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

440 442

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

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

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

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

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

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

471 473

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

473 </Tab>475 </Tab>

474 </Tabs>476 </Tabs>

475 </Step>477 </Step>

claude-code-on-the-web.md +5 −3

Details

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

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

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

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

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

421 421

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

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

443 443

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

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

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

447 447

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

449

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

449 451

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

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

claude-directory.md +10 −12

Details

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

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

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

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

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

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

40 40

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

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

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

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

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

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

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

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

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

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

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

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

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

182paths:182paths:

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

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

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

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

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

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

203paths:203paths:

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

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

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

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

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

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

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

611 children: []611 children: []

1434 1434

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

1436 1436

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

1438 1438

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

1440 探索目錄1440 探索目錄

1452 1452

1453| 檔案 | 位置 | 用途 |1453| 檔案 | 位置 | 用途 |

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

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

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

1459 1459

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

1487<Note>1487<Note>

1488 有幾件事可以覆蓋您在這些檔案中放入的內容：1488 有幾件事可以覆蓋您在這些檔案中放入的內容：

1489 1489

1490 * 您的組織部署的[受管設定](/docs/zh-TW/server-managed-settings)優先於所有內容，除了[設定優先順序下的例外](/docs/zh-TW/settings#exceptions-to-managed-settings-precedence)1490 * 您的組織部署的[受管設定](/docs/zh-TW/server-managed-settings)優先於所有設定檔和 `--settings` 值，除了[設定優先順序下的例外](/docs/zh-TW/settings#exceptions-to-managed-settings-precedence)

1491 * CLI 旗標（如 `--permission-mode` 或 `--settings`）會覆蓋該工作階段的 `settings.json`1491 * CLI 旗標（如 `--permission-mode` 或 `--settings`）會覆蓋該工作階段的 `settings.json`

1492 * 某些環境變數優先於其等效設定，但這會有所不同：檢查[環境變數參考](/docs/zh-TW/env-vars)以了解每個變數1492 * 某些環境變數優先於其等效設定，但這會有所不同：檢查[環境變數參考](/docs/zh-TW/env-vars)以了解每個變數

1493 1493

1708 1708

1709傳遞 `--all` 而不是路徑以一次清除每個專案的狀態，這會直接刪除 `history.jsonl` 而不是篩選它。傳遞 `-i` 以逐項逐步執行刪除計畫。1709傳遞 `--all` 而不是路徑以一次清除每個專案的狀態，這會直接刪除 `history.jsonl` 而不是篩選它。傳遞 `-i` 以逐項逐步執行刪除計畫。

1710 1710

1711在指令碼中，請檢查輸出，而不要只看結束狀態。成功刪除計畫中所有內容的執行會以 `Purged N item(s)` 結尾。請將該行視為成功的標誌。

~~1712~~

1713該命令不會動到 `shell-snapshots/` 和 `backups/`，因為它們不屬於專案範圍，並會在計畫輸出中對其發出警告。如果有人曾在該機器上執行 [`/heapdump`](/docs/zh-TW/troubleshooting#high-cpu-or-memory-usage)，也請刪除它寫入的 `.heapsnapshot` 檔案。堆積快照包含完整對話以及該程序持有的任何憑證，而保留掃描和清除都不會觸及它。1711該命令不會動到 `shell-snapshots/` 和 `backups/`，因為它們不屬於專案範圍，並會在計畫輸出中對其發出警告。如果有人曾在該機器上執行 [`/heapdump`](/docs/zh-TW/troubleshooting#high-cpu-or-memory-usage)，也請刪除它寫入的 `.heapsnapshot` 檔案。堆積快照包含完整對話以及該程序持有的任何憑證，而保留掃描和清除都不會觸及它。

1714 1712

1715你也可以手動刪除上述任何應用程式資料路徑，除了 [保留的狀態檔案](#state-files-to-keep)。新工作階段不受影響。下表顯示你對過去工作階段失去的內容。1713你也可以手動刪除上述任何應用程式資料路徑，除了 [保留的狀態檔案](#state-files-to-keep)。新工作階段不受影響。下表顯示你對過去工作階段失去的內容。

claude-projects.md +7 −7

Details

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

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

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

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

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

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

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

65 65

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

92 92

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

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

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

96 96

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

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

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

397</h3>397</h3>

398 398

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

400 400

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

402 402

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

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

590</h2>590</h2>

591 591

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

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

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

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

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

cli-reference.md +3 −1

Details

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

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

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

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

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

95| `--fallback-model` | 當主要模型過載或無法使用時（例如已淘汰的模型），啟用自動回退到指定的模型。接受按順序嘗試的逗號分隔清單。請參閱[回退模型鏈](/docs/zh-TW/model-config#fallback-model-chains)。若要在工作階段之間保留鏈，請使用 [`fallbackModel` 設定](/docs/zh-TW/settings-reference#fallbackmodel)，此旗標會覆蓋它 | `claude --fallback-model sonnet,haiku` |97| `--fallback-model` | 當主要模型過載或無法使用時（例如已淘汰的模型），啟用自動回退到指定的模型。接受按順序嘗試的逗號分隔清單。請參閱[回退模型鏈](/docs/zh-TW/model-config#fallback-model-chains)。若要在工作階段之間保留鏈，請使用 [`fallbackModel` 設定](/docs/zh-TW/settings-reference#fallbackmodel)，此旗標會覆蓋它 | `claude --fallback-model sonnet,haiku` |

97| `--forward-subagent-text` | 在輸出串流中發出[子代理程式](/docs/zh-TW/sub-agents)文字和思考區塊作為 `assistant` 和 `user` 訊息，並設定 `parent_tool_use_id`，以便您可以重建每個子代理程式的文字記錄。沒有此旗標，Claude Code 會省略在[前景](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)中執行的子代理程式的文字和思考區塊。需要 `--print` 和 `--output-format stream-json`。Claude Code 也會轉發來自[巢狀子代理程式](/docs/zh-TW/sub-agents#let-subagents-spawn-their-own-subagents)的訊息，將 `parent_tool_use_id` 設定為啟動每個子代理程式的 Agent 或 Skill 工具呼叫的 ID；這需要 Claude Code v2.1.219 或更新版本，分叉的 skill 產生的子代理程式訊息以及巢狀分叉 skills 的訊息需要 v2.1.275 或更新版本。[`CLAUDE_CODE_FORWARD_SUBAGENT_TEXT`](/docs/zh-TW/env-vars) 環境變數啟用相同的行為。需要 Claude Code v2.1.211 或更新版本 | `claude -p --output-format stream-json --verbose --forward-subagent-text "query"` |99| `--forward-subagent-text` | 在輸出串流中將 [subagent](/docs/zh-TW/sub-agents) 的文字和思考區塊作為 `assistant` 和 `user` 訊息發出，並設定 `parent_tool_use_id`，以便您可以重建每個 subagent 的逐字稿。沒有此旗標時，Claude Code 會省略在[前景](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)中執行的 subagent 的文字和思考區塊。需要 `--print` 和 `--output-format stream-json`。關於巢狀 subagent、分叉的 skill 以及各自所需的版本，請參閱[追蹤 subagent 訊息](/docs/zh-TW/headless#follow-subagent-messages)。[`CLAUDE_CODE_FORWARD_SUBAGENT_TEXT`](/docs/zh-TW/env-vars) 環境變數會啟用相同的行為。需要 Claude Code v2.1.211 或更新版本 | `claude -p --output-format stream-json --verbose --forward-subagent-text "query"` |

98| `--from-pr` | 開啟工作階段選擇器，篩選至連結到特定提取要求的工作階段。接受 PR 編號、GitHub 或 GitHub Enterprise PR URL、GitLab 合併要求 URL 或 Bitbucket 提取要求 URL。當 Claude 建立提取要求時，工作階段會自動連結 | `claude --from-pr 123` |100| `--from-pr` | 開啟工作階段選擇器，篩選至連結到特定提取要求的工作階段。接受 PR 編號、GitHub 或 GitHub Enterprise PR URL、GitLab 合併要求 URL 或 Bitbucket 提取要求 URL。當 Claude 建立提取要求時，工作階段會自動連結 | `claude --from-pr 123` |

99| `--ide` | 如果恰好有一個有效的 IDE 可用，在啟動時自動連線到 IDE | `claude --ide` |101| `--ide` | 如果恰好有一個有效的 IDE 可用，在啟動時自動連線到 IDE | `claude --ide` |

cloud-environments.md +71 −55

Details

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

11</Note>11</Note>

12 12

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

14 14

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

16 16

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

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

60 60

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

62 62

63 <Frame>63 <Frame>

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

91 91

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

93 93

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

95 95

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

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

98</h3>98</h3>

99 99

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

101 101

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

103 103

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

105 需求105 需求

106</h4>106</h4>

107 107

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

109 109

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

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

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

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

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

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

116 116

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

118 新增認證118 新增機密

119</h4>119</h4>

120 120

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

122 122

123<Steps>123<Steps>

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

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

126 </Step>126 </Step>

127 127

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

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

130 130

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

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

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

134 134

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

136 </Step>136 </Step>

137 137

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

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

140 </Step>140 </Step>

141</Steps>141</Steps>

142 142

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

144 144

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

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

147</h4>147</h4>

148 148

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

150 150

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

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

153</h4>153</h4>

154 154

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

156 156

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

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

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

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

179 179

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

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

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

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

184 184

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

197 197

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

199 199

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

201 201

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

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

239 239

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

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

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

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

244 244

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

254registry.example.com254registry.example.com

255```255```

256 256

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

258 258

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

260 260

272* **Git 認證**：VM 內的 git 用戶端使用範圍認證，代理驗證並將其交換為您的實際 GitHub 令牌。272* **Git 認證**：VM 內的 git 用戶端使用範圍認證，代理驗證並將其交換為您的實際 GitHub 令牌。

273* **API 請求**：來自內建 GitHub 工具的請求，以及來自 [`proxy-injected` 預留位置](#work-with-github-issues-and-pull-requests)下的 `gh` 的請求，使用您的真實認證進行。273* **API 請求**：來自內建 GitHub 工具的請求，以及來自 [`proxy-injected` 預留位置](#work-with-github-issues-and-pull-requests)下的 `gh` 的請求，使用您的真實認證進行。

274* **推送限制**：代理伺服器會拒絕分支刪除，以及推送分支以外的任何內容（例如標籤）。它不限制推送可以更新哪些分支。若要進行此限制，請在 GitHub 上使用分支保護規則或規則集。274* **推送限制**：代理伺服器會拒絕分支刪除，以及推送分支以外的任何內容（例如標籤）。它不限制推送可以更新哪些分支。若要進行此限制，請在 GitHub 上使用分支保護規則或規則集。

275* **儲存庫範圍**：GitHub API 和發行資產請求僅到達附加到工作階段的儲存庫，因此下載來自未附加儲存庫的發行資產的設定指令碼會收到 403。275* **儲存庫範圍**：代理伺服器僅為附加到工作階段的儲存庫提供 GitHub API 請求服務。針對其他儲存庫的 API 請求會收到 403，其訊息以 `GitHub access to` 開頭並包含 `is not enabled for this session`。

276* **GraphQL 限制**：代理僅提供一組固定的 GraphQL 操作用於拉取請求工作流程。代理在 GraphQL 端點上拒絕所有其他內容，並顯示 403，說明 `This GraphQL query is not enabled for this session` 並命名 REST 後備 `gh api repos/{owner}/{repo}/...`。限制適用於通過代理的每個請求，無論您提供的認證如何，因此您設定的 `GH_TOKEN` 會收到相同的 403。Claude 無法通過代理到達僅存在於 GraphQL 中的 GitHub API，例如 Projects v2。276* **GraphQL 限制**：代理伺服器會以 403 拒絕對 GitHub GraphQL 端點的請求，其訊息以 `GitHub GraphQL is not available from Claude Code sessions` 開頭，並指出 REST 備援 `gh api repos/{owner}/{repo}/...`。使用 GraphQL 的 `gh` 子命令（例如 `gh pr` 和 `gh issue`）會收到相同的 403。限制適用於通過代理伺服器的每個請求，無論您提供的憑證如何，因此您設定的 `GH_TOKEN` 會收到相同的 403。Claude 無法通過代理伺服器到達僅存在於 GraphQL 中的 GitHub API，例如 Projects v2。

277 277

278來自公開儲存庫的已提交檔案通過 `raw.githubusercontent.com` 到達，[安全代理](#security-proxy)改為處理。該網域在預設[Trusted 清單](#default-allowed-domains)中，因此除非環境的[存取層級](#access-levels)排除它，否則這些檔案保持可到達。278來自公開儲存庫的已提交檔案通過 `raw.githubusercontent.com` 到達，[安全代理](#security-proxy)改為處理。該網域在預設[Trusted 清單](#default-allowed-domains)中，因此除非環境的[存取層級](#access-levels)排除它，否則這些檔案保持可到達。

279 279

285 285

286* 防止惡意請求286* 防止惡意請求

287* 速率限制和濫用防止287* 速率限制和濫用防止

288* 用於增強安全性的內容篩選

289* 所請求主機名稱的 DNS 層級稽核軌跡

290 288

291<h2 id="what’s-available-in-cloud-sessions">289<h2 id="what’s-available-in-cloud-sessions">

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

293</h2>291</h2>

294 292

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

296 294

297<Note>295<Note>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

323 321

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

325 323

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

325

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

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

328</h4>

329

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

331

332```bash theme={null}

333#!/bin/bash

334mkdir -p ~/.claude

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

336Use conventional commit messages.

337EOF

338```

339

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

341

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

327 343

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

329 已安裝的工具345 已安裝的工具

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

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

347 363

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

349 365

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

351 367

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

355 371

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

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

358</h3>374</h3>

359 375

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

361 377

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

363 379

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

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

366 382

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

368 384

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

370 386

371GitHub 的 [`gh` CLI](https://cli.github.com) 已預先安裝。如果您需要內建工具未涵蓋的 `gh` 命令，例如 `gh release` 或 `gh workflow run`，請要求 Claude 執行它。`gh` 會自動讀取 `GH_TOKEN`，因此您不需要執行 `gh auth login`。387GitHub 的 [`gh` CLI](https://cli.github.com) 已預先安裝。如果您需要內建工具未涵蓋的 GitHub 操作，請要求 Claude 使用 `gh api` 呼叫 REST API。使用 REST API 的 `gh` 子命令（例如 `gh workflow list`）也能運作。代理伺服器會[拒絕使用 GraphQL 的子命令](#github-proxy)，例如 `gh pr` 和 `gh issue`。`gh` 會自動讀取 `GH_TOKEN`，因此您不需要執行 `gh auth login`。

372 388

373<h3 id="link-output-back-to-the-session">389<h3 id="link-output-back-to-the-session">

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

375</h3>391</h3>

376 392

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

378 394

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

380 396

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

382 398

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

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

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

389</h3>405</h3>

390 406

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

392 408

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

394 執行測試410 執行測試

395</h4>411</h4>

396 412

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

398 414

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

400 啟動服務416 啟動服務

430* 16 GB 的 RAM446* 16 GB 的 RAM

431* 30 GB 的磁碟447* 30 GB 的磁碟

432 448

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

434 450

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

436 時間限制452 時間限制

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

442 458

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

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

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

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

447 463

code-review.md +1 −1

Details

386 調整努力和引數386 調整努力和引數

387</h3>387</h3>

388 388

389傳遞[努力級別](/docs/zh-TW/model-config#adjust-effort-level)以權衡覆蓋範圍和信心。在 `low` 和 `medium` 時，審查僅報告它最有信心的發現結果，因此您看到的誤報較少；`high` 到 `max` 擴大覆蓋範圍，可能包括審查不太確定的發現結果。389傳遞 [effort 等級](/docs/zh-TW/model-config#adjust-effort-level)以在覆蓋範圍和信心之間取捨。在 `low` 時，審查會報告它最有信心的發現結果，因此您看到的誤報較少。從 `medium` 到 `max`，審查會擴大覆蓋範圍。

390 390

391當您未輸入級別時，審查會重用您上次輸入的 `low` 到 `max` 級別，即使在較早的工作階段中，Claude Code 會顯示通知，例如 `重用 high 努力，您上次輸入的級別`。輸入級別，例如 `/code-review high`，以變更稍後執行重用的內容；您在非互動式 `-p` 執行中傳遞的級別不會更新它。`ultra` 既不更新也不使用記住的級別。如果您從未輸入過級別，審查會使用工作階段的當前努力。在 v2.1.223 之前，沒有級別的 `/code-review` 始終使用工作階段的當前努力。391當您未輸入級別時，審查會重用您上次輸入的 `low` 到 `max` 級別，即使在較早的工作階段中，Claude Code 會顯示通知，例如 `重用 high 努力，您上次輸入的級別`。輸入級別，例如 `/code-review high`，以變更稍後執行重用的內容；您在非互動式 `-p` 執行中傳遞的級別不會更新它。`ultra` 既不更新也不使用記住的級別。如果您從未輸入過級別，審查會使用工作階段的當前努力。在 v2.1.223 之前，沒有級別的 `/code-review` 始終使用工作階段的當前努力。

392 392

context-window.md +11 −11

Details

1586 1586

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

1588 1588

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

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

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

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

1599 1599

1600| 機制 | 壓縮後 |1600| 機制 | 壓縮後 |

1601| :- | :- |1601| :- | :- |

1602| 系統提示和輸出風格 | 兩者仍然適用 |1602| 系統提示詞和輸出風格 | 兩者仍然適用 |

1603| 專案根目錄 CLAUDE.md 和未限定範圍的規則 | 從磁碟重新注入 |1603| 專案根目錄 CLAUDE.md 和未限定範圍的規則 | 從磁碟重新注入 |

1604| 自動記憶 | 從磁碟重新注入 |1604| 自動記憶 | 從磁碟重新注入 |

1605| [Git 狀態快照](/docs/zh-TW/settings-reference#includegitinstructions) | Claude Code 從您的儲存庫讀取新的快照 |1605| [Git 狀態快照](/docs/zh-TW/settings-reference#includegitinstructions) | Claude Code 從您的儲存庫讀取新的快照 |

1606| Claude 在[計畫模式](/docs/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode)中編寫的計畫 | 從磁碟重新注入 |1606| Claude 在 [plan mode](/docs/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 中編寫的計畫 | 從磁碟重新注入 |

1608| 子目錄中的巢狀 CLAUDE.md | Claude Code [視需要](/docs/zh-TW/memory#how-claude-md-files-load)重新載入它們 |1608| 子目錄中的巢狀 CLAUDE.md | Claude Code [視需要](/docs/zh-TW/memory#how-claude-md-files-load)重新載入它們 |

1609| Claude 讀取或編輯的檔案 | Claude Code 重新讀取最多五個，最近修改的優先 |1609| Claude 讀取或編輯的檔案 | Claude Code 重新讀取最多五個，最近修改的優先 |

1610| 已叫用的技能主體 | 重新注入，每個技能上限為 5,000 個權杖，總計 25,000 個權杖；最舊的優先刪除 |1610| 已叫用的 skill 主體 | 重新注入，每個 skill 上限為 5,000 個 token，總計 25,000 個 token；最舊的優先刪除 |

1611| [背景命令](/docs/zh-TW/interactive-mode#background-bash-commands)和背景[子代理](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background) | 保持執行。Claude Code 提醒 Claude 哪些仍在執行，以便它不會啟動重複的 |1611| [背景命令](/docs/zh-TW/interactive-mode#background-bash-commands)和背景 [subagent](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background) | 保持執行。Claude Code 提醒 Claude 哪些仍在執行，以便它不會啟動重複的 |

1612| hooks 較早新增的上下文 | 與其餘對話一起總結 |1612| hook 較早新增的上下文 | 與其餘對話一起總結 |

1613| 符合 `compact` 來源的 [SessionStart hooks](/docs/zh-TW/hooks-guide#re-inject-context-after-compaction) | Claude Code 執行它們並將其輸出新增到壓縮的上下文中 |1613| 符合 `compact` 來源的 [SessionStart hook](/docs/zh-TW/hooks-guide#re-inject-context-after-compaction) | Claude Code 執行它們並將其輸出新增到壓縮的上下文中 |

1614 1614

1615壓縮後立即，Claude Code 重新讀取 Claude 在工作階段中讀取或編輯的最多五個檔案，選擇最近修改的檔案。超過 5,000 個權杖的檔案會以路徑參考的形式返回，不含其內容，顯示為 `Referenced file` 而不是 `Read`。1615壓縮後立即，Claude Code 重新讀取 Claude 在工作階段中讀取或編輯的最多五個檔案，選擇最近修改的檔案。超過 5,000 個 token 的檔案會以路徑參考的形式返回，不含其內容，顯示為 `Referenced file` 而不是 `Read`。

1616 1616

1617路徑限定範圍的規則和巢狀 CLAUDE.md 檔案在讀取其觸發檔案時載入到訊息歷史記錄中，因此壓縮會將它們與其他所有內容一起總結。如果規則必須在壓縮後保持，請刪除 `paths:` frontmatter 或將其移至專案根目錄 CLAUDE.md。1617路徑限定範圍的規則和巢狀 CLAUDE.md 檔案在 Claude 讀取、寫入或編輯其觸發檔案時載入到訊息歷史記錄中，因此壓縮會將它們與其他所有內容一起總結。如果規則必須在壓縮後保持，請刪除 `paths:` frontmatter 或將其移至專案根目錄 CLAUDE.md。

1618 1618

1619技能主體在壓縮後重新注入，但大型技能會被截斷以適應每個技能的上限，一旦超過總預算，最舊的已叫用技能就會被刪除。截斷會保留檔案的開頭，因此請將最重要的指示放在 `SKILL.md` 的頂部附近。1619skill 主體在壓縮後重新注入，但大型 skill 會被截斷以適應每個 skill 的上限，一旦超過總預算，最舊的已叫用 skill 就會被刪除。截斷會保留檔案的開頭，因此請將最重要的指示放在 `SKILL.md` 的頂部附近。

1620 1620

1621<h2 id="when-your-context-fills-up">1621<h2 id="when-your-context-fills-up">

1622 當您的上下文填滿時1622 當您的上下文填滿時

1632* **在任務之間清除**：切換到不相關的工作時運行 `/clear`。舊對話會擠出您接下來需要的文件，並在每條消息上花費令牌。1632* **在任務之間清除**：切換到不相關的工作時運行 `/clear`。舊對話會擠出您接下來需要的文件，並在每條消息上花費令牌。

1633* **委託大型讀取**：將研究發送給[子代理](/docs/zh-TW/sub-agents)，以便文件內容保留在其上下文視窗中，而不是您的。1633* **委託大型讀取**：將研究發送給[子代理](/docs/zh-TW/sub-agents)，以便文件內容保留在其上下文視窗中，而不是您的。

1634 1634

1635如果您需要更大的視窗而不是更小的對話，Fable 模型、Sonnet 5 及更高版本、Opus 4.6 及更高版本以及 Sonnet 4.6 支持 100 萬令牌上下文視窗。請參閱[擴展上下文](/docs/zh-TW/model-config#extended-context)以了解按計劃的可用性以及如何選擇 `[1m]` 模型變體。壓縮在更大的限制下以相同方式工作。1635如果您需要更大的視窗而不是更小的對話，Fable 模型、Sonnet 5 及更高版本、Haiku 5.5、Opus 4.6 及更高版本以及 Sonnet 4.6 支援 100 萬 token 上下文視窗。請參閱[擴展上下文](/docs/zh-TW/model-config#extended-context)以了解按方案的可用性以及如何選擇 `[1m]` 模型變體。壓縮在更大的限制下以相同方式運作。

1636 1636

1637Sonnet 5.5 和 Sonnet 5 以 1M 上下文視窗運行，沒有 `[1m]` 變體可選擇。請參閱[Sonnet 5.5 和 Sonnet 5 上下文視窗](/docs/zh-TW/model-config#sonnet-5-5-and-sonnet-5-context-window)以了解其自動壓縮閾值，以及[閘道後面的上下文視窗](/docs/zh-TW/model-config#context-window-behind-a-gateway)以了解當您將 `ANTHROPIC_BASE_URL` 設定為 [LLM 閘道](/docs/zh-TW/llm-gateway)時 Claude Code 如何調整視窗大小。1637Sonnet 5.5 和 Sonnet 5 以 1M 上下文視窗運行，沒有 `[1m]` 變體可選擇。請參閱[Sonnet 5.5 和 Sonnet 5 上下文視窗](/docs/zh-TW/model-config#sonnet-5-5-and-sonnet-5-context-window)以了解其自動壓縮閾值，以及[閘道後面的上下文視窗](/docs/zh-TW/model-config#context-window-behind-a-gateway)以了解當您將 `ANTHROPIC_BASE_URL` 設定為 [LLM 閘道](/docs/zh-TW/llm-gateway)時 Claude Code 如何調整視窗大小。

1638 1638

costs.md +2 −2

Details

361 361

362延伸思考預設為啟用，因為它可以顯著改善複雜規劃和推理任務的效能。思考 token 會作為輸出 token 計費，預設預算可能是每個請求數萬個 token，取決於模型。362延伸思考預設為啟用，因為它可以顯著改善複雜規劃和推理任務的效能。思考 token 會作為輸出 token 計費，預設預算可能是每個請求數萬個 token，取決於模型。

363 363

364對於不需要深度推理的較簡單任務，您可以透過 `/effort` 或在 `/model` 中降低 [effort 等級](/docs/zh-TW/model-config#adjust-effort-level)，或在 `/config` 中停用思考，以降低成本。您無法在 Opus 5.5、Sonnet 5.5 或 Fable 模型上關閉思考，它們始終使用延伸思考。364對於不需要深度推理的較簡單任務，您可以透過 `/effort` 或在 `/model` 中降低 [effort 等級](/docs/zh-TW/model-config#adjust-effort-level)，或在 `/config` 中停用思考，以降低成本。您無法在 Opus 5.5、Sonnet 5.5、Haiku 5.5 或 Fable 模型上關閉思考，它們始終使用延伸思考。

365 365

366在具有[固定思考預算](/docs/zh-TW/model-config#adaptive-reasoning-and-fixed-thinking-budgets)的模型上，您也可以透過設定 `MAX_THINKING_TOKENS` [環境變數](/docs/zh-TW/env-vars)來降低預算，例如 `MAX_THINKING_TOKENS=8000`。自適應推理模型會忽略非零預算，因此在這些模型上請改用 effort 等級。366在具有[固定思考預算](/docs/zh-TW/model-config#adaptive-reasoning-and-fixed-thinking-budgets)的模型上，您也可以透過設定 `MAX_THINKING_TOKENS` [環境變數](/docs/zh-TW/env-vars)來降低預算，例如 `MAX_THINKING_TOKENS=8000`。自適應推理模型會忽略非零預算，因此在這些模型上請改用 effort 等級。

367 367

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

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

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

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

398 398

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

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

deep-links.md +8 −2

Details

166 註冊和支援的平台166 註冊和支援的平台

167</h2>167</h2>

168 168

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

170 170

171| 平台 | 處理程式位置 |171| 平台 | 處理程式位置 |

172| - | - |172| - | - |

176 176

177處理程式在偵測到的終端機模擬器中啟動 Claude Code。在 macOS 上，Claude Code 記住您最近互動式工作階段中的終端機並重複使用它，支援 iTerm2、Ghostty、kitty、Alacritty、WezTerm 和 Terminal.app。在 Linux 上，它遵守 `$TERMINAL` 環境變數，然後是 `x-terminal-emulator`，然後是常見模擬器的列表。在 Windows 上，它優先選擇 Windows Terminal，然後是 PowerShell，然後是 `cmd.exe`。177處理程式在偵測到的終端機模擬器中啟動 Claude Code。在 macOS 上，Claude Code 記住您最近互動式工作階段中的終端機並重複使用它，支援 iTerm2、Ghostty、kitty、Alacritty、WezTerm 和 Terminal.app。在 Linux 上，它遵守 `$TERMINAL` 環境變數，然後是 `x-terminal-emulator`，然後是常見模擬器的列表。在 Windows 上，它優先選擇 Windows Terminal，然後是 PowerShell，然後是 `cmd.exe`。

178 178

179要完全防止註冊，請在 `settings.json` 中將 [`disableDeepLinkRegistration`](/docs/zh-TW/settings-reference#disabledeeplinkregistration) 設定為 `"disable"`。要在整個組織中強制執行此操作，使用者無法重新啟用它，請改為在[受管設定](/docs/zh-TW/server-managed-settings)中設定它。179要完全防止註冊，請在 `settings.json` 中將 [`disableDeepLinkRegistration`](/docs/zh-TW/settings-reference#disabledeeplinkregistration) 設定為 `"disable"`。要在整個組織中強制執行此操作，使用者無法重新啟用它，請改為在[受管設定](/docs/zh-TW/server-managed-settings)中設定它。Claude Code 的 `disableDeepLinkRegistration` 設定僅涵蓋 `claude-cli://` 連結。

180 180

181<h2 id="open-a-vs-code-tab-instead-of-a-terminal">181<h2 id="open-a-vs-code-tab-instead-of-a-terminal">

182 開啟 VS Code 標籤而不是終端機182 開啟 VS Code 標籤而不是終端機

184 184

185VS Code 擴充功能在 `vscode://anthropic.claude-code/open` 註冊自己的處理程式，它開啟一個 Claude Code 編輯器標籤而不是終端機視窗。請參閱[從其他工具啟動 VS Code 標籤](/docs/zh-TW/vs-code#launch-a-vs-code-tab-from-other-tools)以了解該 URL 的參數。185VS Code 擴充功能在 `vscode://anthropic.claude-code/open` 註冊自己的處理程式，它開啟一個 Claude Code 編輯器標籤而不是終端機視窗。請參閱[從其他工具啟動 VS Code 標籤](/docs/zh-TW/vs-code#launch-a-vs-code-tab-from-other-tools)以了解該 URL 的參數。

186 186

187<h2 id="open-a-claude-desktop-session-on-an-ssh-connection">

188 透過 SSH 連線開啟 Claude Desktop 工作階段

189</h2>

190

191Claude Desktop 會自行處理其 `claude://` 連結。若要透過 SSH 在遠端機器上開啟 Desktop 工作階段，請參閱[從連結開啟 SSH 工作階段](/docs/zh-TW/desktop#open-an-ssh-session-from-a-link)。

192

187<h2 id="troubleshooting">193<h2 id="troubleshooting">

188 疑難排解194 疑難排解

189</h2>195</h2>

desktop.md +59 −8

Details

108 自動模式可用性108 自動模式可用性

109</h4>109</h4>

110 110

111自動模式適用於 Anthropic API 上的所有使用者，需要 Claude Opus 4.6 或更新版本、Sonnet 4.6 或更新版本，或 [Fable 模型](/docs/zh-TW/model-config#work-with-fable)。組織管理員可以使用[受管設定](#managed-settings)中的 `disableAutoMode` 鍵關閉自動模式。111自動模式適用於 Anthropic API 上的所有使用者，需要 Claude Opus 4.6 或更新版本、Sonnet 4.6 或更新版本、Haiku 5.5，或 [Fable 模型](/docs/zh-TW/model-config#work-with-fable)。組織管理員可以使用[受管設定](#managed-settings)中的 `disableAutoMode` 鍵關閉自動模式。

112 112

113在將 Desktop 路由到 Google Cloud 的 Agent Platform 的 Enterprise 部署中，自動模式也預設可用；請參閱 [Bedrock、Agent Platform 或 Foundry 上的自動模式](/docs/zh-TW/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)以了解支援的模型。113在將 Desktop 路由到 Google Cloud 的 Agent Platform 的 Enterprise 部署中，自動模式也預設可用；請參閱 [Bedrock、Agent Platform 或 Foundry 上的自動模式](/docs/zh-TW/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)以了解支援的模型。

114 114

225 在終端機中執行命令225 在終端機中執行命令

226</h3>226</h3>

227 227

228整合終端機讓您在工作階段旁執行命令，而無需切換到另一個應用程式。點擊工作階段標題列中的 **Terminal**，或在 macOS 或 Windows 上按 **Ctrl+\`**。終端機在您工作階段的工作目錄中開啟，並與 Claude 共用相同的環境，因此 `npm test` 或 `git status` 等命令會看到 Claude 正在編輯的相同檔案。若要開啟第二個終端機標籤，請點擊終端機窗格標題中的 **+** 或右鍵點擊聊天中的資料夾以選擇 **Open in terminal**。終端機僅在本機工作階段中可用。228整合終端機讓您在工作階段旁執行命令，而無需切換到另一個應用程式。點擊工作階段標題列中的 **Terminal**，或在 macOS 或 Windows 上按 **Ctrl+\`**。終端機在您工作階段的工作目錄中開啟，並與 Claude 共用相同的環境，因此 `npm test` 或 `git status` 等命令會看到 Claude 正在編輯的相同檔案。若要開啟第二個終端機標籤，請點擊終端機窗格標題中的 **+** 或右鍵點擊聊天中的資料夾以選擇 **Open in terminal**。終端機可在本機和 [SSH](#ssh-sessions) 工作階段中使用。

229 229

230<h3 id="open-and-edit-files">230<h3 id="open-and-edit-files">

231 開啟和編輯檔案231 開啟和編輯檔案

743 743

744若要在任何平台上為本機會話和開發伺服器設定環境變數，請在提示框中開啟環境下拉式選單，將滑鼠懸停在 **Local** 上，然後點擊齒輪圖示以開啟本機環境編輯器。您在此處儲存的變數會在您的機器上加密儲存，並適用於您啟動的每個本機會話和預覽伺服器。您也可以將變數新增到 `~/.claude/settings.json` 檔案中的 `env` 金鑰，儘管這些僅到達 Claude 會話而不是開發伺服器。有關支援的變數的完整清單，請參閱[環境變數](/docs/zh-TW/env-vars)。744若要在任何平台上為本機會話和開發伺服器設定環境變數，請在提示框中開啟環境下拉式選單，將滑鼠懸停在 **Local** 上，然後點擊齒輪圖示以開啟本機環境編輯器。您在此處儲存的變數會在您的機器上加密儲存，並適用於您啟動的每個本機會話和預覽伺服器。您也可以將變數新增到 `~/.claude/settings.json` 檔案中的 `env` 金鑰，儘管這些僅到達 Claude 會話而不是開發伺服器。有關支援的變數的完整清單，請參閱[環境變數](/docs/zh-TW/env-vars)。

745 745

746[Extended thinking](/docs/zh-TW/model-config#extended-thinking) 預設啟用，這改進了複雜推理任務的效能，但使用額外的 tokens。在 Anthropic API 上，在本機環境編輯器中將 `MAX_THINKING_TOKENS` 設定為 `0` 以關閉思考；這對 Opus 5.5、Sonnet 5.5 或 Fable 模型沒有影響，它們始終使用 extended thinking。在 Anthropic API 上關閉思考後，Claude Code 會傳送 effort `high` 而不是更高的級別給它知道[不接受該組合](/docs/zh-TW/errors#effort-isnt-available-with-thinking-turned-off)的模型，例如 Opus 5。746[延伸思考](/docs/zh-TW/model-config#extended-thinking)預設啟用，這改進了複雜推理任務的效能，但使用額外的 token。在 Anthropic API 上，在本機環境編輯器中將 `MAX_THINKING_TOKENS` 設定為 `0` 以關閉思考；這對 Opus 5.5、Sonnet 5.5、Haiku 5.5 或 Fable 模型沒有影響，它們始終使用延伸思考。在 Anthropic API 上關閉思考後，Claude Code 會傳送 effort `high` 而不是更高的級別給它知道[不接受該組合](/docs/zh-TW/errors#effort-isnt-available-with-thinking-turned-off)的模型，例如 Opus 5。

747 747

748在具有[自適應推理](/docs/zh-TW/model-config#adjust-effort-level)的模型上，對於正值的 `MAX_THINKING_TOKENS`，Claude Code 會忽略該數值本身，因為改由自適應推理控制思考深度。在 Opus 4.6 和 Sonnet 4.6 上，將 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 設定為 `1` 以使用固定思考預算；Fable 模型、Sonnet 5 及更新版本，以及 Opus 4.7 及更新版本始終使用自適應推理，沒有固定預算模式。748在具有[自適應推理](/docs/zh-TW/model-config#adjust-effort-level)的模型上，對於正值的 `MAX_THINKING_TOKENS`，Claude Code 會忽略該數值本身，因為改由自適應推理控制思考深度。在 Opus 4.6 和 Sonnet 4.6 上，將 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 設定為 `1` 以使用固定思考預算；Fable 模型、Sonnet 5 及更新版本、Haiku 5.5，以及 Opus 4.7 及更新版本始終使用自適應推理，沒有固定預算模式。

749 749

750<h4 id="local-sessions-on-managed-devices">750<h4 id="local-sessions-on-managed-devices">

751 受管設備上的本機會話751 受管設備上的本機會話

783 783

784遠端機器必須執行 Linux 或 macOS。桌面應用程式會在您第一次連接時自動在遠端機器上安裝 Claude Code。連接後，SSH 會話支援權限模式、連接器、plugins 和 MCP servers。784遠端機器必須執行 Linux 或 macOS。桌面應用程式會在您第一次連接時自動在遠端機器上安裝 Claude Code。連接後，SSH 會話支援權限模式、連接器、plugins 和 MCP servers。

785 785

786<h4 id="open-an-ssh-session-from-a-link">

787 從連結開啟 SSH 工作階段

788</h4>

789

790`claude://code/new` 連結會開啟 Desktop 的新工作階段頁面，且可以指定一個 SSH 連線。將此類連結放在操作手冊、儀表板或 wiki 頁面中，即可開啟已針對正確機器和資料夾設定好的 Desktop。對於會移除此類連結的平台，請參閱[連結顯示為純文字而無法點擊](/docs/zh-TW/deep-links#the-link-renders-as-plain-text-instead-of-being-clickable)。

791

792SSH 連結需要 Claude Desktop v2.110.0 或更新版本。

793

794以下連結指定了 `build.example.com` 上的使用者 `dev`、連接埠 2222 和資料夾 `/srv/payments`，並填入提示詞：

795

796```text theme={null}

797claude://code/new?ssh_host=dev%40build.example.com&ssh_port=2222&ssh_folder=/srv/payments&q=Investigate%20the%20failed%20deploy

798```

799

800SSH 連結接受以下參數，其中只有 `ssh_host` 為必要：

801

802| 參數 | 值 |

803| :- | :- |

804| `ssh_host` | `host` 或 `user@host`，寫法與 **SSH host** 欄位相同。值不能以 `-` 開頭，且主機部分只接受字母、數字、`.`、`_`、`:` 和 `-` |

805| `ssh_port` | 1 到 65535 之間的連接埠號碼 |

806| `ssh_folder` | 遠端機器上的資料夾。以 `/` 或 `~/` 開頭，或使用 `~` |

807| `q` | 提示詞輸入框的 URL 編碼文字 |

808

809來自 `~/.ssh/config` 的別名只對擁有該項目的人才能作為 `ssh_host` 使用。若要符合其他人已有的連線，請讓連結使用與該連線相同的使用者、主機和連接埠。

810

811當您開啟連結時，Desktop 會在選擇連線前要求您確認：

812

813* **您已有的連線**：如果主機、使用者和連接埠與您的某個連線相符，Desktop 會詢問是否使用它，並顯示該連線的名稱和主機，以及連結中指定的資料夾（如果有）。

814* **新連線**：否則 Desktop 會開啟新增 SSH 連線的對話框。當您新增連線時，Desktop 會在儲存任何內容前詢問是否連接，並顯示連結中的主機，以及連結中指定的連接埠和資料夾（如果有）。

815

816在您確認之前，Desktop 不會儲存連結中的主機、連接埠或資料夾，也不會以它們選擇或開啟連線。如果已選擇了某個 SSH 連線，新工作階段頁面仍可自行連接到該連線，就像沒有連結時一樣，即使連結指定的是相同主機也是如此。連結無法攜帶金鑰檔案、密碼或命令。

817

818任何人都可以撰寫連結，因此請檢查它填入的內容：

819

820* **確認之前**：檢查主機和資料夾。

821* **傳送之前**：檢查提示詞和所選的環境。

822

823Desktop 會在連結開啟時填入提示詞，取代您尚未傳送的任何文字，且絕不會替您傳送。它將提示詞視為純文字，因此開頭的 `/` 或 `!` 以及 `@` 檔案提及不會作為命令或提及生效。如果您取消，提示詞會保留在輸入框中，且您先前選擇的環境不會改變。

824

825連結不會繞過 [`sshHostAllowlist`](#restrict-which-ssh-hosts-users-can-connect-to)。Desktop 會在連接時檢查允許清單。

826

827如果連結開啟 Desktop 時沒有出現關於連線的對話框，請檢查是否為以下原因之一：

828

829* **您已登出**：請登入，然後再次開啟連結。

830* **另一個對話框已開啟**：請將其關閉，然後再次開啟連結。

831* **連結無效**：Desktop 會顯示一則訊息說明需要修正的內容，且不會填入提示詞。

832* **Desktop 版本早於 v2.110.0**：較早的版本會忽略 SSH 參數，並僅以提示詞開啟新工作階段頁面。

833* **SSH 工作階段已關閉**：如果您的管理員將允許清單設定為空陣列，Desktop 會拒絕 SSH 連結。

834

786<h4 id="pre-configure-ssh-connections-for-your-team">835<h4 id="pre-configure-ssh-connections-for-your-team">

787 為您的團隊預先配置 SSH 連線836 為您的團隊預先配置 SSH 連線

788</h4>837</h4>

805}854}

806```855```

807 856

808每個項目都需要 `id`、`name` 和 `sshHost`。`sshPort` 和 `sshIdentityFile` 欄位是選用的。使用者也可以將 `sshConfigs` 新增到他們自己的 `~/.claude/settings.json`，這是透過對話框新增的連線的儲存位置。857每個項目都需要 `id`、`name` 和 `sshHost`。`sshPort` 和 `sshIdentityFile` 欄位是選用的。使用者也可以將 `sshConfigs` 新增到他們自己的 `~/.claude/settings.json`。

809 858

810<h4 id="restrict-which-ssh-hosts-users-can-connect-to">859<h4 id="restrict-which-ssh-hosts-users-can-connect-to">

811 限制使用者可以連接的 SSH 主機860 限制使用者可以連接的 SSH 主機

867| `sshHostAllowlist` | 將 [SSH 工作階段](#restrict-which-ssh-hosts-users-can-connect-to)限制在已解析主機名稱符合這些模式之一的主機。空陣列會停用 SSH 工作階段。僅從受管設定讀取。 |916| `sshHostAllowlist` | 將 [SSH 工作階段](#restrict-which-ssh-hosts-users-can-connect-to)限制在已解析主機名稱符合這些模式之一的主機。空陣列會停用 SSH 工作階段。僅從受管設定讀取。 |

868| `disableDesktopLocalSessions` | 設定為 `true` 以關閉[在裝置上執行的 Code 工作階段](#local-sessions-on-managed-devices)，僅保留連線到其他主機的 SSH 工作階段和雲端工作階段。該值必須是 JSON 布林值 `true`。僅從受管設定讀取。需要 Claude Desktop v1.37937.0 或更新版本。 |917| `disableDesktopLocalSessions` | 設定為 `true` 以關閉[在裝置上執行的 Code 工作階段](#local-sessions-on-managed-devices)，僅保留連線到其他主機的 SSH 工作階段和雲端工作階段。該值必須是 JSON 布林值 `true`。僅從受管設定讀取。需要 Claude Desktop v1.37937.0 或更新版本。 |

918| `disableSshSavedPasswords` | 設定為 `true` 以停止 Desktop 提供記住 SSH 密碼的選項，並停止使用或顯示先前已儲存的密碼。開啟此設定不會刪除這些密碼。僅從受管設定讀取。需要 Claude Desktop v1.49585.0 或更新版本。 |

869| `managedMcpServers` | 將 MCP 伺服器設定推送給所有使用者。僅在第三方 (3P) Desktop 部署中可用。在每個項目中，設定 `"http"`、`"sse"` 或 `"stdio"` 的傳輸方式、連線詳細資訊，以及可選的 `toolPolicy` 對應，以限制使用者可以叫用該伺服器的哪些工具。請透過受管設定檔案、MDM 或 Claude apps gateway 原則的 [`desktop` 區塊](/docs/zh-TW/claude-apps-gateway-config#claude-desktop-overlay)傳遞，因為第三方部署不會收到管理員主控台設定。若要透過閘道傳遞，您需要在閘道伺服器上使用 Claude Code v2.1.232 或更新版本。這是桌面應用程式自己的鍵；Claude Code 會讀取自己的[同名受管設定](/docs/zh-TW/managed-mcp#provide-servers-through-managed-settings)，其項目結構不同。 |919| `managedMcpServers` | 將 MCP 伺服器設定推送給所有使用者。僅在第三方 (3P) Desktop 部署中可用。在每個項目中，設定 `"http"`、`"sse"` 或 `"stdio"` 的傳輸方式、連線詳細資訊，以及可選的 `toolPolicy` 對應，以限制使用者可以叫用該伺服器的哪些工具。請透過受管設定檔案、MDM 或 Claude apps gateway 原則的 [`desktop` 區塊](/docs/zh-TW/claude-apps-gateway-config#claude-desktop-overlay)傳遞，因為第三方部署不會收到管理員主控台設定。若要透過閘道傳遞，您需要在閘道伺服器上使用 Claude Code v2.1.232 或更新版本。這是桌面應用程式自己的鍵；Claude Code 會讀取自己的[同名受管設定](/docs/zh-TW/managed-mcp#provide-servers-through-managed-settings)，其項目結構不同。 |

870 920

871哪些受管設定會套用到 Desktop 工作階段，取決於該工作階段執行的位置。模型限制（例如 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection)）在 Desktop 的 Claude Code 工作階段中的強制方式與終端機 CLI 相同；請參閱[使用介面涵蓋範圍](/docs/zh-TW/model-config#surface-coverage)。921哪些受管設定會套用到 Desktop 工作階段，取決於該工作階段執行的位置。模型限制（例如 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection)）在 Desktop 的 Claude Code 工作階段中的強制方式與終端機 CLI 相同；請參閱[使用介面涵蓋範圍](/docs/zh-TW/model-config#surface-coverage)。

872 922

873* **此機器上的本機工作階段**：部署到磁碟的受管設定檔案會套用。當工作階段使用[符合條件的登入或金鑰](/docs/zh-TW/server-managed-settings#platform-availability)向 Anthropic 的 API 進行身分驗證時，透過管理員主控台遠端推送的受管設定也會套用到這些工作階段，並遵循與終端機 CLI 相同的[設定優先順序](/docs/zh-TW/settings#settings-precedence)。923* **此機器上的本機工作階段**：部署到磁碟的受管設定檔案會套用。當工作階段使用[符合條件的登入或金鑰](/docs/zh-TW/server-managed-settings#platform-availability)向 Anthropic 的 API 進行身分驗證時，透過管理員主控台遠端推送的受管設定也會套用到這些工作階段，並遵循與終端機 CLI 相同的[設定優先順序](/docs/zh-TW/settings#settings-precedence)。

874* **[雲端工作階段](#cloud-sessions)**：接收[伺服器管理的設定](/docs/zh-TW/server-managed-settings)；裝置部署的檔案不會套用到它們，因為它們在 Anthropic 管理的 VM 上執行。路由到[自託管環境](/docs/zh-TW/self-hosted-environments)的工作階段也會讀取執行器映像中的受管設定檔案。[Claude Code 如何結合受管來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)說明該檔案何時適用。924* **[雲端工作階段](#cloud-sessions)**：接收[伺服器管理的設定](/docs/zh-TW/server-managed-settings)；裝置部署的檔案不會套用到它們，因為它們在 Anthropic 管理的 VM 上執行。路由到[自託管環境](/docs/zh-TW/self-hosted-environments)的工作階段也會讀取執行器映像中的受管設定檔案。[Claude Code 如何結合受管來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)說明該檔案何時適用。

875* **[SSH 工作階段](#ssh-sessions)**：工作階段從遠端主機讀取受管設定檔案。Desktop 本身會從本機的受管設定讀取 `sshConfigs`、`sshHostAllowlist` 和 `disableDesktopLocalSessions`。925* **[SSH 工作階段](#ssh-sessions)**：工作階段從遠端主機讀取受管設定檔案。Desktop 本身會從本機的受管設定讀取 `sshConfigs`、`sshHostAllowlist`、`disableSshSavedPasswords` 和 `disableDesktopLocalSessions`。

876* **[Cowork](https://claude.com/docs/cowork/overview) 工作階段**：在此機器上的 Cowork 工作階段中，即使使用者以 Team 或 Enterprise 帳戶登入，Claude Code 也永遠不會擷取管理員主控台設定，並且會讀取部署到機器的原則，除非您的 Claude Desktop 設定設有 `requireCoworkFullVmSandbox`。遠端 Cowork 工作階段兩者皆不會接收。請參閱[原則適用的位置和時間](/docs/zh-TW/managed-settings#where-and-when-a-policy-applies)以了解哪些裝置檔案會套用到 Cowork，以及 [MCP 權限規則](/docs/zh-TW/permissions#mcp)以了解 `Bash` 和 `WebFetch` 規則如何套用於 Cowork 的工具。926* **[Cowork](https://claude.com/docs/cowork/overview) 工作階段**：在此機器上的 Cowork 工作階段中，即使使用者以 Team 或 Enterprise 帳戶登入，Claude Code 也永遠不會擷取管理員主控台設定，並且會讀取部署到機器的原則，除非您的 Claude Desktop 設定設有 `requireCoworkFullVmSandbox`。遠端 Cowork 工作階段兩者皆不會接收。請參閱[原則適用的位置和時間](/docs/zh-TW/managed-settings#where-and-when-a-policy-applies)以了解哪些裝置檔案會套用到 Cowork，以及 [MCP 權限規則](/docs/zh-TW/permissions#mcp)以了解 `Bash` 和 `WebFetch` 規則如何套用於 Cowork 的工具。

877 927

878在本機和 SSH 工作階段中，桌面應用程式會直接將每個使用者已連線的 claude.ai 連接器傳遞給 Claude Code。無論您使用哪個設定來源或檔案位置，任何 MCP 設定或 `managed-mcp.json` 都不會影響這些連接器。若要在這些工作階段中封鎖連接器的工具，請使用您組織的[連接器工具控制](/docs/zh-TW/mcp#organization-controls-on-connector-tools)。[連接器如何到達 Claude Code](/docs/zh-TW/mcp#how-connectors-reach-claude-code) 說明在每種工作階段中由哪些設定管理連接器。928在本機和 SSH 工作階段中，桌面應用程式會直接將每個使用者已連線的 claude.ai 連接器傳遞給 Claude Code。無論您使用哪個設定來源或檔案位置，任何 MCP 設定或 `managed-mcp.json` 都不會影響這些連接器。若要在這些工作階段中封鎖連接器的工具，請使用您組織的[連接器工具控制](/docs/zh-TW/mcp#organization-controls-on-connector-tools)。[連接器如何到達 Claude Code](/docs/zh-TW/mcp#how-connectors-reach-claude-code) 說明在每種工作階段中由哪些設定管理連接器。

885 裝置管理原則935 裝置管理原則

886</h3>936</h3>

887 937

888IT 團隊可以透過 macOS 上的 MDM 或 Windows 上的群組原則來管理桌面應用程式。可用的原則包括啟用或停用 Claude Code 功能、控制自動更新和設定自訂部署 URL。938IT 團隊可以透過 macOS 上的 MDM、Windows 上的群組原則或 Linux 上的原則檔案來管理桌面應用程式。可用的原則包括啟用或停用 Claude Code 功能、控制 macOS 和 Windows 上的自動更新，以及設定自訂部署 URL。

889 939

890* **macOS**：使用 Jamf 或 Kandji 等工具透過 `com.anthropic.claudefordesktop` 偏好設定網域進行設定940* **macOS**：使用 Jamf 或 Kandji 等工具透過 `com.anthropic.claudefordesktop` 偏好設定網域進行設定

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

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

892 943

893<h3 id="network-access-requirements">944<h3 id="network-access-requirements">

894 網路存取需求945 網路存取需求

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

1093 1144

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

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

1096 1147

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

1098 1149

desktop-ios-simulator.md +1 −1

Details

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

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

94 94

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

96 96

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

98 98

env-vars.md +334 −330

Details

93}93}

94```94```

95 95

96Claude Code 會依原樣將這些值複製到其環境中。這些值不會經過任何 shell 處理，因此 `~` 或 `$HOME` 等簡寫會保持輸入時的樣子。對於接受路徑的變數（例如 `CLAUDE_CONFIG_DIR`），請寫入絕對路徑：`"CLAUDE_CONFIG_DIR": "/home/you/.claude-work"`。

96您選擇的檔案控制變數套用的對象：98您選擇的檔案控制變數套用的對象：

97 99

98| 檔案 | 套用對象 |100| 檔案 | 套用對象 |

124 變數126 變數

125</h2>127</h2>

126 128

127逾時、token 預算和重試次數等數值變數，除了純數字之外，也接受科學記號和數字分隔符寫法，除非該變數的列中註明只接受純數字。例如，Claude Code 會將 `2e3` 讀為 2000，將 `64_000` 讀為 64000。在 v2.1.211 之前，這些寫法可能會在無任何提示的情況下設定成小得多的值，例如 `1e6` 會將逾時設為 1。129數值型變數（例如逾時、token 預算與重試次數）除了純數字之外，也接受科學記號與數字分隔符號寫法，除非該變數所在列註明僅接受純數字。例如，Claude Code 會將 `2e3` 讀取為 2000，將 `64_000` 讀取為 64000。在 v2.1.211 之前，這些寫法可能會在沒有任何提示的情況下設定為小得多的值，例如 `1e6` 會將逾時設定為 1。

128 130

129<Note>131<Note>

130 對於開啟或關閉某項行為的變數，設定 `1`、`true`、`yes` 或 `on` 即可開啟，設定 `0`、`false`、`no` 或 `off` 即可關閉，大小寫不拘。132 對於開啟或關閉某項行為的變數，設定 `1`、`true`、`yes` 或 `on` 即可開啟，設定 `0`、`false`、`no` 或 `off` 即可關閉，不區分大小寫。

131 133

132 有些變數只會判斷您是否有設定它們，因此任何非空值（包括 `0`）都會開啟該行為；若要關閉該行為，需取消設定該變數或將其設為空值。以下變數採用這種方式：134 部分變數只會判斷您是否有設定它們，因此任何非空值（包括 `0`）都會開啟該行為，若要關閉該行為，需取消設定該變數或將其設為空值。以下變數即以此方式運作：

133 135

134 * `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`136 * `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`

135 * `DISABLE_TELEMETRY`137 * `DISABLE_TELEMETRY`

138 * `FALLBACK_FOR_ALL_PRIMARY_MODELS`140 * `FALLBACK_FOR_ALL_PRIMARY_MODELS`

139 * `IS_DEMO`141 * `IS_DEMO`

140 142

141 另有一個變數有其自己的規則：`FORCE_HYPERLINK` 讀取的是數字，因此只有 `0` 會將其關閉。每個變數的列中也會說明其各自的規則。143 另有一個變數有其專屬規則：`FORCE_HYPERLINK` 讀取的是數字，因此只有 `0` 會將其關閉。每個變數所在列也會說明其自身的規則。

142</Note>144</Note>

143 145

144| 變數 | 用途 |146| 變數 | 用途 |

145| :- | :- |147| :- | :- |

146| `ANTHROPIC_API_KEY` | 以 `X-Api-Key` 標頭傳送的 API 金鑰。設定後，即使您已登入，也會使用此金鑰，而非您的 Claude Pro、Max、Team 或 Enterprise 訂閱。在非互動模式（`-p`）下，只要存在此金鑰就一律會使用。在互動模式下，系統會在此金鑰覆寫您的訂閱之前提示您核准一次。若要改用您的訂閱，請執行 `unset ANTHROPIC_API_KEY` |148| `ANTHROPIC_API_KEY` | 以 `X-Api-Key` 標頭傳送的 API 金鑰。設定後，即使您已登入，也會使用此金鑰，而非您的 Claude Pro、Max、Team 或 Enterprise 訂閱。在非互動模式（`-p`）中，只要有此金鑰就一律使用。在互動模式中，系統會提示您核准一次該金鑰，之後它才會取代您的訂閱。若要改用您的訂閱，請執行 `unset ANTHROPIC_API_KEY` |

148| `ANTHROPIC_AWS_API_KEY` | [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 的工作區 API 金鑰，於 AWS Console 中產生。以 `x-api-key` 傳送，且優先於 AWS SigV4 |150| `ANTHROPIC_AWS_API_KEY` | [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 的工作區 API 金鑰，於 AWS Console 中產生。以 `x-api-key` 傳送，且優先於 AWS SigV4 |

149| `ANTHROPIC_AWS_BASE_URL` | 覆寫 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 端點 URL。用於自訂區域，或透過 [LLM 閘道](/docs/zh-TW/llm-gateway)路由時。預設為 `https://aws-external-anthropic.{region}.api.aws`。Claude Code 解析區域時，採用[與 Amazon Bedrock 相同的優先順序](/docs/zh-TW/amazon-bedrock#3-configure-claude-code) |151| `ANTHROPIC_AWS_BASE_URL` | 覆寫 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 端點 URL。用於自訂區域，或透過 [LLM 閘道](/docs/zh-TW/llm-gateway) 路由時。預設為 `https://aws-external-anthropic.{region}.api.aws`。Claude Code 會以[與 Amazon Bedrock 相同的優先順序](/docs/zh-TW/amazon-bedrock#3-configure-claude-code)解析區域 |

150| `ANTHROPIC_AWS_WORKSPACE_ID` | [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 的必要項目。每個請求都會以 `anthropic-workspace-id` 標頭傳送 |152| `ANTHROPIC_AWS_WORKSPACE_ID` | [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 的必要設定。每個請求都會以 `anthropic-workspace-id` 標頭傳送 |

151| `ANTHROPIC_BASE_URL` | 覆寫 API 端點，以透過代理伺服器或閘道路由請求。設為非第一方主機時，[MCP Tool Search](/docs/zh-TW/mcp#scale-with-mcp-tool-search) 預設為停用。如果您的代理伺服器會轉送 `tool_reference` 區塊，請設定 `ENABLE_TOOL_SEARCH=true`。自 v2.1.196 起，當此變數指向 `api.anthropic.com` 以外的主機時，[Remote Control](/docs/zh-TW/remote-control#requirements) 會停用，與其在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上的行為一致 |153| `ANTHROPIC_BASE_URL` | 覆寫 API 端點，以透過代理伺服器或閘道路由請求。設定為非第一方主機時，[MCP Tool Search](/docs/zh-TW/mcp#scale-with-mcp-tool-search) 預設為停用。若您的代理伺服器會轉送 `tool_reference` 區塊，請設定 `ENABLE_TOOL_SEARCH=true`。自 v2.1.196 起，當此變數指向 `api.anthropic.com` 以外的主機時，[Remote Control](/docs/zh-TW/remote-control#requirements) 會停用，與其在 Amazon Bedrock、Google Cloud's Agent Platform 及 Microsoft Foundry 上的行為一致 |

152| `ANTHROPIC_BEDROCK_BASE_URL` | 覆寫 Amazon Bedrock 端點 URL。用於自訂 Amazon Bedrock 端點，或透過 [LLM 閘道](/docs/zh-TW/llm-gateway)路由時。請參閱 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) |154| `ANTHROPIC_BEDROCK_BASE_URL` | 覆寫 Amazon Bedrock 端點 URL。用於自訂 Amazon Bedrock 端點，或透過 [LLM 閘道](/docs/zh-TW/llm-gateway) 路由時。請參閱 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) |

153| `ANTHROPIC_BEDROCK_MANTLE_BASE_URL` | 覆寫 Amazon Bedrock Mantle 端點 URL。請參閱 [Mantle 端點](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint) |155| `ANTHROPIC_BEDROCK_MANTLE_BASE_URL` | 覆寫 Amazon Bedrock Mantle 端點 URL。請參閱 [Mantle 端點](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint) |

154| `ANTHROPIC_BEDROCK_REGION_PREFIX` | Claude Code 優先嘗試的跨區域推論設定檔前綴（`us`、`eu`、`apac`、`jp`、`au` 或 `global`），而非從 AWS 區域推導出的前綴。在 AWS GovCloud 區域中會被忽略。需要 Claude Code v2.1.224 或更新版本。請參閱 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock#cross-region-inference-profile-prefixes) |156| `ANTHROPIC_BEDROCK_REGION_PREFIX` | Claude Code 優先嘗試的跨區域推論設定檔前綴（`us`、`eu`、`apac`、`jp`、`au` 或 `global`），而非由 AWS 區域推導出的前綴。在 AWS GovCloud 區域中會被忽略。需要 Claude Code v2.1.224 或更新版本。請參閱 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock#cross-region-inference-profile-prefixes) |

155| `ANTHROPIC_BEDROCK_SERVICE_TIER` | Amazon Bedrock [服務層級](https://docs.aws.amazon.com/bedrock/latest/userguide/service-tiers-inference.html)（`default`、`flex` 或 `priority`）。以 `X-Amzn-Bedrock-Service-Tier` 標頭傳送。請參閱 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock#service-tiers) |157| `ANTHROPIC_BEDROCK_SERVICE_TIER` | Amazon Bedrock [服務層級](https://docs.aws.amazon.com/bedrock/latest/userguide/service-tiers-inference.html)（`default`、`flex` 或 `priority`）。以 `X-Amzn-Bedrock-Service-Tier` 標頭傳送。請參閱 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock#service-tiers) |

156| `ANTHROPIC_BETAS` | 要包含在 API 請求中的額外 `anthropic-beta` 標頭值清單，以逗號分隔。Claude Code 已會傳送其所需的 beta 標頭；使用此變數可在 Claude Code 加入原生支援之前選擇加入 [Anthropic API beta](https://platform.claude.com/docs/en/api/beta-headers)。與需要 API 金鑰身分驗證的 [`--betas` 旗標](/docs/zh-TW/cli-reference#cli-flags)不同，此變數適用於所有驗證方式，包括 Claude.ai 訂閱 |158| `ANTHROPIC_BETAS` | 以逗號分隔的額外 `anthropic-beta` 標頭值清單，會包含在 API 請求中。Claude Code 已會傳送其所需的 beta 標頭；在 Claude Code 加入原生支援之前，可使用此變數選擇加入某項 [Anthropic API beta](https://platform.claude.com/docs/en/api/beta-headers)。與需要 API 金鑰身分驗證的 [`--betas` 旗標](/docs/zh-TW/cli-reference#cli-flags)不同，此變數適用於所有驗證方式，包括 Claude.ai 訂閱 |

157| `ANTHROPIC_CUSTOM_HEADERS` | 要新增至請求的自訂標頭（`Name: Value` 格式，多個標頭以換行分隔）。如果名稱或值包含 HTTP 標頭無法承載的字元，例如彎引號或零寬空格，請求會失敗，並顯示依位置指出該組名稱與值的錯誤。需要 Claude Code v2.1.227 或更新版本。[Invalid request header value](/docs/zh-TW/errors#invalid-request-header-value) 列出了確切的字元集以及檢查執行的位置。若值設定的是憑證、組織或租用戶、路由或 API 行為標頭，例如 `Authorization` 或 `Host`，當由伺服器管理設定傳遞時，會被視為[需要核准的設定](/docs/zh-TW/server-managed-settings#environment-variables-and-the-approval-dialog)。若來自專案或本機設定，此類值會遵循[何時套用 `env` 值的規則](/docs/zh-TW/settings-reference#when-claude-code-applies-env-values) |159| `ANTHROPIC_CUSTOM_HEADERS` | 要新增至請求的自訂標頭（`Name: Value` 格式，多個標頭以換行分隔）。若名稱或值包含 HTTP 標頭無法承載的字元（例如彎引號或零寬空格），請求會失敗，並顯示依位置指出該組標頭的錯誤。需要 Claude Code v2.1.227 或更新版本。[Invalid request header value](/docs/zh-TW/errors#invalid-request-header-value) 列出確切的字元集以及檢查執行的位置。若值設定的是憑證、組織或租用戶、路由或 API 行為相關標頭（例如 `Authorization` 或 `Host`），當由伺服器管理設定傳遞時，會被視為[需要核准的設定](/docs/zh-TW/server-managed-settings#environment-variables-and-the-approval-dialog)。若來自專案或本機設定，此類值會遵循[`env` 值何時套用的規則](/docs/zh-TW/settings-reference#when-claude-code-applies-env-values) |

158| `ANTHROPIC_CUSTOM_MODEL_OPTION` | 要在 `/model` 選擇器中新增為自訂項目的模型 ID。使用此變數可讓非標準或閘道專屬的模型可供選擇，而不必取代內建別名。請參閱[模型設定](/docs/zh-TW/model-config#add-a-custom-model-option) |160| `ANTHROPIC_CUSTOM_MODEL_OPTION` | 要在 `/model` 選擇器中新增為自訂項目的模型 ID。可用於讓非標準或閘道專屬的模型可供選擇，而不必取代內建別名。請參閱[模型設定](/docs/zh-TW/model-config#add-a-custom-model-option) |

160| `ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` | `/model` 選擇器中自訂模型項目的顯示名稱。未設定時，若 Claude Code [能辨識該 ID](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)，項目會顯示模型名稱，否則顯示模型 ID |162| `ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` | `/model` 選擇器中自訂模型項目的顯示名稱。未設定時，若 Claude Code [能辨識該 ID](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)，該項目會顯示模型名稱，否則顯示模型 ID |

161| `ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES` | 自訂模型支援的[功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)清單，以逗號分隔，例如 `effort,thinking`。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |163| `ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES` | 以逗號分隔的自訂模型所支援[功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)清單，例如 `effort,thinking`。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

162| `ANTHROPIC_DEFAULT_FABLE_MODEL` | `fable` 別名解析至的模型 ID，也是 Claude Code 在第三方供應商上為[自動模型備援](/docs/zh-TW/model-config#automatic-model-fallback)所辨識為 Fable 模型的 ID。請參閱[模型設定](/docs/zh-TW/model-config#environment-variables) |164| `ANTHROPIC_DEFAULT_FABLE_MODEL` | `fable` 別名所解析的模型 ID，也是 Claude Code 在第三方供應商上為[自動模型備援](/docs/zh-TW/model-config#automatic-model-fallback)辨識為 Fable 模型的 ID。請參閱[模型設定](/docs/zh-TW/model-config#environment-variables) |

163| `ANTHROPIC_DEFAULT_FABLE_MODEL_DESCRIPTION` | `/model` 選擇器中固定 Fable 模型的顯示描述。未設定時，該列會顯示以 `Custom Fable model` 開頭的預設描述。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |165| `ANTHROPIC_DEFAULT_FABLE_MODEL_DESCRIPTION` | `/model` 選擇器中已固定之 Fable 模型的顯示描述。未設定時，該列會顯示以 `Custom Fable model` 開頭的預設描述。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

164| `ANTHROPIC_DEFAULT_FABLE_MODEL_NAME` | `/model` 選擇器中固定 Fable 模型的顯示名稱。未設定時，若 Claude Code 能辨識固定的 ID，該列會顯示模型名稱，否則顯示固定的 ID。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |166| `ANTHROPIC_DEFAULT_FABLE_MODEL_NAME` | `/model` 選擇器中已固定之 Fable 模型的顯示名稱。未設定時，若 Claude Code 能辨識所固定的 ID，該列會顯示模型名稱，否則顯示所固定的 ID。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

165| `ANTHROPIC_DEFAULT_FABLE_MODEL_SUPPORTED_CAPABILITIES` | 固定 Fable 模型支援的[功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)清單，以逗號分隔，例如 `effort,thinking`。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |167| `ANTHROPIC_DEFAULT_FABLE_MODEL_SUPPORTED_CAPABILITIES` | 以逗號分隔的已固定 Fable 模型所支援[功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)清單，例如 `effort,thinking`。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

166| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | `haiku` 別名解析至的模型 ID，也用於[背景功能](/docs/zh-TW/costs#background-token-usage)。請參閱[模型設定](/docs/zh-TW/model-config#environment-variables) |168| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | `haiku` 別名所解析的模型 ID，也用於[背景功能](/docs/zh-TW/costs#background-token-usage)。請參閱[模型設定](/docs/zh-TW/model-config#environment-variables) |

167| `ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION` | `/model` 選擇器中固定 Haiku 模型的顯示描述。未設定時，該列會顯示以 `Custom Haiku model` 開頭的預設描述。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |169| `ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION` | `/model` 選擇器中已固定之 Haiku 模型的顯示描述。未設定時，該列會顯示以 `Custom Haiku model` 開頭的預設描述。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

168| `ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME` | `/model` 選擇器中固定 Haiku 模型的顯示名稱。未設定時，若 Claude Code 能辨識固定的 ID，該列會顯示模型名稱，否則顯示固定的 ID。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |170| `ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME` | `/model` 選擇器中已固定之 Haiku 模型的顯示名稱。未設定時，若 Claude Code 能辨識所固定的 ID，該列會顯示模型名稱，否則顯示所固定的 ID。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

169| `ANTHROPIC_DEFAULT_HAIKU_MODEL_SUPPORTED_CAPABILITIES` | 固定 Haiku 模型支援的[功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)清單，以逗號分隔，例如 `effort,thinking`。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |171| `ANTHROPIC_DEFAULT_HAIKU_MODEL_SUPPORTED_CAPABILITIES` | 以逗號分隔的已固定 Haiku 模型所支援[功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)清單，例如 `effort,thinking`。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

170| `ANTHROPIC_DEFAULT_MODEL` | 新工作階段預設啟動時使用的模型。需要 Claude Code v2.1.236 或更新版本。請參閱[為新工作階段設定預設模型](/docs/zh-TW/model-config#set-a-default-model-for-new-sessions) |172| `ANTHROPIC_DEFAULT_MODEL` | 新工作階段預設啟動時使用的模型。需要 Claude Code v2.1.236 或更新版本。請參閱[為新工作階段設定預設模型](/docs/zh-TW/model-config#set-a-default-model-for-new-sessions) |

171| `ANTHROPIC_DEFAULT_OPUS_MODEL` | `opus` 別名解析至的模型 ID，也是 `opusplan` 在 Plan Mode 啟用時使用的模型。請參閱[模型設定](/docs/zh-TW/model-config#environment-variables) |173| `ANTHROPIC_DEFAULT_OPUS_MODEL` | `opus` 別名所解析的模型 ID，也是 `opusplan` 在 Plan Mode 啟用時所使用的模型。請參閱[模型設定](/docs/zh-TW/model-config#environment-variables) |

172| `ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION` | `/model` 選擇器中固定 Opus 模型的顯示描述。未設定時，該列會顯示以 `Custom Opus model` 開頭的預設描述。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |174| `ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION` | `/model` 選擇器中已固定之 Opus 模型的顯示描述。未設定時，該列會顯示以 `Custom Opus model` 開頭的預設描述。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

173| `ANTHROPIC_DEFAULT_OPUS_MODEL_NAME` | `/model` 選擇器中固定 Opus 模型的顯示名稱。未設定時，若 Claude Code 能辨識固定的 ID，該列會顯示模型名稱，否則顯示固定的 ID。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |175| `ANTHROPIC_DEFAULT_OPUS_MODEL_NAME` | `/model` 選擇器中已固定之 Opus 模型的顯示名稱。未設定時，若 Claude Code 能辨識所固定的 ID，該列會顯示模型名稱，否則顯示所固定的 ID。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

174| `ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES` | 固定 Opus 模型支援的[功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)清單，以逗號分隔，例如 `effort,thinking`。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |176| `ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES` | 以逗號分隔的已固定 Opus 模型所支援[功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)清單，例如 `effort,thinking`。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

175| `ANTHROPIC_DEFAULT_SONNET_MODEL` | `sonnet` 別名解析至的模型 ID，也是 `opusplan` 在 Plan Mode 未啟用時使用的模型。請參閱[模型設定](/docs/zh-TW/model-config#environment-variables) |177| `ANTHROPIC_DEFAULT_SONNET_MODEL` | `sonnet` 別名所解析的模型 ID，也是 `opusplan` 在 Plan Mode 未啟用時所使用的模型。請參閱[模型設定](/docs/zh-TW/model-config#environment-variables) |

176| `ANTHROPIC_DEFAULT_SONNET_MODEL_DESCRIPTION` | `/model` 選擇器中固定 Sonnet 模型的顯示描述。未設定時，該列會顯示以 `Custom Sonnet model` 開頭的預設描述。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |178| `ANTHROPIC_DEFAULT_SONNET_MODEL_DESCRIPTION` | `/model` 選擇器中已固定之 Sonnet 模型的顯示描述。未設定時，該列會顯示以 `Custom Sonnet model` 開頭的預設描述。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

177| `ANTHROPIC_DEFAULT_SONNET_MODEL_NAME` | `/model` 選擇器中固定 Sonnet 模型的顯示名稱。未設定時，若 Claude Code 能辨識固定的 ID，該列會顯示模型名稱，否則顯示固定的 ID。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |179| `ANTHROPIC_DEFAULT_SONNET_MODEL_NAME` | `/model` 選擇器中已固定之 Sonnet 模型的顯示名稱。未設定時，若 Claude Code 能辨識所固定的 ID，該列會顯示模型名稱，否則顯示所固定的 ID。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

178| `ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES` | 固定 Sonnet 模型支援的[功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)清單，以逗號分隔，例如 `effort,thinking`。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |180| `ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES` | 以逗號分隔的已固定 Sonnet 模型所支援[功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)清單，例如 `effort,thinking`。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

179| `ANTHROPIC_FEDERATION_RULE_ID` | [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的聯合規則 ID。當您將其與 `ANTHROPIC_ORGANIZATION_ID` 一起設定時，Claude Code 會選用聯合憑證，其優先順序高於您的 `/login` 憑證。請參閱[身分驗證優先順序](/docs/zh-TW/authentication#authentication-precedence) |181| `ANTHROPIC_FEDERATION_RULE_ID` | [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的聯合規則 ID。當您將其與 `ANTHROPIC_ORGANIZATION_ID` 一同設定時，Claude Code 會選用聯合憑證，其優先順序高於您的 `/login` 憑證。請參閱[身分驗證優先順序](/docs/zh-TW/authentication#authentication-precedence) |

180| `ANTHROPIC_FOUNDRY_API_KEY` | 用於 Microsoft Foundry 身分驗證的 API 金鑰（請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)） |182| `ANTHROPIC_FOUNDRY_API_KEY` | 用於 Microsoft Foundry 身分驗證的 API 金鑰（請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)） |

181| `ANTHROPIC_FOUNDRY_AUTH_TOKEN` | 用於 Microsoft Foundry 身分驗證的 Bearer token，例如 Microsoft Entra 存取 token。Claude Code 會以 `Authorization: Bearer` 標頭傳送。優先於 `ANTHROPIC_FOUNDRY_API_KEY` 和 Azure 預設憑證鏈。請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)。需要 Claude Code v2.1.203 或更新版本 |183| `ANTHROPIC_FOUNDRY_AUTH_TOKEN` | 用於 Microsoft Foundry 身分驗證的 Bearer token，例如 Microsoft Entra 存取 token。Claude Code 會以 `Authorization: Bearer` 標頭傳送。優先於 `ANTHROPIC_FOUNDRY_API_KEY` 及 Azure 預設憑證鏈。請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)。需要 Claude Code v2.1.203 或更新版本 |

182| `ANTHROPIC_FOUNDRY_BASE_URL` | Microsoft Foundry 資源的完整基礎 URL（例如 `https://my-resource.services.ai.azure.com/anthropic`）。可替代 `ANTHROPIC_FOUNDRY_RESOURCE`（請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)） |184| `ANTHROPIC_FOUNDRY_BASE_URL` | Microsoft Foundry 資源的完整基礎 URL（例如 `https://my-resource.services.ai.azure.com/anthropic`）。為 `ANTHROPIC_FOUNDRY_RESOURCE` 的替代方案（請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)） |

183| `ANTHROPIC_FOUNDRY_RESOURCE` | Microsoft Foundry 資源名稱（例如 `my-resource`）。Claude Code [會拒絕 URL 或主機名稱](/docs/zh-TW/errors#anthropic-foundry-resource-must-be-a-foundry-resource-name)。若未設定 `ANTHROPIC_FOUNDRY_BASE_URL` 則為必要項目（請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)） |185| `ANTHROPIC_FOUNDRY_RESOURCE` | Microsoft Foundry 資源名稱（例如 `my-resource`）。Claude Code [會拒絕 URL 或主機名稱](/docs/zh-TW/errors#anthropic-foundry-resource-must-be-a-foundry-resource-name)。若未設定 `ANTHROPIC_FOUNDRY_BASE_URL` 則為必要設定（請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)） |

185| `ANTHROPIC_ORGANIZATION_ID` | [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的組織 ID。請與 `ANTHROPIC_FEDERATION_RULE_ID` 一起設定。請參閱[身分驗證優先順序](/docs/zh-TW/authentication#authentication-precedence) |187| `ANTHROPIC_ORGANIZATION_ID` | [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的組織 ID。請與 `ANTHROPIC_FEDERATION_RULE_ID` 一同設定。請參閱[身分驗證優先順序](/docs/zh-TW/authentication#authentication-precedence) |

186| `ANTHROPIC_PROFILE` | 用於身分驗證的 Anthropic 設定檔名稱，例如由 [`ant auth login`](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/authentication) 建立的設定檔，或透過[在沒有 API 金鑰的情況下登入 Console 帳戶](/docs/zh-TW/authentication#sign-in-without-an-api-key)所建立的設定檔。請參閱[身分驗證優先順序](/docs/zh-TW/authentication#authentication-precedence) |188| `ANTHROPIC_PROFILE` | 用於身分驗證的 Anthropic 設定檔名稱，例如由 [`ant auth login`](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/authentication) 建立的設定檔，或透過[不使用 API 金鑰登入 Console 帳戶](/docs/zh-TW/authentication#sign-in-without-an-api-key)所建立的設定檔。請參閱[身分驗證優先順序](/docs/zh-TW/authentication#authentication-precedence) |

188| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | 使用 Amazon Bedrock 或 Amazon Bedrock Mantle 時，覆寫 Haiku 級模型的 AWS 區域。在 Amazon Bedrock 上，只有在同時設定 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 或已棄用的 `ANTHROPIC_SMALL_FAST_MODEL` 時才會生效，因為否則 Amazon Bedrock 會在工作階段區域中以[預設 Sonnet 模型或主要模型](/docs/zh-TW/amazon-bedrock#4-pin-model-versions)執行背景任務 |190| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | 使用 Amazon Bedrock 或 Amazon Bedrock Mantle 時，覆寫 Haiku 級模型的 AWS 區域。在 Amazon Bedrock 上，僅在同時設定 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 或已棄用的 `ANTHROPIC_SMALL_FAST_MODEL` 時才會生效，因為否則 Amazon Bedrock 會在工作階段區域中以[預設 Sonnet 模型或主要模型](/docs/zh-TW/amazon-bedrock#4-pin-model-versions)執行背景任務 |

189| `ANTHROPIC_VERTEX_BASE_URL` | 覆寫 Google Cloud's Agent Platform 端點 URL。用於自訂 Google Cloud's Agent Platform 端點，或透過 [LLM 閘道](/docs/zh-TW/llm-gateway)路由時。請參閱 [Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai) |191| `ANTHROPIC_VERTEX_BASE_URL` | 覆寫 Google Cloud's Agent Platform 端點 URL。用於自訂 Google Cloud's Agent Platform 端點，或透過 [LLM 閘道](/docs/zh-TW/llm-gateway) 路由時。請參閱 [Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai) |

190| `ANTHROPIC_VERTEX_PROJECT_ID` | Google Cloud's Agent Platform 請求所指向的 GCP 專案 ID。請參閱[設定 GCP 憑證](/docs/zh-TW/google-vertex-ai#3-configure-gcp-credentials) |192| `ANTHROPIC_VERTEX_PROJECT_ID` | Google Cloud's Agent Platform 請求所指向的 GCP 專案 ID。請參閱[設定 GCP 憑證](/docs/zh-TW/google-vertex-ai#3-configure-gcp-credentials) |

191| `ANTHROPIC_WORKSPACE_ID` | [workload identity federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的工作區 ID。當您的聯合規則範圍涵蓋多個工作區時，請設定此變數，讓 token 交換知道要以哪個工作區為目標 |193| `ANTHROPIC_WORKSPACE_ID` | [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的工作區 ID。當您的聯合規則涵蓋多個工作區時請設定此變數，讓 token 交換知道要以哪個工作區為目標 |

192| `API_FORCE_IDLE_TIMEOUT` | 覆寫 5 分鐘的主體閒置逾時；當沒有任何位元組傳入時，此逾時會中止串流模型回應。設為 `0` 可關閉逾時，例如當速度較慢的[閘道](/docs/zh-TW/llm-gateway)或本機模型在區塊之間暫停超過 5 分鐘時；設為 `1` 則可對所有供應商保持開啟。未設定時，此逾時會在直接 Anthropic API、[Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws)，以及設定了 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1` 的 Amazon Bedrock 以外的供應商上啟用。[串流監控程式](/docs/zh-TW/network-config#streaming-idle-watchdogs)會獨立於此逾時運作，即使您在此設定 `0`，仍會中止長時間的無回應暫停 |194| `API_FORCE_IDLE_TIMEOUT` | 覆寫 5 分鐘的主體閒置逾時，該逾時會在沒有位元組抵達時中止串流模型回應。設為 `0` 可關閉逾時，例如當緩慢的[閘道](/docs/zh-TW/llm-gateway)或本機模型在區塊之間暫停超過 5 分鐘時；設為 `1` 則對所有供應商都保持開啟。未設定時，除了直接使用 Anthropic API、[Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws)，以及設定了 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1` 的 Amazon Bedrock 之外，其他供應商都會啟用此逾時。[串流監控程式](/docs/zh-TW/network-config#streaming-idle-watchdogs)獨立於此運作，即使您在此設為 `0`，仍會中止長時間的無回應暫停 |

193| `API_TIMEOUT_MS` | API 請求的逾時，以毫秒為單位（預設：600000，即 10 分鐘；最大值：2147483647）。當請求在速度較慢的網路上或透過代理伺服器路由時發生逾時，請調高此值。超過最大值的值會使底層計時器溢位，導致請求立即失敗 |195| `API_TIMEOUT_MS` | API 請求的逾時時間，以毫秒為單位（預設：600000，即 10 分鐘；最大值：2147483647）。當請求在緩慢的網路上逾時，或透過代理伺服器路由時，請調高此值。超過最大值的值會使底層計時器溢位，導致請求立即失敗 |

194| `AWS_BEARER_TOKEN_BEDROCK` | 用於身分驗證的 Amazon Bedrock API 金鑰（請參閱 [Amazon Bedrock API 金鑰](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)） |196| `AWS_BEARER_TOKEN_BEDROCK` | 用於身分驗證的 Amazon Bedrock API 金鑰（請參閱 [Amazon Bedrock API keys](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)） |

195| `BASH_DEFAULT_TIMEOUT_MS` | 前景 Bash 或 PowerShell 工具命令的預設逾時，以毫秒為單位（預設：120000，即 2 分鐘）。超過 30 分鐘的預設值，也會成為無人值守工作階段中[背景命令時間限制](/docs/zh-TW/tools-reference#time-limit-for-background-commands)的預設值。背景時間限制需要 Claude Code v2.1.285 或更新版本 |197| `BASH_DEFAULT_TIMEOUT_MS` | 前景 Bash 或 PowerShell 工具命令的預設逾時，以毫秒為單位（預設：120000，即 2 分鐘）。若預設值超過 30 分鐘，在無人值守的工作階段中，也會成為[背景命令的時間限制](/docs/zh-TW/tools-reference#time-limit-for-background-commands)預設值。背景時間限制需要 Claude Code v2.1.285 或更新版本 |

196| `BASH_MAX_OUTPUT_LENGTH` | Claude Code 讀回命令結果中的 bash 輸出字元數上限（預設：30000；最大值：150000）。如果您設定了 [`bashOutputMaxChars`](/docs/zh-TW/settings-reference#bashoutputmaxchars) 設定，Claude Code 會忽略此變數。請參閱[輸出限制](/docs/zh-TW/tools-reference#output-limits) |198| `BASH_MAX_OUTPUT_LENGTH` | Claude Code 讀回命令結果中的 bash 輸出最大字元數（預設：30000；最大值：150000）。若您設定了 [`bashOutputMaxChars`](/docs/zh-TW/settings-reference#bashoutputmaxchars) 設定，Claude Code 會忽略此變數。請參閱[輸出限制](/docs/zh-TW/tools-reference#output-limits) |

197| `BASH_MAX_TIMEOUT_MS` | 模型可為前景 Bash 或 PowerShell 工具命令設定的逾時上限，以毫秒為單位（預設：600000，即 10 分鐘）。實際上限為此值與 `BASH_DEFAULT_TIMEOUT_MS` 中的較大者。超過 2 小時的實際上限，也會成為無人值守工作階段中[背景命令時間限制](/docs/zh-TW/tools-reference#time-limit-for-background-commands)的最大值。背景時間限制需要 Claude Code v2.1.285 或更新版本 |199| `BASH_MAX_TIMEOUT_MS` | 模型可為前景 Bash 或 PowerShell 工具命令設定的最大逾時，以毫秒為單位（預設：600000，即 10 分鐘）。實際上限為此值與 `BASH_DEFAULT_TIMEOUT_MS` 中較大者。若實際上限超過 2 小時，在無人值守的工作階段中，也會成為[背景命令的時間限制](/docs/zh-TW/tools-reference#time-limit-for-background-commands)最大值。背景時間限制需要 Claude Code v2.1.285 或更新版本 |

198| `BETA_TRACING_ENDPOINT` | [詳細 beta 追蹤](/docs/zh-TW/monitoring-usage#traces-beta)的 OTLP/HTTP 端點：搭配 `ENABLE_BETA_TRACING_DETAILED=1` 時，日誌與追蹤會傳送至此處，而非已設定的匯出器。請在您的 shell、使用者設定或受管設定中設定此變數。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略 |200| `BETA_TRACING_ENDPOINT` | [詳細 beta 追蹤](/docs/zh-TW/monitoring-usage#traces-beta)的 OTLP/HTTP 端點：搭配 `ENABLE_BETA_TRACING_DETAILED=1` 時，日誌與追蹤會傳送至該處，而非已設定的匯出器。請在您的 shell、使用者設定或受管設定中設定。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略 |

199| `CCR_FORCE_BUNDLE` | 設為 `1` 可強制 [`claude --cloud`](/docs/zh-TW/claude-code-on-the-web#send-local-repositories-without-github) 打包並上傳您的本機儲存庫，而非從其遠端複製 |201| `CCR_FORCE_BUNDLE` | 設為 `1` 可強制 [`claude --cloud`](/docs/zh-TW/claude-code-on-the-web#send-local-repositories-without-github) 打包並上傳您的本機儲存庫，而非從其遠端複製 |

200| `CLAUDECODE` | 在 Claude Code 產生的子程序中設為 `1`（Bash 和 PowerShell 工具、tmux 工作階段、[hook](/docs/zh-TW/hooks) 命令、[狀態列](/docs/zh-TW/statusline)命令、stdio [MCP 伺服器](/docs/zh-TW/mcp)子程序）。IDE 擴充功能也會在其整合式終端機中設定此變數。用於偵測指令碼是否在 Claude Code 產生的子程序中執行。若要檢查目前程序是否由工具呼叫或 hook 直接產生，而非在 Claude Code 啟動的 stdio MCP 伺服器內，請改用 `CLAUDE_CODE_CHILD_SESSION` |202| `CLAUDECODE` | 在 Claude Code 產生的子程序（Bash 與 PowerShell 工具、tmux 工作階段、[hook](/docs/zh-TW/hooks) 命令、[狀態列](/docs/zh-TW/statusline)命令、stdio [MCP 伺服器](/docs/zh-TW/mcp)子程序）中設為 `1`。IDE 擴充功能也會在其整合式終端機中設定此變數。可用於偵測指令碼是否在 Claude Code 產生的子程序中執行。若要檢查目前程序是否由工具呼叫或 hook 直接產生，而非在 Claude Code 啟動的 stdio MCP 伺服器內，請改用 `CLAUDE_CODE_CHILD_SESSION` |

201| `CLAUDE_AFK_COUNTDOWN_MS` | 未回答的 [`AskUserQuestion`](/docs/zh-TW/tools-reference) 對話方塊在自動繼續之前多少毫秒，畫面上會出現倒數計時。預設 `20000`（20 秒），上限為自動繼續逾時。除非已開啟自動繼續，否則沒有作用；請參閱 [`askUserQuestionTimeout`](/docs/zh-TW/settings-reference#askuserquestiontimeout) 設定和 `CLAUDE_AFK_TIMEOUT_MS`。需要 Claude Code v2.1.198 或更新版本 |203| `CLAUDE_AFK_COUNTDOWN_MS` | 在未回答的 [`AskUserQuestion`](/docs/zh-TW/tools-reference) 對話框自動繼續之前，畫面上倒數計時出現的毫秒數。預設為 `20000`（20 秒），上限為自動繼續逾時。除非已開啟自動繼續，否則沒有作用；請參閱 [`askUserQuestionTimeout`](/docs/zh-TW/settings-reference#askuserquestiontimeout) 設定與 `CLAUDE_AFK_TIMEOUT_MS`。需要 Claude Code v2.1.198 或更新版本 |

202| `CLAUDE_AFK_TIMEOUT_MS` | 閒置多少毫秒後，未回答的 [`AskUserQuestion`](/docs/zh-TW/tools-reference) 對話方塊會在沒有您回應的情況下自動繼續。自動繼續預設為關閉；可透過 [`askUserQuestionTimeout`](/docs/zh-TW/settings-reference#askuserquestiontimeout) 設定選擇啟用。此變數是用於示範和自動化測試的覆寫：設定後，它會優先於該設定，即使該設定未設定或為 `never`，也會開啟自動繼續。設定 `0` 不會關閉逾時，而是會立即關閉對話方塊。在 v2.1.198 和 v2.1.199 中，自動繼續預設為開啟，逾時為 `60000`（60 秒）。需要 Claude Code v2.1.198 或更新版本 |204| `CLAUDE_AFK_TIMEOUT_MS` | 未回答的 [`AskUserQuestion`](/docs/zh-TW/tools-reference) 對話框在閒置多少毫秒後，會在無您參與的情況下自動繼續。自動繼續預設為關閉；請透過 [`askUserQuestionTimeout`](/docs/zh-TW/settings-reference#askuserquestiontimeout) 設定選擇加入。此變數是用於示範與自動化測試的覆寫：設定後，它會優先於該設定，即使該設定未設定或為 `never`，也會開啟自動繼續。設為 `0` 並不會關閉逾時，而是會立即關閉對話框。在 v2.1.198 與 v2.1.199 中，自動繼續預設為開啟，逾時為 `60000`（60 秒）。需要 Claude Code v2.1.198 或更新版本 |

203| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 設為 `1` 可停用所有內建 [subagent](/docs/zh-TW/sub-agents) 類型，例如 Explore 和 Plan。僅適用於非互動模式（`-p` 旗標）。適合想要從空白狀態開始的 SDK 使用者。這也會移除 `general-purpose`，即當 Agent 工具呼叫省略 `subagent_type` 時 Claude Code 執行的 subagent。此類呼叫隨後會失敗並顯示 [`subagent_type is required`](/docs/zh-TW/errors#subagent-type-is-required) |205| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 設為 `1` 可停用所有內建 [subagent](/docs/zh-TW/sub-agents) 類型，例如 Explore 與 Plan。僅適用於非互動模式（`-p` 旗標）。適合想要從零開始的 SDK 使用者。這也會移除 `general-purpose`，即 Agent 工具呼叫省略 `subagent_type` 時 Claude Code 所執行的 subagent。此類呼叫隨後會以 [`subagent_type is required`](/docs/zh-TW/errors#subagent-type-is-required) 失敗 |

205| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | subagent 的停滯逾時，以毫秒為單位。預設 `600000`（10 分鐘）；如果您在串流監控程式開啟時調高 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`，預設值會隨之提高，如[處理緩慢或停滯的 API 回應](/docs/zh-TW/agent-sdk/typescript#handle-slow-or-stalled-api-responses)所述。計時器會在每個串流進度事件時重設；如果在時間範圍內沒有收到任何進度，Claude Code 會中止該 subagent 並向父層回報停滯 |207| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | subagent 的停滯逾時，以毫秒為單位。預設為 `600000`（10 分鐘）；若您在串流監控程式開啟時調高 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`，預設值也會隨之提高，如[處理緩慢或停滯的 API 回應](/docs/zh-TW/agent-sdk/typescript#handle-slow-or-stalled-api-responses)所述。計時器會在每個串流進度事件時重設；若在時間範圍內沒有任何進度，Claude Code 會中止該 subagent 並向上層回報停滯 |

206| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 設定觸發自動壓縮時所採用的自動壓縮視窗百分比（1-100）。使用較低的值（例如 `50`）可提早壓縮；此變數無法提高閾值，因此高於預設百分比的值會被忽略。僅適用於[在達到模型上下文限制之前壓縮](/docs/zh-TW/model-config#context-window-and-auto-compaction)的工作階段。同時適用於主要對話和 subagent |208| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 設定自動壓縮視窗中觸發自動壓縮的百分比（1-100）。使用較低的值（例如 `50`）可提早壓縮；此變數無法提高閾值，因此高於預設百分比的值會被忽略。僅適用於[在模型上下文限制之前壓縮](/docs/zh-TW/model-config#context-window-and-auto-compaction)的工作階段。同時適用於主要對話與 subagent |

207| `CLAUDE_AUTO_BACKGROUND_TASKS` | 設為 `1` 可強制啟用長時間執行之 agent 任務的自動背景化。啟用後，subagent 在執行約兩分鐘後會移至背景。在 Claude Code v2.1.212 或更新版本中，也會在非互動模式下啟用[長時間 MCP 工具呼叫的自動背景化](/docs/zh-TW/mcp#automatic-backgrounding-of-long-tool-calls) |209| `CLAUDE_AUTO_BACKGROUND_TASKS` | 設為 `1` 可強制啟用長時間執行之 agent 任務的自動背景化。啟用後，subagent 在執行約兩分鐘後會移至背景。在 Claude Code v2.1.212 或更新版本中，也會在非互動模式下啟用[長時間 MCP 工具呼叫的自動背景化](/docs/zh-TW/mcp#automatic-backgrounding-of-long-tool-calls) |

208| `CLAUDE_AX_PREPARK_MS` | 在[螢幕閱讀器模式](/docs/zh-TW/accessibility)中，Claude Code 寫入新的或已變更的行之前等待的毫秒數。預設 `0`，因此 Claude Code 不會等待。在 v2.1.287 之前，預設值為 `50`。Claude Code 將等待時間上限設為 `5000`。需要 Claude Code v2.1.233 或更新版本 |210| `CLAUDE_AX_PREPARK_MS` | 在[螢幕閱讀器模式](/docs/zh-TW/accessibility)中，Claude Code 寫入新行或已變更行之前等待的毫秒數。預設為 `0`，因此 Claude Code 不會等待。在 v2.1.287 之前，預設值為 `50`。Claude Code 將等待上限設為 `5000`。需要 Claude Code v2.1.233 或更新版本 |

209| `CLAUDE_AX_SCREEN_READER` | 設為 `1` 可呈現適合螢幕閱讀器的輸出：不含裝飾性邊框或動畫的純文字。設為 `0` 可強制關閉螢幕閱讀器模式，即使 [`axScreenReader`](/docs/zh-TW/settings-reference#axscreenreader) 為 `true`。[`--ax-screen-reader`](/docs/zh-TW/cli-reference#cli-flags) 旗標優先。需要 Claude Code v2.1.181 或更新版本 |211| `CLAUDE_AX_SCREEN_READER` | 設為 `1` 可呈現適合螢幕閱讀器的輸出：不含裝飾性邊框或動畫的純文字。設為 `0` 可強制關閉螢幕閱讀器模式，即使 [`axScreenReader`](/docs/zh-TW/settings-reference#axscreenreader) 為 `true` 亦然。[`--ax-screen-reader`](/docs/zh-TW/cli-reference#cli-flags) 旗標優先於此變數。需要 Claude Code v2.1.181 或更新版本 |

210| `CLAUDE_AX_STARTUP_QUIET_MS` | 在[螢幕閱讀器模式](/docs/zh-TW/accessibility)中，Claude Code 在啟動確認行之後延遲第一次介面呈現的毫秒數，讓您的螢幕閱讀器能在新輸出打斷之前完整念出該行。預設 `3000`。設定 `0` 可立即呈現。Claude Code 將延遲上限設為 `600000`（10 分鐘）。您的第一次按鍵會提早結束延遲。需要 Claude Code v2.1.217 或更新版本 |212| `CLAUDE_AX_STARTUP_QUIET_MS` | 在[螢幕閱讀器模式](/docs/zh-TW/accessibility)中，Claude Code 在啟動確認行之後暫緩第一次介面呈現的毫秒數，讓您的螢幕閱讀器能在新輸出中斷之前完整唸出該行。預設為 `3000`。設為 `0` 可立即呈現。Claude Code 將暫緩上限設為 `600000`（10 分鐘）。您的第一次按鍵會提早結束暫緩。需要 Claude Code v2.1.217 或更新版本 |

212| `CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` | 位元組層級串流閒置監控程式的逾時，以毫秒為單位；設定後，對於該監控程式，它會優先於 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`，且不會變更事件層級監控程式。Claude Code 會將此變數限制在 10 秒到 30 分鐘之間。需要 Claude Code v2.1.210 或更新版本 |214| `CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` | 位元組層級串流閒置監控程式的逾時，以毫秒為單位；設定後，對該監控程式而言會優先於 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`，且不影響事件層級監控程式。Claude Code 會將此變數限制在 10 秒到 30 分鐘之間。需要 Claude Code v2.1.210 或更新版本 |

213| `CLAUDE_CLIENT_PRESENCE_FILE` | 一個檔案的路徑，該檔案由外部工具（例如螢幕鎖定監聽程式）在您解鎖螢幕時建立、在您鎖定螢幕時刪除。檔案存在期間，Claude Code 會略過 [Remote Control 行動推播通知](/docs/zh-TW/remote-control#mobile-push-notifications)，讓您在積極使用電腦時不再收到推播。當檔案不存在或無法讀取時，通知會照常傳送。Claude Code 會在每次觸發推播的事件時檢查一次該檔案，而非持續輪詢。需要 Claude Code v2.1.181 或更新版本 |215| `CLAUDE_CLIENT_PRESENCE_FILE` | 一個檔案的路徑，由外部工具（例如螢幕鎖定監聽器）在您解鎖螢幕時建立、鎖定螢幕時刪除。當該檔案存在時，Claude Code 會略過 [Remote Control 行動推播通知](/docs/zh-TW/remote-control#mobile-push-notifications)，讓您在正在使用電腦時不會收到推播。當檔案不存在或無法讀取時，通知會照常傳送。Claude Code 會在每個觸發推播的事件時檢查一次該檔案，而非輪詢。需要 Claude Code v2.1.181 或更新版本 |

215| `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` | 設為 `1` 可從以 `--add-dir` 指定的目錄載入記憶檔案。會載入 `CLAUDE.md`、`.claude/CLAUDE.md`、`.claude/rules/*.md` 和 `CLAUDE.local.md`。根據預設，額外目錄不會載入記憶檔案 |217| `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` | 設為 `1` 可從以 `--add-dir` 指定的目錄載入記憶檔案。會載入 `CLAUDE.md`、`.claude/CLAUDE.md`、`.claude/rules/*.md` 與 `CLAUDE.local.md`。預設情況下，額外目錄不會載入記憶檔案 |

216| `CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT` | 設為 `1` 可在[全螢幕呈現](/docs/zh-TW/fullscreen)中每一個畫格都重新繪製整個螢幕，而非傳送增量更新。如果全螢幕模式顯示過時或位置錯誤的文字片段，請使用此設定。Claude Code 會在 Windows 上為背景工作階段和 [agent view](/docs/zh-TW/agent-view) 自動啟用此功能 |218| `CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT` | 設為 `1` 可在[全螢幕呈現](/docs/zh-TW/fullscreen)中每一影格都重繪整個畫面，而非傳送增量更新。若全螢幕模式顯示過時或錯位的文字片段，請使用此設定。Claude Code 會在 Windows 上的背景工作階段與 [agent view](/docs/zh-TW/agent-view) 自動啟用此設定 |

217| `CLAUDE_CODE_ALWAYS_ENABLE_EFFORT` | 設為 `1` 可在每個請求中傳送 [effort](/docs/zh-TW/model-config#adjust-effort-level) 參數，即使 Claude Code 無法辨識該模型 ID 支援 effort。在透過 [LLM 閘道](/docs/zh-TW/llm-gateway)或以自訂識別碼提供模型的第三方供應商路由時使用。在 API 層拒絕 effort 參數的模型，包括 Claude 3 模型、Sonnet 4.0 和 4.5、Opus 4.0 和 4.1，以及 Haiku 4.5，仍會被排除，以免請求失敗 |219| `CLAUDE_CODE_ALWAYS_ENABLE_EFFORT` | 設為 `1` 可在每個請求中傳送 [effort](/docs/zh-TW/model-config#adjust-effort-level) 參數，即使 Claude Code 無法將該模型 ID 辨識為支援 effort。當透過以自訂識別碼提供模型的 [LLM 閘道](/docs/zh-TW/llm-gateway)或第三方供應商路由時，請使用此設定。在 API 層級拒絕 effort 參數的模型（包括 Claude 3 模型、Sonnet 4.0 與 4.5、Opus 4.0 與 4.1，以及 Haiku 4.5）仍會被排除，以免請求失敗 |

218| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` | 憑證應重新整理的間隔，以毫秒為單位（使用 [`apiKeyHelper`](/docs/zh-TW/settings-reference#apikeyhelper) 時） |220| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` | 憑證重新整理的間隔，以毫秒為單位（使用 [`apiKeyHelper`](/docs/zh-TW/settings-reference#apikeyhelper) 時） |

219| `CLAUDE_CODE_ARTIFACT_AUTO_OPEN` | 設為 `0` 可阻止 Claude Code 在發布新的 [artifact](/docs/zh-TW/artifacts#create-an-artifact) 時自動開啟瀏覽器 |221| `CLAUDE_CODE_ARTIFACT_AUTO_OPEN` | 設為 `0` 可在新的 [artifact](/docs/zh-TW/artifacts#create-an-artifact) 發佈時，不讓 Claude Code 自動開啟瀏覽器 |

220| `CLAUDE_CODE_ARTIFACT_COMMENTS` | 設為 `0` 可阻止 Claude 讀取和回覆 [artifact 上的留言](/docs/zh-TW/artifacts#collect-comments-on-an-artifact)。當 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 已[關閉 artifact](/docs/zh-TW/artifacts#availability) 時沒有作用。需要 Claude Code v2.1.221 或更新版本 |222| `CLAUDE_CODE_ARTIFACT_COMMENTS` | 設為 `0` 可讓 Claude 停止讀取及回覆 [artifact 上的留言](/docs/zh-TW/artifacts#collect-comments-on-an-artifact)。當 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 已[關閉 artifact](/docs/zh-TW/artifacts#availability) 時沒有作用。需要 Claude Code v2.1.221 或更新版本 |

221| `CLAUDE_CODE_ARTIFACT_COMMENTS_AUTOREACT` | 設為 `0` 可阻止 Claude [自行回覆傳送給它的留言](/docs/zh-TW/artifacts#let-claude-reply-to-comments-on-its-own)。需要 Claude Code v2.1.228 或更新版本 |223| `CLAUDE_CODE_ARTIFACT_COMMENTS_AUTOREACT` | 設為 `0` 可讓 Claude 停止[自行回覆傳送給它的留言](/docs/zh-TW/artifacts#let-claude-reply-to-comments-on-its-own)。需要 Claude Code v2.1.228 或更新版本 |

222| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 設為 `0` 可從系統提示詞的開頭省略[歸屬區塊](/docs/zh-TW/llm-gateway-protocol#system-prompt-attribution-block)，該區塊包含用戶端版本和提示詞指紋。無論如何設定，直接連線至 Anthropic API 時的快取都不受影響。在某些直接連線的設定中，即使您設定 `0`，Claude Code 仍會在[自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)分類器請求上保留該區塊。請在[系統提示詞歸屬區塊](/docs/zh-TW/llm-gateway-protocol#system-prompt-attribution-block)中查看這涵蓋哪些連線和憑證。在 v2.1.181 之前，該區塊在自訂基礎 URL 和 Microsoft Foundry 連線上包含每個請求專屬的 token，因此在這些版本上，當您的 LLM 閘道根據請求主體進行快取或將請求轉送至第三方供應商，或當您直接連線至 Microsoft Foundry 時，請將其設為 `0` |224| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 設為 `0` 可從系統提示詞開頭省略[歸屬區塊](/docs/zh-TW/llm-gateway-protocol#system-prompt-attribution-block)，該區塊包含用戶端版本與提示詞指紋。無論如何，直接連線至 Anthropic API 時的快取都不受影響。在某些直接連線設定中，即使您設為 `0`，Claude Code 仍會在[自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)分類器請求中保留該區塊。請在[系統提示詞歸屬區塊](/docs/zh-TW/llm-gateway-protocol#system-prompt-attribution-block)中查看此情況涵蓋哪些連線與憑證。在 v2.1.181 之前，該區塊在自訂基礎 URL 與 Microsoft Foundry 連線中包含每個請求各自的 token，因此在這些版本上，若您的 LLM 閘道會依請求主體進行快取或將請求轉送至第三方供應商，或您直接連線至 Microsoft Foundry，請將其設為 `0` |

224| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 設定[自動壓縮視窗](/docs/zh-TW/model-config#set-the-auto-compact-window)的 token 數，範圍從 `100000` 到 `1000000`。僅接受純整數，例如 `500000`：像 `500k` 這樣的值會被讀為 `500`，並被限制為 100K 的最小值。實際視窗也會受模型上下文視窗的限制。優先於 `/autocompact` 命令、`--autocompact` 旗標和 `autoCompactWindow` 設定。狀態列的 `used_percentage` 一律以模型的完整上下文視窗計算，因此一旦設定此變數，該百分比就不再能表示壓縮何時執行 |226| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 以 token 為單位設定[自動壓縮視窗](/docs/zh-TW/model-config#set-the-auto-compact-window)，範圍從 `100000` 到 `1000000`。僅接受純整數，例如 `500000`：像 `500k` 這樣的值會被讀取為 `500`，並被限制為最小值 100K。實際視窗也以模型的上下文視窗為上限。優先於 `/autocompact` 命令、`--autocompact` 旗標與 `autoCompactWindow` 設定。狀態列的 `used_percentage` 一律以模型的完整上下文視窗為基準計算，因此一旦設定此變數，該百分比就不再能表示壓縮何時執行 |

225| `CLAUDE_CODE_AUTO_CONNECT_IDE` | 覆寫自動 [IDE 連線](/docs/zh-TW/vs-code)。根據預設，在支援的 IDE 整合式終端機中啟動時，Claude Code 會自動連線。設為 `false` 可防止此行為。設為 `true` 可在自動偵測失敗時強制嘗試連線，例如 tmux 遮蔽了父終端機時。優先於 [`autoConnectIde`](/docs/zh-TW/settings-reference#autoconnectide) 全域設定 |227| `CLAUDE_CODE_AUTO_CONNECT_IDE` | 覆寫自動 [IDE 連線](/docs/zh-TW/vs-code)。預設情況下，在受支援 IDE 的整合式終端機中啟動時，Claude Code 會自動連線。設為 `false` 可防止此行為。設為 `true` 可在自動偵測失敗時（例如 tmux 遮蔽了上層終端機時）強制嘗試連線。優先於 [`autoConnectIde`](/docs/zh-TW/settings-reference#autoconnectide) 全域設定 |

226| `CLAUDE_CODE_AUTO_MODE_SERVER` | 控制 Claude Code 是否要求伺服器[審查自動模式動作](/docs/zh-TW/permission-modes#server-side-classifier-review)。設為 `0` 可改用 Claude Code 自己的分類器請求。在直接連線至 Anthropic API 時，需要 v2.1.281 或更新版本。連結的章節列出了變數未設定時哪些工作階段會詢問伺服器，以及自哪個版本起適用。需要 Claude Code v2.1.271 或更新版本 |228| `CLAUDE_CODE_AUTO_MODE_SERVER` | 控制 Claude Code 是否要求伺服器[審查自動模式動作](/docs/zh-TW/permission-modes#server-side-classifier-review)。設為 `0` 可改用 Claude Code 自己的分類器請求。在直接連線至 Anthropic API 時，需要 v2.1.281 或更新版本。連結的章節列出未設定此變數時哪些工作階段會詢問伺服器，以及自哪個版本起。需要 Claude Code v2.1.271 或更新版本 |

227| `CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS` | Claude Code 等待 AWS 預設憑證提供者鏈產生憑證的時間，以毫秒為單位，超過此時間後請求會失敗並顯示 [`AWS default-chain credential resolve timed out`](/docs/zh-TW/errors#aws-default-chain-credential-resolve-timed-out)（預設：`60000`）。當鏈中的某個步驟確實需要更長時間時，請調高此值，例如透過 `aws-vault` 等包裝工具進行搭配 MFA 的瀏覽器型 SSO 登入。適用於 Claude Code 使用預設鏈簽署的所有情況：[Amazon Bedrock](/docs/zh-TW/amazon-bedrock#credential-caching-and-resolution-timeout)、[Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 以及 [Mantle 端點](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint)。需要 Claude Code v2.1.207 或更新版本 |229| `CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS` | Claude Code 等待 AWS 預設憑證提供者鏈產生憑證的毫秒數，超過後請求會以 [`AWS default-chain credential resolve timed out`](/docs/zh-TW/errors#aws-default-chain-credential-resolve-timed-out) 失敗（預設：`60000`）。當您的憑證鏈中某個步驟確實需要更長時間時請調高此值，例如透過 `aws-vault` 等包裝工具進行的瀏覽器 SSO 登入並搭配 MFA。適用於 Amazon Bedrock、[Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 及 [Mantle 端點](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint)。請參閱[憑證快取與解析逾時](/docs/zh-TW/amazon-bedrock#credential-caching-and-resolution-timeout)。需要 Claude Code v2.1.207 或更新版本 |

228| `CLAUDE_CODE_BASH_EDIT_DIFF` | 設為 `0` 可關閉 [Bash 命令執行期間變更之檔案的差異](/docs/zh-TW/hooks#bash)，設為 `1` 則可在每種權限模式中記錄該差異。優先於 [`bashEditDiffEnabled`](/docs/zh-TW/settings-reference#basheditdiffenabled) 設定。需要 Claude Code v2.1.269 或更新版本 |230| `CLAUDE_CODE_BASH_EDIT_DIFF` | 設為 `0` 可關閉 [Bash 命令執行期間所變更檔案的差異](/docs/zh-TW/hooks#bash)，設為 `1` 則可在所有權限模式中記錄該差異。優先於 [`bashEditDiffEnabled`](/docs/zh-TW/settings-reference#basheditdiffenabled) 設定。需要 Claude Code v2.1.269 或更新版本 |

229| `CLAUDE_CODE_BG_TASKS_REPORT_RUNNING` | 設為 `0` 可讓非互動工作階段在每個回合結束時向其主機回報閒置狀態，即使背景工作仍在執行中。根據預設，當背景 agent 或[工作流程](/docs/zh-TW/workflows)執行等背景工作仍在進行時，工作階段在回合結束後仍會持續回報執行中狀態。這可避免監看狀態的主機（例如遠端工作階段清單）在工作進行中宣告 Claude 正在等待您的輸入。背景 shell 命令（例如開發伺服器）不會維持執行中狀態。執行中狀態的預設行為和 `0` 退出選項需要 Claude Code v2.1.269 或更新版本；在較早的版本上，請設定 `1` 以維持執行中狀態 |231| `CLAUDE_CODE_BG_TASKS_REPORT_RUNNING` | 設為 `0` 可讓非互動工作階段在每個回合結束時向其主機回報閒置狀態，即使背景工作仍在執行中。預設情況下，當背景 agent 或 [工作流程](/docs/zh-TW/workflows)執行等背景工作仍在進行時，工作階段在回合結束後仍會持續回報執行中狀態。這可避免監看狀態的主機（例如遠端工作階段清單）在工作進行中宣告 Claude 正在等待您的輸入。背景 shell 命令（例如開發伺服器）不會維持執行中狀態。執行中狀態預設值與 `0` 選擇退出需要 Claude Code v2.1.269 或更新版本；在較早版本中，請設為 `1` 以維持執行中狀態 |

230| `CLAUDE_CODE_BRIDGE_SESSION_ID` | 當工作階段有作用中的 [Remote Control](/docs/zh-TW/remote-control) 連線時，會在 Bash 工具和 [hook 命令](/docs/zh-TW/hooks)子程序中自動設定，並在連線結束時移除。其值為 `session_` 形式的工作階段 ID，與工作階段 `claude.ai/code` URL 中出現的識別碼相同，因此指令碼可以連結回執行它的工作階段。需要 Claude Code v2.1.199 或更新版本。在[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)中，請改為讀取 `CLAUDE_CODE_REMOTE_SESSION_ID` |232| `CLAUDE_CODE_BRIDGE_SESSION_ID` | 當工作階段有作用中的 [Remote Control](/docs/zh-TW/remote-control) 連線時，會自動在 Bash 工具與 [hook 命令](/docs/zh-TW/hooks)子程序中設定，並在連線結束時移除。其值為 `session_` 格式的工作階段 ID，與出現在工作階段 `claude.ai/code` URL 中的識別碼相同，因此指令碼可以連結回執行它的工作階段。需要 Claude Code v2.1.199 或更新版本。在[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)中，請改為讀取 `CLAUDE_CODE_REMOTE_SESSION_ID` |

231| `CLAUDE_CODE_BS_AS_CTRL_BACKSPACE` | 設為 `0` 可讓 Claude Code 將 `0x08` 位元組（也寫作 `^H`）讀取為一般 Backspace，設為 `1` 則讀取為 Ctrl+Backspace。任一值都會取代平台預設值。根據預設，Claude Code 在 Windows 上將其讀取為 Ctrl+Backspace（`TERM_PROGRAM` 為 `mintty` 或 `TERM` 為 `cygwin` 時除外），在 macOS 和 Linux 上則讀取為一般 Backspace。在 [Backspace 會刪除整個單字](/docs/zh-TW/terminal-config#fix-backspace-deleting-a-whole-word-on-windows)的 Windows 終端機中，請設定 `0` |233| `CLAUDE_CODE_BS_AS_CTRL_BACKSPACE` | 設為 `0` 可讓 Claude Code 將 `0x08` 位元組（亦寫作 `^H`）讀取為一般 Backspace，設為 `1` 則讀取為 Ctrl+Backspace。任一值都會取代平台預設值。預設情況下，Claude Code 在 Windows 上將其讀取為 Ctrl+Backspace（`TERM_PROGRAM` 為 `mintty` 或 `TERM` 為 `cygwin` 時除外），在 macOS 與 Linux 上則讀取為一般 Backspace。在 [Backspace 會刪除整個單字](/docs/zh-TW/terminal-config#fix-backspace-deleting-a-whole-word-on-windows)的 Windows 終端機中，請設為 `0` |

232| `CLAUDE_CODE_CERT_STORE` | TLS 連線的 CA 憑證來源清單，以逗號分隔。`bundled` 是隨 Claude Code 提供的 Mozilla CA 集合。`system` 是作業系統信任存放區，僅在具有 `tls.getCACertificates` 的執行環境中讀取：原生二進位檔，或 npm 安裝時的 Node 22.15 或更新版本。請參閱 [CA 憑證存放區](/docs/zh-TW/network-config#ca-certificate-store)。預設為 `bundled,system` |234| `CLAUDE_CODE_CERT_STORE` | 以逗號分隔的 TLS 連線 CA 憑證來源清單。`bundled` 是隨 Claude Code 提供的 Mozilla CA 集合。`system` 是作業系統信任存放區，僅在具備 `tls.getCACertificates` 的執行環境中讀取：原生二進位檔，或 npm 安裝時的 Node 22.15 或更新版本。請參閱 [CA 憑證存放區](/docs/zh-TW/network-config#ca-certificate-store)。預設為 `bundled,system` |

233| `CLAUDE_CODE_CHILD_SESSION` | 在 Claude Code 透過 Bash、PowerShell 和 Monitor 工具、[hook](/docs/zh-TW/hooks) 命令以及[狀態列](/docs/zh-TW/statusline)命令產生的子程序中設為 `1`。不會為 stdio [MCP 伺服器](/docs/zh-TW/mcp)子程序設定，因為這些子程序存在時間長，會比產生它們的工作階段存活更久。與 `CLAUDECODE` 不同，此變數只會由 Claude Code 本身在啟動子程序時設定，IDE 擴充功能不會設定，因此能可靠地區分巢狀工作階段與在 IDE 整合式終端機中啟動的頂層 `claude`。以此方式啟動的巢狀互動式 `claude` TUI 會自動從 `--resume`、`--continue`、向上鍵歷史記錄和 `claude agents` 清單中排除。非互動式 `claude -p` 工作階段仍會保存。設定 `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1` 可覆寫此排除。需要 Claude Code v2.1.172 或更新版本 |235| `CLAUDE_CODE_CHILD_SESSION` | 在 Claude Code 透過 Bash、PowerShell 與 Monitor 工具、[hook](/docs/zh-TW/hooks) 命令及[狀態列](/docs/zh-TW/statusline)命令所產生的子程序中設為 `1`。stdio [MCP 伺服器](/docs/zh-TW/mcp)子程序不會設定此變數，因為它們是長期存在的程序，會比產生它們的工作階段存活得更久。與 `CLAUDECODE` 不同，此變數僅由 Claude Code 本身在啟動子程序時設定，IDE 擴充功能不會設定，因此能可靠地區分巢狀工作階段與在 IDE 整合式終端機中啟動的頂層 `claude`。以此方式啟動的巢狀互動式 `claude` TUI 會自動從 `--resume`、`--continue`、向上鍵歷史記錄及 `claude agents` 清單中排除。非互動的 `claude -p` 工作階段仍會保存。設定 `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1` 可覆寫此排除。需要 Claude Code v2.1.172 或更新版本 |

237| `CLAUDE_CODE_CONNECT_TIMEOUT_MS` | 已在 v2.1.186 中移除，現在不具作用。先前用於為串流 API 請求的連線、TLS 和回應標頭階段設定個別逾時。請使用 `API_TIMEOUT_MS` 設定每個請求的逾時。關於串流請求的回應標頭階段，請參閱 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` |239| `CLAUDE_CODE_CONNECT_TIMEOUT_MS` | 已於 v2.1.186 移除，現在不會有任何作用。先前用於為串流 API 請求的連線、TLS 與回應標頭階段設定個別逾時。請使用 `API_TIMEOUT_MS` 設定每個請求的逾時。關於串流請求的回應標頭階段，請參閱 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` |

238| `CLAUDE_CODE_DEBUG_LOGS_DIR` | 覆寫偵錯日誌檔案路徑。儘管名稱如此，這是檔案路徑，而非目錄。需要另外透過 `--debug`、`/debug` 或 `DEBUG` 環境變數啟用偵錯模式：僅設定此變數並不會啟用日誌記錄。[`--debug-file`](/docs/zh-TW/cli-reference#cli-flags) 旗標可同時完成兩者。預設為 `~/.claude/debug/<session-id>.txt` |240| `CLAUDE_CODE_DEBUG_LOGS_DIR` | 覆寫偵錯日誌檔案路徑。儘管名稱如此，這是檔案路徑而非目錄。需透過 `--debug`、`/debug` 或 `DEBUG` 環境變數另外啟用偵錯模式：僅設定此變數並不會啟用日誌記錄。[`--debug-file`](/docs/zh-TW/cli-reference#cli-flags) 旗標可同時完成兩者。預設為 `~/.claude/debug/<session-id>.txt` |

239| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | 寫入偵錯日誌檔案的最低日誌等級。值：`verbose`、`debug`（預設）、`info`、`warn`、`error`。設為 `verbose` 可包含高流量的診斷資訊，例如完整的狀態列命令輸出；或提高至 `error` 以減少雜訊 |241| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | 寫入偵錯日誌檔案的最低日誌等級。值：`verbose`、`debug`（預設）、`info`、`warn`、`error`。設為 `verbose` 可包含大量診斷資訊，例如完整的狀態列命令輸出；或提高至 `error` 以減少雜訊 |

240| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | 設為 `1` 可停用 [1M 上下文視窗](/docs/zh-TW/model-config#extended-context)支援。設定後，模型選擇器中將無法使用 1M 模型變體，且 Claude Code 會將使用原生 1M 視窗之模型（例如 [Sonnet 5.5](/docs/zh-TW/model-config#sonnet-5-5-and-sonnet-5-context-window) 和 Fable 模型）的工作階段限制在 200K 視窗；關於此限制如何強制執行，請參閱[延伸上下文](/docs/zh-TW/model-config#extended-context)。適用於有合規要求的企業環境。關於其在修正無法辨識之 `[1m]` 模型 ID 視窗方面的作用，請參閱[修正閘道或自訂模型 ID 的視窗](/docs/zh-TW/model-config#correct-the-window-for-a-gateway-or-custom-model-id) |242| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | 設為 `1` 可停用 [1M 上下文視窗](/docs/zh-TW/model-config#extended-context)支援。設定後，模型選擇器中將無法使用 1M 模型變體，且 Claude Code 會將使用原生 1M 視窗之模型（例如 [Sonnet 5.5](/docs/zh-TW/model-config#sonnet-5-5-and-sonnet-5-context-window) 與 Fable 模型）的工作階段限制在 200K 視窗；關於如何強制執行此限制，請參閱[延伸上下文](/docs/zh-TW/model-config#extended-context)。適用於有法規遵循要求的企業環境。關於此變數在修正無法辨識之 `[1m]` 模型 ID 視窗時的作用，請參閱[修正閘道或自訂模型 ID 的視窗](/docs/zh-TW/model-config#correct-the-window-for-a-gateway-or-custom-model-id) |

241| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | 設為 `1` 可在 Opus 4.6 和 Sonnet 4.6 上停用[自適應推理](/docs/zh-TW/model-config#adjust-effort-level)，並改用由 `MAX_THINKING_TOKENS` 控制的固定思考預算。對 [Fable 模型](/docs/zh-TW/model-config#extended-thinking)、Sonnet 5 及更新版本，或 Opus 4.7 及更新版本沒有作用，這些模型一律使用自適應推理 |243| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | 設為 `1` 可在 Opus 4.6 與 Sonnet 4.6 上停用[自適應推理](/docs/zh-TW/model-config#adjust-effort-level)，並改用由 `MAX_THINKING_TOKENS` 控制的固定思考預算。對 [Fable 模型](/docs/zh-TW/model-config#extended-thinking)、Sonnet 5 及更新版本、Haiku 5.5，或 Opus 4.7 及更新版本沒有作用，這些模型一律使用自適應推理 |

242| `CLAUDE_CODE_DISABLE_ADMIN_ENV_UNION` | 設為 `1` 可阻止 Claude Code 跨管理來源逐鍵合併[受管設定](/docs/zh-TW/managed-settings#precedence-within-the-managed-tier)的 `env` 區塊，使得只有最高優先順序來源的整個 `env` 區塊生效，如同 v2.1.223 之前的行為。請在啟動 Claude Code 的環境中設定，因為 Claude Code 會忽略透過設定 `env` 區塊傳遞的副本。需要 Claude Code v2.1.223 或更新版本 |244| `CLAUDE_CODE_DISABLE_ADMIN_ENV_UNION` | 設為 `1` 可讓 Claude Code 停止跨管理來源依鍵合併[受管設定](/docs/zh-TW/managed-settings#precedence-within-the-managed-tier)的 `env` 區塊，因此只會套用最高優先順序來源的整個 `env` 區塊，與 v2.1.223 之前相同。請在啟動 Claude Code 的環境中設定，因為 Claude Code 會忽略透過設定 `env` 區塊傳遞的副本。需要 Claude Code v2.1.223 或更新版本 |

243| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | 設為 `1` 可停用 [advisor 工具](/docs/zh-TW/advisor)。`/advisor` 命令將無法使用，任何已設定的 `advisorModel` 都會被忽略，而 `--advisor` 旗標仍可接受但沒有作用，因此傳遞此旗標的現有指令碼仍可正常運作而不會出錯 |245| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | 設為 `1` 可停用 [advisor 工具](/docs/zh-TW/advisor)。`/advisor` 命令將無法使用，任何已設定的 `advisorModel` 都會被忽略，而 `--advisor` 旗標仍會被接受但沒有作用，因此傳入該旗標的現有指令碼可繼續正常運作而不會出錯 |

244| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | 設為 `1` 可關閉[背景 agent 和 agent view](/docs/zh-TW/agent-view)：`claude agents`、`--bg`、`/background` 以及隨需啟動的監督程序。等同於 [`disableAgentView`](/docs/zh-TW/settings-reference#disableagentview) 設定 |246| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | 設為 `1` 可關閉[背景 agent 與 agent view](/docs/zh-TW/agent-view)：`claude agents`、`--bg`、`/background` 及隨需 supervisor。等同於 [`disableAgentView`](/docs/zh-TW/settings-reference#disableagentview) 設定 |

245| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | 設為 `1` 可停用[全螢幕呈現](/docs/zh-TW/fullscreen)並使用傳統的主畫面呈現器。對話會保留在終端機的原生捲動緩衝區中，因此 `Cmd+f` 和 tmux 複製模式可照常運作。優先於 `CLAUDE_CODE_NO_FLICKER` 和 [`tui`](/docs/zh-TW/settings-reference#tui) 設定。您也可以使用 `/tui default` 切換。不適用於從 [agent view](/docs/zh-TW/agent-view) 開啟的背景工作階段，這些工作階段一律使用全螢幕呈現 |247| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | 設為 `1` 可停用[全螢幕呈現](/docs/zh-TW/fullscreen)並使用傳統的主畫面呈現器。對話會保留在終端機的原生捲動緩衝區中，因此 `Cmd+f` 與 tmux 複製模式可照常運作。優先於 `CLAUDE_CODE_NO_FLICKER` 與 [`tui`](/docs/zh-TW/settings-reference#tui) 設定。您也可以使用 `/tui default` 切換。不適用於從 [agent view](/docs/zh-TW/agent-view) 開啟的背景工作階段，這些工作階段一律使用全螢幕呈現 |

246| `CLAUDE_CODE_DISABLE_ARTIFACT` | 設為 `1` 可關閉 [Artifact](/docs/zh-TW/artifacts) 工具，該工具會將工作階段輸出發布為 claude.ai 上的私人網頁。設定後，任何設定檔都無法重新開啟此工具。若要改從設定檔關閉此工具，請將 [`enableArtifact`](/docs/zh-TW/settings-reference#enableartifact) 設為 `false`；已棄用的 [`disableArtifact`](/docs/zh-TW/settings-reference#disableartifact) 鍵也可關閉此工具 |248| `CLAUDE_CODE_DISABLE_ARTIFACT` | 設為 `1` 可關閉 [Artifact](/docs/zh-TW/artifacts) 工具，該工具會將工作階段輸出發佈為 claude.ai 上的私人網頁。設定後，任何設定檔都無法重新開啟此工具。若要改從設定檔關閉此工具，請將 [`enableArtifact`](/docs/zh-TW/settings-reference#enableartifact) 設為 `false`；已棄用的 [`disableArtifact`](/docs/zh-TW/settings-reference#disableartifact) 鍵也能將其關閉 |

248| `CLAUDE_CODE_DISABLE_AUTH_REFRESH_LOCK` | 設為 `1` 可讓 Claude Code 程序自行執行其 [`gcpAuthRefresh`](/docs/zh-TW/settings-reference#gcpauthrefresh) 或 [`awsAuthRefresh`](/docs/zh-TW/settings-reference#awsauthrefresh) 命令，而非在另一個程序執行該命令時等待。需要 Claude Code v2.1.286 或更新版本 |250| `CLAUDE_CODE_DISABLE_AUTH_REFRESH_LOCK` | 設為 `1` 可讓 Claude Code 程序自行執行其 [`gcpAuthRefresh`](/docs/zh-TW/settings-reference#gcpauthrefresh) 或 [`awsAuthRefresh`](/docs/zh-TW/settings-reference#awsauthrefresh) 命令，而非在另一個程序執行時等待。需要 Claude Code v2.1.286 或更新版本 |

249| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | 設為 `1` 可停用[自動記憶](/docs/zh-TW/memory#auto-memory)。設為 `0` 可強制開啟自動記憶，即使 `--bare` 模式或 [`autoMemoryEnabled: false`](/docs/zh-TW/settings-reference#automemoryenabled) 原本會停用它。停用時，Claude 不會建立或載入自動記憶檔案 |251| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | 設為 `1` 可停用[自動記憶](/docs/zh-TW/memory#auto-memory)。設為 `0` 可強制開啟自動記憶，即使 `--bare` 模式或 [`autoMemoryEnabled: false`](/docs/zh-TW/settings-reference#automemoryenabled) 原本會將其停用。停用時，Claude 不會建立或載入自動記憶檔案 |

250| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | 設為 `1` 可停用所有背景任務功能，包括 Bash 和 subagent 工具上的 `run_in_background` 參數、自動背景化以及 Ctrl+B 快捷鍵 |252| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | 設為 `1` 可停用所有背景任務功能，包括 Bash 與 subagent 工具上的 `run_in_background` 參數、自動背景化，以及 Ctrl+B 快速鍵 |

251| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_DEFAULT` | 設為 `1` 可阻止 Claude Code 將缺少 `Content-Type` 標頭或該標頭為空的 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 串流回應視為 Amazon Bedrock 的二進位事件串流。根據預設，Claude Code 會假設閘道從原本未經修改的回應中移除了該標頭，因此會解碼主體，讓串流持續運作。僅在閘道同時將串流重新以 server-sent events 發出時才設定此變數；Claude Code 接著會改為將沒有標頭的主體讀取為 server-sent events。需要 Claude Code v2.1.239 或更新版本 |253| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_DEFAULT` | 設為 `1` 可讓 Claude Code 停止將缺少或為空 `Content-Type` 標頭的 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 串流回應視為 Amazon Bedrock 的二進位事件串流。預設情況下，Claude Code 會假設是閘道從原本未修改的回應中移除了該標頭，因此會解碼主體，讓串流持續運作。僅在閘道同時將串流重新以 server-sent events 發出時才設定此變數；屆時 Claude Code 會改將無標頭的主體讀取為 server-sent events。需要 Claude Code v2.1.239 或更新版本 |

252| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` | 設為 `1` 可略過檢查 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 串流回應是否帶有 `application/vnd.amazon.eventstream` content-type。若未設定此變數，當回應帶有不同的 content-type 時，Claude Code 會讓請求失敗並顯示指出該類型的錯誤，這表示[閘道或代理伺服器正在轉換回應](/docs/zh-TW/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)。請設定閘道以未經修改的方式轉送 `Content-Type` 標頭和主體，而非設定此變數。需要 Claude Code v2.1.208 或更新版本 |254| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` | 設為 `1` 可略過檢查 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 串流回應是否帶有 `application/vnd.amazon.eventstream` content-type。若未設定此變數，當回應帶有不同的 content-type 時，Claude Code 會使請求失敗並顯示指出該類型的錯誤，這表示有[閘道或代理伺服器正在轉換回應](/docs/zh-TW/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)。請設定閘道不加修改地轉送 `Content-Type` 標頭與主體，而非設定此變數。需要 Claude Code v2.1.208 或更新版本 |

253| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | 設為 `1` 可在[監督程序](/docs/zh-TW/agent-view#the-supervisor-process)停止、重新啟動或更新[背景工作階段](/docs/zh-TW/agent-view)的程序時，停止該工作階段正在執行的背景 shell 命令、動態工作流程，以及自 v2.1.198 起的背景 subagent，而非將它們移交給該工作階段的下一個程序。僅影響該移交：使用 `←` 或 [`/background`](/docs/zh-TW/agent-view#from-inside-a-session) 將工作階段移至背景時，仍會延續進行中的工作，而 `CLAUDE_DISABLE_ADOPT` 會同時關閉兩者。需要 Claude Code v2.1.196 或更新版本 |255| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | 設為 `1` 可在 [supervisor](/docs/zh-TW/agent-view#the-supervisor-process) 停止、重新啟動或更新[背景工作階段](/docs/zh-TW/agent-view)的程序時，停止該工作階段正在執行的背景 shell 命令、動態工作流程，以及自 v2.1.198 起的背景 subagent，而非將它們交給該工作階段的下一個程序。僅影響此交接：使用 `←` 或 [`/background`](/docs/zh-TW/agent-view#from-inside-a-session) 將工作階段背景化時，仍會延續進行中的工作，而 `CLAUDE_DISABLE_ADOPT` 會同時關閉兩者。需要 Claude Code v2.1.196 或更新版本 |

254| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | 設為 `1` 可阻止 Claude Code 在記憶體壓力下終止[背景 shell 命令](/docs/zh-TW/interactive-mode#background-bash-commands)。根據預設，在 macOS 和 Linux 上，當作業系統回報嚴重的記憶體壓力，且工作階段已閒置 30 分鐘、沒有任何回合或 subagent 在執行時，Claude Code 會終止背景 shell。Windows 沒有記憶體壓力訊號，因此此變數在該平台上沒有作用。需要 Claude Code v2.1.193 或更新版本 |256| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | 設為 `1` 可讓 Claude Code 停止在記憶體壓力下終止[背景 shell 命令](/docs/zh-TW/interactive-mode#background-bash-commands)。預設情況下，在 macOS 與 Linux 上，當作業系統回報嚴重記憶體壓力，且工作階段已閒置 30 分鐘、沒有任何回合或 subagent 在執行時，Claude Code 會終止背景 shell。Windows 沒有記憶體壓力訊號，因此此變數在該平台上沒有作用。需要 Claude Code v2.1.193 或更新版本 |

255| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | 設為 `1` 可停用 Claude Code 隨附的 [skill](/docs/zh-TW/skills) 和工作流程：隨附的 skill 和工作流程會被完全移除，而 `/init` 等內建命令仍可輸入，但會對模型隱藏。`/doctor` 與內建命令一樣仍可輸入；請改用 `DISABLE_DOCTOR_COMMAND` 將其隱藏。來自外掛、`.claude/skills/` 和 `.claude/commands/` 的 skill 不受影響。等同於 [`disableBundledSkills`](/docs/zh-TW/settings-reference#disablebundledskills) 設定 |257| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | 設為 `1` 可停用 Claude Code 隨附的 [skill](/docs/zh-TW/skills) 與工作流程：隨附 skill 與工作流程會被完全移除，而 `/init` 等內建命令仍可輸入，但會對模型隱藏。`/doctor` 與內建命令一樣仍可輸入；請改用 `DISABLE_DOCTOR_COMMAND` 將其隱藏。來自外掛、`.claude/skills/` 與 `.claude/commands/` 的 skill 不受影響。等同於 [`disableBundledSkills`](/docs/zh-TW/settings-reference#disablebundledskills) 設定 |

256| `CLAUDE_CODE_DISABLE_CFC_PROMPT` | 設為 `1` 可保留 [Claude in Chrome](/docs/zh-TW/chrome) 瀏覽器工具，同時省略系統提示詞中的 Chrome 區段以及 `/claude-in-chrome` [隨附 skill](/docs/zh-TW/skills#bundled-skills)。適用於內嵌 Claude Code 並提供自己的瀏覽器指引的主機。需要 Claude Code v2.1.257 或更新版本 |258| `CLAUDE_CODE_DISABLE_CFC_PROMPT` | 設為 `1` 可保留 [Claude in Chrome](/docs/zh-TW/chrome) 瀏覽器工具，同時省略系統提示詞中的 Chrome 章節與 `/claude-in-chrome` [隨附 skill](/docs/zh-TW/skills#bundled-skills)。適用於嵌入 Claude Code 並提供自有瀏覽器指引的主機。需要 Claude Code v2.1.257 或更新版本 |

258| `CLAUDE_CODE_DISABLE_CRON` | 設為 `1` 可停用[排程任務](/docs/zh-TW/scheduled-tasks)。`/loop` skill 和 cron 工具將無法使用，且任何已排程的任務都會停止觸發，包括已在工作階段中途執行的任務 |260| `CLAUDE_CODE_DISABLE_CRON` | 設為 `1` 可停用[排程任務](/docs/zh-TW/scheduled-tasks)。`/loop` skill 與 cron 工具將無法使用，且任何已排程的任務都會停止觸發，包括在工作階段中已在執行的任務 |

259| `CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT` | 設為 `1` 可關閉[關鍵路徑移除](/docs/zh-TW/permission-modes#critical-paths)提示的時間限制。在 `auto` 模式下，Claude Code 會改為將這些移除傳送給分類器；在 `bypassPermissions` 模式下，提示會等待您的回答。請在啟動 Claude Code 的環境中設定，因為 Claude Code 會忽略透過設定 `env` 區塊傳遞的副本。需要 Claude Code v2.1.281 或更新版本 |261| `CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT` | 設為 `1` 可關閉[關鍵路徑移除](/docs/zh-TW/permission-modes#critical-paths)提示的時間限制。在 `auto` 模式中，Claude Code 會改將這些移除操作傳送給分類器；在 `bypassPermissions` 模式中，提示會等待您的回答。請在啟動 Claude Code 的環境中設定，因為 Claude Code 會忽略透過設定 `env` 區塊傳遞的副本。需要 Claude Code v2.1.281 或更新版本 |

260| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | 設為 `1` 可從 API 請求中移除預先發布版的 `anthropic-beta` 請求標頭、與其搭配的主體欄位，以及 `defer_loading` 和 `eager_input_streaming` 等 beta 工具結構描述欄位。當代理伺服器閘道因 `anthropic-beta` 標頭而以 `Unexpected value(s)` 錯誤拒絕請求，或出現 `Extra inputs are not permitted` 錯誤時使用。[停用預先發布版功能](/docs/zh-TW/llm-gateway-protocol#disable-pre-release-capabilities)列出了此變數移除的項目，包括 [MCP Tool Search](/docs/zh-TW/mcp#scale-with-mcp-tool-search)，以及 Claude Code 仍會持續傳送的項目 |262| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | 設為 `1` 可從 API 請求中移除搶先體驗版的 `anthropic-beta` 請求標頭、與其搭配的主體欄位，以及 `defer_loading` 與 `eager_input_streaming` 等 beta 工具結構描述欄位。當代理伺服器閘道以 `anthropic-beta` 標頭的 `Unexpected value(s)` 錯誤或 `Extra inputs are not permitted` 錯誤拒絕請求時，請使用此設定。[停用搶先體驗功能](/docs/zh-TW/llm-gateway-protocol#disable-pre-release-capabilities)列出此變數移除的項目（包括 [MCP Tool Search](/docs/zh-TW/mcp#scale-with-mcp-tool-search)），以及 Claude Code 仍會持續傳送的項目 |

261| `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS` | 設為 `1` 可停用內建的 [Explore 和 Plan subagent](/docs/zh-TW/sub-agents#built-in-subagents)。Claude 會改用其搜尋工具或 general-purpose subagent 進行探索，而 [plan mode](/docs/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 會直接讀取檔案，而非啟動 Explore 和 Plan agent。名為 `Explore` 或 `Plan` 的自訂 subagent 不受影響。若要在 Agent SDK 或非互動模式中移除所有內建 subagent 類型，請改用 `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS`。需要 Claude Code v2.1.198 或更新版本 |263| `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS` | 設為 `1` 可停用內建的 [Explore 與 Plan subagent](/docs/zh-TW/sub-agents#built-in-subagents)。Claude 會改用其搜尋工具或 general-purpose subagent 進行探索，而 [plan mode](/docs/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 會直接讀取檔案，而非啟動 Explore 與 Plan agent。名為 `Explore` 或 `Plan` 的自訂 subagent 不受影響。若要在 Agent SDK 或非互動模式中移除所有內建 subagent 類型，請改用 `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS`。需要 Claude Code v2.1.198 或更新版本 |

263| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | 設為 `1` 可停用「How is Claude doing?」工作階段品質問卷。當設定了 `DISABLE_TELEMETRY`、`DO_NOT_TRACK` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 時，問卷也會停用，除非 `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` 重新選擇加入。若要設定取樣率而非完全停用，請使用 [`feedbackSurveyRate`](/docs/zh-TW/settings-reference#feedbacksurveyrate) 設定。請參閱[工作階段品質問卷](/docs/zh-TW/data-usage#session-quality-surveys) |265| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | 設為 `1` 可停用「How is Claude doing?」工作階段品質調查。當設定了 `DISABLE_TELEMETRY`、`DO_NOT_TRACK` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 時，調查也會停用，除非 `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` 重新選擇加入。若要設定抽樣率而非完全停用，請使用 [`feedbackSurveyRate`](/docs/zh-TW/settings-reference#feedbacksurveyrate) 設定。請參閱[工作階段品質調查](/docs/zh-TW/data-usage#session-quality-surveys) |

264| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | 設為 `1` 可停用檔案[檢查點功能](/docs/zh-TW/checkpointing)。`/rewind` 命令將無法還原程式碼變更。覆寫 [`fileCheckpointingEnabled`](/docs/zh-TW/settings-reference#filecheckpointingenabled) 設定 |266| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | 設為 `1` 可停用檔案[檢查點功能](/docs/zh-TW/checkpointing)。`/rewind` 命令將無法還原程式碼變更。覆寫 [`fileCheckpointingEnabled`](/docs/zh-TW/settings-reference#filecheckpointingenabled) 設定 |

265| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | 設為 `1` 可從 Claude 的上下文中移除內建的提交和 PR 工作流程指令以及 git 狀態快照。在使用您自己的 git 工作流程 skill 時很有用。設定後優先於 [`includeGitInstructions`](/docs/zh-TW/settings-reference#includegitinstructions) 設定 |267| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | 設為 `1` 可從 Claude 的上下文中移除內建的提交與 PR 工作流程指令，以及 git 狀態快照。適用於使用您自己的 git 工作流程 skill 時。設定後，優先於 [`includeGitInstructions`](/docs/zh-TW/settings-reference#includegitinstructions) 設定 |

266| `CLAUDE_CODE_DISABLE_INLINE_SHELL_RM_PROMPT` | 設為 `1` 可阻止 Claude Code 讀取以 `-c` 傳遞給 shell 的指令碼（例如 `bash -c 'rm -rf ~'`）以檢查[關鍵路徑](/docs/zh-TW/permission-modes#removals-inside-nested-commands-and-inline-scripts)移除。Claude Code 仍會檢查這些指令碼中的 shell 變數和位置參數目標，其他關鍵路徑檢查也會持續執行。請在啟動 Claude Code 的環境中設定，因為 Claude Code 會忽略透過設定 `env` 區塊傳遞的副本。需要 Claude Code v2.1.288 或更新版本 |268| `CLAUDE_CODE_DISABLE_INLINE_SHELL_RM_PROMPT` | 設為 `1` 可讓 Claude Code 停止讀取以 `-c` 傳給 shell 的指令碼（例如 `bash -c 'rm -rf ~'`）來檢查[關鍵路徑](/docs/zh-TW/permission-modes#removals-inside-nested-commands-and-inline-scripts)移除操作。Claude Code 仍會檢查這些指令碼中的 shell 變數與位置參數目標，其他關鍵路徑檢查也會持續執行。請在啟動 Claude Code 的環境中設定，因為 Claude Code 會忽略透過設定 `env` 區塊傳遞的副本。需要 Claude Code v2.1.288 或更新版本 |

267| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | 設為 `1` 可防止在 Anthropic API 上將 Opus 4.0 和 4.1 自動重新對應至目前的 Opus 版本。當您刻意想要固定使用較舊的模型時使用。此重新對應不會在 Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry 上執行 |269| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | 設為 `1` 可防止在 Anthropic API 上將 Opus 4.0 與 4.1 自動重新對應至目前的 Opus 版本。當您刻意想固定較舊的模型時使用。此重新對應不會在 Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry 上執行 |

268| `CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK` | 設為 `1` 可阻止 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock#when-a-model-is-disabled-mid-session) 和 [Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai#when-a-model-is-disabled-mid-session) 上的 Claude Code 在您的帳戶於工作階段中途失去該工作階段模型的存取權時切換至較舊的模型；被拒絕的請求會改為立即失敗。您設定的[備援模型鏈](/docs/zh-TW/model-config#fallback-model-chains)在該拒絕發生時仍會切換，且[啟動模型檢查](/docs/zh-TW/amazon-bedrock#startup-model-checks)在啟動時仍會改用備援。需要 Claude Code v2.1.285 或更新版本 |270| `CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK` | 設為 `1` 可讓 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock#when-a-model-is-disabled-mid-session) 與 [Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai#when-a-model-is-disabled-mid-session) 上的 Claude Code，在您的帳戶於工作階段中途失去該工作階段模型的存取權時，不改用較舊的模型；被拒絕的請求會立即失敗。您設定的[備援模型鏈](/docs/zh-TW/model-config#fallback-model-chains)在遭到此拒絕時仍會切換，而[啟動模型檢查](/docs/zh-TW/amazon-bedrock#startup-model-checks)在啟動時仍會改用備援模型。需要 Claude Code v2.1.285 或更新版本 |

269| `CLAUDE_CODE_DISABLE_MOUSE` | 設為 `1` 可在[全螢幕呈現](/docs/zh-TW/fullscreen)中停用滑鼠追蹤。使用 `PgUp` 和 `PgDn` 的鍵盤捲動仍可運作。使用此設定可保留終端機原生的選取即複製行為 |271| `CLAUDE_CODE_DISABLE_MOUSE` | 設為 `1` 可在[全螢幕呈現](/docs/zh-TW/fullscreen)中停用滑鼠追蹤。使用 `PgUp` 與 `PgDn` 的鍵盤捲動仍可運作。使用此設定可保留終端機原生的選取即複製行為 |

270| `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` | 設為 `1` 可在[全螢幕呈現](/docs/zh-TW/fullscreen)中停用點按、拖曳和懸停處理，同時保留滑鼠滾輪捲動。當您希望滾輪捲動在 Claude Code 中運作，但不希望點按會定位游標、展開工具輸出或開啟連結時使用。兩者都設定時，`CLAUDE_CODE_DISABLE_MOUSE` 優先。需要 Claude Code v2.1.195 或更新版本 |272| `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` | 設為 `1` 可在[全螢幕呈現](/docs/zh-TW/fullscreen)中停用點擊、拖曳與懸停處理，同時保留滑鼠滾輪捲動。當您希望在 Claude Code 中使用滾輪捲動，但不希望點擊會移動游標、展開工具輸出或開啟連結時，請使用此設定。兩者都設定時，`CLAUDE_CODE_DISABLE_MOUSE` 優先。需要 Claude Code v2.1.195 或更新版本 |

271| `CLAUDE_CODE_DISABLE_MTLS_RELOAD_ON_STALE_CONNECTION` | 設為 `1` 可阻止 Claude Code 在 API 請求因連線層級錯誤（例如連線重設或 TLS 交握錯誤）而失敗時，重新讀取 [mTLS 用戶端憑證和金鑰](/docs/zh-TW/network-config#mtls-authentication)。停用重新載入後，Claude Code 只會在下次套用設定時或下次啟動時載入輪替後的檔案。需要 Claude Code v2.1.232 或更新版本 |273| `CLAUDE_CODE_DISABLE_MTLS_RELOAD_ON_STALE_CONNECTION` | 設為 `1` 可讓 Claude Code 在 API 請求因連線層級錯誤（例如連線重設或 TLS 交握錯誤）失敗時，停止重新讀取 [mTLS 用戶端憑證與金鑰](/docs/zh-TW/network-config#mtls-authentication)。停用重新載入後，Claude Code 只會在下次套用設定時或下次啟動時載入已輪替的檔案。需要 Claude Code v2.1.232 或更新版本 |

272| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 設為任何非空值（例如 `1`）可停用非必要的網路流量：自動更新、遙測、錯誤回報、`/feedback` 命令、[Claude 草擬的意見回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior)、版本說明、[PR 和 MR 狀態徽章](/docs/zh-TW/interactive-mode#pr-review-status)檢查，以及[快速模式](/docs/zh-TW/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)檢查等可用性檢查。它也會停止[外掛 `command` 來源的背景執行](/docs/zh-TW/plugins/loading#when-a-command-source-re-runs)，這些是本機命令而非網路流量，但因為它們可能觸發相依套件安裝而一併停止。**將其設為 `0` 或 `false` 仍會停用此流量**，這與大多數開關變數不同；請取消設定此變數以再次允許。也會停用功能旗標擷取，這會使 [Remote Control](/docs/zh-TW/remote-control#requirements) 和其他[需要功能旗標擷取的功能](#features-that-need-feature-flag-fetching)無法使用。官方外掛市集的自動安裝不在涵蓋範圍內；請使用 `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` 停用。不影響[閘道模型探索](/docs/zh-TW/llm-gateway-connect#add-gateway-models-to-the-model-picker)，該功能有其自己的選擇加入設定 |274| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 設為任何非空值（例如 `1`）可停用非必要的網路流量：自動更新、遙測、錯誤回報、`/feedback` 命令、[Claude 草擬的意見回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior)、版本資訊、[PR 與 MR 狀態徽章](/docs/zh-TW/interactive-mode#pr-review-status)檢查，以及[快速模式](/docs/zh-TW/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)檢查等可用性檢查。它也會停止[外掛 `command` 來源的背景執行](/docs/zh-TW/plugins/loading#when-a-command-source-re-runs)，這些是本機命令而非網路流量，但因為它們可能觸發相依套件安裝，所以一併停止。**設為 `0` 或 `false` 仍會停用此流量**，這與大多數開關型變數不同；請取消設定此變數才能再次允許。也會停用功能旗標擷取，這會使 [Remote Control](/docs/zh-TW/remote-control#requirements) 及其他[需要功能旗標擷取的功能](#features-that-need-feature-flag-fetching)無法使用。不涵蓋官方外掛市集的自動安裝；請使用 `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` 將其停用。不影響[閘道模型探索](/docs/zh-TW/llm-gateway-connect#add-gateway-models-to-the-model-picker)，該功能有其自己的選擇加入機制 |

274| `CLAUDE_CODE_DISABLE_NOTIFICATION_PRESENCE_CHECK` | 設為 `1` 可在您於終端機中輸入或聚焦於終端機時，仍傳送 `PushNotification` 工具的桌面通知。根據預設，當工具偵測到近期的鍵盤活動或終端機焦點時，會同時略過桌面通知和[行動推播](/docs/zh-TW/remote-control#mobile-push-notifications)。此變數僅停用該本機檢查，因此當伺服器偵測到您處於活動狀態時，仍可抑制行動推播。需要 Claude Code v2.1.193 或更新版本 |276| `CLAUDE_CODE_DISABLE_NOTIFICATION_PRESENCE_CHECK` | 設為 `1` 可讓 `PushNotification` 工具即使在您正在終端機中輸入或終端機處於焦點時，仍傳送桌面通知。預設情況下，當偵測到近期的鍵盤活動或終端機焦點時，該工具會同時略過桌面通知與[行動推播](/docs/zh-TW/remote-control#mobile-push-notifications)。此變數僅停用該本機檢查，因此當伺服器偵測到您處於活動狀態時，仍可能抑制行動推播。需要 Claude Code v2.1.193 或更新版本 |

275| `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` | 設為 `1` 可停用官方外掛市集的自動註冊。Claude Code 會在即將註冊市集時讀取此變數，通常是在電腦首次互動式啟動期間。如果當時已設定此變數，Claude Code 會永久略過註冊。之後取消設定此變數並不會撤銷該略過。隨時執行 `claude plugin marketplace add anthropics/claude-plugins-official` 即可註冊市集 |277| `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` | 設為 `1` 可停用官方外掛市集的自動註冊。Claude Code 會在即將註冊市集時讀取此變數，通常是在機器首次互動式啟動期間。若當時已設定此變數，Claude Code 會永久略過註冊。之後取消設定此變數並不會撤銷略過。您可以隨時執行 `claude plugin marketplace add anthropics/claude-plugins-official` 來註冊市集 |

276| `CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS` | 設為 `1` 可阻止 Claude Code 在將權限請求傳送至 Agent SDK `canUseTool` 回呼的工作階段中，執行您[針對未回應權限請求的 `Notification` hook](/docs/zh-TW/hooks#notification)；Claude Desktop 和 VS Code 擴充功能正是以此方式承載 Claude Code。在終端機工作階段中沒有作用。需要 Claude Code v2.1.233 或更新版本 |278| `CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS` | 設為 `1` 可讓 Claude Code 在將權限請求傳送至 Agent SDK 的 `canUseTool` 回呼的工作階段中，停止執行您的[針對未回答權限請求的 `Notification` hook](/docs/zh-TW/hooks#notification)；Claude Desktop 與 VS Code 擴充功能即是以此方式承載 Claude Code。在終端機工作階段中沒有作用。需要 Claude Code v2.1.233 或更新版本 |

278| `CLAUDE_CODE_DISABLE_POWERSHELL_CMD_RM_DENY` | 設為 `1` 可關閉 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool)中拒絕在[系統路徑](/docs/zh-TW/permission-modes#remove-item-in-powershell)（例如磁碟機根目錄或您的家目錄）上使用 `cmd` 內建命令 `rd`、`rmdir`、`del` 和 `erase` 的檢查。Claude Code 會忽略設定檔 `env` 區塊中的此變數。需要 Claude Code v2.1.283 或更新版本 |280| `CLAUDE_CODE_DISABLE_POWERSHELL_CMD_RM_DENY` | 設為 `1` 可關閉 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool)的檢查，該檢查會拒絕在[系統路徑](/docs/zh-TW/permission-modes#remove-item-in-powershell)（例如磁碟機根目錄或您的家目錄）上使用 `cmd` 內建命令 `rd`、`rmdir`、`del` 與 `erase`。Claude Code 會忽略設定檔 `env` 區塊中的此變數。需要 Claude Code v2.1.283 或更新版本 |

279| `CLAUDE_CODE_DISABLE_REFUSAL_FALLBACK` | 設為 `1` 可關閉[安全分類器標記請求時的自動模型切換](/docs/zh-TW/model-config#automatic-model-fallback)，也就是 [`switchModelsOnFlag`](/docs/zh-TW/settings-reference#switchmodelsonflag) 設定所控制的行為 |281| `CLAUDE_CODE_DISABLE_REFUSAL_FALLBACK` | 設為 `1` 可關閉[安全分類器標記請求時的自動模型切換](/docs/zh-TW/model-config#automatic-model-fallback)，即由 [`switchModelsOnFlag`](/docs/zh-TW/settings-reference#switchmodelsonflag) 設定所控制的行為 |

280| `CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS` | 設為 `1` 可阻止 Claude Code 傳送結構化輸出的 `output_config.format` 欄位以及與其搭配的 `anthropic-beta` 值，適用於上游會拒絕這些項目的 [LLM 閘道](/docs/zh-TW/llm-gateway-protocol#feature-pass-through)。這會保留 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/zh-TW/llm-gateway-protocol#disable-pre-release-capabilities) 所關閉的其他預先發布版功能。需要 Claude Code v2.1.288 或更新版本 |282| `CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS` | 設為 `1` 可讓 Claude Code 停止傳送結構化輸出的 `output_config.format` 欄位及與其搭配的 `anthropic-beta` 值，適用於上游會拒絕這些內容的 [LLM 閘道](/docs/zh-TW/llm-gateway-protocol#feature-pass-through)。這會保留 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/zh-TW/llm-gateway-protocol#disable-pre-release-capabilities) 會關閉的其他搶先體驗功能。需要 Claude Code v2.1.288 或更新版本 |

281| `CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT` | 設為 `1` 可關閉針對目標完全為命令替換輸出之遞迴 `rm`（例如 `rm -rf "$(pwd)"`）的[關鍵路徑](/docs/zh-TW/permission-modes#critical-paths)檢查。其他關鍵路徑檢查會持續執行。請在啟動 Claude Code 的環境中設定，因為 Claude Code 會忽略透過設定 `env` 區塊傳遞的副本。需要 Claude Code v2.1.281 或更新版本 |283| `CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT` | 設為 `1` 可關閉針對遞迴 `rm` 的[關鍵路徑](/docs/zh-TW/permission-modes#critical-paths)檢查，該 `rm` 的目標完全是命令替換的輸出，例如 `rm -rf "$(pwd)"`。其他關鍵路徑檢查會持續執行。請在啟動 Claude Code 的環境中設定，因為 Claude Code 會忽略透過設定 `env` 區塊傳遞的副本。需要 Claude Code v2.1.281 或更新版本 |

282| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | 設為 `1` 可停用根據對話上下文自動更新終端機標題。這也會略過[產生工作階段標題](/docs/zh-TW/sessions#name-your-sessions)的背景 small/fast 模型請求 |284| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | 設為 `1` 可停用根據對話上下文自動更新終端機標題。這也會略過[產生工作階段標題](/docs/zh-TW/sessions#name-your-sessions)的背景小型/快速模型請求 |

283| `CLAUDE_CODE_DISABLE_THINKING` | 設為 `1` 可完全從 API 請求中省略 `thinking` 參數。這是針對會拒絕此參數之代理伺服器和閘道的相容性選項。在預設會思考的模型上，省略此參數表示模型仍可能進行思考。若要在 Anthropic API 上明確停用[延伸思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)，請改用 `MAX_THINKING_TOKENS=0`。這兩個變數都無法在 Opus 5.5、Sonnet 5.5 或 Fable 模型上關閉思考，這些模型無法關閉思考。在[第三方供應商](/docs/zh-TW/third-party-integrations)上，`MAX_THINKING_TOKENS=0` 同樣會省略此參數，因此這兩個變數在該處的行為相同 |285| `CLAUDE_CODE_DISABLE_THINKING` | 設為 `1` 可從 API 請求中完全省略 `thinking` 參數。這是針對會拒絕該參數之代理伺服器與閘道的相容性選項。在預設會思考的模型上，省略該參數代表模型仍可能會思考。若要在 Anthropic API 上明確停用[延伸思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)，請改用 `MAX_THINKING_TOKENS=0`。這兩個變數都無法在 Opus 5.5、Sonnet 5.5、Haiku 5.5 或 Fable 模型上關閉思考，這些模型無法關閉思考。在[第三方供應商](/docs/zh-TW/third-party-integrations)上，`MAX_THINKING_TOKENS=0` 同樣會省略該參數，因此兩個變數在該處的行為相同 |

284| `CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT` | 設為 `1` 可在 Claude Code 無法辨識模型 ID（例如 [LLM 閘道](/docs/zh-TW/llm-gateway)別名）時略過主動[自動壓縮](/docs/zh-TW/costs#reduce-token-usage)。若未設定此變數，Claude Code 會在其為該 ID 假設的上下文視窗處進行壓縮。`CLAUDE_CODE_MAX_CONTEXT_TOKENS` 可改為修正假設的視窗；關於每個變數的適用時機，請參閱[修正閘道或自訂模型 ID 的視窗](/docs/zh-TW/model-config#correct-the-window-for-a-gateway-or-custom-model-id)。需要 Claude Code v2.1.223 或更新版本 |286| `CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT` | 設為 `1` 可在 Claude Code 無法辨識模型 ID（例如 [LLM 閘道](/docs/zh-TW/llm-gateway)別名）時，略過主動[自動壓縮](/docs/zh-TW/costs#reduce-token-usage)。若未設定此變數，Claude Code 會依其為該 ID 假設的上下文視窗進行壓縮。`CLAUDE_CODE_MAX_CONTEXT_TOKENS` 則可改為修正所假設的視窗；關於各變數的適用時機，請參閱[修正閘道或自訂模型 ID 的視窗](/docs/zh-TW/model-config#correct-the-window-for-a-gateway-or-custom-model-id)。需要 Claude Code v2.1.223 或更新版本 |

285| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | 設為 `1` 可在[全螢幕呈現](/docs/zh-TW/fullscreen)中停用虛擬捲動，並呈現逐字稿中的每則訊息。如果在全螢幕模式中捲動時，應該出現訊息的地方顯示空白區域，請使用此設定 |287| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | 設為 `1` 可在[全螢幕呈現](/docs/zh-TW/fullscreen)中停用虛擬捲動，並呈現逐字稿中的每一則訊息。若在全螢幕模式中捲動時，應出現訊息的地方顯示為空白區域，請使用此設定 |

286| `CLAUDE_CODE_DISABLE_WEB_FETCH` | 設為 `1` 可關閉 [WebFetch](/docs/zh-TW/tools-reference#webfetch-tool-behavior) 工具。[WebSearch](/docs/zh-TW/tools-reference#websearch-tool-behavior) 工具仍可使用。需要 Claude Code v2.1.285 或更新版本 |288| `CLAUDE_CODE_DISABLE_WEB_FETCH` | 設為 `1` 可關閉 [WebFetch](/docs/zh-TW/tools-reference#webfetch-tool-behavior) 工具。[WebSearch](/docs/zh-TW/tools-reference#websearch-tool-behavior) 工具仍可使用。需要 Claude Code v2.1.285 或更新版本 |

287| `CLAUDE_CODE_DISABLE_WINDOWS_SHELL_LAUNCHER` | 設為 `1` 可在 Windows 上直接啟動 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool)命令，而非透過 `cmd.exe` 啟動器。根據預設，啟動器可讓[在背景執行](/docs/zh-TW/tools-reference#background-commands)的 PowerShell 命令[延續至工作階段的下一個程序](/docs/zh-TW/agent-view#the-supervisor-process)，例如當您[將工作階段移至背景](/docs/zh-TW/agent-view#from-inside-a-session)時。如果您設定此變數，移至背景的 PowerShell 命令會在工作階段程序結束時停止。Bash 命令不受影響。需要 Claude Code v2.1.269 或更新版本 |289| `CLAUDE_CODE_DISABLE_WINDOWS_SHELL_LAUNCHER` | 設為 `1` 可在 Windows 上直接啟動 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool)命令，而非透過 `cmd.exe` 啟動器。預設情況下，啟動器能讓[在背景執行](/docs/zh-TW/tools-reference#background-commands)的 PowerShell 命令[延續至工作階段的下一個程序](/docs/zh-TW/agent-view#the-supervisor-process)，例如當您[將工作階段背景化](/docs/zh-TW/agent-view#from-inside-a-session)時。若您設定此變數，背景化的 PowerShell 命令會在工作階段的程序結束時停止。Bash 命令不受影響。需要 Claude Code v2.1.269 或更新版本 |

288| `CLAUDE_CODE_DISABLE_WORKFLOWS` | 設為 `1` 可停用[工作流程](/docs/zh-TW/workflows#turn-workflows-off)。等同於 [`disableWorkflows`](/docs/zh-TW/settings-reference#disableworkflows) 設定 |290| `CLAUDE_CODE_DISABLE_WORKFLOWS` | 設為 `1` 可停用[工作流程](/docs/zh-TW/workflows#turn-workflows-off)。等同於 [`disableWorkflows`](/docs/zh-TW/settings-reference#disableworkflows) 設定 |

289| `CLAUDE_CODE_EFFORT_LEVEL` | 設定支援之模型的 effort 等級。值：`low`、`medium`、`high`、`xhigh`、`max`，或 `auto` 以使用模型預設值。可用的等級取決於模型。優先於 `--effort`、`/effort`，以及 `modelSettings` 和 `effortLevel` 設定。[`maxEffortLevel`](/docs/zh-TW/settings-reference#maxeffortlevel) 上限仍然適用。請參閱[調整 effort 等級](/docs/zh-TW/model-config#adjust-effort-level) |291| `CLAUDE_CODE_EFFORT_LEVEL` | 為支援的模型設定 effort 等級。值：`low`、`medium`、`high`、`xhigh`、`max`，或 `auto` 以使用模型預設值。可用等級取決於模型。優先於 `--effort`、`/effort`，以及 `modelSettings` 與 `effortLevel` 設定。[`maxEffortLevel`](/docs/zh-TW/settings-reference#maxeffortlevel) 上限仍會套用。請參閱[調整 effort 等級](/docs/zh-TW/model-config#adjust-effort-level) |

290| `CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS` | 設為 `1` 可將帶有工作階段狀態的 [`session_state_changed`](/docs/zh-TW/agent-sdk/typescript#sdksessionstatechangedmessage) 訊息加入訊息串流。需要 [Agent SDK](/docs/zh-TW/agent-sdk/overview)，或同時使用 `--print`、`--output-format stream-json` 與 `--verbose` |292| `CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS` | 設為 `1` 可在訊息串流中加入帶有工作階段狀態的 [`session_state_changed`](/docs/zh-TW/agent-sdk/typescript#sdksessionstatechangedmessage) 訊息。需要 [Agent SDK](/docs/zh-TW/agent-sdk/overview)，或同時使用 `--print`、`--output-format stream-json` 與 `--verbose` |

291| `CLAUDE_CODE_ENABLE_AUTO_MODE` | 為了與舊版相容而接受，但不會產生任何效果。自動模式在每個供應商上預設皆可使用，包括 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry，以及已登入的 [Claude apps 閘道](/docs/zh-TW/claude-apps-gateway)工作階段。在 v2.1.158 至 v2.1.206 中，必須將此變數設為 `1`，才能在這些供應商上使用[自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) |293| `CLAUDE_CODE_ENABLE_AUTO_MODE` | 為了與舊版相容而接受，但沒有任何作用。自動模式在每個供應商上皆預設可用，包括 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry，以及已登入的 [Claude apps 閘道](/docs/zh-TW/claude-apps-gateway)工作階段。在 v2.1.158 至 v2.1.206 中，必須將此設為 `1`，才能在這些供應商上使用[自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) |

292| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | 覆寫[工作階段回顧](/docs/zh-TW/interactive-mode#session-recap)的可用性。設為 `0` 可強制關閉回顧，無論 `/config` 切換開關為何。設為 `1` 可在 [`awaySummaryEnabled`](/docs/zh-TW/settings-reference#awaysummaryenabled) 為 `false` 時強制開啟回顧。優先於該設定與 `/config` 切換開關 |294| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | 覆寫[工作階段回顧](/docs/zh-TW/interactive-mode#session-recap)的可用性。設為 `0` 可強制關閉回顧，不論 `/config` 切換開關為何。當 [`awaySummaryEnabled`](/docs/zh-TW/settings-reference#awaysummaryenabled) 為 `false` 時，設為 `1` 可強制開啟回顧。優先於該設定與 `/config` 切換開關 |

293| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 設為 `1` 可在[非互動模式](/docs/zh-TW/headless)中，於背景安裝完成後在回合邊界重新整理外掛狀態。預設為關閉，因為重新整理會在工作階段中途變更系統提示詞，使該回合的[提示快取](/docs/zh-TW/prompt-caching)失效 |295| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 設為 `1` 可在[非互動模式](/docs/zh-TW/headless)中，於背景安裝完成後在回合邊界重新整理外掛狀態。預設為關閉，因為重新整理會在工作階段中途變更系統提示詞，導致該回合的[提示快取](/docs/zh-TW/prompt-caching)失效 |

294| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | 設為 `1` 可在傳送至 Anthropic 的非必要流量遭封鎖時，將「How is Claude doing?」工作階段品質問卷路由至您自己的 [OpenTelemetry collector](/docs/zh-TW/monitoring-usage)。問卷評分僅會以 OTEL 事件的形式發送至您設定的 collector。在此模式下，不會有任何問卷資料傳送至 Anthropic。適用於已設定 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`、`DISABLE_TELEMETRY` 或 `DO_NOT_TRACK` 的情況，否則不會產生任何效果。`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` 與組織的產品意見回饋政策優先於此變數 |296| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | 設為 `1` 可在傳送至 Anthropic 的非必要流量遭封鎖時，將「How is Claude doing?」工作階段品質調查導向您自己的 [OpenTelemetry collector](/docs/zh-TW/monitoring-usage)。調查評分僅會以 OTEL 事件的形式傳送至您設定的 collector。在此模式下，不會有任何調查資料傳送給 Anthropic。適用於已設定 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`、`DISABLE_TELEMETRY` 或 `DO_NOT_TRACK` 的情況，否則沒有作用。`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` 與組織的產品意見回饋政策優先於此變數 |

295| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 控制工具呼叫輸入是否在 Claude 產生時即從 API 串流傳送。關閉時，大型工具輸入（例如長篇檔案寫入）只會在 Claude 產生完畢後才送達，看起來可能像是停住了。在 Anthropic API 上預設為啟用。在 Amazon Bedrock 與 Google Cloud's Agent Platform 上，會在已部署容器支援的情況下依模型啟用。設為 `0` 可選擇停用。透過 `ANTHROPIC_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_BEDROCK_BASE_URL` 經由代理伺服器路由時，設為 `1` 可強制開啟。在 Microsoft Foundry 與[閘道](/docs/zh-TW/llm-gateway)連線上預設為關閉 |297| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 控制工具呼叫輸入是否在 Claude 產生時即從 API 串流傳送。關閉時，大型工具輸入（例如寫入長檔案）只會在 Claude 產生完畢後才送達，看起來可能像是停滯不動。在 Anthropic API 上預設啟用。在 Amazon Bedrock 與 Google Cloud's Agent Platform 上，會依模型在已部署容器支援時啟用。設為 `0` 可選擇退出。當透過 `ANTHROPIC_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_BEDROCK_BASE_URL` 經由代理伺服器路由時，設為 `1` 可強制啟用。在 Microsoft Foundry 與[閘道](/docs/zh-TW/llm-gateway)連線上預設為關閉 |

296| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 當 `ANTHROPIC_BASE_URL` 指向與 Anthropic 相容的閘道（例如 LiteLLM、Kong 或內部代理伺服器）時，設為 `1` 可從閘道的 `/v1/models` 端點填入 `/model` 選擇器。預設為關閉，因為以共用 API 金鑰為後盾的閘道，否則會向每位使用者顯示該金鑰可存取的所有模型。探索到的模型仍會依工作階段收到的 [`availableModels`](/docs/zh-TW/settings-reference#availablemodels) 允許清單進行篩選；請透過 [MDM 或受管設定檔](/docs/zh-TW/managed-settings#delivery-mechanisms)提供此清單，因為[伺服器管理的傳遞方式不適用於閘道設定](/docs/zh-TW/server-managed-settings#platform-availability) |298| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 當 `ANTHROPIC_BASE_URL` 指向與 Anthropic 相容的閘道（例如 LiteLLM、Kong 或內部代理伺服器）時，設為 `1` 可從閘道的 `/v1/models` 端點填入 `/model` 選擇器。預設為關閉，因為以共用 API 金鑰支援的閘道否則會向每位使用者顯示該金鑰可存取的所有模型。探索到的模型仍會依工作階段收到的 [`availableModels`](/docs/zh-TW/settings-reference#availablemodels) 允許清單篩選；請透過 [MDM 或受管設定檔](/docs/zh-TW/managed-settings#delivery-mechanisms)傳遞該清單，因為[伺服器受管傳遞在閘道設定中無法使用](/docs/zh-TW/server-managed-settings#platform-availability) |

298| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 設為 `false` 可關閉提示詞建議，也就是出現在提示詞輸入區中的灰色預測文字。優先於 [`promptSuggestionEnabled`](/docs/zh-TW/settings-reference#promptsuggestionenabled) 設定，也就是 `/config` 中 **Prompt suggestions** 切換開關所寫入的設定。Claude Code 也會[在您的帳戶接近或達到用量上限時暫停建議](/docs/zh-TW/interactive-mode#when-claude-code-skips-suggestions)。設為 `true` 可讓建議持續開啟，直到您達到上限為止。需要 Claude Code v2.1.238 或更新版本。請參閱[提示詞建議](/docs/zh-TW/interactive-mode#prompt-suggestions) |300| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 設為 `false` 可關閉提示詞建議，即出現在提示詞輸入框中的灰色預測文字。優先於 [`promptSuggestionEnabled`](/docs/zh-TW/settings-reference#promptsuggestionenabled) 設定，也就是 `/config` 中 **Prompt suggestions** 切換開關所寫入的設定。當您的帳戶接近或已達用量上限時，Claude Code 也會[暫停建議](/docs/zh-TW/interactive-mode#when-claude-code-skips-suggestions)。設為 `true` 可讓建議持續開啟，直到您達到上限為止。需要 Claude Code v2.1.238 或更新版本。請參閱[提示詞建議](/docs/zh-TW/interactive-mode#prompt-suggestions) |

299| `CLAUDE_CODE_ENABLE_TASKS` | 選擇 Claude Code 在[具備任務追蹤工具的工作階段](/docs/zh-TW/tools-reference#task-tool-availability)中提供哪些任務追蹤工具。根據預設，Claude Code 提供 Task 工具 `TaskCreate`、`TaskUpdate`、`TaskGet` 與 `TaskList`。設為 `0` 可改為使用舊版的 `TodoWrite` 工具。請參閱[任務清單](/docs/zh-TW/interactive-mode#task-list) |301| `CLAUDE_CODE_ENABLE_TASKS` | 選擇 Claude Code 在[具備任務追蹤工具的工作階段](/docs/zh-TW/tools-reference#task-tool-availability)中提供哪些任務追蹤工具。預設情況下，Claude Code 提供 Task 工具 `TaskCreate`、`TaskUpdate`、`TaskGet` 與 `TaskList`。設為 `0` 則改為使用舊版的 `TodoWrite` 工具。請參閱[任務清單](/docs/zh-TW/interactive-mode#task-list) |

300| `CLAUDE_CODE_ENABLE_TELEMETRY` | 設為 `1` 可啟用 OpenTelemetry 的指標與日誌資料收集。必須在設定 OTel 匯出器之前設定。請在您的 shell、使用者設定或受管設定中設定。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略。請參閱[監控](/docs/zh-TW/monitoring-usage) |302| `CLAUDE_CODE_ENABLE_TELEMETRY` | 設為 `1` 可啟用 OpenTelemetry 資料收集，用於指標與日誌。必須先設定此變數，才能設定 OTel exporter。請在您的 shell、使用者設定或受管設定中設定。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略。請參閱[監控](/docs/zh-TW/monitoring-usage) |

301| `CLAUDE_CODE_ENABLE_TODO_TOOLS` | 設為 `1` 可在每個模型上取得任務追蹤工具。若未設定，Claude Code 預設只會在 [Task 工具可用性](/docs/zh-TW/tools-reference#task-tool-availability)所列的模型上提供這些工具。`CLAUDE_CODE_ENABLE_TASKS` 仍會決定使用 Task 工具或 `TodoWrite`。需要 Claude Code v2.1.233 或更新版本 |303| `CLAUDE_CODE_ENABLE_TODO_TOOLS` | 設為 `1` 可在每個模型上取得任務追蹤工具。若未設定，Claude Code 預設只在 [Task 工具可用性](/docs/zh-TW/tools-reference#task-tool-availability)下列出的模型上提供這些工具。`CLAUDE_CODE_ENABLE_TASKS` 仍會選擇 Task 工具或 `TodoWrite`。需要 Claude Code v2.1.233 或更新版本 |

304| `CLAUDE_CODE_EXTRA_BODY` | 要合併至每個 API 請求主體頂層的 JSON 物件。適用於傳遞 Claude Code 未直接公開的供應商專屬參數。在您的 shell 中 export 的值，也會套用至您以 `claude agents` 或 `--bg` 派送的[背景工作階段](/docs/zh-TW/agent-view)。在 v2.1.206 之前，背景工作階段會忽略從 shell export 的值，而使用背景監督程序所繼承的副本 |306| `CLAUDE_CODE_EXTRA_BODY` | 要合併至每個 API 請求本文最上層的 JSON 物件。適用於傳遞 Claude Code 未直接公開的供應商特定參數。在您的 shell 中匯出的值，也會套用至您以 `claude agents` 或 `--bg` 派送的[背景工作階段](/docs/zh-TW/agent-view)。在 v2.1.206 之前，背景工作階段會忽略 shell 匯出的值，而使用背景監督程序所繼承的副本 |

306| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | 設為 `1` 可強制保存逐字稿、提示詞歷史記錄及 `claude agents` 註冊，即使此 `claude` 是從另一個 Claude Code 工作階段內啟動的也一樣。當繼承的 `CLAUDE_CODE_CHILD_SESSION` 值（例如來自 `screen` 工作階段，或最初由 Claude Code 的 Bash 工具啟動的背景啟動器）導致真正的頂層工作階段被誤判為巢狀工作階段時使用。自 v2.1.178 起，Claude Code 會自動偵測 tmux 的情況並忽略繼承的標記，因此 tmux 不再需要此變數。在 v2.1.169 及更早版本中也會採用；在 v2.1.170 與 v2.1.171 中則沒有效果，因為這兩個版本移除了它所覆寫的巢狀工作階段偵測 |308| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | 設為 `1` 可強制保存逐字稿、提示詞歷史記錄，以及 `claude agents` 註冊，即使此 `claude` 是從另一個 Claude Code 工作階段內啟動的也一樣。當繼承而來的 `CLAUDE_CODE_CHILD_SESSION` 值（例如來自 `screen` 工作階段，或最初由 Claude Code 的 Bash 工具啟動的背景啟動器）導致真正的頂層工作階段被誤判為巢狀時使用。自 v2.1.178 起，Claude Code 會自動偵測 tmux 的情況並忽略繼承的標記，因此 tmux 不再需要此變數。在 v2.1.169 及更早版本中也會採用；在 v2.1.170 與 v2.1.171 中沒有作用，因為這兩個版本已移除它所覆寫的巢狀工作階段偵測 |

307| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | 設為 `1` 可在您的終端機支援但未被自動偵測到時（例如透過 SSH 連線但未轉送 `TERM_PROGRAM`），強制以刪除線呈現 Claude 回應中的 `~~text~~`。若未設定，未被偵測到的終端機會顯示字面上的 `~~` 標記，而不是將文字呈現為刪除線。需要 Claude Code v2.1.186 或更新版本 |309| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | 當您的終端機支援刪除線但未被自動偵測到時（例如透過 SSH 連線且未轉送 `TERM_PROGRAM`），設為 `1` 可強制將 Claude 回應中的 `~~text~~` 呈現為刪除線。若未設定，未被偵測到的終端機會顯示字面的 `~~` 標記，而不會將文字呈現為刪除線。需要 Claude Code v2.1.186 或更新版本 |

308| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 設為 `1` 可在您的終端機支援但未被自動偵測到時，強制啟用 DEC private mode 2026 [同步輸出](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)。適用於實作了 BSU/ESU 但不回應能力探測的模擬器，例如 Emacs `eat`。在 tmux 下沒有效果。與切換至[全螢幕呈現](/docs/zh-TW/fullscreen)的 `CLAUDE_CODE_NO_FLICKER` 不同，此變數不會變更呈現器 |310| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 當您的終端機支援 DEC private mode 2026 [同步輸出](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)但未被自動偵測到時，設為 `1` 可強制啟用。適用於實作 BSU/ESU 但不回應功能探測的模擬器，例如 Emacs `eat`。在 tmux 下沒有作用。與會切換至[全螢幕呈現](/docs/zh-TW/fullscreen)的 `CLAUDE_CODE_NO_FLICKER` 不同，此變數不會變更呈現器 |

309| `CLAUDE_CODE_FORK_SUBAGENT` | 控制[分支模式](/docs/zh-TW/sub-agents#turn-fork-mode-on-or-off)，此模式讓 Claude 能自行產生[分支 subagent](/docs/zh-TW/sub-agents#fork-the-current-conversation)，且僅在互動式工作階段中預設開啟。設為 `1` 可在 `claude -p` 與 Agent SDK 中也開啟，或設為 `0` 在所有類型的工作階段中關閉。無論分支模式是否開啟，您都可以執行 `/subtask`。互動式的預設行為需要 Claude Code v2.1.232 或更新版本；在較早版本中，請將此變數設為 `1` 以開啟分支模式 |311| `CLAUDE_CODE_FORK_SUBAGENT` | 控制[分叉模式](/docs/zh-TW/sub-agents#turn-fork-mode-on-or-off)，此模式可讓 Claude 自行產生[分叉 subagent](/docs/zh-TW/sub-agents#fork-the-current-conversation)，且預設僅在互動式工作階段中開啟。設為 `1` 可在 `claude -p` 與 Agent SDK 中也開啟，設為 `0` 則在所有類型的工作階段中關閉。無論分叉模式是否開啟，您都可以執行 `/subtask`。互動式預設需要 Claude Code v2.1.232 或更新版本；在較早版本中，請將此變數設為 `1` 以開啟分叉模式 |

310| `CLAUDE_CODE_FORWARD_SUBAGENT_TEXT` | 設為 `1` 可在 `claude -p --output-format stream-json` 輸出中發出 [subagent](/docs/zh-TW/sub-agents) 的文字與思考區塊，行為與 [`--forward-subagent-text`](/docs/zh-TW/cli-reference#cli-flags) 旗標相同。當執行框架呼叫 `claude` 且無法自行傳遞旗標時，請使用此變數。旗標在非互動模式搭配 stream-json 輸出以外的情況下會以錯誤結束，而此變數在那些情況下會被忽略，因此在整個程序範圍設定時，巢狀呼叫仍能正常運作。需要 Claude Code v2.1.211 或更新版本 |312| `CLAUDE_CODE_FORWARD_SUBAGENT_TEXT` | 設為 `1` 可在 `claude -p --output-format stream-json` 輸出中傳出 [subagent](/docs/zh-TW/sub-agents) 的文字與思考區塊，行為與 [`--forward-subagent-text`](/docs/zh-TW/cli-reference#cli-flags) 旗標相同。當測試框架呼叫 `claude` 且無法自行傳遞旗標時，請使用此變數。此旗標在非互動模式搭配 stream-json 輸出以外的情況下會以錯誤結束，而此變數在這些情況下會被忽略，因此在整個程序範圍設定時，巢狀呼叫仍可正常運作。需要 Claude Code v2.1.211 或更新版本 |

311| `CLAUDE_CODE_GATEWAY_HINT_HEADERS` | 設為 `1` 可在自訂代理伺服器或第三方供應商（例如 Amazon Bedrock 或 Claude Platform on AWS）上傳送[閘道提示標頭](/docs/zh-TW/llm-gateway-protocol#gateway-hint-headers)，例如 `x-claude-code-request-class` 與 `x-claude-code-compaction`。設為 `0` 可在所有連線上停止傳送這些標頭，包括直接連線至 Anthropic API 的情況，Claude Code 在該情況下預設會傳送它們。需要 Claude Code v2.1.273 或更新版本 |313| `CLAUDE_CODE_GATEWAY_HINT_HEADERS` | 設為 `1` 可在自訂代理伺服器或第三方供應商（例如 Amazon Bedrock 或 Claude Platform on AWS）上傳送[閘道提示標頭](/docs/zh-TW/llm-gateway-protocol#gateway-hint-headers)，例如 `x-claude-code-request-class` 與 `x-claude-code-compaction`。設為 `0` 可在所有連線上停止傳送這些標頭，包括直接連線至 Anthropic API 的情況，Claude Code 在該情況下預設會傳送。需要 Claude Code v2.1.273 或更新版本 |

312| `CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS` | 由 `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` 開啟之[閘道模型探索](/docs/zh-TW/llm-gateway-protocol#model-discovery)請求的逾時時間（毫秒）（預設：`3000`）。當您的閘道在啟動時需要超過三秒才能回應 `/v1/models` 時，請調高此值。僅接受純數字；`0`、負值與其他寫法會保留預設值。需要 Claude Code v2.1.269 或更新版本 |314| `CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS` | 由 `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` 開啟的[閘道模型探索](/docs/zh-TW/llm-gateway-protocol#model-discovery)請求的逾時（毫秒）（預設：`3000`）。當您的閘道在啟動時需要超過三秒才能回應 `/v1/models` 時，請調高此值。只接受純數字；`0`、負值及其他寫法會保留預設值。需要 Claude Code v2.1.269 或更新版本 |

313| `CLAUDE_CODE_GIT_BASH_PATH` | 僅限 Windows：Git Bash 可執行檔（`bash.exe`）的路徑。當 Git Bash 已安裝但不在您的 PATH 中時使用。若路徑不存在，或檔案名稱不是 `bash.exe`、`sh.exe`、`bash` 或 `sh`，Claude Code 會忽略此變數，並如同未設定般自動偵測 Git Bash，同時記錄一則可透過 `--debug` 查看的警告。在 v2.1.219 之前，當路徑不存在時 Claude Code 會在啟動時結束，且會將任何現有檔案當作 shell 使用，而不檢查它是否為 bash 或 sh。請參閱 [Windows 設定](/docs/zh-TW/setup#set-up-on-windows) |315| `CLAUDE_CODE_GIT_BASH_PATH` | 僅限 Windows：Git Bash 執行檔（`bash.exe`）的路徑。當 Git Bash 已安裝但不在您的 PATH 中時使用。若路徑不存在，或檔案名稱不是 `bash.exe`、`sh.exe`、`bash` 或 `sh`，Claude Code 會忽略此變數並如同未設定一般自動偵測 Git Bash，同時記錄一則可透過 `--debug` 檢視的警告。在 v2.1.219 之前，當路徑不存在時 Claude Code 會在啟動時結束，且會將任何既有檔案當作 shell 使用，而不檢查其是否為 bash 或 sh。請參閱 [Windows 設定](/docs/zh-TW/setup#set-up-on-windows) |

314| `CLAUDE_CODE_GLOB_HIDDEN` | 設為 `false` 可在 Claude 呼叫 [Glob 工具](/docs/zh-TW/tools-reference#glob-tool-behavior)時從結果中排除 dotfile。預設會包含。不影響 `@` 檔案自動完成、`ls`、Grep 或 Read |316| `CLAUDE_CODE_GLOB_HIDDEN` | 設為 `false` 可在 Claude 呼叫 [Glob 工具](/docs/zh-TW/tools-reference#glob-tool-behavior)時，從結果中排除點檔案。預設會包含。不影響 `@` 檔案自動完成、`ls`、Grep 或 Read |

315| `CLAUDE_CODE_GLOB_NO_IGNORE` | 設為 `false` 可讓 [Glob 工具](/docs/zh-TW/tools-reference#glob-tool-behavior)遵守 `.gitignore` 模式。根據預設，Glob 會傳回所有符合的檔案，包括被 gitignore 的檔案。不影響 `@` 檔案自動完成，後者有自己的 [`respectGitignore` 設定](/docs/zh-TW/settings-reference#respectgitignore) |317| `CLAUDE_CODE_GLOB_NO_IGNORE` | 設為 `false` 可讓 [Glob 工具](/docs/zh-TW/tools-reference#glob-tool-behavior)遵循 `.gitignore` 模式。預設情況下，Glob 會傳回所有符合的檔案，包括被 gitignore 的檔案。不影響 `@` 檔案自動完成，其有自己的 [`respectGitignore` 設定](/docs/zh-TW/settings-reference#respectgitignore) |

317| `CLAUDE_CODE_GOAL_CHECKIN_MINUTES` | 背景工作可讓進行中的目標等待多少分鐘，之後 Claude Code 會[請 Claude 檢查它](/docs/zh-TW/goal#background-work-defers-evaluation)。預設為 `30`。設為 `0` 可關閉檢查。請以純數字提供整數分鐘數，最多 `10080`，即一週。Claude Code 會將其他任何值視為未設定並使用預設值。需要 Claude Code v2.1.234 或更新版本 |319| `CLAUDE_CODE_GOAL_CHECKIN_MINUTES` | 背景工作可讓進行中的目標等待多少分鐘，之後 Claude Code 會[請 Claude 檢查該目標](/docs/zh-TW/goal#background-work-defers-evaluation)。預設為 `30`。設為 `0` 可關閉檢查。請以純數字提供整數分鐘，最多 `10080`，即一週。Claude Code 會將任何其他值視為未設定並使用預設值。需要 Claude Code v2.1.234 或更新版本 |

318| `CLAUDE_CODE_GZIP_REQUEST_BODIES` | 設為 `0` 可關閉傳送至 `api.anthropic.com` 的 Claude API、遙測與 [artifact](/docs/zh-TW/artifacts) 發布請求本文的 gzip 壓縮。預設情況下，Claude Code 會在直接連線時壓縮大型請求本文，而在您透過代理伺服器傳送請求、設定用戶端憑證或設定 `NODE_EXTRA_CA_CERTS` 時略過壓縮。如果 Claude Code 無法偵測到的 [TLS 檢查代理伺服器](/docs/zh-TW/network-config#ca-certificate-store)錯誤處理壓縮的請求，請使用 `0` |320| `CLAUDE_CODE_GZIP_REQUEST_BODIES` | 設為 `0` 可關閉傳送至 `api.anthropic.com` 的 Claude API、遙測與 [artifact](/docs/zh-TW/artifacts) 發布請求本文的 gzip 壓縮。預設情況下，Claude Code 會在直接連線上壓縮大型請求本文，並在您透過代理伺服器傳送請求、設定用戶端憑證或設定 `NODE_EXTRA_CA_CERTS` 時略過壓縮。若 Claude Code 無法偵測的 [TLS 檢查代理伺服器](/docs/zh-TW/network-config#ca-certificate-store)錯誤處理壓縮的請求，請使用 `0` |

321| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | 設為 `1` 可略過 IDE 擴充功能的自動安裝。等同於將 [`autoInstallIdeExtension`](/docs/zh-TW/settings-reference#autoinstallideextension) 設為 `false` |323| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | 設為 `1` 可略過 IDE 擴充功能的自動安裝。等同於將 [`autoInstallIdeExtension`](/docs/zh-TW/settings-reference#autoinstallideextension) 設為 `false` |

323| `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` | 一個工作階段中可同時執行多少個 [subagent](/docs/zh-TW/sub-agents#concurrent-subagent-limit)，超過後 Agent 工具會拒絕再產生新的 subagent（預設：20）。接受以純數字表示的正整數；其他值都會被忽略，因此此變數可調整上限，但無法停用上限。需要 Claude Code v2.1.217 或更新版本 |325| `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` | 一個工作階段中可同時執行多少個 [subagent](/docs/zh-TW/sub-agents#concurrent-subagent-limit)，超過後 Agent 工具將拒絕再產生新的 subagent（預設：20）。接受以純數字表示的正整數；其他任何值都會被忽略，因此此變數可以調整上限，但無法停用上限。需要 Claude Code v2.1.217 或更新版本 |

324| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | 覆寫 Claude Code 為目前模型假設的上下文視窗大小。自 v2.1.193 起，其套用方式取決於 Claude Code 如何解析模型 ID；請參閱[修正閘道或自訂模型 ID 的視窗](/docs/zh-TW/model-config#correct-the-window-for-a-gateway-or-custom-model-id)。當透過 `ANTHROPIC_BASE_URL` 路由至某個模型，而其上下文視窗與該名稱的內建大小不符時使用 |326| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | 覆寫 Claude Code 為目前使用中的模型所假設的上下文視窗大小。自 v2.1.193 起，其套用方式取決於 Claude Code 如何解析模型 ID；請參閱[修正閘道或自訂模型 ID 的視窗](/docs/zh-TW/model-config#correct-the-window-for-a-gateway-or-custom-model-id)。當透過 `ANTHROPIC_BASE_URL` 路由至某個模型，而其上下文視窗與該名稱的內建大小不符時，請使用此變數 |

325| `CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH` | Claude Code 傳送給模型的每個 MCP 工具描述與每個 MCP 伺服器指令的最大長度（字元）（預設：2048）。Claude Code 會[截斷較長的文字](/docs/zh-TW/mcp#for-mcp-server-authors)。接受以純數字表示的正整數。其他值都會被忽略並套用預設值。需要 Claude Code v2.1.280 或更新版本 |327| `CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH` | Claude Code 傳送給模型的每個 MCP 工具描述與每個 MCP 伺服器指令的最大長度（字元數）（預設：2048）。Claude Code 會[截斷較長的文字](/docs/zh-TW/mcp#for-mcp-server-authors)。接受以純數字表示的正整數。其他任何值都會被忽略並套用預設值。需要 Claude Code v2.1.280 或更新版本 |

326| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 設定大多數請求的最大輸出 token 數。預設值與上限因模型而異；請參閱[最大輸出 token](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)。Claude Code 會將超過模型上限的值降至上限。對於 Claude Code 無法解析為已知模型的模型 ID，預設值為 32000，上限為 128000。提高此值會減少觸發[自動壓縮](/docs/zh-TW/costs#reduce-token-usage)前可用的有效上下文視窗 |328| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 設定大多數請求的最大輸出 token 數。預設值與上限因模型而異；請參閱[最大輸出 token](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)。Claude Code 會將超過模型上限的值降至上限。對於 Claude Code 無法解析為已知模型的模型 ID，預設值為 32000，上限為 128000。提高此值會減少觸發[自動壓縮](/docs/zh-TW/costs#reduce-token-usage)前可用的有效上下文視窗 |

327| `CLAUDE_CODE_MAX_RETRIES` | 覆寫失敗 API 請求的重試次數（預設：10）。自 v2.1.186 起上限為 15；自 v2.1.199 起，`CLAUDE_CODE_RETRY_WATCHDOG` 會提高預設值並移除上限。對於需要撐過較長服務中斷的無人看管工作階段，請改為設定 `CLAUDE_CODE_RETRY_WATCHDOG` |329| `CLAUDE_CODE_MAX_RETRIES` | 覆寫失敗 API 請求的重試次數（預設：10）。自 v2.1.186 起上限為 15；自 v2.1.199 起，`CLAUDE_CODE_RETRY_WATCHDOG` 會提高預設值並移除上限。對於需要撐過較長中斷時間的無人值守工作階段，請改為設定 `CLAUDE_CODE_RETRY_WATCHDOG` |

328| `CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION` | 已於 v2.1.224 移除，現在不會產生任何作用。先前會限制 Claude 在一個工作階段中可使用 Agent 工具產生的 [subagent](/docs/zh-TW/sub-agents) 總數（預設：200）；超過上限時，產生 subagent 會以 `Subagent spawn limit reached` 失敗。[同時執行的 subagent 上限](/docs/zh-TW/sub-agents#concurrent-subagent-limit)與[深度上限](/docs/zh-TW/sub-agents#let-subagents-spawn-their-own-subagents)仍然適用 |330| `CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION` | 已於 v2.1.224 移除，現在不具作用。先前用於限制 Claude 在一個工作階段中可透過 Agent 工具產生的 [subagent](/docs/zh-TW/sub-agents) 總數（預設：200）；超過上限時產生會以 `Subagent spawn limit reached` 失敗。[同時 subagent 上限](/docs/zh-TW/sub-agents#concurrent-subagent-limit)與[深度上限](/docs/zh-TW/sub-agents#let-subagents-spawn-their-own-subagents)仍然適用 |

329| `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` | 主要對話之下允許的 [subagent 層數](/docs/zh-TW/sub-agents#let-subagents-spawn-their-own-subagents) （預設：3）。在預設值下，subagent 可以產生自己的 subagent，而位於第三層的 subagent 無法再進一步產生；設為 `1` 可關閉巢狀。在 v2.1.217 至 v2.1.218 中，預設值為 1，因此除非您提高上限，否則 subagent 無法產生自己的 subagent；v2.1.219 將預設值提高為 3。接受以純數字表示的正整數；其他值都會被忽略，因此上限可以調整但無法移除。需要 Claude Code v2.1.217 或更新版本 |331| `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` | 主對話之下允許的 [subagent 層數](/docs/zh-TW/sub-agents#let-subagents-spawn-their-own-subagents)（預設：3）。在預設值下，subagent 可以產生自己的 subagent，而第三層的 subagent 無法再往下產生；設為 `1` 可關閉巢狀。在 v2.1.217 至 v2.1.218 中，預設值為 1，因此除非您提高上限，否則 subagent 無法產生自己的 subagent；v2.1.219 將預設值提高為 3。接受以純數字表示的正整數；其他任何值都會被忽略，因此上限可以調整但無法移除。需要 Claude Code v2.1.217 或更新版本 |

331| `CLAUDE_CODE_MAX_TURNS` | 在未傳遞明確上限時，限制 agentic 回合數。等同於傳遞 [`--max-turns`](/docs/zh-TW/cli-reference#cli-flags)，兩者都設定時以後者為優先。非正整數的值會在啟動時以錯誤拒絕，而不會被視為無上限 |333| `CLAUDE_CODE_MAX_TURNS` | 在未傳遞明確上限時，限制 agentic 回合的數量。等同於傳遞 [`--max-turns`](/docs/zh-TW/cli-reference#cli-flags)，兩者皆設定時以旗標為優先。非正整數的值會在啟動時以錯誤拒絕，而不會被視為無上限 |

332| `CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION` | 一個工作階段可進行的 [WebSearch](/docs/zh-TW/tools-reference#websearch-tool-behavior) 呼叫總數上限（預設：200）。當 Claude 達到上限時，後續的 WebSearch 呼叫會傳回一則通知，告訴它以已收集到的資訊繼續。接受沒有上界的正整數。其他值都會被忽略並套用預設值，因此上限可以提高但無法關閉。需要 Claude Code v2.1.212 或更新版本 |334| `CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION` | 一個工作階段可進行的 [WebSearch](/docs/zh-TW/tools-reference#websearch-tool-behavior) 呼叫總數上限（預設：200）。當 Claude 達到上限時，後續的 WebSearch 呼叫會傳回通知，告知它以已收集到的資訊繼續進行。接受沒有上限的正整數。其他任何值都會被忽略並套用預設值，因此上限可以提高但無法關閉。需要 Claude Code v2.1.212 或更新版本 |

334| `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` | 仍在執行的 MCP 工具呼叫在[移至背景任務](/docs/zh-TW/mcp#automatic-backgrounding-of-long-tool-calls)之前經過的時間（毫秒）（預設：120000，即 2 分鐘）。設為 `0` 可關閉自動移至背景。需要 Claude Code v2.1.212 或更新版本 |336| `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` | 仍在執行中的 MCP 工具呼叫[移至背景任務](/docs/zh-TW/mcp#automatic-backgrounding-of-long-tool-calls)前經過的時間（毫秒）（預設：120000，即 2 分鐘）。設為 `0` 可關閉自動背景化。需要 Claude Code v2.1.212 或更新版本 |

335| `CLAUDE_CODE_MCP_STARTUP_WAIT_MS` | [非互動](/docs/zh-TW/headless)工作階段的第一個回合等待仍在連線中之 MCP 伺服器的時間（毫秒），用以取代預設的[第一回合等待](/docs/zh-TW/agent-sdk/mcp#connection-timing)。設定後，等待會涵蓋所有擱置中的伺服器。設為 `0` 可略過等待。無論此值為何，[`--permission-prompt-tool`](/docs/zh-TW/cli-reference#cli-flags) 伺服器都會保留自己的 `MCP_TIMEOUT` 等待。需要 Claude Code v2.1.274 或更新版本 |337| `CLAUDE_CODE_MCP_STARTUP_WAIT_MS` | [非互動](/docs/zh-TW/headless)工作階段的第一個回合等待仍在連線中的 MCP 伺服器的時間（毫秒），取代預設的[第一回合等待](/docs/zh-TW/agent-sdk/mcp#connection-timing)。設定後，等待會涵蓋所有待處理的伺服器。設為 `0` 可略過等待。[`--permission-prompt-tool`](/docs/zh-TW/cli-reference#cli-flags) 伺服器無論此值為何，都會保留自己的 `MCP_TIMEOUT` 等待。需要 Claude Code v2.1.274 或更新版本 |

336| `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` | MCP 工具呼叫的閒置逾時時間（毫秒）。當 stdio、HTTP、SSE、WebSocket 或 [claude.ai 連接器](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai) MCP 伺服器在這段時間內未傳送任何回應或進度通知時，工具呼叫會以錯誤中止，而不是等待整體的 `MCP_TOOL_TIMEOUT`。覆寫各傳輸方式的預設值：網路伺服器為 300000（5 分鐘），stdio 伺服器為 1800000（30 分鐘）。設為 `0` 可停用閒置檢查。低於 1000 的值會被提高為一秒，且此值的上限為實際生效的 `MCP_TOOL_TIMEOUT`。`.mcp.json` 中至少為 1000 的個別伺服器 `timeout`，會將該伺服器的閒置時間窗提高到至少為該 `timeout` 值。不適用於 IDE 伺服器或 SDK 程序內伺服器。需要 Claude Code v2.1.187 或更新版本。在 v2.1.203 之前，stdio 伺服器不受閒置逾時限制 |338| `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` | MCP 工具呼叫的閒置逾時（毫秒）。當 stdio、HTTP、SSE、WebSocket 或 [claude.ai 連接器](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai) MCP 伺服器在這段時間內未傳送任何回應或進度通知時，工具呼叫會以錯誤中止，而不會等待整體的 `MCP_TOOL_TIMEOUT`。覆寫各傳輸方式的預設值：網路伺服器為 300000（5 分鐘），stdio 伺服器為 1800000（30 分鐘）。設為 `0` 可停用閒置檢查。低於 1000 的值會提高為一秒，且此值的上限為實際生效的 `MCP_TOOL_TIMEOUT`。`.mcp.json` 中至少為 1000 的個別伺服器 `timeout`，會將該伺服器的閒置時間窗提高至至少為 `timeout` 值。不適用於 IDE 伺服器或 SDK 程序內伺服器。需要 Claude Code v2.1.187 或更新版本。在 v2.1.203 之前，stdio 伺服器不受閒置逾時限制 |

337| `CLAUDE_CODE_MESSAGING_SOCKET` | 由 Claude Code 設定，而非由您設定：在繫結[收件匣 socket](/docs/zh-TW/cross-session-messaging#the-sessions-inbox-socket) 的工作階段中，Claude Code 會在繫結 socket 時，將該 socket 的路徑匯出給 hook 與 Bash 命令。在啟動時即開啟訊息功能的工作階段中，Claude Code 會在任何 hook 執行之前繫結 socket。機器上的其他工作階段會將訊息傳遞至此路徑。每個工作階段都會匯出自己的 socket，而非繼承自父工作階段的 socket，且抵達該 socket 的訊息會經過該工作階段的[傳入控制](/docs/zh-TW/cross-session-messaging#control-inbound-messages)。設定中的 `env` 區塊無法設定此變數。需要 Claude Code v2.1.224 或更新版本 |339| `CLAUDE_CODE_MESSAGING_SOCKET` | 由 Claude Code 設定，而非由您設定：在繫結[收件匣 socket](/docs/zh-TW/cross-session-messaging#the-sessions-inbox-socket) 的工作階段中，Claude Code 會在繫結 socket 時將該 socket 的路徑匯出給 hook 與 Bash 命令。在啟動時即開啟訊息功能的工作階段中，Claude Code 會在任何 hook 執行前繫結 socket。機器上的其他工作階段會將訊息傳遞至此路徑。每個工作階段都會匯出自己的 socket，而非從父工作階段繼承，且抵達該 socket 的訊息會經過該工作階段的[傳入控制](/docs/zh-TW/cross-session-messaging#control-inbound-messages)。設定的 `env` 區塊無法設定此變數。需要 Claude Code v2.1.224 或更新版本 |

338| `CLAUDE_CODE_MESSAGING_TOKEN` | 由 Claude Code 設定，而非由您設定：在繫結[收件匣 socket](/docs/zh-TW/cross-session-messaging#the-sessions-inbox-socket) 的工作階段中，Claude Code 會將此個別工作階段的 token 與 `CLAUDE_CODE_MESSAGING_SOCKET` 一併匯出給 hook 與 Bash 命令。向該 socket 傳送資料的指令碼可以將 `{"type":"auth","token":"<token>"}` 作為第一行傳送，以證明它屬於該工作階段。在原生 Windows 上，Claude Code 要求此行，並會關閉任何未以有效的此行開頭的連線。[own-child 規則](/docs/zh-TW/cross-session-messaging#the-sessions-inbox-socket)說明了 Claude Code 何時會檢查此 token。每個工作階段都會匯出自己的 token，絕不會使用繼承自父工作階段的 token。設定中的 `env` 區塊無法設定此變數。需要 Claude Code v2.1.228 或更新版本 |340| `CLAUDE_CODE_MESSAGING_TOKEN` | 由 Claude Code 設定，而非由您設定：在繫結[收件匣 socket](/docs/zh-TW/cross-session-messaging#the-sessions-inbox-socket) 的工作階段中，Claude Code 會將此每個工作階段專屬的 token 連同 `CLAUDE_CODE_MESSAGING_SOCKET` 一起匯出給 hook 與 Bash 命令。向 socket 發送訊息的指令碼可以將 `{"type":"auth","token":"<token>"}` 作為第一行傳送，以證明其屬於該工作階段。在原生 Windows 上，Claude Code 要求這一行，並會關閉任何未以有效的這一行開頭的連線。[自身子程序規則](/docs/zh-TW/cross-session-messaging#the-sessions-inbox-socket)說明 Claude Code 何時會查驗此 token。每個工作階段都會匯出自己的 token，絕不會使用從父工作階段繼承的 token。設定的 `env` 區塊無法設定此變數。需要 Claude Code v2.1.228 或更新版本 |

340| `CLAUDE_CODE_NEW_INIT` | 設為 `1` 可讓 `/init` 執行互動式設定流程。此流程會在探索程式碼庫並寫入檔案之前，詢問要產生哪些檔案，包括 CLAUDE.md、skill 與 hook。若未設定此變數，`/init` 會自動產生 CLAUDE.md 而不提示 |342| `CLAUDE_CODE_NEW_INIT` | 設為 `1` 可讓 `/init` 執行互動式設定流程。此流程會在探索程式碼庫並寫入檔案之前，詢問要產生哪些檔案，包括 CLAUDE.md、skill 與 hook。若未設定此變數，`/init` 會自動產生 CLAUDE.md 而不提示 |

341| `CLAUDE_CODE_NONBLOCKING_STDOUT` | 設為 `1` 可透過第二個非阻塞檔案描述元寫入終端機輸出，讓停止讀取的終端機（例如已暫停的 tmux control-mode 窗格或停滯的 SSH 連線）無法在工作階段中途凍結 Claude Code。當 stdout 為終端機時，適用於 macOS、Linux 與 WSL。需要 Claude Code v2.1.261 或更新版本 |343| `CLAUDE_CODE_NONBLOCKING_STDOUT` | 設為 `1` 可透過第二個非阻塞檔案描述元寫入終端機輸出，讓停止讀取的終端機（例如暫停的 tmux control-mode 窗格或停滯的 SSH 連線）無法在工作階段中途凍結 Claude Code。在 stdout 為終端機時，適用於 macOS、Linux 與 WSL。需要 Claude Code v2.1.261 或更新版本 |

342| `CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES` | 限制 Claude Code 重新傳送逾時之[非串流請求](/docs/zh-TW/errors#streaming-response-ended-before-any-complete-data-was-received)的次數。設為 `0` 時，請求會在第一次逾時時失敗。預設未設定，因此由 `CLAUDE_CODE_MAX_RETRIES` 限制這些重新傳送。關於逾時時間，請參閱[調整重試行為](/docs/zh-TW/errors#tune-retry-behavior)。需要 Claude Code v2.1.285 或更新版本 |344| `CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES` | 限制 Claude Code 重新傳送逾時的[非串流請求](/docs/zh-TW/errors#streaming-response-ended-before-any-complete-data-was-received)的次數。設為 `0` 時，請求會在第一次逾時即失敗。預設為未設定，因此由 `CLAUDE_CODE_MAX_RETRIES` 限制這些重新傳送。關於逾時，請參閱[調整重試行為](/docs/zh-TW/errors#tune-retry-behavior)。需要 Claude Code v2.1.285 或更新版本 |

343| `CLAUDE_CODE_NO_FLICKER` | 設為 `1` 可啟用[全螢幕呈現](/docs/zh-TW/fullscreen)，這是一項研究預覽功能，可減少閃爍並在長對話中維持記憶體用量平穩。覆寫 [`tui`](/docs/zh-TW/settings-reference#tui) 設定；您也可以使用 `/tui fullscreen` 切換 |345| `CLAUDE_CODE_NO_FLICKER` | 設為 `1` 可啟用[全螢幕呈現](/docs/zh-TW/fullscreen)，這是一項研究預覽功能，可減少閃爍並在長對話中維持記憶體用量平穩。覆寫 [`tui`](/docs/zh-TW/settings-reference#tui) 設定；您也可以使用 `/tui fullscreen` 切換 |

344| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | 用於 Claude.ai 身分驗證的 OAuth refresh token。設定後，`claude auth login` 會直接交換此 token，而不開啟瀏覽器。需要 `CLAUDE_CODE_OAUTH_SCOPES`。適用於在自動化環境中佈建身分驗證 |346| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | 用於 Claude.ai 身分驗證的 OAuth refresh token。設定後，`claude auth login` 會直接交換此 token，而不會開啟瀏覽器。需要 `CLAUDE_CODE_OAUTH_SCOPES`。適用於在自動化環境中佈建身分驗證 |

345| `CLAUDE_CODE_OAUTH_SCOPES` | 核發 refresh token 時所使用的 OAuth 範圍，以空格分隔，例如 `"user:profile user:inference user:sessions:claude_code"`。設定 `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` 時為必要 |347| `CLAUDE_CODE_OAUTH_SCOPES` | 簽發 refresh token 時所用的 OAuth 範圍，以空格分隔，例如 `"user:profile user:inference user:sessions:claude_code"`。設定 `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` 時為必要 |

346| `CLAUDE_CODE_OAUTH_TOKEN` | 用於 claude.ai 身分驗證的 OAuth access token。是 SDK 與自動化環境中 `/login` 的替代方案。優先於儲存在 keychain 中的憑證。可使用 [`claude setup-token`](/docs/zh-TW/authentication#generate-a-long-lived-token) 產生。除非您執行 [`/login`](/docs/zh-TW/authentication#authentication-precedence)，否則 Claude Code 在整個工作階段中都會使用您設定的 token。若要更換已過期的 token，請產生新的 token 並重新啟動 |348| `CLAUDE_CODE_OAUTH_TOKEN` | 用於 claude.ai 身分驗證的 OAuth access token。在 SDK 與自動化環境中可取代 `/login`。優先於儲存在鑰匙圈中的憑證。可使用 [`claude setup-token`](/docs/zh-TW/authentication#generate-a-long-lived-token) 產生。除非您執行 [`/login`](/docs/zh-TW/authentication#authentication-precedence)，否則 Claude Code 會在整個工作階段中使用您設定的 token。若要替換已過期的 token，請產生新的 token 並重新啟動 |

347| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | 已於 v2.1.160 移除，現在不會產生任何作用。先前會將[快速模式](/docs/zh-TW/fast-mode)固定為 Claude Opus 4.6，而非目前的預設模型。Opus 4.6 已不再支援快速模式 |349| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | 已於 v2.1.160 移除，現在不具作用。先前用於將[快速模式](/docs/zh-TW/fast-mode)固定為 Claude Opus 4.6，而非目前的預設值。Opus 4.6 已不再支援快速模式 |

348| `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` | 承載內容之 OpenTelemetry 屬性（模型回應、工具內容、系統提示詞、原始 API 主體）的最大長度，包含截斷標記，以 UTF-16 程式碼單元計算（預設：61440，即 60 KB）。僅在您的遙測後端接受大於 64 KB 的屬性值時才提高此值，或降低此值以減少遙測量。需要 Claude Code v2.1.214 或更新版本。請參閱[監控](/docs/zh-TW/monitoring-usage) |350| `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` | 承載內容的 OpenTelemetry 屬性（模型回應、工具內容、系統提示詞、原始 API 本文）的最大長度，包含截斷標記，以 UTF-16 程式碼單位計算（預設：61440，即 60 KB）。僅在您的遙測後端接受大於 64 KB 的屬性值時才調高此值，或調低此值以減少遙測量。需要 Claude Code v2.1.214 或更新版本。請參閱[監控](/docs/zh-TW/monitoring-usage) |

349| `CLAUDE_CODE_OTEL_DIAG_STDERR` | 設為 `1` 可將 OpenTelemetry 匯出器的診斷錯誤寫入 stderr。根據預設，這些錯誤只會在使用 `--debug` 時出現，因此設定錯誤的匯出器（例如 Prometheus 連接埠衝突）否則會在無聲無息中失敗。需要 Claude Code v2.1.179 或更新版本。請參閱[監控](/docs/zh-TW/monitoring-usage) |351| `CLAUDE_CODE_OTEL_DIAG_STDERR` | 設為 `1` 可將 OpenTelemetry exporter 的診斷錯誤寫入 stderr。預設情況下，這些錯誤只會在使用 `--debug` 時出現，因此設定錯誤的 exporter（例如 Prometheus 連接埠衝突）否則會無聲失敗。需要 Claude Code v2.1.179 或更新版本。請參閱[監控](/docs/zh-TW/monitoring-usage) |

351| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 重新整理動態 OpenTelemetry 標頭的間隔（毫秒）（預設：1740000 / 29 分鐘）。請參閱[動態標頭](/docs/zh-TW/monitoring-usage#dynamic-headers) |353| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 重新整理動態 OpenTelemetry 標頭的間隔（毫秒）（預設：1740000 / 29 分鐘）。請參閱[動態標頭](/docs/zh-TW/monitoring-usage#dynamic-headers) |

352| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | OpenTelemetry 匯出器在關閉時完成作業的逾時時間（毫秒）（預設：2000）。若指標在結束時遭到捨棄，請提高此值。請參閱[監控](/docs/zh-TW/monitoring-usage) |354| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | OpenTelemetry exporter 在關閉時完成作業的逾時（毫秒）（預設：2000）。若結束時遺失指標，請調高此值。請參閱[監控](/docs/zh-TW/monitoring-usage) |

353| `CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE` | 設為 `1` 可讓 Claude Code 在有新版本可用時，於背景執行您套件管理員的升級命令。適用於 Homebrew 與 WinGet 安裝。其他套件管理員仍會顯示升級命令而不執行。請參閱[自動更新](/docs/zh-TW/setup#auto-updates) |355| `CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE` | 設為 `1` 可讓 Claude Code 在有新版本時，於背景執行您套件管理員的升級命令。適用於 Homebrew 與 WinGet 安裝。其他套件管理員仍會顯示升級命令而不執行。請參閱[自動更新](/docs/zh-TW/setup#auto-updates) |

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

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

357| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 複製或重新整理外掛市集的逾時時間（毫秒）（預設：120000）。對於大型儲存庫或緩慢的網路連線，請提高此值。請參閱 [Git clone timed out](/docs/zh-TW/plugins/troubleshooting#git-clone-timed-out-after-120s) |359| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | 控制 Claude Code 是否在 [mod](/docs/zh-TW/plugins/mods/overview) 的檔案變更時重新載入該 mod。重新載入適用於您以 `--plugin-dir` 從目錄載入的 mod，且在互動式工作階段中預設為開啟。設為 `1` 可在非互動式工作階段中也開啟，設為 `0` 則在所有工作階段中關閉。需要 Claude Code v2.1.287 或更新版本。請參閱 [mod 設定與環境變數](/docs/zh-TW/plugins/mods/reference#settings-and-environment-variables) |

358| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 設為 `1` 可在市集重新整理無法連線至遠端或無法向遠端完成身分驗證時，略過重新複製的嘗試並繼續使用現有的市集 checkout。適用於重新複製也會以相同方式失敗的離線或實體隔離環境。請參閱[市集更新在離線環境中失敗](/docs/zh-TW/plugins/troubleshooting#marketplace-updates-keep-failing-offline) |360| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 複製或重新整理外掛市集的逾時（毫秒）（預設：120000）。對於大型儲存庫或緩慢的網路連線，請調高此值。請參閱 [Git clone 逾時](/docs/zh-TW/plugins/troubleshooting#git-clone-timed-out-after-120s) |

359| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | 設為 `1` 可透過 HTTPS 而非 SSH 複製 GitHub `owner/repo` 簡寫來源。適用於外掛安裝與更新，以及 `/plugin marketplace add` 與 `update`。適用於 CI runner、容器或任何未針對 `github.com` 設定 SSH 金鑰的環境 |361| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 設為 `1` 可在市集重新整理無法連線至遠端或無法通過遠端身分驗證時，略過重新複製的嘗試並繼續使用既有的市集 checkout。適用於重新複製也會以相同方式失敗的離線或氣隙隔離環境。請參閱[市集更新在離線環境中失敗](/docs/zh-TW/plugins/troubleshooting#marketplace-updates-keep-failing-offline) |

360| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 一個或多個唯讀外掛種子目錄的路徑，在 Unix 上以 `:` 分隔，在 Windows 上以 `;` 分隔。可用來將預先填入的外掛目錄打包至容器映像中。Claude Code 會在啟動時從這些目錄註冊市集，並使用預先快取的外掛而無須重新複製。請參閱[為容器預先填入外掛](/docs/zh-TW/plugins/org#seed-containers-and-ci) |362| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | 設為 `1` 可透過 HTTPS 而非 SSH 複製 GitHub `owner/repo` 簡寫來源。適用於外掛安裝與更新，以及 `/plugin marketplace add` 與 `update`。適用於 CI runner、容器，或任何未針對 `github.com` 設定 SSH 金鑰的環境 |

361| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | 設為 `1` 可讓 Claude Code 在為工具呼叫、hook 與狀態列命令啟動 PowerShell 時不傳遞 `-ExecutionPolicy Bypass`，改為遵守機器的有效執行原則。根據預設，Claude Code 會在程序範圍略過執行原則，讓 `.ps1` 指令碼與模組匯入能在預設為 Restricted 的 Windows 安裝上運作。無論此設定為何，程序範圍的略過絕不會覆寫群組原則 `MachinePolicy` 或 `UserPolicy` |363| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 一或多個唯讀外掛種子目錄的路徑，在 Unix 上以 `:` 分隔，在 Windows 上以 `;` 分隔。使用此變數可將預先填入的外掛目錄打包至容器映像中。Claude Code 會在啟動時從這些目錄註冊市集，並使用預先快取的外掛而不重新複製。請參閱[為容器預先填入外掛](/docs/zh-TW/plugins/org#seed-containers-and-ci) |

362| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | 在使用 `-p` 旗標的[非互動模式](/docs/zh-TW/headless#background-tasks-at-exit)中，最後一個回合之後閒置等待背景工作（例如 subagent 與工作流程）的上限時間（毫秒）。每當 Claude 進行一個回合來處理背景結果時，閒置等待就會重新開始計算。預設：`600000`，即 10 分鐘。當閒置等待達到上限時，Claude Code 會停止等待其餘的背景任務並結束。設為 `0` 可無限期等待。此上限與適用於一般背景 shell 的五秒寬限期是分開的。需要 Claude Code v2.1.182 或更新版本 |364| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | 設為 `1` 可讓 Claude Code 在為工具呼叫、hook 與狀態列命令啟動 PowerShell 時不再傳遞 `-ExecutionPolicy Bypass`，而改為遵循機器實際生效的執行原則。預設情況下，Claude Code 會在程序範圍繞過執行原則，讓 `.ps1` 指令碼與模組匯入能在預設為 Restricted 的 Windows 安裝上運作。無論此設定為何，程序範圍的繞過絕不會覆寫群組原則 `MachinePolicy` 或 `UserPolicy` |

363| `CLAUDE_CODE_PROCESS_WRAPPER` | 透過以 argv 前綴（例如 `/opt/corp/launcher`）指定的企業啟動器，啟動 Claude Code 從其自身二進位檔啟動的程序，例如承載 [agent view](/docs/zh-TW/agent-view) 工作階段的背景服務。請在使用者設定或[受管設定](/docs/zh-TW/managed-settings)的 `env` 區塊中設定，而不是以 shell export 設定，如此分離的背景服務才能繼承它；專案與本機設定無法設定此變數。等同於 [`processWrapper` 設定](/docs/zh-TW/settings-reference#processwrapper)，該設定需要 Claude Code v2.1.210 或更新版本；兩者都設定時，此變數優先。VS Code 擴充功能會透過其 `claudeProcessWrapper` 設定另行設定自己的啟動器。在 Windows 上會被忽略。關於值的格式、啟動器涵蓋的範圍，以及啟動器必須符合的約定，請參閱[在企業啟動器後方執行 Claude Code](/docs/zh-TW/corporate-launcher)。需要 Claude Code v2.1.208 或更新版本 |365| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | 在使用 `-p` 旗標的[非互動模式](/docs/zh-TW/headless#background-tasks-at-exit)中，最後一個回合之後閒置等待背景工作（例如 subagent 與工作流程）的上限（毫秒）。每當 Claude 進行一個回合來處理背景結果時，閒置等待都會重新開始計算。預設：`600000`，即 10 分鐘。當閒置等待達到上限時，Claude Code 會停止等待剩餘的背景任務並結束。設為 `0` 可無限期等待。此上限與適用於一般背景 shell 的五秒寬限期是分開的。需要 Claude Code v2.1.182 或更新版本 |

364| `CLAUDE_CODE_PROJECT_DIR_NAME` | 與 `CLAUDE_CONFIG_DIR` 一起設定，以選擇 Claude Code 儲存該工作階段逐字稿與自動記憶時所使用的 `projects/` 目錄名稱，取代由工作目錄路徑衍生的名稱。例如，以 `CLAUDE_CONFIG_DIR=/srv/tenant-a CLAUDE_CODE_PROJECT_DIR_NAME=work claude` 啟動 Claude Code，會將它們儲存在 `/srv/tenant-a/projects/work/` 下。當 `CLAUDE_CONFIG_DIR` 未設定時，Claude Code 會忽略此變數，且只會從您啟動 `claude` 的環境中讀取它，絕不會從[設定檔的 `env` 區塊](#in-settings-files)讀取。請參閱[自行命名專案目錄](/docs/zh-TW/sessions#name-the-project-directory-yourself)。需要 Claude Code v2.1.234 或更新版本 |366| `CLAUDE_CODE_PROCESS_WRAPPER` | 透過以 argv 前綴（例如 `/opt/corp/launcher`）指定的企業啟動器，啟動 Claude Code 從自身二進位檔啟動的程序，例如承載 [agent view](/docs/zh-TW/agent-view) 工作階段的背景服務。請在使用者設定或[受管設定](/docs/zh-TW/managed-settings)的 `env` 區塊中設定，而非以 shell 匯出，讓分離的背景服務能夠繼承；專案與本機設定無法設定此變數。等同於 [`processWrapper` 設定](/docs/zh-TW/settings-reference#processwrapper)，該設定需要 Claude Code v2.1.210 或更新版本；兩者皆設定時以此變數為優先。VS Code 擴充功能會透過其 `claudeProcessWrapper` 設定另行設定自己的啟動器。在 Windows 上會被忽略。關於值的格式、啟動器涵蓋的範圍以及啟動器必須滿足的約定，請參閱[在企業啟動器後方執行 Claude Code](/docs/zh-TW/corporate-launcher)。需要 Claude Code v2.1.208 或更新版本 |

365| `CLAUDE_CODE_PROMPT_CACHE_TTL` | 設定 `5m` 或 `1h`（Claude Code 僅接受這兩個值），以選擇主要對話的[提示快取 TTL](/docs/zh-TW/prompt-caching#cache-lifetime)：包括您的互動式、`-p` 與 SDK 回合，以及與之內嵌執行的輔助程式。優先於 `promptCacheTtl` 設定與 `ENABLE_PROMPT_CACHING_1H`，而 `FORCE_PROMPT_CACHING_5M` 會覆寫它。API 對 1 小時快取寫入收取較高的費率。需要 Claude Code v2.1.242 或更新版本 |367| `CLAUDE_CODE_PROJECT_DIR_NAME` | 與 `CLAUDE_CONFIG_DIR` 一起設定，可選擇 Claude Code 儲存該工作階段逐字稿與自動記憶的 `projects/` 目錄名稱，取代從工作目錄路徑衍生的名稱。例如，以 `CLAUDE_CONFIG_DIR=/srv/tenant-a CLAUDE_CODE_PROJECT_DIR_NAME=work claude` 啟動 Claude Code，會將它們儲存在 `/srv/tenant-a/projects/work/` 下。當 `CLAUDE_CONFIG_DIR` 未設定時，Claude Code 會忽略此變數，且只會從您啟動 `claude` 的環境讀取，絕不會從[設定檔的 `env` 區塊](#in-settings-files)讀取。請參閱[自行命名專案目錄](/docs/zh-TW/sessions#name-the-project-directory-yourself)。需要 Claude Code v2.1.234 或更新版本 |

366| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | 設為 `1` 可在 `ANTHROPIC_BASE_URL` 指向自訂代理伺服器時傳播 W3C trace context。傳播範圍涵蓋模型與 HTTP MCP 請求上的 `traceparent` 標頭，以及 Bash、PowerShell 與 hook 子程序的 `TRACEPARENT` 環境變數。根據預設，僅在直接連線至 Anthropic API 時才會啟用傳播。於 v2.1.152 新增。請參閱[追蹤（beta）](/docs/zh-TW/monitoring-usage#traces-beta) |368| `CLAUDE_CODE_PROMPT_CACHE_TTL` | 設為 `5m` 或 `1h`（Claude Code 僅接受這兩個值），可選擇主對話的[提示快取 TTL](/docs/zh-TW/prompt-caching#cache-lifetime)：包括您的互動式、`-p` 與 SDK 回合，以及與其內嵌執行的輔助程式。優先於 `promptCacheTtl` 設定與 `ENABLE_PROMPT_CACHING_1H`，而 `FORCE_PROMPT_CACHING_5M` 會覆寫此變數。API 會以較高費率計費 1 小時的快取寫入。需要 Claude Code v2.1.242 或更新版本 |

367| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | 由嵌入 Claude Code 並代其管理模型供應商路由的主機平台設定。設定後，Claude Code 會忽略設定檔中的供應商選擇、端點與身分驗證變數，例如 `CLAUDE_CODE_USE_BEDROCK`、`ANTHROPIC_BASE_URL` 與 `ANTHROPIC_API_KEY`，因此使用者設定無法覆寫主機的路由。Claude Code 也會忽略[受管設定](/docs/zh-TW/managed-settings)中的模型選擇鍵，例如 `model`、`fallbackModel` 與 `modelOverrides`，無論由哪個受管來源提供，因此主機的模型設定會優先於過時的受管模型釘選。Claude Code 也會忽略受管 `env` 區塊中的模型選擇變數，例如 `ANTHROPIC_MODEL` 與 `ANTHROPIC_DEFAULT_*_MODEL` 系列；受管設定中的 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection) 允許清單仍然適用，除非主機提供自己的清單。Claude Code 也會略過它在第三方供應商（例如 Amazon Bedrock、Claude Platform on AWS、Google Cloud's Agent Platform 與 Microsoft Foundry）上原本會套用的自動遙測退出，因此遙測會遵循標準的 `DISABLE_TELEMETRY` 退出機制。請參閱[依 API 供應商區分的預設行為](/docs/zh-TW/data-usage#default-behaviors-by-api-provider) |369| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | 當 `ANTHROPIC_BASE_URL` 指向自訂代理伺服器時，設為 `1` 可傳播 W3C trace context。傳播涵蓋模型與 HTTP MCP 請求上的 `traceparent` 標頭，以及 Bash、PowerShell 與 hook 子程序的 `TRACEPARENT` 環境變數。預設情況下，僅在直接連線至 Anthropic API 時啟用傳播。於 v2.1.152 新增。請參閱[追蹤（beta）](/docs/zh-TW/monitoring-usage#traces-beta) |

368| `CLAUDE_CODE_PROXY_RESOLVES_HOSTS` | 設為 `1` 可讓代理伺服器而非呼叫端執行 DNS 解析。適用於應由代理伺服器處理主機名稱解析之環境的選擇性功能 |370| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | 由內嵌 Claude Code 並代其管理模型供應商路由的主機平台所設定。設定後，Claude Code 會忽略設定檔中的供應商選擇、端點與身分驗證變數，例如 `CLAUDE_CODE_USE_BEDROCK`、`ANTHROPIC_BASE_URL` 與 `ANTHROPIC_API_KEY`，因此使用者設定無法覆寫主機的路由。Claude Code 也會忽略[受管設定](/docs/zh-TW/managed-settings)中的模型選擇鍵，例如 `model`、`fallbackModel` 與 `modelOverrides`，無論由哪個受管來源傳遞，讓主機的模型設定優先於過時的受管模型固定設定。Claude Code 也會忽略受管 `env` 區塊中的模型選擇變數，例如 `ANTHROPIC_MODEL` 與 `ANTHROPIC_DEFAULT_*_MODEL` 系列；受管設定中的 [`availableModels`](/docs/zh-TW/model-config#restrict-model-selection) 允許清單仍然適用，除非主機提供自己的清單。Claude Code 也會略過它在第三方供應商（例如 Amazon Bedrock、Claude Platform on AWS、Google Cloud's Agent Platform 與 Microsoft Foundry）上原本會套用的自動遙測退出，因此遙測會遵循標準的 `DISABLE_TELEMETRY` 退出機制。請參閱[各 API 供應商的預設行為](/docs/zh-TW/data-usage#default-behaviors-by-api-provider) |

371| `CLAUDE_CODE_PROXY_RESOLVES_HOSTS` | 設為 `1` 可讓代理伺服器執行 DNS 解析，而非由呼叫端執行。適用於應由代理伺服器處理主機名稱解析之環境的選擇性功能 |

369| `CLAUDE_CODE_REMOTE` | 當 Claude Code 以[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)執行時，會自動設為 `true`。可從 hook 或設定指令碼讀取此值，以偵測您是否處於雲端工作階段中 |372| `CLAUDE_CODE_REMOTE` | 當 Claude Code 以[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)執行時，會自動設為 `true`。可從 hook 或設定指令碼讀取此值，以偵測您是否處於雲端工作階段中 |

370| `CLAUDE_CODE_REMOTE_SESSION_ID` | 在[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)中會自動設為目前工作階段的 ID。讀取此值可建構連回工作階段逐字稿的連結。請參閱[將輸出連結回工作階段](/docs/zh-TW/cloud-environments#link-output-back-to-the-session) |373| `CLAUDE_CODE_REMOTE_SESSION_ID` | 在[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)中自動設為目前工作階段的 ID。讀取此值可建構連回工作階段逐字稿的連結。請參閱[將輸出連回工作階段](/docs/zh-TW/cloud-environments#link-output-back-to-the-session) |

371| `CLAUDE_CODE_RESTRICTED` | 設為 `1` 可以受限模式啟動工作階段，與傳遞 [`--restricted`](/docs/zh-TW/cli-reference#cli-flags) 相同。Claude Code 會忽略設定檔 `env` 區塊中的此變數。需要 Claude Code v2.1.248 或更新版本 |374| `CLAUDE_CODE_RESTRICTED` | 設為 `1` 可在受限模式下啟動工作階段，與傳遞 [`--restricted`](/docs/zh-TW/cli-reference#cli-flags) 相同。Claude Code 會忽略設定檔 `env` 區塊中的此變數。需要 Claude Code v2.1.248 或更新版本 |

372| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | 設為 `1` 可在前一個工作階段於回合中途結束時自動恢復。用於 SDK 模式，讓模型無須 SDK 重新傳送提示詞即可繼續。若要關閉，請取消設定此變數或將其設為 `0`。關於 VS Code 聊天面板，請參閱[重新載入後繼續對話](/docs/zh-TW/vs-code#continue-conversations-after-a-reload) |375| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | 設為 `1` 可在先前的工作階段於回合中途結束時自動繼續。用於 SDK 模式，讓模型不需 SDK 重新傳送提示詞即可繼續。若要關閉，請取消設定此變數或將其設為 `0`。關於 VS Code 聊天面板，請參閱[重新載入後繼續對話](/docs/zh-TW/vs-code#continue-conversations-after-a-reload) |

373| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN_MAX_AGE_MS` | 對於在回合中途結束的工作階段，最後一則逐字稿訊息在恢復時仍可自動繼續的最大存在時間（毫秒）。當最後一則訊息早於此界限時，Claude Code 會略過 `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` 的自動恢復及其 `CLAUDE_CODE_RESUME_PROMPT` 接續訊息，工作階段會以閒置狀態啟動，讓您明確地繼續。未設定或 `0` 表示沒有界限，但最後一個請求因 API 錯誤而失敗的回合，只有在該錯誤發生未滿六小時時才會恢復。正值會限制每個回合，包括這些回合；負值或非數值則套用一小時的界限。長時間執行之 agent 的啟動指令碼可設定此值，讓針對舊逐字稿的重新啟動不會重新執行過時的提示詞。當 Claude Code 重新啟動一個從互動式工作階段繼承對話且已當機的 [agent view](/docs/zh-TW/agent-view) 工作階段時，會自行設定一小時的界限。需要 Claude Code v2.1.211 或更新版本 |376| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN_MAX_AGE_MS` | 於回合中途結束的工作階段在繼續時可自動接續的最後一則逐字稿訊息的最大存在時間（毫秒）。當最後一則訊息超過此界限時，Claude Code 會略過 `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` 自動繼續及其 `CLAUDE_CODE_RESUME_PROMPT` 接續訊息，工作階段會以閒置狀態啟動，讓您明確地繼續。未設定或 `0` 表示沒有界限，但最後一個請求因 API 錯誤而失敗的回合，只有在該錯誤發生未滿六小時時才會繼續。正值會限制每個回合，包括上述回合；負值或非數值會套用一小時的界限。長時間執行之 agent 的產生指令碼可以設定此值，讓針對舊逐字稿的重新啟動不會重新執行過時的提示詞。當 Claude Code 重新啟動一個從互動式工作階段繼承對話且已當機的 [agent view](/docs/zh-TW/agent-view) 工作階段時，會自行設定一小時的界限。需要 Claude Code v2.1.211 或更新版本 |

374| `CLAUDE_CODE_RESUME_PROMPT` | 覆寫 Claude Code 在 `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` 繼續被中斷的回合（而非重新傳送其提示詞）時，或您以 `-p` 恢復[延後的工具呼叫](/docs/zh-TW/hooks#defer-a-tool-call-for-later)時，傳送給 Claude 的接續訊息。預設為 `Continue from where you left off.`。空字串會使用預設值 |377| `CLAUDE_CODE_RESUME_PROMPT` | 覆寫當 `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` 接續中斷的回合而非重新傳送其提示詞時，或當您以 `-p` 繼續[延後的工具呼叫](/docs/zh-TW/hooks#defer-a-tool-call-for-later)時，Claude Code 傳送給 Claude 的接續訊息。預設為 `Continue from where you left off.`。空字串會使用預設值 |

375| `CLAUDE_CODE_RETRY_WATCHDOG` | 針對無人看管的工作階段（例如評估框架、CI 工作或遠端 worker）設為 `1`。會無限期重試 `429` 與 `529` 容量錯誤，而不是在 `CLAUDE_CODE_MAX_RETRIES` 次嘗試後失敗。當標準速度請求收到回報支出上限或用量點數已用盡的 `429` 時，Claude Code 會立即失敗，即使該回應來自依排程重設的[閘道支出上限](/docs/zh-TW/errors#spend-limit-reached)也一樣。在 v2.1.239 之前，watchdog 會無限期重試這些錯誤。關於快速模式請求，請參閱[處理速率限制](/docs/zh-TW/fast-mode#handle-rate-limits)。watchdog 在每次嘗試之間最多退避 5 分鐘，或當回應帶有速率限制重設時間時，等到限制重設為止，因此達到用量上限的工作階段會等待剩餘的時間窗結束。在 v2.1.199 或更新版本中，它也會將其他暫時性錯誤（例如伺服器錯誤、逾時與連線中斷）的預設重試次數提高至 300 次，約為三小時的退避時間，並在您明確設定 `CLAUDE_CODE_MAX_RETRIES` 時移除其 15 次的上限。需要 Claude Code v2.1.186 或更新版本 |378| `CLAUDE_CODE_RETRY_WATCHDOG` | 針對無人值守的工作階段（例如評估測試框架、CI 作業或遠端 worker）設為 `1`。會無限期重試 `429` 與 `529` 容量錯誤，而不會在 `CLAUDE_CODE_MAX_RETRIES` 次嘗試後失敗。當標準速度的請求收到回報支出上限或用量點數耗盡的 `429` 時，Claude Code 會立即失敗，即使是來自依排程重設的[閘道支出上限](/docs/zh-TW/errors#spend-limit-reached)也一樣。在 v2.1.239 之前，watchdog 會無限期重試這些錯誤。關於快速模式請求，請參閱[處理速率限制](/docs/zh-TW/fast-mode#handle-rate-limits)。watchdog 會在嘗試之間最多退避 5 分鐘，或在回應帶有速率限制重設時間時等到限制重設為止，因此達到用量上限的工作階段會等待剩餘的時間窗結束。在 v2.1.199 或更新版本中，它也會將其他暫時性錯誤（例如伺服器錯誤、逾時與中斷的連線）的預設重試次數提高到 300，約為三小時的退避時間，並在您明確設定 `CLAUDE_CODE_MAX_RETRIES` 時移除其 15 次的上限。需要 Claude Code v2.1.186 或更新版本 |

376| `CLAUDE_CODE_SAFE_MODE` | 設為 `1` 可以安全模式啟動：CLAUDE.md、skill、外掛、hook、MCP 伺服器、自訂命令與 agent、輸出風格、工作流程、自訂主題、自訂快捷鍵、狀態列與檔案建議命令、LSP 伺服器以及自動記憶都不會載入，以便對損壞的設定進行疑難排解。受管設定政策仍然適用，包括由政策設定的 hook、狀態列與檔案建議命令；受管外掛、受管 skill、受管 CLAUDE.md 與由政策設定的 MCP 伺服器則不會載入。等同於傳遞 [`--safe-mode`](/docs/zh-TW/cli-reference#cli-flags)。直接產生的子程序會繼承此變數 |379| `CLAUDE_CODE_SAFE_MODE` | 設為 `1` 可在安全模式下啟動：CLAUDE.md、skill、外掛、hook、MCP 伺服器、自訂命令與 agent、輸出風格、工作流程、自訂主題、自訂快捷鍵、狀態列與檔案建議命令、LSP 伺服器以及自動記憶都不會載入，以便對損壞的設定進行疑難排解。受管設定原則仍然適用，包括原則所設定的 hook、狀態列與檔案建議命令；受管外掛、受管 skill、受管 CLAUDE.md 以及原則所設定的 MCP 伺服器則不適用。等同於傳遞 [`--safe-mode`](/docs/zh-TW/cli-reference#cli-flags)。直接產生的子程序會繼承此變數 |

377| `CLAUDE_CODE_SCRIPT_CAPS` | 當設定了 `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` 時，限制特定指令碼在每個工作階段中可被呼叫次數的 JSON 物件。鍵是與命令文字比對的子字串；值是整數呼叫上限。例如，`{"deploy.sh": 2}` 允許 `deploy.sh` 最多被呼叫兩次。比對以子字串為基礎，因此像 `./scripts/deploy.sh $(evil)` 這類 shell 展開手法仍會計入上限。透過 `xargs` 或 `find -exec` 進行的執行期擴散不會被偵測到；這是一項縱深防禦控制 |380| `CLAUDE_CODE_SCRIPT_CAPS` | 在設定 `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` 時，限制特定指令碼每個工作階段可被呼叫次數的 JSON 物件。鍵是與命令文字比對的子字串；值是整數呼叫上限。例如，`{"deploy.sh": 2}` 允許 `deploy.sh` 最多被呼叫兩次。比對以子字串為基礎，因此像 `./scripts/deploy.sh $(evil)` 這樣的 shell 展開技巧仍會計入上限。透過 `xargs` 或 `find -exec` 的執行期擴散無法偵測；這是一種縱深防禦控制 |

378| `CLAUDE_CODE_SCROLL_SPEED` | 設定[全螢幕呈現](/docs/zh-TW/fullscreen#mouse-wheel-scrolling)中的滑鼠滾輪捲動倍數。接受最大 20 的任何正值，包括低於 1 的小數值，例如 `0.5`，可在已放大滾輪事件的終端機中減慢加速的觸控板與滾輪捲動。若您的終端機每一格傳送一個滾輪事件且未放大，設為 `3` 可與 `vim` 一致。在 JetBrains IDE 終端機中會被忽略，因為 Claude Code 在那裡使用自己的捲動處理 |381| `CLAUDE_CODE_SCROLL_SPEED` | 設定[全螢幕呈現](/docs/zh-TW/fullscreen#mouse-wheel-scrolling)中的滑鼠滾輪捲動倍數。接受最大 20 的任何正值，包括小於 1 的小數值（例如 `0.5`），以在已放大滾輪事件的終端機中減緩加速的觸控板與滾輪捲動。若您的終端機每個刻度傳送一個滾輪事件且未放大，請設為 `3` 以符合 `vim`。在 JetBrains IDE 終端機中會被忽略，因為 Claude Code 在該處使用自己的捲動處理 |

379| `CLAUDE_CODE_SEND_FEEDBACK` | 設為 `0` 可為工作階段關閉 [Claude 草擬的意見回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior)。在您的帳戶已具備存取權的情況下，設為 `1` 可將其開啟；此變數本身無法授予存取權，而其他關閉意見回饋的開關，例如 `DISABLE_FEEDBACK_COMMAND` 與 [`feedbackDrafts`](/docs/zh-TW/settings-reference#feedbackdrafts) 設定的 `off` 值，仍然適用 |382| `CLAUDE_CODE_SEND_FEEDBACK` | 設為 `0` 可為工作階段關閉 [Claude 草擬的意見回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior)。設為 `1` 可在您的帳戶已具有存取權時開啟；此變數本身無法授予存取權，且其他關閉意見回饋的開關（例如 `DISABLE_FEEDBACK_COMMAND` 以及 [`feedbackDrafts`](/docs/zh-TW/settings-reference#feedbackdrafts) 設定的 `off` 值）仍然適用 |

380| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | 覆寫 [SessionEnd](/docs/zh-TW/hooks#sessionend) hook 的時間預算（毫秒）。此值也是每個未自行設定 `timeout` 之 hook 的逾時時間。適用於工作階段結束、`/clear`，以及透過互動式 `/resume` 切換工作階段。根據預設，預算為 1.5 秒，並會自動提高至設定檔中所設定的最高個別 hook `timeout`，最多 60 秒。外掛提供之 hook 的逾時不會提高預算 |383| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | 覆寫 [SessionEnd](/docs/zh-TW/hooks#sessionend) hook 的時間預算（毫秒）。此值也是每個未自行設定 `timeout` 的 hook 的逾時。適用於工作階段結束、`/clear`，以及透過互動式 `/resume` 切換工作階段。預設預算為 1.5 秒，並會自動提高至設定檔中所設定的最高個別 hook `timeout`，最多 60 秒。外掛提供的 hook 上的逾時不會提高預算 |

381| `CLAUDE_CODE_SESSION_ID` | 在 Bash 與 PowerShell 工具子程序、[hook 命令](/docs/zh-TW/hooks)子程序以及 stdio [MCP 伺服器](/docs/zh-TW/mcp)子程序中，會自動設為目前的工作階段 ID。對於 Bash、PowerShell 與 hook，此值與 hook JSON 輸入中的 `session_id` 欄位一致，並會在 `/clear` 時更新。MCP 伺服器子程序會保留其啟動時的 ID。使用 `--resume <session-id>` 時，它會收到恢復後的 ID，與 hook 和 Bash 一致。使用 `--continue` 或未指定明確 ID 的 `--resume` 時，它可能會改為收到初始啟動時的 ID。可用來將指令碼與外部工具關聯到啟動它們的 Claude Code 工作階段 |384| `CLAUDE_CODE_SESSION_ID` | 在 Bash 與 PowerShell 工具子程序、[hook 命令](/docs/zh-TW/hooks)子程序以及 stdio [MCP 伺服器](/docs/zh-TW/mcp)子程序中，自動設為目前的工作階段 ID。對於 Bash、PowerShell 與 hook，此值與 hook JSON 輸入中的 `session_id` 欄位相符，並會在 `/clear` 時更新。MCP 伺服器子程序會保留其產生時的 ID。在 `--resume <session-id>` 時，它會收到繼續的 ID，與 hook 和 Bash 相符。在未指定明確 ID 的 `--continue` 或 `--resume` 時，它可能會改為收到初始啟動的 ID。可用於將指令碼與外部工具關聯至啟動它們的 Claude Code 工作階段 |

382| `CLAUDE_CODE_SHELL` | 設定 Claude Code 用來執行 Bash 工具命令的 shell。接受 `bash` 或 `zsh` 二進位檔的路徑，例如 `/opt/homebrew/bin/bash`。不支援其他 shell，例如 `fish`。若該值不是可運作的 `bash` 或 `zsh` 路徑，Claude Code 會忽略它並改用自動偵測。自動偵測會在您的 `$SHELL` 指向 `bash` 或 `zsh` 時使用它，否則會在您的 `PATH` 與標準安裝位置中，先挑選第一個可運作的 `zsh`，其次是 `bash` |385| `CLAUDE_CODE_SHELL` | 設定 Claude Code 用於執行 Bash 工具命令的 shell。接受 `bash` 或 `zsh` 二進位檔的路徑，例如 `/opt/homebrew/bin/bash`。不支援其他 shell，例如 `fish`。若此值不是可運作的 `bash` 或 `zsh` 路徑，Claude Code 會忽略它並改用自動偵測。自動偵測會在您的 `$SHELL` 指向 `bash` 或 `zsh` 時使用它，否則會在您的 `PATH` 與標準安裝位置中，依序挑選第一個可運作的 `zsh`，再來是 `bash` |

383| `CLAUDE_CODE_SHELL_PREFIX` | 包裝 Claude Code 所產生之 shell 命令的命令前綴：Bash 工具呼叫、[hook](/docs/zh-TW/hooks) 命令、[狀態列](/docs/zh-TW/statusline)命令，以及 stdio [MCP 伺服器](/docs/zh-TW/mcp)啟動命令。PowerShell hook 與 exec 形式的 hook 執行時不會加上前綴。適用於日誌記錄或稽核。設定為單純的可執行檔路徑（例如 `/path/to/logger.sh`）時，會以 `/path/to/logger.sh '<command>'` 執行每個命令。包裝程式會在 `$1` 中以單一經 shell 引號處理的引數接收命令列，因此包裝程式必須以 shell 重新評估 `$1`，例如 `exec bash -c "$1"`。將 `$1` 視為單純的可執行檔路徑，會破壞傳遞 `npx -y <package>` 等引數的 stdio MCP 伺服器。對於 Bash 工具呼叫，`$1` 包含 Claude Code 組合的完整 shell 呼叫，包括環境設定，而不僅是 Claude 執行的命令 |386| `CLAUDE_CODE_SHELL_PREFIX` | 包裝 Claude Code 所產生之 shell 命令的命令前綴：Bash 工具呼叫、[hook](/docs/zh-TW/hooks) 命令、[狀態列](/docs/zh-TW/statusline)命令以及 stdio [MCP 伺服器](/docs/zh-TW/mcp)啟動命令。PowerShell hook 與 exec 形式的 hook 不會加上前綴執行。適用於記錄或稽核。設定像 `/path/to/logger.sh` 這樣的單純執行檔路徑，會將每個命令以 `/path/to/logger.sh '<command>'` 的形式執行。包裝程式會在 `$1` 中以單一經 shell 引號處理的引數接收命令列，因此包裝程式必須以 shell 重新評估 `$1`，例如 `exec bash -c "$1"`。將 `$1` 視為單純執行檔路徑，會導致傳遞引數（例如 `npx -y <package>`）的 stdio MCP 伺服器無法運作。對於 Bash 工具呼叫，`$1` 包含 Claude Code 組合的完整 shell 呼叫，包括環境設定，而不僅是 Claude 執行的命令 |

384| `CLAUDE_CODE_SIMPLE` | 設為 `1` 可以最精簡的系統提示詞執行，且僅提供 Bash、檔案讀取與檔案編輯工具。來自 `--mcp-config` 的 MCP 工具仍可使用。停用 hook、skill、自訂命令、subagent、已安裝外掛、MCP 伺服器、自動記憶與 CLAUDE.md 的自動探索。透過 `--add-dir` 傳入之目錄中的 skill 仍會載入。不會讀取 OAuth token 與 keychain 憑證，因此 Anthropic 身分驗證必須來自 `ANTHROPIC_API_KEY` 或 `--settings` 中的 `apiKeyHelper`。等同於傳遞 [`--bare`](/docs/zh-TW/headless#start-faster-with-bare-mode) |387| `CLAUDE_CODE_SIMPLE` | 設為 `1` 可以最精簡的系統提示詞執行，且只使用 Bash、檔案讀取與檔案編輯工具。來自 `--mcp-config` 的 MCP 工具仍可使用。停用 hook、skill、自訂命令、subagent、已安裝外掛、MCP 伺服器、自動記憶以及 CLAUDE.md 的自動探索。您以 `--add-dir` 傳入之目錄中的 skill 仍會載入。不會讀取 OAuth token 與鑰匙圈憑證，因此 Anthropic 身分驗證必須來自 `ANTHROPIC_API_KEY` 或 `--settings` 中的 `apiKeyHelper`。等同於傳遞 [`--bare`](/docs/zh-TW/headless#start-faster-with-bare-mode) |

385| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 設為 `1` 可在任何模型上使用較短的系統提示詞與精簡的工具描述。設為 `0`、`false`、`no` 或 `off` 可選擇退出，即使在實驗或伺服器設定原本會啟用它的模型上也一樣。完整的工具集、hook、MCP 伺服器與 CLAUDE.md 探索仍保持啟用 |388| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 設為 `1` 可在任何模型上使用較短的系統提示詞與精簡的工具描述。設為 `0`、`false`、`no` 或 `off` 可選擇退出，即使在實驗或伺服器設定原本會啟用它的模型上也一樣。完整的工具集、hook、MCP 伺服器以及 CLAUDE.md 探索仍保持啟用 |

386| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | 略過 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 的用戶端身分驗證，適用於自行簽署請求的閘道 |389| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | 略過 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 的用戶端身分驗證，適用於自行簽署請求的閘道 |

387| `CLAUDE_CODE_SKIP_AWS_CRED_CACHE` | 設為 `1` 可關閉從 AWS 預設憑證提供者鏈解析之憑證的程序內快取，讓 Claude Code 在每個 API 請求時都解析該鏈。快取關閉時，以 SSO 為基礎的設定檔會在每個請求時向 IAM Identity Center 請求憑證。請參閱[憑證快取與解析逾時](/docs/zh-TW/amazon-bedrock#credential-caching-and-resolution-timeout)。需要 Claude Code v2.1.207 或更新版本 |390| `CLAUDE_CODE_SKIP_AWS_CRED_CACHE` | 設為 `1` 可關閉從 AWS 預設憑證提供者鏈所解析之憑證的程序內快取，讓 Claude Code 在每個 API 請求時都解析該鏈。關閉快取後，以 SSO 為基礎的設定檔會在每個請求時向 IAM Identity Center 請求憑證。請參閱[憑證快取與解析逾時](/docs/zh-TW/amazon-bedrock#credential-caching-and-resolution-timeout)。需要 Claude Code v2.1.207 或更新版本 |

389| `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS` | 設為 `1` 可將失敗的[快速模式](/docs/zh-TW/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)可用性檢查視為可用，適用於會封鎖該檢查直接傳送至 `api.anthropic.com` 之請求的網路。Claude Code 仍會遵守「disabled by your organization」回應 |392| `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS` | 設為 `1` 可將失敗的[快速模式](/docs/zh-TW/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)可用性檢查視為可用，適用於封鎖該檢查直接連往 `api.anthropic.com` 之請求的網路。Claude Code 仍會遵循「disabled by your organization」回應 |

390| `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK` | 設為 `1` 可略過用戶端的[快速模式](/docs/zh-TW/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)可用性檢查，適用於會攔截該檢查之請求而非拒絕它的代理伺服器。當您的組織已停用快速模式時，API 仍會拒絕快速模式請求 |393| `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK` | 設為 `1` 可略過用戶端的[快速模式](/docs/zh-TW/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)可用性檢查，適用於攔截而非拒絕該檢查請求的代理伺服器。當您的組織已停用快速模式時，API 仍會拒絕快速模式請求 |

391| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | 略過 Microsoft Foundry 的 Azure 身分驗證，適用於會注入自己 `Authorization` 標頭的代理伺服器或閘道。Claude Code 會在不附帶 Azure 憑證的情況下傳送請求，並保留您提供的 `Authorization` 標頭，例如透過 `ANTHROPIC_CUSTOM_HEADERS` 提供的標頭。設定了 `ANTHROPIC_FOUNDRY_API_KEY` 或 `ANTHROPIC_FOUNDRY_AUTH_TOKEN` 時會被忽略。在 v2.1.203 之前，除非同時設定了 API 金鑰，否則此變數會導致 Microsoft Foundry 用戶端無法傳送請求 |394| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | 略過 Microsoft Foundry 的 Azure 身分驗證，適用於注入自己 `Authorization` 標頭的代理伺服器或閘道。Claude Code 會在不帶 Azure 憑證的情況下傳送請求，並保留您提供的 `Authorization` 標頭（例如透過 `ANTHROPIC_CUSTOM_HEADERS`）。當設定 `ANTHROPIC_FOUNDRY_API_KEY` 或 `ANTHROPIC_FOUNDRY_AUTH_TOKEN` 時會被忽略。在 v2.1.203 之前，除非同時設定 API 金鑰，否則此變數會導致 Microsoft Foundry 用戶端無法傳送請求 |

393| `CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY` | [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 與 [Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai) 上的[啟動模型檢查](/docs/zh-TW/amazon-bedrock#startup-model-checks)，會在此機器上記住它們發現您的帳戶無法呼叫哪些模型，最長一天。設為 `1` 可關閉此記憶。需要 Claude Code v2.1.285 或更新版本 |396| `CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY` | [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) 與 [Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai) 上的[啟動模型檢查](/docs/zh-TW/amazon-bedrock#startup-model-checks)，會在此機器上記住它們發現您的帳戶無法呼叫的模型，最長一天。設為 `1` 可關閉此記憶。需要 Claude Code v2.1.285 或更新版本 |

394| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 設為 `1` 可略過將提示詞歷史記錄與工作階段逐字稿寫入磁碟。在設定此變數的情況下啟動的工作階段，不會出現在 `--resume`、`--continue` 或上方向鍵歷史記錄中。適用於短暫的指令碼工作階段 |397| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 設為 `1` 可略過將提示詞歷史記錄與工作階段逐字稿寫入磁碟。設定此變數後啟動的工作階段不會出現在 `--resume`、`--continue` 或向上鍵歷史記錄中。適用於短暫的指令碼化工作階段 |

396| `CLAUDE_CODE_STARTUP_FAILURE_RESULTS` | 設為 `1` 可讓以 `--output-format stream-json` 啟動的工作階段，針對原本只會以 stderr 結束的啟動失敗，寫入一則[說明 Claude Code 拒絕啟動原因的結果訊息](/docs/zh-TW/agent-sdk/typescript#startup_failure_reason)。需要 Claude Code v2.1.274 或更新版本 |399| `CLAUDE_CODE_STARTUP_FAILURE_RESULTS` | 設為 `1` 可讓以 `--output-format stream-json` 啟動的工作階段，針對原本只以 stderr 結束的啟動失敗，寫入一則[說明 Claude Code 拒絕啟動原因的結果訊息](/docs/zh-TW/agent-sdk/typescript#startup_failure_reason)。需要 Claude Code v2.1.274 或更新版本 |

397| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | [Stop](/docs/zh-TW/hooks#stop) 或 [SubagentStop](/docs/zh-TW/hooks#subagentstop) hook 可連續阻止回合結束的最大次數，超過後 Claude Code 會覆寫它並仍然結束回合（預設：8）。設為 `0` 可停用上限。若您的 hook 確實需要更多次迭代才能解決，請提高此值 |400| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | [Stop](/docs/zh-TW/hooks#stop) 或 [SubagentStop](/docs/zh-TW/hooks#subagentstop) hook 可連續阻止回合結束的最大次數，超過後 Claude Code 會覆寫它並仍然結束回合（預設：8）。設為 `0` 可停用上限。若您的 hook 確實需要更多次迭代才能解決，請調高此值 |

398| `CLAUDE_CODE_SUBAGENT_MODEL` | 未以其他方式指派模型之 [subagent](/docs/zh-TW/sub-agents#choose-a-model)、[agent team](/docs/zh-TW/agent-teams#specify-teammates-and-models) 隊員與[工作流程](/docs/zh-TW/workflows) agent 的預設模型。接受 `haiku` 等別名或完整模型名稱。有兩個來源優先於此變數：Claude 在產生 agent 時傳遞的模型，以及 agent 定義中的 `model` 欄位（包括 `inherit`）。若要改變這一點，請設定 [`CLAUDE_CODE_SUBAGENT_MODEL_FORCE`](/docs/zh-TW/sub-agents#run-every-subagent-on-one-model)。完整順序請參閱[選擇模型](/docs/zh-TW/sub-agents#choose-a-model)。將其設為 `inherit` 與不設定相同。在 v2.1.251 之前，此變數會覆寫每次呼叫的模型與定義中的 `model` 欄位 |401| `CLAUDE_CODE_SUBAGENT_MODEL` | 未透過其他方式指定模型的 [subagent](/docs/zh-TW/sub-agents#choose-a-model)、[agent team](/docs/zh-TW/agent-teams#specify-teammates-and-models) 隊員以及[工作流程](/docs/zh-TW/workflows) agent 的預設模型。接受別名（例如 `haiku`）或完整模型名稱。有兩個來源優先於此變數：Claude 產生 agent 時傳遞的模型，以及 agent 定義中的 `model` 欄位（包括 `inherit`）。若要改變這一點，請設定 [`CLAUDE_CODE_SUBAGENT_MODEL_FORCE`](/docs/zh-TW/sub-agents#run-every-subagent-on-one-model)。完整順序請參閱[選擇模型](/docs/zh-TW/sub-agents#choose-a-model)。設為 `inherit` 與不設定相同。在 v2.1.251 之前，此變數會覆寫每次呼叫的模型與定義的 `model` 欄位 |

399| `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` | 設為 `1` 可將單一模型強制套用至 subagent、隊員與工作流程 agent。[讓每個 subagent 都在同一個模型上執行](/docs/zh-TW/sub-agents#run-every-subagent-on-one-model)說明了是哪個模型。需要 Claude Code v2.1.257 或更新版本 |402| `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` | 設為 `1` 可強制 subagent、隊員與工作流程 agent 使用同一個模型。[讓每個 subagent 都在同一個模型上執行](/docs/zh-TW/sub-agents#run-every-subagent-on-one-model)說明了是哪一個模型。需要 Claude Code v2.1.257 或更新版本 |

400| `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL` | 設定 `5m` 或 `1h`（Claude Code 僅接受這兩個值），以選擇主要對話以外之請求的[提示快取 TTL](/docs/zh-TW/prompt-caching#cache-lifetime)，例如 [subagent](/docs/zh-TW/sub-agents)、工作流程與背景工作。優先於 `subagentPromptCacheTtl` 設定與 `ENABLE_PROMPT_CACHING_1H`，而 `FORCE_PROMPT_CACHING_5M` 會覆寫它。API 對 1 小時快取寫入收取較高的費率。需要 Claude Code v2.1.242 或更新版本 |403| `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL` | 設為 `5m` 或 `1h`（Claude Code 僅接受這兩個值），可選擇主對話以外之請求的[提示快取 TTL](/docs/zh-TW/prompt-caching#cache-lifetime)，例如 [subagent](/docs/zh-TW/sub-agents)、工作流程與背景工作。優先於 `subagentPromptCacheTtl` 設定與 `ENABLE_PROMPT_CACHING_1H`，而 `FORCE_PROMPT_CACHING_5M` 會覆寫此變數。API 會以較高費率計費 1 小時的快取寫入。需要 Claude Code v2.1.242 或更新版本 |

401| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | 設為 `1` 可從 Claude Code 啟動之子程序（例如 Bash 命令、hook 與 stdio MCP 伺服器）的環境中移除憑證。清除機制會依變數名稱或其值辨識憑證，並保留 GitHub token 與代理伺服器設定。請參閱[子程序環境清除會移除哪些內容](#what-the-subprocess-environment-scrub-removes)。設定 `allowed_non_write_users` 時，`claude-code-action` 會自動設定此變數 |404| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | 設為 `1` 可從 Claude Code 啟動之子程序（例如 Bash 命令、hook 與 stdio MCP 伺服器）的環境中移除憑證。清除機制會依變數名稱或值辨識憑證，並保留 GitHub token 與代理伺服器設定。請參閱[子程序環境清除會移除哪些內容](#what-the-subprocess-environment-scrub-removes)。設定 `allowed_non_write_users` 時，`claude-code-action` 會自動設定此變數 |

402| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 在非互動模式（`-p` 旗標）中設為 `1`，可在第一個查詢之前等待外掛安裝完成。若未設定，外掛會在背景安裝，可能在第一個回合時無法使用。可搭配 `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` 限制等待時間 |405| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 在非互動模式（`-p` 旗標）中設為 `1`，可在第一個查詢之前等待外掛安裝完成。若未設定，外掛會在背景安裝，且可能在第一個回合時無法使用。可搭配 `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` 以限制等待時間 |

403| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | 同步外掛安裝的逾時時間（毫秒）。超過時，Claude Code 會在沒有外掛的情況下繼續，並記錄一則錯誤。無預設值：若未設定此變數，同步安裝會等到完成為止 |406| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | 同步外掛安裝的逾時（毫秒）。超過時，Claude Code 會在沒有外掛的情況下繼續並記錄錯誤。沒有預設值：若未設定此變數，同步安裝會等到完成為止 |

404| `CLAUDE_CODE_SYNC_SKILLS` | 在使用 `-p` 旗標的非互動模式中設為 `1`，可讓 Claude Code 在該次執行中下載您 claude.ai 帳戶已啟用的 skill，並在執行第一個查詢之前等待其清單，最長等待 `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS`。下載本身會在背景完成，而當 Claude 呼叫某個 skill 時，會等待該 skill 下載完成。需要 claude.ai 身分驗證。您以 claude.ai 帳戶登入的終端機工作階段，即使未設定此變數，也會將這些 skill [下載](/docs/zh-TW/skills#where-synced-skills-load)至 `~/.claude/skills/synced/`，並約每 10 分鐘重新同步一次，因此只有在 `-p` 執行需要在第一個查詢時就使用您目前的 skill 時才需要設定。在 v2.1.273 之前，終端機工作階段只會在設定了此變數的 `-p` 執行中下載它們。`synced` 資料夾名稱[保留給此下載使用](/docs/zh-TW/skills#where-skills-live)。在 v2.1.227 之前，skill 會直接下載至 `~/.claude/skills/`。Claude Code 會[對下載的 skill 套用額外規則](/docs/zh-TW/skills#how-synced-skills-behave)，例如不在您的機器上執行其 `!` 命令 |407| `CLAUDE_CODE_SYNC_SKILLS` | 在搭配 `-p` 旗標的非互動模式中設為 `1`，可讓 Claude Code 在該次執行中下載為您的 claude.ai 帳戶啟用的 skill，並在執行第一次查詢之前等待其清單，最長等待 `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS`。需要 claude.ai 身分驗證。您以 claude.ai 帳戶登入的終端機工作階段不需要此變數就會[同步這些 skill](/docs/zh-TW/skills#where-synced-skills-load)，因此請僅在 `-p` 執行需要在第一次查詢時取得您目前的 skill 時才設定 |

405| `CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MS` | 當以 [Agent SDK](/docs/zh-TW/agent-sdk/typescript#query-object) 建置的應用程式重新載入 skill 時，在工作階段中途執行之 skill 重新同步的逾時時間（毫秒）（預設：30000）。超過時，重新載入會以已送達的 skill 繼續，其餘的下載會在背景完成 |408| `CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MS` | 當以 [Agent SDK](/docs/zh-TW/agent-sdk/typescript#query-object) 建置的應用程式重新載入 skill 時，於工作階段中途執行之 skill 重新同步的逾時（毫秒）（預設：30000）。超過時，重新載入會以已抵達的 skill 繼續進行，其餘的下載則在背景完成 |

406| `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` | 設定 `CLAUDE_CODE_SYNC_SKILLS` 時，第一個查詢等待初始 skill 清單的逾時時間（毫秒）（預設：5000）。超過時，第一個查詢會以已送達的 skill 執行。無論如何，下載都會在背景完成，而當 Claude 呼叫某個 skill 時，會等待該 skill 下載完成 |409| `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` | 設定 `CLAUDE_CODE_SYNC_SKILLS` 時，第一個查詢等待初始 skill 清單的逾時（毫秒）（預設：5000）。超過時，第一個查詢會以已抵達的 skill 執行。無論如何，下載都會在背景完成，而 Claude 在呼叫某個 skill 時會等待該 skill 下載完成 |

407| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | 設為 `false` 可停用差異輸出中的語法醒目提示。適用於色彩干擾您終端機設定的情況。若也要停用程式碼區塊與檔案預覽中的醒目提示，請使用 [`syntaxHighlightingDisabled`](/docs/zh-TW/settings-reference#syntaxhighlightingdisabled) 設定 |410| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | 設為 `false` 可停用差異輸出中的語法醒目提示。適用於色彩干擾您終端機設定的情況。若也要在程式碼區塊與檔案預覽中停用醒目提示，請使用 [`syntaxHighlightingDisabled`](/docs/zh-TW/settings-reference#syntaxhighlightingdisabled) 設定 |

408| `CLAUDE_CODE_TASK_LIST_ID` | 在多個工作階段之間共用任務清單。在多個 Claude Code 執行個體中設定相同的 ID，即可在[具備 Task 工具的工作階段](/docs/zh-TW/tools-reference#task-tool-availability)中協調共用的任務清單。請參閱[任務清單](/docs/zh-TW/interactive-mode#task-list) |411| `CLAUDE_CODE_TASK_LIST_ID` | 在多個工作階段之間共用任務清單。在多個 Claude Code 執行個體中設定相同的 ID，即可在[具備 Task 工具的工作階段](/docs/zh-TW/tools-reference#task-tool-availability)中協調共用的任務清單。請參閱[任務清單](/docs/zh-TW/interactive-mode#task-list) |

409| `CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MS` | 以毫秒為單位，覆寫非互動工作階段在結束時等待其 [agent team](/docs/zh-TW/agent-teams) 完成拆除的時間。接受 1000 至 60000；超出範圍的值會被忽略，並套用預設值 10000。需要 Claude Code v2.1.206 或更新版本 |412| `CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MS` | 以毫秒覆寫非互動式工作階段在結束時等待其 [agent team](/docs/zh-TW/agent-teams) 完成拆除的時間。接受 1000 至 60000；超出範圍的值會被忽略並套用預設值 10000。需要 Claude Code v2.1.206 或更新版本 |

410| `CLAUDE_CODE_TMPDIR` | 覆寫用於內部暫存檔的暫存目錄。Claude Code 在 Unix 上會在此路徑後附加 `/claude-{uid}/`，在 Windows 上則附加 `/claude/`。預設：macOS 上為 `/tmp`，Linux 與 Windows 上為 `os.tmpdir()`。在 macOS 與 Linux 上，當您的覆寫值是較長的路徑時，[沙箱化](/docs/zh-TW/sandboxing)的 Bash 子程序會收到位於系統預設值下的較短備援 `$TMPDIR`，因為某些工具在暫存路徑過長時會失敗。未沙箱化的 Bash 命令在您的 shell 設定了 `$TMPDIR` 時會繼承它。在原生 Windows 上，當您的 shell 未設定 `$TMPDIR` 時，參照 `$TMPDIR` 的 Bash 命令會收到您的覆寫值，若您未設定覆寫值則收到 `%TEMP%`。Claude Code 自身的暫存檔一律使用您的覆寫值。請在您的 shell、使用者設定或受管設定中設定。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略 |413| `CLAUDE_CODE_TMPDIR` | 覆寫用於內部暫存檔案的暫存目錄。Claude Code 會在 Unix 上於此路徑後附加 `/claude-{uid}/`，在 Windows 上附加 `/claude/`。預設：macOS 上為 `/tmp`，Linux 與 Windows 上為 `os.tmpdir()`。在 macOS 與 Linux 上，當您的覆寫值是較長的路徑時，[沙箱化](/docs/zh-TW/sandboxing)的 Bash 子程序會收到位於系統預設值下的較短備援 `$TMPDIR`，因為某些工具在暫存路徑過長時會失敗。未沙箱化的 Bash 命令會在您的 shell 已設定 `$TMPDIR` 時繼承它。在原生 Windows 上，當您的 shell 未設定 `$TMPDIR` 時，參照 `$TMPDIR` 的 Bash 命令會收到您的覆寫值，若您未設定則收到 `%TEMP%`。Claude Code 自身的暫存檔案一律使用您的覆寫值。請在您的 shell、使用者設定或受管設定中設定。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略 |

411| `CLAUDE_CODE_TMUX_TRUECOLOR` | 設為任何非空值（例如 `1`），可允許在 tmux 中輸出 24 位元 truecolor。**設為 `0` 或 `false` 仍會允許 truecolor**，這與大多數開/關變數不同；請取消設定此變數以恢復 256 色限制。根據預設，當設定了 `$TMUX` 時，Claude Code 會限制為 256 色，因為除非經過設定，否則 tmux 不會傳遞 truecolor 跳脫序列。請在將 `set -ga terminal-overrides ',*:Tc'` 加入您的 `~/.tmux.conf` 之後設定此變數。其他 tmux 設定請參閱[終端機設定](/docs/zh-TW/terminal-config) |414| `CLAUDE_CODE_TMUX_TRUECOLOR` | 設為任何非空值（例如 `1`）可允許在 tmux 內輸出 24 位元真彩色。**設為 `0` 或 `false` 仍會允許真彩色**，這與大多數開關型變數不同；請取消設定此變數以恢復 256 色限制。預設情況下，當設定了 `$TMUX` 時，Claude Code 會限制為 256 色，因為除非經過設定，否則 tmux 不會傳遞真彩色跳脫序列。請在將 `set -ga terminal-overrides ',*:Tc'` 加入您的 `~/.tmux.conf` 後設定此變數。其他 tmux 設定請參閱[終端機設定](/docs/zh-TW/terminal-config) |

412| `CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE` | 在 Linux 與 WSL 上，設為以逗號分隔的程序種類清單，Claude Code 會將這些種類的程序[排除在工具記憶體上限之外](/docs/zh-TW/tools-reference#memory-limit-on-linux-and-wsl)，例如 `mcp` 或 `lsp`。設為 `none` 可限制所有種類，或設為 `all-new` 僅限制 Bash、PowerShell 與 Monitor 工具命令。無論您列出什麼，Claude Code 都會讓 Bash、PowerShell 與 Monitor 工具命令受上限約束。需要 Claude Code v2.1.246 或更新版本 |415| `CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE` | 在 Linux 與 WSL 上，設為以逗號分隔的程序種類清單，指定 Claude Code [從工具記憶體上限中排除](/docs/zh-TW/tools-reference#memory-limit-on-linux-and-wsl)的程序種類，例如 `mcp` 或 `lsp`。設為 `none` 可限制每一種程序，設為 `all-new` 則只限制 Bash、PowerShell 與 Monitor 工具命令。無論您列出什麼，Claude Code 都會將 Bash、PowerShell 與 Monitor 工具命令保留在上限之內。需要 Claude Code v2.1.246 或更新版本 |

413| `CLAUDE_CODE_TOOL_MEMORY_LIMIT` | 在 Linux 與 WSL 上，設為 `4G` 之類的大小，可[限制 Bash 與 PowerShell 工具命令可使用的記憶體](/docs/zh-TW/tools-reference#memory-limit-on-linux-and-wsl)，在 v2.1.246 或更新版本中也包括 Monitor 工具命令。請以純數字寫入大小，單獨使用表示位元組數，或加上 `K`、`M`、`G` 或 `T` 後綴。設為 `0` 或 `off` 可關閉上限。當 Claude Code 啟動的第一個程序開啟或關閉上限後，變更的值會在您下次啟動 `claude` 時生效。需要 Claude Code v2.1.233 或更新版本 |416| `CLAUDE_CODE_TOOL_MEMORY_LIMIT` | 在 Linux 與 WSL 上，設為像 `4G` 這樣的大小，可[限制 Bash 與 PowerShell 工具命令可使用的記憶體](/docs/zh-TW/tools-reference#memory-limit-on-linux-and-wsl)，在 v2.1.246 或更新版本中也包括 Monitor 工具命令。請以純數字撰寫大小，單獨表示位元組數，或加上 `K`、`M`、`G` 或 `T` 後綴。設為 `0` 或 `off` 可關閉上限。一旦 Claude Code 啟動的第一個程序已開啟或關閉上限，變更後的值會在您下次啟動 `claude` 時生效。需要 Claude Code v2.1.233 或更新版本 |

414| `CLAUDE_CODE_TRANSCRIPT_LOCAL_GC` | 設為 `1` 可限制長時間 `-p` 或 Agent SDK 工作階段之[逐字稿檔案](/docs/zh-TW/sessions#where-transcripts-are-stored)的成長大小。每次壓縮之後，一旦檔案大於 5 MB，Claude Code 就會移除該次壓縮之前的歷史記錄。無論檔案是否經過修剪，恢復工作階段都會還原相同的對話。請在您啟動 Claude Code 的環境中設定，因為設定中的 `env` 區塊無法開啟它。需要 Claude Code v2.1.287 或更新版本 |417| `CLAUDE_CODE_TRANSCRIPT_LOCAL_GC` | 設為 `1` 可限制長時間 `-p` 或 Agent SDK 工作階段的[逐字稿檔案](/docs/zh-TW/sessions#where-transcripts-are-stored)成長大小。每次壓縮後，一旦檔案大於 5 MB，Claude Code 就會移除該次壓縮之前的歷史記錄。無論檔案是否經過修剪，繼續工作階段都會還原相同的對話。請在您啟動 Claude Code 的環境中設定，因為設定的 `env` 區塊無法開啟此變數。需要 Claude Code v2.1.287 或更新版本 |

415| `CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS` | Claude Code 取消其轉送至遠端用戶端（例如 [Remote Control](/docs/zh-TW/remote-control) 或 SDK 主機）之對話框，或[被擱置之跨工作階段訊息](/docs/zh-TW/cross-session-messaging#control-inbound-messages)的核准對話框之前的期限（毫秒）；權限提示與 `AskUserQuestion` 問題使用各自的流程，不受此值管控。在 Claude Code v2.1.236 或更新版本中，它也會限制可能在無人看管下執行之工作階段中，於工作階段中途出現的 [Fable 用量點數同意提示](/docs/zh-TW/model-config#fable-and-usage-credits)。[控制傳入訊息](/docs/zh-TW/cross-session-messaging#control-inbound-messages)與[非互動工作階段](/docs/zh-TW/cross-session-messaging#non-interactive-sessions)說明了完整的擱置訊息到期規則，包括期限不適用的情況。覆寫 [`dialogExpiry`](/docs/zh-TW/settings-reference#dialogexpiry) 設定。`0` 或負值會停用期限 |418| `CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS` | Claude Code 取消轉送至遠端用戶端（例如 [Remote Control](/docs/zh-TW/remote-control) 或 SDK 主機）的對話方塊，或[暫留之跨工作階段訊息](/docs/zh-TW/cross-session-messaging#control-inbound-messages)的核准對話方塊之前的期限（毫秒）；權限提示與 `AskUserQuestion` 問題使用各自的流程，不受此變數管轄。在 Claude Code v2.1.236 或更新版本中，它也會限制可能在無人值守情況下執行之工作階段中，於工作階段中途出現的 [Fable 用量點數同意提示](/docs/zh-TW/model-config#fable-and-usage-credits)。[控制傳入訊息](/docs/zh-TW/cross-session-messaging#control-inbound-messages)與[非互動式工作階段](/docs/zh-TW/cross-session-messaging#non-interactive-sessions)涵蓋完整的暫留訊息到期規則，包括期限不適用的情況。覆寫 [`dialogExpiry`](/docs/zh-TW/settings-reference#dialogexpiry) 設定。`0` 或負值會停用期限 |

420| `CLAUDE_CODE_USE_NATIVE_FILE_SEARCH` | 設為 `1` 可使用 Node.js 檔案 API 而非 ripgrep 來探索自訂命令、subagent 與輸出風格。若內建的 ripgrep 二進位檔在您的環境中無法使用或遭封鎖，請設定此變數。不影響 Grep 或檔案搜尋工具 |423| `CLAUDE_CODE_USE_NATIVE_FILE_SEARCH` | 設為 `1` 可使用 Node.js 檔案 API 而非 ripgrep 來探索自訂命令、subagent 與輸出風格。若隨附的 ripgrep 二進位檔在您的環境中無法使用或遭到封鎖，請設定此變數。不影響 Grep 或檔案搜尋工具 |

421| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | 控制 PowerShell 工具。在未安裝 Git Bash 的 Windows 上，此工具會自動啟用；設為 `0` 可停用。在已安裝 Git Bash 的 Windows 上，此工具對 claude.ai 與 Console 帳戶預設為開啟；設為 `1` 可在 Amazon Bedrock、Google Cloud's Agent Platform 與 Microsoft Foundry 工作階段中啟用，或設為 `0` 將其關閉。在 Linux、macOS 與 WSL 上，設為 `1` 可啟用，這需要您的 `PATH` 中有 `pwsh`。在 Windows 上啟用時，Claude 可原生執行 PowerShell 命令，而不必透過 Git Bash 路由。請參閱 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool) |424| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | 控制 PowerShell 工具。在未安裝 Git Bash 的 Windows 上，此工具會自動啟用；設為 `0` 可將其停用。在已安裝 Git Bash 的 Windows 上，claude.ai 與 Console 帳戶預設會開啟此工具；設為 `1` 可在 Amazon Bedrock、Google Cloud's Agent Platform 與 Microsoft Foundry 工作階段中啟用，或設為 `0` 將其關閉。在 Linux、macOS 與 WSL 上，設為 `1` 即可啟用，但需要 `PATH` 中有 `pwsh`。在 Windows 上啟用後，Claude 可以原生執行 PowerShell 命令，而不需透過 Git Bash 轉送。請參閱 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool) |

423| `CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS` | 設定 [WebFetch](/docs/zh-TW/tools-reference#webfetch-tool-behavior) 將每個已擷取 URL 的回應保留在快取中的毫秒數。預設值為 `900000`，即 15 分鐘。僅接受純數字；`0`、小數或任何其他寫法都會維持預設值。Claude Code 每次啟動時只讀取一次此值，因此在設定的 `env` 區塊中所做的變更，會在您下次啟動 `claude` 時生效。需要 Claude Code v2.1.233 或更新版本 |426| `CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS` | 設定 [WebFetch](/docs/zh-TW/tools-reference#webfetch-tool-behavior) 將每個已擷取 URL 的回應保留在快取中的毫秒數。預設值為 `900000`，即 15 分鐘。僅接受純數字；`0`、小數或任何其他寫法都會維持預設值。Claude Code 每次啟動只讀取此值一次，因此在設定的 `env` 區塊中所做的變更，會在下次啟動 `claude` 時套用。需要 Claude Code v2.1.233 或更新版本 |

424| `CLAUDE_CODE_WEBFETCH_DEADLINE_MS` | [WebFetch](/docs/zh-TW/tools-reference#webfetch-tool-behavior) 等待頁面下載（包括其所追蹤的任何重新導向）的時間上限，以毫秒為單位。屆時仍未完成的下載會以期限錯誤失敗。預設值為 `300000`，即五分鐘。設定為 `0` 可移除此限制。僅接受純數字；小數或任何其他寫法都會維持預設值。需要 Claude Code v2.1.268 或更新版本 |427| `CLAUDE_CODE_WEBFETCH_DEADLINE_MS` | [WebFetch](/docs/zh-TW/tools-reference#webfetch-tool-behavior) 等待頁面下載完成的時間上限（毫秒），包含其所跟隨的任何重新導向。屆時仍未完成的下載會以截止期限錯誤失敗。預設值為 `300000`，即五分鐘。設為 `0` 可移除此限制。僅接受純數字；小數或任何其他寫法都會維持預設值。需要 Claude Code v2.1.268 或更新版本 |

425| `CLAUDE_CODE_WORKER_CHECKIN_SCHEDULE` | 當 `CLAUDE_AUTO_BACKGROUND_TASKS` 設定為 `1` 時，Claude Code 在每次提醒 Claude 檢查仍在執行中的[背景 subagent](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background) 之前等待的時間。接受一個或多個以逗號分隔、介於 `1` 到 `86400` 之間的整數秒等待時間，例如 `600` 或 `600,1800,3600`。每個值都是下一次提醒之前的等待時間，最後一個值會重複使用。僅接受純數字；任何其他值或寫法都會視為未設定。未設定時不會有任何提醒。需要 Claude Code v2.1.283 或更新版本 |428| `CLAUDE_CODE_WORKER_CHECKIN_SCHEDULE` | 當 `CLAUDE_AUTO_BACKGROUND_TASKS` 設為 `1` 時，Claude Code 每次提醒 Claude 檢查仍在執行中的[背景 subagent](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background) 之前要等待多久。接受一個或多個以逗號分隔、介於 `1` 到 `86400` 之間的整數秒數等待時間，例如 `600` 或 `600,1800,3600`。每個值代表下一次提醒前的等待時間，最後一個值會重複使用。僅接受純數字；任何其他值或寫法都會視為未設定。未設定時不會有任何提醒。需要 Claude Code v2.1.283 或更新版本 |

426| `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` | 單次[工作流程](/docs/zh-TW/workflows)執行同時執行的 agent 數量，範圍從 `1` 到 `256`。預設情況下，一次執行最多同時執行 16 個 agent，當 Claude Code 可用的 CPU 較少時則會更少；排入佇列的 `agent()` 呼叫會等待空閒的位置。每個執行中 agent 的逐字稿都會保留在 Claude Code 的記憶體中，因此較高的值會提高記憶體使用量。僅接受純數字；超出範圍的值和其他寫法都會維持預設值。需要 Claude Code v2.1.269 或更新版本 |429| `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` | 單次[工作流程](/docs/zh-TW/workflows)執行同時執行的 agent 數量，範圍從 `1` 到 `256`。預設情況下，一次執行最多同時執行 16 個 agent，當 Claude Code 可用的 CPU 較少時則更少；排隊中的 `agent()` 呼叫會等待空出的位置。每個執行中 agent 的逐字稿都會保留在 Claude Code 的記憶體中，因此較高的值會增加記憶體用量。僅接受純數字；超出範圍的值與其他寫法都會維持預設值。需要 Claude Code v2.1.269 或更新版本 |

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

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

429| `CLAUDE_DISABLE_ADOPT` | 設定為 `1`，在您按下 `←` 或使用 [`/background`](/docs/zh-TW/agent-view#from-inside-a-session) 將工作階段移至背景時，停止正在進行的背景工作，而不是將其延續。Claude Code 會在移至背景之前要求您確認，然後停止原本會延續的任務。需要 Claude Code v2.1.195 或更新版本 |432| `CLAUDE_DISABLE_ADOPT` | 設為 `1` 可在您按下 `←` 或使用 [`/background`](/docs/zh-TW/agent-view#from-inside-a-session) 將工作階段移至背景時，停止進行中的背景工作，而不是將其延續下去。Claude Code 會在移至背景前要求您確認，然後停止原本會延續下去的任務。需要 Claude Code v2.1.195 或更新版本 |

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

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

432| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | 設定為 `1` 可在 Amazon Bedrock `vnd.amazon.eventstream` 回應上啟用位元組層級的串流閒置監控程式，這也會在 Bedrock 串流請求上啟用[第一個位元組期限](/docs/zh-TW/network-config#streaming-idle-watchdogs)。預設為關閉。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 設定逾時 |435| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | 設為 `1` 可在 Amazon Bedrock `vnd.amazon.eventstream` 回應上啟用位元組層級的串流閒置監視器，這也會在 Bedrock 串流請求上啟用[第一位元組截止期限](/docs/zh-TW/network-config#streaming-idle-watchdogs)。預設為關閉。請使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 設定逾時 |

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

434| `CLAUDE_ENV_FILE` | shell 指令碼的路徑，Claude Code 會在每個 Bash 命令之前於同一個 shell 程序中執行其內容，因此檔案中的 export 對該命令可見。用於在命令之間保留 virtualenv 或 conda 的啟用狀態。也會由 [SessionStart](/docs/zh-TW/hooks#persist-environment-variables)、[Setup](/docs/zh-TW/hooks#setup)、[CwdChanged](/docs/zh-TW/hooks#cwdchanged) 和 [FileChanged](/docs/zh-TW/hooks#filechanged) hook 動態填入 |437| `CLAUDE_ENV_FILE` | shell 指令碼的路徑，Claude Code 會在每個 Bash 命令之前於同一個 shell 程序中執行其內容，因此檔案中的 export 對該命令可見。可用於在各命令之間保留 virtualenv 或 conda 的啟用狀態。也會由 [SessionStart](/docs/zh-TW/hooks#persist-environment-variables)、[Setup](/docs/zh-TW/hooks#setup)、[CwdChanged](/docs/zh-TW/hooks#cwdchanged) 與 [FileChanged](/docs/zh-TW/hooks#filechanged) hook 動態填入 |

435| `CLAUDE_JOB_DIR` | 由 Claude Code 在每個[背景工作階段](/docs/zh-TW/agent-view)中設定為該工作階段的 `~/.claude/jobs/<id>` 目錄。工作階段執行的 shell 命令會繼承此變數。請將暫存檔案寫入 [`$CLAUDE_JOB_DIR/tmp`](/docs/zh-TW/agent-view#where-state-is-stored)。Claude 在該處的 `Write` 和 `Edit` 呼叫不會要求權限，且該目錄會在工作階段刪除時一併移除 |438| `CLAUDE_JOB_DIR` | 由 Claude Code 在每個[背景工作階段](/docs/zh-TW/agent-view)中設定為該工作階段的 `~/.claude/jobs/<id>` 目錄。該工作階段執行的 shell 命令會繼承此變數。請將暫存檔案寫入 [`$CLAUDE_JOB_DIR/tmp`](/docs/zh-TW/agent-view#where-state-is-stored)。Claude 在該處的 `Write` 與 `Edit` 呼叫不會要求權限，且刪除工作階段時會移除此目錄 |

436| `CLAUDE_PID` | Claude Code 會在其產生的子程序中將此變數設定為自己的程序 ID：包括 Bash 和 PowerShell 工具命令以及 hook 命令。在 Linux 上，Bash 工具的 shell 整合會使用它來拒絕會比對到 Claude Code 程序本身的 `pkill` 模式；請參閱[錯誤參考](/docs/zh-TW/errors#pkill-pattern-matches-the-claude-code-process)。可從您自己的指令碼讀取此變數，以刻意識別父 Claude Code 程序或向其傳送訊號。需要 Claude Code v2.1.214 或更新版本 |439| `CLAUDE_PID` | Claude Code 會在其產生的子程序中將此變數設定為自己的程序 ID：包括 Bash 與 PowerShell 工具命令以及 hook 命令。在 Linux 上，Bash 工具的 shell 整合會使用它來拒絕會比對到 Claude Code 程序本身的 `pkill` 模式；請參閱[錯誤參考](/docs/zh-TW/errors#pkill-pattern-matches-the-claude-code-process)。您可以在自己的指令碼中讀取它，以刻意識別上層 Claude Code 程序或向其傳送訊號。需要 Claude Code v2.1.214 或更新版本 |

437| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | 未提供明確名稱時，自動產生的 [Remote Control](/docs/zh-TW/remote-control) 工作階段名稱前綴。預設為您電腦的主機名稱，產生如 `myhost-graceful-unicorn` 的名稱。`--remote-control-session-name-prefix` CLI 旗標可為單次呼叫設定相同的值 |440| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | 未提供明確名稱時，自動產生的 [Remote Control](/docs/zh-TW/remote-control) 工作階段名稱的前綴。預設為您電腦的主機名稱，產生如 `myhost-graceful-unicorn` 的名稱。`--remote-control-session-name-prefix` CLI 旗標可為單次呼叫設定相同的值 |

438| `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` | 在執行[第一個位元組期限](/docs/zh-TW/network-config#streaming-idle-watchdogs)的連線上，串流請求第一個回應位元組的期限，以毫秒為單位。關於 Claude Code 如何限制此值、為大型請求內文增加的額外時間，以及在您未設定時如何選擇期限，請參閱 [No response from API](/docs/zh-TW/errors#no-response-from-api)。需要 Claude Code v2.1.242 或更新版本 |441| `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` | 在執行[第一位元組截止期限](/docs/zh-TW/network-config#streaming-idle-watchdogs)的連線上，串流請求第一個回應位元組的截止期限（毫秒）。關於 Claude Code 如何限制此值、針對大型請求主體額外增加的時間，以及未設定此變數時如何選擇截止期限，請參閱 [No response from API](/docs/zh-TW/errors#no-response-from-api)。需要 Claude Code v2.1.242 或更新版本 |

439| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 事件層級和位元組層級串流閒置監控程式關閉停滯連線之前的逾時時間，以毫秒為單位。當您明確設定此變數時，最小值為 `300000`（5 分鐘）；較低的值會被靜默調整為最小值，以容納延伸思考的暫停和代理伺服器緩衝，且位元組層級監控程式會將此值上限設為 30 分鐘。對於位元組層級監控程式，`CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` 優先於此變數。關於各監控程式未設定時的預設值，請參閱[串流閒置監控程式](/docs/zh-TW/network-config#streaming-idle-watchdogs) |442| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 事件層級與位元組層級的串流閒置監視器關閉停滯連線前的逾時時間（毫秒）。明確設定此變數時，最小值為 `300000`（5 分鐘）；較低的值會被自動調整，以容納延伸思考的停頓與代理伺服器緩衝，且位元組層級監視器會將此值上限設為 30 分鐘。對於位元組層級監視器，`CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` 優先於此變數。關於各監視器在未設定時的預設值，請參閱[串流閒置監視器](/docs/zh-TW/network-config#streaming-idle-watchdogs) |

440| `CLAUDE_SUBAGENT_BG_SHELL_MAX_MS` | 已在 v2.1.260 中移除，現在不會產生任何作用。先前用於限制 [subagent](/docs/zh-TW/sub-agents) 啟動的[背景 shell 命令](/docs/zh-TW/interactive-mode#background-bash-commands)可執行的時間，以毫秒為單位，預設值為 60 分鐘。請參閱[背景命令生命週期規則](/docs/zh-TW/tools-reference#background-commands) |443| `CLAUDE_SUBAGENT_BG_SHELL_MAX_MS` | 已於 v2.1.260 移除，現在不起任何作用。先前用於限制由 [subagent](/docs/zh-TW/sub-agents) 啟動的[背景 shell 命令](/docs/zh-TW/interactive-mode#background-bash-commands)可執行的時間（毫秒），預設為 60 分鐘。請參閱[背景命令生命週期規則](/docs/zh-TW/tools-reference#background-commands) |

441| `DEBUG` | 設定為 `1` 可啟用偵錯模式，等同於使用 [`--debug`](/docs/zh-TW/cli-reference#cli-flags) 啟動。偵錯日誌會寫入 `~/.claude/debug/<session-id>.txt`，或寫入由 `CLAUDE_CODE_DEBUG_LOGS_DIR` 設定的路徑。只有真值 `1`、`true`、`yes` 和 `on` 會啟用偵錯模式，因此為其他工具設定的命名空間模式（例如 `DEBUG=express:*`）不會觸發它 |444| `DEBUG` | 設為 `1` 可啟用除錯模式，等同於使用 [`--debug`](/docs/zh-TW/cli-reference#cli-flags) 啟動。除錯日誌會寫入 `~/.claude/debug/<session-id>.txt`，或寫入 `CLAUDE_CODE_DEBUG_LOGS_DIR` 所設定的路徑。只有真值 `1`、`true`、`yes` 與 `on` 會啟用除錯模式，因此為其他工具設定的命名空間模式（例如 `DEBUG=express:*`）不會觸發它 |

443| `DISABLE_AUTO_COMPACT` | 設定為 `1` 可停用接近上下文限制時的自動壓縮。手動 `/compact` 命令仍然可用。當您想明確控制何時進行壓縮時使用。覆寫 [`autoCompactEnabled`](/docs/zh-TW/settings-reference#autocompactenabled) 設定 |446| `DISABLE_AUTO_COMPACT` | 設為 `1` 可停用接近上下文上限時的自動壓縮。手動 `/compact` 命令仍可使用。適合想要明確控制壓縮時機的情況。會覆寫 [`autoCompactEnabled`](/docs/zh-TW/settings-reference#autocompactenabled) 設定 |

446| `DISABLE_DOCTOR_COMMAND` | 設定為 `1` 可隱藏 [`/doctor`](/docs/zh-TW/commands#all-commands) 設定檢查 skill 及其 `/checkup` 別名。適用於使用者不應從工作階段執行設定診斷的受管部署。不影響 `claude doctor` 終端機命令。在 v2.1.205 之前，此變數會隱藏 `/doctor` 診斷畫面命令 |449| `DISABLE_DOCTOR_COMMAND` | 設為 `1` 可隱藏 [`/doctor`](/docs/zh-TW/commands#all-commands) 設定檢查 skill 及其 `/checkup` 別名。適用於不希望使用者在工作階段中執行設定診斷的受管部署。不影響 `claude doctor` 終端機命令。在 v2.1.205 之前，此變數會隱藏 `/doctor` 診斷畫面命令 |

449| `DISABLE_FEEDBACK_COMMAND` | 設定為 `1` 可停用 `/feedback` 命令和 [Claude 草擬的意見回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior)。也會停用透過相同途徑回報的 `/bug` 和 `/share`；在 v2.1.212 之前，它們是 `/feedback` 的別名，因此該命令在所有名稱下都會被停用。也接受較舊的名稱 `DISABLE_BUG_COMMAND` |452| `DISABLE_FEEDBACK_COMMAND` | 設為 `1` 可停用 `/feedback` 命令與 [Claude 草擬的意見回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior)。也會停用透過相同途徑回報的 `/bug` 與 `/share`；在 v2.1.212 之前，它們是 `/feedback` 的別名，因此該命令在所有名稱下都會被停用。也接受舊名稱 `DISABLE_BUG_COMMAND` |

450| `DISABLE_GROWTHBOOK` | 設定為 `1` 或 `true` 可停用 GrowthBook 功能旗標擷取，並對每個旗標使用程式碼預設值。這會使 [Remote Control](/docs/zh-TW/remote-control#requirements) 和其他[需要功能旗標擷取的功能](#features-that-need-feature-flag-fetching)無法使用。將其設定為 `0` 或 `false` 會保持擷取開啟。除非同時設定 `DISABLE_TELEMETRY`，否則遙測事件記錄會保持開啟 |453| `DISABLE_GROWTHBOOK` | 設為 `1` 或 `true` 可停用 GrowthBook 功能旗標擷取，並對每個旗標使用程式碼中的預設值。這會使 [Remote Control](/docs/zh-TW/remote-control#requirements) 以及其他[需要擷取功能旗標的功能](#features-that-need-feature-flag-fetching)無法使用。設為 `0` 或 `false` 會維持擷取開啟。除非同時設定 `DISABLE_TELEMETRY`，否則遙測事件記錄仍會保持開啟 |

452| `DISABLE_INSTALL_GITHUB_APP_COMMAND` | 設定為 `1` 可隱藏 `/install-github-app` 命令。使用第三方供應商（Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry）時已預設隱藏 |455| `DISABLE_INSTALL_GITHUB_APP_COMMAND` | 設為 `1` 可隱藏 `/install-github-app` 命令。使用第三方供應商（Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry）時已預設隱藏 |

453| `DISABLE_INTERLEAVED_THINKING` | 設定為 `1` 可避免傳送 interleaved-thinking beta 標頭。適用於您的 LLM 閘道或供應商不支援[交錯思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking)的情況 |456| `DISABLE_INTERLEAVED_THINKING` | 設為 `1` 可避免傳送 interleaved-thinking beta 標頭。適用於您的 LLM 閘道或供應商不支援[交錯思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking)的情況 |

458| `DISABLE_PROMPT_CACHING_HAIKU` | 設定為 `1` 可對[預設 Haiku 模型](/docs/zh-TW/prompt-caching#disable-prompt-caching)停用提示快取，無論其在何處執行 |461| `DISABLE_PROMPT_CACHING_HAIKU` | 設為 `1` 可對[預設 Haiku 模型](/docs/zh-TW/prompt-caching#disable-prompt-caching)停用提示快取，無論其在何處執行 |

461| `DISABLE_TELEMETRY` | 設定為任何非空值（例如 `1`）即可選擇不參與遙測。與大多數開關變數不同，**將其設定為 `0` 或 `false` 仍會選擇不參與**；請取消設定此變數以重新開啟遙測。遙測事件不包含使用者資料，例如程式碼、檔案路徑或 Bash 命令。也會停用[功能旗標擷取](#features-that-need-feature-flag-fetching)。請參閱[為您的組織關閉遙測](/docs/zh-TW/managed-settings#turn-telemetry-off-for-your-organization) |464| `DISABLE_TELEMETRY` | 設為任何非空值（例如 `1`）可選擇不參與遙測。**設為 `0` 或 `false` 仍會選擇不參與**，這與大多數開關變數不同；取消設定此變數才能重新開啟遙測。遙測事件不包含程式碼、檔案路徑或 Bash 命令等使用者資料。也會停用[功能旗標擷取](#features-that-need-feature-flag-fetching)。請參閱[為您的組織關閉遙測](/docs/zh-TW/managed-settings#turn-telemetry-off-for-your-organization) |

462| `DISABLE_UPDATES` | 設定為 `1` 可封鎖所有更新，包括手動執行的 `claude update` 和 `claude install`。比 `DISABLE_AUTOUPDATER` 更嚴格。適用於透過您自己的管道發佈 Claude Code 且使用者不應自行更新的情況 |465| `DISABLE_UPDATES` | 設為 `1` 可封鎖所有更新，包括手動執行 `claude update` 與 `claude install`。比 `DISABLE_AUTOUPDATER` 更嚴格。適用於透過您自己的管道發布 Claude Code，且使用者不應自行更新的情況 |

464| `DO_NOT_TRACK` | 設定為 `1` 可選擇不參與遙測，效果與 `DISABLE_TELEMETRY` 相同，包括對[功能旗標擷取](#features-that-need-feature-flag-fetching)的影響。Claude Code 會將此變數視為標準布林值讀取，因此 `0` 會保持遙測開啟，並遵循許多開發者 CLI 所認可的跨工具慣例 |467| `DO_NOT_TRACK` | 設為 `1` 可選擇不參與遙測，效果與 `DISABLE_TELEMETRY` 相同，包括對[功能旗標擷取](#features-that-need-feature-flag-fetching)的影響。Claude Code 會將此變數當作標準布林值讀取，因此 `0` 會維持遙測開啟，並將其視為許多開發者 CLI 共同認可的跨工具慣例來遵循 |

465| `ENABLE_BETA_TRACING_DETAILED` | 設定為 `1`，並將 `BETA_TRACING_ENDPOINT` 設定為您的 OTLP/HTTP 收集器端點，即可開啟[詳細 beta 追蹤](/docs/zh-TW/monitoring-usage#traces-beta)，這會新增帶有內容的 span 屬性和 `claude_code.hook` span。互動式 CLI 工作階段還需要您的組織已列入此 beta 的允許清單。這兩個變數在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中都會被忽略 |468| `ENABLE_BETA_TRACING_DETAILED` | 設為 `1`，並將 `BETA_TRACING_ENDPOINT` 設為您的 OTLP/HTTP 收集器端點，即可開啟[詳細 beta 追蹤](/docs/zh-TW/monitoring-usage#traces-beta)，這會加入包含內容的 span 屬性以及 `claude_code.hook` span。互動式 CLI 工作階段還需要您的組織已列入此 beta 的允許清單。這兩個變數在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中都會被忽略 |

466| `ENABLE_CLAUDEAI_MCP_SERVERS` | 設定為 `false` 可讓 Claude Code 停止擷取 [claude.ai MCP 伺服器](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai)。對已登入的使用者預設啟用。若要按專案或按組織停用，請改為在設定中設定 [`disableClaudeAiConnectors`](/docs/zh-TW/settings-reference#disableclaudeaiconnectors) |469| `ENABLE_CLAUDEAI_MCP_SERVERS` | 設為 `false` 可讓 Claude Code 停止擷取 [claude.ai MCP 伺服器](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai)。對已登入的使用者預設為啟用。若要依專案或依組織停用，請改為在設定中設定 [`disableClaudeAiConnectors`](/docs/zh-TW/settings-reference#disableclaudeaiconnectors) |

467| `ENABLE_PROMPT_CACHING_1H` | 設定為 `1` 可請求 1 小時的[提示快取 TTL](/docs/zh-TW/prompt-caching#cache-lifetime)，而非預設的 5 分鐘。適用於 API 金鑰、[Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai)、[Microsoft Foundry](/docs/zh-TW/microsoft-foundry) 和 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 使用者。在內含用量範圍內的訂閱使用者會在[主要對話](/docs/zh-TW/prompt-caching#which-ttl-each-request-gets)上自動獲得 1 小時 TTL。使用[用量點數](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)的訂閱使用者可設定此變數以保留 1 小時 TTL。1 小時快取寫入會以較高費率計費。若要改為依請求類別選擇 TTL，請使用 `CLAUDE_CODE_PROMPT_CACHE_TTL` 和 `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`，兩者都優先於此變數 |470| `ENABLE_PROMPT_CACHING_1H` | 設為 `1` 可請求 1 小時的[提示快取 TTL](/docs/zh-TW/prompt-caching#cache-lifetime)，而非預設的 5 分鐘。適用於 API 金鑰、[Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai)、[Microsoft Foundry](/docs/zh-TW/microsoft-foundry) 與 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 使用者。在內含用量範圍內的訂閱使用者，會在[主要對話](/docs/zh-TW/prompt-caching#which-ttl-each-request-gets)上自動獲得 1 小時 TTL。使用[用量點數](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)的訂閱使用者可以設定此變數以保留 1 小時 TTL。1 小時快取寫入會以較高費率計費。若要改為依請求類別選擇 TTL，請使用 `CLAUDE_CODE_PROMPT_CACHE_TTL` 與 `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`，這兩者優先於此變數 |

469| `ENABLE_TOOL_SEARCH` | 控制 [MCP Tool Search](/docs/zh-TW/mcp#scale-with-mcp-tool-search)。未設定時，Claude Code 預設會延遲載入所有 MCP 工具。但在早於 Claude 4.5 世代的 Google Cloud's Agent Platform 模型上、在託管於 Azure 的 Microsoft Foundry 部署上，以及當 `ANTHROPIC_BASE_URL` 指向非第一方主機時，仍會預先載入它們。`true` 一律延遲載入並傳送 beta 標頭，但上述相同的 Agent Platform 模型和 Microsoft Foundry 部署除外；在不支援 `tool_reference` 的代理伺服器上，請求會失敗。`auto` 會在工具定義可容納於上下文的 10% 以內時預先載入。`auto:N` 可設定自訂門檻，例如 `auto:5` 代表 5%。`false` 會預先載入所有工具。設定 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` 時，您自行設定的值會被忽略。在 v2.1.221 之前，除非您將此變數設定為 `true`，否則 Claude Code 會對 Google Cloud's Agent Platform 上的所有模型停用工具搜尋 |472| `ENABLE_TOOL_SEARCH` | 控制 [MCP Tool Search](/docs/zh-TW/mcp#scale-with-mcp-tool-search)。未設定時，Claude Code 預設會延後載入所有 MCP 工具。但在早於 Claude 4.5 世代的 Google Cloud's Agent Platform 模型、託管於 Azure 的 Microsoft Foundry 部署，以及 `ANTHROPIC_BASE_URL` 指向非第一方主機時，仍會預先載入這些工具。`true` 一律延後載入並傳送 beta 標頭，但上述相同的 Agent Platform 模型與 Microsoft Foundry 部署除外；在不支援 `tool_reference` 的代理伺服器上，請求會失敗。`auto` 會在工具定義可容納於上下文的 10% 以內時預先載入。`auto:N` 可設定自訂閾值，例如 `auto:5` 代表 5%。`false` 會預先載入所有工具。設定 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` 時，您自行設定的值會被忽略。在 v2.1.221 之前，除非您將此變數設為 `true`，否則 Claude Code 會對 Google Cloud's Agent Platform 上的所有模型停用工具搜尋 |

470| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | 設定為任何非空值（例如 `1`），可讓 Claude Code 在未設定備援模型時，對每個模型遇到重複的過載錯誤時停止重試。與大多數開關變數不同，**將其設定為 `0` 或 `false` 仍會啟用此功能**；請取消設定此變數以還原預設的重試行為。若未設定，當您使用 API 金鑰或[第三方供應商](/docs/zh-TW/third-party-integrations)而非 Claude 訂閱進行身分驗證時，Claude Code 只會對其識別為 Opus、Fable 或 Mythos 的模型以這種方式停止重試。在 Claude Code v2.1.160 或更新版本中，Claude Code 會在任何主要模型遇到重複的過載錯誤時切換至您設定的[備援模型鏈](/docs/zh-TW/model-config#fallback-model-chains)，因此此變數不會影響切換至備援模型 |473| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | 設為任何非空值（例如 `1`），可在未設定備援模型時，讓 Claude Code 對所有模型在重複發生過載錯誤時停止重試。**設為 `0` 或 `false` 仍會啟用此行為**，這與大多數開關變數不同；取消設定此變數才能恢復預設的重試行為。未設定時，只有當您使用 API 金鑰或[第三方供應商](/docs/zh-TW/third-party-integrations)而非 Claude 訂閱進行身分驗證時，Claude Code 才會對其識別為 Opus、Fable 或 Mythos 的模型以此方式停止重試。在 Claude Code v2.1.160 或更新版本中，Claude Code 會在任何主要模型重複發生過載錯誤時切換至您設定的[備援模型鏈](/docs/zh-TW/model-config#fallback-model-chains)，因此此變數不影響切換至備援模型 |

472| `FORCE_HYPERLINK` | 當您的終端機支援可點擊的 OSC 8 超連結但未被自動偵測到時，設定為 `1` 可啟用它們，設定為 `0` 則可停用。未設定時，Claude Code 僅在偵測到終端機支援時啟用超連結。Claude Code 會將此值解析為數字而非布林值，因此 `false`、`no` 或 `off` 等值會啟用超連結，而非停用。頁尾的 [PR 或合併請求徽章](/docs/zh-TW/interactive-mode#pr-review-status)即使在 Claude Code 無法偵測終端機支援時（例如透過 SSH）也會以超連結呈現。設定 `0` 可將徽章以純文字呈現 |475| `FORCE_HYPERLINK` | 設為 `1` 可在您的終端機支援但未被自動偵測到時，啟用可點擊的 OSC 8 超連結，或設為 `0` 將其停用。未設定時，Claude Code 只有在偵測到終端機支援時才會啟用超連結。Claude Code 會將此值解析為數字而非布林值，因此 `false`、`no` 或 `off` 等值會啟用超連結，而不是停用。即使 Claude Code 無法偵測到終端機支援（例如透過 SSH 時），頁尾的 [PR 或合併請求徽章](/docs/zh-TW/interactive-mode#pr-review-status)仍會顯示為超連結。設為 `0` 可將徽章顯示為純文字 |

473| `FORCE_PROMPT_CACHING_5M` | 設定為 `1` 可強制使用 5 分鐘的提示快取 TTL，即使原本會套用 1 小時 TTL。覆寫 `CLAUDE_CODE_PROMPT_CACHE_TTL`、`CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`、`ENABLE_PROMPT_CACHING_1H`，以及 `promptCacheTtl` 和 `subagentPromptCacheTtl` 設定 |476| `FORCE_PROMPT_CACHING_5M` | 設為 `1` 可強制使用 5 分鐘的提示快取 TTL，即使原本會套用 1 小時 TTL。會覆寫 `CLAUDE_CODE_PROMPT_CACHE_TTL`、`CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`、`ENABLE_PROMPT_CACHING_1H`，以及 `promptCacheTtl` 與 `subagentPromptCacheTtl` 設定 |

476| `IS_DEMO` | 設定為任何非空值（例如 `1`）可啟用示範模式：在標頭和 `/status` 輸出中隱藏您的電子郵件和組織名稱，並略過初始設定流程。與大多數開關變數不同，**將其設定為 `0` 或 `false` 仍會啟用示範模式**；請取消設定此變數以將其關閉。適用於直播或錄製工作階段時 |479| `IS_DEMO` | 設為任何非空值（例如 `1`）可啟用示範模式：在標頭與 `/status` 輸出中隱藏您的電子郵件與組織名稱，並略過初始設定流程。**設為 `0` 或 `false` 仍會啟用示範模式**，這與大多數開關變數不同；取消設定此變數才能將其關閉。適用於直播或錄製工作階段的情況 |

477| `MAX_MCP_OUTPUT_TOKENS` | MCP 工具回應中允許的最大 token 數（預設值：25000）。當輸出超過 10,000 個 token 時，Claude Code 會顯示警告。宣告 [`anthropic/maxResultSizeChars`](/docs/zh-TW/mcp#raise-the-limit-for-a-specific-tool) 的工具會改用該字元限制處理文字內容，但這些工具的圖片內容仍受此變數限制。來自未具備該註解之工具、長度超過 50,000 個字元的成功文字結果，無論此變數為何都會[儲存至檔案](/docs/zh-TW/mcp#mcp-output-limits-and-warnings) |480| `MAX_MCP_OUTPUT_TOKENS` | MCP 工具回應中允許的最大 token 數（預設值：25000）。當輸出超過 10,000 個 token 時，Claude Code 會顯示警告。宣告了 [`anthropic/maxResultSizeChars`](/docs/zh-TW/mcp#raise-the-limit-for-a-specific-tool) 的工具會改用該字元上限處理文字內容，但這些工具的圖片內容仍受此變數限制。來自未帶有該註解之工具、長度超過 50,000 個字元的成功文字結果，無論此變數為何，都會[儲存至檔案](/docs/zh-TW/mcp#mcp-output-limits-and-warnings) |

478| `MAX_STRUCTURED_OUTPUT_RETRIES` | 在使用 `-p` 旗標的非互動模式下，當模型回應未通過 [`--json-schema`](/docs/zh-TW/cli-reference#cli-flags) 驗證時，Claude Code 允許的嘗試次數；在這麼多次失敗嘗試仍無有效輸出後，執行即失敗。當[工作流程](/docs/zh-TW/workflows) subagent 的結構化輸出未通過驗證時，也適用相同的上限。預設值為 5，即一次初次嘗試加上四次重試 |481| `MAX_STRUCTURED_OUTPUT_RETRIES` | 在使用 `-p` 旗標的非互動模式下，當模型回應未通過 [`--json-schema`](/docs/zh-TW/cli-reference#cli-flags) 驗證時，Claude Code 允許的嘗試次數；在達到該次數的失敗嘗試且沒有有效輸出後，執行即告失敗。當[工作流程](/docs/zh-TW/workflows) subagent 的結構化輸出未通過驗證時，也套用相同的上限。預設為 5，即第一次嘗試加上四次重試 |

479| `MAX_THINKING_TOKENS` | [延伸思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)的固定 token 預算。Claude Code 會將其上限設為比請求的最大輸出 token 數少一個 token，且絕不低於 1,024。關於該限制如何設定，請參閱 `CLAUDE_CODE_MAX_OUTPUT_TOKENS`。未設定且已啟用思考時，具有[自適應推理](/docs/zh-TW/model-config#adjust-effort-level)的模型會自行選擇思考深度，其他模型則使用上限。設定為 `0` 可在 Anthropic API 上停用思考，但 Opus 5.5、Sonnet 5.5 和 Fable 模型除外，這些模型無法關閉思考。在[第三方供應商](/docs/zh-TW/third-party-integrations)上，`0` 則會改為省略 `thinking` 參數。在 Anthropic API 上關閉思考時，對於 Claude Code 已知[不接受該組合](/docs/zh-TW/errors#effort-isnt-available-with-thinking-turned-off)的模型（例如 Opus 5），Claude Code 會傳送 effort `high` 而非更高的等級。對於正值，Claude Code 在自適應推理模型上會忽略數字本身，除非 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 關閉了自適應推理 |482| `MAX_THINKING_TOKENS` | [延伸思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)的固定 token 預算。Claude Code 會將其上限設為比請求的最大輸出 token 數少一個 token，且永遠不低於 1,024。關於該上限的設定方式，請參閱 `CLAUDE_CODE_MAX_OUTPUT_TOKENS`。未設定且已啟用思考時，具備[自適應推理](/docs/zh-TW/model-config#adjust-effort-level)的模型會自行選擇思考深度，其他模型則使用上限值。設為 `0` 可在 Anthropic API 上停用思考，但 Opus 5.5、Sonnet 5.5、Haiku 5.5 與 Fable 模型除外，這些模型無法關閉思考。在[第三方供應商](/docs/zh-TW/third-party-integrations)上，`0` 則會改為省略 `thinking` 參數。在 Anthropic API 上關閉思考時，對於 Claude Code 已知[不接受該組合](/docs/zh-TW/errors#effort-isnt-available-with-thinking-turned-off)的模型（例如 Opus 5），Claude Code 會傳送 effort `high`，而不是更高的等級。若為正值，Claude Code 在自適應推理模型上會忽略該數字本身，除非 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 關閉了自適應推理 |

480| `MCP_CLIENT_SECRET` | 需要[預先設定憑證](/docs/zh-TW/mcp#use-pre-configured-oauth-credentials)之 MCP 伺服器的 OAuth 用戶端密碼。使用 `--client-secret` 新增伺服器時可避免互動式提示 |483| `MCP_CLIENT_SECRET` | 需要[預先設定憑證](/docs/zh-TW/mcp#use-pre-configured-oauth-credentials)之 MCP 伺服器的 OAuth 用戶端密鑰。可在使用 `--client-secret` 新增伺服器時避免互動式提示 |

481| `MCP_CONNECTION_NONBLOCKING` | 控制啟動時是否在第一次查詢之前等待 MCP 伺服器連線。MCP 啟動預設為非封鎖式：伺服器會在背景連線，其工具會在完成時陸續可用。設定為 `0` 可讓 Claude Code 在第一次查詢之前等待伺服器連線。以 [`alwaysLoad: true`](/docs/zh-TW/mcp#exempt-a-server-from-deferral) 設定的伺服器無論如何仍會讓啟動等待，除非是從[探索快取](/docs/zh-TW/mcp#server-status-detail)提供，因為建構第一個提示詞時其工具必須存在。在未使用 `--input-format stream-json` 的非互動模式（`-p`）下，無論此變數為何，Claude Code 也會在第一個回合之前等待仍在擱置中的伺服器。當您明確傳遞 [`--mcp-config`](/docs/zh-TW/cli-reference#cli-flags) 時，等待會有較長的期限；關於已快取伺服器的例外情況，請參閱該旗標的項目 |484| `MCP_CONNECTION_NONBLOCKING` | 控制啟動時是否在第一次查詢前等待 MCP 伺服器連線。MCP 啟動預設為非阻塞：伺服器會在背景連線，其工具會在完成時陸續可用。設為 `0` 可讓 Claude Code 在第一次查詢前等待伺服器連線。以 [`alwaysLoad: true`](/docs/zh-TW/mcp#exempt-a-server-from-deferral) 設定的伺服器無論如何仍會讓啟動等待，除非是從[探索快取](/docs/zh-TW/mcp#server-status-detail)提供，因為建立第一個提示詞時其工具必須已存在。在未使用 `--input-format stream-json` 的非互動模式（`-p`）下，無論此變數為何，Claude Code 也會在第一個回合前等待仍在擱置中的伺服器。當您明確傳入 [`--mcp-config`](/docs/zh-TW/cli-reference#cli-flags) 時，等待的截止期限會較長；關於已快取伺服器的例外情況，請參閱該旗標的說明 |

482| `MCP_CONNECT_TIMEOUT_MS` | 封鎖式 MCP 啟動在擷取工具清單快照之前，等待連線批次的時間，以毫秒為單位（預設值：5000）。適用於 `MCP_CONNECTION_NONBLOCKING=0` 時，或標記為 [`alwaysLoad: true`](/docs/zh-TW/mcp#exempt-a-server-from-deferral) 的伺服器。在期限時仍在擱置中的伺服器會在背景繼續連線。與 `MCP_TIMEOUT` 不同，後者限制的是單一伺服器的連線嘗試 |485| `MCP_CONNECT_TIMEOUT_MS` | 阻塞式 MCP 啟動在擷取工具清單快照前，等待連線批次的時間（毫秒）（預設值：5000）。適用於 `MCP_CONNECTION_NONBLOCKING=0` 時，或標示為 [`alwaysLoad: true`](/docs/zh-TW/mcp#exempt-a-server-from-deferral) 的伺服器。截止期限到時仍在擱置中的伺服器會繼續在背景連線。與 `MCP_TIMEOUT` 不同，後者限制的是個別伺服器的連線嘗試 |

483| `MCP_DISCOVERY_CACHE` | 開啟或關閉 [MCP 探索快取](/docs/zh-TW/mcp#server-status-detail)。開啟快取時，您先前使用過的遠端 HTTP 或 SSE 伺服器可顯示 [`cached` 狀態](/docs/zh-TW/mcp#server-status-detail)，且 Claude Code 會在其第一次工具呼叫時才連線，而非在啟動時連線。除非逐步推出已為您的帳戶啟用，否則快取預設為關閉。設定為 `1` 可將其開啟，設定為 `0` 則可在逐步推出已啟用時仍保持關閉。在 v2.1.238 之前，快取預設為開啟。`cached` 狀態需要 Claude Code v2.1.221 或更新版本 |486| `MCP_DISCOVERY_CACHE` | 開啟或關閉 [MCP 探索快取](/docs/zh-TW/mcp#server-status-detail)。快取開啟時，您先前使用過的遠端 HTTP 或 SSE 伺服器可能會顯示 [`cached` 狀態](/docs/zh-TW/mcp#server-status-detail)，且 Claude Code 會在其第一次工具呼叫時才連線，而不是在啟動時連線。除非漸進式推出已為您的帳戶啟用，否則快取預設為關閉。設為 `1` 可將其開啟，或設為 `0` 讓其即使在推出已啟用時仍保持關閉。在 v2.1.238 之前，快取預設為開啟。`cached` 狀態需要 Claude Code v2.1.221 或更新版本 |

484| `MCP_DISCOVERY_CACHE_MAX_STALE_S` | [探索快取](/docs/zh-TW/mcp#server-status-detail)項目的最長存留時間，以秒為單位（預設值：14400，即 4 小時）。在啟動時若項目比這個時間更舊，Claude Code 會將其捨棄並在啟動時連線伺服器，如同快取關閉時的行為。Claude Code 會將此值上限設為 7 天。在 v2.1.238 之前，預設值為 86400，即 24 小時，且 Claude Code 不會限制此值 |487| `MCP_DISCOVERY_CACHE_MAX_STALE_S` | [探索快取](/docs/zh-TW/mcp#server-status-detail)項目的最大存留時間（秒）（預設值：14400，即 4 小時）。在項目超過此存留時間的啟動中，Claude Code 會捨棄該項目並在啟動時連線伺服器，就像快取關閉時一樣。Claude Code 會將此值上限設為 7 天。在 v2.1.238 之前，預設值為 86400，即 24 小時，且 Claude Code 不會限制此值 |

485| `MCP_DISCOVERY_CACHE_STRIKES` | 在啟動時若[探索快取](/docs/zh-TW/mcp#server-status-detail)項目比 `MCP_DISCOVERY_CACHE_TTL_S` 更舊，Claude Code 會在背景重新整理它。此變數設定在 Claude Code 捨棄該項目並改為在下次啟動時連線伺服器之前，可以連續失敗多少次重新整理（預設值：1）。如果您的網路連線偶爾會中斷，請提高此值，讓一次失敗的重新整理不會捨棄該項目。需要 Claude Code v2.1.238 或更新版本 |488| `MCP_DISCOVERY_CACHE_STRIKES` | 在[探索快取](/docs/zh-TW/mcp#server-status-detail)項目超過 `MCP_DISCOVERY_CACHE_TTL_S` 的啟動中，Claude Code 會在背景重新整理該項目。此變數設定在 Claude Code 捨棄該項目並改為在下次啟動時連線伺服器之前，可以連續失敗幾次重新整理（預設值：1）。如果您的網路連線偶爾中斷，可以提高此值，讓單次重新整理失敗不會導致項目被捨棄。需要 Claude Code v2.1.238 或更新版本 |

486| `MCP_DISCOVERY_CACHE_TTL_S` | Claude Code 在不重新整理的情況下使用[探索快取](/docs/zh-TW/mcp#server-status-detail)項目的秒數（預設值：900）。在啟動時若項目比這個時間更舊，Claude Code 仍會使用它，但會在背景重新整理。一旦項目比 `MCP_DISCOVERY_CACHE_MAX_STALE_S` 更舊，Claude Code 則會改為捨棄它。Claude Code 會將此值上限設為 `MCP_DISCOVERY_CACHE_MAX_STALE_S`，預設為 4 小時。在 v2.1.238 之前，Claude Code 不會限制此值 |489| `MCP_DISCOVERY_CACHE_TTL_S` | Claude Code 使用[探索快取](/docs/zh-TW/mcp#server-status-detail)項目而不重新整理的秒數（預設值：900）。在項目超過此時間的啟動中，Claude Code 仍會使用它，但會在背景重新整理。一旦項目超過 `MCP_DISCOVERY_CACHE_MAX_STALE_S`，Claude Code 就會改為捨棄它。Claude Code 會將此值上限設為 `MCP_DISCOVERY_CACHE_MAX_STALE_S`，預設為 4 小時。在 v2.1.238 之前，Claude Code 不會限制此值 |

487| `MCP_OAUTH_CALLBACK_PORT` | OAuth 重新導向回呼的固定連接埠，在新增具有[預先設定憑證](/docs/zh-TW/mcp#use-pre-configured-oauth-credentials)的 MCP 伺服器時，可作為 `--callback-port` 的替代方案 |490| `MCP_OAUTH_CALLBACK_PORT` | OAuth 重新導向回呼的固定連接埠，可在新增具有[預先設定憑證](/docs/zh-TW/mcp#use-pre-configured-oauth-credentials)的 MCP 伺服器時作為 `--callback-port` 的替代方案 |

488| `MCP_PROTOCOL_NEGOTIATION` | 僅適用於 [v2 MCP 用戶端執行階段](/docs/zh-TW/mcp#mcp-client-runtimes)，控制 Claude Code 是否探測伺服器是否支援 MCP 協定修訂版 2026-07-28。設定 `auto` 可探測 HTTP、claude.ai 連接器和 stdio 伺服器，設定 `legacy` 則不探測任何伺服器。未設定此變數時，Claude Code 會探測 [MCP 用戶端執行階段](/docs/zh-TW/mcp#mcp-client-runtimes)中所述的伺服器。任何其他值都會被忽略，並在偵錯日誌中留下警告。需要 Claude Code v2.1.221 或更新版本 |491| `MCP_PROTOCOL_NEGOTIATION` | 僅在 [v2 MCP 用戶端執行環境](/docs/zh-TW/mcp#mcp-client-runtimes)上，決定 Claude Code 是否探測伺服器是否支援 MCP 協定修訂版 2026-07-28。設為 `auto` 可探測 HTTP、claude.ai 連接器與 stdio 伺服器，或設為 `legacy` 不探測任何伺服器。未設定此變數時，Claude Code 會探測 [MCP 用戶端執行環境](/docs/zh-TW/mcp#mcp-client-runtimes)中所述的伺服器。任何其他值都會被忽略，並在除錯日誌中留下警告。需要 Claude Code v2.1.221 或更新版本 |

490| `MCP_SDK_GENERATION` | 固定此程序用來連線 MCP 伺服器的 [MCP 用戶端執行階段](/docs/zh-TW/mcp#mcp-client-runtimes)：`v1` 建構於 MCP TypeScript SDK 1.x，`v2` 則建構於 [MCP TypeScript SDK 2.0](https://ts.sdk.modelcontextprotocol.io/v2/)。未設定此變數時，Claude Code 會使用 v2，自該章節所列的版本開始。在 Claude Code v2.1.221 或更新版本中，v2 執行階段會檢查 MCP OAuth 伺服器在其授權回應中傳回的簽發者（issuer），並在不相符時以開頭為 `Issuer mismatch in authorization response` 的錯誤使登入失敗。v1 執行階段不會執行此檢查。如果您設定了無法識別的值，Claude Code 會忽略它並將警告寫入偵錯日誌。Claude Code 每個程序只讀取一次此值。需要 Claude Code v2.1.218 或更新版本 |493| `MCP_SDK_GENERATION` | 固定此程序用來連線 MCP 伺服器的 [MCP 用戶端執行環境](/docs/zh-TW/mcp#mcp-client-runtimes)：`v1`，建構於 MCP TypeScript SDK 1.x；或 `v2`，建構於 [MCP TypeScript SDK 2.0](https://ts.sdk.modelcontextprotocol.io/v2/)。未設定此變數時，Claude Code 會從該節列出的版本開始使用 v2。在 Claude Code v2.1.221 或更新版本中，v2 執行環境會檢查 MCP OAuth 伺服器在其授權回應中傳回的簽發者，若不相符，則登入會失敗並顯示以 `Issuer mismatch in authorization response` 開頭的錯誤。v1 執行環境不會執行此檢查。如果您設定了無法識別的值，Claude Code 會忽略它並將警告寫入除錯日誌。Claude Code 每個程序只讀取此值一次。需要 Claude Code v2.1.218 或更新版本 |

493| `MCP_TOOL_TIMEOUT` | MCP 工具執行的逾時時間，以毫秒為單位（預設值：100000000，約 28 小時）。對於 HTTP、SSE 或 claude.ai 連接器伺服器，每個請求預設也會在 60 秒後逾時；將此變數或個別伺服器的 `timeout` 設定為高於 60000，即可提高該每次請求的限制。較低的值仍會縮短整體工具執行逾時，但每次請求的限制會維持在 60 秒。Stdio 和 WebSocket 伺服器沒有每次請求的計時器。`.mcp.json` 中個別伺服器的 `timeout` 欄位會針對該伺服器覆寫此值。至少為 1000 的個別伺服器 `timeout` 也會設定該伺服器工具呼叫的最小閒置時間窗，因此 `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` 絕不會更早中止它們；此下限需要 Claude Code v2.1.203 或更新版本。對於環境變數，低於 1000 的值會被提高至一秒；對於個別伺服器欄位，低於 1000 的值會被忽略 |496| `MCP_TOOL_TIMEOUT` | MCP 工具執行的逾時時間（毫秒）（預設值：100000000，約 28 小時）。對於 HTTP、SSE 或 claude.ai 連接器伺服器，每個請求預設也會在 60 秒後逾時；將此變數或個別伺服器的 `timeout` 設為高於 60000，即可提高該單一請求上限。較低的值仍會縮短整體工具執行逾時，但單一請求上限維持 60 秒。Stdio 與 WebSocket 伺服器沒有單一請求計時器。`.mcp.json` 中個別伺服器的 `timeout` 欄位會針對該伺服器覆寫此值。至少為 1000 的個別伺服器 `timeout` 也會設定該伺服器工具呼叫的最小閒置時間窗口，因此 `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` 永遠不會更早中止它們；此下限需要 Claude Code v2.1.203 或更新版本。對於環境變數，低於 1000 的值會被調整為一秒；對於個別伺服器欄位，低於 1000 的值會被忽略 |

495| `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` | 標準 OpenTelemetry SDK 的屬性值長度限制。Claude Code 會將包含內容的遙測屬性上限設為此值與 `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 之中較小者，讓截斷標記保持在 SDK 限制之內。Claude Code 會以相同方式讀取 `OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT` 和 `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` 變體，且已設定值中最小者會套用至所有訊號。需要 Claude Code v2.1.214 或更新版本。請參閱[監控](/docs/zh-TW/monitoring-usage#common-configuration-variables) |498| `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` | 標準 OpenTelemetry SDK 的屬性值長度上限。Claude Code 會將包含內容的遙測屬性上限設為此值與 `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 中較小者，讓截斷標記保持在 SDK 限制之內。Claude Code 會以相同方式讀取 `OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT` 與 `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` 變體，並將已設定的最小值套用至所有訊號。需要 Claude Code v2.1.214 或更新版本。請參閱[監控](/docs/zh-TW/monitoring-usage#common-configuration-variables) |

496| `OTEL_LOG_ASSISTANT_RESPONSES` | 設定為 `1` 可在 `assistant_response` OpenTelemetry 日誌事件中包含模型的回應文字。未設定時，Claude Code 會改用 `OTEL_LOG_USER_PROMPTS` 的值。設定為 `0` 可在設定了 `OTEL_LOG_USER_PROMPTS` 的情況下仍保持回應被遮蔽。請在您的 shell、使用者設定或受管設定中設定。在[專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略。需要 Claude Code v2.1.193 或更新版本。請參閱[監控](/docs/zh-TW/monitoring-usage#assistant-response-event) |499| `OTEL_LOG_ASSISTANT_RESPONSES` | 設為 `1` 可在 `assistant_response` OpenTelemetry 日誌事件中包含模型的回應文字。未設定時，Claude Code 會改用 `OTEL_LOG_USER_PROMPTS` 的值。設為 `0` 可在即使已設定 `OTEL_LOG_USER_PROMPTS` 時仍保持回應遮蔽。請在 shell、使用者設定或受管設定中設定此變數。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略。需要 Claude Code v2.1.193 或更新版本。請參閱[監控](/docs/zh-TW/monitoring-usage#assistant-response-event) |

497| `OTEL_LOG_MANAGED_SETTINGS` | 設定為 `1` 可將遮蔽後的受管設定，以及遮蔽前設定的 SHA-256 摘要，新增至 `managed_settings_resolved` OpenTelemetry 日誌事件。預設為停用。請在您的 shell、使用者設定或受管設定中設定；專案或本機設定中的值不會將其開啟。需要 Claude Code v2.1.274 或更新版本。請參閱[監控](/docs/zh-TW/monitoring-usage#managed-settings-resolved-event) |500| `OTEL_LOG_MANAGED_SETTINGS` | 設為 `1` 可在 `managed_settings_resolved` OpenTelemetry 日誌事件中加入遮蔽後的受管設定，以及遮蔽前設定的 SHA-256 摘要。預設為停用。請在 shell、使用者設定或受管設定中設定此變數；專案或本機設定中的值不會將其開啟。需要 Claude Code v2.1.274 或更新版本。請參閱[監控](/docs/zh-TW/monitoring-usage#managed-settings-resolved-event) |

498| `OTEL_LOG_RAW_API_BODIES` | 將 Anthropic Messages API 的請求和回應 JSON 以 `api_request_body` / `api_response_body` 日誌事件發出。設定為 `1` 可發出在內容限制處截斷的內嵌內文，或設定為 `file:<dir>` 將未截斷的內文寫入磁碟並改為發出 `body_ref` 路徑。`CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 可設定內容限制，預設為 60 KB。預設為停用；內文包含完整的對話記錄。請在您的 shell、使用者設定或受管設定中設定。在[專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略。請參閱[監控](/docs/zh-TW/monitoring-usage#api-request-body-event) |501| `OTEL_LOG_RAW_API_BODIES` | 將 Anthropic Messages API 請求與回應的 JSON 以 `api_request_body` / `api_response_body` 日誌事件發出。設為 `1` 可內嵌在內容上限處截斷的主體，或設為 `file:<dir>` 將未截斷的主體寫入磁碟，並改為發出 `body_ref` 路徑。`CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 用於設定內容上限，預設為 60 KB。預設為停用；主體包含完整的對話記錄。請在 shell、使用者設定或受管設定中設定此變數。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略。請參閱[監控](/docs/zh-TW/monitoring-usage#api-request-body-event) |

499| `OTEL_LOG_TOOL_CONTENT` | 設定為 `1` 可在 `tool.output` OpenTelemetry span 事件中包含工具內容。Span 屬性會在[其各自的閘門](/docs/zh-TW/monitoring-usage#new-context-gates)下攜帶工具內容。需要[追蹤](/docs/zh-TW/monitoring-usage#traces-beta)。預設為停用以保護敏感資料。請在您的 shell、使用者設定或受管設定中設定。在[專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略，但該章節所述的關閉值除外。請參閱[監控](/docs/zh-TW/monitoring-usage#tool-output-span-event) |502| `OTEL_LOG_TOOL_CONTENT` | 設為 `1` 可在 `tool.output` OpenTelemetry span 事件中包含工具內容。Span 屬性會在[其各自的閘門](/docs/zh-TW/monitoring-usage#new-context-gates)下攜帶工具內容。需要啟用[追蹤](/docs/zh-TW/monitoring-usage#traces-beta)。預設為停用以保護敏感資料。請在 shell、使用者設定或受管設定中設定此變數。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略，但該節所述的關閉值除外。請參閱[監控](/docs/zh-TW/monitoring-usage#tool-output-span-event) |

500| `OTEL_LOG_TOOL_DETAILS` | 設定為 `1` 可在 OpenTelemetry 指標、追蹤和日誌中包含工具輸入引數；MCP 伺服器名稱；使用者撰寫的工作流程名稱；工具失敗時的原始錯誤字串；`api_refusal` 事件上的拒絕 `category`；[費用和 token 指標](/docs/zh-TW/monitoring-usage#cost-counter)上的實際 agent、skill、外掛和 MCP 伺服器名稱；以及其他工具詳細資訊。預設為停用以保護 PII。請在您的 shell、使用者設定或受管設定中設定。在[專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略，但該章節所述的關閉值除外。請參閱[監控](/docs/zh-TW/monitoring-usage) |503| `OTEL_LOG_TOOL_DETAILS` | 設為 `1` 可在 OpenTelemetry 指標、追蹤與日誌中包含工具輸入引數；MCP 伺服器名稱；使用者撰寫的工作流程名稱；工具失敗時的原始錯誤字串；`api_refusal` 事件中的拒絕 `category`；[費用與 token 指標](/docs/zh-TW/monitoring-usage#cost-counter)中真實的 agent、skill、外掛與 MCP 伺服器名稱；以及其他工具詳細資訊。預設為停用以保護 PII。請在 shell、使用者設定或受管設定中設定此變數。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略，但該節所述的關閉值除外。請參閱[監控](/docs/zh-TW/monitoring-usage) |

501| `OTEL_LOG_USER_PROMPTS` | 設定為 `1` 可在 OpenTelemetry 追蹤和日誌中包含使用者提示詞文字。預設為停用（提示詞會被遮蔽）。請在您的 shell、使用者設定或受管設定中設定。在[專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略，但該章節所述的關閉值除外。請參閱[監控](/docs/zh-TW/monitoring-usage) |504| `OTEL_LOG_USER_PROMPTS` | 設為 `1` 可在 OpenTelemetry 追蹤與日誌中包含使用者提示詞文字。預設為停用（提示詞會被遮蔽）。請在 shell、使用者設定或受管設定中設定此變數。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略，但該節所述的關閉值除外。請參閱[監控](/docs/zh-TW/monitoring-usage) |

503| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | 設定為 `true` 可在指標屬性中包含工作階段進入點（預設值：排除）。於 v2.1.152 新增。請參閱[監控](/docs/zh-TW/monitoring-usage) |506| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | 設為 `true` 可在指標屬性中包含工作階段進入點（預設值：排除）。於 v2.1.152 新增。請參閱[監控](/docs/zh-TW/monitoring-usage) |

504| `OTEL_METRICS_INCLUDE_REPOSITORY` | 設定為 `true` 可為 OpenTelemetry 指標和事件加上識別工作階段儲存庫的 `vcs.*` 屬性（預設值：排除）。需要 Claude Code v2.1.269 或更新版本。請參閱[儲存庫屬性](/docs/zh-TW/monitoring-usage#repository-attributes) |507| `OTEL_METRICS_INCLUDE_REPOSITORY` | 設為 `true` 可為 OpenTelemetry 指標與事件加上識別工作階段儲存庫的 `vcs.*` 屬性（預設值：排除）。需要 Claude Code v2.1.269 或更新版本。請參閱[儲存庫屬性](/docs/zh-TW/monitoring-usage#repository-attributes) |

505| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | 自 v2.1.161 起，Claude Code 會將 `OTEL_RESOURCE_ATTRIBUTES` 的鍵附加至指標資料點標籤。設定為 `false` 可排除它們（預設值：包含）。請參閱[監控](/docs/zh-TW/monitoring-usage#multi-team-organization-support) |508| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | 自 v2.1.161 起，Claude Code 會將 `OTEL_RESOURCE_ATTRIBUTES` 的鍵附加至指標資料點標籤。設為 `false` 可將其排除（預設值：包含）。請參閱[監控](/docs/zh-TW/monitoring-usage#multi-team-organization-support) |

508| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | 覆寫向 [Skill 工具](/docs/zh-TW/skills#control-who-invokes-a-skill)顯示之 skill 中繼資料的字元預算。預算會依上下文視窗的 1% 動態調整，備援值為 8,000 個字元。為了回溯相容性而保留舊名稱 |511| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | 覆寫提供給 [Skill 工具](/docs/zh-TW/skills#control-who-invokes-a-skill)之 skill 中繼資料的字元預算。此預算會以上下文視窗的 1% 動態調整，備援值為 8,000 個字元。為了向後相容而保留舊名稱 |

509| `TASK_MAX_OUTPUT_LENGTH` | 已在 v2.1.277 中與其所設定大小的 `TaskOutput` 工具一起移除，現在不會產生任何作用。先前用於設定 `TaskOutput` 工具保留之[背景任務](/docs/zh-TW/tools-reference#background-commands)輸出的最大字元數。Claude 現在改用 `Read` 讀取背景任務的輸出檔案 |512| `TASK_MAX_OUTPUT_LENGTH` | 已於 v2.1.277 移除，現在不起任何作用，其所設定大小的 `TaskOutput` 工具也一併移除。先前用於設定 `TaskOutput` 工具保留的[背景任務](/docs/zh-TW/tools-reference#background-commands)輸出最大字元數。Claude 現在改用 `Read` 讀取背景任務的輸出檔案 |

533| `VERTEX_REGION_CLAUDE_HAIKU_5_5` | 使用 Google Cloud's Agent Platform 時覆寫 Claude Haiku 5.5 的區域。於 v2.1.293 新增 |

530 534

531也支援標準 OpenTelemetry 匯出器變數（`OTEL_METRICS_EXPORTER`、`OTEL_LOGS_EXPORTER`、`OTEL_EXPORTER_OTLP_ENDPOINT`、`OTEL_EXPORTER_OTLP_PROTOCOL`、`OTEL_EXPORTER_OTLP_HEADERS`、`OTEL_METRIC_EXPORT_INTERVAL`、`OTEL_RESOURCE_ATTRIBUTES`，以及各訊號專屬的變體）。設定詳細資訊請參閱[監控](/docs/zh-TW/monitoring-usage)。535也支援標準 OpenTelemetry 匯出器變數（`OTEL_METRICS_EXPORTER`、`OTEL_LOGS_EXPORTER`、`OTEL_EXPORTER_OTLP_ENDPOINT`、`OTEL_EXPORTER_OTLP_PROTOCOL`、`OTEL_EXPORTER_OTLP_HEADERS`、`OTEL_METRIC_EXPORT_INTERVAL`、`OTEL_RESOURCE_ATTRIBUTES` 以及各訊號專屬的變體）。關於設定細節，請參閱[監控](/docs/zh-TW/monitoring-usage)。

532 536

533請在您的 shell、使用者設定或受管設定中設定 `CLAUDE_CODE_ENABLE_TELEMETRY`，以及用於開啟匯出、選擇匯出目的地或擷取內容的 OpenTelemetry 變數。Claude Code [會在專案和本機設定中忽略它們](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)，但該章節所述的關閉值除外。`OTEL_RESOURCE_ATTRIBUTES` 以及匯出間隔、逾時和壓縮變數（例如 `OTEL_METRIC_EXPORT_INTERVAL`）從專案和本機設定中設定時仍然有效。537請在 shell、使用者設定或受管設定中設定 `CLAUDE_CODE_ENABLE_TELEMETRY`，以及用於開啟匯出、選擇匯出目的地或擷取內容的 OpenTelemetry 變數。Claude Code [會在專案與本機設定中忽略這些變數](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)，但該節所述的關閉值除外。`OTEL_RESOURCE_ATTRIBUTES` 以及匯出間隔、逾時與壓縮相關變數（例如 `OTEL_METRIC_EXPORT_INTERVAL`）在專案與本機設定中仍會套用。

534 538

535<h2 id="what-the-subprocess-environment-scrub-removes">539<h2 id="what-the-subprocess-environment-scrub-removes">

536 子程序環境清除會移除哪些內容540 子程序環境清除會移除哪些內容

errors.md +4 −5

Details

131| `403` with `x-deny-reason: host_not_allowed` in a cloud or routine session | [網路](#host-not-allowed-in-a-cloud-session) |131| `403` with `x-deny-reason: host_not_allowed` in a cloud or routine session | [網路](#host-not-allowed-in-a-cloud-session) |

133| `403` with `This GraphQL query is not enabled for this session` in a cloud session | [GitHub proxy](/docs/zh-TW/cloud-environments#github-proxy) |133| `403` with `GitHub GraphQL is not available from Claude Code sessions` in a cloud session | [GitHub proxy](/docs/zh-TW/cloud-environments#github-proxy) |

134| `The cloud environments service returned an empty response` / `The cloud environments service returned a response in an unexpected format` | [網路](#the-cloud-environments-service-returned-an-empty-or-unexpected-response) |134| `The cloud environments service returned an empty response` / `The cloud environments service returned a response in an unexpected format` | [網路](#the-cloud-environments-service-returned-an-empty-or-unexpected-response) |

136| `N sessions ended while this machine was offline — the environment was cleaned up on the server and can't be resumed.` | [網路](#sessions-ended-while-this-machine-was-offline) |136| `N sessions ended while this machine was offline — the environment was cleaned up on the server and can't be resumed.` | [網路](#sessions-ended-while-this-machine-was-offline) |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

409 410

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

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

2299 2300

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

2301 2302

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

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

2304 2305

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

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

2906```2907```

2907 2908

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

~~2909~~

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

2911 2910

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

fast-mode.md +1 −1

Details

88 88

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

90 90

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

92 92

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

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

feature-availability.md +4 −4

Details

220</table>220</table>

221 221

222<span id="fn1" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>1</sup> 在 Google Cloud's Agent Platform 上，web search 適用於 Claude 4 模型及更新版本。<br />222<span id="fn1" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>1</sup> 在 Google Cloud's Agent Platform 上，web search 適用於 Claude 4 模型及更新版本。<br />

223<span id="fn2" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>2</sup> 在這些提供者上，auto mode 僅支援 Claude Sonnet 5 或更新版本、Opus 4.7 或更新版本，以及 Fable 模型。請參閱 [Auto mode 配置](/docs/zh-TW/auto-mode-config)。如需工作階段在這些提供者上開始時的權限模式，請參閱[工作階段開始時的模式](/docs/zh-TW/permission-modes#which-mode-a-session-starts-in)。在 v2.1.158 到 v2.1.206 中，這些提供者上的 auto mode 也需要設定 `CLAUDE_CODE_ENABLE_AUTO_MODE=1`；v2.1.207 移除了此要求。<br />223<span id="fn2" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>2</sup> 在這些提供者上，auto mode 僅支援 Claude Sonnet 5 或更新版本、Opus 4.7 或更新版本、Haiku 5.5，以及 Fable 模型。請參閱 [Auto mode 設定](/docs/zh-TW/auto-mode-config)。如需工作階段在這些提供者上開始時的權限模式，請參閱[工作階段開始時的模式](/docs/zh-TW/permission-modes#which-mode-a-session-starts-in)。在 v2.1.158 到 v2.1.206 中，這些提供者上的 auto mode 也需要設定 `CLAUDE_CODE_ENABLE_AUTO_MODE=1`；v2.1.207 移除了此要求。<br />

224<span id="fn3" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>3</sup> 受您與雲端提供者的協議約束。<br />224<span id="fn3" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>3</sup> 受您與雲端提供者的協議約束。<br />

225<span id="fn4" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>4</sup> 僅限儀表板和 API。[貢獻指標](/docs/zh-TW/analytics#enable-contribution-metrics)需要 claude.ai Team 或 Enterprise 組織。<br />225<span id="fn4" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>4</sup> 僅限儀表板和 API。[貢獻指標](/docs/zh-TW/analytics#enable-contribution-metrics)需要 claude.ai Team 或 Enterprise 組織。<br />

226<span id="fn5" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>5</sup> 需要 macOS 和 Linux 上的 Claude Code v2.1.224 或更新版本，包括 WSL 2 內的 Linux。在原生 Windows 上，需要 Claude Code v2.1.234 或更新版本。使用 API 金鑰驗證時，訊息傳遞僅限同一機器。在 Amazon Bedrock、AWS 上的 Claude Platform、Google Cloud's Agent Platform 和 Microsoft Foundry 上，訊息傳遞僅限同一機器，需要 Claude Code v2.1.248 或更新版本。Claude 只能從連接到 [Remote Control](/docs/zh-TW/remote-control) 的工作階段找到您的[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)和其他機器上的工作階段。若要連接，您需要 claude.ai 登入和其他 [Remote Control 要求](/docs/zh-TW/remote-control#requirements)。請參閱[在其他機器上訊息傳遞工作階段](/docs/zh-TW/cross-session-messaging#message-sessions-on-other-machines)。226<span id="fn5" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>5</sup> 需要 macOS 和 Linux 上的 Claude Code v2.1.224 或更新版本，包括 WSL 2 內的 Linux。在原生 Windows 上，需要 Claude Code v2.1.234 或更新版本。使用 API 金鑰驗證時，訊息傳遞僅限同一機器。在 Amazon Bedrock、AWS 上的 Claude Platform、Google Cloud's Agent Platform 和 Microsoft Foundry 上，訊息傳遞僅限同一機器，需要 Claude Code v2.1.248 或更新版本。Claude 只能從連接到 [Remote Control](/docs/zh-TW/remote-control) 的工作階段找到您的[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)和其他機器上的工作階段。若要連接，您需要 claude.ai 登入和其他 [Remote Control 要求](/docs/zh-TW/remote-control#requirements)。請參閱[在其他機器上訊息傳遞工作階段](/docs/zh-TW/cross-session-messaging#message-sessions-on-other-machines)。

244 **部分支援：**244 **部分支援：**

245 245

246 * [Desktop](/docs/zh-TW/desktop)：僅透過 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)246 * [Desktop](/docs/zh-TW/desktop)：僅透過 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)

247 * [Auto mode](/docs/zh-TW/auto-mode-config)：Sonnet 5 或更新版本、Opus 4.7 或更新版本，以及 Fable 模型僅限247 * [Auto mode](/docs/zh-TW/auto-mode-config)：僅限 Sonnet 5 或更新版本、Opus 4.7 或更新版本、Haiku 5.5，以及 Fable 模型

248 * [Cross-session messaging](/docs/zh-TW/cross-session-messaging)：僅限此機器上的您的工作階段 <sup><a href="#fn5">5</a></sup>248 * [Cross-session messaging](/docs/zh-TW/cross-session-messaging)：僅限此機器上的您的工作階段 <sup><a href="#fn5">5</a></sup>

249 * [Zero Data Retention](/docs/zh-TW/zero-data-retention)：受您的 AWS 協議約束249 * [Zero Data Retention](/docs/zh-TW/zero-data-retention)：受您的 AWS 協議約束

250 250

270 270

271 * [Desktop](/docs/zh-TW/desktop)：透過[受管設定](https://claude.com/docs/third-party/claude-desktop/configuration)或 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)271 * [Desktop](/docs/zh-TW/desktop)：透過[受管設定](https://claude.com/docs/third-party/claude-desktop/configuration)或 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)

272 * [Web search](/docs/zh-TW/tools-reference#websearch-tool-behavior)：Claude 4 模型及更新版本272 * [Web search](/docs/zh-TW/tools-reference#websearch-tool-behavior)：Claude 4 模型及更新版本

273 * [Auto mode](/docs/zh-TW/auto-mode-config)：Sonnet 5 或更新版本、Opus 4.7 或更新版本，以及 Fable 模型僅限273 * [Auto mode](/docs/zh-TW/auto-mode-config)：僅限 Sonnet 5 或更新版本、Opus 4.7 或更新版本、Haiku 5.5，以及 Fable 模型

274 * [Cross-session messaging](/docs/zh-TW/cross-session-messaging)：僅限此機器上的您的工作階段 <sup><a href="#fn5">5</a></sup>274 * [Cross-session messaging](/docs/zh-TW/cross-session-messaging)：僅限此機器上的您的工作階段 <sup><a href="#fn5">5</a></sup>

275 * [Zero Data Retention](/docs/zh-TW/zero-data-retention)：受您的 Google Cloud 協議約束275 * [Zero Data Retention](/docs/zh-TW/zero-data-retention)：受您的 Google Cloud 協議約束

276 276

284 284

285 * [Desktop](/docs/zh-TW/desktop)：僅透過 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)285 * [Desktop](/docs/zh-TW/desktop)：僅透過 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)

286 * [Web search](/docs/zh-TW/tools-reference#websearch-tool-behavior)：[部署於 Anthropic 上](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)僅限286 * [Web search](/docs/zh-TW/tools-reference#websearch-tool-behavior)：[部署於 Anthropic 上](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)僅限

287 * [Auto mode](/docs/zh-TW/auto-mode-config)：Sonnet 5 或更新版本、Opus 4.7 或更新版本，以及 Fable 模型僅限287 * [Auto mode](/docs/zh-TW/auto-mode-config)：僅限 Sonnet 5 或更新版本、Opus 4.7 或更新版本、Haiku 5.5，以及 Fable 模型

288 * [Cross-session messaging](/docs/zh-TW/cross-session-messaging)：僅限此機器上的您的工作階段 <sup><a href="#fn5">5</a></sup>288 * [Cross-session messaging](/docs/zh-TW/cross-session-messaging)：僅限此機器上的您的工作階段 <sup><a href="#fn5">5</a></sup>

289 * [Zero Data Retention](/docs/zh-TW/zero-data-retention)：受您的 Azure 協議約束289 * [Zero Data Retention](/docs/zh-TW/zero-data-retention)：受您的 Azure 協議約束

290 290

glossary.md +33 −33

Details

130 130

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

132 132

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

134 134

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

136 136

196 Effort level196 Effort level

197</h3>197</h3>

198 198

199一個設定，控制自適應推理，讓模型決定是否以及在每個步驟上進行多少思考。更高的努力意味著更多的思考 tokens 和更深入的推理；更低的努力更快且更便宜。Effort 在 Fable 模型、Opus 4.6 及更新版本和 Sonnet 4.6 及更新版本上受支援。199一個設定，控制自適應推理，讓模型決定是否以及在每個步驟上進行多少思考。更高的 effort 意味著更多的思考 tokens 和更深入的推理；更低的 effort 更快且更便宜。Effort 在 Fable 模型、Opus 4.6 及更新版本、Sonnet 4.6 及更新版本以及 Haiku 5.5 上受支援。

200 200

201了解更多：[Adjust effort level](/docs/zh-TW/model-config#adjust-effort-level)201了解更多：[Adjust effort level](/docs/zh-TW/model-config#adjust-effort-level)

202 202

377</h2>377</h2>

378 378

379<h3 id="sandboxing">379<h3 id="sandboxing">

380 Sandboxing380 沙箱機制

381</h3>381</h3>

382 382

383Bash 工具的 OS 級檔案系統和網路隔離。命令在您預先定義的邊界內執行，因此 Claude 可以在其中自由工作，無需每個命令的批准提示。Sandboxing 是與 [permission rules](#permission-rule) 分開的一層。383Bash 工具的 OS 層級檔案系統和網路隔離。命令在您預先定義的邊界內執行，因此 Claude 可以在其中自由工作，無需針對每個命令顯示核准提示。沙箱機制是與[權限規則](#permission-rule)分開的一層。

384 384

385了解更多：[Sandboxing](/docs/zh-TW/sandboxing)385了解更多：[沙箱機制](/docs/zh-TW/sandboxing)

386 386

387<h3 id="session">387<h3 id="session">

388 Session388 工作階段

389</h3>389</h3>

390 390

391與您當前目錄相關的對話，具有自己的獨立 [context window](#context-window)。會話可以使用 `claude -c` 恢復、使用 `--fork-session` 分叉以在新會話 ID 下保留歷史記錄，或在終端間並行執行。執行 `/clear` 啟動新會話；前一個會話保持存儲並可通過 `/resume` 獲得。每個會話的記錄存儲在 `~/.claude/projects/` 下。391與您目前目錄相關聯的對話，具有自己獨立的[上下文視窗](#context-window)。工作階段可以使用 `claude -c` 恢復、使用 `--fork-session` 分叉以在新的工作階段 ID 下保留歷史記錄，或在多個終端機中並行執行。執行 `/clear` 會啟動新的工作階段；前一個工作階段會保持儲存，並可透過 `/resume` 取得。每個工作階段的逐字稿儲存在 `~/.claude/projects/` 下。

392 392

393了解更多：[Work with sessions](/docs/zh-TW/how-claude-code-works#work-with-sessions)393了解更多：[使用工作階段](/docs/zh-TW/how-claude-code-works#work-with-sessions)

394 394

395<h3 id="settings-layers">395<h3 id="settings-layers">

396 Settings layers396 設定層級

397</h3>397</h3>

398 398

399Claude Code 讀取設定的層級結構，按優先順序從最高到最低：[managed policy](#managed-settings)、命令列引數、`.claude/settings.local.json` 的本地設定、`.claude/settings.json` 的專案設定，然後是 `~/.claude/settings.json` 的使用者設定。陣列跨層級合併；較高層級的標量覆蓋較低層級的。請參閱 [Settings precedence](/docs/zh-TW/settings#settings-precedence)。399Claude Code 讀取設定的層級結構，依優先順序從最高到最低：[受管政策](#managed-settings)、您透過 `--settings` 旗標傳入的設定、`.claude/settings.local.json` 的本機設定、`.claude/settings.json` 的專案設定，然後是 `~/.claude/settings.json` 的使用者設定。陣列會跨層級合併；較高層級的純量值會覆寫較低層級的值。請參閱[設定優先順序](/docs/zh-TW/settings#settings-precedence)。

400 400

401了解更多：[Settings files](/docs/zh-TW/settings#where-settings-live)401了解更多：[設定檔](/docs/zh-TW/settings#where-settings-live)

402 402

403<h3 id="skill">403<h3 id="skill">

404 Skill404 Skill

405</h3>405</h3>

406 406

407一個 `SKILL.md` 檔案，包含 Claude 添加到其工具包中的指令、知識或工作流程。Claude 在相關時自動載入 skill，或您可以使用 `/skill-name` 直接調用它。Skills 遵循 Agent Skills 開放標準；Claude Code 使用調用控制和 subagent 執行擴展它。407一個 `SKILL.md` 檔案，包含 Claude 加入其工具組中的指令、知識或工作流程。Claude 會在相關時自動載入 skill，或者您可以使用 `/skill-name` 直接呼叫它。Skills 遵循 Agent Skills 開放標準；Claude Code 以呼叫控制和 subagent 執行擴充了此標準。

408 408

409Skills 是自訂命令的推薦後繼者。`.claude/commands/deploy.md` 的檔案和 `.claude/skills/deploy/SKILL.md` 的檔案都會建立 `/deploy` 並以相同方式工作；現有命令檔案繼續工作。409Skills 是自訂命令的建議後繼者。位於 `.claude/commands/deploy.md` 的檔案和位於 `.claude/skills/deploy/SKILL.md` 的檔案都會建立 `/deploy` 並以相同方式運作；現有的命令檔案仍可繼續使用。

410 410

411了解更多：[Extend Claude with skills](/docs/zh-TW/skills)411了解更多：[使用 skills 擴充 Claude](/docs/zh-TW/skills)

412 412

413<h3 id="subagent">413<h3 id="subagent">

414 Subagent414 Subagent

415</h3>415</h3>

416 416

417一個專門的 AI 助手，在自己的上下文視窗中運行，具有自訂系統提示、特定工具存取和獨立權限。它處理委派的任務並向主對話返回摘要。使用 subagents 將大型探索保留在主上下文之外或執行並行研究。Subagent 保持在產生它的會話內。若要在您自己執行的不同會話之間傳遞發現，請使用 [cross-session messaging](/docs/zh-TW/cross-session-messaging)。417一個專門的 AI 助理，在自己的上下文視窗中執行，具有自訂系統提示詞、特定工具存取權和獨立權限。它處理委派的任務，並向主對話傳回摘要。使用 subagent 可將大型探索保留在主要上下文之外，或執行並行研究。Subagent 會留在產生它的工作階段內。若要在您自己執行的不同工作階段之間傳遞發現，請使用[跨工作階段訊息傳遞](/docs/zh-TW/cross-session-messaging)。

418 418

419內建 subagents 包括 Explore、Plan 和通用目的。419內建 subagent 包括 Explore、Plan 和通用型。

420 420

421了解更多：[Create custom subagents](/docs/zh-TW/sub-agents)421了解更多：[建立自訂 subagent](/docs/zh-TW/sub-agents)

422 422

423<h3 id="surface">423<h3 id="surface">

424 Surface424 使用介面

425</h3>425</h3>

426 426

427您存取 Claude Code 的任何地方：CLI、VS Code、JetBrains、Desktop 或 claude.ai。所有 surfaces 共享相同的引擎。您機器上的會話讀取您的本地 CLAUDE.md、設定和 skills；[cloud sessions](/docs/zh-TW/cloud-environments#what-carries-over-from-your-setup) 從您儲存庫的全新複製開始，不讀取您機器上的 `~/.claude/`。Slack 和 Chrome 擴展是連接到 surface 的整合，而不是 surfaces 本身。427您存取 Claude Code 的任何地方：CLI、VS Code、JetBrains、Desktop 或 claude.ai。所有使用介面共用相同的引擎。您機器上的工作階段會讀取您本機的 CLAUDE.md、設定和 skills；[雲端工作階段](/docs/zh-TW/cloud-environments#what-carries-over-from-your-setup)從您儲存庫的全新複製開始，不會讀取您機器上的 `~/.claude/`。Slack 和 Chrome 擴充功能是連接到使用介面的整合，而不是使用介面本身。

428 428

429了解更多：[Platforms and integrations](/docs/zh-TW/platforms)429了解更多：[平台與整合](/docs/zh-TW/platforms)

430 430

431<h3 id="system-prompt">431<h3 id="system-prompt">

432 System prompt432 系統提示詞

433</h3>433</h3>

434 434

435Claude Code 在每個請求時在您的對話前發送的指令，涵蓋 Claude 如何使用工具、安全行為和格式化其回應。您可以使用 `--append-system-prompt` 添加到系統提示或使用 `--system-prompt` 替換它。系統提示是 [prompt cache](/docs/zh-TW/prompt-caching#how-the-cache-is-organized) 的第一層。435Claude Code 在每個請求中於您的對話之前傳送的指令，涵蓋 Claude 如何使用工具、如何安全行事，以及如何格式化其回應。您可以使用 `--append-system-prompt` 附加內容到系統提示詞，或使用 `--system-prompt` 取代它。系統提示詞是[提示快取](/docs/zh-TW/prompt-caching#how-the-cache-is-organized)的第一層。

436 436

437您的 [CLAUDE.md](#claude-md) 檔案和您的 [output style](#output-style) 的指令不是系統提示的一部分。Claude Code 在對話中將它們作為 [system reminders](#system-reminder) 傳遞。437您的 [CLAUDE.md](#claude-md) 檔案和您的[輸出風格](#output-style)指令不屬於系統提示詞。Claude Code 會在對話中將它們作為[系統提醒](#system-reminder)傳遞。

438 438

439了解更多：[System prompt flags](/docs/zh-TW/cli-reference#system-prompt-flags)439了解更多：[系統提示詞旗標](/docs/zh-TW/cli-reference#system-prompt-flags)

440 440

441<h3 id="system-reminder">441<h3 id="system-reminder">

442 System reminder442 系統提醒

443</h3>443</h3>

444 444

445Claude Code 作為 [harness](#agentic-harness) 添加到對話中的訊息，以給予 Claude 上下文。您不會自己發送系統提醒。Claude Code 在會話執行時插入它們，例如當會話啟動時、當 hook 返回文字時或當檔案在磁碟上變更時。Claude 與您的訊息一起讀取它們。以下所有內容都作為系統提醒到達 Claude：445Claude Code 作為[執行框架](#agentic-harness)加入對話中的訊息，用以提供 Claude 上下文。您不會自己傳送系統提醒。Claude Code 會在工作階段執行期間插入它們，例如在工作階段啟動時、hook 傳回文字時，或檔案在磁碟上變更時。Claude 會將它們與您的訊息一起讀取。以下內容都會以系統提醒的形式傳達給 Claude：

446 446

447* 您的 [CLAUDE.md](#claude-md) 檔案447* 您的 [CLAUDE.md](#claude-md) 檔案

448* 您的 [output style](#output-style) 的指令448* 您的[輸出風格](#output-style)指令

449* [hook](#hook) 作為 `additionalContext` 返回的文字449* [hook](#hook) 以 `additionalContext` 傳回的文字

450* 可用 [skills](#skill) 的列表450* 可用 [skills](#skill) 的清單

451* 一個注意，Claude 之前讀取的檔案已在磁碟上變更451* 說明 Claude 先前讀取的檔案已在磁碟上變更的通知

452* 提交和拉取請求的歸屬行452* 提交和 pull request 的署名行

453 453

454在記錄的 API 請求中，系統提醒出現在使用者訊息內的 `<system-reminder>` 標籤中，或在某些模型上作為具有 `system` 角色的單獨訊息。454在記錄的 API 請求中，系統提醒會以 `<system-reminder>` 標籤包裝並出現在使用者訊息內，或在某些模型上作為具有 `system` 角色的獨立訊息出現。

455 455

456了解更多：[Context Claude Code adds outside the system prompt](/docs/zh-TW/agent-sdk/modifying-system-prompts#context-claude-code-adds-outside-the-system-prompt)456了解更多：[Claude Code 在系統提示詞之外加入的上下文](/docs/zh-TW/agent-sdk/modifying-system-prompts#context-claude-code-adds-outside-the-system-prompt)

457 457

458<h2 id="t">458<h2 id="t">

459 T459 T

google-vertex-ai.md +2 −2

Details

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

211```211```

212 212

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

214 214

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

216 216

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

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

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

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

370 370

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

372 372

headless.md +22 −6

Details

219 追蹤 subagent 訊息219 追蹤 subagent 訊息

220</h4>220</h4>

221 221

222來自 [subagent](/docs/zh-TW/sub-agents) 的訊息會以 `assistant` 及 `user` 訊息的形式出現在串流中，其 `parent_tool_use_id` 欄位為產生該 subagent 的工具呼叫 ID。來自主對話的訊息在該欄位中則為 `null`。222來自 [subagent](/docs/zh-TW/sub-agents) 以及[在 subagent 中執行](/docs/zh-TW/skills#run-skills-in-a-subagent)的 skill 的訊息，會以 `assistant` 及 `user` 訊息的形式出現在串流中。其 `parent_tool_use_id` 欄位會指出每則訊息屬於哪一次執行。來自主對話的訊息在該欄位中則為 `null`。

223 223

224在[前景](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)執行的 subagent 的第一則訊息是一則 `user` 訊息，內含驅動它的提示詞。在第一則訊息之後，Claude Code 會發出：224分叉 skill 或在[前景](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)執行的 subagent 的第一則訊息，是一則 `user` 訊息，內含驅動它的提示詞或 skill 內容。在第一則訊息之後，Claude Code 會發出：

225 225

226* **預設情況下**：subagent 的 `tool_use` 及 `tool_result` 區塊。226* **預設情況下**：該次執行的 `tool_use` 及 `tool_result` 區塊。

227* **使用 [`--forward-subagent-text`](/docs/zh-TW/cli-reference#cli-flags) 或 [`CLAUDE_CODE_FORWARD_SUBAGENT_TEXT`](/docs/zh-TW/env-vars) 時**：還會包含 subagent 的文字及思考區塊，因此您可以重建每個 subagent 的逐字稿。這需要 Claude Code v2.1.211 或更新版本。227* **使用 [`--forward-subagent-text`](/docs/zh-TW/cli-reference#cli-flags) 或 [`CLAUDE_CODE_FORWARD_SUBAGENT_TEXT`](/docs/zh-TW/env-vars) 時**：還會包含該次執行的文字及思考區塊，因此您可以重建每次執行的逐字稿。

228 228

229啟用任一選項時，Claude Code 會轉發來自[每個巢狀層級的 subagent](/docs/zh-TW/sub-agents#let-subagents-spawn-their-own-subagents) 的訊息，無論每個 subagent 是透過 Agent 工具產生，還是以[分叉 skill](/docs/zh-TW/skills#run-skills-in-a-subagent) 的形式啟動。由分叉 skill 產生的 subagent 的訊息，以及在 subagent 或另一個分叉 skill 內啟動的分叉 skill 的訊息，需要 Claude Code v2.1.275 或更新版本。在 `parent_tool_use_id` 中，巢狀 subagent 的訊息會帶有啟動它的 Agent 或 Skill 工具呼叫 ID，因此您可以依循這些 ID 重建完整的巢狀樹狀結構。在 v2.1.219 之前，來自巢狀 subagent 的訊息不會出現在串流中。229啟用任一選項時，Claude Code 會轉發來自[每個巢狀層級的 subagent](/docs/zh-TW/sub-agents#let-subagents-spawn-their-own-subagents) 的訊息，無論每個 subagent 是透過 Agent 工具產生，還是以分叉 skill 的形式啟動。在 `parent_tool_use_id` 中，巢狀 subagent 的訊息會帶有啟動它的 Agent 或 Skill 工具呼叫 ID，因此您可以依循這些 ID 重建完整的巢狀樹狀結構。

230 230

231[在 subagent 中執行](/docs/zh-TW/skills#run-skills-in-a-subagent)的 skill 會以相同方式出現在串流中：分叉 skill 的第一則訊息是一則 `user` 訊息，內含驅動該次執行的 skill 內容。如果您啟用任一選項，串流也會包含分叉 skill 的文字及思考區塊。在 v2.1.265 之前，串流中只會出現分叉 skill 的 `tool_use` 及 `tool_result` 區塊。231由 Claude 透過工具呼叫啟動的執行，會帶有該工具呼叫的 ID。您透過將 `/<skill-name>` 作為提示詞傳入而啟動的分叉 skill 沒有工具呼叫，因此其訊息會改為帶有 `forked-command-` 值，並在它完成後才送達。請在第一欄中找到該次執行的啟動方式：

232

233| 執行的啟動方式 | `parent_tool_use_id` | 其訊息送達的時機 |

234| :- | :- | :- |

235| Claude 從主對話呼叫 Agent 工具 | 該 Agent `tool_use` 區塊的 ID | 在 subagent 運作期間 |

236| Claude 從主對話為分叉 skill 呼叫 Skill 工具 | 該 Skill `tool_use` 區塊的 ID | 在分叉 skill 運作期間 |

237| 您將 `/<skill-name>` 作為提示詞傳入 | 以 `forked-command-` 開頭的值 | 在分叉 skill 完成後一併依序送達 |

238

239對於從提示詞啟動的分叉 skill，請以 `forked-command-` 前綴比對 `parent_tool_use_id`，因為其後的名稱可能與您輸入的名稱不同。

240

241如果您的串流中缺少其中某些訊息，請對照以下最低版本檢查您的 Claude Code 版本：

242

243* **`--forward-subagent-text` 及 `CLAUDE_CODE_FORWARD_SUBAGENT_TEXT`**：v2.1.211 或更新版本

244* **在每個巢狀層級進行轉發**：v2.1.219 或更新版本

245* **Claude 從主對話以 Skill 工具啟動的分叉 skill**：其 `tool_use` 及 `tool_result` 區塊需要 v2.1.86 或更新版本，其第一則 `user` 訊息以及文字及思考區塊需要 v2.1.265 或更新版本

246* **由分叉 skill 產生的 subagent 的訊息，以及在 subagent 或另一個分叉 skill 內啟動的分叉 skill 的訊息**：v2.1.275 或更新版本

247* **您透過將 `/<skill-name>` 作為提示詞傳入而啟動的分叉 skill 的訊息**：v2.1.287 或更新版本

232 248

233<h4 id="handle-api-retries">249<h4 id="handle-api-retries">

234 處理 API 重試250 處理 API 重試

hooks.md +8 −6

Details

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

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

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

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

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

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

3273 WorktreeRemove3273 WorktreeRemove

3274</h3>3274</h3>

3275 3275

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

3277 3277

3278* 您結束 `--worktree` 工作階段並選擇移除它3278* 您結束互動式 [worktree 工作階段](/docs/zh-TW/worktrees#start-claude-in-a-worktree)，並在 Claude Code 提示時選擇移除 worktree

3279* 具有 `isolation: "worktree"` 的 subagent 完成3279* 您結束一個尚未[命名](/docs/zh-TW/sessions#name-your-sessions)的互動式 worktree 工作階段，Claude Code 未發現任何已變更或未追蹤的檔案，並在未提示的情況下移除 worktree

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

3281

3282Claude Code 使用 git 尋找已變更或未追蹤的檔案，因此在不是 git checkout 或不位於 git checkout 內的 worktree 中，即使目錄含有未提交的工作，也找不到任何檔案。請在 WorktreeRemove hook 刪除任何內容之前，先檢查這類工作。

3281 3283

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

3283 3285

3284* **沒有 WorktreeRemove hook**：當您結束 `--worktree` 工作階段並選擇移除時，Claude Code 會改用 `git worktree remove --force` 處理您的 WorktreeCreate hook 回傳的路徑，因此 git 能識別的 worktree 會被移除。git 無法識別的 worktree，例如您的 hook 以非 git 版本控制系統建立的 worktree，會保留在磁碟上。關於刪除[背景工作階段](/docs/zh-TW/agent-view#what-deleting-a-session-removes)時如何處理 hook 建立的 worktree，請參閱 agent view 的刪除規則。3286* **沒有 WorktreeRemove hook**：當 Claude Code 在您結束 worktree 工作階段時移除 worktree，會改用 `git worktree remove --force` 處理您的 WorktreeCreate hook 所回傳的路徑，因此 git 能識別的 worktree 會被移除。git 無法識別的 worktree（例如您的 hook 使用非 git 版本控制系統建立的 worktree）會保留在磁碟上。關於刪除[背景工作階段](/docs/zh-TW/agent-view#what-deleting-a-session-removes)時如何處理由 hook 建立的 worktree，請參閱 agent view 的刪除規則。

3285* **Hook 以 0 結束**：該 worktree 視為已移除。Claude Code 不會從 hook 讀取其他任何內容，因此請確保您的 hook 已刪除該目錄。3287* **Hook 以 0 結束**：該 worktree 視為已移除。Claude Code 不會從 hook 讀取其他任何內容，因此請確保您的 hook 已刪除該目錄。

3286* **Hook 以非零結束**：如果 `worktree_path` 處的目錄在之後仍然存在，移除即失敗，且 worktree 會保留在磁碟上，不會改用 git。在以非零結束之前已刪除目錄的 hook 視為已移除。關於失敗的回報方式，請參閱 [WorktreeRemove 輸入](#worktreeremove-input)。3288* **Hook 以非零結束**：如果 `worktree_path` 處的目錄在之後仍然存在，移除即失敗，且 worktree 會保留在磁碟上，不會改用 git。在以非零結束之前已刪除目錄的 hook 視為已移除。關於失敗的回報方式，請參閱 [WorktreeRemove 輸入](#worktreeremove-input)。

3287 3289

hooks-guide.md +1 −1

Details

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

Details

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

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

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

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

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

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

82 82

interactive-mode.md +1 −1

Details

42| `Ctrl+Enter` 或 `Ctrl+X Ctrl+S` | 立即傳送排隊的訊息 | 傳送您的[排隊訊息](#queue-messages-while-claude-works)和您的草稿與它們一起立即發出。[Claude Code 何時傳送您排隊的內容](#when-claude-code-sends-what-you-queued)涵蓋了 Claude 正在處理的回合會發生什麼。在[shell 模式](#shell-mode-with-prefix)中，該鍵只會將您的命令排隊。在不報告延伸鍵的終端中，`Ctrl+Enter` 會以純 `Enter` 的形式到達；`Ctrl+X Ctrl+S` 在任何終端中都有效。需要 Claude Code v2.1.275 或更新版本 |42| `Ctrl+Enter` 或 `Ctrl+X Ctrl+S` | 立即傳送排隊的訊息 | 傳送您的[排隊訊息](#queue-messages-while-claude-works)和您的草稿與它們一起立即發出。[Claude Code 何時傳送您排隊的內容](#when-claude-code-sends-what-you-queued)涵蓋了 Claude 正在處理的回合會發生什麼。在[shell 模式](#shell-mode-with-prefix)中，該鍵只會將您的命令排隊。在不報告延伸鍵的終端中，`Ctrl+Enter` 會以純 `Enter` 的形式到達；`Ctrl+X Ctrl+S` 在任何終端中都有效。需要 Claude Code v2.1.275 或更新版本 |

43| `Shift+Tab` 或 `Alt+M`（當 Node 或 Bun 執行時間未啟用 VT 輸入模式時在 Windows 上） | 循環權限模式 | 循環通過 `default`（在模式指示器中標記為 Manual）、`acceptEdits`、`plan` 和（如果可用）`bypassPermissions`，然後是 `auto`。從 `auto`，第一次按下會切換到 `default`。請參閱[權限模式](/docs/zh-TW/permission-modes)。在檔案權限提示上，相同的鍵會關閉開啟的[註解欄位](/docs/zh-TW/permissions#add-a-comment-when-you-answer-a-permission-prompt)。沒有開啟欄位時，它會選擇允許該操作以供工作階段其餘部分的選項（當提示提供該選項時） |43| `Shift+Tab` 或 `Alt+M`（當 Node 或 Bun 執行時間未啟用 VT 輸入模式時在 Windows 上） | 循環權限模式 | 循環通過 `default`（在模式指示器中標記為 Manual）、`acceptEdits`、`plan` 和（如果可用）`bypassPermissions`，然後是 `auto`。從 `auto`，第一次按下會切換到 `default`。請參閱[權限模式](/docs/zh-TW/permission-modes)。在檔案權限提示上，相同的鍵會關閉開啟的[註解欄位](/docs/zh-TW/permissions#add-a-comment-when-you-answer-a-permission-prompt)。沒有開啟欄位時，它會選擇允許該操作以供工作階段其餘部分的選項（當提示提供該選項時） |

47 47

48<h3 id="text-editing">48<h3 id="text-editing">

keybindings.md +3 −2

Details

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

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

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

307 308

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

llm-gateway-connect.md +8 −1

Details

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

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

218 218

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

220

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

222

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

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

225

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

220 227

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

222 229

managed-mcp.md +17 −5

Details

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

348</h4>348</h4>

349 349

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

351

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

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

351 354

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

353 356

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

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

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

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

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

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

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

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

366

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

368

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

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

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

361 372

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

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

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

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

533</Accordion>545</Accordion>

534 546

memory.md +2 −2

Details

8 8

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

10 10

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

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

13 13

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

15 15

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

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

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

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

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

model-config.md +36 −23

Details

43| **`opus[1m]`** | 使用具有 [100 萬 token 上下文視窗](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)的 Opus 進行長時間工作階段 |43| **`opus[1m]`** | 使用具有 [100 萬 token 上下文視窗](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)的 Opus 進行長時間工作階段 |

44| **`opusplan`** | 特殊模式，在 plan mode 期間使用 `opus`，然後在執行時切換至 `sonnet` |44| **`opusplan`** | 特殊模式，在 plan mode 期間使用 `opus`，然後在執行時切換至 `sonnet` |

45 45

~~46`opus` 和 `sonnet` 別名解析到的版本取決於供應商：~~46`opus`、`sonnet` 和 `haiku` 別名在 Anthropic API 上會解析為最新版本，在部分其他供應商上則會解析為較早的版本：

47 47

~~48| 供應商 | `opus` | `sonnet` |~~48| 供應商 | `opus` | `sonnet` | `haiku` |

~~49| :- | :- | :- |~~49| :- | :- | :- | :- |

54 54

55<span id="fable-alias-resolution" />55<span id="fable-alias-resolution" />

56 56

58 58

59未設定為提供 `claude-fable-5-1` 的閘道會拒絕對該模型的請求。若要透過提供該模型的閘道使用 Fable 5.1，請使用 `/model claude-fable-5-1` 選擇它。59未設定為提供 `claude-fable-5-1` 的閘道會拒絕對該模型的請求。若要透過提供該模型的閘道使用 Fable 5.1，請使用 `/model claude-fable-5-1` 選擇它。

60 60

~~61當別名解析為較舊的模型時，您可以明確選擇完整模型名稱，或設定 `ANTHROPIC_DEFAULT_OPUS_MODEL` 或 `ANTHROPIC_DEFAULT_SONNET_MODEL` 來使用較新的模型。~~61當 `opus` 或 `sonnet` 解析為較舊的模型時，您可以明確選擇完整模型名稱，或設定 `ANTHROPIC_DEFAULT_OPUS_MODEL` 或 `ANTHROPIC_DEFAULT_SONNET_MODEL` 來使用較新的模型。

62 62

63較早的版本會將這些別名解析為較舊的模型。關於每個別名變更時的版本，請參閱[版本歷史](#version-history)。63較早的版本會將這些別名解析為較舊的模型。關於每個別名變更時的版本，請參閱[版本歷史](#version-history)。

64 64

65別名會指向您供應商的建議版本，並隨時間更新。若要固定使用特定版本，請使用完整模型名稱，例如 `claude-opus-5-5`，或設定對應的環境變數，例如 `ANTHROPIC_DEFAULT_OPUS_MODEL`。65別名會指向您供應商的建議版本，並隨時間更新。若要固定使用特定版本，請使用完整模型名稱，例如 `claude-opus-5-5`，或設定對應的環境變數，例如 `ANTHROPIC_DEFAULT_OPUS_MODEL`。

66 66

67<Note>67<Note>

68 Sonnet 5.5 需要 Claude Code v2.1.284 或更新版本，Opus 5.5 需要 v2.1.280 或更新版本。如果從較舊版本對其中任一模型發出的請求失敗，請參閱 [Claude Code does not support this model](/docs/zh-TW/errors#claude-code-does-not-support-this-model)。執行 `claude update` 進行升級。68 Sonnet 5.5 需要 Claude Code v2.1.284 或更新版本，Opus 5.5 需要 v2.1.280 或更新版本。如果從較舊版本對其中任一模型發出的請求失敗，請參閱 [Claude Code does not support this model](/docs/zh-TW/errors#claude-code-does-not-support-this-model)。使用 Haiku 5.5 時請使用 v2.1.293 或更新版本。執行 `claude update` 進行升級。

69</Note>69</Note>

70 70

71<h3 id="work-with-fable">71<h3 id="work-with-fable">

156 156

157當 Claude Code 直接或透過代理其請求的 [LLM 閘道](/docs/zh-TW/llm-gateway)與 Anthropic API 通訊時，`/model` 選擇器中會顯示價格，而某一列上的價格即為該列所選模型的價格。在 Amazon Bedrock 等[第三方供應商](/docs/zh-TW/third-party-integrations)以及 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway) 上，由您的供應商或閘道決定您支付的費用，因此選擇器的各列不會顯示價格。價格僅為顯示標籤；它不會影響某一列所選擇的模型或您供應商的計費。在 v2.1.206 之前，[Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 和閘道工作階段會顯示 Anthropic 的牌價，且某一列可能顯示與其所選模型不同之模型的價格。157當 Claude Code 直接或透過代理其請求的 [LLM 閘道](/docs/zh-TW/llm-gateway)與 Anthropic API 通訊時，`/model` 選擇器中會顯示價格，而某一列上的價格即為該列所選模型的價格。在 Amazon Bedrock 等[第三方供應商](/docs/zh-TW/third-party-integrations)以及 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway) 上，由您的供應商或閘道決定您支付的費用，因此選擇器的各列不會顯示價格。價格僅為顯示標籤；它不會影響某一列所選擇的模型或您供應商的計費。在 v2.1.206 之前，[Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 和閘道工作階段會顯示 Anthropic 的牌價，且某一列可能顯示與其所選模型不同之模型的價格。

158 158

159以 `claude --resume`、`--continue` 或 `/resume` 選擇器啟動的恢復工作階段，會保留逐字稿儲存時所使用的模型，不論目前的 `model` 設定為何。如果還原的模型已停用或被 [`availableModels`](#restrict-model-selection) 排除，工作階段會改依一般的優先順序進行。這可防止其他工作階段的 `/model` 選擇在恢復時變更模型。在使用供應商專屬部署 ID 而非 Anthropic 模型 ID 的供應商上（例如 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry），完全不會還原逐字稿中的模型，工作階段會透過一般的優先順序來解析其模型。159以 `claude --resume`、`--continue` 或 `/resume` 選擇器啟動的恢復工作階段，會保留逐字稿儲存時所使用的模型。如果還原的模型已停用或被 [`availableModels`](#restrict-model-selection) 排除，工作階段會改依一般的優先順序進行。在使用供應商專屬部署 ID 而非 Anthropic 模型 ID 的供應商上（例如 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry），完全不會還原逐字稿中的模型，工作階段會透過一般的優先順序來解析其模型。

160

161如果您的 `model` 設定為 `haiku`，在 Haiku 模型上儲存的工作階段會以 `haiku` 目前解析到的模型恢復。例如，一旦 `haiku` 解析為 Haiku 5.5，在 Haiku 4.5 上儲存的工作階段就會以 Haiku 5.5 恢復。

160 162

161您透過 `--model` 或 `ANTHROPIC_MODEL` 為新啟動選擇的模型仍優先於還原的模型。自 v2.1.195 起，[`ANTHROPIC_DEFAULT_OPUS_MODEL`](#environment-variables) 系列變數也同樣優先。[`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions) 在其章節所列的條件下也可優先。163您透過 `--model` 或 `ANTHROPIC_MODEL` 為新啟動選擇的模型仍優先於還原的模型。自 v2.1.195 起，[`ANTHROPIC_DEFAULT_OPUS_MODEL`](#environment-variables) 系列變數也同樣優先。[`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions) 在其章節所列的條件下也可優先。

162 164

645| 模型 | 等級 |647| 模型 | 等級 |

646| :- | :- |648| :- | :- |

650 652

651如果您設定了目前模型不支援的等級，Claude Code 會改用等於或低於您所設定等級中最高的支援等級。例如，`xhigh` 在 Opus 4.6 上會以 `high` 執行。您的組織或您自己的設定也可以限制模型提供的等級；請參閱[組織 effort 限制](#organization-effort-limits)。653如果您設定了目前模型不支援的等級，Claude Code 會改用等於或低於您所設定等級中最高的支援等級。例如，`xhigh` 在 Opus 4.6 上會以 `high` 執行。您的組織或您自己的設定也可以限制模型提供的等級；請參閱[組織 effort 限制](#organization-effort-limits)。

654 656

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

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

6573. 模型的預設 effort：所有支援 effort 的模型都預設為 `high`，但 Opus 5.5 和 Sonnet 5.5 預設為 `medium`、Opus 4.7 預設為 `xhigh`，而當您的組織為其[組織預設模型](#organization-default-model)設定預設 effort 等級時，該等級就是您執行該模型時的預設值。自動模型備援後適用的等級，請參閱[備援後的 effort 等級](#effort-level-after-a-fallback)。6593. 模型的預設 effort：所有支援 effort 的模型都預設為 `high`，但 Opus 5.5、Sonnet 5.5 和 Haiku 5.5 預設為 `medium`、Opus 4.7 預設為 `xhigh`，而當您的組織為其[組織預設模型](#organization-default-model)設定預設 effort 等級時，該等級就是您執行該模型時的預設值。自動模型備援後適用的等級，請參閱[備援後的 effort 等級](#effort-level-after-a-fallback)。

658 660

659除非上述來源之一為 Opus 5.5 設定了等級，否則 Opus 5.5 會從 `medium` 開始，且您使用者設定檔中的頂層 `effortLevel` 不會計入 Opus 5.5。該鍵是 Claude Code 開始按模型儲存等級之前 `/effort` 寫入的舊形式：它會繼續在先前適用的地方適用，即 Opus 5、Fable 5.1 及更早的模型，而 Opus 5.5 及其後發布的模型則會從自己的預設值開始，直到您使用 `/effort` 或 `/model` 選擇器為其選擇等級為止。專案、本機或受管設定中的頂層 `effortLevel`，或透過 `--settings` 傳入的 `effortLevel`，則適用於所有模型。661除非上述來源之一為 Opus 5.5 設定了等級，否則 Opus 5.5 會從 `medium` 開始，且您使用者設定檔中的頂層 `effortLevel` 不會計入 Opus 5.5。該鍵是 Claude Code 開始按模型儲存等級之前 `/effort` 寫入的舊形式：它會繼續在先前適用的地方適用，即 Opus 5、Fable 5.1 及更早的模型，而 Opus 5.5 及其後發布的模型則會從自己的預設值開始，直到您使用 `/effort` 或 `/model` 選擇器為其選擇等級為止。專案、本機或受管設定中的頂層 `effortLevel`，或透過 `--settings` 傳入的 `effortLevel`，則適用於所有模型。

660 662

709| 等級 | 使用時機 |711| 等級 | 使用時機 |

710| :- | :- |712| :- | :- |

711| `low` | 您會檢閱每個結果的快速交流，例如腦力激盪、初步草稿，或像重新命名這類的小變更 |713| `low` | 您會檢閱每個結果的快速交流，例如腦力激盪、初步草稿，或像重新命名這類的小變更 |

715| `max` | 您希望 Claude 在沒有您參與的情況下處理的困難問題，例如找出安全漏洞。`max` 可能出現報酬遞減且容易過度思考，因此在廣泛採用前請先測試 |717| `max` | 您希望 Claude 在沒有您參與的情況下處理的困難問題，例如找出安全漏洞。`max` 可能出現報酬遞減且容易過度思考，因此在廣泛採用前請先測試 |

753 755

754自適應推理讓每個步驟的思考變為可選，因此 Claude 能更快回應例行提示詞，並將更深入的思考保留給能從中受益的步驟。如果您希望 Claude 比目前等級產生的思考頻率更高或更低，可以直接在提示詞或 `CLAUDE.md` 中說明；模型會在其 effort 設定範圍內回應該指引。756自適應推理讓每個步驟的思考變為可選，因此 Claude 能更快回應例行提示詞，並將更深入的思考保留給能從中受益的步驟。如果您希望 Claude 比目前等級產生的思考頻率更高或更低，可以直接在提示詞或 `CLAUDE.md` 中說明；模型會在其 effort 設定範圍內回應該指引。

755 757

756Fable 模型、Sonnet 5 及更新版本，以及 Opus 4.7 及更新版本一律使用自適應推理。固定思考預算模式和 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 不適用於這些模型。758Fable 模型、Sonnet 5 及更新版本、Haiku 5.5，以及 Opus 4.7 及更新版本一律使用自適應推理。固定思考預算模式和 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 不適用於這些模型。

757 759

758在 Opus 4.6 和 Sonnet 4.6 上，您可以設定 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1`，以恢復由 `MAX_THINKING_TOKENS` 控制的先前固定思考預算。請參閱[環境變數](/docs/zh-TW/env-vars)。760在 Opus 4.6 和 Sonnet 4.6 上，您可以設定 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1`，以恢復由 `MAX_THINKING_TOKENS` 控制的先前固定思考預算。請參閱[環境變數](/docs/zh-TW/env-vars)。

759 761

767| :- | :- |769| :- | :- |

770| 透過環境變數停用 | 設定 [`MAX_THINKING_TOKENS=0`](/docs/zh-TW/env-vars)，這會在 Anthropic API 上關閉思考，但 Opus 5.5、Sonnet 5.5 和 Fable 模型除外。在[第三方供應商](/docs/zh-TW/third-party-integrations)上，Claude Code 會改為省略 `thinking` 參數，自適應推理模型仍可能進行思考 |772| 透過環境變數停用 | 設定 [`MAX_THINKING_TOKENS=0`](/docs/zh-TW/env-vars)，這會在 Anthropic API 上關閉思考，但 Opus 5.5、Sonnet 5.5、Haiku 5.5 和 Fable 模型除外。在[第三方供應商](/docs/zh-TW/third-party-integrations)上，Claude Code 會改為省略 `thinking` 參數，自適應推理模型仍可能進行思考 |

771 773

772您無法在 Opus 5.5、Sonnet 5.5 或 Fable 模型上關閉思考。對於這些模型，工作階段切換開關和 `/config` 列會顯示 `Thinking can't be turned off`，而不提供切換選項，且已儲存的 `alwaysThinkingEnabled: false` 或 `MAX_THINKING_TOKENS=0` 在這些模型上無效。在這些模型上，模型會根據 effort 等級決定每個步驟的思考量。當您切換至接受該設定的模型時，已儲存的設定會再次適用。774您無法在 Opus 5.5、Sonnet 5.5、Haiku 5.5 或 Fable 模型上關閉思考。對於這些模型，工作階段切換開關和 `/config` 列會顯示 `Thinking can't be turned off`，而不提供切換選項，且已儲存的 `alwaysThinkingEnabled: false` 或 `MAX_THINKING_TOKENS=0` 在這些模型上無效。在這些模型上，模型會根據 effort 等級決定每個步驟的思考量。當您切換至接受該設定的模型時，已儲存的設定會再次適用。

773 775

774Claude Code 預設會收合思考輸出。按 `Ctrl+O` 切換詳細模式，即可看到以灰色斜體文字顯示的推理。Anthropic API 上的互動式工作階段預設會收到經過編修的思考區塊，因此如果您希望展開時能看到完整摘要，請在[設定](/docs/zh-TW/settings)中設定 `showThinkingSummaries: true`。即使思考內容被收合或編修，您仍需為所有產生的思考 token 付費。776Claude Code 預設會收合思考輸出。按 `Ctrl+O` 切換詳細模式，即可看到以灰色斜體文字顯示的推理。Anthropic API 上的互動式工作階段預設會收到經過編修的思考區塊，因此如果您希望展開時能看到完整摘要，請在[設定](/docs/zh-TW/settings)中設定 `showThinkingSummaries: true`。即使思考內容被收合或編修，您仍需為所有產生的思考 token 付費。

775 777

779 延伸上下文781 延伸上下文

780</h3>782</h3>

781 783

782Fable 5.1、Fable 5、Sonnet 5 及更新版本、Opus 4.6 及更新版本，以及 Sonnet 4.6 支援 [100 萬 token 上下文視窗](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)，適用於處理大型程式碼庫的長時間工作階段。784Fable 5.1、Fable 5、Sonnet 5 及更新版本、Haiku 5.5、Opus 4.6 及更新版本，以及 Sonnet 4.6 支援 [100 萬 token 上下文視窗](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)，適用於處理大型程式碼庫的長時間工作階段。

783 785

784在 Anthropic API 上，Fable 5.1、Fable 5、Sonnet 5 及更新版本，以及 Opus 4.7 及更新版本在每個方案（包括 Pro）上都以 1M 視窗執行。在這些模型上，您不需要選擇 `[1m]` 變體，也不需要為 1M 視窗開啟用量點數。在某些方案上，Fable 的使用本身可能會計入用量點數；請參閱 [Fable 與用量點數](#fable-and-usage-credits)。786在 Anthropic API 上，Fable 5.1、Fable 5、Sonnet 5 及更新版本、Haiku 5.5，以及 Opus 4.7 及更新版本在每個方案（包括 Pro）上都以 1M 視窗執行。在這些模型上，您不需要選擇 `[1m]` 變體，也不需要為 1M 視窗開啟用量點數。在某些方案上，Fable 的使用本身可能會計入用量點數；請參閱 [Fable 與用量點數](#fable-and-usage-credits)。

785 787

786Opus 4.6 和 Sonnet 4.6 只能透過其 `[1m]` 變體達到 1M，而能否使用該變體取決於您的方案。在 Max、Team 和 Enterprise 方案上（包括 Team Standard 和 Team Premium 席位），具有 1M 上下文的 Opus 4.6 已包含在您的訂閱中。具有 1M 上下文的 Sonnet 4.6 在每個訂閱方案（包括 Max）上都需要[用量點數](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)。788Opus 4.6 和 Sonnet 4.6 只能透過其 `[1m]` 變體達到 1M，而能否使用該變體取決於您的方案。在 Max、Team 和 Enterprise 方案上（包括 Team Standard 和 Team Premium 席位），具有 1M 上下文的 Opus 4.6 已包含在您的訂閱中。具有 1M 上下文的 Sonnet 4.6 在每個訂閱方案（包括 Max）上都需要[用量點數](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)。

787 789

795 797

796<span id="context-window-behind-a-gateway" />798<span id="context-window-behind-a-gateway" />

797 799

798如果您將 `ANTHROPIC_BASE_URL` 設定為 [LLM 閘道](/docs/zh-TW/llm-gateway)或其他代理伺服器，Claude Code 會為它能識別的每個模型提供與該模型在 Anthropic API 上相同的上下文視窗。Fable 5.1、Fable 5、Sonnet 5 及更新版本，以及 Opus 4.7 及更新版本會取得 1M 視窗，無需選擇 `[1m]` 變體；而只能透過 `[1m]` 變體達到 1M 的模型（例如 Opus 4.6），在未使用該變體時會以 200K 執行。Claude Code 無法偵測閘道或其後方伺服器所強制執行的較低限制。如果您的閘道會拒絕超過 200K token 的請求，請在啟動 Claude Code 的環境中設定 [`CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000`](/docs/zh-TW/env-vars)，讓所有模型上的工作階段都[在該邊界進行壓縮](#set-the-auto-compact-window)。800如果您將 `ANTHROPIC_BASE_URL` 設定為 [LLM 閘道](/docs/zh-TW/llm-gateway)或其他代理伺服器，Claude Code 會為它能識別的每個模型提供與該模型在 Anthropic API 上相同的上下文視窗。Fable 5.1、Fable 5、Sonnet 5 及更新版本、Haiku 5.5，以及 Opus 4.7 及更新版本會取得 1M 視窗，無需選擇 `[1m]` 變體；而只能透過 `[1m]` 變體達到 1M 的模型（例如 Opus 4.6），在未使用該變體時會以 200K 執行。Claude Code 無法偵測閘道或其後方伺服器所強制執行的較低限制。如果您的閘道會拒絕超過 200K token 的請求，請在啟動 Claude Code 的環境中設定 [`CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000`](/docs/zh-TW/env-vars)，讓所有模型上的工作階段都[在該邊界進行壓縮](#set-the-auto-compact-window)。

799 801

800若要關閉 1M 上下文，請設定 `CLAUDE_CODE_DISABLE_1M_CONTEXT=1`。Claude Code 會從模型選擇器中移除 1M 模型變體。對於具有原生 1M 視窗的模型（例如 Sonnet 5 和 Fable 模型），它也會將該模型視為具有 200K 上下文視窗：802若要關閉 1M 上下文，請設定 `CLAUDE_CODE_DISABLE_1M_CONTEXT=1`。Claude Code 會從模型選擇器中移除 1M 模型變體。對於具有原生 1M 視窗的模型（例如 Sonnet 5 和 Fable 模型），它也會將該模型視為具有 200K 上下文視窗：

801 803

804 806

805在 v2.1.223 之前，Claude Code 只會將 Sonnet 5、Opus 4.8 和 Opus 5 工作階段限制在 200K。請參閱[環境變數](/docs/zh-TW/env-vars)。807在 v2.1.223 之前，Claude Code 只會將 Sonnet 5、Opus 4.8 和 Opus 5 工作階段限制在 200K。請參閱[環境變數](/docs/zh-TW/env-vars)。

806 808

8071M 上下文視窗採用標準模型定價，超過 200K 的 token 不收取額外費用。對於延伸上下文已包含在訂閱中的方案，用量仍由您的訂閱涵蓋。對於透過用量點數使用延伸上下文的方案，token 會計入用量點數。8091M 上下文視窗採用標準模型定價，超過 200K 的 token 不收取額外費用，但 Haiku 5.5 除外，其[提示詞超過 100K token 時費用較高](#haiku-5-5-context-window-and-pricing)。對於延伸上下文已包含在訂閱中的方案，用量仍由您的訂閱涵蓋。對於透過用量點數使用延伸上下文的方案，token 會計入用量點數。

808 810

809如果您的帳戶支援 1M 上下文，該選項會出現在最新版 Claude Code 的 `/model` 選擇器中。如果您沒有看到它，請重新啟動工作階段；若使用第三方供應商，請檢查您的部署是否已透過 `ANTHROPIC_DEFAULT_*_MODEL` 變數[釘選模型](#pin-models-for-third-party-deployments)。811如果您的帳戶支援 1M 上下文，該選項會出現在最新版 Claude Code 的 `/model` 選擇器中。如果您沒有看到它，請重新啟動工作階段；若使用第三方供應商，請檢查您的部署是否已透過 `ANTHROPIC_DEFAULT_*_MODEL` 變數[釘選模型](#pin-models-for-third-party-deployments)。

810 812

831 833

832* **`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`**：將所有具有原生 1M 視窗之模型的工作階段限制在 200K 視窗；關於如何強制執行此限制，請參閱[延伸上下文](#extended-context)。適用於需要限制上下文的部署。834* **`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`**：將所有具有原生 1M 視窗之模型的工作階段限制在 200K 視窗；關於如何強制執行此限制，請參閱[延伸上下文](#extended-context)。適用於需要限制上下文的部署。

833 835

836<h4 id="haiku-5-5-context-window-and-pricing">

837 Haiku 5.5 上下文視窗與定價

838</h4>

839

840在 Anthropic API 上，Haiku 5.5 在每個方案上都以 1M 上下文視窗執行，沒有需要選擇的 `[1m]` 後綴。其模型 ID 為 `claude-haiku-5-5`。若要使用它，請在工作階段中執行 `/model claude-haiku-5-5`，或從您的 shell 使用 `claude --model claude-haiku-5-5` 啟動 Claude Code。

841

842當 Haiku 5.5 請求的提示詞超過 100K token 時，每個 token 的費用較高。關於兩種費率，請參閱 [Anthropic 定價](https://platform.claude.com/docs/en/about-claude/pricing)。

843

844工作階段預設約在 967K token 時自動壓縮。若要更早壓縮，請為該模型[設定較小的自動壓縮視窗](#set-the-auto-compact-window)。

845

834<h2 id="context-window-and-auto-compaction">846<h2 id="context-window-and-auto-compaction">

835 上下文視窗與自動壓縮847 上下文視窗與自動壓縮

836</h2>848</h2>

865* [雲端工作階段](/docs/zh-TW/claude-code-on-the-web)會在對話接近模型限制時進行壓縮877* [雲端工作階段](/docs/zh-TW/claude-code-on-the-web)會在對話接近模型限制時進行壓縮

866* 未啟用[擴充上下文](#extended-context)的 Sonnet 4.6 與 Opus 4.6 會在 200K 邊界進行壓縮；Opus 4.8 及更新版本以 200K 上下文視窗執行時（例如在 Amazon Bedrock、Google Cloud 的 Agent Platform 與 Microsoft Foundry 上）也是如此878* 未啟用[擴充上下文](#extended-context)的 Sonnet 4.6 與 Opus 4.6 會在 200K 邊界進行壓縮；Opus 4.8 及更新版本以 200K 上下文視窗執行時（例如在 Amazon Bedrock、Google Cloud 的 Agent Platform 與 Microsoft Foundry 上）也是如此

867* 當您設定 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/zh-TW/env-vars) 時，具有原生 1M 視窗的模型（例如 Sonnet 5 與 Fable 模型）會在 200K 邊界進行壓縮879* 當您設定 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/zh-TW/env-vars) 時，具有原生 1M 視窗的模型（例如 Sonnet 5 與 Fable 模型）會在 200K 邊界進行壓縮

868* 以原生 1M 視窗執行的模型會在視窗填滿前進行壓縮，預設約為 967K token。在 Anthropic API 上，這些模型包括 Sonnet 5、Fable 模型，以及 Opus 4.7 及更新版本。在 Amazon Bedrock、Google Cloud 的 Agent Platform 與 Microsoft Foundry 上，哪些模型以該視窗執行，請參閱[為第三方部署固定模型](#pin-models-for-third-party-deployments)。若位於自訂 `ANTHROPIC_BASE_URL` 之後，請參閱[閘道後方的上下文視窗](#context-window-behind-a-gateway)880* 以原生 1M 視窗執行的模型會在視窗填滿前進行壓縮，預設約為 967K token。在 Anthropic API 上，這些模型包括 Sonnet 5、Haiku 5.5、Fable 模型，以及 Opus 4.7 及更新版本。在 Amazon Bedrock、Google Cloud 的 Agent Platform 與 Microsoft Foundry 上，哪些模型以該視窗執行，請參閱[為第三方部署固定模型](#pin-models-for-third-party-deployments)。若位於自訂 `ANTHROPIC_BASE_URL` 之後，請參閱[閘道後方的上下文視窗](#context-window-behind-a-gateway)

869* 使用 Claude Code 無法辨識之模型 ID（例如 [LLM 閘道](/docs/zh-TW/llm-gateway)別名）的工作階段，會在 Claude Code 為該 ID 假定的上下文視窗進行壓縮；請參閱[為閘道或自訂模型 ID 修正視窗](#correct-the-window-for-a-gateway-or-custom-model-id)881* 使用 Claude Code 無法辨識之模型 ID（例如 [LLM 閘道](/docs/zh-TW/llm-gateway)別名）的工作階段，會在 Claude Code 為該 ID 假定的上下文視窗進行壓縮；請參閱[為閘道或自訂模型 ID 修正視窗](#correct-the-window-for-a-gateway-or-custom-model-id)

870 882

871<h3 id="correct-the-window-for-a-gateway-or-custom-model-id">883<h3 id="correct-the-window-for-a-gateway-or-custom-model-id">

1094 1106

1095| 版本 | 變更 |1107| 版本 | 變更 |

1096| :- | :- |1108| :- | :- |

1109| v2.1.293 | 在 Anthropic API 上，`haiku` 解析為 Haiku 5.5 |

1097| v2.1.284 | 在 Anthropic API 上，`sonnet` 解析為 Sonnet 5.5 |1110| v2.1.284 | 在 Anthropic API 上，`sonnet` 解析為 Sonnet 5.5 |

1098| v2.1.280 | 在 Anthropic API、Claude Platform on AWS、Amazon Bedrock 及 Google Cloud's Agent Platform 上，`opus` 解析為 Opus 5.5 |1111| v2.1.280 | 在 Anthropic API、Claude Platform on AWS、Amazon Bedrock 及 Google Cloud's Agent Platform 上，`opus` 解析為 Opus 5.5 |

1099| v2.1.257 | `fable` 解析為 Fable 5.1，但 Claude apps 閘道工作階段除外 |1112| v2.1.257 | `fable` 解析為 Fable 5.1，但 Claude apps 閘道工作階段除外 |

1101| v2.1.207 | 在 Claude Platform on AWS、Amazon Bedrock 及 Agent Platform 上，`opus` 解析為 Opus 4.8 |1114| v2.1.207 | 在 Claude Platform on AWS、Amazon Bedrock 及 Agent Platform 上，`opus` 解析為 Opus 4.8 |

1102| v2.1.197 | 在 Anthropic API 上，`sonnet` 解析為 Sonnet 5 |1115| v2.1.197 | 在 Anthropic API 上，`sonnet` 解析為 Sonnet 5 |

1103| v2.1.154 | 在 Anthropic API 上，`opus` 解析為 Opus 4.8 |1116| v2.1.154 | 在 Anthropic API 上，`opus` 解析為 Opus 4.8 |

1104| 更早版本 | 在 Claude Platform on AWS 上，`opus` 解析為 Opus 4.7；在 Amazon Bedrock 及 Agent Platform 上則解析為 Opus 4.6。在所有供應商上，`fable` 皆解析為 Fable 5 |1117| 更早版本 | 在 Claude Platform on AWS 上，`opus` 解析為 Opus 4.7；在 Amazon Bedrock 及 Agent Platform 上則解析為 Opus 4.6。在所有供應商上，`fable` 皆解析為 Fable 5，`haiku` 皆解析為 Haiku 4.5 |

monitoring-usage.md +1 −1

Details

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

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

553 553

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

555 555

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

557 557

overview.md +6 −4

Details

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

29 ```29 ```

30 30

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

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

32 34

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

42 44

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

44 46

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

46 48

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

48 50

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

50 52

85 claude87 claude

86 ```88 ```

87 89

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

89 91

90 <Tip>92 <Tip>

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

171 </Accordion>173 </Accordion>

172 174

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

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

175 177

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

177 179

permission-modes.md +2 −2

Details

333 333

334* **計畫**：所有計畫。334* **計畫**：所有計畫。

335* **組織**：在 Team 和 Enterprise 上，自動模式預設可用。管理員可以透過在[受管設定](/docs/zh-TW/managed-settings)中將 `permissions.disableAutoMode` 設定為 `"disable"` 來為組織關閉它。335* **組織**：在 Team 和 Enterprise 上，自動模式預設可用。管理員可以透過在[受管設定](/docs/zh-TW/managed-settings)中將 `permissions.disableAutoMode` 設定為 `"disable"` 來為組織關閉它。

336* **模型**：在 Anthropic API 和 [AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws) 上，Claude Opus 4.6 或更新版本、Sonnet 4.6 或更新版本，或 [Fable 模型](/docs/zh-TW/model-config#work-with-fable)。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和已登入的 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway)工作階段上，僅限 Claude Sonnet 5 或更新版本、Opus 4.7 或更新版本和 Fable 模型。較舊的模型，包括 Sonnet 4.5、Opus 4.5、Haiku 和 claude-3 模型，在任何提供商上都不受支援。336* **模型**：在 Anthropic API 和 [AWS 上的 Claude Platform](/docs/zh-TW/claude-platform-on-aws) 上，Claude Opus 4.6 或更新版本、Sonnet 4.6 或更新版本、Haiku 5.5，或 [Fable 模型](/docs/zh-TW/model-config#work-with-fable)。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和已登入的 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway)工作階段上，僅限 Claude Sonnet 5 或更新版本、Opus 4.7 或更新版本、Haiku 5.5 和 Fable 模型。較舊的模型，包括 Sonnet 4.5、Opus 4.5、Haiku 4.5 和 claude-3 模型，在任何提供商上都不受支援。

337* **提供商**：在 Anthropic API、AWS 上的 Claude Platform、Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和已登入的 Claude 應用程式閘道工作階段上預設可用。337* **提供商**：在 Anthropic API、AWS 上的 Claude Platform、Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和已登入的 Claude 應用程式閘道工作階段上預設可用。

338 338

339如果 Claude Code 報告自動模式不可用，首先檢查這些要求以及任何設定檔是否設定了 [`disableAutoMode`](/docs/zh-TW/settings-reference#disableautomode)。Anthropic 也可能已在伺服器端關閉自動模式，或伺服器可能已為您的帳戶拒絕自動模式。收到任一答案的工作階段會保持自動模式關閉直到工作階段結束，因此請稍後啟動新工作階段。339如果 Claude Code 報告自動模式不可用，首先檢查這些要求以及任何設定檔是否設定了 [`disableAutoMode`](/docs/zh-TW/settings-reference#disableautomode)。Anthropic 也可能已在伺服器端關閉自動模式，或伺服器可能已為您的帳戶拒絕自動模式。收到任一答案的工作階段會保持自動模式關閉直到工作階段結束，因此請稍後啟動新工作階段。

348 348

349在 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-TW/google-vertex-ai)、[Microsoft Foundry](/docs/zh-TW/microsoft-foundry) 和已登入的 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway)工作階段上，自動模式預設可用。當沒有其他設定指定權限模式時，在該章節表格列出的版本上，它也是[內建起始權限模式](#which-mode-a-session-starts-in)。要自己選擇起始權限模式，請按照[以不同權限模式啟動](#start-in-a-different-mode)的說明設定 `permissions.defaultMode`，或從 VS Code 擴充功能的模式指示器中選擇權限模式。349在 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-TW/google-vertex-ai)、[Microsoft Foundry](/docs/zh-TW/microsoft-foundry) 和已登入的 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway)工作階段上，自動模式預設可用。當沒有其他設定指定權限模式時，在該章節表格列出的版本上，它也是[內建起始權限模式](#which-mode-a-session-starts-in)。要自己選擇起始權限模式，請按照[以不同權限模式啟動](#start-in-a-different-mode)的說明設定 `permissions.defaultMode`，或從 VS Code 擴充功能的模式指示器中選擇權限模式。

350 350

351這些提供商上僅支援 Claude Sonnet 5 或更新版本、Opus 4.7 或更新版本和 Fable 模型。在任何其他模型上，工作階段改為以手動模式啟動。351這些提供商上僅支援 Claude Sonnet 5 或更新版本、Opus 4.7 或更新版本、Haiku 5.5 和 Fable 模型。在任何其他模型上，工作階段改為以手動模式啟動。在這些提供商上搭配 Haiku 5.5 使用自動模式需要 Claude Code v2.1.293 或更新版本。

352 352

353要防止開發人員使用自動模式，請在[受管設定](/docs/zh-TW/managed-settings)中將 `disableAutoMode` 設定為 `"disable"`。這會從 `Shift+Tab` 循環中移除 `auto`，並且以 `--permission-mode auto` 啟動的工作階段改為以手動模式啟動。已在自動模式中執行的工作階段，在該設定從[管理員部署的來源](/docs/zh-TW/managed-settings#which-managed-source-claude-code-uses)送達該工作階段時會離開自動模式，並顯示 `auto mode disabled by settings`。在 v2.1.251 之前，執行中的工作階段會保持自動模式直到它結束。353要防止開發人員使用自動模式，請在[受管設定](/docs/zh-TW/managed-settings)中將 `disableAutoMode` 設定為 `"disable"`。這會從 `Shift+Tab` 循環中移除 `auto`，並且以 `--permission-mode auto` 啟動的工作階段改為以手動模式啟動。已在自動模式中執行的工作階段，在該設定從[管理員部署的來源](/docs/zh-TW/managed-settings#which-managed-source-claude-code-uses)送達該工作階段時會離開自動模式，並顯示 `auto mode disabled by settings`。在 v2.1.251 之前，執行中的工作階段會保持自動模式直到它結束。

354 354

plugin-evals.md +6 −2

Details

77 claude plugin eval init77 claude plugin eval init

78 ```78 ```

79 79

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

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

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

81 85

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

83 87

116 120

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

118 122

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

120 124

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

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

plugins/components.md +1 −1

Details

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

734```734```

735 735

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

737 737

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

739 739

plugins/mods/interface.md +5 −3

Details

428 428

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

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

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

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

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

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

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

564 564

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

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

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

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

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

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

571```571```

572 572

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

574

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

574 576

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

plugins/mods/reference.md +23 −2

Details

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

243 243

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

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

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

247 247

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

255 255

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

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

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

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

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

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

270 270

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

272 272

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

274 `Box` 框線樣式

275</h3>

276

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

278

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

280| :- | :- | :- |

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

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

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

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

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

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

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

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

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

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

291

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

293

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

274 限制295 限制

275</h2>296</h2>

plugins/troubleshooting.md +1 −0

Details

17 17

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

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

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

20</Note>21</Note>

21 22

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

prompt-caching.md +35 −35

Details

14 快取的組織方式14 快取的組織方式

15</h2>15</h2>

16 16

17每次您在 Claude Code 中傳送訊息時，它都會發出新的 API 請求。模型在請求之間不會記住任何內容，因此 Claude Code 會重新傳送完整的上下文：系統提示、您的專案上下文、每個先前的訊息和工具結果，以及您的新訊息。新內容會附加在末尾，這表示每個請求的大部分內容與前一個請求相同。Prompt caching 是 API 避免重新處理未變更部分的方式。17每次您在 Claude Code 中傳送訊息時，它都會發出新的 API 請求。模型在請求之間不會記住任何內容，因此 Claude Code 會重新傳送完整的上下文：系統提示詞、您的專案上下文、每個先前的訊息和工具結果，以及您的新訊息。新內容會附加在末尾，這表示每個請求的大部分內容與前一個請求相同。提示快取是 API 避免重新處理未變更部分的方式。

18 18

19API 透過將每個請求的開始部分（稱為前綴）與最近處理的內容進行比對來進行快取。在正常的回合中，前綴是整個先前的請求，只有最新的交換是新的。比對是精確的，因此前綴中任何地方的變更都會重新計算其後的所有內容。沒有按檔案或按區段的快取。請參閱 API 參考中的 [prompt caching 如何運作](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#how-prompt-caching-works)以了解基礎機制。19API 透過將每個請求的開始部分（稱為前綴）與最近處理的內容進行比對來進行快取。在正常的回合中，前綴是整個先前的請求，只有最新的交換是新的。比對是精確的，因此前綴中任何地方的變更都會重新計算其後的所有內容。沒有按檔案或按區段的快取。請參閱 API 參考中的[提示快取如何運作](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#how-prompt-caching-works)以了解基礎機制。

20 20

21<img src="https://mintcdn.com/claude-code/VbDJw--l6T9a9Wvm/images/prompt-caching-prefix.svg?fit=max&auto=format&n=VbDJw--l6T9a9Wvm&q=85&s=f2e8f0b8298a50305fe428ca3f1d1594" className="dark:hidden" alt="四個回合顯示為不斷增長的水平條。每個回合的請求包含前一個回合的所有內容加上末尾附加的最新交換。在第二和第三個回合中，未變更的前綴從快取中讀取，只有新的交換被處理。在第四個回合中，系統提示已變更，因此前綴不再比對，整個請求被重新處理並寫入。" width="720" height="454" data-path="images/prompt-caching-prefix.svg" />21<img src="https://mintcdn.com/claude-code/VbDJw--l6T9a9Wvm/images/prompt-caching-prefix.svg?fit=max&auto=format&n=VbDJw--l6T9a9Wvm&q=85&s=f2e8f0b8298a50305fe428ca3f1d1594" className="dark:hidden" alt="四個回合顯示為不斷增長的水平條。每個回合的請求包含前一個回合的所有內容加上末尾附加的最新交換。在第二和第三個回合中，未變更的前綴從快取中讀取，只有新的交換被處理。在第四個回合中，系統提示詞已變更，因此前綴不再比對，整個請求被重新處理並寫入。" width="720" height="454" data-path="images/prompt-caching-prefix.svg" />

22 22

23<img src="https://mintcdn.com/claude-code/_xqph1dUOslCOwsj/images/prompt-caching-prefix-dark.svg?fit=max&auto=format&n=_xqph1dUOslCOwsj&q=85&s=297dc1c639f0915cae858d0c4b6f3be5" className="hidden dark:block" alt="四個回合顯示為不斷增長的水平條。每個回合的請求包含前一個回合的所有內容加上末尾附加的最新交換。在第二和第三個回合中，未變更的前綴從快取中讀取，只有新的交換被處理。在第四個回合中，系統提示已變更，因此前綴不再比對，整個請求被重新處理並寫入。" width="720" height="454" data-path="images/prompt-caching-prefix-dark.svg" />23<img src="https://mintcdn.com/claude-code/_xqph1dUOslCOwsj/images/prompt-caching-prefix-dark.svg?fit=max&auto=format&n=_xqph1dUOslCOwsj&q=85&s=297dc1c639f0915cae858d0c4b6f3be5" className="hidden dark:block" alt="四個回合顯示為不斷增長的水平條。每個回合的請求包含前一個回合的所有內容加上末尾附加的最新交換。在第二和第三個回合中，未變更的前綴從快取中讀取，只有新的交換被處理。在第四個回合中，系統提示詞已變更，因此前綴不再比對，整個請求被重新處理並寫入。" width="720" height="454" data-path="images/prompt-caching-prefix-dark.svg" />

24 24

25為了充分利用前綴比對，Claude Code 會組織每個請求，使得在回合之間很少變更的內容優先出現：25為了充分利用前綴比對，Claude Code 會組織每個請求，使得在回合之間很少變更的內容優先出現：

26 26

27| 層級 | 內容 | 變更時機 |27| 層級 | 內容 | 變更時機 |

28| - | - | - |28| - | - | - |

31| 對話 | 您的訊息、Claude 的回應、工具結果 | 每個回合 |31| 對話 | 您的訊息、Claude 的回應、工具結果 | 每個回合 |

32 32

33對對話層的變更會保留系統提示和專案上下文的快取。對系統提示的變更會使所有內容失效，因為所有後續內容現在位於不同的前綴後面。第三欄提供常見的觸發器，而不是詳盡的清單，下面的章節涵蓋完整的集合。33對對話層的變更會保留系統提示詞和專案上下文的快取。對系統提示詞的變更會使所有內容失效，因為所有後續內容現在位於不同的前綴後面。第三欄提供常見的觸發器，而不是詳盡的清單，下面的章節涵蓋完整的集合。

34 34

35前綴比對規則解釋了此頁面上的大多數行為。例如，[Plan Mode](/docs/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 和 [skill loading](/docs/zh-TW/skills) 會將其指示附加為對話訊息，因此快取的前綴保持完整。35前綴比對規則解釋了此頁面上的大多數行為。例如，[plan mode](/docs/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 和 [skill loading](/docs/zh-TW/skills) 會將其指示附加為對話訊息，因此快取的前綴保持完整。

36 36

37有兩個設定不會出現在層級表中，但仍會影響保留的快取內容：37有兩個設定不會出現在層級表中，但仍會影響保留的快取內容：

38 38

39* **Model**：每個模型都有自己的快取。切換模型會重新計算整個請求，即使內容相同。請參閱下面的 [Switching models](#switching-models)。39* **Model**：每個模型都有自己的快取。切換模型會重新計算整個請求，即使內容相同。請參閱下面的 [Switching models](#switching-models)。

40* **Effort level**：在大多數模型上，每個 effort level 都有自己的快取，因此在工作階段中途變更 effort 會重新計算整個請求。在具有 API 金鑰或 Claude 訂閱的 Opus 5.5、Sonnet 5.5 和 Fable 5.1 上，快取預設保持完整。請參閱下面的 [Changing effort level](#changing-effort-level)。40* **Effort 等級**：在大多數模型上，每個 effort 等級都有自己的快取，因此在工作階段中途變更 effort 會重新計算整個請求。在具有 API 金鑰或 Claude 訂閱的 Opus 5.5、Sonnet 5.5、Haiku 5.5 和 Fable 5.1 上，快取預設保持完整。請參閱下面的 [Changing effort level](#changing-effort-level)。

41 41

42<Tip>42<Tip>

~~43 在工作階段的開始選擇您的模型和 effort level，然後在任務之間的自然中斷處保存 `/compact`。您在任務中途進行的變更越少，快取命中率就越高。~~43 在工作階段的開始選擇您的模型和 effort 等級，然後將 `/compact` 留到任務之間的自然中斷處使用。您在任務中途進行的變更越少，快取命中率就越高。

44</Tip>44</Tip>

45 45

46<h3 id="where-the-cache-lives">46<h3 id="where-the-cache-lives">

58 58

59在提供者自己的端點、Amazon Bedrock 及其 [Mantle endpoint](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint)、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，快取該區塊的方式與 Claude API 相同。59在提供者自己的端點、Amazon Bedrock 及其 [Mantle endpoint](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint)、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，快取該區塊的方式與 Claude API 相同。

60 60

61當您的請求通過 [LLM gateway](/docs/zh-TW/llm-gateway)、自訂 `ANTHROPIC_BASE_URL` 或雲端提供者基礎 URL 覆蓋（例如 [`ANTHROPIC_BEDROCK_BASE_URL`](/docs/zh-TW/env-vars)）時，保留的快取取決於閘道如何處理 Claude Code 傳送的 [`cache_control` 標記](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#explicit-cache-breakpoints)：61當您的請求通過 [LLM gateway](/docs/zh-TW/llm-gateway)、自訂 `ANTHROPIC_BASE_URL` 或雲端提供者基礎 URL 覆寫（例如 [`ANTHROPIC_BEDROCK_BASE_URL`](/docs/zh-TW/env-vars)）時，保留的快取取決於閘道如何處理 Claude Code 傳送的 [`cache_control` 標記](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#explicit-cache-breakpoints)：

62 62

63* **原封不動地轉發它們**：該區塊和您的對話快取方式與在提供者自己的端點上相同。63* **原封不動地轉發它們**：該區塊和您的對話快取方式與在提供者自己的端點上相同。

64* **以命名 `cache_control` 的 `400` 錯誤拒絕標記的請求**：Claude Code 會重新傳送請求，將標記從區塊移到您的最後一條對話訊息上，並在對話的其餘部分保持在那裡。該區塊計費為未快取的輸入；您的對話保持快取。64* **以命名 `cache_control` 的 `400` 錯誤拒絕標記的請求**：Claude Code 會重新傳送請求，將標記從區塊移到您的最後一條對話訊息上，並在對話的其餘部分保持在那裡。該區塊計費為未快取的輸入；您的對話保持快取。

73這些動作會導致下一個請求遺漏部分或全部快取。您會看到一次較慢、成本較高的回合，之後新的前綴會被快取。一旦您知道它們有成本，大多數動作在任務進行中是可以避免的。模型切換可能感覺沒有成本，直到您注意到隨後的較慢回合。73這些動作會導致下一個請求遺漏部分或全部快取。您會看到一次較慢、成本較高的回合，之後新的前綴會被快取。一旦您知道它們有成本，大多數動作在任務進行中是可以避免的。模型切換可能感覺沒有成本，直到您注意到隨後的較慢回合。

74 74

75* [切換模型](#switching-models)75* [切換模型](#switching-models)

~~76* [變更努力程度](#changing-effort-level)~~76* [變更 effort 等級](#changing-effort-level)

77* [開啟快速模式](#turning-on-fast-mode)77* [開啟快速模式](#turning-on-fast-mode)

78* [連接或移除 MCP 伺服器](#connecting-or-removing-an-mcp-server)78* [連接或移除 MCP 伺服器](#connecting-or-removing-an-mcp-server)

79* [啟用或停用外掛程式](#enabling-or-disabling-a-plugin)79* [啟用或停用外掛程式](#enabling-or-disabling-a-plugin)

88 88

89每個模型都有自己的快取。使用 [`/model`](/docs/zh-TW/model-config#setting-your-model) 切換意味著下一個請求會讀取整個對話歷史記錄而沒有快取命中，即使內容相同。89每個模型都有自己的快取。使用 [`/model`](/docs/zh-TW/model-config#setting-your-model) 切換意味著下一個請求會讀取整個對話歷史記錄而沒有快取命中，即使內容相同。

90 90

91當您在終端執行 `/model` 時，Claude Code 會要求您確認切換，但僅限於快取仍然溫暖且新模型不是產生最後一個回應的模型時。快取在 Claude Code 在此對話中最後一次傳送請求或 Claude 最後一次回應後的一個[快取 TTL](#cache-lifetime) 內保持溫暖。一旦該時間過去，快取就會過期，因此 Claude Code 會在不詢問的情況下進行切換。91當您在終端機執行 `/model` 時，Claude Code 會要求您確認切換，但僅限於快取仍然溫暖且新模型不是產生最後一個回應的模型時。快取在 Claude Code 在此對話中最後一次傳送請求或 Claude 最後一次回應後的一個[快取 TTL](#cache-lifetime) 內保持溫暖。一旦該時間過去，快取就會過期，因此 Claude Code 會在不詢問的情況下進行切換。

92 92

93在 v2.1.238 之前，Claude Code 沒有檢查快取 TTL，即使在快取過期後也會詢問。93在 v2.1.238 之前，Claude Code 沒有檢查快取 TTL，即使在快取過期後也會詢問。

94 94

95您也可以使用 [PreModelSwitch hook](/docs/zh-TW/hooks#premodelswitch-decision-control) 要求此確認或跳過它。95您也可以使用 [PreModelSwitch hook](/docs/zh-TW/hooks#premodelswitch-decision-control) 要求此確認或跳過它。

96 96

97[`opusplan` 模型設定](/docs/zh-TW/model-config#opusplan-model-setting)在計畫模式期間解析為 Opus，在執行期間解析為 Sonnet，因此每次計畫模式切換都是模型切換並啟動新的快取。97[`opusplan` 模型設定](/docs/zh-TW/model-config#opusplan-model-setting)在 plan mode 期間解析為 Opus，在執行期間解析為 Sonnet，因此每次 plan mode 切換都是模型切換並啟動新的快取。

98 98

99[自動模型回退](/docs/zh-TW/model-config#automatic-model-fallback)在 Fable 模型、Opus 5.5、Sonnet 5.5 和 Opus 5 上也是模型切換。當安全分類器在具有回退模型的類別中標記請求時，Claude Code 會在該模型上重新執行請求，並且工作階段會在那裡繼續。99[自動模型備援](/docs/zh-TW/model-config#automatic-model-fallback)在 Fable 模型、Opus 5.5、Sonnet 5.5 和 Opus 5 上也是模型切換。當安全分類器在具有備援模型的類別中標記請求時，Claude Code 會在該模型上重新執行請求，並且工作階段會在那裡繼續。

100 100

101當技能或命令的前置資料命名一個[`model`](/docs/zh-TW/skills#frontmatter-reference)不同於工作階段目前模型時，該回合也是模型切換：下一個請求會讀取整個對話歷史記錄而沒有快取命中。工作階段模型會在您的下一個提示時繼續。`context: fork` 技能會設定[分叉子代理的模型](/docs/zh-TW/skills#run-skills-in-a-subagent)。101當 skill 或命令的 frontmatter 指定的 [`model`](/docs/zh-TW/skills#frontmatter-reference) 不同於工作階段目前模型時，該回合也是模型切換：下一個請求會讀取整個對話歷史記錄而沒有快取命中。工作階段模型會在您的下一個提示詞時恢復。`context: fork` skill 則會改為設定[分叉 subagent 的模型](/docs/zh-TW/skills#run-skills-in-a-subagent)。

102 102

103<h3 id="changing-effort-level">103<h3 id="changing-effort-level">

104 變更努力程度104 變更 effort 等級

105</h3>105</h3>

106 106

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

108 108

109在具有 API 金鑰或 Claude 訂閱的 Opus 5.5、Sonnet 5.5 和 Fable 5.1 上，變更努力程度會保留快取，Claude Code 會在不詢問的情況下套用新的程度。這不適用於 Amazon Bedrock、Google Cloud 的 Agent Platform 或 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway)，或當您設定 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/zh-TW/llm-gateway-protocol#disable-pre-release-capabilities) 或您的組織具有 HIPAA 設定時。109在具有 API 金鑰或 Claude 訂閱的 Opus 5.5、Sonnet 5.5、Haiku 5.5 和 Fable 5.1 上，變更 effort 會保留快取，Claude Code 會在不詢問的情況下套用新的等級。這不適用於 Amazon Bedrock、Google Cloud 的 Agent Platform 或 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway)，或當您設定 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/zh-TW/llm-gateway-protocol#disable-pre-release-capabilities) 或您的組織具有 HIPAA 設定時。

110 110

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

112 112

113<h3 id="turning-on-fast-mode">113<h3 id="turning-on-fast-mode">

114 開啟快速模式114 開啟快速模式

115</h3>115</h3>

116 116

117啟用[快速模式](/docs/zh-TW/fast-mode)會新增一個請求標頭，該標頭是快取金鑰的一部分，因此 Claude Code 傳送的第一個啟用快速模式的請求會讀取整個對話歷史記錄而沒有快取命中。Claude Code 在回合開始時設定該標頭一次，並為整個回合保留它，因此當您在 Claude 工作時開啟快速模式時，標頭的快取遺漏會在您下一個回合的第一個請求時發生。這些未快取的輸入令牌按[快速模式費率](/docs/zh-TW/fast-mode#understand-the-cost-tradeoff)計費，這就是為什麼在工作階段開始時開啟它的成本比在長工作階段深處開啟它的成本要低。如果您目前的模型不支援快速模式，啟用快速模式也會[切換您的模型](#switching-models)，該切換本身會從執行回合中的下一個請求開始啟動新的快取。117啟用[快速模式](/docs/zh-TW/fast-mode)會新增一個請求標頭，該標頭是快取金鑰的一部分，因此 Claude Code 傳送的第一個啟用快速模式的請求會讀取整個對話歷史記錄而沒有快取命中。Claude Code 在回合開始時設定該標頭一次，並為整個回合保留它，因此當您在 Claude 工作時開啟快速模式時，標頭的快取遺漏會在您下一個回合的第一個請求時發生。這些未快取的輸入 token 按[快速模式費率](/docs/zh-TW/fast-mode#understand-the-cost-tradeoff)計費，這就是為什麼在工作階段開始時開啟它的成本比在長工作階段深處開啟它的成本要低。如果您目前的模型不支援快速模式，啟用快速模式也會[切換您的模型](#switching-models)，該切換本身會從執行回合中的下一個請求開始啟動新的快取。

118 118

119成本每個對話應用一次。在第一個快速模式回合之後，Claude Code 會繼續傳送標頭，並且僅改變請求的速度設定，這不是快取金鑰的一部分。關閉快速模式、[達到速率限制後自動回退到標準速度](/docs/zh-TW/fast-mode#handle-rate-limits)以及稍後重新開啟都會保留快取。如果您[在工作階段中途用完使用額度](/docs/zh-TW/fast-mode#handle-rate-limits)，Claude Code 會以相同方式在標準速度下重試每個被拒絕的快速模式請求，因此此回退也會保留快取。`/clear` 和 `/compact` 會重設此設定，因為它們無論如何都會在這些點重建快取。119成本每個對話應用一次。在第一個快速模式回合之後，Claude Code 會繼續傳送標頭，並且僅改變請求的速度設定，這不是快取金鑰的一部分。關閉快速模式、[達到速率限制後自動改用標準速度](/docs/zh-TW/fast-mode#handle-rate-limits)以及稍後重新開啟都會保留快取。如果您[在工作階段中途用完用量點數](/docs/zh-TW/fast-mode#handle-rate-limits)，Claude Code 會以相同方式在標準速度下重試每個被拒絕的快速模式請求，因此此備援也會保留快取。`/clear` 和 `/compact` 會重設此設定，因為它們無論如何都會在這些點重建快取。

120 120

121<h3 id="connecting-or-removing-an-mcp-server">121<h3 id="connecting-or-removing-an-mcp-server">

122 連接或移除 MCP 伺服器122 連接或移除 MCP 伺服器

123</h3>123</h3>

124 124

125工具定義位於系統提示層，因此當請求中的工具定義集合在回合之間變更時，快取會失效。切換[顧問工具](/docs/zh-TW/advisor)是一個例外：其定義位於快取中斷點之後，因此啟用或停用 `/advisor` 會保留快取的前綴完整。[MCP 伺服器](/docs/zh-TW/mcp)變更是否執行此操作取決於[工具搜尋](/docs/zh-TW/mcp#scale-with-mcp-tool-search)是否延遲工作階段的 MCP 工具，在支援的模型上為預設值：125工具定義位於系統提示詞層，因此當請求中的工具定義集合在回合之間變更時，快取會失效。切換[顧問工具](/docs/zh-TW/advisor)是一個例外：其定義位於快取中斷點之後，因此啟用或停用 `/advisor` 會保留快取的前綴完整。[MCP 伺服器](/docs/zh-TW/mcp)變更是否執行此操作取決於[工具搜尋](/docs/zh-TW/mcp#scale-with-mcp-tool-search)是否延遲工作階段的 MCP 工具，在支援的模型上為預設值：

126 126

127* **工具延遲**：Claude Code 會為整個對話保留對話第一個請求中的工具清單，因此伺服器在工作階段中途連接或斷開不會擾亂已快取的任何內容。在第一個請求後完成連接的伺服器會提供其工具作為延遲定義，Claude 會按需載入。127* **工具延遲**：Claude Code 會為整個對話保留對話第一個請求中的工具清單，因此伺服器在工作階段中途連接或斷開不會擾亂已快取的任何內容。在第一個請求後完成連接的伺服器會提供其工具作為延遲定義，Claude 會按需載入。

128* **工具載入到前綴中**：新增定義會使快取失效，移除定義也會如此。這發生在[工具搜尋低於其 `auto` 閾值、已停用或不可用](/docs/zh-TW/mcp#configure-tool-search)時，例如在早於 Claude 4.5 世代的 Google Cloud Agent Platform 模型上、使用自訂 `ANTHROPIC_BASE_URL` 閘道或在 Microsoft Foundry [部署在 Azure 上](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)一旦 Claude Code 偵測到部署拒絕工具搜尋時。128* **預先載入工具**：新增定義會使快取失效，刻意移除定義也會如此。這適用於[工具搜尋低於其 `auto` 閾值、已停用或不可用](/docs/zh-TW/mcp#configure-tool-search)時，例如在早於 Claude 4.5 世代的 Google Cloud Agent Platform 模型上、使用自訂 `ANTHROPIC_BASE_URL` 閘道，或在 Microsoft Foundry [託管於 Azure 的部署](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)上且 Claude Code 偵測到該部署拒絕工具搜尋時。

129 129

130在沒有工具搜尋的情況下，工作階段中途的伺服器變更是否使快取失效取決於變更的內容。對於每個變更，此表格說明快取是否保留以及下一個請求中工具定義會發生什麼。130在沒有工具搜尋的情況下，工作階段中途的伺服器變更是否使快取失效取決於變更的內容。對於每個變更，此表格說明快取是否保留以及下一個請求中工具定義會發生什麼。

131 131

136| 遠端伺服器在連接斷開後[自動重新連接](/docs/zh-TW/mcp#automatic-reconnection) | 已保留，除非在伺服器重新連接時傳送的請求新增 `WaitForMcpServers` 工具，這會使快取失效一次 | 伺服器的定義保持不變。在伺服器重新連接時傳送的請求可以在對話尚未列出時新增 `WaitForMcpServers`，然後該工具會在對話的其餘部分保持列出 |136| 遠端伺服器在連接斷開後[自動重新連接](/docs/zh-TW/mcp#automatic-reconnection) | 已保留，除非在伺服器重新連接時傳送的請求新增 `WaitForMcpServers` 工具，這會使快取失效一次 | 伺服器的定義保持不變。在伺服器重新連接時傳送的請求可以在對話尚未列出時新增 `WaitForMcpServers`，然後該工具會在對話的其餘部分保持列出 |

137| 您故意移除工具，例如使用[拒絕規則](#denying-an-entire-tool)或在 `/mcp` 中停用其伺服器 | 已失效 | 定義已移除 |137| 您故意移除工具，例如使用[拒絕規則](#denying-an-entire-tool)或在 `/mcp` 中停用其伺服器 | 已失效 | 定義已移除 |

138 138

139當您繼續其工具載入到前綴中的對話時，其中一個 MCP 伺服器仍然可以在第一個請求發出時進行連接。如果文字記錄記錄了該伺服器的工具定義，該請求會按記錄的方式包含它們，因此當伺服器以相同工具完成連接時不會變更。139當您繼續其工具載入到前綴中的對話時，其中一個 MCP 伺服器仍然可以在第一個請求發出時進行連接。如果逐字稿記錄了該伺服器的工具定義，該請求會按記錄的方式包含它們，因此當伺服器以相同工具完成連接時不會變更。

140 140

141編輯您的 MCP 設定本身不會變更快取。新設定只有在重新啟動後才會生效，這是伺服器連接或斷開的時候。141編輯您的 MCP 設定本身不會變更快取。新設定只有在重新啟動後才會生效，這是伺服器連接或斷開的時候。

142 142

150 保留快取的外掛程式元件150 保留快取的外掛程式元件

151</h4>151</h4>

152 152

153Claude Code 永遠不會使外掛程式的技能、命令、代理、hooks、監視器或主題的快取失效。它會在現有對話之後附加其內容，因此下一個請求會為該內容付費，並且仍然會從快取中讀取其之前的所有內容。153Claude Code 永遠不會因外掛程式的 skill、命令、agent、hook、監視器或主題而使快取失效。它會在現有對話之後附加其內容，因此下一個請求會為該內容付費，並且仍然會從快取中讀取其之前的所有內容。

154 154

155<h4 id="plugins-that-provide-mcp-servers">155<h4 id="plugins-that-provide-mcp-servers">

156 提供 MCP 伺服器的外掛程式156 提供 MCP 伺服器的外掛程式

177 177

178當 `/reload-plugins` 執行且重新載入會觸發完整重新讀取時，Claude Code 會顯示警告且不套用重新載入。執行 `/reload-plugins --force` 以無論如何套用它。178當 `/reload-plugins` 執行且重新載入會觸發完整重新讀取時，Claude Code 會顯示警告且不套用重新載入。執行 `/reload-plugins --force` 以無論如何套用它。

179 179

180`/reload-plugins` 也在沒有互動式終端的工作階段中執行，例如桌面應用程式、Agent SDK 和[非互動式模式](/docs/zh-TW/headless)搭配 `-p`，當您直接將其輸入工作階段時。需要 Claude Code v2.1.260 或更新版本。180`/reload-plugins` 也在沒有互動式終端機的工作階段中執行，例如桌面應用程式、Agent SDK 和搭配 `-p` 的[非互動模式](/docs/zh-TW/headless)，當您直接將其輸入工作階段時。需要 Claude Code v2.1.260 或更新版本。

181 181

182在這些工作階段中，重新載入會套用除了外掛程式 MCP 伺服器變更之外的所有內容，這些變更[在您的下一個工作階段中生效](/docs/zh-TW/plugins/cli-reference#reload-plugins)，因此永遠不會在工作階段中途造成完整重新讀取的成本。182在這些工作階段中，重新載入會套用除了外掛程式 MCP 伺服器變更之外的所有內容，這些變更[在您的下一個工作階段中生效](/docs/zh-TW/plugins/cli-reference#reload-plugins)，因此永遠不會在工作階段中途造成完整重新讀取的成本。

183 183

191 拒絕整個工具191 拒絕整個工具

192</h3>192</h3>

193 193

194新增裸工具名稱（如 `Bash` 或 `WebFetch`）作為[拒絕規則](/docs/zh-TW/permissions#manage-permissions)，Claude 無法從您的下一個請求開始呼叫該工具，無論您是通過 `/permissions` 新增規則還是通過[直接編輯設定檔](/docs/zh-TW/settings#when-edits-take-effect)。這包括您在回合中途通過 `/permissions` 新增的規則。194如果您新增裸工具名稱（如 `Bash` 或 `WebFetch`）作為[拒絕規則](/docs/zh-TW/permissions#manage-permissions)，Claude 從您的下一個請求開始便無法呼叫該工具，無論您是通過 `/permissions` 新增規則還是通過[直接編輯設定檔](/docs/zh-TW/settings#when-edits-take-effect)。這包括您在回合中途通過 `/permissions` 新增的規則。

195 195

196當[工具搜尋](/docs/zh-TW/mcp#scale-with-mcp-tool-search)處於活動狀態時（在支援的模型上為預設值），請求的工具定義不會變更，快取的前綴會保留。當工具搜尋不可用或已停用時，Claude Code 會從下一個請求中移除定義，這會使快取失效，稍後移除規則也會如此。196當[工具搜尋](/docs/zh-TW/mcp#scale-with-mcp-tool-search)處於活動狀態時（在支援的模型上為預設值），請求的工具定義不會變更，快取的前綴會保留。當工具搜尋不可用或已停用時，Claude Code 會從下一個請求中移除定義，這會使快取失效，稍後移除規則也會如此。

197 197

198只有在工具名稱位置相符的拒絕規則才有此效果：裸工具名稱、等效的 `Bash(*)` 形式或[工具名稱 glob](/docs/zh-TW/permissions#tool-name-wildcards)（如 `"*"`）。與只有 MCP 工具相符的 glob（如 `"mcp__*"`）會以相同方式阻止這些工具。範圍拒絕規則（如 `Bash(rm *)`）以及所有允許和詢問規則都不會變更 Claude 看到的工具。Claude Code 在 Claude 嘗試呼叫時檢查它們，保留前綴完整。198只有在工具名稱位置相符的拒絕規則才會以此方式封鎖工具：裸工具名稱、等效的 `Bash(*)` 形式或[工具名稱 glob](/docs/zh-TW/permissions#tool-name-wildcards)（如 `"*"`）。只與 MCP 工具相符的 glob（如 `"mcp__*"`）會以相同方式封鎖這些工具。範圍拒絕規則（如 `Bash(rm *)`）以及所有允許和詢問規則都不會變更 Claude 看到的工具。Claude Code 在 Claude 嘗試呼叫時檢查它們，保留前綴完整。

199 199

200<h3 id="compacting-the-conversation">200<h3 id="compacting-the-conversation">

201 壓縮對話201 壓縮對話

202</h3>202</h3>

203 203

204[壓縮](/docs/zh-TW/context-window#what-survives-compaction)會用摘要取代您的訊息歷史記錄。根據設計，這會使對話層失效，因為下一個請求具有新的、較短的歷史記錄，不與舊歷史記錄共享前綴。Claude Code 會重複使用系統提示層，除非對話是[在保留會以其他方式變更的系統提示的同時繼續](#resuming-a-session)；在這種情況下，第一次壓縮會切換到目前提示，該層會重建一次。它會從磁碟重新載入專案內容，只有在工作階段開始以來 CLAUDE.md 和記憶未變更時才會快取命中。204[壓縮](/docs/zh-TW/context-window#what-survives-compaction)會用摘要取代您的訊息歷史記錄。根據設計，這會使對話層失效，因為下一個請求具有新的、較短的歷史記錄，不與舊歷史記錄共享前綴。Claude Code 會重複使用系統提示詞層，除非對話是[在保留原本會變更的系統提示詞的情況下繼續](#resuming-a-session)；在這種情況下，第一次壓縮會切換到目前的提示詞，該層會重建一次。它會從磁碟重新載入專案上下文，只有在工作階段開始以來 CLAUDE.md 和記憶未變更時才會快取命中。

205 205

206為了產生摘要，Claude Code 會傳送一個單獨的請求，其中包含與您的對話相同的系統提示、工具和歷史記錄，加上作為最終使用者訊息附加的摘要指令。當快取溫暖時，該請求會從快取讀取您的前綴，因此工作階段中途的 `/compact` 成本是內容大小建議的一小部分，並且大部分時間花在產生摘要上。206為了產生摘要，Claude Code 會傳送一個單獨的請求，其中包含與您的對話相同的系統提示詞、工具和歷史記錄，加上作為最終使用者訊息附加的摘要指令。當快取溫暖時，該請求會從快取讀取您的前綴，因此工作階段中途的 `/compact` 成本只是上下文大小所暗示的一小部分，並且大部分時間花在產生摘要上。

207 207

208在超過[快取生命週期](#cache-lifetime)的中斷後，沒有快取可讀取，因此摘要請求會將完整歷史記錄重新處理為未快取的輸入。這就是為什麼當您[繼續舊工作階段](/docs/zh-TW/sessions#resume-from-a-summary)時 `/compact` 成本最高。在溫暖和冷的情況下，壓縮後的回合只會為更短的摘要重建對話快取，因此該回合不是較慢的部分。208在超過[快取生命週期](#cache-lifetime)的中斷後，沒有快取可讀取，因此摘要請求會將完整歷史記錄重新處理為未快取的輸入。這就是為什麼當您[繼續舊工作階段](/docs/zh-TW/sessions#resume-from-a-summary)時 `/compact` 成本最高。在溫暖和冷的情況下，壓縮後的回合只會為更短的摘要重建對話快取，因此該回合不是較慢的部分。

209 209

210<Tip>210<Tip>

211 當您捨棄的內容是您不再需要的內容時，壓縮對您有利。為了選擇其開銷何時發生，請在工作的自然中斷處（例如任務之間）執行 `/compact`，而不是等待自動壓縮在任務中途觸發。如果您走上了想要完全放棄的路徑，請改為[`/rewind`](#rewinding-the-conversation)到較早的回合。重新開始會截斷回到已快取的前綴，而不是像壓縮那樣建立新的前綴。211 當您捨棄的上下文是您不再需要的內容時，壓縮對您有利。為了選擇其開銷何時發生，請在工作的自然中斷處（例如任務之間）執行 `/compact`，而不是等待自動壓縮在任務中途觸發。如果您走上了想要完全放棄的路徑，請改為使用 [`/rewind`](#rewinding-the-conversation) 回到較早的回合。倒轉會截斷回到已快取的前綴，而不是像壓縮那樣建立新的前綴。

212</Tip>212</Tip>

213 213

214<h3 id="accumulating-many-images">214<h3 id="accumulating-many-images">

217 217

218API 限制每個請求可以攜帶多少影像和 PDF。如需目前的數字，請參閱 API 文件中的[請求限制](https://platform.claude.com/docs/en/build-with-claude/vision#request-limits)。Claude Code 也會限制請求中影像和 PDF 的總大小，因此大型螢幕擷取畫面會以比小型螢幕擷取畫面更少的影像數量達到限制。218API 限制每個請求可以攜帶多少影像和 PDF。如需目前的數字，請參閱 API 文件中的[請求限制](https://platform.claude.com/docs/en/build-with-claude/vision#request-limits)。Claude Code 也會限制請求中影像和 PDF 的總大小，因此大型螢幕擷取畫面會以比小型螢幕擷取畫面更少的影像數量達到限制。

219 219

220當下一個請求會超過任一限制時，Claude Code 會從其傳送的內容中移除一批最舊的影像和 PDF，這會為更多內容騰出空間，然後才需要再次移除任何內容。Claude 無法再看到移除的影像。如果 Claude 稍後需要其中一個，請再次共享它。220當下一個請求會超過任一限制時，Claude Code 會從其傳送的內容中移除一批最舊的影像和 PDF，這會為更多內容騰出空間，然後才需要再次移除任何內容。Claude 無法再看到移除的影像。如果 Claude 再次需要其中一個，請再次分享它。

221 221

222移除影像會變更保存它們的訊息，因此下一個請求會從這些訊息中最早的訊息開始重新處理對話。因為 Claude Code 一次移除一批，您會看到每批一個較慢的回合，而不是每個新螢幕擷取畫面一個。222移除影像會變更保存它們的訊息，因此下一個請求會從這些訊息中最早的訊息開始重新處理對話。因為 Claude Code 一次移除一批，您會看到每批一個較慢的回合，而不是每個新螢幕擷取畫面一個。

223 223

225 升級 Claude Code225 升級 Claude Code

226</h3>226</h3>

227 227

228新的 Claude Code 版本通常會更新系統提示或工具定義，因此您在升級後開始的第一個對話會從頭開始建立其快取。[自動更新](/docs/zh-TW/setup#auto-updates)會在背景下載新版本，但在下一次啟動時套用它們，永遠不會在工作階段中途，因此您會看到這是重新啟動後的未快取第一個回合，而不是工作階段期間的驚喜。設定 `DISABLE_AUTOUPDATER=1` 以控制何時套用升級。228新的 Claude Code 版本通常會更新系統提示詞或工具定義，因此您在升級後開始的第一個對話會從頭開始建立其快取。[自動更新](/docs/zh-TW/setup#auto-updates)會在背景下載新版本，但在下一次啟動時套用它們，永遠不會在工作階段中途，因此您會看到這是重新啟動後的未快取第一個回合，而不是工作階段期間的意外。設定 `DISABLE_AUTOUPDATER=1` 以控制何時套用升級。

229 229

230<Note>230<Note>

231 如需繼續您在升級前開始的對話的成本，請參閱[繼續工作階段](#resuming-a-session)。231 如需繼續您在升級前開始的對話的成本，請參閱[繼續工作階段](#resuming-a-session)。

310 310

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

312 312

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

314 314

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

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

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

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

330 330

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

332 332

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

334 自己選擇 TTL334 自己選擇 TTL

prompt-library.md +1 −1

Details

1342 },1342 },

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

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

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

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

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

1348 },1348 },

quickstart.md +58 −92

Details

4 4

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

6 6

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

8 8

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

10 10

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

12 開始前12 開始前

14 14

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

16 16

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

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

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

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

21 20

22<Note>21<Note>

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

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

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

24</Note>26</Note>

25 27

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

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

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

35 37

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

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

38 ```40 ```

39 41

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

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

41 45

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

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

44 ```48 ```

45 49

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

47 51

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

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

50 ```54 ```

51 55

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

53 57

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

55 59

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

57 61

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

59 63

63 </Tab>67 </Tab>

64 68

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

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

67 brew install --cask claude-code71 brew install --cask claude-code

68 ```72 ```

69 73

75 </Tab>79 </Tab>

76 80

77 <Tab title="WinGet">81 <Tab title="WinGet">

~~78 ```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}~~82 ```powershell theme={null}

79 winget install Anthropic.ClaudeCode83 winget install Anthropic.ClaudeCode

80 ```84 ```

81 85

95 99

96此命令會列印版本號碼，後面跟著 `(Claude Code)`。100此命令會列印版本號碼，後面跟著 `(Claude Code)`。

97 101

~~98<h2 id="step-2-log-in-to-your-account">~~102<h2 id="step-2-start-your-first-session">

~~99 步驟 2：登入您的帳戶~~103 步驟 2：開始您的第一個工作階段

100</h2>104</h2>

101 105

102Claude Code 需要帳戶才能使用。使用 `claude` 命令啟動互動式工作階段，首次使用時系統會提示您登入：106在任何專案目錄中開啟終端機，然後啟動 Claude Code：

103 107

104```bash theme={null}108```bash theme={null}

109cd /path/to/your/project

105claude110claude

106```111```

107 112

108對於 Claude 訂閱或 Console 帳戶，請按照提示在瀏覽器中完成驗證。如果您已設定 `ANTHROPIC_API_KEY` 環境變數，Claude Code 會略過登入提示，改為要求您核准該金鑰。若要稍後切換帳戶或重新驗證，請在執行中的工作階段內輸入 `/login`：113將 `/path/to/your/project` 替換為您要處理的專案路徑。

~~109~~

110```text wrap theme={null}

111/login

112```

~~113~~

114您可以使用以下任何帳戶類型登入：

~~115~~

116* [Claude Pro、Max、Team 或 Enterprise](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=quickstart_login)（推薦）

117* [Claude Console](https://platform.claude.com/)（具有預付額度的 API 存取）。首次登入時，Console 中會自動建立「Claude Code」工作區以進行集中成本追蹤。

118* [Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry](/docs/zh-TW/third-party-integrations)（企業雲端提供商）

119* 自行託管的 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway)（如果您的組織執行一個的話）：您的管理員會預先設定閘道 URL，`/login` 會直接在 **Cloud gateway** 畫面上開啟，供您使用公司 SSO 登入

~~120~~

121登入後，您的認證將被儲存，您無需再次登入。深入瞭解 [認證管理](/docs/zh-TW/authentication#credential-management)。

122 114

123<h2 id="step-3-start-your-first-session">115Claude Code 會在首次使用時提示您登入。若使用 Claude 訂閱或 Console 帳戶，請依照提示在瀏覽器中完成身分驗證。如果您已設定 `ANTHROPIC_API_KEY` 環境變數，且在 Claude Code 詢問是否使用該金鑰時予以核准，Claude Code 便會略過登入提示。

124 步驟 3：啟動您的第一個工作階段

125</h2>

126 116

127在任何專案目錄中開啟您的終端並啟動 Claude Code：117您可以使用下列任一種帳戶類型登入：

128 118

129```bash theme={null}119* [Claude Pro、Max、Team 或 Enterprise](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=quickstart_login)（建議）

130cd /path/to/your/project120* [Claude Console](https://platform.claude.com/)（使用預付額度的 API 存取）。首次登入時，系統會自動在 Console 中建立一個「Claude Code」工作區，以便集中追蹤費用。

131claude121* [Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry](/docs/zh-TW/third-party-integrations)（企業雲端供應商）

132```122* 自行託管的 [Claude apps 閘道](/docs/zh-TW/claude-apps-gateway)（如果您的組織有執行的話）：您的管理員會預先設定閘道 URL，而 `/login` 會直接開啟 **Cloud gateway** 畫面，供您使用企業 SSO 登入

133 123

134將 `/path/to/your/project` 替換為您要處理的專案路徑。124登入後，您的憑證會被儲存，之後不需要再次登入。如需了解更多資訊，請參閱[憑證管理](/docs/zh-TW/authentication#credential-management)。

135 125

136您將看到 Claude Code 提示，其中顯示版本、目前的模型和工作目錄。輸入 `/help` 以查看可用命令，或輸入 `/resume` 以繼續之前的對話。126Claude Code 提示字元會出現，其上方會顯示版本、目前的模型及工作目錄。輸入 `/help` 以查看可用的命令，或輸入 `/resume` 以繼續先前的對話。若之後要切換帳戶或重新進行身分驗證，請在執行中的工作階段內輸入 `/login`。

137 127

138<h2 id="step-4-ask-your-first-question">128<h2 id="step-3-ask-your-first-question">

139 步驟 4：提出您的第一個問題129 步驟 3：提出您的第一個問題

140</h2>130</h2>

141 131

142讓我們從了解您的程式碼庫開始。嘗試以下命令之一：132試試以下其中一個命令：

143 133

144```text wrap theme={null}134```text wrap theme={null}

145what does this project do?135what does this project do?

159explain the folder structure149explain the folder structure

160```150```

161 151

162您也可以詢問 Claude 其自身的功能：152您也可以詢問 Claude 關於其自身功能的問題：

163 153

164```text wrap theme={null}154```text wrap theme={null}

165what can Claude Code do?155what can Claude Code do?

174```164```

175 165

176<Note>166<Note>

177 Claude Code 會根據需要讀取您的專案檔案。您無需手動新增內容。167 Claude Code 會視需要讀取您的專案檔案。無需手動新增上下文。

178</Note>168</Note>

179 169

180<h2 id="step-5-make-your-first-code-change">170<h2 id="step-4-make-your-first-code-change">

181 步驟 5：進行您的第一次程式碼變更171 步驟 4：進行您的第一次程式碼變更

182</h2>172</h2>

183 173

184現在讓 Claude Code 進行一些實際的編碼。嘗試一個簡單的任務：174試試一個小任務：

185 175

186```text wrap theme={null}176```text wrap theme={null}

187add a hello world function to the main file177add a hello world function to the main file

188```178```

189 179

190Claude Code 找到適當的檔案並向您顯示變更。如果它在進行變更前詢問，請選擇 **是** 以批准。180Claude Code 會找到適當的檔案並向您顯示變更內容。如果它在進行變更前詢問，請選擇 **Yes** 以核准。

~~191~~

192使用 Claude Code v2.1.283 或更新版本，auto mode 是互動式終端工作階段的[內建起始權限模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)：分類器會檢查動作而不是由您檢查，Claude 可以在不詢問的情況下編輯大多數檔案並執行大多數命令。在較早的版本上，auto mode 僅在 Pro、Max 和 Team 方案上是內建的起始權限模式。對於您安裝或升級後立即開始的工作階段，請參閱[安裝或升級後的第一個工作階段](/docs/zh-TW/env-vars#first-session-after-an-install-or-upgrade)。

193 181

194<Note>182工作階段的[權限模式](/docs/zh-TW/permission-modes)決定了 Claude 可以在不先詢問您的情況下執行哪些動作。隨時按下 `Shift+Tab` 即可切換您目前所在工作階段的權限模式。

195 您的設定或您的組織可以設定不同的起始權限模式。[工作階段開始時的權限模式](/docs/zh-TW/permission-modes#which-mode-a-session-starts-in) 列出了相關內容。隨時按 `Shift+Tab` 以切換您所在工作階段的權限模式。

196</Note>

197 183

198<h2 id="step-6-use-git-with-claude-code">184<h2 id="step-5-use-git-with-claude-code">

199 步驟 6：使用 Git 與 Claude Code185 步驟 5：搭配 Claude Code 使用 Git

200</h2>186</h2>

201 187

202Claude Code 使 Git 操作變得對話式：188Claude Code 讓 Git 操作變得像對話一樣自然：

203 189

204```text wrap theme={null}190```text wrap theme={null}

205what files have I changed?191what files have I changed?

209commit my changes with a descriptive message195commit my changes with a descriptive message

210```196```

211 197

212您也可以提示進行更複雜的 Git 操作：198您也可以透過提示詞執行更複雜的 Git 操作：

213 199

214```text wrap theme={null}200```text wrap theme={null}

215create a new branch called feature/quickstart201create a new branch called feature/quickstart

223help me resolve merge conflicts209help me resolve merge conflicts

224```210```

225 211

226<h2 id="step-7-fix-a-bug-or-add-a-feature">212<h2 id="step-6-fix-a-bug-or-add-a-feature">

227 步驟 7：修復錯誤或新增功能213 步驟 6：修正錯誤或新增功能

228</h2>214</h2>

229 215

230Claude 擅長除錯和功能實現。216以自然語言描述您想要的內容：

~~231~~

232用自然語言描述您想要的內容：

233 217

234```text wrap theme={null}218```text wrap theme={null}

235add input validation to the user registration form219add input validation to the user registration form

236```220```

237 221

238或修復現有問題：222或修正現有問題：

239 223

240```text wrap theme={null}224```text wrap theme={null}

241there's a bug where users can submit empty forms - fix it225there's a bug where users can submit empty forms - fix it

242```226```

243 227

244Claude Code 將：228<h2 id="step-7-test-out-other-common-workflows">

~~245~~ 229 步驟 7：試用其他常見工作流程

246* 定位相關程式碼

247* 理解上下文

248* 實現解決方案

249* 如果可用，執行測試

~~250~~

251<h2 id="step-8-test-out-other-common-workflows">

252 步驟 8：測試其他常見工作流程

253</h2>230</h2>

254 231

255有許多方式可以與 Claude 合作：232與 Claude 協作的方式有很多種：

256 233

257**重構程式碼**234**重構程式碼**

258 235

260refactor the authentication module to use async/await instead of callbacks237refactor the authentication module to use async/await instead of callbacks

261```238```

262 239

263**編寫測試**240**撰寫測試**

264 241

265```text wrap theme={null}242```text wrap theme={null}

266write unit tests for the calculator functions243write unit tests for the calculator functions

279```256```

280 257

281<Tip>258<Tip>

282 像與有幫助的同事交談一樣與 Claude 交談。描述您想要達成的目標，它將幫助您實現。259 像與一位樂於助人的同事交談一樣與 Claude 對話。描述您想要達成的目標，它就會協助您實現。

283</Tip>260</Tip>

284 261

285<h2 id="essential-commands">262<h2 id="essential-commands">

357 334

358現在您已經學習了基礎知識，請探索更多進階功能：335現在您已經學習了基礎知識，請探索更多進階功能：

359 336

360<CardGroup cols={2}>337* [Claude Code 如何運作](/docs/zh-TW/how-claude-code-works)：了解代理式迴圈、內建工具以及 Claude Code 如何與您的專案互動

361 <Card title="Claude Code 如何運作" icon="microchip" href="/docs/zh-TW/how-claude-code-works">338* [最佳實踐](/docs/zh-TW/best-practices)：透過有效的提示和專案設定獲得更好的結果

362 了解代理迴圈、內建工具以及 Claude Code 如何與您的專案互動339* [常見工作流程](/docs/zh-TW/common-workflows)：常見任務的逐步指南

363 </Card>340* [擴展 Claude Code](/docs/zh-TW/features-overview)：使用 CLAUDE.md、skill、hook、MCP 等進行自訂

~~364~~

365 <Card title="最佳實踐" icon="star" href="/docs/zh-TW/best-practices">

366 透過有效的提示和專案設定獲得更好的結果

367 </Card>

~~368~~

369 <Card title="常見工作流程" icon="graduation-cap" href="/docs/zh-TW/common-workflows">

370 常見任務的逐步指南

371 </Card>

372 341

373 <Card title="擴展 Claude Code" icon="puzzle-piece" href="/docs/zh-TW/features-overview">342請參閱[進階設定](/docs/zh-TW/setup)以了解安裝選項、手動更新或解除安裝說明。

374 使用 CLAUDE.md、skills、hooks、MCP 等進行自訂

375 </Card>

376</CardGroup>

377 343

378<h2 id="getting-help">344<h2 id="getting-help">

379 獲取幫助345 獲取幫助

380</h2>346</h2>

381 347

382* **在 Claude Code 中**：輸入 `/help` 或詢問「how do I」問題348* **在 Claude Code 中**：輸入 `/help` 或詢問「how do I」問題

383* **文件**：您在這裡！瀏覽其他指南349* **文件**：瀏覽本網站上的其他指南

384* **課程**：參加 [Claude Code 101](https://academy.claude.com/courses/claude-code-101) 和其他免費自學課程，位於 [Claude Academy](https://academy.claude.com/)350* **課程**：參加 [Claude Code 101](https://academy.claude.com/courses/claude-code-101) 和其他免費自學課程，位於 [Claude Academy](https://academy.claude.com/)

385* **社群**：加入 [Discord 伺服器](https://www.anthropic.com/discord) 以獲取提示和支援351* **社群**：加入 [Discord 伺服器](https://www.anthropic.com/discord) 以獲取提示和支援

remote-control.md +1 −1

Details

365</h2>365</h2>

366 366

367* **每個互動程序一個遠端工作階段**：在伺服器模式之外，每個 Claude Code 實例一次只支援一個遠端工作階段。使用[伺服器模式](#start-a-remote-control-session)從單一程序執行多個並行工作階段。367* **每個互動程序一個遠端工作階段**：在伺服器模式之外，每個 Claude Code 實例一次只支援一個遠端工作階段。使用[伺服器模式](#start-a-remote-control-session)從單一程序執行多個並行工作階段。

368* **本機程序必須保持執行**：Remote Control 以本機程序的形式執行。如果您關閉終端機、結束 Desktop 應用程式或 VS Code，或以其他方式停止 `claude` 程序，工作階段將離線，直到您[將其恢復](#resume-sessions-after-stopping-the-server)。若要在您從 SSH 中斷連線後讓工作階段在遠端機器上保持執行，請在 `tmux` 或 `screen` 內啟動它。368* **本機程序必須保持執行**：Remote Control 以本機程序的形式執行。如果您關閉終端機、結束 Desktop 應用程式或 VS Code，或以其他方式停止 `claude` 程序，工作階段將離線，直到您[將其恢復](#resume-sessions-after-stopping-the-server)。如果您從遠端機器上的終端機執行 `claude`，請在 `tmux` 或 `screen` 內啟動它，以便在您從 SSH 中斷連線後讓工作階段保持執行。

369* **伺服器模式中的已損毀工作階段**：如果由 `claude remote-control` 提供服務的工作階段損毀，請從已連線的裝置向其傳送訊息。Claude Code 會再次提供服務。您不必重新啟動伺服器。需要 Claude Code v2.1.238 或更新版本。369* **伺服器模式中的已損毀工作階段**：如果由 `claude remote-control` 提供服務的工作階段損毀，請從已連線的裝置向其傳送訊息。Claude Code 會再次提供服務。您不必重新啟動伺服器。需要 Claude Code v2.1.238 或更新版本。

370* **已連線工作階段上的 HTTP 403 拒絕**：一旦互動工作階段已連線，當您的機器與 Anthropic 伺服器之間的某個位置以 HTTP 403 回應時（在 VPN 或網路變更後可能發生），Claude Code 會重試最多三分鐘。如果拒絕持續更久，Claude Code 會中斷連線，原因會指出拒絕的內容：網路邊界，或您自己網路上的代理伺服器、VPN 或防火牆。370* **已連線工作階段上的 HTTP 403 拒絕**：一旦互動工作階段已連線，當您的機器與 Anthropic 伺服器之間的某個位置以 HTTP 403 回應時（在 VPN 或網路變更後可能發生），Claude Code 會重試最多三分鐘。如果拒絕持續更久，Claude Code 會中斷連線，原因會指出拒絕的內容：網路邊界，或您自己網路上的代理伺服器、VPN 或防火牆。

371* **延長的網路中斷**：如果您的機器已開啟但無法連線到網路，您接下來的操作取決於模式：371* **延長的網路中斷**：如果您的機器已開啟但無法連線到網路，您接下來的操作取決於模式：

routines.md +1 −1

Details

93 為例行工作選擇 [cloud environment](/docs/zh-TW/cloud-environments)。環境控制雲端工作階段可以存取的內容：93 為例行工作選擇 [cloud environment](/docs/zh-TW/cloud-environments)。環境控制雲端工作階段可以存取的內容：

94 94

95 * **Network access**：設定每次執行期間可用的網際網路存取級別95 * **Network access**：設定每次執行期間可用的網際網路存取級別

96 * **Environment variables**：提供 Claude 在每次執行期間可以使用的值。它們 [對使用該環境的任何人都可見](/docs/zh-TW/cloud-environments#what-carries-over-from-your-setup)，因此在 Pro 和 Max 方案上，將 Claude 在執行期間呼叫的 API 的金鑰儲存為 [API credentials](/docs/zh-TW/cloud-environments#add-api-credentials)。該部分也列出了永遠不會獲得認證的請求96 * **Environment variables**：提供 Claude 在每次執行期間可以使用的值。這些值[對使用該環境的任何人都可見](/docs/zh-TW/cloud-environments#what-carries-over-from-your-setup)，因此在 Pro 和 Max 方案上，請改將 Claude 在執行期間呼叫的 API 金鑰儲存為 [網路機密](/docs/zh-TW/cloud-environments#add-api-credentials)。該章節也列出了永遠不會取得機密的請求

97 * **Setup script**：安裝例行工作需要的相依性和工具。結果是 [cached](/docs/zh-TW/cloud-environments#environment-caching)，因此指令碼不會在每個工作階段上重新執行97 * **Setup script**：安裝例行工作需要的相依性和工具。結果是 [cached](/docs/zh-TW/cloud-environments#environment-caching)，因此指令碼不會在每個工作階段上重新執行

98 98

99 提供了 **Default** 環境，具有 **Trusted** 網路存取，它只允許 [default allowlist](/docs/zh-TW/cloud-environments#default-allowed-domains) 的套件登錄、雲端提供者 API、容器登錄和常見開發網域透過工作階段的網路。您新增到例行工作的連接器透過 Anthropic 的伺服器存取其服務，因此不需要更改允許清單。如果您的例行工作需要直接存取您自己的服務或該清單外的網域，請在執行前編輯環境的 [network access](/docs/zh-TW/cloud-environments#network-access)。若要使用單獨的環境，請先 [create one](/docs/zh-TW/cloud-environments#configure-your-environment)。99 提供了 **Default** 環境，具有 **Trusted** 網路存取，它只允許 [default allowlist](/docs/zh-TW/cloud-environments#default-allowed-domains) 的套件登錄、雲端提供者 API、容器登錄和常見開發網域透過工作階段的網路。您新增到例行工作的連接器透過 Anthropic 的伺服器存取其服務，因此不需要更改允許清單。如果您的例行工作需要直接存取您自己的服務或該清單外的網域，請在執行前編輯環境的 [network access](/docs/zh-TW/cloud-environments#network-access)。若要使用單獨的環境，請先 [create one](/docs/zh-TW/cloud-environments#configure-your-environment)。

self-hosted-environments-testing.md +2 −2

Details

104 範例指令碼104 範例指令碼

105</h2>105</h2>

106 106

107下面的指令碼針對 `$CLAUDE_TEST_ENVIRONMENT_ID`（您的測試環境的 `ccpool_...` ID，顯示在管理頁面上環境的詳細對話框中或由[建立環境呼叫](#create-a-dedicated-test-environment)返回）執行完整迴圈，並在每個回覆中斷言哨兵短語。從您希望工作階段在其中工作的存放庫的 git 簽出執行它，在此主機上啟動執行器後，安裝擷取 hook 並匯出 `E2E_REPLY_DIR`。107下面的指令碼針對 `$CLAUDE_TEST_ENVIRONMENT_ID`（您的測試環境的 `ccpool_...` ID，顯示在管理頁面上環境的詳細對話框中或由[建立環境呼叫](#create-a-dedicated-test-environment)返回）執行完整迴圈，並在每個回覆中斷言哨兵短語。從您希望工作階段在其中工作的儲存庫的 git 簽出執行它，在此主機上啟動執行器後，安裝擷取 hook 並匯出 `E2E_REPLY_DIR`。請先依照[從 CI 進行驗證](#authenticate-from-ci)中的說明，在執行指令碼的機器上使用 claude.ai 帳戶登入。若未登入，第一次分派會失敗並出現錯誤，例如 `Unable to get organization UUID for cloud session creation`。

108 108

109```bash theme={null}109```bash theme={null}

110#!/usr/bin/env bash110#!/usr/bin/env bash

174echo "PASS: test-environment round-trip (session $SESSION_ID)"174echo "PASS: test-environment round-trip (session $SESSION_ID)"

175```175```

176 176

177將 `TURN1`/`TURN2` 提示和 `EXPECT1`/`EXPECT2` 哨兵替換為任何練習您的設定的內容，例如要求 Claude 執行您的自訂 MCP 工具之一並斷言其輸出。177將 `TURN1`/`TURN2` 提示詞和 `EXPECT1`/`EXPECT2` 哨兵替換為任何能測試您的設定的內容，例如要求 Claude 執行您的自訂 MCP 工具之一並斷言其輸出。

178 178

179<h2 id="remote-test-runners">179<h2 id="remote-test-runners">

180 遠端測試執行器180 遠端測試執行器

server-managed-settings.md +2 −2

Details

43 <Step title="開啟管理員主控台">43 <Step title="開啟管理員主控台">

44 在 claude.ai 主控台中，前往 [**Organization settings > Claude Code > Managed settings**](https://claude.ai/admin-settings/claude-code)。44 在 claude.ai 主控台中，前往 [**Organization settings > Claude Code > Managed settings**](https://claude.ai/admin-settings/claude-code)。

45 45

46 如果連結將您重新導向至不同的 Organization settings 頁面，而不是 Claude Code 頁面，表示您的帳戶沒有所需的角色。管理員和其他非擁有者角色無法檢視或編輯受管設定，因此請要求您組織中的擁有者或主要擁有者進行變更。請參閱[存取控制](#access-control)。46 在 Team 或 Enterprise 組織中，如果頁面顯示您沒有存取權，請要求[擁有者或主要擁有者](#access-control)進行變更。

47 </Step>47 </Step>

48 48

49 <Step title="定義您的設定">49 <Step title="定義您的設定">

149 設定優先順序149 設定優先順序

150</h3>150</h3>

151 151

152伺服器管理的設定和[端點管理的設定](/docs/zh-TW/managed-settings#delivery-mechanisms)都佔據 Claude Code [設定階層](/docs/zh-TW/settings#settings-precedence)中的最高層級。沒有其他設定層級可以覆蓋它們，包括命令列引數，除了[受管設定優先順序的例外](/docs/zh-TW/settings#exceptions-to-managed-settings-precedence)。152伺服器管理的設定和[端點管理的設定](/docs/zh-TW/managed-settings#delivery-mechanisms)都佔據 Claude Code [設定階層](/docs/zh-TW/settings#settings-precedence)中的最高層級。您在此設定的金鑰優先於使用者自己的設定檔或 `--settings` 值中的相同金鑰，但[受管設定優先順序的例外](/docs/zh-TW/settings#exceptions-to-managed-settings-precedence)除外。

153 153

154在受管層級內，Claude Code 預設會使用第一個傳遞至少一個原則金鑰的來源，先檢查伺服器管理的設定，然後是端點管理的設定，除了[接下來涵蓋的例外金鑰](#per-key-exceptions-across-managed-sources)。[Claude Code 如何合併受管來源](/docs/zh-TW/managed-settings#precedence-within-the-managed-tier)有完整的排名、控制金鑰的例外，以及適用於每個來源的選擇加入。154在受管層級內，Claude Code 預設會使用第一個傳遞至少一個原則金鑰的來源，先檢查伺服器管理的設定，然後是端點管理的設定，除了[接下來涵蓋的例外金鑰](#per-key-exceptions-across-managed-sources)。[Claude Code 如何合併受管來源](/docs/zh-TW/managed-settings#precedence-within-the-managed-tier)有完整的排名、控制金鑰的例外，以及適用於每個來源的選擇加入。

155 155

sessions.md +69 −67

Details

11[桌面應用程式](/docs/zh-TW/desktop#work-in-parallel-with-sessions)、[claude.ai/code](/docs/zh-TW/claude-code-on-the-web) 和 [VS Code 擴充功能](/docs/zh-TW/vs-code#resume-past-conversations)各自維護自己的 session 歷史記錄，桌面應用程式也可以[恢復 CLI session](/docs/zh-TW/desktop#coming-from-the-cli)。本頁涵蓋 CLI。11[桌面應用程式](/docs/zh-TW/desktop#work-in-parallel-with-sessions)、[claude.ai/code](/docs/zh-TW/claude-code-on-the-web) 和 [VS Code 擴充功能](/docs/zh-TW/vs-code#resume-past-conversations)各自維護自己的 session 歷史記錄，桌面應用程式也可以[恢復 CLI session](/docs/zh-TW/desktop#coming-from-the-cli)。本頁涵蓋 CLI。

12 12

13<h2 id="resume-a-session">13<h2 id="resume-a-session">

~~14 恢復 session~~14 恢復工作階段

15</h2>15</h2>

16 16

~~17Sessions 在您工作時會持續儲存到[本地文字記錄檔案](#export-and-locate-session-data)，因此您可以在退出或執行 `/clear` 後返回到一個。使用這些進入點：~~17工作階段在您工作時會持續儲存到[本機逐字稿檔案](#export-and-locate-session-data)，因此您可以在退出或執行 `/clear` 後返回其中一個工作階段。請使用這些進入點：

18 18

19| 命令 | 功能 |19| 命令 | 功能 |

20| :- | :- |20| :- | :- |

27 27

28使用 [`claude -p`](/docs/zh-TW/headless) 或 [Agent SDK](/docs/zh-TW/agent-sdk/overview) 建立的 Claude Code sessions 會被排除在 session 選擇器和 `claude --continue` 之外。您仍然可以透過將其 session ID 傳遞給 `claude --resume <session-id>` 來恢復它。使用 `claude --continue` 時，Claude Code 也會跳過[第一個提示是 `/loop` 的 sessions](#where-the-session-picker-looks)。當您執行 [`claude -p --continue`](/docs/zh-TW/headless#continue-conversations) 時，Claude Code 會包含 `-p`、SDK 和 `/loop` sessions。28Claude Code 會將使用 [`claude -p`](/docs/zh-TW/headless) 或 [Agent SDK](/docs/zh-TW/agent-sdk/overview) 建立的工作階段排除在工作階段選擇器和 `claude --continue` 之外。您仍然可以將其工作階段 ID 傳遞給 `claude --resume <session-id>` 來恢復它。使用 `claude --continue` 時，Claude Code 也會跳過[第一個提示詞是 `/loop` 的工作階段](#where-the-session-picker-looks)。當您執行 [`claude -p --continue`](/docs/zh-TW/headless#continue-conversations) 時，Claude Code 會包含 `-p`、SDK 和 `/loop` 工作階段。

29 29

30您可以從任何目錄執行 `claude --resume <session-id>`，因此可以恢復在其他地方啟動或已使用 [`/cd`](/docs/zh-TW/commands) 移動的工作階段。Claude Code 會依下列順序尋找該 ID：30您可以從任何目錄執行 `claude --resume <session-id>`，因此可以恢復在其他地方啟動或已使用 [`/cd`](/docs/zh-TW/commands) 移動的工作階段。Claude Code 會依下列順序尋找該 ID：

31 31

36 36

37在 v2.1.223 之前，查詢會停在目前專案目錄及其 git worktree，因此您必須從工作階段最後工作的目錄恢復。37在 v2.1.223 之前，查詢會停在目前專案目錄及其 git worktree，因此您必須從工作階段最後工作的目錄恢復。

38 38

39`claude --continue` 會開啟已完成的[背景 session](/docs/zh-TW/agent-view)，但不會開啟仍在執行的 session；開啟已完成的背景 sessions 需要 Claude Code v2.1.257 或更新版本。如果您最近的對話是您[移到背景](/docs/zh-TW/agent-view#send-the-session-to-the-background)的對話，且它仍在那裡執行，Claude Code 會以 `Your most recent conversation is running in the background` 和該 session 的 ID 退出。從 [`claude agents`](/docs/zh-TW/agent-view#attach-to-a-session) 附加到 session，或執行 `claude --resume` 以選擇另一個。39`claude --continue` 會開啟已完成的[背景工作階段](/docs/zh-TW/agent-view)，但不會開啟仍在執行的工作階段；開啟已完成的背景工作階段需要 Claude Code v2.1.257 或更新版本。如果您最近的對話是您[移到背景](/docs/zh-TW/agent-view#send-the-session-to-the-background)的對話，且它仍在背景執行，Claude Code 會顯示 `Your most recent conversation is running in the background` 和該工作階段的 ID 並退出。請從 [`claude agents`](/docs/zh-TW/agent-view#attach-to-a-session) 附加到該工作階段，或執行 `claude --resume` 以選擇另一個工作階段。

40 40

41<h3 id="resume-a-running-background-session">41<h3 id="resume-a-running-background-session">

42 恢復執行中的背景工作階段42 恢復執行中的背景工作階段

44 44

45當您使用 `claude --resume` 或 `/resume` 恢復的對話屬於仍在執行的[背景工作階段](/docs/zh-TW/agent-view)時，Claude Code 會開啟該執行中的工作階段本身。在命令列上使用 `--bg` 時，恢復則改為[背景分派](/docs/zh-TW/agent-view#from-your-shell)。在 v2.1.285 之前，Claude Code 會拒絕並告訴您使用 `claude attach <id>` 開啟該工作階段，或先使用 `claude stop <id>` 停止它。45當您使用 `claude --resume` 或 `/resume` 恢復的對話屬於仍在執行的[背景工作階段](/docs/zh-TW/agent-view)時，Claude Code 會開啟該執行中的工作階段本身。在命令列上使用 `--bg` 時，恢復則改為[背景分派](/docs/zh-TW/agent-view#from-your-shell)。在 v2.1.285 之前，Claude Code 會拒絕並告訴您使用 `claude attach <id>` 開啟該工作階段，或先使用 `claude stop <id>` 停止它。

46 46

47* **從您的 shell**：`claude --resume <session>` 在同一終端機中對該 session 執行 [`claude attach`](/docs/zh-TW/agent-view#attach-to-a-session)，而不是載入文字記錄本身。您在命令列上傳遞的提示，如 `claude --resume <session> "check the tests too"`，會先作為該 session 的下一個輪次進行。Claude Code 會列印 `Sent your prompt to the background session (<id>); opening it…` 然後附加。在終端機上輸入的 `claude -p --resume <session> "prompt"` 也會執行相同操作，因此 `-p` 不會保持該執行非互動式。47* **從您的 shell**：`claude --resume <session>` 會在同一個終端機中對該工作階段執行 [`claude attach`](/docs/zh-TW/agent-view#attach-to-a-session)，而不是自行載入逐字稿。您在命令列上傳遞的提示詞，例如 `claude --resume <session> "check the tests too"`，會先作為該工作階段的下一個回合送出，Claude Code 會在附加之前列印 `Sent your prompt to the background session (<id>); opening it…`。在終端機中輸入的 `claude -p --resume <session> "prompt"` 也會執行相同操作，因此 `-p` 不會讓該次執行保持非互動式。

48 48

~~49 當命令列具有以下任何情況時，Claude Code 不會開啟 session：~~49 當命令列具有以下任何一項時，Claude Code 不會開啟該工作階段：

50 50

~~51 * 管道或重新導向的輸入或輸出~~51 * 經由管道傳送或重新導向的輸入或輸出

~~52 * 設定 session 的旗標，例如 `--permission-mode`、`--model` 或 `--settings`~~52 * 設定工作階段的旗標，例如 `--permission-mode`、`--model` 或 `--settings`

53 * 讀取輸出的旗標，例如 `--output-format json` 或 `--json-schema`53 * 讀取輸出的旗標，例如 `--output-format json` 或 `--json-schema`

~~54 * 限制或倒帶執行的旗標，例如 `--max-turns` 或 `--max-budget-usd`~~54 * 限制或倒轉執行的旗標，例如 `--max-turns` 或 `--max-budget-usd`

55 55

56 使用這些中的任何一個，或當[代理檢視已關閉](/docs/zh-TW/agent-view#turn-off-agent-view)時，Claude Code 不會傳送任何內容，並以狀態 1 退出，列印 session 在背景執行以及開啟它的 `claude attach <id>` 命令，或當它無法確定 ID 時告訴您在 `claude agents` 中找到它。新增 `--fork-session` 以恢復對話的副本。要在您自己的 session 中繼續對話本身，並套用您的旗標，請執行 `claude stop <id>`，然後重複該命令。56 具有其中任何一項，或當 [agent 檢視已關閉](/docs/zh-TW/agent-view#turn-off-agent-view)時，Claude Code 不會傳送任何內容，並以狀態 1 退出，列印該工作階段正在背景執行，以及用來開啟它的 `claude attach <id>` 命令；若無法判定 ID，則會告訴您在 `claude agents` 中尋找它。新增 `--fork-session` 可改為恢復該對話的副本。若要在您自己的工作階段中繼續對話本身並套用您的旗標，請執行 `claude stop <id>`，然後重複該命令。

57 57

58 以 `/` 或 `!` 開頭的提示不會被傳送，當 session 等待您回答問題時也不會傳送任何提示。在這兩種情況下，Claude Code 都不會開啟 session，訊息會包含 `Your prompt was not sent to it` 以及原因。58 以 `/` 或 `!` 開頭的提示詞不會被傳送，而當工作階段正在等待您回答問題時，任何提示詞也都不會被傳送。在這兩種情況下，Claude Code 都不會開啟該工作階段，訊息會包含 `Your prompt was not sent to it` 以及原因。

59* **從 session 內**：`/resume` 將您目前的對話移到背景，並將此終端機附加到執行中的 session，列印 `Opening "<title>", running in the background (<id>)`。在空提示上按 `←` 以返回代理檢視，這也會列出您留下的對話。當目前的對話無法移到背景時（例如因為您已附加到背景 session 或 session 持久性已關閉），`/resume` 會列印要執行的 `claude attach` 命令。59* **從工作階段內**：`/resume` 會將您目前的對話移到背景，並將此終端機附加到執行中的工作階段，列印 `Opening "<title>", running in the background (<id>)`。在空白提示詞上按 `←` 即可返回 agent 檢視，其中也會列出您離開的對話。當目前的對話無法移到背景時（例如因為您已附加到背景工作階段，或工作階段持久化已關閉），`/resume` 會改為列印要執行的 `claude attach` 命令。

60 60

61<h3 id="what-a-resumed-session-restores">61<h3 id="what-a-resumed-session-restores">

~~62 恢復的 session 會復原什麼~~62 恢復的工作階段會復原什麼

63</h3>63</h3>

64 64

~~65當 Claude Code 從其文字記錄載入對話時，恢復的 session 會復原對話以及儲存在其中的狀態：~~65當 Claude Code 從逐字稿載入對話時，恢復的工作階段會復原該對話以及其中儲存的狀態：

66 66

67* 對話歷史記錄：完整歷史記錄，包括工具呼叫和結果。當前一個程序結束時仍在執行的工具（例如在當機中），在您恢復時不會完成或再次執行；Claude 會看到呼叫標記為在其結果被記錄之前被切斷，並被告知在再次執行之前檢查它是否生效，除非設定了 [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/zh-TW/env-vars#variables)。在 v2.1.281 之前，Claude Code 會從對話中刪除被切斷的呼叫，或將其顯示為您中斷的呼叫。67* 對話記錄：完整的記錄，包括工具呼叫和結果。在前一個程序結束時（例如當機時）仍在執行的工具，在您恢復時不會完成或再次執行。Claude 會看到該呼叫被標記為在結果記錄之前就被中斷，並被告知在再次執行之前先檢查它是否已生效，除非設定了 [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/zh-TW/env-vars#variables)。在 v2.1.281 之前，Claude Code 會從對話中刪除被中斷的呼叫，或將其以您中斷的呼叫呈現給 Claude。

68* 模型：session 會在其使用的模型上繼續。當模型已被淘汰或不被 `availableModels` 允許時，模型不會被復原；當 `--model` 旗標或 `ANTHROPIC_MODEL` 系列環境變數在啟動時選擇一個時；或在使用提供者特定部署 ID 的提供者上，例如 [Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry](/docs/zh-TW/third-party-integrations)；請參閱[模型設定](/docs/zh-TW/model-config#setting-your-model)以了解解析順序。68* 模型：工作階段會繼續使用其原本使用的模型，但[設定您的模型](/docs/zh-TW/model-config#setting-your-model)中所述的情況除外。

69* Agent：使用 [`--agent`](/docs/zh-TW/sub-agents#invoke-subagents-explicitly) 或 `agent` 設定啟動的 session 會繼續作為該 agent，保持其工具限制和模型。在恢復時傳遞 `--agent` 以選擇不同的；對於任一情況下的系統提示，請參閱[恢復對話中的系統提示旗標](/docs/zh-TW/cli-reference#system-prompt-flags-in-resumed-conversations)。Claude Code 在兩個地方查找 agent：session 的原始目錄（前提是您已[信任該工作區](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)），然後是您恢復的目錄，因此專案範圍的 agent 在您從另一個目錄恢復時仍會載入。如果 Claude Code 在任一地方都找不到 agent，session 會以預設工具恢復，並顯示[警告，命名該 agent](/docs/zh-TW/errors#session-agent-no-longer-available)。69* Agent：使用 [`--agent`](/docs/zh-TW/sub-agents#invoke-subagents-explicitly) 或 `agent` 設定啟動的工作階段會繼續作為該 agent 運作，並保留其工具限制和模型。恢復時傳遞 `--agent` 可選擇不同的 agent；關於任一情況下的系統提示詞，請參閱[恢復對話中的系統提示詞旗標](/docs/zh-TW/cli-reference#system-prompt-flags-in-resumed-conversations)。Claude Code 會在兩個地方尋找該 agent：工作階段的原始目錄（前提是您已[信任該工作區](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)），然後是您進行恢復的目錄，因此當您從另一個目錄恢復時，專案範圍的 agent 仍會載入。如果 Claude Code 在這兩個地方都找不到該 agent，工作階段會以預設工具恢復，並顯示[指出該 agent 名稱的警告](/docs/zh-TW/errors#session-agent-no-longer-available)。

70* 權限模式：如果您從終端機使用 `claude --continue`、`claude --resume <session-id>` 或 `claude --resume <name>`（當名稱符合一個 session 時）恢復，不帶 `-p`，Claude Code 會復原 session 所在的權限模式，除了[恢復時的權限模式](#permission-mode-on-resume)中的情況，其中也涵蓋 session 選擇器、`/resume` 和使用 `claude -p` 恢復。傳遞 `--permission-mode` 或 `--dangerously-skip-permissions` 以覆蓋復原的模式。70* 權限模式：如果您在終端機中使用 `claude --continue`、`claude --resume <session-id>` 或 `claude --resume <name>`（當名稱符合單一工作階段時）且不帶 `-p` 恢復，Claude Code 會復原工作階段當時的權限模式，但[恢復時的權限模式](#permission-mode-on-resume)中的情況除外，該節也涵蓋工作階段選擇器、`/resume` 以及使用 `claude -p` 恢復。傳遞 `--permission-mode` 或 `--dangerously-skip-permissions` 可覆寫復原的模式。

~~71* 活躍目標：[session 結束時仍然活躍的目標](/docs/zh-TW/goal#resume-with-an-active-goal)會延續；其輪次計數、計時器和代幣支出基線會重設。~~71* 進行中的目標：工作階段結束時仍在進行中的[目標](/docs/zh-TW/goal#resume-with-an-active-goal)會延續；其回合計數、計時器和 token 花費基準會重設。

~~72* 排程工作：[尚未過期的工作](/docs/zh-TW/scheduled-tasks#limitations)會被復原。背景 Bash 和監視工作不會。~~72* 排程任務：[尚未過期的任務](/docs/zh-TW/scheduled-tasks#limitations)會被復原。背景 Bash 和監視任務則不會。

73* 背景工作：[背景子 agent](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)、背景 Bash 命令或[工作流程](/docs/zh-TW/workflows)在前一個程序結束時顯示在恢復的文字記錄中，作為它未完成的註記。Claude Code 不會從這些註記開始一個輪次；Claude 會在您的下一個提示中讀取它們。73* 背景工作：隨著前一個程序結束的[背景 subagent](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)、背景 Bash 命令或[工作流程](/docs/zh-TW/workflows)，會在恢復的逐字稿中顯示為未完成的註記。Claude Code 不會因這些註記而開始一個回合；Claude 會在您的下一個提示詞時一併讀取它們。

74 74

75並非原始啟動的每個設定旗標都會被復原。如果 session 依賴於 `--mcp-config`、`--settings`、`--plugin-dir`、`--fallback-model` 或使用 `--add-dir` 新增的目錄，在恢復時再次傳遞它們；使用 `/add-dir` 在 session 中途新增的目錄也不會被復原，儘管 session 選擇器仍會使用它們來定位 session。標準設定檔案（例如 `settings.json` 和 `settings.local.json`）會在啟動時重新讀取，因此存在於其中的設定不需要再次傳遞。對於 `--system-prompt` 和 `--append-system-prompt`，請參閱[恢復對話中的系統提示旗標](/docs/zh-TW/cli-reference#system-prompt-flags-in-resumed-conversations)。75並非原始啟動時的每個設定旗標都會被復原。如果工作階段依賴 `--mcp-config`、`--settings`、`--plugin-dir`、`--fallback-model` 或使用 `--add-dir` 新增的目錄，請在恢復時再次傳遞它們；在工作階段中途使用 `/add-dir` 新增的目錄也不會被復原，但工作階段選擇器仍會使用它們來定位工作階段。標準設定檔（例如 `settings.json` 和 `settings.local.json`）會在啟動時重新讀取，因此存放在其中的設定不需要再次傳遞。關於 `--system-prompt` 和 `--append-system-prompt`，請參閱[恢復對話中的系統提示詞旗標](/docs/zh-TW/cli-reference#system-prompt-flags-in-resumed-conversations)。

76 76

77<h4 id="permission-mode-on-resume">77<h4 id="permission-mode-on-resume">

78 恢復時的權限模式78 恢復時的權限模式

79</h4>79</h4>

80 80

81Claude Code 啟動恢復的 session 所在的權限模式取決於您如何恢復。下面的情況適用於 Claude Code 從其文字記錄載入對話時；當您[開啟仍在執行的背景 session](#resume-a-running-background-session) 時，該 session 會保持它所在的權限模式。81Claude Code 以哪種權限模式啟動恢復的工作階段，取決於您的恢復方式。以下情況適用於 Claude Code 從逐字稿載入對話時；當您改為[開啟仍在執行的背景工作階段](#resume-a-running-background-session)時，該工作階段會保持其目前的權限模式。

82 82

83* 終端機：`claude --continue`、`claude --resume <session-id>` 或 `claude --resume <name>`（當名稱符合一個 session 時），不帶 `-p`。Claude Code 會復原 session 所在的權限模式，除了表格中的情況。傳遞 `--permission-mode` 或 `--dangerously-skip-permissions` 以覆蓋復原的模式。83* 終端機：`claude --continue`、`claude --resume <session-id>` 或 `claude --resume <name>`（當名稱符合單一工作階段時），且不帶 `-p`。Claude Code 會復原工作階段當時的權限模式，但表格中的情況除外。傳遞 `--permission-mode` 或 `--dangerously-skip-permissions` 可覆寫復原的模式。

84* 非互動式：`claude -p --resume` 或 `claude -p --continue`。Claude Code 會在新 `claude -p` 執行會啟動的權限模式中啟動執行，除了在[下面的條件](#resume-in-plan-mode-with-p)下以 Plan Mode 結束的 session 會在 Plan Mode 中恢復。84* 非互動式：`claude -p --resume` 或 `claude -p --continue`。Claude Code 會以新的 `claude -p` 執行會採用的權限模式啟動該次執行，但以 plan mode 結束的工作階段在[下列條件](#resume-in-plan-mode-with-p)下會以 plan mode 恢復。

~~85* VS Code：擴充功能的對話面板。表格僅涵蓋以 Plan Mode 結束的對話；對於其餘部分，請參閱[恢復過去的對話](/docs/zh-TW/vs-code#resume-past-conversations)。~~85* VS Code：擴充功能的對話面板。表格僅涵蓋以 plan mode 結束的對話；其餘情況請參閱[恢復過去的對話](/docs/zh-TW/vs-code#resume-past-conversations)。

86* 啟動時的 Session 選擇器：您從[session 選擇器](#use-the-session-picker)選擇的 session，無論您是使用 `claude --resume` 單獨開啟它、`claude --from-pr` 還是符合多個 session 的名稱。Claude Code 不會復原儲存的權限模式。它會在從相同命令列啟動新 session 時所在的權限模式中啟動 session。86* 啟動時的工作階段選擇器：您從[工作階段選擇器](#use-the-session-picker)選擇的工作階段，無論您是單獨使用 `claude --resume`、使用 `claude --from-pr`，還是使用符合多個工作階段的名稱來開啟選擇器。Claude Code 會以從相同命令列啟動新工作階段時的權限模式啟動該工作階段，但以 plan mode 結束的工作階段會在 plan mode 中恢復，除非您傳遞 `--permission-mode`、`--dangerously-skip-permissions` 或 `--fork-session`。不會復原其他已儲存的權限模式。

~~87* `/resume` 在 session 內，帶或不帶引數：Claude Code 不會復原儲存的權限模式。您切換到的對話會在您目前 session 所在的權限模式中繼續。~~87* 在工作階段內使用 `/resume`，帶或不帶引數：您切換到的對話會以您目前工作階段所在的權限模式繼續，但以 plan mode 結束的對話會在 plan mode 中恢復，即使您是以 `--permission-mode` 或 `--dangerously-skip-permissions` 啟動 Claude Code。如果該對話在本次 Claude Code 執行中稍早已開啟過，例如您一開始所在的對話，或您以 `/clear` 或 `/resume` 離開的對話，它則會改為以您目前的權限模式繼續。

88 88

89在非互動式和 VS Code 路徑上復原 Plan Mode 需要 Claude Code v2.1.246 或更新版本。每一列命名 session 結束時所在的權限模式、您透過哪個終端機、非互動式和 VS Code 路徑恢復它，以及 Claude Code 在恢復的 session 中啟動的權限模式。89在非互動式和 VS Code 路徑上復原 plan mode 需要 Claude Code v2.1.246 或更新版本。每一列列出工作階段結束時的權限模式、您透過終端機、非互動式和 VS Code 中的哪一種路徑恢復它，以及 Claude Code 啟動恢復之工作階段時採用的權限模式。

90 90

92| :- | :- | :- |92| :- | :- | :- |

93| `bypassPermissions` | 終端機 | 新 session 會啟動的權限模式。要再次[略過權限](/docs/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode)，請在啟動時使用其啟動旗標之一或 [user、`--settings` 或受管設定](/docs/zh-TW/settings-reference#permissions-defaultmode)中的 `permissions.defaultMode: "bypassPermissions"` 啟用它 |93| `bypassPermissions` | 終端機 | 新工作階段會啟動的權限模式。若要再次[略過權限](/docs/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode)，請在啟動時使用其啟動旗標之一，或在 [user、`--settings` 或受管設定](/docs/zh-TW/settings-reference#permissions-defaultmode)中使用 `permissions.defaultMode: "bypassPermissions"` 啟用它 |

~~94| `plan` | 終端機 | 新 session 會啟動的權限模式 |~~94| `plan` | 終端機 | plan mode。使用 `--fork-session` 時，則為新工作階段會啟動的權限模式 |

~~95| `auto` | 終端機 | `auto`，僅當您的帳戶仍符合 [auto mode 要求](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)時 |~~95| `auto` | 終端機 | `auto`，僅當您的帳戶仍符合[自動模式要求](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)時 |

96| Manual | 終端機 | Manual，當新 session 會從[內建預設](/docs/zh-TW/permission-modes#which-mode-a-session-starts-in)以 auto mode 啟動時。當設定檔案中的 `defaultMode` [生效](/docs/zh-TW/permission-modes#which-mode-a-session-starts-in)時，Claude Code 會在該模式中啟動恢復的 session |96| Manual | 終端機 | 當新工作階段會依[內建預設值](/docs/zh-TW/permission-modes#which-mode-a-session-starts-in)以自動模式啟動時，為 Manual。當設定檔中的 `defaultMode` [生效](/docs/zh-TW/permission-modes#which-mode-a-session-starts-in)時，Claude Code 則會改以該模式啟動恢復的工作階段 |

100

101<a id="resume-in-plan-mode-with-p" />

100 102

101<h5 id="resume-in-plan-mode-with-p">103<h5 id="resume-in-plan-mode-with-p">

102 使用 `-p` 在 Plan Mode 中恢復104 使用 `-p` 以 plan mode 恢復

103</h5>105</h5>

104 106

105`claude -p --resume` 或 `claude -p --continue` 執行只有在所有這些條件都成立時才會在 Plan Mode 中恢復：107`claude -p --resume` 或 `claude -p --continue` 執行只有在下列所有條件都成立時，才會以 plan mode 恢復：

106 108

107* 您傳遞 [`--permission-prompt-tool`](/docs/zh-TW/cli-reference#cli-flags)，不傳遞 [`--permission-prompts none`](/docs/zh-TW/headless#turn-off-permission-prompts-in-unattended-runs)，以便 Claude Code 可以呈現計畫以供批准109* 您傳遞 [`--permission-prompt-tool`](/docs/zh-TW/cli-reference#cli-flags) 且未傳遞 [`--permission-prompts none`](/docs/zh-TW/headless#turn-off-permission-prompts-in-unattended-runs)，以便 Claude Code 能呈現計畫以供核准

108* 您不傳遞 `--permission-mode` 或 `--dangerously-skip-permissions`110* 您未傳遞 `--permission-mode` 或 `--dangerously-skip-permissions`

109* 您不傳遞 `--fork-session`111* 您未傳遞 `--fork-session`

110* 執行不是透過[頻道](/docs/zh-TW/channels)啟動的112* 該次執行不是透過[頻道](/docs/zh-TW/channels)啟動的

111 113

112<h3 id="resume-from-a-summary">114<h3 id="resume-from-a-summary">

113 從摘要恢復115 從摘要恢復

114</h3>116</h3>

115 117

116在 Pro 或 Max 計畫上，當您恢復已閒置超過約一小時且超過 100,000 代幣的 session 時，Claude Code 會復原對話，然後在您傳送第一條訊息之前開啟對話框。到那時，session 的[提示快取](/docs/zh-TW/prompt-caching#cache-lifetime)已過期，因此無論您選擇對話框的哪個選項，下一個請求都會一次性處理完整歷史記錄。118在 Pro 或 Max 方案中，當您恢復已閒置超過約一小時且超過 100,000 個 token 的工作階段時，Claude Code 會復原對話，然後在您傳送第一則訊息之前開啟一個對話框。此時工作階段的[提示快取](/docs/zh-TW/prompt-caching#cache-lifetime)已過期，因此無論您選擇對話框中的哪個選項，下一個請求都會將完整記錄處理一次。

117 119

118對話框提供三種方式來繼續 session。它們在每種方式攜帶多少對話到後續請求中有所不同，這是在保留每個細節和每個請求傳送更少代幣之間的權衡：120對話框提供三種繼續工作階段的方式。它們的差別在於各自會將多少對話內容帶入後續請求，這是在保留每個細節與每個請求傳送較少 token 之間的取捨：

119 121

120* **從摘要恢復**：立即執行 [`/compact`](/docs/zh-TW/context-window#what-survives-compaction)。Claude Code 透過完整歷史記錄傳送一個摘要請求，然後用摘要、您最近的交換和最多五個最近讀取的檔案替換歷史記錄。後續請求會攜帶摘要而不是完整歷史記錄。122* **從摘要恢復**：立即執行 [`/compact`](/docs/zh-TW/context-window#what-survives-compaction)。Claude Code 會針對完整記錄傳送一個摘要請求，然後以摘要、您最近的幾次交流以及最多五個最近讀取的檔案取代記錄。後續請求會攜帶摘要，而不是完整記錄。

121* **按原樣恢復完整 session**：載入未更改的對話。在您傳送第一條訊息後，Claude Code 會重新處理並重新快取完整歷史記錄，然後在快取保持溫暖時從快取中重新讀取它以進行後續請求。123* **按原樣恢復完整工作階段**：以未變更的狀態載入對話。在您傳送第一則訊息後，Claude Code 會重新處理並重新快取完整記錄，然後在快取保持有效期間，於後續請求中從快取重新讀取。

122* **不要再問我**：恢復完整 session 並停止在所有未來恢復上顯示對話框。124* **不要再詢問我**：恢復完整工作階段，並在之後所有的恢復中不再顯示此對話框。

123 125

124按原樣恢復會保留對話的每個細節可用，每個請求的成本會隨著對話的大小而擴展。從摘要恢復的成本較低，因為它攜帶摘要而不是完整歷史記錄，但摘要遺漏的任何內容都不再在 Claude 的上下文中。請參閱[為什麼長 session 中的使用量會增加](/docs/zh-TW/costs#why-usage-climbs-in-a-long-session)以了解該每個請求成本的來源。126按原樣恢復會保留對話的每個細節，但每個請求的成本會隨對話大小而增加。從摘要恢復在之後的每個請求中成本較低，因為它攜帶的是摘要而不是完整記錄，但摘要遺漏的任何內容都不再存在於 Claude 的上下文中。請參閱[為什麼長時間工作階段中的使用量會攀升](/docs/zh-TW/costs#why-usage-climbs-in-a-long-session)，了解每個請求成本的來源。

125 127

126<h3 id="where-the-session-picker-looks">128<h3 id="where-the-session-picker-looks">

127 session 選擇器查看的位置129 工作階段選擇器的查找範圍

128</h3>130</h3>

129 131

130Claude Code 按專案目錄儲存 sessions。預設情況下，session 選擇器顯示：132Claude Code 會依專案目錄儲存工作階段。根據預設，工作階段選擇器會顯示：

131 133

132* 來自目前 worktree 的 sessions，包括[背景 sessions](/docs/zh-TW/agent-view)，在清單中標記為 `bg`134* 來自目前 worktree 的工作階段，包括[背景工作階段](/docs/zh-TW/agent-view)，它們在清單中會標記為 `bg`

133* 在其他地方啟動並使用 `/add-dir` 新增目前目錄的 sessions135* 在其他地方啟動並使用 `/add-dir` 新增目前目錄的工作階段

134 136

135使用 `Ctrl+W` 擴展到儲存庫的所有 worktrees，或使用 `Ctrl+A` 擴展到此機器上的每個專案。137使用 `Ctrl+W` 可將範圍擴大到儲存庫的所有 worktree，或使用 `Ctrl+A` 擴大到此機器上的每個專案。

136 138

137第一個提示是 [`/loop`](/docs/zh-TW/scheduled-tasks#run-a-prompt-repeatedly-with-%2Floop) 命令的 sessions 不會出現在選擇器中，`claude --continue` 也會跳過它們。在對話中稍後執行 `/loop` 不會隱藏 session。在 v2.1.211 之前，對話早期的 `/loop` 執行會永久隱藏選擇器中的 session。139第一個提示詞是 [`/loop`](/docs/zh-TW/scheduled-tasks#run-a-prompt-repeatedly-with-%2Floop) 命令的工作階段不會出現在選擇器中，`claude --continue` 也會跳過它們。在對話稍後才執行 `/loop` 不會隱藏該工作階段。在 v2.1.211 之前，在對話早期執行 `/loop` 會讓該工作階段永久從選擇器中隱藏。

138 140

139使用 [`/cd`](/docs/zh-TW/commands) 移動 session 會將其重新定位到新目錄的專案儲存空間，因此之後會出現在該目錄的選擇器中。從 v2.1.196 開始，移動的 session 即使在當機或強制退出後，也會保持不在舊目錄的選擇器中。在較早的版本上，當舊路徑包含特殊字元（例如底線）時，在不乾淨的退出後，它也可能在舊目錄的清單中重新出現。141使用 [`/cd`](/docs/zh-TW/commands) 移動工作階段會將其重新定位到新目錄的專案儲存空間，因此之後它會出現在該目錄的選擇器中。從 v2.1.196 開始，已移動的工作階段即使在當機或強制退出後，也不會出現在舊目錄的選擇器中。在較早的版本中，當舊路徑包含特殊字元（例如底線）時，在非正常退出後，它也可能重新出現在舊目錄的清單中。

140 142

141從同一儲存庫的另一個 worktree 選擇 session 時，Claude Code 會在原地恢復它；當 session 自己的 worktree 不再存在時，Claude Code 會[在您目前的目錄中恢復它](/docs/zh-TW/worktrees#resume-a-worktree-session)。從不相關的專案選擇 session 時，Claude Code 會將 `cd` 和恢復命令複製到您的剪貼簿。如果該專案的目錄不再存在，Claude Code 會在您目前的目錄中恢復 session，而不是複製會失敗的 `cd` 命令。143從同一儲存庫的另一個 worktree 選擇工作階段時，Claude Code 會在原處恢復它；當該工作階段自己的 worktree 已不存在時，Claude Code 會[在您目前的目錄中恢復它](/docs/zh-TW/worktrees#resume-a-worktree-session)。從不相關的專案選擇工作階段時，Claude Code 會改為將 `cd` 和恢復命令複製到您的剪貼簿。如果該專案的目錄已不存在，Claude Code 會在您目前的目錄中恢復該工作階段，而不是複製一個會失敗的 `cd` 命令。

142 144

143按名稱恢復會在目前儲存庫及其 worktrees 中解析。兩種形式都會尋找完全相符的項目，並直接恢復它，即使它位於不同的 worktree 中：145依名稱恢復會在目前儲存庫及其 worktree 中解析。兩種形式都會尋找完全相符的項目，即使它位於不同的 worktree 中也會直接恢復：

144 146

145| 命令 | 完全相符 | 模糊名稱 |147| 命令 | 完全相符 | 名稱不明確 |

146| :- | :- | :- |148| :- | :- | :- |

149 151

150<h2 id="name-your-sessions">152<h2 id="name-your-sessions">

151 命名您的 sessions153 命名您的 sessions

settings.md +36 −34

Details

405| 範圍 | 檔案 | 影響對象 | 用途 |405| 範圍 | 檔案 | 影響對象 | 用途 |

406| :- | :- | :- | :- |406| :- | :- | :- | :- |

411 411

412在「檔案」欄中，`~/.claude` 是您主目錄中的 `.claude` 資料夾，而裸露的 `.claude` 是您專案內的 `.claude` 資料夾。412在「檔案」欄中，`~/.claude` 是您家目錄中的 `.claude` 資料夾，而單獨的 `.claude` 是您專案內的 `.claude` 資料夾。

413 413

414<span id="where-each-file-applies" />414<span id="where-each-file-applies" />

415 415

425 425

426<SettingsScope />426<SettingsScope />

427 427

428* **`~/.claude/settings.json`**：您機器上的每個專案，以及隊友或雲端工作階段上的任何內容都不會428* **`~/.claude/settings.json`**：您機器上的每個專案，而不會到達隊友的機器或雲端工作階段

429* **`acme-app/.claude/settings.json`**：您的 `acme-app/`。只有在您將檔案提交到版本控制時，它才會到達隊友的複製和雲端工作階段；在您這樣做之前，它就像任何其他檔案一樣在您的磁碟上，沒有人有它429* **`acme-app/.claude/settings.json`**：您的 `acme-app/`。只有在您將檔案提交到版本控制時，它才會到達隊友的複製和雲端工作階段；在您這樣做之前，它就像任何其他檔案一樣在您的磁碟上，沒有人有它

430* **`acme-app/.claude/settings.local.json`**：僅您的 `acme-app/`。Claude Code 在第一次寫入檔案時將其新增至您的全域 git 排除項目，因此它保留在您的提交之外；如果您手動建立檔案，[自行將其新增至 `.gitignore`](#keep-personal-settings-out-of-a-repository)430* **`acme-app/.claude/settings.local.json`**：僅您的 `acme-app/`。Claude Code 在第一次寫入檔案時將其新增至您的全域 git 排除項目，因此它保留在您的提交之外；如果您手動建立檔案，[自行將其新增至 `.gitignore`](#keep-personal-settings-out-of-a-repository)

431* **受管設定**，無論是 `managed-settings.json` 檔案、MDM 政策，還是來自 claude.ai 主控台的[伺服器受管設定](/docs/zh-TW/server-managed-settings)：您的組織部署到的每台機器上的每個專案，或您使用組織帳戶登入的地方。只有伺服器受管設定才能到達雲端工作階段431* **受管設定**，無論是 `managed-settings.json` 檔案、MDM 政策，還是來自 claude.ai 主控台的[伺服器受管設定](/docs/zh-TW/server-managed-settings)：您的組織部署到的每台機器上的每個專案，或您使用組織帳戶登入的地方。只有伺服器受管設定才能到達雲端工作階段

440 440

441* **受管**：您的組織部署它。您不建立或編輯它。441* **受管**：您的組織部署它。您不建立或編輯它。

442* **共享專案**：已經使用 Claude Code 的專案可能已提交一個。如果沒有，請在專案資料夾中的 `.claude/settings.json` 建立一個。442* **共享專案**：已經使用 Claude Code 的專案可能已提交一個。如果沒有，請在專案資料夾中的 `.claude/settings.json` 建立一個。

443* **使用者**和**專案本機**：自行建立它們，或讓 Claude Code 建立它們。它在您第一次在 `/config` 選單中變更儲存在使用者設定中的選項時寫入 `~/.claude/settings.json`，例如佈景主題，以及在您第一次在權限提示上給予常設核准時寫入 `.claude/settings.local.json`，例如「是的，不要再問」以取得 Bash 命令。少數 `/config` 選項，包括**顯示提示**，改為儲存至 `.claude/settings.local.json` 而不是使用者檔案。443* **使用者**和**專案本機**：自行建立它們，或讓 Claude Code 建立它們。它在您第一次在 `/config` 選單中變更儲存在使用者設定中的選項時寫入 `~/.claude/settings.json`，例如佈景主題，以及在您第一次在權限提示上給予常設核准時寫入 `.claude/settings.local.json`，例如針對 Bash 命令選擇「是的，不要再問」。少數 `/config` 選項，包括**顯示提示**，改為儲存至 `.claude/settings.local.json` 而不是使用者檔案。

444 444

445<Info>445<Info>

446 在 Windows 上，`~/.claude` 表示 `%USERPROFILE%\.claude`。若要將主目錄檔案保留在其他地方，請設定 [`CLAUDE_CONFIG_DIR`](/docs/zh-TW/env-vars)；Claude Code 會改為在那裡儲存您的設定、工作階段歷史記錄和 plugins。446 在 Windows 上，`~/.claude` 表示 `%USERPROFILE%\.claude`。若要將家目錄檔案保留在其他地方，請設定 [`CLAUDE_CONFIG_DIR`](/docs/zh-TW/env-vars)；Claude Code 會改為在那裡儲存您的設定、工作階段歷史記錄和外掛。

447</Info>447</Info>

448 448

449Claude Code 也保留第五個檔案 [`~/.claude.json`](/docs/zh-TW/claude-directory#ce-claude-json)，它為自己寫入；您不需要編輯它。它保留您的登入工作階段、[MCP 伺服器](/docs/zh-TW/mcp)設定、每個專案的狀態（例如信任決定），以及 `/config` 為您寫入的[全域設定金鑰](/docs/zh-TW/settings-reference#global-config-settings)。449Claude Code 也保留第五個檔案 [`~/.claude.json`](/docs/zh-TW/claude-directory#ce-claude-json)，它為自己寫入；您不需要編輯它。它保留您的登入工作階段、[MCP 伺服器](/docs/zh-TW/mcp)設定、每個專案的狀態（例如信任決定），以及 `/config` 為您寫入的[全域設定鍵](/docs/zh-TW/settings-reference#global-config-settings)。

450 450

451<h3 id="share-settings-with-your-team">451<h3 id="share-settings-with-your-team">

452 與您的團隊共享設定452 與您的團隊共享設定

453</h3>453</h3>

454 454

455提交 `.claude/settings.json` 以便複製儲存庫的每個人都取得相同的權限、hooks 和 plugins。每個隊友仍然可以在自己的 `.claude/settings.local.json` 中為自己覆寫它，因此個人例外不需要提交。如需完整的團隊檔案，請參閱[團隊的共享設定](/docs/zh-TW/settings-example#a-teams-shared-settings)。455提交 `.claude/settings.json` 以便複製儲存庫的每個人都取得相同的權限、hook 和外掛。每個隊友仍然可以在自己的 `.claude/settings.local.json` 中為自己覆寫它，因此個人例外不需要提交。如需完整的團隊檔案，請參閱[團隊的共享設定](/docs/zh-TW/settings-example#a-teams-shared-settings)。

456 456

457您提交的某些內容會等到每個隊友[信任資料夾](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)，而少數金鑰永遠不會從儲存庫檔案生效；[對不適用的設定進行疑難排解](#common-cases)涵蓋兩者。457您提交的某些內容會等到每個隊友[信任資料夾](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)，而少數設定鍵永遠不會從儲存庫檔案生效；[對不適用的設定進行疑難排解](#common-cases)涵蓋兩者。

458 458

459<span id="local-settings-file" />459<span id="local-settings-file" />

460 460

468 將個人設定保留在儲存庫之外468 將個人設定保留在儲存庫之外

469</h3>469</h3>

470 470

471若要在一個專案中為自己變更設定而不為隊友變更，請將其儲存在專案內的 `.claude/settings.local.json` 中。Claude Code 在提交的 `.claude/settings.json` 上應用該檔案，因此如果您的團隊檔案設定 `"model": "claude-sonnet-5"` 而您想要 Opus，請在本機檔案中放入 `"model": "claude-opus-5-5"`，只有您的工作階段會變更。471若要在一個專案中為自己變更設定而不為隊友變更，請將其儲存在專案內的 `.claude/settings.local.json` 中。Claude Code 在提交的 `.claude/settings.json` 上套用該檔案，因此如果您的團隊檔案設定 `"model": "claude-sonnet-5"` 而您想要 Opus，請在本機檔案中放入 `"model": "claude-opus-5-5"`，只有您的工作階段會變更。

472 472

473Claude Code 也寫入此檔案，將其保留在您的提交之外，並在不需要信任步驟的情況下應用其允許規則：473Claude Code 也寫入此檔案，將其保留在您的提交之外，並在不需要信任步驟的情況下套用其允許規則：

474 474

475* **Claude Code 也寫入它。** 當 Claude 要求執行 Bash 命令的權限，而您選擇「是的，不要再問」時，Claude Code 會將該[權限核准](/docs/zh-TW/permissions#permission-system)儲存在此處作為 `allow` 規則。475* **Claude Code 也寫入它。** 當 Claude 要求執行 Bash 命令的權限，而您選擇「是的，不要再問」時，Claude Code 會將該[權限核准](/docs/zh-TW/permissions#permission-system)儲存在此處作為 `allow` 規則。

476* **您不需要自行 gitignore 它，除非您手動建立它。** Claude Code 在不已忽略它的 git 儲存庫中第一次寫入檔案時，它會將 `**/.claude/settings.local.json` 新增至您的全域 git 排除項目檔案，因此檔案在每個儲存庫中保留在您的提交之外。該檔案是 `core.excludesFile`，當您的全域 git 設定將其設定為絕對或 `~` 前綴路徑時；否則它是 `$XDG_CONFIG_HOME/git/ignore`，或當 `XDG_CONFIG_HOME` 未設定時為 `~/.config/git/ignore`。如果您手動建立檔案，而 Claude Code 尚未寫入它，請自行將其新增至 `.gitignore`。476* **您不需要自行 gitignore 它，除非您手動建立它。** Claude Code 在尚未忽略它的 git 儲存庫中第一次寫入檔案時，它會將 `**/.claude/settings.local.json` 新增至您的全域 git 排除項目檔案，因此檔案在每個儲存庫中保留在您的提交之外。當您的全域 git 設定將 `core.excludesFile` 設為絕對路徑或 `~` 前綴路徑時，該檔案就是 `core.excludesFile`；否則它是 `$XDG_CONFIG_HOME/git/ignore`，或當 `XDG_CONFIG_HOME` 未設定時為 `~/.config/git/ignore`。如果您手動建立檔案，而 Claude Code 尚未寫入它，請自行將其新增至 `.gitignore`。

477* **其 allow 規則在檔案保持未追蹤時不等待信任。** 因為檔案是您的而不是儲存庫的，Claude Code 應用其 `allow` 規則而不需要它對提交檔案要求的[工作區信任](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)步驟。如果檔案由 git 追蹤，信任步驟也適用於它；請參閱[當您的本機設定檔案需要信任時](/docs/zh-TW/permissions#when-your-local-settings-file-needs-trust)。477* **其 allow 規則在檔案保持未追蹤時不等待信任。** 因為檔案是您的而不是儲存庫的，Claude Code 套用其 `allow` 規則而不需要它對提交檔案要求的[工作區信任](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)步驟。如果檔案由 git 追蹤，信任步驟也適用於它；請參閱[當您的本機設定檔案需要信任時](/docs/zh-TW/permissions#when-your-local-settings-file-needs-trust)。

478 478

479<span id="where-claude-code-looks-for-each-file" />479<span id="where-claude-code-looks-for-each-file" />

480 480

486 Claude Code 在 git 儲存庫中保留本機檔案的位置486 Claude Code 在 git 儲存庫中保留本機檔案的位置

487</h4>487</h4>

488 488

489當 Claude 要求執行 Bash 命令的權限，而您選擇「是的，不要再問」時，Claude Code 會將該核准儲存為 `.claude/settings.local.json` 中的 `allow` 規則。如果您在 git 儲存庫的子目錄中啟動 Claude Code，它會在儲存庫根目錄讀取和寫入該檔案，並在整個儲存庫中應用核准。在 [worktree](/docs/zh-TW/worktrees) 中，它使用主簽出根目錄的檔案。489當 Claude 要求執行 Bash 命令的權限，而您選擇「是的，不要再問」時，Claude Code 會將該核准儲存為 `.claude/settings.local.json` 中的 `allow` 規則。如果您在 git 儲存庫的子目錄中啟動 Claude Code，它會在儲存庫根目錄讀取和寫入該檔案，並在整個儲存庫中套用核准。在 [worktree](/docs/zh-TW/worktrees) 中，它使用主簽出根目錄的檔案。

490 490

491兩個規則限定根位置：491兩個規則限定根位置：

492 492

493* **當檔案改為與 `.claude/settings.json` 保持在一起時**：在 git 儲存庫之外，當儲存庫根目錄是您的主目錄時，在 Windows 上，或當儲存庫根目錄或其 `.git` 或 `.claude` 項目不由您的使用者擁有時。493* **當檔案改為與 `.claude/settings.json` 保持在一起時**：在 git 儲存庫之外，當儲存庫根目錄是您的家目錄時，在 Windows 上，或當儲存庫根目錄或其 `.git` 或 `.claude` 項目不由您的使用者擁有時。

494* **檔案中的路徑不在儲存庫根目錄錨定**：以 `/` 開頭的權限規則或相對沙箱路徑[改為在工作階段的主要工作目錄錨定](/docs/zh-TW/permissions#read-and-edit)。494* **檔案中的路徑不在儲存庫根目錄錨定**：以 `/` 開頭的權限規則或相對沙箱路徑[改為在工作階段的主要工作目錄錨定](/docs/zh-TW/permissions#read-and-edit)。

495 495

496在 v2.1.211 之前，Claude Code 在啟動目錄中保留檔案。它仍然讀取較早版本在根檔案旁邊留下的檔案；當兩者設定相同金鑰時，根的值適用，兩個檔案的權限規則適用。Agent SDK 的 [`resolveSettings()`](/docs/zh-TW/agent-sdk/typescript#resolvesettings) 協助程式始終從啟動目錄讀取檔案。496在 v2.1.211 之前，Claude Code 在啟動目錄中保留檔案。它仍然會讀取較早版本留在該處的檔案，與根檔案一併讀取；當兩者設定相同的設定鍵時，以根的值為準，而兩個檔案的權限規則都適用。Agent SDK 的 [`resolveSettings()`](/docs/zh-TW/agent-sdk/typescript#resolvesettings) 協助程式始終從啟動目錄讀取檔案。

497 497

498Claude Code 從工作階段的[主要工作目錄](/docs/zh-TW/permissions#working-directories)讀取共享 `.claude/settings.json`，因此若要使用在儲存庫根目錄提交的檔案，請從那裡啟動 Claude Code。在您[使用 `/cd` 移動工作階段](/docs/zh-TW/permissions#move-the-session-to-another-directory)後，Claude Code 改為從新目錄讀取兩個專案檔案，按相同規則放置本機檔案。從您移動到的目錄讀取它們需要 Claude Code v2.1.246 或更新版本。498Claude Code 從工作階段的[主要工作目錄](/docs/zh-TW/permissions#working-directories)讀取共享 `.claude/settings.json`，因此若要使用在儲存庫根目錄提交的檔案，請從那裡啟動 Claude Code。在您[使用 `/cd` 移動工作階段](/docs/zh-TW/permissions#move-the-session-to-another-directory)後，Claude Code 改為從新目錄讀取兩個專案檔案，按相同規則放置本機檔案。從您移動到的目錄讀取它們需要 Claude Code v2.1.246 或更新版本。

499 499

511 檢查您的組織強制執行的內容511 檢查您的組織強制執行的內容

512</h3>512</h3>

513 513

514如果您的組織管理 Claude Code，某些設定是為您決定的，您在自己的檔案中放入的任何內容都不會變更它們。若要查看哪些，請執行 `/status`：`Setting sources` 行命名適用於您的受管來源。受管設定在此機器上 Claude Code 執行的任何地方適用；[開發人員可以變更的內容](/docs/zh-TW/managed-settings#what-a-developer-can-change)涵蓋本機管理員權限和 Claude Code 以外的工具。514如果您的組織管理 Claude Code，某些設定是為您決定的，您在自己的檔案中放入的任何內容都不會變更它們。若要查看哪些，請執行 `/status`：`Setting sources` 行會列出適用於您的受管來源。受管設定在此機器上 Claude Code 執行的任何地方適用；[開發人員可以變更的內容](/docs/zh-TW/managed-settings#what-a-developer-can-change)涵蓋本機管理員權限和 Claude Code 以外的工具。

515 515

516受管設定通過受管設定頁面上的[傳遞機制](/docs/zh-TW/managed-settings#delivery-mechanisms)到達您，最常見的是：516受管設定透過受管設定頁面上的[傳遞機制](/docs/zh-TW/managed-settings#delivery-mechanisms)到達您，最常見的是：

517 517

518* [伺服器受管設定](/docs/zh-TW/server-managed-settings)，Claude Code 從 claude.ai 管理主控台或自託管[Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway)擷取518* [伺服器受管設定](/docs/zh-TW/server-managed-settings)，Claude Code 從 claude.ai 管理主控台或自行託管的 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway)擷取

519* MDM 或作業系統層級政策，以及系統目錄中的 `managed-settings.json` 檔案519* MDM 或作業系統層級政策，以及系統目錄中的 `managed-settings.json` 檔案

520* 嵌入主機（例如 Claude Desktop），通過 SDK `managedSettings` 選項；請參閱[從嵌入主機控制政策](/docs/zh-TW/managed-settings#parent-settings-from-embedding-hosts)520* 嵌入主機（例如 Claude Desktop），透過 SDK `managedSettings` 選項；請參閱[從嵌入主機控制政策](/docs/zh-TW/managed-settings#parent-settings-from-embedding-hosts)

521 521

522在在 Claude Desktop 應用程式中在您的機器上執行的 [Cowork](https://claude.com/docs/cowork/overview) 工作階段中，Claude Code 不會從 claude.ai 管理主控台擷取伺服器受管設定，它讀取部署到您的裝置的政策，除非您的組織的 Claude Desktop 設定設定 `requireCoworkFullVmSandbox`。[政策適用的位置和時間](/docs/zh-TW/managed-settings#where-and-when-a-policy-applies)涵蓋 Cowork 和雲端工作階段。522在 Claude Desktop 應用程式中於您的機器上執行的 [Cowork](https://claude.com/docs/cowork/overview) 工作階段中，Claude Code 不會從 claude.ai 管理主控台擷取伺服器受管設定，且它會讀取部署到您裝置的政策，除非您組織的 Claude Desktop 設定設定了 `requireCoworkFullVmSandbox`。[政策適用的位置和時間](/docs/zh-TW/managed-settings#where-and-when-a-policy-applies)涵蓋 Cowork 和雲端工作階段。

523 523

524如果您是管理員，[為您的組織設定 Claude Code](/docs/zh-TW/admin-setup) 會逐步說明選擇要強制執行的內容，而[部署受管設定](/docs/zh-TW/managed-settings)涵蓋傳遞以及如何確認政策生效。524如果您是管理員，[為您的組織設定 Claude Code](/docs/zh-TW/admin-setup) 會逐步說明選擇要強制執行的內容，而[部署受管設定](/docs/zh-TW/managed-settings)涵蓋傳遞以及如何確認政策生效。

525 525

653 設定優先順序653 設定優先順序

654</h2>654</h2>

655 655

656當相同的鍵出現在多個位置時，Claude Code 會使用最高層級設定的值。下面的堆疊顯示各個層級，最高的在頂部；較高層級的鍵會覆蓋下面任何地方的相同鍵。656當相同的鍵出現在多個位置時，Claude Code 會使用最高層級設定的值。下面的堆疊顯示各個層級，最高的在頂部；較高層級的鍵會覆寫下面任何地方的相同鍵。

657 657

658<SettingsPrecedence />658<SettingsPrecedence />

659 659

660按順序，優先順序最高的優先：660按順序，優先順序最高的優先：

661 661

6621. **受管設定**：您的組織部署的設定，透過 `managed-settings.json` 檔案、MDM 原則或來自 claude.ai 主控台的[伺服器管理設定](/docs/zh-TW/server-managed-settings)。您設定的任何內容都不會覆蓋它們：您使用 `--settings` 傳遞的鍵不會覆蓋相同的受管鍵，而 `--model` 之類的旗標只會從您的組織允許的模型中選擇。受管 `model` 設定每個工作階段開始時的模型，您仍然可以使用 `/model` 切換；鎖定是 [`availableModels`](/docs/zh-TW/settings-reference#availablemodels)，它限制 `/model`、`--model` 和您自己檔案中的 `model` 鍵。當您的組織提供多個受管來源時，[受管層級內的優先順序](/docs/zh-TW/managed-settings#precedence-within-the-managed-tier)規則說明 Claude Code 從每個來源讀取的內容。6621. **受管設定**：您的組織部署的設定，透過 `managed-settings.json` 檔案、MDM 原則或來自 claude.ai 主控台的[伺服器管理設定](/docs/zh-TW/server-managed-settings)。您自己的設定檔案或 `--settings` 中的任何內容都不會覆寫受管鍵，而 `--model` 之類的旗標只會從您的組織允許的模型中選擇。受管 [`model`](/docs/zh-TW/settings-reference#model) 是起始預設值，而不是鎖定；鎖定是 [`availableModels`](/docs/zh-TW/settings-reference#availablemodels) 和 [`deniedModels`](/docs/zh-TW/settings-reference#deniedmodels)。當您的組織提供多個受管來源時，[受管層級內的優先順序](/docs/zh-TW/managed-settings#precedence-within-the-managed-tier)規則說明 Claude Code 從每個來源讀取的內容。

6632. **命令列引數**：您從終端機啟動 `claude` 時傳遞的旗標，適用於一個工作階段；請參閱[變更一個工作階段的設定](#change-a-setting-for-one-session)。Claude Code 使用 `--settings <file-or-json>` 傳遞的 JSON 與您的設定檔案合併，遵循與其他層級相同的規則：它採用您在此設定的鍵而不是本機、專案或使用者設定中的相同鍵，並為您省略的鍵保留較低層級的值。6632. **命令列**：您啟動 `claude` 時使用 `--settings <file-or-json>` 傳遞的 JSON，僅適用於該工作階段；請參閱[變更一個工作階段的設定](#change-a-setting-for-one-session)。您在此設定的鍵會覆寫您專案和使用者設定檔案中的相同鍵，而您省略的鍵會保留這些檔案中的值。其他旗標（例如 `--model`）會為工作階段設定單一項目，不屬於此堆疊；[設定參考](/docs/zh-TW/settings-reference)上的鍵項目說明哪些旗標會覆寫它。

6643. **專案本機設定** (`.claude/settings.local.json`)：您對此專案的個人設定。6643. **專案本機設定** (`.claude/settings.local.json`)：您對此專案的個人設定。

6654. **共用專案設定** (`.claude/settings.json`)：您的團隊簽入原始碼控制的設定。6654. **共用專案設定** (`.claude/settings.json`)：您的團隊簽入原始碼控制的設定。

6665. **使用者設定** (`~/.claude/settings.json`)：您對每個專案的個人設定。6665. **使用者設定** (`~/.claude/settings.json`)：您對每個專案的個人設定。

670對於少數安全敏感的鍵，Claude Code 會尊重來自較低層級的更嚴格值而不是受管值；[受管設定優先順序的例外](#exceptions-to-managed-settings-precedence)列出了它們。670對於少數安全敏感的鍵，Claude Code 會尊重來自較低層級的更嚴格值而不是受管值；[受管設定優先順序的例外](#exceptions-to-managed-settings-precedence)列出了它們。

671 671

672<h3 id="lists-merge-instead-of-overriding">672<h3 id="lists-merge-instead-of-overriding">

673 列表合併而不是覆蓋673 列表合併而不是覆寫

674</h3>674</h3>

675 675

676當您在多個檔案中設定相同的列表鍵（例如 `permissions.allow`）時，Claude Code 會合併列表而不是選擇一個，因此每個檔案都可以新增項目而不移除另一個檔案的項目。四個保存模型列表或每個模型項目的鍵遵循自己的規則：676當您在多個檔案中設定相同的列表鍵（例如 `permissions.allow`）時，Claude Code 會合併列表而不是選擇一個，因此每個檔案都可以新增項目而不移除另一個檔案的項目。四個保存模型列表或每個模型項目的鍵遵循自己的規則：

689當 Claude 工作時，Claude Code 在微調器下方顯示一行提示，例如「使用 /config 變更您的預設權限模式（包括 Plan Mode）」。假設您想關閉這些提示，因此您在 `~/.claude/settings.json` 中將 [`spinnerTipsEnabled`](/docs/zh-TW/settings-reference#spinnertipsenabled) 設定為 `false`。下面的每個情景都是可能將它們重新開啟的事情，以及您可以做什麼。689當 Claude 工作時，Claude Code 在微調器下方顯示一行提示，例如「使用 /config 變更您的預設權限模式（包括 Plan Mode）」。假設您想關閉這些提示，因此您在 `~/.claude/settings.json` 中將 [`spinnerTipsEnabled`](/docs/zh-TW/settings-reference#spinnertipsenabled) 設定為 `false`。下面的每個情景都是可能將它們重新開啟的事情，以及您可以做什麼。

690 690

691<h4 id="team-settings-override-personal-settings">691<h4 id="team-settings-override-personal-settings">

692 團隊設定覆蓋個人設定692 團隊設定覆寫個人設定

693</h4>693</h4>

694 694

695您的團隊的 `.claude/settings.json` 將其設定為 `true`。Claude Code 使用專案值，因為共用專案位於使用者之上，因此您在該專案中看到提示，在其他地方看不到。695您的團隊的 `.claude/settings.json` 將其設定為 `true`。Claude Code 使用專案值，因為共用專案位於使用者之上，因此您在該專案中看到提示，在其他地方看不到。

697您可以取回您的值：在該專案的 `.claude/settings.local.json` 中新增 `"spinnerTipsEnabled": false`。專案本機位於共用專案之上，因此您在那裡的工作階段停止顯示提示，您的隊友的工作階段不會改變。697您可以取回您的值：在該專案的 `.claude/settings.local.json` 中新增 `"spinnerTipsEnabled": false`。專案本機位於共用專案之上，因此您在那裡的工作階段停止顯示提示，您的隊友的工作階段不會改變。

698 698

699<h4 id="organization-settings-override-everything">699<h4 id="organization-settings-override-everything">

700 組織設定覆蓋一切700 組織設定覆寫一切

701</h4>701</h4>

702 702

703您的組織的受管設定將其設定為 `true`。您在使用者、專案或本機設定中放置的任何內容都不會關閉提示，`--settings` 也不會。受管是最高層級。703您的組織的受管設定將其設定為 `true`。您在使用者、專案或本機設定中放置的任何內容都不會關閉提示，`--settings` 也不會。受管是最高層級。

705您無法取回您的值。執行 `/status` 以查看哪個受管來源適用，並詢問您的管理員是否應該變更原則。705您無法取回您的值。執行 `/status` 以查看哪個受管來源適用，並詢問您的管理員是否應該變更原則。

706 706

707<h4 id="the-command-line-overrides-your-files-for-one-session">707<h4 id="the-command-line-overrides-your-files-for-one-session">

708 命令列覆蓋您的檔案一個工作階段708 命令列覆寫您的檔案一個工作階段

709</h4>709</h4>

710 710

711您使用 `claude --settings '{"spinnerTipsEnabled": true}'` 啟動了工作階段。命令列位於除受管外的每個檔案之上，因此該工作階段顯示提示，即使您的檔案說 `false`。711您使用 `claude --settings '{"spinnerTipsEnabled": true}'` 啟動了工作階段。命令列位於除受管外的每個檔案之上，因此該工作階段顯示提示，即使您的檔案說 `false`。

716 旗標或環境變數設定相同的內容716 旗標或環境變數設定相同的內容

717</h4>717</h4>

718 718

719某些鍵具有命令列旗標或環境變數，無論哪個檔案設定它，都會覆蓋設定值：`ANTHROPIC_MODEL` 覆蓋 [`model`](/docs/zh-TW/settings-reference#model) 設定，`--model` 在一個工作階段內覆蓋兩者。719某些鍵具有命令列旗標或環境變數，無論哪個檔案設定它，都會覆寫設定值：`ANTHROPIC_MODEL` 覆寫 [`model`](/docs/zh-TW/settings-reference#model) 設定，`--model` 在一個工作階段內覆寫兩者。

720 720

721您是否可以取回您的值取決於鍵：取消設定變數或刪除旗標，並檢查[設定參考](/docs/zh-TW/settings-reference)上的鍵項目和[環境變數參考](/docs/zh-TW/env-vars)上的變數列，以了解 Claude Code 使用哪一個。721您是否可以取回您的值取決於鍵：取消設定變數或刪除旗標，並檢查[設定參考](/docs/zh-TW/settings-reference)上的鍵項目和[環境變數參考](/docs/zh-TW/env-vars)上的變數列，以了解 Claude Code 使用哪一個。

722 722

740 740

741其他東西設定了相同的鍵，檔案無法設定該值，或檔案未載入：741其他東西設定了相同的鍵，檔案無法設定該值，或檔案未載入：

742 742

743* **較高層級設定它。** 另一個設定檔案、`--settings` 旗標或受管來源在您的上方設定鍵；[堆疊](#settings-precedence)說明哪一個。旗標或環境變數也可以自行覆蓋鍵，按鍵決定；[設定參考](/docs/zh-TW/settings-reference)上的鍵項目說明 Claude Code 使用哪一個，[`env` 項目](/docs/zh-TW/settings-reference#env)涵蓋受管 `env` 值與 shell 匯出。743* **較高層級設定它。** 另一個設定檔案、`--settings` 旗標或受管來源在您的上方設定鍵；[堆疊](#settings-precedence)說明哪一個。旗標或環境變數也可以自行覆寫鍵，按鍵決定；[設定參考](/docs/zh-TW/settings-reference)上的鍵項目說明 Claude Code 使用哪一個，[`env` 項目](/docs/zh-TW/settings-reference#env)涵蓋受管 `env` 值與 shell 匯出。

744* **安全鍵保持其嚴格值。** 對於少數鍵，Claude Code 尊重來自任何檔案的限制值，因此專案 `true` 的 [`disableClaudeAiConnectors`](/docs/zh-TW/settings-reference#disableclaudeaiconnectors) 保持開啟；請參閱[受管設定優先順序的例外](#exceptions-to-managed-settings-precedence)。744* **安全鍵保持其嚴格值。** 對於少數鍵，Claude Code 尊重來自任何檔案的限制值，因此專案 `true` 的 [`disableClaudeAiConnectors`](/docs/zh-TW/settings-reference#disableclaudeaiconnectors) 保持開啟；請參閱[受管設定優先順序的例外](#exceptions-to-managed-settings-precedence)。

745* **檔案無法設定該值。** [`permissions.defaultMode`](/docs/zh-TW/settings-reference#permissions-defaultmode) 值 `auto` 和 `bypassPermissions` 不會從專案或本機設定生效；改為在使用者或受管設定中設定它們，或為一個工作階段傳遞 `--permission-mode`。在 v2.1.257 之前，`bypassPermissions` 從任何檔案生效。745* **檔案無法設定該值。** [`permissions.defaultMode`](/docs/zh-TW/settings-reference#permissions-defaultmode) 值 `auto` 和 `bypassPermissions` 不會從專案或本機設定生效；改為在使用者或受管設定中設定它們，或為一個工作階段傳遞 `--permission-mode`。在 v2.1.257 之前，`bypassPermissions` 從任何檔案生效。

746 746

770* **Claude Code 忽略儲存庫檔案中的鍵。** 在[設定索引](/docs/zh-TW/settings-reference#settings-index)的「範圍」欄中查找 `User, local, or managed`、`User or managed`、`Managed` 或 `Global config`。這些鍵永遠不會從共用檔案應用，除了少數儲存庫檔案仍然可以關閉的鍵。每個這些項目在其「範圍」行上都說明了這一點。`Global config` 鍵僅從 `~/.claude.json` 應用。770* **Claude Code 忽略儲存庫檔案中的鍵。** 在[設定索引](/docs/zh-TW/settings-reference#settings-index)的「範圍」欄中查找 `User, local, or managed`、`User or managed`、`Managed` 或 `Global config`。這些鍵永遠不會從共用檔案應用，除了少數儲存庫檔案仍然可以關閉的鍵。每個這些項目在其「範圍」行上都說明了這一點。`Global config` 鍵僅從 `~/.claude.json` 應用。

771 771

772 在 `env` 鍵內，遙測匯出變數也永遠不會從共用檔案應用，除了少數關閉值；請參閱[Claude Code 在 `env` 中忽略的變數](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)。772 在 `env` 鍵內，遙測匯出變數也永遠不會從共用檔案應用，除了少數關閉值；請參閱[Claude Code 在 `env` 中忽略的變數](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)。

773* **鍵等待信任。** `permissions.allow` 規則、`permissions.additionalDirectories`、`extraKnownMarketplaces` 和大多數 [`env`](/docs/zh-TW/settings-reference#env) 值僅在每個隊友[信任資料夾](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)後應用。在那之前，他們仍然看到提示，不會從檔案宣告的市場獲得外掛程式。`deny` 和 `ask` 規則立即應用。773* **鍵等待信任。** `permissions.allow` 規則、`permissions.additionalDirectories`、`extraKnownMarketplaces` 和大多數 [`env`](/docs/zh-TW/settings-reference#env) 值僅在每個隊友[信任資料夾](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)後應用。在那之前，他們仍然看到提示，不會從檔案宣告的市集獲得外掛。`deny` 和 `ask` 規則立即應用。

774 774

775<h4 id="permission-rules-combine-differently-than-you-expected">775<h4 id="permission-rules-combine-differently-than-you-expected">

776 權限規則的合併方式與您預期的不同776 權限規則的合併方式與您預期的不同

785 受管設定優先順序的例外785 受管設定優先順序的例外

786</h3>786</h3>

787 787

788對於少數值限制工作階段的鍵，Claude Code 尊重來自範圍的限制值，該範圍在其他情況下無法覆蓋受管設定。在此表中找到鍵以查看它尊重哪個值以及來自何處。788對於少數值限制工作階段的鍵，Claude Code 尊重來自範圍的限制值，該範圍在其他情況下無法覆寫受管設定。在此表中找到鍵以查看它尊重哪個值以及來自何處。

789 789

790| 鍵 | Claude Code 尊重的值 | 備註 |790| 鍵 | Claude Code 尊重的值 | 備註 |

791| :- | :- | :- |791| :- | :- | :- |

793| [`enableArtifact`](/docs/zh-TW/settings-reference#enableartifact) | 來自任何範圍的 `false`，以及來自任何範圍的 `disableArtifact: true` | 即使受管來源設定 `true` 也被尊重；沒有任何東西會打開[成品工具](/docs/zh-TW/artifacts#disable-artifacts)。需要 Claude Code v2.1.242 或更新版本 |793| [`enableArtifact`](/docs/zh-TW/settings-reference#enableartifact) | 來自任何範圍的 `false`，以及來自任何範圍的 `disableArtifact: true` | 即使受管來源設定 `true` 也被尊重；沒有任何東西會重新開啟 [Artifact 工具](/docs/zh-TW/artifacts#disable-artifacts)。需要 Claude Code v2.1.242 或更新版本 |

795| [`permissions.blockReadsOutsideWorkingDirectories`](/docs/zh-TW/settings-reference#permissions-blockreadsoutsideworkingdirectories) | 來自任何範圍的 `true` | 即使受管來源設定 `false` 也被尊重。需要 Claude Code v2.1.257 或更新版本 |

796| [`autoMode.classifyAllShell`](/docs/zh-TW/settings-reference#automode-classifyallshell) | 來自 `~/.claude/settings.json` 或 `--settings` 的 `true` | 即使受管來源設定 `false` 也被尊重 |

795| [`remoteControlAtStartup`](/docs/zh-TW/settings-reference#remotecontrolatstartup) | 來自 `.claude/settings.json` 或 `.claude/settings.local.json` 的 `false` | 即使受管來源設定 `true` 也被尊重；專案或本機 `true` 被忽略 |797| [`remoteControlAtStartup`](/docs/zh-TW/settings-reference#remotecontrolatstartup) | 來自 `.claude/settings.json` 或 `.claude/settings.local.json` 的 `false` | 即使受管來源設定 `true` 也被尊重；專案或本機 `true` 被忽略 |

796| [`crossSessionInbound`](/docs/zh-TW/settings-reference#crosssessioninbound) | 來自 `.claude/settings.json` 或 `.claude/settings.local.json` 的更嚴格值，在 `accept` \< `hold` \< `refuse` 梯級上 | 在受管、`--settings` 和使用者值上被尊重；不是更嚴格的專案或本機值被忽略 |798| [`crossSessionInbound`](/docs/zh-TW/settings-reference#crosssessioninbound) | 來自 `.claude/settings.json` 或 `.claude/settings.local.json` 的更嚴格值，在 `accept` \< `hold` \< `refuse` 梯級上 | 在受管、`--settings` 和使用者值上被尊重；不是更嚴格的專案或本機值被忽略 |

797| [`useAutoModeDuringPlan`](/docs/zh-TW/settings-reference#useautomodeduringplan) | 來自任何受管來源、`--settings`、`~/.claude/settings.json` 或 `.claude/settings.local.json` 的 `false` | 即使獲勝的受管來源設定 `true` 也被尊重；`.claude/settings.json` 中的 `false` 被忽略 |799| [`useAutoModeDuringPlan`](/docs/zh-TW/settings-reference#useautomodeduringplan) | 來自任何受管來源、`--settings`、`~/.claude/settings.json` 或 `.claude/settings.local.json` 的 `false` | 即使獲勝的受管來源設定 `true` 也被尊重；`.claude/settings.json` 中的 `false` 被忽略 |

799| [`syncClaudeAiPlugins`](/docs/zh-TW/settings-reference#syncclaudeaiplugins) | 來自任何受管來源、`--settings`、`~/.claude/settings.json` 或 `.claude/settings.local.json` 的 `false` | 即使獲勝的受管來源設定 `true` 也被尊重；`.claude/settings.json` 中的 `false` 被忽略 |801| [`syncClaudeAiPlugins`](/docs/zh-TW/settings-reference#syncclaudeaiplugins) | 來自任何受管來源、`--settings`、`~/.claude/settings.json` 或 `.claude/settings.local.json` 的 `false` | 即使獲勝的受管來源設定 `true` 也被尊重；`.claude/settings.json` 中的 `false` 被忽略 |

800| [`maxEffortLevel`](/docs/zh-TW/settings-reference#maxeffortlevel) | 來自任何範圍（包括 `--settings`）的較低上限 | 即使 Claude Code 應用的受管設定設定較高的上限也被尊重；最低上限適用。需要 Claude Code v2.1.267 或更新版本 |802| [`maxEffortLevel`](/docs/zh-TW/settings-reference#maxeffortlevel) | 來自任何範圍（包括 `--settings`）的較低上限 | 即使 Claude Code 應用的受管設定設定較高的上限也被尊重；最低上限適用。需要 Claude Code v2.1.267 或更新版本 |

801 803

802執行 Claude Code 並設定 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-TW/env-vars) 的應用程式也是例外。Claude Code 採用該應用程式的模型設定而不是來自每個受管來源的 `model`、`fallbackModel`、`modelPicker` 和 `modelOverrides` 鍵，以及受管 `env` 區塊中的模型選擇變數，例如 `ANTHROPIC_MODEL` 和 `ANTHROPIC_DEFAULT_*_MODEL` 系列。Claude Code 保持受管 [`availableModels`](/docs/zh-TW/settings-reference#availablemodels) 允許清單有效，除非應用程式提供自己的。804在自身內部執行 Claude Code 並設定 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-TW/env-vars) 的應用程式也是例外。Claude Code 採用該應用程式的模型設定而不是來自每個受管來源的 `model`、`fallbackModel`、`modelPicker` 和 `modelOverrides` 鍵，以及受管 `env` 區塊中的模型選擇變數，例如 `ANTHROPIC_MODEL` 和 `ANTHROPIC_DEFAULT_*_MODEL` 系列。Claude Code 保持受管 [`availableModels`](/docs/zh-TW/settings-reference#availablemodels) 允許清單有效，除非應用程式提供自己的。

803 805

804<h2 id="settings-in-cloud-sessions">806<h2 id="settings-in-cloud-sessions">

805 雲端工作階段中的設定807 雲端工作階段中的設定

settings-reference.md +1 −1

Details

870 870

871透過將此設定為 `false` 來為每個工作階段關閉[延伸思考](/docs/zh-TW/model-config#extended-thinking)。思考預設為開啟，因此 `true` 不會改變任何內容。大多數人透過 `/config` 而不是編輯檔案來設定此項。871透過將此設定為 `false` 來為每個工作階段關閉[延伸思考](/docs/zh-TW/model-config#extended-thinking)。思考預設為開啟，因此 `true` 不會改變任何內容。大多數人透過 `/config` 而不是編輯檔案來設定此項。

872 872

873在始終思考的模型上，例如 Opus 5.5、Sonnet 5.5 和 Fable 模型，`false` 無效。在[第三方提供者](/docs/zh-TW/third-party-integrations)上，Claude Code 省略 `thinking` 參數而不是關閉思考，因此自適應推理模型可能仍會思考。在 Anthropic API 上關閉思考時，Claude Code 會傳送努力 `high` 而不是更高級別給它知道[不接受該組合](/docs/zh-TW/errors#effort-isnt-available-with-thinking-turned-off)的模型，例如 Opus 5。873在始終思考的模型上，例如 Opus 5.5、Sonnet 5.5、Haiku 5.5 和 Fable 模型，`false` 無效。在[第三方提供者](/docs/zh-TW/third-party-integrations)上，Claude Code 會省略 `thinking` 參數而不是關閉思考，因此自適應推理模型可能仍會思考。在 Anthropic API 上關閉思考時，對於 Claude Code 已知[不接受該組合](/docs/zh-TW/errors#effort-isnt-available-with-thinking-turned-off)的模型（例如 Opus 5），Claude Code 會傳送 effort `high` 而不是更高的等級。

874 874

875* **範圍**: [`任何檔案`](#scopes)875* **範圍**: [`任何檔案`](#scopes)

876* **類型**: 布林值876* **類型**: 布林值

setup.md +5 −3

Details

49 curl -fsSL https://claude.ai/install.sh | bash49 curl -fsSL https://claude.ai/install.sh | bash

50 ```50 ```

51 51

52 在 Windows 上，當您在 PowerShell 中時，提示字元會顯示 `PS C:\`，而在 CMD 中時會顯示 `C:\`（不含 `PS`）。

52 **Windows PowerShell：**54 **Windows PowerShell：**

53 55

54 ```powershell theme={null}56 ```powershell theme={null}

63 65

64 當安裝程式完成時，請開啟新的終端機視窗並執行 `claude --version`。正常的安裝會列印版本號碼。如果您的殼層說找不到 `claude` 或無法識別，安裝目錄還未在您的 PATH 上：請參閱[修正您的 PATH](/docs/zh-TW/troubleshoot-install#command-not-found-claude-after-installation)。66 當安裝程式完成時，請開啟新的終端機視窗並執行 `claude --version`。正常的安裝會列印版本號碼。如果您的殼層說找不到 `claude` 或無法識別，安裝目錄還未在您的 PATH 上：請參閱[修正您的 PATH](/docs/zh-TW/troubleshoot-install#command-not-found-claude-after-installation)。

65 67

66 如果您看到 `The token '&&' is not a valid statement separator`，表示您在 PowerShell 中，而非 CMD。如果您看到 `'irm' is not recognized as an internal or external command`，表示您在 CMD 中，而非 PowerShell。當您在 PowerShell 中時，提示符會顯示 `PS C:\`，而在 CMD 中時會顯示 `C:\`（不含 `PS`）。68 如果您看到 `The token '&&' is not a valid statement separator`，表示您在 PowerShell 中，而非 CMD。如果您看到 `'irm' is not recognized as an internal or external command`，表示您在 CMD 中，而非 PowerShell。

67 69

68 如果安裝命令失敗並出現 `syntax error near unexpected token '<'`、`403` 或其他 curl 錯誤，請參閱[疑難排解安裝](/docs/zh-TW/troubleshoot-install#find-your-error)以將錯誤與修正相對應，並查看替代安裝方法。70 如果安裝命令失敗並出現 `syntax error near unexpected token '<'`、`403` 或其他任何錯誤，請參閱[疑難排解安裝](/docs/zh-TW/troubleshoot-install#find-your-error)以將錯誤與修正相對應，並查看替代安裝方法。

69 71

70 建議在原生 Windows 上安裝 [Git for Windows](https://git-scm.com/downloads/win)，以便 Claude Code 可以使用 Bash 工具。如果未安裝 Git for Windows，Claude Code 會改用 PowerShell 作為殼層工具。WSL 設定不需要 Git for Windows。72 建議在原生 Windows 上安裝 [Git for Windows](https://git-scm.com/downloads/win)，以便 Claude Code 可以使用 Bash 工具。如果未安裝 Git for Windows，Claude Code 會改用 PowerShell 作為殼層工具。WSL 設定不需要 Git for Windows。

71 73

204 206

205Claude Code 需要 Pro、Max、Team、Enterprise 或 Console 帳戶。免費的 claude.ai 方案不包括 Claude Code 存取權。您也可以透過第三方 API 提供者（如 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai) 或 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)）使用 Claude Code。207Claude Code 需要 Pro、Max、Team、Enterprise 或 Console 帳戶。免費的 claude.ai 方案不包括 Claude Code 存取權。您也可以透過第三方 API 提供者（如 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock)、[Google Cloud's Agent Platform](/docs/zh-TW/google-vertex-ai) 或 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)）使用 Claude Code。

206 208

207安裝後，執行 `claude` 並按照瀏覽器提示登入。如果設定了 `ANTHROPIC_API_KEY` 環境變數，Claude Code 會提示您一次以核准該金鑰，而不是開啟瀏覽器。請參閱[驗證](/docs/zh-TW/authentication)以了解所有帳戶類型和團隊設定選項。209安裝後，執行 `claude` 並按照瀏覽器提示登入。如果您已設定 `ANTHROPIC_API_KEY` 環境變數，並在 Claude Code 詢問是否使用該金鑰時予以核准，Claude Code 便會略過登入提示。請參閱[身分驗證](/docs/zh-TW/authentication)以了解所有帳戶類型和團隊設定選項。

208 210

209<h2 id="update-claude-code">211<h2 id="update-claude-code">

210 更新 Claude Code212 更新 Claude Code

skills.md +7 −2

Details

237 237

238在 Cowork 或雲端工作階段中，Claude Code 會載入為您的 claude.ai 帳戶啟用的技能，[Cowork 和雲端工作階段中的技能](#skills-in-cowork-and-cloud-sessions)說明了如何選擇這些工作階段獲得的技能。238在 Cowork 或雲端工作階段中，Claude Code 會載入為您的 claude.ai 帳戶啟用的技能，[Cowork 和雲端工作階段中的技能](#skills-in-cowork-and-cloud-sessions)說明了如何選擇這些工作階段獲得的技能。

239 239

240在您的終端中，Claude Code 在您使用 claude.ai 帳戶登入的工作階段中同步這些技能。當工作階段啟動時，Claude Code 在背景中將您帳戶的技能下載到 `~/.claude/skills/synced/` 中，然後在工作階段執行時大約每 10 分鐘檢查一次 claude.ai 是否有變更。當檢查發現技能在 claude.ai 上被新增、編輯或關閉時，Claude Code 在執行中的工作階段中新增、更新或移除它，無需重新啟動。終端工作階段中的同步需要 Claude Code v2.1.273 或更新版本。240在您的終端機中，Claude Code 會在您使用 claude.ai 帳戶登入的工作階段中同步這些 skill。工作階段啟動時，Claude Code 會在背景將您帳戶的 skill 下載到 `~/.claude/skills/synced/`，然後在工作階段執行期間檢查 claude.ai 是否有變更。當檢查發現某個 skill 在 claude.ai 上被新增、編輯或關閉時，Claude Code 會在執行中的工作階段中新增、更新或移除它，無需重新啟動。在終端機工作階段中同步需要 Claude Code v2.1.273 或更新版本。

241 241

242同步永遠不會延遲啟動，因為 Claude 只在叫用技能時等待技能的下載。因此，短[非互動式](/docs/zh-TW/headless)執行可能在新增的技能下載之前完成，在這種情況下，稍後的工作階段會下載它。若要使非互動式執行下載您的技能並在回答提示之前等待清單，請將 [`CLAUDE_CODE_SYNC_SKILLS`](/docs/zh-TW/env-vars#variables) 設定為 `1`。242工作階段閒置時，檢查的頻率會降低：

243

244* **當您或 Claude 在工作階段中工作時**：大約每 10 分鐘檢查一次。

245* **當工作階段閒置時**：大約每 40 分鐘檢查一次。當您再次在工作階段中輸入時，如果上次檢查已超過 10 分鐘，Claude Code 會在幾分鐘內進行檢查。

246

247同步永遠不會延遲啟動，因為 Claude 只有在叫用某個 skill 時才會等待該 skill 下載。因此，簡短的[非互動式](/docs/zh-TW/headless)執行可能會在新增的 skill 下載完成前結束，這種情況下會由之後的工作階段下載它。若要讓非互動式執行下載您的 skill 並在回答提示詞之前等待清單，請將 [`CLAUDE_CODE_SYNC_SKILLS`](/docs/zh-TW/env-vars#variables) 設定為 `1`。在 v2.1.273 之前，終端機工作階段只有在設定了此變數的 `-p` 執行中才會下載它們。

243 248

244Claude Code 僅在使用您的 claude.ai 帳戶登入的工作階段中同步，並[從 Anthropic 擷取功能旗標](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)。它不在這些工作階段中同步：249Claude Code 僅在使用您的 claude.ai 帳戶登入的工作階段中同步，並[從 Anthropic 擷取功能旗標](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)。它不在這些工作階段中同步：

245 250

sub-agents.md +4 −4

Details

310 310

311| 欄位 | 必需 | 描述 |311| 欄位 | 必需 | 描述 |

312| :- | :- | :- |312| :- | :- | :- |

313| `name` | 是 | 唯一識別碼，例如 `code-reviewer` 或 `reviewer-v2`。[Hooks](/docs/zh-TW/hooks#subagentstart) 將此值作為 `agent_type` 接收。檔案名稱不必匹配。名稱不能包含 `:`，它保留用於[plugin 範圍識別碼](/docs/zh-TW/plugins/overview)，例如 `my-plugin:reviewer`。Claude Code 不載入名稱包含一個的檔案，並將錯誤記錄到偵錯日誌。在 v2.1.218 之前，此類名稱被接受 |313| `name` | 是 | 最多 256 個字元的唯一識別碼，例如 `code-reviewer` 或 `reviewer-v2`。[Hook](/docs/zh-TW/hooks#subagentstart) 會以 `agent_type` 接收此值。檔案名稱不必相符。名稱不能包含 `:`，它保留給[外掛範圍識別碼](/docs/zh-TW/plugins/overview)使用，例如 `my-plugin:reviewer` |

314| `description` | 是 | Claude 應何時委派給此子代理 |314| `description` | 是 | Claude 應何時委派給此子代理 |

315| `tools` | 否 | 子代理可以使用的[工具](#available-tools)，作為逗號分隔的字串，例如 `Read, Grep, Bash` 或 YAML 列表。如果省略，繼承子代理可用的每個工具。如果列表中沒有條目解析為工具，子代理通常[無法啟動](/docs/zh-TW/errors#agent-would-be-spawned-with-zero-tools)並出現錯誤，命名未解析的條目。若要將 Skills 預載入上下文，請使用 `skills` 欄位而不是在此列出 `Skill` |315| `tools` | 否 | 子代理可以使用的[工具](#available-tools)，作為逗號分隔的字串，例如 `Read, Grep, Bash` 或 YAML 列表。如果省略，繼承子代理可用的每個工具。如果列表中沒有條目解析為工具，子代理通常[無法啟動](/docs/zh-TW/errors#agent-would-be-spawned-with-zero-tools)並出現錯誤，命名未解析的條目。若要將 Skills 預載入上下文，請使用 `skills` 欄位而不是在此列出 `Skill` |

316| `disallowedTools` | 否 | 要拒絕的工具，從繼承或指定的列表中移除。與 `tools` 相同的格式。具有指定符的條目（例如 `Bash(git push *)`）仍然[移除整個工具](#available-tools) |316| `disallowedTools` | 否 | 要拒絕的工具，從繼承或指定的列表中移除。與 `tools` 相同的格式。具有指定符的條目（例如 `Bash(git push *)`）仍然[移除整個工具](#available-tools) |

348 348

349* **沒有 `name`**：Claude Code 將檔案視為保存在代理旁邊的文件。349* **沒有 `name`**：Claude Code 將檔案視為保存在代理旁邊的文件。

350* **不是檔案第一行的開啟 `---`**：Claude Code 讀取檔案為沒有 frontmatter，並將其視為文件。350* **不是檔案第一行的開啟 `---`**：Claude Code 讀取檔案為沒有 frontmatter，並將其視為文件。

351* **以 `-` 開頭或包含 `:` 的 `name`**：Claude Code 跳過檔案並將錯誤寫入偵錯日誌。請參閱上表中的 `name` 列。351* **`name` 以 `-` 開頭、包含 `:`，或超過 256 個字元**：Claude Code 會略過該檔案，並將錯誤寫入除錯日誌。

352* **有 `name` 但沒有 `description`**：Claude Code 跳過檔案並將原因寫入偵錯日誌。352* **有 `name` 但沒有 `description`**：Claude Code 跳過檔案並將原因寫入偵錯日誌。

353* **不解析的 YAML**：Claude Code 不從檔案讀取任何欄位，跳過它，並將解析錯誤寫入偵錯日誌。353* **不解析的 YAML**：Claude Code 不從檔案讀取任何欄位，跳過它，並將解析錯誤寫入偵錯日誌。

354 354

1164 1164

1165* 當 subagent 完成時，Claude 接收其 agent ID。1165* 當 subagent 完成時，Claude 接收其 agent ID。

1166* 內建的 Explore 和 Plan agents 是一次性的，不返回 agent ID，所以 Claude 無法恢復它們。當您需要繼續工作時，請使用 `general-purpose` 或自訂 subagent。1166* 內建的 Explore 和 Plan agents 是一次性的，不返回 agent ID，所以 Claude 無法恢復它們。當您需要繼續工作時，請使用 `general-purpose` 或自訂 subagent。

1167* 當 subagent 在其 [`maxTurns`](#supported-frontmatter-fields) 限制處停止時，Claude Code 會將返回的輸出標記為部分。對於返回 agent ID 的 subagents，Claude Code 也會在結果中註明 Claude 可以傳送訊息給 subagent 以從停止的地方繼續。1167* 當 subagent 在其 [`maxTurns`](#supported-frontmatter-fields) 限制處停止時，Claude Code 會將返回的輸出標記為部分，Claude 可以恢復該 subagent 以繼續其工作。

1168 1168

1169Claude 使用 `SendMessage` 工具，將 agent 的 ID 或名稱作為 `to` 欄位來恢復它。`SendMessage` 不需要啟用 [agent teams](/docs/zh-TW/agent-teams)；只有結構化的團隊協定訊息，例如 `shutdown_request` 和 `plan_approval_response`，才需要啟用。除了 subagents 和隊員，在啟用跨工作階段訊息的工作階段中，Claude 可以使用相同的工具傳送訊息給 [您的其他 Claude Code 工作階段](/docs/zh-TW/cross-session-messaging)，無論是在此機器上或 [其他機器上](/docs/zh-TW/cross-session-messaging#message-sessions-on-other-machines)。1169Claude 使用 `SendMessage` 工具，將 agent 的 ID 或名稱作為 `to` 欄位來恢復它。`SendMessage` 不需要啟用 [agent teams](/docs/zh-TW/agent-teams)；只有結構化的團隊協定訊息，例如 `shutdown_request` 和 `plan_approval_response`，才需要啟用。除了 subagents 和隊員，在啟用跨工作階段訊息的工作階段中，Claude 可以使用相同的工具傳送訊息給 [您的其他 Claude Code 工作階段](/docs/zh-TW/cross-session-messaging)，無論是在此機器上或 [其他機器上](/docs/zh-TW/cross-session-messaging#message-sessions-on-other-machines)。

1170 1170

1281 1281

1282因為 fork 的系統提示和工具定義與父級相同，其第一個請求重複使用父級的 [prompt cache](/docs/zh-TW/prompt-caching#subagents-and-the-cache)。這使得 forking 比為需要相同上下文的任務產生新 subagent 更便宜。1282因為 fork 的系統提示詞和工具定義與父級相同，其第一個請求重複使用父級的[提示快取](/docs/zh-TW/prompt-caching#subagents-and-the-cache)。由於這種重複使用，對於需要相同上下文的任務，fork 的成本比新的 subagent 更低。

1283 1283

1284當 Claude 透過 Agent 工具產生 fork 時，它可以傳遞 `isolation: "worktree"`，以便 fork 的檔案編輯被寫入單獨的 git worktree 而不是您的簽出。Fork 無法產生進一步的 forks。1284當 Claude 透過 Agent 工具產生 fork 時，它可以傳遞 `isolation: "worktree"`，以便 fork 的檔案編輯被寫入單獨的 git worktree 而不是您的簽出。Fork 無法產生進一步的 forks。

1285 1285

vs-code.md +22 −7

Details

40 40

41擴充功能也會安裝在其他 VS Code 分支中，例如 Devin Desktop 或 Kiro。在編輯器的擴充功能檢視中搜尋「Claude Code」，或從 [Open VSX registry](https://open-vsx.org/extension/Anthropic/claude-code) 安裝。如果您的編輯器無法安裝擴充功能，請[安裝 CLI](/docs/zh-TW/quickstart) 並在其整合終端中執行 `claude`。CLI 可在任何終端中運作。41擴充功能也會安裝在其他 VS Code 分支中，例如 Devin Desktop 或 Kiro。在編輯器的擴充功能檢視中搜尋「Claude Code」，或從 [Open VSX registry](https://open-vsx.org/extension/Anthropic/claude-code) 安裝。如果您的編輯器無法安裝擴充功能，請[安裝 CLI](/docs/zh-TW/quickstart) 並在其整合終端中執行 `claude`。CLI 可在任何終端中運作。

42 42

43若要在開發容器中執行 Claude Code，請參閱[開發容器](/docs/zh-TW/devcontainer)。

43<Note>如果安裝後擴充功能未出現，請重新啟動 VS Code 或從命令面板執行「Developer: Reload Window」。</Note>45<Note>如果安裝後擴充功能未出現，請重新啟動 VS Code 或從命令面板執行「Developer: Reload Window」。</Note>

44 46

45<h2 id="get-started">47<h2 id="get-started">

606| `environmentVariables` | `[]` | 為 Claude 程序設定環境變數。使用 Claude Code 設定以改為共享設定。[`CLAUDE_CONFIG_DIR`](/docs/zh-TW/env-vars) 項目僅在其值為絕對路徑時才會套用；擴充功能不會展開 `~`，並會忽略相對路徑值。 |608| `environmentVariables` | `[]` | 為 Claude 程序設定環境變數。使用 Claude Code 設定以改為共享設定。[`CLAUDE_CONFIG_DIR`](/docs/zh-TW/env-vars) 項目僅在其值為絕對路徑時才會套用；擴充功能不會展開 `~`，並會忽略相對路徑值。 |

609| `claudeProcessWrapper` | - | 用於啟動 Claude 程序的可執行檔。當存在時，組合的二進位路徑會作為引數傳遞。如果擴充功能組建不包含您平台的二進位檔，請將其設定為單獨安裝的 `claude` 二進位檔。在包裝的設定中，對話以 Manual 模式開始，除非您設定 `initialPermissionMode` 或在較早的對話中選擇了 Manual、Edit automatically 或 Auto，因為擴充功能會在那裡略過設定和內建預設步驟；請參閱[切換權限模式](/docs/zh-TW/permission-modes#switch-permission-modes)。啟動時出現「不支援的平台」錯誤表示您的平台沒有組合的二進位檔；請參閱[哪些平台有預先建置的二進位檔](/docs/zh-TW/troubleshoot-install#native-binary-not-found-after-npm-install)。 |611| `claudeProcessWrapper` | - | 用於啟動 Claude 程序的可執行檔。當存在時，組合的二進位路徑會作為引數傳遞。如果擴充功能建置不包含您平台的二進位檔，請將其設定為單獨安裝的 `claude` 二進位檔。 |

610 612

611<h2 id="use-a-screen-reader">613<h2 id="use-a-screen-reader">

612 使用螢幕閱讀器614 使用螢幕閱讀器

793 795

794當擴充功能處於活動狀態時，它會執行一個本機 MCP 伺服器，CLI 會自動連接到該伺服器。這就是 CLI 如何在 VS Code 的原生差異檢視器中開啟差異、讀取您目前的選擇以進行 `@` 提及，以及在您在 Jupyter 筆記本中工作時要求 VS Code 執行儲存格的方式。796當擴充功能處於活動狀態時，它會執行一個本機 MCP 伺服器，CLI 會自動連接到該伺服器。這就是 CLI 如何在 VS Code 的原生差異檢視器中開啟差異、讀取您目前的選擇以進行 `@` 提及，以及在您在 Jupyter 筆記本中工作時要求 VS Code 執行儲存格的方式。

795 797

796伺服器名稱為 `ide`，並且從 `/mcp` 隱藏，因為沒有任何要設定的內容。不過，如果您的組織使用 `PreToolUse` hook 來允許列表 MCP 工具，您需要知道它的存在。798伺服器名稱為 `ide`，並且從 `/mcp` 隱藏，因為沒有任何要設定的內容。不過，如果您的組織使用 `PreToolUse` hook 將 MCP 工具加入允許清單，您需要知道它的存在。

797 799

798**選擇和開啟檔案內容。** 連接時，CLI 會在您傳送的每個提示上包含您目前的編輯器選擇和活動檔案的路徑作為內容。當發生這種情況時，文字記錄會顯示 `⧉ Selected N lines from <file>` 行。800**選擇和開啟檔案內容。** 連接時，CLI 會在您傳送的每個提示詞中包含您目前的編輯器選擇和活動檔案的路徑作為內容。當發生這種情況時，逐字稿會顯示 `⧉ Selected N lines from <file>` 行。

799 801

800如果您[在 Claude 工作時將訊息加入佇列](/docs/zh-TW/interactive-mode#queue-messages-while-claude-works)，它會保留您按下 `Enter` 時的選擇，無論您之後選擇什麼。802如果您[在 Claude 工作時將訊息加入佇列](/docs/zh-TW/interactive-mode#queue-messages-while-claude-works)，它會保留您按下 `Enter` 時的選擇，無論您之後選擇什麼。

801 803

803 805

804如果您關閉[附加開啟檔案設定](#extension-settings)，CLI 只有在您在該檔案中選取文字時才會接收活動檔案的路徑。806如果您關閉[附加開啟檔案設定](#extension-settings)，CLI 只有在您在該檔案中選取文字時才會接收活動檔案的路徑。

805 807

806**傳輸和驗證。** 伺服器繫結到 `127.0.0.1` 上的隨機連接埠，範圍在 10000–65535，連接埠不可設定。傳輸是未加密的 `ws://`；因為通訊端是僅限迴圈的，任何可以擷取流量的程序也可以從鎖定檔案讀取權杖，所以 TLS 不會增加保護。每次擴充功能啟動都會產生一個新的隨機驗證權杖，將其寫入位於 `~/.claude/ide/<port>.lock` 的鎖定檔案，CLI 必須將其作為 `X-Claude-Code-Ide-Authorization` 標頭呈現以進行連接。鎖定檔案在 `0700` 目錄中具有 `0600` 權限，因此只有執行 VS Code 的使用者可以讀取它。如果設定了 `CLAUDE_CONFIG_DIR`，鎖定檔案會改為寫入 `$CLAUDE_CONFIG_DIR/ide/`。808**傳輸和身分驗證。** 伺服器繫結到 `127.0.0.1` 上的隨機連接埠，範圍在 10000–65535，連接埠不可設定。傳輸是未加密的 `ws://`；因為通訊端是僅限迴圈的，任何可以擷取流量的程序也可以從鎖定檔案讀取權杖，所以 TLS 不會增加保護。每次擴充功能啟動都會產生一個新的隨機驗證權杖，將其寫入位於 `~/.claude/ide/<port>.lock` 的鎖定檔案，CLI 必須將其作為 `X-Claude-Code-Ide-Authorization` 標頭呈現以進行連接。鎖定檔案在 `0700` 目錄中具有 `0600` 權限，因此只有執行 VS Code 的使用者可以讀取它。如果設定了 `CLAUDE_CONFIG_DIR`，鎖定檔案會改為寫入 `$CLAUDE_CONFIG_DIR/ide/`。

807 809

808**公開給模型的工具。** 伺服器裝載十幾個工具，但只有兩個對模型可見。其餘的是 CLI 用於自己的 UI 的內部 RPC（開啟差異、讀取選擇、儲存檔案），在工具清單到達 Claude 之前會被篩選掉。810**公開給模型的工具。** 伺服器裝載十幾個工具，但只有兩個對模型可見。其餘的是 CLI 用於自己的 UI 的內部 RPC，例如開啟差異、讀取選擇和儲存檔案。它們在工具清單到達 Claude 之前會被篩選掉。

809 811

810| 工具名稱（如 hooks 所見） | 它的作用 | 唯讀 |812| 工具名稱（如 hook 所見） | 它的作用 | 唯讀 |

811| - | - | - |813| - | - | - |

812| `mcp__ide__getDiagnostics` | 傳回語言伺服器診斷：VS Code 的問題面板中的錯誤和警告。可選擇限定於一個檔案。 | 是 |814| `mcp__ide__getDiagnostics` | 傳回語言伺服器診斷：VS Code 的問題面板中的錯誤和警告。可選擇限定於一個檔案。 | 是 |

813| `mcp__ide__executeCode` | 在活動 Jupyter 筆記本的核心中執行 Python 程式碼。請參閱下面的確認流程。 | 否 |815| `mcp__ide__executeCode` | 在活動 Jupyter 筆記本的核心中執行 Python 程式碼。請參閱下面的確認流程。 | 否 |

834**Jupyter 執行始終先詢問。** `mcp__ide__executeCode` 無法以無聲方式執行任何操作。在每次呼叫時，程式碼會作為新儲存格插入到活動筆記本的末尾，VS Code 會將其捲動到檢視中，原生快速選擇會要求您**執行**或**取消**。取消，或使用 `Esc` 關閉選擇器，會向 Claude 傳回錯誤，不會執行任何操作。當沒有活動筆記本、未安裝 Jupyter 擴充功能 (`ms-toolsai.jupyter`) 或核心不是 Python 時，該工具也會直接拒絕。836**Jupyter 執行始終先詢問。** `mcp__ide__executeCode` 無法以無聲方式執行任何操作。在每次呼叫時，程式碼會作為新儲存格插入到活動筆記本的末尾，VS Code 會將其捲動到檢視中，原生快速選擇會要求您**執行**或**取消**。取消，或使用 `Esc` 關閉選擇器，會向 Claude 傳回錯誤，不會執行任何操作。當沒有活動筆記本、未安裝 Jupyter 擴充功能 (`ms-toolsai.jupyter`) 或核心不是 Python 時，該工具也會直接拒絕。

835 837

836<Note>838<Note>

837 快速選擇確認與 `PreToolUse` hooks 分開。`mcp__ide__executeCode` 的允許列表項目讓 Claude *提議*執行儲存格；VS Code 內的快速選擇是讓它*實際*執行的原因。839 快速選擇確認與 `PreToolUse` hook 分開。`mcp__ide__executeCode` 的允許清單項目讓 Claude *提議*執行儲存格；VS Code 內的快速選擇是讓它*實際*執行的原因。

838</Note>840</Note>

839 841

840<a id="troubleshooting" />842<a id="troubleshooting" />

843 修復常見問題845 修復常見問題

844</h2>846</h2>

845 847

848登入、網路和啟動錯誤在安裝疑難排解和錯誤參考頁面上各有專門的條目。請在表格中找到您看到的情況，然後點擊對應的連結。

849

850| 您看到的情況 | 前往位置 |

851| - | - |

852| 登入後出現 `API Error: 403 Request not allowed` | [登入後出現 403 Forbidden](/docs/zh-TW/troubleshoot-install#403-forbidden-after-login) |

853| 您已經登入後仍被要求再次登入 | [未登入或 token 已過期](/docs/zh-TW/troubleshoot-install#not-logged-in-or-token-expired) |

854| 雲端供應商憑證在您的終端機中可用，但在擴充功能中無法使用 | [Bedrock、Agent Platform 或 Foundry 憑證未載入](/docs/zh-TW/troubleshoot-install#bedrock-agent-platform-or-foundry-credentials-not-loading) |

855| `SSL certificate verification failed` 或 `Self-signed certificate detected` | [SSL 憑證錯誤](/docs/zh-TW/errors#ssl-certificate-errors) |

856| `Claude Code process exited with code 1` 或其他代碼 | [Claude Code process exited with code N](/docs/zh-TW/errors#claude-code-process-exited-with-code-n) |

857| `Could not locate the Claude CLI on PATH` | [Could not locate the Claude CLI on PATH](/docs/zh-TW/errors#could-not-locate-the-claude-cli-on-path) |

858| `The connection to Claude Code ended before this message completed` | [The connection to Claude Code ended before this message completed](/docs/zh-TW/errors#the-connection-to-claude-code-ended-before-this-message-completed) |

859| 在 VS Code 的整合式終端機中找不到 `claude` | [在 VS Code 中執行 CLI](#run-cli-in-vs-code) |

860

846<h3 id="extension-won’t-install">861<h3 id="extension-won’t-install">

847 擴充功能無法安裝862 擴充功能無法安裝

848</h3>863</h3>

workflows.md +6 −1

Details

522 522

523要為整個組織關閉工作流程，在[受管設定](/docs/zh-TW/server-managed-settings)中設定 `"disableWorkflows": true`，或使用 [Claude Code 管理員設定](https://claude.ai/admin-settings/claude-code)頁面上的切換。523要為整個組織關閉工作流程，在[受管設定](/docs/zh-TW/server-managed-settings)中設定 `"disableWorkflows": true`，或使用 [Claude Code 管理員設定](https://claude.ai/admin-settings/claude-code)頁面上的切換。

524 524

525禁用工作流程時，捆綁的工作流程命令和 `/workflow-authoring` 技能不可用，`ultracode` 關鍵字不再觸發執行，**Ultracode** 切換從 `/effort` 中移除。已在進行中的執行會繼續進行。525停用工作流程時：

526

527* `/workflows`、工作流程命令和 `/workflow-authoring` skill 不可用

528* `ultracode` 關鍵字不再觸發執行，**Ultracode** 切換從 `/effort` 中移除

529

530已在進行中的執行會繼續進行。

526 531

527關閉工作流程也會使 [ultracode](#let-claude-decide-with-ultracode) 不可用。沒有受管設定單獨排除 ultracode：無論它在何處[可用](/docs/zh-TW/model-config#when-ultracode-is-available)，使用者都可以使用 `/effort ultracode` 將其開啟。[努力上限](/docs/zh-TW/model-config#organization-effort-limits)會降低啟用 ultracode 的工作階段執行的努力等級，但不會關閉 ultracode。532關閉工作流程也會使 [ultracode](#let-claude-decide-with-ultracode) 不可用。沒有受管設定單獨排除 ultracode：無論它在何處[可用](/docs/zh-TW/model-config#when-ultracode-is-available)，使用者都可以使用 `/effort ultracode` 將其開啟。[努力上限](/docs/zh-TW/model-config#organization-effort-limits)會降低啟用 ultracode 的工作階段執行的努力等級，但不會關閉 ultracode。

528 533

worktrees.md +3 −1

Details

6 6

7> 在獨立的 git worktrees 中隔離平行的 Claude Code 會話，使變更不會相互衝突。涵蓋 `--worktree` 旗標、子代理隔離、`.worktreeinclude`、清理和非 git VCS hooks。7> 在獨立的 git worktrees 中隔離平行的 Claude Code 會話，使變更不會相互衝突。涵蓋 `--worktree` 旗標、子代理隔離、`.worktreeinclude`、清理和非 git VCS hooks。

8 8

9[git worktree](https://git-scm.com/docs/git-worktree) 是一個獨立的工作目錄，具有自己的檔案和分支，但與主要檢出共享相同的儲存庫歷史記錄和遠端。在自己的 worktree 中執行每個 Claude Code 會話意味著一個會話中的編輯永遠不會觸及另一個會話中的檔案，因此一個會話可以建置功能，而第二個會話可以修復錯誤。9[git worktree](https://git-scm.com/docs/git-worktree) 是一個獨立的工作目錄，具有自己的檔案和分支，但與主要檢出共享相同的儲存庫歷史記錄和遠端。在各自的 worktree 中執行每個 Claude Code 工作階段，可為其提供一份獨立的檔案副本進行編輯，因此一個工作階段可以建置功能，而第二個工作階段可以修復錯誤。

10 10

11<Note>11<Note>

12 Worktrees 需要 git 儲存庫；對於其他版本控制系統，請[配置 hooks 以取代 git 邏輯](#non-git-version-control)。在[桌面應用程式](/docs/zh-TW/desktop#work-in-parallel-with-sessions)中，當您啟動會話時選擇 **worktree** 選項，為其提供自己的 worktree。12 Worktrees 需要 git 儲存庫；對於其他版本控制系統，請[配置 hooks 以取代 git 邏輯](#non-git-version-control)。在[桌面應用程式](/docs/zh-TW/desktop#work-in-parallel-with-sessions)中，當您啟動會話時選擇 **worktree** 選項，為其提供自己的 worktree。

104* **Git 重定向**：Claude Code 會阻止將 git 重定向到主要檢出的 Bash 或 Monitor 命令。重定向可以透過 `git -C`、`--git-dir`、`GIT_DIR` 或 `GIT_WORK_TREE` 變數，或在執行 git 之前 `cd` 到主要檢出。104* **Git 重定向**：Claude Code 會阻止將 git 重定向到主要檢出的 Bash 或 Monitor 命令。重定向可以透過 `git -C`、`--git-dir`、`GIT_DIR` 或 `GIT_WORK_TREE` 變數，或在執行 git 之前 `cd` 到主要檢出。

105* **命令形狀**：當 Claude Code 無法從命令文字驗證命令執行的任何 git 保持在 worktree 內時，Claude Code 會阻止 Bash 或 Monitor 命令。例如，當命令名稱在執行時計算、語法無法解析，或像 `${!name}` 或 `${ command; }` 這樣的展開可能執行文字中未明確說明的命令時，就會發生這種情況。Claude Code 會告訴 Claude 如何重寫被拒絕的命令，例如將其分割成純粹的、獨立的命令。您無法關閉此檢查。105* **命令形狀**：當 Claude Code 無法從命令文字驗證命令執行的任何 git 保持在 worktree 內時，Claude Code 會阻止 Bash 或 Monitor 命令。例如，當命令名稱在執行時計算、語法無法解析，或像 `${!name}` 或 `${ command; }` 這樣的展開可能執行文字中未明確說明的命令時，就會發生這種情況。Claude Code 會告訴 Claude 如何重寫被拒絕的命令，例如將其分割成純粹的、獨立的命令。您無法關閉此檢查。

106 106

107這些檢查會讀取編輯所針對的路徑、命令執行所在的目錄，以及命令的文字。它們都不會追蹤 shell 命令寫入了哪些檔案，因此未在主要檢出中執行 git 卻寫入主要檢出的命令（例如 `cp` 或 shell 重定向）不會被這些檢查拒絕。Claude Code 會將該命令視為任何其他 shell 命令處理，因此它是直接執行還是向您顯示權限提示，取決於您的[權限模式](/docs/zh-TW/permission-modes)和規則。

108

107檢查適用於您啟動 Claude Code 的儲存庫。它們也涵蓋連結 worktree 連結自的主要檢出。對於 PowerShell 命令，Claude Code 只應用工作目錄檢查。109檢查適用於您啟動 Claude Code 的儲存庫。它們也涵蓋連結 worktree 連結自的主要檢出。對於 PowerShell 命令，Claude Code 只應用工作目錄檢查。

108 110

109Claude 將每次拒絕視為命名 worktree 並說明如何進行的工具錯誤。如需被拒絕的命令，請參閱[拒絕訊息的含義以及如何清除它](/docs/zh-TW/errors#command-blocked-by-the-worktree-isolation-checks)。111Claude 將每次拒絕視為命名 worktree 並說明如何進行的工具錯誤。如需被拒絕的命令，請參閱[拒絕訊息的含義以及如何清除它](/docs/zh-TW/errors#command-blocked-by-the-worktree-isolation-checks)。

Documentation 2026-10-06 23:59 UTC to 2026-10-07 20:57 UTC