Documentation — Spybara

admin-setup.md +2 −2

Details

137 已連結的 GitHub 帳戶137 已連結的 GitHub 帳戶

138</h3>138</h3>

139 139

140在 Team 和 Enterprise 方案中，[**Admin settings > GitHub**](https://claude.ai/admin-settings/github) 會列出透過 [Claude GitHub App](https://github.com/apps/claude) 連結至您 Claude 組織的 GitHub 組織和個人帳戶。Claude Code、[Claude Tag](https://claude.com/docs/claude-tag/admins/configure-github) 和 Claude Security 共用此清單。開啟此頁面需要您在 Claude 組織中具備管理員角色。140在 Team 和 Enterprise 方案中，[**Organization settings > GitHub**](https://claude.ai/admin-settings/github) 會列出透過 [Claude GitHub App](https://github.com/apps/claude) 連結至您 Claude 組織的 GitHub 組織和個人帳戶。Claude Code、[Claude Tag](https://claude.com/docs/claude-tag/admins/configure-github) 和 Claude Security 共用此清單。開啟此頁面需要您在 Claude 組織中具備管理員角色。

141 141

142管理員或成員都可以連結帳戶：142管理員或成員都可以連結帳戶：

143 143

162| Analytics dashboard | Teams / Enterprise 上具有排行榜的採用和貢獻指標；Console 上的每個使用者使用情況和支出指標 | Teams / Enterprise 在 [claude.ai/analytics](https://claude.ai/analytics/claude-code)，Console 在 [platform.claude.com/claude-code](https://platform.claude.com/claude-code) | [Analytics](/docs/zh-TW/analytics) |162| Analytics dashboard | Teams / Enterprise 上具有排行榜的採用和貢獻指標；Console 上的每個使用者使用情況和支出指標 | Teams / Enterprise 在 [claude.ai/analytics](https://claude.ai/analytics/claude-code)，Console 在 [platform.claude.com/claude-code](https://platform.claude.com/claude-code) | [Analytics](/docs/zh-TW/analytics) |

163| Programmatic reporting | 透過 API 的每個使用者使用情況和成本資料 | Enterprise 的 [Enterprise Analytics API](https://platform.claude.com/docs/en/api/admin/analytics)，Console 的 [Claude Code Analytics API](https://platform.claude.com/docs/en/build-with-claude/claude-code-analytics-api) | [Costs](/docs/zh-TW/costs#manage-costs-for-your-organization) |163| Programmatic reporting | 透過 API 的每個使用者使用情況和成本資料 | Enterprise 的 [Enterprise Analytics API](https://platform.claude.com/docs/en/api/admin/analytics)，Console 的 [Claude Code Analytics API](https://platform.claude.com/docs/en/build-with-claude/claude-code-analytics-api) | [Costs](/docs/zh-TW/costs#manage-costs-for-your-organization) |

164| Spend controls | 支出限制和速率限制 | Teams / Enterprise 的管理員設定、Console 的工作區限制；在第三方雲端上，雲端預算控制或具有每個使用者[支出限制](/docs/zh-TW/claude-apps-gateway-spend-limits)的 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway) | [Costs](/docs/zh-TW/costs#manage-costs-for-your-organization) |164| Spend controls | 支出限制和速率限制 | Teams / Enterprise 的組織設定、Console 的工作區限制；在第三方雲端上，雲端預算控制或具有每個使用者[支出限制](/docs/zh-TW/claude-apps-gateway-spend-limits)的 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway) | [Costs](/docs/zh-TW/costs#manage-costs-for-your-organization) |

165 165

166在 Teams 和 Enterprise 上，每個使用者的使用情況和支出數字來自您組織分析設定中的[支出報告](https://support.claude.com/en/articles/12883420-view-usage-analytics-for-team-and-enterprise-plans)，而不是分析儀表板。雲端提供者透過 AWS Cost Explorer、GCP Billing 或 Azure Cost Management 公開支出。如需規劃跨 Claude chat、Claude Code 和 Cowork 的企業預算，請參閱 [Claude Enterprise 消費指南](https://support.claude.com/en/articles/14782391-claude-enterprise-consumption-guide)。166在 Teams 和 Enterprise 上，每個使用者的使用情況和支出數字來自您組織分析設定中的[支出報告](https://support.claude.com/en/articles/12883420-view-usage-analytics-for-team-and-enterprise-plans)，而不是分析儀表板。雲端提供者透過 AWS Cost Explorer、GCP Billing 或 Azure Cost Management 公開支出。如需規劃跨 Claude chat、Claude Code 和 Cowork 的企業預算，請參閱 [Claude Enterprise 消費指南](https://support.claude.com/en/articles/14782391-claude-enterprise-consumption-guide)。

167 167

agent-sdk/mcp.md +14 −0

Details

919 ```919 ```

920</CodeGroup>920</CodeGroup>

921 921

922<h3 id="a-tool-is-missing-from-an-sdk-mcp-server">

923 SDK MCP 伺服器中缺少某個工具

924</h3>

925

926在 TypeScript SDK 中，當某個工具的輸入 schema 無法轉換為 JSON Schema 時，您使用 [`createSdkMcpServer()`](/docs/zh-TW/agent-sdk/typescript#createsdkmcpserver) 建立的伺服器在列出其工具時會略過該工具。SDK 會在此時發出警告。在 Node.js 下，該警告是代碼為 `CLAUDE_SDK_MCP_TOOL_SCHEMA_UNCONVERTIBLE` 的程序警告，並以下列文字開頭：

927

928```text theme={null}

929Tool "<name>" on SDK MCP server "<server>" was left out of the server's tool list, because its input schema cannot be converted to JSON Schema

930```

931

932警告的其餘部分會在轉換錯誤有訊息時提供該訊息，接著說明應檢查和變更的內容。

933

934在 TypeScript Agent SDK v0.3.286 之前，只要有一個無法轉換的 schema，就會導致伺服器的整個工具列表失敗且不會出現此警告，因此該伺服器的所有工具都無法傳達給 Claude。

935

922<h3 id="connection-timeouts">936<h3 id="connection-timeouts">

923 連線逾時937 連線逾時

924</h3>938</h3>

agent-sdk/troubleshooting.md +1 −1

Details

13| 症狀 | 前往 |13| 症狀 | 前往 |

14| :- | :- |14| :- | :- |

15| 找不到 Skills、skill 未被使用、`Invalid skill name` 錯誤 | [Skills 故障排除](/docs/zh-TW/agent-sdk/skills#troubleshooting) |15| 找不到 Skills、skill 未被使用、`Invalid skill name` 錯誤 | [Skills 故障排除](/docs/zh-TW/agent-sdk/skills#troubleshooting) |

17| Plugin 未載入、plugin skills 未出現 | [Plugins 故障排除](/docs/zh-TW/agent-sdk/plugins#troubleshooting) |17| Plugin 未載入、plugin skills 未出現 | [Plugins 故障排除](/docs/zh-TW/agent-sdk/plugins#troubleshooting) |

18| Claude 未委派給子代理、基於檔案系統的代理未載入 | [Subagents 故障排除](/docs/zh-TW/agent-sdk/subagents#troubleshooting) |18| Claude 未委派給子代理、基於檔案系統的代理未載入 | [Subagents 故障排除](/docs/zh-TW/agent-sdk/subagents#troubleshooting) |

19| Checkpointing 選項未被識別、使用者訊息沒有 UUID、`No file checkpoint found`、`File rewinding is not enabled`、`ProcessTransport is not ready for writing` | [檔案 checkpointing 故障排除](/docs/zh-TW/agent-sdk/file-checkpointing#troubleshooting) |19| Checkpointing 選項未被識別、使用者訊息沒有 UUID、`No file checkpoint found`、`File rewinding is not enabled`、`ProcessTransport is not ready for writing` | [檔案 checkpointing 故障排除](/docs/zh-TW/agent-sdk/file-checkpointing#troubleshooting) |

agent-sdk/typescript.md +12 −0

Details

863 fast_mode_state?: "off" | "cooldown" | "on";863 fast_mode_state?: "off" | "cooldown" | "on";

864 fast_mode_disabled_reason?: FastModeDisabledReason;864 fast_mode_disabled_reason?: FastModeDisabledReason;

865 hooks_applied?: boolean;865 hooks_applied?: boolean;

866 sdk_mcp_manifests_parked?: Record<

867 string,

868 | "parked"

869 | "already_connected"

870 | "protocol_version_mismatch"

871 | "malformed"

872 | "not_honoured"

873 >;

866};874};

867```875```

868 876

875 883

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

877 885

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

887

878回應一律會回報 `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)。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)。

879 889

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

1955| - | - |1965| - | - |

1956| `interrupt_receipt_v1` | [`interrupt()`](#query-object) 會以 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) 收據解析，其中列出中斷到達時仍待處理的訊息 |1966| `interrupt_receipt_v1` | [`interrupt()`](#query-object) 會以 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) 收據解析，其中列出中斷到達時仍待處理的訊息 |

1957| `interrupt_cancel_queued_v1` | `interrupt` 控制請求會遵循 `cancel_queued: true`，取消收據原本會列在 `still_queued` 下的訊息，並改為列在 `cancelled` 下。請參閱 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse)。需要 Claude Code v2.1.219 或更新版本 |1967| `interrupt_cancel_queued_v1` | `interrupt` 控制請求會遵循 `cancel_queued: true`，取消收據原本會列在 `still_queued` 下的訊息，並改為列在 `cancelled` 下。請參閱 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse)。需要 Claude Code v2.1.219 或更新版本 |

1968| `sdk_mcp_manifests` | `initialize` 控制請求接受 `sdkMcpServerManifests`，即從您程序內 [SDK MCP 伺服器](/docs/zh-TW/agent-sdk/custom-tools)擷取的 MCP 交握結果。Claude Code 在 v2.1.286 或更新版本中宣告此 capability |

1969| `sdk_mcp_tools_list_changed` | 來自 [SDK MCP 伺服器](/docs/zh-TW/agent-sdk/custom-tools)的 `tools/list_changed` 通知會讓 Claude Code 重新列出該伺服器的工具，因此伺服器在工作階段中途新增的工具能送達 Claude。Claude Code 在 v2.1.286 或更新版本中宣告此 capability |

1958 1970

1959`plugin_errors` 陣列列出外掛載入失敗。項目描述的可能是未載入且不在 `plugins` 中的外掛，或是載入時缺少其中某部分（例如其 hooks 檔案）的外掛。沒有任何失敗時，會省略此鍵。`SDKSystemMessage` 在 Agent SDK v0.3.283 或更新版本中宣告 `plugin_errors`。1971`plugin_errors` 陣列列出外掛載入失敗。項目描述的可能是未載入且不在 `plugins` 中的外掛，或是載入時缺少其中某部分（例如其 hooks 檔案）的外掛。沒有任何失敗時，會省略此鍵。`SDKSystemMessage` 在 Agent SDK v0.3.283 或更新版本中宣告 `plugin_errors`。

1960 1972

agent-view.md +5 −2

Details

347 347

348若要組合篩選條件，請以 `a:`、`s:`、`n:` 或 `o:` 開頭，再加上更多條件，以空格分隔。清單會顯示符合所有條件的工作階段。例如，`s:blocked a:reviewer` 會列出正在等待您的 `reviewer` 工作階段。348若要組合篩選條件，請以 `a:`、`s:`、`n:` 或 `o:` 開頭，再加上更多條件，以空格分隔。清單會顯示符合所有條件的工作階段。例如，`s:blocked a:reviewer` 會列出正在等待您的 `reviewer` 工作階段。

349 349

350篩選條件啟用時，您摺疊的群組會展開以顯示符合的項目，並選定第一個符合項目，因此按 `Enter` 即可開啟它。清除輸入即可移除篩選條件，這些群組會再次摺疊。350篩選條件啟用時，您摺疊的群組會展開以顯示符合的項目，並選定一個符合項目，因此按 `Enter` 即可開啟它。清除輸入即可移除篩選條件，這些群組會再次摺疊。

351 351

352<h3 id="keyboard-shortcuts">352<h3 id="keyboard-shortcuts">

353 鍵盤快捷鍵353 鍵盤快捷鍵

369| `Tab` | 在空輸入上，瀏覽所有子代理。否則應用突出顯示的建議 |369| `Tab` | 在空輸入上，瀏覽所有子代理。否則應用突出顯示的建議 |

372| `Ctrl+F` | 使用 [`n:` 篩選條件](#filter-sessions) 依名稱尋找工作階段 |

373| `Alt+↑` / `Alt+↓` | 跳至上一個或下一個群組標題 |

379| `?` | 顯示所有快捷鍵 |381| `?` | 顯示所有快捷鍵 |

380 382

381`Ctrl+S`、`Ctrl+T` 和 `Ctrl+G` 遵循您的 [`keybindings.json`](/docs/zh-TW/keybindings)。在 [`Agents` 上下文](/docs/zh-TW/keybindings#agents-actions) 中使用 `agents:switchView` 和 `agents:togglePin` 動作重新繫結或取消繫結 `Ctrl+S` 和 `Ctrl+T`，以及透過 `Chat` 上下文的 `chat:externalEditor` 繫結重新繫結 `Ctrl+G`。表中的其他快捷鍵無法重新繫結。383在 [`Agents` 情境](/docs/zh-TW/keybindings#agents-actions) 中具有動作的快捷鍵會遵循您的 [`keybindings.json`](/docs/zh-TW/keybindings)。`Ctrl+G` 也是如此，透過 `Chat` 情境的 `chat:externalEditor` 繫結。

382 384

383<h2 id="dispatch-new-agents">385<h2 id="dispatch-new-agents">

384 分派新 agent386 分派新 agent

1087 1089

1088| 版本 | 變更 |1090| 版本 | 變更 |

1089| - | - |1091| - | - |

1092| v2.1.288 | `Ctrl+F` 會依名稱尋找工作階段，`Alt+↑` / `Alt+↓` 會在群組標題之間跳轉。這兩者以及 `Ctrl+R` 都可以[重新繫結](/docs/zh-TW/keybindings#agents-actions)。 |

1090| v2.1.287 | [`n:<text>` 篩選器](#filter-sessions)會依名稱或第一個提示詞尋找工作階段。當任何篩選器作用中時，您摺疊的群組會展開以顯示其符合項目，並選取第一個符合項目，因此 `Enter` 會開啟它。 |1093| v2.1.287 | [`n:<text>` 篩選器](#filter-sessions)會依名稱或第一個提示詞尋找工作階段。當任何篩選器作用中時，您摺疊的群組會展開以顯示其符合項目，並選取第一個符合項目，因此 `Enter` 會開啟它。 |

1091| v2.1.287 | 作為[查看回覆](#peek-and-reply)傳送的命令會在工作階段目前的回合結束時執行，包括在工作階段自己的輸入中一輸入就會立即執行的命令。內容恰好為 `/stop` 的回覆會立即停止工作階段。 |1094| v2.1.287 | 作為[查看回覆](#peek-and-reply)傳送的命令會在工作階段目前的回合結束時執行，包括在工作階段自己的輸入中一輸入就會立即執行的命令。內容恰好為 `/stop` 的回覆會立即停止工作階段。 |

1092| v2.1.281 | [`--setting-sources`](/docs/zh-TW/cli-reference#cli-flags) 限制[轉移](#what-carries-over-when-you-background)到您使用 `←` 或 `/bg` 背景化的工作階段，以及您從 agent view 分派的工作階段。在此版本之前，生成的工作階段載入每個設定來源。 |1095| v2.1.281 | [`--setting-sources`](/docs/zh-TW/cli-reference#cli-flags) 限制[轉移](#what-carries-over-when-you-background)到您使用 `←` 或 `/bg` 背景化的工作階段，以及您從 agent view 分派的工作階段。在此版本之前，生成的工作階段載入每個設定來源。 |

amazon-bedrock.md +17 −0

Details

386 386

387當這些檢查發現您的帳戶無法呼叫的模型時，Claude Code 會在此機器上記住該拒絕長達一天，並在該時間內啟動時跳過記住的模型，而不會再次詢問 Amazon Bedrock。Claude Code 會在距離上次檢查已過十分鐘後，再次檢查目前預設模型的記住拒絕，因此您的管理員重新啟用的預設會恢復。若要關閉此記憶，請設定 [`CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY=1`](/docs/zh-TW/env-vars)。387當這些檢查發現您的帳戶無法呼叫的模型時，Claude Code 會在此機器上記住該拒絕長達一天，並在該時間內啟動時跳過記住的模型，而不會再次詢問 Amazon Bedrock。Claude Code 會在距離上次檢查已過十分鐘後，再次檢查目前預設模型的記住拒絕，因此您的管理員重新啟用的預設會恢復。若要關閉此記憶，請設定 [`CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY=1`](/docs/zh-TW/env-vars)。

388 388

389<h3 id="when-your-organization-enforces-a-model-allowlist">

390 當您的組織強制執行模型允許清單時

391</h3>

392

393如果您在受管設定中設定了 [`enforceAvailableModels`](/docs/zh-TW/model-config#enforce-the-allowlist-for-the-default-model)，啟動模型檢查只會使用您的 `availableModels` 清單所允許的模型。這適用於 Amazon Bedrock Invoke API，且需要 Claude Code v2.1.287 或更新版本。未搭配 `enforceAvailableModels` 的清單不會限制這些檢查。

394

395這些檢查會將每個項目與其將傳送的推論設定檔 ID（包括其[區域前綴](#cross-region-inference-profile-prefixes)）進行比較，因此請使用這些 ID 撰寫清單。此範例針對模型解析為 `us.` 設定檔的部署，允許 Opus 4.8 和 Sonnet 4.5：

396

397```json theme={null}

398{

399 "availableModels": ["us.anthropic.claude-opus-4-8", "us.anthropic.claude-sonnet-4-5-20250929-v1:0"],

400 "enforceAvailableModels": true

401}

402```

403

404關於別名、版本前綴和 `modelOverrides` 項目，請參閱[為第三方部署釘選模型](/docs/zh-TW/model-config#pin-models-for-third-party-deployments)。

405

389<h3 id="when-a-model-is-disabled-mid-session">406<h3 id="when-a-model-is-disabled-mid-session">

390 當模型在工作階段中被停用時407 當模型在工作階段中被停用時

391</h3>408</h3>

artifacts.md +3 −1

Details

156 讓 Claude 自動回覆評論156 讓 Claude 自動回覆評論

157</h3>157</h3>

158 158

159在您的工作階段發佈成品後，Claude Code 會在工作階段執行期間監視該成品的評論。當可以編輯成品的人向 Claude 發送評論時，它會立即到達您的工作階段，Claude 可以讀取執行緒並回覆，而無需您詢問。159在您的工作階段發佈 artifact 後，Claude Code 會監視該 artifact 的評論。當可以編輯 artifact 的人向 Claude 發送評論時，它會立即到達您的工作階段，Claude 可以讀取執行緒並回覆，而無需您詢問。

160 160

161您需要 Claude Code v2.1.228 或更新版本。如果您關閉了[功能旗標擷取](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)，Claude Code 不會監視評論。161您需要 Claude Code v2.1.228 或更新版本。如果您關閉了[功能旗標擷取](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)，Claude Code 不會監視評論。

162 162

174* **在 `/tasks` 中停止任務**：Claude 停止回覆該成品，直到您要求它在那裡恢復回覆。重新發佈成品不會再次開始回覆，當您稍後恢復工作階段時，停止仍然適用。174* **在 `/tasks` 中停止任務**：Claude 停止回覆該成品，直到您要求它在那裡恢復回覆。重新發佈成品不會再次開始回覆，當您稍後恢復工作階段時，停止仍然適用。

175* **在 3 秒內按兩次 `Ctrl+X Ctrl+K`**：[停止每個執行中背景子代理](/docs/zh-TW/interactive-mode#general-controls)的和弦也會停止 Claude 在工作階段的其餘時間內回覆每個成品。要求 Claude 恢復回覆不會撤銷此停止。175* **在 3 秒內按兩次 `Ctrl+X Ctrl+K`**：[停止每個執行中背景子代理](/docs/zh-TW/interactive-mode#general-controls)的和弦也會停止 Claude 在工作階段的其餘時間內回覆每個成品。要求 Claude 恢復回覆不會撤銷此停止。

176 176

177由 Claude Code 自行啟動的監視，可能會在 artifact 數小時沒有活動後結束。若要重新啟動監視，請再次發佈 artifact 或要求 Claude 監視它。

178

177如果傳遞評論的服務變得不可用或停止回應，Claude Code 會嘗試重新連接一段時間，然後停止監視您的工作階段正在監視的每個成品。179如果傳遞評論的服務變得不可用或停止回應，Claude Code 會嘗試重新連接一段時間，然後停止監視您的工作階段正在監視的每個成品。

178 180

179<h2 id="pull-live-data-with-mcp-connectors">181<h2 id="pull-live-data-with-mcp-connectors">

best-practices.md +5 −4

Details

538</h3>538</h3>

539 539

540<Tip>540<Tip>

541 循環遍歷任務，為每個任務調用 `claude -p`。使用 `--allowedTools` 為批量操作限定權限。541 迴圈處理各項任務，為每個任務呼叫 `claude -p`。使用 `--allowedTools` 為批次作業預先核准工具。

542</Tip>542</Tip>

543 543

544對於大型遷移或分析，您可以在許多平行 Claude 調用中分配工作。執行 [`/batch <instruction>`](/docs/zh-TW/commands#all-commands) 讓 Claude 將變更分割到 5 到 30 個子代理。每個子代理在自己的 worktree 中工作。要改為從您自己的腳本驅動扇出，請循環遍歷 `claude -p`：544對於大型遷移或分析，您可以在許多平行 Claude 調用中分配工作。執行 [`/batch <instruction>`](/docs/zh-TW/commands#all-commands) 讓 Claude 將變更分割到 5 到 30 個子代理。每個子代理在自己的 worktree 中工作。要改為從您自己的腳本驅動扇出，請循環遍歷 `claude -p`：

552 ```bash theme={null}552 ```bash theme={null}

553 for file in $(cat files.txt); do553 for file in $(cat files.txt); do

554 claude -p "Migrate $file from Python 2 to Python 3. Return OK or FAIL." \554 claude -p "Migrate $file from Python 2 to Python 3. Return OK or FAIL." \

555 --allowedTools "Edit,Bash(git commit *)"555 --allowedTools "Edit,Bash(git commit *)" \

556 --permission-mode dontAsk

556 done557 done

557 ```558 ```

558 </Step>559 </Step>

559 560

560 <Step title="在幾個文件上測試，然後大規模運行">561 <Step title="先在幾個檔案上測試，再對全部檔案執行">

561 根據前 2-3 個文件出現的問題改進您的提示，然後在完整集合上運行。`--allowedTools` 旗標限制 Claude 可以做什麼，這在您無人值守運行時很重要。562 根據前 2-3 個檔案出現的問題改進您的提示詞，然後對完整集合執行。`--allowedTools` 旗標會預先核准遷移所需的工具，而 [`--permission-mode dontAsk`](/docs/zh-TW/permission-modes#allow-only-pre-approved-tools-with-dontask-mode) 會拒絕其他任何需要核准的操作，這在無人值守執行時非常重要。

562 </Step>563 </Step>

563</Steps>564</Steps>

564 565

channels.md +1 −1

Details

326 為您的組織啟用 channels326 為您的組織啟用 channels

327</h3>327</h3>

328 328

329可以從 [**claude.ai → 管理員設定 → Claude Code → Channels**](https://claude.ai/admin-settings/claude-code) 為您的組織啟用 channels（需要擁有者角色），或通過在受管設定中將 `channelsEnabled` 設定為 `true`。329可以從 [**組織設定 > Claude Code > Channels**](https://claude.ai/admin-settings/claude-code) 為您的組織啟用頻道（需要擁有者角色），或通過在受管設定中將 `channelsEnabled` 設定為 `true`。

330 330

331啟用後，您組織中的使用者可以使用 `--channels` 將 channel 伺服器選擇加入個別工作階段。如果設定已停用或未設定，MCP 伺服器仍會連接，其工具可以工作，但 channel 訊息不會到達。啟動警告會告訴使用者讓管理員啟用該設定。331啟用後，您組織中的使用者可以使用 `--channels` 將 channel 伺服器選擇加入個別工作階段。如果設定已停用或未設定，MCP 伺服器仍會連接，其工具可以工作，但 channel 訊息不會到達。啟動警告會告訴使用者讓管理員啟用該設定。

332 332

claude-apps-gateway.md +90 −87

Details

259 連接開發人員259 連接開發人員

260</h2>260</h2>

261 261

262開發人員從自己的筆記型電腦使用一次瀏覽器登入進行連接，使用他們的公司工作帳戶。他們不需要 claude.ai 帳戶、API 金鑰或訂閱，因為對模型的請求透過使用組織上游認證的閘道進行。連接由您透過 MDM 推送的[用戶端側受管設定](/docs/zh-TW/claude-apps-gateway-config#client-side-managed-settings)驅動，因此開發人員端沒有手動設定；本節涵蓋管理員配置的內容。262開發人員從自己的筆記型電腦使用一次瀏覽器登入進行連接，使用他們的公司工作帳戶。他們不需要 claude.ai 帳戶、API 金鑰或訂閱，因為對模型的請求透過使用組織上游憑證的閘道進行。連接由您透過 MDM 推送的[用戶端側受管設定](/docs/zh-TW/claude-apps-gateway-config#client-side-managed-settings)驅動，因此開發人員端沒有手動設定；本節涵蓋管理員設定的內容。

263 263

264CLI 在首次連接時對閘道的 TLS 葉憑證進行指紋識別，並按主機名固定它。它在登入期間、無聲會話重新整理期間和受管設定擷取期間再次檢查該固定，而推論請求使用標準 TLS 驗證而不使用固定。透過 HTTPS Proxy 路由的請求會跳過固定檢查，因此將閘道主機新增至 `NO_PROXY` 以保持它們直接。264CLI 在首次連接時對閘道的 TLS 葉憑證進行指紋識別，並按主機名固定它。它在登入期間、無聲工作階段重新整理期間和受管設定擷取期間再次檢查該固定，而推論請求使用標準 TLS 驗證而不使用固定。透過 HTTPS 代理伺服器路由的請求會跳過固定檢查，因此將閘道主機新增至 `NO_PROXY` 以保持它們直接連線。

265 265

266發佈預期的 SHA-256 指紋以及閘道 URL，以便開發人員有可比較的內容。`/login` 提示顯示指紋的前 16 個字元作為小寫十六進位，無冒號。若要從憑證檔案以該形式列印完整指紋，請執行：266發佈預期的 SHA-256 指紋以及閘道 URL，以便開發人員有可比較的內容。`/login` 提示顯示指紋的前 16 個字元作為小寫十六進位，無冒號。若要從憑證檔案以該形式列印完整指紋，請執行：

267 267

270```270```

271 271

272當憑證輪換時，每個開發人員都會再次看到信任提示，因此將輪換視為計劃事件並重新發佈指紋。如果您的閘道原則包含[需要批准的設定](/docs/zh-TW/server-managed-settings#security-approval-dialogs)，開發人員在接受新憑證後也會再次看到該批准對話，因為 Claude Code 會將[批准記憶](/docs/zh-TW/server-managed-settings#approval-memory)金鑰設定為固定的憑證。272當憑證輪換時，每個開發人員都會再次看到信任提示，因此將輪換視為計劃事件並重新發佈指紋。如果您的閘道原則包含[需要核准的設定](/docs/zh-TW/server-managed-settings#security-approval-dialogs)，開發人員在接受新憑證後也會再次看到該核准對話框，因為 Claude Code 會將[核准記憶](/docs/zh-TW/server-managed-settings#approval-memory)綁定至固定的憑證。

273 273

274閘道可以在其令牌回應中返回可選的 `email` 欄位，以命名登入使用的帳戶。當它這樣做時，開發人員在 Claude Code 儲存認證之前確認帳戶。確認登入後，`/status` 顯示帳戶。274閘道可以在其 token 回應中返回可選的 `email` 欄位，以命名登入使用的帳戶。當它這樣做時，開發人員在 Claude Code 儲存憑證之前確認帳戶。確認登入後，`/status` 顯示帳戶。

275 275

276確認需要開發人員機器上的 Claude Code v2.1.275 或更新版本；低於該版本的用戶端會忽略該欄位。`claude` 二進位檔中的閘道伺服器不返回該欄位，因此其登入完成時沒有確認。276確認需要開發人員機器上的 Claude Code v2.1.275 或更新版本；低於該版本的用戶端會忽略該欄位。`claude` 二進位檔中的閘道伺服器不返回該欄位，因此其登入完成時沒有確認。

277 277

278開發人員登入後，[模型選擇器](/docs/zh-TW/model-config)顯示其 `availableModels` 允許清單中的模型。受管設定在啟動時應用並每小時重新整理一次，遙測路由到您的收集器。278開發人員登入後，[模型選擇器](/docs/zh-TW/model-config)顯示其 `availableModels` 允許清單中的模型。受管設定在啟動時套用並每小時重新整理一次，遙測路由到您的收集器。

279 279

280會話在 `ttl_hours` 過期前無聲重新整理。當 IdP 取消佈建後重新整理失敗時，Claude Code 會提示開發人員再次登入。280工作階段在 `ttl_hours` 過期前無聲重新整理。當 IdP 取消佈建後重新整理失敗時，Claude Code 會提示開發人員再次登入。

281 281

282<h3 id="set-the-gateway-url">282<h3 id="set-the-gateway-url">

283 設定閘道 URL283 設定閘道 URL

284</h3>284</h3>

285 285

286三個金鑰進入您透過 MDM 或直接在磁碟上部署的每個 OS [受管設定檔](/docs/zh-TW/managed-settings#delivery-mechanisms)。`forceLoginMethod` 和 `forceLoginGatewayUrl` 在**雲端閘道**螢幕上直接開啟 `/login`，URL 已填入，而 `parentSettingsBehavior: "merge"` 讓 Claude Desktop 將閘道的出口允許清單傳遞給它啟動的 Claude Code 會話，詳見[將原則傳遞給 Claude Desktop 會話](#deliver-policy-to-claude-desktop-sessions)：286三個設定鍵放入您透過 MDM 或直接在磁碟上部署的各 OS [受管設定檔](/docs/zh-TW/managed-settings#delivery-mechanisms)。`forceLoginMethod` 和 `forceLoginGatewayUrl` 在**雲端閘道**畫面上直接開啟 `/login`，URL 已填入，而 `parentSettingsBehavior: "merge"` 讓 Claude Desktop 將閘道的出口允許清單傳遞給它啟動的 Claude Code 工作階段，詳見[將原則傳遞給 Claude Desktop 工作階段](#deliver-policy-to-claude-desktop-sessions)：

287 287

288```json theme={null}288```json theme={null}

289{289{

295 295

296開發人員按 Enter 進行連接。[首次連接 TLS 指紋提示](#connect-developers)仍然出現。一旦檔案在機器上，未完成閘道登入的開發人員會看到[管理員原則要求雲端閘道登入](/docs/zh-TW/errors#administrator-policy-requires-a-cloud-gateway-sign-in)下所述的其中一則訊息。透過環境變數（例如 `CLAUDE_CODE_USE_BEDROCK`）選擇雲端提供商的開發人員不需要閘道登入。296開發人員按 Enter 進行連接。[首次連接 TLS 指紋提示](#connect-developers)仍然出現。一旦檔案在機器上，未完成閘道登入的開發人員會看到[管理員原則要求雲端閘道登入](/docs/zh-TW/errors#administrator-policy-requires-a-cloud-gateway-sign-in)下所述的其中一則訊息。透過環境變數（例如 `CLAUDE_CODE_USE_BEDROCK`）選擇雲端提供商的開發人員不需要閘道登入。

297 297

298開發人員無法手動設定此項。登入選擇器中沒有閘道選項，`forceLoginGatewayUrl` 在開發人員自己的設定檔中被忽略。`forceLoginMethod` 單獨，沒有 URL，將開發人員留在「聯絡您的 IT 管理員」訊息處。登入金鑰應該在您推送到機器的檔案中，而不是在閘道的 `managed.policies[].cli` 區塊中，該區塊僅到達已連接的用戶端。298開發人員無法手動設定此項。登入選擇器中沒有閘道選項，`forceLoginGatewayUrl` 在開發人員自己的設定檔中被忽略。單獨使用 `forceLoginMethod` 而沒有 URL，會讓開發人員停留在「聯絡您的 IT 管理員」訊息處。登入設定鍵應該在您推送到機器的檔案中，而不是在閘道的 `managed.policies[].cli` 區塊中，該區塊僅到達已連接的用戶端。

299 299

300<h3 id="allow-a-gateway-on-public-address-space-you-own">300<h3 id="allow-a-gateway-on-public-address-space-you-own">

301 允許公開位址空間上的閘道301 允許您擁有的公開位址空間上的閘道

302</h3>302</h3>

303 303

304某些組織從他們擁有的公開 IPv4 區塊（例如電信業者自己的位址空間或舊版 `/8`）對其內部網路進行編號，因此他們的閘道無法擁有私人位址。在 `gatewayInternalNetworks` 受管設定中列出這些區塊。`/login` 然後在開發人員的機器從同一區塊內的位址連接到它時，接受位於列出區塊內的閘道。這需要開發人員機器上的 Claude Code v2.1.268 或更新版本；較早的版本忽略該金鑰並應用私人位址規則。304某些組織從他們擁有的公開 IPv4 區塊（例如電信業者自己的位址空間或舊版 `/8`）對其內部網路進行編號，因此他們的閘道無法擁有私人位址。在 `gatewayInternalNetworks` 受管設定中列出這些區塊。`/login` 然後在開發人員的機器從同一區塊內的位址連接到它時，接受位於列出區塊內的閘道。這需要開發人員機器上的 Claude Code v2.1.268 或更新版本；較早的版本忽略該設定鍵並套用私人位址規則。

305 305

306<Warning>306<Warning>

307 `gatewayInternalNetworks` 適用於恰好從公開位址空間編號的內部網路。它不會使將閘道暴露到網際網路變得安全：受信任的閘道可以推送在開發人員機器上執行命令的設定。307 `gatewayInternalNetworks` 適用於恰好從公開位址空間編號的內部網路。它不會使將閘道暴露到網際網路變得安全：受信任的閘道可以推送在開發人員機器上執行命令的設定。

308 308

309 使用您的防火牆或負載平衡器規則將閘道保持在網路外無法到達。將閘道的 [`access_control.allow_cidrs`](/docs/zh-TW/claude-apps-gateway-config#http-tuning) 設定為您在此宣告的相同區塊，以便閘道本身拒絕來自其他任何地方的用戶端。在負載平衡器或入口後面，也將 `listen.trusted_proxies` 設定為該前端，因為閘道否則會根據前端自己的位址而不是開發人員的位址來匹配 `allow_cidrs`。309 使用您的防火牆或負載平衡器規則，讓閘道無法從您的網路外部到達。將閘道的 [`access_control.allow_cidrs`](/docs/zh-TW/claude-apps-gateway-config#http-tuning) 設定為您在此宣告的相同區塊，以便閘道本身拒絕來自其他任何地方的用戶端。在負載平衡器或入口後面，也將 `listen.trusted_proxies` 設定為該前端，因為閘道否則會根據前端自己的位址而不是開發人員的位址來比對 `allow_cidrs`。

310</Warning>310</Warning>

311 311

312將金鑰新增至與登入金鑰相同的受管設定來源：受管設定檔、MDM 設定檔或登錄原則。Claude Code 在使用者、專案和伺服器受管設定中忽略它。312將設定鍵新增至與登入設定鍵相同的受管設定來源：受管設定檔、MDM 設定檔或登錄原則。Claude Code 在使用者、專案和伺服器受管設定中忽略它。

313 313

314此範例宣告一個區塊。將 `203.0.113.0/24` 替換為您自己的區塊。它是文件範圍，Claude Code 拒絕這些。314此範例宣告一個區塊。將 `203.0.113.0/24` 替換為您自己的區塊。它是文件範圍，Claude Code 拒絕這些。

315 315

322Claude Code 在 `/login` 驗證清單，然後才聯絡任何閘道：322Claude Code 在 `/login` 驗證清單，然後才聯絡任何閘道：

323 323

324* 每個項目是一個 IPv4 區塊，寫成其第一個位址和 `/8` 到 `/32` 的前綴。324* 每個項目是一個 IPv4 區塊，寫成其第一個位址和 `/8` 到 `/32` 的前綴。

325* 清單最多包含四個區塊，沒有兩個重疊。325* 清單最多包含四個區塊，且沒有兩個重疊。

326* 沒有區塊與私人位址空間重疊：`10.0.0.0/8`、`172.16.0.0/12`、`192.168.0.0/16`、`127.0.0.0/8`、`169.254.0.0/16` 和 `100.64.0.0/10`。`/login` 已經在沒有此金鑰的情況下接受那裡的閘道。326* 沒有區塊與私人位址空間重疊：`10.0.0.0/8`、`172.16.0.0/12`、`192.168.0.0/16`、`127.0.0.0/8`、`169.254.0.0/16` 和 `100.64.0.0/10`。`/login` 已經在沒有此設定鍵的情況下接受那裡的閘道。

327* 沒有區塊與永遠不是組織網路的空間重疊：`198.18.0.0/15` 和 `192.0.0.0/24`，VPN 和 NAT64 用戶端將其作為本地位址；文件範圍 `192.0.2.0/24`、`198.51.100.0/24` 和 `203.0.113.0/24`；以及保留範圍 `0.0.0.0/8`、`192.88.99.0/24` 和多播 `224.0.0.0/4`。您可以在 `240.0.0.0/4` 內宣告區塊，某些大型網路將其用作內部單播空間。327* 沒有區塊與永遠不是組織網路的空間重疊：`198.18.0.0/15` 和 `192.0.0.0/24`，VPN 和 NAT64 用戶端將其作為本機位址；文件範圍 `192.0.2.0/24`、`198.51.100.0/24` 和 `203.0.113.0/24`；以及保留範圍 `0.0.0.0/8`、`192.88.99.0/24` 和多播 `224.0.0.0/4`。您可以在 `240.0.0.0/4` 內宣告區塊，某些大型網路將其用作內部單播空間。

328 328

329來自 `managed-settings.json` 及其 `managed-settings.d/` 插入檔案的區塊合併為一個清單，這些限制適用於合併清單。若要縮小區塊，請替換其項目而不是在插入中新增第二個重疊的；`/login` 拒絕重疊。329來自 `managed-settings.json` 及其 `managed-settings.d/` 插入檔案的區塊合併為一個清單，這些限制適用於合併後的清單。若要縮小區塊，請替換其項目，而不是在插入檔案中新增第二個重疊的項目；`/login` 會拒絕重疊。

330 330

331如果項目違反規則，或值不是字串清單，Claude Code 在該機器上拒絕每個新的閘道登入並在訊息中命名問題。登入到私人位址上的閘道也會失敗，現有登入保持有效。在部署前在一台機器上嘗試該值。Claude Code 也在它報告的[無效受管設定](/docs/zh-TW/managed-settings#keys-that-fail-closed)中列出錯誤類型的值。331如果項目違反規則，或值不是字串清單，Claude Code 會在該機器上拒絕每個新的閘道登入，並在訊息中指出問題。登入到私人位址上的閘道也會失敗，現有登入保持有效。在部署前先在一台機器上嘗試該值。Claude Code 也會在它報告的[無效受管設定](/docs/zh-TW/managed-settings#keys-that-fail-closed)中列出類型錯誤的值。

332 332

333使用有效清單，`/login` 對位址位於列出區塊內的閘道應用三個檢查：333使用有效清單時，`/login` 對位址位於列出區塊內的閘道套用三項檢查：

334 334

335* 閘道主機名解析到的每個位址都位於該一個區塊內。Claude Code 拒絕也在其外有記錄的名稱，包括私人和 IPv6 位址。335* 閘道主機名解析到的每個位址都位於該同一區塊內。Claude Code 拒絕在區塊外也有記錄的名稱，包括私人和 IPv6 位址。

336* 開發人員的機器從同一區塊內連接。Claude Code 拒絕 NAT 後面、容器或 WSL2 內或其位址池位於區塊外的 VPN 上的機器，並命名機器連接的位址。336* 開發人員的機器從同一區塊內連接。Claude Code 拒絕位於 NAT 後面、容器或 WSL2 內，或位址池位於區塊外的 VPN 上的機器，並指出機器連接所使用的位址。

337* 連接是直接的。如果 `HTTPS_PROXY` 適用於閘道主機，`/login` 拒絕並命名要新增的 `NO_PROXY` 項目。337* 連接是直接的。如果 `HTTPS_PROXY` 適用於閘道主機，`/login` 會拒絕並指出要新增的 `NO_PROXY` 項目。

338 338

339當所有三個通過時，[信任提示](#connect-developers)新增一行命名機器的位址、閘道的位址和包含兩者的宣告區塊。339當三項都通過時，[信任提示](#connect-developers)會新增一行，指出機器的位址、閘道的位址，以及同時包含兩者的宣告區塊。

340 340

341該金鑰對其他閘道不改變任何內容：登入到私人位址上的閘道像以前一樣有效，登入到每個列出區塊外的公開位址上的閘道像以前一樣被拒絕。341該設定鍵對其他閘道不改變任何內容：登入到私人位址上的閘道像以前一樣有效，登入到所有列出區塊外的公開位址上的閘道像以前一樣被拒絕。

342 342

343宣告的區塊縮小誰可以登入但不證明機器在哪裡，因此僅宣告您的組織控制的位址空間。與其他租戶共享的區塊（例如雲端提供商的公開範圍）讓其中的任何人通過相同的檢查。343宣告的區塊縮小了誰可以登入，但無法證明機器的所在位置，因此僅宣告您的組織控制的位址空間。與其他租戶共享的區塊（例如雲端提供商的公開範圍）會讓其中的任何人通過相同的檢查。

344 344

345<h3 id="deliver-policy-to-claude-desktop-sessions">345<h3 id="deliver-policy-to-claude-desktop-sessions">

346 將原則傳遞給 Claude Desktop 會話346 將原則傳遞給 Claude Desktop 工作階段

347</h3>347</h3>

348 348

349Claude Desktop 在嵌入式 Claude Code 會話上執行其 Cowork 和 Code 標籤，以及當您啟用它時的 Chat 標籤，並透過閘道傳送其模型請求。它將原則傳遞給每個會話，從閘道在 `/user/bootstrap` 提供的配置建立：模型允許清單、禁用的工具，以及從匹配原則的 `cli` 區塊衍生的出口允許清單，加上[`desktop` 覆蓋](/docs/zh-TW/claude-apps-gateway-config#claude-desktop-overlay)。349Claude Desktop 在嵌入式 Claude Code 工作階段上執行其 Cowork 和 Code 標籤，以及您啟用時的 Chat 標籤，並透過閘道傳送其模型請求。它將原則傳遞給每個工作階段，原則由閘道在 `/user/bootstrap` 提供的設定建立：模型允許清單、停用的工具，以及從相符原則的 `cli` 區塊衍生的出口允許清單，加上 [`desktop` 覆蓋](/docs/zh-TW/claude-apps-gateway-config#claude-desktop-overlay)。

350 350

351其他 `cli` 金鑰，例如 hooks、`env` 和範圍權限規則（如 `Bash(npm *)`），僅到達透過 `/login` 登入的用戶端。Claude Desktop 從其自己的受管配置讀取閘道 URL，並使用其自己的流程登入，與[設定閘道 URL](#set-the-gateway-url) 中的 `forceLoginMethod` 和 `forceLoginGatewayUrl` 金鑰分開。351其他 `cli` 設定鍵，例如 hook、`env` 和範圍權限規則（如 `Bash(npm *)`），僅到達透過 `/login` 登入的用戶端。Claude Desktop 從其自己的受管設定讀取閘道 URL，並使用其自己的流程登入，與[設定閘道 URL](#set-the-gateway-url) 中的 `forceLoginMethod` 和 `forceLoginGatewayUrl` 設定鍵分開。

352 352

353由啟動程序傳遞的設定是父設定。Claude Code 在任何具有管理員部署的受管來源的機器上忽略父設定，除非[傳遞原則的來源](/docs/zh-TW/managed-settings#which-managed-source-claude-code-uses)設定 `parentSettingsBehavior: "merge"`。353由啟動程序傳遞的設定是父設定。Claude Code 在任何具有管理員部署之受管來源的機器上忽略父設定，除非[傳遞原則的來源](/docs/zh-TW/managed-settings#which-managed-source-claude-code-uses)設定了 `parentSettingsBehavior: "merge"`。

354 354

355<h4 id="which-machines-need-the-opt-in">355<h4 id="which-machines-need-the-opt-in">

356 哪些機器需要選擇加入356 哪些機器需要選擇加入

357</h4>357</h4>

358 358

359僅執行 Claude Desktop 的機器需要它。Claude Desktop 將模型清單和禁用工具清單應用於嵌入式會話本身，但出口允許清單僅作為父設定到達它們，形式為 `WebFetch` 網域規則和沙箱網路規則。沒有選擇加入，這些會話執行時沒有出口限制，沒有任何警告。閘道仍然拒絕原則不授予的模型的推論請求。359僅執行 Claude Desktop 的機器需要它。Claude Desktop 會自行將模型清單和停用工具清單套用於嵌入式工作階段，但出口允許清單僅作為父設定到達它們，形式為 `WebFetch` 網域規則和沙箱網路規則。沒有選擇加入時，這些工作階段執行時沒有出口限制，且不會有任何警告。閘道仍然拒絕原則未授予之模型的推論請求。

360 360

361外掛程式市集允許清單也僅作為父設定到達嵌入式會話。當您在 Claude Desktop 的受管配置中關閉使用者新增的外掛程式市集時，Claude Desktop 2.16120.0 或更新版本會隱藏您的組織未佈建的市集，並拒絕從它們安裝。若要停止嵌入式會話載入已從這些市集安裝的外掛程式，它會將 `strictKnownMarketplaces` 清單作為父設定傳送給它們。沒有選擇加入，Claude Code 會忽略該清單，這些外掛程式會繼續載入。361外掛市集允許清單也僅作為父設定到達嵌入式工作階段。當您在 Claude Desktop 的受管設定中關閉使用者新增的外掛市集時，Claude Desktop 2.16120.0 或更新版本會隱藏您的組織未佈建的市集，並拒絕從它們安裝。為了阻止嵌入式工作階段載入已從這些市集安裝的外掛，它會將 `strictKnownMarketplaces` 清單作為父設定傳送給它們。沒有選擇加入時，Claude Code 會忽略該清單，這些外掛會繼續載入。

362 362

363開發人員透過 `/login` 登入的機器不需要它；每個 Claude Code 會話從閘道擷取其原則。363開發人員透過 `/login` 登入的機器不需要它；每個 Claude Code 工作階段從閘道擷取其原則。

364 364

365其[`policyHelper`](/docs/zh-TW/settings-reference#policyhelper)提供受管設定的機隊無法使用它：Claude Code 在這些機隊上永遠不會合併父設定，因為它僅從助手的輸出讀取受管設定。365由 [`policyHelper`](/docs/zh-TW/settings-reference#policyhelper) 提供受管設定的機隊無法使用它：Claude Code 在這些機隊上永遠不會合併父設定，因為它僅從 helper 的輸出讀取受管設定。

366 366

367<h4 id="set-the-opt-in">367<h4 id="set-the-opt-in">

368 設定選擇加入368 設定選擇加入

369</h4>369</h4>

370 370

371從[設定閘道 URL](#set-the-gateway-url) 部署受管設定片段，將其鏡像到任何優先於檔案的用戶端側來源，然後驗證。371部署[設定閘道 URL](#set-the-gateway-url) 中的受管設定片段，將其鏡像到任何優先於該檔案的用戶端側來源，然後驗證。

372 372

373<Steps>373<Steps>

374 <Step title="在受管設定檔中部署選擇加入">374 <Step title="在受管設定檔中部署選擇加入">

375 上面的[片段](#set-the-gateway-url)已經包含 `parentSettingsBehavior: "merge"`，因此您推送到機器的檔案攜帶它。375 [上面的片段](#set-the-gateway-url)已經包含 `parentSettingsBehavior: "merge"`，因此您推送到機器的檔案會攜帶它。

376 </Step>376 </Step>

377 377

378 <Step title="將片段鏡像到任何優先於檔案的來源">378 <Step title="將片段鏡像到任何優先於該檔案的來源">

379 Claude Code 僅從[選定的來源](/docs/zh-TW/managed-settings#which-managed-source-claude-code-uses)讀取 `parentSettingsBehavior`。將任何原則金鑰新增至來源可以使該來源成為選定的來源，因此在用戶端側來源中，鏡像整個片段而不僅僅是 `parentSettingsBehavior`。[用戶端側受管設定](/docs/zh-TW/claude-apps-gateway-config#client-side-managed-settings)涵蓋透過群組原則或配置設定檔傳遞原則的機隊。macOS 上的受管偏好設定 plist 或 Windows 上的 HKLM 原則優先於 `managed-settings.json` 檔案，閘道自己的遠端受管設定優先於兩者，因此在登入閘道的機器上，也在閘道原則的 [`cli` 區塊](/docs/zh-TW/claude-apps-gateway-config#managed)中設定 `parentSettingsBehavior`。379 Claude Code 僅從[選定的來源](/docs/zh-TW/managed-settings#which-managed-source-claude-code-uses)讀取 `parentSettingsBehavior`。將任何原則設定鍵新增至某個來源可能會使該來源成為選定的來源，因此在用戶端側來源中，請鏡像整個片段，而不僅僅是 `parentSettingsBehavior`。[用戶端側受管設定](/docs/zh-TW/claude-apps-gateway-config#client-side-managed-settings)涵蓋透過群組原則或組態設定檔傳遞原則的機隊。macOS 上的受管偏好設定 plist 或 Windows 上的 HKLM 原則優先於 `managed-settings.json` 檔案，而閘道自己的遠端受管設定優先於兩者，因此在登入閘道的機器上，也要在閘道原則的 [`cli` 區塊](/docs/zh-TW/claude-apps-gateway-config#managed)中設定 `parentSettingsBehavior`。

380 </Step>380 </Step>

381 381

382 <Step title="檢查選定的來源">382 <Step title="檢查選定的來源">

383 在僅執行 Claude Desktop 的機器上，呼叫 Agent SDK 的 [`resolveSettings()`](/docs/zh-TW/agent-sdk/typescript#resolvesettings) 並在其 `sources` 清單中的 `managed` 項目上讀取 `policyOrigin`。該值命名選定的用戶端側來源，`plist`、`hklm` 或 `file`，這是必須攜帶片段的來源。Claude Desktop 的嵌入式會話不擷取閘道原則，因此閘道的 `cli` 區塊永遠不會計為它們的選定來源。383 在僅執行 Claude Desktop 的機器上，呼叫 Agent SDK 的 [`resolveSettings()`](/docs/zh-TW/agent-sdk/typescript#resolvesettings)，並讀取其 `sources` 清單中 `managed` 項目上的 `policyOrigin`。該值指出選定的用戶端側來源：`plist`、`hklm` 或 `file`，這就是必須攜帶片段的來源。Claude Desktop 的嵌入式工作階段不擷取閘道原則，因此閘道的 `cli` 區塊永遠不會被視為它們的選定來源。

384 </Step>384 </Step>

385</Steps>385</Steps>

386 386

390 390

391一旦您部署 `parentSettingsBehavior: "merge"`，任何啟動 Claude Code 的主機程序都可以提供父設定，不僅是 Claude Desktop，還有 Agent SDK 應用程式或 IDE 擴充功能。391一旦您部署 `parentSettingsBehavior: "merge"`，任何啟動 Claude Code 的主機程序都可以提供父設定，不僅是 Claude Desktop，還有 Agent SDK 應用程式或 IDE 擴充功能。

392 392

393Claude Code 根據限制性金鑰的允許清單篩選父設定，但某些允許的金鑰可以授予存取權而不是限制它。除非您設定 `allowManaged*Only` 鎖定，主機提供的權限允許規則和沙箱允許清單仍然適用。您的原則的拒絕和詢問規則無論如何都保持有效；[它們在任何允許規則之前進行評估](/docs/zh-TW/permissions#manage-permissions)。393Claude Code 根據限制性設定鍵的允許清單篩選父設定，但某些允許的設定鍵可能會授予存取權而非加以限制。除非您設定 `allowManaged*Only` 鎖定，否則主機提供的權限允許規則和沙箱允許清單仍然適用。無論如何，您的原則的拒絕和詢問規則都保持有效；[它們在任何允許規則之前進行評估](/docs/zh-TW/permissions#manage-permissions)。

394 394

395Claude Code 以剝離形式轉發父提供的 [`sandbox.credentials`](/docs/zh-TW/settings-reference#sandbox-credentials) 項目：395Claude Code 以剝離形式轉發父提供的 [`sandbox.credentials`](/docs/zh-TW/settings-reference#sandbox-credentials) 項目：

396 396

397* **`deny` 項目**：僅使用其 `path` 或 `name` 和模式轉發。397* **`deny` 項目**：僅使用其 `path` 或 `name` 和模式轉發。

398* **具有 [`mode: mask`](/docs/zh-TW/sandboxing#mask-credential-files) 的檔案項目**：轉發為僅限哨兵，作為整個檔案遮罩，其 `injectHosts` 是空清單，因此代理在任何平台上永遠不會用真實值替換父提供的項目。所有結構化遮罩欄位也被刪除，因此父提供的擷取模式無法取代另一個來源為相同路徑設定的更嚴格遮罩。398* **具有 [`mode: mask`](/docs/zh-TW/sandboxing#mask-credential-files) 的檔案項目**：僅以哨兵形式轉發，作為 `injectHosts` 為空清單的整個檔案遮罩，因此代理伺服器在任何平台上永遠不會為父提供的項目替換為真實值。所有結構化遮罩欄位也會被刪除，因此父提供的擷取模式無法取代另一個來源為相同路徑設定的更嚴格遮罩。

399* **具有 `mode: mask` 的 `envVars` 項目**：不轉發。`deny` 是父通道可以透過 `envVars` 項目表達的唯一限制。399* **具有 `mode: mask` 的 `envVars` 項目**：不轉發。`deny` 是父通道可以透過 `envVars` 項目表達的唯一限制。

400* **[`awsPairs` 和 `sigv4`](/docs/zh-TW/sandboxing#re-sign-aws-requests)**：轉發限制專用。從 `sigv4`，僅保留 `deny` 值，定義 `sigv4` 區塊的父會將所有三種請求形式 `streaming`、`presigned` 和 `sigv4a` 固定為 `deny`。`awsPairs` 對永遠不會以可重新簽署的形式轉發；命名其中一個常規 AWS 變數的對被替換為保持 `AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY` 和 `AWS_SESSION_TOKEN` 自動配對被抑制的惰性項目。400* **[`awsPairs` 和 `sigv4`](/docs/zh-TW/sandboxing#re-sign-aws-requests)**：以僅限制的形式轉發。從 `sigv4` 中僅保留 `deny` 值，而只要父項定義了 `sigv4` 區塊，就會將所有三種請求形式 `streaming`、`presigned` 和 `sigv4a` 固定為 `deny`。`awsPairs` 配對永遠不會以可重新簽署的形式轉發；命名其中一個慣用 AWS 變數的配對會被替換為惰性項目，使 `AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY` 和 `AWS_SESSION_TOKEN` 的自動配對保持被抑制。

401 401

402<h4 id="deploy-the-locks">402<h4 id="deploy-the-locks">

403 部署鎖定403 部署鎖定

404</h4>404</h4>

405 405

406為了保持父設定盡可能接近限制專用，如篩選器支援的那樣，將所有五個 `allowManaged*Only` 鎖定和它們管理的允許清單新增至與合併選擇加入相同的來源：406為了讓父設定盡可能接近篩選器所支援的僅限制形式，請將全部五個 `allowManaged*Only` 鎖定及其管理的允許清單，新增至與合併選擇加入相同的來源：

407 407

408```json theme={null}408```json theme={null}

409{409{

428}428}

429```429```

430 430

431OS 原則（例如 HKLM 登錄原則或受管偏好設定 plist）優先於此檔案，因此透過它而不是檔案傳遞整個片段。閘道的遠端受管設定優先於 OS 原則和檔案來源，但僅到達已連接的用戶端。將鎖定、允許清單和合併選擇加入鏡像到原則的 [`cli` 區塊](/docs/zh-TW/claude-apps-gateway-config#managed)中，並保持此檔案部署，因為永遠不連接的機器（包括僅執行 Claude Desktop 的機器）僅從檔案獲取其原則。431OS 原則（例如 HKLM 登錄原則或受管偏好設定 plist）優先於此檔案，因此請透過它而不是檔案傳遞整個片段。閘道的遠端受管設定優先於 OS 原則和檔案來源，但僅到達已連接的用戶端。將鎖定、允許清單和合併選擇加入鏡像到原則的 [`cli` 區塊](/docs/zh-TW/claude-apps-gateway-config#managed)中，並保持此檔案的部署，因為永遠不連接的機器（包括僅執行 Claude Desktop 的機器）僅從該檔案取得其原則。

432 432

433<h4 id="lock-behavior-across-sources">433<h4 id="lock-behavior-across-sources">

434 跨來源的鎖定行為434 跨來源的鎖定行為

435</h4>435</h4>

436 436

437設定一個鎖定不會限制其他鎖定；每個金鑰都記錄在[設定參考](/docs/zh-TW/settings-reference#all-settings)中。437設定一個鎖定不會限制其他鎖定；每個設定鍵都記錄在[設定參考](/docs/zh-TW/settings-reference#all-settings)中。

438 438

439從低於獲勝者的管理員來源，兩個沙箱鎖定仍然適用，`allowManagedPermissionRulesOnly` 仍然阻止父提供的允許規則和 `additionalDirectories`。在 Claude Code v2.1.273 或更新版本上，MCP 伺服器鎖定也從低於獲勝者的來源應用，當它開啟時，受管 `allowedMcpServers` 清單來自設定一個的最高優先級管理員來源。439來自低於獲勝來源的管理員來源時，兩個沙箱鎖定仍然適用，且 `allowManagedPermissionRulesOnly` 仍然阻擋父提供的允許規則和 `additionalDirectories`。在 Claude Code v2.1.273 或更新版本上，MCP 伺服器鎖定也會從低於獲勝來源的來源套用，且在其開啟時，受管 `allowedMcpServers` 清單來自有設定該清單的最高優先級管理員來源。

440 440

441hooks 鎖定和 `allowManagedPermissionRulesOnly` 對開發人員自己規則的影響預設需要獲勝的來源；在[Claude Code 如何合併受管來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)中的 `managedSourcesBehavior` 合併選擇加入下，Claude Code 應用任何來源為每個鎖定設定的最嚴格值。在 [`policyHelper`](/docs/zh-TW/settings-reference#policyhelper) 機隊上，鎖定僅從助手的輸出讀取。441hook 鎖定以及 `allowManagedPermissionRulesOnly` 對開發人員自己規則的影響，預設需要來自獲勝的來源；在 [Claude Code 如何合併受管來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)中的 `managedSourcesBehavior` 合併選擇加入下，Claude Code 會對每個鎖定套用任何來源設定的最嚴格值。在 [`policyHelper`](/docs/zh-TW/settings-reference#policyhelper) 機隊上，Claude Code 僅從 helper 的輸出讀取鎖定。

442 442

443每個鎖定使 Claude Code 忽略開發人員自己的該設定項目，因此在鎖定旁邊包含您組織的允許清單：443每個鎖定都會使 Claude Code 忽略開發人員自己針對該設定的項目，因此請在鎖定旁邊包含您組織的允許清單：

444 444

445* **網路網域**：使用空受管網域清單鎖定會阻止所有沙箱出站流量。445* **網路網域**：以空的受管網域清單鎖定會阻擋所有沙箱出站流量。

446* **MCP 伺服器**：使用沒有任何管理員來源或父提供的設定中的 `allowedMcpServers` 的鎖定會載入 `deniedMcpServers` 不阻止的每個伺服器。446* **MCP 伺服器**：在任何管理員來源或父提供的設定中都沒有 `allowedMcpServers` 的情況下鎖定，會載入 `deniedMcpServers` 未阻擋的每個伺服器。

447* **讀取路徑**：`allowRead` 項目僅重新允許 `denyRead` 區域內的路徑，因此將它們與受管 `denyRead` 配對。447* **讀取路徑**：`allowRead` 項目僅重新允許 `denyRead` 區域內的路徑，因此請將它們與受管 `denyRead` 配對。

448 448

449<h4 id="settings-the-locks-don’t-cover">449<h4 id="settings-the-locks-don’t-cover">

450 鎖定不涵蓋的設定450 鎖定不涵蓋的設定

451</h4>451</h4>

452 452

453六個父提供的設定即使設定了所有五個鎖定也會通過篩選器。在預設首次獲勝設定下，阻止父項的管理員值是最高優先級管理員來源中的值，除了 `allowedMcpServers` 當[MCP 伺服器鎖定](#lock-behavior-across-sources)開啟時。在 `managedSourcesBehavior` 合併選擇加入下，[Claude Code 如何合併受管來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)說明哪個來源的值改為適用。453即使設定了所有五個鎖定，這些父提供的設定仍會通過篩選器：

454 454

455* **`forceLoginOrgUUID`**：當最高優先級管理員來源未設定組織 UUID 時，Claude Code 會接受父提供的值。閘道登入不檢查此金鑰。最高優先級管理員來源中的組織 UUID 會阻止父項的值，是 Claude Code 強制執行的值。455* **`forceLoginOrgUUID`**：當最高優先級管理員來源未設定組織 UUID 時，Claude Code 會接受父提供的值。閘道登入不檢查此設定鍵。最高優先級管理員來源中的組織 UUID 會阻擋父項的值，且是 Claude Code 強制執行的值。

456* **`allowedMcpServers`**：當沒有管理員清單生效時，Claude Code 會接受父提供的允許清單。`allowManagedMcpServersOnly` 不會阻止它，因為鎖定強制執行無論哪個清單獲勝作為受管值，包括當沒有管理員來源提供清單時的父提供清單。最高優先級管理員來源中的清單會阻止父項的並是 Claude Code 強制執行的清單，因此在那裡設定 `allowedMcpServers`，在鎖定旁邊。在 v2.1.223 之前，任何管理員來源中任一金鑰的值都會阻止父項的。456* **`allowedMcpServers`**：當沒有管理員清單生效時，Claude Code 會接受父提供的允許清單。`allowManagedMcpServersOnly` 不會阻擋它，因為鎖定會將獲勝的清單作為受管值強制執行，包括在沒有管理員來源提供清單時的父提供清單。最高優先級管理員來源中的清單會阻擋父項的清單，且是 Claude Code 強制執行的清單，因此請在那裡、在鎖定旁邊設定 `allowedMcpServers`。在 v2.1.223 之前，任何管理員來源中任一設定鍵的值都會阻擋父項的值。

457* **`availableModels`**：當獲勝的受管來源未設定模型清單時，Claude Code 會接受父提供的模型清單。如果您的機隊限制模型，在獲勝的來源中設定 `availableModels`。457* **`availableModels`**：當獲勝的受管來源未設定模型清單時，Claude Code 會接受父提供的模型清單。如果您的機隊限制模型，請在獲勝的來源中設定 `availableModels`。

458* **`strictKnownMarketplaces`**：當獲勝的受管來源未設定外掛程式市集允許清單時，Claude Code 會接受父提供的外掛程式市集允許清單。Claude Desktop 2.16120.0 或更新版本在其受管配置關閉使用者新增的外掛程式市集時傳送一個。如果您的機隊限制市集，在獲勝的來源中設定 `strictKnownMarketplaces`。需要 Claude Code v2.1.282 或更新版本。458* **`allowedProviders`**：當獲勝的受管來源未設定 API 提供商允許清單時，Claude Code 會接受父提供的 API 提供商允許清單。如果您的機隊限制開發人員可以使用的 API 提供商，請在獲勝的來源中設定 `allowedProviders`。需要 Claude Code v2.1.285 或更新版本。

459* **`blockedMarketplaces`**：父提供的市集封鎖清單通過並新增至任何受管來源設定的封鎖清單，因為封鎖清單只能進一步限制。需要 Claude Code v2.1.282 或更新版本。459* **`strictKnownMarketplaces`**：當獲勝的受管來源未設定外掛市集允許清單時，Claude Code 會接受父提供的外掛市集允許清單。Claude Desktop 2.16120.0 或更新版本在其受管設定關閉使用者新增的外掛市集時會傳送一個。如果您的機隊限制市集，請在獲勝的來源中設定 `strictKnownMarketplaces`。需要 Claude Code v2.1.282 或更新版本。

460* **`strictPluginOnlyCustomization`**：此金鑰無論任何鎖定都通過篩選器，它使 Claude Code 忽略開發人員自己的自訂，包括保護性 hooks。沒有鎖定阻止它。460* **`blockedMarketplaces`**：父提供的市集封鎖清單會通過，並新增至任何受管來源設定的封鎖清單，因為封鎖清單只能進一步限制。需要 Claude Code v2.1.282 或更新版本。

461* **`strictPluginOnlyCustomization`**：無論任何鎖定，此設定鍵都會通過篩選器，且它會使 Claude Code 忽略開發人員自己的自訂，包括保護性 hook。沒有鎖定能阻擋它。

462

463在預設的首次獲勝設定下，只有當管理員值位於最高優先級管理員來源時，才會阻擋父項的值，但 [MCP 伺服器鎖定](#lock-behavior-across-sources)開啟時的 `allowedMcpServers` 除外。在 `managedSourcesBehavior` 合併選擇加入下，[Claude Code 如何合併受管來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources)說明改為套用哪個來源的值。

461 464

462<h3 id="connect-claude-desktop">465<h3 id="connect-claude-desktop">

463 連接 Claude Desktop466 連接 Claude Desktop

464</h3>467</h3>

465 468

466[Claude Desktop](/docs/zh-TW/desktop)透過不同的 MDM 金鑰連接到相同的閘道：在 Claude Desktop 的[受管配置](https://claude.com/docs/third-party/claude-desktop/configuration)中將 `bootstrapUrl` 設定為 `<listen.public_url>/user/bootstrap`，並使用 `desktop` 金鑰選擇加入使用者的原則。[Claude Desktop 覆蓋](/docs/zh-TW/claude-apps-gateway-config#claude-desktop-overlay)涵蓋兩個部分。需要閘道伺服器上的 Claude Code v2.1.203 或更新版本。469[Claude Desktop](/docs/zh-TW/desktop) 透過不同的 MDM 設定鍵連接到相同的閘道：在 Claude Desktop 的[受管設定](https://claude.com/docs/third-party/claude-desktop/configuration)中將 `bootstrapUrl` 設定為 `<listen.public_url>/user/bootstrap`，並使用 `desktop` 設定鍵讓使用者的原則選擇加入。[Claude Desktop 覆蓋](/docs/zh-TW/claude-apps-gateway-config#claude-desktop-overlay)涵蓋這兩個部分。需要閘道伺服器上的 Claude Code v2.1.203 或更新版本。

467 470

468Claude Desktop 透過閘道的身份提供者使用相同的瀏覽器 SSO 步驟簽署開發人員，然後從閘道而不是從 Anthropic 擷取其配置。模型存取和原則遵循與 CLI 相同的每個群組規則。同時使用 CLI 和 Claude Desktop 的開發人員分別登入每個；閘道會話不在它們之間共享。471Claude Desktop 透過閘道的身分提供者，以相同的瀏覽器 SSO 步驟讓開發人員登入，然後從閘道而不是從 Anthropic 擷取其設定。模型存取和原則遵循與 CLI 相同的各群組規則。同時使用 CLI 和 Claude Desktop 的開發人員需分別登入兩者；閘道工作階段不會在它們之間共享。

469 472

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

471 474

472<h3 id="ci-pipelines-and-remote-machines">475<h3 id="ci-pipelines-and-remote-machines">

473 CI 管道和遠端機器476 CI 管道和遠端機器

474</h3>477</h3>

475 478

476沒有無人值守管道的服務令牌流程。閘道登入始終執行瀏覽器裝置流程，因此沒有開發人員批准登入的 CI 作業無法進行身份驗證；針對您的提供商直接配置這些。479無人值守的管道沒有服務 token 流程。閘道登入始終執行瀏覽器裝置流程，因此沒有開發人員核准登入的 CI 作業無法進行身分驗證；請直接針對您的提供商設定這些作業。

477 480

478開發人員登入後，該機器上的每個 Claude Code 會話都使用閘道會話，包括非互動式 `claude -p` 執行和由 Agent SDK 啟動的會話。Claude Code 將[閘道原則](/docs/zh-TW/claude-apps-gateway-config#managed)應用於每個會話。481開發人員登入後，該機器上的每個 Claude Code 工作階段都會使用閘道工作階段，包括非互動式 `claude -p` 執行和由 Agent SDK 啟動的工作階段。Claude Code 將[閘道原則](/docs/zh-TW/claude-apps-gateway-config#managed)套用於每個工作階段。

479 482

480裝置流程將輪詢 CLI 與批准瀏覽器分開，因此沒有顯示的遠端開發框仍然有效：開發人員透過 SSH 在遠端機器上執行 `/login`，並在其筆記型電腦上的瀏覽器中開啟驗證連結。483裝置流程將輪詢的 CLI 與核准的瀏覽器分開，因此沒有顯示器的遠端開發機器仍然可以運作：開發人員透過 SSH 在遠端機器上執行 `/login`，並在其筆記型電腦上的瀏覽器中開啟驗證連結。

481 484

482<h3 id="whats-enforced-on-developers">485<h3 id="whats-enforced-on-developers">

483 在開發人員上強制執行的內容486 對開發人員強制執行的內容

484</h3>487</h3>

485 488

486這些保證適用於每個透過 `/login` 登入的會話。Claude Desktop 啟動的嵌入式會話按[將原則傳遞給 Claude Desktop 會話](#deliver-policy-to-claude-desktop-sessions)中所述獲取其原則，遙測項目說明其匯出的去向。489這些保證適用於每個透過 `/login` 登入的工作階段。Claude Desktop 啟動的嵌入式工作階段按照[將原則傳遞給 Claude Desktop 工作階段](#deliver-policy-to-claude-desktop-sessions)中所述取得其原則，遙測項目則說明其匯出的去向。

~~487~~ 490

488* **模型存取**：對於原則不授予的模型的請求返回 400，`/model` 選擇器被篩選為原則的 `availableModels` 允許清單。在原則中設定 [`enforceAvailableModels: true`](/docs/zh-TW/model-config#default-model-behavior)，以便預設選項解析為 `availableModels` 內的模型，而不是 Claude Code 的內建預設值；沒有它，預設保持可選擇，如果該模型未被授予，則在請求時被拒絕。491* **模型存取**：對原則未授予之模型的請求會返回 400，且 `/model` 選擇器會篩選為原則的 `availableModels` 允許清單。這包括工作階段在開發人員選擇模型之前啟動時使用的模型；請參閱[在原則允許的模型上啟動工作階段](/docs/zh-TW/claude-apps-gateway-config#start-sessions-on-a-model-the-policy-allows)。

489* **遙測目的地**：在透過 `/login` 登入的會話中，CLI 將其 OTLP/HTTP 匯出傳送到閘道，而不是本地設定的 `OTEL_EXPORTER_OTLP_ENDPOINT`，除非原則[將您的收集器命名為端點](/docs/zh-TW/claude-apps-gateway-config#export-directly-to-your-collector)。閘道將它接收的匯出轉發到 [`telemetry.forward_to`](/docs/zh-TW/claude-apps-gateway-config#telemetry) 中的目的地。492* **遙測目的地**：在透過 `/login` 登入的工作階段中，CLI 將其 OTLP/HTTP 匯出傳送到閘道，而不是本機設定的 `OTEL_EXPORTER_OTLP_ENDPOINT`，除非原則[將您的收集器指定為端點](/docs/zh-TW/claude-apps-gateway-config#export-directly-to-your-collector)。閘道將它接收的匯出轉發到 [`telemetry.forward_to`](/docs/zh-TW/claude-apps-gateway-config#telemetry) 中的目的地。

490 * 在[Claude Desktop 啟動](#connect-claude-desktop)的嵌入式會話中，CLI 將其匯出傳送到配置的 `OTEL_EXPORTER_OTLP_ENDPOINT`。CLI 僅當該端點指向閘道本身時才將閘道會話令牌附加到這些匯出。493 * 在 [Claude Desktop 啟動](#connect-claude-desktop)的嵌入式工作階段中，CLI 將其匯出傳送到設定的 `OTEL_EXPORTER_OTLP_ENDPOINT`。僅當該端點指向閘道本身時，CLI 才會將閘道工作階段 token 附加到這些匯出。

491 * 沒有為信號配置目的地時，閘道接受並丟棄它。494 * 當某個信號沒有設定目的地時，閘道會接受並丟棄它。

492 * 如果您已經直接收集 Claude Code 遙測，將您的收集器新增為 `forward_to` 目的地，或在原則中命名它以跳過轉發。495 * 如果您已經直接收集 Claude Code 遙測，請將您的收集器新增為 `forward_to` 目的地，或在原則中指定它以跳過轉發。

493* **認證**：閘道令牌是會話的唯一認證。[Anthropic 設定檔](/docs/zh-TW/authentication#anthropic-profiles-and-federation-credentials)和任何較早的 claude.ai 登入在登入時被忽略，因此開發人員不需要先登出 claude.ai。對於配置的 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 認證，請參閱[管理員原則要求雲端閘道登入](/docs/zh-TW/errors#administrator-policy-requires-a-cloud-gateway-sign-in)。496* **憑證**：閘道 token 是工作階段的唯一憑證。登入期間會忽略 [Anthropic 設定檔](/docs/zh-TW/authentication#anthropic-profiles-and-federation-credentials)和任何較早的 claude.ai 登入，因此開發人員不需要先登出 claude.ai。對於設定的 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 憑證，或由較早的 Claude Console 登入所儲存的 API 金鑰，請參閱[管理員原則要求雲端閘道登入](/docs/zh-TW/errors#administrator-policy-requires-a-cloud-gateway-sign-in)。

494* **受管設定**：鎖定的金鑰無法在本地覆蓋。CLI 在啟動時應用原則，並在每個每小時輪詢時應用變更，除了[僅在下次啟動時應用的變更](/docs/zh-TW/server-managed-settings#fetch-and-caching-behavior)。497* **受管設定**：鎖定的設定鍵無法在本機覆蓋。CLI 在啟動時套用原則，並在每小時輪詢時套用變更，但[僅在下次啟動時套用的變更](/docs/zh-TW/server-managed-settings#fetch-and-caching-behavior)除外。

495* **閘道無法到達時啟動**：已登入的會話在啟動時約 10 秒後以錯誤退出，而不是在沒有其設定的情況下啟動。498* **閘道無法到達時啟動**：已登入的工作階段會在啟動時約 10 秒後以錯誤結束，而不是在沒有其設定的情況下啟動。

496* **閘道結束會話後啟動**：請參閱[強制執行故障關閉啟動](/docs/zh-TW/server-managed-settings#enforce-fail-closed-startup)，了解哪些啟動在登出閘道的情況下開啟，哪些在閘道以 `401` 回答時退出。499* **閘道結束工作階段後啟動**：請參閱[強制執行故障關閉啟動](/docs/zh-TW/server-managed-settings#enforce-fail-closed-startup)，了解哪些啟動會在登出閘道的狀態下開啟，哪些會在閘道以 `401` 回應時結束。

497* **取消佈建**：其使用者在 IdP 中被禁用的會話在下一次刷新失敗時在 `ttl_hours` 內過期。500* **取消佈建**：使用者在 IdP 中被停用的工作階段，會在下一次重新整理失敗時於 `ttl_hours` 內過期。

498* **登出**：`/logout` 刪除開發人員機器上的閘道認證。501* **登出**：`/logout` 會刪除開發人員機器上的閘道憑證。

499 * 當閘道的探索文件在閘道 URL 的自己的配置、主機和連接埠上宣傳 `revocation_endpoint` 時，`/logout` 也將儲存的令牌傳送到該端點，以便閘道可以在其端結束會話。請求是盡力而為，因此登出在開發人員的機器上完成，無論端點是否回答。撤銷需要開發人員機器上的 Claude Code v2.1.275 或更新版本。502 * 當閘道的探索文件在與閘道 URL 相同的配置、主機和連接埠上公告 `revocation_endpoint` 時，`/logout` 也會將儲存的 token 傳送到該端點，以便閘道可以在其端結束工作階段。此請求為盡力而為，因此無論端點是否回應，登出都會在開發人員的機器上完成。撤銷需要開發人員機器上的 Claude Code v2.1.275 或更新版本。

500 * `claude` 二進位檔中的閘道伺服器不宣傳任何，因此從它登出僅在開發人員的機器上結束會話。若要強制會話在伺服器端退出，請參閱 [JWT 祕密輪換](/docs/zh-TW/claude-apps-gateway-deploy#jwt-secret-rotation)。503 * `claude` 二進位檔中的閘道伺服器不公告任何撤銷端點，因此從它登出僅會在開發人員的機器上結束工作階段。若要在伺服器端強制結束工作階段，請參閱 [JWT 祕密輪換](/docs/zh-TW/claude-apps-gateway-deploy#jwt-secret-rotation)。

501 504

502<h3 id="what-the-organization-can-see">505<h3 id="what-the-organization-can-see">

503 組織可以看到什麼506 組織可以看到什麼

504</h3>507</h3>

505 508

506使用情況遙測攜帶開發人員的身份、令牌計數、模型和延遲到組織的收集器。閘道不記錄或儲存提示或完成內容。是否收集更豐富的遙測（例如日誌和追蹤），可能包括命令和檔案路徑，是組織的[按目的地選擇](/docs/zh-TW/claude-apps-gateway-config#telemetry)。509使用情況遙測會將開發人員的身分、token 計數、模型和延遲傳送到組織的收集器。閘道不會記錄或儲存提示詞或完成內容。是否收集更豐富的遙測（例如日誌和追蹤，可能包括命令和檔案路徑），是組織的[按目的地選擇](/docs/zh-TW/claude-apps-gateway-config#telemetry)。

507 510

508<h2 id="availability-and-limitations">511<h2 id="availability-and-limitations">

509 可用性和限制512 可用性和限制

515 518

516| 功能 | 狀態 | 備註 |519| 功能 | 狀態 | 備註 |

517| - | - | - |520| - | - | - |

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

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

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

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

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

523| 按使用者和按群組支出限制 | 可用 | 請參閱[支出限制](/docs/zh-TW/claude-apps-gateway-spend-limits) |526| 按使用者和按群組支出限制 | 可用 | 請參閱[支出限制](/docs/zh-TW/claude-apps-gateway-spend-limits) |

524| 伺服器端網路搜尋 | 不可用 | CLI 無法看到閘道路由到的上游提供商，因此無法驗證網路搜尋支援並在閘道會話上禁用 WebSearch |527| 伺服器端網路搜尋 | 不可用 | CLI 無法看到閘道路由到的上游提供商，因此無法驗證網路搜尋支援並在閘道工作階段上禁用 WebSearch |

525| [Remote Control](/docs/zh-TW/remote-control) | 不可用 | CLI 顯示[命名閘道的錯誤](/docs/zh-TW/errors#remote-control-requires-the-anthropic-api) |528| [Remote Control](/docs/zh-TW/remote-control) | 不可用 | CLI 顯示[命名閘道的錯誤](/docs/zh-TW/errors#remote-control-requires-the-anthropic-api) |

526| [`/design-sync`](/docs/zh-TW/commands#all-commands) 和 `/design-login` | 不可用 | 兩者都需要 claude.ai，CLI 在閘道會話上不聯絡，因此兩個命令都不會出現 |529| [`/design-sync`](/docs/zh-TW/commands#all-commands) 和 `/design-login` | 不可用 | 兩者都需要 claude.ai，CLI 在閘道工作階段上不聯絡，因此兩個命令都不會出現 |

527| 需要功能旗標擷取的功能，例如 `/import` 和 `claude import` | 不可用 | CLI 在閘道會話上跳過旗標擷取。[需要功能旗標擷取的功能](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)列出關閉的內容 |530| 需要功能旗標擷取的功能，例如 `/import` 和 `claude import` | 不可用 | CLI 在閘道工作階段上跳過旗標擷取。[需要功能旗標擷取的功能](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)列出關閉的內容 |

528| 標準提示快取 | 可用 | 閘道將 `cache_control` 斷點轉發到每個上游。[快取位置](/docs/zh-TW/prompt-caching#where-the-cache-lives)涵蓋 CLI 標記的區塊，包括它在對話中途附加的系統內容 |531| 標準提示快取 | 可用 | 閘道將 `cache_control` 斷點轉發到每個上游。[快取位置](/docs/zh-TW/prompt-caching#where-the-cache-lives)涵蓋 CLI 標記的區塊，包括它在對話中途附加的系統內容 |

529| 1 小時快取 TTL | 不可用 | CLI 在閘道會話上省略擴展快取 TTL 測試版，因為並非閘道可以路由到的每個上游都支援 1 小時 TTL，因此透過閘道的提示快取使用 5 分鐘 TTL；請參閱上面的測試版標頭備註 |532| 1 小時快取 TTL | 不可用 | CLI 在閘道工作階段上省略擴展快取 TTL 測試版，因為並非閘道可以路由到的每個上游都支援 1 小時 TTL，因此透過閘道的提示快取使用 5 分鐘 TTL；請參閱上面的測試版標頭備註 |

530| 自動模式 | 可用 | 遵循[第三方提供商規則](/docs/zh-TW/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)：只有第三方提供商上符合條件的模型可以使用它。在 v2.1.207 之前，閘道會話上的自動模式需要設定 `CLAUDE_CODE_ENABLE_AUTO_MODE=1`，可透過受管原則 `env` 區塊傳遞 |533| 自動模式 | 可用 | 遵循[第三方提供商規則](/docs/zh-TW/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)：只有第三方提供商上符合條件的模型可以使用它。在 v2.1.207 之前，閘道工作階段上的自動模式需要設定 `CLAUDE_CODE_ENABLE_AUTO_MODE=1`，可透過受管原則 `env` 區塊傳遞 |

531| 僅限第一方的最佳化，例如全域快取範圍和令牌高效工具 | 不可用 | CLI 在閘道會話上不啟用它們；請參閱上面的測試版標頭備註 |534| 僅限第一方的最佳化，例如全域快取範圍和令牌高效工具 | 不可用 | CLI 在閘道工作階段上不啟用它們；請參閱上面的測試版標頭備註 |

532| OTLP/gRPC | 不支援 | 僅 OTLP over HTTP |535| OTLP/gRPC | 不支援 | 僅 OTLP over HTTP |

533| SAML、LDAP 和其他非 OIDC 身份驗證 | 不支援 | 僅 OIDC。如果需要，使用 OIDC 橋接 |536| SAML、LDAP 和其他非 OIDC 身份驗證 | 不支援 | 僅 OIDC。如果需要，使用 OIDC 橋接 |

534| 多租戶（多個 OIDC 發行者） | 不支援 | 每個閘道一個發行者。執行單獨的執行個體 |537| 多租戶（多個 OIDC 發行者） | 不支援 | 每個閘道一個發行者。執行單獨的執行個體 |

claude-apps-gateway-config.md +214 −140

Details

62| - | - | - |62| - | - | - |

63| `host` | 否 | 繫結位址。預設 `0.0.0.0`。 |63| `host` | 否 | 繫結位址。預設 `0.0.0.0`。 |

64| `port` | 否 | 繫結連接埠。預設 `8080`。 |64| `port` | 否 | 繫結連接埠。預設 `8080`。 |

65| `public_url` | 除非 `host` 是環回 | 外部可見的 `https://` 來源，用於建立 IdP `redirect_uri` 和發現中繼資料。在 `host` 不是環回位址時為必需，無論 TLS 是在代理（例如 ALB、Ingress 或 Cloud Run）還是在閘道本身透過 `tls` 終止，因為閘道永遠不會從 `X-Forwarded-*` 標頭衍生自己的來源；它們是使用者端可欺騙的。沒有它啟動會失敗。下面的 `trusted_proxies` 僅控制使用者端 IP 解析。啟用[遙測](#telemetry)時也是必需的，因為閘道從此 URL 建立它推送給使用者端的 OTLP 端點。 |65| `public_url` | 除非 `host` 是環回 | 外部可見的 `https://` 來源，用於建立 IdP `redirect_uri` 和發現中繼資料。在 `host` 不是環回位址時為必需，無論 TLS 是在代理伺服器（例如 ALB、Ingress 或 Cloud Run）還是在閘道本身透過 `tls` 終止，因為閘道永遠不會從 `X-Forwarded-*` 標頭衍生自己的來源；它們是用戶端可偽造的。沒有它啟動會失敗。下面的 `trusted_proxies` 僅控制用戶端 IP 解析。啟用[遙測](#telemetry)時也是必需的，因為閘道從此 URL 建立它推送給用戶端的 OTLP 端點。 |

66| `tls.cert` / `tls.key` | 否 | 如果閘道自己終止 TLS，則為 PEM 路徑 |66| `tls.cert` / `tls.key` | 否 | 如果閘道自己終止 TLS，則為 PEM 路徑 |

67| `trusted_proxies` | 否 | 閘道前面的負載平衡器的 CIDR 或 IP。設定時，閘道僅信任來自這些對等方的 `X-Forwarded-For`，並記錄真實使用者端 IP 以進行每 IP 速率限制和稽核。等同於 nginx `set_real_ip_from`。`X-Forwarded-For` 項目寫成 `ipv4:port` 或 `[ipv6]:port`（如某些負載平衡器所做），會以連接埠被刪除的方式讀取。附加連接埠且沒有括號的 IPv6 位址可能被讀取為不同位址或根本不被讀取，因此在任何寫入該形式的代理上關閉連接埠選項。 |67| `trusted_proxies` | 否 | 閘道前面的負載平衡器的 CIDR 或 IP。設定時，閘道僅信任來自這些對等方的 `X-Forwarded-For`，並記錄真實用戶端 IP 以進行每 IP 速率限制和稽核。等同於 nginx `set_real_ip_from`。`X-Forwarded-For` 項目寫成 `ipv4:port` 或 `[ipv6]:port`（如某些負載平衡器所做），會以連接埠被刪除的方式讀取。附加連接埠且沒有括號的 IPv6 位址可能被讀取為不同位址或根本不被讀取，因此在任何寫入該形式的代理伺服器上關閉連接埠選項。 |

68 68

69<h3 id="oidc">69<h3 id="oidc">

70 `oidc`70 `oidc`

83| `allowed_groups` | 否 | 限制登入為這些 IdP 群組的成員，與 `groups_claim` 相符。允許電子郵件網域中但不在這些群組中的使用者被拒絕。需要 IdP 發出群組宣告。匹配是針對該宣告中值的精確、區分大小寫的字串比較，閘道不展開嵌套群組：若要允許子群組的成員，請在此列出子群組或設定 IdP 以發出扁平化成員資格。 |83| `allowed_groups` | 否 | 限制登入為這些 IdP 群組的成員，與 `groups_claim` 相符。允許電子郵件網域中但不在這些群組中的使用者被拒絕。需要 IdP 發出群組宣告。匹配是針對該宣告中值的精確、區分大小寫的字串比較，閘道不展開嵌套群組：若要允許子群組的成員，請在此列出子群組或設定 IdP 以發出扁平化成員資格。 |

84| `groups_claim` | 否 | 哪個 id\_token 宣告攜帶群組成員資格。預設 `groups`。Microsoft Entra 在 `roles` 下發出應用程式角色。接受平面鍵或 RFC 6901 JSON 指標，例如 `/resource_access/gateway/roles` 用於嵌套宣告。 |84| `groups_claim` | 否 | 哪個 id\_token 宣告攜帶群組成員資格。預設 `groups`。Microsoft Entra 在 `roles` 下發出應用程式角色。接受平面鍵或 RFC 6901 JSON 指標，例如 `/resource_access/gateway/roles` 用於嵌套宣告。 |

85| `google_groups` | 否 | 透過 Google Workspace Admin SDK Directory API 查詢已登入使用者的群組，因為 Google 的 id\_token 不攜帶群組宣告。將 `service_account_json_path` 設定為具有 `https://www.googleapis.com/auth/admin.directory.group.readonly` 範圍的網域範圍委派的服務帳戶金鑰檔案，並將 `admin_email` 設定為服務帳戶模擬的 Workspace 管理員；Directory API 需要真實的管理員主體。每個使用者的群組電子郵件地址成為其群組宣告，因此 `allowed_groups` 和 `managed.policies.match.groups` 與群組電子郵件相符。 |85| `google_groups` | 否 | 透過 Google Workspace Admin SDK Directory API 查詢已登入使用者的群組，因為 Google 的 id\_token 不攜帶群組宣告。將 `service_account_json_path` 設定為具有 `https://www.googleapis.com/auth/admin.directory.group.readonly` 範圍的網域範圍委派的服務帳戶金鑰檔案，並將 `admin_email` 設定為服務帳戶模擬的 Workspace 管理員；Directory API 需要真實的管理員主體。每個使用者的群組電子郵件地址成為其群組宣告，因此 `allowed_groups` 和 `managed.policies.match.groups` 與群組電子郵件相符。 |

86| `email_claim` | 否 | 哪個 id\_token 宣告攜帶使用者的電子郵件。預設 `email`。某些 IdP（例如 ADFS 和 Entra B2C）改為發出 `upn` 或 `preferred_username`。接受平面鍵、JSON 指標或後備鍵清單，其中使用第一個存在的鍵。 |86| `email_claim` | 否 | 哪個 id\_token 宣告攜帶使用者的電子郵件。預設 `email`。某些 IdP（例如 ADFS 和 Entra B2C）改為發出 `upn` 或 `preferred_username`。接受平面鍵、JSON 指標或備援鍵清單，其中使用第一個存在的鍵。 |

87| `scopes` | 否 | 閘道請求的 OIDC 範圍的完整覆蓋。預設 `[openid, profile, email, offline_access]`。當您的 IdP 拒絕它不識別的範圍或需要自訂範圍來發出群組或電子郵件時設定。必須包含 `openid`。刪除 `offline_access` 會停用重新整理令牌，因此開發人員每 `session.ttl_hours` 重新執行瀏覽器登入。請參閱[身分識別提供者設定](/docs/zh-TW/claude-apps-gateway-deploy#identity-provider-setup)以了解每個 IdP 範圍配方，例如 Google 的重新整理令牌流程。 |87| `scopes` | 否 | 完整覆寫閘道請求的 OIDC 範圍。預設 `[openid, profile, email, offline_access]`。當您的 IdP 拒絕它不識別的範圍或需要自訂範圍來發出群組或電子郵件時設定。必須包含 `openid`。刪除 `offline_access` 會停用重新整理 token，因此開發人員每 `session.ttl_hours` 重新執行瀏覽器登入。請參閱[身分識別提供者設定](/docs/zh-TW/claude-apps-gateway-deploy#identity-provider-setup)以了解每個 IdP 範圍配方，例如 Google 的重新整理 token 流程。 |

88| `scope_on_refresh` | 否 | 當閘道交換重新整理令牌時，也傳送 `scope`，具有與登入請求相同的清單。預設 `false`：重新整理請求省略 `scope`。大多數 IdP 在每次重新整理時返回 id\_token，不需要這個。當您的 IdP 僅在再次要求 `openid` 時才在重新整理時返回 id\_token 時設定 `true`，Okta 為其重新整理授權記錄了這一點。沒有 id\_token，每次重新整理都取決於 IdP 的 userinfo 端點接受重新整理的存取令牌。如果您在登入或匹配原則上閘控群組，且您的 IdP 的重新整理時間 id\_token 省略它們，也設定 `userinfo_fallback: true`，以便閘道從 userinfo 端點填補它們。授予的範圍少於請求的 IdP 可以使用 `invalid_scope` 拒絕重新整理，包括現有工作階段（如果您在此開啟時將項目新增到 `scopes`）。如果在設定後重新整理開始在 `token_endpoint` 失敗，請取消設定金鑰。需要閘道伺服器上的 Claude Code v2.1.260 或更新版本。 |88| `scope_on_refresh` | 否 | 當閘道交換重新整理 token 時，也傳送 `scope`，具有與登入請求相同的清單。預設 `false`：重新整理請求省略 `scope`。大多數 IdP 在每次重新整理時返回 id\_token，不需要這個。當您的 IdP 僅在再次請求 `openid` 時才在重新整理時返回 id\_token 時設定 `true`，Okta 為其重新整理授權記錄了這一點。沒有 id\_token，每次重新整理都取決於 IdP 的 userinfo 端點接受重新整理的存取 token。如果您在登入或匹配原則上閘控群組，且您的 IdP 的重新整理時間 id\_token 省略它們，也設定 `userinfo_fallback: true`，以便閘道從 userinfo 端點填補它們。授予的範圍少於請求的 IdP 可以使用 `invalid_scope` 拒絕重新整理，包括現有工作階段（如果您在此開啟時將項目新增到 `scopes`）。如果在設定後重新整理開始在 `token_endpoint` 失敗，請取消設定此鍵。需要閘道伺服器上的 Claude Code v2.1.260 或更新版本。 |

89| `extra_auth_params` | 否 | 附加到 IdP 授權請求的額外查詢參數，逐字。這是 IdP 特定行為的覆蓋機制，例如 Google 重新整理令牌的 `access_type: offline`、某些 Entra 租戶的 `domain_hint` 或逐步提升流程的 `acr_values`。無法覆蓋閘道管理的協定參數：`state`、`nonce`、`redirect_uri`、PKCE、`scope`、`response_type`、`response_mode` 和 `client_id`。 |89| `extra_auth_params` | 否 | 附加到 IdP 授權請求的額外查詢參數，逐字。這是 IdP 特定行為的覆寫機制，例如 Google 重新整理 token 的 `access_type: offline`、某些 Entra 租戶的 `domain_hint` 或逐步提升流程的 `acr_values`。無法覆寫閘道管理的協定參數：`state`、`nonce`、`redirect_uri`、PKCE、`scope`、`response_type`、`response_mode` 和 `client_id`。 |

90| `userinfo_fallback` | 否 | 當 id\_token 省略電子郵件或群組時，從 `/userinfo` 擷取它們。Keycloak 輕量級存取令牌、Okta 組織伺服器和 ADFS 最小令牌需要。id\_token 保持權威；userinfo 僅填補空白。預設 `false`。 |90| `userinfo_fallback` | 否 | 當 id\_token 省略電子郵件或群組時，從 `/userinfo` 擷取它們。Keycloak 輕量級存取 token、Okta 組織伺服器和 ADFS 最小 token 需要。id\_token 保持權威；userinfo 僅填補空白。預設 `false`。 |

91| `use_pkce` | 否 | 在授權請求上傳送 PKCE (S256) 挑戰。預設 `true`。僅當您的 IdP 為此機密用戶端拒絕 PKCE 時設定 `false`。 |91| `use_pkce` | 否 | 在授權請求上傳送 PKCE (S256) 挑戰。預設 `true`。僅當您的 IdP 為此機密用戶端拒絕 PKCE 時設定 `false`。 |

92| `clock_skew_seconds` | 否 | 驗證 id\_token 時間宣告時容許時鐘漂移。預設 `0`，這是嚴格的。如果您在登入後立即看到「令牌已過期/尚未有效」錯誤，請提高以應對主機/IdP 時鐘偏差。 |92| `clock_skew_seconds` | 否 | 驗證 id\_token 時間宣告時容許時鐘漂移。預設 `0`，這是嚴格的。如果您在登入後立即看到「token 已過期/尚未有效」錯誤，請提高以應對主機/IdP 時鐘偏差。 |

93| `token_endpoint_auth_method` | 否 | 閘道向 IdP 的 token 端點進行身分驗證的方式：`client_secret_basic`、`client_secret_post`，或用於[憑證用戶端身分驗證](#certificate-client-authentication)的 `private_key_jwt`。預設情況下，閘道會根據 IdP 公告的內容，從兩種 `client_secret` 方法中選擇一種。 |93| `token_endpoint_auth_method` | 否 | 閘道向 IdP 的 token 端點進行身分驗證的方式：`client_secret_basic`、`client_secret_post`，或用於[憑證用戶端身分驗證](#certificate-client-authentication)的 `private_key_jwt`。預設情況下，閘道會根據 IdP 公告的內容，從兩種 `client_secret` 方法中選擇一種。 |

95| `id_token_signed_response_alg` | 否 | 預期的 id\_token 簽署演算法。預設 `RS256`。為使用 ES256、PS256 或 EdDSA 簽署的 IdP 設定。 |95| `id_token_signed_response_alg` | 否 | 預期的 id\_token 簽署演算法。預設 `RS256`。為使用 ES256、PS256 或 EdDSA 簽署的 IdP 設定。 |

~~96| `additional_authorized_parties` | 否 | 除了 `client_id` 之外要接受的額外 `azp` 值，用於 Keycloak 代理和令牌交換流程 |~~96| `additional_authorized_parties` | 否 | 除了 `client_id` 之外要接受的額外 `azp` 值，用於 Keycloak 仲介和 token 交換流程 |

~~97| `discovery_url` | 否 | 從此 URL 擷取發現文件，而不是從 `issuer` 衍生，用於代理後面重寫簽發者主機的 IdP。路徑必須包含 `/.well-known/`。 |~~97| `discovery_url` | 否 | 從此 URL 擷取發現文件，而不是從 `issuer` 衍生，用於位於重寫簽發者主機的代理伺服器後面的 IdP。路徑必須包含 `/.well-known/`。 |

98| `use_proxy` | 否 | 透過 `HTTPS_PROXY` 或 `HTTP_PROXY` 中的轉發代理傳送閘道自己的 IdP 請求，遵守 `NO_PROXY`。`false` 保持這些請求直接。需要 v2.1.227 或更新版本；請參閱下面的[透過轉發代理的 IdP 請求](#idp-requests-through-a-forward-proxy)。 |98| `use_proxy` | 否 | 透過 `HTTPS_PROXY` 或 `HTTP_PROXY` 中的轉發代理伺服器傳送閘道自己的 IdP 請求，遵守 `NO_PROXY`。`false` 保持這些請求直接。需要 v2.1.227 或更新版本；請參閱下面的[透過轉發代理伺服器的 IdP 請求](#idp-requests-through-a-forward-proxy)。 |

99| `form_action_origins` | 否 | `/device` 頁面的 `Content-Security-Policy: form-action` 指令的其他來源。閘道已允許 `'self'` 和發現的 `authorization_endpoint` 來源，但 Chrome 對整個重新導向鏈強制執行 `form-action`。如果您的 IdP 透過第二個主機重新導向，例如 Azure AD 聯合到 ADFS、中樞輪輻 Okta 或公司 SSO 攔截器，列出授權請求可能重新導向的每個來源。 |99| `form_action_origins` | 否 | `/device` 頁面的 `Content-Security-Policy: form-action` 指令的其他來源。閘道已允許 `'self'` 和發現的 `authorization_endpoint` 來源，但 Chrome 對整個重新導向鏈強制執行 `form-action`。如果您的 IdP 透過第二個主機重新導向，例如 Azure AD 聯合到 ADFS、中樞輪輻 Okta 或公司 SSO 攔截器，列出授權請求可能重新導向的每個來源。 |

100| `ca_cert_pem` | 否 | PEM 編碼的 CA 憑證本身，而不是檔案的路徑。它替換 IdP 請求的系統信任存放區。若要載入掛載的檔案，請寫入 `${file:/etc/gateway/idp-ca.pem}`。用於公司 PKI 後面的 Keycloak 或 Dex。 |100| `ca_cert_pem` | 否 | PEM 編碼的 CA 憑證本身，而不是檔案的路徑。它僅替換 IdP 請求的系統信任存放區。若要載入掛載的檔案，請寫入 `${file:/etc/gateway/idp-ca.pem}`。用於公司 PKI 後面的 Keycloak 或 Dex。 |

101 101

102<h4 id="certificate-client-authentication">102<h4 id="certificate-client-authentication">

103 憑證用戶端身分驗證103 憑證用戶端身分驗證

104</h4>104</h4>

105 105

106如果您的身分識別提供者使用憑證而非用戶端密碼來驗證 OAuth 用戶端（如 Microsoft Entra 使用憑證認證的方式），請設定 `token_endpoint_auth_method: private_key_jwt`。需要閘道伺服器上的 Claude Code v2.1.284 或更新版本。106如果您的身分識別提供者使用憑證而非用戶端密碼來驗證 OAuth 用戶端（如 Microsoft Entra 使用憑證的方式），請設定 `token_endpoint_auth_method: private_key_jwt`。需要閘道伺服器上的 Claude Code v2.1.284 或更新版本。

107 107

108使用此設定時，閘道不會傳送任何密碼。當開發人員登入時，以及每次閘道重新整理其工作階段時，閘道都會使用以憑證私密金鑰簽署的短期 JWT 向 IdP 的 token 端點進行身分驗證。該 JWT 以 RS256 簽署，並透過 `x5t` 和 `x5t#S256` 指紋標頭（而非 `kid`）識別憑證。您的 IdP 必須能夠依指紋找到已註冊的憑證。108使用此設定時，閘道不會傳送任何密碼。當開發人員登入時，以及每次閘道重新整理其工作階段時，閘道都會使用以憑證私密金鑰簽署的短期 JWT 向 IdP 的 token 端點進行身分驗證。該 JWT 以 RS256 簽署，並透過 `x5t` 和 `x5t#S256` 指紋標頭（而非 `kid`）識別憑證。您的 IdP 必須能夠依指紋找到已註冊的憑證。

109 109

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 請求

164</h4>164</h4>

165 165

166推論上游在每個版本上都遵守 `HTTPS_PROXY` 和 `HTTP_PROXY`。閘道自己對 IdP、發現、JWKS、令牌和 userinfo 的請求直接進行，除非您設定 `oidc.use_proxy: true`，這需要 v2.1.227 或更新版本。當代理變數被設定、`use_proxy` 未設定且簽發者未被 `NO_PROXY` 涵蓋時，閘道保持這些請求直接並在啟動時記錄通知，要求您選擇；`use_proxy: false` 保持它們直接並沉默通知。166推論上游在每個版本上都遵守 `HTTPS_PROXY` 和 `HTTP_PROXY`。閘道自己對 IdP 的請求（發現、JWKS、token 和 userinfo）直接進行，除非您設定 `oidc.use_proxy: true`，這需要 v2.1.227 或更新版本。當代理伺服器變數被設定、`use_proxy` 未設定且簽發者未被 `NO_PROXY` 涵蓋時，閘道保持這些請求直接並在啟動時記錄通知，請您做出選擇；`use_proxy: false` 保持它們直接並隱藏通知。

167 167

168使用 `use_proxy: true`，Pod 自己解析每個 IdP 端點的主機名稱，並要求代理 `CONNECT` 到解析的 IP 位址，因此代理必須接受 `CONNECT` 到發現文件命名的每個主機的 IP 位址，而不僅僅是簽發者。使用 `http://` 代理 URL。`ca_cert_pem` 和[SSRF 防護](/docs/zh-TW/claude-apps-gateway-deploy#threat-model-summary)也適用於代理路徑。168使用 `use_proxy: true` 時，Pod 自己解析每個 IdP 端點的主機名稱，並請代理伺服器 `CONNECT` 到解析的 IP 位址，因此代理伺服器必須接受 `CONNECT` 到發現文件命名的每個主機的 IP 位址，而不僅僅是簽發者。使用 `http://` 代理伺服器 URL。`ca_cert_pem` 和[SSRF 防護](/docs/zh-TW/claude-apps-gateway-deploy#threat-model-summary)也適用於經代理伺服器的路徑。

169 169

170[Proxy-only egress](#proxy-only-egress) 改變這兩者：當它處於活動狀態時，IdP 請求遵循代理，除非您設定 `use_proxy: false`，閘道將每個 IdP 主機名稱交給代理，而不先解析它。170[Proxy-only egress](#proxy-only-egress) 改變這兩者：當它處於活動狀態時，IdP 請求遵循代理伺服器，除非您設定 `use_proxy: false`，且閘道將每個 IdP 主機名稱交給代理伺服器，而不先解析它。

171 171

172<h4 id="proxy-only-egress">172<h4 id="proxy-only-egress">

173 Proxy-only egress173 Proxy-only egress

174</h4>174</h4>

175 175

176在閘道的環境中設定 `CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1`，在 `HTTPS_PROXY` 旁邊，當 Pod 僅透過該轉發代理到達其他主機且無法自己解析公開 DNS 名稱時，或當代理拒絕 `CONNECT` 到 IP 位址時。需要 v2.1.277 或更新版本。它是環境變數而不是 `gateway.yaml` 金鑰，因此設定檔中的任何內容都無法放鬆閘道的位址檢查。176當 Pod 僅透過該轉發代理伺服器到達其他主機且無法自己解析公開 DNS 名稱時，或當代理伺服器拒絕 `CONNECT` 到 IP 位址時，在閘道的環境中於 `HTTPS_PROXY` 旁邊設定 `CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1`。需要 v2.1.277 或更新版本。它是環境變數而不是 `gateway.yaml` 設定鍵，因此設定檔中的任何內容都無法放寬閘道的位址檢查。

177 177

178```bash theme={null}178```bash theme={null}

179export HTTPS_PROXY=http://proxy.corp.example.com:3128179export HTTPS_PROXY=http://proxy.corp.example.com:3128

184 184

185當 proxy-only egress 處於活動狀態時，閘道在啟動時記錄一個 `network:` 行。185當 proxy-only egress 處於活動狀態時，閘道在啟動時記錄一個 `network:` 行。

186 186

187下面的每一行是設定了 `HTTPS_PROXY` 的閘道上一類出站請求，預設情況下和 proxy-only egress 處於活動狀態時。187下面的每一列是設定了 `HTTPS_PROXY` 的閘道上一類出站請求，分別列出預設情況下和 proxy-only egress 處於活動狀態時的行為。

188 188

189| 出站請求 | 預設 | Proxy-only egress 處於活動狀態 |189| 出站請求 | 預設 | Proxy-only egress 處於活動狀態 |

190| - | - | - |190| - | - | - |

191| `provider: anthropic` 上游、Workload Identity Federation 令牌交換、`telemetry.forward_to` 匯出 | 在本地解析和檢查，然後透過代理 `CONNECT` 到檢查的 IP 位址。列在 `NO_PROXY` 中的遙測收集器改為直接到達 | 主機名稱交給代理 |191| `provider: anthropic` 上游、Workload Identity Federation token 交換、`telemetry.forward_to` 匯出 | 在本地解析和檢查，然後透過代理伺服器 `CONNECT` 到檢查的 IP 位址。列在 `NO_PROXY` 中的遙測收集器改為直接到達 | 主機名稱交給代理伺服器 |

192| IdP 發現、JWKS、令牌和 userinfo | 直接，除非 [`oidc.use_proxy: true`](#idp-requests-through-a-forward-proxy)，然後 `CONNECT` 到檢查的 IP 位址 | 主機名稱交給代理，除非 `oidc.use_proxy: false` 保持內部 IdP 直接 |192| IdP 發現、JWKS、token 和 userinfo | 直接，除非 [`oidc.use_proxy: true`](#idp-requests-through-a-forward-proxy)，然後 `CONNECT` 到檢查的 IP 位址 | 主機名稱交給代理伺服器，除非 `oidc.use_proxy: false` 保持內部 IdP 直接 |

193| Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上游；Google 群組查詢 | 主機名稱交給代理 | 未更改 |193| Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上游；Google 群組查詢 | 主機名稱交給代理伺服器 | 未更改 |

194 194

195Proxy-only egress 保持關閉，除非閘道的環境滿足所有這三個條件：195Proxy-only egress 保持關閉，除非閘道的環境滿足所有這三個條件：

196 196

197* `HTTPS_PROXY` 或 `HTTP_PROXY` 被設定。197* `HTTPS_PROXY` 或 `HTTP_PROXY` 被設定。

198* `NO_PROXY` 和 `no_proxy` 為空。如果您的平台將任一個注入 Pod，在閘道容器上將兩者設定為空值。在 `NO_PROXY` 中列出遙測收集器保持 proxy-only egress 關閉。198* `NO_PROXY` 和 `no_proxy` 為空。如果您的平台將任一個注入 Pod，在閘道容器上將兩者設定為空值。在 `NO_PROXY` 中列出遙測收集器會使 proxy-only egress 保持關閉。

199* `CLAUDE_GATEWAY_ALLOW_LOOPBACK` 未開啟。Pod 自己環回上的收集器或 IdP 無法與 proxy-only egress 結合，因為交給代理的環回位址將是代理主機自己的，因此給這些服務一個代理可以到達的位址。出於相同原因，當 proxy-only egress 處於活動狀態時，閘道完全拒絕 `localhost` 風格的名稱。199* `CLAUDE_GATEWAY_ALLOW_LOOPBACK` 未開啟。Pod 自己環回上的收集器或 IdP 無法與 proxy-only egress 結合，因為交給代理伺服器的環回位址將是代理伺服器主機自己的，因此請改為給這些服務一個代理伺服器可以到達的位址。出於相同原因，當 proxy-only egress 處於活動狀態時，閘道完全拒絕 `localhost` 風格的名稱。

200 200

201當其中一個條件未滿足時，閘道在啟動時記錄警告，命名停止它的變數，並保持預設行為。201當其中一個條件未滿足時，閘道在啟動時記錄警告，命名阻止它的變數，並保持預設行為。

202 202

203一旦 proxy-only egress 處於活動狀態，允許代理中的每個目的地，包括內部收集器和任何由 IP 位址設定的主機。您仍然可以使用 [`oidc.use_proxy: false`](#idp-requests-through-a-forward-proxy) 保持內部 IdP 直接。203一旦 proxy-only egress 處於活動狀態，請在代理伺服器中允許每個目的地，包括內部收集器和任何由 IP 位址設定的主機。您仍然可以使用 [`oidc.use_proxy: false`](#idp-requests-through-a-forward-proxy) 保持內部 IdP 直接。

204 204

205<Warning>205<Warning>

206 僅當代理的允許清單至少與閘道自己的檢查一樣嚴格時才開啟此功能。代理必須拒絕雲中繼資料端點，例如 `169.254.169.254` 和 `metadata.google.internal`、連結本地位址和代理主機自己的環回，並且必須按名稱解析到的位址拒絕它們，而不僅僅是按名稱，因為閘道不再捕捉解析到其中之一的主機名稱。連接到被要求的任何地方的代理會移除閘道對這些請求的[SSRF 防護](/docs/zh-TW/claude-apps-gateway-deploy#threat-model-summary)。206 僅當代理伺服器的允許清單至少與閘道自己的檢查一樣嚴格時才開啟此功能。代理伺服器必須拒絕雲中繼資料端點（例如 `169.254.169.254` 和 `metadata.google.internal`）、連結本地位址和代理伺服器主機自己的環回，並且必須按名稱解析到的位址拒絕它們，而不僅僅是按名稱，因為閘道不再攔截解析到其中之一的主機名稱。連接到任何被要求之處的代理伺服器會移除閘道對這些請求的[SSRF 防護](/docs/zh-TW/claude-apps-gateway-deploy#threat-model-summary)。

207</Warning>207</Warning>

208 208

209<h3 id="session">209<h3 id="session">

210 `session`210 `session`

211</h3>211</h3>

212 212

213`session` 區塊塑造閘道在登入後鑄造的持有人令牌：簽署它們的祕密和它們的生命週期。213`session` 區塊塑造閘道在登入後鑄造的持有人 token：簽署它們的祕密和它們的生命週期。

214 214

215| 欄位 | 必需 | 說明 |215| 欄位 | 必需 | 說明 |

216| - | - | - |216| - | - | - |

217| `jwt_secret` | 是 | 至少 32 位元組的熵，例如來自 `openssl rand -base64 32`。簽署閘道的 HS256 持有人令牌。接受單一字串或用於輪換的陣列：索引 0 簽署，所有項目驗證。若要輪換，前置新祕密，等待 `ttl_hours`，然後刪除舊祕密。 |217| `jwt_secret` | 是 | 至少 32 位元組的熵，例如來自 `openssl rand -base64 32`。簽署閘道的 HS256 持有人 token。接受單一字串或用於輪換的陣列：索引 0 簽署，所有項目驗證。若要輪換，前置新祕密，等待 `ttl_hours`，然後刪除舊祕密。 |

218| `ttl_hours` | 否 | 閘道持有人令牌生命週期。預設 `1`。當 IdP 發出重新整理令牌時，CLI 在過期前無聲地重新整理。較短的生命週期會更快地取消佈建；較長的生命週期會減少 IdP 往返次數。如果您的 IdP 因為 `offline_access` 不可用而無法發出重新整理令牌，則沒有無聲重新整理，因此將其提高到 `8` 或 `12` 以避免每小時將開發人員送回瀏覽器登入。 |218| `ttl_hours` | 否 | 閘道持有人 token 生命週期。預設 `1`。當 IdP 發出重新整理 token 時，CLI 在過期前無聲地重新整理。較短的生命週期會更快地取消佈建；較長的生命週期會減少 IdP 往返次數。如果您的 IdP 因為 `offline_access` 不可用而無法發出重新整理 token，則沒有無聲重新整理，因此將其提高到 `8` 或 `12` 以避免每小時將開發人員送回瀏覽器登入。 |

219 219

220<h3 id="store">220<h3 id="store">

221 `store`221 `store`

225 225

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

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

228| `postgres_url` | 是 | `postgres://` 或 `postgresql://` URL。必需：裝置授權會合點，瀏覽器回呼寫入且輪詢 CLI 讀取，需要跨副本狀態。閘道在啟動時執行自己的架構遷移，並在升級時執行，因此角色需要在目標架構上建立和更改表的權限。請參閱[升級](/docs/zh-TW/claude-apps-gateway-deploy#upgrades)和 [Postgres](/docs/zh-TW/claude-apps-gateway-deploy#postgres)。 |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)。 |

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

232| `connect_timeout_seconds` | 否 | 閘道開啟 Postgres 連線時等待的秒數。從 `1` 到 `60` 的整數，預設 `5`。如果新閘道執行個體啟動時連線嘗試逾時，請提高它。需要閘道伺服器上的 Claude Code v2.1.274 或更新版本。較早的版本在設定金鑰時拒絕啟動。 |232| `connect_timeout_seconds` | 否 | 閘道開啟 Postgres 連線時等待的秒數。從 `1` 到 `60` 的整數，預設 `5`。如果新閘道執行個體啟動時連線嘗試逾時，請提高它。需要閘道伺服器上的 Claude Code v2.1.274 或更新版本。較早的版本在設定此鍵時拒絕啟動。 |

233| `readiness_grace_seconds` | 否 | Postgres 停止回答後 `/readyz` 保持報告就緒的秒數。從 `0` 到 `3600` 的整數，預設 `0`。請參閱[中斷行為](/docs/zh-TW/claude-apps-gateway-deploy#outage-behavior)以了解如何選擇值。需要閘道伺服器上的 Claude Code v2.1.282 或更新版本。較早的版本在設定金鑰時拒絕啟動。 |233| `readiness_grace_seconds` | 否 | Postgres 停止回答後 `/readyz` 保持報告就緒的秒數。從 `0` 到 `3600` 的整數，預設 `0`。請參閱[中斷行為](/docs/zh-TW/claude-apps-gateway-deploy#outage-behavior)以了解如何選擇值。需要閘道伺服器上的 Claude Code v2.1.282 或更新版本。較早的版本在設定此鍵時拒絕啟動。 |

234 234

235對於本地開發，將 `postgres_url` 指向一次性 Postgres 容器，例如 `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`。235對於本地開發，將 `postgres_url` 指向一次性 Postgres 容器，例如 `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`。

236 236

240 240

241`upstreams` 是一個有序清單。閘道將推論轉發到解析所請求模型的第一個上游。241`upstreams` 是一個有序清單。閘道將推論轉發到解析所請求模型的第一個上游。

242 242

243在 `5xx`、`429`、`401`、`403`、`404` 或逾時時，它會故障轉移到下一個；其他 `4xx` 不會，因為這些錯誤可歸因於請求而不是上游。`401` 或 `403` 表示閘道自己的認證對該上游失敗。`404` 表示該上游不服務所請求的模型，因此清單中稍後的上游仍然可以。243在 `5xx`、`429`、`401`、`403`、`404` 或逾時時，閘道會故障轉移到下一個上游；其他 `4xx` 不會，因為這些錯誤可歸因於請求而不是上游。`401` 或 `403` 表示上游拒絕了閘道使用的憑證，或拒絕其存取，例如存取所請求的模型。`404` 表示該上游不服務所請求的模型，因此清單中稍後的上游仍然可以。

244 244

245如果您在上游上設定 `forward_user_identity: true`，它返回給攜帶開發人員電子郵件的請求的 `429` 不會故障轉移。請參閱[每個使用者限制拒絕如何到達開發人員](#per-user-identity-headers-for-a-proxy-you-run)。245如果您在上游上設定 `forward_user_identity: true`，它返回給攜帶開發人員電子郵件的請求的 `429` 不會故障轉移。請參閱[每個使用者限制拒絕如何到達開發人員](#per-user-identity-headers-for-a-proxy-you-run)。

246 246

247故障轉移於 `404` 需要閘道 v2.1.198 或更新版本。較早的版本即使清單中稍後的上游服務該模型，也會將第一個 `404` 返回給使用者端。247在 `404` 時故障轉移需要閘道 v2.1.198 或更新版本。較早的版本即使清單中稍後的上游服務該模型，也會將第一個 `404` 返回給用戶端。

248 248

249相同提供者的多個上游必須設定不同的 `name:`。249相同提供者的多個上游必須設定不同的 `name:`。

250 250

251Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 和 Microsoft Foundry 用戶端在啟動時建立一次，其 SDK 在內部重新整理認證，因此輪換雲認證不需要重新啟動。靜態 Anthropic API 金鑰和持有人在啟動時讀取；請參閱 [Anthropic API](#anthropic-api)。251Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 和 Microsoft Foundry 用戶端在啟動時建立一次，其 SDK 在內部重新整理憑證，因此輪換雲憑證不需要重新啟動。靜態 Anthropic API 金鑰和持有人 token 在啟動時讀取；請參閱 [Anthropic API](#anthropic-api)。

252 252

253<h4 id="upstream-error-messages">253<h4 id="upstream-error-messages">

254 上游錯誤訊息254 上游錯誤訊息

257閘道返回一個上游的錯誤回應，或其自己的 `502`，取決於上游如何回答：257閘道返回一個上游的錯誤回應，或其自己的 `502`，取決於上游如何回答：

258 258

259* **上游返回閘道不[故障轉移](#multiple-upstreams)的狀態**：該上游的回應。閘道不嘗試進一步的上游。259* **上游返回閘道不[故障轉移](#multiple-upstreams)的狀態**：該上游的回應。閘道不嘗試進一步的上游。

260* **閘道嘗試的每個上游都以閘道[故障轉移](#multiple-upstreams)的方式失敗**：最後一個 `429`。當沒有返回 `429` 時，閘道優先選擇，按順序，最後一個 `401` 或 `403`、最後一個 `404` 和最後一個 `501`。當沒有返回任何這些時，閘道自己的 `502`，`all upstreams failed (N attempted)`，其中 N 計算 [`upstreams`](#upstreams) 中的每個項目，包括閘道跳過的項目，因為它們不服務所請求的模型。260* **閘道嘗試的每個上游都以閘道[故障轉移](#multiple-upstreams)的方式失敗**：最後一個 `429`。當沒有返回 `429` 時，閘道依序優先選擇最後一個 `401` 或 `403`、最後一個 `404` 和最後一個 `501`。當沒有返回任何這些時，則為閘道自己的 `502`，`all upstreams failed (N attempted)`，其中 N 計算 [`upstreams`](#upstreams) 中的每個項目，包括閘道因不服務所請求模型而跳過的項目。

261 261

262當閘道返回上游的回應時，它保持上游的狀態碼。它是否保持上游的訊息取決於提供者。Anthropic API 上游的錯誤正文未更改地到達開發人員。262當閘道返回上游的回應時，它保持上游的狀態碼。它是否保持上游的訊息取決於提供者。Anthropic API 上游的錯誤正文未經更改地到達開發人員。

263 263

264Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上游可以在其錯誤文字中命名您的帳戶 ID、角色 ARN 和專案 ID。閘道在[操作日誌](/docs/zh-TW/claude-apps-gateway-deploy#logs)中記錄該完整文字。開發人員從這些上游看到的內容取決於拒絕：264Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上游可能在其錯誤文字中命名您的帳戶 ID、角色 ARN 和專案 ID。閘道在[操作日誌](/docs/zh-TW/claude-apps-gateway-deploy#logs)中記錄該完整文字。開發人員從這些上游看到的內容取決於拒絕：

265 265

266* Anthropic 標準錯誤信封中的 `400` 或 `413`：上游自己的訊息，例如 `prompt is too long`。Claude Platform on AWS、Agent Platform 和 Microsoft Foundry 為模型 API 拒絕返回此信封。266* Anthropic 標準錯誤信封中的 `400` 或 `413`：上游自己的訊息，例如 `prompt is too long`。Claude Platform on AWS、Agent Platform 和 Microsoft Foundry 為模型 API 拒絕返回此信封。

267* 提供者自己形狀中的 `400` 或 `413`：`capability_rejected:` 令牌。當閘道無法分類拒絕時，`400` 上的 `upstream rejected the request` 或 `413` 上的 `request too large for this upstream`。267* 提供者自己形狀中的 `400` 或 `413`：`capability_rejected:` token。當閘道無法分類拒絕時，`400` 上為 `upstream rejected the request`，`413` 上為 `request too large for this upstream`。

268* 任何其他狀態：通用的每狀態副本，例如 `429` 上的 `upstream rate limit exceeded`。268* 任何其他狀態：通用的每狀態文字，例如 `429` 上的 `upstream rate limit exceeded`。

269 269

270例如，閘道將 Amazon Bedrock 的 `Input is too long for requested model.` 替換為 `capability_rejected: prompt_too_long`。Claude Code [自動壓縮](/docs/zh-TW/errors#prompt-is-too-long)該令牌，就像它對 `prompt is too long` 所做的那樣。270例如，閘道將 Amazon Bedrock 的 `Input is too long for requested model.` 替換為 `capability_rejected: prompt_too_long`。Claude Code 在收到該 token 時會[自動壓縮](/docs/zh-TW/errors#prompt-is-too-long)，就像它對 `prompt is too long` 所做的那樣。

271 271

272保持雲上游的 `400` 或 `413` 訊息，或將其替換為 `capability_rejected:` 令牌，需要閘道 v2.1.233 或更新版本。272保持雲上游的 `400` 或 `413` 訊息，或將其替換為 `capability_rejected:` token，需要閘道 v2.1.233 或更新版本。

273 273

274<h4 id="anthropic-api">274<h4 id="anthropic-api">

275 Anthropic API275 Anthropic API

282 - provider: anthropic282 - provider: anthropic

283 auth:283 auth:

284 api_key: ${ANTHROPIC_API_KEY}284 api_key: ${ANTHROPIC_API_KEY}

285 # 或 OAuth 持有人（例如工作負載身分識別聯合交換的令牌）：285 # 或 OAuth 持有人 token（例如工作負載身分識別聯合交換的 token）：

286 # oauth_token: ${file:/var/run/secrets/anthropic-oauth-token}286 # oauth_token: ${file:/var/run/secrets/anthropic-oauth-token}

287 # base_url: https://api.anthropic.com # 預設；覆蓋以使用轉發代理287 # base_url: https://api.anthropic.com # 預設；覆寫以使用轉發代理伺服器

288```288```

289 289

290兩種認證形式在它們傳送的標頭中有所不同：290兩種憑證形式在它們傳送的標頭中有所不同：

291 291

292* **`api_key`**：傳送 `x-api-key`。在 Claude Console 中輪換它並更新環境變數。292* **`api_key`**：傳送 `x-api-key`。在 Claude Console 中輪換它並更新環境變數。

293* **`oauth_token`**：傳送 `Authorization: Bearer`。當您的組織發出短期令牌而不是長期 API 金鑰時使用持有人形式。持有人在啟動時讀取一次，因此透過重新掛載祕密和重新啟動來重新整理。293* **`oauth_token`**：傳送 `Authorization: Bearer`。當您的組織發出短期 token 而不是長期 API 金鑰時使用持有人形式。持有人 token 在啟動時讀取一次，因此透過重新掛載祕密和重新啟動來重新整理。

294 294

295除了靜態金鑰或持有人，您可以使用工作負載身分識別聯合。按照[工作負載身分識別聯合指南](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation)建立聯合規則，然後將您的工作負載的 OIDC JWT 掛載為檔案，例如 Kubernetes 投影服務帳戶令牌或 CI 平台的 id-token。閘道將 JWT 交換為短期持有人並自動重新整理它。令牌檔案在每次交換時重新讀取，因此輪換的投影令牌無需重新啟動即可被拾取。295除了靜態金鑰或持有人 token，您可以使用工作負載身分識別聯合。按照[工作負載身分識別聯合指南](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation)建立聯合規則，然後將您的工作負載的 OIDC JWT 掛載為檔案，例如 Kubernetes 投影服務帳戶 token 或 CI 平台的 id-token。閘道將 JWT 交換為短期持有人 token 並自動重新整理它。token 檔案在每次交換時重新讀取，因此輪換的投影 token 無需重新啟動即可被拾取。

296 296

297```yaml theme={null}297```yaml theme={null}

298upstreams:298upstreams:

308<a id="per-user-identity-headers-for-a-proxy-you-run" />308<a id="per-user-identity-headers-for-a-proxy-you-run" />

309 309

310<h5 id="per-user-identity-headers-for-a-proxy-you-run">310<h5 id="per-user-identity-headers-for-a-proxy-you-run">

311 針對您執行的代理的每個使用者身分識別標頭311 針對您執行的代理伺服器的每個使用者身分識別標頭

312</h5>312</h5>

313 313

314您可以將 `provider: anthropic` 上游的 `base_url` 指向您執行的代理，而不是 Anthropic API。若要告訴該代理哪個開發人員傳送了每個請求，請在該上游上設定 `forward_user_identity: true`。代理然後可以按開發人員歸因支出。需要在閘道伺服器上執行 Claude Code v2.1.233 或更新版本。314您可以將 `provider: anthropic` 上游的 `base_url` 指向您執行的代理伺服器，而不是 Anthropic API。若要告訴該代理伺服器哪個開發人員傳送了每個請求，請在該上游上設定 `forward_user_identity: true`。代理伺服器然後可以按開發人員歸因支出。需要在閘道伺服器上執行 Claude Code v2.1.233 或更新版本。

315 315

316例如，對於 `upstream-gateway.internal.example.com` 的代理：316例如，對於位於 `upstream-gateway.internal.example.com` 的代理伺服器：

317 317

318```yaml theme={null}318```yaml theme={null}

319upstreams:319upstreams:

329| 標頭 | 值 |329| 標頭 | 值 |

330| - | - |330| - | - |

334 334

335當 IdP 令牌不攜帶電子郵件時，閘道僅傳送 `x-claude-gateway-user-id` 並省略兩個電子郵件標頭。如果您的 IdP 將電子郵件放在不同的宣告中，請將 [`oidc.email_claim`](#oidc) 設定為該宣告。335當 IdP token 不攜帶電子郵件時，閘道僅傳送 `x-claude-gateway-user-id` 並省略兩個電子郵件標頭。如果您的 IdP 將電子郵件放在不同的宣告中，請將 [`oidc.email_claim`](#oidc) 設定為該宣告。

336 336

337當您的代理答覆攜帶開發人員電子郵件的請求的 `429` 時，閘道將該回應原樣返回給開發人員，而不是故障轉移到下一個上游，因此您的代理的每個使用者預算或速率限制保持。代理的其他回應遵循普通[故障轉移規則](#upstreams)。如果開發人員的 IdP 令牌不攜帶電子郵件，閘道轉發其請求而不帶電子郵件標頭，因此對其中一個請求的 `429` 計為上游容量並故障轉移。在閘道伺服器上的 v2.1.267 之前，每個 `429` 都故障轉移。337當您的代理伺服器對攜帶開發人員電子郵件的請求答覆 `429` 時，閘道將該回應原樣返回給開發人員，而不是故障轉移到下一個上游，因此您的代理伺服器的每個使用者預算或速率限制得以維持。代理伺服器的其他回應遵循一般的[故障轉移規則](#upstreams)。如果開發人員的 IdP token 不攜帶電子郵件，閘道轉發其請求而不帶電子郵件標頭，因此對其中一個請求的 `429` 計為上游容量並故障轉移。在閘道伺服器上的 v2.1.267 之前，每個 `429` 都故障轉移。

338 338

339僅在 `base_url` 是您操作的代理的上游上設定 `forward_user_identity`。閘道將開發人員電子郵件傳送到該 `base_url` 命名的任何伺服器。如果 `base_url` 是 Anthropic API（預設），閘道拒絕啟動。339僅在 `base_url` 是您操作的代理伺服器的上游上設定 `forward_user_identity`。閘道將開發人員電子郵件傳送到該 `base_url` 命名的任何伺服器。如果 `base_url` 是 Anthropic API（預設），閘道拒絕啟動。

340 340

341<h4 id="amazon-bedrock">341<h4 id="amazon-bedrock">

342 Amazon Bedrock342 Amazon Bedrock

343</h4>343</h4>

344 344

345對於閘道替換或前置的用戶端 Bedrock 部署，請參閱 [Claude Code on Amazon Bedrock](/docs/zh-TW/amazon-bedrock)。閘道端上游：345對於閘道替換或前置的用戶端 Amazon Bedrock 部署，請參閱 [Claude Code on Amazon Bedrock](/docs/zh-TW/amazon-bedrock)。閘道端上游：

346 346

347```yaml theme={null}347```yaml theme={null}

348upstreams:348upstreams:

349 - provider: bedrock349 - provider: bedrock

350 region: us-east-1350 region: us-east-1

351 auth: {} # 首選：AWS 預設認證鏈351 auth: {} # 首選：AWS 預設憑證鏈

352 # 或明確認證：352 # 或明確憑證：

353 # auth:353 # auth:

354 # aws_access_key_id: ${AWS_AKID}354 # aws_access_key_id: ${AWS_AKID}

355 # aws_secret_access_key: ${AWS_SK}355 # aws_secret_access_key: ${AWS_SK}

356 # aws_session_token: ${AWS_ST}356 # aws_session_token: ${AWS_ST}

357 # 或 Bedrock API 持有人令牌：357 # 或 Bedrock API 持有人 token：

358 # auth:358 # auth:

359 # aws_bearer_token: ${AWS_BEARER_TOKEN}359 # aws_bearer_token: ${AWS_BEARER_TOKEN}

360 # 覆蓋 bedrock-runtime 端點以進行 FIPS 或 VPC 端點部署：360 # 覆寫 bedrock-runtime 端點以進行 FIPS 或 VPC 端點部署：

361 # base_url: https://bedrock-runtime-fips.us-east-1.amazonaws.com361 # base_url: https://bedrock-runtime-fips.us-east-1.amazonaws.com

362```362```

363 363

364空的 `auth` 區塊使用 AWS SDK 的預設認證鏈：環境變數、`~/.aws/credentials`、ECS 任務角色、EC2 執行個體中繼資料或 EKS 上的 IRSA。在生產環境中，給予閘道 Pod 一個 IAM 角色，而不是在容器映像中嵌入靜態金鑰。364空的 `auth` 區塊使用 AWS SDK 的預設憑證鏈：環境變數、`~/.aws/credentials`、ECS 任務角色、EC2 執行個體中繼資料或 EKS 上的 IRSA。在生產環境中，給予閘道 Pod 一個 IAM 角色，而不是在容器映像中嵌入靜態金鑰。

365 365

366明確認證必須完整：當 `aws_access_key_id` 和 `aws_secret_access_key` 未一起設定時，或當 `aws_session_token` 在沒有它們的情況下設定時，閘道在啟動時失敗。在 v2.1.207 之前，部分 `auth:` 區塊通過驗證。366明確憑證必須完整：當 `aws_access_key_id` 和 `aws_secret_access_key` 未一起設定時，或當 `aws_session_token` 在沒有它們的情況下設定時，閘道在啟動時失敗。在 v2.1.207 之前，部分 `auth:` 區塊會通過驗證。

367 367

368| 設定 | 方式 |368| 設定 | 方式 |

369| - | - |369| - | - |

370| IAM 權限 | 授予閘道的主體 `bedrock:InvokeModel` 和 `bedrock:InvokeModelWithResponseStream` 在推論設定檔 ARN 和基礎基礎模型 ARN 上。對於美國地區的內建目錄：`arn:aws:bedrock:<region>:<account>:inference-profile/us.anthropic.*` 和 `arn:aws:bedrock:*::foundation-model/anthropic.*`。也授予基礎模型 ARN 上的 `bedrock:CountTokens`。閘道使用它（免費）來計算用戶端放棄的請求的輸入令牌，因此[支出限制](#admin)保持準確。沒有它，閘道會回退到該計數的一令牌 Bedrock 請求。 |370| IAM 權限 | 在推論設定檔 ARN 和底層基礎模型 ARN 上授予閘道的主體 `bedrock:InvokeModel` 和 `bedrock:InvokeModelWithResponseStream`。對於美國地區的內建目錄：`arn:aws:bedrock:<region>:<account>:inference-profile/us.anthropic.*` 和 `arn:aws:bedrock:*::foundation-model/anthropic.*`。也授予基礎模型 ARN 上的 `bedrock:CountTokens`。閘道使用它（免費）來計算用戶端放棄的請求的輸入 token，因此[支出限制](#admin)保持準確。沒有它，閘道會改用一個 token 的 Bedrock 請求來取得該計數。 |

371| 模型存取 | Amazon Bedrock 在商業地區預設啟用模型存取。剩餘的帳戶級閘控是 Anthropic 的一次性使用案例表單：如果您的 AWS 帳戶中沒有人提交過，請開啟 Amazon Bedrock 主控台，從模型目錄中選擇 Anthropic 模型，並完成表單。請參閱[提交使用案例詳細資訊](/docs/zh-TW/amazon-bedrock#1-submit-use-case-details)以了解 AWS Organizations 表單和提交者需要的權限。 |371| 模型存取 | Amazon Bedrock 在商業地區預設啟用模型存取。剩餘的帳戶級閘控是 Anthropic 的一次性使用案例表單：如果您的 AWS 帳戶中沒有人提交過，請開啟 Amazon Bedrock 主控台，從模型目錄中選擇 Anthropic 模型，並完成表單。請參閱[提交使用案例詳細資訊](/docs/zh-TW/amazon-bedrock#1-submit-use-case-details)以了解 AWS Organizations 表單和提交者需要的權限。 |

372| EKS (IRSA) | 建立具有上述原則和針對您叢集的 OIDC 提供者的信任原則的 IAM 角色，範圍限於閘道的服務帳戶。使用 `eks.amazonaws.com/role-arn: arn:aws:iam::<acct>:role/claude-gateway` 註釋服務帳戶。`auth: {}` 會拾取它。 |372| EKS (IRSA) | 建立具有上述原則和針對您叢集的 OIDC 提供者的信任原則的 IAM 角色，範圍限於閘道的服務帳戶。使用 `eks.amazonaws.com/role-arn: arn:aws:iam::<acct>:role/claude-gateway` 註釋服務帳戶。`auth: {}` 會拾取它。 |

373| ECS / EC2 | 將 IAM 角色附加到任務定義或執行個體設定檔。`auth: {}` 會拾取它。 |373| ECS / EC2 | 將 IAM 角色附加到任務定義或執行個體設定檔。`auth: {}` 會拾取它。 |

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<h5 id="apply-an-amazon-bedrock-guardrail">377<h5 id="apply-an-amazon-bedrock-guardrail">

392```392```

393 393

394<Warning>394<Warning>

395 閘道不支援防護欄輸入標籤。它不向提示新增防護內容標籤，因此 Amazon Bedrock 僅應用於標籤輸入的防護欄篩選器不會在透過閘道的流量上執行。對於哪些篩選器取決於輸入標籤，請參閱 Amazon Bedrock 文件中的[輸入標籤](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-tagging.html)。395 閘道不支援防護欄輸入標籤。它不向提示詞新增防護內容標籤，因此 Amazon Bedrock 僅應用於標籤輸入的防護欄篩選器不會在透過閘道的流量上執行。對於哪些篩選器取決於輸入標籤，請參閱 Amazon Bedrock 文件中的[輸入標籤](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-tagging.html)。

396</Warning>396</Warning>

397 397

398也授予簽署此上游請求的主體的防護欄上的 `bedrock:ApplyGuardrail`：閘道的 AWS 主體，或使用 [`assume_role`](#bedrock-in-another-aws-account) 的 `role_arn` 中命名的角色。398也將該防護欄上的 `bedrock:ApplyGuardrail` 授予簽署此上游請求的主體：閘道的 AWS 主體，或使用 [`assume_role`](#bedrock-in-another-aws-account) 時 `role_arn` 中命名的角色。

399 399

400在每個 `bedrock` 上游或沒有上游上設定 `guardrail`。閘道拒絕在混合上啟動，因為[故障轉移](#multiple-upstreams)可能會將請求傳送到沒有防護欄的 Bedrock 上游。400在每個 `bedrock` 上游上都設定 `guardrail`，或都不設定。閘道在混合設定時拒絕啟動，因為[故障轉移](#multiple-upstreams)可能會將請求傳送到沒有防護欄的 Bedrock 上游。

401 401

402防護欄僅涵蓋 Bedrock 上游。如果您在 `upstreams` 中列出另一個提供者，閘道將請求傳送到該提供者而不帶防護欄。402防護欄僅涵蓋 Bedrock 上游。如果您在 `upstreams` 中列出另一個提供者，閘道將請求傳送到該提供者而不帶防護欄；如果該提供者是 [`mantle`](#amazon-bedrock-mantle-endpoint)，則閘道拒絕啟動。

403 403

404當 `/v1/messages` 請求的正文攜帶 `amazon-bedrock-*` 欄位（例如 `amazon-bedrock-guardrailConfig`）到達設定了 `guardrail` 的 Bedrock 上游時，閘道答覆 400 而不是轉發它。404當 `/v1/messages` 請求的正文攜帶 `amazon-bedrock-*` 欄位（例如 `amazon-bedrock-guardrailConfig`）到達設定了 `guardrail` 的 Bedrock 上游時，閘道答覆 400 而不是轉發它。

405 405

409 另一個 AWS 帳戶中的 Bedrock409 另一個 AWS 帳戶中的 Bedrock

410</h5>410</h5>

411 411

412在 Bedrock 上游上設定 `assume_role`，閘道僅使用其自己的 AWS 身分識別來呼叫您命名的角色上的 `sts:AssumeRole`，該角色可以在與閘道不同的 AWS 帳戶中。該上游的每個 Bedrock 請求都使用 STS 返回的一小時認證簽署，因此沒有長期存取金鑰跨帳戶。412在 Bedrock 上游上設定 `assume_role`，閘道僅使用其自己的 AWS 身分識別來呼叫您命名的角色上的 `sts:AssumeRole`，該角色可以在與閘道不同的 AWS 帳戶中。該上游的每個 Bedrock 請求都使用 STS 返回的一小時憑證簽署，因此沒有長期存取金鑰跨帳戶。

413 413

414需要執行 Claude Code v2.1.281 或更新版本的閘道。較早的閘道在找到金鑰時拒絕啟動。414需要執行 Claude Code v2.1.281 或更新版本的閘道。較早的閘道在找到此鍵時拒絕啟動。

415 415

416```yaml theme={null}416```yaml theme={null}

417upstreams:417upstreams:

424 # external_id: ${BEDROCK_ROLE_EXTERNAL_ID} # 當角色的信任原則需要時424 # external_id: ${BEDROCK_ROLE_EXTERNAL_ID} # 當角色的信任原則需要時

425```425```

426 426

427`assume_role` 區塊採用三個金鑰：427`assume_role` 區塊採用三個鍵：

428 428

429| 金鑰 | 意義 |429| 鍵 | 意義 |

430| - | - |430| - | - |

431| `role_arn` | 閘道假設的 IAM 角色，作為 `arn:aws:iam::` 或 `arn:aws-us-gov:iam::` ARN。給予它此上游需要的 [Bedrock 權限](#amazon-bedrock)，包括 `bedrock:CountTokens`，以及當上游設定 `guardrail` 時的 `bedrock:ApplyGuardrail`。 |431| `role_arn` | 閘道擔任的 IAM 角色，作為 `arn:aws:iam::` 或 `arn:aws-us-gov:iam::` ARN。給予它此上游需要的 [Bedrock 權限](#amazon-bedrock)，包括 `bedrock:CountTokens`，以及當上游設定 `guardrail` 時的 `bedrock:ApplyGuardrail`。 |

433| `session_name` | 選用。`email` 或 `sub` 給每個開發人員自己的工作階段：請參閱[每個開發人員 AWS 成本歸因](#per-developer-aws-cost-attribution)。未設定，每個請求使用一個名為 `claude-apps-gateway` 的工作階段。 |433| `session_name` | 選用。`email` 或 `sub` 給每個開發人員自己的工作階段：請參閱[每個開發人員 AWS 成本歸因](#per-developer-aws-cost-attribution)。未設定時，每個請求使用一個名為 `claude-apps-gateway` 的工作階段。 |

434 434

435角色的信任原則命名閘道自己的主體，例如其 IRSA 或 ECS 任務角色。該主體需要角色上的 `sts:AssumeRole` 和沒有 Bedrock 權限。如果您設定沒有 `external_id`，請刪除 `Condition`。435角色的信任原則命名閘道自己的主體，例如其 IRSA 或 ECS 任務角色。該主體需要角色上的 `sts:AssumeRole`，自身不需要任何 Bedrock 權限。如果您未設定 `external_id`，請刪除 `Condition`。

436 436

437```json theme={null}437```json theme={null}

438{438{

446}446}

447```447```

448 448

449* 如果 STS 拒絕或無法到達，閘道不會使用上游自己的認證傳送請求。它記錄 STS 錯誤以及要檢查的內容，然後嘗試您列出的下一個上游。[上游錯誤訊息](#upstream-error-messages)涵蓋當沒有上游成功時用戶端接收的內容。沒有 `assume_role` 的稍後上游會使用其自己的認證服務請求，因此僅在這是您想要的情況下列出一個。449* 如果 STS 拒絕或無法到達，閘道不會使用上游自己的憑證傳送請求。它記錄 STS 錯誤以及要檢查的內容，然後嘗試您列出的下一個上游。[上游錯誤訊息](#upstream-error-messages)涵蓋當沒有上游成功時用戶端接收的內容。沒有 `assume_role` 的稍後上游會使用其自己的憑證服務請求，因此僅在這是您想要的情況下才列出這樣的上游。

450* 閘道呼叫區域 STS 端點 `sts.<region>.amazonaws.com`，其網路必須到達。對於 FIPS 端點，在閘道的環境中設定 `AWS_USE_FIPS_ENDPOINT=true` 而不是在 AWS 設定檔中設定 `use_fips_endpoint`。450* 閘道呼叫區域 STS 端點 `sts.<region>.amazonaws.com`，其網路必須能到達。對於 FIPS 端點，在閘道的環境中設定 `AWS_USE_FIPS_ENDPOINT=true`，而不是在 AWS 設定檔中設定 `use_fips_endpoint`。

451* `assume_role` 僅適用於 `provider: bedrock` 並需要 SigV4 來源認證：當它在 `aws_bearer_token` 旁邊設定時，閘道拒絕啟動。451* `assume_role` 僅適用於 `provider: bedrock` 並需要 SigV4 來源憑證：當它與 `aws_bearer_token` 一起設定時，閘道拒絕啟動。

452* 閘道允許的每個開發人員都可以使用此上游；[`managed`](#managed)控制哪些開發人員可能使用哪些模型。若要保持透過角色服務的模型也不從另一個帳戶服務，請給它一個自訂 id，其 `upstream_model` 對應僅具有此上游的名稱。對於這樣的 id，閘道跳過每個其他上游，因此請求和已放棄請求的令牌計數都無法故障轉移到另一個帳戶。內建模型名稱仍在每個上游上按順序嘗試，包括這個，到達它的請求使用相同角色簽署，因此除非其帳戶也應該服務它們，否則最後列出此上游。452* 閘道允許的每個開發人員都可以使用此上游；[`managed`](#managed) 控制哪些開發人員可以使用哪些模型。若要避免透過該角色服務的模型也從另一個帳戶服務，請給它一個自訂 id，其 `upstream_model` 對應僅具有此上游的名稱。對於這樣的 id，閘道跳過每個其他上游，因此請求和已放棄請求的 token 計數都無法故障轉移到另一個帳戶。內建模型名稱的請求仍可能[到達此上游](#multiple-upstreams)，且閘道會使用相同角色簽署它。除非其帳戶也應該服務這些模型，否則請將此上游列在最後。

453 453

454此範例給一個模型一個自訂 id，只有隔離上游服務：454此範例給一個模型一個僅由隔離上游服務的自訂 id：

455 455

456```yaml theme={null}456```yaml theme={null}

457models:457models:

466 每個開發人員 AWS 成本歸因466 每個開發人員 AWS 成本歸因

467</h5>467</h5>

468 468

469預設情況下，閘道使用一個認證簽署每個 Bedrock 請求，因此 AWS 在單個 IAM 主體下看到所有開發人員的請求。將 `session_name: email` 新增到 [`assume_role`](#bedrock-in-another-aws-account)，閘道每個開發人員每小時呼叫一次 `sts:AssumeRole`，工作階段名稱設定為該開發人員的電子郵件，並使用返回的認證簽署其請求，因此每個開發人員的請求在 AWS 下以其自己的假設角色工作階段到達。角色可以在閘道自己的帳戶中。469預設情況下，閘道使用一個憑證簽署每個 Bedrock 請求，因此 AWS 在單個 IAM 主體下看到所有開發人員的請求。將 `session_name: email` 新增到 [`assume_role`](#bedrock-in-another-aws-account)，閘道會為每個開發人員每小時呼叫一次 `sts:AssumeRole`，工作階段名稱設定為該開發人員的電子郵件，並使用返回的憑證簽署其請求，因此每個開發人員的請求以其自己的擔任角色工作階段到達 AWS。角色可以在閘道自己的帳戶中。

470 470

471需要執行 Claude Code v2.1.281 或更新版本的閘道。[AWS 上的成本歸因](/docs/zh-TW/claude-apps-gateway-on-aws#cost-attribution)涵蓋 IAM 角色以及 AWS 帳單顯示工作階段的位置。471需要執行 Claude Code v2.1.281 或更新版本的閘道。[AWS 上的成本歸因](/docs/zh-TW/claude-apps-gateway-on-aws#cost-attribution)涵蓋 IAM 角色以及 AWS 計費顯示工作階段的位置。

472 472

473```yaml theme={null}473```yaml theme={null}

474upstreams:474upstreams:

480 session_name: email # 或 sub480 session_name: email # 或 sub

481```481```

482 482

483`session_name` 選擇哪個已驗證宣告成為 AWS `RoleSessionName`：`email` 或 `sub`。閘道將 ASCII 字母、數字和 `_+,.@-` 以外的任何字元寫成 `=XX` 十六進位（每 UTF-8 位元組），並將長於 64 字元的結果縮短為前置詞加雜湊，因此每個開發人員的工作階段名稱保持有效且唯一。來自其令牌缺少宣告的開發人員的請求不會透過此上游傳送，操作員日誌說要切換到 `sub` 或設定 [`oidc.email_claim`](#oidc)。483`session_name` 選擇哪個已驗證宣告成為 AWS `RoleSessionName`：`email` 或 `sub`。閘道將 ASCII 字母、數字和 `_+,.@-` 以外的任何字元寫成 `=XX` 十六進位（每 UTF-8 位元組），並將長於 64 字元的結果縮短為前置詞加雜湊，因此每個開發人員的工作階段名稱保持有效且唯一。來自 token 缺少該宣告的開發人員的請求不會透過此上游傳送，操作員日誌會提示切換到 `sub` 或設定 [`oidc.email_claim`](#oidc)。

484 484

485活躍開發人員每小時每個閘道副本成本一個 STS 呼叫，並且並行首次請求共享一個呼叫。485一位活躍開發人員每小時在每個閘道副本上花費一個 STS 呼叫，且並行的首次請求共享一個呼叫。

486 486

487閘道也在此角色上進行一個呼叫：用戶端放棄的請求的令牌計數，因此[支出限制](/docs/zh-TW/claude-apps-gateway-spend-limits)保持準確。該計數及其[一令牌後備請求](#amazon-bedrock)由共享 `claude-apps-gateway` 工作階段簽署，因此 AWS 將後備歸因於 `claude-apps-gateway` 而不是開發人員。487閘道也在此角色上進行一個自己的呼叫：用戶端放棄的請求的 token 計數，以使[支出限制](/docs/zh-TW/claude-apps-gateway-spend-limits)保持準確。該計數及其[一個 token 的備援請求](#amazon-bedrock)由共享的 `claude-apps-gateway` 工作階段簽署，因此 AWS 將該備援請求歸因於 `claude-apps-gateway` 而不是開發人員。

488 488

489對於嚴格的每個開發人員歸因，在您列出的每個 Bedrock 上游上設定 `assume_role` 與 `session_name`。沒有它的上游使用其自己的認證簽署它服務的請求。489對於嚴格的每個開發人員歸因，在您列出的每個 Bedrock 上游上設定 `assume_role` 與 `session_name`。沒有它的上游使用其自己的憑證簽署它服務的請求。

490

491<h4 id="amazon-bedrock-mantle-endpoint">

492 Amazon Bedrock Mantle 端點

493</h4>

494

495`mantle` 提供者將推論傳送到 Amazon Bedrock 的 [Mantle 端點](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint)。它需要閘道伺服器上的 Claude Code v2.1.283 或更新版本。較早的閘道版本會在啟動時拒絕它，因此請在新增之前升級每個副本。

496

497下面的範例將 Mantle 放在第一位，其後接一個 Amazon Bedrock 上游，以服務 `models` 欄位未列出的每個模型：

498

499```yaml theme={null}

500upstreams:

501 - provider: mantle

502 region: us-east-1

503 models: [claude-opus-4-7, claude-haiku-4-5] # 必需

504 auth: {} # AWS 預設憑證鏈

505 - provider: bedrock

506 region: us-east-1

507 auth: {}

508```

509

510下表列出 `mantle` 上游特有的欄位。

511

512| 欄位 | 必需 | 說明 |

513| - | - | - |

514| `region` | 是 | AWS 地區。閘道將端點衍生為 `https://bedrock-mantle.<region>.api.aws/anthropic`。 |

515| `models` | 是 | 您的 AWS 帳戶在 Mantle 上已獲授權的模型，以用戶端傳送的名稱命名，例如 `claude-haiku-4-5`。只有這些模型會送往此上游，其他每個模型都會跳到下一個上游。 |

516| `auth` | 否 | 採用與 [Amazon Bedrock](#amazon-bedrock) 上游的 `auth` 區塊相同的鍵，並遵循相同規則。 |

517| `base_url` | 否 | 覆寫衍生的端點。請在結尾保留 `/anthropic` 路徑。 |

518

519授予上游的 AWS 身分識別 Mantle 自己用於推論和 token 計數的 IAM 動作，這些動作列於[使用 Mantle 端點](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint)中。

520

521對於閘道不認識的 Mantle 模型 ID，請在頂層 [`models:`](#models) 區塊中新增一個項目，其 `upstream_model` 將此上游的名稱對應到該 ID。然後也將該項目的 `id` 放入此上游的 `models` 欄位。

522

523`bedrock` 上游的 `guardrail` 和 `assume_role` 設定不會延伸到 Mantle 服務的請求：

524

525* **`guardrail`**：閘道不對其傳送到 Mantle 的請求套用任何 [Bedrock 防護欄](#apply-an-amazon-bedrock-guardrail)，因此當列出 `mantle` 上游且任何 `bedrock` 上游設定了 `guardrail` 時，閘道拒絕啟動。

526* **`assume_role`**：`mantle` 上游不接受 [`assume_role`](#bedrock-in-another-aws-account)。Mantle 服務的請求使用 `mantle` 上游自己的 `auth` 憑證傳送，且不會[按開發人員歸因](#per-developer-aws-cost-attribution)。

527

528關於 Mantle 自己的錯誤回應的意義，請參閱 [Mantle 端點錯誤](/docs/zh-TW/amazon-bedrock#mantle-endpoint-errors)。

490 529

491<h4 id="claude-platform-on-aws">530<h4 id="claude-platform-on-aws">

492 Claude Platform on AWS531 Claude Platform on AWS

493</h4>532</h4>

494 533

495Claude Platform on AWS 在 `aws-external-anthropic.<region>.api.aws` 的 AWS 基礎設施上服務第一方 Anthropic API。它使用第一方模型 ID，按原樣接受 `anthropic-beta` 標頭，並服務 `count_tokens`，因此 Bedrock 特定的轉譯都不適用。`anthropicAws` 提供者需要 Claude Code v2.1.198 或更新版本；較早的閘道版本在啟動時拒絕它。534Claude Platform on AWS 在 AWS 基礎設施上於 `aws-external-anthropic.<region>.api.aws` 服務第一方 Anthropic API。它使用第一方模型 ID，按原樣接受 `anthropic-beta` 標頭，並服務 `count_tokens`，因此 Bedrock 特定的轉譯都不適用。`anthropicAws` 提供者需要 Claude Code v2.1.198 或更新版本；較早的閘道版本在啟動時拒絕它。

496 535

497對於相同平台的用戶端部署，請參閱 [Claude Code on Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws)。閘道端上游：536對於相同平台的用戶端部署，請參閱 [Claude Code on Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws)。閘道端上游：

498 537

503 workspace_id: wrkspc_...542 workspace_id: wrkspc_...

504 auth:543 auth:

505 api_key: ${ANTHROPIC_AWS_API_KEY} # 作為 x-api-key 傳送544 api_key: ${ANTHROPIC_AWS_API_KEY} # 作為 x-api-key 傳送

506 # 或透過 AWS 預設認證鏈的 SigV4：545 # 或透過 AWS 預設憑證鏈的 SigV4：

507 # auth: {}546 # auth: {}

508 # 或明確的 SigV4 認證：547 # 或明確的 SigV4 憑證：

509 # auth:548 # auth:

510 # aws_access_key_id: ${AWS_ACCESS_KEY_ID}549 # aws_access_key_id: ${AWS_ACCESS_KEY_ID}

511 # aws_secret_access_key: ${AWS_SECRET_ACCESS_KEY}550 # aws_secret_access_key: ${AWS_SECRET_ACCESS_KEY}

512 # 覆蓋衍生的端點：551 # 覆寫衍生的端點：

513 # base_url: https://aws-external-anthropic.us-east-1.api.aws552 # base_url: https://aws-external-anthropic.us-east-1.api.aws

514```553```

515 554

516該平台在與 Amazon Bedrock 不同的 AWS 帳戶中執行，並為其自己的服務名稱 `aws-external-anthropic` 簽署 SigV4 請求，因此 Bedrock 範圍的 IAM 角色不授權它。`auth.api_key` 中的 API 金鑰在同時設定 SigV4 認證時優先。空的 `auth` 區塊使用 AWS SDK 的預設認證鏈，與 [Amazon Bedrock](#amazon-bedrock) 上游使用的相同鏈。555該平台在與 Amazon Bedrock 不同的 AWS 帳戶中執行，並為其自己的服務名稱 `aws-external-anthropic` 簽署 SigV4 請求，因此 Bedrock 範圍的 IAM 角色不會授權它。`auth.api_key` 中的 API 金鑰在同時設定 SigV4 憑證時優先。空的 `auth` 區塊使用 AWS SDK 的預設憑證鏈，與 [Amazon Bedrock](#amazon-bedrock) 上游使用的相同鏈。

517 556

518| 欄位 | 必需 | 說明 |557| 欄位 | 必需 | 說明 |

519| - | - | - |558| - | - | - |

520| `region` | 是 | AWS 地區，小寫字母、數字和連字號。閘道將端點衍生為 `https://aws-external-anthropic.<region>.api.aws`。 |559| `region` | 是 | AWS 地區，小寫字母、數字和連字號。閘道將端點衍生為 `https://aws-external-anthropic.<region>.api.aws`。 |

521| `workspace_id` | 是 | 在每個請求上傳送為標頭；平台需要它 |560| `workspace_id` | 是 | 在每個請求上傳送為標頭；平台需要它 |

522| `auth.api_key` | 否 | 平台的 API 金鑰，作為 `x-api-key` 傳送。不是持有人令牌：兩種驗證模式是 API 金鑰或 SigV4。 |561| `auth.api_key` | 否 | 平台的 API 金鑰，作為 `x-api-key` 傳送。不是持有人 token：兩種驗證模式是 API 金鑰或 SigV4。 |

523| `auth.aws_access_key_id` / `auth.aws_secret_access_key` | 否 | 明確的 SigV4 認證。設定其中一個而不設定另一個在啟動時失敗。`auth.aws_session_token` 與它們一起被接受。 |562| `auth.aws_access_key_id` / `auth.aws_secret_access_key` | 否 | 明確的 SigV4 憑證。設定其中一個而不設定另一個在啟動時失敗。`auth.aws_session_token` 可與它們一起使用。 |

524| `base_url` | 否 | 覆蓋衍生的端點 |563| `base_url` | 否 | 覆寫衍生的端點 |

525 564

526因為平台解析第一方模型 ID，內建目錄無需 [`models:`](#models) 區塊即可路由到它。當您策劃 `models:` 清單時，使用第一方 ID 鍵入 `anthropicAws:` 項目。565因為平台解析第一方模型 ID，內建目錄無需 [`models:`](#models) 區塊即可路由到它。當您策劃 `models:` 清單時，使用第一方 ID 作為 `anthropicAws:` 項目的值。

527 566

528<h4 id="google-cloud-agent-platform">567<h4 id="google-cloud-agent-platform">

529 Google Cloud Agent Platform568 Google Cloud Agent Platform

536 - provider: vertex575 - provider: vertex

537 region: us-east5576 region: us-east5

538 project_id: example-prod577 project_id: example-prod

539 auth: {} # 首選：應用程式預設認證578 auth: {} # 首選：應用程式預設憑證

540 # 或服務帳戶金鑰檔案：579 # 或服務帳戶金鑰檔案：

541 # auth: { service_account_json: /secrets/sa.json }580 # auth: { service_account_json: /secrets/sa.json }

542 # 覆蓋 aiplatform 端點以進行私人服務連線：581 # 覆寫 aiplatform 端點以進行私人服務連線：

543 # base_url: https://us-east5-aiplatform.p.googleapis.com582 # base_url: https://us-east5-aiplatform.p.googleapis.com

544```583```

545 584

546空的 `auth` 區塊使用應用程式預設認證：`GOOGLE_APPLICATION_CREDENTIALS`、GCE 中繼資料或 GKE 工作負載身分識別。支援服務帳戶 JSON 金鑰檔案但不建議；使用工作負載身分識別或將服務帳戶附加到 GCE 或 Cloud Run 執行個體。585空的 `auth` 區塊使用應用程式預設憑證：`GOOGLE_APPLICATION_CREDENTIALS`、GCE 中繼資料或 GKE 工作負載身分識別。支援服務帳戶 JSON 金鑰檔案但不建議；請使用工作負載身分識別或將服務帳戶附加到 GCE 或 Cloud Run 執行個體。

547 586

548設定 `region: global` 以使用 [Agent Platform 的全域端點](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations)而不是區域端點。Google 然後將每個請求路由到可用的地區，因此您不追蹤每個地區的模型可用性。設定特定地區會將每個請求固定到它。587設定 `region: global` 以使用 [Google Cloud 的 Agent Platform 全域端點](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations)而不是區域端點。Google 然後將每個請求路由到可用的地區，因此您不需追蹤每個地區的模型可用性。設定特定地區會將每個請求固定到該地區。

549 588

550| 設定 | 方式 |589| 設定 | 方式 |

551| - | - |590| - | - |

552| IAM 權限 | 授予閘道的服務帳戶在專案上的 `roles/aiplatform.user`，或具有 `aiplatform.endpoints.predict` 的自訂角色。啟用 Agent Platform API (`aiplatform.googleapis.com`)。 |591| IAM 權限 | 授予閘道的服務帳戶在專案上的 `roles/aiplatform.user`，或具有 `aiplatform.endpoints.predict` 的自訂角色。啟用 Google Cloud 的 Agent Platform API (`aiplatform.googleapis.com`)。 |

553| 模型存取 | 在 Model Garden 中，為您的專案啟用 Claude 模型。它們發佈到特定地區；檢查模型卡以了解支援的地區。 |592| 模型存取 | 在 Model Garden 中，為您的專案啟用 Claude 模型。它們發佈到特定地區；檢查模型卡以了解支援的地區。 |

554| GKE (工作負載身分識別) | 將 GCP 服務帳戶繫結到閘道的 Kubernetes 服務帳戶，並使用 `iam.gke.io/gcp-service-account: claude-gateway@<proj>.iam.gserviceaccount.com` 註釋 KSA。`auth: {}` 會拾取它。 |593| GKE (工作負載身分識別) | 將 GCP 服務帳戶繫結到閘道的 Kubernetes 服務帳戶，並使用 `iam.gke.io/gcp-service-account: claude-gateway@<proj>.iam.gserviceaccount.com` 註釋 KSA。`auth: {}` 會拾取它。 |

555| Cloud Run / GCE | 將服務的服務帳戶設定為具有 `roles/aiplatform.user` 的帳戶。`auth: {}` 會拾取它。 |594| Cloud Run / GCE | 將服務的服務帳戶設定為具有 `roles/aiplatform.user` 的帳戶。`auth: {}` 會拾取它。 |

556| 其他任何地方 | `auth: { service_account_json: /secrets/sa.json }`，JSON 金鑰檔案的路徑，掛載為祕密。該欄位採用檔案路徑，而不是金鑰內容，因此不涉及 `${file:…}` 擴展。 |595| 其他任何地方 | `auth: { service_account_json: /secrets/sa.json }`，掛載為祕密的 JSON 金鑰檔案的路徑。該欄位採用檔案路徑，而不是金鑰內容，因此不涉及 `${file:…}` 擴展。 |

557 596

558<h4 id="microsoft-foundry">597<h4 id="microsoft-foundry">

559 Microsoft Foundry598 Microsoft Foundry

560</h4>599</h4>

561 600

562對於用戶端 Foundry 部署，請參閱 [Claude Code on Microsoft Foundry](/docs/zh-TW/microsoft-foundry)。閘道端上游：601對於用戶端 Microsoft Foundry 部署，請參閱 [Claude Code on Microsoft Foundry](/docs/zh-TW/microsoft-foundry)。閘道端上游：

563 602

564```yaml theme={null}603```yaml theme={null}

565upstreams:604upstreams:

571 # api_key: ${FOUNDRY_API_KEY}610 # api_key: ${FOUNDRY_API_KEY}

572```611```

573 612

574`use_azure_ad: true` 透過 `DefaultAzureCredential` 解析：AKS、ACI 或 App Service 上的受管身分識別；Azure CLI；或環境認證。API 金鑰有效但是專案範圍的，不會自動輪換。Foundry 的端點衍生自 `resource:`；設定選用的 `base_url` 以覆蓋它以進行主權雲，例如 Azure Government。613`use_azure_ad: true` 透過 `DefaultAzureCredential` 解析：AKS、ACI 或 App Service 上的受管身分識別；Azure CLI；或環境憑證。API 金鑰有效但是專案範圍的，且不會自動輪換。Microsoft Foundry 的端點衍生自 `resource:`；設定選用的 `base_url` 以針對主權雲（例如 Azure Government）覆寫它。

575 614

576| 設定 | 方式 |615| 設定 | 方式 |

577| - | - |616| - | - |

579| 部署 | Foundry 使用管理員選擇的部署名稱，而不是規範模型 ID。新增 [`models:`](#models) 區塊，將每個規範 ID 對應到您的部署名稱。 |618| 部署 | Microsoft Foundry 使用管理員選擇的部署名稱，而不是規範模型 ID。新增 [`models:`](#models) 區塊，將每個規範 ID 對應到您的部署名稱。 |

582| 其他任何地方 | `auth: { api_key: "${FOUNDRY_API_KEY}" }`。在 `{ }` 內引用 `${…}`。 |621| 其他任何地方 | `auth: { api_key: "${FOUNDRY_API_KEY}" }`。在 `{ }` 內為 `${…}` 加上引號。 |

583 622

584<h4 id="static-headers-on-upstream-requests">623<h4 id="static-headers-on-upstream-requests">

585 上游請求上的靜態標頭624 上游請求上的靜態標頭

586</h4>625</h4>

587 626

588若要將固定標頭新增到閘道傳送到一個上游的請求，請在該上游上設定 `headers:`。當您在提供者前面執行的代理透過標頭路由或歸因流量時使用它。627若要將固定標頭新增到閘道傳送到某一個上游的請求，請在該上游上設定 `headers:`。當您在提供者前面執行的代理伺服器透過標頭路由或歸因流量時使用它。

589 628

590`headers:` 需要閘道伺服器上的 Claude Code v2.1.277 或更新版本。較早的閘道在找到金鑰時拒絕啟動。在新增金鑰之前升級每個副本，並在回滾到較早版本之前移除金鑰。629`headers:` 需要閘道伺服器上的 Claude Code v2.1.277 或更新版本。較早的閘道在找到此鍵時拒絕啟動。在新增此鍵之前升級每個副本，並在回滾到較早版本之前移除此鍵。

591 630

592標頭進入 `base_url` 命名的伺服器，或當 `base_url` 未設定時進入提供者自己的端點。提供者也會收到它們，除非您的代理移除它們。631標頭會送往 `base_url` 命名的伺服器，或當 `base_url` 未設定時送往提供者自己的端點。提供者也會收到它們，除非您的代理伺服器移除它們。

593 632

594此範例透過 `upstream-proxy.internal.example.com` 的代理到達 `provider: vertex` 上游。它設定代理讀取的 `x-source` 標頭，並從 `PROXY_TOKEN` 環境變數傳送令牌作為 `x-proxy-token`：633此範例透過位於 `upstream-proxy.internal.example.com` 的代理伺服器到達 `provider: vertex` 上游。它設定代理伺服器讀取的 `x-source` 標頭，並將來自 `PROXY_TOKEN` 環境變數的 token 作為 `x-proxy-token` 傳送：

595 634

596```yaml theme={null}635```yaml theme={null}

597upstreams:636upstreams:

605 x-proxy-token: ${PROXY_TOKEN}644 x-proxy-token: ${PROXY_TOKEN}

606```645```

607 646

608值是可列印的 ASCII 文字，兩端沒有空格。引用數字、`true` 或 `false`，以便 YAML 將其讀取為文字。647值是可列印的 ASCII 文字，兩端沒有空格。為數字、`true` 或 `false` 加上引號，以便 YAML 將其讀取為文字。

609 648

610若要將祕密保持在設定檔之外，請使用[祕密擴展](#secret-expansion)從環境變數使用 `${VAR}` 或從檔案使用 `${file:/path}` 載入值。解析為空值的 `${VAR}` 會停止閘道啟動。649若要將祕密保持在設定檔之外，請使用[祕密擴展](#secret-expansion)，透過 `${VAR}` 從環境變數或透過 `${file:/path}` 從檔案載入值。解析為空值的 `${VAR}` 會使閘道無法啟動。

611 650

612`headers:` 適用於每個提供者，每個上游僅傳送自己的。651`headers:` 適用於每個提供者，且每個上游僅傳送自己的標頭。

613 652

614並非閘道傳送到上游的每個請求都攜帶它們：653並非閘道傳送到上游的每個請求都攜帶它們：

615 654

617| - | - |656| - | - |

618| `/v1/messages`、串流或不串流，以及 `/v1/messages/count_tokens` | 是 |657| `/v1/messages`（串流或非串流），以及 `/v1/messages/count_tokens` | 是 |

620| Amazon Bedrock 的 `CountTokens` 呼叫用於使用者端放棄的請求 | 否 |659| Amazon Bedrock 針對用戶端放棄的請求進行的 `CountTokens` 呼叫 | 否 |

621| Workload Identity Federation 令牌交換 | 否 |660| Workload Identity Federation token 交換 | 否 |

622 661

623在使用 AWS SigV4 簽署請求的 Amazon Bedrock 或 Claude Platform on AWS 上游上，這些標頭是簽名的一部分，因此您的代理必須原樣傳遞它們。662在使用 AWS SigV4 簽署請求的 Amazon Bedrock 或 Claude Platform on AWS 上游上，這些標頭是簽章的一部分，因此您的代理伺服器必須原樣傳遞它們。

624 663

625如果您使用閘道保留的名稱，它拒絕啟動，啟動錯誤命名標頭。保留名稱包括：664如果您使用閘道保留的名稱，它會拒絕啟動，且啟動錯誤會指出該標頭。保留名稱包括：

626 665

627* `authorization` 和 `x-api-key`666* `authorization` 和 `x-api-key`

628* `host`、`content-type` 和 `user-agent`667* `host`、`content-type` 和 `user-agent`

632 多個上游671 多個上游

633</h4>672</h4>

634 673

635相同的提供者可以出現多次，具有不同的 `name:`。這涵蓋不同的地區、透過不同認證鏈的不同帳戶、佈建輸送量與隨需，以及跨提供者故障轉移。674相同的提供者可以出現多次，具有不同的 `name:`。這涵蓋不同的地區、透過不同憑證鏈的不同帳戶、佈建輸送量與隨需，以及跨提供者備援。

636 675

637閘道按順序嘗試上游。`5xx`、`429`、`401`、`403`、`404`、逾時和遺漏端點 (`501`) 故障轉移；其他 `4xx` 不會。676閘道按順序嘗試上游。`5xx`、`429`、`401`、`403`、`404`、逾時和遺漏端點 (`501`) 會故障轉移；其他 `4xx` 不會。

638 677

639`429` 是每個上游容量，因此佈建輸送量 (PT) 耗盡會故障轉移到隨需。如果您在上游上設定 [`forward_user_identity: true`](#per-user-identity-headers-for-a-proxy-you-run)，攜帶開發人員電子郵件的請求的 `429` 是每個使用者拒絕，而不是故障轉移。678`429` 代表每個上游的容量，因此佈建輸送量 (PT) 耗盡會故障轉移到隨需。如果您在上游上設定 [`forward_user_identity: true`](#per-user-identity-headers-for-a-proxy-you-run)，對攜帶開發人員電子郵件的請求的 `429` 則是每個使用者的拒絕，不會故障轉移。

640 679

641每個請求從第一個上游開始。請求僅在它前面的每個上游都失敗或不服務所請求的模型時才到達稍後的上游。680每個請求從第一個上游開始。請求僅在它前面的每個上游都失敗或不服務所請求的模型時才到達稍後的上游。

642 681

643閘道不保留失敗上游的記錄，因此當上游關閉時，到達它的每個請求仍然嘗試它並等待它失敗後再繼續。682閘道不保留失敗上游的記錄，因此當上游關閉時，到達它的每個請求仍然會嘗試它，並等待它失敗後再繼續。

644 683

645對於 Anthropic API 上游，[`timeouts.upstream_ttfb_ms`](#http-tuning)限制在關閉上游上的等待。該設定不適用於其他提供者，閘道在那裡等待最多一小時以便上游開始回應。684對於 Anthropic API 上游，[`timeouts.upstream_ttfb_ms`](#http-tuning) 限制在關閉上游上的等待時間。該設定不適用於其他提供者，閘道在那些提供者上最多等待一小時讓上游開始回應。

646 685

647`404` 是每個上游模型可用性，因此未啟用模型的上游不會阻止清單中稍後服務它的上游。無法解析所請求模型的上游會被跳過，無需網路往返。686`404` 代表每個上游的模型可用性，因此未啟用模型的上游不會阻止清單中稍後服務它的上游。無法解析所請求模型的上游會被跳過，無需網路往返。

648 687

649此範例首先路由佈建輸送量 Bedrock 配額，溢出到隨需和第二個帳戶，最後故障轉移到 Anthropic API：688此範例首先路由佈建輸送量 Amazon Bedrock 配額，溢出到隨需和第二個帳戶，最後改用 Anthropic API：

650 689

651```yaml theme={null}690```yaml theme={null}

652upstreams:691upstreams:

686 725

687| 槓桿 | 方式 |726| 槓桿 | 方式 |

688| - | - |727| - | - |

689| 不同地區 | 每個地區一個 Bedrock 上游，每個都有自己的 `region:`。使用 [`auto_include_builtin_models: true`](#models)，跨地區推論設定檔會自動路由；對於地區固定部署，使用 `models:` 區塊。 |728| 不同地區 | 每個地區一個 Amazon Bedrock 上游，每個都有自己的 `region:`。使用 [`auto_include_builtin_models: true`](#models)，跨地區推論設定檔會自動路由；對於地區固定部署，使用 `models:` 區塊。 |

690| 不同帳戶 | 每個帳戶一個 Bedrock 上游。預設鏈 (`auth: {}`) 使用 Pod 的身分識別；對於第二個帳戶，新增 [`assume_role`](#bedrock-in-another-aws-account) 以透過短期認證到達它，或在 `auth:` 中設定明確認證或持有人令牌。 |729| 不同帳戶 | 每個帳戶一個 Amazon Bedrock 上游。預設鏈 (`auth: {}`) 使用 Pod 的身分識別；對於第二個帳戶，新增 [`assume_role`](#bedrock-in-another-aws-account) 以透過短期憑證到達它，或在 `auth:` 中設定明確憑證或持有人 token。 |

693| 模型範圍路由 | 只有自訂模型 `id`（不是內建 Claude 模型）會跳過其 `upstream_model:` 對應中不存在的上游。閘道按順序嘗試每個上游上的內建模型，並在對應中沒有項目時使用提供者的預設 ID，因此對於內建模型，對應改變上游接收的 ID 而不是是否嘗試它；拒絕 ID 的上游遵循與任何其他上游錯誤相同的[故障轉移規則](#upstreams)。 |732| 模型範圍路由 | 只有自訂模型 `id`（不是內建 Claude 模型）會跳過其 `upstream_model:` 對應中不存在的上游。`mantle` 上游僅針對其 [`models` 欄位](#amazon-bedrock-mantle-endpoint)中列出的模型進行嘗試。在其他每個上游上，閘道按順序嘗試內建模型，並在對應中沒有項目時使用提供者的預設 ID，因此對於內建模型，對應改變的是上游接收的 ID，而不是是否嘗試該上游；拒絕 ID 的上游遵循與任何其他上游錯誤相同的[故障轉移規則](#upstreams)。 |

694 733

695在雲提供者之間或直接 Anthropic API 之間故障轉移會改變哪些協議、地理位置和其他條款管理請求。734在雲提供者之間故障轉移，或故障轉移到直接 Anthropic API，會改變哪些協議、地理位置和其他條款管理該請求。

696 735

697CLI 對閘道應用相同的功能閘控，無論哪個上游服務給定請求，因此故障轉移不會傳送上游會拒絕的正文欄位。736無論哪個上游服務給定請求，CLI 對閘道都應用相同的功能閘控，因此故障轉移不會傳送上游會拒絕的正文欄位。

698 737

699<h2 id="optional-sections">738<h2 id="optional-sections">

700 選用區段739 選用區段

846 - match: {}885 - match: {}

847 cli:886 cli:

848 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]887 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]

888 # 讓 /model 中的 Default 選項在每個原則的

889 # 清單內解析。eng-contractors 原則繼承 enforceAvailableModels。

890 enforceAvailableModels: true

849```891```

850 892

851`match: {}` 全部捕捉（按慣例列在最後）被視為基礎層。每個其他原則從全部捕捉繼承它未設定的任何金鑰，因此每個角色項目只需列出與組織預設不同的內容。合併規則取決於金鑰類型：893`match: {}` 全部捕捉（按慣例列在最後）被視為基礎層。每個其他原則從全部捕捉繼承它未設定的任何金鑰，因此每個角色項目只需列出與組織預設不同的內容。合併規則取決於金鑰類型：

854* **拒絕清單和 hook 陣列**：`permissions.deny`、`permissions.ask`、`disabledMcpjsonServers`、`deniedMcpServers`、`blockedMarketplaces` 和每個 `hooks` 事件類型陣列。這些取基礎和原則的聯集，因此組織範圍的拒絕或稽核 hook 不會被每個角色覆寫意外丟棄。896* **拒絕清單和 hook 陣列**：`permissions.deny`、`permissions.ask`、`disabledMcpjsonServers`、`deniedMcpServers`、`blockedMarketplaces` 和每個 `hooks` 事件類型陣列。這些取基礎和原則的聯集，因此組織範圍的拒絕或稽核 hook 不會被每個角色覆寫意外丟棄。

855* **記錄類型金鑰**：`env`、`modelOverrides` 和 `skillOverrides`。這些淺合併，因此每個角色 `env` 區塊覆寫它設定的金鑰並從基礎繼承其餘的。897* **記錄類型金鑰**：`env`、`modelOverrides` 和 `skillOverrides`。這些淺合併，因此每個角色 `env` 區塊覆寫它設定的金鑰並從基礎繼承其餘的。

856 898

857`availableModels` 也在 `/v1/messages` 伺服器端強制執行，因此被拒絕的模型返回 `400`，無論用戶端傳送什麼。899`availableModels` 也在 `/v1/messages` 伺服器端強制執行，因此被拒絕的模型返回 `400`，無論用戶端傳送什麼。空清單會拒絕每個模型。此檢查也涵蓋開發者選擇模型之前工作階段啟動時所使用的模型，因此請[讓工作階段從原則允許的模型啟動](#start-sessions-on-a-model-the-policy-allows)。

858 900

859gateway 在轉發請求之前驗證 `model` 值本身，因此格式不正確的值永遠不會到達上游。它在兩種情況下以 `400` 拒絕請求：901gateway 在轉發請求之前驗證 `model` 值本身，因此格式不正確的值永遠不會到達上游。它在兩種情況下以 `400` 拒絕請求：

860 902

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

882</Note>924</Note>

883 925

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

927 讓工作階段從原則允許的模型啟動

928</h4>

929

930如果 `availableModels` 未包含 Claude Code 的預設模型，工作階段會收到 `400` 回應，直到開發者選擇列出的模型（例如使用 `/model`）。在 gateway 工作階段中，預設模型是 `opus` 別名解析到的 Opus 模型，而單獨設定 `availableModels` 不會變更它。

931

932要修正此問題，請在相同的 `cli` 區塊中設定 [`enforceAvailableModels: true`](/docs/zh-TW/model-config#enforce-the-allowlist-for-the-default-model)，然後檢查清單包含哪種項目：

933

934* **別名（例如 `sonnet`）或內建 ID（例如 `claude-sonnet-4-6`）**：工作階段會從其中一個模型啟動，且 `/model` 中的 Default 選項會解析到該模型

935* **清單中沒有別名或內建 ID**：工作階段可能仍會從內建預設模型啟動，因此也請在該原則的 `cli` 區塊中將 [`model`](/docs/zh-TW/model-config#control-the-model-users-run-on) 設定為其中一個列出的 ID

936

937此原則列出一個由 [`models`](#models) 定義的自訂 ID，並讓工作階段從該 ID 啟動：

938

939```yaml theme={null}

940managed:

941 policies:

942 - match: { groups: [restricted-projects] }

943 cli:

944 availableModels: [claude-opus-restricted]

945 enforceAvailableModels: true

946 model: claude-opus-restricted

947```

948

884<h4 id="matcher-values-that-stop-the-gateway-at-boot">949<h4 id="matcher-values-that-stop-the-gateway-at-boot">

885 在啟動時停止 gateway 的 matcher 值950 在啟動時停止 gateway 的 matcher 值

886</h4>951</h4>

918 cli:983 cli:

919 # 模型存取（也在 /v1/messages 伺服器端強制執行）984 # 模型存取（也在 /v1/messages 伺服器端強制執行）

920 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]985 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]

986 enforceAvailableModels: true # Default 在清單內解析

921 987

922 # 權限原則988 # 權限原則

923 permissions:989 permissions:

1039 - match: { groups: [eng-contractors] }1105 - match: { groups: [eng-contractors] }

1040 cli:1106 cli:

1041 availableModels: [claude-sonnet-4-6]1107 availableModels: [claude-sonnet-4-6]

1108 enforceAvailableModels: true

1042 desktop:1109 desktop:

1043 isLocalDevMcpEnabled: false1110 isLocalDevMcpEnabled: false

1044 disableAutoUpdates: true1111 disableAutoUpdates: true

1432 # region: us-east-11499 # region: us-east-1

1433 # auth: {}1500 # auth: {}

1434 1501

1502 # - provider: mantle

1503 # region: us-east-1

1504 # models: [claude-opus-4-8, claude-opus-4-7, claude-haiku-4-5]

1505 # auth: {}

1506

1435 # - provider: anthropicAws1507 # - provider: anthropicAws

1436 # region: us-east-11508 # region: us-east-1

1437 # workspace_id: wrkspc_...1509 # workspace_id: wrkspc_...

1454 upstream_model:1526 upstream_model:

1455 anthropic: claude-opus-4-81527 anthropic: claude-opus-4-8

1456 # bedrock: us.anthropic.claude-opus-4-81528 # bedrock: us.anthropic.claude-opus-4-8

1529 # mantle: anthropic.claude-opus-4-8

1457 # anthropicAws: claude-opus-4-81530 # anthropicAws: claude-opus-4-8

1458 # vertex: claude-opus-4-81531 # vertex: claude-opus-4-8

1459 # foundry: <your-opus-deployment-name>1532 # foundry: <your-opus-deployment-name>

1471 - match: { groups: [contractors] }1544 - match: { groups: [contractors] }

1472 cli:1545 cli:

1473 availableModels: [claude-haiku-4-5]1546 availableModels: [claude-haiku-4-5]

1474 # 將預設選擇器選項限制為 availableModels 而不是

1475 # 層級預設，因此承包商不會在預設上獲得 400。

1476 enforceAvailableModels: true

1477 # allow 自動批准這些工具；它不阻止其餘的。1547 # allow 自動批准這些工具；它不阻止其餘的。

1478 # 新增 deny 規則以限制工具。1548 # 新增 deny 規則以限制工具。

1479 permissions: { allow: [Read, Grep] }1549 permissions: { allow: [Read, Grep] }

1480 - match: {}1550 - match: {}

1481 cli:1551 cli:

1482 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]1552 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]

1553 # 將預設選擇器選項限制為每個原則的 availableModels，

1554 # 而不是內建預設，因此任何角色都不會在預設上獲得 400。

1555 # 承包商原則會繼承此鍵。

1556 enforceAvailableModels: true

1483 permissions:1557 permissions:

1484 allow: [Read, Grep, Bash, Edit]1558 allow: [Read, Grep, Bash, Edit]

1485 deny: ["WebFetch"]1559 deny: ["WebFetch"]

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

Details

429 429

430當請求的標頭總計超過 256 KiB，或超過 [`limits.max_request_header_bytes`](/docs/zh-TW/claude-apps-gateway-config#http-tuning)（若您有設定）時，gateway 會回應 `431`。它不會為這些請求寫入任何日誌行或稽核事件。v2.1.284 之前的 gateway 版本在超過 16 KiB 時即回應 `431`。430當請求的標頭總計超過 256 KiB，或超過 [`limits.max_request_header_bytes`](/docs/zh-TW/claude-apps-gateway-config#http-tuning)（若您有設定）時，gateway 會回應 `431`。它不會為這些請求寫入任何日誌行或稽核事件。v2.1.284 之前的 gateway 版本在超過 16 KiB 時即回應 `431`。

431 431

432需要變更的內容取決於 gateway 的版本和設定：432請從以下第一個適用於您 gateway 的項目開始：

433 433

434* **早於 v2.1.284 的 gateway**：升級 gateway434* **早於 v2.1.284 的 gateway**：升級 gateway

435* **已設定 `limits.max_request_header_bytes`**：提高該值或移除該設定鍵435* **已設定 `limits.max_request_header_bytes`**：提高該值或移除該設定鍵

436* **以上皆不適用，或之後仍出現 `431`**：讓您的 IdP 發出較少的群組。[身分提供者設定](#identity-provider-setup)說明 Okta、Microsoft Entra ID 和 Google Workspace 如何提供群組436* **以上皆不適用，或之後仍出現 `431`**：讓您的 IdP 發出較少的群組。[身分提供者設定](#identity-provider-setup)說明 Okta、Microsoft Entra ID 和 Google Workspace 如何提供群組

437 437

438精簡群組宣告時，請保留您在以下設定中指定的群組，這些設定決定開發者的存取權、原則和支出上限：

439

440* **[`oidc.allowed_groups`](/docs/zh-TW/claude-apps-gateway-config#oidc)**：決定誰可以登入

441* **[`admin.admin_groups`](/docs/zh-TW/claude-apps-gateway-config#admin)**：決定誰可以使用其 gateway 工作階段呼叫管理 API

442* **[`managed.policies`](/docs/zh-TW/claude-apps-gateway-config#managed) 中的 `match.groups`**：決定哪個原則適用於開發者

443* **`rbac_group` [支出上限](/docs/zh-TW/claude-apps-gateway-spend-limits)**：決定哪些群組上限適用於開發者

444

438<h2 id="related">445<h2 id="related">

439 相關446 相關

440</h2>447</h2>

claude-code-on-the-web.md +103 −63

Details

12 12

13雲端工作階段是在雲端基礎設施上執行的 Claude Code 工作階段，而不是在您的機器上執行。預設情況下，它在 Anthropic 管理的基礎設施上執行，或在您的組織的[自託管環境](/docs/zh-TW/self-hosted-environments)上執行（如果路由到那裡）。工作階段在您關閉筆記型電腦後仍會繼續執行，您可以從任何裝置檢查或控制它。13雲端工作階段是在雲端基礎設施上執行的 Claude Code 工作階段，而不是在您的機器上執行。預設情況下，它在 Anthropic 管理的基礎設施上執行，或在您的組織的[自託管環境](/docs/zh-TW/self-hosted-environments)上執行（如果路由到那裡）。工作階段在您關閉筆記型電腦後仍會繼續執行，您可以從任何裝置檢查或控制它。

14 14

15若要讓雲端工作階段從 GitHub 複製您的程式碼並推送分支，請使用其中一種 [GitHub 連接方式](#github-authentication-options)連接 GitHub。如果您的儲存庫位於 GitLab、Bitbucket 或其他主機上，請參閱[平台限制](#limitations)以了解可用的功能。

15您可以從以下任何介面啟動雲端工作階段：17您可以從以下任何介面啟動雲端工作階段：

16 18

17* **瀏覽器**：[claude.ai/code](https://claude.ai/code)，也稱為網頁版 Claude Code19* **瀏覽器**：[claude.ai/code](https://claude.ai/code)，也稱為網頁版 Claude Code

20* **終端**：[`claude --cloud`](#from-terminal-to-cloud)22* **終端**：[`claude --cloud`](#from-terminal-to-cloud)

21* **例行工作**：[排程和觸發的執行](/docs/zh-TW/routines)每次都作為雲端工作階段執行23* **例行工作**：[排程和觸發的執行](/docs/zh-TW/routines)每次都作為雲端工作階段執行

22 24

23若要讓 Claude 為一項工作啟動並追蹤許多雲端工作階段，請使用[專案](/docs/zh-TW/claude-projects)。在您的終端、IDE 或選擇了 **Local** 的桌面應用程式中的工作階段在您自己的機器上執行。若要從您的手機或瀏覽器控制其中一個本機工作階段，請使用[遠端控制](/docs/zh-TW/remote-control)。25完成設定後，請使用本頁在終端機和雲端之間移動工作、管理和共享工作階段、為 pull request 開啟自動修復，以及進行疑難排解。

~~25<Tip>~~

~~26 初次使用雲端工作階段？從[開始使用](/docs/zh-TW/web-quickstart)開始，連接您的 GitHub 帳戶並提交您的第一個任務。~~

~~27</Tip>~~

28 26

~~29本頁涵蓋：~~27<Note>

28 以下情況在其他頁面中說明：

30 29

~~31* [雲端環境](#cloud-environments)：工作階段執行的位置，以及如何配置該位置~~30 * **啟動您的第一個雲端工作階段**：[開始使用雲端工作階段](/docs/zh-TW/web-quickstart)會連接 GitHub，並引導您在瀏覽器中完成一項任務

~~32* [GitHub 驗證選項](#github-authentication-options)：連接 GitHub 的兩種方式~~31 * **為一項工作使用多個雲端工作階段**：[專案](/docs/zh-TW/claude-projects)會讓 Claude 為您啟動並追蹤這些工作階段

~~33* [在終端和雲端之間移動任務](#move-tasks-between-terminal-and-cloud)，使用 `--cloud` 和 `--teleport`~~32 * **從另一部裝置控制本機工作階段**：在您的終端機、IDE 或選擇了 **Local** 的 Desktop 應用程式中的工作階段會在您的機器上執行，而 [Remote Control](/docs/zh-TW/remote-control) 可讓您從手機或瀏覽器存取這些工作階段

~~34* [使用工作階段](#work-with-sessions)：權限模式、檢查、共享、封存、刪除~~33</Note>

~~35* [自動修復拉取請求](#auto-fix-pull-requests)：自動回應 CI 失敗和審查評論~~

~~36* [安全性和隔離](#security-and-isolation)：工作階段如何隔離~~

~~37* [限制](#limitations)：速率限制和平台限制~~

38 34

39<h2 id="cloud-environments">35<h2 id="cloud-environments">

40 雲端環境36 雲端環境

41</h2>37</h2>

42 38

43每個雲端工作階段都在一個[雲端環境](/docs/zh-TW/cloud-environments)中執行，這是一個已保存的設定，控制網路存取、環境變數和設定指令碼。如果您還沒有環境，上線會設定一個**預設**環境，具有[**信任**網路存取](/docs/zh-TW/cloud-environments#access-levels)，要麼為您建立它，要麼要求您建立它。請參閱[預設環境](/docs/zh-TW/cloud-environments#the-default-environment)，了解在您的計畫上會發生哪種情況，以及當您有多個環境時工作階段如何選擇環境。39每個雲端工作階段都在一個[雲端環境](/docs/zh-TW/cloud-environments)中執行，這是一個已保存的設定，控制網路存取、環境變數和設定指令碼。

44 40

45相同的環境適用於您啟動雲端工作階段的任何地方：網頁、終端、[Claude Tag](https://claude.com/docs/claude-tag/overview)、[例行工作](/docs/zh-TW/routines)，以及行動和 Desktop 應用程式。Claude Tag 頻道工作階段僅使用組織級別環境，要麼是[共享環境](/docs/zh-TW/cloud-environments#organization-shared-environments)，要麼是[自託管環境](/docs/zh-TW/self-hosted-environments)。41* **您的第一個環境**：如果您還沒有環境，上線會設定一個**預設**環境，具有[**信任**網路存取](/docs/zh-TW/cloud-environments#access-levels)，要麼為您建立它，要麼要求您建立它。請參閱[預設環境](/docs/zh-TW/cloud-environments#the-default-environment)，了解在您的計畫上會發生哪種情況

46 42* **工作階段使用哪個環境**：請參閱[預設環境](/docs/zh-TW/cloud-environments#the-default-environment)，了解當您有多個環境時工作階段如何選擇環境

47請參閱[設定雲端環境](/docs/zh-TW/cloud-environments)以變更環境允許的內容、設定變數或新增設定指令碼，以及[已安裝的工具](/docs/zh-TW/cloud-environments#installed-tools)以了解工作階段在沒有任何設定的情況下包含的內容。43* **變更工作階段在啟動時可以存取或執行的內容**：請參閱[設定雲端環境](/docs/zh-TW/cloud-environments)

44* **在沒有任何設定的情況下已安裝的內容**：請參閱[已安裝的工具](/docs/zh-TW/cloud-environments#installed-tools)

48 45

49<h2 id="github-authentication-options">46<h2 id="github-authentication-options">

50 GitHub 驗證選項47 GitHub 驗證選項

59 56

~~60在儲存庫上安裝 Claude GitHub App 也會為其中的提取請求啟用[自動修復](#auto-fix-pull-requests)。~~57以下功能取決於儲存庫上是否已安裝 Claude GitHub App：

61 58

62[專案](/docs/zh-TW/claude-projects)中的執行緒需要在它們複製的每個儲存庫上安裝 Claude GitHub App，無論您使用哪種方法連接。請參閱[設定 GitHub 存取](/docs/zh-TW/claude-projects#set-up-github-access)。59* **自動修復**：在儲存庫上安裝 Claude GitHub App 也會為其中的 pull request 啟用[自動修復](#auto-fix-pull-requests)

60* **專案**：[專案](/docs/zh-TW/claude-projects)中的執行緒需要在它們複製的每個儲存庫上安裝 Claude GitHub App，無論您使用哪種方法連接。請參閱[設定 GitHub 存取](/docs/zh-TW/claude-projects#set-up-github-access)

63 61

64在 Anthropic 代管的環境中，您的 GitHub 認證保持在 Anthropic 伺服器上加密，永遠不會進入工作階段的虛擬機器。來自虛擬機器的 GitHub 操作會通過 [GitHub proxy](/docs/zh-TW/cloud-environments#github-proxy)，它在伺服器端附加認證。62在 Anthropic 代管的環境中，您的 GitHub 認證保持在 Anthropic 伺服器上加密，永遠不會進入工作階段的虛擬機器。來自虛擬機器的 GitHub 操作會通過 [GitHub proxy](/docs/zh-TW/cloud-environments#github-proxy)，它在伺服器端附加認證。

65 63

66有關 `/schedule` 如何在建立例行工作之前檢查儲存庫存取，請參閱[儲存庫和分支權限](/docs/zh-TW/routines#repositories-and-branch-permissions)。有關 `/web-setup` 的逐步說明，請參閱[從您的終端連接](/docs/zh-TW/web-quickstart#connect-from-your-terminal)，包括 `/web-setup` 儲存的內容以及如何移除它。64有關 `/web-setup` 的逐步說明，請參閱[從您的終端機連接](/docs/zh-TW/web-quickstart#connect-from-your-terminal)，包括 `/web-setup` 儲存的內容以及如何移除它。

68快速網頁設定是一個組織設定，讓成員使用 `/web-setup` 連接 GitHub，在瀏覽器上線期間跳過 Claude GitHub App 安裝提示，並讓瀏覽器上線為他們建立[**預設**環境](/docs/zh-TW/cloud-environments#the-default-environment)，而不是顯示環境表單。在 Team 和 Enterprise 計畫上，預設情況下它是關閉的，這會隱藏 `/web-setup`。[擁有者](/docs/zh-TW/server-managed-settings#access-control)可以在 [**管理設定 > Claude Code**](https://claude.ai/admin-settings/claude-code) 使用**快速網頁設定**切換來開啟它。

69 65

70<Note>66<Note>

71 啟用[零資料保留](/docs/zh-TW/zero-data-retention)的組織無法使用 `/web-setup` 或其他雲端工作階段功能。67 啟用[零資料保留](/docs/zh-TW/zero-data-retention)的組織無法使用 `/web-setup` 或其他雲端工作階段功能。

72</Note>68</Note>

73 69

70<h3 id="quick-setup-for-team-and-enterprise">

71 Team 和 Enterprise 的快速設定

72</h3>

74快速設定是一個組織設定，可減少成員在 GitHub 和環境設定上的步驟。在 Team 和 Enterprise 計畫上，預設情況下它是關閉的。

76開啟後，成員會有以下變化：

78* **`/web-setup`**：成員可以使用 `/web-setup` 連接 GitHub。此設定關閉時，該命令會被隱藏

79* **GitHub App 提示**：瀏覽器上線會跳過 Claude GitHub App 安裝提示

80* **第一個環境**：瀏覽器上線會為成員建立[**預設**環境](/docs/zh-TW/cloud-environments#the-default-environment)，而不是顯示環境表單

82[擁有者](/docs/zh-TW/server-managed-settings#access-control)可以在 [**組織設定 > Claude Code**](https://claude.ai/admin-settings/claude-code) 使用**快速設定**切換來開啟它。

74<h2 id="move-tasks-between-terminal-and-cloud">84<h2 id="move-tasks-between-terminal-and-cloud">

75 在終端機和雲端之間移動任務85 在終端機和雲端之間移動任務

76</h2>86</h2>

78這些工作流程需要 [Claude Code CLI](/docs/zh-TW/quickstart) 登入到同一個 claude.ai 帳戶。您可以從終端機啟動新的雲端工作階段，或將雲端工作階段拉入您的終端機以在本機繼續。雲端工作階段即使在您關閉筆記型電腦後仍會保留，您可以從任何地方（包括 Claude 行動應用程式）監控它們。88這些工作流程需要 [Claude Code CLI](/docs/zh-TW/quickstart) 登入到同一個 claude.ai 帳戶。您可以從終端機啟動新的雲端工作階段，或將雲端工作階段拉入您的終端機以在本機繼續。雲端工作階段即使在您關閉筆記型電腦後仍會保留，您可以從任何地方（包括 Claude 行動應用程式）監控它們。

79 89

80<Note>90<Note>

81 從 CLI，工作階段交接是單向的：您可以使用 `--teleport` 將雲端工作階段拉入您的終端機，但您無法將現有的終端機工作階段推送到雲端。`--cloud` 旗標搭配任務描述會為您目前的儲存庫建立新的雲端工作階段；搭配 `-p` 和工作階段 ID 或 claude.ai/code URL 時，它會改為 [將訊息加入該現有工作階段的佇列](/docs/zh-TW/claude-code-on-the-web#send-follow-ups-from-the-cli)。[桌面應用程式](/docs/zh-TW/desktop#continue-in-another-surface) 提供 **Continue in** 功能表，可以將本機工作階段傳送到雲端。91 從 CLI，工作階段交接是單向的：您可以使用 `--teleport` 將雲端工作階段拉入您的終端機，但您無法將現有的終端機工作階段推送到雲端。`--cloud` 旗標搭配任務描述會為您目前的儲存庫建立新的雲端工作階段；搭配 `-p` 和工作階段 ID 或 claude.ai/code URL 時，它會改為 [將訊息加入該現有工作階段的佇列](/docs/zh-TW/claude-code-on-the-web#send-follow-ups-from-the-cli)。[桌面應用程式](/docs/zh-TW/desktop#continue-in-another-surface) 可以從其 **Open in** 功能表，將其 Code 分頁中的本機工作階段傳送到雲端。

82</Note>92</Note>

83 93

84<h3 id="from-terminal-to-cloud">94<h3 id="from-terminal-to-cloud">

173 從 CLI 傳送後續訊息183 從 CLI 傳送後續訊息

174</h3>184</h3>

175 185

176一旦雲端工作階段執行，無論它在何處執行，都可以從任何您使用 `claude auth login` 登入的機器上的 `claude` CLI 傳送後續訊息。CLI 使用您的 Anthropic 帳戶認證進行驗證，不傳送任何本機工作階段狀態，因此命令不需要從啟動工作階段的機器執行，在每個 shell 中都相同，包括 PowerShell。186一旦雲端工作階段執行，無論它在何處執行，都可以從任何您使用 `claude auth login` 登入的機器上的 `claude` CLI 傳送後續訊息。CLI 使用您的 Anthropic 帳戶憑證進行身分驗證，不傳送任何本機工作階段狀態，因此命令不需要從啟動工作階段的機器執行。

177 187

178該命令發佈一條訊息並退出：188該命令發佈一條訊息並退出：

179 189

189 `--cloud` 需要 Anthropic 帳戶。當 Claude Code 針對 Amazon Bedrock、Google Cloud 的 Agent Platform 或其他第三方提供者進行設定時，它不可用。僅透過 `ANTHROPIC_BASE_URL` 設定的 [LLM gateway](/docs/zh-TW/llm-gateway) 不算作此檢查的第三方提供者，但您仍需要使用 `claude auth login` 登入。您組織的 `allow_remote_sessions` 原則也必須啟用。擁有者可以在 claude.ai/admin-settings/claude-code 的 Claude Code 管理設定中開啟它。199 `--cloud` 需要 Anthropic 帳戶。當 Claude Code 針對 Amazon Bedrock、Google Cloud 的 Agent Platform 或其他第三方提供者進行設定時，它不可用。僅透過 `ANTHROPIC_BASE_URL` 設定的 [LLM gateway](/docs/zh-TW/llm-gateway) 不算作此檢查的第三方提供者，但您仍需要使用 `claude auth login` 登入。您組織的 `allow_remote_sessions` 原則也必須啟用。擁有者可以在 claude.ai/admin-settings/claude-code 的 Claude Code 管理設定中開啟它。

190</Note>200</Note>

191 201

192<h4 id="output-and-errors">202<h4 id="output">

193 輸出和錯誤203 輸出

194</h4>204</h4>

195 205

196成功時，命令會列印工作階段 ID 和檢視工作階段的連結：206成功時，命令會列印工作階段 ID 和檢視工作階段的連結：

203 213

204傳遞 `--output-format json` 以取得機器可讀的結果：成功時為 `{ok, session_id, url}`，或當傳送失敗時為 `{ok: false, session_id, error}`，例如當工作階段遺失或已封存時。設定錯誤（例如不支援的提供者或已停用的組織原則）會列印到 stderr，不含 JSON。`--output-format stream-json` 不支援 `--cloud <session-id>`。214傳遞 `--output-format json` 以取得機器可讀的結果：成功時為 `{ok, session_id, url}`，或當傳送失敗時為 `{ok: false, session_id, error}`，例如當工作階段遺失或已封存時。設定錯誤（例如不支援的提供者或已停用的組織原則）會列印到 stderr，不含 JSON。`--output-format stream-json` 不支援 `--cloud <session-id>`。

205 215

206CLI 會在錯誤前加上 `Error: ` 前綴。失敗的傳遞會包裝為 `failed to send message to cloud session <id>: <reason>`。216如果傳送失敗，請參閱 [傳送到雲端工作階段時的錯誤](#errors-when-sending-to-a-cloud-session)。

~~207~~

208| 訊息 | 它的意思 |

209| - | - |

210| `Cloud sessions aren't available with <provider>. They run on Anthropic's infrastructure and require an Anthropic account.` | Claude Code 針對第三方提供者進行設定。訊息會使用您的設定使用的標籤命名提供者，例如 `Amazon Bedrock` 或 `Google Vertex AI`。移除該提供者的設定，例如取消設定 `CLAUDE_CODE_USE_BEDROCK`，並使用 Anthropic 帳戶登入（`claude auth login`）。 |

211| `Cloud sessions are disabled by your organization's policy. Contact your organization admin to enable them.` | `allow_remote_sessions` 組織原則已關閉。 |

212| `Couldn't verify your organization's policy for cloud sessions. Check your network connection and try again.` | Claude Code 無法擷取您的組織原則，因此它拒絕傳送而不是假設雲端工作階段被允許。檢查您的網路連線並重試。 |

213| `Attaching to an existing cloud session is not enabled for your account.` | 您執行了 `--cloud <session-id>` 而沒有 `-p`。使用 `claude -p "your message" --cloud <session-id>` 傳送訊息。 |

214| `Session not found: <id>` | ID 或 URL 與您可以存取的工作階段不符。根據工作階段的 claude.ai/code URL 檢查它。 |

215| `cloud session <id> is archived and cannot accept new messages` | 工作階段已被封存。改為啟動新工作階段。 |

216 217

217<h3 id="from-cloud-to-terminal">218<h3 id="from-cloud-to-terminal">

218 從雲端到終端機219 從雲端到終端機

239| 需求 | 詳細資訊 |240| 需求 | 詳細資訊 |

240| - | - |241| - | - |

241| 乾淨的 git 狀態 | 您的工作目錄必須沒有未提交的變更。如果需要，Teleport 會提示您隱藏變更。 |242| 乾淨的 git 狀態 | 您的工作目錄必須沒有未提交的變更。如果需要，Teleport 會提示您隱藏變更。 |

242| 正確的儲存庫 | 您必須從同一儲存庫的簽出執行 `--teleport`，而不是分叉。如果您從不同儲存庫的簽出執行它，Claude Code 會顯示一個錯誤，命名工作階段的儲存庫和您的簽出。在 v2.1.219 之前，錯誤沒有命名您的簽出的儲存庫。如果 Claude Code 無法將您的遠端解析為主機名稱，例如 SSH 主機別名如 `git@work:owner/repo.git`，它會要求您確認，並在遠端的擁有者和儲存庫名稱與工作階段的儲存庫相符時接受簽出。 |243| 正確的儲存庫 | 您必須從同一儲存庫的簽出執行 `--teleport`，而不是分叉。如果您從不同儲存庫的簽出執行它，Claude Code 會顯示一個錯誤，命名工作階段的儲存庫和您的簽出的儲存庫。如果 Claude Code 無法將您的遠端解析為主機名稱，例如 SSH 主機別名如 `git@work:owner/repo.git`，它會要求您確認，並在遠端的擁有者和儲存庫名稱與工作階段的儲存庫相符時接受簽出。 |

243| 分支可用 | 雲端工作階段的分支必須已推送到遠端。Teleport 會自動擷取並簽出它。 |244| 分支可用 | 雲端工作階段的分支必須已推送到遠端。Teleport 會自動擷取並簽出它。 |

244| 相同帳戶 | 您必須驗證到雲端工作階段中使用的同一 claude.ai 帳戶。 |245| 相同帳戶 | 您必須驗證到雲端工作階段中使用的同一 claude.ai 帳戶。 |

245 246

249 `--teleport` 不可用250 `--teleport` 不可用

250</h4>251</h4>

251 252

252Teleport 需要 claude.ai 訂閱驗證。如果您透過 API 金鑰進行驗證，請執行 `/login` 以改為使用您的 claude.ai 帳戶登入。如果錯誤命名您的提供者，雲端工作階段無法透過第三方提供者取得；請參閱 [error table](#output-and-errors)。如果您已透過 claude.ai 登入且 `--teleport` 仍然不可用，您的組織可能已停用雲端工作階段。253Teleport 需要 claude.ai 訂閱身分驗證。請找出符合您情況的項目：

254

255* **您透過 API 金鑰進行身分驗證**：執行 `/login` 以改為使用您的 claude.ai 帳戶登入

256* **錯誤命名了您的提供者**：雲端工作階段無法透過第三方提供者取得。請參閱 [錯誤表](#errors-when-sending-to-a-cloud-session)

257* **您已透過 claude.ai 登入**：您的組織可能已停用雲端工作階段

253 258

254<h2 id="work-with-sessions">259<h2 id="work-with-sessions">

255 使用工作階段260 使用工作階段

257 262

258工作階段出現在 claude.ai/code 的側邊欄中。從那裡，您可以檢查變更、與隊友共享、封存完成的工作或永久刪除工作階段。263工作階段出現在 claude.ai/code 的側邊欄中。從那裡，您可以檢查變更、與隊友共享、封存完成的工作或永久刪除工作階段。

259 264

260<h3 id="take-back-a-queued-message">265<h3 id="permission-modes-in-cloud-sessions">

261 取回已排隊的訊息266 雲端工作階段中的權限模式

262</h3>267</h3>

263 268

264如果您在 Claude 工作時發送訊息，該訊息會排隊，直到 Claude 讀取它。若要取回已排隊的訊息，請點擊它上面的 ✕。文字會返回到訊息框，以便您可以編輯它或發送其他內容。269您可以從[模式下拉式功能表](/docs/zh-TW/permission-modes#switch-permission-modes)選擇雲端工作階段的[權限模式](/docs/zh-TW/permission-modes)，無論是在您建立任務時還是在工作階段執行時。

265 270

266如果 Claude 已經讀取訊息，它會保留在對話中。271當您執行下列任一操作時，Claude Code 會以工作階段當時所在的權限模式恢復該工作階段：

272

273* 重新開啟其 Anthropic 託管[環境已過期](#environment-expired)的工作階段

274* 向自託管執行器[在閒置時釋放](/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags)的工作階段發送訊息

275

276<h3 id="review-changes">

277 檢查變更

278</h3>

279

280每個工作階段顯示一個差異指示器，其中包含新增和移除的行數，例如 `+42 -18`。選擇它以開啟差異檢視、在特定行上留下內聯評論，並使用您的下一條訊息將它們發送給 Claude。

281

282差異檢視預設會將工作階段的變更與其基礎分支進行比較。若要與儲存庫中的任何其他分支進行比較，請選擇**比較對象**並選擇一個。

283

284Claude Code 從原始 git blob 內容計算這些差異，因此儲存庫中設定的差異驅動器和 `textconv` 篩選器不適用。

285

286以下步驟在其他地方有說明：

287

288* **完整逐步說明，包括 PR 建立**：請參閱[檢查和迭代](/docs/zh-TW/web-quickstart#review-and-iterate)

289* **讓 Claude 自動監控 PR 以查找 CI 失敗和審查評論**：請參閱[自動修復 pull requests](#auto-fix-pull-requests)

267 290

268<h3 id="manage-context">291<h3 id="manage-context">

269 管理上下文292 管理上下文

291 314

292[Agent teams](/docs/zh-TW/agent-teams) 預設關閉，但可以通過將 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 新增到您的[環境變數](/docs/zh-TW/cloud-environments#set-environment-variables)來啟用。315[Agent teams](/docs/zh-TW/agent-teams) 預設關閉，但可以通過將 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 新增到您的[環境變數](/docs/zh-TW/cloud-environments#set-environment-variables)來啟用。

293 316

294<h3 id="permission-modes-in-cloud-sessions">317<h3 id="take-back-a-queued-message">

295 雲端工作階段中的權限模式318 取回已排隊的訊息

296</h3>

~~297~~

298您可以從[模式下拉式功能表](/docs/zh-TW/permission-modes#switch-permission-modes)選擇雲端工作階段的[權限模式](/docs/zh-TW/permission-modes)，無論是在您建立任務時還是在工作階段執行時。當您重新開啟其 Anthropic 託管[環境已過期](#environment-expired)的工作階段，或向工作階段發送訊息時，該工作階段的自託管執行器[在閒置時釋放](/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags)，Claude Code 會在它所在的權限模式中恢復工作階段。

~~299~~

300<h3 id="review-changes">

301 檢查變更

302</h3>319</h3>

303 320

304每個工作階段顯示一個差異指示器，其中包含新增和移除的行數，例如 `+42 -18`。選擇它以開啟差異檢視、在特定行上留下內聯評論，並使用您的下一條訊息將它們發送給 Claude。321如果您在 Claude 工作時發送訊息，該訊息會排隊，直到 Claude 讀取它。若要取回已排隊的訊息，請點擊它上面的 ✕。文字會返回到訊息框，以便您可以編輯它或發送其他內容。

~~305~~

306差異檢視預設會將工作階段的變更與其基礎分支進行比較。若要與儲存庫中的任何其他分支進行比較，請選擇**比較對象**並選擇一個。

~~307~~

308Claude Code 從原始 git blob 內容計算這些差異，包括 Claude 編輯時顯示的每個檔案差異，因此儲存庫中配置的差異驅動器和 `textconv` 篩選器不適用。對於不是工作階段自己簽出之一的儲存庫中的檔案，例如在工作階段期間在工作區內複製的檔案，每個檔案差異會顯示 Claude 的編輯本身，而不是 git 比較。

309 322

310請參閱[檢查和迭代](/docs/zh-TW/web-quickstart#review-and-iterate)以了解完整逐步說明，包括 PR 建立。若要讓 Claude 自動監控 PR 以查找 CI 失敗和審查評論，請參閱[自動修復拉取請求](#auto-fix-pull-requests)。323如果 Claude 已經讀取訊息，它會保留在對話中。

311 324

312<h3 id="share-sessions">325<h3 id="share-sessions">

313 共享工作階段326 共享工作階段

319 從 Enterprise 或 Team 帳戶共享332 從 Enterprise 或 Team 帳戶共享

320</h4>333</h4>

321 334

322對於 Enterprise 和 Team 帳戶，兩個可見性選項是**私人**和**Team**。Team 可見性使工作階段對您的 claude.ai 組織的其他成員可見。[Slack 中的 Claude](/docs/zh-TW/slack)工作階段會自動以 Team 可見性共享。335對於 Enterprise 和 Team 帳戶，共享的運作方式如下：

323 336

324儲存庫存取驗證預設啟用，基於連接到收件者帳戶的 GitHub 帳戶。您帳戶的顯示名稱對所有有存取權限的收件者可見。337* **可見性選項**：**私人**和**Team**。Team 可見性使工作階段對您的 claude.ai 組織的其他成員可見

338* **儲存庫存取**：驗證預設啟用，基於連接到收件者帳戶的 GitHub 帳戶

339* **您的名稱**：您帳戶的顯示名稱對所有有存取權限的收件者可見

340* **Slack 工作階段**：[Slack 中的 Claude](/docs/zh-TW/slack)工作階段會自動以 Team 可見性共享

325 341

326<h4 id="share-from-a-max-or-pro-account">342<h4 id="share-from-a-max-or-pro-account">

327 從 Max 或 Pro 帳戶共享343 從 Max 或 Pro 帳戶共享

328</h4>344</h4>

329 345

330對於 Max 和 Pro 帳戶，兩個可見性選項是**私人**和**公開**。公開可見性使工作階段對任何登入 claude.ai 的使用者可見。346對於 Max 和 Pro 帳戶，共享的運作方式如下：

331 347

332在共享之前檢查您的工作階段是否包含敏感內容。工作階段可能包含來自私人 GitHub 儲存庫的程式碼和認證。儲存庫存取驗證預設未啟用。348* **可見性選項**：**私人**和**公開**。公開可見性使工作階段對任何登入 claude.ai 的使用者可見

349* **儲存庫存取**：驗證預設未啟用

350* **敏感內容**：在共享之前檢查您的工作階段。工作階段可能包含來自私人 GitHub 儲存庫的程式碼和憑證

333 351

334若要要求收件者具有儲存庫存取權限，或從共享工作階段中隱藏您的名稱，請前往 [**設定 > Claude Code > 共享設定**](https://claude.ai/settings/claude-code)。352若要要求收件者具有儲存庫存取權限，或從共享工作階段中隱藏您的名稱，請前往 [**設定 > Claude Code > 共享設定**](https://claude.ai/settings/claude-code)。

335 353

421 無法取得組織 UUID439 無法取得組織 UUID

422</h3>440</h3>

423 441

424`claude --cloud` 和 `claude --teleport` 需要使用 claude.ai 帳戶登入。如果您使用 API 金鑰進行驗證，或您的儲存帳戶詳細資訊已過期，這些命令會失敗，出現 `Unable to get organization UUID` 或訊息表示 API 金鑰驗證不足。使用 API 金鑰驗證或過期的帳戶詳細資訊，執行 `claude --teleport` 而不使用工作階段 ID 會在工作階段選擇器中顯示 `Error loading Claude Code sessions`，而不是任一訊息，相同的修復適用。442`claude --cloud` 和 `claude --teleport` 需要使用 claude.ai 帳戶登入。如果您使用 API 金鑰進行身分驗證，或您儲存的帳戶詳細資訊已過期，您會看到以下其中一項：

443

444* `Unable to get organization UUID`

445* 表示 API 金鑰身分驗證不足的訊息

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

425 447

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

427 449

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

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

435* 確認您登入到擁有工作階段的相同帳戶457* 確認您登入到擁有工作階段的相同帳戶

436* 如果您看到 `Remote Control may not be available for this organization`，擁有者尚未為您的組織啟用雲端工作階段458* 如果您看到 `Remote Control may not be available for this organization`，擁有者尚未為您的組織啟用雲端工作階段

437 459

460<h3 id="errors-when-sending-to-a-cloud-session">

461 傳送至雲端工作階段時的錯誤

462</h3>

463

464這些錯誤來自使用 [`--cloud <session-id>`](#send-follow-ups-from-the-cli) 執行 `claude`，無論是否搭配 `-p`。CLI 會在錯誤前加上 `Error: ` 前綴。傳送失敗會包裝為 `failed to send message to cloud session <id>: <reason>`。

465

466| 訊息 | 含義 |

467| - | - |

468| `Cloud sessions aren't available with <provider>. They run on Anthropic's infrastructure and require an Anthropic account.` | Claude Code 已設定為使用第三方提供者。訊息會以您的設定所使用的標籤指出提供者名稱，例如 `Amazon Bedrock` 或 `Google Vertex AI`。請移除該提供者的設定，例如取消設定 `CLAUDE_CODE_USE_BEDROCK`，並使用 Anthropic 帳戶登入（`claude auth login`）。 |

469| `Cloud sessions are disabled by your organization's policy. Contact your organization admin to enable them.` | `allow_remote_sessions` 組織政策已關閉。 |

470| `Couldn't verify your organization's policy for cloud sessions. Check your network connection and try again.` | Claude Code 無法取得您組織的政策，因此會拒絕傳送，而不是假設允許雲端工作階段。請檢查您的網路連線並重試。 |

471| `Attaching to an existing cloud session is not enabled for your account.` | 您在未使用 `-p` 的情況下執行了 `--cloud <session-id>`。請使用 `claude -p "your message" --cloud <session-id>` 傳送訊息。 |

472| `Session not found: <id>` | 該 ID 或 URL 與您可存取的任何工作階段都不相符。請對照工作階段的 claude.ai/code URL 進行檢查。 |

473| `cloud session <id> is archived and cannot accept new messages` | 該工作階段已封存。請改為啟動新的工作階段。 |

474

438<h3 id="environment-expired">475<h3 id="environment-expired">

439 環境已過期476 環境已過期

440</h3>477</h3>

441 478

442雲端工作階段在不活動一段時間後停止，工作階段的 VM 被回收。工作階段在等待您批准 [MCP 連接器](/docs/zh-TW/cloud-environments#network-access)工具呼叫或登入 MCP 伺服器時計為不活動，並且可以在該等待期間過期。479雲端工作階段在不活動一段時間後停止，工作階段的 VM 被回收。工作階段在等待您批准 [MCP 連接器](/docs/zh-TW/cloud-environments#network-access)工具呼叫或登入 MCP 伺服器時計為不活動，並且可以在該等待期間過期。

443 480

444從 [claude.ai/code](https://claude.ai/code) 重新開啟工作階段以佈建新 VM，並恢復您的對話歷史記錄。在 VM 被回收時仍在執行的背景工作，例如 subagents 和 shell 命令，不會被恢復。481從 [claude.ai/code](https://claude.ai/code) 重新開啟工作階段以佈建新 VM：

482

483* **會恢復**：您的對話歷史記錄

484* **不會恢復**：在 VM 被回收時仍在執行的背景工作，例如 subagents 和 shell 命令

445 485

446<h2 id="limitations">486<h2 id="limitations">

447 限制487 限制

claude-directory.md +3 −3

Details

497 oneLiner: 'Custom keyboard shortcuts',497 oneLiner: 'Custom keyboard shortcuts',

498 when: 'Read at session start and hot-reloaded when you edit the file',498 when: 'Read at session start and hot-reloaded when you edit the file',

499 description: <>Rebind keyboard shortcuts in the interactive CLI. Run <C>/keybindings</C> to create or open this file with a schema reference. Ctrl+C, Ctrl+D, Ctrl+M, and Caps Lock are reserved and cannot be rebound.</>,499 description: <>Rebind keyboard shortcuts in the interactive CLI. Run <C>/keybindings</C> to create or open this file with a schema reference. Ctrl+C, Ctrl+D, Ctrl+M, and Caps Lock are reserved and cannot be rebound.</>,

500 exampleIntro: <>This example binds <C>Ctrl+E</C> to open your external editor and unbinds <C>Ctrl+U</C> by setting it to <C>null</C>. The <C>context</C> field scopes bindings to a specific part of the CLI, here the main chat input.</>,500 exampleIntro: <>This example binds <C>Ctrl+E</C> to open your external editor and unbinds <C>Ctrl+S</C> by setting it to <C>null</C>. The <C>context</C> field scopes bindings to a specific part of the CLI, here the main chat input.</>,

501 example: `{501 example: `{

502 "$schema": "https://www.schemastore.org/claude-code-keybindings.json",502 "$schema": "https://www.schemastore.org/claude-code-keybindings.json",

503 "$docs": "https://code.claude.com/docs/en/keybindings",503 "$docs": "https://code.claude.com/docs/en/keybindings",

506 "context": "Chat",506 "context": "Chat",

507 "bindings": {507 "bindings": {

508 "ctrl+e": "chat:externalEditor",508 "ctrl+e": "chat:externalEditor",

509 "ctrl+u": null509 "ctrl+s": null

510 }510 }

511 }511 }

512 ]512 ]

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

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

1461 1461

cloud-environments.md +1 −1

Details

26 26

27* **CLI 流程（例如 `/web-setup`）**：為您建立 **Default**27* **CLI 流程（例如 `/web-setup`）**：為您建立 **Default**

28* **Pro 和 Max 上的網頁上線設定**：為您建立 **Default**28* **Pro 和 Max 上的網頁上線設定**：為您建立 **Default**

29* **Team 和 Enterprise 上的網頁上線設定**：顯示 **Create your first cloud environment** 表單，除非擁有者已開啟[快速網頁設定](/docs/zh-TW/claude-code-on-the-web#github-authentication-options)；保持表單的預設值並點擊 **Create & finish** 以取得相同的 **Default** 環境29* **Team 和 Enterprise 上的網頁上線設定**：顯示 **Create your first cloud environment** 表單，除非擁有者已開啟[快速設定](/docs/zh-TW/claude-code-on-the-web#quick-setup-for-team-and-enterprise)；保持表單的預設值並點擊 **Create & finish** 以取得相同的 **Default** 環境

30 30

31**Default** 本身不帶有任何設定：31**Default** 本身不帶有任何設定：

32 32

costs.md +2 −2

Details

112| :- | :- |112| :- | :- |

113| Pro 或 Max 訂閱者 | 在瀏覽器中開啟 claude.ai 上的 [**Settings > Usage**](https://claude.ai/settings/usage)。在其 **Usage credits** 部分中，您可以開啟或關閉使用額度，並檢查您的額度餘額、本月支出和每月支出限制 |113| Pro 或 Max 訂閱者 | 在瀏覽器中開啟 claude.ai 上的 [**Settings > Usage**](https://claude.ai/settings/usage)。在其 **Usage credits** 部分中，您可以開啟或關閉使用額度，並檢查您的額度餘額、本月支出和每月支出限制 |

114| 具有計費存取權限的 Team 或 Enterprise 成員 | 在瀏覽器中開啟您的組織的使用情況設定 [**Admin settings > Usage**](https://claude.ai/admin-settings/usage) |114| 具有計費存取權限的 Team 或 Enterprise 成員 | 在瀏覽器中開啟您的組織的使用情況設定 [**Organization settings > Usage**](https://claude.ai/admin-settings/usage) |

115| 沒有計費存取權限的 Team 或 Enterprise 成員 | 要求您確認，然後向您的組織管理員傳送請求。在 v2.1.211 之前，Claude Code 在沒有確認步驟的情況下傳送請求 |115| 沒有計費存取權限的 Team 或 Enterprise 成員 | 要求您確認，然後向您的組織管理員傳送請求。在 v2.1.211 之前，Claude Code 在沒有確認步驟的情況下傳送請求 |

116 116

117對於沒有計費存取權限的 Team 和 Enterprise 成員，確認僅出現在互動式工作階段中：在使用 `-p` 旗標的非互動式模式和從[遠端控制](/docs/zh-TW/remote-control)中，該命令不傳送請求，並告訴您改為在互動式工作階段中執行它。117對於沒有計費存取權限的 Team 和 Enterprise 成員，確認僅出現在互動式工作階段中：在使用 `-p` 旗標的非互動式模式和從[遠端控制](/docs/zh-TW/remote-control)中，該命令不傳送請求，並告訴您改為在互動式工作階段中執行它。

229* **「您已達到工作階段限制」或「您已達到每週限制」**：訂閱方案上基於座位的使用視窗，在所有模型中共享，因此開發人員無法透過使用 `/model` 切換模型來恢復存取權限。該訊息顯示視窗何時重設。在模型特定的「您已達到 Opus 限制」或「您已達到 Sonnet 限制」訊息之後，使用 `/model` 切換到該系列外的模型確實會讓開發人員繼續工作。請參閱[使用限制錯誤](/docs/zh-TW/errors#youve-hit-your-session-limit)。開發人員在此期間可以做什麼：229* **「您已達到工作階段限制」或「您已達到每週限制」**：訂閱方案上基於座位的使用視窗，在所有模型中共享，因此開發人員無法透過使用 `/model` 切換模型來恢復存取權限。該訊息顯示視窗何時重設。在模型特定的「您已達到 Opus 限制」或「您已達到 Sonnet 限制」訊息之後，使用 `/model` 切換到該系列外的模型確實會讓開發人員繼續工作。請參閱[使用限制錯誤](/docs/zh-TW/errors#youve-hit-your-session-limit)。開發人員在此期間可以做什麼：

230 * 執行 `/usage-credits` 以請求超過額度的使用量，如果您已啟用[使用額度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)。230 * 執行 `/usage-credits` 以請求超過額度的使用量，如果您已啟用[使用額度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)。

231 * 在 Claude Code v2.1.234 或更新版本上，[在重設後自動等待並繼續中斷的任務](/docs/zh-TW/interactive-mode#wait-for-a-usage-limit-to-reset)；該部分列出 Claude Code 何時自行開始等待以及開發人員何時從 `/rate-limit-options` 選擇它。若要控制您的機隊 Claude Code 是否自行開始該等待，請在[受管設定](/docs/zh-TW/settings#settings-precedence)中設定 [`autoContinueAtUsageLimit`](/docs/zh-TW/settings-reference#autocontinueatusagelimit)。231 * 在 Claude Code v2.1.234 或更新版本上，[在重設後自動等待並繼續中斷的任務](/docs/zh-TW/interactive-mode#wait-for-a-usage-limit-to-reset)；該部分列出 Claude Code 何時自行開始等待以及開發人員何時從 `/rate-limit-options` 選擇它。若要控制您的機隊 Claude Code 是否自行開始該等待，請在[受管設定](/docs/zh-TW/settings#settings-precedence)中設定 [`autoContinueAtUsageLimit`](/docs/zh-TW/settings-reference#autocontinueatusagelimit)。

232* **「您已達到個人支出限制」、「組織的每月支出限制」或「團隊的共享預算」**：開發人員的請求將被計費至使用額度，而這些額度已達到您設定的支出限制。若要讓開發人員繼續，請前往[**管理員設定 > 使用**](https://claude.ai/admin-settings/usage)並增加訊息命名的限制。當訊息也命名計畫重設時間時，開發人員可以改為等待直到那時。請參閱[錯誤參考](/docs/zh-TW/errors#youve-hit-your-monthly-spend-limit)以了解每個變體。232* **「You've hit your individual spend limit」、「org's monthly spend limit」或「team's shared budget」**：開發人員的請求將被計費至用量點數，而這些點數已達到您設定的支出限制。若要讓開發人員繼續，請前往[**組織設定 > 用量**](https://claude.ai/admin-settings/usage)並提高訊息中指明的限制。當訊息也指明方案重設時間時，開發人員可以改為等待直到那時。請參閱[錯誤參考](/docs/zh-TW/errors#youve-hit-your-monthly-spend-limit)以了解每個變體。

233* **來自 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway) 的支出限制訊息**：開發人員超過了您在自託管閘道上設定的支出上限，閘道會阻止他們的請求，直到期間重設或您提高上限。請參閱[閘道支出限制](/docs/zh-TW/claude-apps-gateway-spend-limits)以了解上限、重設時間表和開發人員看到的訊息。233* **來自 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway) 的支出限制訊息**：開發人員超過了您在自託管閘道上設定的支出上限，閘道會阻止他們的請求，直到期間重設或您提高上限。請參閱[閘道支出限制](/docs/zh-TW/claude-apps-gateway-spend-limits)以了解上限、重設時間表和開發人員看到的訊息。

234* **上下文或自動壓縮警告**：不是使用限制。對話已接近工作階段的[自動壓縮視窗](/docs/zh-TW/model-config#set-the-auto-compact-window)，Claude Code 會總結較舊的歷史記錄以釋放空間的閾值。將開發人員指向[減少 token 使用量](#reduce-token-usage)。234* **上下文或自動壓縮警告**：不是使用限制。對話已接近工作階段的[自動壓縮視窗](/docs/zh-TW/model-config#set-the-auto-compact-window)，Claude Code 會總結較舊的歷史記錄以釋放空間的閾值。將開發人員指向[減少 token 使用量](#reduce-token-usage)。

235* **API 或雲端提供者方案上的意外高支出**：通常可追溯到從未清除的長工作階段或留作預設模型的 Opus。分享的最高影響習慣是在不相關的任務之間清除和將模型與工作相匹配，兩者都涵蓋在[減少 token 使用量](#reduce-token-usage)中。235* **API 或雲端提供者方案上的意外高支出**：通常可追溯到從未清除的長工作階段或留作預設模型的 Opus。分享的最高影響習慣是在不相關的任務之間清除和將模型與工作相匹配，兩者都涵蓋在[減少 token 使用量](#reduce-token-usage)中。

cross-session-messaging.md +1 −0

Details

192以下任一方式都可以顯示完整文字：192以下任一方式都可以顯示完整文字：

193 193

194* 按 `Ctrl+O` 開啟[逐字稿檢視器](/docs/zh-TW/interactive-mode#transcript-viewer)，並在寄件者的工作階段名稱下閱讀完整文字。194* 按 `Ctrl+O` 開啟[逐字稿檢視器](/docs/zh-TW/interactive-mode#transcript-viewer)，並在寄件者的工作階段名稱下閱讀完整文字。

195* 在[全螢幕渲染](/docs/zh-TW/fullscreen#use-the-mouse)中，點擊省略了部分訊息的預覽行，即可就地展開。

195* 在以 [`--verbose`](/docs/zh-TW/cli-reference#cli-flags) 啟動的工作階段中，Claude Code 會顯示完整文字而不是預覽。196* 在以 [`--verbose`](/docs/zh-TW/cli-reference#cli-flags) 啟動的工作階段中，Claude Code 會顯示完整文字而不是預覽。

196 197

197預覽只會縮短您看到的內容。無論您是否展開它，Claude 都會讀取完整訊息。198預覽只會縮短您看到的內容。無論您是否展開它，Claude 都會讀取完整訊息。

desktop.md +39 −39

Details

244 切換檢視模式244 切換檢視模式

245</h3>245</h3>

246 246

247檢視模式控制聊天記錄中顯示多少詳細資訊。從傳送按鈕旁的 **Transcript view** 下拉式選單切換模式，或在 macOS 或 Windows 上按 **Ctrl+O** 以循環瀏覽它們。Thinking 模式僅在 Claude 在您正在檢視的會話中產生思考後才會出現在下拉式選單中。247檢視模式控制聊天逐字稿中顯示多少詳細資訊。若要切換檢視模式，請從工作階段標題旁的插入符號開啟工作階段選單並選擇 **Transcript view**，或在 macOS 或 Windows 上按 **Ctrl+O** 以循環瀏覽它們。Thinking 模式僅在 Claude 在您正在檢視的工作階段中產生思考後才會出現在選單中。

248 248

249| 模式 | 它顯示什麼 |249| 模式 | 它顯示什麼 |

250| - | - |250| - | - |

369* **Unhide apps when Claude finishes**：當電腦使用未在背景執行時，Claude 工作時會隱藏您的其他視窗，以便它僅與批准的應用程式互動。當 Claude 完成時，隱藏的視窗會被恢復，除非您關閉此設定。369* **Unhide apps when Claude finishes**：當電腦使用未在背景執行時，Claude 工作時會隱藏您的其他視窗，以便它僅與批准的應用程式互動。當 Claude 完成時，隱藏的視窗會被恢復，除非您關閉此設定。

370 370

371<h2 id="manage-sessions">371<h2 id="manage-sessions">

372 管理會話372 管理工作階段

373</h2>373</h2>

374 374

375每個會話都是一個獨立的對話，具有自己的上下文和變更。您可以並行執行多個會話、分支出側邊聊天、讓 Claude 檢查並傳送訊息到您的其他會話、將工作傳送到雲端，或讓 Dispatch 從您的手機為您啟動會話。375每個工作階段都是一個獨立的對話，具有自己的上下文和變更。您可以並行執行多個工作階段、分支出側邊聊天、讓 Claude 檢查並傳送訊息到您的其他工作階段、將工作傳送到雲端，或讓 Dispatch 從您的手機為您啟動工作階段。

376 376

377<h3 id="work-in-parallel-with-sessions">377<h3 id="work-in-parallel-with-sessions">

378 使用會話並行工作378 使用工作階段並行工作

379</h3>379</h3>

380 380

381點擊側邊欄中的 **+ New session**，或在 macOS 上按 **Cmd+N** 或在 Windows 上按 **Ctrl+N**，以並行處理多個任務。按 **Ctrl+Tab** 和 **Ctrl+Shift+Tab** 以循環瀏覽側邊欄中的會話。對於 Git 儲存庫，選擇分支名稱旁邊的 **worktree** 選項，以使用 [Git worktrees](/docs/zh-TW/worktrees) 為會話提供自己的隔離專案副本，因此一個會話中的變更不會影響其他會話，直到您提交它們。381點擊側邊欄中的 **+ New session**，或在 macOS 上按 **Cmd+N** 或在 Windows 上按 **Ctrl+N**，以並行處理多個任務。按 **Ctrl+Tab** 和 **Ctrl+Shift+Tab** 以循環瀏覽側邊欄中的工作階段。對於 Git 儲存庫，選擇分支名稱旁邊的 **worktree** 選項，以使用 [Git worktrees](/docs/zh-TW/worktrees) 為工作階段提供自己的隔離專案副本，因此一個工作階段中的變更不會影響其他工作階段，直到您提交它們。

382 382

383若要同時檢視兩個會話，請在 macOS 上按住 **Cmd** 或在 Windows 上按住 **Ctrl**，然後點擊側邊欄中的會話。會話會在您已開啟的會話旁邊的第二個窗格中開啟。當分割處於活動狀態時，點擊另一個側邊欄會話會取代具有焦點的窗格。在 macOS 上按 **Cmd+\\** 或在 Windows 上按 **Ctrl+\\** 以關閉焦點窗格並返回單一會話。383若要同時檢視兩個工作階段，請在 macOS 上按住 **Cmd** 或在 Windows 上按住 **Ctrl**，然後點擊側邊欄中的工作階段。工作階段會在您已開啟的工作階段旁邊的第二個窗格中開啟。當分割處於活動狀態時，點擊另一個側邊欄工作階段會取代具有焦點的窗格。在 macOS 上按 **Cmd+\\** 或在 Windows 上按 **Ctrl+\\** 以關閉焦點窗格並返回單一工作階段。

384 384

385Worktrees 預設儲存在 `<project-root>/.claude/worktrees/` 中。您可以在「設定」→「Claude Code」下的「Worktree location」中將其變更為自訂目錄。您也可以設定一個分支前綴，該前綴會被加在每個 worktree 分支名稱前面，這對於保持 Claude 建立的分支井然有序很有用。若要在完成後移除 worktree，請將滑鼠懸停在側邊欄中的會話上，然後點擊存檔圖示。若要在 PR 合併或關閉後自動存檔會話，請在「設定」→「Claude Code」中開啟 **Auto-archive after PR merge or close**。自動存檔僅適用於已完成執行的本機會話。385Worktrees 預設儲存在 `<project-root>/.claude/worktrees/` 中。您可以在「設定」→「Claude Code」下的「Worktree location」中將其變更為自訂目錄。您也可以設定一個分支前綴，該前綴會被加在每個 worktree 分支名稱前面，這對於保持 Claude 建立的分支井然有序很有用。若要在完成後移除 worktree，請將滑鼠懸停在側邊欄中的工作階段上，然後點擊存檔圖示。若要在 pull request 合併或關閉後自動存檔工作階段，請在「設定」→「Claude Code」中開啟 **Auto-archive after PR merge or close**。自動存檔僅適用於已完成執行的本機工作階段。

386 386

387若要在新 worktrees 中包含 gitignored 檔案（如 `.env`），請在您的專案根目錄中建立 [`.worktreeinclude` 檔案](/docs/zh-TW/worktrees#copy-gitignored-files-into-worktrees)。387若要在新 worktrees 中包含 gitignored 檔案（如 `.env`），請在您的專案根目錄中建立 [`.worktreeinclude` 檔案](/docs/zh-TW/worktrees#copy-gitignored-files-into-worktrees)。

388 388

389<Note>389<Note>

390 會話隔離需要 [Git](https://git-scm.com/downloads)。大多數 Mac 預設包含 Git。在終端機中執行 `git --version` 進行檢查；如果它列印版本號，表示已安裝 Git。如果您遇到 Git 錯誤，請在 [Cowork 標籤](https://claude.com/product/cowork) 中詢問 Claude 以幫助排除您的設定問題。390 工作階段隔離需要 [Git](https://git-scm.com/downloads)。大多數 Mac 預設包含 Git。在終端機中執行 `git --version` 進行檢查；如果它列印版本號，表示已安裝 Git。如果您遇到 Git 錯誤，請在 [Cowork 標籤](https://claude.com/product/cowork) 中詢問 Claude 以幫助排除您的設定問題。

391</Note>391</Note>

392 392

393使用側邊欄頂部的控制項按狀態、專案或環境篩選會話，並按專案分組會話。若要重新命名會話，請點擊活動會話頂部工具列中的會話標題。393使用側邊欄頂部的控制項按狀態、專案或環境篩選工作階段，並按專案分組工作階段。若要重新命名工作階段，請點擊活動工作階段頂部工具列中的工作階段標題。

394 394

395若要檢查上下文使用情況，請參閱[檢查使用情況](#check-usage)。當上下文填滿時，Claude 會自動總結對話並繼續工作。您也可以輸入 `/compact` 來更早觸發總結並釋放上下文空間。有關壓縮如何運作的詳細資訊，請參閱[上下文視窗](/docs/zh-TW/how-claude-code-works#the-context-window)。395若要檢查上下文使用情況，請參閱[檢查使用情況](#check-usage)。當上下文填滿時，Claude 會自動總結對話並繼續工作。您也可以輸入 `/compact` 來更早觸發總結並釋放上下文空間。有關壓縮如何運作的詳細資訊，請參閱[上下文視窗](/docs/zh-TW/how-claude-code-works#the-context-window)。

396 396

397桌面應用程式會在 Code 會話完成任務且您目前未檢視該會話時傳送作業系統通知。對於屬於[專案](/docs/zh-TW/claude-projects#see-what-needs-you-in-overview)的會話，您會改為收到專案的通知。397桌面應用程式會在 Code 工作階段完成任務且您目前未檢視該工作階段時傳送作業系統通知。對於屬於[專案](/docs/zh-TW/claude-projects#see-what-needs-you-in-overview)的工作階段，您會改為收到專案的通知。

398 398

399<h3 id="ask-a-side-question-without-derailing-the-session">399<h3 id="ask-a-side-question-without-derailing-the-session">

400 在不偏離會話的情況下詢問側邊問題400 在不偏離工作階段的情況下詢問側邊問題

401</h3>401</h3>

402 402

403側邊聊天讓您詢問 Claude 一個使用您會話上下文的問題，但不會將任何內容新增回主對話。當您想要理解一段程式碼、檢查假設或探索想法而不引導會話偏離時，請使用它。403側邊聊天讓您詢問 Claude 一個使用您工作階段上下文的問題，但不會將任何內容新增回主對話。當您想要理解一段程式碼、檢查假設或探索想法而不引導工作階段偏離時，請使用它。

404 404

405在 macOS 上按 **Cmd+;** 或在 Windows 上按 **Ctrl+;** 以開啟側邊聊天，或在提示框中輸入 `/btw`。側邊聊天可以讀取主執行緒中到該點為止的所有內容。完成後，關閉側邊聊天並在您離開的地方繼續主會話。405在 macOS 上按 **Cmd+;** 或在 Windows 上按 **Ctrl+;** 以開啟側邊聊天，或在提示詞輸入框中輸入 `/btw`。側邊聊天可以讀取主執行緒中到該點為止的所有內容。完成後，關閉側邊聊天並在您離開的地方繼續主工作階段。

406 406

407側邊聊天在本機、SSH 和 WSL 會話中可用。桌面應用程式不會將側邊聊天儲存到磁碟，因此您在關閉應用程式後無法返回到一個。407側邊聊天在本機、SSH 和 WSL 工作階段中可用。桌面應用程式不會將側邊聊天儲存到磁碟，因此您在關閉應用程式後無法返回到一個。

408 408

409<h3 id="watch-background-tasks">409<h3 id="watch-background-tasks">

410 觀看背景任務410 觀看背景任務

411</h3>411</h3>

412 412

413任務窗格顯示在目前會話內執行的背景工作：子代理、背景 shell 命令和[動態工作流程](/docs/zh-TW/workflows)。從 **Views** 選單開啟它或將其拖入您的佈局。413任務窗格顯示在目前工作階段內執行的背景工作：subagents、背景 shell 命令和[動態工作流程](/docs/zh-TW/workflows)。從 **Views** 選單開啟它或將其拖入您的佈局。

414 414

415點擊任何項目以在子代理窗格中查看其輸出或停止它。若要查看其他會話正在執行的操作，請使用[側邊欄](#work-in-parallel-with-sessions)，或詢問 Claude [為您檢查它們](#work-across-sessions)。415點擊任何項目以在 subagent 窗格中查看其輸出或停止它。若要查看其他工作階段正在執行的操作，請使用[側邊欄](#work-in-parallel-with-sessions)，或詢問 Claude [為您檢查它們](#work-across-sessions)。

416 416

417<h3 id="work-across-sessions">417<h3 id="work-across-sessions">

418 跨會話工作418 跨工作階段工作

419</h3>419</h3>

420 420

421Claude 可以列出您的其他 Code 標籤會話、讀取每個會話一直在執行的操作，以及在它們之間傳送訊息。以純文字詢問：「哪個會話涉及了身份驗證重構？」、「API 會話得出了什麼結論？」或「告訴付款會話架構已變更」。您也可以詢問 Claude 重新命名或存檔會話。Claude 存檔會話的方式與側邊欄的存檔圖示相同，因此詢問它清理 PR 已合併的會話。421Claude 可以列出您的其他 Code 標籤工作階段、讀取每個工作階段一直在執行的操作，以及在它們之間傳送訊息。以日常用語詢問：「哪個工作階段涉及了身份驗證重構？」、「API 工作階段得出了什麼結論？」或「告訴付款工作階段 schema 已變更」。您也可以詢問 Claude 重新命名或存檔工作階段。Claude 存檔工作階段的方式與側邊欄的存檔圖示相同，因此可以請它清理 PR 已合併的工作階段。

422 422

423透過此介面，Claude 只能看到桌面應用程式本身執行的會話：本機、[SSH](#ssh-sessions) 和 Code 標籤中的 [WSL](/docs/zh-TW/desktop-wsl) 會話。Claude 看不到雲端會話，或您從終端機 CLI 或 VS Code 擴充功能啟動的會話，即使在同一專案的 worktrees 中也是如此，因此有九個終端機 worktrees 開啟和兩個桌面會話時，Claude 在其中一個回答會報告另一個桌面會話。Claude 永遠不會列出您詢問的會話。預設情況下，它會看到 20 個最近活躍的會話，並跳過已存檔的會話，除非您要求它們。[跨會話傳訊](/docs/zh-TW/cross-session-messaging)另外讓 Claude 傳送訊息到[您的其他 Claude Code 會話](/docs/zh-TW/cross-session-messaging#see-which-sessions-claude-can-reach)，包括終端機會話。423透過此使用介面，Claude 只能看到桌面應用程式本身執行的工作階段：Code 標籤中的本機、[SSH](#ssh-sessions) 和 [WSL](/docs/zh-TW/desktop-wsl) 工作階段。Claude 看不到雲端工作階段，或您從終端機 CLI 或 VS Code 擴充功能啟動的工作階段，即使在同一專案的 worktrees 中也是如此，因此有九個終端機 worktrees 開啟和兩個桌面工作階段時，Claude 在其中一個回答會報告另一個桌面工作階段。Claude 永遠不會列出您詢問的工作階段。預設情況下，它會看到 20 個最近活躍的工作階段，並跳過已存檔的工作階段，除非您要求它們。[跨工作階段傳訊](/docs/zh-TW/cross-session-messaging)另外讓 Claude 傳送訊息到[您的其他 Claude Code 工作階段](/docs/zh-TW/cross-session-messaging#see-which-sessions-claude-can-reach)，包括終端機工作階段。

424 424

425當 Claude 透過此介面傳送訊息到另一個會話時，Claude Code 會在那裡將其顯示為一張卡片，標籤為傳送會話的標題和返回連結，因此您總是可以看到訊息來自何處。如果接收會話正在執行任務中，Claude Code 會保留訊息，Claude 會在目前工作完成後讀取它。接收 Claude 可以回覆，Claude Code 會透過此介面傳遞回覆。Claude 無法傳遞到已存檔的會話，並會在訊息未通過時告訴您。425當 Claude 透過此使用介面傳送訊息到另一個工作階段時，Claude Code 會在那裡將其顯示為一張卡片，標籤為傳送工作階段的標題和返回連結，因此您總是可以看到訊息來自何處。如果接收工作階段正在執行任務中，Claude Code 會保留訊息，Claude 會在目前工作完成後讀取它。接收端的 Claude 可以回覆，Claude Code 會透過此使用介面傳遞回覆。Claude 無法傳遞到已存檔的工作階段，並會在訊息未送達時告訴您。

426 426

427Claude Code 在會話間應用四個安全行為：427Claude Code 在工作階段間應用四個安全行為：

428 428

429* 在存檔任何會話之前，Claude 會先詢問您。您會在每個權限模式中看到批准卡片，包括自動和略過權限。429* 在存檔任何工作階段之前，Claude 會先詢問您。您會在每個權限模式中看到核准卡片，包括自動和略過權限。

430* 透過此介面，Claude 無法從沒有人監視的會話（例如排程任務執行）傳送跨會話訊息，也無法傳遞訊息到一個。430* 透過此使用介面，Claude 無法從沒有人監視的工作階段（例如排程任務執行）傳送跨工作階段訊息，也無法傳遞訊息到這類工作階段。

431* Claude Code 會根據接收會話的[入站控制](/docs/zh-TW/cross-session-messaging#control-inbound-messages)檢查來自此介面的每條訊息，即使接收會話本身沒有[跨會話傳訊](/docs/zh-TW/cross-session-messaging#availability)。如果您在接收會話中將 [`crossSessionInbound`](/docs/zh-TW/settings-reference#crosssessioninbound) 設定為 `refuse`，Claude Code 會丟棄來自此介面的訊息。Claude Code 會向 Claude 桌面應用程式報告拒絕。在 v2.1.234 之前，Claude Code 會丟棄來自此介面到沒有跨會話傳訊的接收會話的每條訊息。431* Claude Code 會根據接收工作階段的[入站控制](/docs/zh-TW/cross-session-messaging#control-inbound-messages)檢查來自此使用介面的每條訊息，即使接收工作階段本身沒有[跨工作階段傳訊](/docs/zh-TW/cross-session-messaging#availability)。如果您在接收工作階段中將 [`crossSessionInbound`](/docs/zh-TW/settings-reference#crosssessioninbound) 設定為 `refuse`，Claude Code 會丟棄來自此使用介面的訊息。Claude Code 會向 Claude 桌面應用程式報告拒絕。在 v2.1.234 之前，Claude Code 會丟棄來自此使用介面到沒有跨工作階段傳訊的接收工作階段的每條訊息。

432* Claude Code 引用每條傳入訊息並將其歸因於傳送它的會話，Claude 在對其進行操作時仍然遵循接收會話自己的權限設定。432* Claude Code 引用每條傳入訊息並將其歸因於傳送它的工作階段，Claude 在對其進行操作時仍然遵循接收工作階段自己的權限設定。

433 433

434Claude 也可以建議新會話。當它注意到值得修復但超出目前任務範圍的內容時，它會在聊天中提供工作作為任務晶片。點擊晶片以在具有自己 worktree 的新會話中啟動該工作；Claude 會不中斷地繼續您的目前會話。434Claude 也可以建議新工作階段。當它注意到值得修復但超出目前任務範圍的內容時，它會在聊天中以任務晶片的形式提供該工作。點擊晶片以在具有自己 worktree 的新工作階段中啟動該工作；Claude 會不中斷地繼續您的目前工作階段。

435 435

436<h3 id="run-long-running-tasks-in-the-cloud">436<h3 id="run-long-running-tasks-in-the-cloud">

437 在雲端執行長時間執行的任務437 在雲端執行長時間執行的任務

438</h3>438</h3>

439 439

440對於大型重構、測試套件、遷移或其他長時間執行的任務，在開始會話時選擇 **Cloud** 而不是 **Local**。雲端會話預設在 Anthropic 管理的基礎設施上執行，即使您關閉應用程式或關閉電腦，也會繼續執行。隨時檢查以查看進度或引導 Claude 朝不同方向發展。您也可以從 [claude.ai/code](https://claude.ai/code) 或 [Claude 行動應用程式](/docs/zh-TW/mobile)監控雲端會話。440對於大型重構、測試套件、遷移或其他長時間執行的任務，在開始工作階段時選擇 **Cloud** 而不是 **Local**。雲端工作階段預設在 Anthropic 管理的基礎設施上執行，即使您關閉應用程式或關閉電腦，也會繼續執行。隨時檢查以查看進度或引導 Claude 朝不同方向發展。您也可以從 [claude.ai/code](https://claude.ai/code) 或 [Claude 行動應用程式](/docs/zh-TW/mobile)監控雲端工作階段。

441 441

442雲端會話也支援多個儲存庫。選擇雲端環境後，點擊所選儲存庫旁邊的 **+** 按鈕，將其他儲存庫新增到會話。每個儲存庫都有自己的分支選擇器。這對於跨越多個程式碼庫的任務很有用，例如更新共用程式庫及其使用者。442雲端工作階段也支援多個儲存庫。選擇雲端環境後，點擊所選儲存庫旁邊的 **+** 按鈕，將其他儲存庫新增到工作階段。每個儲存庫都有自己的分支選擇器。這對於跨越多個程式碼庫的任務很有用，例如更新共用程式庫及其使用者。

443 443

444有關雲端會話如何運作的更多資訊，請參閱[在網路上使用 Claude Code](/docs/zh-TW/claude-code-on-the-web)。當一項工作需要許多雲端會話時，請在側邊欄中選擇 **Projects** 以建立[專案](/docs/zh-TW/claude-projects)，Claude 會從一個對話中為您啟動並追蹤會話。444有關雲端工作階段如何運作的更多資訊，請參閱[在雲端使用 Claude Code](/docs/zh-TW/claude-code-on-the-web)。當一項工作需要許多雲端工作階段時，請在側邊欄中選擇 **Projects** 以建立[專案](/docs/zh-TW/claude-projects)，Claude 會從一個對話中為您啟動並追蹤工作階段。

445 445

446<h3 id="continue-in-another-surface">446<h3 id="continue-in-another-surface">

447 在另一個介面中繼續447 在另一個使用介面中繼續

448</h3>448</h3>

449 449

450**Continue in** 選單可從會話工具列右下角的 VS Code 圖示存取，可讓您將會話移至另一個介面：450若要在其他地方繼續工作階段，請從工作階段標題旁的插入符號或側邊欄中該工作階段的列開啟工作階段選單，然後選擇 **Open in**：

451 451

452* **Claude Code on the Web**：將您的本機會話傳送到雲端繼續執行。Desktop 推送您的分支、產生對話摘要，並使用完整上下文建立新的雲端會話。然後您可以選擇存檔本機會話或保留它。這需要乾淨的工作樹，不適用於 SSH 會話。452* 選擇 **Cloud** 以將工作階段作為[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)繼續，您的對話會以摘要形式帶過去。在您確認之前，對話框會說明您的檔案是否也會一併移動，以及雲端工作階段準備就緒後是否會存檔此工作階段。透過 [SSH](#ssh-sessions) 或在 [WSL](/docs/zh-TW/desktop-wsl) 中執行的工作階段無法以此方式移動。

453* **Your IDE**：在目前工作目錄的支援 IDE 中開啟您的專案。453* 選擇已安裝的編輯器或您的檔案管理器，以在其中開啟該工作階段在磁碟上的資料夾。

454 454

455<h3 id="sessions-from-dispatch">455<h3 id="sessions-from-dispatch">

456 來自 Dispatch 的會話456 來自 Dispatch 的工作階段

457</h3>457</h3>

458 458

459[Dispatch](https://support.claude.com/en/articles/13947068) 是與 Claude 的持久對話，存在於 [Cowork](https://claude.com/product/cowork) 標籤中。您向 Dispatch 傳送任務，它決定如何處理它。459[Dispatch](https://support.claude.com/en/articles/13947068) 是與 Claude 的持久對話，存在於 [Cowork](https://claude.com/product/cowork) 標籤中。您向 Dispatch 傳送任務，它決定如何處理它。

460 460

461任務可以透過兩種方式成為 Code 會話：您直接要求一個，例如「開啟 Claude Code 會話並修復登入錯誤」，或 Dispatch 決定任務是開發工作並自行產生一個。通常路由到 Code 的任務包括修復錯誤、更新相依性、執行測試或開啟提取請求。研究、文件編輯和試算表工作保留在 Cowork 中。461任務可以透過兩種方式成為 Code 工作階段：您直接要求一個，例如「開啟 Claude Code 工作階段並修復登入錯誤」，或 Dispatch 決定任務是開發工作並自行產生一個。通常路由到 Code 的任務包括修復錯誤、更新相依性、執行測試或開啟 pull request。研究、文件編輯和試算表工作保留在 Cowork 中。

462 462

463無論哪種方式，Code 會話都會在 Code 標籤的側邊欄中出現，帶有 **Dispatch** 徽章。當它完成或需要您的批准時，您會在手機上收到推送通知。463無論哪種方式，Code 工作階段都會在 Code 標籤的側邊欄中出現，帶有 **Dispatch** 徽章。當它完成或需要您的核准時，您會在手機上收到推送通知。

464 464

465如果您已[啟用電腦使用](#let-claude-use-your-computer)，Dispatch 產生的 Code 會話也可以使用它。這些會話中的應用程式批准在 30 分鐘後過期並重新提示，而不是像常規 Code 會話那樣持續整個會話。465如果您已[啟用電腦使用](#let-claude-use-your-computer)，Dispatch 產生的 Code 工作階段也可以使用它。這些工作階段中的應用程式核准在 30 分鐘後過期並重新提示，而不是像常規 Code 工作階段那樣持續整個工作階段。

466 466

467有關設定、配對和 Dispatch 設定，請參閱 [Dispatch 幫助文章](https://support.claude.com/en/articles/13947068)。Dispatch 需要 Pro 或 Max 計畫，在 Team 或 Enterprise 計畫上不可用。467有關設定、配對和 Dispatch 設定，請參閱 [Dispatch 幫助文章](https://support.claude.com/en/articles/13947068)。Dispatch 需要 Pro 或 Max 計畫，在 Team 或 Enterprise 計畫上不可用。

468 468

739 739

740[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。740[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。

741 741

742在具有[自適應推理](/docs/zh-TW/model-config#adjust-effort-level)的模型上，除了 `0` 以外的 `MAX_THINKING_TOKENS` 值會被忽略，因為自適應推理控制思考深度。在 Opus 4.6 和 Sonnet 4.6 上，將 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 設定為 `1` 以使用固定思考預算；Fable 模型、Sonnet 5 及更新版本，以及 Opus 4.7 及更新版本始終使用自適應推理，沒有固定預算模式。742在具有[自適應推理](/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 及更新版本始終使用自適應推理，沒有固定預算模式。

743 743

744<h4 id="local-sessions-on-managed-devices">744<h4 id="local-sessions-on-managed-devices">

745 受管設備上的本機會話745 受管設備上的本機會話

1005| `--dangerously-skip-permissions` | 略過權限模式。在 Pro 和 Max 方案上，在「設定」→「Claude Code」→「允許略過權限模式」中啟用它；在 Team 和 Enterprise 方案上，組織政策控制它 |1005| `--dangerously-skip-permissions` | 略過權限模式。在 Pro 和 Max 方案上，在「設定」→「Claude Code」→「允許略過權限模式」中啟用它；在 Team 和 Enterprise 方案上，組織政策控制它 |

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裝置名稱下方的列調整來自模擬器的影片串流。如果窗格對您的 Mac 造成負擔，請降低 **Frame rate** 或 **Resolution**，在 H.264 和 JPEG 之間切換 **Encoding**，或檢查 **FPS** 以顯示窗格接收的幀速率。這些設定會變更窗格顯示裝置的方式，而不是應用程式的執行方式。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

desktop-quickstart.md +1 −1

Details

135 135

136**將 Claude 排程執行。** 設定[排程工作](/docs/zh-TW/desktop-scheduled-tasks)以定期自動執行 Claude：每天早上進行程式碼審查、每週進行相依性稽核，或從您連接的工具提取資訊的簡報。136**將 Claude 排程執行。** 設定[排程工作](/docs/zh-TW/desktop-scheduled-tasks)以定期自動執行 Claude：每天早上進行程式碼審查、每週進行相依性稽核，或從您連接的工具提取資訊的簡報。

137 137

138**準備好時進行擴展。** 從側邊欄開啟[平行工作階段](/docs/zh-TW/desktop#work-in-parallel-with-sessions)以同時處理多個工作，可選擇每個工作都在自己的 Git worktree 中，並開啟[工作窗格](/docs/zh-TW/desktop#watch-background-tasks)以監控工作階段正在執行的子代理和背景命令。開啟[側邊聊天](/docs/zh-TW/desktop#ask-a-side-question-without-derailing-the-session)以提出問題而不會偏離主線。將[長期執行的工作發送到雲端](/docs/zh-TW/desktop#run-long-running-tasks-in-the-cloud)以便即使您關閉應用程式也能繼續執行，或[在網路或 IDE 中繼續工作階段](/docs/zh-TW/desktop#continue-in-another-surface)（如果工作耗時超過預期）。[連接外部工具](/docs/zh-TW/desktop#extend-claude-code)（例如 GitHub、Slack 和 Linear）以整合您的工作流程。138**準備好時進行擴展。** 從側邊欄開啟[平行工作階段](/docs/zh-TW/desktop#work-in-parallel-with-sessions)以同時處理多個任務，可選擇每個任務都在自己的 Git worktree 中，並開啟[任務窗格](/docs/zh-TW/desktop#watch-background-tasks)以監控工作階段正在執行的 subagents 和背景命令。開啟[側邊聊天](/docs/zh-TW/desktop#ask-a-side-question-without-derailing-the-session)以提出問題而不會偏離主線。將[長期執行的工作發送到雲端](/docs/zh-TW/desktop#run-long-running-tasks-in-the-cloud)以便即使您關閉應用程式也能繼續執行，或在任務耗時超過預期時，[將已開始的工作階段移至雲端](/docs/zh-TW/desktop#continue-in-another-surface)。[連接外部工具](/docs/zh-TW/desktop#extend-claude-code)（例如 GitHub、Slack 和 Linear）以整合您的工作流程。

139 139

140<h2 id="what’s-next">140<h2 id="what’s-next">

141 接下來141 接下來

env-vars.md +348 −309

Details

124 變數124 變數

125</h2>125</h2>

126 126

127逾時、token 預算與重試次數等數值變數，除了純數字之外，也接受科學記號與數字分隔符號的寫法，但變數所在列註明僅接受純數字者除外。例如，Claude Code 會將 `2e3` 讀取為 2000，將 `64_000` 讀取為 64000。在 v2.1.211 之前，這些寫法可能會在無任何提示的情況下設定成小得多的值，例如 `1e6` 會將逾時設定為 1。127數值型變數（例如逾時、token 預算與重試次數）除了純數字之外，也接受科學記號與數字分隔符寫法，但若某變數的列註明只接受純數字則除外。例如，Claude Code 會將 `2e3` 讀取為 2000，將 `64_000` 讀取為 64000。在 v2.1.211 之前，這些寫法可能會在無提示的情況下設定成小得多的值，例如 `1e6` 會將逾時設為 1。

128 128

129<Note>129<Note>

130 對於開啟或關閉某項行為的變數，設定 `1`、`true`、`yes` 或 `on` 可將其開啟，設定 `0`、`false`、`no` 或 `off` 可將其關閉，不區分大小寫。130 對於開啟或關閉某項行為的變數，設定 `1`、`true`、`yes` 或 `on` 即可開啟，設定 `0`、`false`、`no` 或 `off` 即可關閉，大小寫不拘。

131 131

132 部分變數只判斷是否有設定，因此任何非空值（包括 `0`）都會開啟該行為，若要關閉該行為，請取消設定該變數或將其設為空值。以下變數採用此方式：132 有些變數只會判斷您是否有設定它，因此任何非空值（包括 `0`）都會開啟該行為，若要關閉該行為，請取消設定該變數或將其設為空值。以下變數屬於這種方式：

133 133

134 * `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`134 * `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`

135 * `DISABLE_TELEMETRY`135 * `DISABLE_TELEMETRY`

138 * `FALLBACK_FOR_ALL_PRIMARY_MODELS`138 * `FALLBACK_FOR_ALL_PRIMARY_MODELS`

139 * `IS_DEMO`139 * `IS_DEMO`

140 140

141 另有一個變數有其專屬規則：`FORCE_HYPERLINK` 讀取的是數字，因此只有 `0` 會將其關閉。每個變數所在列也會說明其專屬規則。141 另有一個變數有自己的規則：`FORCE_HYPERLINK` 讀取的是數字，因此只有 `0` 會將其關閉。每個變數的列中也會說明其各自的規則。

142</Note>142</Note>

143 143

144| 變數 | 用途 |144| 變數 | 用途 |

145| :- | :- |145| :- | :- |

146| `ANTHROPIC_API_KEY` | 以 `X-Api-Key` 標頭傳送的 API 金鑰。設定後，即使您已登入，也會使用此金鑰，而非您的 Claude Pro、Max、Team 或 Enterprise 訂閱。在非互動模式（`-p`）中，只要存在此金鑰就一律會使用。在互動模式中，系統會在此金鑰覆寫您的訂閱之前，提示您核准一次。若要改用您的訂閱，請執行 `unset ANTHROPIC_API_KEY` |146| `ANTHROPIC_API_KEY` | 以 `X-Api-Key` 標頭傳送的 API 金鑰。設定後，即使您已登入，也會使用此金鑰，而非您的 Claude Pro、Max、Team 或 Enterprise 訂閱。在非互動模式（`-p`）中，只要有此金鑰就一律使用。在互動模式中，系統會提示您核准此金鑰一次，之後它才會覆寫您的訂閱。若要改用您的訂閱，請執行 `unset ANTHROPIC_API_KEY` |

148| `ANTHROPIC_AWS_API_KEY` | [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 的工作區 API 金鑰，於 AWS Console 中產生。以 `x-api-key` 傳送，且優先於 AWS SigV4 |148| `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)解析區域 |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) |

150| `ANTHROPIC_AWS_WORKSPACE_ID` | [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 的必要項目。在每個請求中以 `anthropic-workspace-id` 標頭傳送 |150| `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 上的行為一致 |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 上的行為一致 |

152| `ANTHROPIC_BEDROCK_BASE_URL` | 覆寫 Amazon Bedrock 端點 URL。用於自訂 Amazon Bedrock 端點，或透過 [LLM 閘道](/docs/zh-TW/llm-gateway)路由時。請參閱 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) |152| `ANTHROPIC_BEDROCK_BASE_URL` | 覆寫 Amazon Bedrock 端點 URL。用於自訂 Amazon Bedrock 端點，或透過 [LLM 閘道](/docs/zh-TW/llm-gateway)路由時。請參閱 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock) |

153| `ANTHROPIC_BEDROCK_MANTLE_BASE_URL` | 覆寫 Amazon Bedrock Mantle 端點 URL。請參閱 [Mantle 端點](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint) |153| `ANTHROPIC_BEDROCK_MANTLE_BASE_URL` | 覆寫 Amazon Bedrock Mantle 端點 URL。請參閱 [Mantle 端點](/docs/zh-TW/amazon-bedrock#use-the-mantle-endpoint) |

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

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

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 訂閱 |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 訂閱 |

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

158| `ANTHROPIC_CUSTOM_MODEL_OPTION` | 要在 `/model` 選擇器中新增為自訂項目的模型 ID。可用此變數讓非標準或閘道專屬的模型可供選擇，而不取代內建別名。請參閱[模型設定](/docs/zh-TW/model-config#add-a-custom-model-option) |158| `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 |160| `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) |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) |

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

163| `ANTHROPIC_DEFAULT_FABLE_MODEL_DESCRIPTION` | `/model` 選擇器中固定 Fable 模型的顯示說明。未設定時，該列會顯示以 `Custom Fable model` 開頭的預設說明。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |163| `ANTHROPIC_DEFAULT_FABLE_MODEL_DESCRIPTION` | `/model` 選擇器中固定 Fable 模型的顯示說明。未設定時，該列會顯示以 `Custom Fable model` 開頭的預設說明。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

164| `ANTHROPIC_DEFAULT_FABLE_MODEL_NAME` | `/model` 選擇器中固定 Fable 模型的顯示名稱。未設定時，如果 Claude Code 能辨識固定的 ID，該列會顯示模型名稱，否則顯示固定的 ID。請參閱[模型設定](/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) |

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

166| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | `haiku` 別名所解析成的模型 ID，也用於[背景功能](/docs/zh-TW/costs#background-token-usage)。請參閱[模型設定](/docs/zh-TW/model-config#environment-variables) |166| `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) |167| `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) |168| `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) |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) |

170| `ANTHROPIC_DEFAULT_MODEL` | 新工作階段預設啟動時使用的模型。需要 Claude Code v2.1.236 或更新版本。請參閱[為新工作階段設定預設模型](/docs/zh-TW/model-config#set-a-default-model-for-new-sessions) |170| `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) |171| `ANTHROPIC_DEFAULT_OPUS_MODEL` | `opus` 別名所解析到的模型 ID，也是 Plan Mode 啟用時 `opusplan` 使用的模型。請參閱[模型設定](/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) |172| `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) |173| `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) |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) |

175| `ANTHROPIC_DEFAULT_SONNET_MODEL` | `sonnet` 別名所解析成的模型 ID，也是 `opusplan` 在 Plan Mode 未啟用時使用的模型。請參閱[模型設定](/docs/zh-TW/model-config#environment-variables) |175| `ANTHROPIC_DEFAULT_SONNET_MODEL` | `sonnet` 別名所解析到的模型 ID，也是 Plan Mode 未啟用時 `opusplan` 使用的模型。請參閱[模型設定](/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) |176| `ANTHROPIC_DEFAULT_SONNET_MODEL_DESCRIPTION` | `/model` 選擇器中固定 Sonnet 模型的顯示說明。未設定時，該列會顯示以 `Custom Sonnet model` 開頭的預設說明。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

177| `ANTHROPIC_DEFAULT_SONNET_MODEL_NAME` | `/model` 選擇器中固定 Sonnet 模型的顯示名稱。未設定時，如果 Claude Code 能辨識固定的 ID，該列會顯示模型名稱，否則顯示固定的 ID。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |177| `ANTHROPIC_DEFAULT_SONNET_MODEL_NAME` | `/model` 選擇器中固定 Sonnet 模型的顯示名稱。未設定時，若 Claude Code 能識別固定的 ID，該列會顯示模型名稱，否則顯示固定的 ID。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

178| `ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES` | 固定 Sonnet 模型支援的[功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)，以逗號分隔，例如 `effort,thinking`。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |178| `ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES` | 固定 Sonnet 模型支援的[功能](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities)，以逗號分隔，例如 `effort,thinking`。請參閱[模型設定](/docs/zh-TW/model-config#customize-pinned-model-display-and-capabilities) |

179| `ANTHROPIC_FEDERATION_RULE_ID` | [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) |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) |

180| `ANTHROPIC_FOUNDRY_API_KEY` | 用於 Microsoft Foundry 身分驗證的 API 金鑰（請參閱 [Microsoft Foundry](/docs/zh-TW/microsoft-foundry)） |180| `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 或更新版本 |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 或更新版本 |

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

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)） |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_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) |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) |

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) |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_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)執行背景任務 |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)執行背景任務 |

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

190| `ANTHROPIC_VERTEX_PROJECT_ID` | Google Cloud's Agent Platform 請求所指向的 GCP 專案 ID。請參閱[設定 GCP 憑證](/docs/zh-TW/google-vertex-ai#3-configure-gcp-credentials) |190| `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 交換知道要以哪個工作區為目標 |191| `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`，也會中止長時間無回應的暫停 |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`，也會中止長時間的無聲暫停 |

193| `API_TIMEOUT_MS` | API 請求的逾時，以毫秒為單位（預設：600000，即 10 分鐘；最大值：2147483647）。當請求在緩慢網路上逾時，或透過代理伺服器路由時，請調高此值。超過最大值的值會使底層計時器溢位，並導致請求立即失敗 |193| `API_TIMEOUT_MS` | API 請求的逾時時間，以毫秒為單位（預設：600000，即 10 分鐘；最大值：2147483647）。當請求在緩慢網路上逾時，或透過代理伺服器路由時，請增加此值。超過最大值的數值會造成底層計時器溢位，導致請求立即失敗 |

194| `AWS_BEARER_TOKEN_BEDROCK` | 用於身分驗證的 Amazon Bedrock API 金鑰（請參閱 [Amazon Bedrock API 金鑰](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)） |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/)） |

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

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

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

198| `BETA_TRACING_ENDPOINT` | [詳細 beta 追蹤](/docs/zh-TW/monitoring-usage#traces-beta)的 OTLP 端點：搭配 `ENABLE_BETA_TRACING_DETAILED=1` 時，日誌與追蹤會傳送至此處，而非已設定的匯出器。請在您的 shell、使用者設定或受管設定中設定。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略 |198| `BETA_TRACING_ENDPOINT` | [詳細 beta 追蹤](/docs/zh-TW/monitoring-usage#traces-beta)的 OTLP 端點：搭配 `ENABLE_BETA_TRACING_DETAILED=1` 時，日誌與追蹤會傳送至此處，而非已設定的匯出器。請在您的 shell、使用者設定或受管設定中設定。在[專案與本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略 |

199| `CCR_FORCE_BUNDLE` | 設為 `1` 可強制 [`claude --cloud`](/docs/zh-TW/claude-code-on-the-web#send-local-repositories-without-github) 打包並上傳您的本機儲存庫，而非從其遠端複製 |199| `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` |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` |

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

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

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) 失敗 |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_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 並向上層回報停滯 |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，並向父層回報停滯 |

206| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 設定觸發自動壓縮時自動壓縮視窗的百分比（1-100）。使用較低的值（例如 `50`）可提早壓縮；此變數無法提高閾值，因此高於預設百分比的值會被忽略。僅適用於[在模型上下文限制之前壓縮](/docs/zh-TW/model-config#context-window-and-auto-compaction)的工作階段。同時適用於主要對話與 subagent |206| `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) |207| `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 或更新版本 |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 或更新版本 |

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 或更新版本 |209| `CLAUDE_AX_SCREEN_READER` | 設為 `1` 可呈現對螢幕閱讀器友善的輸出：不含裝飾性邊框或動畫的純文字。設為 `0` 可強制關閉螢幕閱讀器模式，即使 [`axScreenReader`](/docs/zh-TW/settings-reference#axscreenreader) 為 `true`。[`--ax-screen-reader`](/docs/zh-TW/cli-reference#cli-flags) 旗標優先。需要 Claude Code v2.1.181 或更新版本 |

210| `CLAUDE_AX_STARTUP_QUIET_MS` | 在[螢幕閱讀器模式](/docs/zh-TW/accessibility)中，Claude Code 在啟動確認行之後延後第一次介面呈現的毫秒數，讓您的螢幕閱讀器能在新輸出打斷之前完整唸出該行。預設為 `3000`。設定 `0` 可立即呈現。Claude Code 將延後時間上限設為 `600000`（10 分鐘）。您的第一次按鍵會提早結束延後。需要 Claude Code v2.1.217 或更新版本 |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_BYTE_STREAM_IDLE_TIMEOUT_MS` | 位元組層級串流閒置監控程式的逾時，以毫秒為單位；設定後，對於該監控程式會優先於 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`，且不影響事件層級監控程式。Claude Code 會將此變數限制在 10 秒到 30 分鐘之間。需要 Claude Code v2.1.210 或更新版本 |212| `CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` | 位元組層級串流閒置監控程式的逾時，以毫秒為單位；設定後，此變數會在該監控程式上優先於 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`，並保持事件層級監控程式不變。Claude Code 會將此變數限制在 10 秒到 30 分鐘之間。需要 Claude Code v2.1.210 或更新版本 |

213| `CLAUDE_CLIENT_PRESENCE_FILE` | 一個檔案的路徑，由外部工具（例如螢幕鎖定監聽程式）在您解鎖螢幕時建立、鎖定螢幕時刪除。檔案存在期間，Claude Code 會略過 [Remote Control 行動推播通知](/docs/zh-TW/remote-control#mobile-push-notifications)，讓您在積極使用電腦時不再收到推播。當檔案不存在或無法讀取時，通知會照常傳送。Claude Code 會在每個觸發推播的事件時檢查一次該檔案，而非輪詢。需要 Claude Code v2.1.181 或更新版本 |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_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` | 設為 `1` 可從以 `--add-dir` 指定的目錄載入記憶檔案。會載入 `CLAUDE.md`、`.claude/CLAUDE.md`、`.claude/rules/*.md` 與 `CLAUDE.local.md`。預設情況下，額外目錄不會載入記憶檔案 |215| `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` | 設為 `1` 可從以 `--add-dir` 指定的目錄載入記憶檔案。會載入 `CLAUDE.md`、`.claude/CLAUDE.md`、`.claude/rules/*.md` 與 `CLAUDE.local.md`。預設情況下，額外目錄不會載入記憶檔案 |

216| `CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT` | 設為 `1` 可在[全螢幕呈現](/docs/zh-TW/fullscreen)中每一影格重繪整個畫面，而非傳送增量更新。如果全螢幕模式顯示過時或錯位的文字片段，請使用此變數。Claude Code 會在 Windows 上為背景工作階段與 [agent view](/docs/zh-TW/agent-view) 自動啟用此功能 |216| `CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT` | 設為 `1` 可在[全螢幕呈現](/docs/zh-TW/fullscreen)中於每一幀重繪整個畫面，而非傳送增量更新。若全螢幕模式顯示過時或錯位的文字片段，請使用此設定。Claude Code 會在 Windows 上為背景工作階段與 [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）仍會被排除，以免請求失敗 |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）仍會被排除，以免請求失敗 |

218| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` | 憑證應重新整理的間隔，以毫秒為單位（使用 [`apiKeyHelper`](/docs/zh-TW/settings-reference#apikeyhelper) 時） |218| `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) 時不自動開啟瀏覽器 |219| `CLAUDE_CODE_ARTIFACT_AUTO_OPEN` | 設為 `0` 可讓 Claude Code 在發布新的 [artifact](/docs/zh-TW/artifacts#create-an-artifact) 時不自動開啟瀏覽器 |

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

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

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

223| `CLAUDE_CODE_AUTO_BACKGROUND_WORKER_CHECKIN_SECONDS` | 啟用 `CLAUDE_AUTO_BACKGROUND_TASKS` 時，提醒 Claude 檢查仍在執行中之[背景 subagent](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background) 的間隔秒數。僅接受 `1` 到 `86400` 的純整數；任何其他值或寫法都會視為未設定。未設定時，不會有檢查提醒。需要 Claude Code v2.1.248 或更新版本 |223| `CLAUDE_CODE_AUTO_BACKGROUND_WORKER_CHECKIN_SECONDS` | 已於 v2.1.283 移除。請改用 `CLAUDE_CODE_WORKER_CHECKIN_SCHEDULE` |

224| `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` 一律以模型的完整上下文視窗為基準計算，因此一旦設定此變數，該百分比就不再代表何時會執行壓縮 |224| `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) 全域設定 |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) 全域設定 |

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

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

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

229| `CLAUDE_CODE_BG_TASKS_REPORT_RUNNING` | 設為 `0` 可讓非互動工作階段在每個回合結束時向其主機回報閒置狀態，即使背景工作仍在執行中亦然。預設情況下，當背景 agent 或[工作流程](/docs/zh-TW/workflows)執行等背景工作仍在進行時，工作階段在回合結束後仍會持續回報執行中狀態。這可避免監看狀態的主機（例如遠端工作階段清單）在工作進行中宣告 Claude 正在等待您的輸入。背景 shell 命令（例如開發伺服器）不會維持執行中狀態。執行中狀態的預設行為與 `0` 選擇退出需要 Claude Code v2.1.269 或更新版本；在較早版本上，請設定 `1` 以維持執行中狀態 |229| `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` |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` |

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。若在 Windows 終端機中 [Backspace 會刪除整個單字](/docs/zh-TW/terminal-config#fix-backspace-deleting-a-whole-word-on-windows)，請設定 `0` |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` |

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

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

237| `CLAUDE_CODE_CONNECT_TIMEOUT_MS` | 已在 v2.1.186 中移除，現在不會有任何作用。先前用於為串流 API 請求的連線、TLS 與回應標頭階段設定個別的逾時。請使用 `API_TIMEOUT_MS` 設定每個請求的逾時。關於串流請求的回應標頭階段，請參閱 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` |237| `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` |238| `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` 以減少雜訊 |239| `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) |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) |

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 及更新版本無效，這些模型一律使用自適應推理 |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 及更新版本無效，這些模型一律使用自適應推理 |

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

243| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | 設為 `1` 可停用 [advisor 工具](/docs/zh-TW/advisor)。`/advisor` 命令會變成無法使用，任何已設定的 `advisorModel` 都會被忽略，而 `--advisor` 旗標仍會被接受但無效，因此傳遞此旗標的現有指令碼仍可正常運作而不會出錯 |243| `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) 設定 |244| `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) 開啟的背景工作階段，這些工作階段一律使用全螢幕呈現 |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) 開啟的背景工作階段，這些工作階段一律使用全螢幕呈現 |

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) 鍵也會將其關閉 |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_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 或更新版本 |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 或更新版本 |

249| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | 設為 `1` 可停用[自動記憶](/docs/zh-TW/memory#auto-memory)。設為 `0` 可強制開啟自動記憶，即使 `--bare` 模式或 [`autoMemoryEnabled: false`](/docs/zh-TW/settings-reference#automemoryenabled) 原本會將其停用亦然。停用時，Claude 不會建立或載入自動記憶檔案 |249| `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 快捷鍵 |250| `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 會假設閘道從原本未經修改的回應中移除了該標頭，因此會解碼主體，讓串流持續運作。僅在閘道也將串流重新以伺服器傳送事件形式發出時才設定此變數；Claude Code 接著會將無標頭的主體讀取為伺服器傳送事件。需要 Claude Code v2.1.239 或更新版本 |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 或更新版本 |

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

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

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) 設定 |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) 設定 |

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 或更新版本 |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_CRON` | 設為 `1` 可停用[排程任務](/docs/zh-TW/scheduled-tasks)。`/loop` skill 與 cron 工具會變成無法使用，且任何已排程的任務都會停止觸發，包括已在工作階段中途執行的任務 |258| `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 或更新版本 |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 或更新版本 |

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 仍會傳送的項目 |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 仍會持續傳送的內容 |

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

264| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | 設為 `1` 可停用檔案[檢查點功能](/docs/zh-TW/checkpointing)。`/rewind` 命令將無法還原程式碼變更。覆寫 [`fileCheckpointingEnabled`](/docs/zh-TW/settings-reference#filecheckpointingenabled) 設定 |264| `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) 設定 |265| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | 設為 `1` 可從 Claude 的上下文中移除內建的提交與 PR 工作流程指令，以及 git 狀態快照。在使用您自己的 git 工作流程 skill 時很有用。設定後優先於 [`includeGitInstructions`](/docs/zh-TW/settings-reference#includegitinstructions) 設定 |

266| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | 設為 `1` 可防止在 Anthropic API 上將 Opus 4.0 與 4.1 自動重新對應至目前的 Opus 版本。當您刻意想固定使用較舊的模型時使用。此重新對應不會在 Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry 上執行 |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 或更新版本 |

267| `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 或更新版本 |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 上執行 |

268| `CLAUDE_CODE_DISABLE_MOUSE` | 設為 `1` 可在[全螢幕呈現](/docs/zh-TW/fullscreen)中停用滑鼠追蹤。使用 `PgUp` 與 `PgDn` 的鍵盤捲動仍可運作。使用此變數可保留終端機原生的選取即複製行為 |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 或更新版本 |

269| `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` | 設為 `1` 可在[全螢幕呈現](/docs/zh-TW/fullscreen)中停用點選、拖曳與滑鼠懸停處理，同時保留滑鼠滾輪捲動。當您希望滾輪捲動在 Claude Code 中運作，但不希望點選會定位游標、展開工具輸出或開啟連結時使用。兩者皆設定時，`CLAUDE_CODE_DISABLE_MOUSE` 優先。需要 Claude Code v2.1.195 或更新版本 |269| `CLAUDE_CODE_DISABLE_MOUSE` | 設為 `1` 可在[全螢幕呈現](/docs/zh-TW/fullscreen)中停用滑鼠追蹤。使用 `PgUp` 與 `PgDn` 的鍵盤捲動仍可運作。使用此設定可保留終端機的原生選取即複製行為 |

270| `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 或更新版本 |270| `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_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)，該功能有其自己的選擇加入機制 |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 或更新版本 |

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)，其有自己的選擇加入機制 |

273| `CLAUDE_CODE_DISABLE_NOTIFICATION_PRESENCE_CHECK` | 設為 `1` 可讓 `PushNotification` 工具即使在您於終端機中輸入或終端機處於焦點時，仍傳送桌面通知。預設情況下，當工具偵測到最近的鍵盤活動或終端機焦點時，會同時略過桌面通知與[行動推播](/docs/zh-TW/remote-control#mobile-push-notifications)。此變數只停用該本機檢查，因此當伺服器偵測到您處於活動狀態時，仍可抑制行動推播。需要 Claude Code v2.1.193 或更新版本 |274| `CLAUDE_CODE_DISABLE_NOTIFICATION_PRESENCE_CHECK` | 設為 `1` 可在您於終端機中輸入或聚焦於終端機時，仍傳送 `PushNotification` 工具的桌面通知。預設情況下，當工具偵測到近期鍵盤活動或終端機焦點時，會同時略過桌面通知與[行動推播](/docs/zh-TW/remote-control#mobile-push-notifications)。此變數僅停用該本機檢查，因此伺服器在偵測到您處於活動狀態時仍可抑制行動推播。需要 Claude Code v2.1.193 或更新版本 |

274| `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` | 設為 `1` 可停用官方外掛市集的自動註冊。Claude Code 會在即將註冊市集時讀取此變數，通常是在電腦第一次互動式啟動期間。如果當時已設定此變數，Claude Code 會永久略過註冊。之後取消設定此變數並不會撤銷該略過。隨時執行 `claude plugin marketplace add anthropics/claude-plugins-official` 即可註冊該市集 |275| `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` | 設為 `1` 可停用官方外掛市集的自動註冊。Claude Code 會在即將註冊市集時讀取此變數，通常是在機器首次互動式啟動期間。若此時已設定此變數，Claude Code 會永久略過註冊。之後取消設定此變數不會復原該略過。隨時執行 `claude plugin marketplace add anthropics/claude-plugins-official` 即可註冊市集 |

275| `CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS` | 設為 `1` 可讓 Claude Code 在將未回答的權限請求傳送至 Agent SDK 的 `canUseTool` 回呼的工作階段中（Claude Desktop 與 VS Code 擴充功能即以此方式託管 Claude Code），不再執行您[針對未回答權限請求的 `Notification` hook](/docs/zh-TW/hooks#notification)。在終端機工作階段中無效。需要 Claude Code v2.1.233 或更新版本 |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 或更新版本 |

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

278| `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 或更新版本 |279| `CLAUDE_CODE_DISABLE_REFUSAL_FALLBACK` | 設為 `1` 可關閉[安全分類器標記請求時的自動模型切換](/docs/zh-TW/model-config#automatic-model-fallback)，即 [`switchModelsOnFlag`](/docs/zh-TW/settings-reference#switchmodelsonflag) 設定所控制的行為 |

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

280| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | 設為 `1` 可停用依據對話上下文自動更新終端機標題。這也會略過[產生工作階段標題](/docs/zh-TW/sessions#name-your-sessions)的背景小型/快速模型請求 |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 或更新版本 |

281| `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` 同樣會省略此參數，因此兩個變數在該處的行為相同 |282| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | 設為 `1` 可停用根據對話上下文自動更新終端機標題。這也會略過[產生工作階段標題](/docs/zh-TW/sessions#name-your-sessions)的背景小型/快速模型請求 |

282| `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 或更新版本 |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` 同樣會省略此參數，因此兩個變數在那裡的行為相同 |

283| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | 設為 `1` 可在[全螢幕呈現](/docs/zh-TW/fullscreen)中停用虛擬捲動，並呈現逐字稿中的每則訊息。如果在全螢幕模式中捲動時，訊息應出現的位置顯示空白區域，請使用此變數 |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 或更新版本 |

285| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | 設為 `1` 可在[全螢幕呈現](/docs/zh-TW/fullscreen)中停用虛擬捲動，並呈現逐字稿中的每則訊息。若在全螢幕模式中捲動時，應出現訊息的地方顯示空白區域，請使用此設定 |

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

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

286| `CLAUDE_CODE_DISABLE_WORKFLOWS` | 設為 `1` 可停用[工作流程](/docs/zh-TW/workflows#turn-workflows-off)。等同於 [`disableWorkflows`](/docs/zh-TW/settings-reference#disableworkflows) 設定 |288| `CLAUDE_CODE_DISABLE_WORKFLOWS` | 設為 `1` 可停用[工作流程](/docs/zh-TW/workflows#turn-workflows-off)。等同於 [`disableWorkflows`](/docs/zh-TW/settings-reference#disableworkflows) 設定 |

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

288| `CLAUDE_CODE_ENABLE_AUTO_MODE` | 為了與較舊版本相容而接受，但不會有任何作用。自動模式在每個供應商上預設皆可使用，包括 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry，以及已登入的 [Claude apps gateway](/docs/zh-TW/claude-apps-gateway) 工作階段。在 v2.1.158 至 v2.1.206 中，必須將此變數設為 `1`，才能在這些供應商上使用[自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) |290| `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)才能在這些供應商上使用 |

289| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | 覆寫[工作階段回顧](/docs/zh-TW/interactive-mode#session-recap)的可用性。設為 `0` 可強制關閉回顧，不論 `/config` 切換開關為何。設為 `1` 可在 [`awaySummaryEnabled`](/docs/zh-TW/settings-reference#awaysummaryenabled) 為 `false` 時強制開啟回顧。優先於該設定與 `/config` 切換開關 |291| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | 覆寫[工作階段回顧](/docs/zh-TW/interactive-mode#session-recap)的可用性。設為 `0` 可強制關閉回顧，不論 `/config` 切換開關為何。設為 `1` 可在 [`awaySummaryEnabled`](/docs/zh-TW/settings-reference#awaysummaryenabled) 為 `false` 時強制開啟回顧。優先於該設定與 `/config` 切換開關 |

290| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 設為 `1` 可在[非互動模式](/docs/zh-TW/headless)中，於背景安裝完成後在回合邊界重新整理外掛狀態。預設為關閉，因為重新整理會在工作階段中途變更系統提示詞，導致該回合的[提示快取](/docs/zh-TW/prompt-caching)失效 |292| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 設為 `1` 可在[非互動模式](/docs/zh-TW/headless)中，於背景安裝完成後在回合邊界重新整理外掛狀態。預設為關閉，因為重新整理會在工作階段中途變更系統提示詞，使該回合的[提示快取](/docs/zh-TW/prompt-caching)失效 |

291| `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` 與組織的產品意見回饋政策優先於此變數 |293| `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` 與組織的產品意見回饋政策優先於此變數 |

292| `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)連線上預設為關閉 |294| `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)連線上預設為關閉 |

293| `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) |295| `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) |

295| `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) |297| `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) |

296| `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) |298| `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) |

297| `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) |299| `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) |

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

301| `CLAUDE_CODE_EXTRA_BODY` | 要合併至每個 API 請求主體頂層的 JSON 物件。適用於傳遞 Claude Code 未直接公開的供應商專屬參數。在 shell 中匯出的值也會套用至您使用 `claude agents` 或 `--bg` 分派的[背景工作階段](/docs/zh-TW/agent-view)。在 v2.1.206 之前，背景工作階段會忽略 shell 匯出的值，而使用背景監督程序所繼承的副本 |303| `CLAUDE_CODE_EXTRA_BODY` | 要合併至每個 API 請求本文頂層的 JSON 物件。適用於傳遞 Claude Code 未直接公開的供應商特定參數。在您的 shell 中 export 的值也會套用至您以 `claude agents` 或 `--bg` 派送的[背景工作階段](/docs/zh-TW/agent-view)。在 v2.1.206 之前，背景工作階段會忽略 shell export 的值，而使用背景監督程序所繼承的任何副本 |

303| `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 中沒有作用，因為這兩個版本移除了它所覆寫的巢狀工作階段偵測 |305| `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 中沒有效果，因為這兩個版本移除了它所覆寫的巢狀工作階段偵測 |

304| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | 設為 `1` 可在終端機支援但未被自動偵測時（例如透過 SSH 連線且未轉送 `TERM_PROGRAM`），強制以刪除線呈現 Claude 回應中的 `~~text~~`。若未設定，未被偵測到的終端機會顯示字面的 `~~` 標記，而不是以刪除線呈現文字。需要 Claude Code v2.1.186 或更新版本 |306| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | 設為 `1` 可在您的終端機支援但未被自動偵測到時（例如透過 SSH 且未轉送 `TERM_PROGRAM`），強制以刪除線呈現 Claude 回應中的 `~~text~~`。若未設定，未被偵測到的終端機會顯示字面上的 `~~` 標記，而不是以刪除線呈現文字。需要 Claude Code v2.1.186 或更新版本 |

305| `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` 不同，此變數不會變更渲染器 |307| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 設為 `1` 可在您的終端機支援但未被自動偵測到時，強制啟用 DEC private mode 2026 [同步輸出](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)。適用於 Emacs `eat` 等實作了 BSU/ESU 但不回應功能探測的模擬器。在 tmux 下沒有效果。與會切換為[全螢幕呈現](/docs/zh-TW/fullscreen)的 `CLAUDE_CODE_NO_FLICKER` 不同，此變數不會變更呈現器 |

306| `CLAUDE_CODE_FORK_SUBAGENT` | 控制 [fork 模式](/docs/zh-TW/sub-agents#turn-fork-mode-on-or-off)，此模式可讓 Claude 自行產生 [fork 的 subagent](/docs/zh-TW/sub-agents#fork-the-current-conversation)，且僅在互動式工作階段中預設為開啟。設為 `1` 可在 `claude -p` 與 Agent SDK 中也開啟它，設為 `0` 則在所有類型的工作階段中關閉。無論 fork 模式是否開啟，您都可以執行 `/subtask`。互動式預設值需要 Claude Code v2.1.232 或更新版本；在較早版本中，請將此變數設為 `1` 以開啟 fork 模式 |308| `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` 以開啟分叉模式 |

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

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

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

310| `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) |312| `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) |

311| `CLAUDE_CODE_GLOB_HIDDEN` | 設為 `false` 可在 Claude 呼叫 [Glob 工具](/docs/zh-TW/tools-reference#glob-tool-behavior)時從結果中排除 dotfile。預設會包含。不影響 `@` 檔案自動完成、`ls`、Grep 或 Read |313| `CLAUDE_CODE_GLOB_HIDDEN` | 設為 `false` 可在 Claude 呼叫 [Glob 工具](/docs/zh-TW/tools-reference#glob-tool-behavior)時將點檔案（dotfiles）排除於結果之外。預設會包含。不影響 `@` 檔案自動完成、`ls`、Grep 或 Read |

312| `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) |314| `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) |

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

317| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | 設為 `1` 可略過 IDE 擴充功能的自動安裝。相當於將 [`autoInstallIdeExtension`](/docs/zh-TW/settings-reference#autoinstallideextension) 設為 `false` |319| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | 設為 `1` 可略過 IDE 擴充功能的自動安裝。等同於將 [`autoInstallIdeExtension`](/docs/zh-TW/settings-reference#autoinstallideextension) 設為 `false` |

319| `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` | 單一工作階段中可同時執行的 [subagent](/docs/zh-TW/sub-agents#concurrent-subagent-limit) 數量上限，超過時 Agent 工具會拒絕再產生新的 subagent（預設：20）。接受以純數字表示的正整數；其他任何值都會被忽略，因此此變數可以調整上限，但無法停用它。需要 Claude Code v2.1.217 或更新版本 |321| `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` | 一個工作階段中可同時執行多少個 [subagent](/docs/zh-TW/sub-agents#concurrent-subagent-limit)，超過後 Agent 工具會拒絕再產生新的 subagent（預設：20）。接受以純數字表示的正整數；其他任何值都會被忽略，因此此變數可調整上限但無法停用。需要 Claude Code v2.1.217 或更新版本 |

320| `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` 路由至某個模型，而其上下文視窗與該名稱的內建大小不符時使用 |322| `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` 路由至某個模型，而其上下文視窗與其名稱的內建大小不符時使用 |

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

322| `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)前可用的有效上下文視窗 |324| `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)前可用的有效上下文視窗 |

323| `CLAUDE_CODE_MAX_RETRIES` | 覆寫失敗 API 請求的重試次數（預設：10）。自 v2.1.186 起上限為 15；自 v2.1.199 起，`CLAUDE_CODE_RETRY_WATCHDOG` 會提高預設值並移除上限。對於需要撐過較長服務中斷的無人值守工作階段，請改為設定 `CLAUDE_CODE_RETRY_WATCHDOG` |325| `CLAUDE_CODE_MAX_RETRIES` | 覆寫重試失敗 API 請求的次數（預設：10）。自 v2.1.186 起上限為 15；自 v2.1.199 起，`CLAUDE_CODE_RETRY_WATCHDOG` 會提高預設值並移除上限。對於需要等待較長服務中斷的無人值守工作階段，請改為設定 `CLAUDE_CODE_RETRY_WATCHDOG` |

324| `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)仍然適用 |326| `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)仍然適用 |

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

327| `CLAUDE_CODE_MAX_TURNS` | 在未傳遞明確限制時，限制 agentic 回合的數量。相當於傳遞 [`--max-turns`](/docs/zh-TW/cli-reference#cli-flags)，若兩者皆設定則以該旗標為優先。非正整數的值會在啟動時以錯誤拒絕，而不是被視為無上限 |329| `CLAUDE_CODE_MAX_TURNS` | 在未傳遞明確限制時，限制 agentic 回合數。等同於傳遞 [`--max-turns`](/docs/zh-TW/cli-reference#cli-flags)，兩者都設定時以後者為優先。非正整數的值會在啟動時以錯誤拒絕，而不是視為無上限 |

328| `CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION` | 單一工作階段可進行的 [WebSearch](/docs/zh-TW/tools-reference#websearch-tool-behavior) 呼叫總數上限（預設：200）。當 Claude 達到上限時，後續的 WebSearch 呼叫會傳回一則通知，告訴它以已蒐集的資訊繼續進行。接受沒有上限值的正整數。其他任何值都會被忽略並套用預設值，因此此上限可以提高但無法關閉。需要 Claude Code v2.1.212 或更新版本 |330| `CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION` | 一個工作階段可進行的 [WebSearch](/docs/zh-TW/tools-reference#websearch-tool-behavior) 呼叫總數上限（預設：200）。當 Claude 達到上限時，後續的 WebSearch 呼叫會傳回一則通知，告知它使用已收集到的資訊繼續進行。接受沒有上限的正整數。其他任何值都會被忽略並套用預設值，因此上限可以提高但無法關閉。需要 Claude Code v2.1.212 或更新版本 |

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

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

332| `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 伺服器不受閒置逾時限制 |334| `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 伺服器不受閒置逾時限制 |

333| `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 或更新版本 |335| `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，而不是從父工作階段繼承，抵達的訊息會經過該工作階段的[傳入控制](/docs/zh-TW/cross-session-messaging#control-inbound-messages)。設定中的 `env` 區塊無法設定此變數。需要 Claude Code v2.1.224 或更新版本 |

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

336| `CLAUDE_CODE_NEW_INIT` | 設為 `1` 可讓 `/init` 執行互動式設定流程。此流程會在探索程式碼庫並寫入檔案之前，詢問要產生哪些檔案，包括 CLAUDE.md、skill 與 hook。若未設定此變數，`/init` 會自動產生 CLAUDE.md 而不進行詢問 |338| `CLAUDE_CODE_NEW_INIT` | 設為 `1` 可讓 `/init` 執行互動式設定流程。此流程會在探索程式碼庫並寫入檔案之前，詢問要產生哪些檔案，包括 CLAUDE.md、skill 與 hook。若未設定此變數，`/init` 會自動產生 CLAUDE.md 而不提示 |

337| `CLAUDE_CODE_NONBLOCKING_STDOUT` | 設為 `1` 可透過第二個非阻塞檔案描述元寫入終端機輸出，讓停止讀取的終端機（例如已暫停的 tmux control-mode 窗格或停滯的 SSH 連線）無法在工作階段中途凍結 Claude Code。當 stdout 為終端機時，適用於 macOS、Linux 與 WSL。需要 Claude Code v2.1.261 或更新版本 |339| `CLAUDE_CODE_NONBLOCKING_STDOUT` | 設為 `1` 可透過第二個非阻塞檔案描述元寫入終端機輸出，如此一來，停止讀取的終端機（例如暫停的 tmux control-mode 窗格或停滯的 SSH 連線）就無法在工作階段中途凍結 Claude Code。在 stdout 為終端機時，適用於 macOS、Linux 與 WSL。需要 Claude Code v2.1.261 或更新版本 |

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

339| `CLAUDE_CODE_NO_FLICKER` | 設為 `1` 可啟用[全螢幕呈現](/docs/zh-TW/fullscreen)，這是一項研究預覽功能，可減少閃爍並在長對話中維持記憶體用量穩定。覆寫 [`tui`](/docs/zh-TW/settings-reference#tui) 設定；您也可以使用 `/tui fullscreen` 切換 |341| `CLAUDE_CODE_NO_FLICKER` | 設為 `1` 可啟用[全螢幕呈現](/docs/zh-TW/fullscreen)，這是一項研究預覽功能，可減少閃爍並在長對話中維持記憶體用量平穩。覆寫 [`tui`](/docs/zh-TW/settings-reference#tui) 設定；您也可以使用 `/tui fullscreen` 切換 |

340| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | 用於 Claude.ai 身分驗證的 OAuth refresh token。設定後，`claude auth login` 會直接交換此 token，而不是開啟瀏覽器。需要 `CLAUDE_CODE_OAUTH_SCOPES`。適用於在自動化環境中佈建身分驗證 |342| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | 用於 Claude.ai 身分驗證的 OAuth refresh token。設定後，`claude auth login` 會直接交換此 token，而不是開啟瀏覽器。需要 `CLAUDE_CODE_OAUTH_SCOPES`。適用於在自動化環境中佈建身分驗證 |

341| `CLAUDE_CODE_OAUTH_SCOPES` | 核發 refresh token 時所使用的 OAuth 範圍，以空格分隔，例如 `"user:profile user:inference user:sessions:claude_code"`。設定 `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` 時為必要 |343| `CLAUDE_CODE_OAUTH_SCOPES` | 發出 refresh token 時所使用、以空格分隔的 OAuth 範圍，例如 `"user:profile user:inference user:sessions:claude_code"`。設定 `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` 時為必要 |

342| `CLAUDE_CODE_OAUTH_TOKEN` | 用於 claude.ai 身分驗證的 OAuth 存取 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 並重新啟動 |344| `CLAUDE_CODE_OAUTH_TOKEN` | 用於 claude.ai 身分驗證的 OAuth 存取 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 並重新啟動 |

343| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | 已於 v2.1.160 移除，現在不具任何作用。先前用於將[快速模式](/docs/zh-TW/fast-mode)固定為 Claude Opus 4.6，而非目前的預設值。Opus 4.6 已不再支援快速模式 |345| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | 已在 v2.1.160 中移除，現在不會產生任何作用。先前會將[快速模式](/docs/zh-TW/fast-mode)固定為 Claude Opus 4.6，而非目前的預設值。Opus 4.6 不再支援快速模式 |

344| `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) |346| `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) |

345| `CLAUDE_CODE_OTEL_DIAG_STDERR` | 設為 `1` 可將 OpenTelemetry exporter 的診斷錯誤寫入 stderr。預設情況下，這些錯誤只會在使用 `--debug` 時出現，因此設定錯誤的 exporter（例如 Prometheus 連接埠衝突）原本會無聲無息地失敗。需要 Claude Code v2.1.179 或更新版本。請參閱[監控](/docs/zh-TW/monitoring-usage) |347| `CLAUDE_CODE_OTEL_DIAG_STDERR` | 設為 `1` 可將 OpenTelemetry exporter 診斷錯誤寫入 stderr。預設情況下這些錯誤只會在使用 `--debug` 時出現，因此設定錯誤的 exporter（例如 Prometheus 連接埠衝突）否則會靜默失敗。需要 Claude Code v2.1.179 或更新版本。請參閱[監控](/docs/zh-TW/monitoring-usage) |

346| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | 清除待處理 OpenTelemetry span 的逾時時間（毫秒）（預設：5000）。請參閱[監控](/docs/zh-TW/monitoring-usage) |348| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | 清除（flush）待處理 OpenTelemetry span 的逾時時間（毫秒）（預設：5000）。請參閱[監控](/docs/zh-TW/monitoring-usage) |

347| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 重新整理動態 OpenTelemetry 標頭的間隔（毫秒）（預設：1740000 / 29 分鐘）。請參閱[動態標頭](/docs/zh-TW/monitoring-usage#dynamic-headers) |349| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 重新整理動態 OpenTelemetry 標頭的間隔（毫秒）（預設：1740000 / 29 分鐘）。請參閱[動態標頭](/docs/zh-TW/monitoring-usage#dynamic-headers) |

348| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | OpenTelemetry exporter 在關閉時完成作業的逾時時間（毫秒）（預設：2000）。若指標在結束時遺失，請提高此值。請參閱[監控](/docs/zh-TW/monitoring-usage) |350| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | OpenTelemetry exporter 在關閉時完成作業的逾時時間（毫秒）（預設：2000）。若指標在結束時遺失，請調高此值。請參閱[監控](/docs/zh-TW/monitoring-usage) |

349| `CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE` | 設為 `1` 可讓 Claude Code 在有新版本可用時，於背景執行套件管理器的升級命令。適用於 Homebrew 與 WinGet 安裝。其他套件管理器仍會顯示升級命令而不執行。請參閱[自動更新](/docs/zh-TW/setup#auto-updates) |351| `CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE` | 設為 `1` 可讓 Claude Code 在有新版本時於背景執行您套件管理工具的升級命令。適用於 Homebrew 與 WinGet 安裝。其他套件管理工具會繼續顯示升級命令而不執行。請參閱[自動更新](/docs/zh-TW/setup#auto-updates) |

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

352| `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) |354| `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) |

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

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

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

356| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 一個或多個唯讀外掛種子目錄的路徑，在 Unix 上以 `:` 分隔，在 Windows 上以 `;` 分隔。使用此變數可將預先填入的外掛目錄打包至容器映像中。Claude Code 會在啟動時從這些目錄註冊市集，並使用預先快取的外掛而無需重新複製。請參閱[為容器預先填入外掛](/docs/zh-TW/plugins/org#seed-containers-and-ci) |358| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 一或多個唯讀外掛種子目錄的路徑，在 Unix 上以 `:` 分隔，在 Windows 上以 `;` 分隔。使用此變數可將預先填入的外掛目錄打包至容器映像中。Claude Code 會在啟動時從這些目錄註冊市集，並使用預先快取的外掛而無需重新複製。請參閱[為容器預先填入外掛](/docs/zh-TW/plugins/org#seed-containers-and-ci) |

357| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | 設為 `1` 可讓 Claude Code 在為工具呼叫、hook 與狀態列命令產生 PowerShell 時，停止傳遞 `-ExecutionPolicy Bypass`，改為遵循機器的有效執行原則。預設情況下，Claude Code 會在程序範圍略過執行原則，讓 `.ps1` 腳本與模組匯入能在預設為 Restricted 的 Windows 安裝上運作。無論此設定為何，程序範圍的略過都絕不會覆寫群組原則 `MachinePolicy` 或 `UserPolicy` |359| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | 設為 `1` 可讓 Claude Code 在為工具呼叫、hook 與狀態列命令產生 PowerShell 時，不傳遞 `-ExecutionPolicy Bypass`，改為遵循機器的有效執行原則。預設情況下，Claude Code 會在程序範圍內略過執行原則，讓 `.ps1` 指令碼與模組匯入能在預設為 Restricted 的 Windows 安裝上運作。無論此設定為何，程序範圍的略過絕不會覆寫群組原則 `MachinePolicy` 或 `UserPolicy` |

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

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

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

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

362| `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) |364| `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) |

363| `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) |365| `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) |

365| `CLAUDE_CODE_REMOTE` | 當 Claude Code 以[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)執行時，會自動設為 `true`。可從 hook 或設定腳本讀取此值，以偵測您是否在雲端工作階段中 |367| `CLAUDE_CODE_REMOTE` | 當 Claude Code 以[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)執行時，會自動設為 `true`。從 hook 或設定指令碼讀取此變數，以偵測您是否處於雲端工作階段中 |

366| `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) |368| `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) |

367| `CLAUDE_CODE_RESTRICTED` | 設為 `1` 可以受限模式啟動工作階段，與傳遞 [`--restricted`](/docs/zh-TW/cli-reference#cli-flags) 相同。Claude Code 會忽略設定檔 `env` 區塊中的此變數。需要 Claude Code v2.1.248 或更新版本 |369| `CLAUDE_CODE_RESTRICTED` | 設為 `1` 可在受限模式下啟動工作階段，與傳遞 [`--restricted`](/docs/zh-TW/cli-reference#cli-flags) 相同。Claude Code 會忽略設定檔 `env` 區塊中的此變數。需要 Claude Code v2.1.248 或更新版本 |

368| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | 設為 `1` 可在前一個工作階段於回合中途結束時自動繼續。用於 SDK 模式，讓模型無需 SDK 重新傳送提示詞即可繼續。若要關閉，請取消設定此變數或將其設為 `0`。關於 VS Code 聊天面板，請參閱[重新載入後繼續對話](/docs/zh-TW/vs-code#continue-conversations-after-a-reload) |370| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | 設為 `1` 可在先前的工作階段於回合中途結束時自動恢復。用於 SDK 模式，讓模型無需 SDK 重新傳送提示詞即可繼續。若要關閉，請取消設定此變數或將其設為 `0`。關於 VS Code 聊天面板，請參閱[重新載入後繼續對話](/docs/zh-TW/vs-code#continue-conversations-after-a-reload) |

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

370| `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.`。空字串會使用預設值 |372| `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.`。空字串會使用預設值 |

371| `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 或更新版本 |373| `CLAUDE_CODE_RETRY_WATCHDOG` | 設為 `1` 可用於無人值守的工作階段，例如評估測試框架、CI 工作或遠端 worker。會無限期重試 `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 或更新版本 |

372| `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)。直接產生的子程序會繼承此變數 |374| `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)。直接產生的子程序會繼承此變數 |

373| `CLAUDE_CODE_SCRIPT_CAPS` | 當設定 `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` 時，用於限制特定腳本在每個工作階段中可被呼叫次數的 JSON 物件。鍵是與命令文字比對的子字串；值是整數呼叫上限。例如，`{"deploy.sh": 2}` 允許 `deploy.sh` 最多被呼叫兩次。比對以子字串為基礎，因此像 `./scripts/deploy.sh $(evil)` 這類 shell 展開技巧仍會計入上限。透過 `xargs` 或 `find -exec` 的執行階段擴散不會被偵測到；這是一項縱深防禦控制 |375| `CLAUDE_CODE_SCRIPT_CAPS` | JSON 物件，用於在設定 `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` 時，限制特定指令碼在每個工作階段中可被呼叫的次數。鍵是與命令文字比對的子字串；值是整數呼叫上限。例如，`{"deploy.sh": 2}` 允許 `deploy.sh` 最多被呼叫兩次。比對是以子字串為基礎，因此像 `./scripts/deploy.sh $(evil)` 這類 shell 展開技巧仍會計入上限。不會偵測透過 `xargs` 或 `find -exec` 進行的執行階段扇出；這是一項縱深防禦控制 |

374| `CLAUDE_CODE_SCROLL_SPEED` | 設定[全螢幕呈現](/docs/zh-TW/fullscreen#mouse-wheel-scrolling)中的滑鼠滾輪捲動倍數。接受最高 20 的任何正值，包括低於 1 的小數值（例如 `0.5`），以在已會放大滾輪事件的終端機中減緩加速的觸控板與滾輪捲動。若您的終端機每格傳送一個滾輪事件而未放大，請設為 `3` 以與 `vim` 一致。在 JetBrains IDE 終端機中會被忽略，Claude Code 在其中使用自己的捲動處理 |376| `CLAUDE_CODE_SCROLL_SPEED` | 設定[全螢幕呈現](/docs/zh-TW/fullscreen#mouse-wheel-scrolling)中的滑鼠滾輪捲動倍數。接受最高 20 的任何正值，包括低於 1 的小數值（例如 `0.5`），以便在已放大滾輪事件的終端機中減緩經過加速的觸控板與滾輪捲動。如果您的終端機每一格只傳送一個滾輪事件且未放大，設為 `3` 可與 `vim` 一致。在 JetBrains IDE 終端機中會被忽略，Claude Code 在該處使用自己的捲動處理 |

375| `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` 值，仍然適用 |377| `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` 值，仍然適用 |

376| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | 覆寫 [SessionEnd](/docs/zh-TW/hooks#sessionend) hook 的時間預算（毫秒）。此值也是每個未自行設定 `timeout` 之 hook 的逾時時間。適用於工作階段結束、`/clear`，以及透過互動式 `/resume` 切換工作階段。預設預算為 1.5 秒，會自動提高至設定檔中所設定的最高個別 hook `timeout`，最多 60 秒。外掛提供之 hook 的逾時不會提高預算 |378| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | 覆寫 [SessionEnd](/docs/zh-TW/hooks#sessionend) hook 的時間預算（毫秒）。此值也是每個未自行設定 `timeout` 之 hook 的逾時時間。適用於工作階段結束、`/clear`，以及透過互動式 `/resume` 切換工作階段。預設預算為 1.5 秒，會自動提高至設定檔中設定的最高個別 hook `timeout`，最多 60 秒。外掛提供之 hook 的逾時不會提高預算 |

377| `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 工作階段 |379| `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 工作階段建立關聯 |

378| `CLAUDE_CODE_SHELL` | 設定 Claude Code 用來執行 Bash 工具命令的 shell。接受 `bash` 或 `zsh` 二進位檔的路徑，例如 `/opt/homebrew/bin/bash`。不支援 `fish` 等其他 shell。若此值不是可運作的 `bash` 或 `zsh` 路徑，Claude Code 會忽略它並改用自動偵測。自動偵測會在 `$SHELL` 指向 `bash` 或 `zsh` 時使用它，否則會從您的 `PATH` 與標準安裝位置中挑選第一個可運作的 `zsh`，其次是 `bash` |380| `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` |

379| `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 執行的命令 |381| `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 執行的命令 |

380| `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) |382| `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) |

381| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 設為 `1` 可在任何模型上使用較短的系統提示詞與簡化的工具描述。設為 `0`、`false`、`no` 或 `off` 可選擇退出，即使在實驗或伺服器設定原本會啟用它的模型上也一樣。完整的工具集、hook、MCP 伺服器與 CLAUDE.md 探索仍保持啟用 |383| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 設為 `1` 可在任何模型上使用較短的系統提示詞與縮略的工具描述。設為 `0`、`false`、`no` 或 `off` 可選擇退出，即使在實驗或伺服器設定原本會啟用它的模型上亦然。完整的工具組、hook、MCP 伺服器與 CLAUDE.md 探索仍保持啟用 |

382| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | 略過 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 的用戶端身分驗證，適用於自行簽署請求的閘道 |384| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | 略過 [Claude Platform on AWS](/docs/zh-TW/claude-platform-on-aws) 的用戶端身分驗證，適用於自行簽署請求的閘道 |

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

385| `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」回應 |387| `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」回應 |

386| `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK` | 設為 `1` 可略過用戶端的[快速模式](/docs/zh-TW/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)可用性檢查，適用於攔截而非拒絕該檢查請求的代理伺服器。當您的組織停用快速模式時，API 仍會拒絕快速模式請求 |388| `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK` | 設為 `1` 可略過用戶端的[快速模式](/docs/zh-TW/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)可用性檢查，適用於攔截而非拒絕該檢查請求的代理伺服器。當您的組織已停用快速模式時，API 仍會拒絕快速模式請求 |

387| `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 用戶端無法傳送請求 |389| `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 用戶端無法傳送請求 |

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

390| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 設為 `1` 可略過將提示詞歷史記錄與工作階段逐字稿寫入磁碟。設定此變數後啟動的工作階段不會出現在 `--resume`、`--continue` 或向上鍵歷史記錄中。適用於臨時的腳本化工作階段 |392| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 設為 `1` 可略過將提示詞歷史記錄與工作階段逐字稿寫入磁碟。設定此變數後啟動的工作階段不會出現在 `--resume`、`--continue` 或向上鍵歷史記錄中。適用於短暫的指令碼工作階段 |

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

393| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | [Stop](/docs/zh-TW/hooks#stop) 或 [SubagentStop](/docs/zh-TW/hooks#subagentstop) hook 可連續阻止回合結束的最大次數，超過後 Claude Code 會覆寫它並仍結束回合（預設：8）。設為 `0` 可停用此上限。若您的 hook 確實需要更多次迭代才能解決，請提高此值 |395| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | [Stop](/docs/zh-TW/hooks#stop) 或 [SubagentStop](/docs/zh-TW/hooks#subagentstop) hook 可連續阻止回合結束的最大次數，超過後 Claude Code 會覆寫它並照樣結束回合（預設：8）。設為 `0` 可停用上限。如果您的 hook 確實需要更多次迭代才能解決，請調高此值 |

394| `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` 欄位 |396| `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` 欄位 |

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

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

397| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | 設為 `1` 可從子程序環境（Bash 工具、hook、MCP stdio 伺服器）中移除憑證：Anthropic 與雲端供應商憑證、Claude Code 識別為憑證的任何其他變數，以及內嵌在套件登錄 URL 中的憑證。父 Claude 程序會保留這些憑證以進行 API 呼叫，但子程序無法讀取它們，從而降低透過 shell 展開竊取機密的提示詞注入攻擊風險。在 v2.1.251 或更新版本中，清除作業也會移除 Claude Code 自己的設定儲存區指標變數（例如 `CLAUDE_CONFIG_DIR`），讓子程序無法找到已重新定位的設定目錄。若子程序需要這些變數，請勿設定此清除。在 Linux 上，這也會在隔離的 PID 命名空間中執行 Bash 子程序，使其無法透過 `/proc` 讀取主機程序環境；副作用是 `ps`、`pgrep` 與 `kill` 無法看到主機程序或向其傳送訊號。設定 `allowed_non_write_users` 時，`claude-code-action` 會自動設定此變數 |399| `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` 會自動設定此變數 |

398| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 在非互動模式（`-p` 旗標）中設為 `1`，可在第一個查詢之前等待外掛安裝完成。若未設定，外掛會在背景安裝，第一個回合時可能無法使用。搭配 `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` 以限制等待時間 |400| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 在非互動模式（`-p` 旗標）中設為 `1`，可在第一個查詢之前等待外掛安裝完成。若未設定，外掛會在背景安裝，可能無法在第一個回合中使用。搭配 `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` 使用以限制等待時間 |

399| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | 同步外掛安裝的逾時時間（毫秒）。超過時，Claude Code 會在沒有外掛的情況下繼續並記錄錯誤。沒有預設值：若未設定此變數，同步安裝會等待至完成為止 |401| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | 同步外掛安裝的逾時時間（毫秒）。超過時，Claude Code 會在沒有外掛的情況下繼續並記錄錯誤。沒有預設值：若未設定此變數，同步安裝會等到完成為止 |

400| `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)，例如不在您的機器上執行其 `!` 命令 |402| `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` 執行中才會下載這些 skill。`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)，例如不在您的機器上執行其 `!` 命令 |

401| `CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MS` | 當建構於 [Agent SDK](/docs/zh-TW/agent-sdk/typescript#query-object) 的應用程式重新載入 skill 時，在工作階段中途執行之 skill 重新同步的逾時時間（毫秒）（預設：30000）。超過時，重新載入會以已抵達的 skill 繼續，剩餘的下載會在背景完成 |403| `CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MS` | 當以 [Agent SDK](/docs/zh-TW/agent-sdk/typescript#query-object) 建置的應用程式重新載入 skill 時，於工作階段中途執行之 skill 重新同步的逾時時間（毫秒）（預設：30000）。超過時，重新載入會以已抵達的 skill 繼續，其餘下載則在背景完成 |

402| `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` | 設定 `CLAUDE_CODE_SYNC_SKILLS` 時，第一個查詢等待初始 skill 清單的逾時時間（毫秒）（預設：5000）。超過時，第一個查詢會以已抵達的 skill 執行。無論如何，下載都會在背景完成，Claude 在呼叫某個 skill 時會等待該 skill 下載完成 |404| `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` | 設定 `CLAUDE_CODE_SYNC_SKILLS` 時，第一個查詢等待初始 skill 清單的逾時時間（毫秒）（預設：5000）。超過時，第一個查詢會以已抵達的 skill 執行。無論如何下載都會在背景完成，而 Claude 在呼叫某個 skill 時會等待該 skill 下載完成 |

403| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | 設為 `false` 可停用差異輸出中的語法醒目提示。適用於色彩干擾終端機設定的情況。若要同時停用程式碼區塊與檔案預覽中的醒目提示，請使用 [`syntaxHighlightingDisabled`](/docs/zh-TW/settings-reference#syntaxhighlightingdisabled) 設定 |405| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | 設為 `false` 可停用差異輸出中的語法醒目提示。當色彩干擾您的終端機設定時很有用。若也要停用程式碼區塊與檔案預覽中的醒目提示，請使用 [`syntaxHighlightingDisabled`](/docs/zh-TW/settings-reference#syntaxhighlightingdisabled) 設定 |

404| `CLAUDE_CODE_TASK_LIST_ID` | 在工作階段之間共用任務清單。在[具備 Task 工具的工作階段](/docs/zh-TW/tools-reference#task-tool-availability)中，於多個 Claude Code 執行個體中設定相同的 ID，即可在共用任務清單上協調。請參閱[任務清單](/docs/zh-TW/interactive-mode#task-list) |406| `CLAUDE_CODE_TASK_LIST_ID` | 在工作階段之間共用任務清單。在多個 Claude Code 執行個體中設定相同的 ID，即可在[具備 Task 工具的工作階段](/docs/zh-TW/tools-reference#task-tool-availability)中協調共用的任務清單。請參閱[任務清單](/docs/zh-TW/interactive-mode#task-list) |

405| `CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MS` | 以毫秒為單位，覆寫非互動式工作階段在結束時等待其 [agent team](/docs/zh-TW/agent-teams) 完成拆除的時間。接受 1000 至 60000；超出範圍的值會被忽略並套用預設值 10000。需要 Claude Code v2.1.206 或更新版本 |407| `CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MS` | 以毫秒覆寫非互動式工作階段在結束時等待其 [agent team](/docs/zh-TW/agent-teams) 完成拆除的時間。接受 1000 至 60000；超出範圍的值會被忽略，並套用預設值 10000。需要 Claude Code v2.1.206 或更新版本 |

406| `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)中會被忽略 |408| `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)中會被忽略 |

407| `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) |409| `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) |

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

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

410| `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` 或負值會停用期限 |412| `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 或更新版本 |

413| `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` 或負值會停用期限 |

415| `CLAUDE_CODE_USE_NATIVE_FILE_SEARCH` | 設為 `1` 可使用 Node.js 檔案 API 而非 ripgrep 來探索自訂命令、subagent 與輸出風格。若內建的 ripgrep 二進位檔在您的環境中無法使用或遭封鎖，請設定此變數。不影響 Grep 或檔案搜尋工具 |418| `CLAUDE_CODE_USE_NATIVE_FILE_SEARCH` | 設為 `1` 可使用 Node.js 檔案 API 而非 ripgrep 來探索自訂命令、subagent 與輸出風格。如果內建的 ripgrep 二進位檔在您的環境中無法使用或遭封鎖，請設定此變數。不影響 Grep 或檔案搜尋工具 |

416| `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` 可啟用，這需要 `pwsh` 位於您的 `PATH` 中。在 Windows 上啟用時，Claude 可以原生執行 PowerShell 命令，而不需透過 Git Bash 路由。請參閱 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool) |419| `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` 可啟用，這需要 `pwsh` 位於您的 `PATH` 中。在 Windows 上啟用時，Claude 可以原生執行 PowerShell 命令，而不必透過 Git Bash 路由。請參閱 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool) |

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

419| `CLAUDE_CODE_WEBFETCH_DEADLINE_MS` | [WebFetch](/docs/zh-TW/tools-reference#webfetch-tool-behavior) 等待頁面下載完成的時間上限（毫秒），包括其所追蹤的任何重新導向。屆時仍未完成的下載會以期限錯誤失敗。預設為 `300000`，即五分鐘。設為 `0` 可移除限制。僅接受純數字；小數或任何其他寫法會維持預設值。需要 Claude Code v2.1.268 或更新版本 |422| `CLAUDE_CODE_WEBFETCH_DEADLINE_MS` | [WebFetch](/docs/zh-TW/tools-reference#webfetch-tool-behavior) 等待頁面下載完成（包括其追蹤的任何重新導向）的時間上限，以毫秒為單位。若下載在此時間之前未完成，會因期限錯誤而失敗。預設值為 `300000`，即五分鐘。設定為 `0` 可移除此限制。僅接受純數字；小數或任何其他寫法都會保留預設值。需要 Claude Code v2.1.268 或更新版本 |

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

421| `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 最多等待這麼長的時間，讓其餘 agent 讀取已快取的前綴，而不是各自在未快取的情況下處理它。預設值為 `5000`。設定為 `0` 可停用等待。設定 `DISABLE_PROMPT_CACHING` 時，agent 永遠不會等待。需要 Claude Code v2.1.229 或更新版本 |424| `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 或更新版本 |

422| `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)中會被忽略 |425| `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 或更新版本 |

423| `CLAUDE_DISABLE_ADOPT` | 設定為 `1` 可在您按下 `←` 或使用 [`/background`](/docs/zh-TW/agent-view#from-inside-a-session) 將工作階段移至背景時，停止進行中的背景工作，而非將其延續。Claude Code 會在移至背景前要求您確認，然後停止原本會延續的任務。需要 Claude Code v2.1.195 或更新版本 |426| `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)中會被忽略 |

427| `CLAUDE_DISABLE_ADOPT` | 設定為 `1`，可在您按下 `←` 或使用 [`/background`](/docs/zh-TW/agent-view#from-inside-a-session) 將工作階段移至背景時，停止進行中的背景工作，而不是將其延續下去。Claude Code 會在移至背景前要求您確認，然後停止原本會延續下去的任務。需要 Claude Code v2.1.195 或更新版本 |

424| `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 參數時設定 |428| `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 參數時設定 |

425| `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) |429| `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) |

426| `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` 設定逾時 |430| `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` 設定逾時 |

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

428| `CLAUDE_ENV_FILE` | shell 指令碼的路徑，Claude Code 會在同一個 shell 程序中、每個 Bash 命令之前執行其內容，因此檔案中的 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 動態填入 |432| `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 動態填入 |

429| `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` 呼叫不會要求權限，且該目錄會在工作階段刪除時一併移除 |433| `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` 呼叫不會提示權限，且該目錄會在工作階段刪除時一併移除 |

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

431| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | 未提供明確名稱時，自動產生的 [Remote Control](/docs/zh-TW/remote-control) 工作階段名稱的前綴。預設為您機器的主機名稱，產生類似 `myhost-graceful-unicorn` 的名稱。`--remote-control-session-name-prefix` CLI 旗標會為單次呼叫設定相同的值 |435| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | 未提供明確名稱時，自動產生的 [Remote Control](/docs/zh-TW/remote-control) 工作階段名稱的前綴。預設為您電腦的主機名稱，產生類似 `myhost-graceful-unicorn` 的名稱。`--remote-control-session-name-prefix` CLI 旗標會針對單次呼叫設定相同的值 |

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

433| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 事件層級和位元組層級串流閒置監視程式關閉停滯連線前的逾時（以毫秒為單位）。當您明確設定此變數時，最小值為 `300000`（5 分鐘）；較低的值會被靜默提高，以吸收延伸思考的暫停和代理伺服器緩衝，且位元組層級監視程式會將值上限設為 30 分鐘。對於位元組層級監視程式，`CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` 優先於此變數。關於各監視程式未設定時的預設值，請參閱[串流閒置監視程式](/docs/zh-TW/network-config#streaming-idle-watchdogs) |437| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 事件層級和位元組層級的串流閒置監控程式關閉停滯連線前的逾時時間，以毫秒為單位。當您明確設定此變數時，最小值為 `300000`（5 分鐘）；較低的值會被靜默調整，以吸收延伸思考的暫停和代理伺服器緩衝，且位元組層級的監控程式會將此值上限設為 30 分鐘。對於位元組層級的監控程式，`CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` 優先於此變數。關於各監控程式在未設定時的預設值，請參閱[串流閒置監控程式](/docs/zh-TW/network-config#streaming-idle-watchdogs) |

434| `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) |438| `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) |

435| `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:*`）不會觸發它 |439| `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:*`）不會觸發它 |

437| `DISABLE_AUTO_COMPACT` | 設定為 `1` 可停用接近上下文限制時的自動壓縮。手動 `/compact` 命令仍可使用。適用於您想明確控制壓縮發生時機的情況。覆寫 [`autoCompactEnabled`](/docs/zh-TW/settings-reference#autocompactenabled) 設定 |441| `DISABLE_AUTO_COMPACT` | 設定為 `1` 可停用接近上下文限制時的自動壓縮。手動 `/compact` 命令仍然可用。適用於您想要明確控制壓縮發生時機的情況。會覆寫 [`autoCompactEnabled`](/docs/zh-TW/settings-reference#autocompactenabled) 設定 |

440| `DISABLE_DOCTOR_COMMAND` | 設定為 `1` 可隱藏 [`/doctor`](/docs/zh-TW/commands#all-commands) 設定檢查 skill 及其 `/checkup` 別名。適用於使用者不應從工作階段執行設定診斷的受管部署。不影響 `claude doctor` 終端機命令。在 v2.1.205 之前，此變數會隱藏 `/doctor` 診斷畫面命令 |444| `DISABLE_DOCTOR_COMMAND` | 設定為 `1` 可隱藏 [`/doctor`](/docs/zh-TW/commands#all-commands) 設定檢查 skill 及其 `/checkup` 別名。適用於使用者不應從工作階段中執行設定診斷的受管部署。不影響 `claude doctor` 終端機命令。在 v2.1.205 之前，此變數會隱藏 `/doctor` 診斷畫面命令 |

443| `DISABLE_FEEDBACK_COMMAND` | 設定為 `1` 可停用 `/feedback` 命令和 [Claude 草擬的意見回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior)。也會停用透過相同路徑回報的 `/bug` 和 `/share`；在 v2.1.212 之前，它們是 `/feedback` 的別名，因此該命令在所有名稱下都會被停用。也接受較舊的名稱 `DISABLE_BUG_COMMAND` |447| `DISABLE_FEEDBACK_COMMAND` | 設定為 `1` 可停用 `/feedback` 命令和 [Claude 草擬的意見回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior)。也會停用透過相同途徑回報的 `/bug` 和 `/share`；在 v2.1.212 之前，它們是 `/feedback` 的別名，因此該命令在所有名稱下都會被停用。也接受舊名稱 `DISABLE_BUG_COMMAND` |

444| `DISABLE_GROWTHBOOK` | 設定為 `1` 或 `true` 可停用 GrowthBook 功能旗標擷取，並對每個旗標使用程式碼中的預設值。這會使 [Remote Control](/docs/zh-TW/remote-control#requirements) 和其他[需要功能旗標擷取的功能](#features-that-need-feature-flag-fetching)無法使用。設定為 `0` 或 `false` 會保持擷取開啟。除非也設定了 `DISABLE_TELEMETRY`，否則遙測事件日誌會保持開啟 |448| `DISABLE_GROWTHBOOK` | 設定為 `1` 或 `true` 可停用 GrowthBook 功能旗標擷取，並對每個旗標使用程式碼預設值。這會使 [Remote Control](/docs/zh-TW/remote-control#requirements) 和其他[需要功能旗標擷取的功能](#features-that-need-feature-flag-fetching)無法使用。將其設定為 `0` 或 `false` 會保持擷取開啟。除非也設定了 `DISABLE_TELEMETRY`，否則遙測事件日誌記錄會保持開啟 |

446| `DISABLE_INSTALL_GITHUB_APP_COMMAND` | 設定為 `1` 可隱藏 `/install-github-app` 命令。使用第三方提供者（Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry）時已預先隱藏 |450| `DISABLE_INSTALL_GITHUB_APP_COMMAND` | 設定為 `1` 可隱藏 `/install-github-app` 命令。使用第三方供應商（Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry）時已預設隱藏 |

447| `DISABLE_INTERLEAVED_THINKING` | 設定為 `1` 可避免傳送 interleaved-thinking beta 標頭。適用於您的 LLM 閘道或提供者不支援[交錯思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking)的情況 |451| `DISABLE_INTERLEAVED_THINKING` | 設定為 `1` 可防止傳送 interleaved-thinking beta 標頭。適用於您的 LLM 閘道或供應商不支援[交錯思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking)的情況 |

452| `DISABLE_PROMPT_CACHING_HAIKU` | 設定為 `1` 可為[預設 Haiku 模型](/docs/zh-TW/prompt-caching#disable-prompt-caching)停用提示快取，無論其在何處執行 |456| `DISABLE_PROMPT_CACHING_HAIKU` | 設定為 `1` 可為[預設 Haiku 模型](/docs/zh-TW/prompt-caching#disable-prompt-caching)停用提示快取，無論其在何處執行 |

455| `DISABLE_TELEMETRY` | 設定為任何非空值（例如 `1`）可選擇退出遙測。**設定為 `0` 或 `false` 仍會選擇退出**，這與大多數開關變數不同；取消設定此變數即可重新開啟遙測。遙測事件不包含程式碼、檔案路徑或 Bash 命令等使用者資料。也會停用[功能旗標擷取](#features-that-need-feature-flag-fetching)。請參閱[為您的組織關閉遙測](/docs/zh-TW/managed-settings#turn-telemetry-off-for-your-organization) |459| `DISABLE_TELEMETRY` | 設定為任何非空值（例如 `1`）可選擇退出遙測。與大多數開關變數不同，**將其設定為 `0` 或 `false` 仍會選擇退出**；請取消設定此變數以重新開啟遙測。遙測事件不包含程式碼、檔案路徑或 Bash 命令等使用者資料。也會停用[功能旗標擷取](#features-that-need-feature-flag-fetching)。請參閱[為您的組織關閉遙測](/docs/zh-TW/managed-settings#turn-telemetry-off-for-your-organization) |

456| `DISABLE_UPDATES` | 設定為 `1` 可封鎖所有更新，包括手動執行的 `claude update` 和 `claude install`。比 `DISABLE_AUTOUPDATER` 更嚴格。適用於透過您自己的通道發布 Claude Code 且使用者不應自行更新的情況 |460| `DISABLE_UPDATES` | 設定為 `1` 可封鎖所有更新，包括手動執行 `claude update` 和 `claude install`。比 `DISABLE_AUTOUPDATER` 更嚴格。適用於透過您自己的管道發布 Claude Code 且使用者不應自行更新的情況 |

458| `DO_NOT_TRACK` | 設定為 `1` 可選擇退出遙測，效果與 `DISABLE_TELEMETRY` 相同，包括對[功能旗標擷取](#features-that-need-feature-flag-fetching)的影響。Claude Code 會將此變數讀取為標準布林值，因此 `0` 會保持遙測開啟，並將其視為許多開發者 CLI 所認可的跨工具慣例來遵循 |462| `DO_NOT_TRACK` | 設定為 `1` 可選擇退出遙測，效果與 `DISABLE_TELEMETRY` 相同，包括對[功能旗標擷取](#features-that-need-feature-flag-fetching)的影響。Claude Code 將此變數讀取為標準布林值，因此 `0` 會保持遙測開啟，並將其視為許多開發者 CLI 所認可的跨工具慣例 |

459| `ENABLE_BETA_TRACING_DETAILED` | 設定為 `1` 並搭配 `BETA_TRACING_ENDPOINT`，可開啟[詳細 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)中都會被忽略 |463| `ENABLE_BETA_TRACING_DETAILED` | 設定為 `1` 並搭配 `BETA_TRACING_ENDPOINT`，可開啟[詳細 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)中都會被忽略 |

460| `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) |464| `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) |

461| `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`，它們優先於此變數 |465| `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`，它們優先於此變數 |

463| `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 上為所有模型停用工具搜尋 |467| `ENABLE_TOOL_SEARCH` | 控制 [MCP 工具搜尋](/docs/zh-TW/mcp#scale-with-mcp-tool-search)。未設定時，Claude Code 預設會延遲載入所有 MCP 工具。但在 Google Cloud's Agent Platform 上早於 Claude 4.5 世代的模型、託管於 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 上為所有模型停用工具搜尋 |

464| `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)，因此此變數不影響切換至備援模型的行為 |468| `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)，因此此變數不會影響切換到備援模型 |

466| `FORCE_HYPERLINK` | 設定為 `1` 可在您的終端機支援但未被自動偵測到時啟用可點擊的 OSC 8 超連結，或設定為 `0` 以停用超連結。未設定時，Claude Code 只會在偵測到終端機支援時啟用超連結。Claude Code 會將此值解析為數字而非布林值，因此 `false`、`no` 或 `off` 等值會啟用超連結而非停用。頁尾的 [PR 或合併請求徽章](/docs/zh-TW/interactive-mode#pr-review-status)即使在 Claude Code 無法偵測終端機支援時（例如透過 SSH）也會呈現為超連結。設定為 `0` 可將徽章呈現為純文字 |470| `FORCE_HYPERLINK` | 當您的終端機支援可點擊的 OSC 8 超連結但未被自動偵測到時，設定為 `1` 可啟用它們，設定為 `0` 則停用。未設定時，Claude Code 只有在偵測到終端機支援時才會啟用超連結。Claude Code 將此值解析為數字而非布林值，因此 `false`、`no` 或 `off` 之類的值會啟用超連結而非停用。即使 Claude Code 無法偵測到終端機支援（例如透過 SSH 時），頁尾的 [PR 或合併請求徽章](/docs/zh-TW/interactive-mode#pr-review-status)仍會以超連結呈現。設定 `0` 可將徽章呈現為純文字 |

467| `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` 設定 |471| `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` 設定 |

470| `IS_DEMO` | 設定為任何非空值（例如 `1`）可啟用示範模式：從標頭和 `/status` 輸出中隱藏您的電子郵件和組織名稱，並略過初始設定流程。**設定為 `0` 或 `false` 仍會啟用示範模式**，這與大多數開關變數不同；取消設定此變數即可關閉。適用於直播或錄製工作階段時 |474| `IS_DEMO` | 設定為任何非空值（例如 `1`）可啟用示範模式：從標頭和 `/status` 輸出中隱藏您的電子郵件和組織名稱，並略過入門導覽。與大多數開關變數不同，**將其設定為 `0` 或 `false` 仍會啟用示範模式**；請取消設定此變數以將其關閉。適用於直播或錄製工作階段時 |

471| `MAX_MCP_OUTPUT_TOKENS` | MCP 工具回應中允許的最大 token 數。當輸出超過 10,000 個 token 時，Claude Code 會顯示警告。宣告了 [`anthropic/maxResultSizeChars`](/docs/zh-TW/mcp#raise-the-limit-for-a-specific-tool) 的工具會改為對文字內容使用該字元限制，但這些工具的圖片內容仍受此變數限制（預設：25000） |475| `MAX_MCP_OUTPUT_TOKENS` | MCP 工具回應中允許的最大 token 數。當輸出超過 10,000 個 token 時，Claude Code 會顯示警告。宣告了 [`anthropic/maxResultSizeChars`](/docs/zh-TW/mcp#raise-the-limit-for-a-specific-tool) 的工具會改為對文字內容使用該字元限制，但這些工具的圖片內容仍受此變數限制（預設值：25000） |

472| `MAX_STRUCTURED_OUTPUT_RETRIES` | 在使用 `-p` 旗標的非互動模式中，當模型的回應未通過 [`--json-schema`](/docs/zh-TW/cli-reference#cli-flags) 驗證時，Claude Code 允許的嘗試次數；達到該次數的失敗嘗試且沒有任何有效輸出後，執行即會失敗。當[工作流程](/docs/zh-TW/workflows) subagent 的結構化輸出未通過驗證時，也適用相同的上限。預設為 5，即一次初始嘗試加上四次重試 |476| `MAX_STRUCTURED_OUTPUT_RETRIES` | 在使用 `-p` 旗標的非互動模式下，當模型的回應未能通過 [`--json-schema`](/docs/zh-TW/cli-reference#cli-flags) 驗證時，Claude Code 允許的嘗試次數；在達到該失敗次數且沒有有效輸出後，執行會失敗。當[工作流程](/docs/zh-TW/workflows) subagent 的結構化輸出未能通過驗證時，也會套用相同的上限。預設值為 5，即第一次嘗試加上四次重試 |

473| `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` 可關閉自適應推理的那些模型除外 |477| `MAX_THINKING_TOKENS` | [延伸思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)的固定 token 預算。Claude Code 會將其上限設為請求最大輸出 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` 關閉了自適應推理 |

474| `MCP_CLIENT_SECRET` | 需要[預先設定憑證](/docs/zh-TW/mcp#use-pre-configured-oauth-credentials)的 MCP 伺服器所使用的 OAuth 用戶端密鑰。使用 `--client-secret` 新增伺服器時可避免互動式提示 |478| `MCP_CLIENT_SECRET` | 需要[預先設定憑證](/docs/zh-TW/mcp#use-pre-configured-oauth-credentials)的 MCP 伺服器所使用的 OAuth 用戶端密碼。可避免使用 `--client-secret` 新增伺服器時出現互動式提示 |

475| `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) 時，等待的期限會較長；關於已快取伺服器的例外情況，請參閱該旗標的條目 |479| `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) 時，等待的期限會較長；關於已快取伺服器的例外情況，請參閱該旗標的項目 |

476| `MCP_CONNECT_TIMEOUT_MS` | 阻塞式 MCP 啟動在擷取工具清單快照前，等待連線批次的時間（以毫秒為單位）（預設：5000）。適用於 `MCP_CONNECTION_NONBLOCKING=0` 時，或標記為 [`alwaysLoad: true`](/docs/zh-TW/mcp#exempt-a-server-from-deferral) 的伺服器。到期限時仍在擱置中的伺服器會在背景繼續連線。與 `MCP_TIMEOUT` 不同，後者限制的是個別伺服器的連線嘗試 |480| `MCP_CONNECT_TIMEOUT_MS` | 阻塞式 MCP 啟動在擷取工具清單快照之前，等待連線批次的時間，以毫秒為單位（預設值：5000）。適用於 `MCP_CONNECTION_NONBLOCKING=0` 時，或標記為 [`alwaysLoad: true`](/docs/zh-TW/mcp#exempt-a-server-from-deferral) 的伺服器。在期限到達時仍在等待中的伺服器會在背景繼續連線。與限制個別伺服器連線嘗試的 `MCP_TIMEOUT` 不同 |

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

478| `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 不會限制此值 |482| `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 不會限制此值 |

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

480| `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 不會限制此值 |484| `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 不會限制此值 |

481| `MCP_OAUTH_CALLBACK_PORT` | OAuth 重新導向回呼的固定連接埠，可在使用[預先設定憑證](/docs/zh-TW/mcp#use-pre-configured-oauth-credentials)新增 MCP 伺服器時，作為 `--callback-port` 的替代方案 |485| `MCP_OAUTH_CALLBACK_PORT` | OAuth 重新導向回呼的固定連接埠，可在新增具有[預先設定憑證](/docs/zh-TW/mcp#use-pre-configured-oauth-credentials)的 MCP 伺服器時作為 `--callback-port` 的替代方案 |

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

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

487| `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 的值會被忽略 |491| `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 的值會被忽略 |

489| `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) |493| `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) |

490| `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) |494| `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) |

491| `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) |495| `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) |

492| `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) |496| `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) |

493| `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) |497| `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) |

494| `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) |498| `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) |

495| `OTEL_LOG_USER_PROMPTS` | 設定為 `1` 可在 OpenTelemetry 追蹤和日誌中包含使用者提示詞文字。預設停用（提示詞會被遮蔽）。請在您的 shell、使用者設定或受管設定中設定它。在[專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略，但該章節所述的關閉值除外。請參閱[監控](/docs/zh-TW/monitoring-usage) |499| `OTEL_LOG_USER_PROMPTS` | 設定為 `1` 可在 OpenTelemetry 追蹤和日誌中包含使用者提示詞文字。預設為停用（提示詞會被遮蔽）。請在您的 shell、使用者設定或受管設定中設定。在[專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略，但該節所述的關閉值除外。請參閱[監控](/docs/zh-TW/monitoring-usage) |

497| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | 設定為 `true` 可在指標屬性中包含工作階段進入點（預設：排除）。於 v2.1.152 新增。請參閱[監控](/docs/zh-TW/monitoring-usage) |501| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | 設定為 `true` 可在指標屬性中包含工作階段進入點（預設值：排除）。於 v2.1.152 新增。請參閱[監控](/docs/zh-TW/monitoring-usage) |

498| `OTEL_METRICS_INCLUDE_REPOSITORY` | 設定為 `true` 可使用識別工作階段儲存庫的 `vcs.*` 屬性標記 OpenTelemetry 指標和事件（預設：排除）。需要 Claude Code v2.1.269 或更新版本。請參閱[儲存庫屬性](/docs/zh-TW/monitoring-usage#repository-attributes) |502| `OTEL_METRICS_INCLUDE_REPOSITORY` | 設定為 `true` 可為 OpenTelemetry 指標和事件加上識別工作階段儲存庫的 `vcs.*` 屬性標籤（預設值：排除）。需要 Claude Code v2.1.269 或更新版本。請參閱[儲存庫屬性](/docs/zh-TW/monitoring-usage#repository-attributes) |

499| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | 自 v2.1.161 起，Claude Code 會將 `OTEL_RESOURCE_ATTRIBUTES` 的鍵附加至指標資料點標籤。設定為 `false` 可排除它們（預設：包含）。請參閱[監控](/docs/zh-TW/monitoring-usage#multi-team-organization-support) |503| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | 自 v2.1.161 起，Claude Code 會將 `OTEL_RESOURCE_ATTRIBUTES` 鍵附加到指標資料點標籤上。設定為 `false` 可將其排除（預設值：包含）。請參閱[監控](/docs/zh-TW/monitoring-usage#multi-team-organization-support) |

502| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | 覆寫顯示給 [Skill 工具](/docs/zh-TW/skills#control-who-invokes-a-skill)的 skill 中繼資料字元預算。預算會動態調整為上下文視窗的 1%，備援值為 8,000 個字元。為了向後相容而保留此舊名稱 |506| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | 覆寫顯示給 [Skill 工具](/docs/zh-TW/skills#control-who-invokes-a-skill)的 skill 中繼資料字元預算。此預算會以上下文視窗的 1% 動態調整，備援值為 8,000 個字元。保留舊名稱以維持向後相容性 |

503| `TASK_MAX_OUTPUT_LENGTH` | 已在 v2.1.277 中移除，現在不起作用，其所控制大小的 `TaskOutput` 工具也一併移除。先前用於設定 `TaskOutput` 工具保留的[背景任務](/docs/zh-TW/tools-reference#background-commands)輸出的最大字元數。Claude 現在改用 `Read` 讀取背景任務的輸出檔案 |507| `TASK_MAX_OUTPUT_LENGTH` | 已在 v2.1.277 中與其所調整大小的 `TaskOutput` 工具一同移除，現在不起任何作用。先前用於設定 `TaskOutput` 工具保留的[背景任務](/docs/zh-TW/tools-reference#background-commands)輸出的最大字元數。Claude 現在改用 `Read` 讀取背景任務的輸出檔案 |

524 528

525也支援標準 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)。529也支援標準 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)。

526 530

527請在您的 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`）在專案和本機設定中仍會套用。531請在您的 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`）在專案和本機設定中仍然適用。

532

533<h2 id="what-the-subprocess-environment-scrub-removes">

534 子程序環境清除會移除哪些內容

535</h2>

536

537當您將 [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](#variables) 設為 `1` 時，Claude Code 會從其啟動的子程序環境中移除憑證，例如 Bash 命令、hook 以及 stdio MCP 伺服器。這可減少提示詞注入攻擊透過 shell 展開所能讀取的內容。Claude Code 程序本身會保留這些憑證，以供其自身的 API 呼叫使用。

538

539清除機制會依據變數名稱或其值的形式來辨識憑證，因此請將其作為一道防護層，搭配範圍狹窄的[權限規則](/docs/zh-TW/permissions)一起使用，而非當作唯一的控制手段。

540

541下表說明清除機制對範例變數的處理方式：

542

543| 範例變數 | 清除機制的處理方式 |

544| :- | :- |

545| `ANTHROPIC_API_KEY`、`AWS_SECRET_ACCESS_KEY` | 移除 |

546| `NPM_TOKEN`、`DB_PASSWORD` | 移除，因為名稱看起來像憑證 |

547| 包含密碼的 `DATABASE_URL` | 移除，因為值看起來像憑證 |

548| 包含密碼的 `PIP_INDEX_URL` 或 `NPM_CONFIG_REGISTRY` | 保留 URL，但從中去除使用者名稱和密碼 |

549| `CLAUDE_CONFIG_DIR` | 移除。需要 Claude Code v2.1.251 或更新版本 |

550| `GITHUB_TOKEN`、`GH_TOKEN`、`GH_ENTERPRISE_TOKEN`、`GITHUB_ENTERPRISE_TOKEN` | 保留原狀，讓 `gh` 以及呼叫 GitHub API 的指令碼能繼續運作 |

551| `HTTP_PROXY`、`HTTPS_PROXY` | 保留原狀，包括 [URL 中的使用者名稱和密碼](/docs/zh-TW/network-config#basic-authentication)。[沙箱](/docs/zh-TW/sandboxing#network-isolation)可自行為沙箱中的命令設定這些變數 |

552| `GIT_CONFIG_COUNT`、`GIT_CONFIG_KEY_<n>`、`GIT_CONFIG_VALUE_<n>` | 無論其內容為何，皆保留原狀 |

553| 變數名稱和值看起來都不像憑證的機密 | 保留原狀 |

554

555由於清除機制會保留 `GITHUB_TOKEN`，請僅授予 GitHub Actions 工作所需的最小 `permissions`。若要從沙箱中的 Bash 命令移除 GitHub token，請在 [`sandbox.credentials`](/docs/zh-TW/sandboxing#protect-credentials) 下新增一筆 `deny` 項目。

556

557如果子程序需要其中某個會被移除的變數，請勿設定清除機制。

558

559在 Linux 上，清除機制也會在隔離的 PID 命名空間中執行 Bash 子程序，使其無法透過 `/proc` 讀取主機程序的環境。其副作用是 `ps`、`pgrep` 和 `kill` 無法看到主機程序，也無法向其傳送訊號。

528 560

529<h2 id="features-that-need-feature-flag-fetching">561<h2 id="features-that-need-feature-flag-fetching">

530 需要功能旗標擷取的功能562 需要擷取功能旗標的功能

531</h2>563</h2>

532 564

533Claude Code 透過從 Anthropic 擷取的功能旗標來啟用某些功能。Claude Code 在以下工作階段中會跳過該擷取：565Claude Code 會透過從 Anthropic 擷取的功能旗標來啟用部分功能。在下列工作階段中，Claude Code 會略過該擷取：

534 566

535* 設定 `DISABLE_GROWTHBOOK`、`DISABLE_TELEMETRY`、`DO_NOT_TRACK` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 的工作階段；[變數表](#variables)中每個變數的列會說明哪些值會關閉擷取567* 設定了 `DISABLE_GROWTHBOOK`、`DISABLE_TELEMETRY`、`DO_NOT_TRACK` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 的工作階段；[變數表](#variables)中每個變數的列會說明哪些值會關閉擷取

536* [第三方提供者](/docs/zh-TW/third-party-integrations)上的工作階段，例如 Amazon Bedrock、AWS 上的 Claude Platform、Google Cloud 的 Agent Platform 或 Microsoft Foundry，除非嵌入 Claude Code 的主機平台設定 `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`568* 使用[第三方供應商](/docs/zh-TW/third-party-integrations)（例如 Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 或 Microsoft Foundry）的工作階段，除非嵌入 Claude Code 的主機平台設定了 `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`

537* [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway)工作階段569* [Claude apps 閘道](/docs/zh-TW/claude-apps-gateway)工作階段

538 570

539擷取關閉時，您無法：571關閉擷取時，您無法：

540 572

541* 執行 [`/auto-mode-setup`](/docs/zh-TW/auto-mode-config#generate-environment-entries) 來草擬 `autoMode.environment` 項目573* 執行 [`/auto-mode-setup`](/docs/zh-TW/auto-mode-config#generate-environment-entries) 來草擬 `autoMode.environment` 項目

542* 使用[遠端控制](/docs/zh-TW/remote-control)，其中設定 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 或 `DISABLE_GROWTHBOOK`。對於 `DISABLE_TELEMETRY` 和 `DO_NOT_TRACK`，請參閱[遠端控制需求](/docs/zh-TW/remote-control#requirements)574* 在設定了 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 或 `DISABLE_GROWTHBOOK` 的情況下使用 [Remote Control](/docs/zh-TW/remote-control)。關於 `DISABLE_TELEMETRY` 和 `DO_NOT_TRACK`，請參閱 [Remote Control 需求](/docs/zh-TW/remote-control#requirements)

543* [訊息工作階段超越此機器](/docs/zh-TW/cross-session-messaging#message-sessions-on-other-machines)，當[遠端控制](/docs/zh-TW/remote-control#requirements)無法使用時。此機器上工作階段之間的訊息傳遞在擷取關閉時可運作575* 在 [Remote Control](/docs/zh-TW/remote-control#requirements) 無法使用時，[傳送訊息給此機器以外的工作階段](/docs/zh-TW/cross-session-messaging#message-sessions-on-other-machines)。關閉擷取時，此機器上工作階段之間的訊息傳送仍可運作

544* 執行 [`claude import` 或 `/import` 命令](/docs/zh-TW/cli-reference#cli-commands)576* 執行 [`claude import` 或 `/import` 命令](/docs/zh-TW/cli-reference#cli-commands)

545* 執行 [`/skill-doctor`](/docs/zh-TW/skills#find-unused-skills) 或在 `/plugin` **Stats** 標籤中開啟其報告577* 執行 [`/skill-doctor`](/docs/zh-TW/skills#find-unused-skills)，或在 `/plugin` 的 **Stats** 分頁中開啟其報告

546* 同步為您的 claude.ai 帳戶啟用的[技能](/docs/zh-TW/skills#where-synced-skills-load)和[外掛程式](/docs/zh-TW/plugins/loading#synced-plugins)到您的終端工作階段578* 將您的 claude.ai 帳戶所啟用的 [skills](/docs/zh-TW/skills#where-synced-skills-load) 和[外掛](/docs/zh-TW/plugins/loading#synced-plugins)同步到您的終端機工作階段

547* 使用[顧問工具](/docs/zh-TW/advisor#requirements)579* 使用 [advisor 工具](/docs/zh-TW/advisor#requirements)

548* 讀取或回覆[成品上的評論](/docs/zh-TW/artifacts#collect-comments-on-an-artifact)580* 閱讀或回覆 [artifact 上的留言](/docs/zh-TW/artifacts#collect-comments-on-an-artifact)

549* 讓 Claude 讀取[其他組織的公開 artifact](/docs/zh-TW/artifacts#read-an-artifact-shared-with-you)581* 讓 Claude 讀取[其他組織的公開 artifact](/docs/zh-TW/artifacts#read-an-artifact-shared-with-you)

550* 讓 Claude Code 探測 claude.ai 連接器伺服器或 stdio 伺服器是否支援 [MCP 協定修訂版本 2026-07-28](/docs/zh-TW/mcp#mcp-client-runtimes)，除非您設定 `MCP_PROTOCOL_NEGOTIATION=auto`582* 讓 Claude Code 探測 claude.ai 連接器伺服器或 stdio 伺服器是否支援 [MCP 協定修訂版 2026-07-28](/docs/zh-TW/mcp#mcp-client-runtimes)，除非您設定 `MCP_PROTOCOL_NEGOTIATION=auto`

551* 在安裝 Git Bash 的 Windows 上預設為 claude.ai 和 Console 帳戶取得 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool)；Claude Code 透過 Git Bash 路由 Shell 命令，除非您設定 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`。在沒有 Git Bash 的 Windows 上，工具保持開啟583* 在已安裝 Git Bash 的 Windows 上，為 claude.ai 和 Console 帳戶預設取得 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool)；除非您設定 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`，否則 Claude Code 會透過 Git Bash 執行 shell 命令。在未安裝 Git Bash 的 Windows 上，該工具會保持啟用

552* 取得 [Claude 草擬的回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior)，Claude Code 透過擷取的旗標來啟用此功能584* 取得 [Claude 草擬的意見回饋](/docs/zh-TW/tools-reference#sendfeedback-tool-behavior)，Claude Code 是透過擷取的旗標來啟用此功能

553* 讓 Claude [將大型貼上視為貼上而非輸入的文字](/docs/zh-TW/terminal-config#how-claude-treats-pasted-text)；`[Pasted text #N]` 預留位置後面的內容會以未標記的方式到達 Claude585* 讓 Claude [將大量貼上內容視為貼上的文字，而非輸入的文字](/docs/zh-TW/terminal-config#how-claude-treats-pasted-text)；`[Pasted text #N]` 預留位置背後的內容會未經標記地傳送給 Claude

554* 讓 Claude Code [排除 MCP 工具，其輸入結構描述 API 會拒絕](/docs/zh-TW/mcp#tools-with-invalid-input-schemas)；它仍會傳送結構描述，包含它的請求會失敗，並出現[命名工具位置的 400 錯誤](/docs/zh-TW/errors#tool-input-schema-is-invalid)586* 讓 Claude Code [排除 API 會拒絕其輸入 schema 的 MCP 工具](/docs/zh-TW/mcp#tools-with-invalid-input-schemas)；它仍會傳送該 schema，而包含該 schema 的請求會失敗，並出現[依位置指出該工具的 400 錯誤](/docs/zh-TW/errors#tool-input-schema-is-invalid)

555 587

556<h3 id="first-session-after-an-install-or-upgrade">588<h3 id="first-session-after-an-install-or-upgrade">

557 安裝或升級後的第一個工作階段589 安裝或升級後的第一個工作階段

558</h3>590</h3>

559 591

560在您安裝 Claude Code 或升級到新增功能的版本後的第一個工作階段中，[旗標閘道功能](#features-that-need-feature-flag-fetching)可能會遺失。該工作階段也可能以不同的[權限模式](/docs/zh-TW/permission-modes#which-mode-a-session-starts-in)啟動，而不是您稍後的工作階段。Claude Code 在該工作階段期間擷取旗標，因此您的下一個工作階段具有該功能和通常的起始權限模式。592在您安裝 Claude Code 後，或升級到新增某項功能的版本後的第一個工作階段中，[受旗標控管的功能](#features-that-need-feature-flag-fetching)可能不存在。該工作階段的起始[權限模式](/docs/zh-TW/permission-modes#which-mode-a-session-starts-in)也可能與您之後的工作階段不同。當 Claude Code 在該工作階段中擷取旗標時，會將其儲存在機器上，因此您在該機器上的下一個工作階段就會具備該功能及一般的起始權限模式。

593

594全新安裝後，在非互動式工作階段（例如 `claude -p`、Agent SDK 或 VS Code 擴充功能）中，Claude Code 可能會在[選擇起始權限模式](/docs/zh-TW/permission-modes#which-mode-a-session-starts-in)之前取得旗標，但不一定會等待旗標。

595

596在如下的設定中，第一個之後的工作階段也會在沒有新擷取旗標的情況下啟動：

597

598* **每次執行都是乾淨的環境**：如果每次執行都在 CI 容器中啟動，或在任何沒有先前工作階段所儲存旗標的環境中啟動，則每次執行都是第一個工作階段

599* **沒有 API 金鑰的閘道 token**：如果您使用 `ANTHROPIC_AUTH_TOKEN` 進行身分驗證且沒有 API 金鑰，而 `ANTHROPIC_BASE_URL` 指向 Anthropic 以外的主機（例如 [LLM 閘道](/docs/zh-TW/llm-gateway)），Claude Code 就沒有可用來擷取旗標的憑證

561 600

562在全新安裝後，在非互動式工作階段（例如 `claude -p`、Agent SDK 或 VS Code 擴充功能）中，Claude Code 仍可在[選擇起始權限模式](/docs/zh-TW/permission-modes#which-mode-a-session-starts-in)之前擷取旗標。601若要選擇這些設定中工作階段的起始權限模式，請參閱[以不同的權限模式啟動](/docs/zh-TW/permission-modes#start-in-a-different-mode)。

563 602

564<h2 id="see-also">603<h2 id="see-also">

565 另請參閱604 另請參閱

errors.md +19 −1

Details

369| `Denying Bash also turns off the PowerShell tool, so Claude has neither` | [設定警告](#denying-bash-also-turns-off-the-powershell-tool) |

846**該怎麼做：**847**該怎麼做：**

847 848

848* 在 Pro 和 Max 上，在 claude.ai 的[**設定 > 使用量**](https://claude.ai/settings/usage)中提高您的每月支出限制，或執行 `/usage-credits`849* 在 Pro 和 Max 上，在 claude.ai 的[**設定 > 使用量**](https://claude.ai/settings/usage)中提高您的每月支出限制，或執行 `/usage-credits`

849* 在 Team 和 Enterprise 上，如果您管理計費，請在[**管理設定 > 使用量**](https://claude.ai/admin-settings/usage)中提高限制，或要求管理員提高。`/usage-credits` 會為您向您的管理員發送該請求850* 在 Team 和 Enterprise 上，如果您管理計費，請在[**組織設定 > 使用量**](https://claude.ai/admin-settings/usage)中提高限制，或請管理員提高。`/usage-credits` 會為您向管理員發送該請求

850* 對於頻道的限制，要求組織擁有者或頻道的管理員在 claude.ai 上提高它。請參閱 Claude Tag 文件中的[每頻道限制](https://claude.com/docs/claude-tag/admins/set-spend-limit#per-channel-limits)851* 對於頻道的限制，要求組織擁有者或頻道的管理員在 claude.ai 上提高它。請參閱 Claude Tag 文件中的[每頻道限制](https://claude.com/docs/claude-tag/admins/set-spend-limit#per-channel-limits)

851* 如果訊息命名您的方案視窗的重設時間，您可以改為等待它852* 如果訊息命名您的方案視窗的重設時間，您可以改為等待它

852* 執行 `/usage` 以查看您的方案視窗和每個視窗何時重設853* 執行 `/usage` 以查看您的方案視窗和每個視窗何時重設

5638 5639

5639在[背景工作階段](/docs/zh-TW/agent-view)或使用 `--output-format json` 或 `stream-json` 時，Claude Code 將警告寫入偵錯日誌而不是 stderr，因此機器讀取輸出保持乾淨。使用 `--debug` 在 `~/.claude/debug/<session-id>.txt` 處擷取它。在 v2.1.246 之前，Claude Code 接受這些規則而不警告。5640在[背景工作階段](/docs/zh-TW/agent-view)或使用 `--output-format json` 或 `stream-json` 時，Claude Code 將警告寫入偵錯日誌而不是 stderr，因此機器讀取輸出保持乾淨。使用 `--debug` 在 `~/.claude/debug/<session-id>.txt` 處擷取它。在 v2.1.246 之前，Claude Code 接受這些規則而不警告。

5640 5641

5642<h3 id="denying-bash-also-turns-off-the-powershell-tool">

5643 Denying Bash also turns off the PowerShell tool

5644</h3>

5645

5646您移除了整個 Bash 工具，例如使用 `--disallowedTools Bash`，或在您的某個設定檔中使用單純的 `Bash` 或 `Bash(*)` [拒絕規則](/docs/zh-TW/permissions#match-all-uses-of-a-tool)。在已安裝 Git Bash 的 Windows 上，[拒絕 Bash 也會關閉 PowerShell 工具](/docs/zh-TW/tools-reference#bash-deny-rules-also-turn-off-the-powershell-tool)，因此工作階段啟動時沒有任何 shell 工具。Claude Code 會在啟動時列印此警告：

5647

5648```text theme={null}

5649Denying Bash also turns off the PowerShell tool, so Claude has neither. To use PowerShell, set CLAUDE_CODE_USE_POWERSHELL_TOOL=1.

5650```

5651

5652**該怎麼做：**

5653

5654* 若要讓 Claude 使用 PowerShell，請在您的環境中或設定檔的 `env` 區塊中將 [`CLAUDE_CODE_USE_POWERSHELL_TOOL`](/docs/zh-TW/env-vars) 設定為 `1`，如[啟用 PowerShell 工具](/docs/zh-TW/tools-reference#enable-the-powershell-tool)所示。之後 PowerShell 工具會保持開啟，與您的 Bash 拒絕規則並存。

5655* 若要封鎖特定命令而非整個工具，請在同一設定檔或旗標中，將單純的 `Bash` 項目替換為有範圍的規則，例如 `Bash(git push *)`。Claude 會保留 Bash 工具，而 PowerShell 工具會保持關閉，直到您也設定該變數或新增有範圍的 [`PowerShell` 權限規則](/docs/zh-TW/permissions#powershell)。

5656

5657在[背景工作階段](/docs/zh-TW/agent-view)中或使用 `--output-format json` 或 `stream-json` 時，Claude Code 會將警告寫入偵錯日誌而不是 stderr。使用 `--debug` 執行，即可在 `~/.claude/debug/<session-id>.txt` 擷取它。在 v2.1.287 之前，Claude Code 會以相同方式關閉 PowerShell 工具，但不列印警告。

5658

5641<h3 id="crosssessioninbound-must-be-one-of-accept-hold-refuse">5659<h3 id="crosssessioninbound-must-be-one-of-accept-hold-refuse">

5642 crossSessionInbound 必須是 accept、hold、refuse 之一5660 crossSessionInbound 必須是 accept、hold、refuse 之一

5643</h3>5661</h3>

fast-mode.md +4 −4

Details

136快速模式需要以下所有條件：136快速模式需要以下所有條件：

137 137

138* **僅限 Anthropic API 或訂閱**：快速模式可透過 Anthropic Console API 和使用額度的 Claude 訂閱方案取得。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 AWS 上的 Claude Platform 上無法使用。Console 組織還必須[為您的組織佈建快速模式存取](#enable-fast-mode-for-your-organization)。138* **僅限 Anthropic API 或訂閱**：快速模式可透過 Anthropic Console API 和使用額度的 Claude 訂閱方案取得。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 AWS 上的 Claude Platform 上無法使用。Console 組織還必須[為您的組織佈建快速模式存取](#enable-fast-mode-for-your-organization)。

139* **為訂閱方案開啟使用額度**：在 Pro、Max、Team 或 Enterprise 方案上，您的帳戶必須[開啟使用額度](/docs/zh-TW/costs#add-usage-credits-to-your-subscription)，這允許超出您方案包含使用量的計費。在開啟之前，`/fast` 會報告「快速模式需要使用額度」。您開啟它們的方式取決於您的方案：139* **為訂閱方案開啟用量點數**：在 Pro、Max、Team 或 Enterprise 方案上，您的帳戶必須開啟[用量點數](/docs/zh-TW/costs#add-usage-credits-to-your-subscription)，這允許超出您方案包含使用量的計費。在開啟之前，`/fast` 會報告「快速模式需要用量點數」。您開啟它們的方式取決於您的方案：

140 * 在 Pro 和 Max 上，在 claude.ai 上的 [**設定 > 使用量**](https://claude.ai/settings/usage) 的 **使用額度** 部分開啟它們，或執行 `/usage-credits` 以開啟該頁面。140 * 在 Pro 和 Max 上，在 claude.ai 上的 [**設定 > 使用量**](https://claude.ai/settings/usage) 的 **用量點數** 部分開啟它們，或執行 `/usage-credits` 以開啟該頁面。

141 * 在 Team 和 Enterprise 上，具有計費存取權限的成員在 [**管理設定 > 使用量**](https://claude.ai/admin-settings/usage) 為組織開啟它們，沒有存取權限的成員執行 `/usage-credits` 以向組織的管理員發送請求。141 * 在 Team 和 Enterprise 上，具有計費存取權限的成員在 [**組織設定 > 使用量**](https://claude.ai/admin-settings/usage) 為組織開啟它們，沒有存取權限的成員執行 `/usage-credits` 以向組織的管理員發送請求。

142 142

143<Note>143<Note>

144 快速模式使用量直接從使用額度中扣除，即使您在方案上還有剩餘使用量。144 快速模式使用量直接從使用額度中扣除，即使您在方案上還有剩餘使用量。

165* **Console**（API 客戶）：管理員在 [Claude Code 偏好設定](https://platform.claude.com/claude-code/preferences)中啟用它。快速模式處於[研究預覽](#research-preview)中，因此您的組織還必須在快速模式請求成功之前佈建快速模式存取。若要取得存取權，請聯絡您的帳戶經理或加入等候清單，如 [Claude API 上的快速模式](https://platform.claude.com/docs/en/build-with-claude/fast-mode)中所述。165* **Console**（API 客戶）：管理員在 [Claude Code 偏好設定](https://platform.claude.com/claude-code/preferences)中啟用它。快速模式處於[研究預覽](#research-preview)中，因此您的組織還必須在快速模式請求成功之前佈建快速模式存取。若要取得存取權，請聯絡您的帳戶經理或加入等候清單，如 [Claude API 上的快速模式](https://platform.claude.com/docs/en/build-with-claude/fast-mode)中所述。

166 166

167 沒有佈建的存取權，API 會以 429 拒絕每個快速模式請求，Claude Code 會將每個拒絕視為[快速模式速率限制](#handle-rate-limits)。與速率限制的冷卻時間不同，拒絕會持續到佈建存取權為止。167 沒有佈建的存取權，API 會以 429 拒絕每個快速模式請求，Claude Code 會將每個拒絕視為[快速模式速率限制](#handle-rate-limits)。與速率限制的冷卻時間不同，拒絕會持續到佈建存取權為止。

168* **Claude AI**（Team 和 Enterprise）：擁有者在 [管理設定 > Claude Code](https://claude.ai/admin-settings/claude-code) 啟用它168* **Claude AI**（Team 和 Enterprise）：擁有者在 [**組織設定 > Claude Code**](https://claude.ai/admin-settings/claude-code) 啟用它

169 169

170另一個完全停用快速模式的選項是設定 `CLAUDE_CODE_DISABLE_FAST_MODE=1`。請參閱[環境變數](/docs/zh-TW/env-vars)。170另一個完全停用快速模式的選項是設定 `CLAUDE_CODE_DISABLE_FAST_MODE=1`。請參閱[環境變數](/docs/zh-TW/env-vars)。

171 171

features-overview.md +4 −4

Details

248| **Subagents** | 生成時 | 具有指定 skills 的新鮮上下文，或用於[分支](/docs/zh-TW/sub-agents#fork-the-current-conversation)的父對話 | 與主會話隔離 |248| **Subagents** | 生成時 | 具有指定 skills 的新鮮上下文，或用於[分支](/docs/zh-TW/sub-agents#fork-the-current-conversation)的父對話 | 與主會話隔離 |

249| **Hooks** | 觸發時 | 無（外部運行） | 零，除非 hook 返回額外上下文 |249| **Hooks** | 觸發時 | 無（外部運行） | 零，除非 hook 返回額外上下文 |

250 250

251\*預設情況下，skill 描述在會話開始時載入，以便 Claude 決定何時使用它們。在 skill 的 frontmatter 中設置 `disable-model-invocation: true` 以將其完全隱藏在 Claude 中，直到您手動調用它。對於您未編寫的 skill，在設置中設置 [`skillOverrides`](/docs/zh-TW/skills#override-skill-visibility-from-settings) 以執行相同操作，而無需編輯其檔案。251\*在 skill 的 frontmatter 中設定 [`disable-model-invocation: true`](/docs/zh-TW/skills#control-who-invokes-a-skill)，以將其描述排除在 Claude 的上下文之外。對於您未編寫的 skill，在設定中設定 [`skillOverrides`](/docs/zh-TW/skills#override-skill-visibility-from-settings) 以執行相同操作，而無需編輯其檔案。

252 252

253<h3 id="understand-how-features-load">253<h3 id="understand-how-features-load">

254 了解功能如何載入254 了解功能如何載入

278 278

279 **什麼載入：** 對於模型可調用的 skills，Claude 在每個請求中看到名稱和描述。當您使用 `/<name>` 調用 skill 或 Claude 自動載入它時，完整內容載入到您的對話中。279 **什麼載入：** 對於模型可調用的 skills，Claude 在每個請求中看到名稱和描述。當您使用 `/<name>` 調用 skill 或 Claude 自動載入它時，完整內容載入到您的對話中。

280 280

281 **Claude 如何選擇 skills：** Claude 將您的任務與 skill 描述相匹配，以決定哪些相關。如果描述模糊或重疊，Claude 可能載入錯誤的 skill 或錯過會有幫助的。要告訴 Claude 使用特定 skill，請使用 `/<name>` 調用它。具有 `disable-model-invocation: true` 的 Skills 對 Claude 不可見，直到您調用它們。281 **Claude 如何選擇 skills：** Claude 將您的任務與 skill 描述相匹配，以決定哪些相關。如果描述模糊或重疊，Claude 可能載入錯誤的 skill 或錯過會有幫助的。要告訴 Claude 使用特定 skill，請使用 `/<name>` 調用它。

282 282

283 **上下文成本：** 低，直到使用。僅使用者 skills 在調用前成本為零。283 **上下文成本：** 低，直到使用。僅使用者 skills 在調用前成本為零。

284 284

285 **在 subagents 中：** Skills 在 subagents 中的工作方式不同。不是按需載入，subagent 的 `skills` 欄位中列出的 skills 在啟動時完全預載入其上下文。Subagents 仍然可以通過 Skill 工具發現和調用未列出的專案、使用者和 plugin skills。285 **在 subagents 中：** Skills 在 subagents 中的工作方式不同。不是按需載入，subagent 的 `skills` 欄位中列出的 skills 在啟動時完全預載入其上下文。Subagents 仍然可以通過 Skill 工具發現和調用未列出的專案、使用者和 plugin skills。

286 286

287 <Tip>對具有副作用的 skills 使用 `disable-model-invocation: true`。這節省上下文並確保只有您觸發它們。</Tip>287 <Tip>對具有副作用的 skills 使用 `disable-model-invocation: true`。這節省上下文並確保它們只在您指名時執行。</Tip>

288 </Tab>288 </Tab>

289 289

290 <Tab title="MCP 伺服器">290 <Tab title="MCP 伺服器">

291 **何時：** 會話開始。291 **何時：** 工作階段開始。

292 292

293 **什麼載入：** 來自連接伺服器的工具名稱和伺服器指令。完整 JSON 架構保持延遲，直到 Claude 需要特定工具。293 **什麼載入：** 來自連接伺服器的工具名稱和伺服器指令。完整 JSON 架構保持延遲，直到 Claude 需要特定工具。

294 294

fullscreen.md +1 −1

Details

109* **點擊清單邊緣的 `↑ N more` 或 `↓ N more` 列**，以跳至清單的該端，而不選擇任何選項。需要 Claude Code v2.1.286 或更新版本。109* **點擊清單邊緣的 `↑ N more` 或 `↓ N more` 列**，以跳至清單的該端，而不選擇任何選項。需要 Claude Code v2.1.286 或更新版本。

110* **點擊已摺疊的工具結果**，以展開它並查看完整輸出。再次點擊以摺疊。工具呼叫及其結果會一起展開。只有有更多內容要顯示的訊息才可點擊。110* **點擊已摺疊的工具結果**，以展開它並查看完整輸出。再次點擊以摺疊。工具呼叫及其結果會一起展開。只有有更多內容要顯示的訊息才可點擊。

111 * 點擊也會展開 `!` shell 命令的輸出，無論是較舊的截斷結果或命令執行時的即時進度列。需要 Claude Code v2.1.257 或更新版本。111 * 點擊也會展開 `!` shell 命令的輸出，無論是較舊的截斷結果或命令執行時的即時進度列。需要 Claude Code v2.1.257 或更新版本。

112 * 點擊也會展開當寄件者是[隊友](/docs/zh-TW/agent-teams)或在您的工作階段中執行的另一個代理時的暗淡 `Message from @<sender>` 列。來自[您其他工作階段之一](/docs/zh-TW/cross-session-messaging#what-a-message-looks-like)的訊息列也會顯示訊息的第一行，且無法點擊，因此按 `Ctrl+o` 以讀取該訊息。112 * 點擊也會展開當寄件者是[隊友](/docs/zh-TW/agent-teams)或在您的工作階段中執行的另一個 agent 時的暗淡 `Message from @<sender>` 列。

113* **在 macOS 上按住 `Cmd`，或在 Linux 和 Windows 上按住 `Ctrl`，然後點擊 URL 或檔案路徑**，以開啟它。純 `http://` 和 `https://` URL 會在您的瀏覽器中開啟，而工具輸出中的檔案路徑（例如在 Edit 或 Write 後列印的路徑）會在您的預設應用程式中開啟。不使用修飾鍵的純點擊不會開啟連結，符合原生終端機行為。113* **在 macOS 上按住 `Cmd`，或在 Linux 和 Windows 上按住 `Ctrl`，然後點擊 URL 或檔案路徑**，以開啟它。純 `http://` 和 `https://` URL 會在您的瀏覽器中開啟，而工具輸出中的檔案路徑（例如在 Edit 或 Write 後列印的路徑）會在您的預設應用程式中開啟。不使用修飾鍵的純點擊不會開啟連結，符合原生終端機行為。

114 * Claude Code 會將網路 (UNC) 路徑（例如 `\\server\share\file.ts`）呈現為純文字，沒有連結，因為開啟網路路徑可能會將您的 Windows 認證傳送到它命名的主機。114 * Claude Code 會將網路 (UNC) 路徑（例如 `\\server\share\file.ts`）呈現為純文字，沒有連結，因為開啟網路路徑可能會將您的 Windows 認證傳送到它命名的主機。

115 * 某些 macOS 終端機會將 `Cmd`+點擊轉發給執行中的應用程式，而不是自己開啟連結，而終端機滑鼠協定無法編碼 `Cmd` 鍵，因此 Claude Code 會收到純點擊。在 Ghostty 以及 macOS 上的 Warp 中，Claude Code 會偵測到這一點，並讓純點擊連結開啟它，而按住 `Cmd` 仍然有效。115 * 某些 macOS 終端機會將 `Cmd`+點擊轉發給執行中的應用程式，而不是自己開啟連結，而終端機滑鼠協定無法編碼 `Cmd` 鍵，因此 Claude Code 會收到純點擊。在 Ghostty 以及 macOS 上的 Warp 中，Claude Code 會偵測到這一點，並讓純點擊連結開啟它，而按住 `Cmd` 仍然有效。

google-vertex-ai.md +17 −0

Details

295 295

296當這些檢查發現您的專案無法呼叫的模型時，Claude Code 會在此機器上記住拒絕長達一天，並在該時間內啟動時略過記住的模型，而不會再次詢問 Agent Platform。Claude Code 會在距離上次檢查已過十分鐘後，再次檢查目前預設模型的記住拒絕，因此您的管理員重新啟用的預設值會恢復。若要關閉此記憶功能，請設定 [`CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY=1`](/docs/zh-TW/env-vars)。296當這些檢查發現您的專案無法呼叫的模型時，Claude Code 會在此機器上記住拒絕長達一天，並在該時間內啟動時略過記住的模型，而不會再次詢問 Agent Platform。Claude Code 會在距離上次檢查已過十分鐘後，再次檢查目前預設模型的記住拒絕，因此您的管理員重新啟用的預設值會恢復。若要關閉此記憶功能，請設定 [`CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY=1`](/docs/zh-TW/env-vars)。

297 297

298<h3 id="when-your-organization-enforces-a-model-allowlist">

299 當您的組織強制執行模型允許清單時

300</h3>

301

302如果您在受管設定中設定 [`enforceAvailableModels`](/docs/zh-TW/model-config#enforce-the-allowlist-for-the-default-model)，啟動模型檢查只會使用您的 `availableModels` 清單所允許的模型。這需要 Claude Code v2.1.287 或更新版本。未搭配 `enforceAvailableModels` 的清單不會限制這些檢查。

303

304這些檢查會將每個項目與其將傳送至 Agent Platform 的模型 ID 進行比較，因此請以這些 ID 撰寫清單。此範例允許 Opus 4.8 和 Sonnet 4.5：

305

306```json theme={null}

307{

308 "availableModels": ["claude-opus-4-8", "claude-sonnet-4-5@20250929"],

309 "enforceAvailableModels": true

310}

311```

312

313關於別名、版本前綴和 `modelOverrides` 項目，請參閱[為第三方部署固定模型](/docs/zh-TW/model-config#pin-models-for-third-party-deployments)。

314

298<h3 id="when-a-model-is-disabled-mid-session">315<h3 id="when-a-model-is-disabled-mid-session">

299 當模型在工作階段中被停用時316 當模型在工作階段中被停用時

300</h3>317</h3>

headless.md +1 −1

Details

59| 系統提示詞新增 | `--append-system-prompt`、`--append-system-prompt-file` |59| 系統提示詞新增 | `--append-system-prompt`、`--append-system-prompt-file` |

60| 設定 | `--settings <file-or-json>` |60| 設定 | `--settings <file-or-json>` |

61| MCP 伺服器 | `--mcp-config <file-or-json>` |61| MCP 伺服器 | `--mcp-config <file-or-json>` |

63| 一個 plugin | `--plugin-dir <path>`、`--plugin-url <url>` |63| 一個 plugin | `--plugin-dir <path>`、`--plugin-url <url>` |

64 64

65bare 模式也會限制工作階段執行期間發生的事情：65bare 模式也會限制工作階段執行期間發生的事情：

hooks.md +46 −10

Details

438| 欄位 | 必要 | 說明 |438| 欄位 | 必要 | 說明 |

439| :- | :- | :- |439| :- | :- | :- |

440| `type` | 是 | `"command"`、`"http"`、`"mcp_tool"`、`"prompt"` 或 `"agent"` |440| `type` | 是 | `"command"`、`"http"`、`"mcp_tool"`、`"prompt"` 或 `"agent"` |

441| `if` | 否 | 用於篩選此 hook 執行時機的權限規則語法，例如 `"Bash(git *)"` 或 `"Edit(*.ts)"`。只有在工具呼叫符合該模式時，hook 命令才會執行。請參閱下方的 [Bash 比對表](#bash-if-matching)，了解 Bash 模式如何針對子命令、`$()` 與反引號進行評估。僅在工具事件上評估：`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest` 與 `PermissionDenied`。在其他事件上，設定了 `if` 的 hook 永遠不會執行。使用與[權限規則](/docs/zh-TW/permissions)相同的語法 |441| `if` | 否 | 用於篩選此 hook 執行時機的[權限規則語法](/docs/zh-TW/permissions#permission-rule-syntax)，例如 `"Bash(git *)"` 或 `"Edit(*.ts)"`。只有在工具呼叫符合該模式時，hook 命令才會執行。請參閱 [Bash 比對表](#bash-if-matching)，了解 Bash 模式如何針對子命令、`$()` 與反引號進行評估。僅在工具事件上評估：`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest` 與 `PermissionDenied`。在其他事件上，設定了 `if` 的 hook 永遠不會執行 |

442| `timeout` | 否 | 取消前的秒數。對於以 [`async: true`](#run-hooks-in-the-background) 執行的命令 hook，Claude Code 不會強制執行此值。預設值：`command`、`http` 與 `mcp_tool` 為 600；`prompt` 為 30；`agent` 為 60。在 [`UserPromptSubmit`](#userpromptsubmit)、[`PreModelSwitch`](#premodelswitch) 與 [`PostModelSwitch`](#postmodelswitch) 上，Claude Code 會將 `command`、`http` 與 `mcp_tool` 的預設值降為 30，在 [`MessageDisplay`](#messagedisplay) 上則降為 10。[`SessionEnd`](#sessionend) hook 共用 1.5 秒的時間預算；若您的設定為個別 hook 設定了更長的 `timeout`，Claude Code 會將預算提高以配合，最多 60 秒 |442| `timeout` | 否 | 取消前的秒數。對於以 [`async: true`](#run-hooks-in-the-background) 執行的命令 hook，Claude Code 不會強制執行此值。預設值：`command`、`http` 與 `mcp_tool` 為 600；`prompt` 為 30；`agent` 為 60。在 [`UserPromptSubmit`](#userpromptsubmit)、[`PreModelSwitch`](#premodelswitch) 與 [`PostModelSwitch`](#postmodelswitch) 上，Claude Code 會將 `command`、`http` 與 `mcp_tool` 的預設值降為 30，在 [`MessageDisplay`](#messagedisplay) 上則降為 10。[`SessionEnd`](#sessionend) hook 共用 1.5 秒的時間預算；若您的設定為個別 hook 設定了更長的 `timeout`，Claude Code 會將預算提高以配合，最多 60 秒 |

443| `statusMessage` | 否 | hook 執行期間顯示的自訂轉圈訊息 |443| `statusMessage` | 否 | hook 執行期間顯示的自訂轉圈訊息 |

444| `once` | 否 | 若為 `true`，Claude Code 會在 hook 第一次成功執行後將其移除。執行失敗、以退出碼 2 封鎖或逾時的情況下，hook 會保留，因此在下一個符合的事件上會再次執行。僅對在 [skill frontmatter](#hooks-in-skills-and-agents) 中宣告的 hook 生效；在設定檔與 agent frontmatter 中會被忽略 |444| `once` | 否 | 若為 `true`，Claude Code 會在 hook 第一次成功執行後將其移除。執行失敗、以退出碼 2 封鎖或逾時的情況下，hook 會保留，因此在下一個符合的事件上會再次執行。僅對在 [skill frontmatter](#hooks-in-skills-and-agents) 中宣告的 hook 生效；在設定檔與 agent frontmatter 中會被忽略 |

447 447

448在檔案工具的 `if` 條件中，像 `"Edit(src/**)"` 這樣的單一區段目錄模式只會符合工作目錄中的 `src` 目錄及其下的檔案。若要符合任意深度中名為 `src` 的目錄，請寫成 `"Edit(**/src/**)"`。在 v2.1.214 之前，`"Edit(src/**)"` 會符合工作目錄下任意深度中名為 `src` 的目錄。448在檔案工具的 `if` 條件中，像 `"Edit(src/**)"` 這樣的單一區段目錄模式只會符合工作目錄中的 `src` 目錄及其下的檔案。若要符合任意深度中名為 `src` 的目錄，請寫成 `"Edit(**/src/**)"`。在 v2.1.214 之前，`"Edit(src/**)"` 會符合工作目錄下任意深度中名為 `src` 的目錄。

449 449

450<span id="bash-if-matching" />對於 Bash 模式，您的 hook 命令是否執行取決於模式的形式以及 Claude 所叫用的 Bash 命令。比對前會先移除開頭的 `VAR=value` 指派。450<h4 id="bash-if-matching">

451 `if` 模式如何比對 Bash 命令

452</h4>

453

454對於 [`if` 欄位](#common-fields)中的 Bash 模式，您的 hook 命令是否執行取決於模式的形式以及 Claude 所叫用的 Bash 命令。比對前會先移除開頭的 `VAR=value` 指派。

451 455

453| :- | :- | :- | :- |457| :- | :- | :- | :- |

1913 1917

1914| 欄位 | 類型 | 範例 | 說明 |1918| 欄位 | 類型 | 範例 | 說明 |

1915| :- | :- | :- | :- |1919| :- | :- | :- | :- |

1916| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React"}], "multiSelect": false}]` | 要呈現的問題，每個問題包含 `question` 字串、簡短的 `header`、`options` 陣列，以及選擇性的 `multiSelect` 旗標 |1920| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React", "description": "Component library"}, {"label": "Vue", "description": "Progressive framework"}], "multiSelect": false}]` | 要呈現的問題，每個問題包含 `question` 字串、簡短的 `header`、`options` 陣列，以及選用的 `multiSelect` 旗標 |

1917| `answers` | object | `{"Which framework?": "React"}` | 選擇性。將問題文字對應到所選選項的標籤。多選答案會以逗號連接標籤。Claude 不會設定此欄位；請透過 `updatedInput` 提供，以程式化方式作答 |1921| `answers` | object | `{"Which framework?": "React"}` | 選擇性。將問題文字對應到所選選項的標籤。多選答案會以逗號連接標籤。Claude 不會設定此欄位；請透過 `updatedInput` 提供，以程式化方式作答 |

1918 1922

1919<h5 id="exitplanmode">1923<h5 id="exitplanmode">

1965}1969}

1966```1970```

1967 1971

1968<span id="allow-with-updatedinput" />1972<Note>

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

1974</Note>

1969 1975

1970在使用 `-p` 旗標的[非互動模式](/docs/zh-TW/headless)中，只有當執行具有接收提示的[權限主機](/docs/zh-TW/headless#turn-off-permission-prompts-in-unattended-runs)（例如 Agent SDK 的 `canUseTool` 回呼）時，Claude Code 才會提供 `AskUserQuestion` 與 `ExitPlanMode`。這些工具需要使用者互動。回傳 `permissionDecision: "allow"` 並搭配 `updatedInput` 即可滿足此需求：hook 從 stdin 讀取工具的輸入，透過您自己的 UI 收集答案，並在 `updatedInput` 中回傳，讓工具在不提示的情況下執行。對於這些工具，只回傳 `"allow"` 是不夠的。對於 `AskUserQuestion`，請回傳原始的 `questions` 陣列，並加入一個 [`answers`](#askuserquestion) 物件，將每個問題的文字對應到所選的答案。1976<h4 id="allow-with-updatedinput">

1977 需要使用者互動的工具

1978</h4>

1971 1979

1972伺服器以 [`_meta["anthropic/requiresUserInteraction"]`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 標記的 MCP 工具則更為嚴格：hook 無法以 `"allow"` 略過其核准提示，無論是否搭配 `updatedInput`，因為 Claude Code 無法確認 hook 已收集該工具所需的互動。1980`AskUserQuestion` 與 `ExitPlanMode` 需要使用者互動。在搭配 `-p` 旗標的[非互動模式](/docs/zh-TW/headless)中，只有當執行有可接收提示的[權限主機](/docs/zh-TW/headless#turn-off-permission-prompts-in-unattended-runs)（例如 Agent SDK 的 `canUseTool` 回呼）時，Claude Code 才會提供這些工具。

1973 1981

1974<Note>1982當 `PreToolUse` hook 執行下列動作時，即可滿足該需求：

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

1976</Note>19841. 從 stdin 讀取工具的輸入

19852. 透過您自己的 UI 收集答案

19863. 傳回 `permissionDecision: "allow"`，並搭配包含答案的 `updatedInput`，讓工具在不提示的情況下執行

1987

1988對這些工具而言，僅傳回 `"allow"` 是不夠的。

1989

1990對於 `AskUserQuestion`，請回傳原始的 `questions` 陣列，並新增一個 [`answers`](#askuserquestion) 物件，將每個問題的文字對應到所選答案。此輸出以 `React` 回答一個問題：

1991

1992```json theme={null}

1993{

1994 "hookSpecificOutput": {

1995 "hookEventName": "PreToolUse",

1996 "permissionDecision": "allow",

1997 "updatedInput": {

1998 "questions": [

1999 {

2000 "question": "Which framework?",

2001 "header": "Framework",

2002 "options": [{"label": "React", "description": "Component library"}, {"label": "Vue", "description": "Progressive framework"}],

2003 "multiSelect": false

2004 }

2005 ],

2006 "answers": {"Which framework?": "React"}

2007 }

2008 }

2009}

2010```

2011

2012伺服器以 [`_meta["anthropic/requiresUserInteraction"]`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 標記的 MCP 工具則更為嚴格：hook 無法以 `"allow"` 略過其核准提示，無論是否搭配 `updatedInput`，因為 Claude Code 無法確認 hook 已收集該工具所需的互動。

1977 2013

1978<h4 id="defer-a-tool-call-for-later">2014<h4 id="defer-a-tool-call-for-later">

1979 延後工具呼叫2015 延後工具呼叫

2000 "deferred_tool_use": {2036 "deferred_tool_use": {

2001 "id": "toolu_01abc",2037 "id": "toolu_01abc",

2002 "name": "AskUserQuestion",2038 "name": "AskUserQuestion",

2003 "input": { "questions": [{ "question": "Which framework?", "header": "Framework", "options": [{"label": "React"}, {"label": "Vue"}], "multiSelect": false }] }2039 "input": { "questions": [{ "question": "Which framework?", "header": "Framework", "options": [{"label": "React", "description": "Component library"}, {"label": "Vue", "description": "Progressive framework"}], "multiSelect": false }] }

2004 }2040 }

2005}2041}

2006```2042```

interactive-mode.md +2 −0

Details

470* 您的帳戶接近或已達到使用限制。若要在達到限制之前保持建議開啟，請將 [`CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION`](/docs/zh-TW/env-vars) 設定為 `true`。在 v2.1.238 之前，即使將變數設定為 `true`，Claude Code 也會在接近限制時跳過建議470* 您的帳戶接近或已達到使用限制。若要在達到限制之前保持建議開啟，請將 [`CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION`](/docs/zh-TW/env-vars) 設定為 `true`。在 v2.1.238 之前，即使將變數設定為 `true`，Claude Code 也會在接近限制時跳過建議

471* 在[代理團隊](/docs/zh-TW/agent-teams)中，預設情況下在隊友的工作階段中。主導者的工作階段會顯示建議471* 在[代理團隊](/docs/zh-TW/agent-teams)中，預設情況下在隊友的工作階段中。主導者的工作階段會顯示建議

472 472

473通知 `Showing fewer prompt suggestions · use one to bring them back` 表示 Claude Code 顯示建議的頻率降低了，因為您連續多次未使用建議。若要恢復為一般頻率，請使用一個建議，或將 [`CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION`](/docs/zh-TW/env-vars) 設定為 `true`。

474

473在列印模式中，Claude Code 預設不會產生建議。使用 [`--prompt-suggestions`](/docs/zh-TW/cli-reference#cli-flags) 搭配 `-p "<prompt>" --output-format stream-json --verbose` 讓 Claude Code 在每個產生建議的輪次後發出 `prompt_suggestion` 訊息。產生器在此也會跳過非常短的對話和冷提示快取，因此單一短 `-p` 查詢可能不會發出任何建議。475在列印模式中，Claude Code 預設不會產生建議。使用 [`--prompt-suggestions`](/docs/zh-TW/cli-reference#cli-flags) 搭配 `-p "<prompt>" --output-format stream-json --verbose` 讓 Claude Code 在每個產生建議的輪次後發出 `prompt_suggestion` 訊息。產生器在此也會跳過非常短的對話和冷提示快取，因此單一短 `-p` 查詢可能不會發出任何建議。

474 476

475<h3 id="turn-prompt-suggestions-off">477<h3 id="turn-prompt-suggestions-off">

keybindings.md +4 −0

Details

464| :- | :- | :- |464| :- | :- | :- |

467| `agents:find` | Ctrl+F | 使用 [`n:` 篩選器](/docs/zh-TW/agent-view#filter-sessions) 依名稱尋找工作階段。需要 v2.1.288 或更新版本 |

468| `agents:rename` | Ctrl+R | [重新命名](/docs/zh-TW/agent-view#organize-the-list) 選定的工作階段。需要 v2.1.288 或更新版本 |

469| `agents:previousGroup` | Ctrl+Up, Meta+Up | 跳到上一個 [群組標題](/docs/zh-TW/agent-view#organize-the-list)。需要 v2.1.288 或更新版本 |

470| `agents:nextGroup` | Ctrl+Down, Meta+Down | 跳到下一個群組標題。需要 v2.1.288 或更新版本 |

467 471

468當代理檢視開啟時，Claude Code 會對 `Agents` 上下文綁定的任何按鍵使用 `Agents` 綁定，並忽略同一按鍵上的 `Chat` 或 `Global` 綁定。例如，在代理檢視中按 Ctrl+S 會切換工作階段分組，而不是觸發預設的 `chat:stash`。472當代理檢視開啟時，Claude Code 會對 `Agents` 上下文綁定的任何按鍵使用 `Agents` 綁定，並忽略同一按鍵上的 `Chat` 或 `Global` 綁定。例如，在代理檢視中按 Ctrl+S 會切換工作階段分組，而不是觸發預設的 `chat:stash`。

469 473

managed-mcp.md +61 −29

Details

282 282

283允許清單和拒絕清單會篩選允許載入哪些已設定的伺服器。它們不是登錄表：伺服器仍然必須由使用者、外掛程式或您的組織新增，才能讓任一清單對其適用。283允許清單和拒絕清單會篩選允許載入哪些已設定的伺服器。它們不是登錄表：伺服器仍然必須由使用者、外掛程式或您的組織新增，才能讓任一清單對其適用。

284 284

285您的組織透過 `managedMcpServers` 提供的伺服器會在沒有允許清單項目的情況下載入，而[伺服器如何被評估](#how-a-server-is-evaluated)涵蓋 `managed-mcp.json` 伺服器。拒絕清單適用於每個伺服器，無論其來自何處，除了進程內 `type: "sdk"` 項目外。285您的組織透過 `managedMcpServers` 提供的伺服器會在沒有允許清單項目的情況下載入，而[跳過允許清單檢查的伺服器](#servers-that-skip-the-allowlist-check)涵蓋 `managed-mcp.json` 伺服器。拒絕清單適用於每個伺服器，無論其來自何處，除了程序內 `type: "sdk"` 項目外。

286 286

287若要將伺服器部署給使用者，請使用 [`managed-mcp.json`](#exclusive-control-with-managed-mcp-json) 或 [`managedMcpServers`](#provide-servers-through-managed-settings)。兩個清單也會篩選使用 [`--mcp-config` CLI 旗標](/docs/zh-TW/cli-reference#cli-flags)傳遞的伺服器，除了進程內 `type: "sdk"` 項目外；`--strict-mcp-config` 限制哪些設定檔會載入，不會繞過任一清單。287若要將伺服器部署給使用者，請使用 [`managed-mcp.json`](#exclusive-control-with-managed-mcp-json) 或 [`managedMcpServers`](#provide-servers-through-managed-settings)。兩個清單也會篩選使用 [`--mcp-config` CLI 旗標](/docs/zh-TW/cli-reference#cli-flags)傳遞的伺服器，除了進程內 `type: "sdk"` 項目外；`--strict-mcp-config` 限制哪些設定檔會載入，不會繞過任一清單。

288 288

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

312 312

313將 `allowedMcpServers` 保留未設定與將其設定為空陣列不同：313將 `allowedMcpServers` 保留未設定與將其設定為空陣列不同：

314 314

315| 設定 | 未設定（預設） | 空陣列 `[]` | 已填入 |315| 設定 | 未設定（預設） | 空陣列 `[]` | 已填入 |

316| :- | :- | :- | :- |316| :- | :- | :- | :- |

319 319

320請參閱[受管設定中的無效項目](/docs/zh-TW/managed-settings#invalid-entries-in-managed-settings)，了解項目未通過結構描述驗證時會發生什麼。320請參閱[受管設定中的無效項目](/docs/zh-TW/managed-settings#invalid-entries-in-managed-settings)，了解項目未通過結構描述驗證時會發生什麼。

321 321

322<h4 id="how-servername-entries-match">

323 `serverName` 項目如何比對

324</h4>

325

326`serverName` 項目會精確比對使用者指派的標籤，不支援萬用字元。

327

322<Warning>328<Warning>

323 任一清單中的 `serverName` 項目不是安全控制。名稱是使用者在執行 `claude mcp add` 或編輯設定檔時指派的標籤，而不是基礎伺服器，因此使用者可以呼叫任何伺服器 `github`。對於 claude.ai 連接器，名稱是 claude.ai 傳回的顯示名稱，可能會變更。若要強制執行實際執行的伺服器，請新增 `serverCommand` 或 `serverUrl` 項目。329 任一清單中的 `serverName` 項目不是安全控制。名稱是使用者在執行 `claude mcp add` 或編輯設定檔時指派的標籤，而不是基礎伺服器，因此使用者可以呼叫任何伺服器 `github`。對於 claude.ai 連接器，名稱是 claude.ai 傳回的顯示名稱，可能會變更。若要強制執行實際執行的伺服器，請新增 `serverCommand` 或 `serverUrl` 項目。

324</Warning>330</Warning>

330 336

331若要關閉 Claude Code 自行擷取的所有 claude.ai 連接器，請參閱 [`disableClaudeAiConnectors`](/docs/zh-TW/mcp#disable-claude-ai-connectors)。337若要關閉 Claude Code 自行擷取的所有 claude.ai 連接器，請參閱 [`disableClaudeAiConnectors`](/docs/zh-TW/mcp#disable-claude-ai-connectors)。

332 338

333<h3 id="how-a-server-is-evaluated">339<h4 id="how-servercommand-entries-match">

334 伺服器如何被評估340 `serverCommand` 項目如何比對

335</h3>341</h4>

~~336~~

337在載入伺服器之前（包括來自 `managed-mcp.json` 的伺服器），Claude Code 會按順序執行以下三項檢查。當使用者重新連接伺服器或在 `/mcp` 中開啟已停用的伺服器時，它會再次執行它們。進程內 `type: "sdk"` 伺服器（[啟動工作階段的應用程式註冊](/docs/zh-TW/mcp#how-connectors-reach-claude-code)）會跳過全部三項。

~~338~~

3391. **合併清單。** 來自每個設定範圍的允許清單和拒絕清單項目合併為一個允許清單和一個拒絕清單。當 `allowManagedMcpServersOnly` 為 `true` 時，僅保留受管允許清單；拒絕清單始終從每個範圍合併。當存在多個受管來源時，[從每個管理員來源讀取的鍵](/docs/zh-TW/managed-settings#keys-read-from-every-admin-source)說明其中哪些提供受管範圍的清單。

3402. **檢查拒絕清單。** 與任何拒絕清單項目比對的伺服器（按 URL、命令或名稱）會被阻止。沒有任何東西會覆蓋拒絕清單比對。

3413. **檢查允許清單。** 如果 `allowedMcpServers` 未在任何地方設定，每個通過拒絕清單的伺服器都會載入。如果已設定，伺服器必須比對的內容取決於其類型，如下表所示。

~~342~~

343 三組伺服器會跳過此檢查：

344 342

345 * 組織自己的伺服器：每個 `managedMcpServers` 項目，以及任何 `managed-mcp.json` 項目，其值不使用 `${VAR}` 展開。343`serverCommand` 項目將命令及其引數保存為一個陣列，例如 `{ "serverCommand": ["npx", "-y", "server"] }`。Claude Code 會將該陣列與伺服器設定中的命令和引數進行比較：

346 * 內建伺服器，例如 Chrome 中的 Claude、Claude Code 在執行中的 VS Code 或 JetBrains IDE 中連接的 `ide` 伺服器，以及 CLI 本身設定的伺服器。

347 * [Claude Tag](/docs/zh-TW/claude-tag) 工作階段的 Slack 工具：它用來讀取執行緒和發佈回覆的伺服器會在沒有允許清單項目的情況下載入。

348 344

349 在其命令、引數、`env`、URL 或標頭中使用 `${VAR}` 展開的 `managed-mcp.json` 伺服器仍會被檢查。使用者、外掛程式或 claude.ai 新增的每個伺服器也會被檢查，以及使用者使用 `--mcp-config` 傳遞的每個伺服器。345* **命令精確比對。** 每個引數，按順序。`["npx", "-y", "server"]` 不比對 `["npx", "server"]` 或 `["npx", "-y", "server", "--flag"]`。

346* **不比較 `env` 區塊。** `["node", "server.js"]` 會比對以任何 `env` 值執行該命令的伺服器。某些環境變數會變更 `node` 在啟動時載入的內容。若要自行設定 `env` 值，請在 [`managed-mcp.json`](#exclusive-control-with-managed-mcp-json) 中定義伺服器。

350 347

351| 伺服器類型 | 比對時允許 |348<h4 id="how-serverurl-entries-match">

352| :- | :- |349 `serverUrl` 項目如何比對

353| 遠端（HTTP 或 SSE） | 一個 `serverUrl` 項目。當允許清單不包含 `serverUrl` 項目時，`serverName` 比對才計數 |350</h4>

354| Stdio | 一個 `serverCommand` 項目。當允許清單不包含 `serverCommand` 項目時，`serverName` 比對才計數 |

355 351

356這些檢查內部適用三個比對規則：352URL 支援在模式中的任何地方使用 `*` 萬用字元，包括 scheme。主機名稱比對不區分大小寫，並忽略尾隨 FQDN 點，因此 `https://Mcp.Example.com/*` 比對 `https://mcp.example.com/api`。路徑保持區分大小寫。

357 353

358* **命令精確比對。** 每個引數，按順序。`["npx", "-y", "server"]` 不比對 `["npx", "server"]` 或 `["npx", "-y", "server", "--flag"]`。354下表顯示常見模式允許的內容：

359* **`serverCommand` 和 `serverUrl` 值在比對前展開。** 政策項目和伺服器的已設定值都會經過 [`${VAR}` 和 `${VAR:-default}` 展開](/docs/zh-TW/mcp#environment-variable-expansion-in-mcp-json)，因此寫成 `["${HOME}/bin/server"]` 的項目會比對使用相同參考或展開路徑的伺服器設定。在 Windows 上，參考在該處設定的環境變數，例如 `${USERPROFILE}` 而不是 `${HOME}`。`serverName` 值按字面比對，永遠不會展開。兩側讀取不同的環境；[政策項目如何展開](#how-policy-entries-expand)涵蓋哪個以及允許清單和拒絕清單項目如何不同。

360* **URL 支援 `*` 萬用字元**在模式中的任何地方，包括配置。主機名稱比對不區分大小寫，並忽略尾隨 FQDN 點，因此 `https://Mcp.Example.com/*` 比對 `https://mcp.example.com/api`。路徑保持區分大小寫。

361 355

362| 模式 | 允許 |356| 模式 | 允許 |

363| :- | :- |357| :- | :- |

368| `*://mcp.example.com/*` | 任何配置到特定網域 |362| `*://mcp.example.com/*` | 任何配置到特定網域 |

369 363

370<h4 id="how-policy-entries-expand">364<h4 id="how-policy-entries-expand">

371 政策項目如何展開365 `serverCommand` 和 `serverUrl` 項目中的環境變數

372</h4>366</h4>

373 367

374伺服器的已設定值從即時程序環境展開，就像 `.mcp.json` 的其餘部分一樣。政策項目改為從固定環境展開，因此由專案或使用者設定檔設定的變數無法變更允許清單項目的含義。因為政策項目仍然取決於啟動殼層對其參考的任何變數的值，請對您依賴以進行強制執行的項目使用字面 URL 和命令。368`serverCommand` 和 `serverUrl` 值在比對前展開。政策項目和伺服器的已設定值都會經過 [`${VAR}` 和 `${VAR:-default}` 展開](/docs/zh-TW/mcp#environment-variable-expansion-in-mcp-json)，因此寫成 `["${HOME}/bin/server"]` 的項目會比對使用相同參考或展開路徑的伺服器設定。`serverName` 值按字面比對，永遠不會展開。

369

370兩側讀取不同的環境：

371

372* **伺服器的已設定值**：從即時程序環境展開，就像 `.mcp.json` 的其餘部分一樣

373* **政策項目**：從固定環境展開，因此由專案或使用者設定檔設定的變數無法變更允許清單項目的含義

374

375因為政策項目仍然取決於啟動 shell 對其參考的任何變數的值，請對您依賴以進行強制執行的項目使用字面 URL 和命令。

376

377在 Windows 上，請參考在該處設定的環境變數，例如 `${USERPROFILE}` 而不是 `${HOME}`。

378

379兩個清單的展開方式不同：

375 380

376| 項目清單 | 展開自 | 會變更 URL 項目的配置、主機或路徑範圍的展開 |381| 項目清單 | 展開自 | 會變更 URL 項目的配置、主機或路徑範圍的展開 |

377| - | - | - |382| - | - | - |

380 385

381需要 Claude Code v2.1.219 或更新版本。386固定環境和此表中的規則需要 Claude Code v2.1.219 或更新版本。

387

388<h3 id="how-a-server-is-evaluated">

389 伺服器如何被評估

390</h3>

391

392在載入伺服器之前（包括來自 `managed-mcp.json` 的伺服器），Claude Code 會按順序執行以下三項檢查。當使用者重新連接伺服器或在 `/mcp` 中開啟已停用的伺服器時，它會再次執行它們。程序內 `type: "sdk"` 伺服器（由[啟動工作階段的應用程式註冊](/docs/zh-TW/mcp#how-connectors-reach-claude-code)）會跳過全部三項。

393

3941. **合併清單。** 來自每個設定範圍的允許清單和拒絕清單項目合併為一個允許清單和一個拒絕清單。當 `allowManagedMcpServersOnly` 為 `true` 時，僅保留受管允許清單；拒絕清單始終從每個範圍合併。當存在多個受管來源時，[從每個管理員來源讀取的鍵](/docs/zh-TW/managed-settings#keys-read-from-every-admin-source)說明其中哪些提供受管範圍的清單。

3952. **檢查拒絕清單。** 與任何拒絕清單項目比對的伺服器（按 URL、命令或名稱）會被阻止。沒有任何東西會覆寫拒絕清單比對。

3963. **檢查允許清單。** [某些伺服器會跳過此檢查](#servers-that-skip-the-allowlist-check)。如果 `allowedMcpServers` 未在任何地方設定，每個通過拒絕清單的伺服器都會載入。如果已設定，伺服器必須比對的內容取決於其類型，如下表所示。

397

398| 伺服器類型 | 比對時允許 |

399| :- | :- |

400| 遠端（HTTP 或 SSE） | 一個 `serverUrl` 項目。當允許清單不包含 `serverUrl` 項目時，`serverName` 比對才計數 |

401| Stdio | 一個 `serverCommand` 項目。當允許清單不包含 `serverCommand` 項目時，`serverName` 比對才計數 |

402

403<h4 id="servers-that-skip-the-allowlist-check">

404 跳過允許清單檢查的伺服器

405</h4>

406

407除了跳過[全部三項檢查](#how-a-server-is-evaluated)的程序內 `type: "sdk"` 伺服器之外，還有三組伺服器會跳過允許清單檢查：

408

409* 組織自己的伺服器：每個 `managedMcpServers` 項目，以及任何 `managed-mcp.json` 項目，其值不使用 `${VAR}` 展開。

410* 內建伺服器，例如 Chrome 中的 Claude、Claude Code 在執行中的 VS Code 或 JetBrains IDE 中連接的 `ide` 伺服器，以及 CLI 本身設定的伺服器。

411* [Claude Tag](/docs/zh-TW/claude-tag) 工作階段的 Slack 工具：它用來讀取執行緒和發佈回覆的伺服器會在沒有允許清單項目的情況下載入。

412

413在其命令、引數、`env`、URL 或標頭中使用 `${VAR}` 展開的 `managed-mcp.json` 伺服器仍會被檢查。Claude Code 也會檢查使用者、外掛程式或 claude.ai 新增的每個伺服器，以及使用者使用 `--mcp-config` 傳遞的每個伺服器。

382 414

383<h3 id="example-configuration">415<h3 id="example-configuration">

384 範例設定416 範例設定

managed-settings.md +15 −13

Details

216 216

217要讓 Claude Code 應用您的組織提供的每個管理員來源，請在您部署的最高排名來源中將 [`managedSourcesBehavior`](/docs/zh-TW/settings-reference#managedsourcesbehavior) 設定為 `"merge"`。Claude Code 僅從具有金鑰或原則金鑰的最高排名來源讀取該金鑰，因此較低來源無法選擇自己合併到上面的來源，永遠不會接收伺服器管理設定的機器也需要在其 MDM 設定檔中有該金鑰。使用者可寫的 HKCU 登錄永遠不會與另一個來源合併。需要 Claude Code v2.1.242 或更新版本。217要讓 Claude Code 應用您的組織提供的每個管理員來源，請在您部署的最高排名來源中將 [`managedSourcesBehavior`](/docs/zh-TW/settings-reference#managedsourcesbehavior) 設定為 `"merge"`。Claude Code 僅從具有金鑰或原則金鑰的最高排名來源讀取該金鑰，因此較低來源無法選擇自己合併到上面的來源，永遠不會接收伺服器管理設定的機器也需要在其 MDM 設定檔中有該金鑰。使用者可寫的 HKCU 登錄永遠不會與另一個來源合併。需要 Claude Code v2.1.242 或更新版本。

218 218

219在 `"merge"` 下，Claude Code 添加較低來源的列表項目，例如 `permissions.allow` 規則和 hooks，到原則，因此僅在排名低於最高來源的每個來源都在管理員控制下時才開啟它。219在 `"merge"` 下，Claude Code 添加較低來源的列表項目，例如 `permissions.allow` 規則和 hook，到原則，因此僅在排名低於最高來源的每個來源都在管理員控制下時才開啟它。

220 220

221此表格顯示 Claude Code 在 `"merge"` 下如何結合每種金鑰。[`managedSourcesBehavior` 項目](/docs/zh-TW/settings-reference#managedsourcesbehavior) 命名三行中的每個金鑰：限制允許清單、整體採用的值和僅從最高排名來源讀取的金鑰。221此表格顯示 Claude Code 在 `"merge"` 下如何結合每種金鑰。[`managedSourcesBehavior` 項目](/docs/zh-TW/settings-reference#managedsourcesbehavior) 命名三行中的每個金鑰：限制允許清單、整體採用的值和僅從最高排名來源讀取的金鑰。

222 222

231| `env` | 在任一設定下跨管理員來源按變數合併，如 [從每個管理員來源讀取的金鑰](#keys-read-from-every-admin-source) 所述 | |231| `env` | 在任一設定下跨管理員來源按變數合併，如 [從每個管理員來源讀取的金鑰](#keys-read-from-every-admin-source) 所述 | |

233 233

271 在 Claude Code v2.1.273 或更新版本上，當 `allowManagedMcpServersOnly` 開啟時，來自設定列表的最高排名管理員來源的 `allowedMcpServers` 列表適用並阻止父的，作為 [跨來源金鑰](#keys-read-from-every-admin-source)。父的列表僅在沒有管理員來源設定列表時適用。[`managedSourcesBehavior`](/docs/zh-TW/settings-reference#managedsourcesbehavior) 項目說明在 `"merge"` 下哪個來源提供每個金鑰。在 v2.1.223 之前，任何管理員來源中的值阻止父的271 在 Claude Code v2.1.273 或更新版本上，當 `allowManagedMcpServersOnly` 開啟時，來自設定列表的最高排名管理員來源的 `allowedMcpServers` 列表適用並阻止父的，作為 [跨來源金鑰](#keys-read-from-every-admin-source)。父的列表僅在沒有管理員來源設定列表時適用。[`managedSourcesBehavior`](/docs/zh-TW/settings-reference#managedsourcesbehavior) 項目說明在 `"merge"` 下哪個來源提供每個金鑰。在 v2.1.223 之前，任何管理員來源中的值阻止父的

272* 對於 `availableModels`，Claude Code 強制執行它應用的受管設定中的值，並阻止父提供的列表272* 對於 `availableModels`，Claude Code 強制執行它應用的受管設定中的值，並阻止父提供的列表

273* 對於 `strictKnownMarketplaces`，Claude Code 同樣強制執行它應用的受管設定中的列表，並阻止父提供的列表。父的列表僅在沒有應用的受管來源設定列表時適用。需要 Claude Code v2.1.282 或更新版本273* 對於 `strictKnownMarketplaces`，Claude Code 同樣強制執行它應用的受管設定中的列表，並阻止父提供的列表。父的列表僅在沒有應用的受管來源設定列表時適用。需要 Claude Code v2.1.282 或更新版本

274* 對於 `allowedProviders`，[選定的受管來源](#which-managed-source-claude-code-uses) 中的列表會阻止父提供的列表，而在 [`managedSourcesBehavior`](/docs/zh-TW/settings-reference#managedsourcesbehavior) `"merge"` 選擇加入下，任何管理員來源中的列表都會阻止父提供的列表。需要 Claude Code v2.1.285 或更新版本

274* 父提供的 `blockedMarketplaces` 除了受管來源設定的任何拒絕清單外還適用。需要 Claude Code v2.1.282 或更新版本275* 父提供的 `blockedMarketplaces` 除了受管來源設定的任何拒絕清單外還適用。需要 Claude Code v2.1.282 或更新版本

275 276

276<h4 id="keep-cowork-folder-access-when-only-managed-rules-apply">277<h4 id="keep-cowork-folder-access-when-only-managed-rules-apply">

277 當僅應用受管規則時保持 Cowork 資料夾存取278 當僅應用受管規則時保持 Cowork 資料夾存取

278</h4>279</h4>

279 280

280[Cowork](https://claude.com/docs/cowork/overview) 在 Claude Desktop 應用程式中在 Claude Code 上運行其工作階段，並通過它在啟動工作階段時提供的允許規則授予每個工作階段對其工作資料夾（例如使用者連接的資料夾）的存取權限。當您的受管原則設定 [`allowManagedPermissionRulesOnly`](/docs/zh-TW/settings-reference#allowmanagedpermissionrulesonly) 時，Claude Code 僅保留受管原則中的允許規則：它刪除主機作為父設定、`--allowedTools` 或設定檔提供的允許規則，因此對這些資料夾的寫入失去預先批准。在要求編輯前的 Cowork 工作階段中，Cowork 無法顯示提示，Claude 將每次寫入報告為被阻止，因為路徑解析為受保護的位置或連接資料夾外的路徑。281[Cowork](https://claude.com/docs/cowork/overview) 在 Claude Desktop 應用程式中在 Claude Code 上運行其工作階段，並通過它在啟動工作階段時提供的允許規則授予每個工作階段對其工作資料夾（例如使用者連接的資料夾）的存取權限。當您的受管原則設定 [`allowManagedPermissionRulesOnly`](/docs/zh-TW/settings-reference#allowmanagedpermissionrulesonly) 時，Claude Code 僅保留受管原則中的允許規則：它刪除主機作為父設定、`--allowedTools` 或設定檔提供的允許規則，因此對這些資料夾的寫入失去預先批准。在要求編輯前的 Cowork 工作階段中，Cowork 無法顯示權限提示，Claude 將每次寫入報告為被阻止，因為路徑解析為受保護的位置或連接資料夾外的路徑。

281 282

282要恢復寫入，請為這些資料夾添加允許規則到 Claude Code [選擇](#precedence-within-the-managed-tier) 的受管來源在這些機器上：在 MDM 管理的車隊上，那是 MDM 原則而不是單獨的受管設定檔。此示例使用檔案形式，MDM 原則採用相同的金鑰。它保持 `allowManagedPermissionRulesOnly` 設定並允許在每個使用者主目錄中的 `CoworkProjects` 資料夾下編輯；將路徑替換為您的使用者連接的資料夾：283要恢復寫入，請為這些資料夾添加允許規則到 Claude Code [選擇](#precedence-within-the-managed-tier) 的受管來源在這些機器上：在 MDM 管理的車隊上，那是 MDM 原則而不是單獨的受管設定檔。此示例使用檔案形式，MDM 原則採用相同的金鑰。它保持 `allowManagedPermissionRulesOnly` 設定並允許在每個使用者家目錄中的 `CoworkProjects` 資料夾下編輯；將路徑替換為您的使用者連接的資料夾：

283 284

284```json managed-settings.json theme={null}285```json managed-settings.json theme={null}

285{286{

292}293}

293```294```

294 295

295部署原則後，Claude 可以在新 Cowork 工作階段中的該資料夾下保存檔案。[讀取和編輯規則](/docs/zh-TW/permissions#read-and-edit) 涵蓋路徑語法，包括絕對路徑的 `//` 形式。296部署原則後，Claude 可以在新 Cowork 工作階段中的該資料夾下保存檔案。[Read 和 Edit 規則](/docs/zh-TW/permissions#read-and-edit) 涵蓋路徑語法，包括絕對路徑的 `//` 形式。

296 297

297<h3 id="what-a-developer-can-change">298<h3 id="what-a-developer-can-change">

298 開發人員可以更改的內容299 開發人員可以更改的內容

299</h3>300</h3>

300 301

301開發人員自己的設定檔、`--settings` 值和專案檔案永遠不會覆蓋受管值；[例外](/docs/zh-TW/settings#exceptions-to-managed-settings-precedence) 僅允許較嚴格的較低層級值計算。這些情況位於該規則之外：302開發人員自己的設定檔、`--settings` 值和專案檔案永遠不會覆寫受管值；[例外](/docs/zh-TW/settings#exceptions-to-managed-settings-precedence) 僅允許較嚴格的較低層級值計算。這些情況位於該規則之外：

302 303

303* **工作階段的模型**：受管 `model` 是預設值，不是鎖定。`--model` 和 `ANTHROPIC_MODEL` 仍然為該工作階段選擇模型，因此部署 [`availableModels`](/docs/zh-TW/settings-reference#availablemodels) 以限制選擇。304* **工作階段的模型**：受管 `model` 是預設值，不是鎖定。`--model` 和 `ANTHROPIC_MODEL` 仍然為該工作階段選擇模型，因此部署 [`availableModels`](/docs/zh-TW/settings-reference#availablemodels) 以限制選擇。

305* **工作階段的自動壓縮視窗**：受管 [`autoCompactWindow`](/docs/zh-TW/settings-reference#autocompactwindow) 同樣是預設值。`--autocompact` 旗標和 `CLAUDE_CODE_AUTO_COMPACT_WINDOW` 變數仍然會為該工作階段設定 [自動壓縮視窗](/docs/zh-TW/model-config#set-the-auto-compact-window)。

304* **本機管理員權限**：作為機器上管理員的開發人員可以編輯受管來源本身，這就是為什麼 MDM 工具可以按計劃重新部署設定檔或檔案，以及為什麼 HKLM 登錄和 macOS 受管偏好設定域存在。306* **本機管理員權限**：作為機器上管理員的開發人員可以編輯受管來源本身，這就是為什麼 MDM 工具可以按計劃重新部署設定檔或檔案，以及為什麼 HKLM 登錄和 macOS 受管偏好設定域存在。

305* **伺服器管理的快取**：伺服器管理的設定來自 Anthropic 的伺服器，對本機快取的編輯 [僅持續到下一次成功擷取](/docs/zh-TW/server-managed-settings#security-considerations)。307* **伺服器管理的快取**：伺服器管理的設定來自 Anthropic 的伺服器，對本機快取的編輯 [僅持續到下一次成功擷取](/docs/zh-TW/server-managed-settings#security-considerations)。

306* **其他工具**：受管設定僅綁定 Claude Code。從另一個工具呼叫 API 的開發人員不受它們約束。308* **其他工具**：受管設定僅綁定 Claude Code。從另一個工具呼叫 API 的開發人員不受它們約束。

346 尋找 Claude Code 丟棄的項目348 尋找 Claude Code 丟棄的項目

347</h3>349</h3>

348 350

349如果受管理設定檔案、MDM 設定檔、登錄檔值或伺服器管理承載未通過架構驗證，Claude Code 首先跳過它可以修復的個別項目（例如一個無效的權限規則），並為每個項目發出警告。Claude Code 然後丟棄任何仍然失敗的值，除非該值屬於[失敗關閉](#keys-that-fail-closed)的金鑰之一。351如果受管理設定檔案、MDM 設定檔、登錄檔值或伺服器管理 payload 未通過 schema 驗證，Claude Code 首先跳過它可以修復的個別項目（例如一個無效的權限規則），並為每個項目發出警告。Claude Code 然後丟棄任何仍然失敗的值，除非該值屬於[失敗關閉](#keys-that-fail-closed)的金鑰之一。

350 352

351Claude Code 對 [`policyHelper`](/docs/zh-TW/settings-reference#policyhelper) 發出的 `managedSettings` 更加嚴格：它進行相同的項目修復，但任何倖存的架構違規都會導致整個 helper 執行失敗，在啟動時 Claude Code 拒絕啟動，與 helper 以非零狀態退出的情況相同。353Claude Code 對 [`policyHelper`](/docs/zh-TW/settings-reference#policyhelper) 發出的 `managedSettings` 更加嚴格：它進行相同的項目修復，但任何倖存的 schema 違規都會導致整個 helper 執行失敗，在啟動時 Claude Code 拒絕啟動，與 helper 以非零狀態退出的情況相同。

352 354

353當受管理設定檔案、drop-in 檔案、MDM plist 或 HKLM 登錄檔值存在但無法解析為 JSON 物件時，Claude Code 拒絕啟動並列印[命名來源的錯誤](/docs/zh-TW/errors#managed-settings-document-could-not-be-parsed)，即使另一個管理員來源提供有效政策也是如此。每個來源在以下情況下以這種方式失敗：355當受管理設定檔案、drop-in 檔案、MDM plist 或 HKLM 登錄檔值存在但無法解析為 JSON 物件時，Claude Code 拒絕啟動並列印[命名來源的錯誤](/docs/zh-TW/errors#managed-settings-document-could-not-be-parsed)，即使另一個管理員來源提供有效政策也是如此。每個來源在以下情況下以這種方式失敗：

354 356

398 400

399| 欄位 | 存在但無效時的行為 |401| 欄位 | 存在但無效時的行為 |

400| :- | :- |402| :- | :- |

401| `allowedMcpServers` | 強制執行為空的允許清單，直到修復該值，因此使用者添加的任何 MCP 伺服器都不被允許。您的組織通過 [`managedMcpServers`](/docs/zh-TW/settings-reference#managedmcpservers) 提供的伺服器仍然會載入，`managed-mcp.json` 伺服器根據[伺服器如何被評估](/docs/zh-TW/managed-mcp#how-a-server-is-evaluated)載入。個別無效項目被剝離，有效子集被強制執行。 |403| `allowedMcpServers` | 強制執行為空的允許清單，直到修復該值，因此使用者添加的任何 MCP 伺服器都不被允許。您的組織通過 [`managedMcpServers`](/docs/zh-TW/settings-reference#managedmcpservers) 提供的伺服器仍然會載入，`managed-mcp.json` 伺服器根據[跳過允許清單檢查的伺服器](/docs/zh-TW/managed-mcp#servers-that-skip-the-allowlist-check)載入。個別無效項目被剝離，有效子集被強制執行。 |

402| [`allowedProviders`](/docs/zh-TW/settings-reference#allowedproviders) | 強制執行為空的允許清單，直到修復該值，因此每個 API 提供者都被拒絕，Claude Code 不會在機器上啟動。如果只有個別項目不是已知的提供者名稱，Claude Code 會丟棄並報告該項目，並強制執行其餘項目。 |404| [`allowedProviders`](/docs/zh-TW/settings-reference#allowedproviders) | 強制執行為空的允許清單，直到修復該值，因此每個 API 提供者都被拒絕，Claude Code 不會在機器上啟動。如果只有個別項目不是已知的提供者名稱，Claude Code 會丟棄並報告該項目，並強制執行其餘項目。 |

403| `allowedHttpHookUrls` | Claude Code 強制執行空的受管理[允許清單](/docs/zh-TW/settings-reference#allowedhttphookurls)，直到您修復該值，因此 HTTP hook 只有在另一個設定檔案列出其 URL 時才會執行。如果只有個別項目無效，Claude Code 會剝離該項目並強制執行其餘項目。 |405| `allowedHttpHookUrls` | Claude Code 強制執行空的受管理[允許清單](/docs/zh-TW/settings-reference#allowedhttphookurls)，直到您修復該值，因此 HTTP hook 只有在另一個設定檔案列出其 URL 時才會執行。如果只有個別項目無效，Claude Code 會剝離該項目並強制執行其餘項目。 |

404| `httpHookAllowedEnvVars` | Claude Code 強制執行空的受管理[允許清單](/docs/zh-TW/settings-reference#httphookallowedenvvars)，直到您修復該值，因此標頭變數只有在另一個設定檔案命名它時才會被插值。如果只有個別項目無效，Claude Code 會剝離該項目並強制執行其餘項目。 |406| `httpHookAllowedEnvVars` | Claude Code 強制執行空的受管理[允許清單](/docs/zh-TW/settings-reference#httphookallowedenvvars)，直到您修復該值，因此標頭變數只有在另一個設定檔案命名它時才會被插值。如果只有個別項目無效，Claude Code 會剝離該項目並強制執行其餘項目。 |

406| `strictKnownMarketplaces` | 強制執行為空的允許清單，直到修復該值，因此沒有[市場來源](/docs/zh-TW/plugins/org#restrict-what-users-can-install)被允許。無效或無法強制執行的個別項目（例如無法編譯的 `hostPattern` 正規表達式）被剝離，有效子集被強制執行。 |408| `strictKnownMarketplaces` | 強制執行為空的允許清單，直到修復該值，因此沒有[市集來源](/docs/zh-TW/plugins/org#restrict-what-users-can-install)被允許。無效或無法強制執行的個別項目（例如無法編譯的 `hostPattern` 正規表達式）被剝離，有效子集被強制執行。 |

411| `crossSessionInbound` | 視為 `refuse`（最限制性的值），因此入站[跨工作階段訊息](/docs/zh-TW/cross-session-messaging#control-inbound-messages)被拒絕，直到修復該值。開發人員看到[警告](/docs/zh-TW/errors#crosssessioninbound-must-be-one-of-accept-hold-refuse)。 |413| `crossSessionInbound` | 視為 `refuse`（最限制性的值），因此入站[跨工作階段訊息](/docs/zh-TW/cross-session-messaging#control-inbound-messages)被拒絕，直到修復該值。開發人員看到[警告](/docs/zh-TW/errors#crosssessioninbound-must-be-one-of-accept-hold-refuse)。 |

414| `blockedMarketplaces` | 個別無效項目被剝離，有效子集被強制執行。解析但永遠無法匹配的項目（例如無法編譯的 `hostPattern` 正規表達式）被保留並發出警告。它在修復前不會阻止任何內容，但[市場限制](/docs/zh-TW/plugins/org#restrict-what-users-can-install)保持活躍。完全無效的值被丟棄並發出警告，因為阻止每個市場會阻止政策從未命名的來源。 |416| `blockedMarketplaces` | 個別無效項目被剝離，有效子集被強制執行。解析但永遠無法匹配的項目（例如無法編譯的 `hostPattern` 正規表達式）被保留並發出警告。它在修復前不會阻止任何內容，但[市集限制](/docs/zh-TW/plugins/org#restrict-what-users-can-install)保持活躍。完全無效的值被丟棄並發出警告，因為阻止每個市集會阻止政策從未命名的來源。 |

416| `sandbox.credentials` | 可恢復的無效項目被降級為 `mode: "deny"` 並發出警告；無法恢復的項目被剝離；有效項目保持強制執行。請參閱[受管理設定中的無效認證項目](/docs/zh-TW/settings-reference#invalid-credential-entries-in-managed-settings)。 |418| `sandbox.credentials` | 可恢復的無效項目被降級為 `mode: "deny"` 並發出警告；無法恢復的項目被剝離；有效項目保持強制執行。請參閱[受管理設定中的無效憑證項目](/docs/zh-TW/settings-reference#invalid-credential-entries-in-managed-settings)。 |

417| `strictPluginOnlyCustomization` | 視為 `true`（鎖定所有四個表面），當該值既不是布林值也不是陣列時。此版本不識別為表面的陣列項目不鎖定任何內容；狀態注意計算此類項目，以便您可以檢查它們是否有拼寫錯誤。 |419| `strictPluginOnlyCustomization` | 視為 `true`（鎖定所有四個使用介面），當該值既不是布林值也不是陣列時。此版本不識別為使用介面的陣列項目不鎖定任何內容；狀態注意計算此類項目，以便您可以檢查它們是否有拼寫錯誤。 |

419 421

420`allowedHttpHookUrls` 和 `httpHookAllowedEnvVars` 跨設定檔案合併，因此您的使用者、專案或本機設定中的項目在受管理清單為空時仍然適用。422`allowedHttpHookUrls` 和 `httpHookAllowedEnvVars` 跨設定檔案合併，因此您的使用者、專案或本機設定中的項目在受管理清單為空時仍然適用。

model-config.md +2 −1

Details

285* **[自動模型備援](#automatic-model-fallback)**：目標被排除的備援不會執行，因此被標記的請求會改以拒絕結束285* **[自動模型備援](#automatic-model-fallback)**：目標被排除的備援不會執行，因此被標記的請求會改以拒絕結束

286* **[自動模式分類器](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)**：分類器預設使用的 Claude Sonnet 5 僅在允許清單允許 Sonnet 5 時適用。當其被排除時，分類器會以工作階段的模型（已受允許清單管控）執行，或在工作階段以 [Fable 模型](#work-with-fable)執行時改用 Opus 模型。在 Anthropic API 以外的提供者上，該 Opus 備援會以您在 `ANTHROPIC_DEFAULT_OPUS_MODEL` 中設定的模型執行，否則使用 Opus 5，且不會參照允許清單。需要 Claude Code v2.1.210 或更新版本286* **[自動模式分類器](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)**：分類器預設使用的 Claude Sonnet 5 僅在允許清單允許 Sonnet 5 時適用。當其被排除時，分類器會以工作階段的模型（已受允許清單管控）執行，或在工作階段以 [Fable 模型](#work-with-fable)執行時改用 Opus 模型。在 Anthropic API 以外的提供者上，該 Opus 備援會以您在 `ANTHROPIC_DEFAULT_OPUS_MODEL` 中設定的模型執行，否則使用 Opus 5，且不會參照允許清單。需要 Claude Code v2.1.210 或更新版本

287* **[快速模式](/docs/zh-TW/fast-mode)**：若啟用快速模式後工作階段所使用的模型不在允許清單中，將會拒絕啟用快速模式287* **[快速模式](/docs/zh-TW/fast-mode)**：若啟用快速模式後工作階段所使用的模型不在允許清單中，將會拒絕啟用快速模式

288* **Amazon Bedrock 與 Google Cloud 的 Agent Platform 上的可用性備援**：當您的帳戶在工作階段中途失去某個模型的存取權時，切換至其他模型時會略過被排除的模型。[Amazon Bedrock](/docs/zh-TW/amazon-bedrock#when-your-organization-enforces-a-model-allowlist) 與 [Google Cloud 的 Agent Platform](/docs/zh-TW/google-vertex-ai#when-your-organization-enforces-a-model-allowlist) 上的啟動模型檢查，僅在受管設定也設定了 [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model) 時才會略過被排除的模型

288 289

289```json theme={null}290```json theme={null}

290{291{

766| :- | :- |767| :- | :- |

769| 透過環境變數停用 | 設定 [`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` 參數，自適應推理模型仍可能進行思考。其他值僅在使用[固定思考預算](#adaptive-reasoning-and-fixed-thinking-budgets)時適用 |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` 參數，自適應推理模型仍可能進行思考 |

770 771

771您無法在 Opus 5.5、Sonnet 5.5 或 Fable 模型上關閉思考。對於這些模型，工作階段切換開關和 `/config` 列會顯示 `Thinking can't be turned off`，而不提供切換選項，且已儲存的 `alwaysThinkingEnabled: false` 或 `MAX_THINKING_TOKENS=0` 在這些模型上無效。在這些模型上，模型會根據 effort 等級決定每個步驟的思考量。當您切換至接受該設定的模型時，已儲存的設定會再次適用。772您無法在 Opus 5.5、Sonnet 5.5 或 Fable 模型上關閉思考。對於這些模型，工作階段切換開關和 `/config` 列會顯示 `Thinking can't be turned off`，而不提供切換選項，且已儲存的 `alwaysThinkingEnabled: false` 或 `MAX_THINKING_TOKENS=0` 在這些模型上無效。在這些模型上，模型會根據 effort 等級決定每個步驟的思考量。當您切換至接受該設定的模型時，已儲存的設定會再次適用。

772 773

monitoring-usage.md +42 −11

Details

358 358

359<span id="new-context-gates" />359<span id="new-context-gates" />

360 360

361**詳細測試版追蹤下的內容屬性**

362

361<Note>363<Note>

362 其他內容承載屬性，例如 `new_context`、`system_prompt_preview`、`user_system_prompt`、`tool_input` 和 `response.model_output`，僅在詳細測試版追蹤作用中時發出。它們不是穩定跨度架構的一部分。364 其他內容承載屬性，例如 `new_context`、`system_reminders`、`system_prompt_preview`、`user_system_prompt`、`tool_input` 和 `response.model_output`，僅在詳細測試版追蹤作用中時發出。它們不是穩定跨度 schema 的一部分。

365</Note>

363 366

364 `new_context` 上的閘門取決於哪個跨度攜帶它，每個副本都在內容限制處截斷（預設值 60 KB）。在 `claude_code.tool` 跨度上，它攜帶該工具呼叫的結果，無論工具如何，並需要 `OTEL_LOG_TOOL_CONTENT=1`。在 `claude_code.interaction` 跨度上，它攜帶使用者提示，在 `claude_code.llm_request` 跨度上，它攜帶該請求的新使用者訊息和工具結果。這兩者都需要 `OTEL_LOG_USER_PROMPTS=1`。367這些屬性出現在以下跨度上，`由以下閘門控制` 命名屬性在詳細測試版追蹤之上需要的變數。長於內容限制（預設值 60 KB）的值會被截斷。

365 368

366 `user_system_prompt` 另外需要 `OTEL_LOG_USER_PROMPTS=1`。它僅攜帶您透過 `systemPrompt` SDK 選項或 `--system-prompt` 和 `--append-system-prompt` 旗標提供的系統提示文字，在內容限制處截斷（預設值 60 KB），並且每個工作階段發出一次而不是每個請求。369| 屬性 | 跨度 | 說明 | 由以下閘門控制 |

367</Note>370| - | - | - | - |

379

380在詳細測試版追蹤下且設定 `OTEL_LOG_USER_PROMPTS=1` 時，Claude Code 也會發出 `claude_code.system_prompt` 事件，攜帶完整的系統提示詞，並在內容限制處截斷。它會在工作階段首次傳送每個不同的系統提示詞時到達，並在壓縮後再次到達。

368 381

369<h3 id="dynamic-headers">382<h3 id="dynamic-headers">

370 動態標頭383 動態標頭

797* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述810* `event.sequence`：用於排序事件的每個程序計數器，在[事件相關屬性](#event-correlation-attributes)下描述

798* `prompt_length`：提示的長度811* `prompt_length`：提示的長度

799* `prompt`：提示內容。預設情況下編輯。設定 `OTEL_LOG_USER_PROMPTS=1` 以包含它812* `prompt`：提示內容。預設情況下編輯。設定 `OTEL_LOG_USER_PROMPTS=1` 以包含它

813* `prompt_text`：與 `prompt` 相同的值，在相同條件下遮蔽。將帶點屬性名稱儲存為巢狀物件的後端，會將 `prompt.id` 讀取為名為 `prompt` 之物件內的 `id`，因而可能遺失提示詞字串。在這類後端上請改讀取 `prompt_text`。需要 Claude Code v2.1.287 或更新版本

800* `message.uuid`：結果使用者消息的 UUID，與保存的文字記錄項目相符。在命令分派上不存在，它可以產生零個或多個消息。需要 Claude Code v2.1.214 或更新版本814* `message.uuid`：結果使用者消息的 UUID，與保存的文字記錄項目相符。在命令分派上不存在，它可以產生零個或多個消息。需要 Claude Code v2.1.214 或更新版本

801* `command_name`：當提示呼叫命令時的命令名稱。內建和捆綁命令名稱（例如 `compact` 或 `debug`）按原樣發出；別名（例如 `reset`）按輸入方式發出而不是規範名稱。自訂、外掛程式和 MCP 命令名稱會摺疊為 `custom` 或 `mcp`，除非設定了 `OTEL_LOG_TOOL_DETAILS=1`815* `command_name`：當提示呼叫命令時的命令名稱。內建和捆綁命令名稱（例如 `compact` 或 `debug`）按原樣發出；別名（例如 `reset`）按輸入方式發出而不是規範名稱。自訂、外掛程式和 MCP 命令名稱會摺疊為 `custom` 或 `mcp`，除非設定了 `OTEL_LOG_TOOL_DETAILS=1`

802* `command_source`：命令存在時的來源：`builtin`、`custom` 或 `mcp`。外掛程式提供的命令報告為 `custom`816* `command_source`：命令存在時的來源：`builtin`、`custom` 或 `mcp`。外掛程式提供的命令報告為 `custom`

1694* OpenTelemetry 匯出到您的後端是選擇加入的，需要明確配置。如需了解 Anthropic 的獨立營運遙測以及如何停用它，請參閱[資料使用](/docs/zh-TW/data-usage#telemetry-services)1708* OpenTelemetry 匯出到您的後端是選擇加入的，需要明確配置。如需了解 Anthropic 的獨立營運遙測以及如何停用它，請參閱[資料使用](/docs/zh-TW/data-usage#telemetry-services)

1695* 原始檔案內容和程式碼片段不包含在指標或事件中。追蹤跨度是單獨的資料路徑：請參閱下面的 `OTEL_LOG_TOOL_CONTENT` 項目1709* 原始檔案內容和程式碼片段不包含在指標或事件中。追蹤跨度是單獨的資料路徑：請參閱下面的 `OTEL_LOG_TOOL_CONTENT` 項目

1696* 透過 OAuth 驗證時，`user.email` 包含在遙測屬性中，僅傳送到您配置的 OTel 端點，絕不會傳送到 Anthropic。如果這對您的組織是個問題，請與您的遙測後端合作以篩選或編輯此欄位1710* 透過 OAuth 驗證時，`user.email` 包含在遙測屬性中，僅傳送到您配置的 OTel 端點，絕不會傳送到 Anthropic。如果這對您的組織是個問題，請與您的遙測後端合作以篩選或編輯此欄位

1697* 預設不收集使用者提示內容。僅記錄提示長度。若要包含提示內容，請設定 `OTEL_LOG_USER_PROMPTS=1`。在詳細的測試版追蹤下，此變數的作用範圍更廣：它也控制 [`new_context` 跨度屬性](#new-context-gates)，該屬性在 `claude_code.llm_request` 跨度上帶有工具結果1711* 預設不收集使用者提示詞內容。僅記錄提示詞長度。若要包含提示詞內容，請設定 `OTEL_LOG_USER_PROMPTS=1`。啟用時：

1698* 助理回應文字預設不收集。僅記錄回應長度。若要包含回應文字，請設定 `OTEL_LOG_ASSISTANT_RESPONSES=1`。如同 Claude Code 的所有 OpenTelemetry 資料，回應文字僅傳送到您配置的 OTel 端點，絕不會傳送到 Anthropic。當此變數未設定時，`OTEL_LOG_USER_PROMPTS` 會用作備用方案，因此如果您想要提示內容而不要回應內容，請設定 `OTEL_LOG_ASSISTANT_RESPONSES=0`1712 * `user_prompt` 事件在兩個屬性中帶有提示詞文字：`prompt` 和 [`prompt_text`](#user-prompt-event)。如果您在收集器中依屬性名稱捨棄或遮蔽事件的提示詞文字，請在規則中列出這兩個屬性

1699* 工具輸入引數和參數預設不記錄。若要包含它們，請設定 `OTEL_LOG_TOOL_DETAILS=1`。針對 Claude Desktop 的內建伺服器，在 Claude Desktop 擁有的工作階段中，`tool_decision` 和 `tool_result` 帶有 `mcp_server_name`/`mcp_tool_name` 配對，即主機撰寫的名稱而非引數內容，即使旗標關閉也是如此。此例外需要 Claude Code v2.1.214 或更新版本。此資料僅傳送到您配置的 OTEL 端點，絕不會傳送到 Anthropic。引數仍可能包含敏感值，因此請根據需要配置您的遙測後端以篩選或編輯這些屬性。啟用時：1713

1700 * `tool_result` 和 `tool_decision` 事件包含 `tool_parameters` 屬性，其中包含 Bash 命令、MCP 伺服器和工具名稱以及技能名稱。`full_command` 等欄位未截斷地發出1714 此 OpenTelemetry Collector `attributes` 處理器會在列出它的管線中刪除這兩個屬性：

1715

1716 ```yaml theme={null}

1717 processors:

1718 attributes/drop-prompt-text:

1719 actions:

1720 - key: prompt

1721 action: delete

1722 - key: prompt_text

1723 action: delete

1724 ```

1725

1726 * 開啟[追蹤](#traces-beta)時，`claude_code.interaction` 跨度會在其 `user_prompt` 屬性中帶有提示詞文字

1727

1728 * 在詳細的測試版追蹤下，跨度也會帶有每個請求所傳送的新使用者訊息、工具結果和系統提醒、系統提示詞文字，以及模型輸出。[詳細測試版追蹤下的內容屬性](#new-context-gates)列出了每個屬性。`claude_code.system_prompt` 事件帶有完整的系統提示詞

1729* 助理回應文字預設不收集。僅記錄回應長度。若要包含回應文字，請設定 `OTEL_LOG_ASSISTANT_RESPONSES=1`。如同 Claude Code 的所有 OpenTelemetry 資料，回應文字僅傳送到您設定的 OTel 端點，絕不會傳送到 Anthropic。當此變數未設定時，`OTEL_LOG_USER_PROMPTS` 會用作備援，因此如果您想要事件中有提示詞內容而不要回應內容，請設定 `OTEL_LOG_ASSISTANT_RESPONSES=0`。在詳細的測試版追蹤下，`claude_code.llm_request` 跨度仍會在 [`response.model_output`](#new-context-gates) 中帶有模型輸出，該屬性遵循 `OTEL_LOG_USER_PROMPTS` 而非此變數

1730* 工具輸入引數和參數預設不記錄。若要包含它們，請設定 `OTEL_LOG_TOOL_DETAILS=1`。針對 Claude Desktop 的內建伺服器，在 Claude Desktop 擁有的工作階段中，`tool_decision` 和 `tool_result` 帶有 `mcp_server_name`/`mcp_tool_name` 配對，即主機撰寫的名稱而非引數內容，即使旗標關閉也是如此。此例外需要 Claude Code v2.1.214 或更新版本。此資料僅傳送到您設定的 OTEL 端點，絕不會傳送到 Anthropic。引數仍可能包含敏感值，因此請根據需要設定您的遙測後端以篩選或編輯這些屬性。啟用時：

1731 * `tool_result` 和 `tool_decision` 事件包含 `tool_parameters` 屬性，其中包含 Bash 命令、MCP 伺服器和工具名稱以及 skill 名稱。`full_command` 等欄位未截斷地發出

1701 * `tool_result` 事件另外包含 `tool_input` 屬性，其中包含檔案路徑、URL、搜尋模式和其他引數。超過 512 個字元的個別值會被截斷，總計上限約為 4 K 字元1732 * `tool_result` 事件另外包含 `tool_input` 屬性，其中包含檔案路徑、URL、搜尋模式和其他引數。超過 512 個字元的個別值會被截斷，總計上限約為 4 K 字元

1702 * `user_prompt` 事件包含自訂、plugin 和 MCP 命令的逐字 `command_name`1733 * `user_prompt` 事件包含自訂、外掛和 MCP 命令的逐字 `command_name`

1703 * [成本和權杖計數器](#cost-counter)以及 `api_request`、`api_error` 和 `api_refusal` 事件在其歸因屬性中帶有真實的代理、技能、plugin 和 MCP 伺服器和工具名稱1734 * [成本和 token 計數器](#cost-counter)以及 `api_request`、`api_error` 和 `api_refusal` 事件在其歸因屬性中帶有真實的 agent、skill、外掛和 MCP 伺服器和工具名稱

1704 * 追蹤跨度包含相同的 `tool_input` 屬性和輸入衍生屬性，例如 `file_path`，截斷方式與 `tool_input` 相同1735 * `claude_code.tool` 跨度帶有輸入衍生屬性，例如 `file_path`。在詳細的測試版追蹤下，它還會帶有 [`tool_input`](#new-context-gates) 屬性

1705* 工具內容預設不在追蹤跨度中記錄。若要包含它，請設定 `OTEL_LOG_TOOL_CONTENT=1`。`claude_code.tool` 跨度隨後帶有 [`tool.output` 跨度事件](#tool-output-span-event)，其中包含原始檔案內容、Bash 命令輸出，以及 MCP 工具、WebFetch 和 WebSearch 傳回的內容，在內容限制（預設 60 KB）處按屬性截斷。來自 MCP 工具、WebFetch 和 WebSearch 的結果需要 Claude Code v2.1.283 或更新版本。工具內容也透過 [`new_context` 到達跨度，其控制因跨度而異](#new-context-gates)。根據需要配置您的遙測後端以篩選或編輯這些屬性1736* 工具內容預設不在追蹤跨度中記錄。若要包含它，請設定 `OTEL_LOG_TOOL_CONTENT=1`。`claude_code.tool` 跨度隨後帶有 [`tool.output` 跨度事件](#tool-output-span-event)，其中包含原始檔案內容、Bash 命令輸出，以及 MCP 工具、WebFetch 和 WebSearch 傳回的內容，在內容限制（預設 60 KB）處按屬性截斷。來自 MCP 工具、WebFetch 和 WebSearch 的結果需要 Claude Code v2.1.283 或更新版本。工具內容也透過 [`new_context` 到達跨度，其控制因跨度而異](#new-context-gates)。根據需要配置您的遙測後端以篩選或編輯這些屬性

1706* 原始 Anthropic Messages API 請求和回應主體預設不記錄。若要包含它們，請在您的 shell、使用者設定或受管設定中設定 `OTEL_LOG_RAW_API_BODIES`。在[專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略。主體包含完整的對話歷史記錄，包括系統提示、每個先前的使用者和助手輪次以及工具結果，因此啟用此選項意味著同意其他 `OTEL_LOG_*` 內容旗標會揭露的所有內容。Claude Code 始終從這些主體中編輯 Claude 的擴展思考內容，無論其他設定如何。您設定的值決定了 Claude Code 如何傳遞主體：1737* 原始 Anthropic Messages API 請求和回應主體預設不記錄。若要包含它們，請在您的 shell、使用者設定或受管設定中設定 `OTEL_LOG_RAW_API_BODIES`。在[專案和本機設定](/docs/zh-TW/settings-reference#variables-claude-code-ignores-in-env)中會被忽略。主體包含完整的對話歷史記錄，包括系統提示、每個先前的使用者和助手輪次以及工具結果，因此啟用此選項意味著同意其他 `OTEL_LOG_*` 內容旗標會揭露的所有內容。Claude Code 始終從這些主體中編輯 Claude 的擴展思考內容，無論其他設定如何。您設定的值決定了 Claude Code 如何傳遞主體：

1707 * 使用 `=1` 時，Claude Code 為每個 API 呼叫發出 `api_request_body` 和 `api_response_body` 日誌事件。事件的 `body` 屬性帶有 JSON 序列化的承載，在內容限制（預設 60 KB）處截斷1738 * 使用 `=1` 時，Claude Code 為每個 API 呼叫發出 `api_request_body` 和 `api_response_body` 日誌事件。事件的 `body` 屬性帶有 JSON 序列化的承載，在內容限制（預設 60 KB）處截斷

permission-modes.md +15 −13

Details

67 工作階段在哪個模式中啟動67 工作階段在哪個模式中啟動

68</h2>68</h2>

69 69

~~70當您在終端中啟動新工作階段時，Claude Code 會從適用的第一個中取得權限模式：~~70當您在終端機中啟動新工作階段時，Claude Code 會從適用的第一個中取得權限模式：

71 71

721. `--permission-mode` 旗標或 `--dangerously-skip-permissions`721. `--permission-mode` 旗標或 `--dangerously-skip-permissions`

73 73

81 81

82內建 `auto` 預設在 macOS、Linux 和 WSL 上需要 Claude Code v2.1.228 或更新版本，在原生 Windows 上需要 v2.1.233 或更新版本。在較早的版本上，內建預設是 Manual。82內建 `auto` 預設在 macOS、Linux 和 WSL 上需要 Claude Code v2.1.228 或更新版本，在原生 Windows 上需要 v2.1.233 或更新版本。在較早的版本上，內建預設是 Manual。

83 83

84內建預設取決於您如何執行 Claude Code。符合的第一行適用。該表涵蓋您在終端或透過 VS Code 擴充功能啟動的工作階段；對於桌面應用程式和 claude.ai，請參閱[切換權限模式](#switch-permission-modes)中的 Desktop 和 Web 標籤。84內建預設取決於您如何執行 Claude Code。符合的第一行適用。該表涵蓋您在終端機或透過 VS Code 擴充功能啟動的工作階段；對於桌面應用程式和 claude.ai，請參閱[切換權限模式](#switch-permission-modes)中的 Desktop 和 Web 標籤。

85 85

86| 您如何執行 Claude Code | 內建起始權限模式 |86| 您如何執行 Claude Code | 內建起始權限模式 |

87| :- | :- |87| :- | :- |

88| 任何設定檔將 `disableAutoMode` 設定為 `"disable"` | `default` |88| 任何設定檔將 `disableAutoMode` 設定為 `"disable"` | `default` |

89| `claude -p` 或 [Agent SDK](/docs/zh-TW/agent-sdk/permissions#permission-modes) | 在[擷取功能旗標](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)的工作階段中為 `default`。在不擷取的工作階段中，例如在第三方提供者上或關閉遙測的情況下，Claude Code v2.1.285 或更新版本上為 `auto`，較早版本上為 `default`。組織政策禁止 `auto` 預設的工作階段會改為以 `default` 啟動 |89| `claude -p` 或 [Agent SDK](/docs/zh-TW/agent-sdk/permissions#permission-modes) | 在[擷取功能旗標](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)的工作階段中為 `default`。在不擷取的工作階段中，例如在第三方提供者上或關閉遙測的情況下，Claude Code v2.1.285 或更新版本上為 `auto`，較早版本上為 `default`。組織政策禁止 `auto` 預設的工作階段會改為以 `default` 啟動 |

90| 在終端或透過 [VS Code 擴充功能](/docs/zh-TW/vs-code) | Claude Code v2.1.283 或更新版本上的 `auto`；在較早的版本上，Pro、Max 或 Team 方案上的 `auto`（在[擷取功能旗標](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)的工作階段中），否則為 `default` |90| 在終端機或透過 [VS Code 擴充功能](/docs/zh-TW/vs-code) | Claude Code v2.1.283 或更新版本上的 `auto`；在較早的版本上，Pro、Max 或 Team 方案上的 `auto`（在[擷取功能旗標](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)的工作階段中），否則為 `default` |

91 91

92在您[安裝或升級後的第一個工作階段](/docs/zh-TW/env-vars#first-session-after-an-install-or-upgrade)中，Claude Code 可以在其功能旗標到達之前選擇起始權限模式。該工作階段可能以不同的權限模式啟動，而不是表格給出的模式，您的下一個工作階段符合表格。92在您[安裝或升級後的第一個工作階段](/docs/zh-TW/env-vars#first-session-after-an-install-or-upgrade)中，Claude Code 可以在其功能旗標到達之前選擇起始權限模式。該工作階段可能以與表格所列不同的權限模式啟動。

93 93

94當旗標、設定檔或內建預設選擇 `auto` 但自動模式對工作階段不可用時，Claude Code 會改為以 Manual 啟動工作階段。當工作階段不符合[可用性要求](#eliminate-prompts-with-auto-mode)時，自動模式不可用，例如設定檔關閉它或不支援它的模型，或當 Anthropic 已在伺服器端暫時關閉它時。94當旗標、設定檔或內建預設選擇 `auto` 但自動模式對工作階段不可用時，Claude Code 會改為以 Manual 啟動工作階段。當工作階段不符合[可用性要求](#eliminate-prompts-with-auto-mode)時，自動模式不可用，例如設定檔關閉它或不支援它的模型，或當 Anthropic 已在伺服器端暫時關閉它時。

95 95

96內建預設第一次在自動模式中啟動您的工作階段時，Claude Code 會顯示連結到此頁面的通知：96內建預設第一次在自動模式中啟動您的工作階段時，Claude Code 會顯示連結到此頁面的通知：

97 97

~~98* 在終端中，一次，在工作階段頂部~~98* 在終端機中，一次，在工作階段頂部

99* 在 VS Code 擴充功能中，作為新對話螢幕上的卡片，直到您關閉它99* 在 VS Code 擴充功能中，作為新對話螢幕上的卡片，直到您關閉它

100 100

101如果您的 `~/.claude/settings.json` 將 `defaultMode` 設定為 `auto` 以外的值，且沒有其他設定檔設定它，您的工作階段會繼續以該模式啟動。在 Pro、Max 和 Team 方案上，以及在[不擷取功能旗標](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)的工作階段中，Claude Code 會在終端或 VS Code 擴充功能中詢問一次，是否將設定變更為自動模式。如果您拒絕，您的設定會保持原樣。101如果您的 `~/.claude/settings.json` 將 `defaultMode` 設定為 `auto` 以外的值，且沒有其他設定檔設定它，您的工作階段會繼續以該模式啟動。在 Pro、Max 和 Team 方案上，以及在[不擷取功能旗標](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)的工作階段中，Claude Code 會在終端機或 VS Code 擴充功能中詢問一次，是否將設定變更為自動模式。如果您拒絕，您的設定會保持原樣。

102 102

103<h3 id="start-in-a-different-mode">103<h3 id="start-in-a-different-mode">

104 以不同的權限模式啟動104 以不同的權限模式啟動

109| 若要為以下設定起始權限模式 | 執行此操作 |109| 若要為以下設定起始權限模式 | 執行此操作 |

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

112| 您在此機器上啟動的每個終端工作階段 | 在 `~/.claude/settings.json` 中設定 `permissions.defaultMode`。如需 VS Code 擴充功能讀取的內容，請參閱[切換權限模式](#switch-permission-modes) |112| 您在此機器上啟動的每個終端機工作階段 | 在 `~/.claude/settings.json` 中設定 `permissions.defaultMode`。如需 VS Code 擴充功能讀取的內容，請參閱[切換權限模式](#switch-permission-modes) |

113| 您在一個專案中啟動的每個終端工作階段 | 在專案的 `.claude/settings.json` 中設定 `permissions.defaultMode`。您在終端中啟動的工作階段遵守除 `auto` 和 `bypassPermissions` 外的每個值；VS Code 擴充功能啟動的工作階段不讀取專案設定以取得起始權限模式 |113| 您在一個專案中啟動的每個終端機工作階段 | 在專案的 `.claude/settings.json` 中設定 `permissions.defaultMode`。您在終端機中啟動的工作階段遵守除 `auto` 和 `bypassPermissions` 外的每個值；VS Code 擴充功能啟動的工作階段不讀取專案設定以取得起始權限模式 |

114| 您組織中的每個終端工作階段 | 在[受管設定](/docs/zh-TW/managed-settings)中設定 `permissions.defaultMode`。終端工作階段以該模式啟動，人們仍然可以切換到自動模式；如需 VS Code 擴充功能讀取的內容，請參閱[切換權限模式](#switch-permission-modes)。若要移除自動模式以便沒有人可以選擇它，請改為將 `permissions.disableAutoMode` 設定為 `"disable"` |114| 您組織中的每個終端機工作階段 | 在[受管設定](/docs/zh-TW/managed-settings)中設定 `permissions.defaultMode`。終端機工作階段以該模式啟動，人們仍然可以切換到自動模式；如需 VS Code 擴充功能讀取的內容，請參閱[切換權限模式](#switch-permission-modes)。若要移除自動模式以便沒有人可以選擇它，請改為將 `permissions.disableAutoMode` 設定為 `"disable"` |

115 115

116此範例使您機器上的每個終端工作階段以 Manual 模式啟動，其設定值為 `default`。將其儲存在 `~/.claude/settings.json` 中：116此範例使您機器上的每個終端機工作階段以 Manual 模式啟動，其設定值為 `default`。將其儲存在 `~/.claude/settings.json` 中：

117 117

118```json theme={null}118```json theme={null}

119{119{

676* `.devcontainer`676* `.devcontainer`

677* `.yarn`677* `.yarn`

678* `.mvn`678* `.mvn`

679* `.claude`，除了 `.claude/worktrees` 其中 Claude 儲存其自身的 git worktrees679* `.claude`，除了 `.claude/worktrees`（Claude 在其中儲存其自身的 git worktrees），以及在未使用 `--restricted` 啟動的工作階段中，Claude 自身[自動記憶](/docs/zh-TW/memory#storage-location)目錄中的 markdown 檔案

680* 您使用 [`--plugin-dir`](/docs/zh-TW/plugins/mods/create#change-a-mod-with-claude) 載入的目錄，因為當檔案變更時 Claude Code 會從中重新載入並執行 mod 的程式碼680* 您使用 [`--plugin-dir`](/docs/zh-TW/plugins/mods/create#change-a-mod-with-claude) 載入的目錄，因為當檔案變更時 Claude Code 會從中重新載入並執行 mod 的程式碼

681 681

682受保護的檔案：682受保護的檔案：

739Claude Code 也會查看這些構造：739Claude Code 也會查看這些構造：

740 740

741* **巢狀命令**：帶有 `(...)` 的子殼層、帶有 `{ ...; }` 的大括號群組、帶有 `$(...)` 或反引號的命令替換，或帶有 `<(...)` 的程序替換。Claude Code 會找到關鍵路徑移除，無論它位於巢狀形式內（如 `(rm -rf ~)` 或 `echo "$(rm -rf ~)"`），還是位於同一命令中的其他位置。741* **巢狀命令**：帶有 `(...)` 的子殼層、帶有 `{ ...; }` 的大括號群組、帶有 `$(...)` 或反引號的命令替換，或帶有 `<(...)` 的程序替換。Claude Code 會找到關鍵路徑移除，無論它位於巢狀形式內（如 `(rm -rf ~)` 或 `echo "$(rm -rf ~)"`），還是位於同一命令中的其他位置。

742* **內聯指令碼**：Claude Code 檢查傳遞給殼層（例如 `sh -c` 或 `bash -c`）的指令碼，以查找 shell 變數和位置參數[目標](#other-targets-that-count-as-critical-paths)。742* **內聯指令碼**：以 `-c` 傳遞給 `sh`、`bash`、`zsh` 或類似 POSIX shell 的指令碼，如 `bash -c 'rm -rf ~'`。

743 * 當指令碼是雙引號時，呼叫殼層會在內部殼層接收指令碼之前展開其變數。在 `find . -name '*.tmp' -exec sh -c "rm -rf \"$1\"/*" _ {} \;` 中，命令會針對每個匹配項展開為從檔案系統根目錄的移除，Claude Code 將其視為關鍵路徑移除。743 * 當指令碼是雙引號時，呼叫端 shell 會在內部 shell 接收指令碼之前展開其變數。在 `find . -name '*.tmp' -exec sh -c "rm -rf \"$1\"/*" _ {} \;` 中，命令會針對每個匹配項展開為從檔案系統根目錄的移除，Claude Code 將其視為關鍵路徑移除。

744 * 將 `$1` 綁定到實際值的單引號指令碼（如 `sh -c 'rm -rf "$1"/*' _ {}` 所做的）不會被標記。744 * 將 `$1` 綁定到實際值的單引號指令碼（如 `sh -c 'rm -rf "$1"/*' _ {}` 所做的）不會被標記。

745 745

746要關閉對直接輸入在 `-c` 指令碼中的關鍵路徑（例如 `~`）的檢查，請在啟動 Claude Code 的環境中設定 [`CLAUDE_CODE_DISABLE_INLINE_SHELL_RM_PROMPT=1`](/docs/zh-TW/env-vars#variables)。

747

746<h3 id="rewrite-a-flagged-command">748<h3 id="rewrite-a-flagged-command">

747 重寫被標記的命令749 重寫被標記的命令

748</h3>750</h3>

plugins/cli-reference.md +6 −2

Details

336| `version` | string | 對於市集安裝，[Claude Code 在安裝時計算的](/docs/zh-TW/plugins/loading#versions-and-updates) 版本。對於工作階段專用、skills-directory 或同步 plugin，manifest 的 `version`，或未宣告時為 `unknown` |336| `version` | string | 對於市集安裝，[Claude Code 在安裝時計算的](/docs/zh-TW/plugins/loading#versions-and-updates) 版本。對於工作階段專用、skills-directory 或同步 plugin，manifest 的 `version`，或未宣告時為 `unknown` |

337| `scope` | string | 安裝為 `user`、`project`、`local` 或 `managed`；skills-directory plugins 為 `user` 或 `project`；工作階段專用 plugins 為 `session`；從 claude.ai 同步的 plugins 為 `synced` |337| `scope` | string | 安裝為 `user`、`project`、`local` 或 `managed`；skills-directory plugins 為 `user` 或 `project`；工作階段專用 plugins 為 `session`；從 claude.ai 同步的 plugins 為 `synced` |

340| `readFromFolder` | string | 對於工作階段從其市集資料夾 [就地載入](/docs/zh-TW/plugins/loading#in-place-and-copied-plugins) 的 plugin，該資料夾內 plugin 的來源目錄。需要 Claude Code v2.1.289 或更新版本 |

341| `folderVersion` | string | 搭配 `readFromFolder`，Claude Code 從該資料夾載入時 plugin 的 `version`，可能與上方的 `version` 欄位不同。當 plugin 未載入或未宣告版本時不存在。需要 Claude Code v2.1.289 或更新版本 |

637 * 名為 `.claude` 的目錄：其中的 `skills`、`agents` 和 `commands` 目錄639 * 名為 `.claude` 的目錄：其中的 `skills`、`agents` 和 `commands` 目錄

638 * 任何其他目錄：其 `.claude` 下的這三個目錄640 * 任何其他目錄：其 `.claude` 下的這三個目錄

639 641

642當目錄同時包含 `.claude-plugin/marketplace.json` 和 `.claude-plugin/plugin.json` 時，Claude Code 會驗證市集，也會驗證 plugin 的 manifest 和元件檔案。這需要 Claude Code v2.1.289 或更新版本。

643

640Claude Code 不遵循您命名的目錄內的符號連結。它的作用取決於連結的位置：644Claude Code 不遵循您命名的目錄內的符號連結。它的作用取決於連結的位置：

641 645

642* **plugin 或 `.claude` 根下的連結 `skills`、`agents` 或 `commands` 目錄**：Claude Code 警告其中的任何內容都未被讀取。646* **plugin 或 `.claude` 根下的連結 `skills`、`agents` 或 `commands` 目錄**：Claude Code 警告其中的任何內容都未被讀取。

647 651

648* **plugin 根處的 `SKILL.md`**：當您針對 plugin 目錄執行 `claude plugin validate` 時，Claude Code 不檢查 plugin 根處的 `SKILL.md`652* **plugin 根處的 `SKILL.md`**：當您針對 plugin 目錄執行 `claude plugin validate` 時，Claude Code 不檢查 plugin 根處的 `SKILL.md`

649* **plugin 根處的 `CLAUDE.md`**：在 plugin 執行中，Claude Code 也警告 plugin 根處的 `CLAUDE.md`653* **plugin 根處的 `CLAUDE.md`**：在 plugin 執行中，Claude Code 也警告 plugin 根處的 `CLAUDE.md`

650* **市集執行中的 Plugin 檔案**：從市集目錄，Claude Code 不開啟 plugins 的 skill、agent、command 或 hook 檔案，或它們捆綁的 MCP 伺服器檔案。若要在這些檔案中找到錯誤，驗證每個 plugin 目錄654* **市集執行中的 Plugin 檔案**：從市集目錄，Claude Code 不開啟市集列於其他目錄中之 plugins 的 skill、agent、command 或 hook 檔案，或它們捆綁的 MCP 伺服器檔案。若要在這些檔案中找到錯誤，驗證每個 plugin 目錄

651 655

652<h4 id="output-and-exit-codes">656<h4 id="output-and-exit-codes">

653 輸出和結束代碼657 輸出和結束代碼

plugins/create.md +2 −2

Details

100 Greet the user warmly and ask how you can help them today.100 Greet the user warmly and ask how you can help them today.

101 ```101 ```

102 102

103 `disable-model-invocation: true` 行表示 Claude 不會自行執行技能，因此只有您觸發它。從您希望 Claude 自行執行的技能中移除該行。技能的命令結合外掛程式名稱和技能的名稱，因此您將此技能執行為 `/my-first-plugin:hello`。對於其他 frontmatter 欄位，請參閱[技能 frontmatter 參考](/docs/zh-TW/skills#frontmatter-reference)。103 `disable-model-invocation: true` 行表示 Claude 不會自行執行該 skill。從您希望 Claude 自行執行的 skill 中移除該行。skill 的命令結合外掛程式名稱和 skill 的名稱，因此您將此 skill 執行為 `/my-first-plugin:hello`。對於其他 frontmatter 欄位，請參閱[skill frontmatter 參考](/docs/zh-TW/skills#frontmatter-reference)。

104 </Step>104 </Step>

105 105

106 <Step title="驗證外掛程式">106 <Step title="驗證外掛程式">

107 在執行任何操作之前檢查清單和技能的 frontmatter：107 在執行任何操作之前檢查清單和 skill 的 frontmatter：

108 108

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

110 claude plugin validate ./my-first-plugin110 claude plugin validate ./my-first-plugin

plugins/host-marketplace.md +1 −1

Details

215 215

216若要向使用者發佈新版本，變更 plugin 的 `version`。使用者只有在 plugin 的計算版本與他們擁有的版本不同時才獲得新副本。該版本首先來自 `plugin.json`，然後來自 marketplace 項目，根據 [Versions and updates](/docs/zh-TW/plugins/loading#versions-and-updates)。216若要向使用者發佈新版本，變更 plugin 的 `version`。使用者只有在 plugin 的計算版本與他們擁有的版本不同時才獲得新副本。該版本首先來自 `plugin.json`，然後來自 marketplace 項目，根據 [Versions and updates](/docs/zh-TW/plugins/loading#versions-and-updates)。

217 217

218使用者從 marketplace 新增為本地目錄的 [load in place](/docs/zh-TW/plugins/loading#find-plugins-on-disk) 的 plugin 不受 `version` 控制。它在每個工作階段啟動時載入您的目前檔案，無論其版本字串說什麼。218使用者從透過本機路徑新增的市集[就地載入](/docs/zh-TW/plugins/loading#find-plugins-on-disk)的外掛不受 `version` 控制。它在每個工作階段啟動時載入您的目前檔案，無論其版本字串說什麼。

219 219

220對於除了就地載入或來自 `command` source 的安裝之外的每次安裝，要麼在每次發佈時增加 `version`，要麼省略它：220對於除了就地載入或來自 `command` source 的安裝之外的每次安裝，要麼在每次發佈時增加 `version`，要麼省略它：

221 221

plugins/loading.md +3 −3

Details

208Claude Code 根據 plugins 的來源，從您保存它們的位置就地載入某些 plugins，並將其餘的複製到快取中：208Claude Code 根據 plugins 的來源，從您保存它們的位置就地載入某些 plugins，並將其餘的複製到快取中：

209 209

210* **`--plugin-dir` 和技能目錄 plugins**：目錄就地載入，永遠不會被複製。`--plugin-url` 存檔或 `--plugin-dir` `.zip` 首先被提取到工作階段臨時目錄中210* **`--plugin-dir` 和技能目錄 plugins**：目錄就地載入，永遠不會被複製。`--plugin-url` 存檔或 `--plugin-dir` `.zip` 首先被提取到工作階段臨時目錄中

211* **您從本地目錄新增的市場中的相對路徑 plugins**：plugin 從其在市場資料夾內的路徑就地載入。您對來源目錄的編輯在下次工作階段啟動或 `/reload-plugins` 時生效，您無需增加版本。plugin 的 hook 程序和 MCP 和 LSP 伺服器接收指向來源目錄的 `CLAUDE_PLUGIN_ROOT`。如需其 Node.js 套件依賴項，請參閱 [依賴項安裝何時執行](#when-the-dependency-install-runs)211* **您從本機路徑新增的市集中的相對路徑外掛**：外掛從其在市集資料夾內的路徑就地載入。您對來源目錄的編輯會在下次工作階段啟動或 `/reload-plugins` 時生效，您無需增加版本。外掛的 hook 程序以及 MCP 和 LSP 伺服器會接收指向來源目錄的 `CLAUDE_PLUGIN_ROOT`。如需其 Node.js 相依套件，請參閱[相依套件安裝何時執行](#when-the-dependency-install-runs)

212* **[連結模式](/docs/zh-TW/plugins/marketplace-reference#command-plugin-source) 中的 `command` 來源 plugins**：命令列印的目錄通過快取項目中的連結就地載入212* **[連結模式](/docs/zh-TW/plugins/marketplace-reference#command-plugin-source) 中的 `command` 來源 plugins**：命令列印的目錄通過快取項目中的連結就地載入

213* **每個其他市場 plugin**：Claude Code 在安裝時將 plugin 複製到 `cache/<marketplace>/<plugin>/<version>/` 中並從該副本載入。plugin 目錄外的檔案不被複製，因此當 plugin 內的指令碼讀取 plugin 根目錄上方的路徑（例如 `../shared`）時，它找不到它們213* **每個其他市場 plugin**：Claude Code 在安裝時將 plugin 複製到 `cache/<marketplace>/<plugin>/<version>/` 中並從該副本載入。plugin 目錄外的檔案不被複製，因此當 plugin 內的指令碼讀取 plugin 根目錄上方的路徑（例如 `../shared`）時，它找不到它們

214 214

250* 當 Claude Code 將 plugin 更新到新版本時250* 當 Claude Code 將 plugin 更新到新版本時

251* 在工作階段啟動時，當已啟用 plugin 尚未快取時，例如在新機器上251* 在工作階段啟動時，當已啟用 plugin 尚未快取時，例如在新機器上

252 252

253對於從本地目錄市場 [就地載入](#in-place-and-copied-plugins) 的相對路徑 plugin，Claude Code 不會將依賴項安裝到來源目錄中。自己在那裡安裝它們，或從 hook 安裝到 [`${CLAUDE_PLUGIN_DATA}`](/docs/zh-TW/plugins/components#path-variables-and-persistent-data)。253對於從您以本機路徑新增的市集[就地載入](#in-place-and-copied-plugins)的相對路徑外掛，Claude Code 不會將相依套件安裝到來源目錄中。請自行在那裡安裝，或從 hook 安裝到 [`${CLAUDE_PLUGIN_DATA}`](/docs/zh-TW/plugins/components#path-variables-and-persistent-data)。

254 254

255安裝僅在外掛的根目錄同時包含 `package.json` 和支援的鎖定檔案時執行。255安裝僅在外掛的根目錄同時包含 `package.json` 和支援的鎖定檔案時執行。

256 256

315 315

316固定 `"version"` 的清單是計算的版本在提交中保持相同的一種方式。請參閱 [Claude Code 如何計算版本](#how-claude-code-computes-the-version) 以了解解決順序。316固定 `"version"` 的清單是計算的版本在提交中保持相同的一種方式。請參閱 [Claude Code 如何計算版本](#how-claude-code-computes-the-version) 以了解解決順序。

317 317

318從本地目錄市場 [就地載入](#in-place-and-copied-plugins) 的 plugin 在每次工作階段啟動時載入其當前來源檔案，無論其版本字串說什麼。對於從 [在 claude.ai 上託管的市場](/docs/zh-TW/plugins/install#add-from-claude-ai) 的 plugin，claude.ai 為 plugin 記錄的版本是其版本，清單的 `version` 不被讀取。318從您透過本機路徑新增的市集 [就地載入](#in-place-and-copied-plugins) 的 plugin 在每次工作階段啟動時載入其當前來源檔案，無論其版本字串說什麼。對於從 [在 claude.ai 上託管的市集](/docs/zh-TW/plugins/install#add-from-claude-ai) 的 plugin，claude.ai 為 plugin 記錄的版本是其版本，清單的 `version` 不被讀取。

319 319

320<h3 id="how-claude-code-computes-the-version">320<h3 id="how-claude-code-computes-the-version">

321 Claude Code 如何計算版本321 Claude Code 如何計算版本

plugins/manifest-reference.md +1 −1

Details

199 `version`199 `version`

200</h3>200</h3>

201 201

202版本字串，不根據 semver 檢查。設定它會將 plugin 固定到該版本，直到您變更它；請參閱[版本和更新](/docs/zh-TW/plugins/loading#versions-and-updates)。具有[`command` 來源](/docs/zh-TW/plugins/marketplace-reference)的 plugin、來自[託管在 claude.ai 上的 marketplace](/docs/zh-TW/plugins/install#add-from-claude-ai) 的 plugin，以及[就地載入](/docs/zh-TW/plugins/loading#find-plugins-on-disk)的 plugin（來自作為本機目錄新增的 marketplace）不受此欄位固定。202版本字串，不根據 semver 檢查。設定它會將 plugin 固定到該版本，直到您變更它；請參閱[版本和更新](/docs/zh-TW/plugins/loading#versions-and-updates)。具有[`command` 來源](/docs/zh-TW/plugins/marketplace-reference)的 plugin、來自[託管在 claude.ai 上的 marketplace](/docs/zh-TW/plugins/install#add-from-claude-ai) 的 plugin，以及[就地載入](/docs/zh-TW/plugins/loading#find-plugins-on-disk)的 plugin（來自從本機路徑新增的 marketplace）不受此欄位固定。

203 203

204<h3 id="metadata">204<h3 id="metadata">

205 `metadata`205 `metadata`

plugins/mods/interface.md +2 −2

Details

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

436| `Svg` | SVG 文件 | 桌面 |436| `Svg` | SVG 文件 | 桌面 |

438| `Raster`, `Image` | [彩色儲存格網格](#draw-a-grid-of-colored-cells)和圖片 | 終端機 |438| `Raster`, `Image` | [彩色儲存格網格](#draw-a-grid-of-colored-cells)和圖片 | 終端機 |

439 439

440如果您的模組是 `.tsx` 或 `.jsx` 檔案，您可以將樹寫成 JSX。請先從 `$.ui.resolve(e)` 解構元素。440如果您的模組是 `.tsx` 或 `.jsx` 檔案，您可以將樹寫成 JSX。請先從 `$.ui.resolve(e)` 解構元素。

664 當 Claude Code 在未被要求時重新繪製664 當 Claude Code 在未被要求時重新繪製

665</h3>665</h3>

666 666

667當位置的 prop 更改或終端機的寬度更改時，Claude Code 會再次執行您的 `ui.render` hook。它不會在計時器上執行 hook，也無法判斷您的模組中的變數何時更改。667當位置的 prop 更改或終端機的寬度更改時，Claude Code 會再次執行您的 `ui.render` hook。當位置中的 `Client` 失敗，且您的 mod 處理 [`ui.fault`](/docs/zh-TW/plugins/mods/reference#interface) 時，Claude Code 會在您的 `ui.fault` hook 返回後再執行一次該 hook，讓您的 `ui.render` hook 可以略過該 `Client`。它不會在計時器上執行 hook，也無法判斷您的模組中的變數何時更改。

668 668

669<h3 id="redraw-when-your-data-changes">669<h3 id="redraw-when-your-data-changes">

670 當您的資料更改時重新繪製670 當您的資料更改時重新繪製

plugins/mods/reference.md +7 −6

Details

6 6

7> Claude Code mod 的完整參考資料：hook 模組配置、事件、mods API 方法、轉譯位置、各使用介面的元素、限制與設定。7> Claude Code mod 的完整參考資料：hook 模組配置、事件、mods API 方法、轉譯位置、各使用介面的元素、限制與設定。

8 8

9查詢 [mod](/docs/zh-TW/plugins/mods/overview) 可處理的任何事件、可呼叫的任何 mods API 方法，或可繪製的任何轉譯位置，適用於 v2.1.287 版起的 Claude Code CLI 與 Desktop 應用程式。每個項目皆提供名稱與一行說明，若有對應的指南章節，亦會連結至該處。9查詢 [mod](/docs/zh-TW/plugins/mods/overview) 可處理的任何事件、可呼叫的任何 mods API 方法，或可繪製的任何轉譯位置，適用於 v2.1.289 版起的 Claude Code CLI 與 Desktop 應用程式。每個項目皆提供名稱與一行說明，若有對應的指南章節，亦會連結至該處。

10 10

11<Note>11<Note>

12 完整的參考資料是 Claude Code 的 [mod TypeScript 宣告](https://github.com/anthropics/claude-code/blob/main/mods/types/claude-code.d.ts)，其中以範例描述每個事件、方法與元素。GitHub 上的副本可能比您安裝的 Claude Code 版本更舊。兩者不一致時，請以 [Claude Code 為您的版本寫入的副本](/docs/zh-TW/plugins/mods/create#get-the-types-for-your-build)為準。12 完整的參考資料是 Claude Code 的 [mod TypeScript 宣告](https://github.com/anthropics/claude-code/blob/main/mods/types/claude-code.d.ts)，其中以範例描述每個事件、方法與元素。GitHub 上的副本可能比您安裝的 Claude Code 版本更舊。兩者不一致時，請以 [Claude Code 為您的版本寫入的副本](/docs/zh-TW/plugins/mods/create#get-the-types-for-your-build)為準。

128 Subagent128 Subagent

129</h3>129</h3>

130 130

131subagent 事件在 subagent 類型提供給 Claude 時，以及 subagent 即將啟動時觸發：131subagent 事件在 subagent 類型提供給 Claude 時，以及 subagent 或 agent team 隊員即將啟動時觸發：

132 132

133| 事件 | 觸發時機 | hook 可回傳 |133| 事件 | 觸發時機 | hook 可回傳 |

134| :- | :- | :- |134| :- | :- | :- |

135| `agent.offer` | subagent 類型提供給 Claude 時 | 以 `{ isOffered: false }` 保留不提供 |135| `agent.offer` | subagent 類型提供給 Claude 時 | 以 `{ isOffered: false }` 保留不提供 |

136| `agent.spawn` | subagent 即將啟動時 | `{ model }` 或 `{ deny: reason }` |136| `agent.spawn` | subagent 或 [agent team](/docs/zh-TW/agent-teams) 隊員即將啟動時。對於隊員，`e.isTeammate` 為 `true`。 | 以 `next({ ...e, model })` 選擇其模型，或 `{ deny: reason }` |

137 137

138<h3 id="interface">138<h3 id="interface">

139 介面139 介面

152| [`ui.fault`](/docs/zh-TW/plugins/mods/interface#redraw-when-something-changes) | 您的 mod 所繪製的 `Client` 元素無法載入、繪製或執行時。`e.phase` 為 `load`、`render` 或 `run`，`e.reason` 為錯誤訊息。需要 Claude Code v2.1.289 或更新版本。 |

152 153

153<h3 id="other-mods">154<h3 id="other-mods">

154 其他 mod155 其他 mod

192| 命名空間 | 方法 |193| 命名空間 | 方法 |

193| :- | :- |194| :- | :- |

195| [`$.ui`](/docs/zh-TW/plugins/mods/interface#pick-where-to-draw) | `resolve`、`invalidate`、`open`、`close`、`panes`、`focus`、`scroll`、`toast`、`status`、`log`、`notice`、`ask`、`copy`、`blit` |196| [`$.ui`](/docs/zh-TW/plugins/mods/interface#pick-where-to-draw) | `resolve`、`invalidate`、`open`、`close`、`panes`、`focus`、`scroll`、`toast`、`status`、`log`、`notice`、`ask`、`copy`、`selection`、`blit` |

276 277

277| 限制 | 值 |278| 限制 | 值 |

278| :- | :- |279| :- | :- |

279| hook 針對單一事件本身的執行時間，不計入 `next` 內部或 `$.clock.sleep` 以外之 mods API 呼叫內部的時間 | 10 秒 |280| hook 針對單一事件本身的執行時間，不計入 `next` 內部或 `$.clock.sleep` 以外之 mods API 呼叫內部的時間 | 10 秒，`prompt.edit` hook 則為 50 毫秒 |

280| `.catch` 處理常式的執行時間 | 1 秒 |281| `.catch` 處理常式的執行時間 | 1 秒 |

281| 所有 `session.end` hook 合計 | 1.5 秒 |282| 所有 `session.end` hook 合計 | 與 [SessionEnd hook 預算](/docs/zh-TW/hooks#sessionend-input)相同，除非您變更，否則為 1.5 秒，自您設定中的 `SessionEnd` hook 完成時起算 |

plugins/troubleshooting.md +1 −1

Details

1016 1016

1017按順序檢查這些原因：1017按順序檢查這些原因：

1018 1018

1019* **Skill 設定 `disable-model-invocation: true`**：設定該欄位後，只有您可以叫用該 skill。[建立您的第一個外掛程式](/docs/zh-TW/plugins/create#create-your-first-plugin)中的範本 skill 會設定它。從您想要 Claude 自行叫用的 skill 中移除該行。[控制誰叫用 skill](/docs/zh-TW/skills#control-who-invokes-a-skill) 涵蓋該欄位1019* **Skill 設定 `disable-model-invocation: true`**：[建立您的第一個外掛程式](/docs/zh-TW/plugins/create#create-your-first-plugin)中的範本 skill 會設定它。從您想要 Claude 自行叫用的 skill 中移除該行。[控制誰叫用 skill](/docs/zh-TW/skills#control-who-invokes-a-skill) 涵蓋該欄位

1020* **描述不符合人們的提問方式**：完成[Skill 未觸發](/docs/zh-TW/skills#skill-not-triggering)中的檢查1020* **描述不符合人們的提問方式**：完成[Skill 未觸發](/docs/zh-TW/skills#skill-not-triggering)中的檢查

1021* **描述被截斷**：安裝許多 skills 時，Claude Code 會縮短描述以符合列表的字元預算，這可能會去除 Claude 需要匹配請求的關鍵字。請參閱[Skill 描述被截短](/docs/zh-TW/skills#skill-descriptions-are-cut-short)1021* **描述被截斷**：安裝許多 skills 時，Claude Code 會縮短描述以符合列表的字元預算，這可能會去除 Claude 需要匹配請求的關鍵字。請參閱[Skill 描述被截短](/docs/zh-TW/skills#skill-descriptions-are-cut-short)

1022 1022

sandboxing.md +1 −1

Details

463 463

464遮罩需要以下條件：464遮罩需要以下條件：

465 465

466* **TLS 終止**：代理伺服器會在請求內容中替換真實值，因此必須能看到請求內容。請設定 [`network.tlsTerminate`](/docs/zh-TW/settings-reference#sandbox-network-tlsterminate)，讓代理伺服器自行終止 TLS。若未設定，遮罩會失敗但不會洩漏任何內容：命令仍只看到哨兵值，但哨兵值會原封不動地送達伺服器，導致身分驗證失敗。Claude Code 會在啟動時回報此設定錯誤。466* **TLS 終止**：代理伺服器會在請求內容中替換真實值，因此必須能看到請求內容。請設定 [`network.tlsTerminate`](/docs/zh-TW/settings-reference#sandbox-network-tlsterminate)，讓代理伺服器自行終止 TLS。若未設定，遮罩會失敗但不會洩漏任何內容：命令仍只看到哨兵值，但哨兵值會原封不動地送達伺服器，導致身分驗證失敗。若要檢查此設定錯誤，請在終端機中執行 `claude doctor`，並查看是否出現 `TLS termination is unavailable` 警告。

467* **允許的目的地**：每個 `mask` 項目可以列出 `injectHosts`，即允許真實值送達的主機。代理伺服器只會在[網域允許清單](#network-isolation)允許的連線上注入，因此每個 `injectHosts` 主機也必須能透過 `network.allowedDomains` 連線到。對於沒有 `injectHosts` 的 `mask` 項目，代理伺服器會在傳送至 `network.allowedDomains` 中每個主機的請求中替換真實值。467* **允許的目的地**：每個 `mask` 項目可以列出 `injectHosts`，即允許真實值送達的主機。代理伺服器只會在[網域允許清單](#network-isolation)允許的連線上注入，因此每個 `injectHosts` 主機也必須能透過 `network.allowedDomains` 連線到。對於沒有 `injectHosts` 的 `mask` 項目，代理伺服器會在傳送至 `network.allowedDomains` 中每個主機的請求中替換真實值。

468* **受信任的設定範圍**：遮罩會授權代理伺服器將您的真實憑證傳送至某處，因此 Claude Code 只接受來自使用者設定、受管設定和 `--settings` 旗標的 `mask` 項目、`network.tlsTerminate`、[`credentials.allowPlaintextInject`](/docs/zh-TW/settings-reference#sandbox-credentials-allowplaintextinject)、`awsPairs` 和 `sigv4`。它會忽略儲存庫的 `.claude/settings.json` 或 `.claude/settings.local.json` 中的這些設定。當您的管理員透過伺服器管理的設定提供 `mask` 項目、`network.tlsTerminate` 或 `credentials.allowPlaintextInject` 時，這些會被視為[需要核准的設定](/docs/zh-TW/server-managed-settings#security-approval-dialogs)。468* **受信任的設定範圍**：遮罩會授權代理伺服器將您的真實憑證傳送至某處，因此 Claude Code 只接受來自使用者設定、受管設定和 `--settings` 旗標的 `mask` 項目、`network.tlsTerminate`、[`credentials.allowPlaintextInject`](/docs/zh-TW/settings-reference#sandbox-credentials-allowplaintextinject)、`awsPairs` 和 `sigv4`。它會忽略儲存庫的 `.claude/settings.json` 或 `.claude/settings.local.json` 中的這些設定。當您的管理員透過伺服器管理的設定提供 `mask` 項目、`network.tlsTerminate` 或 `credentials.allowPlaintextInject` 時，這些會被視為[需要核准的設定](/docs/zh-TW/server-managed-settings#security-approval-dialogs)。

469 469

self-hosted-environments-deploy.md +19 −0

Details

195 195

196執行器也會在註冊時向 Anthropic 報告選擇加入，在啟動時列印 `Registering as opted in to Anthropic-managed git (--use-anthropic-git-proxy)`。報告選擇加入需要 Claude Code v2.1.267 或更新版本，較早的版本接受該旗標而不報告它或列印該行。選擇加入執行器上的每個工作階段隨後使用 Anthropic 管理的 Git 或每個工作階段的代理 URL。當工作階段使用每個工作階段的代理 URL 時，執行器記錄一行 `[runner:warn]` 說明這一點。196執行器也會在註冊時向 Anthropic 報告選擇加入，在啟動時列印 `Registering as opted in to Anthropic-managed git (--use-anthropic-git-proxy)`。報告選擇加入需要 Claude Code v2.1.267 或更新版本，較早的版本接受該旗標而不報告它或列印該行。選擇加入執行器上的每個工作階段隨後使用 Anthropic 管理的 Git 或每個工作階段的代理 URL。當工作階段使用每個工作階段的代理 URL 時，執行器記錄一行 `[runner:warn]` 說明這一點。

197 197

198<h4 id="github-api-access-without-the-github-cli">

199 不使用 GitHub CLI 存取 GitHub API

200</h4>

201

202如果您的執行器映像不包含 GitHub CLI，Claude Code 可以提供內建的 `gh`，讓 Claude 仍能開啟 pull request、留言以及讀取 CI 結果。內建的 `gh` 適用於使用 Anthropic 管理之 Git 的執行器。它支援一個命令 `gh api`，用於呼叫 GitHub 的 REST API。執行器映像中需要 Claude Code v2.1.287 或更新版本。

203

204以下命令會開啟 pull request，取代 `gh pr create`。內建的 `gh` 會為目前的儲存庫填入 `{owner}` 和 `{repo}`：

205

206```bash theme={null}

207gh api repos/{owner}/{repo}/pulls -f title='Fix' -f head='my-branch' -f base='main'

208```

209

210* **憑證**：內建的 `gh` 透過 Anthropic 管理的 Git 傳送其 REST 請求，由 Anthropic 端提供 GitHub 憑證，因此映像不需要為此準備 GitHub token

211* **哪些工作階段會取得它**：Anthropic 會針對每個工作階段決定是否由 Anthropic 管理的 Git 提供該工作階段的 `gh`。若有提供，執行器為該工作階段記錄的 `[runner:session] governed git ACTIVE` 行會顯示 `gh_path_shim=true`。若沒有提供，該工作階段就沒有 `gh`

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

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

214

215當映像包含 GitHub CLI 時，工作階段會使用它。

216

198<h4 id="trust-a-private-certificate-authority-with-anthropic-managed-git">217<h4 id="trust-a-private-certificate-authority-with-anthropic-managed-git">

199 使用 Anthropic 管理的 Git 信任私有憑證授權單位218 使用 Anthropic 管理的 Git 信任私有憑證授權單位

200</h4>219</h4>

self-hosted-environments-quickstart.md +1 −1

Details

117claude -p "your message" --cloud <session-id>117claude -p "your message" --cloud <session-id>

118```118```

119 119

120對於 `<session-id>`，傳遞裸 `session_...` 或 `cse_...` ID 或工作階段的 claude.ai/code URL。成功傳送會列印 `Sent to cloud session.` 以及工作階段 ID 和檢視連結。接受的 ID 形式、JSON 輸出、帳戶和原則需求，以及錯誤參考在[從 CLI 傳送後續訊息](/docs/zh-TW/claude-code-on-the-web#send-follow-ups-from-the-cli)上，因為該命令對 Anthropic 託管的工作階段的工作方式相同。120對於 `<session-id>`，傳遞裸 `session_...` 或 `cse_...` ID 或工作階段的 claude.ai/code URL。成功傳送會列印 `Sent to cloud session.` 以及工作階段 ID 和檢視連結。接受的 ID 形式、JSON 輸出，以及帳戶和原則需求在[從 CLI 傳送後續訊息](/docs/zh-TW/claude-code-on-the-web#send-follow-ups-from-the-cli)上，因為該命令對 Anthropic 託管的工作階段的工作方式相同。

121 121

122<h2 id="what’s-next">122<h2 id="what’s-next">

123 接下來的步驟123 接下來的步驟

server-managed-settings.md +3 −3

Details

6 6

7> 透過伺服器傳遞的設定在您的組織中集中設定 Claude Code，無需裝置管理基礎設施。7> 透過伺服器傳遞的設定在您的組織中集中設定 Claude Code，無需裝置管理基礎設施。

8 8

9伺服器管理的設定允許組織擁有者透過 claude.ai 主控台中的 [**Admin Settings > Claude Code > Managed settings**](https://claude.ai/admin-settings/claude-code) 集中設定 Claude Code。Claude Code 用戶端在使用者使用符合條件的認證在支援伺服器管理傳遞的平台上進行身份驗證時會自動接收這些設定。請參閱[平台可用性](#platform-availability)以了解符合條件的認證和平台。9伺服器管理的設定允許組織擁有者透過 claude.ai 主控台中的 [**Organization settings > Claude Code > Managed settings**](https://claude.ai/admin-settings/claude-code) 集中設定 Claude Code。當使用者在支援伺服器管理傳遞的平台上使用符合條件的憑證進行身分驗證時，Claude Code 用戶端會自動擷取這些設定。請參閱[平台可用性](#platform-availability)以了解符合條件的憑證和平台。

10 10

11<Note>11<Note>

12 伺服器管理的設定適用於 [Claude for Teams](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=server_settings_teams#team-&-enterprise) 和 [Claude for Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=server_settings_enterprise) 客戶。12 伺服器管理的設定適用於 [Claude for Teams](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=server_settings_teams#team-&-enterprise) 和 [Claude for Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=server_settings_enterprise) 客戶。

41 41

42<Steps>42<Steps>

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

~~44 在 claude.ai 主控台中，前往 [**Admin 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 如果連結將您重新導向至不同的 Admin Settings 頁面，而不是 Claude Code 頁面，表示您的帳戶沒有所需的角色。管理員和其他非擁有者角色無法檢視或編輯受管設定，因此請要求您組織中的擁有者或主要擁有者進行變更。請參閱[存取控制](#access-control)。46 如果連結將您重新導向至不同的 Organization settings 頁面，而不是 Claude Code 頁面，表示您的帳戶沒有所需的角色。管理員和其他非擁有者角色無法檢視或編輯受管設定，因此請要求您組織中的擁有者或主要擁有者進行變更。請參閱[存取控制](#access-control)。

47 </Step>47 </Step>

48 48

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

sessions.md +1 −0

Details

294| 為 [Claude Desktop 和 Cowork 逐字稿](/docs/zh-TW/claude-directory#cleaned-up-automatically) 設定年齡限制 | [`desktopSessionCleanupPeriodDays`](/docs/zh-TW/settings-reference#desktopsessioncleanupperioddays) | 使用者設定、受管設定或 `--settings` |294| 為 [Claude Desktop 和 Cowork 逐字稿](/docs/zh-TW/claude-directory#cleaned-up-automatically) 設定年齡限制 | [`desktopSessionCleanupPeriodDays`](/docs/zh-TW/settings-reference#desktopsessioncleanupperioddays) | 使用者設定、受管設定或 `--settings` |

295| 限制 `-p` 或 Agent SDK 工作階段的逐字稿檔案可成長的大小 | [`CLAUDE_CODE_TRANSCRIPT_LOCAL_GC`](/docs/zh-TW/env-vars) | 環境變數 |

297 298

settings-reference.md +3 −1

Details

990 990

991當您的組織部署任何受管設定時，Claude Code 僅從受管來源讀取此金鑰，並忽略您其他檔案中的此金鑰。991當您的組織部署任何受管設定時，Claude Code 僅從受管來源讀取此金鑰，並忽略您其他檔案中的此金鑰。

992 992

993如需了解此設定鍵如何套用於啟動時的模型檢查，請參閱 [Amazon Bedrock](/docs/zh-TW/amazon-bedrock#when-your-organization-enforces-a-model-allowlist) 和 [Google Cloud 的 Agent Platform](/docs/zh-TW/google-vertex-ai#when-your-organization-enforces-a-model-allowlist)。

994

993* **範圍**: [`任何檔案`](#scopes)995* **範圍**: [`任何檔案`](#scopes)

994* **類型**: 布林值996* **類型**: 布林值

995 * `true`: 當**預設**會解析為 `availableModels` 外的模型時，Claude Code 將其解析為清單中第一個可用的模型997 * `true`: 當**預設**會解析為 `availableModels` 外的模型時，Claude Code 將其解析為清單中第一個可用的模型

3135* [`CLAUDE_CODE_PROJECT_DIR_NAME`](/docs/zh-TW/sessions#name-the-project-directory-yourself)，Claude Code 僅從啟動環境讀取，從每個檔案中被忽略；需要 v2.1.234 或更高版本。3137* [`CLAUDE_CODE_PROJECT_DIR_NAME`](/docs/zh-TW/sessions#name-the-project-directory-yourself)，Claude Code 僅從啟動環境讀取，從每個檔案中被忽略；需要 v2.1.234 或更高版本。

3136* [`CLAUDE_CODE_RESTRICTED`](/docs/zh-TW/env-vars#variables)，Claude Code 僅從啟動環境讀取，從每個檔案中被忽略。3138* [`CLAUDE_CODE_RESTRICTED`](/docs/zh-TW/env-vars#variables)，Claude Code 僅從啟動環境讀取，從每個檔案中被忽略。

3137* [`CLAUDE_CODE_DISABLE_POWERSHELL_CMD_RM_DENY`](/docs/zh-TW/env-vars#variables)，Claude Code 僅從啟動環境讀取，從每個檔案中被忽略。此變數需要 Claude Code v2.1.283 或更高版本。3139* [`CLAUDE_CODE_DISABLE_POWERSHELL_CMD_RM_DENY`](/docs/zh-TW/env-vars#variables)，Claude Code 僅從啟動環境讀取，從每個檔案中被忽略。此變數需要 Claude Code v2.1.283 或更高版本。

3138* [`CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT` 和 `CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT`](/docs/zh-TW/env-vars#variables)，Claude Code 僅從啟動環境讀取，從每個檔案中被忽略。3140* [`CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT`、`CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT` 和 `CLAUDE_CODE_DISABLE_INLINE_SHELL_RM_PROMPT`](/docs/zh-TW/env-vars#variables)，Claude Code 僅從啟動環境讀取，從每個檔案中被忽略。

3139 3141

3140<h3 id="filecheckpointingenabled">3142<h3 id="filecheckpointingenabled">

3141 `fileCheckpointingEnabled`3143 `fileCheckpointingEnabled`

skills.md +16 −3

Details

561 561

562預設情況下，您和 Claude 都可以調用任何 skill。您可以鍵入 `/skill-name` 直接調用它，Claude 可以在與您的對話相關時自動加載它。兩個 frontmatter 欄位讓您限制這一點：562預設情況下，您和 Claude 都可以調用任何 skill。您可以鍵入 `/skill-name` 直接調用它，Claude 可以在與您的對話相關時自動加載它。兩個 frontmatter 欄位讓您限制這一點：

563 563

564* **`disable-model-invocation: true`**：只有您可以調用 skill。用於具有副作用或您想控制時序的工作流程，例如 `/commit`、`/deploy` 或 `/send-slack-message`。您不希望 Claude 因為您的程式碼看起來準備好就決定部署。564* **`disable-model-invocation: true`**：Claude 無法自行調用 skill。用於具有副作用或您想控制時序的工作流程，例如 `/commit`、`/deploy` 或 `/send-slack-message`。您不希望 Claude 因為您的程式碼看起來準備好就決定部署。

565 565

566* **`user-invocable: false`**：只有 Claude 可以調用 skill。用於不可作為命令操作的背景知識。`legacy-system-context` skill 解釋舊系統的工作原理。Claude 應在相關時知道這一點，但 `/legacy-system-context` 對使用者來說不是一個有意義的操作。566* **`user-invocable: false`**：只有 Claude 可以調用 skill。用於不可作為命令操作的背景知識。`legacy-system-context` skill 解釋舊系統的工作原理。Claude 應在相關時知道這一點，但 `/legacy-system-context` 對使用者來說不是一個有意義的操作。

567 567

568此範例建立一個只有您可以觸發的部署 skill。如果您設定 `disable-model-invocation: true`，Claude 無法自動運行 skill：568此範例建立一個部署 skill。如果您設定 `disable-model-invocation: true`，Claude 無法自動運行 skill：

569 569

570```yaml theme={null}570```yaml theme={null}

571---571---

590| :- | :- | :- | :- |590| :- | :- | :- | :- |

591| （預設） | 是 | 是 | 描述始終在上下文中，調用時加載完整 skill |591| （預設） | 是 | 是 | 描述始終在上下文中，調用時加載完整 skill |

592| `disable-model-invocation: true` | 是 | 否 | 描述不在上下文中，您調用時加載完整 skill |592| `disable-model-invocation: true` | 是 | 無法自行調用 | 描述不在上下文中，調用時加載完整 skill |

593| `user-invocable: false` | 否 | 是 | 描述始終在上下文中，調用時加載完整 skill |593| `user-invocable: false` | 否 | 是 | 描述始終在上下文中，調用時加載完整 skill |

594 594

595<Note>595<Note>

596 在常規工作階段中，skill 描述被加載到上下文中，以便 Claude 知道什麼可用，但完整 skill 內容僅在調用時加載。[具有預加載 skills 的子代理](/docs/zh-TW/sub-agents#preload-skills-into-subagents)的工作方式不同：完整 skill 內容在啟動時注入。596 在常規工作階段中，skill 描述被加載到上下文中，以便 Claude 知道什麼可用，但完整 skill 內容僅在調用時加載。[具有預加載 skills 的子代理](/docs/zh-TW/sub-agents#preload-skills-into-subagents)的工作方式不同：完整 skill 內容在啟動時注入。

597</Note>597</Note>

598 598

599<h4 id="where-you-write-the-skill’s-name">

600 在何處寫入 skill 的名稱

601</h4>

602

603若要直接執行 skill，請將其名稱放在訊息的開頭。在一般文字之後，名稱會授予 Claude 執行該 skill 的權限，但不會執行它：

604

605| 位置 | 範例 | 結果 |

606| :- | :- | :- |

607| 在訊息的開頭 | `/deploy staging` | Claude Code 直接執行 skill |

608| 在一般文字之後，作為獨立的單詞且未附加標點符號 | `go ahead and /deploy to staging` | 不會直接執行任何內容。該名稱視為您對該訊息的權限：Claude 可以在回應時執行 skill，並根據您的措辭判斷您是否要求它這麼做 |

609

610若要提及 skill 而不允許執行，請省略斜線。

611

599<h3 id="skill-content-lifecycle">612<h3 id="skill-content-lifecycle">

600 Skill 內容生命週期613 Skill 內容生命週期

601</h3>614</h3>

sub-agents.md +1 −1

Details

632 632

633每個列出的技能的完整內容在啟動時注入子代理的上下文。此欄位控制哪些技能被預載入，而不是子代理可以存取哪些技能：沒有它，子代理仍然可以在執行期間透過 Skill 工具發現和叫用專案、使用者和 plugin 技能。若要防止子代理完全叫用技能，從 [`tools`](#available-tools) 列表中省略 `Skill` 或將其新增到 `disallowedTools`。633每個列出的技能的完整內容在啟動時注入子代理的上下文。此欄位控制哪些技能被預載入，而不是子代理可以存取哪些技能：沒有它，子代理仍然可以在執行期間透過 Skill 工具發現和叫用專案、使用者和 plugin 技能。若要防止子代理完全叫用技能，從 [`tools`](#available-tools) 列表中省略 `Skill` 或將其新增到 `disallowedTools`。

634 634

635您無法預載入設定 [`disable-model-invocation: true`](/docs/zh-TW/skills#control-who-invokes-a-skill) 的技能，因為預載入來自 Claude 可以叫用的相同技能集。這包括捆綁的 `/verify` 技能：只有您可以執行它，因此它也無法被預載入。635您無法預先載入設定了 [`disable-model-invocation: true`](/docs/zh-TW/skills#control-who-invokes-a-skill) 的 skill，因為預先載入取自 Claude 可叫用的同一組 skill。這包括內建的 `/verify` skill，Claude 無法自行執行它。

636 636

637如果列出的技能遺失或被禁用，例如由您組織的原則，Claude Code 跳過它並將警告記錄到偵錯日誌。637如果列出的技能遺失或被禁用，例如由您組織的原則，Claude Code 跳過它並將警告記錄到偵錯日誌。

638 638

tools-reference.md +13 −0

Details

487 487

488Claude Code 以程序範圍只啟動 PowerShell 搭配 `-ExecutionPolicy Bypass`，因此 `.ps1` 指令碼和模組匯入可在預設 Windows 安裝上運作，無需變更機器的原則。程序範圍略過不會覆寫群組原則 `MachinePolicy` 或 `UserPolicy`，因此企業原則仍然適用。若要改為遵守機器的有效執行原則，請設定 `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1`。488Claude Code 以程序範圍只啟動 PowerShell 搭配 `-ExecutionPolicy Bypass`，因此 `.ps1` 指令碼和模組匯入可在預設 Windows 安裝上運作，無需變更機器的原則。程序範圍略過不會覆寫群組原則 `MachinePolicy` 或 `UserPolicy`，因此企業原則仍然適用。若要改為遵守機器的有效執行原則，請設定 `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1`。

489 489

490<h3 id="bash-deny-rules-also-turn-off-the-powershell-tool">

491 Bash 拒絕規則也會關閉 PowerShell 工具

492</h3>

493

494在已安裝 Git Bash 的 Windows 上，拒絕 Bash 也會在該工作階段中關閉 PowerShell 工具。這適用於範圍限定的規則（例如 `Bash(git push *)`）以及單獨的 `Bash`，也適用於來自您任一設定檔或 `--disallowedTools` 的規則。Claude Code 這樣做是因為 `Bash` 規則不會限制 PowerShell 工具，後者有[自己的權限規則](/docs/zh-TW/permissions#powershell)。若 PowerShell 保持開啟，Claude 可能會在其中執行您的規則在 Bash 中所拒絕的操作。

495

496若要在有 Bash 拒絕規則的同時保持 PowerShell 工具開啟，請執行下列任一操作：

497

498* 在您的環境或設定檔的 `env` 區塊中設定 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`，如[啟用 PowerShell 工具](#enable-the-powershell-tool)所示。

499* 在設定檔中新增範圍限定的 [`PowerShell` 權限規則](/docs/zh-TW/permissions#powershell)，例如 `PowerShell(git push *)` 拒絕規則。

500

501若沒有其中任何一項，範圍限定的 Bash 拒絕規則會讓 Bash 工具保持可用，而 Claude Code 會在沒有警告的情況下關閉 PowerShell。移除整個 Bash 工具的規則會讓 Claude 在該工作階段中沒有任何 shell 工具。

502

490<h3 id="shell-selection-in-settings-hooks-and-skills">503<h3 id="shell-selection-in-settings-hooks-and-skills">

491 設定、hooks 和 skills 中的 shell 選擇504 設定、hooks 和 skills 中的 shell 選擇

492</h3>505</h3>

web-quickstart.md +4 −4

Details

62連接 GitHub 是一次性步驟。如果您已經使用 GitHub CLI，您可以[從終端執行此操作](#connect-from-your-terminal)，而不是使用瀏覽器。62連接 GitHub 是一次性步驟。如果您已經使用 GitHub CLI，您可以[從終端執行此操作](#connect-from-your-terminal)，而不是使用瀏覽器。

63 63

64<Note>64<Note>

65 在 Team 和 Enterprise 方案上，**使用 GitHub 登入**步驟僅在您的 Claude 組織的[擁有者](/docs/zh-TW/server-managed-settings#access-control)在[**管理設定 > 連接器**](https://claude.ai/admin-settings/connectors)開啟 GitHub 連接器後才有效。在此之前，該步驟會顯示「GitHub 存取權是 Claude Code 網頁版所需」而不是登入按鈕。連接器開啟後，重新載入 [claude.ai/code](https://claude.ai/code) 並從第一步重新開始。第二個切換開關[快速網頁設定](/docs/zh-TW/claude-code-on-the-web#github-authentication-options)位於[**管理設定 > Claude Code**](https://claude.ai/admin-settings/claude-code)，是選用的：開啟時，`/web-setup` 可運作，且上線流程會為成員建立環境。65 在 Team 和 Enterprise 方案上，**使用 GitHub 登入**步驟僅在您的 Claude 組織的[擁有者](/docs/zh-TW/server-managed-settings#access-control)在[**組織設定 > 連接器**](https://claude.ai/admin-settings/connectors)開啟 GitHub 連接器後才有效。在此之前，該步驟會顯示「GitHub access is required for Claude Code cloud sessions」而不是登入按鈕。連接器開啟後，重新載入 [claude.ai/code](https://claude.ai/code) 並從第一步重新開始。第二個切換開關[快速設定](/docs/zh-TW/claude-code-on-the-web#quick-setup-for-team-and-enterprise)位於[**組織設定 > Claude Code**](https://claude.ai/admin-settings/claude-code)，是選用的：開啟時，`/web-setup` 可運作，且上線流程會為成員建立環境。

66</Note>66</Note>

67 67

68<Steps>68<Steps>

84 [雲端環境](/docs/zh-TW/cloud-environments)是已儲存的設定，控制 Claude 在工作階段期間具有的網路存取權，以及工作階段啟動時執行的內容。連接 GitHub 後發生的情況取決於您的方案：84 [雲端環境](/docs/zh-TW/cloud-environments)是已儲存的設定，控制 Claude 在工作階段期間具有的網路存取權，以及工作階段啟動時執行的內容。連接 GitHub 後發生的情況取決於您的方案：

85 85

86 * **Pro 和 Max**：上線流程會為您建立名為**預設**的環境。86 * **Pro 和 Max**：上線流程會為您建立名為**預設**的環境。

87 * **Team 和 Enterprise**：上線流程會顯示**建立您的第一個雲端環境**表單。保持預填的名稱和網路存取權不變，然後按一下**建立並完成**以建立**預設**環境。如果擁有者已開啟[快速網頁設定](/docs/zh-TW/claude-code-on-the-web#github-authentication-options)，上線流程會改為為您建立**預設**。87 * **Team 和 Enterprise**：上線流程會顯示**建立您的第一個雲端環境**表單。保持預填的名稱和網路存取權不變，然後按一下**建立並完成**以建立**預設**環境。如果擁有者已開啟[快速設定](/docs/zh-TW/claude-code-on-the-web#quick-setup-for-team-and-enterprise)，上線流程會改為為您建立**預設**。

88 88

89 **預設**使用[`信任`網路存取權](/docs/zh-TW/cloud-environments#access-levels)：工作階段可以存取[常見套件登錄](/docs/zh-TW/cloud-environments#default-allowed-domains)和其他允許清單中的網域，以及透過工作階段網路的其他任何內容都無法存取。請參閱[已安裝的工具](/docs/zh-TW/cloud-environments#installed-tools)以了解無需任何設定即可使用的內容。89 **預設**使用[`信任`網路存取權](/docs/zh-TW/cloud-environments#access-levels)：工作階段可以存取[常見套件登錄](/docs/zh-TW/cloud-environments#default-allowed-domains)和其他允許清單中的網域，以及透過工作階段網路的其他任何內容都無法存取。請參閱[已安裝的工具](/docs/zh-TW/cloud-environments#installed-tools)以了解無需任何設定即可使用的內容。

90 90

96 從您的終端連接96 從您的終端連接

97</h3>97</h3>

98 98

99如果您已經使用 GitHub CLI (`gh`)，您可以從終端為雲端工作階段連接 GitHub。這需要 [Claude Code CLI](/docs/zh-TW/quickstart)。在 Team 和 Enterprise 方案上，`/web-setup` 僅在擁有者開啟[快速網頁設定](/docs/zh-TW/claude-code-on-the-web#github-authentication-options)後才可用。99如果您已經使用 GitHub CLI (`gh`)，您可以從終端機為雲端工作階段連接 GitHub。這需要 [Claude Code CLI](/docs/zh-TW/quickstart)。在 Team 和 Enterprise 方案上，`/web-setup` 僅在擁有者開啟[快速設定](/docs/zh-TW/claude-code-on-the-web#quick-setup-for-team-and-enterprise)後才可用。

100 100

101當您執行 `/web-setup` 時，Claude Code 會讀取 `gh auth token` 列印的權杖，要求您確認，並將權杖傳送給 Anthropic。Anthropic 會使用您的 claude.ai 帳戶加密儲存它，您的雲端工作階段會使用它進行 GitHub 存取，直到您[移除它](#remove-the-web-setup-token)。您自己啟動的雲端工作階段隨後可以存取該權杖可以存取的任何儲存庫，無需 Claude GitHub App 安裝。[專案](/docs/zh-TW/claude-projects#set-up-github-access)中的執行緒仍然需要 Claude GitHub App。101當您執行 `/web-setup` 時，Claude Code 會讀取 `gh auth token` 列印的權杖，要求您確認，並將權杖傳送給 Anthropic。Anthropic 會使用您的 claude.ai 帳戶加密儲存它，您的雲端工作階段會使用它進行 GitHub 存取，直到您[移除它](#remove-the-web-setup-token)。您自己啟動的雲端工作階段隨後可以存取該權杖可以存取的任何儲存庫，無需 Claude GitHub App 安裝。[專案](/docs/zh-TW/claude-projects#set-up-github-access)中的執行緒仍然需要 Claude GitHub App。

102 102

259 259

260如果您在 Claude Code 內輸入它並且命令菜單顯示 `No commands match "/web-setup"`，或提交它返回 `Unknown command: /web-setup`，該命令被隱藏是因為未滿足要求。原因通常是您使用 API 金鑰或第三方提供商而不是 claude.ai 訂閱進行驗證。執行 `/login` 以使用您的 claude.ai 帳戶登入。260如果您在 Claude Code 內輸入它並且命令菜單顯示 `No commands match "/web-setup"`，或提交它返回 `Unknown command: /web-setup`，該命令被隱藏是因為未滿足要求。原因通常是您使用 API 金鑰或第三方提供商而不是 claude.ai 訂閱進行驗證。執行 `/login` 以使用您的 claude.ai 帳戶登入。

261 261

262在 Team 和 Enterprise 方案上，該命令預設是隱藏的：[快速網頁設定切換](/docs/zh-TW/claude-code-on-the-web#github-authentication-options)在擁有者開啟之前是關閉的。當它關閉時，[從瀏覽器連接 GitHub](#connect-github) 代替。262在 Team 和 Enterprise 方案上，該命令預設是隱藏的：[快速設定切換](/docs/zh-TW/claude-code-on-the-web#quick-setup-for-team-and-enterprise)在擁有者開啟之前是關閉的。當它關閉時，請改為[從瀏覽器連接 GitHub](#connect-github)。

263 263

264該命令在另外兩種情況下也被隱藏：264該命令在另外兩種情況下也被隱藏：

265 265

Documentation 2026-10-03 23:57 UTC to 2026-10-04 18:58 UTC