Documentation — Spybara

advisor.md +4 −3

Details

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

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

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

101| Fable 5 | Fable 5.1 或 Fable 5 |101| Fable 5 | Fable 5.2、Fable 5.1 或 Fable 5 |

102| Fable 5.1 | Fable 5.1 |102| Fable 5.1 | Fable 5.2 或 Fable 5.1 |

103| Fable 5.2 | Fable 5.2 |

103 104

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

105 106

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

107 108

agent-sdk/custom-tools.md +17 −11

Details

56 56

57### 天氣工具範例57### 天氣工具範例

58 58

59此範例定義 `get_temperature` 工具並將其包裝在 MCP 伺服器中，但不將伺服器傳遞給 `query`。若要執行工具，請參閱下面的[呼叫自訂工具](#call-a-custom-tool)。59此範例定義 `get_temperature` 工具並將其包裝在 MCP 伺服器中，但不將伺服器傳遞給 `query`。若要執行工具，請參閱[呼叫自訂工具](#call-a-custom-tool)。

60 60

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

62from typing import Annotated, Any62from typing import Annotated, Any

148* **TypeScript**：將 `.optional()` 新增至 Zod 欄位。148* **TypeScript**：將 `.optional()` 新增至 Zod 欄位。

149* **Python**：字典 schema 要求每個鍵都必須提供。請使用 JSON Schema 形式，將該參數排除在 `required` 之外，並使用 `args.get()` 讀取它。若要使用具有選用鍵的型別化 schema，請參閱 [TypedDict 類別](https://code.claude.com/docs/zh-TW/agent-sdk/python.md#input-schema-options)。149* **Python**：字典 schema 要求每個鍵都必須提供。請使用 JSON Schema 形式，將該參數排除在 `required` 之外，並使用 `args.get()` 讀取它。若要使用具有選用鍵的型別化 schema，請參閱 [TypedDict 類別](https://code.claude.com/docs/zh-TW/agent-sdk/python.md#input-schema-options)。

150 150

151[下面的 `get_precipitation_chance` 工具](#add-more-tools)顯示兩種模式。151[`get_precipitation_chance` 工具](#add-more-tools)顯示兩種模式。

152 152

153### 呼叫自訂工具153### 呼叫自訂工具

154 154

155透過 `mcpServers` 選項將您建立的 MCP 伺服器傳遞給 `query`，並在 `allowedTools` 中列出每個工具的[完全限定名稱](https://code.claude.com/docs/zh-TW/agent-sdk/mcp.md#tool-naming-convention)，以便工具執行時不會出現權限提示。該名稱為 `mcp__{server_name}__{tool_name}`，其中 `{server_name}` 是您在 `mcpServers` 中為伺服器指定的鍵。如果該鍵包含 `.` 或空格等字元，撰寫 `{server_name}` 時請將其替換為 `_`。155若要呼叫自訂工具，請依照下列步驟操作：

156

1571. 使用 `mcpServers` 選項將您建立的 MCP 伺服器傳遞給 `query`。

1582. 在 `allowedTools` 中列出工具的[完全限定名稱](https://code.claude.com/docs/zh-TW/agent-sdk/mcp.md#tool-naming-convention)，以[預先核准](https://code.claude.com/docs/zh-TW/agent-sdk/permissions.md#allow-and-deny-rules)其呼叫。該名稱遵循 `mcp__{server_name}__{tool_name}` 慣例，其中 `{server_name}` 是您在 `mcpServers` 中為伺服器指定的鍵。如果該鍵包含 `.` 或空格等字元，撰寫 `{server_name}` 時請將其替換為 `_`。

156 159

157這些程式碼片段重複使用[天氣工具範例](#weather-tool-example)中的 `weatherServer` 來詢問 Claude 特定位置的天氣。160這些程式碼片段重複使用[天氣工具範例](#weather-tool-example)中的 `weatherServer` 來詢問 Claude 特定位置的天氣。

158 161

329| :- | :- | :- |332| :- | :- | :- |

334 337

335註釋是中繼資料，不是強制執行。標記為 `readOnlyHint: true` 的工具如果處理程式執行該操作，仍然可以寫入磁碟。保持註釋與處理程式準確。338註釋是中繼資料，不是強制執行。標記為 `readOnlyHint: true` 的工具如果處理程式執行該操作，仍然可以寫入磁碟。保持註釋與處理程式準確。

336 339

373 376

374### 設定允許的工具377### 設定允許的工具

375 378

376`tools` 選項和允許/不允許清單會影響兩個層級：可用性（控制工具是否出現在 Claude 的上下文中）和權限（控制 Claude 嘗試呼叫後是否獲得批准）。`tools` 和裸名稱 `disallowedTools` 項目會變更可用性。`allowedTools` 和限定範圍的 `disallowedTools` 規則會變更權限。如果您在 `allowedTools` 中命名其中一個[任務追蹤工具](https://code.claude.com/docs/zh-TW/agent-sdk/todo-tracking.md#model-availability)，Claude Code 也會為該工作階段啟用這些工具。379您可以透過 `tools`、`allowedTools` 和 `disallowedTools` 選項控制兩個層級：

380

381* **可用性**：工具是否出現在 Claude 的上下文中。若要變更，請使用 `tools` 選項，或在 `disallowedTools` 中列出裸內建名稱，例如 `"Bash"`。

382* **權限**：當 Claude 發出呼叫時，Claude Code 是否核准該呼叫。若要變更，請使用 `allowedTools` 或限定範圍的 `disallowedTools` 規則，例如 `"Bash(rm *)"`。

377 383

378| 選項 | 層級 | 效果 |384| 選項 | 層級 | 效果 |

379| :- | :- | :- |385| :- | :- | :- |

380| `tools: ["Read", "Grep"]` | 可用性 | 只有列出的內建工具在 Claude 的上下文中。未列出的內建工具會被移除。MCP 工具不受影響。 |386| `tools: ["Read", "Grep"]` | 可用性 | 只有列出的內建工具在 Claude 的上下文中。未列出的內建工具會被移除。MCP 工具不受影響。 |

381| `tools: []` | 可用性 | 所有內建工具都會被移除。Claude 只能使用您的 MCP 工具。 |387| `tools: []` | 可用性 | 所有內建工具都會被移除。Claude 只能使用您的 MCP 工具。 |

382| 允許的工具 | 權限 | 列出的工具無需權限提示即可執行。其他未列出的工具仍然可用；呼叫會通過[權限流程](https://code.claude.com/docs/zh-TW/agent-sdk/permissions.md)。 |388| 允許的工具 | 權限 | 列出的工具會預先核准，但[任何允許規則都不會核准的呼叫](https://code.claude.com/docs/zh-TW/agent-sdk/permissions.md#calls-an-allow-rule-never-approves)除外。對未列入清單之工具的呼叫會通過[權限流程](https://code.claude.com/docs/zh-TW/agent-sdk/permissions.md)。 |

383| 不允許的工具 | 兩者 | 裸工具名稱（例如 `"Bash"`）會從 Claude 的上下文中移除工具，與從 `tools` 中省略它的效果相同。限定範圍的規則（例如 `"Bash(rm *)"`）會將工具保留在上下文中，並僅拒絕與[如所寫](https://code.claude.com/docs/zh-TW/permissions.md#bash-rule-limits)相符的呼叫。 |389| 不允許的工具 | 兩者 | 裸內建名稱（例如 `"Bash"`）會從 Claude 的上下文中移除該工具。限定範圍的規則（例如 `"Bash(rm *)"`）會將工具保留在上下文中，並拒絕與規則[如所寫](https://code.claude.com/docs/zh-TW/permissions.md#bash-rule-limits)相符的呼叫。 |

384 390

385若要完全移除內建工具，請從 `tools` 中省略它或在 `disallowedTools` 中列出其裸名稱（Python：`disallowed_tools`）；兩者都會將工具保留在上下文之外，以便 Claude 永遠不會嘗試它。限定範圍的 `disallowedTools` 規則會阻止相符的呼叫，但將工具保留為可見，因此 Claude 可能會浪費一個回合嘗試它。如需完整的評估順序，請參閱[設定權限](https://code.claude.com/docs/zh-TW/agent-sdk/permissions.md)。391若要從 Claude 的上下文中移除內建工具，請從 `tools` 中省略它，或在 `disallowedTools`（TypeScript）或 `disallowed_tools`（Python）中列出其裸名稱。如需完整的評估順序，請參閱[設定權限](https://code.claude.com/docs/zh-TW/agent-sdk/permissions.md#how-permissions-are-evaluated)。

386 392

387### 要求特定工具的核准393### 要求特定工具的核准

388 394

637 643

638## 返回結構化資料644## 返回結構化資料

639 645

640`structuredContent` 是結果上的選用 JSON 物件，與 `content` 陣列分開。使用它來返回原始值，Claude 可以將其讀取為確切的欄位，而不是從文字字串或影像中解析它們。646`structuredContent` 是結果上的選用 JSON 物件，與 `content` 陣列分開。使用它來返回原始值，Claude 可以將其讀取為確切的欄位，而不是從文字字串或影像中解析它們。若為 Python 處理程式，請參閱 [Python 中的結構化內容](#structured-content-in-python)。

641 647

642當設定 `structuredContent` 時，Claude 會收到 JSON 加上來自 `content` 的任何影像或資源區塊。`content` 中的文字區塊不會被轉發，因為假設它們會複製結構化資料。下面的範例將圖表呈現為影像區塊，並從同一個處理程式的 `structuredContent` 中返回其背後的資料點。在程式碼片段中，`chartPngBuffer` 是一個包含已呈現 PNG 位元組的 `Buffer`。648當 TypeScript `tool()` 處理程式設定 `structuredContent` 時，Claude 會收到 JSON 加上 `content` 中的影像和資源區塊，而 `content` 中的文字區塊不會傳送給 Claude。下面的範例將圖表呈現為影像區塊，並從同一個處理程式的 `structuredContent` 中返回其背後的資料點。在程式碼片段中，`chartPngBuffer` 是一個包含已呈現 PNG 位元組的 `Buffer`。

643 649

644```typescript TypeScript theme={null}650```typescript TypeScript theme={null}

645return {651return {

agent-sdk/mcp.md +1 −1

Details

205 205

206### 使用 allowedTools 自動批准206### 使用 allowedTools 自動批准

207 207

208使用 `allowedTools` 自動批准特定的 MCP 工具，讓 Claude 可以在不需要許可權提示的情況下使用它們：208使用 `allowedTools` 自動批准特定的 MCP 工具：

209 209

210```typescript TypeScript hidelines={1,-1} theme={null}210```typescript TypeScript hidelines={1,-1} theme={null}

211const _ = {211const _ = {

agent-sdk/permissions.md +5 −5

Details

18 18

19**1. Hooks**19**1. Hooks**

20 20

21執行 [hook](https://code.claude.com/docs/zh-TW/agent-sdk/hooks.md)。hook 可以直接拒絕該呼叫，或將其傳遞下去。傳回 `allow` 的 hook 不會略過下方的拒絕和詢問規則，無論 hook 結果為何，這些規則都會被評估。21執行 [hook](https://code.claude.com/docs/zh-TW/agent-sdk/hooks.md)。hook 可以直接拒絕該呼叫，或將其傳遞下去。傳回 `allow` 的 hook 不會略過拒絕規則和詢問規則步驟，無論 hook 結果為何，這些步驟都會被評估。

22 22

23返回 `allow` 的 `PreToolUse` hook 也無法核准目標被 Claude Code 識別為[關鍵路徑](https://code.claude.com/docs/zh-TW/permission-modes.md#critical-paths)的 `rm` 或 `rmdir` 命令，例如 `rm -rf ~`。關於該 `allow` 在 plan mode 中的作用，請參閱 [plan mode 中的 hook 核准](https://code.claude.com/docs/zh-TW/permissions.md#hook-approvals-in-plan-mode)。23返回 `allow` 的 `PreToolUse` hook 也無法核准目標被 Claude Code 識別為[關鍵路徑](https://code.claude.com/docs/zh-TW/permission-modes.md#critical-paths)的 `rm` 或 `rmdir` 命令，例如 `rm -rf ~`。關於該 `allow` 在 plan mode 中的作用，請參閱 [plan mode 中的 hook 核准](https://code.claude.com/docs/zh-TW/permissions.md#hook-approvals-in-plan-mode)。

24 24

58 58

59**6. canUseTool 回呼**59**6. canUseTool 回呼**

60 60

61如果上述任何步驟都未解決，請呼叫您的 [`canUseTool` 回呼](https://code.claude.com/docs/zh-TW/agent-sdk/user-input) 以獲得決定。在 `dontAsk` 模式下，此步驟會被跳過，工具會被拒絕，不過您安裝的 [mod](https://code.claude.com/docs/zh-TW/plugins/mods/overview.md) 仍可核准[部分此類呼叫](https://code.claude.com/docs/zh-TW/permissions.md#precedence-among-rules-hooks-and-mods)。61如果先前的步驟都未解決該請求，請呼叫您的 [`canUseTool` 回呼](https://code.claude.com/docs/zh-TW/agent-sdk/user-input) 以獲得決定。在 `dontAsk` 模式下，此步驟會被跳過，工具會被拒絕，不過您安裝的 [mod](https://code.claude.com/docs/zh-TW/plugins/mods/overview.md) 仍可核准[部分此類呼叫](https://code.claude.com/docs/zh-TW/permissions.md#precedence-among-rules-hooks-and-mods)。

62 62

63在 TypeScript SDK 中，如果您設定了 [`permissionPrompts: 'none'`](https://code.claude.com/docs/zh-TW/agent-sdk/typescript#options)，您的回呼在此步驟不會被呼叫。[`PermissionRequest` hook](https://code.claude.com/docs/zh-TW/hooks#permissionrequest) 仍然有機會決定，如果它不決定，Claude Code 會拒絕呼叫。此選項需要 Claude Code v2.1.259 或更新版本。63在 TypeScript SDK 中，如果您設定了 [`permissionPrompts: 'none'`](https://code.claude.com/docs/zh-TW/agent-sdk/typescript#options)，您的回呼在此步驟不會被呼叫。[`PermissionRequest` hook](https://code.claude.com/docs/zh-TW/hooks#permissionrequest) 仍然有機會決定，如果它不決定，Claude Code 會拒絕呼叫。此選項需要 Claude Code v2.1.259 或更新版本。

64 64

80 80

81## 允許和拒絕規則81## 允許和拒絕規則

82 82

83`allowed_tools` 和 `disallowed_tools`（TypeScript：`allowedTools` / `disallowedTools`）在上述評估流程中新增允許和拒絕規則清單的項目。如果您在 `allowed_tools` 中命名其中一個[任務追蹤工具](https://code.claude.com/docs/zh-TW/agent-sdk/todo-tracking.md#model-availability)，Claude Code 也會為該工作階段啟用這些工具。任何未列在 `allowed_tools` 中的其他工具仍可供 Claude 使用，對其進行的需要批准的呼叫會進入權限模式。拒絕規則的行為取決於它們是命名工具還是在工具內限定模式。83當您設定 `allowedTools` 和 `disallowedTools`（TypeScript）或 `allowed_tools` 和 `disallowed_tools`（Python）時，Claude Code 會將其項目新增到[權限評估流程](#how-permissions-are-evaluated)中的允許和拒絕規則清單。任何未列在 `allowed_tools` 中的其他工具仍可供 Claude 使用，對其進行的需要核准的呼叫會進入權限模式。

84 84

85| 選項 | 效果 |85| 選項 | 效果 |

86| :- | :- |86| :- | :- |

87| `allowed_tools=["Read", "Grep"]` | `Read` 和 `Grep` 會自動核准，但[從網路路徑讀取](https://code.claude.com/docs/zh-TW/permissions.md#network-paths)除外。此處未列出的其他工具仍然存在，對它們進行的需要核准的呼叫會進入權限模式和 `canUseTool`。 |87| `allowed_tools=["Read", "Grep"]` | `Read` 和 `Grep` 會自動核准，但[從網路路徑讀取](https://code.claude.com/docs/zh-TW/permissions.md#network-paths)除外。此處未列出的其他工具仍然存在，對它們進行的需要核准的呼叫會進入權限模式和 `canUseTool`。 |

89| `disallowed_tools=["Bash(rm *)"]` | `Bash` 保持可用。符合 `rm *` [如所寫](https://code.claude.com/docs/zh-TW/permissions.md#bash-rule-limits)的呼叫在每個權限模式中都會被拒絕，包括 `bypassPermissions`。其他 `Bash` 呼叫（包括 `/bin/rm`）會進入權限模式。 |89| `disallowed_tools=["Bash(rm *)"]` | `Bash` 保持可用。符合 `rm *` [如所寫](https://code.claude.com/docs/zh-TW/permissions.md#bash-rule-limits)的呼叫在每個權限模式中都會被拒絕，包括 `bypassPermissions`。其他 `Bash` 呼叫（包括 `/bin/rm`）會進入權限模式。 |

91 91

92允許規則僅在字面 `mcp__<server>__` 前綴之後接受工具名稱萬用字元。伺服器段必須無萬用字元，以便規則命名您設定的特定伺服器：`mcp__puppeteer__*` 符合來自 `puppeteer` 伺服器的每個工具，`mcp__github__get_*` 符合其 `get_` 工具。未錨定的項目（如 `allowed_tools=["*"]` 或 `allowed_tools=["mcp__*"]`）會被忽略，不會自動核准任何內容。92允許規則僅在字面 `mcp__<server>__` 前綴之後接受工具名稱萬用字元。伺服器段必須無萬用字元，以便規則命名您設定的特定伺服器：`mcp__puppeteer__*` 符合來自 `puppeteer` 伺服器的每個工具，`mcp__github__get_*` 符合其 `get_` 工具。未錨定的項目（如 `allowed_tools=["*"]` 或 `allowed_tools=["mcp__*"]`）會被忽略，不會自動核准任何內容。

93 93

agent-sdk/python.md +1 −1

Details

2787 2787

2788執行背景來源並將每個事件傳遞給 Claude，以便它可以做出反應而無需輪詢：`command` 執行指令碼並每個 stdout 行發出一個事件，`ws` 開啟 WebSocket 並每個文字框架發出一個事件。提供 `command` 或 `ws` 中的恰好一個。2788執行背景來源並將每個事件傳遞給 Claude，以便它可以做出反應而無需輪詢：`command` 執行指令碼並每個 stdout 行發出一個事件，`ws` 開啟 WebSocket 並每個文字框架發出一個事件。提供 `command` 或 `ws` 中的恰好一個。

2789 2789

2790當 Monitor 執行命令時，它遵循與 Bash 相同的權限規則；WebSocket 監視會單獨提示核准。`ws` 來源需要 Claude Code v2.1.195 或更新版本。有關行為和提供者可用性，請參閱 [Monitor 工具參考](https://code.claude.com/docs/zh-TW/tools-reference.md#monitor-tool)。2790`ws` 來源需要 Claude Code v2.1.195 或更新版本。當 Monitor 執行命令時，它遵循與 Bash 相同的權限規則。有關 WebSocket 權限、行為和提供者可用性，請參閱 [Monitor 工具參考](https://code.claude.com/docs/zh-TW/tools-reference.md#monitor-tool)。

2791 2791

2792**輸入：**2792**輸入：**

2793 2793

agent-sdk/typescript.md +5 −3

Details

3388 3388

3389執行背景來源並將每個事件傳遞給 Claude，使其可以做出反應而無需輪詢：`command` 執行指令碼並每行 stdout 發出一個事件，`ws` 開啟 WebSocket 並每個文字框架發出一個事件。恰好提供 `command` 或 `ws` 其中之一。`ws` 來源需要 Claude Code v2.1.195 或更新版本。3389執行背景來源並將每個事件傳遞給 Claude，使其可以做出反應而無需輪詢：`command` 執行指令碼並每行 stdout 發出一個事件，`ws` 開啟 WebSocket 並每個文字框架發出一個事件。恰好提供 `command` 或 `ws` 其中之一。`ws` 來源需要 Claude Code v2.1.195 或更新版本。

3390 3390

3391`timeout_ms` 是監視的截止時間（毫秒）。預設為 300000，接受最多 3600000 的值。有效截止時間最多為 1800000，即 30 分鐘，因此較大的接受值會縮短至該值。在截止時間時監視結束，Claude 收到一個通知，以便在仍需要時啟動新監視。3391`timeout_ms` 是監視的截止時間（毫秒）：

3392 3392

3393匯出的類型將 `timeout_ms` 標記為必需，因為 schema 會填入預設值；省略它的呼叫會驗證通過。3393* **預設值與限制**：預設為 300000，接受最多 3600000 的值。有效截止時間最多為 1800000，即 30 分鐘，因此較大的接受值會縮短至該值

3394* **到達截止時間時**：監視結束，Claude 收到一個通知，以便在仍需要時啟動新監視

3395* **類型中標記為必需**：匯出的類型將 `timeout_ms` 標記為必需，因為 schema 會填入預設值；省略它的呼叫會驗證通過

3394 3396

3395當 Monitor 執行命令時，它遵循與 Bash 相同的權限規則；WebSocket 監視會單獨提示核准。詳見[Monitor 工具參考](https://code.claude.com/docs/zh-TW/tools-reference.md#monitor-tool)以了解行為和提供者可用性。3397當 Monitor 執行命令時，它遵循與 Bash 相同的權限規則。詳見[Monitor 工具參考](https://code.claude.com/docs/zh-TW/tools-reference.md#monitor-tool)以了解 WebSocket 權限、行為和提供者可用性。

3396 3398

3397### TaskOutput3399### TaskOutput

3398 3400

best-practices.md +2 −2

Details

433 433

434### 變更模型和 effort434### 變更模型和 effort

435 435

436[Effort](https://code.claude.com/docs/zh-TW/model-config.md#adjust-effort-level) 是控制 Claude 思考時間長短的主要方式，它取代了過去人們透過提示詞措辭所做的大部分事情。Claude Opus 5.5、Sonnet 5.5 和 Haiku 5.5 預設為 `medium`，這對於範圍明確的日常功能開發已經綽綽有餘。您會需要在工作階段中以 `/effort` 調整它的時機：436[Effort](https://code.claude.com/docs/zh-TW/model-config.md#adjust-effort-level) 是控制 Claude 思考時間長短的主要方式，它取代了過去人們透過提示詞措辭所做的大部分事情。Claude Fable 5.2、Opus 5.5、Sonnet 5.5 和 Haiku 5.5 預設為 `medium`，這對於範圍明確的日常功能開發已經綽綽有餘。您會需要在工作階段中以 `/effort` 調整它的時機：

437 437

438* 當做對與否取決於容易被忽略的情況時，用 `/effort high` 或 `/effort xhigh` 調高它。例如您沒寫過的程式碼中的錯誤、不穩定的測試，或是 Claude 必須找出舊結構所有讀取者的 schema 變更。這樣 Claude 會在回答之前檢查更多邊界情況並驗證更多工作，額外的時間和 token 就花在這裡。438* 當做對與否取決於容易被忽略的情況時，用 `/effort high` 或 `/effort xhigh` 調高它。例如您沒寫過的程式碼中的錯誤、不穩定的測試，或是 Claude 必須找出舊結構所有讀取者的 schema 變更。這樣 Claude 會在回答之前檢查更多邊界情況並驗證更多工作，額外的時間和 token 就花在這裡。

439* 當您正在快速來回互動且無論如何都會審查每個結果時，用 `/effort low` 調低它：腦力激盪、初步草稿、跨幾個檔案的重新命名。Claude 會更快給您一個起點，而既然您在每一步都會引導，額外的深思熟慮除了讓您等待更久之外，不會有太大改變。439* 當您正在快速來回互動且無論如何都會審查每個結果時，用 `/effort low` 調低它：腦力激盪、初步草稿、跨幾個檔案的重新命名。Claude 會更快給您一個起點，而既然您在每一步都會引導，額外的深思熟慮除了讓您等待更久之外，不會有太大改變。

440* 將 `max` 留給您希望 Claude 在沒有您的情況下努力解決的困難問題，例如尋找安全漏洞。在一般任務上它容易想太多，所以您會付出更多，得到的答案卻可能不比 `high` 更好。440* 將 `max` 留給您希望 Claude 在沒有您的情況下努力解決的困難問題，例如尋找安全漏洞。在一般任務上它容易想太多，所以您會付出更多，得到的答案卻可能不比 `high` 更好。

441* 當只有下一則訊息需要時，例如在原本例行的工作中穿插一個棘手的問題，請在該提示詞中加入 [`ultrathink`](https://code.claude.com/docs/zh-TW/model-config#use-ultrathink-for-one-off-deep-reasoning)，而不是變更設定。441* 當只有下一則訊息需要時，例如在原本例行的工作中穿插一個棘手的問題，請在該提示詞中加入 [`ultrathink`](https://code.claude.com/docs/zh-TW/model-config#use-ultrathink-for-one-off-deep-reasoning)，而不是變更設定。

442 442

443至於模型本身，預設的 Opus 5.5 能妥善處理大多數程式撰寫工作，而 Sonnet 在例行工作上成本較低。[Claude Fable 5.1](https://code.claude.com/docs/zh-TW/model-config.md#work-with-fable) 需要您以 `/model fable` 明確選取，而 Haiku 很適合做簡單工作的 subagent。[模型設定](https://code.claude.com/docs/zh-TW/model-config.md)列出了各方案和供應商的完整清單。443至於模型本身，預設的 Opus 5.5 能妥善處理大多數程式撰寫工作，而 Sonnet 在例行工作上成本較低。若要使用 [Claude Fable 5.2](https://code.claude.com/docs/zh-TW/model-config.md#work-with-fable)，請執行 `/model fable`。Haiku 很適合做簡單工作的 subagent。[模型設定](https://code.claude.com/docs/zh-TW/model-config.md)列出了各方案和供應商的完整清單。

444 444

445### 了解 subagent 的成本445### 了解 subagent 的成本

446 446

claude-apps-gateway.md +1 −1

Details

172 172

173成功開機並不代表推論路徑已通過驗證，因為 Amazon Bedrock 與 Google Cloud 的 Agent Platform 執行個體憑證是在第一個請求時解析，而非在開機時。173成功開機並不代表推論路徑已通過驗證，因為 Amazon Bedrock 與 Google Cloud 的 Agent Platform 執行個體憑證是在第一個請求時解析，而非在開機時。

174 174

175請觀察 stderr 中的開機順序。日誌行使用 `[gateway] <timestamp> <level> <message>` 格式，稽核事件為帶有 `evt` 欄位的單行 JSON，而啟動橫幅（以下省略）會印在遷移行與接聽行之間。全新的資料庫會為每個 schema 遷移印出一行 `migration N applied`；已完成遷移的資料庫則不會印出。您應該會依序看到：175請觀察 stderr 中的開機順序。根據預設，日誌行使用 `[gateway] <timestamp> <level> <message>` 格式，而啟動橫幅（以下省略）會印在遷移行與接聽行之間。稽核事件為帶有 `evt` 欄位的單行 JSON。全新的資料庫會為每個 schema 遷移印出一行 `migration N applied`；已完成遷移的資料庫則不會印出。您應該會依序看到：

176 176

177```text theme={null}177```text theme={null}

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

claude-apps-gateway-config.md +43 −5

Details

26 26

27**選擇性部分：**27**選擇性部分：**

28 28

29* [`login_notice`](#login_notice)：開發人員登入時看到的通知

29* [`admin`](#admin)：Admin API 驗證和支出限制的保留期30* [`admin`](#admin)：Admin API 驗證和支出限制的保留期

30* [`enforcement`](#enforcement)：支出限制失敗開放或失敗關閉行為31* [`enforcement`](#enforcement)：支出限制失敗開放或失敗關閉行為

31* [`pricing`](#pricing)：合約費率以及支出計量和開發人員看到的成本數字的乘數32* [`pricing`](#pricing)：合約費率以及支出計量和開發人員看到的成本數字的乘數

845 846

846## 選用區段847## 選用區段

847 848

849### `login_notice`

850

851若要在開發人員登入時向其顯示通知，請將頂層 `login_notice` 鍵設為通知文字，最多 500 個字元。此範例說明閘道的適用對象，以及可在何處詢問存取權限：

852

853```yaml theme={null}

854login_notice: This gateway is for Example Corp staff. For access questions, email it-help@example.com.

855```

856

857開發人員會在瀏覽器中閘道的驗證頁面上，以及終端機中的互動式登入畫面上，於 `Notice from <gateway hostname>` 下方看到此文字。文字中的換行會變成空格。通知在登入前顯示，因此任何能連線到閘道的人都能讀取。

858

859閘道伺服器上需要 Claude Code v2.1.319 或更新版本；若要在終端機畫面顯示，開發人員的電腦上也需要此版本。較舊的閘道發現此鍵時會拒絕啟動。請在加入此鍵之前升級每個副本，並在回復版本之前移除此鍵。

860

848### `admin`861### `admin`

849 862

850選用。啟用 `/v1/organizations/spend_limits`，其鏡像 Anthropic 的公開 Admin API，以及在 `/v1/messages` 上的每位開發者支出強制執行。請參閱[支出限制](https://code.claude.com/docs/zh-TW/claude-apps-gateway-spend-limits.md)以了解如何設定和強制執行上限；本節涵蓋啟用該功能並調整它的 `gateway.yaml` 金鑰。863選用。啟用 `/v1/organizations/spend_limits`，其鏡像 Anthropic 的公開 Admin API，以及在 `/v1/messages` 上的每位開發者支出強制執行。請參閱[支出限制](https://code.claude.com/docs/zh-TW/claude-apps-gateway-spend-limits.md)以了解如何設定和強制執行上限；本節涵蓋啟用該功能並調整它的 `gateway.yaml` 金鑰。

851 864

852```yaml theme={null}865```yaml theme={null}

853admin:866admin:

854 # 用於 admin 端點的具名靜態 API 金鑰，以 x-api-key 形式傳送。867 # Named static API keys for the admin endpoints, sent as x-api-key.

855 # id 在稽核日誌中顯示為 admin-key:<id>，因此每個金鑰都868 # The id appears in the audit log as admin-key:<id> so each key is

856 # 可追蹤。陣列用於輪換：新增新金鑰、滾動用戶端、869 # attributable. Array for rotation: add the new key, roll clients,

857 # 移除舊金鑰。870 # remove the old.

858 write_keys:871 write_keys:

859 - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }872 - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }

860 - { id: ci, key: "${GATEWAY_ADMIN_WRITE_KEY_CI}" }873 - { id: ci, key: "${GATEWAY_ADMIN_WRITE_KEY_CI}" }

861 read_keys:874 read_keys:

862 - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }875 - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }

863 # 透過一般 gateway JWT（無 API 金鑰）授予完整 admin 的 IdP 群組。876 # IdP groups granted full admin via the normal gateway JWT (no API key).

864 admin_groups: [platform-finops]877 admin_groups: [platform-finops]

865 blocked_message: request an increase at https://go.example.com/claude-limits878 blocked_message: request an increase at https://go.example.com/claude-limits

879 # Try eng-platform's pooled budget first, then eng-all's, then any other group's.

880 pooled_conflict_rule: priority_list

881 pooled_priority_order: [eng-platform, eng-all]

866```882```

867 883

868| 欄位 | 必需 | 說明 |884| 欄位 | 必需 | 說明 |

875| `spend_retention_months` | 否 | 預設 `13`。早於此時間的 `spend` 計數器列會被清除。預設值保留完整年份加上當月部分月份，用於年度比較報告。 |891| `spend_retention_months` | 否 | 預設 `13`。早於此時間的 `spend` 計數器列會被清除。預設值保留完整年份加上當月部分月份，用於年度比較報告。 |

876| `identity_retention_days` | 否 | 預設 `90`。`principal_emails` 列的最後一次看到 TTL，其中保存每位開發者的電子郵件、顯示名稱和群組（PII）。刻意比支出保留期短，因此已取消佈建的身分會在其匿名支出計數器保留時過期。 |892| `identity_retention_days` | 否 | 預設 `90`。`principal_emails` 列的最後一次看到 TTL，其中保存每位開發者的電子郵件、顯示名稱和群組（PII）。刻意比支出保留期短，因此已取消佈建的身分會在其匿名支出計數器保留時過期。 |

877| `group_limit_mode` | 否 | `min`（預設）或 `max`。當開發者在多個具有上限的群組中時，`min` 強制執行最嚴格的，`max` 強制執行最寬鬆的。由強制執行和 `/effective` 使用。 |893| `group_limit_mode` | 否 | `min`（預設）或 `max`。當開發者在多個具有上限的群組中時，`min` 強制執行最嚴格的，`max` 強制執行最寬鬆的。由強制執行和 `/effective` 使用。 |

894| `pooled_conflict_rule` | 否 | `default_order`（預設）或 `priority_list`。閘道嘗試開發人員共用預算的順序。請參閱[共用預算順序](#pooled-budget-order)。需要 v2.1.319 或更新版本。 |

895| `pooled_priority_order` | 使用 `priority_list` 時 | 最多 50 個群組名稱，每個只列出一次，且拼寫須與 IdP 傳送的一致。閘道會優先嘗試這些群組的共用預算。請參閱[共用預算順序](#pooled-budget-order)。需要 v2.1.319 或更新版本。 |

896

897#### 共用預算順序

898

899共用預算是整個群組共同支出的單一月度限制。若要設定，請在[設定群組月度上限的請求](https://code.claude.com/docs/zh-TW/claude-apps-gateway-spend-limits.md#set-a-cap)中加入 `pooled_budget`，例如以 `"pooled_budget": {"amount": "500000"}` 表示 \$5,000。此請求也需包含群組的 `scope`、`"period": "monthly"` 及 `amount`，而 `amount` 仍是每位成員各自的上限。

900

901對於屬於多個此類群組的開發人員，每個請求會計入第一個支出仍低於其限制的預算；當所有預算都用盡時，請求會被拒絕。`pooled_conflict_rule` 設定閘道嘗試預算的順序：

902

903* **`default_order`**：限制最大者優先，限制相同時依群組名稱遞增排序

904* **`priority_list`**：先依清單順序使用 `pooled_priority_order` 中群組的預算，再依群組名稱使用其他群組的預算

905

906若您列出群組但未設定 `pooled_conflict_rule: priority_list`，閘道會忽略該清單，並在啟動時記錄警告。

907

908早於 v2.1.319 的閘道伺服器發現 `pooled_conflict_rule` 或 `pooled_priority_order` 時會拒絕啟動。請在加入任一鍵之前升級每個副本，並在回復版本之前移除這兩個鍵。

878 909

879### `enforcement`910### `enforcement`

880 911

1674# 也會記錄每個 id_token 中的宣告名稱，用於 groups_claim 診斷。1705# 也會記錄每個 id_token 中的宣告名稱，用於 groups_claim 診斷。

1675# 它不影響稽核事件，始終發出。1706# 它不影響稽核事件，始終發出。

1707# 設定 CLAUDE_GATEWAY_LOG_FORMAT=json 以將操作日誌行寫為包含

1708# severity、time 和 message 的 JSON 物件。

1676 1709

1677listen:1710listen:

1678 host: 0.0.0.01711 host: 0.0.0.0

1713 # connect_timeout_seconds: 51746 # connect_timeout_seconds: 5

1714 # readiness_grace_seconds: 300 # 在資料庫容錯移轉期間保持通過整備檢查1747 # readiness_grace_seconds: 300 # 在資料庫容錯移轉期間保持通過整備檢查

1715 1748

1749# 登入時顯示的通知。任何能連線到閘道的人都可以閱讀它。

1750# login_notice: This gateway is for Example Corp staff. For access questions, email it-help@example.com.

1751

1716# 啟用 /v1/organizations/spend_limits（鏡像 Anthropic Admin API）1752# 啟用 /v1/organizations/spend_limits（鏡像 Anthropic Admin API）

1717# 和 /v1/messages 上的每個開發人員支出強制執行。省略以停用。1753# 和 /v1/messages 上的每個開發人員支出強制執行。省略以停用。

1718# 上限本身透過 admin API 設定，而不是此處。1754# 上限本身透過 admin API 設定，而不是此處。

1727# # spend_retention_months: 131763# # spend_retention_months: 13

1728# # identity_retention_days: 901764# # identity_retention_days: 90

1729# # group_limit_mode: min1765# # group_limit_mode: min

1766# # pooled_conflict_rule: priority_list

1767# # pooled_priority_order: [eng-platform, eng-all]

1730 1768

1731# enforcement:1769# enforcement:

1732# fail_closed_on_error: false1770# fail_closed_on_error: false

claude-apps-gateway-deploy.md +14 −0

Details

173 * `admin.denied` 記錄被拒絕的管理員 API 驗證嘗試，包含用戶端 IP、方法、路徑和原因，不包含呈現的金鑰資料：當呈現了 `x-api-key` 但未與任何已設定的金鑰相符時為 `invalid_key`，當僅呈現了 `Authorization` 標頭且其未驗證為 `admin.admin_groups` 中的閘道工作階段時為 `bearer_rejected`，或當兩個標頭都未呈現時為 `no_credentials`173 * `admin.denied` 記錄被拒絕的管理員 API 驗證嘗試，包含用戶端 IP、方法、路徑和原因，不包含呈現的金鑰資料：當呈現了 `x-api-key` 但未與任何已設定的金鑰相符時為 `invalid_key`，當僅呈現了 `Authorization` 標頭且其未驗證為 `admin.admin_groups` 中的閘道工作階段時為 `bearer_rejected`，或當兩個標頭都未呈現時為 `no_credentials`

174* **操作日誌**：人類可讀的 `[gateway]` 前綴行，用於啟動、警告和上游錯誤。`CLAUDE_GATEWAY_LOG_LEVEL` 環境變數控制詳細程度，接受 `debug`、`info`、`warn` 或 `error`，預設為 `info`。在 `debug` 時，每個登入和重新整理也會記錄 id\_token 中的宣告名稱（而非值），加上當 `userinfo_fallback` 提供任何時的 userinfo 宣告名稱，因此您可以診斷 `email_claim` 和 `groups_claim` 設定，而不記錄個人識別資訊。它不影響稽核事件，稽核事件始終被發出。174* **操作日誌**：人類可讀的 `[gateway]` 前綴行，用於啟動、警告和上游錯誤。`CLAUDE_GATEWAY_LOG_LEVEL` 環境變數控制詳細程度，接受 `debug`、`info`、`warn` 或 `error`，預設為 `info`。在 `debug` 時，每個登入和重新整理也會記錄 id\_token 中的宣告名稱（而非值），加上當 `userinfo_fallback` 提供任何時的 userinfo 宣告名稱，因此您可以診斷 `email_claim` 和 `groups_claim` 設定，而不記錄個人識別資訊。它不影響稽核事件，稽核事件始終被發出。

175 175

176#### 以 JSON 格式寫入操作日誌

177

178如果您的日誌收集器從 JSON 欄位讀取每一行的層級，請在閘道的環境中設定 `CLAUDE_GATEWAY_LOG_FORMAT=json`。需要閘道伺服器上的 Claude Code v2.1.319 或更新版本。

179

180之後每一行操作日誌都是一個包含 `severity`、`time` 和 `message` 的物件：

181

182```json theme={null}

183{"severity":"INFO","time":"2026-11-04T17:03:21.512Z","message":"claude gateway listening on http://0.0.0.0:8080"}

184```

185

186`severity` 是以大寫表示的日誌層級，其中 `warn` 寫為 `WARNING`。啟動失敗會產生一行 `ERROR`。

187

188同樣寫入 stderr 的稽核事件不會改變。它們攜帶 `ts` 和 `evt`，不含 `severity`。

189

176### 健康狀態190### 健康狀態

177 191

178閘道提供 `GET /healthz` 作為活躍性探測，`GET /readyz` 作為就緒性探測。`/readyz` 驗證存放區是否可到達。如果您設定了 [`store.readiness_grace_seconds`](https://code.claude.com/docs/zh-TW/claude-apps-gateway-config#store)，`/readyz` 在存放區停止應答後最多繼續報告就緒達該秒數。192閘道提供 `GET /healthz` 作為活躍性探測，`GET /readyz` 作為就緒性探測。`/readyz` 驗證存放區是否可到達。如果您設定了 [`store.readiness_grace_seconds`](https://code.claude.com/docs/zh-TW/claude-apps-gateway-config#store)，`/readyz` 在存放區停止應答後最多繼續報告就緒達該秒數。

claude-apps-gateway-spend-limits.md +11 −2

Details

6 6

7> 透過 Claude 應用程式閘道限制每位開發人員的每日、每週或每月支出。使用管理員 API 設定限制，閘道會在每個請求上即時執行這些限制。7> 透過 Claude 應用程式閘道限制每位開發人員的每日、每週或每月支出。使用管理員 API 設定限制，閘道會在每個請求上即時執行這些限制。

8 8

9支出限制會限制每位開發人員在指定的一天、一週或一個月內透過您的 [Claude 應用程式閘道](https://code.claude.com/docs/zh-TW/claude-apps-gateway) 可以花費的金額。當開發人員超過其限制時，閘道會在他們的下一個請求上返回 `429`，並在該期間重置或管理員提高限制之前阻止他們。使用支出限制為每位開發人員、群組或整個組織設定共享認證的上限。9支出限制會限制每位開發人員在指定的一天、一週或一個月內透過您的 [Claude 應用程式閘道](https://code.claude.com/docs/zh-TW/claude-apps-gateway) 可以花費的金額。當開發人員超過其上限時，閘道會對他們後續的請求返回 `429`，直到管理員提高上限為止；若上限高於 \$0，則直到上限重置為止。使用支出限制為每位開發人員、群組或整個組織在所有人共用的憑證上設定上限。

10 10

11根據預設，Claude 應用程式閘道會透過一個共享的上游認證轉發所有推論，因此您的提供商的帳單會將所有內容歸屬於該認證，而不是個別開發人員。在 Amazon Bedrock 上，[按開發人員的 AWS 成本歸屬](https://code.claude.com/docs/zh-TW/claude-apps-gateway-config.md#per-developer-aws-cost-attribution) 會改變這一點。沒有按開發人員的限制，一個失控的代理程式群隊可能會花費組織的整個承諾。支出限制是閘道在該共享帳單之上的按開發人員檢視和斷路器。11根據預設，Claude 應用程式閘道會透過一個共享的上游認證轉發所有推論，因此您的提供商的帳單會將所有內容歸屬於該認證，而不是個別開發人員。在 Amazon Bedrock 上，[按開發人員的 AWS 成本歸屬](https://code.claude.com/docs/zh-TW/claude-apps-gateway-config.md#per-developer-aws-cost-attribution) 會改變這一點。沒有按開發人員的限制，一個失控的代理程式群隊可能會花費組織的整個承諾。支出限制是閘道在該共享帳單之上的按開發人員檢視和斷路器。

12 12

51 51

52在每個 `/v1/messages` 請求上，閘道在一個 Postgres 查詢中查詢開發人員的上限和期間至今的支出。超過任何上限的開發人員會收到 `429`，其中 `error.type: billing_error` 和標頭 `x-should-retry: false`。52在每個 `/v1/messages` 請求上，閘道在一個 Postgres 查詢中查詢開發人員的上限和期間至今的支出。超過任何上限的開發人員會收到 `429`，其中 `error.type: billing_error` 和標頭 `x-should-retry: false`。

53 53

54訊息會命名期間和重設時間，例如 `spend limit reached (daily; resets 2026-08-08 00:00 UTC)`，後面跟著您的 [`admin.blocked_message`](https://code.claude.com/docs/zh-TW/claude-apps-gateway-config#admin)（如果已設定）。當開發人員同時超過多個上限時，訊息會命名最後重設的上限。回應也會攜帶 `retry-after` 標頭，其中包含距離該重設的剩餘秒數。在閘道伺服器上的 v2.1.225 之前，訊息是 `spend limit reached`，沒有期間、重設時間或 `retry-after` 標頭。54對於高於 `"0"` 的上限，訊息會提供該上限重設的 UTC 日期。如果您設定了 [`admin.blocked_message`](https://code.claude.com/docs/zh-TW/claude-apps-gateway-config#admin)，閘道會將其附加在後面，如下例所示：

56```text theme={null}

57spend limit reached · resets Dec 1 · request an increase at https://go.example.com/claude-limits

58```

60對於 `"0"` 上限，由於重設不會解除它，訊息不含日期。當開發人員同時超過多個上限時，訊息會描述最後重設的上限。回應也會攜帶 `retry-after` 標頭，其中包含距離該上限期間結束的剩餘秒數。

62在閘道伺服器上的 v2.1.319 之前，訊息會命名期間和重設時間，例如 `spend limit reached (daily; resets 2026-08-08 00:00 UTC)`。在 v2.1.225 之前，訊息是 `spend limit reached`，沒有期間、重設時間或 `retry-after` 標頭。

55 63

56在 v2.1.227 或更新版本上，`<public_url>/protocol` 的協議參考也會列出確切的使用量限制回應標頭和 `429` 本文。64在 v2.1.227 或更新版本上，`<public_url>/protocol` 的協議參考也會列出確切的使用量限制回應標頭和 `429` 本文。

57 65

106| 在具有 [`admin:`](https://code.claude.com/docs/zh-TW/claude-apps-gateway-config#admin) 區塊的閘道上，當沒有上限適用於開發人員時，`/usage` 中 **Spend (UTC)** 下的估計支出，例如「\$13.06 today · \$80.76 this week · \$272.06 this month」 | v2.1.319 或更新版本 | v2.1.319 或更新版本 |

98 107

99警告和百分比來自 `anthropic-ratelimit-unified-*` 標頭，閘道會將這些標頭新增到具有上限的開發人員的每個成功 `/v1/messages` 回應中。標頭始終描述開發人員自己的上限：閘道會移除上游提供商的速率限制標頭（描述您的共享配額），並永遠不會轉發它們。108警告和百分比來自 `anthropic-ratelimit-unified-*` 標頭，閘道會將這些標頭新增到具有上限的開發人員的每個成功 `/v1/messages` 回應中。標頭始終描述開發人員自己的上限：閘道會移除上游提供商的速率限制標頭（描述您的共享配額），並永遠不會轉發它們。

100 109

cli-reference.md +2 −2

Details

42| `claude plugin` | 管理 Claude Code [外掛](https://code.claude.com/docs/zh-TW/plugins/overview.md)。別名：`claude plugins`。請參閱 [外掛參考](https://code.claude.com/docs/zh-TW/plugins/cli-reference.md#claude-plugin-commands) 以取得子命令 | `claude plugin install code-review@claude-plugins-official` |42| `claude plugin` | 管理 Claude Code [外掛](https://code.claude.com/docs/zh-TW/plugins/overview.md)。別名：`claude plugins`。請參閱 [外掛參考](https://code.claude.com/docs/zh-TW/plugins/cli-reference.md#claude-plugin-commands) 以取得子命令 | `claude plugin install code-review@claude-plugins-official` |

43| `claude purge [path]` | 刪除專案的所有本機 Claude Code 狀態：逐字稿、工作清單、偵錯日誌、檔案編輯歷史記錄、提示詞歷史記錄行和專案在 `~/.claude.json` 中的項目。省略 `[path]` 以從互動式清單中選擇。旗標：`--dry-run` 以預覽，`-y`/`--yes` 以跳過確認，`-i`/`--interactive` 以確認每個項目，`--all` 用於每個專案。請參閱 [清除本機資料](https://code.claude.com/docs/zh-TW/claude-directory.md#clear-local-data) | `claude purge ~/work/repo --dry-run` |43| `claude purge [path]` | 刪除專案的所有本機 Claude Code 狀態：逐字稿、工作清單、偵錯日誌、檔案編輯歷史記錄、提示詞歷史記錄行和專案在 `~/.claude.json` 中的項目。省略 `[path]` 以從互動式清單中選擇。旗標：`--dry-run` 以預覽，`-y`/`--yes` 以跳過確認，`-i`/`--interactive` 以確認每個項目，`--all` 用於每個專案。請參閱 [清除本機資料](https://code.claude.com/docs/zh-TW/claude-directory.md#clear-local-data) | `claude purge ~/work/repo --dry-run` |

44| `claude remote-control` | 啟動 [Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md) 伺服器以從 Claude.ai 或 Claude 應用程式控制 Claude Code。以伺服器模式執行（無本機互動式工作階段）。請參閱 [伺服器模式旗標](https://code.claude.com/docs/zh-TW/remote-control.md#start-a-remote-control-session)。停止伺服器後，您可以恢復它正在服務的工作階段。請參閱 [停止伺服器後繼續工作階段](https://code.claude.com/docs/zh-TW/remote-control.md#resume-sessions-after-stopping-the-server) | `claude remote-control --name "My Project"` |44| `claude remote-control` | 啟動 [Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md) 伺服器以從 Claude.ai 或 Claude 應用程式控制 Claude Code。別名：`claude rc`。以伺服器模式執行（無本機互動式工作階段）。請參閱 [伺服器模式旗標](https://code.claude.com/docs/zh-TW/remote-control.md#start-a-remote-control-session)。停止伺服器後，您可以恢復它正在服務的工作階段。請參閱 [停止伺服器後繼續工作階段](https://code.claude.com/docs/zh-TW/remote-control.md#resume-sessions-after-stopping-the-server) | `claude remote-control --name "My Project"` |

45| `claude respawn <id>` | 重新啟動 [背景工作階段](https://code.claude.com/docs/zh-TW/agent-view.md#manage-sessions-from-the-shell)（執行中或已停止），保持其對話完整。使用 `--all` 重新啟動每個執行中的工作階段，例如以取得更新的 Claude Code 二進位檔 | `claude respawn 7c5dcf5d` |45| `claude respawn <id>` | 重新啟動 [背景工作階段](https://code.claude.com/docs/zh-TW/agent-view.md#manage-sessions-from-the-shell)（執行中或已停止），保持其對話完整。使用 `--all` 重新啟動每個執行中的工作階段，例如以取得更新的 Claude Code 二進位檔 | `claude respawn 7c5dcf5d` |

46| `claude rm <id>` | 從清單中移除 [背景工作階段](https://code.claude.com/docs/zh-TW/agent-view.md#manage-sessions-from-the-shell)。當移除因工作階段的 worktree [而被拒絕](https://code.claude.com/docs/zh-TW/agent-view.md#what-deleting-a-session-removes) 且第二個 `claude rm` 可以解決時，拒絕會列印要傳遞的確切旗標和值：`--discard-unpushed <commit>@<worktree-id>` 會捨棄具有未推送提交的 worktree 以及這些提交，`--force-remove-worktree <worktree-id>` 刪除 git 或 `WorktreeRemove` hook 無法移除的 worktree 目錄。`--discard-unpushed` 需要 Claude Code v2.1.260 或更新版本，而 `--force-remove-worktree` 需要 v2.1.268 或更新版本。對話逐字稿保留在您的本機機器上，可透過 `claude --resume` 取得 | `claude rm 7c5dcf5d` |46| `claude rm <id>` | 從清單中移除 [背景工作階段](https://code.claude.com/docs/zh-TW/agent-view.md#manage-sessions-from-the-shell)。當移除因工作階段的 worktree [而被拒絕](https://code.claude.com/docs/zh-TW/agent-view.md#what-deleting-a-session-removes) 且第二個 `claude rm` 可以解決時，拒絕會列印要傳遞的確切旗標和值：`--discard-unpushed <commit>@<worktree-id>` 會捨棄具有未推送提交的 worktree 以及這些提交，`--force-remove-worktree <worktree-id>` 刪除 git 或 `WorktreeRemove` hook 無法移除的 worktree 目錄。`--discard-unpushed` 需要 Claude Code v2.1.260 或更新版本，而 `--force-remove-worktree` 需要 v2.1.268 或更新版本。對話逐字稿保留在您的本機機器上，可透過 `claude --resume` 取得 | `claude rm 7c5dcf5d` |

47| `claude self-hosted-runner` | 啟動執行程序，將此機器或容器註冊到 [自託管環境](https://code.claude.com/docs/zh-TW/self-hosted-environments) 並在您的基礎結構上託管 Claude Code 雲端工作階段。執行 `claude self-hosted-runner setup` 以進行引導式操作員逐步解說，`claude self-hosted-runner doctor` 以 [診斷已部署的執行程序](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#troubleshooting)，以及 `claude self-hosted-runner orchestrator` 以生成 [隨需執行程序](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration.md#on-demand-runners)。需要 Claude Code v2.1.224 或更新版本 | `claude self-hosted-runner setup` |47| `claude self-hosted-runner` | 啟動執行程序，將此機器或容器註冊到 [自託管環境](https://code.claude.com/docs/zh-TW/self-hosted-environments) 並在您的基礎結構上託管 Claude Code 雲端工作階段。執行 `claude self-hosted-runner setup` 以進行引導式操作員逐步解說，`claude self-hosted-runner doctor` 以 [診斷已部署的執行程序](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#troubleshooting)，以及 `claude self-hosted-runner orchestrator` 以生成 [隨需執行程序](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration.md#on-demand-runners)。需要 Claude Code v2.1.224 或更新版本 | `claude self-hosted-runner setup` |

111| `--no-session-persistence` | 停用工作階段持續性，使工作階段不會儲存到磁碟且無法恢復。僅列印模式。[`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](https://code.claude.com/docs/zh-TW/env-vars) 環境變數在任何模式中執行相同操作 | `claude -p --no-session-persistence "query"` |111| `--no-session-persistence` | 停用工作階段持續性，使工作階段不會儲存到磁碟且無法恢復。僅列印模式。[`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](https://code.claude.com/docs/zh-TW/env-vars) 環境變數在任何模式中執行相同操作 | `claude -p --no-session-persistence "query"` |

113| `--permission-mode` | 以指定的[權限模式](https://code.claude.com/docs/zh-TW/permission-modes.md)開始。接受 `default`、`acceptEdits`、`plan`、`auto`、`dontAsk`、`bypassPermissions` 或 `manual` 作為 `default` 的別名。`manual` 別名選擇 UI 標籤為 Manual 的權限模式，需要 Claude Code v2.1.200 或更新版本；`claude --help` 會列出它代替 `default`，兩個值都有效。覆蓋設定檔案中的 `defaultMode`。沒有此旗標或 `--dangerously-skip-permissions`，新工作階段會以[工作階段開始的權限模式](https://code.claude.com/docs/zh-TW/permission-modes.md#which-mode-a-session-starts-in)中描述的權限模式開始，這也涵蓋 `-p` 執行開始的內容 | `claude --permission-mode plan` |113| `--permission-mode` | 以指定的[權限模式](https://code.claude.com/docs/zh-TW/permission-modes.md)開始。接受 `default`、`acceptEdits`、`plan`、`auto`、`dontAsk`、`bypassPermissions` 或 `manual` 作為 `default` 的別名。`manual` 別名選擇 UI 標籤為 Manual 的權限模式，需要 Claude Code v2.1.200 或更新版本；`claude --help` 會列出它代替 `default`，兩個值都有效。覆蓋設定檔案中的 `defaultMode`。沒有此旗標或 `--dangerously-skip-permissions`，新工作階段會以[工作階段開始的權限模式](https://code.claude.com/docs/zh-TW/permission-modes.md#which-mode-a-session-starts-in)中描述的權限模式開始，這也涵蓋 `-p` 執行開始的內容 | `claude --permission-mode plan` |

114| `--permission-prompt-tool` | 指定 MCP 工具以在非互動模式中處理權限提示。傳遞該次執行所載入之 MCP 伺服器上某個工具的完整名稱，例如 `mcp__<server>__<tool>`。Claude Code 會在執行第一個回合之前等待該工具的 MCP 伺服器連線，直到 [`MCP_TIMEOUT`](https://code.claude.com/docs/zh-TW/env-vars) 啟動逾時（預設 30 秒）。提示工具無法核准標記為[需要使用者互動](https://code.claude.com/docs/zh-TW/mcp.md#require-approval-for-a-specific-tool)的 MCP 工具：Claude Code 會將其 `allow` 結果轉換為拒絕。此限制需要 Claude Code v2.1.199 或更新版本 | `claude -p --mcp-config ./mcp.json --permission-prompt-tool mcp__permissions__approve "query"` |114| `--permission-prompt-tool` | 指定 MCP 工具以在非互動模式中處理權限提示。傳遞該次執行所載入之 MCP 伺服器上某個工具的完整名稱，例如 `mcp__<server>__<tool>`。Claude Code 會在執行第一個回合之前等待該工具的 MCP 伺服器連線，直到 [`MCP_TIMEOUT`](https://code.claude.com/docs/zh-TW/env-vars) 啟動逾時（預設 30 秒）。請參閱[工具必須傳回的內容](https://code.claude.com/docs/zh-TW/errors.md#permission-prompt-tool-returned-an-invalid-result)。提示工具無法核准標記為[需要使用者互動](https://code.claude.com/docs/zh-TW/mcp.md#require-approval-for-a-specific-tool)的 MCP 工具：Claude Code 會將其 `allow` 結果轉換為拒絕。此限制需要 Claude Code v2.1.199 或更新版本 | `claude -p --mcp-config ./mcp.json --permission-prompt-tool mcp__permissions__approve "query"` |

115| `--permission-prompts` | 在列印模式中設定誰回答權限提示。使用預設 `host`，Claude Code 會將它們傳送到 Agent SDK 主機或 `--permission-prompt-tool` 工具。當沒有人可以回答時傳遞 `none`，Claude Code 會改為拒絕它們。請參閱[在無人值守執行中關閉權限提示](https://code.claude.com/docs/zh-TW/headless.md#turn-off-permission-prompts-in-unattended-runs)。需要 Claude Code v2.1.259 或更新版本 | `claude -p --permission-prompts none "query"` |115| `--permission-prompts` | 在列印模式中設定誰回答權限提示。使用預設 `host`，Claude Code 會將它們傳送到 Agent SDK 主機或 `--permission-prompt-tool` 工具。當沒有人可以回答時傳遞 `none`，Claude Code 會改為拒絕它們。請參閱[在無人值守執行中關閉權限提示](https://code.claude.com/docs/zh-TW/headless.md#turn-off-permission-prompts-in-unattended-runs)。需要 Claude Code v2.1.259 或更新版本 | `claude -p --permission-prompts none "query"` |

116| `--plugin-dir` | 從目錄或 `.zip` 封存載入 plugin，或從[plugins 資料夾](https://code.claude.com/docs/zh-TW/plugins/create.md#load-a-directory-or-archive-for-one-session)載入多個，僅供此工作階段使用。每個旗標採用一個路徑。重複旗標以取得更多路徑：`--plugin-dir A --plugin-dir B.zip`。傳遞 plugins 資料夾需要 Claude Code v2.1.265 或更新版本 | `claude --plugin-dir ./my-plugin` |116| `--plugin-dir` | 從目錄或 `.zip` 封存載入 plugin，或從[plugins 資料夾](https://code.claude.com/docs/zh-TW/plugins/create.md#load-a-directory-or-archive-for-one-session)載入多個，僅供此工作階段使用。每個旗標採用一個路徑。重複旗標以取得更多路徑：`--plugin-dir A --plugin-dir B.zip`。傳遞 plugins 資料夾需要 Claude Code v2.1.265 或更新版本 | `claude --plugin-dir ./my-plugin` |

commands.md +1 −1

Details

162| `/ultrareview [PR or branch]` | 在雲端沙箱中使用 [ultrareview](https://code.claude.com/docs/zh-TW/ultrareview.md) 運行深度、多 agent 程式碼審查。傳遞 PR 參考以檢查該 pull request，或傳遞基礎分支或提交以變更比較基礎。首選調用是 `/code-review ultra`，`/ultrareview` 是別名。在 Pro、Max 和 Ultra 上包括 3 次免費運行，然後需要[用量點數](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |162| `/ultrareview [PR or branch]` | 在雲端沙箱中使用 [ultrareview](https://code.claude.com/docs/zh-TW/ultrareview.md) 運行深度、多 agent 程式碼審查。傳遞 PR 參考以檢查該 pull request，或傳遞基礎分支或提交以變更比較基礎。首選調用是 `/code-review ultra`，`/ultrareview` 是別名。在 Pro、Max 和 Ultra 上包括 3 次免費運行，然後需要[用量點數](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |

163| `/update-config [request]` | **[Skill](https://code.claude.com/docs/zh-TW/skills.md#bundled-skills)。** 描述設定變更，例如允許命令、設定環境變數或添加 [hook](https://code.claude.com/docs/zh-TW/hooks.md)，Claude 編輯匹配的 [`settings.json`](https://code.claude.com/docs/zh-TW/settings) 檔案。對於主題和模型等選項，改用 `/config` |163| `/update-config [request]` | **[Skill](https://code.claude.com/docs/zh-TW/skills.md#bundled-skills)。** 描述設定變更，例如允許命令、設定環境變數或添加 [hook](https://code.claude.com/docs/zh-TW/hooks.md)，Claude 編輯匹配的 [`settings.json`](https://code.claude.com/docs/zh-TW/settings) 檔案。對於主題和模型等選項，改用 `/config` |

165| `/usage` | 顯示工作階段成本、方案用量上限和活動統計。在 Pro、Max、Ultra、Team 或 Enterprise 方案上，包括[計入您的方案上限的內容細目](https://code.claude.com/docs/zh-TW/costs.md#plan-usage-breakdown)。`/cost` 和 `/stats` 是別名 |165| `/usage` | 顯示工作階段成本、方案用量上限和活動統計。在 Pro、Max、Ultra、Team 或 Enterprise 方案上，包括[計入您的方案上限的內容細目](https://code.claude.com/docs/zh-TW/costs.md#plan-usage-breakdown)。在追蹤支出的 Claude 應用程式閘道後方時，顯示[您透過閘道的支出](https://code.claude.com/docs/zh-TW/claude-apps-gateway-spend-limits.md#usage-warnings-in-claude-code)。`/cost` 和 `/stats` 是別名 |

166| `/usage-credits` | 在達到上限時設定用量點數，或向您的管理員請求。在瀏覽器中打開您的[用量點數計費設定](https://code.claude.com/docs/zh-TW/costs.md#add-usage-credits-to-your-subscription)，但沒有計費存取權的 Team 和 Enterprise 成員則改為從 CLI 向其管理員發送用量點數請求，並先在對話框中確認該請求會通知其管理員。當沒有瀏覽器可以打開計費頁面時，例如通過 SSH，命令會改為列印要前往的 URL；這需要 Claude Code v2.1.205 或更新版本，較早版本在這種情況下不顯示任何內容。以前為 `/extra-usage` |166| `/usage-credits` | 在達到上限時設定用量點數，或向您的管理員請求。在瀏覽器中打開您的[用量點數計費設定](https://code.claude.com/docs/zh-TW/costs.md#add-usage-credits-to-your-subscription)，但沒有計費存取權的 Team 和 Enterprise 成員則改為從 CLI 向其管理員發送用量點數請求，並先在對話框中確認該請求會通知其管理員。當沒有瀏覽器可以打開計費頁面時，例如通過 SSH，命令會改為列印要前往的 URL；這需要 Claude Code v2.1.205 或更新版本，較早版本在這種情況下不顯示任何內容。以前為 `/extra-usage` |

167| `/verify` | **[Skill](https://code.claude.com/docs/zh-TW/skills.md#bundled-skills)。** 通過建置您的專案應用程式、運行它並觀察結果來確認程式碼變更執行其應該執行的操作，而不是依賴測試或類型檢查。請參閱[運行和驗證您的應用程式](https://code.claude.com/docs/zh-TW/skills.md#run-and-verify-your-app) |167| `/verify` | **[Skill](https://code.claude.com/docs/zh-TW/skills.md#bundled-skills)。** 通過建置您的專案應用程式、運行它並觀察結果來確認程式碼變更執行其應該執行的操作，而不是依賴測試或類型檢查。請參閱[運行和驗證您的應用程式](https://code.claude.com/docs/zh-TW/skills.md#run-and-verify-your-app) |

168| `/vim` | 在 v2.1.92 中移除。要在 Vim 和 Normal 編輯模式之間切換，請使用 `/config` → Editor mode |168| `/vim` | 在 v2.1.92 中移除。要在 Vim 和 Normal 編輯模式之間切換，請使用 `/config` → Editor mode |

env-vars.md +2 −1

Details

365| `CLAUDE_CODE_PROMPT_CACHE_TTL` | 設定 `5m` 或 `1h`（Claude Code 僅接受這兩個值），以選擇主對話的[提示快取 TTL](https://code.claude.com/docs/zh-TW/prompt-caching.md#cache-lifetime)：包括您的互動式、`-p` 與 SDK 回合，以及與其內嵌執行的輔助程序。優先於 `promptCacheTtl` 設定與 `ENABLE_PROMPT_CACHING_1H`，而 `FORCE_PROMPT_CACHING_5M` 會覆寫它。API 對 1 小時快取寫入以較高費率計費。需要 Claude Code v2.1.242 或更新版本 |365| `CLAUDE_CODE_PROMPT_CACHE_TTL` | 設定 `5m` 或 `1h`（Claude Code 僅接受這兩個值），以選擇主對話的[提示快取 TTL](https://code.claude.com/docs/zh-TW/prompt-caching.md#cache-lifetime)：包括您的互動式、`-p` 與 SDK 回合，以及與其內嵌執行的輔助程序。優先於 `promptCacheTtl` 設定與 `ENABLE_PROMPT_CACHING_1H`，而 `FORCE_PROMPT_CACHING_5M` 會覆寫它。API 對 1 小時快取寫入以較高費率計費。需要 Claude Code v2.1.242 或更新版本 |

366| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | 設為 `1` 可在 `ANTHROPIC_BASE_URL` 指向自訂代理伺服器時傳播 W3C trace context。傳播範圍涵蓋模型與 HTTP MCP 請求上的 `traceparent` 標頭，以及 Bash、PowerShell 與 hook 子程序的 `TRACEPARENT` 環境變數。預設情況下，僅在直接連線至 Anthropic API 時啟用傳播。於 v2.1.152 新增。請參閱[追蹤（beta）](https://code.claude.com/docs/zh-TW/monitoring-usage.md#traces-beta) |366| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | 設為 `1` 可在 `ANTHROPIC_BASE_URL` 指向自訂代理伺服器時傳播 W3C trace context。傳播範圍涵蓋模型與 HTTP MCP 請求上的 `traceparent` 標頭，以及 Bash、PowerShell 與 hook 子程序的 `TRACEPARENT` 環境變數。預設情況下，僅在直接連線至 Anthropic API 時啟用傳播。於 v2.1.152 新增。請參閱[追蹤（beta）](https://code.claude.com/docs/zh-TW/monitoring-usage.md#traces-beta) |

367| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | 由內嵌 Claude Code 並代為管理模型供應商路由的主機平台設定。設定後，Claude Code 會忽略設定檔中的供應商選擇、端點與身分驗證變數，例如 `CLAUDE_CODE_USE_BEDROCK`、`ANTHROPIC_BASE_URL` 與 `ANTHROPIC_API_KEY`，讓使用者設定無法覆寫主機的路由。Claude Code 也會忽略[受管設定](https://code.claude.com/docs/zh-TW/managed-settings.md)中的模型選擇鍵，例如 `model`、`fallbackModel` 與 `modelOverrides`，無論由哪個受管來源提供，因此主機的模型設定會優先於過時的受管模型固定設定。Claude Code 也會忽略受管 `env` 區塊中的模型選擇變數，例如 `ANTHROPIC_MODEL` 與 `ANTHROPIC_DEFAULT_*_MODEL` 系列；受管設定中的 [`availableModels`](https://code.claude.com/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 供應商區分的預設行為](https://code.claude.com/docs/zh-TW/data-usage.md#default-behaviors-by-api-provider) |367| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | 由內嵌 Claude Code 並代為管理模型供應商路由的主機平台設定。設定後，Claude Code 會忽略設定檔中的供應商選擇、端點與身分驗證變數，例如 `CLAUDE_CODE_USE_BEDROCK`、`ANTHROPIC_BASE_URL` 與 `ANTHROPIC_API_KEY`，讓使用者設定無法覆寫主機的路由。Claude Code 也會忽略[受管設定](https://code.claude.com/docs/zh-TW/managed-settings.md)中的模型選擇鍵，例如 `model`、`fallbackModel` 與 `modelOverrides`，無論由哪個受管來源提供，因此主機的模型設定會優先於過時的受管模型固定設定。Claude Code 也會忽略受管 `env` 區塊中的模型選擇變數，例如 `ANTHROPIC_MODEL` 與 `ANTHROPIC_DEFAULT_*_MODEL` 系列；受管設定中的 [`availableModels`](https://code.claude.com/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 供應商區分的預設行為](https://code.claude.com/docs/zh-TW/data-usage.md#default-behaviors-by-api-provider) |

368| `CLAUDE_CODE_PROXY_RESOLVES_HOSTS` | 設為 `1` 可讓代理伺服器執行 DNS 解析，而非由呼叫端執行。適用於應由代理伺服器處理主機名稱解析之環境的選擇性啟用設定 |368| `CLAUDE_CODE_PROXY_RESOLVES_HOSTS` | 設為 `1`，允許代理伺服器代替呼叫者執行 DNS 解析。供應由代理伺服器處理主機名稱解析的環境選擇啟用。當設定了 `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` 時，請在啟動 Claude Code 之程序的環境中設定此變數 |

369| `CLAUDE_CODE_REMOTE` | 當 Claude Code 以[雲端工作階段](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md)執行時自動設為 `true`。可從 hook 或設定指令碼讀取此值，以偵測是否處於雲端工作階段中 |369| `CLAUDE_CODE_REMOTE` | 當 Claude Code 以[雲端工作階段](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md)執行時自動設為 `true`。可從 hook 或設定指令碼讀取此值，以偵測是否處於雲端工作階段中 |

370| `CLAUDE_CODE_REMOTE_SESSION_ID` | 在[雲端工作階段](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md)中自動設為目前工作階段的 ID。讀取此值可建構返回工作階段逐字稿的連結。請參閱[將輸出連結回工作階段](https://code.claude.com/docs/zh-TW/cloud-environments.md#link-output-back-to-the-session) |370| `CLAUDE_CODE_REMOTE_SESSION_ID` | 在[雲端工作階段](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md)中自動設為目前工作階段的 ID。讀取此值可建構返回工作階段逐字稿的連結。請參閱[將輸出連結回工作階段](https://code.claude.com/docs/zh-TW/cloud-environments.md#link-output-back-to-the-session) |

371| `CLAUDE_CODE_RESTRICTED` | 設為 `1` 可以受限模式啟動工作階段，等同於傳遞 [`--restricted`](https://code.claude.com/docs/zh-TW/cli-reference#cli-flags)。Claude Code 會忽略設定檔 `env` 區塊中的此變數。需要 Claude Code v2.1.248 或更新版本 |371| `CLAUDE_CODE_RESTRICTED` | 設為 `1` 可以受限模式啟動工作階段，等同於傳遞 [`--restricted`](https://code.claude.com/docs/zh-TW/cli-reference#cli-flags)。Claude Code 會忽略設定檔 `env` 區塊中的此變數。需要 Claude Code v2.1.248 或更新版本 |

532| `VERTEX_REGION_CLAUDE_FABLE_5_2` | 使用 Google Cloud's Agent Platform 時覆寫 Claude Fable 5.2 的區域。於 v2.1.321 新增 |

534 535

errors.md +106 −29

Details

52| `Credit balance is too low` | [用量上限](#credit-balance-is-too-low) |52| `Credit balance is too low` | [用量上限](#credit-balance-is-too-low) |

53| `You've hit your monthly spend limit` / `You've hit your individual spend limit` / `You've hit your org's monthly spend limit` / `You've hit your channel's monthly spend limit` / `You've hit your team's shared budget` / `You've hit your individual usage limit` | [用量上限](#youve-hit-your-monthly-spend-limit) |53| `You've hit your monthly spend limit` / `You've hit your individual spend limit` / `You've hit your org's monthly spend limit` / `You've hit your channel's monthly spend limit` / `You've hit your team's shared budget` / `You've hit your individual usage limit` | [用量上限](#youve-hit-your-monthly-spend-limit) |

54| `Could not update your spend limit` | [用量上限](#could-not-update-your-spend-limit) |54| `Could not update your spend limit` | [用量上限](#could-not-update-your-spend-limit) |

56| `Not logged in · Please run /login` | [身分驗證](#not-logged-in) |56| `Not logged in · Please run /login` | [身分驗證](#not-logged-in) |

57| `Couldn't save your login` | [身分驗證](#couldnt-save-your-login) |57| `Couldn't save your login` | [身分驗證](#couldnt-save-your-login) |

58| `Sign in again to take your previous account or API key off the config file.` | [身分驗證](#sign-in-again-to-take-your-previous-account-or-api-key-off-the-config-file) |58| `Sign in again to take your previous account or API key off the config file.` | [身分驗證](#sign-in-again-to-take-your-previous-account-or-api-key-off-the-config-file) |

336| `MCP server "<name>" connection closed before the tool call was answered` | [工具錯誤](#connection-closed-before-the-tool-call-was-answered) |336| `MCP server "<name>" connection closed before the tool call was answered` | [工具錯誤](#connection-closed-before-the-tool-call-was-answered) |

338| `MCP server "<name>" tool "<tool>" timed out after <N>s. The server asked the user a question, and no answer came before the time limit.` | [工具錯誤](#mcp-tool-call-timed-out-with-the-servers-question-unanswered) |338| `MCP server "<name>" tool "<tool>" timed out after <N>s. The server asked the user a question, and no answer came before the time limit.` | [工具錯誤](#mcp-tool-call-timed-out-with-the-servers-question-unanswered) |

339| `Permission prompt tool returned an invalid result` | [工具錯誤](#permission-prompt-tool-returned-an-invalid-result) |

341| `<path> is outside <dirs>; the permissions.blockWritesOutsideWorkingDirectories setting blocks writes outside the working directories` | [工具錯誤](#setting-blocks-writes-outside-the-working-directories) |342| `<path> is outside <dirs>; the permissions.blockWritesOutsideWorkingDirectories setting blocks writes outside the working directories` | [工具錯誤](#setting-blocks-writes-outside-the-working-directories) |

420| `The Claude Code program for this computer, the <build> build, could not be found` | [包裝程式與 IDE 錯誤](#the-claude-code-program-for-this-computer-could-not-be-found) |421| `The Claude Code program for this computer, the <build> build, could not be found` | [包裝程式與 IDE 錯誤](#the-claude-code-program-for-this-computer-could-not-be-found) |

422| `No files were restored: N files failed (backup missing, or the file could not be updated)` | [Rewind 警告和錯誤](#no-files-were-restored) |423| `No files were restored: N files failed (backup missing, or the file could not be updated)` | [Rewind 警告和錯誤](#no-files-were-restored) |

424| `The file backups are still being copied. Nothing was changed. Try again in a moment.` | 在 [`/rewind`](https://code.claude.com/docs/zh-TW/checkpointing) 中再次選擇相同的時間點。若在 [`/branch`](https://code.claude.com/docs/zh-TW/sessions#branch-a-session) 後不久還原程式碼，Claude Code 可能仍在將檔案備份複製到新的工作階段。 |

424| `Transcript saving is off — CLAUDE_CODE_SKIP_PROMPT_HISTORY is set` | [工作階段儲存警告](#transcript-saving-is-off-skip-prompt-history) |426| `Transcript saving is off — CLAUDE_CODE_SKIP_PROMPT_HISTORY is set` | [工作階段儲存警告](#transcript-saving-is-off-skip-prompt-history) |

425| `Transcript saving is off — inherited CLAUDE_CODE_CHILD_SESSION marker` | [工作階段儲存警告](#transcript-saving-is-off-child-session-marker) |427| `Transcript saving is off — inherited CLAUDE_CODE_CHILD_SESSION marker` | [工作階段儲存警告](#transcript-saving-is-off-child-session-marker) |

431| `Not loaded: rename <path>, then restart — its name uses "<name>", a name reserved for the skills synced from your claude.ai account` | [設定警告](#a-skill-command-or-workflow-wasnt-loaded-because-its-name-is-reserved) |433| `Not loaded: rename <path>, then restart — its name uses "<name>", a name reserved for the skills synced from your claude.ai account` | [設定警告](#a-skill-command-or-workflow-wasnt-loaded-because-its-name-is-reserved) |

432| `N skill or command names refused: run with --debug to see which ([names]), rename, then restart` | [設定警告](#skill-or-command-name-refused) |434| `N skill or command names refused: run with --debug to see which ([names]), rename, then restart` | [設定警告](#skill-or-command-name-refused) |

433| `Ignoring N permissions.allow entries from ... this workspace has not been trusted` | [設定警告](#workspace-has-not-been-trusted) |435| `Ignoring N permissions.allow entries from ... this workspace has not been trusted` | [設定警告](#workspace-has-not-been-trusted) |

436| `Two Claude Code config files exist: this run uses <path>, not <path>` | [設定警告](#two-claude-code-config-files-exist) |

434| `Make this change again later: <path> could not be updated, so it applies to this session only` | [設定警告](#make-this-change-again-later) |437| `Make this change again later: <path> could not be updated, so it applies to this session only` | [設定警告](#make-this-change-again-later) |

468| `CLAUDE_CODE_AUTO_COMPACT_WINDOW="<value>" isn't a usable size, so Claude Code ignores it` | [`CLAUDE_CODE_AUTO_COMPACT_WINDOW` 的值與警告](https://code.claude.com/docs/zh-TW/model-config#claude_code_auto_compact_window-values) |471| `CLAUDE_CODE_AUTO_COMPACT_WINDOW="<value>" isn't a usable size, so Claude Code ignores it` | [`CLAUDE_CODE_AUTO_COMPACT_WINDOW` 的值與警告](https://code.claude.com/docs/zh-TW/model-config#claude_code_auto_compact_window-values) |

469| `Model "<model>" isn't recognized · context assumed to be 200k tokens` | [修正閘道或自訂模型 ID 的上下文視窗](https://code.claude.com/docs/zh-TW/model-config.md#correct-the-window-for-a-gateway-or-custom-model-id) |472| `Model "<model>" isn't recognized · context assumed to be 200k tokens` | [修正閘道或自訂模型 ID 的上下文視窗](https://code.claude.com/docs/zh-TW/model-config.md#correct-the-window-for-a-gateway-or-custom-model-id) |

470| `Claude Code doesn't recognize the model "<model>", so it assumes a context window of 200k tokens` | [修正閘道或自訂模型 ID 的上下文視窗](https://code.claude.com/docs/zh-TW/model-config.md#correct-the-window-for-a-gateway-or-custom-model-id) |473| `Claude Code doesn't recognize the model "<model>", so it assumes a context window of 200k tokens` | [修正閘道或自訂模型 ID 的上下文視窗](https://code.claude.com/docs/zh-TW/model-config.md#correct-the-window-for-a-gateway-or-custom-model-id) |

474| `Model "<model>" isn't recognized · did you mean "<suggestion>"?` / `Claude Code doesn't recognize the model "<model>". Did you mean "<suggestion>"?` | [修正拼錯的模型名稱](https://code.claude.com/docs/zh-TW/model-config.md#fix-a-mistyped-model-name) |

472| `is ignored — managed settings set allowManagedReadPathsOnly` / `is ignored — managed settings set allowManagedDomainsOnly` | [設定警告](#sandbox-allow-entries-are-ignored-under-a-managed-lock) |476| `is ignored — managed settings set allowManagedReadPathsOnly` / `is ignored — managed settings set allowManagedDomainsOnly` | [設定警告](#sandbox-allow-entries-are-ignored-under-a-managed-lock) |

909Fable 5.1 now uses usage credits · the prompt to confirm went unanswered — nothing was sent · answer it where this session is running, or /model to change913Fable 5.1 now uses usage credits · the prompt to confirm went unanswered — nothing was sent · answer it where this session is running, or /model to change

910```914```

911 915

912訊息會命名工作階段的 Fable 模型，因此在 Fable 5 上它們會讀作 `continuing on Fable 5` 和 `Fable 5 now uses usage credits`。在 v2.1.257 之前，第一條訊息以 `Fable 5 limit reached` 開頭。916訊息會命名工作階段的 Fable 模型，因此在 Fable 5.2 上它們會讀作 `continuing on Fable 5.2` 和 `Fable 5.2 now uses usage credits`。在 v2.1.257 之前，第一條訊息以 `Fable 5 limit reached` 開頭。

913 917

914這發生在 [Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md) 工作階段、[背景工作階段](https://code.claude.com/docs/zh-TW/agent-view.md)、[agent team](https://code.claude.com/docs/zh-TW/agent-teams.md) 隊友工作階段，以及另一個應用程式透過 Agent SDK 託管的工作階段中。如需 Claude Code 何時關閉提示，請參閱 [Fable 和用量點數](https://code.claude.com/docs/zh-TW/model-config.md#fable-and-usage-credits)。918這發生在 [Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md) 工作階段、[背景工作階段](https://code.claude.com/docs/zh-TW/agent-view.md)、[agent team](https://code.claude.com/docs/zh-TW/agent-teams.md) 隊友工作階段，以及另一個應用程式透過 Agent SDK 託管的工作階段中。如需 Claude Code 何時關閉提示，請參閱 [Fable 和用量點數](https://code.claude.com/docs/zh-TW/model-config.md#fable-and-usage-credits)。

915 919

983 987

984### Spend limit reached988### Spend limit reached

985 989

986您透過 [Claude 應用程式閘道](https://code.claude.com/docs/zh-TW/claude-apps-gateway)連接，並已超過閘道營運者設定的[支出上限](https://code.claude.com/docs/zh-TW/claude-apps-gateway-spend-limits.md)。閘道會阻止您的請求，直到指定的期間重設或營運者提高上限。它將每個被阻止的 `429` 回應標記為 `x-should-retry: false`，因此 Claude Code 會顯示此訊息而不重試。990您透過 [Claude 應用程式閘道](https://code.claude.com/docs/zh-TW/claude-apps-gateway)連接，並已達到閘道營運者設定的[支出上限](https://code.claude.com/docs/zh-TW/claude-apps-gateway-spend-limits.md)。閘道會阻止您的請求，直到營運者提高上限，或者若上限高於 \$0，則直到上限重設為止。它將每個被阻止的 `429` 回應標記為 `x-should-retry: false`，因此在終端機中 Claude Code 會顯示此訊息而不重試。

987 991

988```text theme={null}992```text theme={null}

989spend limit reached (daily; resets 2026-08-09 00:00 UTC)993spend limit reached · resets Dec 1

990```994```

991 995

992訊息會指出上限的期間和重設時間，當營運者設定了 `blocked_message` 時，他們的指示會跟在後面。在 v2.1.225 之前，訊息只顯示 `spend limit reached`；較舊版本上的閘道仍會發送該較短的形式。996檢查訊息中是否有日期：

997

998* **有日期**：上限會在該日期的 00:00 UTC 重設

999* **沒有日期**：您的上限為 \$0，或您的閘道執行的是早於 v2.1.225 的版本

1000

1001訊息中的任何其他文字都是您的閘道營運者留下的備註。

1002

1003在閘道伺服器上從 v2.1.225 到 v2.1.319 期間，訊息會指出上限的期間和重設時間，例如 `spend limit reached (daily; resets 2026-08-09 00:00 UTC)`。

993 1004

994**該怎麼做：**1005**該怎麼做：**

995 1006

996* 等待訊息指出的重設時間，或如果訊息包含營運者的指示，請遵循它們1007* 如果訊息有日期，請等待重設，或如果訊息附有營運者的備註，請遵循它

997* 如果您經常達到上限，請要求您的閘道營運者提高上限1008* 如果訊息沒有日期、過了該日期後您仍被阻止，或您經常達到上限，請要求您的閘道營運者提高上限

1009

1010另一則閘道訊息 `This request exceeds your group's budget` 表示您群組的[集區預算](https://code.claude.com/docs/zh-TW/claude-apps-gateway-config.md#pooled-budget-order)已用完。請依照訊息中指出的步驟操作：

1011

1012```text theme={null}

1013This request exceeds your group's budget. Ask your organization's admins to raise it, or try again after it resets on November 1 at 00:00 UTC.

1014```

998 1015

999相關訊息 `spend limit unavailable` 表示閘道無法讀取其支出記錄，並作為預防措施阻止了請求，而不是因為超過您的上限。它通常會自行解除；如果持續發生，請告知您的閘道營運者。1016相關訊息 `spend limit unavailable` 表示閘道無法讀取其支出記錄，並作為預防措施阻止了請求，而不是因為超過您的上限。它通常會自行解除；如果持續發生，請告知您的閘道營運者。

1000 1017

2287 2304

2288### Couldn't send feedback2305### Couldn't send feedback

2289 2306

2290以 `Couldn't send feedback` 開頭的訊息表示意見反應服務未確認收到您從 [`/feedback`、`/bug` 或 `/share` 對話方塊](https://code.claude.com/docs/zh-TW/commands#all-commands)提交的報告，或佇列中的[意見反應草稿](https://code.claude.com/docs/zh-TW/tools-reference.md#sendfeedback-tool-behavior)。請將其視為未收到。當冒號後面接著一句關於您組織的說明時，表示您的組織拒絕接收意見反應，同一份報告會得到相同的回應。2307以 `Couldn't send feedback` 開頭的訊息表示意見反應服務未確認收到您從 [`/feedback`、`/bug` 或 `/share` 對話方塊](https://code.claude.com/docs/zh-TW/commands#all-commands)提交的報告，或佇列中的[意見反應草稿](https://code.claude.com/docs/zh-TW/tools-reference.md#sendfeedback-tool-behavior)。請將其視為未收到。當冒號後面接著一句關於您組織的說明時，表示您的組織拒絕接收意見反應。

2291 2308

2292以下兩個範例中，第二個是組織的拒絕：2309第二個範例是組織的拒絕：

2293 2310

2294```text wrap theme={null}2311```text wrap theme={null}

2295Couldn't send feedback (couldn't reach the service). If it keeps failing, you can file at https://github.com/anthropics/claude-code/issues instead.2312Couldn't send feedback (couldn't reach the service). If it keeps failing, you can file at https://github.com/anthropics/claude-code/issues instead.

2300**該怎麼做：**2317**該怎麼做：**

2301 2318

2302* **未登入**：訊息接著顯示 `: not signed in. Run /login, then retry.`。執行 `/login`，然後再次傳送2319* **未登入**：訊息接著顯示 `: not signed in. Run /login, then retry.`。執行 `/login`，然後再次傳送

2303* **您組織的拒絕**：例如 `: Feedback has not been enabled for your organization.` 或 `: Feedback collection is not available for organizations with custom data retention policies.`。如果訊息附加 `To report a bug, open an issue`，請在 [github.com/anthropics/claude-code/issues](https://github.com/anthropics/claude-code/issues) 提交 issue。佇列中的草稿會保留在佇列中，您可以[捨棄它](https://code.claude.com/docs/zh-TW/tools-reference.md#discard-or-keep-a-draft)2320* **您組織的拒絕**：例如 `: Feedback has not been enabled for your organization.` 或 `: Feedback collection is not available for organizations with custom data retention policies.`。如果訊息附加 `To report a bug, open an issue`，請在 [github.com/anthropics/claude-code/issues](https://github.com/anthropics/claude-code/issues) 提交 issue。之後七天內，`/feedback` 可能會回應它已[被您組織的原則停用](#feedback-is-disabled-by-your-organizations-policy)。佇列中的草稿會保留在佇列中，並仍會[依排程過期](https://code.claude.com/docs/zh-TW/tools-reference.md#discard-or-keep-a-draft)

2304* **憑證遭拒**：訊息接著顯示 `: the sign-in this session uses is not allowed to send feedback` 或 `: the server did not accept the credentials this session uses`。在 Claude Code 提示字元執行 `/status`，以查看此工作階段傳送的是哪個登入、token 或 API 金鑰2321* **憑證遭拒**：訊息接著顯示 `: the sign-in this session uses is not allowed to send feedback` 或 `: the server did not accept the credentials this session uses`。在 Claude Code 提示字元執行 `/status`，以查看此工作階段傳送的是哪個登入、token 或 API 金鑰

2305* **`Couldn't send feedback` 後緊接著 `(request timed out)` 或 `(couldn't reach the service)`**：再次傳送報告或佇列中的草稿。對話方塊會保留您的文字，而佇列中草稿的訊息會顯示 `The draft is still queued.`。如果其他請求也失敗，請檢查您的網路連線並查看 [Unable to connect to API](#unable-to-connect-to-api)。如果持續失敗，請在 [github.com/anthropics/claude-code/issues](https://github.com/anthropics/claude-code/issues) 提交報告2322* **`Couldn't send feedback` 後緊接著 `(request timed out)` 或 `(couldn't reach the service)`**：再次傳送報告或佇列中的草稿。對話方塊會保留您的文字，而佇列中草稿的訊息會顯示 `The draft is still queued.`。如果其他請求也失敗，請檢查您的網路連線並查看 [Unable to connect to API](#unable-to-connect-to-api)。如果持續失敗，請在 [github.com/anthropics/claude-code/issues](https://github.com/anthropics/claude-code/issues) 提交報告

2306* **`Couldn't send feedback` 後緊接著 `(server returned <status>)`，或沒有任何原因**：狀態是服務的回應代碼。當服務有傳送自己的訊息時，該訊息會接在狀態之後，例如 `(server returned 403: Access Forbidden)`。如果持續失敗，請在 [github.com/anthropics/claude-code/issues](https://github.com/anthropics/claude-code/issues) 提交報告2323* **`Couldn't send feedback` 後緊接著 `(server returned <status>)`，或沒有任何原因**：狀態是服務的回應代碼。當服務有傳送自己的訊息時，該訊息會接在狀態之後，例如 `(server returned 403: Access Forbidden)`。如果持續失敗，請在 [github.com/anthropics/claude-code/issues](https://github.com/anthropics/claude-code/issues) 提交報告

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

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

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

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

3435 3452

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

3437 3454

3724 3741

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

3726 3743

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

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

3729 3746

3730**處理方式：**3747**處理方式：**

3731 3748

3878 3895

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

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

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

3882 3899

3883**處理方式：**3900**處理方式：**

3884 3901

4227 4244

4228### /feedback is disabled by your organization's policy4245### /feedback is disabled by your organization's policy

4229 4246

4230此訊息表示您組織的政策不允許從 Claude Code 提供產品意見回饋，因此 `/feedback`、`/bug` 與 `/share` 不會開啟意見回饋對話框。訊息會指出您在 Claude Code 提示字元輸入的命令：4247此訊息表示產品意見回饋已關閉，因此您輸入的命令不會開啟意見回饋對話框。組織的政策與先前的拒絕都會產生此訊息：

4248

4249* **組織政策**：您組織的政策不允許從 Claude Code 提交產品意見回饋。`/feedback`、`/bug` 與 `/share` 都會以此訊息回應。

4250* **先前的拒絕**：意見回饋服務拒絕了您傳送的報告，例如顯示 [`Couldn't send feedback: Feedback has not been enabled for your organization.`](#couldnt-send-feedback)。之後 `/feedback` 與 `/bug` 可能會以此訊息回應。此狀態在這台機器上會從該次拒絕起持續七天。這適用於所有方案，包括 Pro 與 Max。

4251

4252訊息會列出您在 Claude Code 提示字元輸入的命令：

4231 4253

4232```text wrap theme={null}4254```text wrap theme={null}

4233/feedback is disabled by your organization's policy. To report a bug, open an issue at https://github.com/anthropics/claude-code/issues. Issues are public, so leave out anything confidential.4255/feedback is disabled by your organization's policy. To report a bug, open an issue at https://github.com/anthropics/claude-code/issues. Issues are public, so leave out anything confidential.

4238**處理方式：**4260**處理方式：**

4239 4261

4240* 若要回報錯誤，請在 [github.com/anthropics/claude-code/issues](https://github.com/anthropics/claude-code/issues) 建立 issue。任何人都可以閱讀該處的 issue，因此請勿包含程式碼、逐字稿及任何其他機密內容。4262* 若要回報錯誤，請在 [github.com/anthropics/claude-code/issues](https://github.com/anthropics/claude-code/issues) 建立 issue。任何人都可以閱讀該處的 issue，因此請勿包含程式碼、逐字稿及任何其他機密內容。

4263* 在先前遭到拒絕後，請等待七天過去，然後再次傳送報告，以確認服務是否仍會拒絕

4264

4265在 v2.1.319 之前，先前的拒絕不會產生此訊息。

4241 4266

4242在 v2.1.302 之前，完整訊息為 `/feedback is disabled by your organization's policy. Contact your organization admin to enable it.`4267在 v2.1.302 之前，完整訊息為 `/feedback is disabled by your organization's policy. Contact your organization admin to enable it.`

4243 4268

4654* 若要給予回答更多時間，請在伺服器的設定項目中以毫秒為單位設定較長的 [`timeout`](https://code.claude.com/docs/zh-TW/mcp#time-limits-on-mcp-tool-calls)，例如 `"timeout": 600000` 代表 10 分鐘4679* 若要給予回答更多時間，請在伺服器的設定項目中以毫秒為單位設定較長的 [`timeout`](https://code.claude.com/docs/zh-TW/mcp#time-limits-on-mcp-tool-calls)，例如 `"timeout": 600000` 代表 10 分鐘

4655* 改為在互動式工作階段中執行該任務，並自行回答伺服器的 [對話框](https://code.claude.com/docs/zh-TW/mcp.md#respond-to-mcp-elicitation-requests)4680* 改為在互動式工作階段中執行該任務，並自行回答伺服器的 [對話框](https://code.claude.com/docs/zh-TW/mcp.md#respond-to-mcp-elicitation-requests)

4656 4681

4682### Permission prompt tool returned an invalid result

4683

4684您傳給 [`--permission-prompt-tool`](https://code.claude.com/docs/zh-TW/cli-reference#cli-flags) 的工具傳回了 Claude Code 無法讀取的回答，因此等待該回答的工具呼叫並未執行，即使該回答允許了該呼叫也是如此：

4685

4686```text wrap theme={null}

4687Permission prompt tool returned an invalid result. Expected a single text block param with type="text" and a string text value.

4688```

4689

4690**處理方式：**

4691

4692* 傳回一個文字區塊，其文字為 `{"behavior": "allow"}` 或 `{"behavior": "deny", "message": "<reason>"}`。若要變更輸入，請將 `updatedInput` 加入 `allow` 物件。從 v2.1.86 到 v2.1.206，`allow` 需要 `"updatedInput": {}` 才能保留輸入。

4693* 不要傳回 [`structuredContent`](https://code.claude.com/docs/zh-TW/agent-sdk/custom-tools#return-structured-data)，您的 MCP SDK 可能會自行加入它。例如，註冊該工具時：

4694 * **來自 `mcp.server` 的 `FastMCP` 或 `MCPServer`**：使用 `structured_output=False`

4695 * **來自 `fastmcp` 的 `FastMCP`**：使用 `output_schema=None`，並傳回字串

4696 * **MCP TypeScript SDK**：不使用 `outputSchema`

4697* 如果錯誤只在輸入約 40 KB 以上時出現，請勿將輸入複製到 `updatedInput` 或拒絕的 `message` 中。若要變更如此大的輸入，請 [提高您權限提示工具的輸出上限](https://code.claude.com/docs/zh-TW/mcp.md#raise-the-limit-for-a-specific-tool)。

4698

4657### Agent would be spawned with zero tools4699### Agent would be spawned with zero tools

4658 4700

4659subagent 的 [`tools` 清單](https://code.claude.com/docs/zh-TW/sub-agents#supported-frontmatter-fields) 中的每個項目都無法比對到可用的工具，因此 Claude Code 拒絕啟動該 subagent：沒有任何工具，它就無法執行動作。訊息會依問題類型將您的項目分組：4701subagent 的 [`tools` 清單](https://code.claude.com/docs/zh-TW/sub-agents#supported-frontmatter-fields) 中的每個項目都無法比對到可用的工具，因此 Claude Code 拒絕啟動該 subagent：沒有任何工具，它就無法執行動作。訊息會依問題類型將您的項目分組：

6432 6474

6433在 v2.1.257 之前，`claude doctor` 不會標示這些檔案；較早的版本在工作階段被終止時也會留下相同的佔位檔案。6475在 v2.1.257 之前，`claude doctor` 不會標示這些檔案；較早的版本在工作階段被終止時也會留下相同的佔位檔案。

6434 6476

6477### Two Claude Code config files exist

6478

6479Claude Code 正在使用此訊息所列的第一個檔案，因此第二個檔案中的內容不會生效。第一個檔案是 `.config.json`，這是 [`.claude.json`](https://code.claude.com/docs/zh-TW/claude-directory#ce-claude-json) 的舊名稱。訊息中包含一項檢查，可用來找出哪個檔案保存了您的設定：

6480

6481```text wrap theme={null}

6482Two Claude Code config files exist: this run uses /home/you/.claude/.config.json, not /home/you/.claude.json. The file with the higher count here is usually yours, and this prints nothing else from them: grep -c -E '"(hasCompletedOnboarding|mcpServers)"' "/home/you/.claude/.config.json" "/home/you/.claude.json". To end this: if several hosts share this home, first get every host to version 2.1.319 or later, since an older one can write a moved .config.json back. Then stop your Claude processes on every host, move aside the one you do not want, and start none until no host lists it.

6483```

6484

6485在 Windows 上，`The one with hasCompletedOnboarding or mcpServers in it is usually yours.` 會取代包含 `grep` 命令的那一句。

6486

6487**處理方式：**

6488

6489**1. 找出保存您設定的檔案**

6490

6491* **在 Windows 上**：開啟兩個檔案，查看哪一個包含 `hasCompletedOnboarding` 或 `mcpServers`

6492* **在其他平台上**：在您的 shell 中執行訊息中的 `grep` 命令，查看哪個檔案的計數較高

6493

6494**2. 更新共用家目錄的每一台主機**

6495

6496若多台主機共用此家目錄，請先將每台主機上的 Claude Code 更新至訊息所指的版本或更新版本。較舊的版本可能會將已移走的 `.config.json` 寫回。

6497

6498**3. 停止 Claude Code**

6499

6500停止每台主機上的 Claude Code 程序。

6501

6502**4. 移走您不要的檔案**

6503

6504將您不要的檔案移出其資料夾。請移動而非刪除，以便日後可以放回。

6505

6506**5. 等待後再重新啟動 Claude Code**

6507

6508在沒有任何主機仍於舊路徑列出已移走的檔案之前，請勿在任何主機上啟動 Claude Code。

6509

6510當兩個檔案其中之一不存在後，此訊息就不會再出現。

6511

6435### Make this change again later: \~/.claude.json could not be updated6512### Make this change again later: \~/.claude.json could not be updated

6436 6513

6437stderr 上的此通知表示對 [`~/.claude.json`](https://code.claude.com/docs/zh-TW/claude-directory#ce-claude-json) 的變更（例如登入或對信任提示的回答）未儲存到該檔案：6514stderr 上的此通知表示對 [`~/.claude.json`](https://code.claude.com/docs/zh-TW/claude-directory#ce-claude-json) 的變更（例如登入或對信任提示的回答）未儲存到該檔案：

6444 6521

6445* 在之後的工作階段中再次進行此變更。例如，再次執行 `/login`，或再次回答信任提示。6522* 在之後的工作階段中再次進行此變更。例如，再次執行 `/login`，或再次回答信任提示。

6446 6523

6447## 回應品質似乎低於預期6524## 回應品質似乎比平常差

6448 6525

6449如果 Claude 的回答似乎不如您預期的那樣有能力，但沒有顯示錯誤，原因通常是對話狀態而非模型本身。Claude Code 不會無聲地更改模型版本。它只能在這些情況下切換到備用模型：6526如果 Claude 的回答似乎不如預期，但沒有顯示任何錯誤，原因通常是對話狀態，而非模型本身。Claude Code 不會在未告知的情況下變更模型版本。在以下情況下，它可能會切換至備援模型：

6450 6527

6451* 配置的 [`--fallback-model`](https://code.claude.com/docs/zh-TW/cli-reference#cli-flags) 在可用性錯誤後接管該輪次，並在文字記錄中顯示通知6528* 已設定的 [`--fallback-model`](https://code.claude.com/docs/zh-TW/cli-reference#cli-flags) 會在發生可用性錯誤後接手，僅限該回合，並在逐字稿中顯示通知

6452* Amazon Bedrock 或 Google Cloud 的 Agent Platform 啟動檢查發現您的預設模型不可用，或您的帳戶[在工作階段中途失去對它的存取權](https://code.claude.com/docs/zh-TW/amazon-bedrock.md#when-a-model-is-disabled-mid-session)6529* Amazon Bedrock 或 Google Cloud's Agent Platform 的啟動檢查發現您的預設模型無法使用，或您的帳戶[在工作階段中途失去該模型的存取權](https://code.claude.com/docs/zh-TW/amazon-bedrock.md#when-a-model-is-disabled-mid-session)

6453* [自動模型備用](https://code.claude.com/docs/zh-TW/model-config.md#automatic-model-fallback)在 Fable 5.1、Fable 5、Opus 5.5、Sonnet 5.5 和 Opus 5 上將工作階段移至標記類別的備用模型（當該類別有備用模型時），並在文字記錄中顯示通知6530* 在 Fable 模型、Opus 5.5、Sonnet 5.5 和 Opus 5 上，[自動模型備援](https://code.claude.com/docs/zh-TW/model-config.md#automatic-model-fallback)會在被標記的類別有備援模型時，將工作階段移至該類別的備援模型。逐字稿中會顯示通知

6454 6531

6455下面的模型選擇檢查可以捕捉第二和第三種情況；第一種情況顯示為文字記錄通知而非 `/model` 變更。[模型設定](https://code.claude.com/docs/zh-TW/model-config.md)說明每個備用何時適用。6532下方的「模型選擇」檢查可發現第二和第三種情況；第一種情況會以逐字稿通知的形式出現，而不是 `/model` 的變更。[模型設定](https://code.claude.com/docs/zh-TW/model-config.md)說明了各種備援的適用時機。

6456 6533

6457首先檢查這些項目：6534請先檢查以下項目：

6458 6535

6459* **模型選擇**：執行 `/model` 以確認您在預期的模型上。先前的 `/model` 選擇或 `ANTHROPIC_MODEL` 環境變數可能使您在比預期更小的模型上。6536* **模型選擇**：執行 `/model` 以確認您正在使用預期的模型。先前的 `/model` 選擇或 `ANTHROPIC_MODEL` 環境變數，可能讓您使用的是比預期更小的模型。

6460* **努力程度**：執行 `/effort` 以檢查目前的推理程度，並為困難的除錯或設計工作提高它。預設值因模型而異，所以在假設您低於最大值之前請先檢查。請參閱[調整努力程度](https://code.claude.com/docs/zh-TW/model-config.md#adjust-effort-level)以了解每個模型的預設值和 `ultrathink` 快捷方式。6537* **Effort 等級**：執行 `/effort` 以檢查目前的推理等級，並在進行困難的除錯或設計工作時提高等級。預設值因模型而異，因此在假設您低於最大值之前請先確認。如需各模型的預設值及 `ultrathink` 捷徑，請參閱[調整 effort 等級](https://code.claude.com/docs/zh-TW/model-config.md#adjust-effort-level)。

6461* **上下文壓力**：執行 `/context` 以查看視窗有多滿。如果接近容量，請在自然斷點執行 `/compact` 或執行 `/clear` 以重新開始。請參閱[探索上下文視窗](https://code.claude.com/docs/zh-TW/context-window.md)以了解自動壓縮如何影響較早的輪次。6538* **上下文壓力**：執行 `/context` 以查看上下文視窗的使用量。如果接近容量上限，請在自然的段落點執行 `/compact`，或執行 `/clear` 重新開始。如需了解自動壓縮如何影響較早的回合，請參閱[探索上下文視窗](https://code.claude.com/docs/zh-TW/context-window.md)。

6462* **過時的指示**：大型或過時的 `CLAUDE.md` 檔案和 MCP 工具定義會消耗上下文並可能引導回應。`/doctor` 檢查會標記超大的記憶檔案和未使用的擴充功能，而 `/context` 會顯示 MCP 工具的權杖使用情況。在 v2.1.205 之前，`/doctor` 開啟了一個診斷畫面，標記超大的記憶檔案和子代理定義。6539* **過時的指示**：大型或過時的 `CLAUDE.md` 檔案和 MCP 工具定義會佔用上下文，並可能影響回應方向。`/doctor` 檢查會標示過大的記憶檔案和未使用的擴充功能，而 `/context` 會顯示 MCP 工具的 token 使用量。在 v2.1.205 之前，`/doctor` 會開啟一個診斷畫面，標示過大的記憶檔案和 subagent 定義。

6463 6540

6464當回應出錯時，回溯通常比用更正回覆效果更好。按 Esc 兩次或執行 `/rewind` 以回到不良輪次之前，然後用更多細節重新表述提示。在執行緒中更正會將錯誤的嘗試保留在上下文中，這可能會將後來的答案錨定到它。請參閱[檢查點](https://code.claude.com/docs/zh-TW/checkpointing.md)。6541當回應出錯時，倒轉通常比回覆更正更有效。按兩次 Esc 或執行 `/rewind` 以退回到出錯的回合之前，然後以更具體的內容重新表述提示詞。在同一對話串中更正會讓錯誤的嘗試留在上下文中，可能使後續的回答受其影響。請參閱[檢查點功能](https://code.claude.com/docs/zh-TW/checkpointing.md)。

6465 6542

6466如果在檢查上述項目後品質仍然似乎有問題，請執行 `/feedback` 並描述您預期的內容與您得到的內容。以這種方式提交的回饋包括對話文字記錄，這是 Anthropic 診斷真實迴歸的最快方式。如果 `/feedback` 在您的環境中不可用，請參閱[報告錯誤](#report-an-error)。6543如果在檢查上述項目後品質似乎仍有問題，請執行 `/feedback` 並描述您預期的結果與實際得到的結果。以此方式提交的意見回饋會包含對話逐字稿，這是 Anthropic 診斷真正退化問題最快的方式。如果您的環境中無法使用 `/feedback`，請參閱[回報錯誤](#report-an-error)。

6467 6544

6468如果 Claude 警告懷疑提示注入，或因懷疑注入而拒絕請求，而警告命名的文字是 Claude Code 自動添加到對話中的上下文而非檔案或網路內容，請執行 `claude update` 並重試。如果更新後警告重複出現，請[報告它](#report-an-error)而不是將標記的內容貼回提示中。在 v2.1.201 之前，Sonnet 5 以相同方式拒絕了一些請求。6545如果 Claude 警告疑似提示詞注入，或因疑似注入而拒絕請求，且警告中指出的文字是 Claude Code 自動加入對話的上下文，而非檔案或網頁內容，請執行 `claude update` 並重試。如果更新後警告仍重複出現，請[回報此問題](#report-an-error)，而不要將被標示的內容貼回提示詞中。在 v2.1.201 之前，Sonnet 5 也曾以相同方式拒絕部分請求。

6469 6546

6470## 回報錯誤6547## 回報錯誤

6471 6548

fast-mode.md +21 −16

Details

4 4

5# 使用快速模式加快回應速度5# 使用快速模式加快回應速度

6 6

~~7> 在 Claude Code 中切換快速模式，以獲得更快的 Opus 回應。~~7> 在 Claude Code 中使用 `/fast` 切換快速模式，以獲得更快的 Opus 和 Fable 回應。

8 8

9> [!NOTE]9> [!NOTE]

10>10>

~~11> Claude Opus 5.5 的快速模式已可使用，而 Claude Opus 5 和 Claude Opus 4.8 的快速模式則處於[研究預覽](#research-preview)階段。~~11> Claude Fable 5.2 和 Claude Opus 5.5 的快速模式已可使用，而 Claude Opus 5 和 Claude Opus 4.8 的快速模式則處於[研究預覽](#research-preview)階段。

12 12

13快速模式是 Claude Opus 的高速配置，使模型速度提升最高 2.5 倍，但每個 token 的成本更高。當您需要速度進行互動式工作（如快速迭代或實時調試）時，使用 `/fast` 切換開啟，當成本比延遲更重要時，切換關閉。13快速模式是支援模型的高速設定，使模型速度提升最高 2.5 倍，但每個 token 的成本更高。當您需要速度進行互動式工作（如快速迭代或即時除錯）時，使用 `/fast` 切換開啟；當成本比延遲更重要時，則切換關閉。

14 14

15快速模式不是不同的模型。它使用 Claude Opus 搭配不同的 API 配置，優先考慮速度而非成本效率。您獲得相同的品質和功能，只是回應速度更快。快速模式在 Opus 5.5、Opus 5 和 Opus 4.8 上受支援。它在 Sonnet、Haiku 或其他模型上不可用。15快速模式使用相同的模型，搭配以速度優先於成本效率的不同 API 設定，因此品質和功能維持不變。快速模式在 Fable 5.2、Opus 5.5、Opus 5 和 Opus 4.8 上受支援。它在 Sonnet、Haiku 或其他模型上不可用。

16 16

17> [!WARNING]17> [!WARNING]

18>18>

26需要了解的事項：26需要了解的事項：

27 27

28* 使用 `/fast` 在 Claude Code CLI 中切換快速模式。[VS Code 擴充功能](https://code.claude.com/docs/zh-TW/vs-code.md)在選定的模型支援快速模式時提供**切換快速模式**命令。Claude Code 將該切換儲存到您的 [`fastMode` 設定](#toggle-fast-mode)。28* 使用 `/fast` 在 Claude Code CLI 中切換快速模式。[VS Code 擴充功能](https://code.claude.com/docs/zh-TW/vs-code.md)在選定的模型支援快速模式時提供**切換快速模式**命令。Claude Code 將該切換儲存到您的 [`fastMode` 設定](#toggle-fast-mode)。

~~29* 快速模式定價在 Opus 5.5 上為 $8/$40 MTok 輸入/輸出，在 Opus 5 和 Opus 4.8 上為 $10/$50 MTok 輸入/輸出。~~29* 快速模式每 MTok 輸入/輸出的定價在 Fable 5.2 上為 \$16/\$80，在 Opus 5.5 上為 \$8/\$40，在 Opus 5 和 Opus 4.8 上為 \$10/\$50。

30* 適用於訂閱方案（Pro/Max/Ultra/Team/Enterprise）上的 Claude Code 使用者和 Claude Console。Team 和 Enterprise 組織需要擁有者先啟用它，Console 組織則需要先佈建存取權限，才能搭配 Opus 5 或 Opus 4.8 使用。[需求](#requirements)說明了這兩者。30* 適用於訂閱方案（Pro/Max/Ultra/Team/Enterprise）上的 Claude Code 使用者和 Claude Console。Team 和 Enterprise 組織需要擁有者先啟用它，Console 組織則需要先佈建存取權限，才能搭配 Opus 5 或 Opus 4.8 使用。[需求](#requirements)說明了這兩者。

31* 對於訂閱方案（Pro/Max/Ultra/Team/Enterprise）上的 Claude Code 使用者，快速模式僅透過用量點數提供，不包含在訂閱速率限制中。31* 對於訂閱方案（Pro/Max/Ultra/Team/Enterprise）上的 Claude Code 使用者，快速模式僅透過用量點數提供，不包含在訂閱速率限制中。

32 32

35在 CLI 中，可透過以下任一方式切換快速模式：35在 CLI 中，可透過以下任一方式切換快速模式：

36 36

37* 執行 `/fast`，按 Space 切換開啟或關閉，然後按 Enter 確認37* 執行 `/fast`，按 Space 切換開啟或關閉，然後按 Enter 確認

38* 在支援快速模式的模型上，於您的[使用者設定檔](https://code.claude.com/docs/zh-TW/settings.md)中設定 `"fastMode": true`。如果您在其他任何模型上設定此項，您會繼續使用該模型，且快速模式保持關閉。38* 在支援快速模式的模型上，於您的[使用者設定檔](https://code.claude.com/docs/zh-TW/settings.md)中設定 `"fastMode": true`。如果您在其他任何模型上設定此項，您會繼續使用該模型，且快速模式保持關閉。在 Fable 5.2 上，僅有此設定並不會產生作用，直到您在使用 Fable 5.2 時執行 `/fast`。

39 39

40預設情況下，在互動式工作階段中開啟的快速模式會在支援的模型上跨工作階段保留。您可以將快速模式設定為在每個工作階段重設。詳情請參閱[要求每個工作階段選擇加入](#require-per-session-opt-in)。40預設情況下，在互動式工作階段中開啟的快速模式會在支援的模型上跨工作階段保留。在 Fable 5.2 上，只有在您[於使用 Fable 5.2 時開啟](#switch-models-while-fast-mode-is-on)的情況下才會保留。您可以將快速模式設定為在每個工作階段重設。詳情請參閱[要求每個工作階段選擇加入](#require-per-session-opt-in)。

41 41

42在[雲端工作階段](#use-fast-mode-in-cloud-sessions)之外，於使用 `-p` 旗標的[非互動模式](https://code.claude.com/docs/zh-TW/headless.md)中，`/fast` 僅在其 [`--settings`](https://code.claude.com/docs/zh-TW/cli-reference#cli-flags) 值中啟用快速模式所啟動的工作階段中有效，例如 `claude -p --settings '{"fastMode": true}'`；此時切換僅套用於該工作階段，不會儲存為您的預設值。`-p` 形式需要 Claude Code v2.1.205 或更新版本。在其他非互動模式情況下，該命令會回報快速模式無法使用。42在[雲端工作階段](#use-fast-mode-in-cloud-sessions)之外，於使用 `-p` 旗標的[非互動模式](https://code.claude.com/docs/zh-TW/headless.md)中，`/fast` 僅在其 [`--settings`](https://code.claude.com/docs/zh-TW/cli-reference#cli-flags) 值中啟用快速模式所啟動的工作階段中有效，例如 `claude -p --settings '{"fastMode": true}'`；此時切換僅套用於該工作階段，不會儲存為您的預設值。`-p` 形式需要 Claude Code v2.1.205 或更新版本。在其他非互動模式情況下，該命令會回報快速模式無法使用。

43 43

48當您使用 `/fast` 啟用快速模式時：48當您使用 `/fast` 啟用快速模式時：

49 49

50* 如果您目前的模型不支援快速模式，Claude Code 會切換至 Opus50* 如果您目前的模型不支援快速模式，Claude Code 會切換至 Opus

51* 在 Fable 5.2 上使用快速模式需要 Claude Code v2.1.321 或更新版本

51* 您會看到確認訊息："Fast mode ON"52* 您會看到確認訊息："Fast mode ON"

52* 快速模式啟用期間，提示詞旁會出現一個小型 `↯` 圖示53* 快速模式啟用期間，提示詞旁會出現一個小型 `↯` 圖示

53* 隨時再次執行 `/fast` 即可檢查快速模式是開啟還是關閉54* 隨時再次執行 `/fast` 即可檢查快速模式是開啟還是關閉

54 55

55在 Claude Code v2.1.280 及更新版本中，Opus 5.5 是快速模式的預設模型。在 v2.1.280 之前，從 v2.1.219 起快速模式預設使用 Opus 5。56在 Claude Code v2.1.280 及更新版本中，Opus 5.5 是快速模式的預設模型。在 v2.1.280 之前，從 v2.1.219 起快速模式預設使用 Opus 5。

56 57

~~57當您再次使用 `/fast` 停用快速模式時，您會繼續使用 Opus。若要切換至其他模型，請使用 `/model`。~~58當您再次使用 `/fast` 停用快速模式時，您會繼續使用目前的模型。若要切換至其他模型，請使用 `/model`。

58 59

59### 在快速模式開啟時切換模型60### 在快速模式開啟時切換模型

60 61

~~61快速模式會雙向跟隨您的模型切換：~~62快速模式會跟隨您的模型切換：

62 63

63* **切換離開**：當您切換至不支援快速模式的模型時，Claude Code 會關閉快速模式。這包括 Opus 4.7；在 v2.1.221 之前，切換至 Opus 4.7 後快速模式仍保持開啟，且 API 會拒絕這些請求。64* **切換離開**：當您切換至不支援快速模式的模型時，Claude Code 會關閉快速模式。這包括 Opus 4.7；在 v2.1.221 之前，切換至 Opus 4.7 後快速模式仍保持開啟，且 API 會拒絕這些請求。

64* **切換回來**：當您儲存的快速模式偏好設定為開啟時（即新工作階段預設採用的相同偏好設定），切換回受支援的 Opus 模型會再次開啟快速模式。對於已儲存偏好設定為關閉的工作階段，模型切換絕不會開啟快速模式；若已設定[每個工作階段選擇加入](#require-per-session-opt-in)，切換回來也不會開啟快速模式；請執行 `/fast` 重新啟用。65* **切換回來**：當您儲存的偏好設定為開啟時，快速模式會在受支援的 Opus 模型上重新開啟。若已設定[每個工作階段選擇加入](#require-per-session-opt-in)，請改為執行 `/fast`。

66* **切換至 Fable 5.2**：除非您在使用 Fable 5.2 時開啟了快速模式，否則快速模式會關閉。若要開啟，請在 Fable 5.2 上執行 `/fast`。除非您已設定[每個工作階段選擇加入](#require-per-session-opt-in)，否則此設定會跨工作階段保留，直到您將其關閉，或在其他模型上將其開啟為止。

65 67

66每當模型切換開啟或關閉快速模式時，Claude Code 都會顯示 `Fast mode ON` 或 `Fast mode OFF` 確認訊息，且快速模式開啟期間會出現 `↯` 圖示。無論您是使用 `/model`、使用 [`/config model=<model>`](https://code.claude.com/docs/zh-TW/settings)，還是從透過 [Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md) 連線的裝置進行切換，皆是如此。68每當模型切換開啟或關閉快速模式時，Claude Code 都會顯示 `Fast mode ON` 或 `Fast mode OFF` 確認訊息，且快速模式開啟期間會出現 `↯` 圖示。無論您是使用 `/model`、使用 [`/config model=<model>`](https://code.claude.com/docs/zh-TW/settings)，還是從透過 [Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md) 連線的裝置進行切換，皆是如此。

67 69

77 79

78## 了解成本權衡80## 了解成本權衡

79 81

~~80快速模式的每個 token 定價高於標準 Opus：~~82快速模式的每個 token 定價高於標準速度：

81 83

82| 模型 | 輸入 (MTok) | 輸出 (MTok) |84| 模型 | 輸入 (MTok) | 輸出 (MTok) |

83| - | - | - |85| - | - | - |

86| Fable 5.2 | \$16 | \$80 |

84| Opus 5.5 | \$8 | \$40 |87| Opus 5.5 | \$8 | \$40 |

85| Opus 5 | \$10 | \$50 |88| Opus 5 | \$10 | \$50 |

86| Opus 4.8 | \$10 | \$50 |89| Opus 4.8 | \$10 | \$50 |

87 90

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

89 92

90當您在對話中首次啟用快速模式時，您需要為整個對話上下文支付完整的快速模式未快取輸入 token 價格。對話進行得越深入，這筆費用就越高，因此在對話開始時就啟用快速模式，這筆費用最低。快速模式與標準速度會保留[各自獨立的快取](https://code.claude.com/docs/zh-TW/prompt-caching.md#turning-on-fast-mode)，因此之後每次切換時，都會再次以未快取方式讀取部分或全部對話內容。93當您在對話中首次啟用快速模式時，您需要為整個對話上下文支付完整的快速模式未快取輸入 token 價格。對話進行得越深入，這筆費用就越高，因此在對話開始時就啟用快速模式，這筆費用最低。快速模式與標準速度會保留[各自獨立的快取](https://code.claude.com/docs/zh-TW/prompt-caching.md#turning-on-fast-mode)，因此之後每次切換時，都會再次以未快取方式讀取部分或全部對話內容。

91 94

137 140

138* **付費 Console 組織**：Claude Console 帳戶不使用使用額度，您的組織按令牌為快速模式付費，與其餘 API 使用量一起。在 Console 的免費評估方案上，`/fast` 顯示「評估期間快速模式不可用。請購買額度。」若要清除它，請在您的 [Console 計費設定](https://platform.claude.com/settings/billing)中購買額度。141* **付費 Console 組織**：Claude Console 帳戶不使用使用額度，您的組織按令牌為快速模式付費，與其餘 API 使用量一起。在 Console 的免費評估方案上，`/fast` 顯示「評估期間快速模式不可用。請購買額度。」若要清除它，請在您的 [Console 計費設定](https://platform.claude.com/settings/billing)中購買額度。

139 142

140 在 Opus 5.5 上使用快速模式也取決於您組織的[使用層級](https://platform.claude.com/docs/en/api/rate-limits)。143 在 Fable 5.2 或 Opus 5.5 上使用快速模式也取決於您組織的[使用層級](https://platform.claude.com/docs/en/api/rate-limits)。

141* **Team 和 Enterprise 的擁有者啟用**：快速模式在預設情況下對 Team 和 Enterprise 組織停用。擁有者必須明確[啟用快速模式](#enable-fast-mode-for-your-organization)，使用者才能存取它。144* **Team 和 Enterprise 的擁有者啟用**：快速模式在預設情況下對 Team 和 Enterprise 組織停用。擁有者必須明確[啟用快速模式](#enable-fast-mode-for-your-organization)，使用者才能存取它。

142 145

143> [!NOTE]146> [!NOTE]

147> * **快速模式未啟用**：如果尚未為您的組織啟用快速模式，使用 `/fast` 開啟快速模式會顯示「快速模式已被您的組織停用。」150> * **快速模式未啟用**：如果尚未為您的組織啟用快速模式，使用 `/fast` 開啟快速模式會顯示「快速模式已被您的組織停用。」

148> * **快速模式被受管設定關閉**：如果您的組織部署[受管設定](https://code.claude.com/docs/zh-TW/managed-settings.md)，設定 [`fastMode: false`](https://code.claude.com/docs/zh-TW/settings-reference#fastmode)，使用 `/fast` 開啟快速模式會顯示相同的「快速模式已被您的組織停用」訊息。151> * **快速模式被受管設定關閉**：如果您的組織部署[受管設定](https://code.claude.com/docs/zh-TW/managed-settings.md)，設定 [`fastMode: false`](https://code.claude.com/docs/zh-TW/settings-reference#fastmode)，使用 `/fast` 開啟快速模式會顯示相同的「快速模式已被您的組織停用」訊息。

149> * **需要每個工作階段的選擇加入**：設定 [`fastModePerSessionOptIn: true`](#require-per-session-opt-in) 的受管設定會在除了互動式終端工作階段以外的所有地方拒絕 `/fast on`，顯示相同的訊息。152> * **需要每個工作階段的選擇加入**：設定 [`fastModePerSessionOptIn: true`](#require-per-session-opt-in) 的受管設定會在除了互動式終端工作階段以外的所有地方拒絕 `/fast on`，顯示相同的訊息。

150> * **快速模式模型不允許**：如果您組織的 [`availableModels`](https://code.claude.com/docs/zh-TW/model-config#restrict-model-selection) 允許清單排除快速模式 Opus 模型，開啟它會被拒絕，顯示「不在您組織的允許模型中」。在已在支援快速模式的允許 Opus 模型上執行的工作階段中，`/fast` 改為在您目前的模型上啟用快速模式，而不是切換模型。153> * **快速模式模型不允許**：如果您組織的 [`availableModels`](https://code.claude.com/docs/zh-TW/model-config#restrict-model-selection) 允許清單排除快速模式 Opus 模型，開啟它會被拒絕，顯示「不在您組織的允許模型中」。在已在支援快速模式的允許模型上執行的工作階段中，`/fast` 改為在您目前的模型上啟用快速模式，而不是切換模型。

151 154

152### 為您的組織啟用快速模式155### 為您的組織啟用快速模式

153 156

196 199

197### 需要每個工作階段的選擇加入200### 需要每個工作階段的選擇加入

198 201

199預設情況下，使用者在互動式工作階段中開啟的快速模式會在支援的模型上跨工作階段持續。若要變更此設定，請在任何[設定檔](https://code.claude.com/docs/zh-TW/settings.md#where-settings-live)中將 `fastModePerSessionOptIn` 設定為 `true`，這會導致每個工作階段以快速模式關閉開始，並要求使用者使用 `/fast` 明確啟用它。[Team](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_teams#team-&-enterprise) 或 [Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_enterprise) 方案上的擁有者可以透過[伺服器管理的設定](https://code.claude.com/docs/zh-TW/server-managed-settings.md)在整個組織範圍內部署它。202預設情況下，使用者在互動式工作階段中開啟的快速模式會在支援的模型上跨工作階段持續。在 Fable 5.2 上，只有當使用者[在使用 Fable 5.2 時開啟它](#switch-models-while-fast-mode-is-on)，它才會持續。

203

204若要讓每個工作階段都以快速模式關閉開始，請在任何[設定檔](https://code.claude.com/docs/zh-TW/settings.md#where-settings-live)中將 `fastModePerSessionOptIn` 設定為 `true`。使用者接著需要在每個工作階段中使用 `/fast` 啟用它。[Team](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_teams#team-&-enterprise) 或 [Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_enterprise) 方案上的擁有者可以透過[伺服器管理的設定](https://code.claude.com/docs/zh-TW/server-managed-settings.md)在整個組織範圍內部署它。

200 205

201```json theme={null}206```json theme={null}

202{207{

210 215

211## 處理速率限制216## 處理速率限制

212 217

213快速模式與標準 Opus 有不同的速率限制；對於 Console 組織，Claude Platform 的[速率限制](https://platform.claude.com/docs/en/api/rate-limits)頁面中有相關說明。當您達到快速模式速率限制時：218快速模式與標準速度有不同的速率限制；對於 Console 組織，Claude Platform 的[速率限制](https://platform.claude.com/docs/en/api/rate-limits)頁面中有相關說明。當您達到快速模式速率限制時：

214 219

2151. 快速模式自動回退到標準速度2201. 快速模式自動回退到標準速度

2162. `↯` 圖示變灰以指示冷卻2212. `↯` 圖示變灰以指示冷卻

hooks.md +12 −4

Details

1089 1089

1090#### 發出終端機通知1090#### 發出終端機通知

1091 1091

1092Hook 在沒有控制終端機的情況下執行，因此直接將逃逸序列寫入 `/dev/tty` 會失敗。相反，在 `terminalSequence` 欄位中返回逃逸序列，Claude Code 會透過其自己的終端機寫入路徑為您發出它。這不會產生競爭狀況，在 tmux 和 GNU screen 內有效，並在沒有 `/dev/tty` 的 Windows 上有效。1092Hook 在沒有控制終端機的情況下執行，因此直接將逃逸序列寫入 `/dev/tty` 會失敗。相反，在 `terminalSequence` 欄位中返回逃逸序列，Claude Code 會透過其自己的終端機寫入路徑為您發出它。這不會產生競爭狀況，並在沒有 `/dev/tty` 的 Windows 上有效。

1093 1093

1094該欄位接受由一個或多個允許清單中逃逸序列組成的字串：1094該欄位接受由一個或多個允許清單中逃逸序列組成的字串：

1095 1095

1101 1101

1102序列可以用 BEL 或 ST 終止。允許清單外的任何內容，包括 CSI 游標和顏色序列、OSC 調色盤序列、OSC 8 超連結、OSC 52 剪貼簿寫入和 OSC 1337，都會被拒絕，該欄位將被忽略。1102序列可以用 BEL 或 ST 終止。允許清單外的任何內容，包括 CSI 游標和顏色序列、OSC 調色盤序列、OSC 8 超連結、OSC 52 剪貼簿寫入和 OSC 1337，都會被拒絕，該欄位將被忽略。

1103 1103

1104Claude Code 在處理您的 hook 輸出時自行寫入序列，因此該欄位在捨棄 `systemMessage` 和 `continue` 的事件上也有效，例如 `Notification` 和 `StopFailure`。它有兩個限制：1104Claude Code 在處理您的 hook 輸出時自行寫入序列，因此該欄位在捨棄 `systemMessage` 和 `continue` 的事件上也有效，例如 `Notification` 和 `StopFailure`。它有一些限制：

1105 1105

1106* Claude Code 僅在互動式工作階段中寫入序列，且僅在其介面顯示於螢幕上時。在使用 `-p` 旗標的非互動模式和 Agent SDK 中，它忽略該欄位。1106* Claude Code 僅在互動式工作階段中寫入序列，且僅在其介面開啟時。在使用 `-p` 旗標的非互動模式和 Agent SDK 中，它忽略該欄位。

1107* 該欄位僅在不於 [背景](#run-hooks-in-the-background) 執行的 hook 中有效，因此請勿開啟 `async` 和 `asyncRewake`。

1107* `WorktreeCreate` 命令 hook 無法返回 JSON，因為 Claude Code 將其 stdout 讀取為 worktree 路徑。HTTP `WorktreeCreate` hook 返回 JSON 並可以包含該欄位。1108* `WorktreeCreate` 命令 hook 無法返回 JSON，因為 Claude Code 將其 stdout 讀取為 worktree 路徑。HTTP `WorktreeCreate` hook 返回 JSON 並可以包含該欄位。

1108 1109

1109下面的範例從 `Notification` hook 觸發桌面通知。逃逸序列使用 `printf` 八進位逃逸建立，因此控制位元組永遠不會出現在 shell 命令列上，並以 `jq -n --arg` 建立 JSON 輸出，因此通知訊息中的引號、反斜線和換行符號會被正確逃逸：1110如果您使用 tmux 或 GNU screen，請先完成[它們的設定](#get-terminal-notifications-inside-tmux-or-gnu-screen)。下面的範例在可讀取 OSC `777` 的終端機（例如 Ghostty 或 Warp）中，從 `Notification` hook 觸發桌面通知。指令碼的 `jq -nc --arg` 呼叫會建立 JSON 輸出，並逃逸通知訊息中的任何引號、反斜線和換行符號：

1110 1111

1111```bash theme={null}1112```bash theme={null}

1112#!/bin/bash1113#!/bin/bash

1120 1121

1121`{ "terminalSequence": "..." }` 形式在任何 shell 或語言中都相同。1122`{ "terminalSequence": "..." }` 形式在任何 shell 或語言中都相同。

1122 1123

1124#### 在 tmux 或 GNU screen 內取得終端機通知

1125

1126當 Claude Code 在 tmux 或 GNU screen 內執行時，OSC 序列需要以下設定才能到達您的終端機應用程式：

1127

1128* **tmux 3.3 或更新版本**：將 `set -g allow-passthrough on` 新增至 `~/.tmux.conf`，然後從 shell 執行 `tmux source-file ~/.tmux.conf`。此選項適用於這些窗格中的每個程式，而不僅是 Claude Code。使用 `on` 時，只有 tmux 正在顯示的窗格可以傳送序列。若也要讓您所附加之工作階段中的其他窗格傳送序列，請在 tmux 3.4 或更新版本上使用 `all` 取代 `on`。

1129* **GNU screen**：讓 Claude Code 的視窗在 screen 中保持顯示，因為來自背景視窗的序列不會到達您的終端機應用程式

1130

1123#### 為 Claude 新增上下文1131#### 為 Claude 新增上下文

1124 1132

1125`additionalContext` 欄位將字串從您的 hook 傳遞到 Claude 的上下文視窗。Claude Code 將字串包裝在 [系統提醒](https://code.claude.com/docs/zh-TW/glossary.md#system-reminder) 中，並將其插入到 hook 觸發時的對話位置。Claude 在下一個模型請求時讀取提醒，但它不會在介面中顯示為聊天訊息。1133`additionalContext` 欄位將字串從您的 hook 傳遞到 Claude 的上下文視窗。Claude Code 將字串包裝在 [系統提醒](https://code.claude.com/docs/zh-TW/glossary.md#system-reminder) 中，並將其插入到 hook 觸發時的對話位置。Claude 在下一個模型請求時讀取提醒，但它不會在介面中顯示為聊天訊息。

llm-gateway-protocol.md +1 −1

Details

223| 測試版[工具欄位](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) | 工具相關的測試版標頭與工具 schema 欄位（如 `strict` 和 `defer_loading`）配對 | 當請求體在沒有其標頭的情況下通過時，命名無法識別的工具 schema 欄位的 `400`。關於 `defer_loading`，請參閱[不使用工具搜尋重試](#retry-without-tool-search) | 轉發兩者，或 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](#disable-pre-release-capabilities) |223| 測試版[工具欄位](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) | 工具相關的測試版標頭與工具 schema 欄位（如 `strict` 和 `defer_loading`）配對 | 當請求體在沒有其標頭的情況下通過時，命名無法識別的工具 schema 欄位的 `400`。關於 `defer_loading`，請參閱[不使用工具搜尋重試](#retry-without-tool-search) | 轉發兩者，或 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](#disable-pre-release-capabilities) |

224| [努力](https://platform.claude.com/docs/en/build-with-claude/effort)和[結構化輸出](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) | `output_config` 請求體欄位攜帶努力、結構化輸出格式和任務預算設定；每個都與其自己的測試版標頭配對 | 在 Amazon Bedrock 和 Google Cloud 的 Agent Platform 上游上命名 `output_config` 的 `400`，通常是 `Extra inputs are not permitted` | 一起轉發欄位及其標頭，或讓開發人員設定 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](#disable-pre-release-capabilities)，這會移除格式和任務預算設定，但不會移除努力。若只要移除格式，他們可以改為設定 [`CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS=1`](https://code.claude.com/docs/zh-TW/env-vars)，這需要 v2.1.288 或更新版本 |224| [努力](https://platform.claude.com/docs/en/build-with-claude/effort)和[結構化輸出](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) | `output_config` 請求體欄位攜帶努力、結構化輸出格式和任務預算設定；每個都與其自己的測試版標頭配對 | 在 Amazon Bedrock 和 Google Cloud 的 Agent Platform 上游上命名 `output_config` 的 `400`，通常是 `Extra inputs are not permitted` | 一起轉發欄位及其標頭，或讓開發人員設定 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](#disable-pre-release-capabilities)，這會移除格式和任務預算設定，但不會移除努力。若只要移除格式，他們可以改為設定 [`CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS=1`](https://code.claude.com/docs/zh-TW/env-vars)，這需要 v2.1.288 或更新版本 |

225| 對話中途的系統訊息 | 無測試版標頭。Claude Code 針對 Claude Opus 4.8、在其之後發布的模型以及無法識別的模型 ID，將部分提醒和附件文字作為 `messages` 中的 `role: "system"` 項目發送 | `400`，例如 `Unexpected role "system"` | Claude Code 會[在不含系統訊息的情況下重試](#automatic-retry-and-error-forwarding)。若要在 Claude Opus 4.8 之前發布之模型的別名上停止系統訊息，請在您分發的設定中新增 [`modelOverrides` 項目](#settings-for-unrecognized-model-ids) |225| 對話中途的系統訊息 | 無測試版標頭。Claude Code 針對 Claude Opus 4.8、在其之後發布的模型以及無法識別的模型 ID，將部分提醒和附件文字作為 `messages` 中的 `role: "system"` 項目發送 | `400`，例如 `Unexpected role "system"` | Claude Code 會[在不含系統訊息的情況下重試](#automatic-retry-and-error-forwarding)。若要在 Claude Opus 4.8 之前發布之模型的別名上停止系統訊息，請在您分發的設定中新增 [`modelOverrides` 項目](#settings-for-unrecognized-model-ids) |

226| [每回合設定的努力](https://code.claude.com/docs/zh-TW/prompt-caching.md#changing-effort-level) | 在 Opus 5.5、Sonnet 5.5、Haiku 5.5 和 Fable 5.1 上，測試版標頭與 `role: "system"` 項目上的 `output_config.effort` 配對，該項目可以是系統訊息，也可以是內容為空的項目 | 當您的閘道從空項目中移除該欄位時，出現 `400` 並顯示 `messages.N: system content must contain at least one block` | 轉發兩者，或讓開發人員設定 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](#disable-pre-release-capabilities) 以停止發送該欄位和空項目 |226| [每回合設定的努力](https://code.claude.com/docs/zh-TW/prompt-caching.md#changing-effort-level) | 在 Opus 5.5、Sonnet 5.5、Haiku 5.5、Fable 5.2 和 Fable 5.1 上，測試版標頭與 `role: "system"` 項目上的 `output_config.effort` 配對，該項目可以是系統訊息，也可以是內容為空的項目 | 當您的閘道從空項目中移除該欄位時，出現 `400` 並顯示 `messages.N: system content must contain at least one block` | 轉發兩者，或讓開發人員設定 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](#disable-pre-release-capabilities) 以停止發送該欄位和空項目 |

227| [提示詞快取](https://code.claude.com/docs/zh-TW/prompt-caching.md) | 無測試版配對。Claude Code 將 `cache_control` 標記附加到 `system` 區塊和 `messages` 項目，包括在對話中途附加的 `role: "system"` 項目 | 無錯誤：對話在每個回合上都計費為未快取的輸入，在 `usage` 中可見為高 `input_tokens` 且很少或沒有快取活動 | 無論在何處出現，都逐字轉發 `cache_control`，並且不要將區塊形式的 `system` 或訊息內容轉換為純字串 |227| [提示詞快取](https://code.claude.com/docs/zh-TW/prompt-caching.md) | 無測試版配對。Claude Code 將 `cache_control` 標記附加到 `system` 區塊和 `messages` 項目，包括在對話中途附加的 `role: "system"` 項目 | 無錯誤：對話在每個回合上都計費為未快取的輸入，在 `usage` 中可見為高 `input_tokens` 且很少或沒有快取活動 | 無論在何處出現，都逐字轉發 `cache_control`，並且不要將區塊形式的 `system` 或訊息內容轉換為純字串 |

229 229

model-config.md +53 −24

Details

30| 模型別名 | 行為 |30| 模型別名 | 行為 |

31| - | - |31| - | - |

32| **`default`** | 特殊值，會清除任何模型覆寫並還原為[您帳戶的執行階段預設值](#default-model-setting)。其本身並非模型別名 |32| **`default`** | 特殊值，會清除任何模型覆寫並還原為[您帳戶的執行階段預設值](#default-model-setting)。其本身並非模型別名 |

34| **`fable`** | 使用[您供應商的 Fable 模型](#fable-alias-resolution)處理最困難且執行時間最長的任務 |34| **`fable`** | 使用[您供應商的 Fable 模型](#fable-alias-resolution)處理最困難且執行時間最長的任務 |

35| **`sonnet`** | 使用最新的 Sonnet 模型處理日常程式設計任務 |35| **`sonnet`** | 使用最新的 Sonnet 模型處理日常程式設計任務 |

36| **`opus`** | 使用最新的 Opus 模型處理複雜的推理任務 |36| **`opus`** | 使用最新的 Opus 模型處理複雜的推理任務 |

50 50

51除非您設定了 `ANTHROPIC_DEFAULT_FABLE_MODEL`，否則 `fable` 別名會解析為 Fable 5.1，但在 [Claude apps gateway](https://code.claude.com/docs/zh-TW/claude-apps-gateway) 工作階段中例外，此時 `fable` 和 `best` 會解析為 Fable 5。51除非您設定了 `ANTHROPIC_DEFAULT_FABLE_MODEL`，否則 `fable` 別名在 [Claude apps gateway](https://code.claude.com/docs/zh-TW/claude-apps-gateway) 工作階段中會解析為 Fable 5，在其他所有情況下則解析為 Fable 5.2。

52 52

~~53未設定為提供 `claude-fable-5-1` 的閘道會拒絕對該模型的請求。若要透過提供該模型的閘道使用 Fable 5.1，請使用 `/model claude-fable-5-1` 選擇它。~~53未設定為提供 `claude-fable-5-2` 的閘道會拒絕對該模型的請求。若要透過提供該模型的閘道使用 Fable 5.2，請使用 `/model claude-fable-5-2` 選擇它。

54 54

55當 `opus` 或 `sonnet` 解析為較舊的模型時，您可以明確選擇完整模型名稱，或設定 `ANTHROPIC_DEFAULT_OPUS_MODEL` 或 `ANTHROPIC_DEFAULT_SONNET_MODEL` 來使用較新的模型。55當 `opus` 或 `sonnet` 解析為較舊的模型時，您可以明確選擇完整模型名稱，或設定 `ANTHROPIC_DEFAULT_OPUS_MODEL` 或 `ANTHROPIC_DEFAULT_SONNET_MODEL` 來使用較新的模型。

56 56

64 64

65### 使用 Fable65### 使用 Fable

66 66

67[Claude Fable 5.1](https://platform.claude.com/docs/en/about-claude/models/overview) 和 Claude Fable 5 是 Claude Code 中能力最強的模型，適合無法一次完成的大型任務。它們能維持長時間的自主工作階段，在行動前先進行調查，並且比較小的模型更頻繁地驗證自己的工作。Fable 5.1 是較新的版本。67[Claude Fable 模型](https://platform.claude.com/docs/en/about-claude/models/overview)是 Claude Code 中能力最強的模型，適合無法一次完成的大型任務。它們能維持長時間的自主工作階段，在行動前先進行調查，並且比較小的模型更頻繁地驗證自己的工作。

68 68

~~69在任何方案或供應商上，這兩個 Fable 模型都不是帳戶類型的預設模型。請明確選擇其中之一：~~69在任何方案或供應商上，沒有任何 Fable 模型是帳戶類型的預設模型。請明確選擇其中之一：

70 70

71* **Fable 5.1**：執行 `/model fable`，或以 `claude --model fable` 啟動。在 [Claude apps gateway](https://code.claude.com/docs/zh-TW/claude-apps-gateway) 工作階段中，由於別名會解析為 Fable 5，請改為執行 `/model claude-fable-5-1`。71* **Fable 5.2**：執行 `/model fable`，或以 `claude --model fable` 啟動。在 [Claude apps gateway](https://code.claude.com/docs/zh-TW/claude-apps-gateway) 工作階段中，請改為執行 `/model claude-fable-5-2`。

72* **Fable 5**：透過模型 ID 選擇。在 Anthropic API 上，執行 `/model claude-fable-5` 或以 `claude --model claude-fable-5` 啟動。在其他供應商上，請使用您供應商的 Fable 5 模型 ID，或使用 `ANTHROPIC_DEFAULT_FABLE_MODEL` [固定它](#pin-models-for-third-party-deployments)。72* **Fable 5.1 或 Fable 5**：透過模型 ID 選擇。在 Anthropic API 上，執行 `/model claude-fable-5-1` 或 `/model claude-fable-5`，或以 `claude --model claude-fable-5-1` 啟動。在其他供應商上，請使用您供應商的模型 ID，或使用 `ANTHROPIC_DEFAULT_FABLE_MODEL` [固定它](#pin-models-for-third-party-deployments)。

73 73

74如果您直接連線至 Anthropic API，且您的使用者設定將 `claude-fable-5` 或 `claude-fable-5[1m]` 保存為模型（例如因為您在 v2.1.257 之前於 `/model` 選擇器中選擇了 Fable），Claude Code 會在您首次執行 v2.1.257 或更新版本時，將該已儲存的值變更為 `fable` 或 `fable[1m]` 別名。啟動時的模型列會顯示一次 `(auto-updated)`。專案、本機或受管設定中的 `claude-fable-5` 值則維持不變。74在 Pro、Max、Team 和 Enterprise 方案中，儲存在您使用者設定中的 `claude-fable-5-1` 模型會移轉至 `fable` 別名：

76* **Pro 或 Max 方案**：此移轉會在您首次執行 v2.1.321 或更新版本時發生。在終端機中，啟動時的模型列可能會顯示一次 `(auto-updated)`。

77* **Team 或 Enterprise 方案**：此移轉會等待您組織的設定，因此可能在之後的某次啟動時才發生，或完全不會發生。它會從下一個工作階段起套用，且不會顯示 `(auto-updated)` 列。若要檢查您的模型，請執行 `/model`。

79移轉之後，工作階段會以 Fable 5.2 的預設 effort 啟動，除非您已為其[設定等級](#adjust-effort-level)。Console 帳戶、第三方供應商，以及專案、本機或受管設定會保留 `claude-fable-5-1`。

75 80

76被 Fable 模型的安全分類器標記的請求（最常見於網路安全和生物學領域）會觸發[自動模型備援](#automatic-model-fallback)。81被 Fable 模型的安全分類器標記的請求（最常見於網路安全和生物學領域）會觸發[自動模型備援](#automatic-model-fallback)。

77 82

84 89

85> [!NOTE]90> [!NOTE]

86>91>

87> Fable 5.1 需要 Claude Code v2.1.257 或更新版本。如果從較舊版本對其發出的請求失敗，請參閱 [Claude Code does not support this model](https://code.claude.com/docs/zh-TW/errors.md#claude-code-does-not-support-this-model)。執行 `claude update` 進行升級。關於零資料保留下的可用性，請參閱 [ZDR 下的模型可用性](https://code.claude.com/docs/zh-TW/zero-data-retention.md#model-availability-under-zdr)。92> Fable 5.2 需要 Claude Code v2.1.321 或更新版本，Fable 5.1 需要 v2.1.257 或更新版本。如果從較舊版本對其中任一模型發出的請求失敗，請參閱 [Claude Code does not support this model](https://code.claude.com/docs/zh-TW/errors.md#claude-code-does-not-support-this-model)。執行 `claude update` 進行升級。關於零資料保留下的可用性，請參閱 [ZDR 下的模型可用性](https://code.claude.com/docs/zh-TW/zero-data-retention.md#model-availability-under-zdr)。

88 93

89在 Anthropic API 上，Fable 模型會出現在 `/model` 選擇器中，除非 [`availableModels`](#restrict-model-selection) 或[組織模型限制](#organization-model-restrictions)將其排除。當您的組織完全無法使用 Fable 時（例如在[零資料保留](https://code.claude.com/docs/zh-TW/zero-data-retention.md#model-availability-under-zdr)下），該列仍會以灰色顯示於選擇器中，並附上原因說明。94在 Anthropic API 上，Fable 模型會出現在 `/model` 選擇器中，除非 [`availableModels`](#restrict-model-selection) 或[組織模型限制](#organization-model-restrictions)將其排除。當您的組織完全無法使用 Fable 時（例如在[零資料保留](https://code.claude.com/docs/zh-TW/zero-data-retention.md#model-availability-under-zdr)下），該列仍會以灰色顯示於選擇器中，並附上原因說明。

90 95

163 168

164關於相關訊息，請參閱 [Model is not a recognized model id](https://code.claude.com/docs/zh-TW/errors.md#model-is-not-a-recognized-model-id) 和 [Model not found](https://code.claude.com/docs/zh-TW/errors.md#model-not-found)。169關於相關訊息，請參閱 [Model is not a recognized model id](https://code.claude.com/docs/zh-TW/errors.md#model-is-not-a-recognized-model-id) 和 [Model not found](https://code.claude.com/docs/zh-TW/errors.md#model-not-found)。

165 170

166如果您以 `--model` 旗標、`ANTHROPIC_MODEL` 環境變數或 `model` 設定來設定模型，Claude Code 不會事先檢查，輸入錯誤的值會在第一次請求時產生 [There's an issue with the selected model](https://code.claude.com/docs/zh-TW/errors.md#theres-an-issue-with-the-selected-model)。171如果您以 `--model` 旗標、`ANTHROPIC_MODEL` 環境變數或 `model` 設定來設定模型，Claude Code 不會事先拒絕輸入錯誤的值。工作階段會正常啟動，而第一次請求會產生 [There's an issue with the selected model](https://code.claude.com/docs/zh-TW/errors.md#theres-an-issue-with-the-selected-model)。在 Anthropic API 上，不以 `claude-` 開頭且拼寫與某個模型名稱或別名相近的值，也可能產生[建議正確名稱的啟動警告](#fix-a-mistyped-model-name)。

167 172

168當所請求的模型有預定的停用日期，或會自動重新對應至較新版本時，Claude Code 會顯示一則指出所請求模型的警告。互動式工作階段會將其顯示為啟動通知。自 v2.1.182 起，在使用預設文字輸出格式時，相同的警告也會在[非互動模式](https://code.claude.com/docs/zh-TW/headless.md)中寫入 stderr。此檢查也涵蓋在 [subagent frontmatter](https://code.claude.com/docs/zh-TW/sub-agents.md) 中設定的 `model`。對於 `--output-format json` 和 `stream-json`，stderr 警告會被隱藏；請改從[結果訊息](https://code.claude.com/docs/zh-TW/headless.md#get-structured-output)的 `modelUsage` 欄位讀取實際模型。173當所請求的模型有預定的停用日期，或會自動重新對應至較新版本時，Claude Code 會顯示一則指出所請求模型的警告。互動式工作階段會將其顯示為啟動通知。自 v2.1.182 起，在使用預設文字輸出格式時，相同的警告也會在[非互動模式](https://code.claude.com/docs/zh-TW/headless.md)中寫入 stderr。此檢查也涵蓋在 [subagent frontmatter](https://code.claude.com/docs/zh-TW/sub-agents.md) 中設定的 `model`。對於 `--output-format json` 和 `stream-json`，stderr 警告會被隱藏；請改從[結果訊息](https://code.claude.com/docs/zh-TW/headless.md#get-structured-output)的 `modelUsage` 欄位讀取實際模型。

169 174

225 230

226## 限制模型選擇231## 限制模型選擇

227 232

228管理員可以在[受管設定或政策設定](https://code.claude.com/docs/zh-TW/managed-settings.md)中使用 `availableModels` 來限制使用者可以選擇的模型。項目可比對模型系列（例如 `sonnet`）、版本前綴（例如 `claude-sonnet-4-5`），或完整模型 ID（例如 `claude-sonnet-4-5-20250929`）。版本前綴也會比對以另一個區段延伸該前綴的後續模型 ID，因此 `claude-fable-5` 同時允許 Fable 5 與 Fable 5.1，而 `claude-fable-5-1` 僅允許 Fable 5.1。若要封鎖清單所允許的某個模型，或讓每個模型 ID 項目僅允許其所指定的版本，請參閱[封鎖特定模型或版本](#block-specific-models-or-versions)。233管理員可以在[受管設定或政策設定](https://code.claude.com/docs/zh-TW/managed-settings.md)中使用 `availableModels` 來限制使用者可以選擇的模型。每個項目會比對下列其中一種：

234

235* 模型系列，例如 `sonnet`

236* 版本前綴，例如 `claude-sonnet-4-5`。它也會比對以另一個區段延伸該前綴的後續模型 ID。例如，`claude-fable-5` 允許 Fable 5、Fable 5.1 與 Fable 5.2，而 `claude-fable-5-1` 僅允許 Fable 5.1

237* 完整模型 ID，例如 `claude-sonnet-4-5-20250929`

238

239若要封鎖清單所允許的某個模型，或讓每個模型 ID 項目僅允許其所指定的版本，請參閱[封鎖特定模型或版本](#block-specific-models-or-versions)。

229 240

230在內嵌 Claude Code 並設定 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](https://code.claude.com/docs/zh-TW/env-vars) 的平台上，主機的模型設定優先於受管模型設定，而受管的 `availableModels` 允許清單仍然有效，除非主機提供自己的允許清單；[受管設定優先順序的例外](https://code.claude.com/docs/zh-TW/settings.md#exceptions-to-managed-settings-precedence)說明主機會覆寫哪些設定鍵與變數。241在內嵌 Claude Code 並設定 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](https://code.claude.com/docs/zh-TW/env-vars) 的平台上，主機的模型設定優先於受管模型設定，而受管的 `availableModels` 允許清單仍然有效，除非主機提供自己的允許清單；[受管設定優先順序的例外](https://code.claude.com/docs/zh-TW/settings.md#exceptions-to-managed-settings-precedence)說明主機會覆寫哪些設定鍵與變數。

231 242

465 476

466當您的帳戶上沒有記錄任何模型、受管設定[對 Default 模型強制執行允許清單](#enforce-the-allowlist-for-the-default-model)，且帳戶類型預設值不在 `availableModels` 中時，`default` 會解析為強制執行的 Default，而非上述的帳戶類型預設值。當組織預設值與強制執行同時適用時，組織預設值會先取代帳戶類型預設值，接著再對其套用強制執行：位於允許清單內的組織預設值會保留，而不在清單內的則會解析為強制執行的 Default。477當您的帳戶上沒有記錄任何模型、受管設定[對 Default 模型強制執行允許清單](#enforce-the-allowlist-for-the-default-model)，且帳戶類型預設值不在 `availableModels` 中時，`default` 會解析為強制執行的 Default，而非上述的帳戶類型預設值。當組織預設值與強制執行同時適用時，組織預設值會先取代帳戶類型預設值，接著再對其套用強制執行：位於允許清單內的組織預設值會保留，而不在清單內的則會解析為強制執行的 Default。

467 478

468在任何方案或供應商上，Fable 模型都不是帳戶類型預設值。使用 `/model` 選擇其中一個模型時，會將其儲存為您使用者設定中的所選模型，因此之後的工作階段都會以該模型啟動。關於 Claude Code 在 v2.1.257 中對已儲存的 Fable 5 選擇所做的一次性變更，請參閱[使用 Fable](#work-with-fable)。479> [!NOTE]

480>

481> 在任何方案或供應商上，Fable 模型都不是帳戶類型預設值。使用 `/model` 選擇其中一個模型時，會將其儲存為您使用者設定中的所選模型，因此之後的工作階段都會以該模型啟動，但[對已儲存的 Fable 5.1 選擇所做的一次性變更](#work-with-fable)除外。

469 482

470### `opusplan` 模型設定483### `opusplan` 模型設定

471 484

521 534

522Fable 模型、Opus 5.5、Sonnet 5.5 和 Opus 5 會搭配安全分類器執行，這些分類器最常標記網路安全和生物學內容。對於這兩個類別，備援模型取決於拒絕的模型：535Fable 模型、Opus 5.5、Sonnet 5.5 和 Opus 5 會搭配安全分類器執行，這些分類器最常標記網路安全和生物學內容。對於這兩個類別，備援模型取決於拒絕的模型：

523 536

524* **Fable 5.1、Fable 5 和 Opus 5.5**：被標記為生物學的請求會在 Opus 5 上重新執行，被標記為網路安全的請求會在 Opus 4.8 上重新執行。537* **Fable 模型和 Opus 5.5**：被標記為生物學的請求會在 Opus 5 上重新執行，被標記為網路安全的請求會在 Opus 4.8 上重新執行。

525* **Sonnet 5.5**：被標記為網路安全的請求會在 Sonnet 5 上重新執行。被標記為生物學的請求則會以拒絕結束，因為 Sonnet 5.5 沒有生物學備援模型。538* **Sonnet 5.5**：被標記為網路安全的請求會在 Sonnet 5 上重新執行。被標記為生物學的請求則會以拒絕結束，因為 Sonnet 5.5 沒有生物學備援模型。

526* **Opus 5**：被標記為網路安全的請求會在 Opus 4.8 上重新執行。被標記為生物學的請求則會以拒絕結束，因為 Opus 5 執行自己的生物學分類器，且沒有備援模型。539* **Opus 5**：被標記為網路安全的請求會在 Opus 4.8 上重新執行。被標記為生物學的請求則會以拒絕結束，因為 Opus 5 執行自己的生物學分類器，且沒有備援模型。

527 540

582 595

583在 [Amazon Bedrock](https://code.claude.com/docs/zh-TW/amazon-bedrock.md)、[Google Cloud's Agent Platform](https://code.claude.com/docs/zh-TW/google-vertex-ai.md) 和 [Microsoft Foundry](https://code.claude.com/docs/zh-TW/microsoft-foundry.md) 上，模型 ID 是供應商專屬的，因此只有在 Claude Code 能識別所涉及的每個模型時，自動備援才會運作：596在 [Amazon Bedrock](https://code.claude.com/docs/zh-TW/amazon-bedrock.md)、[Google Cloud's Agent Platform](https://code.claude.com/docs/zh-TW/google-vertex-ai.md) 和 [Microsoft Foundry](https://code.claude.com/docs/zh-TW/microsoft-foundry.md) 上，模型 ID 是供應商專屬的，因此只有在 Claude Code 能識別所涉及的每個模型時，自動備援才會運作：

584 597

585* Claude Code 必須將目前模型識別為備援來源。當模型 ID 包含 `claude-fable-5`、符合 `ANTHROPIC_DEFAULT_FABLE_MODEL` 的值，或透過 [`modelOverrides`](#override-model-ids-per-version) 對應時，Fable 5.1 和 Fable 5 會被識別。Opus 5.5、Sonnet 5.5 和 Opus 5 則透過其供應商模型 ID 或 [`modelOverrides`](#override-model-ids-per-version) 對應來識別。598* Claude Code 必須將目前模型識別為備援來源。當模型 ID 包含 `claude-fable-5`、符合 `ANTHROPIC_DEFAULT_FABLE_MODEL` 的值，或透過 [`modelOverrides`](#override-model-ids-per-version) 對應時，Fable 模型會被識別。Opus 5.5、Sonnet 5.5 和 Opus 5 則透過其供應商模型 ID 或 [`modelOverrides`](#override-model-ids-per-version) 對應來識別。

586* 無論拒絕的是哪個模型，Opus 目標都必須能在您的部署中解析：設定 `ANTHROPIC_DEFAULT_OPUS_MODEL`，或在供應商的模型清單中保留 Opus 4.8 項目。若兩者皆無，所有來源模型（包括 Sonnet 5.5）的備援都會維持關閉，被標記的請求會以拒絕結束。599* 無論拒絕的是哪個模型，Opus 目標都必須能在您的部署中解析：設定 `ANTHROPIC_DEFAULT_OPUS_MODEL`，或在供應商的模型清單中保留 Opus 4.8 項目。若兩者皆無，所有來源模型（包括 Sonnet 5.5）的備援都會維持關閉，被標記的請求會以拒絕結束。

587* 被標記類別的備援模型必須能在您的部署中解析。從 Fable 模型、Opus 5.5 或 Opus 5 出發時，如果您設定了 `ANTHROPIC_DEFAULT_OPUS_MODEL`，被標記的請求會針對每個有備援的類別在該模型上重新執行；Opus 5 上的生物學標記仍會以拒絕結束。如果您未設定，被標記為網路安全的請求會在 Opus 4.8 項目上重新執行，而來自 Fable 模型或 Opus 5.5、被標記為生物學的請求則會在 Opus 5 項目上重新執行。從 Sonnet 5.5 出發時，被標記為網路安全的請求會在您於 `ANTHROPIC_DEFAULT_SONNET_MODEL` 中設定的模型上重新執行，若您未設定，則在供應商模型清單中的 Sonnet 5 項目上重新執行。600* 被標記類別的備援模型必須能在您的部署中解析。從 Fable 模型、Opus 5.5 或 Opus 5 出發時，如果您設定了 `ANTHROPIC_DEFAULT_OPUS_MODEL`，被標記的請求會針對每個有備援的類別在該模型上重新執行；Opus 5 上的生物學標記仍會以拒絕結束。如果您未設定，被標記為網路安全的請求會在 Opus 4.8 項目上重新執行，而來自 Fable 模型或 Opus 5.5、被標記為生物學的請求則會在 Opus 5 項目上重新執行。從 Sonnet 5.5 出發時，被標記為網路安全的請求會在您於 `ANTHROPIC_DEFAULT_SONNET_MODEL` 中設定的模型上重新執行，若您未設定，則在供應商模型清單中的 Sonnet 5 項目上重新執行。

588 601

596 609

597#### 安全研究與生物學工作負載610#### 安全研究與生物學工作負載

598 611

599攻擊性安全或生物學方面的工作負載，包括滲透測試、Capture the Flag (CTF) 練習和與生物學相關的程式碼庫，經常會觸發備援，而且通常在第一個請求就觸發。對於在 Fable 5.1、Fable 5 或 Opus 5.5 上進行的實質生物學工作，第一個會切換模型的被標記請求會將工作階段移至 Opus 5，之後被標記為生物學的請求會在那裡以拒絕結束，因為 Opus 5 沒有生物學備援。在 Opus 5 和 Sonnet 5.5 上，您從第一個被標記的請求開始就會收到這些拒絕。612攻擊性安全或生物學方面的工作負載，包括滲透測試、Capture the Flag (CTF) 練習和與生物學相關的程式碼庫，經常會觸發備援，而且通常在第一個請求就觸發。這是這些領域的預期路由，而非帳戶被標記。如果您的組織需要 Fable 等級的能力來進行此類工作，請向您的 Anthropic 客戶團隊詢問受信任存取計畫。

600 613

601這是這些領域的預期路由，而非帳戶被標記。如果您的組織需要 Fable 等級的能力來進行此類工作，請向您的 Anthropic 客戶團隊詢問受信任存取計畫。614對於在 Fable 模型或 Opus 5.5 上進行的實質生物學工作，第一個會切換模型的被標記請求會將工作階段移至 Opus 5。之後被標記為生物學的請求會在那裡以拒絕結束，因為 Opus 5 沒有生物學備援。在 Opus 5 和 Sonnet 5.5 上，這些拒絕從第一個被標記的請求就開始。

602 615

603### 調整 effort 等級616### 調整 effort 等級

604 617

608 621

609| 模型 | 等級 |622| 模型 | 等級 |

610| :- | :- |623| :- | :- |

614 627

6202. 您在工作階段中選擇的等級，例如透過 `/effort`、`/model` 選擇器或 [`applyFlagSettings()`](https://code.claude.com/docs/zh-TW/agent-sdk/typescript#applyflagsettings)6332. 您在工作階段中選擇的等級，例如透過 `/effort`、`/model` 選擇器或 [`applyFlagSettings()`](https://code.claude.com/docs/zh-TW/agent-sdk/typescript#applyflagsettings)

6213. 以 `--effort` 啟動6343. 以 `--effort` 啟動

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

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

624 637

625自動模型備援後適用的等級，請參閱[備援後的 effort 等級](#effort-level-after-a-fallback)。關於 subagent 和隊員，請參閱[Subagent 與隊員的 effort 等級](#effort-level-of-subagents-and-teammates)。638自動模型備援後適用的等級，請參閱[備援後的 effort 等級](#effort-level-after-a-fallback)。關於 subagent 和隊員，請參閱[Subagent 與隊員的 effort 等級](#effort-level-of-subagents-and-teammates)。

626 639

671| 等級 | 使用時機 |684| 等級 | 使用時機 |

672| :- | :- |685| :- | :- |

673| `low` | 您會檢閱每個結果的快速交流，例如腦力激盪、初步草稿，或像重新命名這類的小變更 |686| `low` | 您會檢閱每個結果的快速交流，例如腦力激盪、初步草稿，或像重新命名這類的小變更 |

674| `medium` | Opus 5.5、Sonnet 5.5 和 Haiku 5.5 上的預設值。在 Opus 5.5 和 Sonnet 5.5 上，適合範圍明確的日常工程工作，例如實作新功能。在預設值較高的模型上，可為能夠犧牲部分智慧的成本敏感工作減少 token 用量 |687| `medium` | Fable 5.2、Opus 5.5、Sonnet 5.5 和 Haiku 5.5 模型上的預設值。在 Opus 5.5 和 Sonnet 5.5 上，適合範圍明確的日常工程工作，例如實作新功能。在預設值較高的模型上，可為能夠犧牲部分智慧的成本敏感工作減少 token 用量 |

677| `max` | 您希望 Claude 在沒有您參與的情況下處理的困難問題，例如找出安全漏洞。`max` 可能出現報酬遞減且容易過度思考，因此在廣泛採用前請先測試 |690| `max` | 您希望 Claude 在沒有您參與的情況下處理的困難問題，例如找出安全漏洞。`max` 可能出現報酬遞減且容易過度思考，因此在廣泛採用前請先測試 |

691 704

692* 在不以 `/` 開頭的提示詞中，於引號、括號、路徑或命令等任何內容之外重新輸入它705* 在不以 `/` 開頭的提示詞中，於引號、括號、路徑或命令等任何內容之外重新輸入它

693* 如果 `CLAUDE_CODE_EFFORT_LEVEL` 設定為低於 `xhigh`，請取消設定它。或者將您自己的 [`maxEffortLevel`](https://code.claude.com/docs/zh-TW/settings-reference#maxeffortlevel) 提高至 `xhigh` 或以上，或請組織管理員提高您的[組織限制](#organization-effort-limits)706* 如果 `CLAUDE_CODE_EFFORT_LEVEL` 設定為低於 `xhigh`，請取消設定它。或者將您自己的 [`maxEffortLevel`](https://code.claude.com/docs/zh-TW/settings-reference#maxeffortlevel) 提高至 `xhigh` 或以上，或請組織管理員提高您的[組織限制](#organization-effort-limits)

694* 在工作階段中執行 `/model` 以切換至 Opus 5.5、Sonnet 5.5、Haiku 5.5 或 Fable 5.1 模型。在此字詞無法提高回合等級的情況下（例如在 Amazon Bedrock 上），請改為[設定 effort 等級](#set-the-effort-level)707* 在工作階段中執行 `/model` 以切換至 Opus 5.5、Sonnet 5.5、Haiku 5.5、Fable 5.2 或 Fable 5.1 模型。在此字詞無法提高回合等級的情況下（例如在 Amazon Bedrock 上），請改為[設定 effort 等級](#set-the-effort-level)

695 708

696#### 設定 effort 等級709#### 設定 effort 等級

697 710

767 780

768### 延伸上下文781### 延伸上下文

769 782

770Fable 5.1、Fable 5、Sonnet 5 及更新版本、Haiku 5.5、Opus 4.6 及更新版本，以及 Sonnet 4.6 支援 [100 萬 token 上下文視窗](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)，適用於處理大型程式碼庫的長時間工作階段。783處理大型程式碼庫的長時間工作階段可以使用 [100 萬 token 上下文視窗](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)。Fable 模型、Sonnet 5 及更新版本、Haiku 5.5、Opus 4.6 及更新版本，以及 Sonnet 4.6 支援此視窗。

771 784

772Fable 5.1、Fable 5、Sonnet 5 及更新版本、Haiku 5.5，以及 Opus 4.7 及更新版本預設以 1M 視窗執行，不需要 `[1m]` 後綴。這也包括 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上的工作階段，以及 [Claude apps gateway](https://code.claude.com/docs/zh-TW/claude-apps-gateway) 工作階段。若要改以 200K 視窗執行這些模型，請參閱[關閉 1M 上下文](#turn-off-1m-context)。785Fable 模型、Sonnet 5 及更新版本、Haiku 5.5，以及 Opus 4.7 及更新版本預設以 1M 視窗執行，不需要 `[1m]` 後綴。這也包括 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上的工作階段，以及 [Claude apps gateway](https://code.claude.com/docs/zh-TW/claude-apps-gateway) 工作階段。若要改以 200K 視窗執行這些模型，請參閱[關閉 1M 上下文](#turn-off-1m-context)。

773 786

774Opus 4.6 和 Sonnet 4.6 只能透過其 `[1m]` 變體達到 1M，而能否使用該變體取決於您的方案。在 Max、Ultra、Team 和 Enterprise 方案上（包括 Team Standard 和 Team Premium 席位），具有 1M 上下文的 Opus 4.6 已包含在您的訂閱中。具有 1M 上下文的 Sonnet 4.6 在每個訂閱方案（包括 Max 和 Ultra）上都需要[用量點數](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)。787Opus 4.6 和 Sonnet 4.6 只能透過其 `[1m]` 變體達到 1M，而能否使用該變體取決於您的方案。在 Max、Ultra、Team 和 Enterprise 方案上（包括 Team Standard 和 Team Premium 席位），具有 1M 上下文的 Opus 4.6 已包含在您的訂閱中。具有 1M 上下文的 Sonnet 4.6 在每個訂閱方案（包括 Max 和 Ultra）上都需要[用量點數](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)。

775 788

798 811

799#### LLM 閘道後方的上下文視窗812#### LLM 閘道後方的上下文視窗

800 813

801如果您將 `ANTHROPIC_BASE_URL` 設定為 [LLM 閘道](https://code.claude.com/docs/zh-TW/llm-gateway)或其他代理伺服器，Claude Code 會為它能識別的每個模型提供與該模型在 Anthropic API 上相同的上下文視窗。Fable 5.1、Fable 5、Sonnet 5 及更新版本、Haiku 5.5，以及 Opus 4.7 及更新版本會取得 1M 視窗，無需選擇 `[1m]` 變體；而只能透過 `[1m]` 變體達到 1M 的模型（例如 Opus 4.6），在未使用該變體時會以 200K 執行。Claude Code 無法偵測閘道或其後方伺服器所強制執行的較低限制。如果您的閘道會拒絕超過 200K token 的請求，請在啟動 Claude Code 的環境中設定 [`CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000`](https://code.claude.com/docs/zh-TW/env-vars)，讓所有模型上的工作階段都[在該邊界進行壓縮](#set-the-auto-compact-window)。814如果您將 `ANTHROPIC_BASE_URL` 設定為 [LLM 閘道](https://code.claude.com/docs/zh-TW/llm-gateway)或其他代理伺服器，Claude Code 會為它能識別的每個模型提供與該模型在 Anthropic API 上相同的上下文視窗。Fable 模型、Sonnet 5 及更新版本、Haiku 5.5，以及 Opus 4.7 及更新版本會取得 1M 視窗，無需 `[1m]` 變體。只能透過 `[1m]` 變體達到 1M 的模型（例如 Opus 4.6），在未使用該變體時會以 200K 執行。

815

816Claude Code 無法偵測閘道或其後方伺服器所強制執行的較低限制。如果您的閘道會拒絕超過 200K token 的請求，請在啟動 Claude Code 的環境中設定 [`CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000`](https://code.claude.com/docs/zh-TW/env-vars)，讓所有模型上的工作階段都[在該邊界進行壓縮](#set-the-auto-compact-window)。

802 817

803#### 關閉 1M 上下文818#### 關閉 1M 上下文

804 819

885 900

886一旦 Claude Code 辨識出該 ID 或使用您提供的視窗，當您以該 ID 啟動工作階段時，就不會再出現此警告。901一旦 Claude Code 辨識出該 ID 或使用您提供的視窗，當您以該 ID 啟動工作階段時，就不會再出現此警告。

887 902

903#### 修正輸入錯誤的模型名稱

904

905出現下列任一警告，都表示 Claude Code 無法辨識您設定的模型 ID，且該 ID 的拼寫與其可辨識的某個模型名稱或別名幾乎相同：

906

907```text theme={null}

908⚠ Model "<model>" isn't recognized · did you mean "<suggestion>"?

909Claude Code doesn't recognize the model "<model>". Did you mean "<suggestion>"?

910```

911

912* **您輸入了錯誤的 ID**：[在您設定模型之處](#setting-your-model)將其變更為建議的名稱

913* **該 ID 是刻意設定的**：保持原樣即可。工作階段會依您撰寫的內容傳送該 ID。若 Claude Code 為其假定的上下文視窗有誤，請[修正視窗](#correct-the-window-for-a-gateway-or-custom-model-id)

914

888#### `CLAUDE_CODE_MAX_CONTEXT_TOKENS` 適用於哪些 ID915#### `CLAUDE_CODE_MAX_CONTEXT_TOKENS` 適用於哪些 ID

889 916

890在 [LLM 閘道](https://code.claude.com/docs/zh-TW/llm-gateway)或其他自訂部署上，無論 Claude Code 是否將模型 ID 解析為 Claude 模型，它為該 ID 假定的上下文視窗都可能與模型的實際視窗不同。請將 [`CLAUDE_CODE_MAX_CONTEXT_TOKENS`](https://code.claude.com/docs/zh-TW/env-vars) 設為 Claude Code 應改為假定的視窗。917在 [LLM 閘道](https://code.claude.com/docs/zh-TW/llm-gateway)或其他自訂部署上，無論 Claude Code 是否將模型 ID 解析為 Claude 模型，它為該 ID 假定的上下文視窗都可能與模型的實際視窗不同。請將 [`CLAUDE_CODE_MAX_CONTEXT_TOKENS`](https://code.claude.com/docs/zh-TW/env-vars) 設為 Claude Code 應改為假定的視窗。

1100 1127

1101| 版本 | 變更 |1128| 版本 | 變更 |

1102| :- | :- |1129| :- | :- |

1130| v2.1.321 | `fable` 解析為 Fable 5.2，但 Claude apps 閘道工作階段除外 |

1131| v2.1.321 | `best` 解析為與 `opus` 相同的模型。較早版本在 Fable 可用時，會使用 `fable` 所解析的模型 |

1103| v2.1.293 | 在 Anthropic API 上，`haiku` 解析為 Haiku 5.5 |1132| v2.1.293 | 在 Anthropic API 上，`haiku` 解析為 Haiku 5.5 |

1104| v2.1.284 | 在 Anthropic API 上，`sonnet` 解析為 Sonnet 5.5 |1133| v2.1.284 | 在 Anthropic API 上，`sonnet` 解析為 Sonnet 5.5 |

1105| v2.1.280 | 在 Anthropic API、Claude Platform on AWS、Amazon Bedrock 及 Google Cloud's Agent Platform 上，`opus` 解析為 Opus 5.5 |1134| v2.1.280 | 在 Anthropic API、Claude Platform on AWS、Amazon Bedrock 及 Google Cloud's Agent Platform 上，`opus` 解析為 Opus 5.5 |

permissions.md +2 −1

Details

253| :- | :- | :- |253| :- | :- | :- |

257 257

258最後一欄中的命令由您的其他規則與權限模式決定。258最後一欄中的命令由您的其他規則與權限模式決定。

259 259

273* **指向其他 daemon 的 `docker`**：當命令帶有選擇不同 daemon 的旗標時，例如 `-H`、`--context`，或 Podman 的 `--url` 與 `--connection`，`docker` 的唯讀形式會提示。273* **指向其他 daemon 的 `docker`**：當命令帶有選擇不同 daemon 的旗標時，例如 `-H`、`--context`，或 Podman 的 `--url` 與 `--connection`，`docker` 的唯讀形式會提示。

274* **帶有開啟路徑旗標的 `file`**：當 `file` 傳入 `-m`/`--magic-file` 或 `-f`/`--files-from` 時會提示，因為這些旗標會讓 `file` 開啟旗標值中所指定的路徑。274* **帶有開啟路徑旗標的 `file`**：當 `file` 傳入 `-m`/`--magic-file` 或 `-f`/`--files-from` 時會提示，因為這些旗標會讓 `file` 開啟旗標值中所指定的路徑。

275* **可能印出環境變數的 `ps`**：當 `ps` 的某個引數可能作為 `e` 選項時會提示，例如 `ps auxe` 或 `ps aux -e`，因為該選項會印出程序的環境變數。`ps aux` 與 `ps -ef` 會不經提示即執行。對 `ps aux -e` 等帶連字號形式的檢查需要 Claude Code v2.1.290 或更新版本。275* **可能印出環境變數的 `ps`**：當 `ps` 的某個引數可能作為 `e` 選項時會提示，例如 `ps auxe` 或 `ps aux -e`，因為該選項會印出程序的環境變數。`ps aux` 與 `ps -ef` 會不經提示即執行。對 `ps aux -e` 等帶連字號形式的檢查需要 Claude Code v2.1.290 或更新版本。

276* **帶有查詢與顯示以外旗標的 `which`**：當 `which` 傳入 `-i`/`--read-alias` 或 `--read-functions` 等旗標時會提示。`which node` 與 `which -a node` 會不經提示即執行。

276* **Windows 上的網路路徑**：引數包含網路（UNC）路徑（例如 `\\server\share\file`）的命令會提示，因為存取網路路徑可能會將您的 Windows 憑證傳送給其所指定的主機。相同的檢查也適用於 [PowerShell 工具](https://code.claude.com/docs/zh-TW/tools-reference.md#powershell-tool)命令。277* **Windows 上的網路路徑**：引數包含網路（UNC）路徑（例如 `\\server\share\file`）的命令會提示，因為存取網路路徑可能會將您的 Windows 憑證傳送給其所指定的主機。相同的檢查也適用於 [PowerShell 工具](https://code.claude.com/docs/zh-TW/tools-reference.md#powershell-tool)命令。

277* **寫入特殊 shell 變數**：設定、取消設定或迴圈遍歷某些特殊 shell 變數（例如 `PATH` 或 `IFS`）的命令，即使命令的其餘部分為唯讀也會提示。278* **寫入特殊 shell 變數**：設定、取消設定或迴圈遍歷某些特殊 shell 變數（例如 `PATH` 或 `IFS`）的命令，即使命令的其餘部分為唯讀也會提示。

278* **分析無法解析的命令**：當 Claude Code 無法完整解析某個命令時，它會要求核准，而不是將該命令視為唯讀。超過 10,000 個字元的命令一律會提示，因為它們超出分析所能解析的範圍。279* **分析無法解析的命令**：當 Claude Code 無法完整解析某個命令時，它會要求核准，而不是將該命令視為唯讀。超過 10,000 個字元的命令一律會提示，因為它們超出分析所能解析的範圍。

plugins/mods/events.md +1 −1

Details

279* **您的 hook 在其 `next(e)` 呼叫已讓提示詞通過之後才傳回 `drop`**：回合仍會執行，且該 hook 會[失敗](#handle-a-hook-that-fails)，並顯示包含 `a drop after its next() was answered` 的訊息279* **您的 hook 在其 `next(e)` 呼叫已讓提示詞通過之後才傳回 `drop`**：回合仍會執行，且該 hook 會[失敗](#handle-a-hook-that-fails)，並顯示包含 `a drop after its next() was answered` 的訊息

280* **您的 hook 擲出例外或逾時**：Claude Code 會略過它並送出提示詞。請[加入 `.catch` 處理常式](#handle-a-hook-that-fails)，以免失敗時送出 hook 原本會阻止的提示詞。280* **您的 hook 擲出例外或逾時**：Claude Code 會略過它並送出提示詞。請[加入 `.catch` 處理常式](#handle-a-hook-that-fails)，以免失敗時送出 hook 原本會阻止的提示詞。

281 281

282[其他事件](https://code.claude.com/docs/zh-TW/plugins/mods/reference.md#prompts-and-what-claude-reads)涵蓋 Claude 讀取的其餘內容：`prompt.section` 用於系統提示詞的每個區段，`prompt.context` 用於隨第一則訊息送出的上下文，而 `skill.prompt` 用於 skill 的文字。來自這些 hook、且在請求之間有所變動的文字，會[使提示快取失效](https://code.claude.com/docs/zh-TW/prompt-caching.md)。在 `skill.prompt` hook 中，您也可以讀取[該 skill 來自哪個外掛或檔案](https://code.claude.com/docs/zh-TW/plugins/mods/reference.md#skill-prompt-fields)。282[其他事件](https://code.claude.com/docs/zh-TW/plugins/mods/reference.md#prompts-and-what-claude-reads)涵蓋 Claude 讀取的其餘內容：`prompt.section` 用於系統提示詞的每個區段，`prompt.context` 用於隨第一則訊息送出的上下文，而 `skill.prompt` 用於 skill 的文字。若要在對話開始後變更某個區段，請參閱[傳送變更後的系統提示詞區段或工具描述](https://code.claude.com/docs/zh-TW/plugins/mods/reference.md#break-prompt-cache)。在 `skill.prompt` hook 中，您也可以讀取[該 skill 來自哪個外掛或檔案](https://code.claude.com/docs/zh-TW/plugins/mods/reference.md#skill-prompt-fields)。

283 283

284### 追蹤回合284### 追蹤回合

285 285

plugins/mods/interface.md +154 −67

Details

177 177

178## 選擇繪製位置178## 選擇繪製位置

179 179

180`ui.render` hook 為每個渲染位置執行，除非您將其縮小到您想要繪製的位置。若要選擇渲染位置，請傳遞一個稱為 [matcher](https://code.claude.com/docs/zh-TW/plugins/mods/events.md#filter-which-events-a-hook-handles) 的篩選器作為 `on` 的第二個引數。`{ component: 'Pane' }` 只為窗格執行 hook。在 hook 中，`e.component` 命名位置，`e.surface` 說明哪個應用程式在繪製，`e.props` 保持位置自己的資料。對於窗格，`e.requestId` 是您用來開啟它的 `id`。180除非您將 `ui.render` hook 限定在您想繪製的那一個轉譯位置，否則它會在每個轉譯位置都執行。若要選擇轉譯位置，請將一個篩選條件（稱為 [matcher](https://code.claude.com/docs/zh-TW/plugins/mods/events.md#filter-which-events-a-hook-handles)）作為第二個引數傳給 `on`。`{ component: 'Pane' }` 會讓 hook 只在窗格中執行。在 hook 中，`e.component` 指出位置名稱，`e.surface` 說明是哪個應用程式在繪製，而 `e.props` 則存放該位置自身的資料。對於窗格，`e.requestId` 是您開啟它時所用的 `id`。

181 181

182窗格和帶狀區域在 mod 填充它們之前是空的。選擇一個標籤以查看每個位置是什麼以及如何在其中繪製：182在 mod 填入內容之前，窗格和橫帶都是空的。選擇一個分頁，查看各自是什麼以及如何在其中繪製：

183 183

184> [tab] Pane184> [tab] 窗格

185>185>

186> 窗格是在寬全螢幕終端機中逐字稿旁邊的側邊欄，或在其他情況下是提示詞上方的框架區域。開啟多個窗格時，每個窗格都會獲得一個顯示其標題的標籤。186> 窗格在寬版全螢幕終端機中是位於逐字稿旁的側邊欄，否則則是位於提示詞上方的框線區域。開啟多個窗格時，每個窗格都會有一個顯示其標題的分頁。

187>187>

188> 當您的 mod 使用您選擇的 `id` 呼叫 `$.ui.open` 時，窗格會出現，如 `$.ui.open({ id: 'hello-tabs' })`。[在正確的時間開啟窗格](#open-a-pane-at-the-right-time)涵蓋其他欄位以及窗格何時等待更寬的終端機。188> 當您的 mod 以您選擇的 `id` 呼叫 `$.ui.open` 時，窗格就會出現，例如 `$.ui.open({ id: 'hello-tabs' })`。[在適當時機開啟窗格](#open-a-pane-at-the-right-time)說明了其他欄位，以及窗格何時會等待更寬的終端機。

189>189>

190> 若要在您的窗格中繪製，請篩選 `{ component: 'Pane' }` 並檢查 `e.requestId` 是否為您的 `id`。190> 若要在您的窗格中繪製，請以 `{ component: 'Pane' }` 篩選，並檢查 `e.requestId` 是否為您的 `id`。

191 191

192> [tab] Band above the prompt192> [tab] 提示詞上方的橫帶

193>193>

194> 帶狀區域是直接在提示詞輸入上方的條帶。它始終存在，每個 mod 都共享它。194> 橫帶是緊鄰提示詞輸入框上方的一條區域。它始終存在，且所有 mod 共用。

195>195>

196> 您的 hook 返回一棵樹以在帶狀區域中顯示某些內容，或返回 `next(e)` 以不顯示任何內容。樹會替換 mod [在您之後](https://code.claude.com/docs/zh-TW/plugins/mods/events.md#the-order-mods-run-in)在那裡繪製的內容。若要保持他們的內容，請將 `await next(e)` 的結果放在您樹中 [`Box`](#build-a-tree-from-elements) 的子項中。196> 您的 hook 回傳一棵樹以在橫帶中顯示內容，或回傳 `next(e)` 以不顯示任何內容。一棵樹會取代[在您之後](https://code.claude.com/docs/zh-TW/plugins/mods/events.md#the-order-mods-run-in)執行的 mod 在此處繪製的內容。若要保留它們的內容，請將 `await next(e)` 的結果放入您樹中某個 [`Box`](#build-a-tree-from-elements) 的子元素之中。

197>197>

198> 若要在帶狀區域中繪製，請篩選 `{ component: 'AbovePrompt' }`。198> 若要在橫帶中繪製，請以 `{ component: 'AbovePrompt' }` 篩選。

199 199

200### 更改 Claude Code 已經繪製的內容200mod 也可以[在逐字稿中放置自己的一列](#place-a-row-in-the-transcript)。

201 201

202Claude Code 自己繪製大部分介面：訊息、工具呼叫列、微調器等。這些部分中的每一個也是一個渲染位置，因此 mod 可以重新設定樣式或替換它。若要更改一個，請在 `ui.render` hook 上篩選此表中的其名稱：202### 變更 Claude Code 已繪製的內容

203 203

204| 位置 | 它是什麼 |204Claude Code 自行繪製大部分介面：訊息、工具呼叫列、spinner 等等。其中每個部分也都是轉譯位置，因此 mod 可以重新設定其樣式或加以取代。若要變更其中之一，請以下表中的名稱篩選您的 `ui.render` hook：

205

206| 位置 | 說明 |

205| :- | :- |207| :- | :- |

212 214

213`Pane`、`AskUserQuestion`、`Spinner`、`UserMessage`、`AssistantMessage` 和工具呼叫位置在終端機、Desktop 應用程式和 VS Code 擴充功能中都有效。[轉譯位置表](https://code.claude.com/docs/zh-TW/plugins/mods/reference.md#render-sites)列出其他每個位置的引發位置。215`Pane`、`AskUserQuestion`、`Spinner`、`UserMessage`、`AssistantMessage` 以及工具呼叫位置可在終端機、Desktop 應用程式和 VS Code 擴充功能中運作。[轉譯位置表](https://code.claude.com/docs/zh-TW/plugins/mods/reference.md#render-sites)列出了其他各位置在何處觸發。

214 216

215在 Claude Code 已經繪製的位置，您的 hook 可以更改詳細資訊、替換繪製或不理會。選擇一個標籤以查看每個應用於微調器的選項。範例讀取另一個 hook 計數的 `calls` 變數，如[教學 mod](https://code.claude.com/docs/zh-TW/plugins/mods/create.md#write-a-mod-yourself) 中所示。217在 Claude Code 已繪製的位置，您的 hook 可以變更某個細節、取代繪製內容，或保持不變。選擇一個分頁，查看每種做法套用於 spinner 的效果。這些範例會讀取由另一個 hook 計數的 `calls` 變數，如同[教學 mod](https://code.claude.com/docs/zh-TW/plugins/mods/create.md#write-a-mod-yourself) 中的做法。

216 218

217> [tab] Change a detail219> [tab] 變更細節

218>220>

219> 若要保持 Claude Code 的繪製並更改其一部分，請將 `next` 傳遞事件的副本，其中 `props` 已更改。此 hook 更改微調器單詞後的文字：221> 若要保留 Claude Code 的繪製內容並只變更其中一部分，請將 `props` 已變更的事件副本傳給 `next`。這個 hook 會變更 spinner 文字之後的內容：

220>222>

221> ```javascript theme={null}223> ```javascript theme={null}

222> on('ui.render', { component: 'Spinner' }, async ($, e, next) => {224> on('ui.render', { component: 'Spinner' }, async ($, e, next) => {

223> // 保持 Claude Code 的微調器，並更改其單詞後的文字225> // Keep Claude Code's spinner, and change the text after its word

224> return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })226> return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })

225> })227> })

226> ```228> ```

227>229>

228> 微調器保持其動畫和單詞，您的文字跟隨單詞：230> spinner 保留其動畫與文字，而您的文字接在該文字之後：

229>231>

230> ```text theme={null}232> ```text theme={null}

231> Thinking · tool calls: 2…233> Thinking · tool calls: 2…

232> ```234> ```

233 235

234> [tab] Replace the drawing236> [tab] 取代繪製內容

235>237>

236> 若要在位置的位置繪製您自己的內容，請返回樹並不呼叫 `next`。此 hook 在微調器所在的位置繪製一行文字：238> 若要在該位置繪製您自己的內容，請回傳一棵樹，且不要呼叫 `next`。這個 hook 會在 spinner 原本的位置繪製一行文字：

237>239>

238> ```javascript theme={null}240> ```javascript theme={null}

239> on('ui.render', { component: 'Spinner' }, async ($, e) => {241> on('ui.render', { component: 'Spinner' }, async ($, e) => {

240> const { Text } = $.ui.resolve(e)242> const { Text } = $.ui.resolve(e)

241> // 沒有呼叫 next，所以此行在微調器的位置繪製243> // No call to next, so this line is drawn in the spinner's place

242> return Text({ children: ['Claude has made ' + calls + ' tool calls'] })244> return Text({ children: ['Claude has made ' + calls + ' tool calls'] })

243> })245> })

244> ```246> ```

245>247>

246> 當 Claude 工作時，您的行會顯示，Claude Code 的微調器不會：248> Claude 工作時，會顯示您的那一行，而不會顯示 Claude Code 的 spinner：

247>249>

248> ```text theme={null}250> ```text theme={null}

249> Claude has made 2 tool calls251> Claude has made 2 tool calls

250> ```252> ```

251 253

252> [tab] Leave it alone254> [tab] 保持不變

253>255>

254> 若要將位置保留為 Claude Code 繪製的方式，請返回 `next(e)`。hook 通常對某些事件執行此操作，對其他事件則不執行。此 hook 在沒有要計數的呼叫之前保留微調器：256> 若要讓該位置維持 Claude Code 的繪製方式，請回傳 `next(e)`。hook 經常對某些事件這樣做，而對其他事件則不然。這個 hook 會在有呼叫可計數之前保持 spinner 不變：

255>257>

256> ```javascript theme={null}258> ```javascript theme={null}

257> on('ui.render', { component: 'Spinner' }, async ($, e, next) => {259> on('ui.render', { component: 'Spinner' }, async ($, e, next) => {

258> // 還沒有要顯示的內容，所以不變地傳遞事件260> // Nothing to show yet, so pass the event on unchanged

259> if (calls === 0) return next(e)261> if (calls === 0) return next(e)

260> return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })262> return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })

261> })263> })

262> ```264> ```

263>265>

264> 在第一個工具呼叫之前，微調器看起來就像沒有 mod 的方式：266> 在第一次工具呼叫之前，spinner 看起來和沒有 mod 時一樣：

265>267>

266> ```text theme={null}268> ```text theme={null}

267> Thinking…269> Thinking…

268> ```270> ```

269 271

270在這些位置，`next(e)` 會返回對 Claude Code 繪製內容的參照 `{ type: 'engine', ref }`，除非在您之後執行的 mod 返回了它自己的樹。若要更改該繪製中的內容，請將帶有不同 props 的事件副本傳遞給 `next`，如 **Change a detail** 標籤所示。您可以原樣返回該參照，或將其放在 `Box` 中，與您自己的元素並列：272在這些位置，`next(e)` 會回傳對 Claude Code 繪製內容的參照 `{ type: 'engine', ref }`，除非在您之後執行的 mod 回傳了它自己的樹。若要變更該繪製內容中的東西，請將帶有不同 prop 的事件副本傳給 `next`，如同**變更細節**分頁的做法。您可以直接回傳該參照，或將它與您自己的元素一起放進 `Box`：

271 273

272```javascript theme={null}274```javascript theme={null}

273on('ui.render', { component: 'Spinner' }, async ($, e, next) => {275on('ui.render', { component: 'Spinner' }, async ($, e, next) => {

277})279})

278```280```

279 281

280當 Claude 工作時，微調器會像之前一樣顯示動畫，而 `under the spinner` 會出現在其下方。282Claude 工作時，spinner 照常播放動畫，而 `under the spinner` 會出現在其下方。

281 283

282權限提示不是渲染位置，因此 mod 無法更改其顯示的內容。問題對話框 `AskUserQuestion` 是渲染位置，因此 mod 可以更改它。對話框的樹必須恰好包含該參照一次，並將您的元素放在其上方。否則，Claude Code 會繪製它自己的對話框。284權限提示不是轉譯位置，因此 mod 無法變更其顯示內容。問題對話框 `AskUserQuestion` 則是轉譯位置，因此 mod 可以變更它。對話框的樹必須恰好包含該參照一次，並將您的元素置於其上方。否則，Claude Code 會繪製它自己的對話框。

283 285

284### 在正確的時間開啟窗格286### 在適當時機開啟窗格

285 287

286窗格只在您的 mod 開啟它時出現。您如何以及何時開啟它決定了它是否獲得鍵盤焦點、它請求多少空間，以及它是否在狹窄的終端機中顯示。288窗格只有在您的 mod 開啟它時才會出現。您開啟窗格的方式與時機，決定了它是否取得鍵盤焦點、要求多少空間，以及在狹窄的終端機中是否會顯示。

287 289

288若要開啟窗格，請使用您選擇的 `id` 呼叫 [`$.ui.open`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#mods-api-methods)。`id` 是窗格的名稱：您的 `ui.render` hook 檢查它，您再次傳遞它以關閉窗格。290若要開啟窗格，請以您選擇的 `id` 呼叫 [`$.ui.open`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#mods-api-methods)。`id` 是窗格的名稱：您的 `ui.render` hook 會檢查它，而您在關閉窗格時也要再次傳入它。

289 291

290```javascript theme={null}292```javascript theme={null}

291await $.ui.open({ id: 'hello-tabs', title: 'Hello tabs', focus: true })293await $.ui.open({ id: 'hello-tabs', title: 'Hello tabs', focus: true })

292```294```

293 295

294若要關閉窗格，請使用您用來開啟它的 `id` 呼叫 `$.ui.close`：296若要關閉窗格，請以開啟時所用的 `id` 呼叫 `$.ui.close`：

295 297

296```javascript theme={null}298```javascript theme={null}

297await $.ui.close({ id: 'hello-tabs' })299await $.ui.close({ id: 'hello-tabs' })

298```300```

299 301

300除了 `id`，`$.ui.open` 還採用這些可選欄位：302除了 `id` 之外，`$.ui.open` 還接受下列選用欄位：

301 303

302| 欄位 | 它執行的操作 |304| 欄位 | 作用 |

303| :- | :- |305| :- | :- |

310 312

311[VS Code 擴充功能](#draw-in-the-vs-code-extension)會忽略 `rows` 和 `columns`，並自行決定窗格的大小。313[VS Code 擴充功能](#draw-in-the-vs-code-extension)會忽略 `rows` 和 `columns`，並自行決定窗格大小。

312 314

313`focus`、`closeOnEscape` 和 `holdToasts` 是可選的，只接受 `true`。若要省略其中一個，請將其省略。傳遞 `false` 會擲回錯誤，例如 `ui.open: focus is true or left out`。若要有條件地設定其中一個，請只在條件成立時新增欄位。此呼叫只在 `items` 不為空時請求鍵盤焦點：315`focus`、`closeOnEscape` 和 `holdToasts` 皆為選用，且只接受 `true`。若不使用，請直接省略。傳入 `false` 會擲出錯誤，例如 `ui.open: focus is true or left out`。若要有條件地設定其中之一，請只在條件成立時加入該欄位。以下呼叫只在 `items` 不為空時才請求鍵盤焦點：

314 316

315```javascript theme={null}317```javascript theme={null}

316const pane = { id: 'hello-tabs', title: 'Hello tabs' }318const pane = { id: 'hello-tabs', title: 'Hello tabs' }

317await $.ui.open(items.length > 0 ? { ...pane, focus: true } : pane)319await $.ui.open(items.length > 0 ? { ...pane, focus: true } : pane)

318```320```

319 321

320若要讓命令在 Claude 工作時開啟窗格，請在[註冊命令](https://code.claude.com/docs/zh-TW/plugins/mods/api.md#add-a-command)時新增 `immediate: true`。沒有它，在回合期間輸入的命令會等待回合結束。322若要讓命令在 Claude 工作時開啟窗格，請在[註冊命令](https://code.claude.com/docs/zh-TW/plugins/mods/api.md#add-a-command)時加入 `immediate: true`。若未加入，在回合進行中輸入的命令會等到回合結束才執行。

321 323

322#### 在對話框後方保留快顯通知324#### 在對話框背後暫緩 toast

323 325

324當窗格是使用者回答後即離開的對話框時，請將 `holdToasts: true` 傳遞給 `$.ui.open`，讓快顯通知不會在使用者做決定時出現。在終端機中，保留會在該窗格是正在顯示的窗格期間持續，而在此期間引發的快顯通知會等到保留結束才出現。326當窗格是使用者作答後即離開的對話框時，請將 `holdToasts: true` 傳給 `$.ui.open`，這樣使用者在做決定時就不會出現 toast。在終端機中，暫緩會持續到該窗格不再是目前顯示的窗格為止，這段期間觸發的 toast 會等到暫緩結束才顯示。

325 327

326Claude Code 會保留其他 mod 的快顯通知及它自己的短暫通知，也會保留您的 mod 透過 [`$.ui.toast`](https://code.claude.com/docs/zh-TW/plugins/mods/api#show-something-without-starting-a-turn) 引發的通知。對於保持開啟的窗格，請不要設定此欄位，讓使用者能持續看到這些通知。328除了您的 mod 透過 [`$.ui.toast`](https://code.claude.com/docs/zh-TW/plugins/mods/api#show-something-without-starting-a-turn) 觸發的 toast 之外，Claude Code 也會暫緩其他 mod 的 toast 以及它自己的短暫通知。對於會持續開啟的窗格，請不要設定此欄位，讓使用者能持續看到這些通知。

327 329

328#### 當窗格等待更寬的終端機時330#### 窗格何時會等待更寬的終端機

329 331

330您的 mod 開啟的窗格（未被請求）不會在狹窄的終端機中出現，因此它無法接管小螢幕。它是否出現取決於開啟它的內容：332您的 mod 在未經使用者要求下開啟的窗格，不會出現在狹窄的終端機中，因此不會佔據小螢幕。窗格是否出現取決於開啟它的原因：

331 333

332* **由使用者執行的操作開啟**，例如他們執行的命令或他們按下的按鈕，窗格在任何寬度出現334* **由使用者的操作開啟**，例如使用者執行的命令或按下的按鈕，窗格在任何寬度下都會出現

333* **由您的 mod 自行開啟**，例如從計時器或 [`turn.start`](https://code.claude.com/docs/zh-TW/plugins/mods/events#follow-a-turn) hook，窗格只在至少 144 列寬的終端機中出現。使用者自己開啟該窗格一次後，110 列就足夠了。335* **由您的 mod 自行開啟**，例如從計時器或 [`turn.start`](https://code.claude.com/docs/zh-TW/plugins/mods/events#follow-a-turn) hook 開啟，窗格只會在至少 144 欄寬的終端機中出現。使用者自行開啟過該窗格一次之後，110 欄就足夠了。

334 336

335當窗格出現時，`$.ui.open` 解析為 `{ isPlaced: true }`。當窗格在等待時，`isPlaced` 是 `false`，`reason` 是說明原因的字串。當使用者開啟窗格或加寬終端機時，等待的窗格會出現。若要說明某些內容可用而不開啟窗格，請呼叫 `$.ui.toast('Your message')`，它會顯示快顯通知。337窗格出現時，`$.ui.open` 會解析為 `{ isPlaced: true }`。窗格處於等待狀態時，`isPlaced` 為 `false`，而 `reason` 是說明原因的字串。等待中的窗格會在使用者開啟它或加寬終端機時出現。若要告知某項內容可用而不開啟窗格，請呼叫 `$.ui.toast('Your message')`，它會顯示一則 toast 通知。

336 338

337### 在 VS Code 擴充功能中繪製339### 在 VS Code 擴充功能中繪製

338 340

339在 VS Code 擴充功能中，mod 繪製的內容會出現在聊天面板中，需要擴充功能版本 2.1.299 或更新版本。[不會擷取功能旗標](https://code.claude.com/docs/zh-TW/env-vars.md#features-that-need-feature-flag-fetching)的工作階段（例如在 Amazon Bedrock 上的工作階段）需要 2.1.304 或更新版本。在面板的 `ui.render` hook 中，`e.surface` 為 `vscode`。若要查看面板會繪製哪些位置和元素，以及會忽略哪些 prop，請參閱[轉譯位置](https://code.claude.com/docs/zh-TW/plugins/mods/reference.md#render-sites)和[元素](https://code.claude.com/docs/zh-TW/plugins/mods/reference.md#elements)表格。341在 VS Code 擴充功能中，擴充功能版本 2.1.299 或更新版本會在聊天面板中顯示 mod 繪製的內容。[不擷取功能旗標](https://code.claude.com/docs/zh-TW/env-vars.md#features-that-need-feature-flag-fetching)的工作階段（例如使用 Amazon Bedrock 的工作階段）需要 2.1.304 或更新版本。在面板的 `ui.render` hook 中，`e.surface` 為 `vscode`。若要確認面板會繪製哪些位置與元素，以及會忽略哪些 prop，請參閱[轉譯位置](https://code.claude.com/docs/zh-TW/plugins/mods/reference.md#render-sites)和[元素](https://code.claude.com/docs/zh-TW/plugins/mods/reference.md#elements)表格。

340 342

341若要讓 mod 在面板和終端機中都能運作，請考量以下差異：343若要讓 mod 在面板和終端機中都能運作，請考量下列差異：

342 344

343* **窗格**：在寬度 800 像素以上的面板中，窗格會停駐在對話旁邊，`e.props.placement` 為 `'dock'`，且 `e.viewport.isFullscreen` 為 `true`。在較窄的面板中，窗格會繪製在提示詞輸入框上方，`placement` 為 `'inline'`，且窗格在捲動前會顯示 12 列。345* **窗格**：在 800 像素或更寬的面板中，窗格會停靠在對話旁，`e.props.placement` 為 `'dock'`，且 `e.viewport.isFullscreen` 為 `true`。在較窄的面板中，窗格會繪製在提示詞輸入框上方，`placement` 為 `'inline'`，且窗格顯示 12 列後才會捲動。

344* **快顯通知和狀態列**：這些會位於提示詞輸入框正上方的同一個堆疊中，面板較窄時窗格也在其中，每個 mod 有一個狀態列。當權限請求或對話框顯示時，此堆疊會隱藏。346* **Toast 與狀態列**：這些會在提示詞輸入框正上方排成一疊，面板較窄時也會與窗格排在一起，每個 mod 各有一條狀態列。顯示權限請求或對話框時，這一疊會被隱藏。

345* **標籤**：面板會為 mod 繪製或改寫的內容加上框架，並以外掛的名稱標示，例如 **From the token-chart plugin** 或 **Edited by the token-chart plugin**。347* **標籤**：面板會將 mod 繪製或改寫的內容加上框線，並以外掛名稱標示，例如 **From the token-chart plugin** 或 **Edited by the token-chart plugin**。

346* **鍵盤**：按鈕沒有快速鍵，因此使用者需點擊按鈕，或在按鈕取得焦點後按下 Enter。348* **鍵盤**：按鈕沒有快速鍵，因此使用者需點擊按鈕，或在按鈕取得焦點後按 Enter。

347* **鍵盤焦點**：只有在面板具有焦點、Claude 處於閒置且沒有等待中的問題，並且提示詞輸入框為空時，面板才會接受窗格的 `focus: true` 請求。349* **鍵盤焦點**：只有在面板具有焦點、Claude 處於閒置且沒有等待中的問題，並且提示詞輸入框為空時，面板才會同意窗格的 `focus: true` 請求。

348* **問題對話框**：在 `AskUserQuestion`，面板會保留自己的問題卡片，並在其上方繪製您的元素。您傳遞給 `next` 的 props 不會更改該卡片。350* **問題對話框**：在 `AskUserQuestion`，面板會保留自己的問題卡片，並在其上方繪製您的元素。您傳給 `next` 的 prop 不會變更該卡片。

349* **提示詞建議**：`$.prompt.suggest` 會以 `isShown: false` 解析且不顯示任何內容，因為面板會將提示詞輸入框中的淡色建議文字保留給 Claude 自己的建議。351* **提示詞建議**：`$.prompt.suggest` 會以 `isShown: false` 解析且不顯示任何內容，因為面板會將提示詞輸入框中的淡色建議文字保留給 Claude 自己的建議。

350* **文字限制**：面板會將狀態列截斷為 200 個字元或兩列，並將快顯通知截斷為 500 個字元。352* **文字限制**：面板會將狀態列截斷在 200 個字元或兩列，並將 toast 截斷在 500 個字元。

353

354### 在逐字稿中放置一列

355

356列是您的 mod 在終端機中加到逐字稿最新訊息之後的一行。隨著對話進行，它會停留在該位置，且 Claude 看不到它。`$.ui.place` 需要 Claude Code v2.1.314 或更新版本。

357

358**1. 放置列**

359

360以 `id` 呼叫 [`$.ui.place`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#mods-api-methods)。`id` 是您為該列取的名稱，例如 `build-status`。它可以是 1 到 64 個字母、數字、`_` 或 `-`，而您的 mod 在逐字稿中的每一列都需要各自的 `id`。

361

362**2. 繪製列**

363

364在 [`Placed`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#render-sites) 轉譯位置繪製該列。

365

366此範例新增一個 `/build-status` 命令。使用者執行該命令時，mod 會新增一列，顯示 `Build: passing`。為了讓範例簡短，文字是固定的，實際的 mod 則會繪製自己的結果：

367

368```javascript theme={null}

369export function register(on) {

370 on('session.start', async ($, e, next) => {

371 await $.command.register({ name: 'build-status', description: 'Show the build status' })

372 return next(e)

373 })

374

375 on('command.run', { command: 'build-status' }, async ($) => {

376 const placed = await $.ui.place({ id: 'build-status' })

377 // Where nothing draws the row, reply with text instead

378 return placed.isPlaced ? {} : { text: 'Build: passing' }

379 })

380

381 on('ui.render', { component: 'Placed' }, async ($, e, next) => {

382 // This hook runs for every mod's rows, and another mod can use the same id

383 if (e.props.plugin !== $.plugin.name || e.props.id !== 'build-status') return next(e)

384 const { Text } = $.ui.resolve(e)

385 return Text({ children: ['Build: passing'] })

386 })

387}

388```

389

390若要試用此範例，請將這段程式碼放入一個 [mod](https://code.claude.com/docs/zh-TW/plugins/mods/create.md)。在終端機工作階段中，於 Claude Code 提示詞執行 `/build-status`。`Build: passing` 會以一列的形式出現在逐字稿末尾。

391

392此呼叫不一定會顯示一列，且列稍後也可能消失，因此請在您的 mod 中處理下列情況：

393

394* **結果**：當終端機繪製該列時為 `{ isPlaced: true, requestId }`。否則 `isPlaced` 為 `false`，而 `reason` 會說明原因，例如 `no attached surface draws placed rows yet`。其中一個原因是 mod 同時可擁有的[列數上限](https://code.claude.com/docs/zh-TW/plugins/mods/reference.md#limits)。

395* **以相同 `id` 再次呼叫**：當第一列仍在逐字稿中時，此呼叫不會新增列，並以該列的 `requestId` 解析。若要變更該列顯示的內容，請[重新繪製該列](#redraw-when-something-changes)。

396* **列何時消失**：對話結束時、使用者倒回到該列之前時，或在[全螢幕轉譯](https://code.claude.com/docs/zh-TW/fullscreen.md)以外的情況下壓縮對話時。`--resume` 不會讓該列回來。若要再次顯示該列，請再次呼叫 `$.ui.place`。

397

398### 在對話背後放置背景

399

400> [!NOTE]

401>

402> `$.theme.set` 和 `$.theme.clear` 取代了 `$.ui.backdrop`，後者已在 Claude Code v2.1.319 中移除。請將 `$.ui.backdrop({ id: 'your-backdrop' })` 改為 `$.theme.set({ backdrop: { id: 'your-backdrop' } })`，並將 `$.ui.backdrop(undefined)` 改為 `$.theme.clear()`，後者會移除任何 mod 的背景。

403

404若要在 Desktop 應用程式或行動應用程式中於對話背後放置背景，請以 `backdrop` 呼叫 [`$.theme.set`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#mods-api-methods)，然後在 [`Backdrop`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#render-sites) 轉譯位置繪製背景。若要移除背景，請呼叫 `$.theme.clear()`。終端機不會繪製背景。`$.theme.set` 和 `$.theme.clear` 需要 Claude Code v2.1.319 或更新版本。

405

406此 mod 會在工作階段開始時設定背景、繪製背景，並新增一個移除背景的 `/plain` 命令：

407

408```javascript theme={null}

409export function register(on) {

410 // Neither a reload of this mod nor --resume keeps the backdrop, so set it here

411 on('session.start', async ($, e, next) => {

412 await $.theme.set({ backdrop: { id: 'night-sky', colorScheme: 'dark' } })

413 await $.command.register({ name: 'plain', description: 'Take the backdrop off' })

414 return next(e)

415 })

416

417 on('ui.render', { component: 'Backdrop' }, async ($, e, next) => {

418 // This hook runs for every mod's backdrop, and another mod can use the same id

419 if (e.props.plugin !== $.plugin.name || e.props.id !== 'night-sky') return next(e)

420 const { Box, Text } = $.ui.resolve(e)

421 return Box({ backgroundColor: 'blue', children: [Text({ children: ['Night sky'] })] })

422 })

423

424 on('command.run', { command: 'plain' }, async ($) => {

425 const cleared = await $.theme.clear()

426 return { text: cleared.reason }

427 })

428}

429```

430

431若要試用此範例，請將這段程式碼放入一個 [mod](https://code.claude.com/docs/zh-TW/plugins/mods/create.md)，並在 Desktop 應用程式或行動應用程式中開始工作階段。若要移除背景，請在 Claude Code 提示詞執行 `/plain`。逐字稿會在 mod 名稱之後顯示 `the theme is cleared`，例如名為 `night-sky` 的 mod 會顯示 `night-sky: the theme is cleared`。

432

433請確認 `backdrop` 接受哪些內容、呼叫結果告訴您什麼，以及其他 mod 可以變更什麼：

434

435* **`backdrop` 欄位**：`id` 是您選擇的[名稱](https://code.claude.com/docs/zh-TW/plugins/mods/reference.md#limits)，為必填，其他欄位則為選用。`colorScheme` 為 `'light'` 或 `'dark'`，說明您的繪製內容是淺色還是深色。關於 `glass`，請參閱[適用於您建置版本的型別](https://code.claude.com/docs/zh-TW/plugins/mods/create.md#get-the-types-for-your-build)。

436* **背景是否已繪製**：當連線到工作階段的 Desktop 或行動應用程式表示它會繪製背景時，`$.theme.set` 會以 `isDrawn: true` 解析。否則 `isDrawn` 為 `false`，而 `reason` 會說明原因。

437* **每個工作階段一個背景**：`$.theme.set` 呼叫會取代工作階段的背景，而 `$.theme.clear()` 會移除該背景，無論是哪個 mod 設定的。請只在使用者要求時才呼叫 `$.theme.clear()`。

351 438

352## 從元素建立樹439## 從元素建立樹

353 440

plugins/mods/reference.md +14 −4

Details

57| :- | :- | :- |57| :- | :- | :- |

58| [`tool.call`](https://code.claude.com/docs/zh-TW/plugins/mods/events#guard-or-change-a-tool-call) | 工具即將執行時 | `next(e)`、`{ deny: reason }` 或 `{ result }` |58| [`tool.call`](https://code.claude.com/docs/zh-TW/plugins/mods/events#guard-or-change-a-tool-call) | 工具即將執行時 | `next(e)`、`{ deny: reason }` 或 `{ result }` |

59| [`tool.check`](https://code.claude.com/docs/zh-TW/plugins/mods/events#where-settings-hooks-run-in-the-order) | Claude Code 在 `tool.call` 與 `PreToolUse` hook 之後，決定工具呼叫是否可以執行時。`next(e)` 會解析為規則、權限模式與這些 hook 所得出的決定。 | `next(e)` 或 `{ decision }`，其中 `decision` 設為 `allow`、`ask` 或 `deny`，並可選擇附上 `reason` |59| [`tool.check`](https://code.claude.com/docs/zh-TW/plugins/mods/events#where-settings-hooks-run-in-the-order) | Claude Code 在 `tool.call` 與 `PreToolUse` hook 之後，決定工具呼叫是否可以執行時。`next(e)` 會解析為規則、權限模式與這些 hook 所得出的決定。 | `next(e)` 或 `{ decision }`，其中 `decision` 設為 `allow`、`ask` 或 `deny`，並可選擇附上 `reason` |

60| `tool.describe` | 每個工具一次，在其說明首次傳送給 Claude 時。當 Claude 透過[工具搜尋](https://code.claude.com/docs/zh-TW/mcp.md#scale-with-mcp-tool-search)載入 MCP 工具時會再觸發一次，此時 `e.description` 設為 Claude 針對已載入工具所讀取的文字。 | `{ description }`，可選擇將 `isDeferred` 設為 `true` 以將該工具置於工具搜尋之後，或設為 `false` 以預先載入 |60| `tool.describe` | 每個工具一次，在其說明首次傳送給 Claude 時。當 Claude 透過[工具搜尋](https://code.claude.com/docs/zh-TW/mcp.md#scale-with-mcp-tool-search)載入 MCP 工具時會再觸發一次，此時 `e.description` 設為 Claude 針對已載入工具所讀取的文字。 | `{ description }`，可選擇將 `isDeferred` 設為 `true` 以將該工具置於工具搜尋之後，或設為 `false` 以預先載入。加上 [`breakPromptCache: true`](#break-prompt-cache) 即可在下一個回合傳送變更後的說明。 |

61 61

62#### `tool.check` 上的 agent 與組織欄位62#### `tool.check` 上的 agent 與組織欄位

63 63

86| `prompt.autocomplete` | 使用者在提示詞輸入框中輸入，且有一個字詞在游標處結束時。`e.token` 即為該字詞。Claude Code 不會等待此 hook：其自身的自動完成列會先顯示。 | `{ suggestions }`，即顯示在 Claude Code 自身列下方的 `{ text, label, description }` 列清單。選擇某一列會以其 `text` 覆寫該字詞。 |86| `prompt.autocomplete` | 使用者在提示詞輸入框中輸入，且有一個字詞在游標處結束時。`e.token` 即為該字詞。Claude Code 不會等待此 hook：其自身的自動完成列會先顯示。 | `{ suggestions }`，即顯示在 Claude Code 自身列下方的 `{ text, label, description }` 列清單。選擇某一列會以其 `text` 覆寫該字詞。 |

87| `prompt.compose` | Claude Code 轉譯系統提示詞時 | `{ sections }`，即依傳送順序排列的 `{ id, text, scope }` 清單 |87| `prompt.compose` | Claude Code 轉譯系統提示詞時 | `{ sections }`，即依傳送順序排列的 `{ id, text, scope }` 清單 |

88| [`prompt.section`](https://code.claude.com/docs/zh-TW/plugins/mods/events#rewrite-or-add-to-a-prompt) | 系統提示詞的每個具名區段各一次。`e.name` 是該區段在 `prompt.compose` 中的 `id`。 | `{ text }`，或以 `{ text: null }` 省略該區段 |88| [`prompt.section`](https://code.claude.com/docs/zh-TW/plugins/mods/events#rewrite-or-add-to-a-prompt) | 系統提示詞的每個具名區段各一次。`e.name` 是該區段在 `prompt.compose` 中的 `id`。 | `{ text }`，或以 `{ text: null }` 省略該區段。加上 [`breakPromptCache: true`](#break-prompt-cache) 即可在下一個回合傳送變更後的區段。 |

89| [`prompt.context`](https://code.claude.com/docs/zh-TW/plugins/mods/events#rewrite-or-add-to-a-prompt) | 每個對話一次，針對隨第一則訊息傳送的上下文 | `{ blocks }` |89| [`prompt.context`](https://code.claude.com/docs/zh-TW/plugins/mods/events#rewrite-or-add-to-a-prompt) | 每個對話一次，針對隨第一則訊息傳送的上下文 | `{ blocks }` |

90| `prompt.attachment` | Claude Code 為 Claude 新增一則自己的訊息時，例如提醒。`e.type` 指出種類，對於型別有宣告的種類，`e.detail` 存放撰寫該文字所依據的事實。 | `{ text }`，或以 `{ text: null }` 省略 |90| `prompt.attachment` | Claude Code 為 Claude 新增一則自己的訊息時，例如提醒。`e.type` 指出種類，對於型別有宣告的種類，`e.detail` 存放撰寫該文字所依據的事實。 | `{ text }`，或以 `{ text: null }` 省略 |

91| `prompt.mention` | Claude Code 即將讀取提示詞以 @ 提及的檔案時。需要 Claude Code v2.1.290 或更新版本。 | 以 `next({ ...e, path })` 改為讀取其他檔案，或 `{ deny: reason }` |91| `prompt.mention` | Claude Code 即將讀取提示詞以 @ 提及的檔案時。需要 Claude Code v2.1.290 或更新版本。 | 以 `next({ ...e, path })` 改為讀取其他檔案，或 `{ deny: reason }` |

108 108

109在 `skill.prompt` 上，`e.source`、`e.pluginName`、`e.path`、`e.frontmatter` 與 `e.frontmatterProblem` 需要 Claude Code v2.1.299 或更新版本。109在 `skill.prompt` 上，`e.source`、`e.pluginName`、`e.path`、`e.frontmatter` 與 `e.frontmatterProblem` 需要 Claude Code v2.1.299 或更新版本。

110 110

111#### 使用 `breakPromptCache` 傳送變更後的系統提示詞區段或工具說明

112

113若要在進行中的對話中變更區段或工具說明，請呼叫 `$.ui.invalidate('prompt.section')` 或 `$.ui.invalidate('tool.describe')`，讓您的 hook 再次執行。並從該 hook 回傳 `{ text, breakPromptCache: true }` 或 `{ description, breakPromptCache: true }`。若沒有此欄位，對於區段或預先載入的工具，Claude 會持續讀取[隨對話儲存](https://code.claude.com/docs/zh-TW/cli-reference.md#system-prompt-flags-in-resumed-conversations)的文字，直到新的對話開始或發生[壓縮](https://code.claude.com/docs/zh-TW/prompt-caching.md#compacting-the-conversation)為止。

114

115變更後的文字會在下一個回合傳達給 Claude，且[提示快取](https://code.claude.com/docs/zh-TW/prompt-caching.md)會重新開始，因此該回合會較慢且成本較高。此欄位需要 Claude Code v2.1.321 或更新版本。從 v2.1.299 到 v2.1.321 之前，進行中的對話會在下一個回合取得變更後的文字。

116

111### 命令與設定117### 命令與設定

112 118

113| 事件 | 觸發時機 | hook 可回傳 |119| 事件 | 觸發時機 | hook 可回傳 |

212| 命名空間 | 方法 |218| 命名空間 | 方法 |

213| :- | :- |219| :- | :- |

215| [`$.ui`](https://code.claude.com/docs/zh-TW/plugins/mods/interface#pick-where-to-draw) | `resolve`、`invalidate`、`open`、`close`、`panes`、`focus`、`scroll`、`toast`、`notify`、`status`、`log`、`notice`、`ask`、`copy`、`selection`、`blit` |221| [`$.ui`](https://code.claude.com/docs/zh-TW/plugins/mods/interface#pick-where-to-draw) | `resolve`、`invalidate`、`open`、`close`、`panes`、[`place`](https://code.claude.com/docs/zh-TW/plugins/mods/interface#place-a-row-in-the-transcript)、`focus`、`scroll`、`toast`、`notify`、`status`、`log`、`notice`、`ask`、`copy`、`selection`、`blit`、`view`。`view` 需要 Claude Code v2.1.300 或更新版本，`place` 需要 v2.1.314 或更新版本。 |

222| [`$.theme`](https://code.claude.com/docs/zh-TW/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `set`、`clear`：設定供 Desktop 或行動應用程式繪製的背景，以及移除該背景。需要 Claude Code v2.1.319 或更新版本。 |

218| `$.agent` | `register`、`spawn`、`list`。`list()` 會回傳此工作階段的 subagent 與隊友，每個都帶有 `status`，其值為 `pending`、`running`、`waiting`、`idle`、`completed`、`failed` 或 `killed`，其中 `idle` 與 `waiting` 需要 Claude Code v2.1.289 或更新版本。 |225| `$.agent` | `register`、`spawn`、`list`。`list()` 會回傳此工作階段的 subagent 與隊友，每個都帶有 `status`，其值為 `pending`、`running`、`waiting`、`idle`、`completed`、`failed` 或 `killed`，其中 `idle` 與 `waiting` 需要 Claude Code v2.1.289 或更新版本。 |

243| :- | :- | :- | :- |250| :- | :- | :- | :- |

254| [`Backdrop`](https://code.claude.com/docs/zh-TW/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `id`、`plugin`、`glass`、`colorScheme` | `backdrop` | `desktop` 與 `mobile` 使用介面。當 Desktop 或行動應用程式要求繪製背景時，您的 hook 就會執行。 |

400| `$.ui.toast` | 顯示 4 秒，除非您傳入 `{ timeoutMs }`。在[傳統轉譯器](https://code.claude.com/docs/zh-TW/fullscreen.md#enable-fullscreen-rendering)中，mod 較新的 toast 可能會[取代其較舊的 toast](https://code.claude.com/docs/zh-TW/plugins/mods/troubleshoot.md#a-toast-doesn’t-appear)，無論後者正在顯示或正等待顯示。 |409| `$.ui.toast` | 顯示 4 秒，除非您傳入 `{ timeoutMs }`。在[傳統轉譯器](https://code.claude.com/docs/zh-TW/fullscreen.md#enable-fullscreen-rendering)中，mod 較新的 toast 可能會[取代其較舊的 toast](https://code.claude.com/docs/zh-TW/plugins/mods/troubleshoot.md#a-toast-doesn’t-appear)，無論後者正在顯示或正等待顯示。 |

401| 未經使用者要求而開啟的窗格 | 自 144 個終端機欄寬起放置，使用者開啟過一次後則為 110 |410| 未經使用者要求而開啟的窗格 | 自 144 個終端機欄寬起放置，使用者開啟過一次後則為 110 |

411| 單一 mod 在一個對話中同時擁有的來自 `$.ui.place` 的列 | 500。達到上限時，使用新 `id` 的呼叫會解析為 `{ isPlaced: false, reason: 'a plugin holds at most 500 placed rows' }`。 |

402| mods API 呼叫之引數的巢狀深度 | 28,000 層。超過此深度時，呼叫會被拒絕，訊息以 `nesting deeper than 28000 levels is not supported` 結尾。需要 Claude Code v2.1.299 或更新版本。 |412| mods API 呼叫之引數的巢狀深度 | 28,000 層。超過此深度時，呼叫會被拒絕，訊息以 `nesting deeper than 28000 levels is not supported` 結尾。需要 Claude Code v2.1.299 或更新版本。 |

403| 傳給 `next` 的已變更事件之巢狀深度，[非同步產生器 hook](#events)（例如 `turn.step` 上的 hook）除外 | 28,000 層。超過此深度時，`next` 會被拒絕，訊息以 `nesting deeper than 28000 levels is not supported` 結尾。需要 Claude Code v2.1.299 或更新版本。 |413| 傳給 `next` 的已變更事件之巢狀深度，[非同步產生器 hook](#events)（例如 `turn.step` 上的 hook）除外 | 28,000 層。超過此深度時，`next` 會被拒絕，訊息以 `nesting deeper than 28000 levels is not supported` 結尾。需要 Claude Code v2.1.299 或更新版本。 |

404| hook 傳回值的巢狀深度，`ui.render`、`ui.resolve` 與非同步產生器 hook 除外 | 28,000 層。超過此深度時，hook 的結果會被拒絕，而[回報此情況的通知](https://code.claude.com/docs/zh-TW/plugins/mods/troubleshoot.md#find-out-why-a-mod-does-nothing)會包含 `nesting deeper than 28000 levels is not supported`。需要 Claude Code v2.1.299 或更新版本。 |414| hook 傳回值的巢狀深度，`ui.render`、`ui.resolve` 與非同步產生器 hook 除外 | 28,000 層。超過此深度時，hook 的結果會被拒絕，而[回報此情況的通知](https://code.claude.com/docs/zh-TW/plugins/mods/troubleshoot.md#find-out-why-a-mod-does-nothing)會包含 `nesting deeper than 28000 levels is not supported`。需要 Claude Code v2.1.299 或更新版本。 |

405| 在 hook 模組的單一檔案中彼此巢狀的作用域，例如函式、區塊與迴圈 | 2,000 |415| 在 hook 模組的單一檔案中彼此巢狀的作用域，例如函式、區塊與迴圈 | 2,000 |

408 418

409## 設定與環境變數419## 設定與環境變數

prompt-caching.md +2 −2

Details

33有兩個設定不會出現在層級表中，但仍會影響保留的快取內容：33有兩個設定不會出現在層級表中，但仍會影響保留的快取內容：

34 34

35* **Model**：每個模型都有自己的快取。切換模型會重新計算整個請求，即使內容相同。請參閱下面的 [Switching models](#switching-models)。35* **Model**：每個模型都有自己的快取。切換模型會重新計算整個請求，即使內容相同。請參閱下面的 [Switching models](#switching-models)。

36* **Effort 等級**：在大多數模型上，每個 effort 等級都有自己的快取，因此在工作階段中途變更 effort 會重新計算整個請求。在具有 API 金鑰或 Claude 訂閱的 Opus 5.5、Sonnet 5.5、Haiku 5.5 和 Fable 5.1 上，快取預設保持完整。請參閱下面的 [Changing effort level](#changing-effort-level)。36* **Effort 等級**：在大多數模型上，每個 effort 等級都有自己的快取，因此在工作階段中途變更 effort 會重新計算整個請求。使用 API 金鑰或 Claude 訂閱時，在 Fable 5.1 及更新版本、Opus 5.5、Sonnet 5.5 和 Haiku 5.5 上，快取預設保持完整。請參閱下面的 [Changing effort level](#changing-effort-level)。

37 37

38> [!TIP]38> [!TIP]

39>39>

94 94

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

96 96

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

98 98

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

100 100

remote-control.md +3 −0

Details

49> claude remote-control49> claude remote-control

50> ```50> ```

51>51>

52> `claude rc` 是此命令的別名。

53>

52> 在您接受 Remote Control 的一次性確認之前，`claude remote-control` 會說明其功能，並在啟動伺服器前詢問 `Enable Remote Control? (y/n)`。回答 `y` 即可接受並啟動伺服器。若您拒絕，Claude Code 會在不啟動伺服器的情況下結束，並在您下次執行此命令時再次詢問。54> 在您接受 Remote Control 的一次性確認之前，`claude remote-control` 會說明其功能，並在啟動伺服器前詢問 `Enable Remote Control? (y/n)`。回答 `y` 即可接受並啟動伺服器。若您拒絕，Claude Code 會在不啟動伺服器的情況下結束，並在您下次執行此命令時再次詢問。

53>55>

54> 在伺服器模式下，此程序會持續在終端機中執行，等待遠端連線。它會顯示一個 URL，您可以用來[從其他裝置連線](#connect-from-another-device)，也可以按空白鍵顯示 QR 碼，以便從手機快速存取。當遠端工作階段處於作用中狀態時，終端機會顯示連線狀態和工具活動。56> 在伺服器模式下，此程序會持續在終端機中執行，等待遠端連線。它會顯示一個 URL，您可以用來[從其他裝置連線](#connect-from-another-device)，也可以按空白鍵顯示 QR 碼，以便從手機快速存取。當遠端工作階段處於作用中狀態時，終端機會顯示連線狀態和工具活動。

462* **您的 claude.ai 計畫是 Pro、Max 或 Ultra**：Claude Code 仍在來自較早登入的 Team 或 Enterprise 組織下登入，因此它會檢查該組織的 Remote Control 原則。執行 `/status` 以查看您的登入使用哪個計畫和組織。執行 `claude auth logout` 然後 `claude auth login` 以在您目前的計畫下重新登入。464* **您的 claude.ai 計畫是 Pro、Max 或 Ultra**：Claude Code 仍在來自較早登入的 Team 或 Enterprise 組織下登入，因此它會檢查該組織的 Remote Control 原則。執行 `/status` 以查看您的登入使用哪個計畫和組織。執行 `claude auth logout` 然後 `claude auth login` 以在您目前的計畫下重新登入。

463* **訊息未說要聯絡您的組織管理員**：您的組織已套用 [HIPAA 設定](https://code.claude.com/docs/zh-TW/hipaa-setup.md)，這會關閉 Remote Control。若要確認，請執行 `/status` 並在 `Organization configuration` 列中尋找 `HIPAA`。擁有者會在[管理設定](https://claude.ai/admin-settings/claude-code)中看到 **Remote Control** 切換呈灰色，且無法將其開啟。如果您對此設定有疑問，請詢問擁有者，擁有者可以聯絡您組織的 Anthropic 客戶團隊。在 v2.1.267 之前，此情況顯示「Remote Control isn't available for your organization due to its compliance policy」。465* **訊息未說要聯絡您的組織管理員**：您的組織已套用 [HIPAA 設定](https://code.claude.com/docs/zh-TW/hipaa-setup.md)，這會關閉 Remote Control。若要確認，請執行 `/status` 並在 `Organization configuration` 列中尋找 `HIPAA`。擁有者會在[管理設定](https://claude.ai/admin-settings/claude-code)中看到 **Remote Control** 切換呈灰色，且無法將其開啟。如果您對此設定有疑問，請詢問擁有者，擁有者可以聯絡您組織的 Anthropic 客戶團隊。在 v2.1.267 之前，此情況顯示「Remote Control isn't available for your organization due to its compliance policy」。

464* **Remote Control 對組織中的其他人有效，但對您無效**：如果您的 Enterprise 組織透過[自訂角色](https://support.claude.com/en/articles/13930452)管理您的存取權，您的角色可能是原因。Remote Control 同時需要雲端工作階段權限和 **Claude Code remote control** 權限。請擁有者檢查您的角色是否包含這兩項權限，並在 [**Organization settings > Roles**](https://claude.ai/admin-settings/roles) 新增缺少的權限。466* **Remote Control 對組織中的其他人有效，但對您無效**：如果您的 Enterprise 組織透過[自訂角色](https://support.claude.com/en/articles/13930452)管理您的存取權，您的角色可能是原因。Remote Control 同時需要雲端工作階段權限和 **Claude Code remote control** 權限。請擁有者檢查您的角色是否包含這兩項權限，並在 [**Organization settings > Roles**](https://claude.ai/admin-settings/roles) 新增缺少的權限。

467* **擁有者在[管理設定](https://claude.ai/admin-settings/claude-code)中看到 [Zero Data Retention](https://code.claude.com/docs/zh-TW/zero-data-retention.md) 橫幅**：Remote Control 不適用於您的組織，且擁有者無法將其開啟。

465* **否則，擁有者尚未為您的組織啟用它**：Remote Control 在 Team 和 Enterprise 計畫上預設為關閉。擁有者可以在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 啟用它，方法是開啟 **Remote Control** 切換。此切換是伺服器端組織設定。468* **否則，擁有者尚未為您的組織啟用它**：Remote Control 在 Team 和 Enterprise 計畫上預設為關閉。擁有者可以在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 啟用它，方法是開啟 **Remote Control** 切換。此切換是伺服器端組織設定。

466 469

467在 v2.1.281 之前，當 Claude Code 未在此機器上載入您的組織原則時，此訊息也會出現，例如在離線啟動後。更新版本會改為將該狀態報告為 [`Couldn't verify your organization's policy for remote control`](#couldnt-verify-your-organizations-policy-for-remote-control)。470在 v2.1.281 之前，當 Claude Code 未在此機器上載入您的組織原則時，此訊息也會出現，例如在離線啟動後。更新版本會改為將該狀態報告為 [`Couldn't verify your organization's policy for remote control`](#couldnt-verify-your-organizations-policy-for-remote-control)。

self-hosted-environments-configuration.md +5 −1

Details

154| :- | :- |154| :- | :- |

156| `CLAUDE_RUNNER_REPO_REF` | 要簽出的修訂版本，依工作階段的要求而定：分支、標籤、提交 SHA，或完整參照名稱，例如 `refs/heads/<branch>` 或 `refs/pull/<number>/head`。空值表示儲存庫的預設分支。 |156| `CLAUDE_RUNNER_REPO_REF` | 要簽出的修訂版本，依工作階段的要求而定：分支、標籤、提交 SHA，或完整參照名稱，例如 `refs/heads/<branch>` 或 `refs/pull/<number>/head`。空值表示儲存庫的預設分支。 |

166 166

167在您的 hook 返回後，執行器會驗證 `CLAUDE_RUNNER_CHECKOUT_PATH` 包含 `.git`。如果您的 hook 具體化的是非 git 來源（例如 Perforce 或解開的 tarball），請在執行器的環境中設定 `CLAUDE_RUNNER_SKIP_GIT_VERIFY=1` 以略過該檢查。基於 Git 的流程（例如建立工作分支與推送結果）需要 git 簽出，因此請使用 [`post-session` hook](#post-session) 從非 git 樹匯出結果。167在您的 hook 返回後，執行器會驗證 `CLAUDE_RUNNER_CHECKOUT_PATH` 包含 `.git`。如果您的 hook 具體化的是非 git 來源（例如 Perforce 或解開的 tarball），請在執行器的環境中設定 `CLAUDE_RUNNER_SKIP_GIT_VERIFY=1` 以略過該檢查。基於 Git 的流程（例如建立工作分支與推送結果）需要 git 簽出，因此請使用 [`post-session` hook](#post-session) 從非 git 樹匯出結果。

168 168

169#### 簽出資料夾名稱

170

171`CLAUDE_RUNNER_CHECKOUT_PATH` 以名為 `<repo-owner>-<repo>` 的資料夾結尾，例如 `acme-api`。同一工作階段中的兩個儲存庫不能共用資料夾，即使它們的名稱僅有大小寫差異也是如此。例如，如果工作階段先列出 `acme/api`，再列出 `Acme/API`，第一個會取得 `acme-api`，第二個會取得 `Acme-API-2`。

172

169#### 在 hook 中取得 git 憑證173#### 在 hook 中取得 git 憑證

170 174

171執行器不會將 git 憑證傳遞給 hook。`decode-token` 子命令在此也無法使用，因為 `CLAUDE_RUNNER_CLAUDE_BIN` 未在 checkout hook 環境中設定。請改為從工作階段的身分產生每個工作階段的複製憑證，或退而使用主機本身的 git 身分驗證：175執行器不會將 git 憑證傳遞給 hook。`decode-token` 子命令在此也無法使用，因為 `CLAUDE_RUNNER_CLAUDE_BIN` 未在 checkout hook 環境中設定。請改為從工作階段的身分產生每個工作階段的複製憑證，或退而使用主機本身的 git 身分驗證：

self-hosted-environments-deploy.md +19 −2

Details

23 * **使用 [Anthropic 管理的 git](#use-the-anthropic-git-proxy) 時**：若有此類憑證，Claude 會直接連線到 GitHub，而不是透過 Anthropic 管理的 git。23 * **使用 [Anthropic 管理的 git](#use-the-anthropic-git-proxy) 時**：若有此類憑證，Claude 會直接連線到 GitHub，而不是透過 Anthropic 管理的 git。

24 * **不使用 Anthropic 管理的 git 時**：如果您依照[在映像中提供 git 設定](#ship-git-config-in-your-image)所述嚴格限制其範圍，複製憑證可以保留在映像中。24 * **不使用 Anthropic 管理的 git 時**：如果您依照[在映像中提供 git 設定](#ship-git-config-in-your-image)所述嚴格限制其範圍，複製憑證可以保留在映像中。

25* **將環境祕密保留在執行工作階段的主機之外**：環境祕密可以註冊執行器並拾取在環境上排隊的任何工作階段。在固定群中，它存在於每個執行器主機上，任何工作階段的程式碼都可以讀取祕密檔案。優先使用[按需執行器](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration.md#on-demand-runners)，其中祕密保留在協調器主機上，該主機永遠不執行使用者程式碼，每個執行器接收單次使用的工作單據，該單據恰好註冊一個執行器。在固定群中，將環境祕密檔案視為可由每個工作階段讀取，並在任何懷疑的工作階段洩露後輪換祕密。25* **將環境祕密保留在執行工作階段的主機之外**：環境祕密可以註冊執行器並拾取在環境上排隊的任何工作階段。在固定群中，它存在於每個執行器主機上，任何工作階段的程式碼都可以讀取祕密檔案。優先使用[按需執行器](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration.md#on-demand-runners)，其中祕密保留在協調器主機上，該主機永遠不執行使用者程式碼，每個執行器接收單次使用的工作單據，該單據恰好註冊一個執行器。在固定群中，將環境祕密檔案視為可由每個工作階段讀取，並在任何懷疑的工作階段洩露後輪換祕密。

26 * **懷疑遭入侵後**：請由[所有者](https://code.claude.com/docs/zh-TW/cloud-environments.md#organization-shared-environments)在環境的 **Configuration** 分頁中建立新的祕密並撤銷舊的祕密，然後部署新的祕密。Anthropic 會拒絕所有使用舊祕密的協調器和執行器，包括透過其工作單據啟動的按需執行器。您的執行器會結束，其工作階段也會因此中斷。

26* **預設拒絕網路出站流量**：在每個環境上限制執行器和工作階段容器的出站流量在您自己的網路邊界；[預設拒絕出站流量](#default-deny-egress)涵蓋允許什麼以及為什麼。27* **預設拒絕網路出站流量**：在每個環境上限制執行器和工作階段容器的出站流量在您自己的網路邊界；[預設拒絕出站流量](#default-deny-egress)涵蓋允許什麼以及為什麼。

27* **最小權限主機 IAM**：附加到執行器主機的計算身份，例如執行個體設定檔或節點服務帳戶，應僅授予執行器本身需要的內容。工作階段應通過您的包裝器指令碼而不是繼承主機的身份來獲得自己的認證。28* **最小權限主機 IAM**：附加到執行器主機的計算身份，例如執行個體設定檔或節點服務帳戶，應僅授予執行器本身需要的內容。工作階段應通過您的包裝器指令碼而不是繼承主機的身份來獲得自己的認證。

28* **阻止工作階段的雲端中繼資料端點**：將工作階段保留在主機身份之外需要阻止它們對雲端中繼資料端點的存取，子網級出站流量原則不會攔截連結本地中繼資料流量，因此在容器本身中阻止它：29* **阻止工作階段的雲端中繼資料端點**：將工作階段保留在主機身份之外需要阻止它們對雲端中繼資料端點的存取，子網級出站流量原則不會攔截連結本地中繼資料流量，因此在容器本身中阻止它：

203> [!WARNING]204> [!WARNING]

204>205>

205> 設定 `--use-anthropic-git-proxy` 時，執行器會刪除並取代其執行身分使用者的全域 Git 設定，且不保留任何備份。它會在啟動時以及每個工作階段之前執行此操作。您保存在那裡的登入資訊或憑證輔助程式將會遺失。[`--configure-git`](#let-the-runner-configure-git) 寫入的設定則會保留。請以專用使用者身分或在容器中執行執行器，切勿以您自己的使用者身分執行。206> 設定 `--use-anthropic-git-proxy` 時，執行器會刪除並取代其執行身分使用者的全域 Git 設定，且不保留任何備份。它會在啟動時以及每個工作階段之前執行此操作。您保存在那裡的登入資訊或憑證輔助程式將會遺失。[`--configure-git`](#let-the-runner-configure-git) 寫入的設定則會保留。請以專用使用者身分或在容器中執行執行器，切勿以您自己的使用者身分執行。

207>

208> 全域 Git 設定包括以下三者：`~/.gitconfig`、您設定 `GIT_CONFIG_GLOBAL` 時其所指定的檔案，以及整個 `$XDG_CONFIG_HOME/git` 目錄（預設為 `~/.config/git`）。

206 209

207請將非機密的 Git 設定（例如身分和 `safe.directory`）保存在系統 Git 設定中。210請將非機密的 Git 設定（例如身分和 `safe.directory`）保存在系統 Git 設定中。

208 211

247* **包含 `remote: access denied by the git proxy` 的行**：即使是 Anthropic 所服務的工作階段仍可能被拒絕，例如當組織政策拒絕該工作階段的 Git 存取，或該工作階段未獲授權存取該儲存庫時。此時執行器的日誌會顯示一行包含 `remote: access denied by the git proxy` 的內容，該行其餘部分會說明原因。250* **包含 `remote: access denied by the git proxy` 的行**：即使是 Anthropic 所服務的工作階段仍可能被拒絕，例如當組織政策拒絕該工作階段的 Git 存取，或該工作階段未獲授權存取該儲存庫時。此時執行器的日誌會顯示一行包含 `remote: access denied by the git proxy` 的內容，該行其餘部分會說明原因。

248* **`GitHub authentication required`**：當工作階段建立者在 claude.ai 上沒有可用的 GitHub 連結時會出現此訊息。工作階段的複製會失敗，Git 錯誤訊息為 `GitHub authentication required. Please reconnect your GitHub account.` 請該使用者在其 claude.ai 設定中連結或重新連結 GitHub。251* **`GitHub authentication required`**：當工作階段建立者在 claude.ai 上沒有可用的 GitHub 連結時會出現此訊息。工作階段的複製會失敗，Git 錯誤訊息為 `GitHub authentication required. Please reconnect your GitHub account.` 請該使用者在其 claude.ai 設定中連結或重新連結 GitHub。

249 252

250修正原因後，請重新啟動失敗的工作階段。253修正原因後，請重新啟動使工作階段失敗的執行器，然後請每位建立者在其工作階段中傳送一則訊息，或由 Owner 選取 **Retry**。

251 254

252#### 關閉 Anthropic Git 代理伺服器255#### 關閉 Anthropic Git 代理伺服器

253 256

265 268

266為執行器工作階段使用的每個 Git 主機（包括 github.com）提供無需提示即可運作的憑證。執行器使用者全域 Git 設定中原有的任何憑證都已消失，因為在設定 `--use-anthropic-git-proxy` 期間，執行器已刪除該設定。請[在映像中提供憑證](#ship-git-config-in-your-image)，或使用 [`checkout` 生命週期 hook](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration#checkout)。269為執行器工作階段使用的每個 Git 主機（包括 github.com）提供無需提示即可運作的憑證。執行器使用者全域 Git 設定中原有的任何憑證都已消失，因為在設定 `--use-anthropic-git-proxy` 期間，執行器已刪除該設定。請[在映像中提供憑證](#ship-git-config-in-your-image)，或使用 [`checkout` 生命週期 hook](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration#checkout)。

267 270

271若要改為將憑證保存在[全域 Git 設定](#git-proxy-replaces-global-git-config)中，請先[停止執行器](#shutdown-timing)，因為以該旗標啟動的執行器會在每個工作階段之前重寫該設定。接著刪除 `$XDG_CONFIG_HOME/git`（預設為 `~/.config/git`），並以您自己的檔案取代 `~/.gitconfig` 或 `GIT_CONFIG_GLOBAL` 所指定的檔案。

272

268**3. 開放網路路徑**273**3. 開放網路路徑**

269 274

270允許執行器透過連接埠 443 或 22 連線到執行器工作階段使用的每個 Git 主機。請參閱[網路需求](#network-requirements)中的 Git 主機列。275允許執行器透過連接埠 443 或 22 連線到執行器工作階段使用的每個 Git 主機。請參閱[網路需求](#network-requirements)中的 Git 主機列。

507 512

508## Kubernetes513## Kubernetes

509 514

510執行器預設在連接埠 8080 上提供 `GET /healthz`，可使用 `--health-port` 配置，因此 Kubernetes 探針無需額外設定即可工作。端點在程序活著時返回 `200`，因此下面的探針檢測死程序，而不是卡住的程序；要捕捉停止輪詢的執行器，請在 [`/metrics`](https://code.claude.com/docs/zh-TW/self-hosted-environments-reference#prometheus-metrics) 的 `last_poll_age_seconds` 系列上發出警報。下面的 Deployment 從 Kubernetes Secret 掛載環境祕密，將活躍度和就緒探針指向 `/healthz`，並設定 90 秒的終止寬限期。請參閱[關閉時序](#shutdown-timing)以了解為什麼寬限期很重要。515執行器預設在連接埠 8080 上提供 `GET /healthz`，可使用 `--health-port` 設定。啟動後，只要程序仍在執行，端點就會返回 `200`，因此下面的探針偵測的是已終止的程序，而不是卡住的程序。若要捕捉停止輪詢的執行器，請針對 [`/metrics`](https://code.claude.com/docs/zh-TW/self-hosted-environments-reference#prometheus-metrics) 中的 `last_poll_age_seconds` 系列設定警報。

516

517下面的 Deployment 從 Kubernetes Secret 掛載環境祕密，將活躍度和就緒探針指向 `/healthz`，並設定 90 秒的終止寬限期。請參閱[關閉時序](#shutdown-timing)以了解為什麼寬限期很重要。

511 518

512清單在執行器容器上設定沒有 CPU 或記憶體 `resources`。添加為您執行的容量調整大小的塊，如[為工作階段調整 CPU 和記憶體大小](#size-cpu-and-memory-for-sessions)所述。519清單在執行器容器上設定沒有 CPU 或記憶體 `resources`。添加為您執行的容量調整大小的塊，如[為工作階段調整 CPU 和記憶體大小](#size-cpu-and-memory-for-sessions)所述。

513 520

565 secretName: claude-runner-environment-secret572 secretName: claude-runner-environment-secret

566```573```

567 574

575> [!NOTE]

576>

577> 如果 pod 的事件顯示活躍度探針在啟動期間失敗，請提高其 `initialDelaySeconds` 或新增 `startupProbe`。在執行器完成註冊並完成啟動檢查之前，健康狀態連接埠不會有任何回應。使用上述設定時，若執行器在約 90 秒內未開始提供服務，Kubernetes 會將其重新啟動。

578

568上面的 Deployment 位於 `claude-runners` 命名空間中。首先建立命名空間：579上面的 Deployment 位於 `claude-runners` 命名空間中。首先建立命名空間：

569 580

570```bash theme={null}581```bash theme={null}

942 如果每個呼叫在工作階段開始約 30 分鐘後都開始失敗，很可能是包裝腳本切斷了工作階段的 stdin，導致 token 輪換無法送達；請參閱[保持 stdin 與檔案描述元 3 連接](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration.md#keep-stdin-and-file-descriptor-3-attached)。953 如果每個呼叫在工作階段開始約 30 分鐘後都開始失敗，很可能是包裝腳本切斷了工作階段的 stdin，導致 token 輪換無法送達；請參閱[保持 stdin 與檔案描述元 3 連接](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration.md#keep-stdin-and-file-descriptor-3-attached)。

943 954

944 在 v2.1.274 之前，runner 在幾次嘗試後就會停止重試失敗的取得，並等待下一次排定的取得。失敗的回合不會觸發取得，因此在下一次排定的取得之前，每個回合都會以 401 失敗。955 在 v2.1.274 之前，runner 在幾次嘗試後就會停止重試失敗的取得，並等待下一次排定的取得。失敗的回合不會觸發取得，因此在下一次排定的取得之前，每個回合都會以 401 失敗。

956* **工作階段顯示 `The server has refused to renew this session's access to the model`**：工作階段的 [`CLAUDE_CODE_OAUTH_TOKEN`](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration#wrapper-scripts) 已過期，且 runner 在請求新 token 時收到 HTTP 400 回應。Runner 會記錄 `the server has refused to renew the inference_token`。該工作階段中的回合會失敗。只要工作階段的程序仍在執行，runner 就會持續請求新的 token：

957

958 * **請求成功**：曾顯示該警告的工作階段接著會顯示 `The server renewed this session's access to the model`

959 * **回合持續失敗**：該程序最終會結束，工作階段會顯示失敗訊息，例如 `The session process exited with code 1`

960

961 若要在不等待新 token 的情況下繼續工作，請啟動新的工作階段。如果新的工作階段也失敗，請檢查是否是您的某個代理伺服器或閘道給出了 HTTP 400 回應。如果都不是，請附上第一個工作階段的 ID [聯絡您的 Anthropic 客戶團隊](#report-an-issue)。

945* **回合在 claude.ai/code 中以 `This model needs a newer version of Claude Code` 失敗**：您的 runner 用來啟動工作階段的 Claude Code 版本比工作階段的模型所要求的版本舊，因此 API [拒絕了該請求](https://code.claude.com/docs/zh-TW/errors.md#claude-code-does-not-support-this-model)。請將 runner 升級至訊息要求的版本或更新版本，如[固定版本](#pin-the-version)中所述。在此之前，使用者可以在工作階段中選擇其他模型。962* **回合在 claude.ai/code 中以 `This model needs a newer version of Claude Code` 失敗**：您的 runner 用來啟動工作階段的 Claude Code 版本比工作階段的模型所要求的版本舊，因此 API [拒絕了該請求](https://code.claude.com/docs/zh-TW/errors.md#claude-code-does-not-support-this-model)。請將 runner 升級至訊息要求的版本或更新版本，如[固定版本](#pin-the-version)中所述。在此之前，使用者可以在工作階段中選擇其他模型。

946* **Pod 在排空過程中被終止**：請將 `terminationGracePeriodSeconds` 提高至至少 runner 在啟動時記錄的值。請參閱[關閉時序](#shutdown-timing)。963* **Pod 在排空過程中被終止**：請將 `terminationGracePeriodSeconds` 提高至至少 runner 在啟動時記錄的值。請參閱[關閉時序](#shutdown-timing)。

947* **Runner 記錄以 `was paused or too slow` 結尾的 `[runner:log]` 行**：runner 仍持續執行，不需要重新啟動。在該行所指名的 stdout 或 stderr 串流再次被讀取之前，runner 會捨棄該串流中除最新 256 KiB 以外的所有行。如果您傳入了 [`--log-file`](https://code.claude.com/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags)，請在該處尋找被捨棄的行。964* **Runner 記錄以 `was paused or too slow` 結尾的 `[runner:log]` 行**：runner 仍持續執行，不需要重新啟動。在該行所指名的 stdout 或 stderr 串流再次被讀取之前，runner 會捨棄該串流中除最新 256 KiB 以外的所有行。如果您傳入了 [`--log-file`](https://code.claude.com/docs/zh-TW/self-hosted-environments-reference#runner-cli-flags)，請在該處尋找被捨棄的行。

self-hosted-environments-quickstart.md +3 −1

Details

73 73

74前往管理設定中的[**雲端環境**頁面](https://claude.ai/admin-settings/cloud-environments)。在**自託管環境**下，選擇**新增**，命名環境，然後選擇**建立**。在精靈的第二步，選擇**複製環境金鑰**以複製環境密鑰，管理 UI 將其標記為環境金鑰。claude.ai 只顯示一次密鑰，您之後無法檢索它；它在建立後 365 天過期。環境的 `ccpool_...` ID 在其詳細對話方塊中保持可見；您需要它用於[令牌驗證](https://code.claude.com/docs/zh-TW/self-hosted-environments-identity.md)中的 `aud` 檢查，以及用於從 CI [分派測試工作階段](https://code.claude.com/docs/zh-TW/self-hosted-environments-testing.md#run-the-test-loop)。74前往管理設定中的[**雲端環境**頁面](https://claude.ai/admin-settings/cloud-environments)。在**自託管環境**下，選擇**新增**，命名環境，然後選擇**建立**。在精靈的第二步，選擇**複製環境金鑰**以複製環境密鑰，管理 UI 將其標記為環境金鑰。claude.ai 只顯示一次密鑰，您之後無法檢索它；它在建立後 365 天過期。環境的 `ccpool_...` ID 在其詳細對話方塊中保持可見；您需要它用於[令牌驗證](https://code.claude.com/docs/zh-TW/self-hosted-environments-identity.md)中的 `aud` 檢查，以及用於從 CI [分派測試工作階段](https://code.claude.com/docs/zh-TW/self-hosted-environments-testing.md#run-the-test-loop)。

75 75

76如果您遺失密鑰或需要輪換它，請從環境的**設定**標籤建立新密鑰，將新密鑰推出到您的執行器，然後撤銷舊密鑰。持有已撤銷密鑰的執行器在下一次驗證輪詢時失敗並退出，記錄 `poll auth failed`，您的編排器使用新密鑰重新啟動它們。76如果密鑰可能已外洩，請依照[部署頁面中針對疑似遭入侵情況的步驟](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#after-a-suspected-compromise)處理，而不是下方的輪換方式。

78如果您遺失密鑰或打算輪換它，請從環境的**設定**標籤建立新密鑰。將新密鑰推出到您的執行器，然後撤銷舊密鑰。持有已撤銷密鑰的執行器在下一次驗證輪詢時失敗並退出，記錄 `poll auth failed`，您的編排器會使用新密鑰重新啟動它們。

77 79

78**2. 啟動執行器**80**2. 啟動執行器**

79 81

self-hosted-environments-reference.md +1 −1

Details

141 141

142## 健康端點142## 健康端點

143 143

144執行器在配置的健康連接埠上提供 `GET /healthz`。只要程序活著，無論輪詢迴圈處於什麼狀態，回應都是 `200 OK`，因此此端點上的 HTTP 探測只檢測死程序。JSON 主體描述當前狀態：144執行器在完成註冊並完成啟動檢查後，會在設定的健康連接埠上提供 `GET /healthz`。從那時起，只要程序活著，無論輪詢迴圈處於什麼狀態，回應都是 `200 OK`，因此此端點上的 HTTP 探測只檢測死程序。JSON 主體描述當前狀態：

145 145

146```json theme={null}146```json theme={null}

147{147{

settings.md +1 −0

Details

311| [`permissions.blockReadsOutsideWorkingDirectories`](https://code.claude.com/docs/zh-TW/settings-reference#permissions-blockreadsoutsideworkingdirectories) | 來自任何範圍的 `true` | 即使受管來源設定為 `false` 也會採用。需要 Claude Code v2.1.257 或更新版本 |311| [`permissions.blockReadsOutsideWorkingDirectories`](https://code.claude.com/docs/zh-TW/settings-reference#permissions-blockreadsoutsideworkingdirectories) | 來自任何範圍的 `true` | 即使受管來源設定為 `false` 也會採用。需要 Claude Code v2.1.257 或更新版本 |

312| [`permissions.blockWritesOutsideWorkingDirectories`](https://code.claude.com/docs/zh-TW/settings-reference#permissions-blockwritesoutsideworkingdirectories) | 來自任何範圍的 `true` | 即使受管來源設定為 `false` 也會採用。需要 Claude Code v2.1.314 或更新版本 |312| [`permissions.blockWritesOutsideWorkingDirectories`](https://code.claude.com/docs/zh-TW/settings-reference#permissions-blockwritesoutsideworkingdirectories) | 來自任何範圍的 `true` | 即使受管來源設定為 `false` 也會採用。需要 Claude Code v2.1.314 或更新版本 |

313| [`permissions.denyInsteadOfPrompting`](https://code.claude.com/docs/zh-TW/settings-reference#permissions-denyinsteadofprompting) | 來自 `~/.claude/settings.json` 或 `--settings` 的 `true` | 即使受管來源設定為 `false` 也會採用。需要 Claude Code v2.1.319 或更新版本 |

313| [`autoMode.classifyAllShell`](https://code.claude.com/docs/zh-TW/settings-reference#automode-classifyallshell) | 來自 `~/.claude/settings.json` 或 `--settings` 的 `true` | 即使受管來源設定為 `false` 也會採用 |314| [`autoMode.classifyAllShell`](https://code.claude.com/docs/zh-TW/settings-reference#automode-classifyallshell) | 來自 `~/.claude/settings.json` 或 `--settings` 的 `true` | 即使受管來源設定為 `false` 也會採用 |

314| [`remoteControlAtStartup`](https://code.claude.com/docs/zh-TW/settings-reference#remotecontrolatstartup) | 來自 `.claude/settings.json` 或 `.claude/settings.local.json` 的 `false` | 即使受管來源設定為 `true` 也會採用；專案或本機的 `true` 會被忽略 |315| [`remoteControlAtStartup`](https://code.claude.com/docs/zh-TW/settings-reference#remotecontrolatstartup) | 來自 `.claude/settings.json` 或 `.claude/settings.local.json` 的 `false` | 即使受管來源設定為 `true` 也會採用；專案或本機的 `true` 會被忽略 |

315| [`crossSessionInbound`](https://code.claude.com/docs/zh-TW/settings-reference#crosssessioninbound) | 來自 `.claude/settings.json` 或 `.claude/settings.local.json` 的較嚴格值，依 `accept` \< `hold` \< `refuse` 的等級排序 | 優先於受管、`--settings` 和使用者的值；不較嚴格的專案或本機值會被忽略 |316| [`crossSessionInbound`](https://code.claude.com/docs/zh-TW/settings-reference#crosssessioninbound) | 來自 `.claude/settings.json` 或 `.claude/settings.local.json` 的較嚴格值，依 `accept` \< `hold` \< `refuse` 的等級排序 | 優先於受管、`--settings` 和使用者的值；不較嚴格的專案或本機值會被忽略 |

settings-reference.md +4 −4

Details

448 448

449在可使用[快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md)的工作階段中開啟快速模式，適用於快速迭代或即時除錯等互動式工作，讓您以較高的每 token 成本換取速度。通常不需要手動編輯此鍵。執行 `/fast` 會將 `fastMode: true` 寫入 `~/.claude/settings.json`，再次執行以關閉快速模式則會移除此鍵。449在可使用[快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md)的工作階段中開啟快速模式，適用於快速迭代或即時除錯等互動式工作，讓您以較高的每 token 成本換取速度。通常不需要手動編輯此鍵。執行 `/fast` 會將 `fastMode: true` 寫入 `~/.claude/settings.json`，再次執行以關閉快速模式則會移除此鍵。

450 450

451只有 Opus 5.5、Opus 5 和 Opus 4.8 支援快速模式。從其他模型執行 `/fast` 會將您切換至 Opus，而切換至不支援的模型則會關閉快速模式。請參閱[在快速模式開啟時切換模型](https://code.claude.com/docs/zh-TW/fast-mode.md#switch-models-while-fast-mode-is-on)。451只有 Fable 5.2、Opus 5.5、Opus 5 和 Opus 4.8 支援快速模式。從其他模型執行 `/fast` 會將您切換至 Opus，而切換至不支援的模型則會關閉快速模式。請參閱[在快速模式開啟時切換模型](https://code.claude.com/docs/zh-TW/fast-mode.md#switch-models-while-fast-mode-is-on)。

452 452

453* **範圍**：[`Any file`](#scopes)453* **範圍**：[`Any file`](#scopes)

454* **類型**：Boolean454* **類型**：Boolean

455 * `true`：Claude Code 在可使用快速模式的工作階段中開啟快速模式455 * `true`：Claude Code 在可使用快速模式的工作階段中開啟快速模式。在 Fable 5.2 上，您還必須[在使用 Fable 5.2 時執行 `/fast`](https://code.claude.com/docs/zh-TW/fast-mode#switch-models-while-fast-mode-is-on)

456 * `false`：快速模式保持關閉456 * `false`：快速模式保持關閉

457* **預設值**：未設定，因此快速模式為關閉狀態457* **預設值**：未設定，因此快速模式為關閉狀態

458* **每個工作階段的覆寫**：[`CLAUDE_CODE_DISABLE_FAST_MODE`](https://code.claude.com/docs/zh-TW/env-vars) 會在單一工作階段中關閉快速模式，且此鍵無法將其重新開啟458* **每個工作階段的覆寫**：[`CLAUDE_CODE_DISABLE_FAST_MODE`](https://code.claude.com/docs/zh-TW/env-vars) 會在單一工作階段中關閉快速模式，且此鍵無法將其重新開啟

465 465

466### `fastModePerSessionOptIn`466### `fastModePerSessionOptIn`

467 467

468通常，執行 `/fast` 會將 [`fastMode`](#fastmode) 儲存到使用者的使用者設定中，因此在支援的模型上，新的工作階段開始時快速模式都會開啟。將此鍵設為 `true` 即可停止此行為：已儲存的 `fastMode: true` 不再於工作階段開始時開啟快速模式，每位使用者都必須在需要的每個工作階段中執行 `/fast`。Claude Code 會保留其檔案中的 `fastMode` 鍵，因此關閉此鍵即可恢復舊有行為。468通常，執行 `/fast` 會將 [`fastMode`](#fastmode) 儲存到使用者的使用者設定中，因此在支援的模型上，新的工作階段開始時快速模式都會開啟。在 Fable 5.2 上，只有在使用者[於使用 Fable 5.2 時開啟快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md#switch-models-while-fast-mode-is-on)的情況下才會如此。若要讓每位使用者在需要的每個工作階段中自行執行 `/fast`，請將此鍵設為 `true`。Claude Code 會保留其檔案中的 `fastMode`，因此關閉此鍵即可恢復舊有行為。

469 469

470Team 或 Enterprise 方案的擁有者可以透過[伺服器受管設定](https://code.claude.com/docs/zh-TW/server-managed-settings.md)在整個組織中部署此鍵。當受管設定設定了此鍵時，`/fast on` 在互動式終端機工作階段以外會被拒絕，並回報您的組織已停用快速模式。這包括[非互動模式](https://code.claude.com/docs/zh-TW/headless.md)、[VS Code 擴充功能](https://code.claude.com/docs/zh-TW/vs-code.md)以及[雲端工作階段](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md)。470Team 或 Enterprise 方案的擁有者可以透過[伺服器受管設定](https://code.claude.com/docs/zh-TW/server-managed-settings.md)在整個組織中部署此鍵。當受管設定設定了此鍵時，`/fast on` 在互動式終端機工作階段以外會被拒絕，並回報您的組織已停用快速模式。這包括[非互動模式](https://code.claude.com/docs/zh-TW/headless.md)、[VS Code 擴充功能](https://code.claude.com/docs/zh-TW/vs-code.md)以及[雲端工作階段](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md)。

471 471

472* **範圍**：[`Any file`](#scopes)472* **範圍**：[`Any file`](#scopes)

473* **類型**：Boolean473* **類型**：Boolean

474 * `true`：已儲存的 `fastMode: true` 不再於工作階段開始時開啟快速模式，因此每位使用者需在需要的每個工作階段中執行 `/fast`；除非受管設定設定了此鍵，否則透過 `--settings` 傳入的 `fastMode: true` 仍會對該工作階段生效474 * `true`：已儲存的 `fastMode: true` 不再於工作階段開始時開啟快速模式，因此每位使用者需在需要的每個工作階段中執行 `/fast`；除非受管設定設定了此鍵，否則透過 `--settings` 傳入的 `fastMode: true` 仍會對該工作階段生效

475 * `false`：已儲存的 `fastMode: true` 會在支援的模型上，於每個新工作階段開始時開啟快速模式475 * `false`：已儲存的 `fastMode: true` 會依 [`fastMode`](#fastmode) 所述的方式運作

476* **預設值**：`false`476* **預設值**：`false`

477 477

478```json settings.json theme={null}478```json settings.json theme={null}

sub-agents.md +2 −0

Details

592主對話的權限模式決定 Claude Code 是否使用您設定的值：592主對話的權限模式決定 Claude Code 是否使用您設定的值：

593 593

594* 當主對話在 `bypassPermissions`、`acceptEdits` 或[自動模式](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode)中時，子代理在該相同模式中執行，Claude Code 忽略您設定的 `permissionMode`。在自動模式下，分類器使用主對話的阻止和允許規則評估子代理的工具呼叫。當子代理完成時，分類器也在報告被傳遞之前檢查其工作和最終報告，如[自動模式如何處理子代理](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode)所述。594* 當主對話在 `bypassPermissions`、`acceptEdits` 或[自動模式](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode)中時，子代理在該相同模式中執行，Claude Code 忽略您設定的 `permissionMode`。在自動模式下，分類器使用主對話的阻止和允許規則評估子代理的工具呼叫。當子代理完成時，分類器也在報告被傳遞之前檢查其工作和最終報告，如[自動模式如何處理子代理](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode)所述。

595

596 如果 subagent 在主對話處於 `bypassPermissions` 時要求權限，請檢查其工具呼叫是否屬於[任何模式都不會自動核准的動作](https://code.claude.com/docs/zh-TW/permission-modes.md#actions-no-mode-auto-approves)之一。

595* 當主對話處於 `plan` 模式時，無論您設定哪個 `permissionMode`，subagent 都會保持在 plan mode，除非它在 [agent teams 規則](https://code.claude.com/docs/zh-TW/agent-teams.md#have-teammates-plan-before-implementing)下作為 [agent team 隊員](#subagent-names)執行。如果您設定了 `dontAsk`，subagent 也不會提示您：plan mode 原本會要求您核准的動作會改為被拒絕。597* 當主對話處於 `plan` 模式時，無論您設定哪個 `permissionMode`，subagent 都會保持在 plan mode，除非它在 [agent teams 規則](https://code.claude.com/docs/zh-TW/agent-teams.md#have-teammates-plan-before-implementing)下作為 [agent team 隊員](#subagent-names)執行。如果您設定了 `dontAsk`，subagent 也不會提示您：plan mode 原本會要求您核准的動作會改為被拒絕。

596* 當主對話處於 `default` 或 `dontAsk` 模式時，subagent 會以您設定的權限模式執行。在以下情況下，它會改為保持主對話的權限模式：598* 當主對話處於 `default` 或 `dontAsk` 模式時，subagent 會以您設定的權限模式執行。在以下情況下，它會改為保持主對話的權限模式：

597 * 您設定了 `bypassPermissions`。`bypassPermissions` 例外需要 Claude Code v2.1.267 或更新版本。599 * 您設定了 `bypassPermissions`。`bypassPermissions` 例外需要 Claude Code v2.1.267 或更新版本。

tools-reference.md +22 −7

Details

26| `CronDelete` | 按 ID 取消工作階段範圍的排程任務 | 否 |26| `CronDelete` | 按 ID 取消工作階段範圍的排程任務 | 否 |

27| `CronList` | 列出所有工作階段範圍的排程任務 | 否 |27| `CronList` | 列出所有工作階段範圍的排程任務 | 否 |

28| `Edit` | 對特定檔案進行目標編輯。請參閱 [Edit 工具行為](#edit-tool-behavior) | 是 |28| `Edit` | 對特定檔案進行目標編輯。請參閱 [Edit 工具行為](#edit-tool-behavior) | 是 |

29| `EndConversation` | 結束工作階段，在持續濫用輸入的罕見情況下或當您要求 Claude 演示該工具時。請參閱 [EndConversation 工具行為](#endconversation-tool-behavior) | 否 |29| `EndConversation` | 結束工作階段，用於持續濫用輸入的罕見情況，或當您要求 Claude 結束工作階段並隨後確認時。請參閱 [EndConversation 工具行為](#endconversation-tool-behavior) | 否 |

30| `EnterPlanMode` | 切換到 plan mode 以在編碼前設計方法 | 否 |30| `EnterPlanMode` | 切換到 plan mode 以在編碼前設計方法 | 否 |

31| `EnterWorktree` | 建立隔離的 [git worktree](https://code.claude.com/docs/zh-TW/worktrees.md) 並切換到其中，或切換到現有的 worktree。請參閱 [EnterWorktree 工具行為](#enterworktree-tool-behavior) | 是 |31| `EnterWorktree` | 建立隔離的 [git worktree](https://code.claude.com/docs/zh-TW/worktrees.md) 並切換到其中，或切換到現有的 worktree。請參閱 [EnterWorktree 工具行為](#enterworktree-tool-behavior) | 是 |

32| `ExitPlanMode` | 呈現計畫以供核准並退出 plan mode | 是 |32| `ExitPlanMode` | 呈現計畫以供核准並退出 plan mode | 是 |

274 274

275EndConversation 工具會結束目前的工作階段。Claude 只在兩種情況下使用它：275EndConversation 工具會結束目前的工作階段。Claude 只在兩種情況下使用它：

276 276

277* 作為對持續濫用輸入的最後手段，在嘗試重新導向對話失敗且在較早的訊息中發出明確警告之後277* 當 Claude 發出明確警告且未能重新導向對話後，您仍持續傳送濫用訊息時

278* 當您明確要求查看工具演示並確認您想要結束工作階段時278* 當您明確要求 Claude 結束工作階段，並在 Claude 詢問您是否仍要繼續時予以確認

279 279

280一般的挫折感、粗言穢語或任務進行不順利都不符合條件，對有害內容的請求也不符合，Claude 會拒絕這些請求而不是結束工作階段。Claude Code 遵循與 claude.ai 相同的方法，後者可以[結束少數聊天](https://www.anthropic.com/research/end-subset-conversations)。280一般的挫折感、粗言穢語或任務進行不順利都不符合條件，對有害內容的請求也不符合，Claude 會拒絕這些請求而不是結束工作階段。Claude Code 遵循與 claude.ai 相同的方法，後者可以[結束少數聊天](https://www.anthropic.com/research/end-subset-conversations)。

281 281

390 390

391當 Monitor 執行命令時，它使用與 [Bash 相同的權限規則](https://code.claude.com/docs/zh-TW/permissions.md#tool-specific-permission-rules)，因此您為 Bash 設定的 `allow` 和 `deny` 模式也適用於此處。當 [自動模式](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode) 處於活動狀態時，Claude Code 會擱置命名 `Monitor` 本身的允許規則，以及它捨棄的其他 [廣泛允許規則](https://code.claude.com/docs/zh-TW/permission-modes.md#how-the-classifier-evaluates-actions)，因此分類器以與檢查 Bash 命令相同的方式檢查 Monitor 命令。391當 Monitor 執行命令時，它使用與 [Bash 相同的權限規則](https://code.claude.com/docs/zh-TW/permissions.md#tool-specific-permission-rules)，因此您為 Bash 設定的 `allow` 和 `deny` 模式也適用於此處。當 [自動模式](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode) 處於活動狀態時，Claude Code 會擱置命名 `Monitor` 本身的允許規則，以及它捨棄的其他 [廣泛允許規則](https://code.claude.com/docs/zh-TW/permission-modes.md#how-the-classifier-evaluates-actions)，因此分類器以與檢查 Bash 命令相同的方式檢查 Monitor 命令。

392 392

393[WebSocket 來源](#websocket-source) 有其自己的核准提示，分類器也會在自動模式中決定。

~~394~~

395在下列情況中，Monitor 需要最低版本或 Git Bash：393在下列情況中，Monitor 需要最低版本或 Git Bash：

396 394

397* **最低版本**：在 Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上，或設定了 `DISABLE_TELEMETRY` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 時，Monitor 需要 Claude Code v2.1.310 或更新版本。此要求適用於 [功能旗標擷取](https://code.claude.com/docs/zh-TW/env-vars.md#features-that-need-feature-flag-fetching) 關閉時395* **最低版本**：在 Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上，或設定了 `DISABLE_TELEMETRY` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 時，Monitor 需要 Claude Code v2.1.310 或更新版本。此要求適用於 [功能旗標擷取](https://code.claude.com/docs/zh-TW/env-vars.md#features-that-need-feature-flag-fetching) 關閉時

417 415

418`timeout_ms` 截止時間也適用於 WebSocket 監視：監視在截止時間結束，`TaskStop` 會提前取消它。416`timeout_ms` 截止時間也適用於 WebSocket 監視：監視在截止時間結束，`TaskStop` 會提前取消它。

419 417

420開啟 WebSocket 會提示核准；在 [自動模式](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode) 中，分類器會改為決定。提示不提供跳過相同主機的未來提示的選項。418若沒有 `Monitor` 允許規則，系統會在 Claude 開啟 WebSocket 之前提示您；在 [自動模式](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode) 中，則改由分類器決定，除非適用 [詢問規則](#bash-rules-that-deny-or-prompt-for-websocket-watches)。提示不提供跳過相同主機的未來提示的選項。

419

420#### WebSocket 監視所拒絕的位址與主機

421

422Claude Code 拒絕指向私人、連結本機或雲端中繼資料位址的 URL，包括您的電腦解析為此類位址的主機名稱。在 [代理伺服器](https://code.claude.com/docs/zh-TW/network-config.md#proxy-configuration) 後方時，除非代理伺服器加以封鎖，否則監視可以連線到私人、連結本機或雲端中繼資料位址，因為 Claude Code 不會檢查代理伺服器找到的位址。Claude Code 也拒絕 `sandbox.network.deniedDomains` 中的主機，以及當在受管設定中設定 [`allowManagedDomainsOnly`](https://code.claude.com/docs/zh-TW/settings-reference#sandbox-network-allowmanageddomainsonly) 時，任何在受管允許清單外的主機。

423

424如果代理伺服器後方的監視因 `could not resolve <host>` 而失敗，請將 [`CLAUDE_CODE_PROXY_RESOLVES_HOSTS`](https://code.claude.com/docs/zh-TW/env-vars#variables) 設為 `1`，並重新啟動 Claude Code v2.1.319 或更新版本，讓代理伺服器查詢主機名稱。

425

426#### 拒絕或提示 WebSocket 監視的 Bash 規則

427

428如果 Claude Code 拒絕開啟 WebSocket 的 `Monitor` 呼叫，請尋找寫成 `Bash` 或 `Bash(*)` 的 [拒絕或詢問規則](https://code.claude.com/docs/zh-TW/permissions.md#manage-permissions)。如果儘管您有 `Monitor` 允許規則，該呼叫仍然提示您，也請同樣檢查。針對每個 Bash 命令的規則也涵蓋這些 WebSocket 監視：

429

430* **拒絕規則**：如果工作階段開始時該規則已存在，Claude 將沒有 Monitor 工具，因此無法啟動監視。如果您在工作階段期間新增該規則，Claude 的下一個 `Monitor` 呼叫會被拒絕。拒絕訊息為 `Permission to use Monitor has been denied: it runs code as Bash does, and a rule denies Bash.`

431* **詢問規則**：系統會要求您核准監視。您無法讓允許規則、`PreToolUse` hook、`bypassPermissions` 模式或自動模式分類器代為核准。您可以透過 [`PermissionRequest` hook](https://code.claude.com/docs/zh-TW/hooks#permissionrequest) 核准。在無人可以回應的情況下，例如在 `dontAsk` 模式中，Claude Code 會拒絕該監視。

432

433若要讓這些監視執行，請將規則縮小到您真正指定的命令，例如 `Bash(rm *)`。

421 434

422Claude Code 拒絕指向私人、連結本機或雲端中繼資料位址的 URL，包括解析為該位址的主機名稱。它也拒絕 `sandbox.network.deniedDomains` 中的主機，以及當在受管設定中設定 [`allowManagedDomainsOnly`](https://code.claude.com/docs/zh-TW/settings-reference#sandbox-network-allowmanageddomainsonly) 時，任何在受管允許清單外的主機。435在 Claude Code v2.1.319 或更新版本中，詢問規則以及您在工作階段期間新增的拒絕規則會涵蓋這些監視。

423 436

424## NotebookEdit 工具行為437## NotebookEdit 工具行為

425 438

594* 非互動式 `-p` 執行和[代理 SDK](https://code.claude.com/docs/zh-TW/agent-sdk/overview.md) 工作階段，這些沒有螢幕來查看佇列607* 非互動式 `-p` 執行和[代理 SDK](https://code.claude.com/docs/zh-TW/agent-sdk/overview.md) 工作階段，這些沒有螢幕來查看佇列

595* [雲端工作階段](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md)，無法寫入您機器上的佇列608* [雲端工作階段](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md)，無法寫入您機器上的佇列

596* [Amazon Bedrock](https://code.claude.com/docs/zh-TW/amazon-bedrock.md)、[Claude Platform on AWS](https://code.claude.com/docs/zh-TW/claude-platform-on-aws.md)、[Google Cloud's Agent Platform](https://code.claude.com/docs/zh-TW/google-vertex-ai.md) 或 [Microsoft Foundry](https://code.claude.com/docs/zh-TW/microsoft-foundry.md) 上的工作階段609* [Amazon Bedrock](https://code.claude.com/docs/zh-TW/amazon-bedrock.md)、[Claude Platform on AWS](https://code.claude.com/docs/zh-TW/claude-platform-on-aws.md)、[Google Cloud's Agent Platform](https://code.claude.com/docs/zh-TW/google-vertex-ai.md) 或 [Microsoft Foundry](https://code.claude.com/docs/zh-TW/microsoft-foundry.md) 上的工作階段

610* 透過 [LLM 閘道](https://code.claude.com/docs/zh-TW/llm-gateway)並使用閘道自身的金鑰或 token 連接 Claude 的工作階段

597* 您設定 [`CLAUDE_CODE_SEND_FEEDBACK=0`](https://code.claude.com/docs/zh-TW/env-vars) 或 [`DISABLE_FEEDBACK_COMMAND=1`](https://code.claude.com/docs/zh-TW/env-vars) 的工作階段，將 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 設定為任何非空值，或關閉[功能旗標擷取](https://code.claude.com/docs/zh-TW/env-vars.md#features-that-need-feature-flag-fetching)611* 您設定 [`CLAUDE_CODE_SEND_FEEDBACK=0`](https://code.claude.com/docs/zh-TW/env-vars) 或 [`DISABLE_FEEDBACK_COMMAND=1`](https://code.claude.com/docs/zh-TW/env-vars) 的工作階段，將 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 設定為任何非空值，或關閉[功能旗標擷取](https://code.claude.com/docs/zh-TW/env-vars.md#features-that-need-feature-flag-fetching)

598* 已關閉產品回饋的組織、[零資料保留的組織](https://code.claude.com/docs/zh-TW/zero-data-retention.md#features-disabled-under-zdr)，以及已套用 [HIPAA 設定](https://code.claude.com/docs/zh-TW/hipaa-setup.md)的組織612* 已關閉產品回饋的組織、[零資料保留的組織](https://code.claude.com/docs/zh-TW/zero-data-retention.md#features-disabled-under-zdr)，以及已套用 [HIPAA 設定](https://code.claude.com/docs/zh-TW/hipaa-setup.md)的組織

613* Claude Code 已[在報告遭拒後停止提供回饋](https://code.claude.com/docs/zh-TW/errors.md#feedback-is-disabled-by-your-organizations-policy)的工作階段

599 614

600## Task 工具可用性615## Task 工具可用性

601 616

zero-data-retention.md +2 −2

Details

70 70

71### ZDR 下的模型可用性71### ZDR 下的模型可用性

72 72

73Claude Fable 5.1 和 Fable 5 是[涵蓋的模型](https://support.claude.com/en/articles/15425695-covered-models)，[預設需要資料保留](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements)，ZDR 組織或工作區是否可以使用它們由涵蓋的模型政策而非 Claude Code 管理。如果您的組織無法使用它們，這些模型要麼在 `/model` 選擇器中不存在，要麼顯示為停用，伺服器會拒絕針對它們的請求，無論用戶端設定如何。73Claude Fable 5.2、Fable 5.1 和 Fable 5 是[涵蓋的模型](https://support.claude.com/en/articles/15425695-covered-models)，[預設需要資料保留](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements)，ZDR 組織或工作區是否可以使用它們由涵蓋的模型政策而非 Claude Code 管理。如果您的組織無法使用它們，這些模型要麼在 `/model` 選擇器中不存在，要麼顯示為停用，伺服器會拒絕針對它們的請求，無論用戶端設定如何。

74 74

~~75其他模型在 ZDR 下仍然可用。Fable 模型不是預設值，`best` 別名（在可用的地方解析為最新的 Fable 模型）在無法使用的組織中解析為 Opus。~~75其他模型在 ZDR 下仍然可用。Fable 模型不是預設值，`best` 別名會解析為 Opus。

76 76

77## 政策違規的資料保留77## 政策違規的資料保留

78 78

Documentation 2026-11-08 22:58 UTC to 2026-11-09 23:02 UTC