Documentation — Spybara

agent-sdk/hooks.md +3 −1

Details

771 771

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

773 773

774* `PreToolUse`：Claude Code 阻止工具呼叫。取而代之的是，Claude 收到工具結果，說明 hook 未在逾時前回應，回合繼續。在 v2.1.210 之前，Claude Code 將逾時報告給 Claude 作為使用者拒絕，這使無人值守工作階段停止並等待輸入。774* `PreToolUse`：Claude Code 阻止工具呼叫。如果其他所有 hook 都未返回任何內容或僅返回 `allow` 決定，工具結果會告知 Claude 該 hook 未在逾時前回應，回合繼續。如果您的另一個 hook 已拒絕該呼叫，其拒絕仍會傳達給 Claude：工具結果包含該 hook 的理由，逾時文字可能接在其後。

775

776 在 v2.1.210 之前，Claude Code 將逾時報告給 Claude 作為使用者拒絕，這使無人值守工作階段停止並等待輸入。

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

776* `UserPromptSubmit` 和 [`UserPromptExpansion`](https://code.claude.com/docs/zh-TW/hooks#userpromptexpansion)：Claude Code 以指出 hook 名稱和逾時的訊息阻止提示詞，工作階段繼續。在 v2.1.208 之前，當這些事件上的回調逾時時，Claude Code 以 `error_during_execution` 結束查詢。778* `UserPromptSubmit` 和 [`UserPromptExpansion`](https://code.claude.com/docs/zh-TW/hooks#userpromptexpansion)：Claude Code 以指出 hook 名稱和逾時的訊息阻止提示詞，工作階段繼續。在 v2.1.208 之前，當這些事件上的回調逾時時，Claude Code 以 `error_during_execution` 結束查詢。

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

agent-sdk/permissions.md +1 −1

Details

57 57

58如果您在 TypeScript SDK 期望評估順序在諮詢回呼之前自動批准呼叫的設定中傳遞 `canUseTool` 回呼，SDK 會在構造查詢時發出一次 Node.js 程序警告。警告的代碼是 `CLAUDE_SDK_CAN_USE_TOOL_SHADOWED`。兩個設定會觸發它：58如果您在 TypeScript SDK 期望評估順序在諮詢回呼之前自動批准呼叫的設定中傳遞 `canUseTool` 回呼，SDK 會在構造查詢時發出一次 Node.js 程序警告。警告的代碼是 `CLAUDE_SDK_CAN_USE_TOOL_SHADOWED`。兩個設定會觸發它：

59 59

60* `permissionMode: 'bypassPermissions'`，它自動批准到達權限模式步驟的每個呼叫，除了 [任何模式都不自動批准的操作](https://code.claude.com/docs/zh-TW/permission-modes.md#actions-no-mode-auto-approves)60* `permissionMode: 'bypassPermissions'`，它自動核准到達權限模式步驟的每個呼叫，除了 [任何模式都不自動核准的操作](https://code.claude.com/docs/zh-TW/permission-modes.md#actions-no-mode-auto-approves)

61* 每個裸 `allowedTools` 條目，例如 `"Read"`，它在諮詢回呼之前自動核准整個工具，除了 [任何模式都不自動核准的操作](https://code.claude.com/docs/zh-TW/permission-modes.md#actions-no-mode-auto-approves) 和 [從網路路徑進行的讀取](https://code.claude.com/docs/zh-TW/permissions.md#network-paths)61* 每個裸 `allowedTools` 條目，例如 `"Read"`，它在諮詢回呼之前自動核准整個工具，除了 [任何模式都不自動核准的操作](https://code.claude.com/docs/zh-TW/permission-modes.md#actions-no-mode-auto-approves) 和 [從網路路徑進行的讀取](https://code.claude.com/docs/zh-TW/permissions.md#network-paths)

62 62

63具有指定符的條目（如 `Bash(ls *)`）和 `acceptEdits` 模式不會觸發它，來自設定檔的 allow 規則對檢查不可見。63具有指定符的條目（如 `Bash(ls *)`）和 `acceptEdits` 模式不會觸發它，來自設定檔的 allow 規則對檢查不可見。

agent-sdk/typescript.md +64 −2

Details

312 313

313#### 傳回型別：`SessionMessage`314#### 傳回型別：`SessionMessage`

314 315

315| 屬性 | 型別 | 說明 |316| 屬性 | 型別 | 說明 |

316| :- | :- | :- |317| :- | :- | :- |

632 }): Promise<SDKControlReloadPluginsResponse>;633 }): Promise<SDKControlReloadPluginsResponse>;

633 reloadSkills(): Promise<SDKControlReloadSkillsResponse>;634 reloadSkills(): Promise<SDKControlReloadSkillsResponse>;

634 reloadOutputStyles(): Promise<SDKControlReloadOutputStylesResponse>;635 reloadOutputStyles(): Promise<SDKControlReloadOutputStylesResponse>;

636 seedReadState(path: string, mtime: number): Promise<void>;

635 accountInfo(): Promise<AccountInfo>;637 accountInfo(): Promise<AccountInfo>;

636 reconnectMcpServer(serverName: string): Promise<void>;638 reconnectMcpServer(serverName: string): Promise<void>;

637 toggleMcpServer(serverName: string, enabled: boolean): Promise<void>;639 toggleMcpServer(serverName: string, enabled: boolean): Promise<void>;

638 setMcpServers(servers: Record<string, McpServerConfig>): Promise<McpSetServersResult>;640 setMcpServers(servers: Record<string, McpServerConfig>): Promise<McpSetServersResult>;

641 setMcpPermissionModeOverride(

642 serverName: string,

643 mode: 'default' | 'auto' | null

644 ): Promise<{ warning?: string }>;

639 readMcpResource(serverName: string, uri: string): Promise<SDKControlMcpReadResourceResponse>;645 readMcpResource(serverName: string, uri: string): Promise<SDKControlMcpReadResourceResponse>;

640 streamInput(stream: AsyncIterable<SDKUserMessage>): Promise<void>;646 streamInput(stream: AsyncIterable<SDKUserMessage>): Promise<void>;

641 stopTask(taskId: string): Promise<void>;647 stopTask(taskId: string): Promise<void>;

648 backgroundTasks(toolUseId?: string): Promise<boolean>;

642 close(): void;649 close(): void;

643}650}

644```651```

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

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

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

675| `seedReadState(path, mtime)` | 將檔案標記為已讀取，讓之後的 Edit 不會因 `File has not been read yet` 而失敗。請參閱 [`seedReadState()`](#seedreadstate)。需要 TypeScript SDK v0.2.83 或更新版本 |

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

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

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

680| `setMcpPermissionModeOverride(serverName, mode)` | 以比工作階段更嚴格的模式覆寫單一 MCP 伺服器工具的權限模式，或以 `null` 清除覆寫。僅在串流輸入模式中可用。請參閱 [`setMcpPermissionModeOverride()`](#setmcppermissionmodeoverride)。需要 TypeScript SDK v0.3.187 或更新版本 |

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

684| `backgroundTasks(toolUseId?)` | 將該回合正在等待的執行中 Bash 命令和 subagent 移至背景，與在互動式終端機中按下 Ctrl+B 相同。請參閱 [`backgroundTasks()`](#backgroundtasks)。需要 TypeScript SDK v0.2.139 或更新版本 |

676 686

687#### `setMcpPermissionModeOverride()`

688

689以比工作階段更嚴格的模式覆寫單一 MCP 伺服器工具的權限模式，或以 `null` 清除覆寫。當工作階段以略過逐項動作提示的模式執行，但某個伺服器的工具仍應受到審查時，請使用此方法。需要 TypeScript SDK v0.3.187 或更新版本。

690

691傳遞下列三個值之一作為 `mode`：

692

693* `'default'`：Claude Code 會以[手動模式](https://code.claude.com/docs/zh-TW/permission-modes.md#available-modes)的方式評估該伺服器的工具呼叫。

694* `'auto'`：Claude Code 會將該伺服器的工具呼叫交由[自動模式](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode)分類器處理。當工作階段無法使用分類器時，Claude Code 會拒絕此值。

695* `null`：清除覆寫。

696

697覆寫僅在工作階段處於略過逐項動作提示的模式時生效：`bypassPermissions` 或 `auto`。在任何其他工作階段模式中，Claude Code 會忽略覆寫，因此它永遠不會放寬工作階段允許的範圍。

698

699當尚無該名稱的已知伺服器時，promise 會以 `{ warning }` 解析。Claude Code 仍會儲存覆寫，並在具有完全相同名稱的伺服器連線後套用，因此此警告是用於檢查拼字錯誤，而不是失敗。

700

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

702

703#### `seedReadState()`

704

705將檔案標記為已讀取，讓之後的 Edit 不會因 `File has not been read yet` 而失敗。當您的應用程式已從對話上下文中捨棄先前的 `Read` 結果，而 Claude 接下來要編輯該檔案時，請使用此方法。需要 TypeScript SDK v0.2.83 或更新版本。

706

707將 `mtime` 傳遞為先前讀取當下該檔案的修改時間，以自 epoch 起算的整數毫秒表示，例如 `Math.floor(stat.mtimeMs)`。如果磁碟上的檔案在該時間之後有所變更，Claude Code 會略過標記。

708

709無論檔案是否被標記，promise 都會解析，因此解析的 promise 無法告訴您實際發生了哪一種情況。

710

711#### `backgroundTasks()`

712

713將該回合正在等待的執行中 Bash 命令和 subagent 移至背景，與在互動式終端機中按下 Ctrl+B 相同。傳遞某個工具呼叫的 `toolUseId`，可只將該呼叫啟動的 Bash 命令或 subagent 移至背景；省略則會將所有前景任務移至背景。需要 TypeScript SDK v0.2.139 或更新版本。

714

715每個移至背景的工具呼叫都會立即以「正在背景執行」的結果傳回給 Claude，回合會繼續進行，而 Claude Code 會在任務完成時發出 [`SDKTaskNotificationMessage`](#sdktasknotificationmessage)。

716

717在已啟用背景任務的工作階段中，promise 會解析為布林值：

718

719* **`true`**：有任務被移至背景，或您省略了 `toolUseId`。

720* **`false`**：您傳遞的 `toolUseId` 沒有符合任何前景任務。

721

722如果工作階段已停用背景任務，例如透過 [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](https://code.claude.com/docs/zh-TW/env-vars)，promise 會改為拒絕，且不會有任何任務被移至背景。

723

677#### `applyFlagSettings()`724#### `applyFlagSettings()`

678 725

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

1472 | SDKPermissionDeniedMessage1519 | SDKPermissionDeniedMessage

1473 | SDKPromptSuggestionMessage1520 | SDKPromptSuggestionMessage

1474 | SDKAPIRetryMessage1521 | SDKAPIRetryMessage

1522 | SDKControlRequestProgressMessage

1523 | SDKModelRefusalFallbackMessage

1524 | SDKModelRefusalNoFallbackMessage

1475 | SDKMirrorErrorMessage1525 | SDKMirrorErrorMessage

1476 | SDKInformationalMessage1526 | SDKInformationalMessage

1477 | SDKConversationResetMessage;1527 | SDKConversationResetMessage;

1478```1528```

1479 1529

1530此聯集中有三種訊息用於回報控制請求進度與模型拒絕。每一種都具有 `type: "system"`，因此請依各項所列的 `subtype` 加以區分：

1531

1532* `SDKControlRequestProgressMessage`，`subtype: "control_request_progress"`：回報您的用戶端所送出之長時間執行控制請求的進度。`request_id` 將訊息對應至該請求，`status` 為 `"started"` 或 `"api_retry"`。需要 Agent SDK v0.3.203 或更新版本。

1533* `SDKModelRefusalFallbackMessage`，`subtype: "model_refusal_fallback"`：當模型以拒絕結束串流，且該回合改在備援模型上重試時發出。帶有 `original_model` 與 `fallback_model`。需要 Agent SDK v0.3.170 或更新版本。

1534* `SDKModelRefusalNoFallbackMessage`，`subtype: "model_refusal_no_fallback"`：當模型以拒絕結束串流且未執行任何重試時發出，例如因為未設定備援模型。帶有 `original_model`。需要 Agent SDK v0.3.193 或更新版本。

1535

1480### `SDKAssistantMessage`1536### `SDKAssistantMessage`

1481 1537

1482助手回應訊息。1538助手回應訊息。

1636 stop_reason: string | null;1692 stop_reason: string | null;

1637 ttft_ms?: number;1693 ttft_ms?: number;

1638 ttft_stream_ms?: number;1694 ttft_stream_ms?: number;

1695 time_to_request_ms?: number;

1639 user_message_uuid?: string;1696 user_message_uuid?: string;

1640 user_message_uuids?: string[];1697 user_message_uuids?: string[];

1641 resume_reason?: string;1698 resume_reason?: string;

1701* `api_error_status`：終止對話的 API 錯誤的 HTTP 狀態碼。當回合在沒有 API 錯誤的情況下結束時，不存在或為 `null`。1758* `api_error_status`：終止對話的 API 錯誤的 HTTP 狀態碼。當回合在沒有 API 錯誤的情況下結束時，不存在或為 `null`。

1702* `ttft_ms`：首個 token 的時間（毫秒），在第一個完整助手訊息到達時測量。僅在成功分支上存在。1759* `ttft_ms`：首個 token 的時間（毫秒），在第一個完整助手訊息到達時測量。僅在成功分支上存在。

1703* `ttft_stream_ms`：直到第一個 `message_start` 串流事件（即回應串流開啟時）的時間（毫秒）。低於 `ttft_ms`；兩者之間的差距是串流第一個訊息所花費的時間。僅在成功分支上存在。1760* `ttft_stream_ms`：直到第一個 `message_start` 串流事件（即回應串流開啟時）的時間（毫秒）。低於 `ttft_ms`；兩者之間的差距是串流第一個訊息所花費的時間。僅在成功分支上存在。

1761* `time_to_request_ms`：從回合開始到 Claude Code 傳送 API 請求的時間，以毫秒計。僅出現在成功分支上。需要 Claude Code v2.1.162 或更新版本。

1704* `user_message_uuid`：此回合所回答的、您傳送之訊息的 `uuid`。請參閱 [`user_message_uuid`](#user_message_uuid) 以了解哪些結果會攜帶它。1762* `user_message_uuid`：此回合所回答的、您傳送之訊息的 `uuid`。請參閱 [`user_message_uuid`](#user_message_uuid) 以了解哪些結果會攜帶它。

1705* `user_message_uuids`：Claude Code 在此回合中回答的、您傳送之每則訊息的 `uuid`。請參閱 [`user_message_uuids`](#user_message_uuids)。1763* `user_message_uuids`：Claude Code 在此回合中回答的、您傳送之每則訊息的 `uuid`。請參閱 [`user_message_uuids`](#user_message_uuids)。

1706* `resume_reason`：此回合為何接續因重新啟動而中斷的回合。出現在兩個分支上。請參閱 [`resume_reason`](#resume_reason)。1764* `resume_reason`：此回合為何接續因重新啟動而中斷的回合。出現在兩個分支上。請參閱 [`resume_reason`](#resume_reason)。

1772* 不回答您任何訊息的回合，或回答您傳送之不帶 `uuid` 訊息的回合1830* 不回答您任何訊息的回合，或回答您傳送之不帶 `uuid` 訊息的回合

1773* 不回答您所傳送任何訊息的結果，例如工作程序當機後歸零的結果1831* 不回答您所傳送任何訊息的結果，例如工作程序當機後歸零的結果

1774 1832

1833當 [`UserPromptSubmit`](https://code.claude.com/docs/zh-TW/hooks#userpromptsubmit) hook 封鎖一則開始其自身回合的訊息，或以 `continue: false` 停止它時，您仍會收到該訊息的結果。這是一個 `is_error: false` 且 `num_turns: 0` 的成功結果，其 `result` 為[封鎖訊息](https://code.claude.com/docs/zh-TW/hooks.md#what-a-blocked-prompt-leaves-behind)或[停止訊息](https://code.claude.com/docs/zh-TW/hooks.md#json-output)，並依照與任何其他結果相同的規則回傳該訊息的 `uuid`。該結果沒有 `terminal_reason`，且除了 `result` 文字外，結果上沒有任何內容表明是 hook 結束了該回合。在另一個回合執行期間被 hook 封鎖的訊息可能不會有結果：請參閱 [`user_message_uuids`](#user_message_uuids)。

1834

1775#### `user_message_uuids`1835#### `user_message_uuids`

1776 1836

1777Claude Code 在此回合中回答的、您所傳送之每則訊息的 `uuid`。當您在短時間內傳送多則訊息時，Claude Code 可以將它們合併為一個回合，此時 `user_message_uuid` 只會指名其中的最後一則。若要將回覆與任何一則被合併的訊息對應，請在此清單中任何位置尋找該訊息的 `uuid`。需要 Agent SDK v0.3.259 或更新版本。1837Claude Code 在此回合中回答的、您所傳送之每則訊息的 `uuid`。當您在短時間內傳送多則訊息時，Claude Code 可以將它們合併為一個回合，此時 `user_message_uuid` 只會指名其中的最後一則。若要將回覆與任何一則被合併的訊息對應，請在此清單中任何位置尋找該訊息的 `uuid`。需要 Agent SDK v0.3.259 或更新版本。

1778 1838

1779Claude Code 會在每個攜帶 `user_message_uuid` 的回覆框架以及結果上，將此清單與該欄位一併設定。關於回傳所回答訊息之 `uuid` 的完整回合框架集合，以及各自所需的版本，請參閱 [`user_message_uuid`](#user_message_uuid)。清單一定包含 `user_message_uuid`，且最多保留 64 個項目。1839Claude Code 會在每個攜帶 `user_message_uuid` 的回覆框架以及結果上，將此清單與該欄位一併設定。關於回傳所回答訊息之 `uuid` 的完整回合框架集合，以及各自所需的版本，請參閱 [`user_message_uuid`](#user_message_uuid)。清單一定包含 `user_message_uuid`，且最多保留 64 個項目。

1780 1840

1781當 Claude Code 在回合執行期間接收到您傳送的一般訊息時，會將該訊息的 `uuid` 新增到結果的清單中。1841當 Claude Code 接收您在回合執行期間送出的一般訊息時，會將該訊息的 `uuid` 加入結果的清單中。當 [`UserPromptSubmit`](https://code.claude.com/docs/zh-TW/hooks#userpromptsubmit) hook 在接收時封鎖該訊息，Claude Code 會改為捨棄它：該訊息永遠不會送達 Claude，也不會保留到之後的回合。您不會收到它的結果，其 `uuid` 也不會出現在任何結果的清單中。如果 hook 可能封鎖訊息，請為等待列出您在回合執行期間所送出訊息的結果設定逾時。

1842

1843上述情況適用於 hook 的輸出僅為封鎖時。如果輸出設定了 `continue: false`（即使與 `decision: "block"` 並存），或該 hook 是以 [`ok: false`](https://code.claude.com/docs/zh-TW/hooks#response-schema) 回答且未帶 `continueOnBlock: true` 的提示詞 hook，Claude Code 會停止該訊息而非捨棄它。該訊息會等待其自身的回合，您會收到它的結果，且其文字會保留在對話中，因此 Claude 會在下一個回合看到它。

1782 1844

1783當第一個回覆或結果攜帶 `user_message_uuid` 但沒有清單時，表示它來自較早的 Claude Code 版本，因此請改用該單一欄位。1845當第一個回覆或結果攜帶 `user_message_uuid` 但沒有清單時，表示它來自較早的 Claude Code 版本，因此請改用該單一欄位。

1784 1846

agent-sdk/user-input.md +1 −1

Details

53>53>

54> **回呼永遠不會針對自動批准的工具觸發。** [權限評估流程](https://code.claude.com/docs/zh-TW/agent-sdk/permissions.md#how-permissions-are-evaluated)中任何較早的批准、允許規則或 `acceptEdits` 或 `bypassPermissions` 等模式，都會在諮詢 `canUseTool` 之前解決呼叫。如果您在 `allowed_tools` 中列出工具，`canUseTool` 檢查該工具只會在[評估流程](https://code.claude.com/docs/zh-TW/agent-sdk/permissions.md#how-permissions-are-evaluated)將呼叫路由回提示時執行，例如詢問規則或 `plan` 模式。對於必須應用於每個工具呼叫的邏輯，請使用 [`PreToolUse` hook](https://code.claude.com/docs/zh-TW/agent-sdk/hooks)，它在流程的其餘部分之前執行，可以允許、拒絕或修改請求。54> **回呼永遠不會針對自動批准的工具觸發。** [權限評估流程](https://code.claude.com/docs/zh-TW/agent-sdk/permissions.md#how-permissions-are-evaluated)中任何較早的批准、允許規則或 `acceptEdits` 或 `bypassPermissions` 等模式，都會在諮詢 `canUseTool` 之前解決呼叫。如果您在 `allowed_tools` 中列出工具，`canUseTool` 檢查該工具只會在[評估流程](https://code.claude.com/docs/zh-TW/agent-sdk/permissions.md#how-permissions-are-evaluated)將呼叫路由回提示時執行，例如詢問規則或 `plan` 模式。對於必須應用於每個工具呼叫的邏輯，請使用 [`PreToolUse` hook](https://code.claude.com/docs/zh-TW/agent-sdk/hooks)，它在流程的其餘部分之前執行，可以允許、拒絕或修改請求。

55>55>

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

57 57

58您也可以使用 [`PermissionRequest` hook](https://code.claude.com/docs/zh-TW/agent-sdk/hooks#available-hooks) 在 Claude 等待批准時發送外部通知（Slack、電子郵件、推送）。58您也可以使用 [`PermissionRequest` hook](https://code.claude.com/docs/zh-TW/agent-sdk/hooks#available-hooks) 在 Claude 等待批准時發送外部通知（Slack、電子郵件、推送）。

59 59

channels-reference.md +6 −5

Details

519import { z } from 'zod'519import { z } from 'zod'

520 520

521// setNotificationHandler 透過方法欄位上的 z.literal 進行路由，521// setNotificationHandler 透過方法欄位上的 z.literal 進行路由，

522// 所以此架構既是驗證器又是分派金鑰522// 所以此 schema 既是驗證器又是分派鍵

523const PermissionRequestSchema = z.object({523const PermissionRequestSchema = z.object({

524 method: z.literal('notifications/claude/channel/permission_request'),524 method: z.literal('notifications/claude/channel/permission_request'),

525 params: z.object({525 params: z.object({

526 request_id: z.string(), // 五個小寫字母，在您的提示中逐字包含526 request_id: z.string(), // 五個小寫字母，在您的提示中逐字包含

527 tool_name: z.string(), // 例如 "Bash"、"Write"527 tool_name: z.string(), // 例如 "Bash"、"Write"

528 description: z.string(), // 此呼叫的摘要。視為不受信任。528 description: z.string(), // 此呼叫的摘要。視為不受信任。

529 input_preview: z.string(), // 工具引數作為 JSON 字串文字。視為不受信任。529 input_preview: z.string(), // 工具引數作為 JSON 形狀的文字。視為不受信任。

530 }),530 }),

531})531})

532 532

581}581}

582```582```

583 583

584不完全符合預期格式的遠端回覆以兩種方式之一失敗，在兩種情況下本機終端機對話框都保持開啟：584如果遠端回覆沒有作用且本機終端機對話框保持開啟，請檢查以下原因：

585 585

586* **不同格式**：您的入站處理程式的正規表達式無法符合，因此 `approve it` 或 `yes` 之類的文字（沒有 ID）會作為正常訊息落入 Claude。586* **格式錯誤**：您的入站處理程式的正規表達式無法符合，因此 `approve it` 或 `yes` 之類的文字（沒有 ID）會作為正常訊息落入 Claude。

587* **正確格式，錯誤 ID**：您的伺服器發出判決，但 Claude Code 找不到具有該 ID 的開啟要求並無聲地捨棄它。587* **ID 錯誤**：您的伺服器發出判決，但 Claude Code 找不到具有該 ID 的開啟請求並無聲地捨棄它。

588* **ID 已被先前的提示使用**：您的伺服器使用請求中的 ID 發出判決，但工作階段中先前的提示具有相同的 ID。一旦 ID 重複，Claude Code 會捨棄任何帶有該 ID 的頻道判決，使針對某個提示的回覆無法核准另一個提示。ID 是五個隨機字母，因此重複的情況很少見。請改為在終端機上回答。

588 589

589### 完整範例590### 完整範例

590 591

checkpointing.md +2 −2

Details

90 90

91### 訊息在回合中途傳送未進行檢查點91### 訊息在回合中途傳送未進行檢查點

92 92

93在回溯功能表中，您[在 Claude 仍在工作時輸入的訊息](https://code.claude.com/docs/zh-TW/interactive-mode.md#queue-messages-while-claude-works)可能會被標記為**不復原程式碼**。Claude 在其回合結束前讀取了該訊息。[檢查點是為開始回合的提示詞建立的](#how-checkpoints-work)，因此此訊息沒有自己的檢查點。Claude 讀取該訊息後所做的編輯會計入開始該回合的提示詞。93在回溯功能表中，您[在 Claude 仍在工作時輸入的訊息](https://code.claude.com/docs/zh-TW/interactive-mode.md#queue-messages-while-claude-works)可能會被標記為**不復原程式碼**。被標記的訊息沒有自己的[檢查點](#how-checkpoints-work)。

94 94

95您不需要對訊息本身做任何處理。若要撤銷工作階段中該部分的檔案變更，請選擇開始該回合的提示詞，然後選擇**復原程式碼**或**復原程式碼和對話**。這會還原 Claude 在整個回合中的檔案編輯，包括您的訊息到達之前所做的編輯。選擇被標記的訊息仍會提供**復原對話**，這會將對話回溯到該訊息，並保持您的檔案原樣。95若要撤銷 Claude 在該訊息之後所做的檔案編輯，請選擇開始該回合的提示詞，然後選擇**復原程式碼**或**復原程式碼和對話**。這會還原 Claude 在整個回合中的檔案編輯，包括您的訊息到達之前所做的編輯。

96 96

97### 符號連結和硬連結路徑未復原97### 符號連結和硬連結路徑未復原

98 98

claude-apps-gateway-spend-limits.md +1 −1

Details

98 98

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

100 100

101開發人員看到的支出是閘道自己的[估計值](#how-requests-are-priced)，與其用來執行上限的數字相同，而不是您提供商帳單上的金額。Claude Code 會透過對閘道的另一個請求讀取美元金額。如果您依照[合規態勢](https://code.claude.com/docs/zh-TW/claude-apps-gateway-deploy.md#compliance-posture)的建議，在開發人員的機器上設定 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`，Claude Code 會略過該請求。設定了該變數，或閘道伺服器早於 v2.1.284 時，該列和狀態列只會顯示百分比。101開發人員看到的支出是閘道自己的[估計值](#how-requests-are-priced)，與其用來執行上限的數字相同，而不是您提供商帳單上的金額。Claude Code 會透過對閘道的另一個請求讀取美元金額；即使您在開發人員的機器上設定了 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`，Claude Code 仍會傳送該請求。在 v2.1.295 之前，設定該變數時 Claude Code 會略過該請求，`/usage` 和狀態列只會顯示百分比和重設日期，不含美元金額。

102 102

103## 管理員 API 參考103## 管理員 API 參考

104 104

claude-code-on-the-web.md +29 −9

Details

18 18

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

20* **行動裝置**：[Claude 應用程式](https://code.claude.com/docs/zh-TW/mobile.md)中的 **Code** 標籤20* **行動裝置**：[Claude 應用程式](https://code.claude.com/docs/zh-TW/mobile.md)中的 **Code** 標籤

~~21* **桌面應用程式**：當您[啟動工作階段](https://code.claude.com/docs/zh-TW/desktop.md#run-long-running-tasks-in-the-cloud)時，選擇 **Cloud** 而不是 **Local**~~21* **桌面應用程式**：當您[啟動工作階段](https://code.claude.com/docs/zh-TW/desktop.md#run-long-running-tasks-in-the-cloud)時，在環境選擇器的 **Cloud** 下選擇一個環境

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

23* **雲端排程任務**：[排程和觸發的執行](https://code.claude.com/docs/zh-TW/routines.md)每次都作為雲端工作階段執行23* **雲端排程任務**：[排程和觸發的執行](https://code.claude.com/docs/zh-TW/routines.md)每次都作為雲端工作階段執行

24 24

247 247

248### 檢查變更248### 檢查變更

249 249

250每個工作階段顯示一個差異指示器，其中包含新增和移除的行數，例如 `+42 -18`。選擇它以開啟差異檢視、在特定行上留下內聯評論，並使用您的下一條訊息將它們發送給 Claude。250Claude 將其變更推送到分支後，聊天旁面板中的**變更**卡片會顯示新增和移除的行數，例如 `+42 -18`。點擊**變更**卡片上的行數以開啟差異檢視。

251 251

252差異檢視預設會將工作階段的變更與其基礎分支進行比較。若要與儲存庫中的任何其他分支進行比較，請選擇**比較對象**並選擇一個。252* 您也可以點擊工作階段標題列中的**變更**，或標題列 **⋮** 功能表中的**變更**。

253* 若要在面板隱藏時顯示它，請點擊工作階段標題列中的**顯示工作階段側欄**圖示，或使用標題列的 **⋮** 功能表。

254

255在差異檢視中，您可以對特定行留言，並與其他分支進行比較：

256

257* **留言**：在特定行上留下內聯評論，然後使用您的下一條訊息將評論發送給 Claude

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

253 259

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

255 261

313 319

314### 封存工作階段320### 封存工作階段

315 321

316您可以封存工作階段以保持工作階段清單的組織。封存的工作階段隱藏在預設工作階段清單中，但可以通過篩選封存的工作階段來檢視。322封存工作階段可將其從側邊欄的工作階段清單中移除。若要封存工作階段，請在側邊欄中將滑鼠懸停在該工作階段上，開啟其 **⋯** 功能表，然後選擇**封存**。

317 323

318若要封存工作階段，請在側邊欄中將滑鼠懸停在工作階段上，然後選擇封存圖示。324#### 尋找已封存的工作階段

325

326若要查看已封存的工作階段，請前往 [claude.ai/code/sessions](https://claude.ai/code/sessions) 並開啟**已封存**分頁。若要將工作階段放回側邊欄的工作階段清單，請在該分頁上將滑鼠懸停在該工作階段上，開啟其 **⋮** 功能表，然後選擇**取消封存**。

319 327

320### 刪除工作階段328### 刪除工作階段

321 329

322刪除工作階段會永久移除工作階段及其資料。此操作無法撤銷。您可以通過兩種方式刪除工作階段：330刪除工作階段會永久移除工作階段及其資料。此操作無法撤銷。您可以從側邊欄、工作階段功能表刪除工作階段，若已封存該工作階段，也可以從**已封存**分頁刪除：

323 331

324* **從側邊欄**：篩選封存的工作階段，然後將滑鼠懸停在您要刪除的工作階段上，並選擇刪除圖示332* **從側邊欄**：將滑鼠懸停在工作階段上，開啟其 **⋯** 功能表，然後選擇**刪除**

325* **從工作階段功能表**：開啟工作階段，選擇工作階段標題旁的下拉式功能表，然後選擇**刪除**333* **從工作階段功能表**：開啟工作階段，選擇工作階段標題旁的下拉式功能表，然後選擇**刪除**

334* **從已封存分頁**：在[**已封存**分頁](#find-an-archived-session)上將滑鼠懸停在工作階段上，開啟其 **⋮** 功能表，然後選擇**刪除**

326 335

327在刪除工作階段之前，系統會要求您確認。336在刪除工作階段之前，系統會要求您確認。

328 337

336 345

337根據 PR 來自何處以及您使用的設備，有幾種方式可以開啟自動修復：346根據 PR 來自何處以及您使用的設備，有幾種方式可以開啟自動修復：

338 347

339* **在 Claude Code 網頁版中建立的 PR**：開啟工作階段於 claude.ai/code，開啟 CI 狀態欄，並選擇**自動修復**348* **在雲端工作階段中建立的 PR**：在 claude.ai/code 開啟工作階段，並在 [**Changes** 卡片](#review-changes)中找到該 pull request。開啟 pull request 標題旁的 **⋮** 選單，並開啟**自動修復**

340* **從您的終端**：在 PR 的分支上執行 [`/autofix-pr`](https://code.claude.com/docs/zh-TW/commands)。Claude Code 使用 `gh` 偵測開啟的 PR，生成網頁工作階段，並在一個步驟中開啟自動修復349* **從您的終端**：在 PR 的分支上執行 [`/autofix-pr`](https://code.claude.com/docs/zh-TW/commands)。Claude Code 使用 `gh` 偵測開啟的 PR，生成網頁工作階段，並在一個步驟中開啟自動修復

341* **從行動應用程式**：告訴 Claude 自動修復 PR，例如「監視此 PR 並修復任何 CI 失敗或審查評論」350* **從行動應用程式**：告訴 Claude 自動修復 PR，例如「監視此 PR 並修復任何 CI 失敗或審查評論」

342* **任何現有 PR**：將 PR URL 貼到工作階段中並告訴 Claude 自動修復它351* **任何現有 PR**：將 PR URL 貼到工作階段中並告訴 Claude 自動修復它

343 352

344自動修復是每個 PR 的切換開關。若要停止監視，請在 claude.ai/code 的工作階段中開啟 CI 狀態欄並清除**自動修復**切換，或告訴 Claude 停止監視 PR。353若要停止監視，請在工作階段的 [**Changes** 卡片](#review-changes)中，於 pull request 的 **⋮** 選單中關閉**自動修復**，或告訴 Claude 停止監視 PR。

345 354

346### Claude 如何回應 PR 活動355### Claude 如何回應 PR 活動

347 356

381* 一分鐘後重試，因為容量是按需佈建的390* 一分鐘後重試，因為容量是按需佈建的

382* 確認您的 GitHub 連線可以到達儲存庫，請遵循[連接 GitHub 後沒有儲存庫出現](https://code.claude.com/docs/zh-TW/web-quickstart.md#no-repositories-appear-after-connecting-github)391* 確認您的 GitHub 連線可以到達儲存庫，請遵循[連接 GitHub 後沒有儲存庫出現](https://code.claude.com/docs/zh-TW/web-quickstart.md#no-repositories-appear-after-connecting-github)

383 392

393### Your new session couldn't start

394

395您的提示詞已回到您送出它的輸入框中。

396

397* **連線中斷**：請檢查您的網際網路連線以及您使用的任何 VPN 或代理伺服器，然後再次傳送您的提示詞

398* **伺服器錯誤**：請稍候片刻，然後再次傳送您的提示詞。如果通知再次出現，請檢查 [status.claude.com](https://status.claude.com)

399

400### Can't rewind to this message

401

402當您的工作階段在 Claude Code 版本早於 v2.1.246 的[自架 runner](https://code.claude.com/docs/zh-TW/self-hosted-environments) 上執行時，**Rewind to here** 在最新訊息以外的任何訊息上都會因此錯誤而失敗。請要求負責管理您組織 runner 的人員[升級它們](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#pin-the-version)。

403

384### 無法取得組織 UUID404### 無法取得組織 UUID

385 405

386`claude --cloud` 和 `claude --teleport` 需要使用 claude.ai 帳戶登入。如果您使用 API 金鑰進行身分驗證，或您儲存的帳戶詳細資訊已過期，您會看到以下其中一項：406`claude --cloud` 和 `claude --teleport` 需要使用 claude.ai 帳戶登入。如果您使用 API 金鑰進行身分驗證，或您儲存的帳戶詳細資訊已過期，您會看到以下其中一項：

claude-projects.md +9 −4

Details

111 111

112project 現在在側邊欄的 **Projects** 下列出，其對話已打開。[您的第一批](#your-first-batch) 涵蓋了在您發送工作之前要設定的內容。112project 現在在側邊欄的 **Projects** 下列出，其對話已打開。[您的第一批](#your-first-batch) 涵蓋了在您發送工作之前要設定的內容。

113 113

114### 從現有雲端工作階段開始114### 從現有工作階段開始

115 115

116如果您自己啟動的雲端工作階段正在執行屬於 project 的工作，請打開其側邊欄功能表並選擇 **Move to project**，然後從子功能表中挑選：116如果您自己啟動的雲端工作階段正在執行屬於 project 的工作，請打開其側邊欄功能表並選擇 **Move to project**，然後從子功能表中挑選：

117 117

120 120

121雲端工作階段的訊息框上方也可能出現 **Set up project** 橫幅。如果您使用它而不是 **Continue as new project**，結果是相同的，除了工作階段正在執行的回合會在 project 打開後停止。121雲端工作階段的訊息框上方也可能出現 **Set up project** 橫幅。如果您使用它而不是 **Continue as new project**，結果是相同的，除了工作階段正在執行的回合會在 project 打開後停止。

122 122

123本地工作階段沒有這些選項。若要在 project 中繼續其工作，請在 project 對話中描述工作，或推送其分支、將該儲存庫添加到 project，並在任務中命名分支。123您自己機器上的工作階段在透過 [Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md#start-a-remote-control-session) 連接後，會在 claude.ai/code 獲得相同的側邊欄功能表。從 project 中，Claude 無法讀取在您的帳戶開啟 [**Require trusted devices**](https://code.claude.com/docs/zh-TW/remote-control.md#trusted-devices) 時所連接之工作階段的逐字稿。如果該設定已關閉：

124

1251. 如果工作階段尚未連接，請在其中執行 `/remote-control`。如果它是在該設定開啟時連接的，請先中斷連接，然後再重新連接。

1262. 在瀏覽器中，於 [claude.ai/code](https://claude.ai/code) 的側邊欄中找到該工作階段的列，打開其功能表，並從相同的子功能表中挑選。

127

128如果 **Require trusted devices** 已開啟，或您未使用 Remote Control，請自己在 project 對話中描述工作。或者推送工作階段的分支、將其儲存庫添加到 project，並告訴 Claude 分支名稱。

124 129

125### 設定 GitHub 存取130### 設定 GitHub 存取

126 131

425* **雲端工作階段**：每個執行緒是一個 [雲端工作階段](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md)，除非您要求 Claude 在您的機器上執行它。無論哪種方式，Claude 啟動並追蹤它而不是您。您也可以將自己啟動的雲端工作階段的工作帶入 project：在該工作階段的側邊欄選單中選擇 [**Move to project**](#start-from-an-existing-cloud-session)。430* **雲端工作階段**：每個執行緒是一個 [雲端工作階段](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md)，除非您要求 Claude 在您的機器上執行它。無論哪種方式，Claude 啟動並追蹤它而不是您。您也可以將自己啟動的雲端工作階段的工作帶入 project：在該工作階段的側邊欄選單中選擇 [**Move to project**](#start-from-an-existing-cloud-session)。

426* **排程任務**：當您在 project 中要求排程工作時，Claude 會建立一個[雲端排程任務](https://code.claude.com/docs/zh-TW/routines.md)，在該 project 中作為執行緒執行，並出現在其 **Scheduled tasks** 標籤上。您在 project 外建立的排程任務會繼續獨立運作。431* **排程任務**：當您在 project 中要求排程工作時，Claude 會建立一個[雲端排程任務](https://code.claude.com/docs/zh-TW/routines.md)，在該 project 中作為執行緒執行，並出現在其 **Scheduled tasks** 標籤上。您在 project 外建立的排程任務會繼續獨立運作。

427* **Remote Control**：[Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md) 連接 claude.ai 到在您機器上執行的 Claude Code 工作階段。當您在 project 中要求 Claude 在您的電腦上執行執行緒時，project [使用 Remote Control 來執行它](#run-a-thread-on-your-own-computer)。432* **Remote Control**：[Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md) 連接 claude.ai 到在您機器上執行的 Claude Code 工作階段。當您在 project 中要求 Claude 在您的電腦上執行執行緒時，project [使用 Remote Control 來執行它](#run-a-thread-on-your-own-computer)。

428* **本地工作階段和代理檢視**：您在終端、IDE 或桌面應用程式的本地環境中啟動的工作階段無法新增到 project。[代理檢視](https://code.claude.com/docs/zh-TW/agent-view.md) 是用於並排追蹤多個本地工作階段的螢幕，您仍然自己啟動每個工作階段並給它其任務。433* **本機工作階段和 agent 檢視**：您在終端機、IDE 或桌面應用程式的本機環境中自行啟動的工作階段不會屬於您的 projects，不過您可以[將其工作帶入某個 project](#start-from-an-existing-cloud-session)。[Agent 檢視](https://code.claude.com/docs/zh-TW/agent-view.md) 是用於並排追蹤多個本機工作階段的畫面，您仍然自己啟動每個工作階段並給它其任務。

429* **Worktrees**：[worktree](https://code.claude.com/docs/zh-TW/worktrees.md) 給每個本機工作階段其自己的儲存庫工作副本。雲端執行緒不需要它們：每個執行緒將其儲存庫克隆到其自己的雲端沙箱中，並在自己的分支上工作。434* **Worktrees**：[worktree](https://code.claude.com/docs/zh-TW/worktrees.md) 給每個本機工作階段其自己的儲存庫工作副本。雲端執行緒不需要它們：每個執行緒將其儲存庫克隆到其自己的雲端沙箱中，並在自己的分支上工作。

430* **代理團隊**：[代理團隊](https://code.claude.com/docs/zh-TW/agent-teams.md) 是一個工作階段，為單個任務啟動隊友工作階段，在您的機器上或在雲端工作階段內，並以該任務結束。435* **代理團隊**：[代理團隊](https://code.claude.com/docs/zh-TW/agent-teams.md) 是一個工作階段，為單個任務啟動隊友工作階段，在您的機器上或在雲端工作階段內，並以該任務結束。

431* **Subagents**：[subagent](https://code.claude.com/docs/zh-TW/sub-agents.md) 在一個工作階段內執行，在其自己的內容視窗中執行側面任務，並將摘要返回到該工作階段。project 的執行緒是 Claude 啟動的完整工作階段，並向 project 對話報告，執行緒仍然可以為其自己的側面任務使用 subagents。436* **Subagents**：[subagent](https://code.claude.com/docs/zh-TW/sub-agents.md) 在一個工作階段內執行，在其自己的內容視窗中執行側面任務，並將摘要返回到該工作階段。project 的執行緒是 Claude 啟動的完整工作階段，並向 project 對話報告，執行緒仍然可以為其自己的側面任務使用 subagents。

437 442

438* Projects 在 claude.ai/code、桌面應用程式和 Claude 行動應用程式中可用，不在終端機 CLI、VS Code 擴充功能或 JetBrains 外掛中，也不通過 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry。443* Projects 在 claude.ai/code、桌面應用程式和 Claude 行動應用程式中可用，不在終端機 CLI、VS Code 擴充功能或 JetBrains 外掛中，也不通過 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry。

439* Project 執行緒是 [雲端工作階段](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md)，或通過 [Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md) 在您自己的機器上的工作階段，兩種情況下 Anthropic 都是模型提供者。[安全](https://code.claude.com/docs/zh-TW/security.md) 和 [資料使用](https://code.claude.com/docs/zh-TW/data-usage.md) 涵蓋了雲端工作階段如何隔離以及保留什麼，[連線和安全](https://code.claude.com/docs/zh-TW/remote-control.md#connection-and-security) 涵蓋了您機器上的執行緒如何連線以及儲存什麼。444* Project 執行緒是 [雲端工作階段](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md)，或通過 [Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md) 在您自己的機器上的工作階段，兩種情況下 Anthropic 都是模型提供者。[安全](https://code.claude.com/docs/zh-TW/security.md) 和 [資料使用](https://code.claude.com/docs/zh-TW/data-usage.md) 涵蓋了雲端工作階段如何隔離以及保留什麼，[連線和安全](https://code.claude.com/docs/zh-TW/remote-control.md#connection-and-security) 涵蓋了您機器上的執行緒如何連線以及儲存什麼。

440* 您無法將自己在機器上啟動的工作階段新增到 project。Project 只能通過 [Remote Control 在您的機器上執行執行緒](#run-a-thread-on-your-own-computer)到達您的機器，該部分列出了它需要的內容。445* 您無法將自己在機器上啟動的工作階段新增到 project，但您可以[將其工作帶入 project](#start-from-an-existing-cloud-session)。Project 通過 [Remote Control 在您的機器上執行執行緒](#run-a-thread-on-your-own-computer)到達您的機器，該部分列出了它需要的內容。

441* 雲端執行緒的沙箱在回合之間暫停，並在執行緒繼續時恢復。如果沙箱無法恢復，執行緒從新克隆繼續，因此未提交的變更可能會遺失。在長任務上，要求 Claude 提交並推送進行中的工作。446* 雲端執行緒的沙箱在回合之間暫停，並在執行緒繼續時恢復。如果沙箱無法恢復，執行緒從新克隆繼續，因此未提交的變更可能會遺失。在長任務上，要求 Claude 提交並推送進行中的工作。

442* project 屬於一個使用者。您無法與另一個使用者共享 project 或其執行緒，執行緒記錄沒有其他雲端工作階段具有的共享選項。在測試版期間，projects 沒有組織級控制。447* project 屬於一個使用者。您無法與另一個使用者共享 project 或其執行緒，執行緒記錄沒有其他雲端工作階段具有的共享選項。在測試版期間，projects 沒有組織級控制。

443* 執行緒屬於啟動它的一個 project。您無法將執行緒移動或複製到另一個 project，或將其移出以獨立存在。[**Move to project**](#start-from-an-existing-cloud-session) 僅以另一種方式進行：它將雲端工作階段的工作帶入 project。您無法將兩個 projects 合併為一個。448* 執行緒屬於啟動它的一個 project。您無法將執行緒移動或複製到另一個 project，或將其移出以獨立存在。[**Move to project**](#start-from-an-existing-cloud-session) 僅以另一種方式進行：它將雲端工作階段的工作帶入 project。您無法將兩個 projects 合併為一個。

cli-reference.md +1 −1

Details

136| `--teammate-mode` | 設定[代理程式團隊](https://code.claude.com/docs/zh-TW/agent-teams.md)隊友的顯示方式：`in-process`（預設）、`auto`、`tmux` 或 `iterm2`。覆蓋此工作階段的 [`teammateMode`](https://code.claude.com/docs/zh-TW/settings-reference#teammatemode) 設定。請參閱[選擇顯示模式](https://code.claude.com/docs/zh-TW/agent-teams.md#choose-a-display-mode) | `claude --teammate-mode auto` |136| `--teammate-mode` | 設定[代理程式團隊](https://code.claude.com/docs/zh-TW/agent-teams.md)隊友的顯示方式：`in-process`（預設）、`auto`、`tmux` 或 `iterm2`。覆蓋此工作階段的 [`teammateMode`](https://code.claude.com/docs/zh-TW/settings-reference#teammatemode) 設定。請參閱[選擇顯示模式](https://code.claude.com/docs/zh-TW/agent-teams.md#choose-a-display-mode) | `claude --teammate-mode auto` |

138| `--tools` | 限制 Claude 可以使用的內建工具。使用 `""` 停用全部、`"default"` 取得預設集，或工具名稱如 `"Bash,Edit,Read"`。在 macOS、Linux 和 WSL 上，預設集會排除 `Glob` 和 `Grep`，如[Glob 工具行為](https://code.claude.com/docs/zh-TW/tools-reference.md#glob-tool-behavior)下所述。如果您在此命名[任務追蹤工具](https://code.claude.com/docs/zh-TW/tools-reference.md#task-tool-availability)之一，Claude Code 也會選擇加入。旗標不會影響 MCP 工具；若要也拒絕這些，請使用 `--disallowedTools "mcp__*"`。省略 [`EndConversation`](https://code.claude.com/docs/zh-TW/tools-reference#endconversation-tool-behavior) 的清單不會移除它；`""` 僅在沒有 MCP 工具保持時移除它 | `claude --tools "Bash,Edit,Read"` |138| `--tools` | 限制 Claude 可以使用的內建工具。使用 `""` 停用全部、`"default"` 取得預設集，或工具名稱如 `"Bash,Edit,Read"`。在 macOS、Linux 和 WSL 上，預設集會排除 `Glob` 和 `Grep`，如[Glob 工具行為](https://code.claude.com/docs/zh-TW/tools-reference.md#glob-tool-behavior)下所述。如果您在此指定[任務追蹤工具](https://code.claude.com/docs/zh-TW/tools-reference.md#task-tool-availability)之一，Claude Code 也會讓工作階段選擇加入。旗標不會影響 MCP 工具；若要一併拒絕這些工具，請使用 `--disallowedTools "mcp__*"`。省略 [`EndConversation`](https://code.claude.com/docs/zh-TW/tools-reference#endconversation-tool-behavior) 的清單不會移除它；`""` 僅在沒有剩餘的 MCP 工具時移除它 | `claude --tools "Bash,Edit,Read"` |

141| `--worktree`, `-w` | 在隔離的 [git worktree](https://code.claude.com/docs/zh-TW/worktrees.md) 中啟動 Claude，位於 `<repo>/.claude/worktrees/<name>`。如果您未提供名稱，Claude Code 會產生一個。傳遞 `#<number>`、GitHub 提取要求 URL 或 GitLab 合併要求 URL 以[從 `origin` 擷取該 PR 或 MR 並從它分支 worktree](https://code.claude.com/docs/zh-TW/worktrees#branch-from-a-pull-request)。從 GitLab 合併要求分支需要 Claude Code v2.1.233 或更新版本 | `claude -w feature-auth` |141| `--worktree`, `-w` | 在隔離的 [git worktree](https://code.claude.com/docs/zh-TW/worktrees.md) 中啟動 Claude，位於 `<repo>/.claude/worktrees/<name>`。如果您未提供名稱，Claude Code 會產生一個。傳遞 `#<number>`、GitHub 提取要求 URL 或 GitLab 合併要求 URL 以[從 `origin` 擷取該 PR 或 MR 並從它分支 worktree](https://code.claude.com/docs/zh-TW/worktrees#branch-from-a-pull-request)。從 GitLab 合併要求分支需要 Claude Code v2.1.233 或更新版本 | `claude -w feature-auth` |

code-review.md +1 −1

Details

67 67

68* **發現結果**：相關程式碼行上的內聯評論，並在審查正文中提供摘要68* **發現結果**：相關程式碼行上的內聯評論，並在審查正文中提供摘要

69* **檢查執行**：名為 **Claude Code Review**，其[詳細資訊](https://code.claude.com/docs/zh-TW/code-review-pull-requests.md#check-run-output)中列出發現結果。檢查執行不會以失敗作結。69* **檢查執行**：名為 **Claude Code Review**，其[詳細資訊](https://code.claude.com/docs/zh-TW/code-review-pull-requests.md#check-run-output)中列出發現結果。檢查執行不會以失敗作結。

~~70* **未發現任何問題時**：檢查執行的標題顯示為 **Code review found no issues**，且 Claude 會在 pull request 上發佈相同的簡短說明~~70* **取代發現結果的說明**：當檢查執行的標題顯示為 **Code review found no issues** 時發佈

71 71

72Code Review 會選擇審查所執行的 Claude 模型，其管理設定不提供模型選擇。若要讓審查更徹底或更精簡，請變更[審查等級](#review-levels)。72Code Review 會選擇審查所執行的 Claude 模型，其管理設定不提供模型選擇。若要讓審查更徹底或更精簡，請變更[審查等級](#review-levels)。

73 73

code-review-pull-requests.md +4 −1

Details

152 152

153### 後續審查涵蓋的範圍153### 後續審查涵蓋的範圍

154 154

155自行啟動的後續審查（例如在推送之後）會著重於自上次審查以來的變更，並發佈較少的 nit 和 pre-existing 發現項目。其摘要會在一行以 "found and not posted" 或 "outside the scope of this re-review and not posted." 結尾的文字中，計算它省略的項目數量。155自行啟動的後續審查（例如在推送之後）會著重於自上次審查以來的變更，並發佈較少的 [nit 和 pre-existing 發現項目](#severity-levels)。若要查看它是否因此省略了某些發現項目，請在審查內文中尋找計算其數量的句子：

156

157* **自上次審查以來未變更之程式碼上的發現項目**：該句子以「outside the scope of this re-review and not posted」結尾

158* **Nit 和 pre-existing 發現項目**：該句子以「found and not posted」結尾

156 159

157若要取得不省略任何這些項目的審查，請留言 [`@claude review`](#comment-commands)。它會再次涵蓋整個 pull request。160若要取得不省略任何這些項目的審查，請留言 [`@claude review`](#comment-commands)。它會再次涵蓋整個 pull request。

158 161

code-review-troubleshooting.md +1 −1

Details

16| :- | :- | :- |16| :- | :- | :- |

21| **Code review not repeated — earlier findings still open** | 最新一次推送未執行自動審查，且先前審查中的 Important 發現仍未解決 | 推送修正，或若仍想取得審查，請留言 `@claude review`。請參閱[推送保留先前結果的情況](https://code.claude.com/docs/zh-TW/code-review-pull-requests.md#when-a-push-keeps-the-earlier-result) |21| **Code review not repeated — earlier findings still open** | 最新一次推送未執行自動審查，且先前審查中的 Important 發現仍未解決 | 推送修正，或若仍想取得審查，請留言 `@claude review`。請參閱[推送保留先前結果的情況](https://code.claude.com/docs/zh-TW/code-review-pull-requests.md#when-a-push-keeps-the-earlier-result) |

desktop.md +48 −17

Details

223 223

224#### 隱藏或顯示工作階段詳細資訊面板224#### 隱藏或顯示工作階段詳細資訊面板

225 225

226若要隱藏或顯示面板，請點擊工作階段標題列中的 **Hide session rail** 或 **Show session rail**，或在視窗較窄時點擊標題列 **⋮** 選單中的對應項目。如果您仍然看不到面板，請[檢查您使用的是哪種 Code 標籤佈局](#check-which-layout-you-have)。226若要隱藏或顯示面板，請點擊工作階段標題列中的 **Hide session rail** 或 **Show session rail**，或在標題列的 **⋮** 選單中點擊。如果您仍然看不到面板，請[檢查您使用的是哪種 Code 標籤佈局](#check-which-layout-you-have)。

227 227

228### 在終端機中執行命令228### 在終端機中執行命令

229 229

984 984

985* **系統**：x86\_64 或 arm64 處理器。該機器也必須符合 Claude Code 的[系統需求](https://code.claude.com/docs/zh-TW/setup.md#system-requirements)。在 Linux 上，Claude Code 需要 glibc 2.17 或更新版本，或 musl。若要查看機器使用哪一種，請在該機器上執行 `ldd --version`。在 Alpine Linux 等以 musl 為基礎的發行版上，也請安裝 [Claude Code 所需的套件](https://code.claude.com/docs/zh-TW/setup.md#alpine-linux-and-musl-based-distributions)。985* **系統**：x86\_64 或 arm64 處理器。該機器也必須符合 Claude Code 的[系統需求](https://code.claude.com/docs/zh-TW/setup.md#system-requirements)。在 Linux 上，Claude Code 需要 glibc 2.17 或更新版本，或 musl。若要查看機器使用哪一種，請在該機器上執行 `ldd --version`。在 Alpine Linux 等以 musl 為基礎的發行版上，也請安裝 [Claude Code 所需的套件](https://code.claude.com/docs/zh-TW/setup.md#alpine-linux-and-musl-based-distributions)。

986* **SFTP**：SSH 伺服器必須提供 SFTP 子系統，其 `sshd_config` 中的 `Subsystem sftp` 行會開啟此子系統。若要檢查，請在您電腦上的終端機中以 `sftp` 連線到相同的主機和連接埠。可正常運作的伺服器會顯示 `sftp>` 提示字元。986* **SFTP**：SSH 伺服器必須提供 SFTP 子系統，其 `sshd_config` 中的 `Subsystem sftp` 行會開啟此子系統。若要檢查，請在您電腦上的終端機中以 `sftp` 連線到相同的主機和連接埠。可正常運作的伺服器會顯示 `sftp>` 提示字元。

987* **每個連線的工作階段數**：macOS 和 Linux 上的 Desktop 會在一個 SSH 連線上開啟多個工作階段。如果伺服器的 `sshd_config` 設定了 `MaxSessions 1`，請將其調高，例如調到 OpenSSH 的預設值 10。987* **伺服器上的 `MaxSessions 1`**：若要連線到 `sshd_config` 設定了 `MaxSessions 1` 的伺服器，請執行以下其中一項：

988 * **您的電腦執行 macOS 或 Linux**：更新至 Claude Desktop v3.1623.0 或更新版本

989 * **您的電腦執行 Windows**：確保 Desktop [透過 OpenSSH 用戶端連線](#use-your-ssh-configuration)，因為 Desktop 的內建 SSH 用戶端無法連線到該伺服器

990 * **您可以變更伺服器**：提高 `MaxSessions`，例如提高到 OpenSSH 的預設值 10

991* **使用 `MaxSessions 1` 時的登入**：使用不需提示即可運作的登入方式，例如由您的 SSH agent 保存的金鑰。Desktop 每次連線或重新連線時至少會登入兩次。每個[終端機](#run-commands-in-the-terminal)分頁，以及每個您在其中執行以 `!` 開頭之命令的 Desktop 工作階段，預期至少會再多一次登入。Claude 執行的命令則不會有額外登入。

992* **使用 `MaxSessions 1` 時的一次性代碼**：如果每次登入都會提示您，例如使用一次性代碼時，`!` 命令會失敗。請改在終端機分頁中執行這些命令，終端機分頁會在自己的窗格中提示。

988* **安裝資料夾**：Desktop 會在您家目錄的 `~/.claude/remote/` 下安裝輔助程式和 Claude Code。它會從該處執行這些程式，因此該資料夾不能位於以 `noexec` 掛載的檔案系統上。請在每位連線使用者的家目錄中預留約 1 GB 的磁碟空間。如需該資料夾包含的內容，請參閱[遠端機器上的檔案和程序](#files-and-processes-on-the-remote-machine)。993* **安裝資料夾**：Desktop 會在您家目錄的 `~/.claude/remote/` 下安裝輔助程式和 Claude Code。它會從該處執行這些程式，因此該資料夾不能位於以 `noexec` 掛載的檔案系統上。請在每位連線使用者的家目錄中預留約 1 GB 的磁碟空間。如需該資料夾包含的內容，請參閱[遠端機器上的檔案和程序](#files-and-processes-on-the-remote-machine)。

989* **Shell**：遠端機器上為您帳戶設定的 shell 必須能執行透過 SSH 傳送的命令，如同 Bash、Zsh 和 `sh`994* **Shell**：遠端機器上為您帳戶設定的 shell 必須能執行透過 SSH 傳送的命令，如同 Bash、Zsh 和 `sh`

990* **網路**：Claude Code 在遠端機器上執行，並從該處發出網路請求，因此該機器需要 [Claude Code 所需的網路存取](https://code.claude.com/docs/zh-TW/network-config.md#network-access-requirements)。如果該機器無法下載 Claude Code，Desktop 會在您的電腦上下載後再上傳。Claude Code 的其他請求仍會從遠端機器發出。在 Linux 遠端機器上，如果這些請求需要代理伺服器，請[為 SSH 工作階段設定它](#set-a-proxy-or-a-ca-certificate-for-ssh-sessions)。995* **網路**：Claude Code 在遠端機器上執行，並從該處發出網路請求，因此該機器需要 [Claude Code 所需的網路存取](https://code.claude.com/docs/zh-TW/network-config.md#network-access-requirements)。如果該機器無法下載 Claude Code，Desktop 會在您的電腦上下載後再上傳。Claude Code 的其他請求仍會從遠端機器發出。在 Linux 遠端機器上，如果這些請求需要代理伺服器，請[為 SSH 工作階段設定它](#set-a-proxy-or-a-ca-certificate-for-ssh-sessions)。

993 998

994如果 Linux 遠端機器透過代理伺服器連上網際網路或需要 CA 憑證，請在該機器的 `~/.claude/settings.json` 中的 `env` 下加入[代理伺服器和 CA 變數](https://code.claude.com/docs/zh-TW/network-config.md)。即使您已在該機器的 `~/.profile`、`~/.bash_profile`、`~/.zprofile` 或 `~/.zshrc` 中匯出這些變數，也請加入。999如果 Linux 遠端機器透過代理伺服器連上網際網路或需要 CA 憑證，請在該機器的 `~/.claude/settings.json` 中的 `env` 下加入[代理伺服器和 CA 變數](https://code.claude.com/docs/zh-TW/network-config.md)。即使您已在該機器的 `~/.profile`、`~/.bash_profile`、`~/.zprofile` 或 `~/.zshrc` 中匯出這些變數，也請加入。

995 1000

996SSH 工作階段不會從這些檔案取得這些變數，即使在該機器的終端機中執行的 `claude` 會取得。工作階段可能會因此停滯，或顯示 **The connection from … to the API failed** 或 **Authentication failed**，而重新登入也無濟於事。1001在 SSH 工作階段中，即使該機器終端機中的 `claude` 能取得這些檔案中的變數，Claude Code 也不會取得。工作階段可能因此停滯，或顯示 **The connection from … to the API failed** 或 **Authentication failed**，且重新登入也沒有幫助。

997 1002

998**1. 加入變數**1003**1. 加入變數**

999 1004

1028 1033

1029重新啟動遠端機器，或結束 Desktop 並終止輔助程式的程序，如[移除輔助程式](#files-and-processes-on-the-remote-machine)的前兩個步驟所示。請在沒有任務執行時進行，因為任一種方式都會中斷 Claude 的工作。1034重新啟動遠端機器，或結束 Desktop 並終止輔助程式的程序，如[移除輔助程式](#files-and-processes-on-the-remote-machine)的前兩個步驟所示。請在沒有任務執行時進行，因為任一種方式都會中斷 Claude 的工作。

1030 1035

1031#### 在 macOS 和 Linux 上使用您的 SSH 設定1036#### 使用您的 SSH 設定

1032 1037

1033在 macOS 和 Linux 上，Desktop 會執行您電腦上的 OpenSSH 用戶端來連線，因此會使用您的 `~/.ssh/config`。透過 OpenSSH 用戶端連線需要 Claude Desktop v1.37937.0 或更新版本。在 **SSH host** 欄位中輸入該檔案中的 `Host` 名稱，即可使用其項目中的設定，例如 `HostName`、`User`、`IdentityFile`、`CertificateFile`、`ProxyJump` 和 `ProxyCommand`。1038當 Desktop 透過您電腦上的 OpenSSH 用戶端連線時，您可以在 macOS、Linux 和 Windows 上使用您的 SSH 設定：

1039

1040* **macOS 和 Linux**：Desktop 透過在您電腦上執行 OpenSSH 用戶端來連線，因此會使用您的 `~/.ssh/config`。透過 OpenSSH 用戶端連線需要 Claude Desktop v1.37937.0 或更新版本。

1041* **Windows**：當 Desktop 透過 OpenSSH 用戶端連線時，會使用您的 `%USERPROFILE%\.ssh\config`。如果您使用的是 Claude 帳戶而非第三方供應商，透過 OpenSSH 用戶端連線需要滿足以下所有條件：

1042

1043 * Claude Desktop v2.2553.0 或更新版本。若要查看您的版本，請參閱[檢查您的版本](#check-your-version)。

1044 * Microsoft 的 OpenSSH 9.4 或更新版本

1045 * 使用本頁頂端的下載按鈕安裝 Desktop，因為來自 Microsoft Store 的 Desktop 不會透過 OpenSSH 用戶端連線

1046

1047 如果您無法滿足這些需求，或使用第三方供應商，請參閱[在 Windows 上不透過 OpenSSH 用戶端連線](#connect-on-windows-without-the-openssh-client)。

1048

1049使用 OpenSSH 用戶端時，請在 **SSH host** 欄位中輸入設定檔中的 `Host` 名稱。Desktop 接著會使用該 `Host` 項目中的設定，例如 `HostName`、`User`、`IdentityFile`、`CertificateFile`、`ProxyJump` 和 `ProxyCommand`。

1034 1050

1035新增連線之前，請在您電腦上的終端機中檢查用戶端和項目：1051新增連線之前，請在您電腦上的終端機中檢查用戶端和項目：

1036 1052

1037* **用戶端版本**：執行 `ssh -V`。用戶端必須是 OpenSSH 7.6 或更新版本。1053* **macOS 和 Linux 上的用戶端版本**：執行 `ssh -V`。用戶端必須是 OpenSSH 7.6 或更新版本。

1038* **項目**：以 `Host` 名稱執行 `ssh`，例如 `ssh devbox`。如果失敗，請先修正該項目。1054* **Windows 上的用戶端版本**：Desktop 會先嘗試您 `PATH` 上的 `ssh`，因此請執行 `ssh -V`。如果輸出顯示 `OpenSSH_for_Windows_` 以及 9.4 或更新版本，則用戶端通過檢查。如果未通過，請檢查 Desktop 接下來會嘗試的兩個資料夾：在 `C:\Windows\System32\OpenSSH` 中執行 `.\ssh.exe -V`，然後在 `C:\Program Files\OpenSSH` 中執行。

1055* **Windows 上沒有用戶端通過**：在 Windows 中新增 **OpenSSH Client** 選用功能並安裝擱置中的 Windows 更新，或安裝 [Microsoft 的較新版本](https://learn.microsoft.com/en-us/troubleshoot/windows-server/system-management-components/upgrade-in-box-openssh-to-latest-openssh-release)。然後結束並重新開啟 Desktop。若要查看 Desktop 是否找到可用的 OpenSSH 用戶端，請在 [`ssh.log`](#get-desktops-logs-for-an-ssh-problem) 中尋找 `Windows OpenSSH client:` 和版本，或尋找 `no usable Windows OpenSSH client`。

1056* **項目**：在 Windows 上，請使用通過版本檢查的用戶端。以 `Host` 名稱執行 `ssh`，例如 `ssh devbox`。如果失敗，請先修正項目。

1039 1057

1040您可以將 **SSH port** 和 **SSH key (optional)** 欄位留空。如果您填寫其中之一，Desktop 會將其與項目一併使用：1058您可以將 **SSH port** 和 **SSH key (optional)** 欄位留空。如果您填寫其中之一，Desktop 會將其與項目一併使用：

1041 1059

1042* **SSH port**：此處的值會覆寫項目的 `Port`1060* **SSH port**：此處的值會覆寫項目的 `Port`

1043* **SSH key (optional)**：除了項目的 `IdentityFile` 和您 SSH agent 中的金鑰之外，Desktop 也會提供您選取的金鑰檔案1061* **SSH key (optional)**：使用 OpenSSH 用戶端時，除了項目的 `IdentityFile` 和 SSH agent 中的金鑰外，Desktop 還會提供您選取的金鑰檔案。在 Windows 上，請選取 OpenSSH 格式的金鑰，因為 `ssh` 不會讀取 PuTTY `.ppk` 檔案。

1062

1063##### 在 Windows 上不透過 OpenSSH 用戶端連線

1064

1065在 Windows 上，如果您的電腦不符合 [OpenSSH 用戶端的需求](#use-your-ssh-configuration)，您會透過 Desktop 的內建 SSH 用戶端連線。使用第三方供應商時，預設會透過內建用戶端連線，您的管理員可以變更此設定。關於該設定，請參閱 [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions)。

1066

1067使用內建用戶端時，如果您的 `PATH` 有 `ssh` 命令，您仍可以在 **SSH host** 欄位中輸入 SSH 設定中的 `Host` 名稱，但有以下限制：

1068

1069* **項目中的設定**：Desktop 會採用 `HostName`、`User`、`Port` 和 `IdentityFile`。如果您的 `PATH` 上有 `sh` shell，也會採用 `ProxyCommand`。

1070* **SSH key (optional)**：將此欄位留空以保留項目的 `IdentityFile`，因為您在此選取的金鑰檔案會取代 `IdentityFile`

1071* **`CertificateFile` 和 `ProxyJump`**：Desktop 會忽略 `CertificateFile`，且如果項目設定了 `ProxyJump`，連線會失敗。若要使用其中任一設定，請[透過 OpenSSH 用戶端連線](#use-your-ssh-configuration)。

1044 1072

1045##### 透過跳板主機連線到機器1073##### 透過跳板主機連線到機器

1046 1074

1095 1123

1096##### 在 `ProxyCommand` 中使用來自您 shell 的變數1124##### 在 `ProxyCommand` 中使用來自您 shell 的變數

1097 1125

1098若要在 `ProxyCommand` 或 `Match exec` 命令中使用您自己的環境變數，請在 shell 啟動檔案（例如 `~/.zshrc`）中匯出它，然後結束並重新開啟 Desktop。Desktop 啟動時會讀取您登入 shell 匯出的內容，並保留這些值直到您結束它。1126在 macOS 和 Linux 上，若要在 `ProxyCommand` 或 `Match exec` 命令中使用您自己的環境變數，請在 shell 啟動檔案（例如 `~/.zshrc`）中 export。然後結束並重新開啟 Desktop。Desktop 啟動時會讀取您的登入 shell 所 export 的內容，並保留這些值直到您結束 Desktop。

1099 1127

1100這需要 Claude Desktop v2.37337.0 或更新版本，以及接受 `-0` 的 `env` 命令，您可以在電腦上的終端機中執行 `env -0` 來檢查。1128這需要 Claude Desktop v2.37337.0 或更新版本，以及接受 `-0` 的 `env` 命令，您可以在電腦上的終端機中執行 `env -0` 來檢查。

1101 1129

1103>1131>

1104> 如果您的 shell 設定了臨時 AWS 憑證，請[為 AWS CLI 提供設定檔](#use-aws-credentials-in-a-proxycommand)，而不是匯出 `AWS_*` 變數。1132> 如果您的 shell 設定了臨時 AWS 憑證，請[為 AWS CLI 提供設定檔](#use-aws-credentials-in-a-proxycommand)，而不是匯出 `AWS_*` 變數。

1105 1133

1106##### 在 `ProxyCommand` 中使用 AWS 憑證1134##### 在 macOS 和 Linux 上的 `ProxyCommand` 中使用 AWS 憑證

1107 1135

1108如果您在 shell 啟動檔案中設定了臨時 AWS 憑證，執行 AWS CLI 的 `ProxyCommand` 可能在終端機中能夠連線，但在 Desktop 中失敗。當您的 shell 匯出 `AWS_SESSION_TOKEN`、`AWS_SECURITY_TOKEN` 或 `AWS_CREDENTIAL_EXPIRATION` 時，Desktop 中的 `ssh` 和您的 `ProxyCommand` 不會取得 shell 的 AWS 憑證、`AWS_REGION` 或 `AWS_PROFILE`。1136如果您在 shell 啟動檔案中設定了臨時 AWS 憑證，執行 AWS CLI 的 `ProxyCommand` 可能在終端機中能夠連線，但在 Desktop 中失敗。當您的 shell 匯出 `AWS_SESSION_TOKEN`、`AWS_SECURITY_TOKEN` 或 `AWS_CREDENTIAL_EXPIRATION` 時，Desktop 中的 `ssh` 和您的 `ProxyCommand` 不會取得 shell 的 AWS 憑證、`AWS_REGION` 或 `AWS_PROFILE`。

1109 1137

1242 1270

1243##### 準備長時間任務1271##### 準備長時間任務

1244 1272

1245* **先更新**：在開始長時間任務之前更新 Desktop。在 macOS 和 Windows 上，Desktop 可能會自行重新啟動以安裝已下載的更新。當 Claude 正在處理 SSH 任務時，該重新啟動會等待。在 macOS 上使用 Claude 帳戶時，預設情況下，一旦更新已等待 72 小時，重新啟動仍可能會進行。1273* **先更新**：在開始長時間任務之前更新 Desktop。在 macOS 和 Windows 上，Desktop 可能會自行重新啟動以安裝已下載的更新。當 Claude 正在處理 SSH 任務時，該重新啟動會等待。根據預設，一旦更新已等待 72 小時，如果 Desktop 能[在之後重新加入任務](#reopen-a-session-after-you-quit-desktop)，重新啟動就可能在任務期間進行。

1246* **不要在 Windows 上結束，或在使用第三方供應商且版本早於 v2.42304.0 時結束**：在這些情況下結束後，您會失去執行中的任務，因此請在任務期間讓 Desktop 保持開啟。在其他任何情況下，請在結束前查看[您能取回什麼](#reopen-a-session-after-you-quit-desktop)。1274* **結束前確認**：結束或重新啟動後，您不一定能取回執行中的任務，例如在某些 Desktop 更新之後。相關情況請參閱[結束 Desktop 後重新開啟工作階段](#reopen-a-session-after-you-quit-desktop)。

1275* **使用較舊版本時，讓 Desktop 保持開啟**：在 Windows 上使用 v3.1623.0 之前的 Claude Desktop 時，Desktop 結束或重新啟動後您無法取回執行中的任務。在 macOS 或 Linux 上搭配第三方供應商使用 v2.42304.0 之前的版本時也是如此。在這兩種情況下，請在任務期間讓 Desktop 保持開啟。若要查看您的版本，請參閱[檢查您的版本](#check-your-version)。

1247* **減少請求**：選擇能[讓任務較少等待您](#handle-requests-that-arrive-while-you-are-away)的權限模式、規則或 hook1276* **減少請求**：選擇能[讓任務較少等待您](#handle-requests-that-arrive-while-you-are-away)的權限模式、規則或 hook

1248* **檢查跳板主機**：如果您的跳板主機要求登入（例如推送到手機），請改用無需提示即可運作的登入方式。否則 Desktop 每次嘗試重新連線時都可能再傳送一次推送。1277* **檢查跳板主機**：如果您的跳板主機要求登入（例如推送到手機），請改用無需提示即可運作的登入方式。否則 Desktop 每次嘗試重新連線時都可能再傳送一次推送。

1249* **測試遠端機器**：啟動一個短任務，在任務仍在執行時結束 Desktop，並在任務應已完成很久之後再次開啟工作階段。如果任務尚未完成且工作階段未顯示身分驗證錯誤，請檢查遠端機器上[可能終止任務的因素](#limits-while-desktop-is-disconnected)。1278* **測試遠端機器**：啟動一個短任務，在任務仍在執行時結束 Desktop，並在任務應已完成很久之後再次開啟工作階段。如果任務尚未完成且工作階段未顯示身分驗證錯誤，請檢查遠端機器上[可能終止任務的因素](#limits-while-desktop-is-disconnected)。

1320 1349

1321結束 Desktop 後，任務會在遠端電腦上繼續執行，但除非 Desktop 能重新加入其程序，否則工作階段再次開啟時任務會停止。Desktop 關閉期間，任務會執行直到完成、需要您處理，或達到某個[限制](#limits-while-desktop-is-disconnected)。1350結束 Desktop 後，任務會在遠端電腦上繼續執行，但除非 Desktop 能重新加入其程序，否則工作階段再次開啟時任務會停止。Desktop 關閉期間，任務會執行直到完成、需要您處理，或達到某個[限制](#limits-while-desktop-is-disconnected)。

1322 1351

1323* **Windows 上的 Desktop**：您無法取回執行中的任務，因為 Desktop 在結束後永遠不會重新加入。請只在您預期任務已完成時再啟動 Desktop，因為工作階段可能在 Desktop 啟動時開啟。1352* **Windows 上的 Desktop，任務在 v3.1623.0 之前的版本中啟動**：即使 Desktop 之後已更新，您也無法取回該任務。請只在您預期任務已完成時才再次啟動 Desktop，因為工作階段可能會在 Desktop 啟動時開啟，而工作階段開啟時任務就會停止。如果您不知道任務是在哪個版本中啟動的，也請等到您預期任務已完成。

1324* **第三方供應商，來自較早版本的任務**：如果您在 v2.42304.0 之前的 Desktop 版本中啟動任務，即使在 macOS 或 Linux 上您也無法取回。請只在您預期任務已完成時再啟動 Desktop。1353* **macOS 或 Linux 上的第三方供應商，任務在 v2.42304.0 之前的版本中啟動**：您無法取回該任務。請只在您預期任務已完成時才再次啟動 Desktop。

1325* **其他任何任務，搭配 macOS 或 Linux 上的 Desktop**：啟動 Desktop 並開啟工作階段，如果 Desktop 重新加入，任務就會繼續。它不一定能重新加入，例如在某些 Desktop 更新之後，因此請[在長時間任務前更新](#prepare-a-long-task)。1354* **任何其他任務**：啟動 Desktop 並開啟工作階段，如果 Desktop 重新加入，任務就會繼續進行。它不一定能重新加入，例如在某些 Desktop 更新之後，因此請[在長時間任務之前更新](#prepare-a-long-task)。

1326 1355

1327當 Desktop 無法重新加入時，您也會失去任何正在等待您的核准或問題。如果任務沒有自行繼續，請傳送訊息，Claude 會從對話已儲存的歷史記錄繼續。1356任務停止時，工作階段可能會在 Desktop 啟動新程序時顯示 `Restarting Claude Code on <host>…`。您也會失去任何正在等待您的核准或問題。如果 Claude 沒有自行繼續，請傳送訊息，Claude 就會從對話的已儲存歷程記錄繼續。

1328 1357

1329如需第三方部署的相關資訊，請參閱 [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions)。1358如需第三方部署的相關資訊，請參閱 [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions)。

1330 1359

1411 1440

1412若要了解誰連線到遠端機器，請讀取該機器上 SSH 伺服器的日誌，其中來自 Desktop 的登入看起來與來自終端機的登入相同。Desktop 在 macOS 或 Linux 上時，預期每次 Desktop 連線會有一筆記錄，而不是每個工作階段一筆。1441若要了解誰連線到遠端機器，請讀取該機器上 SSH 伺服器的日誌，其中來自 Desktop 的登入看起來與來自終端機的登入相同。Desktop 在 macOS 或 Linux 上時，預期每次 Desktop 連線會有一筆記錄，而不是每個工作階段一筆。

1413 1442

1443如果伺服器設定了 `MaxSessions 1`，每次 Desktop 連線或重新連線時至少會有兩筆項目。每個終端機分頁，以及每個您在其中執行以 `!` 開頭之命令的 Desktop 工作階段，至少還會再多一筆。

1444

1414您在 Claude Code 的[指標與事件](https://code.claude.com/docs/zh-TW/monitoring-usage.md#available-metrics-and-events)中找不到 Desktop 的 SSH 連線。若要從中得知 SSH 工作階段在哪台遠端機器上執行，請參閱[將遙測歸因於 Desktop SSH 工作階段](https://code.claude.com/docs/zh-TW/monitoring-usage.md#attribute-telemetry-to-desktop-ssh-sessions)。關於 Desktop 自身的連線記錄，請參閱[取得 SSH 問題的 Desktop 日誌](#get-desktops-logs-for-an-ssh-problem)。1445您在 Claude Code 的[指標與事件](https://code.claude.com/docs/zh-TW/monitoring-usage.md#available-metrics-and-events)中找不到 Desktop 的 SSH 連線。若要從中得知 SSH 工作階段在哪台遠端機器上執行，請參閱[將遙測歸因於 Desktop SSH 工作階段](https://code.claude.com/docs/zh-TW/monitoring-usage.md#attribute-telemetry-to-desktop-ssh-sessions)。關於 Desktop 自身的連線記錄，請參閱[取得 SSH 問題的 Desktop 日誌](#get-desktops-logs-for-an-ssh-problem)。

1415 1446

1416#### 登入前即關閉的連線1447#### 登入前即關閉的連線

2112| - | - | - |2143| - | - | - |

errors.md +2 −0

Details

328| `subagent_type is required: the general-purpose agent is not available in this session` | [工具錯誤](#subagent-type-is-required) |328| `subagent_type is required: the general-purpose agent is not available in this session` | [工具錯誤](#subagent-type-is-required) |

329| `Error: this write left the memory index at MEMORY.md at ..., over its ... read limit` | [工具錯誤](#memory-index-is-over-its-read-limit) |329| `Error: this write left the memory index at MEMORY.md at ..., over its ... read limit` | [工具錯誤](#memory-index-is-over-its-read-limit) |

330| `Sandbox is required but failed to initialize: <reason>` | [沙箱機制疑難排解](https://code.claude.com/docs/zh-TW/sandboxing.md#commands-refused-with-sandbox-is-required) |

331| `Sandbox is required (sandbox.failIfUnavailable) and stopped being available in this session: <reason>` | [沙箱機制疑難排解](https://code.claude.com/docs/zh-TW/sandboxing.md#commands-refused-with-sandbox-is-required) |

332| `Failed to write the plan approval request to the lead's inbox — plan not submitted` | [工具錯誤](#failed-to-write-to-a-teammate-inbox) |334| `Failed to write the plan approval request to the lead's inbox — plan not submitted` | [工具錯誤](#failed-to-write-to-a-teammate-inbox) |

fast-mode.md +2 −2

Details

80 80

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

82 82

83當您在對話中首次啟用快速模式時，您需要為整個對話上下文支付完整的快速模式未快取輸入 token 價格。對話進行得越深入，這筆費用就越高，因此在對話開始時就啟用快速模式，這筆費用最低。此費用每個對話只收取一次，因此稍後關閉並再次開啟快速模式不會重複計費。如需了解機制，請參閱[快速模式如何與提示快取互動](https://code.claude.com/docs/zh-TW/prompt-caching.md#turning-on-fast-mode)。83當您在對話中首次啟用快速模式時，您需要為整個對話上下文支付完整的快速模式未快取輸入 token 價格。對話進行得越深入，這筆費用就越高，因此在對話開始時就啟用快速模式，這筆費用最低。快速模式與標準速度會保留[各自獨立的快取](https://code.claude.com/docs/zh-TW/prompt-caching.md#turning-on-fast-mode)，因此之後每次切換時，都會再次以未快取方式讀取部分或全部對話內容。

84 84

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

86 86

167 167

168在閘道後面，請檢查下列設定，在這些設定中 Claude Code 不會發送可用性檢查，且沒有先前成功的檢查快取：168在閘道後面，請檢查下列設定，在這些設定中 Claude Code 不會發送可用性檢查，且沒有先前成功的檢查快取：

169 169

170* 您將 `ANTHROPIC_BASE_URL` 指向您的閘道，並將 [`ANTHROPIC_API_KEY`](https://code.claude.com/docs/zh-TW/llm-gateway-connect#set-the-base-url-and-credential) 設定為閘道發行、但不符合 Anthropic API 金鑰格式的金鑰。Claude Code 不會將此類金鑰傳送至 `api.anthropic.com`。170* 您將 `ANTHROPIC_BASE_URL` 指向您的閘道，並將 [`ANTHROPIC_API_KEY`](https://code.claude.com/docs/zh-TW/llm-gateway-connect#set-the-base-url-and-credential) 設定為閘道發行、但不符合 Anthropic API 金鑰格式的金鑰。

171* 您設定了 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](https://code.claude.com/docs/zh-TW/env-vars)，因此 Claude Code 會跳過檢查。171* 您設定了 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](https://code.claude.com/docs/zh-TW/env-vars)，因此 Claude Code 會跳過檢查。

172 172

173若要在任一設定中復原快速模式，請設定 `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS=1`。173若要在任一設定中復原快速模式，請設定 `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS=1`。

features-overview.md +1 −1

Details

262 262

263**上下文成本：** 低，直到使用。僅使用者 skills 在調用前成本為零。263**上下文成本：** 低，直到使用。僅使用者 skills 在調用前成本為零。

264 264

265**在 subagents 中：** Skills 在 subagents 中的工作方式不同。不是按需載入，subagent 的 `skills` 欄位中列出的 skills 在啟動時完全預載入其上下文。Subagents 仍然可以通過 Skill 工具發現和調用未列出的專案、使用者和 plugin skills。265**在 subagents 中：** subagent 的 `skills` 欄位中列出的 skills，其完整內容會[在啟動時載入其上下文](https://code.claude.com/docs/zh-TW/sub-agents.md#preload-skills-into-subagents)，而非按需載入。Subagents 仍然可以透過 Skill 工具發現和調用未列出的專案、使用者和外掛 skills。

266 266

267> [!TIP]267> [!TIP]

268>268>

glossary.md +2 −2

Details

120 120

121### Compaction121### Compaction

122 122

123當[內容視窗](#context-window)接近其限制時，自動摘要您的對話。較舊的工具輸出會先清除，然後對話會被摘要。專案根目錄 CLAUDE.md 和自動記憶在壓縮後保留並從磁碟重新載入；僅在對話中給出的指示可能會遺失。執行 `/compact` 以手動觸發，可選擇使用焦點，例如 `/compact focus on the API changes`。123當[上下文視窗](#context-window)接近其限制時，自動摘要您的對話。專案根目錄 CLAUDE.md 和自動記憶在壓縮後保留，但僅在對話中給出的指示可能不會保留。執行 `/compact` 以手動觸發，可選擇使用焦點，例如 `/compact focus on the API changes`。

124 124

125深入瞭解：[What survives compaction](https://code.claude.com/docs/zh-TW/context-window.md#what-survives-compaction) · [When context fills up](https://code.claude.com/docs/zh-TW/how-claude-code-works.md#when-context-fills-up)125深入瞭解：[What survives compaction](https://code.claude.com/docs/zh-TW/context-window.md#what-survives-compaction) · [When context fills up](https://code.claude.com/docs/zh-TW/how-claude-code-works.md#when-context-fills-up) · [When Claude Code compacts a conversation you leave idle](https://code.claude.com/docs/zh-TW/settings-reference.md#idlecompaction)

126 126

127### Connector127### Connector

128 128

hooks.md +15 −5

Details

1426 1426

1427Setup hook 無法阻擋；無論退出碼為何，執行都會繼續。無論退出碼為何，Claude Code 都會捨棄 Setup hook 的 [JSON 輸出欄位](#json-output)，例如 `systemMessage`、`continue` 和 `hookSpecificOutput.additionalContext`。使用 `-p` 時，只有在您以 `--output-format stream-json --verbose` 啟動的情況下，Setup hook 的 stdout、stderr 和退出碼才會以 [`hook_response` 事件](https://code.claude.com/docs/zh-TW/headless#read-session-metadata)的形式出現在執行輸出中。1427Setup hook 無法阻擋；無論退出碼為何，執行都會繼續。無論退出碼為何，Claude Code 都會捨棄 Setup hook 的 [JSON 輸出欄位](#json-output)，例如 `systemMessage`、`continue` 和 `hookSpecificOutput.additionalContext`。使用 `-p` 時，只有在您以 `--output-format stream-json --verbose` 啟動的情況下，Setup hook 的 stdout、stderr 和退出碼才會以 [`hook_response` 事件](https://code.claude.com/docs/zh-TW/headless#read-session-metadata)的形式出現在執行輸出中。

1428 1428

1429Setup hook 可以存取 `CLAUDE_ENV_FILE`。寫入該檔案的變數會保存到工作階段後續的 Bash 命令中，與 [SessionStart hook](#persist-environment-variables) 相同。`Setup` 上只會執行 `type: "command"` hook。`Setup` 上的 `type: "mcp_tool"` hook 一律會被略過，如 [MCP tool hook 欄位](#mcp-tool-hook-fields)中所述。1429Setup hook 可以存取 `CLAUDE_ENV_FILE`。如果您的 hook 將變數寫入該檔案，這些變數會保存到該工作階段後續的 Bash 命令中，與 [SessionStart hook](#persist-environment-variables) 相同。`Setup` 上只會執行 `type: "command"` hook。`Setup` 上的 `type: "mcp_tool"` hook 一律會被略過，如 [MCP 工具 hook 欄位](#mcp-tool-hook-fields)中所述。

1430 1430

1431### InstructionsLoaded1431### InstructionsLoaded

1432 1432

1483 1483

1484`UserPromptSubmit` 上的 [Agent SDK 回呼 hook](https://code.claude.com/docs/zh-TW/agent-sdk/hooks.md) 達到逾時時，會以指出該 hook 與逾時的訊息封鎖提示詞，因為那裡的回呼可能扮演不得在失敗時放行的政策關卡。工作階段會繼續。1484`UserPromptSubmit` 上的 [Agent SDK 回呼 hook](https://code.claude.com/docs/zh-TW/agent-sdk/hooks.md) 達到逾時時，會以指出該 hook 與逾時的訊息封鎖提示詞，因為那裡的回呼可能扮演不得在失敗時放行的政策關卡。工作階段會繼續。

1485 1485

1486#### 提示詞檢查期間按下 `Esc`

1487

1488如果您在 hook 仍在檢查提示詞時按下 `Esc` 或中斷工作階段，檢查會停止，提示詞也不會傳達給 Claude。您在終端機輸入的文字會回到提示詞輸入框，並在您重新送出時再次由 hook 檢查。

1489

1490hook 可能在您中斷的同一時刻阻擋提示詞。此時提示詞會維持被阻擋的狀態：您會看到該 hook 的[阻擋訊息](#what-a-blocked-prompt-leaves-behind)，文字也不會回到輸入框。

1491

1486#### UserPromptSubmit 輸入1492#### UserPromptSubmit 輸入

1487 1493

1488除了[通用輸入欄位](#common-input-fields)之外，UserPromptSubmit hook 還會接收包含所送出文字的 `prompt` 欄位。被收合為 `[Pasted text #N]` 預留位置的貼上內容會在原處展開後送達。在 Claude Code [為 Claude 標記貼上文字](https://code.claude.com/docs/zh-TW/terminal-config.md#how-claude-treats-pasted-text)的工作階段中，該展開內容位於 `<pasted_content id="…">` 行和 `</pasted_content id="…">` 行之間，因此若您的 hook 會解析提示詞，請將這些行納入考量。1494除了[通用輸入欄位](#common-input-fields)之外，UserPromptSubmit hook 還會接收包含所送出文字的 `prompt` 欄位。被收合為 `[Pasted text #N]` 預留位置的貼上內容會在原處展開後送達。在 Claude Code [為 Claude 標記貼上文字](https://code.claude.com/docs/zh-TW/terminal-config.md#how-claude-treats-pasted-text)的工作階段中，該展開內容位於 `<pasted_content id="…">` 行和 `</pasted_content id="…">` 行之間，因此若您的 hook 會解析提示詞，請將這些行納入考量。

1741 1747

1742使用 [PreToolUse 決策控制](#pretooluse-decision-control)來允許、拒絕、詢問或延遲工具呼叫。1748使用 [PreToolUse 決策控制](#pretooluse-decision-control)來允許、拒絕、詢問或延遲工具呼叫。

1743 1749

1744`PreToolUse` 上超過逾時的 [Agent SDK 回呼 hook](https://code.claude.com/docs/zh-TW/agent-sdk/hooks.md) 會封鎖工具呼叫，而 Claude 會收到一個指出逾時的錯誤結果。1750`PreToolUse` 上超過逾時的 [Agent SDK 回呼 hook](https://code.claude.com/docs/zh-TW/agent-sdk/hooks.md#hook-timeout) 會阻擋該工具呼叫。

1745 1751

1746#### PreToolUse 輸入1752#### PreToolUse 輸入

1747 1753

2969 2975

2970當主對話中的 shell 命令變更工作目錄時執行，例如 Claude 執行 `cd` 命令時。可用於對目錄變更做出反應：重新載入環境變數、啟用專案專屬的工具鏈，或自動執行設定指令碼。可與 [FileChanged](#filechanged) 搭配，用於 [direnv](https://direnv.net/) 等管理各目錄環境的工具。2976當主對話中的 shell 命令變更工作目錄時執行，例如 Claude 執行 `cd` 命令時。可用於對目錄變更做出反應：重新載入環境變數、啟用專案專屬的工具鏈，或自動執行設定指令碼。可與 [FileChanged](#filechanged) 搭配，用於 [direnv](https://direnv.net/) 等管理各目錄環境的工具。

2971 2977

2972CwdChanged hook 可以存取 [`CLAUDE_ENV_FILE`](#persist-environment-variables)。寫入該檔案的變數會保留至後續的 Bash 命令中，直到下一個 CwdChanged 事件時由 Claude Code 清除。2978CwdChanged hook 可以存取 [`CLAUDE_ENV_FILE`](#persist-environment-variables)。若您的 hook 將變數寫入該檔案，這些變數會保留至後續的 Bash 命令中，直到下一個 CwdChanged 事件時由 Claude Code 清除。

2973 2979

2974CwdChanged 不支援 matcher，每次發生時都會觸發。2980CwdChanged 不支援 matcher，每次發生時都會觸發。

2975 2981

3134* Claude Code 將[背景工作階段](https://code.claude.com/docs/zh-TW/agent-view.md#how-file-edits-are-isolated)隔離在其自己的 worktree 中3140* Claude Code 將[背景工作階段](https://code.claude.com/docs/zh-TW/agent-view.md#how-file-edits-are-isolated)隔離在其自己的 worktree 中

3135* `worktree` 模式下的 [`claude remote-control`](https://code.claude.com/docs/zh-TW/remote-control#start-a-remote-control-session) 在自己的 worktree 中啟動工作階段3141* `worktree` 模式下的 [`claude remote-control`](https://code.claude.com/docs/zh-TW/remote-control#start-a-remote-control-session) 在自己的 worktree 中啟動工作階段

3136 3142

3137當 Claude 透過 Bash 工具執行 `git worktree add`，而非呼叫 `EnterWorktree` 時，您的 WorktreeCreate hook 不會執行。若要檢查或封鎖該命令，請新增一個使用 `Bash` matcher 的 [`PreToolUse`](#pretooluse) hook。3143WorktreeCreate hook 不會針對 Claude 透過 Bash 新增的 worktree 執行，而外掛的 hook 也不會針對您以 `--worktree` 與 [`--tmux`](https://code.claude.com/docs/zh-TW/cli-reference#cli-flags) 啟動時所建立的 worktree 執行：

3144

3145* **透過 Bash 執行 `git worktree add`**：若要檢查或封鎖該命令，請新增一個使用 `Bash` matcher 的 [`PreToolUse`](#pretooluse) hook。

3146* **`--worktree` 搭配 `--tmux`**：Claude Code 會在載入外掛之前建立 worktree，因此來自外掛的 WorktreeCreate hook 不會執行。若要讓您的 hook 在同時使用兩個旗標時執行，請改為在[設定檔](#configuration)中定義它。在 v2.1.300 之前，外掛的 WorktreeCreate hook 在僅使用 `--worktree` 時也不會執行。

3138 3147

3139根據預設，Claude Code 會使用 `git worktree` 建立隔離的工作副本。設定 WorktreeCreate hook 會取代該預設的 git 行為，讓您可以使用其他版本控制系統，例如 SVN、Perforce 或 Mercurial。3148根據預設，Claude Code 會使用 `git worktree` 建立隔離的工作副本。設定 WorktreeCreate hook 會取代該預設的 git 行為，讓您可以使用其他版本控制系統，例如 SVN、Perforce 或 Mercurial。

3140 3149

4076 4085

4077當非同步 hook 觸發時，Claude Code 啟動 hook 程序並立即繼續，而不等待它完成。Hook 在 stdin 上接收與同步 hook 相同的 JSON 輸入。4086當非同步 hook 觸發時，Claude Code 啟動 hook 程序並立即繼續，而不等待它完成。Hook 在 stdin 上接收與同步 hook 相同的 JSON 輸入。

4078 4087

4079背景程序退出後，Claude Code 會在下一個對話輪次將 hook 的 JSON 回應中的 `additionalContext` 和 `systemMessage` 欄位傳遞給 Claude。與同步 hook 的 `systemMessage` 不同，這兩個欄位都不會顯示給你。4088背景程序退出後，Claude Code 會在下一個對話回合將 hook 的 JSON 回應中的 `additionalContext` 和 `systemMessage` 欄位傳遞給 Claude，但[重複的 `SessionStart` 輸出](#limitations)除外。與同步 hook 的 `systemMessage` 不同，這兩個欄位都不會顯示給您。

4080 4089

4081將 JSON 回應單獨輸出至 stdout，或單獨列印在其自己的一行上：4090將 JSON 回應單獨輸出至 stdout，或單獨列印在其自己的一行上：

4082 4091

4144 4153

4145* Hook 輸出在下一個對話輪次上傳遞。如果工作階段閒置，回應會等待直到下一個使用者互動。例外：退出代碼為 2 的 `asyncRewake` hook 即使在工作階段閒置時也會立即喚醒 Claude。4154* Hook 輸出在下一個對話輪次上傳遞。如果工作階段閒置，回應會等待直到下一個使用者互動。例外：退出代碼為 2 的 `asyncRewake` hook 即使在工作階段閒置時也會立即喚醒 Claude。

4146* 每次執行都會建立一個單獨的背景程序。4155* 每次執行都會建立一個單獨的背景程序。

4156* 非同步 `SessionStart` hook 在每次事件觸發時都會執行。當 `additionalContext` 和 `systemMessage` 文字與 Claude 上次從該 hook 收到的內容相同時，Claude Code 會略過該 hook 的輸出，除非此後有同步 `SessionStart` hook 新增了其他文字。當文字變更時，Claude Code 會傳遞該文字，並在壓縮或 `/clear` 之後該 hook 下次執行時再次傳遞。在 v2.1.295 之前，Claude Code 會在每次恢復時將相同的文字再次新增到對話中。

4147 4157

4148## 安全考慮4158## 安全考慮

4149 4159

hooks-guide.md +1 −1

Details

954* `PostToolUse` hooks 無法撤銷操作，因為工具已經執行。954* `PostToolUse` hooks 無法撤銷操作，因為工具已經執行。

955* [`PermissionRequest`](https://code.claude.com/docs/zh-TW/hooks#permissionrequest) hook 在 Claude Code 即將要求您授予權限時觸發，或在它原本會自動拒絕無法顯示提示的呼叫時觸發。在使用 `-p` 旗標的[非互動模式](https://code.claude.com/docs/zh-TW/headless.md)中，它們在 [`dontAsk` 模式](https://code.claude.com/docs/zh-TW/permission-modes#allow-only-pre-approved-tools-with-dontask-mode)以外仍會執行，而沒有任何 hook 做出決策、也沒有其他機制能回應的呼叫會被拒絕。955* [`PermissionRequest`](https://code.claude.com/docs/zh-TW/hooks#permissionrequest) hook 在 Claude Code 即將要求您授予權限時觸發，或在它原本會自動拒絕無法顯示提示的呼叫時觸發。在使用 `-p` 旗標的[非互動模式](https://code.claude.com/docs/zh-TW/headless.md)中，它們在 [`dontAsk` 模式](https://code.claude.com/docs/zh-TW/permission-modes#allow-only-pre-approved-tools-with-dontask-mode)以外仍會執行，而沒有任何 hook 做出決策、也沒有其他機制能回應的呼叫會被拒絕。

956* `Stop` hooks 在 Claude 完成回應時觸發，而不僅在任務完成時。它們在使用者中斷時不觸發。API 錯誤觸發 [StopFailure](https://code.claude.com/docs/zh-TW/hooks.md#stopfailure) 代替。956* `Stop` hooks 在 Claude 完成回應時觸發，而不僅在任務完成時。它們在使用者中斷時不觸發。API 錯誤觸發 [StopFailure](https://code.claude.com/docs/zh-TW/hooks.md#stopfailure) 代替。

957* 當多個 `PreToolUse` hooks 傳回 [`updatedInput`](https://code.claude.com/docs/zh-TW/hooks#pretooluse) 以重寫工具的引數時，最後完成的會獲勝。由於 hooks 並行執行，順序是非確定性的。避免有多個 hook 修改同一工具的輸入。957* 當多個 `PreToolUse` hook 傳回 [`updatedInput`](https://code.claude.com/docs/zh-TW/hooks#pretooluse) 以重寫工具的輸入時，Claude Code 不會合併這些重寫，也不保證工具會以哪一個重寫執行。避免有多個 hook 重寫同一工具的輸入。

958 958

959### Hooks 和權限模式959### Hooks 和權限模式

960 960

how-claude-code-works.md +1 −1

Details

131 131

132#### 當上下文填滿時132#### 當上下文填滿時

133 133

134Claude Code 在您接近限制時自動管理上下文。它首先清除較舊的工具輸出，然後在需要時總結對話。您的請求和關鍵程式碼片段被保留；對話早期的詳細指示可能會丟失。將持久規則放在 CLAUDE.md 中，而不是依賴對話歷史。134Claude Code 在您接近限制時自動管理上下文。它會將對話壓縮成摘要。摘要會保留您的請求和關鍵程式碼片段，但對話早期的詳細指示可能會丟失。將持久規則放在 CLAUDE.md 中，而不是依賴對話歷史。

135 135

136要控制在壓縮期間保留的內容，請在 CLAUDE.md 中新增「Compact Instructions」部分或使用焦點執行 `/compact`（如 `/compact focus on the API changes`）。136要控制在壓縮期間保留的內容，請在 CLAUDE.md 中新增「Compact Instructions」部分或使用焦點執行 `/compact`（如 `/compact focus on the API changes`）。

137 137

interactive-mode.md +2 −0

Details

659 659

660若要重新繫結捲動檔案列表或變更比較對象的快捷鍵，請參閱[差異面板動作](https://code.claude.com/docs/zh-TW/keybindings.md#diff-panel-actions)。660若要重新繫結捲動檔案列表或變更比較對象的快捷鍵，請參閱[差異面板動作](https://code.claude.com/docs/zh-TW/keybindings.md#diff-panel-actions)。

661 661

662在未完成的合併、rebase、cherry-pick 或 revert 期間，面板會持續顯示它上次從 git 讀取的變更，因此不會被該操作的傳入變更填滿。它會在操作結束後的第一次重新整理時更新，例如當 Claude 下一次編輯檔案時。

663

662### 差異對話框664### 差異對話框

663 665

664差異對話框會以帶邊框的區塊形式在提示詞上方開啟，並列出已變更的檔案及其新增和移除的行數。它會將這些檔案與 `HEAD` 進行比較，或與您上次針對此儲存庫[在差異面板中選擇](#diff-panel)的對象進行比較。666差異對話框會以帶邊框的區塊形式在提示詞上方開啟，並列出已變更的檔案及其新增和移除的行數。它會將這些檔案與 `HEAD` 進行比較，或與您上次針對此儲存庫[在差異面板中選擇](#diff-panel)的對象進行比較。

keybindings.md +4 −4

Details

678 678

679## Vim 模式互動679## Vim 模式互動

680 680

681啟用 vim 模式時（透過 `/config` → 編輯器模式），快捷鍵和 vim 模式獨立運作：681當您透過 `/config` 中的編輯器模式設定啟用 vim 模式時，快捷鍵和 vim 模式會獨立運作：

682 682

683* **Vim 模式**在文字輸入層級處理輸入（游標移動、模式、動作）683* **Vim 模式**在文字輸入層級處理輸入：游標移動、模式和動作

684* **快捷鍵**在元件層級處理動作（切換待辦事項、提交等）684* **快捷鍵**在元件層級處理動作，例如切換待辦事項或提交訊息

685* vim 模式中的 Escape 鍵從 INSERT 切換到 NORMAL 模式；它不會觸發 `chat:cancel`685* 在 vim 模式中，Escape 鍵會將 INSERT 模式切換為 NORMAL 模式；它不會觸發 `chat:cancel`

686* 大多數 Ctrl+鍵快捷鍵通過 vim 模式傳遞到快捷鍵系統686* 大多數 Ctrl+鍵快捷鍵通過 vim 模式傳遞到快捷鍵系統

687* Vim 鍵無法透過快捷鍵檔案重新對應。若要對應兩鍵 INSERT 模式序列（例如 `jj`）至 Escape，請使用 [`vimInsertModeRemaps`](https://code.claude.com/docs/zh-TW/interactive-mode#remap-insert-mode-key-sequences) 設定687* Vim 鍵無法透過快捷鍵檔案重新對應。若要對應兩鍵 INSERT 模式序列（例如 `jj`）至 Escape，請使用 [`vimInsertModeRemaps`](https://code.claude.com/docs/zh-TW/interactive-mode#remap-insert-mode-key-sequences) 設定

688* 在 vim NORMAL 模式中，`?` 顯示說明選單（vim 行為）688* 在 vim NORMAL 模式中，`?` 顯示說明選單（vim 行為）

large-codebases.md +2 −2

Details

306 306

307## 新增各目錄範圍的 skills307## 新增各目錄範圍的 skills

308 308

309任何子目錄都可以定義[skills](https://code.claude.com/docs/zh-TW/skills.md)，其範圍限於該目錄自己的堆疊。當 Claude 判斷 skill 相關時，它會按需載入，因此 API 特定的工具在前端工作期間不會消耗上下文。309任何子目錄都可以定義[skills](https://code.claude.com/docs/zh-TW/skills.md)，其範圍限於該目錄自己的堆疊。當 Claude 判斷 skill 相關時，它會按需載入。

310 310

311Skills 位於目錄內的 `.claude/skills/` 下。將它們與該區域的程式碼一起提交，這樣任何複製儲存庫的人都能取得它們。在 monorepo 中，每個套件可以有一組 skills。在大型單一樹狀程式碼庫中，每個子系統（例如 `src/db/.claude/skills/`）有一組。311Skills 位於目錄內的 `.claude/skills/` 下。將它們與該區域的程式碼一起提交，這樣任何複製儲存庫的人都能取得它們。在 monorepo 中，每個套件可以有一組 skills。在大型單一樹狀程式碼庫中，每個子系統（例如 `src/db/.claude/skills/`）有一組。

312 312

347- Mock external services in `src/__tests__/mocks/`347- Mock external services in `src/__tests__/mocks/`

348```348```

349 349

350不同的子目錄以相同方式保存不同的 skills：`packages/web/.claude/skills/component-patterns/` 描述前端的元件慣例，而不是測試。當 Claude 在 `packages/api/` 中的檔案上工作時，它會載入 api-testing skill。當它在 `packages/web/` 中工作時，它會改為載入 component-patterns。在另一個目錄的任務期間，每個目錄的 skills 都不會載入。350不同的子目錄以相同方式保存不同的 skills：`packages/web/.claude/skills/component-patterns/` 描述前端的元件慣例，而不是測試。當 Claude 在 `packages/api/` 中的檔案上工作時，它會載入 api-testing skill。當它在 `packages/web/` 中工作時，它會載入 component-patterns。

351 351

352您也可以按檔案模式而不是按位置來限定 skill 的範圍。[`paths` frontmatter 欄位](https://code.claude.com/docs/zh-TW/skills#frontmatter-reference)採用 glob 模式，只有當 Claude 使用符合的檔案時，它才會自動載入 skill。使用此方法可以讓 skill 位於儲存庫根目錄的 `.claude/skills/` 中，但僅適用於特定檔案，例如限定於 `**/migrations/**` 的資料庫遷移 skill。352您也可以按檔案模式而不是按位置來限定 skill 的範圍。[`paths` frontmatter 欄位](https://code.claude.com/docs/zh-TW/skills#frontmatter-reference)採用 glob 模式，只有當 Claude 使用符合的檔案時，它才會自動載入 skill。使用此方法可以讓 skill 位於儲存庫根目錄的 `.claude/skills/` 中，但僅適用於特定檔案，例如限定於 `**/migrations/**` 的資料庫遷移 skill。

353 353

llm-gateway-connect.md +1 −1

Details

520| `400` 錯誤在每個請求上，在閘道自己的詞語中拒絕無法識別的工具類型，例如 `Input tag 'advisor_20260301'`，在 Claude Code v2.1.275 上 | 在該版本上的逐步推出中，即使關閉顧問，請求也會帶有[顧問工具](https://code.claude.com/docs/zh-TW/advisor.md)項目。Anthropic API 接受它，但驗證工具類型的閘道或上游會拒絕整個請求；[轉發請求正文欄位不變](https://code.claude.com/docs/zh-TW/llm-gateway-protocol.md#forward-as-open-lists)的閘道會不受影響地通過它。該項目是一個不帶任何對話內容的聲明 | 更新到 v2.1.276 或更高版本，除非您打開顧問，否則不會在 `ANTHROPIC_BASE_URL` 閘道後面發送該項目。在 v2.1.275 上，設定 [`CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1`](https://code.claude.com/docs/zh-TW/env-vars)，這會從請求中移除該項目 |520| `400` 錯誤在每個請求上，在閘道自己的詞語中拒絕無法識別的工具類型，例如 `Input tag 'advisor_20260301'`，在 Claude Code v2.1.275 上 | 在該版本上的逐步推出中，即使關閉顧問，請求也會帶有[顧問工具](https://code.claude.com/docs/zh-TW/advisor.md)項目。Anthropic API 接受它，但驗證工具類型的閘道或上游會拒絕整個請求；[轉發請求正文欄位不變](https://code.claude.com/docs/zh-TW/llm-gateway-protocol.md#forward-as-open-lists)的閘道會不受影響地通過它。該項目是一個不帶任何對話內容的聲明 | 更新到 v2.1.276 或更高版本，除非您打開顧問，否則不會在 `ANTHROPIC_BASE_URL` 閘道後面發送該項目。在 v2.1.275 上，設定 [`CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1`](https://code.claude.com/docs/zh-TW/env-vars)，這會從請求中移除該項目 |

521| 模型缺失於 `/model` 選擇器 | 閘道模型名稱不在 Claude Code 的內置列表中，或 Claude Code 顯示替換內置選項的 [`modelPicker`](https://code.claude.com/docs/zh-TW/settings-reference#modelpicker) 陣容 | 啟用[閘道模型發現](#add-gateway-models-to-the-model-picker)或使用[模型配置](https://code.claude.com/docs/zh-TW/model-config.md)變數添加名稱。如果 Claude Code 顯示替換 `modelPicker` 陣容，請將閘道模型添加到其中，或在受管設定提供時要求您的管理員添加它們 |521| 模型缺失於 `/model` 選擇器 | 閘道模型名稱不在 Claude Code 的內置列表中，或 Claude Code 顯示替換內置選項的 [`modelPicker`](https://code.claude.com/docs/zh-TW/settings-reference#modelpicker) 陣容 | 啟用[閘道模型發現](#add-gateway-models-to-the-model-picker)或使用[模型配置](https://code.claude.com/docs/zh-TW/model-config.md)變數添加名稱。如果 Claude Code 顯示替換 `modelPicker` 陣容，請將閘道模型添加到其中，或在受管設定提供時要求您的管理員添加它們 |

522| `/fast` 回報 `Fast mode unavailable due to network connectivity issues`，但推理請求正常運作 | [快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md)可用性檢查會直接連線到 `api.anthropic.com`，不遵循 `ANTHROPIC_BASE_URL`，因此被阻擋的直接出站連線會導致檢查失敗 | 如果出站連線被阻擋，請將 `api.anthropic.com` 加入允許清單，或設定跳過變數。請參閱[在代理伺服器和 LLM 閘道後使用快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways) |522| `/fast` 回報 `Fast mode unavailable due to network connectivity issues`，但推理請求正常運作 | [快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md)可用性檢查會直接連線到 `api.anthropic.com`，不遵循 `ANTHROPIC_BASE_URL`，因此被阻擋的直接出站連線會導致檢查失敗 | 如果出站連線被阻擋，請將 `api.anthropic.com` 加入允許清單，或設定跳過變數。請參閱[在代理伺服器和 LLM 閘道後使用快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways) |

523| 在以 `ANTHROPIC_API_KEY` 中閘道簽發的金鑰進行身分驗證的工作階段中，`/fast` 回報 `Fast mode is currently unavailable` | 當 `ANTHROPIC_BASE_URL` 指向您的閘道時，Claude Code 不會將非 Anthropic API 金鑰格式的金鑰傳送給 `api.anthropic.com`。因此[快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md)可用性檢查不會送出，且若沒有先前成功檢查的快取結果，Claude Code 會將快速模式視為不可用 | 設定 `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS=1`；請參閱[在代理伺服器和 LLM 閘道後使用快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways) |523| 在以 `ANTHROPIC_API_KEY` 中閘道簽發的金鑰進行身分驗證的工作階段中，`/fast` 回報 `Fast mode is currently unavailable` | 當 `ANTHROPIC_BASE_URL` 指向您的閘道，且金鑰不是 Anthropic API 金鑰的格式時，Claude Code 不會送出[快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md)可用性檢查。若沒有先前成功檢查的快取結果，它會將快速模式視為不可用 | 設定 `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS=1`；請參閱[在代理伺服器和 LLM 閘道後使用快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways) |

524| 在以 `ANTHROPIC_AUTH_TOKEN` 進行身分驗證的工作階段中，`/fast` 回報 `Fast mode has been disabled by your organization`，儘管組織已啟用快速模式 | 可用性檢查需要 claude.ai 登入或 API 金鑰；若僅有 bearer token，Claude Code 會將快速模式視為已停用，而不送出檢查 | 設定 `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK=1`；請參閱[在代理伺服器和 LLM 閘道後使用快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways) |524| 在以 `ANTHROPIC_AUTH_TOKEN` 進行身分驗證的工作階段中，`/fast` 回報 `Fast mode has been disabled by your organization`，儘管組織已啟用快速模式 | 可用性檢查需要 claude.ai 登入或 API 金鑰；若僅有 bearer token，Claude Code 會將快速模式視為已停用，而不送出檢查 | 設定 `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK=1`；請參閱[在代理伺服器和 LLM 閘道後使用快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways) |

525| Claude Code 要求您登入，儘管 [curl 測試](#verify-the-connection)成功 | CLI 沒有自己的認證：可達的基礎 URL 不是一個，在互動會話中，專案的 `.claude/settings.json` 或 `.claude/settings.local.json` 中的 `env` 區塊僅在首次執行嚮導和[信任提示](https://code.claude.com/docs/zh-TW/permissions.md#what-runs-before-you-trust-a-folder)後應用 | 在 Claude Code 在首次執行設定之前讀取的位置設定 `ANTHROPIC_AUTH_TOKEN`：shell 匯出、`~/.claude/settings.json` 中的 `env` 區塊或受管設定 |525| Claude Code 要求您登入，儘管 [curl 測試](#verify-the-connection)成功 | CLI 沒有自己的認證：可達的基礎 URL 不是一個，在互動會話中，專案的 `.claude/settings.json` 或 `.claude/settings.local.json` 中的 `env` 區塊僅在首次執行嚮導和[信任提示](https://code.claude.com/docs/zh-TW/permissions.md#what-runs-before-you-trust-a-folder)後應用 | 在 Claude Code 在首次執行設定之前讀取的位置設定 `ANTHROPIC_AUTH_TOKEN`：shell 匯出、`~/.claude/settings.json` 中的 `env` 區塊或受管設定 |

llm-gateway-protocol.md +5 −2

Details

148| :- | :- |148| :- | :- |

149| `x-claude-code-request-class` | 這是什麼類型的請求：`main` 用於主對話的一個回合，`subagent` 用於[子代理](https://code.claude.com/docs/zh-TW/sub-agents.md)的一個回合，`workflow` 用於在工作流程內執行的代理，`compaction` 用於壓縮對話的摘要請求，或 `auxiliary` 用於側面請求，例如工作階段標題、分類器和摘要。在每個請求上傳送 |149| `x-claude-code-request-class` | 這是什麼類型的請求：`main` 用於主對話的一個回合，`subagent` 用於[子代理](https://code.claude.com/docs/zh-TW/sub-agents.md)的一個回合，`workflow` 用於在工作流程內執行的代理，`compaction` 用於壓縮對話的摘要請求，或 `auxiliary` 用於側面請求，例如工作階段標題、分類器和摘要。在每個請求上傳送 |

150| `x-claude-code-agent-type` | 發出請求的子代理類型：內建代理類型名稱，例如 `Explore`、`Plan` 或 `general-purpose`，或 `custom` 用於使用者定義的代理，`teammate` 用於在主導者程序中執行的[代理團隊](https://code.claude.com/docs/zh-TW/agent-teams.md)成員，或 `fork` 用於[分支](https://code.claude.com/docs/zh-TW/sub-agents.md#fork-the-current-conversation)。僅在子代理自己的回合上存在；子代理的壓縮或側面請求保留代理 ID，但不攜帶類型。使用者選擇的代理名稱永遠不會被傳送 |150| `x-claude-code-agent-type` | 發出請求的子代理類型：內建代理類型名稱，例如 `Explore`、`Plan` 或 `general-purpose`，或 `custom` 用於使用者定義的代理，`teammate` 用於在主導者程序中執行的[代理團隊](https://code.claude.com/docs/zh-TW/agent-teams.md)成員，或 `fork` 用於[分支](https://code.claude.com/docs/zh-TW/sub-agents.md#fork-the-current-conversation)。僅在子代理自己的回合上存在；子代理的壓縮或側面請求保留代理 ID，但不攜帶類型。使用者選擇的代理名稱永遠不會被傳送 |

151| `x-claude-code-compaction` | 在[壓縮](https://code.claude.com/docs/zh-TW/prompt-caching.md#compacting-the-conversation)期間摘要對話的請求上存在。該值說明觸發了什麼：`auto` 當上下文視窗接近容量時，`manual` 用於 `/compact`，或 `reactive` 當 API 拒絕請求太長時。對於[閒置壓縮](https://code.claude.com/docs/zh-TW/settings-reference.md#idlecompaction)，該值也是 `auto`。在所有其他請求上不存在 |151| `x-claude-code-compaction` | 在[壓縮](https://code.claude.com/docs/zh-TW/prompt-caching.md#compacting-the-conversation)期間摘要對話的請求上存在。該值說明觸發了什麼：`auto` 當上下文視窗接近容量時，`manual` 用於 `/compact`，或 `reactive` 當 API 拒絕請求太長時。對於互動式終端機工作階段中的[閒置壓縮](https://code.claude.com/docs/zh-TW/settings-reference.md#idlecompaction)，該值也是 `auto`。在所有其他請求上不存在，包括在壓縮之前於背景撰寫摘要的請求 |

152| `x-claude-code-context-compacted` | 在壓縮後的第一個主對話請求上存在一次，具有與 `x-claude-code-compaction` 相同的值。此請求之前的對話前綴不再使用，因此可以刪除以其為鍵的快取 |152| `x-claude-code-context-compacted` | 在壓縮後的第一個主對話請求上存在一次，具有與 `x-claude-code-compaction` 相同的值。此請求之前的對話前綴不再使用，因此可以刪除以其為鍵的快取 |

153| `x-claude-code-prev-tool-durations` | 此請求攜帶其結果的工具呼叫的測量執行時間，格式為 `<name>=<ms>;<name>=<ms>`，例如 `Bash=742;Read=9`。在同一對話的下一個請求之後傳送，來自主工作階段或子代理的一批工具呼叫 |153| `x-claude-code-prev-tool-durations` | 此請求攜帶其結果的工具呼叫的測量執行時間，格式為 `<name>=<ms>;<name>=<ms>`，例如 `Bash=742;Read=9`。在同一對話的下一個請求之後傳送，來自主工作階段或子代理的一批工具呼叫 |

154| `x-claude-code-prompt-id` | 隨機 UUID，識別請求所服務的使用者提示。服務一個提示的請求共享該值，包括該提示啟動的子代理的回合。未歸屬於提示的請求會省略它。使用它按提示對工作階段的請求進行分組。需要 Claude Code v2.1.283 或更新版本 |154| `x-claude-code-prompt-id` | 隨機 UUID，識別請求所服務的使用者提示。服務一個提示的請求共享該值，包括該提示啟動的子代理的回合。未歸屬於提示的請求會省略它。使用它按提示對工作階段的請求進行分組。需要 Claude Code v2.1.283 或更新版本 |

238* 當上游僅拒絕對話中途系統訊息上的 `cache_control` 標記時，Claude Code 會保留系統訊息，並在移動標記後重試一次。在該次重試以及 Claude Code 退出之前的後續請求中，標記會放在 `messages` 中最後一個不是系統訊息的項目上238* 當上游僅拒絕對話中途系統訊息上的 `cache_control` 標記時，Claude Code 會保留系統訊息，並在移動標記後重試一次。在該次重試以及 Claude Code 退出之前的後續請求中，標記會放在 `messages` 中最後一個不是系統訊息的項目上

239* 當上游拒絕[思考簽名](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)時，包括以 `400` 拒絕其中區塊 `bound to a different conversation` 時，Claude Code 會從請求中移除較早的思考區塊、重試，並將它們排除在每個後續請求之外。新回應仍包含思考239* 當上游拒絕[思考簽名](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)時，包括以 `400` 拒絕其中區塊 `bound to a different conversation` 時，Claude Code 會從請求中移除較早的思考區塊、重試，並將它們排除在每個後續請求之外。新回應仍包含思考

240* 當 gateway 或其上游將[顧問工具](https://code.claude.com/docs/zh-TW/advisor.md)項目在 `tools` 中拒絕為無法識別的工具類型時，Claude Code 會重試一次請求，不包含該項目及其 `anthropic-beta` 值。對該基礎 URL 的後續請求會將顧問排除在外，直到 Claude Code 退出，且 `/advisor` 對開發人員在該時間內不可用。Claude Code 通過 `400` 或 `422` 回應識別此拒絕，其訊息在 `Input tag` 後命名工具類型，例如 `Input tag 'advisor_20260301'`。在 v2.1.280 之前，Claude Code 沒有重試此拒絕240* 當 gateway 或其上游將[顧問工具](https://code.claude.com/docs/zh-TW/advisor.md)項目在 `tools` 中拒絕為無法識別的工具類型時，Claude Code 會重試一次請求，不包含該項目及其 `anthropic-beta` 值。對該基礎 URL 的後續請求會將顧問排除在外，直到 Claude Code 退出，且 `/advisor` 對開發人員在該時間內不可用。Claude Code 通過 `400` 或 `422` 回應識別此拒絕，其訊息在 `Input tag` 後命名工具類型，例如 `Input tag 'advisor_20260301'`。在 v2.1.280 之前，Claude Code 沒有重試此拒絕

241* 當上游拒絕 `output_config.effort` 時，Claude Code 會在不包含努力的情況下重試請求，並在 Claude Code 退出之前，對該模型的後續請求中將其排除。Claude Code 通過 `400` 識別此拒絕，其訊息同時命名 `output_config.effort` 和 `Extra inputs are not permitted`，或指出該模型不支援努力參數241* 當上游拒絕 `output_config.effort` 或其 `anthropic-beta` 值時，Claude Code 會重試，並在 Claude Code 退出之前，不再於對該模型的請求中加入兩者。若您的閘道不經修改地轉發上游的 `400`，且其訊息符合以下任一情況，則閘道無需任何變更：

242 * 同時命名 `output_config.effort` 和 `Extra inputs are not permitted`

243 * 指出該模型不支援努力參數

244 * 以 `Unexpected value(s)` 開頭，並針對 `anthropic-beta` 標頭列出 `effort-2025-11-24`。需要 v2.1.310 或更新版本。若開發人員的 [`ANTHROPIC_BETAS`](https://code.claude.com/docs/zh-TW/env-vars) 列出該值，他們會持續發送該值並收到 `400`，因此請讓他們移除該項目

242* 當上游拒絕 `context_management` 欄位或其 `anthropic-beta` 值時，閘道會再收到一次不含它們的請求。如果閘道在後續請求中再次看到它們且上游再次拒絕，則會進行相同的重試。Claude Code 透過其訊息識別此拒絕，例如包含 `context_management: Extra inputs are not permitted` 的訊息。在 v2.1.304 之前，Claude Code 沒有重試此拒絕245* 當上游拒絕 `context_management` 欄位或其 `anthropic-beta` 值時，閘道會再收到一次不含它們的請求。如果閘道在後續請求中再次看到它們且上游再次拒絕，則會進行相同的重試。Claude Code 透過其訊息識別此拒絕，例如包含 `context_management: Extra inputs are not permitted` 的訊息。在 v2.1.304 之前，Claude Code 沒有重試此拒絕

243* 當上游拒絕 `defer_loading` 以外的測試版工具欄位（例如 `strict`）時，`400` 會到達開發人員。在此之前，閘道可能會再次收到[不含工具搜尋欄位](#retry-without-tool-search)的請求。若要停止發送這類欄位，請讓開發人員設定 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](#disable-pre-release-capabilities)246* 當上游拒絕 `defer_loading` 以外的測試版工具欄位（例如 `strict`）時，`400` 會到達開發人員。在此之前，閘道可能會再次收到[不含工具搜尋欄位](#retry-without-tool-search)的請求。若要停止發送這類欄位，請讓開發人員設定 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](#disable-pre-release-capabilities)

244 247

monitoring-usage.md +2 −2

Details

470如果名稱沒有到達，請檢查是否為以下原因之一：470如果名稱沒有到達，請檢查是否為以下原因之一：

471 471

472* **您在執行 Desktop 的電腦上設定了它**：Desktop 不會將您在該處設定的值傳遞給 SSH 工作階段472* **您在執行 Desktop 的電腦上設定了它**：Desktop 不會將您在該處設定的值傳遞給 SSH 工作階段

473* **您在登入檔案中匯出了它**：只有登入 shell 會讀取 `/etc/profile` 之類的檔案。您在該處 `export` 的值會傳達到從登入 shell 啟動的 Claude Code。它不會傳達到 Desktop SSH 工作階段，因為 Desktop 不會透過登入 shell 啟動 Claude Code。473* **您在 `/etc/profile` 或其他只有登入 shell 會讀取的檔案中匯出了它**：當您從登入 shell 執行 `claude` 時名稱會到達，但在 Desktop SSH 工作階段中不會。Desktop 不會透過登入 shell 啟動 Claude Code。請改為在遠端機器上的[受管設定檔](https://code.claude.com/docs/zh-TW/desktop.md#managed-settings)中，於 `env` 下設定此變數。

474* **值中含有空格**：此時 Claude Code 不會將任何鍵複製到事件或資料點上，也不會回報錯誤。[移除值中的空格](#multi-team-organization-support)。474* **值中含有空格**：此時 Claude Code 不會將任何鍵複製到事件或資料點上，也不會回報錯誤。[移除值中的空格](#multi-team-organization-support)。

475* **其他項目已設定此變數**：在桌面應用程式啟動的工作階段中，啟動環境中已設定的變數[優先於設定檔](https://code.claude.com/docs/zh-TW/settings-reference.md#how-env-values-interact-with-your-shell)。[除錯日誌](https://code.claude.com/docs/zh-TW/debug-your-config.md)會列出每個被忽略的變數。當第三方 Desktop 部署在其提供的環境中[指定 OTLP 端點](#how-managed-settings-lock-the-otlp-destination)時，該環境會攜帶 Desktop 自己的 `OTEL_RESOURCE_ATTRIBUTES`。475* **其他項目已設定此變數**：在桌面應用程式啟動的工作階段中，啟動環境中已設定的變數[優先於設定檔](https://code.claude.com/docs/zh-TW/settings-reference.md#how-env-values-interact-with-your-shell)。[除錯日誌](https://code.claude.com/docs/zh-TW/debug-your-config.md)會列出每個被忽略的變數。當第三方 Desktop 部署在其提供的環境中[指定 OTLP 端點](#how-managed-settings-lock-the-otlp-destination)時，該環境會攜帶 Desktop 自己的 `OTEL_RESOURCE_ATTRIBUTES`。

476 476

1403* `pre_tokens`：壓縮前的約略 token 數量1403* `pre_tokens`：壓縮前的約略 token 數量

1404* `post_tokens`：壓縮後的約略 token 數量1404* `post_tokens`：壓縮後的約略 token 數量

1405* `error`：壓縮失敗時的錯誤訊息1405* `error`：壓縮失敗時的錯誤訊息

1406* `precompute_reuse`：僅在 `trigger` 為 `"manual"` 時，或針對[閒置壓縮](https://code.claude.com/docs/zh-TW/settings-reference.md#idlecompaction)（其 `trigger` 回報為 `"auto"`）設定。自動壓縮可在上下文視窗填滿之前於背景準備摘要，而此屬性記錄該次壓縮是否重複使用了預先準備的摘要。`"hit"` 表示已重複使用；`"miss_custom_instructions"`、`"miss_hook"` 與 `"miss_not_ready"` 則說明改為重新計算摘要的原因1406* `precompute_reuse`：僅在 `trigger` 為 `"manual"`，或在互動式終端機工作階段中針對[閒置壓縮](https://code.claude.com/docs/zh-TW/settings-reference.md#idlecompaction)且 `trigger` 為 `"auto"` 時設定。自動壓縮可以在上下文視窗填滿之前於背景準備摘要，此屬性記錄壓縮是否重複使用了該預先準備的摘要。`"hit"` 表示已重複使用；`"miss_custom_instructions"`、`"miss_hook"` 與 `"miss_not_ready"` 則說明改為計算新摘要的原因

1407 1407

1408#### Subagent 完成事件1408#### Subagent 完成事件

1409 1409

permission-modes.md +1 −1

Details

248 248

249**Web and mobile**249**Web and mobile**

250 250

251在 [claude.ai/code](https://claude.ai/code) 上，使用提示詞輸入框旁邊的模式下拉式選單。在行動應用程式中，點選提示詞輸入框中的 **+** 按鈕，然後點選 **Permission**。雲端工作階段和 Remote Control 工作階段提供不同的權限模式：251在 [claude.ai/code](https://claude.ai/code) 上，使用提示詞輸入框下方那一列中的模式下拉式選單。在行動應用程式中，點選提示詞輸入框中的 **+** 按鈕，然後點選 **Permission**。雲端工作階段和 Remote Control 工作階段提供不同的權限模式：

252 252

253* **[Cloud sessions](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md)**：接受編輯、Plan 和 Auto。接受編輯對應於 `default` 模式：雲端工作階段預先核准檔案編輯，無論模式為何，因此下拉式選單會顯示接受編輯而不是 Manual。雲端工作階段仍然遵守設定中的 `defaultMode: "acceptEdits"`。Auto 模式僅在您的組織允許且選定的模型支援時出現。Bypass permissions 不可用。253* **[Cloud sessions](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md)**：接受編輯、Plan 和 Auto。接受編輯對應於 `default` 模式：雲端工作階段預先核准檔案編輯，無論模式為何，因此下拉式選單會顯示接受編輯而不是 Manual。雲端工作階段仍然遵守設定中的 `defaultMode: "acceptEdits"`。Auto 模式僅在您的組織允許且選定的模型支援時出現。Bypass permissions 不可用。

254* **[Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md) sessions** 在您的本機機器上：Manual、接受編輯、Plan 和 Auto（適用於您自己啟動的工作階段），您無法從應用程式選擇 Bypass permissions。若要使用 Auto，工作階段必須符合自動模式的[可用性要求](#eliminate-prompts-with-auto-mode)。如需在您的電腦上執行的專案執行緒，請參閱[在您自己的電腦上執行執行緒](https://code.claude.com/docs/zh-TW/claude-projects.md#run-a-thread-on-your-own-computer)。254* **[Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md) sessions** 在您的本機機器上：Manual、接受編輯、Plan 和 Auto（適用於您自己啟動的工作階段），您無法從應用程式選擇 Bypass permissions。若要使用 Auto，工作階段必須符合自動模式的[可用性要求](#eliminate-prompts-with-auto-mode)。如需在您的電腦上執行的專案執行緒，請參閱[在您自己的電腦上執行執行緒](https://code.claude.com/docs/zh-TW/claude-projects.md#run-a-thread-on-your-own-computer)。

permissions.md +1 −1

Details

79| `acceptEdits` | 自動接受工作目錄或 `additionalDirectories` 中路徑的檔案編輯和常見檔案系統命令，例如 `mkdir`、`touch`、`mv` 和 `cp` |79| `acceptEdits` | 自動接受工作目錄或 `additionalDirectories` 中路徑的檔案編輯和常見檔案系統命令，例如 `mkdir`、`touch`、`mv` 和 `cp` |

80| `plan` | Claude 讀取檔案並執行唯讀 shell 命令以探索，但不編輯您的原始檔案；在 [auto mode](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode) 可用的情況下，分類器批准的命令也會執行。在 CLI 和 VS Code 擴充功能中標示為 Plan |80| `plan` | Claude 讀取檔案並執行唯讀 shell 命令以探索，但不編輯您的原始檔案；在 [auto mode](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode) 可用的情況下，分類器批准的命令也會執行。在 CLI 和 VS Code 擴充功能中標示為 Plan |

81| `auto` | 在沒有例行提示的情況下執行；在 shell 命令和網路要求等操作執行之前，背景 [classifier](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode) 會檢查它們是否符合您的要求 |81| `auto` | 在沒有例行提示的情況下執行；在 shell 命令和網路要求等操作執行之前，背景 [classifier](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode) 會檢查它們是否符合您的要求 |

82| `dontAsk` | 自動拒絕每個原本會提示的呼叫，但您安裝的 [mod](https://code.claude.com/docs/zh-TW/plugins/mods/overview.md) 仍可核准其中部分呼叫。工作目錄中的檔案讀取和其他不需要核准的操作仍會執行，透過 `/permissions` 或 `permissions.allow` 規則預先核准的工具也會執行。`AskUserQuestion`、標示為 [`requiresUserInteraction`](https://code.claude.com/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具、[來自網路路徑的讀取](#network-paths)，以及連接器工具 [您的組織設定為 `ask`](https://code.claude.com/docs/zh-TW/mcp#organization-controls-on-connector-tools) 在工作階段中（該設定到達 Claude Code 的地方）即使您已允許它們也會被拒絕 |82| `dontAsk` | 自動拒絕每個原本會提示的呼叫，但您安裝的 [mod](https://code.claude.com/docs/zh-TW/plugins/mods/overview.md) 仍可核准其中部分呼叫。工作目錄中的檔案讀取和其他不需要核准的操作仍會執行，透過 `/permissions` 或 `permissions.allow` 規則預先核准的工具也會執行。`AskUserQuestion`、標示為 [`requiresUserInteraction`](https://code.claude.com/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具、[來自網路路徑的讀取](#network-paths)，以及在該設定到達 Claude Code 的工作階段中[您的組織設定為 `ask`](https://code.claude.com/docs/zh-TW/mcp#organization-controls-on-connector-tools) 的連接器工具，即使您已允許它們也會被拒絕 |

83| `bypassPermissions` | 跳過權限提示，但[任何模式都不會自動核准的動作](https://code.claude.com/docs/zh-TW/permission-modes.md#actions-no-mode-auto-approves)除外 |83| `bypassPermissions` | 跳過權限提示，但[任何模式都不會自動核准的動作](https://code.claude.com/docs/zh-TW/permission-modes.md#actions-no-mode-auto-approves)除外 |

84 84

85> [!WARNING]85> [!WARNING]

plugins/components.md +3 −2

Details

584 584

585監視器的命令在其啟動位置和可以參考的內容方面受到限制：585監視器的命令在其啟動位置和可以參考的內容方面受到限制：

586 586

587* **僅互動式工作階段**：外掛程式監視器在互動式工作階段中啟動，從不在使用 `-p` 旗標的非互動模式中。在 API 提供者或遙測設定使 [Monitor 工具](https://code.claude.com/docs/zh-TW/tools-reference.md#monitor-tool) 無法使用的工作階段中，它們也不會啟動587* **互動式工作階段**：外掛程式監視器不會在使用 `-p` 旗標的非互動模式中啟動

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

588* **無使用者設定**：`command` 從環境中獲取 [路徑變數](#path-variables-and-persistent-data) 和 `${ENV_VAR}`，但從不獲取 `${user_config.*}`。參考一個的監視器不啟動，監視器程序也不接收 `CLAUDE_PLUGIN_OPTION_<KEY>`589* **無使用者設定**：`command` 從環境中獲取 [路徑變數](#path-variables-and-persistent-data) 和 `${ENV_VAR}`，但從不獲取 `${user_config.*}`。參考一個的監視器不啟動，監視器程序也不接收 `CLAUDE_PLUGIN_OPTION_<KEY>`

589* **中途停用**：如果您在工作階段中途停用外掛程式，Claude Code 不會停止已執行的監視器。它們在工作階段結束時停止590* **中途停用**：如果您在工作階段中途停用外掛程式，Claude Code 不會停止已執行的監視器。它們在工作階段結束時停止

590 591

647 648

648在資料目錄路徑中，`<id>` 是外掛程式識別碼，每個字元除了字母、數字、`_` 和 `-` 外都被 `-` 取代，因此 `my-plugin@my-marketplace` 變成 `my-plugin-my-marketplace`。649在資料目錄路徑中，`<id>` 是外掛程式識別碼，每個字元除了字母、數字、`_` 和 `-` 外都被 `-` 取代，因此 `my-plugin@my-marketplace` 變成 `my-plugin-my-marketplace`。

649 650

650在 Windows 上，替換的路徑使用正斜杠，因此 shell 不會將反斜杠讀取為逸出。651在 Windows 上，大多數替換的路徑使用正斜線，例如 `C:/Users/you/...`。在 [exec 形式 hook](https://code.claude.com/docs/zh-TW/hooks.md#exec-form-and-shell-form) 以及透過 PowerShell 執行的 hook 中，它們會保留原生的反斜線；當未安裝 Git Bash 時，PowerShell 是 Windows 上的預設 shell。

651 652

652### 將相依性安裝到資料目錄653### 將相依性安裝到資料目錄

653 654

plugins/create-marketplace.md +13 −0

Details

148 148

149當兩個名稱不同且有人按清單名稱安裝時，Claude Code 報告 `Plugin "<manifest-name>" not found in marketplace "<marketplace>"`。保持兩個名稱相同。有關 Claude Code 如何使用這兩個名稱的更多資訊，請參閱 [Plugin 載入參考](https://code.claude.com/docs/zh-TW/plugins/loading.md#find-where-a-plugin-came-from)。149當兩個名稱不同且有人按清單名稱安裝時，Claude Code 報告 `Plugin "<manifest-name>" not found in marketplace "<marketplace>"`。保持兩個名稱相同。有關 Claude Code 如何使用這兩個名稱的更多資訊，請參閱 [Plugin 載入參考](https://code.claude.com/docs/zh-TW/plugins/loading.md#find-where-a-plugin-came-from)。

150 150

151### 將未使用的子模組排除在複製之外

152

153當有人新增您的 marketplace 時，Claude Code 會複製儲存庫，並且只擷取包含 plugin 檔案的 git 子模組。需要 Claude Code v2.1.295 或更新版本。

154

155您可以透過放置每個 plugin 的位置，來決定 Claude Code 要擷取哪些子模組：

156

157* **位於子目錄中的 plugin**：Claude Code 會擷取 plugin 目錄內的子模組，以及包含該 plugin 的子模組。請將 plugin 需要的子模組放在 plugin 的目錄內，並將不需要的子模組放在目錄外

158* **位於 marketplace 根目錄的 plugin**：只要 plugin 的任一檔案參照了任何子模組內的路徑，Claude Code 就會擷取儲存庫中的所有子模組。如果您的儲存庫有一個只供建置使用的大型子模組，請將 plugin 移至子目錄中

159

160如果位於根目錄的 plugin 會執行子模組中的檔案，請在 plugin 的 hook 或伺服器設定中明確寫出該檔案的路徑，例如 `${CLAUDE_PLUGIN_ROOT}/vendor/tool/run.sh`。Claude Code 會讀取這些路徑，以判斷 plugin 是否需要這些子模組。它無法看到腳本在執行時才組合出的路徑。

161

162如需完整規則，請參閱 [marketplace 儲存庫中的 Git 子模組](https://code.claude.com/docs/zh-TW/plugins/marketplace-reference.md#git-submodules-in-the-marketplace-repository)。

163

151## 選擇 plugin 來源164## 選擇 plugin 來源

152 165

153`marketplace.json` 中的每個 plugin 項目都有一個 `source`，告訴 Claude Code 從何處取得該 plugin。根據 plugin 檔案的儲存位置選擇來源。該表列出了大多數 marketplace 擁有者使用的來源。166`marketplace.json` 中的每個 plugin 項目都有一個 `source`，告訴 Claude Code 從何處取得該 plugin。根據 plugin 檔案的儲存位置選擇來源。該表列出了大多數 marketplace 擁有者使用的來源。

plugins/host-marketplace.md +1 −1

Details

111告訴使用者每個協定在其機器上需要什麼：111告訴使用者每個協定在其機器上需要什麼：

112 112

113* **SSH**：金鑰必須在沒有密碼提示的情況下工作，例如因為它已載入 `ssh-agent`。主機必須已在 `known_hosts` 中。113* **SSH**：金鑰必須在沒有密碼提示的情況下工作，例如因為它已載入 `ssh-agent`。主機必須已在 `known_hosts` 中。

114* **HTTPS**：Claude Code 保持使用者的 git 認證助手啟用，但禁止它提示。助手已儲存的認證有效；它必須要求的認證失敗。在 GitHub 上，`gh auth login` 後跟 `gh auth setup-git` 會儲存一個。114* **HTTPS**：Claude Code 會保留使用者的 git 憑證輔助程式，但禁止其提示，且不會執行 askpass 程式，例如透過 `GIT_ASKPASS` 設定的程式。輔助程式已儲存的憑證可以使用；需要向使用者詢問的憑證則會失敗。在 GitHub 上，執行 `gh auth login` 後再執行 `gh auth setup-git` 即可儲存憑證。

115 115

116對於 GitHub Enterprise Server 主機，使用者需要從其機器存取該主機的 git 存取。請參閱 [Plugin marketplaces on GHES](https://code.claude.com/docs/zh-TW/github-enterprise-server.md#plugin-marketplaces-on-ghes) 以了解每個 Claude Code 表面需要什麼來到達 GHES 託管的 marketplace。116對於 GitHub Enterprise Server 主機，使用者需要從其機器存取該主機的 git 存取。請參閱 [Plugin marketplaces on GHES](https://code.claude.com/docs/zh-TW/github-enterprise-server.md#plugin-marketplaces-on-ghes) 以了解每個 Claude Code 表面需要什麼來到達 GHES 託管的 marketplace。

117 117

plugins/install.md +1 −1

Details

238 238

239私人市集是您需要認證才能複製的儲存庫中的市集，在 GitHub 或任何其他 git 主機上。您使用與公開市集相同的 `/plugin marketplace add` 或 `claude plugin marketplace add` 命令新增它。Claude Code 使用機器上已有的 git 認證複製它，永遠不會提示，因此每種連接方式都有要求：239私人市集是您需要認證才能複製的儲存庫中的市集，在 GitHub 或任何其他 git 主機上。您使用與公開市集相同的 `/plugin marketplace add` 或 `claude plugin marketplace add` 命令新增它。Claude Code 使用機器上已有的 git 認證複製它，永遠不會提示，因此每種連接方式都有要求：

240 240

241* **HTTPS**：您的 git 認證助手適用，因此您使用 `gh auth login`、macOS Keychain 或 `git-credential-store` 設定的存取有效。互動式提示被抑制，因此您從未驗證過的主機會失敗而不是要求密碼。241* **HTTPS**：您的 git 憑證助手適用，因此您使用 `gh auth login`、macOS Keychain 或 `git-credential-store` 設定的存取有效。Git 的提示和 askpass 程式均已停用，包括在 `GIT_ASKPASS` 中設定的程式，因此當 git 必須要求憑證時，複製會失敗而不是提示。

242* **SSH**：主機必須已在您的 `known_hosts` 檔案中，金鑰必須在沒有密碼提示的情況下工作。如果您的 git 設定在 `GIT_SSH_COMMAND`、`GIT_SSH` 或您的 git 設定的 `core.sshCommand` 中命名 SSH 程式，Claude Code 會執行該程式。242* **SSH**：主機必須已在您的 `known_hosts` 檔案中，金鑰必須在沒有密碼提示的情況下工作。如果您的 git 設定在 `GIT_SSH_COMMAND`、`GIT_SSH` 或您的 git 設定的 `core.sshCommand` 中命名 SSH 程式，Claude Code 會執行該程式。

243* **GitHub `owner/repo` shorthand**：Claude Code 檢查您的 SSH 金鑰是否驗證到 `github.com`，如果驗證則透過 SSH 複製，如果不驗證則透過 HTTPS 複製。設定 [`CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`](https://code.claude.com/docs/zh-TW/env-vars#variables) 以跳過該檢查並始終透過 HTTPS 複製。243* **GitHub `owner/repo` shorthand**：Claude Code 檢查您的 SSH 金鑰是否驗證到 `github.com`，如果驗證則透過 SSH 複製，如果不驗證則透過 HTTPS 複製。設定 [`CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`](https://code.claude.com/docs/zh-TW/env-vars#variables) 以跳過該檢查並始終透過 HTTPS 複製。

244 244

plugins/loading.md +1 −1

Details

41* **設定宣告但 `known_marketplaces.json` 缺少的市場**：Claude Code 複製它，然後重新載入 plugins 並下載尚未快取的已啟用 plugins41* **設定宣告但 `known_marketplaces.json` 缺少的市場**：Claude Code 複製它，然後重新載入 plugins 並下載尚未快取的已啟用 plugins

42* **宣告的市場其來源在設定中已變更**：Claude Code 從新來源重新提取它並顯示 `Plugins changed. Run /reload-plugins to activate.`42* **宣告的市場其來源在設定中已變更**：Claude Code 從新來源重新提取它並顯示 `Plugins changed. Run /reload-plugins to activate.`

43 43

44未被任何路徑提取且沒有可用快取目錄的已啟用 plugin 在 `/plugin` **Errors** 標籤中顯示 `Plugin "<name>" not cached at <path>`，`claude plugin list` 在同一行新增 `— run /plugin to refresh`。如需修復，請參閱 [`Plugin "<name>" not cached at <path>`](https://code.claude.com/docs/zh-TW/plugins/troubleshooting#plugin-not-cached-at)。44未被任何路徑提取且沒有可用快取目錄的已啟用 plugin 會在 `/plugin` **Errors** 標籤中顯示 `Plugin "<name>" not cached at <path>`。如需修復，請參閱 [`Plugin "<name>" not cached at <path>`](https://code.claude.com/docs/zh-TW/plugins/troubleshooting#plugin-not-cached-at)。

45 45

46## 找出 plugin 來自何處46## 找出 plugin 來自何處

47 47

plugins/manifest-reference.md +2 −2

Details

155| `workflows` | Path, or array of paths | [Workflow](https://code.claude.com/docs/zh-TW/workflows.md#distribute-a-workflow-in-a-plugin) `.js` 檔案或目錄。取代預設 `workflows/` 掃描 |155| `workflows` | Path, or array of paths | [Workflow](https://code.claude.com/docs/zh-TW/workflows.md#distribute-a-workflow-in-a-plugin) `.js` 檔案或目錄。取代預設 `workflows/` 掃描 |

158| [`experimental.monitors`](#monitors) | Path, or inline array | 保存 monitors 陣列的 `.json` 檔案，或陣列本身。預設為 `monitors/monitors.json`。頂層 `monitors` 鍵仍會載入，並帶有 `claude plugin validate` 警告。Monitors 僅在互動式工作階段中執行，不在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上執行 |158| [`experimental.monitors`](#monitors) | Path, or inline array | 保存 monitors 陣列的 `.json` 檔案，或陣列本身。預設為 `monitors/monitors.json`。頂層 `monitors` 鍵仍會載入，並帶有 `claude plugin validate` 警告。Monitors [在使用 `-p` 旗標時不會啟動](https://code.claude.com/docs/zh-TW/plugins/components#monitors) |

159| `experimental.evals` | Path, or array of paths | 當它不是預設 `evals/` 時，保存 plugin 的 [eval 案例](https://code.claude.com/docs/zh-TW/plugin-evals.md#use-a-different-eval-directory)的目錄。`claude plugin eval --eval-dir` 覆蓋它 |159| `experimental.evals` | Path, or array of paths | 當它不是預設 `evals/` 時，保存 plugin 的 [eval 案例](https://code.claude.com/docs/zh-TW/plugin-evals.md#use-a-different-eval-directory)的目錄。`claude plugin eval --eval-dir` 覆蓋它 |

160 160

161在「類型」欄中，路徑是相對於 plugin 根目錄的字串，例如 `"./custom/commands"`。161在「類型」欄中，路徑是相對於 plugin 根目錄的字串，例如 `"./custom/commands"`。

606}606}

607```607```

608 608

609在 Windows 上，替換的路徑使用正斜杠，因此 shell 不會將反斜杠讀取為逃逸。609在 Windows 上，大多數替換的路徑使用正斜線，例如 `C:/Users/you/...`。在 [exec 形式 hook](https://code.claude.com/docs/zh-TW/hooks.md#exec-form-and-shell-form) 中，以及透過 PowerShell 執行的 hook 中，這些路徑會保留原生的反斜線；當未安裝 Git Bash 時，PowerShell 是 Windows 上的預設 shell。

610 610

611## 標準配置611## 標準配置

612 612

plugins/marketplace-reference.md +30 −0

Details

172* **`url`**：Claude Code 僅取得 `marketplace.json`，因此相對路徑無法解析。為每個 plugin 提供物件來源，例如 `github` 或 `git-subdir`。172* **`url`**：Claude Code 僅取得 `marketplace.json`，因此相對路徑無法解析。為每個 plugin 提供物件來源，例如 `github` 或 `git-subdir`。

173* **`settings`**：相對路徑被直接拒絕。173* **`settings`**：相對路徑被直接拒絕。

174 174

175#### marketplace 儲存庫中的 Git 子模組

176

177當 Claude Code 複製 marketplace 儲存庫時，只會取得存放 plugin 檔案的 git 子模組。需要 Claude Code v2.1.295 或更新版本。

178

179較早的版本會取得所有子模組，包括巢狀子模組。如果儲存庫有大型子模組，Claude Code 在取得時可能會超過[複製逾時](https://code.claude.com/docs/zh-TW/plugins/troubleshooting.md#git-clone-timed-out-after-120s)。

180

181對於子目錄中的 plugin，例如 `./plugins/formatter`，Claude Code 會在以下情況取得子模組：

182

183* **plugin 位於子模組內**：子模組是 plugin 的目錄或其上層目錄

184* **子模組位於 plugin 內**：子模組位於 plugin 目錄下的任何位置

185* **符號連結指向子模組內**：提交至儲存庫的連結，其目標位於子模組中

186

187位於 marketplace 根目錄的 plugin（使用 `"source": "./"`）會取得儲存庫中的所有子模組，或完全不取得。當以下任一項指向任何子模組內時，Claude Code 會取得所有子模組：

188

189* **元件目錄**：根目錄下存放 plugin 元件的目錄，例如 `skills/`、`hooks/` 或 `bin/`

190* **plugin 設定中的路徑**：plugin 的 marketplace 項目、其 `plugin.json`，或 `.mcp.json`、`hooks/hooks.json` 等設定檔中的路徑

191* **符號連結**：提交至儲存庫的連結

192* **plugin 檔案中的文字**：寫在設定檔或元件目錄下檔案中的子模組路徑，例如 `vendor/tool`

193

194當以上皆不符合時，Claude Code 不會為該 plugin 取得任何子模組。同時是專案又是 plugin 的儲存庫，通常有僅供專案建置使用的子模組，此規則會將其排除。

195

196在無法判斷哪些子模組存放 plugin 檔案的情況下，Claude Code 也會取得所有子模組，例如：

197

198* **根目錄下的 `SKILL.md`**：此時整個儲存庫就是一個 skill 的目錄

199* **Claude Code 無法讀取的檔案**：marketplace 檔案、plugin 的某個設定檔，或 `.gitmodules`

200

201如果您使用 `--sparse` 新增 marketplace，或其來源設定了 `sparsePaths`，Claude Code 只會檢出其中指定的目錄，且不取得任何子模組。較早的版本也是如此。

202

203若要讓 plugin 未使用的子模組不納入複製，請參閱[將未使用的子模組排除在複製之外](https://code.claude.com/docs/zh-TW/plugins/create-marketplace.md#keep-unused-submodules-out-of-the-clone)。

204

175#### pluginRoot 下的裸名205#### pluginRoot 下的裸名

176 206

177裸名是單個目錄名稱，不含 `/`，例如 `"formatter"`。若要寫入裸名而非 `./` 路徑，請將 [`metadata.pluginRoot`](#top-level-fields) 設定為它們解析的目錄。使用 `"pluginRoot": "./plugins"`，`"source": "formatter"` 解析為 `./plugins/formatter`。需要 Claude Code v2.1.239 或更新版本。207裸名是單個目錄名稱，不含 `/`，例如 `"formatter"`。若要寫入裸名而非 `./` 路徑，請將 [`metadata.pluginRoot`](#top-level-fields) 設定為它們解析的目錄。使用 `"pluginRoot": "./plugins"`，`"source": "formatter"` 解析為 `./plugins/formatter`。需要 Claude Code v2.1.239 或更新版本。

plugins/mods/api.md +50 −4

Details

313 313

314#### 被拒絕的呼叫會傳回什麼314#### 被拒絕的呼叫會傳回什麼

315 315

316在結果中，`<reason>` 代表 `the session was stopped and nobody has sent input since`：316在結果中，`<reason>` 代表呼叫被拒絕的原因。在中斷之後，該原因為 `the session was stopped and nobody has sent input since`。關於其他原因，請參閱[在 `claude -p` 執行與 Agent SDK 工作階段中被拒絕的呼叫](#calls-refused-in-non-interactive-runs)。

317 317

318| 部分被拒絕的呼叫 | 直到使用者下一次輸入前的結果 |318| 部分被拒絕的呼叫 | 結果 |

319| :- | :- |319| :- | :- |

320| `$.prompt.submit` | 以 `{ drop: '<reason>' }` 解析，且不會將任何提示詞排入佇列 |320| `$.prompt.submit` | 以 `{ drop: '<reason>' }` 解析，且不會將任何提示詞排入佇列 |

324| 對 [agent team](https://code.claude.com/docs/zh-TW/agent-teams.md) 隊員使用 `$.session.send` | 以 `{ isDelivered: false, reason: 'Teammate "<name>" was not messaged: <reason>.' }` 解析，其中 `<name>` 是隊員的名稱 |324| 對 [agent team](https://code.claude.com/docs/zh-TW/agent-teams.md) 隊員使用 `$.session.send` | 以 `{ isDelivered: false, reason: 'Teammate "<name>" was not messaged: <reason>.' }` 解析，其中 `<name>` 是隊員的名稱 |

325| 以 [`$.tool.call`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#mods-api-methods) 呼叫帶有 `run_in_background: true` 的 Bash、Monitor 或 CronCreate | 以 `{ deny: '<tool> was not run: it starts background work, a schedule or a goal, and <reason>' }` 解析，其中 `<tool>` 是工具的名稱 |325| 以 [`$.tool.call`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#mods-api-methods) 呼叫帶有 `run_in_background: true` 的 Bash、Monitor 或 CronCreate | 以 `{ deny: '<tool> was not run: it starts background work, a schedule or a goal, and <reason>' }` 解析，其中 `<tool>` 是工具的名稱 |

326 326

327伴隨這些 `$.session.send` 和 `$.tool.call` 結果，使用者可能會看到 [`Stopped:` 快顯通知](https://code.claude.com/docs/zh-TW/plugins/mods/troubleshoot#stopped-type-a-message-to-continue)。327當其中某個 `$.session.send` 或 `$.tool.call` 呼叫在互動式工作階段中因中斷而被拒絕時，使用者可能會看到 [`Stopped:` 快顯通知](https://code.claude.com/docs/zh-TW/plugins/mods/troubleshoot#stopped-type-a-message-to-continue)。

328 328

329#### 您的 mod 在中斷前已啟動的工作329#### 您的 mod 在中斷前已啟動的工作

330 330

341 341

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

343 343

344### 在 `claude -p` 執行與 Agent SDK 工作階段中被拒絕的呼叫

345

346在 `claude -p` 執行或 [Agent SDK](https://code.claude.com/docs/zh-TW/agent-sdk/overview.md) 工作階段中，諸如 `{ drop: 'the run reached its --max-turns limit' }` 的結果表示該次執行拒絕了您的 mod 的呼叫。

347

348被拒絕的 `$.prompt.submit` 會以 `{ drop: '<reason>' }` 解析。其他被拒絕的呼叫，例如 `$.command.run` 和 `$.agent.spawn`，會產生[被拒絕的呼叫會傳回什麼](#what-refused-calls-return)中所示的結果，並以該原因取代 `<reason>`。請在下方找到您的 `<reason>`，了解該如何處理：

349

350* **`the run reached its --max-turns limit`**：來自您的 mod 的提示詞以及其產生之 subagent 的回合，都會計入 [`--max-turns`](https://code.claude.com/docs/zh-TW/cli-reference#cli-flags) 或 Agent SDK 的[回合限制](https://code.claude.com/docs/zh-TW/agent-sdk/configuration.md#limit-turns-and-spend)。若需要更多回合，請以更高的限制啟動該次執行。若無法這麼做，請讓您的 mod 停止進行被拒絕的呼叫。若該次執行接收到來自使用者或 SDK 應用程式的另一個提示詞，回合計數會重設，且該次執行會再次接受呼叫。

351* **`the run is past its --max-budget-usd limit`**：請以更高的 `--max-budget-usd` 啟動該次執行，或提高 Agent SDK 的[支出限制](https://code.claude.com/docs/zh-TW/agent-sdk/configuration.md#limit-turns-and-spend)。若無法這麼做，請讓您的 mod 停止進行被拒絕的呼叫。此限制適用於該次執行至今的總成本。當該次執行接收另一個提示詞時，總成本會持續累加，因此重試會傳回相同的原因。

352* **`the host has ended its input`**：例如，SDK 應用程式結束了其[串流輸入](https://code.claude.com/docs/zh-TW/agent-sdk/streaming-vs-single-mode.md)，或以 [`--input-format stream-json`](https://code.claude.com/docs/zh-TW/cli-reference#cli-flags) 啟動的執行中 stdin 已關閉。該次執行正在結束，不再接受任何輸入，因此重試會傳回相同的原因。請讓您的 mod 停止進行被拒絕的呼叫。若該次執行由您自己啟動，下次請保持該輸入開啟，直到您的 mod 不再需要進行任何呼叫為止。

353* **`the session was stopped and nobody has sent input since`**：該次執行已被[中斷](#calls-and-background-work-after-the-user-interrupts-a-turn)，例如透過 Agent SDK 的 [`interrupt()`](https://code.claude.com/docs/zh-TW/agent-sdk/typescript#query-object)。若要在使用者或 SDK 應用程式的下一則訊息之後再次進行呼叫，請依照[重試被拒絕或被捨棄的呼叫](#retry-a-refused-or-dropped-call)操作。

354

355### 載入您的 mod 的 `claude -p` 執行永遠不會結束

356

357若您的 mod 在每個回合結束時都提交提示詞，每個提示詞都會啟動另一個回合。若沒有 [`--max-turns`](https://code.claude.com/docs/zh-TW/cli-reference#cli-flags) 或 `--max-budget-usd`，載入該 mod 的 `claude -p` 執行會持續進行，直到您自行停止為止。

358

359若要讓該次執行自行結束，請在您的 shell 中於命令加上其中任一旗標。若由其他人啟動該次執行，請讓您的 mod 在工作完成後停止提交提示詞。此命令加上了 `--max-turns`：

360

361```bash theme={null}

362claude -p "find the TODOs" --max-turns 5

363```

364

365一旦該次執行達到該限制，mod 的下一個提示詞會被[拒絕](#calls-refused-in-non-interactive-runs)而不會啟動回合，且該次執行會結束。

366

367若該次執行仍超過限制，請在您的 shell 中執行 `claude --version`，若您的版本早於 v2.1.304，請[更新 Claude Code](https://code.claude.com/docs/zh-TW/setup.md#update-claude-code)。從 v2.1.299 起，mod 的提示詞會在達到限制時被拒絕。若您的 mod 會產生 subagent，從 v2.1.304 起，它們的回合會計入 `--max-turns`。

368

344## 在工作階段之間傳送和接收訊息369## 在工作階段之間傳送和接收訊息

345 370

346mod 可以向您的另一個工作階段、此工作階段的某個 subagent，或其 [agent team](https://code.claude.com/docs/zh-TW/agent-teams.md) 中的隊員傳送純文字訊息。它也可以觀察到達和離開的訊息。371mod 可以向您的另一個工作階段、此工作階段的某個 subagent，或其 [agent team](https://code.claude.com/docs/zh-TW/agent-teams.md) 中的隊員傳送純文字訊息。它也可以觀察到達和離開的訊息。

390| `$.http` | `fetch(url, init)` 透過 `http` 或 `https`。它在讀取本文後解析為 `{ status, ok, headers, text }`。 |415| `$.http` | `fetch(url, init)` 透過 `http` 或 `https`。它在讀取本文後解析為 `{ status, ok, headers, text }`。 |

392| `$.env` | `get` 和 `set` 環境變數。將名稱寫為文字字串。 |417| `$.env` | `get` 和 `set` 環境變數。將名稱寫為文字字串。 |

393| `$.settings` | `read` 設定檔和受管原則保留的內容 |418| `$.settings` | `read()` 解析為所有設定，合併為一個物件。搭配 `{ source }` 或 `{ key }` 時，它改為解析為[單一來源的設定或單一設定鍵的值](#read-one-source-or-one-key)。 |

394| `$.session` | `messages()` 將逐字稿傳回為 `{ role, text, toolUses }` 的列表。也是工作目錄、模型等。[`usage()`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#mods-api-methods) 傳回上下文視窗使用和計畫限制。 |419| `$.session` | `messages()` 將逐字稿傳回為 `{ role, text, toolUses }` 的列表。也是工作目錄、模型等。[`usage()`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#mods-api-methods) 傳回上下文視窗使用和計畫限制。 |

395| `$.mcp` | `call` 連接的 MCP 伺服器上的工具 |420| `$.mcp` | `call` 連接的 MCP 伺服器上的工具 |

396 421

408* **`$.process.spawn started, and a plugin withheld its result:`**：拒絕的 mod 尚未將命令的輸出讀取到結尾。如果命令仍在執行，Claude Code 會將其停止。433* **`$.process.spawn started, and a plugin withheld its result:`**：拒絕的 mod 尚未將命令的輸出讀取到結尾。如果命令仍在執行，Claude Code 會將其停止。

409* **`$.process.spawn ran, and a plugin withheld its result:`**：拒絕的 mod 已將命令的輸出讀取到結尾，因此命令已經退出434* **`$.process.spawn ran, and a plugin withheld its result:`**：拒絕的 mod 已將命令的輸出讀取到結尾，因此命令已經退出

410 435

436### 讀取所有設定、單一來源或單一設定鍵

437

438`$.settings.read()` 解析為一個物件，其中包含所有使用中來源的設定，並依[優先順序](https://code.claude.com/docs/zh-TW/settings.md#settings-precedence)合併。傳入 `{ source }` 可改為讀取單一來源，傳入 `{ key }` 可讀取單一設定鍵，也可兩者都傳入：

439

440| 呼叫 | 解析為 |

441| :- | :- |

442| `$.settings.read()` | 合併後的設定，作為一個物件。其頂層鍵與 `settings.json` 檔案的頂層鍵相同，例如 `permissions` 和 `hooks`。 |

443| `$.settings.read({ source: 'policy' })` | 該單一來源的設定，作為一個物件；當該來源不包含任何設定時則為 `{}` |

444| `$.settings.read({ key: 'spinnerTipsEnabled' })` | 該設定鍵在合併後設定中的值；當該設定鍵未設定時則為 `undefined` |

445| `$.settings.read({ key: 'spinnerTipsEnabled', source: 'user' })` | 該設定鍵在該單一來源中的值；當該來源未設定它時則為 `undefined` |

446

447對於 `source`，請傳入要讀取的單一設定來源名稱：

448

449* **`user`**：`~/.claude/settings.json`

450* **`project`**：`.claude/settings.json`

451* **`local`**：`.claude/settings.local.json`

452* **`flag`**：您透過 `--settings` 傳入的內容，以及 SDK 的內嵌設定

453* **`policy`**：[受管設定](https://code.claude.com/docs/zh-TW/managed-settings.md#how-claude-code-combines-managed-sources)

454

455對於 `key`，請傳入單一頂層鍵的確切名稱，而不是指向巢狀物件的點分路徑。`key` 引數需要 Claude Code v2.1.304 或更新版本。

456

411## 後續步驟457## 後續步驟

412 458

413* [對事件做出反應](https://code.claude.com/docs/zh-TW/plugins/mods/events.md)：hook 工具呼叫、提示和回合459* [對事件做出反應](https://code.claude.com/docs/zh-TW/plugins/mods/events.md)：hook 工具呼叫、提示和回合

plugins/mods/create.md +3 −1

Details

46 46

47**4. 試試 mod**47**4. 試試 mod**

48 48

49使用你要求的。對於範例提示，目前分支名稱出現在提示框上方。如果 mod 沒有做你想要的，告訴 Claude 要改變什麼。mod 在每個變更其檔案的轉向結束時重新載入，所以你可以在 Claude 完成後立即試試變更。49使用您所要求的功能。以範例提示詞而言，目前的分支名稱會出現在提示詞輸入框上方。如果 mod 沒有達到您想要的效果，請告訴 Claude 要修改什麼。mod 會在每個變更其檔案的回合結束時重新載入，因此您可以在 Claude 完成後立即試用變更。

51如果逐字稿中有一行以 mod 名稱開頭，並指出[變更未能載入](https://code.claude.com/docs/zh-TW/plugins/mods/troubleshoot.md#this-mods-change-didnt-load)，請在下一則訊息要求 Claude 修正時貼上該行。除非您貼上，否則 Claude 看不到該行。

50 52

51### 在其他工作階段中使用 mod53### 在其他工作階段中使用 mod

52 54

plugins/mods/events.md +73 −3

Details

93 93

94## 對 Claude 正在執行的動作設定 hook94## 對 Claude 正在執行的動作設定 hook

95 95

96處理這些事件，即可在工具呼叫、提示詞或回合發生時檢視或變更它們。如需所有事件以及 hook 可傳回的內容，請參閱[事件參考](https://code.claude.com/docs/zh-TW/plugins/mods/reference.md#events)。96處理這些事件，即可在工具呼叫、提示詞、回合或設定讀取發生時檢視或變更它們。如需所有事件以及 hook 可傳回的內容，請參閱[事件參考](https://code.claude.com/docs/zh-TW/plugins/mods/reference.md#events)。

97 97

98### 防護或變更工具呼叫98### 防護或變更工具呼叫

99 99

115 115

116當 Claude 嘗試執行 `git push --force` 時，命令不會執行，也不會出現權限提示，因為 hook 從未呼叫 `next`。Claude 會將 `deny` 文字當作工具的結果來讀取，因此請將其撰寫為 Claude 可據以行動的指令。其他所有 Bash 命令的執行方式都與沒有 mod 時相同。116當 Claude 嘗試執行 `git push --force` 時，命令不會執行，也不會出現權限提示，因為 hook 從未呼叫 `next`。Claude 會將 `deny` 文字當作工具的結果來讀取，因此請將其撰寫為 Claude 可據以行動的指令。其他所有 Bash 命令的執行方式都與沒有 mod 時相同。

117 117

118如果此 hook 擲出例外或逾時，Claude Code 會略過它，而命令會如同沒有 mod 時一樣繼續執行。若要改為拒絕該命令，請為此 hook [加入 `.catch` 處理常式](#handle-a-hook-that-fails)。

119

118若要在工具執行後採取動作，請 `await next(e)`、執行您的工作，然後傳回 `next` 給您的內容。此 hook 會使用 [`$.ui.log`](https://code.claude.com/docs/zh-TW/plugins/mods/api#show-something-without-starting-a-turn) 記錄 Claude 變更的每個 `.mdx` 檔案，該函式會在逐字稿中加入一行 Claude 不會讀取的淡色文字：120若要在工具執行後採取動作，請 `await next(e)`、執行您的工作，然後傳回 `next` 給您的內容。此 hook 會使用 [`$.ui.log`](https://code.claude.com/docs/zh-TW/plugins/mods/api#show-something-without-starting-a-turn) 記錄 Claude 變更的每個 `.mdx` 檔案，該函式會在逐字稿中加入一行 Claude 不會讀取的淡色文字：

119 121

120```javascript theme={null}122```javascript theme={null}

177* **使用者輸入答案**：`$.ui.ask` 會解析為輸入的文字。hook 會將其與 `Run it` 比較，因此任何其他文字都會拒絕該命令。179* **使用者輸入答案**：`$.ui.ask` 會解析為輸入的文字。hook 會將其與 `Run it` 比較，因此任何其他文字都會拒絕該命令。

178* **沒有人回答**：當使用者關閉問題或選擇 **Chat about this** 時，以及在 `claude -p` 執行中，`$.ui.ask` 會拒絕（reject），因此 `catch` 區塊會讓答案維持為 `Refuse`180* **沒有人回答**：當使用者關閉問題或選擇 **Chat about this** 時，以及在 `claude -p` 執行中，`$.ui.ask` 會拒絕（reject），因此 `catch` 區塊會讓答案維持為 `Refuse`

179 181

180請將等待保留在如 `$.ui.ask` 之類的 mods API 呼叫中，因為這段時間不會計入 hook 的[時間限制](https://code.claude.com/docs/zh-TW/plugins/mods/reference.md#limits)。等待您自己的 promise 所花費的時間則會計入。Claude Code 會略過逾時的 hook，因此被暫停的命令將會執行。182請將等待保留在如 `$.ui.ask` 之類的 mods API 呼叫中，因為這段時間不會計入 hook 的[時間限制](https://code.claude.com/docs/zh-TW/plugins/mods/reference.md#limits)。等待您自己的 promise 所花費的時間則會計入。

183

184Claude Code 會略過逾時的 hook，因此被暫停的命令將會執行。若要改為拒絕該命令，請在 `on` 傳回的註冊上串接[一個 `.catch` 處理常式](#handle-a-hook-that-fails)。該處理常式與 hook 內部的 `catch` 區塊是分開的。

181 185

182#### 在詢問使用者之前核准或拒絕工具呼叫186#### 在詢問使用者之前核准或拒絕工具呼叫

183 187

207 211

208* **在 `main` 上**：即使有規則允許 `git push`，hook 仍會傳回 `deny`212* **在 `main` 上**：即使有規則允許 `git push`，hook 仍會傳回 `deny`

209* **在其他分支上，以及對於其他命令**：該呼叫會得到與沒有 mod 時相同的決定213* **在其他分支上，以及對於其他命令**：該呼叫會得到與沒有 mod 時相同的決定

214* **hook 擲出例外或逾時**：該呼叫同樣會得到與沒有 mod 時相同的決定。若要改為拒絕該呼叫，請[加入一個 `.catch` 處理常式](#handle-a-hook-that-fails)，讓它傳回 `{ decision: 'deny', reason: 'the reason' }`。

210 215

211此 hook 比對的是命令的文字，因此請將其視為給 Claude 的提醒。若要對所有人封鎖推送至 `main`，請在您的 Git 主機上保護該分支。216此 hook 比對的是命令的文字，因此請將其視為給 Claude 的提醒。若要對所有人封鎖推送至 `main`，請在您的 Git 主機上保護該分支。

212 217

269 274

270當您送出如 `open a PR for this change` 之類的提示詞時，您的訊息在逐字稿中看起來不變，而 Claude 還會在其後讀到如 `Current branch: feature/auth` 之類的一行。未提及 pull request 的提示詞會原封不動地通過，且不會執行 `git`。275當您送出如 `open a PR for this change` 之類的提示詞時，您的訊息在逐字稿中看起來不變，而 Claude 還會在其後讀到如 `Current branch: feature/auth` 之類的一行。未提及 pull request 的提示詞會原封不動地通過，且不會執行 `git`。

271 276

272若要阻止提示詞，請在不呼叫 `next` 的情況下傳回 `{ drop: 'the reason' }`。文字會回到使用者的提示詞輸入欄中，而使用者會看到 `Prompt dropped by a hook:` 後接您的原因，因此請以使用者為對象撰寫原因。如果您的 hook 在其 `next(e)` 呼叫已讓提示詞通過之後才傳回 `drop`，回合仍會執行，且該 hook 會[失敗](#handle-a-hook-that-fails)，並顯示包含 `a drop after its next() was answered` 的訊息。277若要阻止提示詞，請在不呼叫 `next` 的情況下傳回 `{ drop: 'the reason' }`。文字會回到使用者的提示詞輸入欄中，而使用者會看到 `Prompt dropped by a hook:` 後接您的原因，因此請以使用者為對象撰寫原因。在以下情況中，提示詞仍會送出：

278

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 原本會阻止的提示詞。

273 281

274[其他事件](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 的文字。來自這些 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)。

275 283

305 313

306若要查看 API 在請求期間自行執行的工具呼叫，例如對 [advisor 工具](https://code.claude.com/docs/zh-TW/advisor.md)的呼叫，請讀取 `result.serverToolUses`。Claude Code 不會執行這些呼叫，因此不會針對它們觸發任何 `tool.call` 或 `tool.check` hook。當回應中沒有此類呼叫時，該欄位不會存在，且此欄位需要 Claude Code v2.1.290 或更新版本。314若要查看 API 在請求期間自行執行的工具呼叫，例如對 [advisor 工具](https://code.claude.com/docs/zh-TW/advisor.md)的呼叫，請讀取 `result.serverToolUses`。Claude Code 不會執行這些呼叫，因此不會針對它們觸發任何 `tool.call` 或 `tool.check` hook。當回應中沒有此類呼叫時，該欄位不會存在，且此欄位需要 Claude Code v2.1.290 或更新版本。

307 315

316### 變更或拒絕設定讀取

317

318`settings.read` hook 會在 mod 的讀取以及 Claude Code 本身的讀取時執行：

319

320* **mod 的讀取**：mod 呼叫 [`$.settings.read`](https://code.claude.com/docs/zh-TW/plugins/mods/api#read-one-source-or-one-key)。

321* **Claude Code 本身的讀取**：Claude Code 建立工作階段的合併設定。當設定或已載入的外掛變更時，此讀取會重複進行。

322

323在依賴任一讀取之前，請先檢查防護與您的版本：

324

325* **內建防護**：在有受管設定，或以 Team 或 Enterprise [`/login`](https://code.claude.com/docs/zh-TW/authentication#authentication-precedence) 作為工作階段的憑證時，[內建防護](https://code.claude.com/docs/zh-TW/plugins/mods/admin.md#know-what-happens-by-default)可能會在您安裝或以 `--plugin-dir` 載入的 mod 中略過此 hook。若要檢查，請在[偵錯日誌](https://code.claude.com/docs/zh-TW/plugins/mods/troubleshoot.md#read-the-debug-log)中搜尋 `settings.read bypassed by cc-plugin-sec-default`。如果含有該文字的某一行指名了您的 mod，請要求您組織的管理員[將該 mod 安裝為組織的 mod 之一](https://code.claude.com/docs/zh-TW/plugins/mods/admin.md#install-your-organizations-mods)。

326* **版本**：此事件在 Claude Code 本身的讀取時觸發，以及 `e.layers` 欄位，需要 Claude Code v2.1.304 或更新版本。

327

328#### `settings.read` hook 收到的內容

329

330| 欄位 | 型別 | 保存的內容 |

331| :- | :- | :- |

332| `e.layers` | 陣列 | 每個使用中且保存設定的來源各一個 `{ source, settings }` 物件，依[優先順序](https://code.claude.com/docs/zh-TW/settings.md#settings-precedence)由低至高排列：`plugin`、`user`、`project`、`local`、`flag`、`policy`。在 `claude plugin test` 中為空。 |

333| `e.source` | 字串 | mod 所要求的單一來源，例如 `$.settings.read({ source: 'policy' })`。此時 `e.layers` 只保存該層。在 Claude Code 本身的讀取以及任何其他合併設定的讀取中不存在。 |

334

335在 `e.layers` 中，`plugin` 保存已啟用外掛所提供的設定，且僅為層名稱，而非可傳給 `$.settings.read` 的 `source`。`flag` 保存以 `--settings` 傳入的設定，`policy` 則保存受管設定。

336

337#### 區分 Claude Code 本身的讀取與 mod 的讀取

338

339在 [Claude Code 本身的讀取](#settings-read-hook)中，[`next.origin`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#the-hook-function) 為 `{ plugin: 'engine', tier: 'core' }`，而在 mod 的讀取中，`next.origin.plugin` 為發出呼叫的 mod 名稱。

340

341#### `settings.read` hook 可傳回的內容

342

343您的 hook 可以原封不動地傳回 [`next(e)`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#the-hook-function) 的結果、自己的 `{ value }`，或 `{ deny: reason }`。在 [Claude Code 本身的讀取](#settings-read-hook)和 mod 的讀取中，`{ value }` 會取代讀取所得的內容，而 `{ deny: reason }` 會拒絕該讀取：

344

345| 傳回 | 在 Claude Code 本身的讀取中 | 在 mod 的讀取中 |

346| :- | :- | :- |

347| `{ value }` | 對於您變更的每個鍵，若您傳回的內容[符合該鍵的 schema](https://code.claude.com/docs/zh-TW/plugins/mods/troubleshoot.md#settings-read-key-refused)，它會取代工作階段合併設定中該鍵的整個值 | 該 mod 的呼叫會解析為您的 `value`，或解析為從您的 `value` 中取出、它所要求的 `key`，因此請傳回完整物件，而非陣列 |

348| `{ deny: reason }` | 工作階段會保留在任何 hook 回應之前所合併的設定，且[偵錯日誌會記錄您的 `reason`](https://code.claude.com/docs/zh-TW/plugins/mods/troubleshoot#settings-read-refused) | 該 mod 的呼叫會以 `<calling mod>: $.settings.read: <reason>` 拒絕 |

349

350在 Claude Code 本身的讀取中，請以 [`next(e)` 的 `value`](#settings-read-next) 為基礎建立您的 `{ value }`，因為您遺漏的鍵會變成未設定。對於 Claude Code 從各來源分別讀取的鍵（例如 `env`），在您的 `value` 中變更它[不會有任何效果](https://code.claude.com/docs/zh-TW/plugins/mods/troubleshoot.md#settings-read-key-no-effect)。

351

352#### `next(e)` 給 `settings.read` hook 的內容

353

354`next(e)` 會解析為 `{ value }` 或 `{ deny }`：

355

356* **`{ value }`**：`value` 是合併的設定，或在設定了 [`e.source`](#settings-read-receives) 時為單一來源的設定。如果[在您的 hook 之後執行](#the-order-mods-run-in)的 hook 傳回了自己的 `{ value }`，您會改為取得該 hook 的 `value`。

357* **`{ deny }`**：在您的 hook 之後執行的 hook 拒絕了該讀取。請原封不動地傳回該 `{ deny }`。

358

359#### 從 `settings.read` hook 變更單一設定

360

361請先檢查[哪些 mod 會收到此事件，以及從哪個版本開始](#settings-read-hook)。

362

363若要變更單一鍵，請展開 [`next(e)`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#the-hook-function) 的 `value` 並設定該鍵，如此 hook 對 [`spinnerTipsEnabled`](https://code.claude.com/docs/zh-TW/settings-reference#spinnertipsenabled) 所做的那樣。此 hook 不檢查 [`next.origin`](#settings-read-origin)，因此它會在 [Claude Code 本身的讀取](#settings-read-hook)和 mod 的合併讀取中同樣變更該鍵：

364

365```javascript theme={null}

366on('settings.read', async ($, e, next) => {

367 const read = await next(e)

368 // Pass through a read of one source, so that only the merged settings change.

369 // Pass through a { deny } from a later hook too: it has no value.

370 if (e.source || !read.value) return read

371 // Keep every other key and change this one

372 return { value: { ...read.value, spinnerTipsEnabled: false } }

373})

374```

375

376在 Claude Code 本身的讀取中，如果您的 hook 傳回超出該鍵 schema 的值（例如字串），則只有該鍵會保留在任何 hook 回應之前所合併的值。偵錯日誌接著會顯示 [`the answer for <key> is no value the key can hold`](https://code.claude.com/docs/zh-TW/plugins/mods/troubleshoot#settings-read-key-refused)。如果您的值符合 schema，但該鍵仍未變更，請參閱[為何傳回的鍵沒有效果](https://code.claude.com/docs/zh-TW/plugins/mods/troubleshoot.md#settings-read-key-no-effect)。

377

308### 處理設定 hook 事件378### 處理設定 hook 事件

309 379

310設定 hook 是您在設定檔中設定的 command、HTTP、prompt 和 agent hook。每個[設定 hook 事件](https://code.claude.com/docs/zh-TW/hooks.md#hook-events)，例如 `Stop`、`SessionEnd` 或 `PostToolUse`，也是一個名為 `classic.` 後接該設定 hook 事件名稱的事件，例如 `classic.Stop`。`e` 是設定 hook 在 stdin 上收到的 JSON，包括 `transcript_path`。380設定 hook 是您在設定檔中設定的 command、HTTP、prompt 和 agent hook。每個[設定 hook 事件](https://code.claude.com/docs/zh-TW/hooks.md#hook-events)，例如 `Stop`、`SessionEnd` 或 `PostToolUse`，也是一個名為 `classic.` 後接該設定 hook 事件名稱的事件，例如 `classic.Stop`。`e` 是設定 hook 在 stdin 上收到的 JSON，包括 `transcript_path`。

plugins/mods/interface.md +10 −1

Details

508* **`Input`**：採用 `onSubmit(value)` 和 `onInput(value)`508* **`Input`**：採用 `onSubmit(value)` 和 `onInput(value)`

509* **`Select`**：採用 `onSelect(value)` 及其 `options` 中的選擇，至少一個具有唯一值的選擇清單，例如 `[{ value: 'sm', label: 'Small' }, { value: 'lg', label: 'Large' }]`509* **`Select`**：採用 `onSelect(value)` 及其 `options` 中的選擇，至少一個具有唯一值的選擇清單，例如 `[{ value: 'sm', label: 'Small' }, { value: 'lg', label: 'Large' }]`

510 510

511測試通過其 `key` 按下或輸入到控制項，因此給每個控制項一個。控制項的每次使用也會引發 [`ui.press`、`ui.input` 或 `ui.select`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#interface)，其中 `key` 在 `e.element` 中，另一個 mod 可以處理這些事件。其 hook 在您的回呼之前執行，因此它會看到使用者輸入到您的 `Input` 中的內容，並可以更改它或代替您的回呼回答。mods API 沒有按下另一個 mod 按鈕的方法。511### 哪些控制項需要 `key`

512

513為每個 `Input` 和 `Select` 提供一個 `key` prop，例如 `key: 'size'`。當 `Button` 具有 `label` prop 或單一字串子元素時，可以不提供 `key`。此時它的鍵即為 `label` 值或該字串。

514

515測試和其他 mod 透過控制項的鍵來識別它：

516

517* **測試**：[測試](https://code.claude.com/docs/zh-TW/plugins/mods/test.md#test-a-drawing)透過控制項的鍵按下或輸入到該控制項。

518* **其他 mod**：Claude Code 在執行控制項的回呼之前，會引發 [`ui.press`、`ui.input` 或 `ui.select`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#interface)，其中 `e.element` 中包含控制項的鍵。另一個 mod 針對該事件的 hook 會看到使用者輸入到您的 `Input` 中的內容，並可以更改該文字或阻止您的回呼執行。mods API 沒有提供該 mod 按下您按鈕的方法。

519

520如果訊息顯示 `needs a key` 或 `is drawn twice`，請[依據該訊息找出原因](https://code.claude.com/docs/zh-TW/plugins/mods/troubleshoot.md#needs-a-key)。

512 521

513### 鍵盤焦點和快捷鍵522### 鍵盤焦點和快捷鍵

514 523

plugins/mods/reference.md +10 −2

Details

21| `.claude-plugin/plugin.json` | 是 | 外掛[資訊清單](https://code.claude.com/docs/zh-TW/plugins/manifest-reference.md)。mod 不會新增任何必要欄位。 |21| `.claude-plugin/plugin.json` | 是 | 外掛[資訊清單](https://code.claude.com/docs/zh-TW/plugins/manifest-reference.md)。mod 不會新增任何必要欄位。 |

22| `hooks/hooks.json` | 是 | `modules`：一個陣列，內含一個相對於此檔案、指向 hook 模組的路徑，例如 `"modules": ["./register.js"]`。也可以在 `hooks` 下存放[設定 hook](https://code.claude.com/docs/zh-TW/hooks.md)。 |22| `hooks/hooks.json` | 是 | `modules`：一個陣列，內含一個相對於此檔案、指向 hook 模組的路徑，例如 `"modules": ["./register.js"]`。也可以在 `hooks` 下存放[設定 hook](https://code.claude.com/docs/zh-TW/hooks.md)。 |

23| hook 模組，例如 [`hooks/register.js`](https://code.claude.com/docs/zh-TW/plugins/mods/create#write-a-mod-yourself) | 是 | mod 的進入點。匯出 `register(on, options)`。檔名為 `.js`、`.mjs`、`.cjs`、`.jsx`、`.ts`、`.mts`、`.cts` 或 `.tsx`。為 ES 模組。 |23| hook 模組，例如 [`hooks/register.js`](https://code.claude.com/docs/zh-TW/plugins/mods/create#write-a-mod-yourself) | 是 | mod 的進入點。匯出 `register(on, options)`。檔名為 `.js`、`.mjs`、`.cjs`、`.jsx`、`.ts`、`.mts`、`.cts` 或 `.tsx`。為 ES 模組。 |

24| [`types/index.d.ts`](https://code.claude.com/docs/zh-TW/plugins/mods/interface#declare-the-values)，由資訊清單中的 `types` 指定 | 當 mod 使用 `$.state` 或在 mods API 中新增命名空間時 | 宣告 `PluginState` 值以及 mod 新增的任何命名空間 |24| [`types/index.d.ts`](https://code.claude.com/docs/zh-TW/plugins/mods/interface#declare-the-values)，除非資訊清單中的 `types` 指定了其他路徑 | 當 mod 使用 `$.state` 或在 mods API 中新增命名空間時 | 宣告 `PluginState` 值以及 mod 新增的任何命名空間。若要在資訊清單中省略 `types`，需要 v2.1.299 或更新版本。 |

25| 檔名以 `.test.ts` 或 `.test.tsx` 結尾的檔案 | 否 | [`claude plugin test`](https://code.claude.com/docs/zh-TW/plugins/mods/test#write-a-test) 執行的測試 |25| 檔名以 `.test.ts` 或 `.test.tsx` 結尾的檔案 | 否 | [`claude plugin test`](https://code.claude.com/docs/zh-TW/plugins/mods/test#write-a-test) 執行的測試 |

26 26

27`register` 會接收 `on` 與 `options`。`options` 存放資訊清單所宣告之 [`userConfig`](https://code.claude.com/docs/zh-TW/plugins/components#user-configuration) 欄位的值，並已填入預設值。27`register` 會接收 `on` 與 `options`。`options` 存放資訊清單所宣告之 [`userConfig`](https://code.claude.com/docs/zh-TW/plugins/components#user-configuration) 欄位的值，並已填入預設值。

110 110

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

112 112

113命令與設定事件在命令執行或被列出時，以及 `/config` 列被顯示或變更時觸發：113命令與設定事件在命令執行或被列出時、`/config` 列被顯示或變更時，以及讀取設定時觸發：

114 114

115| 事件 | 觸發時機 | hook 可回傳 |115| 事件 | 觸發時機 | hook 可回傳 |

116| :- | :- | :- |116| :- | :- | :- |

118| `command.describe` | 每個命令一次，用於命令清單 | `{ description, argumentHint, isHidden }` |118| `command.describe` | 每個命令一次，用於命令清單 | `{ description, argumentHint, isHidden }` |

119| `config.set` | `/config` 列即將變更時 | `next({ ...e, value })` 或 `{ deny: reason }` |119| `config.set` | `/config` 列即將變更時 | `next({ ...e, value })` 或 `{ deny: reason }` |

120| `config.describe` | 每個 `/config` 列一次 | `{ label, description, isHidden }` |120| `config.describe` | 每個 `/config` 列一次 | `{ label, description, isHidden }` |

121| [`settings.read`](https://code.claude.com/docs/zh-TW/plugins/mods/events#settings-read-hook) | mod 呼叫 [`$.settings.read`](https://code.claude.com/docs/zh-TW/plugins/mods/api#reach-files-processes-and-the-network)，或 Claude Code 建置工作階段的合併設定時 | `next(e)`、`{ value }` 或 `{ deny: reason }` |

122

123#### `settings.read` 上的 `e.layers` 與 `e.source`

124

125* **`e.layers`**：每個使用中且包含設定的來源各一個 `{ source, settings }` 物件，[優先順序](https://code.claude.com/docs/zh-TW/settings.md#settings-precedence)最低者排在最前。請參閱[`settings.read` hook 接收的內容](https://code.claude.com/docs/zh-TW/plugins/mods/events#settings-read-receives)。

126* **`e.source`**：mod 所要求的單一來源，例如 `$.settings.read({ source: 'policy' })`。在 Claude Code 自身的讀取，以及任何其他對合併設定的讀取中則不存在

127

128在 `settings.read` 上，於 Claude Code 自身讀取時觸發事件，以及 `e.layers` 欄位，需要 Claude Code v2.1.304 或更新版本。關於此 hook 何時執行以及此 hook 可回傳的內容（附範例），請參閱[變更或拒絕設定讀取](https://code.claude.com/docs/zh-TW/plugins/mods/events.md#settings-read-hook)。

121 129

122### 回合130### 回合

123 131

plugins/mods/troubleshoot.md +60 −0

Details

168 168

169在 v2.1.292 之前，該呼叫會執行第二次，因此提示詞會被提交兩次、命令會被執行兩次，或 subagent 會被啟動兩次。169在 v2.1.292 之前，該呼叫會執行第二次，因此提示詞會被提交兩次、命令會被執行兩次，或 subagent 會被啟動兩次。

170 170

171### `This mod's change didn't load` 或 `the earlier version is no longer running`

172

173對[Claude 在此工作階段中撰寫的 mod](https://code.claude.com/docs/zh-TW/plugins/mods/create.md#ask-claude-for-a-mod) 所做的變更無法載入。逐字稿中的該行以 mod 的名稱開頭，並以原因結尾：

174

175* `This mod's change didn't load, so the earlier version is still running: <reason>.`

176* `This mod didn't load, and the earlier version is no longer running: <reason>.`

177

178Claude 看不到此行，因此當您請 Claude 修復時，請將其貼到您的下一則訊息中。

179

171### `$.agent.register refused: the hooks module that made the call is no longer loaded`180### `$.agent.register refused: the hooks module that made the call is no longer loaded`

172 181

173該行以您的 mod 名稱開頭，例如 `first-mod: $.agent.register refused: the hooks module that made the call is no longer loaded (it was reloaded or removed)`，且該 agent 不會被註冊。您的 mod 在此呼叫之前已被重新載入或卸載。重新載入會載入 hook 模組的新副本，而此呼叫來自仍在舊副本中執行的程式碼，例如尚未返回的 hook。182該行以您的 mod 名稱開頭，例如 `first-mod: $.agent.register refused: the hooks module that made the call is no longer loaded (it was reloaded or removed)`，且該 agent 不會被註冊。您的 mod 在此呼叫之前已被重新載入或卸載。重新載入會載入 hook 模組的新副本，而此呼叫來自仍在舊副本中執行的程式碼，例如尚未返回的 hook。

225 234

226讀取該行上的原因。常見原因是元素不接受的 prop 和應用程式沒有的元素。235讀取該行上的原因。常見原因是元素不接受的 prop 和應用程式沒有的元素。

227 236

237### `needs a key`、`is drawn twice` 或 `key each once`

238

239您的 `ui.render` hook 返回的樹中，某個元素沒有有效的 [`key`](https://code.claude.com/docs/zh-TW/plugins/mods/interface#which-controls-need-a-key)，或兩個元素共用同一個 key。請找出您收到的訊息：

240

241* **`<Input> needs a key` 或 `<Select> needs a key`**：該元素沒有 `key` prop，或其 `key` 為空或不是字串，例如 `key: 3`。請為其指定非空字串作為 `key`。

242* **`<Button> needs a key`**：請為按鈕指定非空字串作為其 `key`

243* **`is drawn twice; each takes its own key`**：訊息所指種類的兩個元素具有相同的 `key`，例如 `Input "size" is drawn twice; each takes its own key`。請為每個元素指定各自的 `key`。

244* **[測試](https://code.claude.com/docs/zh-TW/plugins/mods/test.md#test-a-drawing)中 `press` 產生的 `key each once`**：繪圖中有多個按鈕使用您傳入的 key。具有相同標籤且沒有 `key` prop 的按鈕會共用該標籤作為其 key。請為每個按鈕指定各自的 `key`。

245

228### `ui.render` 行顯示 `threw while drawn`246### `ui.render` 行顯示 `threw while drawn`

229 247

230該行會指出[轉譯位置](https://code.claude.com/docs/zh-TW/plugins/mods/reference.md#render-sites)，接著顯示 `threw while drawn:` 與錯誤，例如 `first-mod: ui.render (ToolUse) threw while drawn: <error>; the engine drew its own`。Claude Code 在繪製您的 [`ui.render`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#interface) hook 返回的樹時，或在根據[您的 hook 傳給 `next` 的 `props`](https://code.claude.com/docs/zh-TW/plugins/mods/interface#change-what-claude-code-already-draws) 繪製該位置時，遇到了該錯誤。結尾的 `the engine drew its own` 表示該位置顯示 Claude Code 的常見內容。248該行會指出[轉譯位置](https://code.claude.com/docs/zh-TW/plugins/mods/reference.md#render-sites)，接著顯示 `threw while drawn:` 與錯誤，例如 `first-mod: ui.render (ToolUse) threw while drawn: <error>; the engine drew its own`。Claude Code 在繪製您的 [`ui.render`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#interface) hook 返回的樹時，或在根據[您的 hook 傳給 `next` 的 `props`](https://code.claude.com/docs/zh-TW/plugins/mods/interface#change-what-claude-code-already-draws) 繪製該位置時，遇到了該錯誤。結尾的 `the engine drew its own` 表示該位置顯示 Claude Code 的常見內容。

303 321

304[在 `classic.SessionStart` hook 中再次載入儲存的值](https://code.claude.com/docs/zh-TW/plugins/mods/interface#load-a-saved-value-again-after-clear)。322[在 `classic.SessionStart` hook 中再次載入儲存的值](https://code.claude.com/docs/zh-TW/plugins/mods/interface#load-a-saved-value-again-after-clear)。

305 323

324### 您的 `settings.read` hook 傳回的設定鍵未生效

325

326傳回的 `env` 項目不會成為環境變數。傳回的 `allow`、`ask` 和 `deny` 規則不會在工具呼叫時受到檢查。請在[設定檔](https://code.claude.com/docs/zh-TW/settings.md)中設定這些項目，或針對環境變數呼叫 [`$.env.set`](https://code.claude.com/docs/zh-TW/plugins/mods/api#reach-files-processes-and-the-network)。

327

328若是其他設定鍵，請查看[哪些 mod 會收到 `settings.read` 以及從哪個版本開始](https://code.claude.com/docs/zh-TW/plugins/mods/events#settings-read-hook)，然後在[偵錯日誌](#read-the-debug-log)中搜尋 `settings.read`，並尋找下列其中一行：

329

330| 日誌行 | 意義與步驟 |

331| :- | :- |

332| `settings.read hook skipped`，位於您的 mod 名稱之後 | 您的 hook 失敗。[修正該行回報的錯誤](#hook-skipped)。 |

333| `settings.read bypassed by cc-plugin-sec-default`，出現在於其前方列出您的 mod 名稱的行上 | [內建防護](https://code.claude.com/docs/zh-TW/plugins/mods/admin.md#know-what-happens-by-default)略過了您的 hook。請您組織的管理員[將該 mod 安裝為組織的 mod 之一](https://code.claude.com/docs/zh-TW/plugins/mods/admin.md#install-your-organizations-mods)。 |

334| `settings.read: the answer for <key> is no value the key can hold` | 傳回的值不符合該設定鍵的 schema。[傳回其允許的值](#settings-read-key-refused)。 |

335| `settings.read: the merge never settles for <key>` | 該行列出的設定鍵會保留設定來源的值。請在設定檔中設定它們。 |

336| `answered settings.read without next()`，位於某個 mod 名稱之後 | 僅在該 mod [於您的 mod 之前執行](https://code.claude.com/docs/zh-TW/plugins/mods/events.md#the-order-mods-run-in)時才相關。此時您的 hook 未在該次讀取中執行。[關閉該 mod](https://code.claude.com/docs/zh-TW/plugins/mods/overview.md#turn-mods-on-or-off)，或者若是您的組織部署了它，請其管理員關閉。 |

337| `settings.read: refused to the engine` | 讀取遭到拒絕，因此沒有任何 hook 的 `{ value }` 生效。[找出拒絕的來源](#settings-read-refused)。 |

338

339若沒有任何一行能解釋該設定鍵，請檢查在您的 mod 之前執行的 mod 中，是否有[變更該設定鍵](https://code.claude.com/docs/zh-TW/plugins/mods/events.md#settings-read-example)的 `settings.read` hook。關閉該 mod，或請您組織的管理員關閉。若沒有任何 hook 變更它，請在設定檔中設定該設定鍵。

340

341### `the answer for <key> is no value the key can hold`

342

343此[偵錯日誌](#read-the-debug-log)行表示 Claude Code 拒絕了您的 [`settings.read`](https://code.claude.com/docs/zh-TW/plugins/mods/events#settings-read-hook) hook 針對所列設定鍵傳回的值，且僅限該設定鍵：

344

345```text theme={null}

346settings.read: the answer for <key> is no value the key can hold; the settings' own value stands

347```

348

349您針對所列設定鍵傳回的值不符合該設定鍵的 schema，例如在型別或範圍上不符。請傳回該設定鍵的[設定參考](https://code.claude.com/docs/zh-TW/settings-reference.md)項目所允許的值。在您的值不符合期間，該設定鍵會保留在任何 hook 回應之前從設定來源合併而來的值。該行將其稱為設定本身的值。

350

351### `settings.read: refused to the engine`

352

353此[偵錯日誌](#read-the-debug-log)行表示 [Claude Code 本身的讀取](https://code.claude.com/docs/zh-TW/plugins/mods/events.md#settings-read-hook)遭到拒絕，因此沒有任何 hook 的 `{ value }` 生效，包括您的。當某個 `settings.read` hook 以 [`{ deny: reason }`](https://code.claude.com/docs/zh-TW/plugins/mods/events#settings-read-returns) 拒絕該讀取時，該行會帶有該 hook 的原因：

354

355```text theme={null}

356settings.read: refused to the engine (engine: $.settings.read: <reason>); the settings' own values stand

357```

358

359在您自己的 hook 程式碼中搜尋 `<reason>` 文字：

360

361* **您的程式碼中有此文字**：您的 hook 拒絕了該讀取。請讓它在 [`next.origin`](https://code.claude.com/docs/zh-TW/plugins/mods/events#settings-read-origin) 顯示為 Claude Code 本身的讀取時傳回 `{ value }`。

362* **您的程式碼中沒有此文字**：逐一[關閉](https://code.claude.com/docs/zh-TW/plugins/mods/overview.md#turn-mods-on-or-off)您的其他 mod。每關閉一個後，從您的 shell 重新執行此工作階段的命令，並加上一個指向新路徑的 `--debug-file`，然後在該檔案中搜尋 `refused to the engine`。若該行存在，請關閉下一個 mod。若不存在，則您最後關閉的 mod 拒絕了該讀取，請保持其關閉。

363

364當沒有其他 mod 可關閉時，請針對您的 hook 傳回的設定鍵使用[設定檔](https://code.claude.com/docs/zh-TW/settings.md)。在讀取遭到拒絕期間，其值仍然有效。

365

306## 讀取偵錯日誌366## 讀取偵錯日誌

307 367

308偵錯日誌對 Claude Code 載入或拒絕的每個模組、失敗的每個 hook 和它拒絕的每個結果都有一行，因此當逐字稿顯示沒有內容時，這是要查看的地方。若要寫入一個，在您的 shell 中使用 `--debug` 啟動 Claude Code，或使用 `--debug-file <path>` 選擇它的位置：368偵錯日誌對 Claude Code 載入或拒絕的每個模組、失敗的每個 hook 和它拒絕的每個結果都有一行，因此當逐字稿顯示沒有內容時，這是要查看的地方。若要寫入一個，在您的 shell 中使用 `--debug` 啟動 Claude Code，或使用 `--debug-file <path>` 選擇它的位置：

plugins/troubleshooting.md +17 −7

Details

251 251

252首先檢查儲存庫本身：拼寫錯誤的 `owner/repo`、不存在的儲存庫或您看不到的私人儲存庫也會以此訊息結尾。在瀏覽器中開啟儲存庫 URL，或在終端機中執行 `git ls-remote <url>`，以確認它存在且您有權存取。252首先檢查儲存庫本身：拼寫錯誤的 `owner/repo`、不存在的儲存庫或您看不到的私人儲存庫也會以此訊息結尾。在瀏覽器中開啟儲存庫 URL，或在終端機中執行 `git ls-remote <url>`，以確認它存在且您有權存取。

253 253

254如果儲存庫是正確的，原因是認證。Claude Code 執行 git 時禁用互動式提示，因此它無法像您的終端機那樣要求您輸入密碼、金鑰密碼或認證。如果 git 需要提示，您會看到 `fatal: Cannot prompt because user interactivity has been disabled` 或 `terminal prompts disabled` 在原始錯誤中。只有已經非互動式工作的認證才會成功：254如果儲存庫是正確的，原因是憑證。Claude Code 會關閉 git 的提示和 askpass 程式（包括在 `GIT_ASKPASS` 中設定的程式），並以批次模式執行 SSH。當 git 需要提示時，複製的錯誤會包含 `fatal: Cannot prompt because user interactivity has been disabled`、`terminal prompts disabled` 或 `fatal: unable to get password from user`。只有 git 無需提示或 askpass 程式即可取得的憑證才會成功：

255 255

256* **SSH**：`ssh -T git@<host>` 必須成功而不提示密碼，並且主機必須已在 `known_hosts` 中256* **SSH**：`ssh -T git@<host>` 必須成功而不提示密碼，並且主機必須已在 `known_hosts` 中

257* **HTTPS**：您的認證助手必須為主機保存令牌。對於 GitHub，執行 `gh auth login` 和 `gh auth setup-git`。對於另一個主機，在您的 git 認證助手中儲存個人存取令牌。使用 `git ls-remote <url>` 測試257* **HTTPS**：您的憑證輔助程式必須保存該主機的 token。對於 GitHub，執行 `gh auth login` 和 `gh auth setup-git`。對於其他主機，在您的 git 憑證輔助程式中儲存個人存取 token。若要測試，請在終端機中取消設定 `GIT_ASKPASS` 並執行 `git -c core.askPass= ls-remote <url>`。

258 258

259一旦 `git ls-remote` 在您的終端機中成功執行而不提示，請再次執行新增或更新。成功的新增會列印 `Successfully added marketplace: <name>`。成功的更新會從您的 shell 列印 `Successfully updated marketplace: <name>`，或在工作階段中列印 `✔ Updated 1 marketplace`。259一旦您所用協定的檢查成功執行而不提示，請再次執行新增或更新。成功的新增會列印 `Successfully added marketplace: <name>`。成功的更新會從您的 shell 列印 `Successfully updated marketplace: <name>`，或在工作階段中列印 `✔ Updated 1 marketplace`。

260 260

261若要讓 Claude Code 跳過 GitHub `owner/repo` 來源的 SSH，請設定 `CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`。沒有它，當 `github.com` 的 SSH 金鑰看起來已配置時，Claude Code 會透過 SSH 複製這些來源，並在 SSH 複製失敗時回退到 HTTPS。261若要讓 Claude Code 跳過 GitHub `owner/repo` 來源的 SSH，請設定 `CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`。沒有它，當 `github.com` 的 SSH 金鑰看起來已配置時，Claude Code 會透過 SSH 複製這些來源，並在 SSH 複製失敗時回退到 HTTPS。

262 262

318 318

319如果儲存庫是 monorepo，使用 `claude plugin marketplace add <source> --sparse <paths>` 限制簽出到您命名的目錄。319如果儲存庫是 monorepo，使用 `claude plugin marketplace add <source> --sparse <paths>` 限制簽出到您命名的目錄。

320 320

321如果儲存庫有大型 git 子模組，請更新 Claude Code。在 v2.1.295 及更新版本中，Claude Code 僅擷取[包含外掛檔案的子模組](https://code.claude.com/docs/zh-TW/plugins/marketplace-reference.md#git-submodules-in-the-marketplace-repository)。較早的版本會擷取每個子模組，光是這樣就可能用盡這 120 秒。

322

321### Marketplace updates keep failing offline323### Marketplace updates keep failing offline

322 324

323您在市集的 git 主機無法到達的環境中工作，每個工作階段都在背景中重複失敗的重新整理。您現有的市集簽出保持原位，啟動不會延遲。325您在市集的 git 主機無法到達的環境中工作，每個工作階段都在背景中重複失敗的重新整理。您現有的市集簽出保持原位，啟動不會延遲。

610| `... has version requirements too complex to intersect` 或 `has an invalid version requirement` | 範圍不是有效的 semver，或無法相交組合的範圍。 | 修復無效範圍或簡化長 `\|\|` 鏈。 |612| `... has version requirements too complex to intersect` 或 `has an invalid version requirement` | 範圍不是有效的 semver，或無法相交組合的範圍。 | 修復無效範圍或簡化長 `\|\|` 鏈。 |

612| `Dependency "<dep>" (required by <plugin>) is in <marketplace>, which is not in the allowlist` | 相依套件在不同的市集中，預設情況下跨市集解析已關閉。 | 在相同範圍自行安裝相依套件，在您的 shell 中使用 `claude plugin install <dep>@<marketplace>` 加上您安裝外掛程式的 `--scope`，然後重試。 |614| `Dependency "<dep>" (required by <plugin>) is in marketplace "<marketplace>", which is not in the allowlist` | 相依套件在不同的市集中，預設情況下跨市集解析已關閉。 | 在相同範圍自行安裝相依套件，在您的 shell 中使用 `claude plugin install <dep>@<marketplace>` 加上您安裝外掛程式的 `--scope`，然後重試。 |

613 615

614若要以程式設計方式查看這些，請在您的 shell 中執行 `claude plugin list --json`。有問題的外掛程式帶有 `errors` 欄位及其訊息和 `errorDetails` 欄位，每個都有 `type`：前三列是 `dependency-unsatisfied`，第四列是 `dependency-version-unsatisfied`。616若要以程式設計方式查看這些，請在您的 shell 中執行 `claude plugin list --json`。有問題的外掛程式帶有 `errors` 欄位及其訊息和 `errorDetails` 欄位，每個都有 `type`：前三列是 `dependency-unsatisfied`，第四列是 `dependency-version-unsatisfied`。

615 617

979 981

980### `${CLAUDE_PLUGIN_ROOT}` 在 Windows 上顯示正斜線982### `${CLAUDE_PLUGIN_ROOT}` 在 Windows 上顯示正斜線

981 983

982在 Windows 上，外掛程式 hook 接收 `${CLAUDE_PLUGIN_ROOT}` 為 `C:/Users/you/...` 而不是 `C:\Users\you\...`，預期反斜線的指令碼會中斷。984在 Windows 上，透過 Git Bash 執行的外掛程式 hook 接收 `${CLAUDE_PLUGIN_ROOT}` 為 `C:/Users/you/...` 而不是 `C:\Users\you\...`，預期反斜線的指令碼會中斷。

983 985

984Claude Code 在 Windows 上透過 Git Bash 執行 shell 形式的 hook，並刻意以正斜線 Win32 形式替換外掛程式根目錄。Bash 內建、MSYS 工具和原生 Windows 二進位檔都接受該形式。986安裝 Git Bash 後，[shell 形式的 hook](https://code.claude.com/docs/zh-TW/hooks.md#exec-form-and-shell-form) 預設會透過 Git Bash 執行。對於透過 Git Bash 執行的 hook，Claude Code 會以正斜線傳遞路徑，使 Bash 不會將反斜線讀取為跳脫字元。Bash 內建命令、MSYS 工具和原生 Windows 二進位檔都接受該形式。

985 987

986如果您的指令碼需要反斜線，請將 hook 切換為保留原生路徑的其中一種形式，如[執行形式和 shell 形式](https://code.claude.com/docs/zh-TW/hooks.md#exec-form-and-shell-form)下所述：988如果您的指令碼需要反斜線，請將 hook 切換為保留原生路徑的其中一種形式，如[執行形式和 shell 形式](https://code.claude.com/docs/zh-TW/hooks.md#exec-form-and-shell-form)下所述：

987 989

1090 1092

1091或者，在 git 儲存庫中託管市集，並告訴使用者使用儲存庫 URL 新增它。對於 git 來源，Claude Code 複製整個儲存庫，因此相對路徑解析。來源類型在 [市集參考](https://code.claude.com/docs/zh-TW/plugins/marketplace-reference.md) 上。1093或者，在 git 儲存庫中託管市集，並告訴使用者使用儲存庫 URL 新增它。對於 git 來源，Claude Code 複製整個儲存庫，因此相對路徑解析。來源類型在 [市集參考](https://code.claude.com/docs/zh-TW/plugins/marketplace-reference.md) 上。

1092 1094

1095### 根外掛程式來自 git 子模組的檔案在安裝後遺失

1096

1097您的外掛程式位於市集根目錄，並執行或讀取儲存庫中某個 git 子模組的檔案。安裝後，該子模組的目錄是空的。在 v2.1.295 之前，Claude Code 會擷取每個子模組，因此該目錄會有內容。

1098

1099當 Claude Code 複製您的市集時，它只會擷取[包含外掛程式檔案的子模組](https://code.claude.com/docs/zh-TW/plugins/marketplace-reference.md#git-submodules-in-the-marketplace-repository)。對於位於根目錄的外掛程式，它會藉由讀取外掛程式設定中的路徑以及外掛程式檔案的文字來判斷。它無法看到指令碼在執行時才建構的路徑。

1100

1101請將指向子模組的路徑完整寫在 Claude Code 能讀取的位置，例如 hook 命令中的 `${CLAUDE_PLUGIN_ROOT}/vendor/tool/run.sh`。Claude Code 接著會為該外掛程式擷取儲存庫中的每個子模組。

1102

1093### Marketplace validation errors1103### Marketplace validation errors

1094 1104

1095您從市集目錄執行了 `claude plugin validate .`，它報告了市集檔案本身的錯誤或警告。1105您從市集目錄執行了 `claude plugin validate .`，它報告了市集檔案本身的錯誤或警告。

1121 1131

1122### `Marketplace source '<source>' is blocked by enterprise policy`1132### `Marketplace source '<source>' is blocked by enterprise policy`

1123 1133

1124您執行了 `/plugin marketplace add`、`update` 或安裝，Claude Code 拒絕了此行。對於 GitHub 或 git 來源，主機跟隨括號中的來源，如 `'github:owner/repo' (github.com)`。1134您執行了 `/plugin marketplace add`、`update` 或安裝，Claude Code 拒絕了此行。

1125 1135

1126您的管理員在受管設定中設定了 `blockedMarketplaces` 或 `strictKnownMarketplaces`，此來源不被允許。要求您的管理員允許來源，或新增訊息列出的允許來源之一。1136您的管理員在受管設定中設定了 `blockedMarketplaces` 或 `strictKnownMarketplaces`，此來源不被允許。要求您的管理員允許來源，或新增訊息列出的允許來源之一。

1127 1137

prompt-caching.md +11 −5

Details

100 100

101### 開啟快速模式101### 開啟快速模式

102 102

103啟用[快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md)會新增一個請求標頭，該標頭是快取金鑰的一部分，因此 Claude Code 傳送的第一個啟用快速模式的請求會讀取整個對話歷史記錄而沒有快取命中。Claude Code 在回合開始時設定該標頭一次，並為整個回合保留它，因此當您在 Claude 工作時開啟快速模式時，標頭的快取遺漏會在您下一個回合的第一個請求時發生。這些未快取的輸入 token 按[快速模式費率](https://code.claude.com/docs/zh-TW/fast-mode.md#understand-the-cost-tradeoff)計費，這就是為什麼在工作階段開始時開啟它的成本比在長工作階段深處開啟它的成本要低。如果您目前的模型不支援快速模式，啟用快速模式也會[切換您的模型](#switching-models)，該切換本身會從執行回合中的下一個請求開始啟動新的快取。103[快速模式](https://code.claude.com/docs/zh-TW/fast-mode.md)與標準速度各自保留獨立的快取，因此在您開啟或關閉快速模式後，下一個請求無法使用另一種速度所快取的內容。在對話中第一次開啟快速模式時，下一個請求會以[快速模式費率](https://code.claude.com/docs/zh-TW/fast-mode.md#understand-the-cost-tradeoff)讀取到目前為止未經快取的整個對話。若要降低此成本，請在工作階段開始時開啟它。

104 104

105成本每個對話應用一次。在第一個快速模式回合之後，Claude Code 會繼續傳送標頭，並且僅改變請求的速度設定，這不是快取金鑰的一部分。關閉快速模式、[達到速率限制後自動改用標準速度](https://code.claude.com/docs/zh-TW/fast-mode.md#handle-rate-limits)以及稍後重新開啟都會保留快取。如果您[在工作階段中途用完用量點數](https://code.claude.com/docs/zh-TW/fast-mode.md#handle-rate-limits)，Claude Code 會以相同方式在標準速度下重試每個被拒絕的快速模式請求，因此此備援也會保留快取。`/clear` 和 `/compact` 會重設此設定，因為它們無論如何都會在這些點重建快取。105* 如果您在 Claude 工作時開啟它，該回合會以標準速度完成，而任何未快取讀取的費用會在您下一個回合的第一個請求中支付。

106* 如果您目前的模型不支援快速模式，啟用快速模式也會[將您切換至 Opus](https://code.claude.com/docs/zh-TW/fast-mode.md#toggle-fast-mode)。該[模型切換](#switching-models)本身會從執行中回合的下一個請求開始啟動新的快取。

107

108之後的每次切換，都會以未快取方式讀取您所切換到的速度尚未快取的內容。Claude Code 自行進行的速度變更，例如達到速率限制後[改用標準速度](https://code.claude.com/docs/zh-TW/fast-mode.md#handle-rate-limits)以及稍後恢復快速模式，也算作切換。

106 109

107### 連接或移除 MCP 伺服器110### 連接或移除 MCP 伺服器

108 111

184>187>

185> 當您捨棄的上下文是您不再需要的內容時，壓縮對您有利。為了選擇其開銷何時發生，請在工作的自然中斷處（例如任務之間）執行 `/compact`，而不是等待自動壓縮在任務中途觸發。如果您走上了想要完全放棄的路徑，請改為使用 [`/rewind`](#rewinding-the-conversation) 回到較早的回合。倒轉會截斷回到已快取的前綴，而不是像壓縮那樣建立新的前綴。188> 當您捨棄的上下文是您不再需要的內容時，壓縮對您有利。為了選擇其開銷何時發生，請在工作的自然中斷處（例如任務之間）執行 `/compact`，而不是等待自動壓縮在任務中途觸發。如果您走上了想要完全放棄的路徑，請改為使用 [`/rewind`](#rewinding-the-conversation) 回到較早的回合。倒轉會截斷回到已快取的前綴，而不是像壓縮那樣建立新的前綴。

186 189

187如果您在終端機工作階段中讓長對話閒置，且該對話處於[一小時 TTL](#which-ttl-each-request-gets)，Claude Code 可能會在快取過期前不久將其壓縮。若要關閉閒置壓縮，請將 [`idleCompaction`](https://code.claude.com/docs/zh-TW/settings-reference#idlecompaction) 設定為 `false`，這需要 Claude Code v2.1.290 或更新版本。190如果您讓處於[一小時 TTL](#which-ttl-each-request-gets) 的長對話閒置，Claude Code 可能會將其壓縮。若要關閉閒置壓縮，請將 [`idleCompaction`](https://code.claude.com/docs/zh-TW/settings-reference#idlecompaction) 設定為 `false`，這需要 Claude Code v2.1.290 或更新版本。

188 191

189### 累積許多影像192### 累積許多影像

190 193

309 312

310在 Claude Code 中，快取實際上是限定在一台機器和一個目錄的範圍內。系統提示會嵌入您的自動記憶路徑，對話會以工作目錄、平台、shell 和作業系統版本的公告開始。因此在不同目錄中的兩個工作階段會建立不同的前綴並且會錯過彼此的快取。313在 Claude Code 中，快取實際上是限定在一台機器和一個目錄的範圍內。系統提示會嵌入您的自動記憶路徑，對話會以工作目錄、平台、shell 和作業系統版本的公告開始。因此在不同目錄中的兩個工作階段會建立不同的前綴並且會錯過彼此的快取。

311 314

312您在同一目錄中並行執行的工作階段會建立相符的前綴並讀取彼此的快取。順序工作階段只有在啟動時取得的 git 狀態快照相符時才會共享前綴，因為每個對話也會帶有該快照中的分支和最近的提交。315* 您在同一目錄中並行執行的工作階段會建立相符的前綴，並可讀取彼此的快取。

316* 順序工作階段只有在啟動時取得的 git 狀態快照相符時才會共享前綴，因為每個對話也會帶有該快照中的分支和最近的提交。

317

318底層 API 快取的範圍更廣。快取在組織之間是隔離的，在某些提供者上，[在組織內的工作區之間隔離](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#cache-storage-and-sharing)。在這些邊界內，兩個請求只有在其模型、[速度](#turning-on-fast-mode)和前綴皆相符時才會共享快取。

313 319

314底層 API 快取的範圍更廣。快取在組織之間是隔離的，在某些提供者上，[在組織內的工作區之間隔離](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#cache-storage-and-sharing)。在這些邊界內，任何兩個具有相同模型和前綴的請求都會讀取相同的快取。對於執行自動化程序群隊的 Agent SDK 呼叫者，請參閱[改善跨使用者和機器的提示快取](https://code.claude.com/docs/zh-TW/agent-sdk/modifying-system-prompts.md#improve-prompt-caching-across-users-and-machines)以將自動記憶位置移出系統提示並在使用者和機器之間共享系統提示的快取項目。320對於執行自動化程序群隊的 Agent SDK 呼叫者，請參閱[改善跨使用者和機器的提示快取](https://code.claude.com/docs/zh-TW/agent-sdk/modifying-system-prompts.md#improve-prompt-caching-across-users-and-machines)以將自動記憶位置移出系統提示詞。

315 321

316## 檢查快取效能322## 檢查快取效能

317 323

remote-control.md +10 −2

Details

179* **變更的差異**：當工作階段的目錄位於 git 儲存庫中時，已連線裝置的差異窗格會顯示您的變更。在具有領先儲存庫預設分支之提交的分支上，窗格會顯示自該分支從預設分支分出以來的變更，包括您尚未提交的編輯。在預設分支本身，或在未領先預設分支的分支上，窗格只會顯示您尚未提交的變更。179* **變更的差異**：當工作階段的目錄位於 git 儲存庫中時，已連線裝置的差異窗格會顯示您的變更。在具有領先儲存庫預設分支之提交的分支上，窗格會顯示自該分支從預設分支分出以來的變更，包括您尚未提交的編輯。在預設分支本身，或在未領先預設分支的分支上，窗格只會顯示您尚未提交的變更。

180* **模型**：當您從已連線的裝置選擇[模型](https://code.claude.com/docs/zh-TW/model-config.md)時，Claude Code 會以該模型執行工作階段。需要 Claude Code v2.1.238 或更新版本。您從裝置的模型控制項選擇的模型僅適用於目前的工作階段。當您從裝置向互動式工作階段傳送 `/model <name>` 時，Claude Code 也會設定新工作階段的預設值。180* **模型**：當您從已連線的裝置選擇[模型](https://code.claude.com/docs/zh-TW/model-config.md)時，Claude Code 會以該模型執行工作階段。需要 Claude Code v2.1.238 或更新版本。您從裝置的模型控制項選擇的模型僅適用於目前的工作階段。當您從裝置向互動式工作階段傳送 `/model <name>` 時，Claude Code 也會設定新工作階段的預設值。

181* **Effort 等級**：當您從已連線的裝置以 `/effort` 或裝置的 effort 控制項設定 [effort 等級](https://code.claude.com/docs/zh-TW/model-config.md#adjust-effort-level)時，Claude Code 會將其套用至您機器上的工作階段。若您已使用 `CLAUDE_CODE_EFFORT_LEVEL` 固定等級，工作階段會維持該等級，且 Claude Code 會拒絕從 effort 控制項選擇的不同等級。從 effort 控制項選擇等級需要您的機器上安裝 Claude Code v2.1.234 或更新版本。181* **Effort 等級**：當您從已連線的裝置以 `/effort` 或裝置的 effort 控制項設定 [effort 等級](https://code.claude.com/docs/zh-TW/model-config.md#adjust-effort-level)時，Claude Code 會將其套用至您機器上的工作階段。若您已使用 `CLAUDE_CODE_EFFORT_LEVEL` 固定等級，工作階段會維持該等級，且 Claude Code 會拒絕從 effort 控制項選擇的不同等級。從 effort 控制項選擇等級需要您的機器上安裝 Claude Code v2.1.234 或更新版本。

182* **連線失敗後重新連線**：執行 `/remote-control` 即可重新連線。若在此期間壓縮改寫了對話，或您使用 `/resume` 切換了對話，Claude Code 會封存其先前使用的伺服器工作階段，而不會將其留在工作階段清單中。您仍可透過[篩選已封存的工作階段](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md#archive-sessions)找到它。在裝置仍連線時切換對話不會封存工作階段。182* **連線失敗後重新連線**：執行 `/remote-control` 即可重新連線。若在此期間壓縮改寫了對話，或您使用 `/resume` 切換了對話，Claude Code 會封存其先前使用的伺服器工作階段，而不會將其留在工作階段清單中。您仍可在 claude.ai/code 的[已封存工作階段](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md#find-an-archived-session)中找到該工作階段。在裝置仍連線時切換對話不會封存工作階段。

183 183

184### 為所有工作階段啟用 Remote Control184### 為所有工作階段啟用 Remote Control

185 185

401 401

402## 疑難排解402## 疑難排解

403 403

404### "Remote Control disconnected" 或 "Can't reach"

405

406在 [claude.ai/code](https://claude.ai/code) 或 Desktop 應用程式中，**Remote Control disconnected** 或 **Can't reach** 訊息表示您的瀏覽器或應用程式與您電腦上的 Claude Code 失去聯繫。這兩則訊息都無法告訴您，Claude 或您正在查看的 subagent 是否仍在您的電腦上運作。請在該電腦上檢查 Claude Code 所處的狀態，並依照對應的步驟重新連線：

407

408* **互動式工作階段顯示 `Remote Control disconnected`**：依照[該行所指出原因的重新連線步驟](#session-ended-elsewhere)操作

409* **Claude Code 正在執行且未顯示任何失敗**：互動式工作階段會在機器喚醒並連上網路後自行重新連線，因此您不需要採取任何動作。如果您使用的是 `claude remote-control`，請參閱[限制](#limitations)下的 **長時間網路中斷**

410* **Claude Code 未在執行**：[重新啟動它並恢復工作階段](#resume-sessions-after-stopping-the-server)

411

404### "Remote Control requires a claude.ai subscription"412### "Remote Control requires a claude.ai subscription"

405 413

406您未使用 claude.ai 帳戶登入，或另一個憑證優先於您的登入。此訊息採用以下其中一種形式：414您未使用 claude.ai 帳戶登入，或另一個憑證優先於您的登入。此訊息採用以下其中一種形式：

463* **使用 `/remote-control`、`claude --remote-control` 或[自動連線](#enable-remote-control-for-all-sessions)**：工作階段會在沒有 Remote Control 的情況下繼續執行，且 Claude Code 會在 claude.ai 將其封存471* **使用 `/remote-control`、`claude --remote-control` 或[自動連線](#enable-remote-control-for-all-sessions)**：工作階段會在沒有 Remote Control 的情況下繼續執行，且 Claude Code 會在 claude.ai 將其封存

464* **使用 `claude remote-control`**：伺服器會停止並封存其所服務的工作階段，然後結束472* **使用 `claude remote-control`**：伺服器會停止並封存其所服務的工作階段，然後結束

465 473

466您仍可透過[篩選已封存的工作階段](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md#archive-sessions)找到已封存的工作階段。474若要再次找到這些工作階段，請在 claude.ai/code 開啟您的[已封存工作階段](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md#find-an-archived-session)。

467 475

468Remote Control 不會自行重新連線。若要在您的組織再次允許後重新開啟它，請在工作階段中執行 `/remote-control`，或在 shell 中執行 `claude remote-control`。在此機器上的 Claude Code 擷取到變更後的原則之前，任一命令都會以 [`Remote Control is disabled by your organization's policy`](#remote-control-is-disabled-by-your-organizations-policy) 失敗。開啟中的工作階段大約每小時擷取一次原則。若要找出阻止 Remote Control 的原因，請將命令輸出的完整文字與該項目進行比對。476Remote Control 不會自行重新連線。若要在您的組織再次允許後重新開啟它，請在工作階段中執行 `/remote-control`，或在 shell 中執行 `claude remote-control`。在此機器上的 Claude Code 擷取到變更後的原則之前，任一命令都會以 [`Remote Control is disabled by your organization's policy`](#remote-control-is-disabled-by-your-organizations-policy) 失敗。開啟中的工作階段大約每小時擷取一次原則。若要找出阻止 Remote Control 的原因，請將命令輸出的完整文字與該項目進行比對。

469 477

routines.md +24 −4

Details

293 293

294#### 支援的事件294#### 支援的事件

295 295

296GitHub 觸發條件可以訂閱以下任一事件類別。在每個類別中，您可以選擇特定的動作（例如 `pull_request.opened`），或對該類別中的所有動作做出回應。296請從以下任一類別中選擇事件。在每個類別中，您可以選擇特定的動作（例如 `pull_request.opened`），或對該類別中的所有動作做出回應。

297 297

298| Event | Triggers when |298| Event | Triggers when |

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

300| Pull request | 當 PR 被開啟、關閉、指派、加上標籤、同步或以其他方式更新時 |300| Pull request | 當 PR 被開啟、關閉、指派、加上標籤、同步或以其他方式更新時 |

301| Release | 當發行版本被建立、發布、編輯或刪除時 |301| Release | 當發行版本被建立、發布、編輯或刪除時 |

302| Issue | 當 issue 被開啟、編輯、關閉、重新開啟、加上標籤、指派或以其他方式更新時 |

302 303

303#### 篩選 pull request304#### 篩選 pull request

304 305

333 334

334按一下任何執行，即可將其作為完整的工作階段開啟。在那裡，您可以查看 Claude 做了什麼、檢閱變更、建立 pull request 或繼續對話。每個執行工作階段的運作方式都與其他工作階段相同：使用工作階段標題旁的下拉選單來重新命名、封存或刪除它。335按一下任何執行，即可將其作為完整的工作階段開啟。在那裡，您可以查看 Claude 做了什麼、檢閱變更、建立 pull request 或繼續對話。每個執行工作階段的運作方式都與其他工作階段相同：使用工作階段標題旁的下拉選單來重新命名、封存或刪除它。

335 336

336> [!NOTE]337在任務詳細資料頁面的 **History** 下，每個已結束執行的資料列末端，若執行失敗會顯示 **Error**，若已取消會顯示 **Cancelled**，若成功則兩者皆不顯示。**Status** 篩選器將這三種結果分別稱為 **Failed**、**Cancelled** 和 **Succeeded**。這些結果說明的是工作階段如何結束，而非 Claude 是否完成了您提示詞所描述的工作，因此請開啟該次執行並閱讀其逐字稿，以了解實際發生了什麼事。

337>338

338> 執行清單中的綠色狀態表示工作階段已啟動並結束，且沒有發生基礎設施錯誤。這並不代表您提示詞所描述的工作已成功完成。請開啟該次執行並閱讀逐字稿，以確認 Claude 實際做了什麼。被封鎖的網路請求、缺少的連接器工具，以及工作本身的失敗，都會顯示在逐字稿中，而不是在狀態指示器中。339* **Succeeded**：工作階段結束時，Claude Code 未回報失敗。被封鎖的網路請求、缺少的連接器工具，以及 Claude 無法完成的工作，都會顯示在逐字稿中，而不是在資料列上

340* **Failed**：工作階段未正常結束。例如，它意外停止、以錯誤結束，或在執行開始前就已被封存

341* **Cancelled**：執行並未失敗，且其工作階段已被封存。如果您封存了一次成功執行的工作階段，該執行會變為 **Cancelled**。任務本身無需任何變更

342

343如果 **History** 下出現警告，請參閱[「The last run」警告](#the-last-run-didnt-start)。

339 344

340### 編輯與控制排程任務345### 編輯與控制排程任務

341 346

499 504

500您 Team 或 Enterprise 組織中的擁有者可能已在 [**Organization settings > Capabilities > Remote sessions**](https://claude.ai/admin-settings/capabilities) 關閉了 **Scheduled tasks (Was Routines)** 切換開關。在 Claude Code v2.1.227 或更新版本中，同一個切換開關也會在 CLI 中隱藏 `/schedule`。這是伺服器端的組織設定，因此無法從您的本機設定覆寫。請聯絡擁有者，為您的組織重新開啟排程任務。505您 Team 或 Enterprise 組織中的擁有者可能已在 [**Organization settings > Capabilities > Remote sessions**](https://claude.ai/admin-settings/capabilities) 關閉了 **Scheduled tasks (Was Routines)** 切換開關。在 Claude Code v2.1.227 或更新版本中，同一個切換開關也會在 CLI 中隱藏 `/schedule`。這是伺服器端的組織設定，因此無法從您的本機設定覆寫。請聯絡擁有者，為您的組織重新開啟排程任務。

501 506

507### "The last run" 警告

508

509當 **History** 下的警告以 "The last run" 開頭時，請在第一欄中找到該警告，並依照該列的說明操作。之後的某次執行開始後，警告就會清除。

510

511| 警告 | 處理方式 |

512| :- | :- |

513| "The last run didn't start because your organization had reached its limit on cloud sessions running at once." | 任務無需變更。請稍後點選 **Run now**，或等待下一次執行 |

514| "The last run didn't start because its cloud environment couldn't be found or used." | 在任務的詳細資料頁面上，開啟其名稱旁的選單，選取 **Edit**，然後找到[雲端環境選擇器](#environments-and-network-access)。如果其顯示 **Unavailable environment**，表示該環境已封存或您的帳戶已無法使用，請在該處選擇其他環境並儲存變更。否則，請在詳細資料頁面上以 **Run now** 重試，或在選擇器中挑選其他環境並儲存變更 |

515| "The last run was blocked because it couldn't access something it needs, or your organization's policy doesn't allow it." | 請確認您的 [GitHub 存取權](#repositories-and-branch-permissions)涵蓋任務的儲存庫。如果已涵蓋，請詢問您 Claude 組織的[擁有者](https://code.claude.com/docs/zh-TW/server-managed-settings.md#access-control)是否有政策封鎖了該任務 |

516| "The last run didn't start because of a problem that's usually temporary." | 點選 **Run now** 再試一次，或等待下一次執行 |

517| "The last run didn't start because its repository or branch wasn't available." | 請在 GitHub 上確認任務中的每個儲存庫都有[執行起始所用的分支](#repositories-and-branch-permissions)。也請確認您的 [GitHub 存取權](#repositories-and-branch-permissions)涵蓋每個儲存庫，如果您的連線已過期，請重新連接 GitHub |

518| "The last run didn't start because some of its settings weren't accepted." | 在任務的詳細資料頁面上，開啟其名稱旁的選單並選取 **Edit**。對話方塊不會標示哪項設定未被接受，因此請在該處逐一檢查每項設定，包括任務的名稱、提示詞、模型、儲存庫、環境、連接器和觸發條件 |

519| "The last run stopped because a usage limit was reached." | 關於達到用量上限後任務的執行何時可以再次開始，請參閱[用量與上限](#usage-and-limits) |

520| "The last run failed." | 點選 **Run now** 再試一次，或等待下一次執行。失敗的執行沒有可開啟的工作階段 |

521

502## 相關資源522## 相關資源

503 523

504* [`/loop` 與工作階段內排程](https://code.claude.com/docs/zh-TW/scheduled-tasks)：在開啟的 CLI 工作階段中排程本機任務524* [`/loop` 與工作階段內排程](https://code.claude.com/docs/zh-TW/scheduled-tasks)：在開啟的 CLI 工作階段中排程本機任務

sandbox-environments.md +4 −4

Details

171 171

172個別開發人員可以選擇本頁面上的任何 sandboxing 方法。組織可以強制執行的內容以及使用哪些工具取決於方法：172個別開發人員可以選擇本頁面上的任何 sandboxing 方法。組織可以強制執行的內容以及使用哪些工具取決於方法：

173 173

174* **Built-in Bash sandbox**：唯一 Claude Code 本身強制執行的方法。通過 [managed settings](https://code.claude.com/docs/zh-TW/managed-settings.md#delivery-mechanisms) 傳遞 `sandbox` 設定金鑰，可以是由您的 MDM 管理的檔案，也可以通過 Claude.ai 上的 [server-managed settings](https://code.claude.com/docs/zh-TW/server-managed-settings.md)。有關要部署的金鑰以及如何防止開發人員擴大策略，請參閱 [Enforce sandboxing with managed settings](https://code.claude.com/docs/zh-TW/sandboxing.md#enforce-sandboxing-with-managed-settings)。174* **Built-in Bash sandbox**：唯一 Claude Code 本身強制執行的方法。通過 [managed settings](https://code.claude.com/docs/zh-TW/managed-settings.md#delivery-mechanisms) 傳遞 `sandbox` 設定鍵，可以是由您的 MDM 管理的檔案，也可以通過 Claude.ai 上的 [server-managed settings](https://code.claude.com/docs/zh-TW/server-managed-settings.md)。有關要部署的鍵以及如何防止開發人員擴大策略，請參閱 [Enforce sandboxing with managed settings](https://code.claude.com/docs/zh-TW/sandboxing.md#enforce-sandboxing-with-managed-settings)。

175* **Dev containers**：將 [example dev container](https://code.claude.com/docs/zh-TW/devcontainer.md) 提交到您的儲存庫以標準化整個團隊的環境。這是一個約定而不是強制邊界，因為 Claude Code 不需要容器。如果開發人員不應該能夠在其外部執行 Claude Code，請使用您組織的設備管理或軟體允許清單工具強制執行。175* **Dev containers**：將 [example dev container](https://code.claude.com/docs/zh-TW/devcontainer.md) 提交到您的儲存庫以標準化整個團隊的環境。這是一個約定而不是強制邊界，因為 Claude Code 不需要容器。如果開發人員不應該能夠在其外部執行 Claude Code，請使用您組織的設備管理或軟體允許清單工具強制執行。

176* **Custom containers and VMs**：通過批准的映像分發 Claude Code，並使用您組織的設備管理或軟體允許清單工具防止在其外部安裝。176* **Custom containers and VMs**：通過批准的映像分發 Claude Code，並使用您組織的設備管理或軟體允許清單工具防止在其外部安裝。

177 177

181 181

182* [Sandboxing](https://code.claude.com/docs/zh-TW/sandboxing.md)：配置內建沙箱化 Bash 工具182* [Sandboxing](https://code.claude.com/docs/zh-TW/sandboxing.md)：配置內建沙箱化 Bash 工具

183* [Dev container](https://code.claude.com/docs/zh-TW/devcontainer.md)：預配置的 Docker 開發容器183* [Dev container](https://code.claude.com/docs/zh-TW/devcontainer.md)：預配置的 Docker 開發容器

184* [Security](https://code.claude.com/docs/zh-TW/security.md)：完整的 Claude Code 安全模型184* [安全性](https://code.claude.com/docs/zh-TW/security.md)：完整的 Claude Code 安全模型

185* [Secure deployment](https://code.claude.com/docs/zh-TW/agent-sdk/secure-deployment.md)：Agent SDK 應用程式的隔離指南185* [安全部署](https://code.claude.com/docs/zh-TW/agent-sdk/secure-deployment.md)：Agent SDK 應用程式的隔離指南

186* [Settings](https://code.claude.com/docs/zh-TW/settings-reference.md#sandbox-settings)：所有沙箱配置金鑰，包括託管設定傳遞186* [設定](https://code.claude.com/docs/zh-TW/settings-reference.md#sandbox-settings)：所有沙箱設定鍵，包括受管設定傳遞

sandboxing.md +26 −2

Details

223* **針對該參數的詢問規則**：為 `Bash(dangerouslyDisableSandbox:true)` 新增一條[詢問規則](https://code.claude.com/docs/zh-TW/permissions.md#match-by-input-parameter)，即可在 Bash 重試時收到提示。在自動模式和 `bypassPermissions` 模式中您也會收到提示，且該規則優先於相符的允許規則223* **針對該參數的詢問規則**：為 `Bash(dangerouslyDisableSandbox:true)` 新增一條[詢問規則](https://code.claude.com/docs/zh-TW/permissions.md#match-by-input-parameter)，即可在 Bash 重試時收到提示。在自動模式和 `bypassPermissions` 模式中您也會收到提示，且該規則優先於相符的允許規則

224* **[`permissions.blockReadsOutsideWorkingDirectories`](https://code.claude.com/docs/zh-TW/settings-reference#permissions-blockreadsoutsideworkingdirectories)**：[任何模式都不會自動核准的動作](https://code.claude.com/docs/zh-TW/permission-modes.md#actions-no-mode-auto-approves)說明了此設定開啟時會提示的重試224* **[`permissions.blockReadsOutsideWorkingDirectories`](https://code.claude.com/docs/zh-TW/settings-reference#permissions-blockreadsoutsideworkingdirectories)**：[任何模式都不會自動核准的動作](https://code.claude.com/docs/zh-TW/permission-modes.md#actions-no-mode-auto-approves)說明了此設定開啟時會提示的重試

225 225

226當命令因 [`Sandbox is required` 訊息](#commands-refused-with-sandbox-is-required)而遭拒時，Claude Code 會忽略 `dangerouslyDisableSandbox` 參數，並同樣拒絕重試。

227

226#### 使用嚴格沙箱模式關閉重試228#### 使用嚴格沙箱模式關閉重試

227 229

228您可以在[沙箱設定](https://code.claude.com/docs/zh-TW/settings-reference.md#sandbox-settings)中設定 `"allowUnsandboxedCommands": false` 來停用非沙箱重試。停用重試後，Claude Code 會忽略 `dangerouslyDisableSandbox` 參數。在沙箱執行期間，Claude 執行的命令除非符合 `excludedCommands` 項目，否則都會被沙箱化。若要在沙箱無法啟動時防止 Claude Code 以非沙箱方式執行命令，請同時設定 [`failIfUnavailable`](https://code.claude.com/docs/zh-TW/settings-reference#sandbox-failifunavailable)。`/sandbox` 的 **Overrides** 分頁會將此設定顯示為 **Strict sandbox mode**。230您可以在[沙箱設定](https://code.claude.com/docs/zh-TW/settings-reference.md#sandbox-settings)中設定 `"allowUnsandboxedCommands": false` 來停用非沙箱重試。停用重試後，Claude Code 會忽略 `dangerouslyDisableSandbox` 參數。在沙箱執行期間，Claude 執行的命令除非符合 `excludedCommands` 項目，否則都會被沙箱化。若要在沙箱無法啟動時防止 Claude Code 以非沙箱方式執行命令，請同時設定 [`failIfUnavailable`](https://code.claude.com/docs/zh-TW/settings-reference#sandbox-failifunavailable)。`/sandbox` 的 **Overrides** 分頁會將此設定顯示為 **Strict sandbox mode**。

899 901

900### 0 位元組唯讀檔案出現在 `.claude` 設定路徑，且「是，不要再問」不會儲存902### 0 位元組唯讀檔案出現在 `.claude` 設定路徑，且「是，不要再問」不會儲存

901 903

902在 Linux 和 WSL2 上，沙箱在沙箱化命令執行時透過在該處建立 0 位元組唯讀預留位置來保持對尚不存在的檔案的寫入拒絕。沙箱在之後移除預留位置。如果在該清理執行之前工作階段被終止，例如透過 SIGKILL，預留位置會保留下來。稍後的工作階段在每次啟動時再次將這些預留位置綁定為唯讀，因此設定寫入（例如儲存權限選擇）會在預留位置所在之處失敗。904在 Linux 和 WSL2 上，沙箱在沙箱化命令執行時透過在該處建立 0 位元組唯讀預留位置來保持對尚不存在的檔案的寫入拒絕。沙箱在之後移除預留位置。

905

906在下列情況中，預留位置會被留下：

907

908* 工作階段在該清理執行之前被終止，例如透過 SIGKILL

909* 工作階段在沙箱化命令仍在執行時結束，例如背景命令

903 910

904在您的終端機中執行 `claude doctor` 以列出剩餘的預留位置檔案。[`Sandbox mask files left behind at write-deny paths`](https://code.claude.com/docs/zh-TW/errors#stale-sandbox-mask-files-left-by-a-killed-session) 警告會列出其中一部分，並計算其餘的數量。在該專案中沒有其他 Claude Code 工作階段執行時，使用 `rm` 刪除每個檔案。在 v2.1.257 之前，Claude Code 會留下相同的預留位置而不標記它們。911稍後的工作階段在每次啟動時再次將這些預留位置綁定為唯讀，因此設定寫入（例如儲存權限選擇）會在仍留有預留位置的路徑上失敗。

912

913在您的終端機中執行 `claude doctor` 以列出剩餘的預留位置檔案。[`Sandbox mask files left behind at write-deny paths`](https://code.claude.com/docs/zh-TW/errors#stale-sandbox-mask-files-left-by-a-killed-session) 警告會列出其中一部分，並計算其餘的數量。在該專案中沒有其他 Claude Code 工作階段執行時，使用 `rm` 刪除每個檔案。在 v2.1.257 之前，Claude Code 在工作階段被終止時會留下相同的預留位置，而不會標記它們。

905 914

906### 啟用沙箱時透過 SSH 執行 `git` 失敗915### 啟用沙箱時透過 SSH 執行 `git` 失敗

907 916

1000 1009

1001在 v2.1.284 之前，代理伺服器會連線到允許的主機名稱所解析到的任何位址。1010在 v2.1.284 之前，代理伺服器會連線到允許的主機名稱所解析到的任何位址。

1002 1011

1012### 命令因 `Sandbox is required` 而被拒絕

1013

1014如果您使用 [`sandbox.failIfUnavailable`](https://code.claude.com/docs/zh-TW/settings-reference#sandbox-failifunavailable) 要求使用沙箱，而沙箱在 Claude Code 啟動後以下列其中一種方式失敗，Claude 執行的每個沙箱化命令都會被拒絕，並顯示所列的訊息。工作階段會繼續執行，而被拒絕的命令不會在沙箱外執行：

1015

1016* **`Sandbox is required but failed to initialize: <reason>`**：Claude Code 已啟動，但沙箱隨後初始化失敗。請採取訊息所提供的步驟：`Restart to retry.` 或 `Fix the sandbox settings to retry`。

1017* **`Sandbox is required (sandbox.failIfUnavailable) and stopped being available in this session: <reason>`**：在 Linux 或 WSL2 上，沙箱已啟動，之後 Claude Code 發現缺少某個相依套件。請修正原因所指出的問題，例如[安裝缺少的相依套件](#set-up-linux-and-wsl2)，然後重新啟動 Claude Code。

1018

1019被排除的命令和您自行輸入的命令會繼續執行，而 Claude 無法在沙箱外重試被拒絕的命令：

1020

1021* **被排除的命令**：符合 [`excludedCommands`](#run-commands-outside-the-sandbox-with-excludedcommands) 項目的命令會繼續在沙箱外執行。當其中一個命令寫入您工作目錄外的 [`filesystem.allowWrite`](https://code.claude.com/docs/zh-TW/settings-reference#sandbox-filesystem-allowwrite) 路徑時，該寫入會經過一般的權限流程。在[管理員強制要求的沙箱](#repository-settings-under-an-admin-required-sandbox)下，Claude Code 會忽略來自儲存庫設定的項目

1022* **您在 [`!` shell 模式提示字元](https://code.claude.com/docs/zh-TW/interactive-mode#shell-mode-with-prefix)輸入的命令**：會繼續在沙箱外執行。在[背景工作階段](https://code.claude.com/docs/zh-TW/agent-view.md)中，它們也會被拒絕

1023* **非沙箱重試**：Claude Code 會忽略[非沙箱重試](#the-unsandboxed-retry-escape-hatch)的 `dangerouslyDisableSandbox` 參數

1024

1025在設定了 `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` 的 Linux 工作階段中，每個命令都會在沙箱中執行，因此被排除的命令和您輸入的命令也會被拒絕。

1026

1003### `/sandbox` 因 `Sandbox settings are overridden by a higher-priority configuration` 而失敗1027### `/sandbox` 因 `Sandbox settings are overridden by a higher-priority configuration` 而失敗

1004 1028

1005當較高的[設定層級](https://code.claude.com/docs/zh-TW/settings.md#settings-precedence)設定了 `sandbox.enabled`、`sandbox.autoAllowBashIfSandboxed` 或 `sandbox.allowUnsandboxedCommands` 時，`/sandbox` 會印出 `Error: Sandbox settings are overridden by a higher-priority configuration and cannot be changed locally.`，而不會開啟其面板。該面板會將您的選擇儲存到 `.claude/settings.local.json`，而儲存在那裡的值無法覆寫那些層級。1029當較高的[設定層級](https://code.claude.com/docs/zh-TW/settings.md#settings-precedence)設定了 `sandbox.enabled`、`sandbox.autoAllowBashIfSandboxed` 或 `sandbox.allowUnsandboxedCommands` 時，`/sandbox` 會印出 `Error: Sandbox settings are overridden by a higher-priority configuration and cannot be changed locally.`，而不會開啟其面板。該面板會將您的選擇儲存到 `.claude/settings.local.json`，而儲存在那裡的值無法覆寫那些層級。

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

Details

783 783

784關於這些來源的套用順序，請參閱[設定優先順序](https://code.claude.com/docs/zh-TW/settings.md#settings-precedence)。784關於這些來源的套用順序，請參閱[設定優先順序](https://code.claude.com/docs/zh-TW/settings.md#settings-precedence)。

785 785

786當 Anthropic 的控制平面為工作階段提供 [Claude Code hook](https://code.claude.com/docs/zh-TW/hooks.md) 時，執行器會將其與您自己的設定並存安裝，而非覆寫您的設定。需要 Claude Code v2.1.229 或更新版本。786當 Anthropic 的控制平面為工作階段提供 [Claude Code hook](https://code.claude.com/docs/zh-TW/hooks.md) 時，執行器會將其與您自己的設定並存安裝，而非覆寫您的設定。需要 Claude Code v2.1.229 或更新版本；較舊的執行器會忽略提供的 hook。提供的 hook 會執行 `python3`，因此請在您的[執行器映像](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#build-the-runner-image)中安裝 `python3`。

787 787

788* **放置位置**：執行器會將每個提供的 hook 指令碼寫入工作階段設定目錄中保留的 `hooks/.ccr-launcher/` 子目錄，並在一個獨立的設定檔中註冊這些指令碼，再透過 `--settings` 將該檔案傳遞給工作階段，而植入的 `settings.json` 和您位於 `hooks/<name>` 的指令碼則保持不變。執行器會為每個工作階段重新建立該保留子目錄，且不會將主機上 `~/.claude/hooks/.ccr-launcher/` 的內容植入工作階段。788* **放置位置**：執行器會將每個提供的 hook 指令碼寫入工作階段設定目錄中保留的 `hooks/.ccr-launcher/` 子目錄，並在一個獨立的設定檔中註冊這些指令碼，再透過 `--settings` 將該檔案傳遞給工作階段，而植入的 `settings.json` 和您位於 `hooks/<name>` 的指令碼則保持不變。執行器會為每個工作階段重新建立該保留子目錄，且不會將主機上 `~/.claude/hooks/.ccr-launcher/` 的內容植入工作階段。

789* **撰寫者**：控制平面以其自身部署中的固定常數填入這些指令碼，絕不來自個別工作階段或第三方輸入。789* **撰寫者**：控制平面以其自身部署中的固定常數填入這些指令碼，絕不來自個別工作階段或第三方輸入。

self-hosted-environments-deploy.md +5 −3

Details

348 348

349下面的配方使用 `--capacity 4`，因此一個容器服務來自同一鎖定所有者的最多四個並發工作階段。這不提供[強化部分](#harden-your-deployment)中的每個工作階段容器隔離：在將環境連接到生產系統之前，要麼以 `--capacity 1` 執行配方，每個工作階段一個容器，要麼使用[按需執行器](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration.md#on-demand-runners)，它也將環境祕密保留在執行工作階段的主機之外。如果您將[Anthropic git 代理](#use-the-anthropic-git-proxy)新增至其中一個配方，也請將 `--capacity` 變更為 `1`。349下面的配方使用 `--capacity 4`，因此一個容器服務來自同一鎖定所有者的最多四個並發工作階段。這不提供[強化部分](#harden-your-deployment)中的每個工作階段容器隔離：在將環境連接到生產系統之前，要麼以 `--capacity 1` 執行配方，每個工作階段一個容器，要麼使用[按需執行器](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration.md#on-demand-runners)，它也將環境祕密保留在執行工作階段的主機之外。如果您將[Anthropic git 代理](#use-the-anthropic-git-proxy)新增至其中一個配方，也請將 `--capacity` 變更為 `1`。

350 350

351此 Dockerfile 是一個最小的起點：351此 Dockerfile 是一個最小的起點。它安裝 `python3`，因為 [Anthropic 控制平面提供](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration.md#how-each-session’s-config-is-assembled)給 Claude Tag 工作階段的 hook（包括讓 Claude 在 Slack 中發佈回覆的 hook）會執行 `python3`。在任何服務 Claude Tag 工作階段的映像中，請將 `python3` 保留在 `PATH` 上：

352 352

353```dockerfile theme={null}353```dockerfile theme={null}

354FROM debian:bookworm-slim354FROM debian:bookworm-slim

355ARG CLAUDE_CODE_VERSION355ARG CLAUDE_CODE_VERSION

356RUN apt-get update && apt-get install -y --no-install-recommends git curl ca-certificates openssh-client jq \356RUN apt-get update && apt-get install -y --no-install-recommends git curl ca-certificates openssh-client jq python3 \

357 && rm -rf /var/lib/apt/lists/*357 && rm -rf /var/lib/apt/lists/*

358RUN curl -fsSL "https://downloads.claude.ai/claude-code-releases/${CLAUDE_CODE_VERSION:?set with --build-arg CLAUDE_CODE_VERSION}/linux-x64/claude" \358RUN curl -fsSL "https://downloads.claude.ai/claude-code-releases/${CLAUDE_CODE_VERSION:?set with --build-arg CLAUDE_CODE_VERSION}/linux-x64/claude" \

359 -o /usr/local/bin/claude && chmod +x /usr/local/bin/claude359 -o /usr/local/bin/claude && chmod +x /usr/local/bin/claude

363ENTRYPOINT ["claude"]363ENTRYPOINT ["claude"]

364```364```

365 365

366如果您的節點是 ARM，將 `linux-x64` 交換為 `linux-arm64`，或在 Alpine 等 musl 基礎映像上交換為 `linux-x64-musl` 或 `linux-arm64-musl`；請參閱 [Alpine Linux 設定](https://code.claude.com/docs/zh-TW/setup.md#alpine-linux-and-musl-based-distributions)以了解 musl 映像需要的額外套件。URL 是標準 Claude Code 發佈位置，因此您可以根據[二進位檔案完整性和程式碼簽名](https://code.claude.com/docs/zh-TW/setup.md#binary-integrity-and-code-signing)中描述的發佈的已簽名清單驗證下載的二進位檔案。執行器需要 Claude Code 版本 2.1.224 或更新版本。構建映像，然後將其推送到您的登錄檔並在下面的配方中引用它：366如果您的節點是 ARM，將 `linux-x64` 交換為 `linux-arm64`，或在 Alpine 等 musl 基礎映像上交換為 `linux-x64-musl` 或 `linux-arm64-musl`；請參閱 [Alpine Linux 設定](https://code.claude.com/docs/zh-TW/setup.md#alpine-linux-and-musl-based-distributions)以了解 musl 映像需要的額外套件。URL 是標準 Claude Code 發佈位置，因此您可以根據[二進位檔案完整性和程式碼簽名](https://code.claude.com/docs/zh-TW/setup.md#binary-integrity-and-code-signing)中描述的發佈的已簽名清單驗證下載的二進位檔案。執行器需要 Claude Code 版本 2.1.224 或更新版本，若要服務 Claude Tag 工作階段則需要 2.1.229 或更新版本。建置映像，然後將其推送到您的登錄檔並在下面的配方中引用它：

367 367

368```bash theme={null}368```bash theme={null}

369docker build \369docker build \

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

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

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

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

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

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

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

824 Runner 升級或原因修正後，請重試該工作階段或啟動新的工作階段。如果以上檢查都找不到原因，請[回報問題](#report-an-issue)。825 Runner 升級或原因修正後，請重試該工作階段或啟動新的工作階段。如果以上檢查都找不到原因，請[回報問題](#report-an-issue)。

825 826

826 對於工作階段推送結果的來源，已刪除的分支會使工作階段失敗。對於工作階段只讀取的 git 來源，runner 會略過該來源並繼續處理其餘來源。當略過會使工作階段完全沒有儲存庫時，runner 會使工作階段失敗。在 v2.1.228 之前，這類工作階段會在空目錄中啟動。827 對於工作階段推送結果的來源，已刪除的分支會使工作階段失敗。對於工作階段只讀取的 git 來源，runner 會略過該來源並繼續處理其餘來源。當略過會使工作階段完全沒有儲存庫時，runner 會使工作階段失敗。在 v2.1.228 之前，這類工作階段會在空目錄中啟動。

828* **Claude Tag 有時不會在 Slack 中張貼其回覆**：回覆提醒是[控制平面所提供的 hook](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration.md#how-each-session’s-config-is-assembled)。請以 `claude --version` 確認 runner 為 Claude Code v2.1.229 或更新版本，因為較舊的 runner 會忽略所提供的 hook；確認 `python3 --version` 能在 runner 映像中成功執行，因為這些 hook 會執行 `python3`；並確認沒有任何設定檔關閉 hook，無論是 `managed-settings.json`、runner 使用者的 `~/.claude/settings.json`，或儲存庫的 `.claude/settings.json` 或 `.claude/settings.local.json` 中的 `disableAllHooks`，或是受管設定中的 `allowManagedHooksOnly` 或涵蓋 hook 的 [`strictPluginOnlyCustomization`](https://code.claude.com/docs/zh-TW/settings-reference#strictpluginonlycustomization)。

827* **工作階段啟動時缺少其中一個儲存庫**：在沒有 [`checkout` hook](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration#checkout) 的 runner 上，git 主機可能會拒絕 runner 對工作階段只讀取之儲存庫的存取檢查。Runner 接著會略過該儲存庫，記錄一行指名該拒絕的 `[runner:warn] could not access context source`，並以其餘儲存庫啟動工作階段。829* **工作階段啟動時缺少其中一個儲存庫**：在沒有 [`checkout` hook](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration#checkout) 的 runner 上，git 主機可能會拒絕 runner 對工作階段只讀取之儲存庫的存取檢查。Runner 接著會略過該儲存庫，記錄一行指名該拒絕的 `[runner:warn] could not access context source`，並以其餘儲存庫啟動工作階段。

828 830

829 Runner 只會略過明確的拒絕：主機回應找不到儲存庫、git 找不到該主機的憑證，或身分驗證失敗。網路故障、逾時或 HTTP `403` 仍會使工作階段啟動失敗，對工作階段推送結果之儲存庫的拒絕也是如此。對於略過會使其完全沒有儲存庫的工作階段，runner 仍會使其失敗。使用 [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy) 時，runner 只會略過 git 代理伺服器本身拒絕的儲存庫。831 Runner 只會略過明確的拒絕：主機回應找不到儲存庫、git 找不到該主機的憑證，或身分驗證失敗。網路故障、逾時或 HTTP `403` 仍會使工作階段啟動失敗，對工作階段推送結果之儲存庫的拒絕也是如此。對於略過會使其完全沒有儲存庫的工作階段，runner 仍會使其失敗。使用 [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy) 時，runner 只會略過 git 代理伺服器本身拒絕的儲存庫。

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

Details

35 35

36在啟動之前在主機上安裝：36在啟動之前在主機上安裝：

37 37

38* **Claude Code v2.1.224 或更新版本**，使用任何[標準安裝方法](https://code.claude.com/docs/zh-TW/setup.md)。執行器是標準 `claude` 二進位檔的一部分，較早版本無法識別 `self-hosted-runner` 子命令。若要固定您的艦隊執行的確切版本，請參閱[安裝特定版本](https://code.claude.com/docs/zh-TW/setup.md#install-a-specific-version)。對於容器映像，請參閱[部署到生產環境](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#build-the-runner-image)中的 Dockerfile。38* **Claude Code v2.1.224 或更新版本**，使用任何[標準安裝方法](https://code.claude.com/docs/zh-TW/setup.md)。執行器是標準 `claude` 二進位檔的一部分，較早版本無法識別 `self-hosted-runner` 子命令。為 Claude Tag 工作階段提供服務的執行器需要 v2.1.229 或更新版本，且其 `PATH` 上需有 `python3`，因為[控制平面為這些工作階段提供的 hook](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration.md#how-each-session’s-config-is-assembled) 會執行 `python3`。若要固定您的艦隊執行的確切版本，請參閱[安裝特定版本](https://code.claude.com/docs/zh-TW/setup.md#install-a-specific-version)。對於容器映像，請參閱[部署到生產環境](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#build-the-runner-image)中的 Dockerfile。

39* **Git 2.24 或更新版本**。部署頁面上的某些 git 選項需要較新的版本；[設定 git](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#configure-git)說明每個下限。39* **Git 2.24 或更新版本**。部署頁面上的某些 git 選項需要較新的版本；[設定 git](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#configure-git)說明每個下限。

40 40

41確認主機已準備好：41確認主機已準備好：

self-hosted-environments-reference.md +21 −4

Details

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

53| `--server-auto-mode-lists <mode>` | `SELF_HOSTED_RUNNER_SERVER_AUTO_MODE_LISTS` | `no-allow` | 控制平面隨工作階段傳送的[自動模式](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode)分類器規則清單中，哪些可以送達該工作階段：`all`、`no-allow` 或 `none`。請參閱[自動模式規則清單](#auto-mode-rule-lists)以了解每個值套用的內容。無效的值會使執行器在啟動時停止。需要 Claude Code v2.1.295 或更新版本。 |53| `--server-auto-mode-lists <mode>` | `SELF_HOSTED_RUNNER_SERVER_AUTO_MODE_LISTS` | `no-allow` | 控制平面隨工作階段傳送的[自動模式](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode)分類器規則清單中，哪些可以送達該工作階段：`all`、`no-allow` 或 `none`。請參閱[自動模式規則清單](#auto-mode-rule-lists)以了解每個值套用的內容。無效的值會使執行器在啟動時停止。需要 Claude Code v2.1.295 或更新版本。 |

55| `--startup-timeout-min <n>` | `SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS` | `15` | 如果子程序未在 N 分鐘內於[活動頻道](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration.md#keep-stdin-and-file-descriptor-3-attached)上發出已完成初始化的信號，則釋放工作階段槽。這 N 分鐘從產生時（複製之後）開始計算，並在子程序完成初始化或回報其狀態之前，每發出一則 `user` 或 `assistant` 訊息時重新計算。在 v2.1.299 之前，此逾時會在工作階段的第一則此類訊息時停止適用。關於初始化信號之後的釋放，請參閱 `--release-idle-session-min`。`0` 停用。 |55| `--startup-timeout-min <n>` | `SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS` | `15` | 在釋放工作階段槽之前，等待尚未完成初始化的子程序的時間。請參閱[工作階段啟動逾時](#session-startup-timeout)以了解計時從何時開始，以及哪些工作階段會繼續執行。`0` 停用逾時。 |

56| `--trust-workspace [bool]` | `SELF_HOSTED_RUNNER_TRUST_WORKSPACE` | 開啟 | 為每個工作階段的存放庫路徑播種持久化信任，以便尊重存放庫提交的 `permissions.allow` 和 `additionalDirectories`。設定 `false` 以放棄存放庫提交的權限授予，並改為在主機設定的 `settings.json` 中配置允許規則；存放庫提交的 `sandbox.*` 設定無論如何仍然適用，這就是為什麼[存放庫設定防護](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#harden-your-deployment)無論此旗標如何都掃描它們。 |56| `--trust-workspace [bool]` | `SELF_HOSTED_RUNNER_TRUST_WORKSPACE` | 開啟 | 為每個工作階段的存放庫路徑播種持久化信任，以便尊重存放庫提交的 `permissions.allow` 和 `additionalDirectories`。設定 `false` 以放棄存放庫提交的權限授予，並改為在主機設定的 `settings.json` 中配置允許規則；存放庫提交的 `sandbox.*` 設定無論如何仍然適用，這就是為什麼[存放庫設定防護](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#harden-your-deployment)無論此旗標如何都掃描它們。 |

57| `--use-anthropic-git-proxy` | `CLAUDE_RUNNER_USE_GIT_PROXY=1` | 關閉 | 透過 [Anthropic git proxy](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#use-the-anthropic-git-proxy) 複製 github.com 上的儲存庫，而不是使用客戶管理的 git 驗證。需要 `--capacity 1` 和 git 2.32 或更新版本；否則執行器拒絕啟動。取代重寫旗標。 |57| `--use-anthropic-git-proxy` | `CLAUDE_RUNNER_USE_GIT_PROXY=1` | 關閉 | 透過 [Anthropic git proxy](https://code.claude.com/docs/zh-TW/self-hosted-environments-deploy.md#use-the-anthropic-git-proxy) 複製 github.com 上的儲存庫，而不是使用客戶管理的 git 驗證。需要 `--capacity 1` 和 git 2.32 或更新版本；否則執行器拒絕啟動。取代重寫旗標。 |

58 58

61* **旗標**：啟動失敗並出現錯誤。61* **旗標**：啟動失敗並出現錯誤。

62* **環境變數**：執行器將值夾住到計時器上限，而不是拒絕它。62* **環境變數**：執行器將值夾住到計時器上限，而不是拒絕它。

63 63

64### 工作階段啟動逾時

66如果工作階段在 `/code-review` 等回合期間失去了其槽，請將執行器和子程序的二進位檔更新至 v2.1.309 或更新版本。從 v2.1.299 到 v2.1.308，一旦啟動逾時經過而沒有出現 `user` 或 `assistant` 訊息，執行器就會釋放工作階段，即使在回合進行中也是如此。

68使用 `--startup-timeout-min <n>` 時，如果子程序在複製後 `<n>` 分鐘內尚未完成初始化，執行器會釋放工作階段的槽。在子程序完成初始化之前開始的回合期間，工作階段會保留其槽，直到子程序的[活動頻道](https://code.claude.com/docs/zh-TW/self-hosted-environments-configuration.md#keep-stdin-and-file-descriptor-3-attached)上經過 `<n>` 分鐘都沒有任何一行輸出為止。子程序完成初始化後，執行器會清除該計時，並改由 `--release-idle-session-min` 控制釋放。若要限制子程序仍存活但已卡住的工作階段，請設定 `--kill-session-after-min`。

64### 自動模式規則清單70### 自動模式規則清單

65 71

66`--server-auto-mode-lists` 讓您決定哪些來自執行器外部的[自動模式](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode)分類器規則可以送達您執行器上的工作階段。Anthropic 的控制平面可以隨工作階段傳送規則清單，並要求執行器套用它們。其中某些項目可能是您組織的管理員所撰寫的規則。這些清單為 `environment`、`soft_deny` 和 `allow`：72`--server-auto-mode-lists` 讓您決定哪些來自執行器外部的[自動模式](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode)分類器規則可以送達您執行器上的工作階段。Anthropic 的控制平面可以隨工作階段傳送規則清單，並要求執行器套用它們。其中某些項目可能是您組織的管理員所撰寫的規則。這些清單為 `environment`、`soft_deny` 和 `allow`：

373 379

374#### 將工作階段的指標與執行器的指標聯結380#### 將工作階段的指標與執行器的指標聯結

375 381

376若要將工作階段自己的指標放在 `claude_code_self_hosted_runner_session_idle_seconds` 旁邊，請依執行器的 `session_id` 進行聯結：382若要查看閒置工作階段的成本，請依 `ccr_session_id` 將執行器的 `claude_code_self_hosted_runner_session_idle_seconds` 與 Claude Code 的成本指標聯結。執行器的指標不帶有該標籤，因此請使用 `label_replace` 為其加上該標籤，如以下查詢所示：

383

384```text theme={null}

385sum by (ccr_session_id) (claude_code_cost_usage_total)

386and on (ccr_session_id)

387label_replace(

388 claude_code_self_hosted_runner_session_idle_seconds > 600,

389 "ccr_session_id", "cse_$1", "session_id", "session_(.*)"

390)

391```

392

393此查詢會為每個閒置超過十分鐘的工作階段傳回一個結果：其 Claude Code 程序到目前為止計算的成本（以美元計）。若要聯結其他 Claude Code 指標，請取代查詢中的 `claude_code_cost_usage_total`。此查詢在任何 `--capacity` 下皆可運作。

377 394

378* **在 `--capacity` 高於 1 時**：直接聯結。在執行器的 `/metrics` 上，工作階段的序列攜帶與該指標相同的 `session_id`，採用 `session_...` 形式。395* **`session_id`**：在連接埠 9464 上，Claude Code 指標上的該標籤包含 Claude Code 自己的 [`session.id`](https://code.claude.com/docs/zh-TW/monitoring-usage#standard-attributes)，不符合任何執行器序列。依此標籤聯結不會傳回任何結果，因此請依 `ccr_session_id` 聯結。

379* **在 `--capacity 1` 時**：依轉換後的 `ccr_session_id` 聯結。預設情況下，連接埠 9464 上的每個 Claude Code 指標都攜帶該標籤，其中包含 `cse_...` 形式的工作階段 ID。在新標籤中，將其 `cse_` 前綴替換為 `session_`，即可取得執行器的 `session_id`。該指標自己的 `session_id` 包含 Claude Code 自己的 [`session.id`](https://code.claude.com/docs/zh-TW/monitoring-usage#standard-attributes)，不符合任何執行器序列。396* **Claude Code 指標沒有 `ccr_session_id`**：請確認 [`OTEL_METRICS_INCLUDE_SESSION_ID`](https://code.claude.com/docs/zh-TW/monitoring-usage#metrics-cardinality-control) 未設定為 `false`

380 397

381### 工作階段生命週期計數器語義398### 工作階段生命週期計數器語義

382 399

settings-reference.md +24 −7

Details

1229在沙箱不支援的平台上，開啟此鍵時 Claude Code 不會啟動。請參閱[使用受管設定強制執行沙箱機制](https://code.claude.com/docs/zh-TW/sandboxing.md#enforce-sandboxing-with-managed-settings)。1229在沙箱不支援的平台上，開啟此鍵時 Claude Code 不會啟動。請參閱[使用受管設定強制執行沙箱機制](https://code.claude.com/docs/zh-TW/sandboxing.md#enforce-sandboxing-with-managed-settings)。

1230 1230

1231* **範圍**：[`Any file`](#scopes)，但[對專案和本機設定有所限制](https://code.claude.com/docs/zh-TW/sandboxing.md#repository-settings-under-an-admin-required-sandbox)1231* **範圍**：[`Any file`](#scopes)，但[對專案和本機設定有所限制](https://code.claude.com/docs/zh-TW/sandboxing.md#repository-settings-under-an-admin-required-sandbox)

1232* **類型**：布林值1232* **類型**：Boolean

1233 * `true`：當 `sandbox.enabled` 為 `true` 但沙箱無法啟動時，Claude Code 會在啟動時以錯誤結束1233 * `true`：當 `sandbox.enabled` 為 `true` 但沙箱無法啟動時，Claude Code 會在啟動時以錯誤結束。若沙箱通過該檢查後初始化失敗，工作階段會繼續執行，而 Claude Code 會[拒絕每個沙箱化命令](https://code.claude.com/docs/zh-TW/sandboxing.md#commands-refused-with-sandbox-is-required)

1234 * `false`：當沙箱無法啟動時，Claude Code 會在沙箱外執行命令1234 * `false`：當沙箱無法啟動時，Claude Code 會在沙箱外執行命令

1235* **預設值**：`false`1235* **預設值**：`false`

1236 1236

1237以下設定會讓每台受管機器都將命令沙箱化，否則拒絕啟動：1237以下設定會為受管機器開啟沙箱，並將 `failIfUnavailable` 設為 `true`：

1238 1238

1239```json managed-settings.json theme={null}1239```json managed-settings.json theme={null}

1240{1240{

2415 2415

2416### `idleCompaction`2416### `idleCompaction`

2417 2417

2418閒置壓縮會在您已離開的長對話的提示快取到期前不久，[壓縮](https://code.claude.com/docs/zh-TW/context-window.md#what-survives-compaction)該對話。接著您的下一則訊息會傳送摘要，而不是整個對話。當您回來時，對話會顯示一行以 `Compacted while idle, before the prompt cache expired` 開頭的訊息。2418閒置壓縮會[壓縮](https://code.claude.com/docs/zh-TW/context-window.md#what-survives-compaction)您已離開的長對話。接著您的下一則訊息會傳送摘要，而不是整個對話。壓縮完成後，對話會顯示一則通知：

2419

2420* **終端機**：一行以 `Compacted while idle, before the prompt cache expired` 開頭的訊息

2421* **[VS Code 聊天面板](#idle-compaction-in-vs-code-and-the-desktop-app)**：包含 `a summary written while you were away` 的通知

2422* **[桌面應用程式](#idle-compaction-in-vs-code-and-the-desktop-app)**：相同的通知，位於標籤包含 `Claude Code notice` 的列中。如果您沒有看到該列或其文字，請切換到 [Verbose 檢視模式](https://code.claude.com/docs/zh-TW/desktop.md#switch-view-modes)。

2419 2423

2420對於符合以下所有條件的對話，閒置壓縮預設為開啟：2424對於符合以下所有條件的對話，閒置壓縮預設為開啟：

2421 2425

2422* **工作階段**：您處於互動式終端機工作階段中2426* **工作階段**：您處於互動式終端機工作階段中，或是在 [Anthropic 選定的帳戶](#idle-compaction-in-vs-code-and-the-desktop-app)上使用 VS Code 擴充功能的聊天面板或桌面應用程式的 Code 分頁

2423* **自動壓縮**：[`autoCompactEnabled`](#autocompactenabled) 已開啟2427* **自動壓縮**：[`autoCompactEnabled`](#autocompactenabled) 已開啟

2424* **提示快取**：對話使用[一小時提示快取 TTL](https://code.claude.com/docs/zh-TW/prompt-caching.md#which-ttl-each-request-gets)2428* **提示快取**：對話使用[一小時提示快取 TTL](https://code.claude.com/docs/zh-TW/prompt-caching.md#which-ttl-each-request-gets)

2425* **功能旗標**：Claude Code 可以[從 Anthropic 擷取功能旗標](https://code.claude.com/docs/zh-TW/env-vars.md#features-that-need-feature-flag-fetching)2429* **功能旗標**：Claude Code 可以[從 Anthropic 擷取功能旗標](https://code.claude.com/docs/zh-TW/env-vars.md#features-that-need-feature-flag-fetching)

2441}2445}

2442```2446```

2443 2447

2444若要在工作階段內關閉或開啟閒置壓縮，請執行 `/config` 並變更**閒置壓縮**列。您的選擇會儲存到您的使用者設定並立即套用。此列需要 Claude Code v2.1.302 或更高版本。如果您執行的是這些版本之一，但 `/config` 未顯示此列，請檢查以下原因：2448若要在終端機工作階段內關閉或開啟閒置壓縮，請執行 `/config` 並變更**閒置壓縮**列。您的選擇會儲存到您的使用者設定並立即套用。此列需要 Claude Code v2.1.302 或更高版本。如果您執行的是這些版本之一，但 `/config` 未顯示此列，請檢查以下原因：

2445 2449

2446* **另一個設定來源設定了此鍵**：受管設定、`--settings` 旗標，或專案或本機設定檔中的值會覆寫您的使用者設定。請改為在該來源中變更此鍵2450* **另一個設定來源設定了此鍵**：受管設定、`--settings` 旗標，或專案或本機設定檔中的值會覆寫您的使用者設定。請改為在該來源中變更此鍵

2447* **功能旗標無法使用**：在 Claude Code 無法[從 Anthropic 擷取功能旗標](https://code.claude.com/docs/zh-TW/env-vars.md#features-that-need-feature-flag-fetching)的情況下，閒置壓縮不會執行，因此沒有可關閉的內容2451* **功能旗標無法使用**：在 Claude Code 無法[從 Anthropic 擷取功能旗標](https://code.claude.com/docs/zh-TW/env-vars.md#features-that-need-feature-flag-fetching)的情況下，閒置壓縮不會執行，因此沒有可關閉的內容

2462}2466}

2463```2467```

2464 2468

2469#### VS Code 與桌面應用程式中的閒置壓縮

2470

2471類似以下的通知表示 Claude Code 已[將您先前的對話替換為摘要](https://code.claude.com/docs/zh-TW/context-window.md#what-survives-compaction)，Claude 現在會以該摘要為基礎繼續工作：

2472

2473```text theme={null}

2474Compacted using a summary written while you were away · turn off with "idleCompaction": false in settings.json

2475```

2476

2477您不需要採取任何動作。若要關閉閒置壓縮，請在 `~/.claude/settings.json` 或其他[設定檔](https://code.claude.com/docs/zh-TW/settings.md#settings-files-and-who-they-affect)中將 `idleCompaction` 設定為 `false`。

2478

2479在 VS Code 擴充功能的聊天面板和桌面應用程式的 Code 分頁中，閒置壓縮會針對 Anthropic 選定的帳戶執行。Claude Code 會在您離開期間撰寫摘要，然後只有在您的下一則訊息距離上次請求一小時或更久時，才會使用該摘要進行壓縮。

2480

2465### `plansDirectory`2481### `plansDirectory`

2466 2482

2467選擇 Claude Code 在 [plan mode](https://code.claude.com/docs/zh-TW/permission-modes.md#analyze-before-you-edit-with-plan-mode) 中寫入的計畫檔案的儲存位置。Claude Code 相對於專案根目錄解析路徑。2483選擇 Claude Code 在 [plan mode](https://code.claude.com/docs/zh-TW/permission-modes.md#analyze-before-you-edit-with-plan-mode) 中寫入的計畫檔案的儲存位置。Claude Code 相對於專案根目錄解析路徑。

3522 3538

3523* **受管和 SDK hook 執行**：來自受管設定的 hook，以及 [Agent SDK](https://code.claude.com/docs/zh-TW/agent-sdk/overview.md) 在程序中註冊的 hook3539* **受管和 SDK hook 執行**：來自受管設定的 hook，以及 [Agent SDK](https://code.claude.com/docs/zh-TW/agent-sdk/overview.md) 在程序中註冊的 hook

3524* **強制啟用的外掛 hook 執行**：來自您的受管設定透過 [`enabledPlugins`](#enabledplugins) 強制啟用之外掛的 hook。Claude Code 以完整的 `plugin@marketplace` ID 進行比對，因此來自不同市集的同名外掛仍會被阻止。這讓您可以透過組織市集分發經過審核的 hook，同時阻止其他所有內容。此類外掛中的 [mod](https://code.claude.com/docs/zh-TW/plugins/mods/overview.md) 只有在[被視為您組織的 mod](https://code.claude.com/docs/zh-TW/plugins/mods/admin.md#install-your-organizations-mods) 時才會載入3540* **強制啟用的外掛 hook 執行**：來自您的受管設定透過 [`enabledPlugins`](#enabledplugins) 強制啟用之外掛的 hook。Claude Code 以完整的 `plugin@marketplace` ID 進行比對，因此來自不同市集的同名外掛仍會被阻止。這讓您可以透過組織市集分發經過審核的 hook，同時阻止其他所有內容。此類外掛中的 [mod](https://code.claude.com/docs/zh-TW/plugins/mods/overview.md) 只有在[被視為您組織的 mod](https://code.claude.com/docs/zh-TW/plugins/mods/admin.md#install-your-organizations-mods) 時才會載入

3541* **來自其他外掛的監視器被阻止**：除非外掛被強制啟用，否則外掛的[監視器](https://code.claude.com/docs/zh-TW/plugins/components.md#monitors)不會啟動。需要 Claude Code v2.1.310 或更新版本

3525* **其他所有內容被阻止**：使用者、專案和本機 hook、來自其他已安裝外掛的 hook 和 mod，以及在 agent frontmatter 中宣告的 hook。[內建於 Claude Code 的 mod](https://code.claude.com/docs/zh-TW/plugins/mods/overview.md#mods-built-into-claude-code) 會繼續執行。若只要阻止使用者的 mod，請改為設定 [`allowManagedModsOnly`](https://code.claude.com/docs/zh-TW/plugins/mods/admin#set-options-on-the-built-in-guard)。3542* **其他所有內容被阻止**：使用者、專案和本機 hook、來自其他已安裝外掛的 hook 和 mod，以及在 agent frontmatter 中宣告的 hook。[內建於 Claude Code 的 mod](https://code.claude.com/docs/zh-TW/plugins/mods/overview.md#mods-built-into-claude-code) 會繼續執行。若只要阻止使用者的 mod，請改為設定 [`allowManagedModsOnly`](https://code.claude.com/docs/zh-TW/plugins/mods/admin#set-options-on-the-built-in-guard)。

3526* **命令來源的外掛被停用**：Claude Code 也會停用具有 [`command` 來源](https://code.claude.com/docs/zh-TW/plugins/marketplace-reference#command-plugin-source)的外掛，包括在受管 `enabledPlugins` 中強制啟用的外掛，除非您明確將 [`disableCommandPluginSources`](#disablecommandpluginsources) 設定為 `false`3543* **命令來源的外掛被停用**：Claude Code 也會停用具有 [`command` 來源](https://code.claude.com/docs/zh-TW/plugins/marketplace-reference#command-plugin-source)的外掛，包括在受管 `enabledPlugins` 中強制啟用的外掛，除非您明確將 [`disableCommandPluginSources`](#disablecommandpluginsources) 設定為 `false`

3527* **市集 `headersHelper` 命令被阻止**：Claude Code 也會阻止市集 [`headersHelper` 命令](https://code.claude.com/docs/zh-TW/plugins/host-marketplace#authenticate-archive-downloads)，除非 [`disableCommandPluginSources`](#disablecommandpluginsources) 明確設定為 `false`，但受管設定本身宣告的市集除外。需要 Claude Code v2.1.238 或更新版本3544* **市集 `headersHelper` 命令被阻止**：Claude Code 也會阻止市集 [`headersHelper` 命令](https://code.claude.com/docs/zh-TW/plugins/host-marketplace#authenticate-archive-downloads)，除非 [`disableCommandPluginSources`](#disablecommandpluginsources) 明確設定為 `false`，但受管設定本身宣告的市集除外。需要 Claude Code v2.1.238 或更新版本

statusline.md +100 −100

Details

167 167

168## 可用資料168## 可用資料

169 169

170Claude Code 透過 stdin 將以下 JSON 欄位傳送到您的指令碼：170Claude Code 會透過 stdin 將下列 JSON 欄位傳送給您的指令碼：

171 171

172| 欄位 | 描述 |172| 欄位 | 說明 |

173| - | - |173| - | - |

178| `workspace.git_worktree` | 當目前目錄位於使用 `git worktree add` 建立的連結 worktree 內時的 Git worktree 名稱。在主工作樹中不存在。對任何 git worktree 都會填入，不同於 `worktree.*` 僅在 [worktree 工作階段](https://code.claude.com/docs/zh-TW/worktrees.md)期間出現 |178| `workspace.git_worktree` | 當目前目錄位於以 `git worktree add` 建立的連結 worktree 內時的 Git worktree 名稱。在主要工作樹中不存在。任何 git worktree 都會填入此欄位，這點與 `worktree.*` 不同，後者僅在工作階段處於 [worktree 工作階段](https://code.claude.com/docs/zh-TW/worktrees.md) 時才會出現 |

179| `workspace.repo.host`, `workspace.repo.owner`, `workspace.repo.name` | 從 `origin` 遠端解析的儲存庫身分，例如 `"github.com"`、`"anthropics"`、`"claude-code"`。在 git 儲存庫外或未設定 `origin` 遠端時不存在。對於巢狀在子群組中的 gitlab.com 專案，`owner` 是包含斜線的完整命名空間路徑，例如 `"group/subgroup"`。在 v2.1.260 之前，這些專案的 `workspace.repo` 不存在 |179| `workspace.repo.host`, `workspace.repo.owner`, `workspace.repo.name` | 從 `origin` 遠端解析出的儲存庫身分，例如 `"github.com"`、`"anthropics"`、`"claude-code"`。在 git 儲存庫之外或未設定 `origin` 遠端時不存在。對於巢狀於子群組中的 gitlab.com 專案，`owner` 是包含斜線的完整命名空間路徑，例如 `"group/subgroup"`。在 v2.1.260 之前，這類專案的 `workspace.repo` 不存在 |

180| `cost.total_cost_usd` | 工作階段預估成本（美元），在用戶端以清單價格計算，除非有 [`modelPricing`](https://code.claude.com/docs/zh-TW/settings-reference#modelpricing) 表生效。可能與您的實際帳單不同。當 `/clear` 開始新工作階段時重設為 \$0 |180| `cost.total_cost_usd` | 以美元計的預估工作階段費用，除非 [`modelPricing`](https://code.claude.com/docs/zh-TW/settings-reference#modelpricing) 表格生效，否則會在用戶端依牌價計算。可能與您的實際帳單不同。當 `/clear` 開始新的工作階段時會重設為 \$0 |

184| `context_window.total_input_tokens`, `context_window.total_output_tokens` | 目前在 context window 中的令牌計數，來自最近的 API 回應。輸入包括快取讀取和寫入 |184| `context_window.total_input_tokens`, `context_window.total_output_tokens` | 目前位於上下文視窗中的 token 數量，來自最近一次的 API 回應。輸入包含快取讀取與寫入 |

191| `effort.level` | 目前的推理努力等級（`low`、`medium`、`high`、`xhigh` 或 `max`）。反映即時工作階段值，包括工作階段中途的 `/effort` 變更。當目前模型不支援努力參數時不存在 |191| `effort.level` | 目前的推理投入程度（`low`、`medium`、`high`、`xhigh` 或 `max`）。反映工作階段的即時值，包括工作階段中途透過 `/effort` 所做的變更。當目前模型不支援 effort 參數時不存在 |

195| `rate_limits.spend_limit.used_percentage`, `rate_limits.spend_limit.resets_at` | 在 Claude apps 閘道後面，您已使用多少支出限制，以及其期間何時重設。請參閱[支出限制欄位](#spend-limit-fields)。需要 Claude Code v2.1.251 或更新版本 |195| `rate_limits.spend_limit.used_percentage`, `rate_limits.spend_limit.resets_at` | 在 Claude apps 閘道後方時，您已使用多少支出上限，以及其週期何時重設。請參閱 [支出上限欄位](#spend-limit-fields)。需要 Claude Code v2.1.251 或更新版本 |

196| `rate_limits.spend_limit.used_usd`, `rate_limits.spend_limit.limit_usd`, `rate_limits.spend_limit.period` | 您以美元計的預估支出和限制，以及限制的期間。這些欄位可能不存在。請參閱[支出限制欄位](#spend-limit-fields)。Claude Code 和閘道都需要 v2.1.284 或更新版本 |196| `rate_limits.spend_limit.used_usd`, `rate_limits.spend_limit.limit_usd`, `rate_limits.spend_limit.period` | 以美元計的預估支出與上限，以及上限的週期。這些欄位可能不存在。請參閱 [支出上限欄位](#spend-limit-fields)。Claude Code 與閘道都需要 v2.1.284 或更新版本 |

197| `prompt_cache` | 工作階段的 [prompt cache](https://code.claude.com/docs/zh-TW/prompt-caching.md) 統計資料（針對主對話）：命中率、未命中次數，以及快取是否溫暖。請參閱 [prompt cache 欄位](#prompt-cache-fields)以了解每個欄位。在主對話的第一次 API 回應之前不存在。需要 Claude Code v2.1.251 或更新版本 |197| `prompt_cache` | 工作階段主要對話的 [提示快取](https://code.claude.com/docs/zh-TW/prompt-caching.md) 統計資料：命中率、未命中次數，以及快取是否處於暖狀態。所有欄位請參閱 [提示快取欄位](#prompt-cache-fields)。在主要對話的第一個 API 回應之前不存在。需要 Claude Code v2.1.251 或更新版本 |

199| `session_name` | 工作階段名稱。使用使用 `--name` 旗標或 `/rename` 設定的自訂名稱（如果存在），否則使用 AI 產生的工作階段標題。[預設顯示名稱](https://code.claude.com/docs/zh-TW/sessions.md#name-your-sessions)（例如 `my-app-3f`）不會填入此欄位。當工作階段既沒有自訂名稱也沒有 AI 產生的標題時不存在 |199| `session_name` | 工作階段名稱。若存在以 `--name` 旗標或 `/rename` 設定的自訂名稱則使用該名稱，否則使用 AI 產生的工作階段標題。[預設顯示名稱](https://code.claude.com/docs/zh-TW/sessions.md#name-your-sessions)（例如 `my-app-3f`）不會填入此欄位。當工作階段既沒有自訂名稱也沒有 AI 產生的標題時不存在 |

200| `prompt_id` | 識別目前正在處理的使用者提示詞的 UUID。符合 [OpenTelemetry 事件上的 `prompt.id` 屬性](https://code.claude.com/docs/zh-TW/monitoring-usage#event-correlation-attributes)。在第一次使用者輸入之前不存在 |200| `prompt_id` | 識別目前正在處理之使用者提示詞的 UUID。與 [OpenTelemetry 事件上的 `prompt.id` 屬性](https://code.claude.com/docs/zh-TW/monitoring-usage#event-correlation-attributes) 相符。在第一次使用者輸入之前不存在 |

204| `vim.mode` | 啟用 [vim 模式](https://code.claude.com/docs/zh-TW/interactive-mode.md#vim-editor-mode)時的目前 vim 模式（`NORMAL`、`INSERT`、`VISUAL` 或 `VISUAL LINE`） |204| `vim.mode` | 啟用 [vim 模式](https://code.claude.com/docs/zh-TW/interactive-mode.md#vim-editor-mode) 時的目前 vim 模式（`NORMAL`、`INSERT`、`VISUAL` 或 `VISUAL LINE`） |

206| `pr.number`, `pr.url` | 目前分支的開啟提取請求。鏡像底部狀態列中的 PR 徽章。在具有 GitLab 遠端的儲存庫中，Claude Code 改為從分支的開啟 [merge request](https://code.claude.com/docs/zh-TW/interactive-mode.md#gitlab-merge-requests) 填入這些欄位，因此 `pr.number` 是 merge request 編號。Merge request 資料需要 Claude Code v2.1.234 或更新版本。當不在 git 儲存庫中、在找到提取請求或 merge request 之前，或一旦它合併或關閉後不存在 |206| `pr.number`, `pr.url` | 目前分支的開啟中 pull request。與頁尾中的 PR 徽章相對應。在具有 GitLab 遠端的儲存庫中，Claude Code 會改以該分支開啟中的 [merge request](https://code.claude.com/docs/zh-TW/interactive-mode.md#gitlab-merge-requests) 填入這些欄位，因此 `pr.number` 是 merge request 編號。Merge request 資料需要 Claude Code v2.1.234 或更新版本。在 git 儲存庫之外、找到 pull request 或 merge request 之前，或其合併或關閉後，皆不存在 |

208| `pr.kind` | 當 `pr` 描述 [GitLab merge request](https://code.claude.com/docs/zh-TW/interactive-mode.md#gitlab-merge-requests)時為 `mr`。對於 GitHub 提取請求不存在，因此在此欄位之前編寫的指令碼可繼續運作。對於 merge request，當 GitLab 報告它可合併時，Claude Code 將 `review_state` 設定為 `approved`，對於任何其他開啟狀態設定為 `pending`，對於草稿設定為 `draft`。需要 Claude Code v2.1.234 或更新版本 |208| `pr.kind` | 當 `pr` 描述的是 [GitLab merge request](https://code.claude.com/docs/zh-TW/interactive-mode.md#gitlab-merge-requests) 時為 `mr`。對於 GitHub pull request 則不存在，因此在此欄位出現之前撰寫的指令碼仍可正常運作。對於 merge request，當 GitLab 回報其可合併時，Claude Code 會將 `review_state` 設為 `approved`，其他任何開啟中狀態設為 `pending`，草稿則設為 `draft`。需要 Claude Code v2.1.234 或更新版本 |

214 214

215> **完整 JSON 架構**215> **完整 JSON schema**

216>216>

217> 您的狀態列命令透過 stdin 接收此 JSON 結構：217> 您的狀態列命令會透過 stdin 接收此 JSON 結構：

218>218>

219> ```json theme={null}219> ```json theme={null}

220> {220> {

330> }330> }

331> ```331> ```

332>332>

333> **可能不存在的欄位**（不在 JSON 中）：333> **可能不存在的欄位**（不會出現在 JSON 中）：

334>334>

335> * `session_name`：當使用 `--name` 或 `/rename` 設定自訂名稱時出現，或一旦存在 AI 產生的工作階段標題。預設顯示名稱（例如 `my-app-3f`）不會填入此欄位335> * `session_name`：當已透過 `--name` 或 `/rename` 設定自訂名稱，或已存在 AI 產生的工作階段標題時出現。預設顯示名稱（例如 `my-app-3f`）不會填入此欄位

336> * `prompt_id`：僅在第一次使用者輸入後出現336> * `prompt_id`：僅在第一次使用者輸入之後出現

337> * `workspace.git_worktree`：僅當目前目錄位於連結 git worktree 內時出現337> * `workspace.git_worktree`：僅在目前目錄位於連結的 git worktree 內時出現

338> * `workspace.repo`：僅在 git 儲存庫內且設定了 `origin` 遠端時出現338> * `workspace.repo`：僅在已設定 `origin` 遠端的 git 儲存庫內出現

339> * `effort`：僅當目前模型支援推理努力參數時出現339> * `effort`：僅在目前模型支援推理投入程度參數時出現

340> * `vim`：僅在啟用 vim 模式時出現340> * `vim`：僅在啟用 vim 模式時出現

341> * `agent`：僅在使用 `--agent` 旗標或設定的代理設定執行時出現341> * `agent`：僅在使用 `--agent` 旗標執行或已設定 agent 設定時出現

342> * `pr`：僅在為目前分支找到開啟 PR 或 GitLab merge request 時出現，一旦它合併或關閉就會移除。`pr.review_state` 和 `pr.kind` 可能獨立不存在342> * `pr`：僅在目前分支找到開啟中的 PR 或 GitLab merge request 時出現，並會在其合併或關閉後移除。`pr.review_state` 與 `pr.kind` 可能單獨不存在

343> * `worktree`：僅在 [worktree 工作階段](https://code.claude.com/docs/zh-TW/worktrees.md)期間出現。存在時，對於基於 hook 的 worktree，`branch` 和 `original_branch` 也可能不存在343> * `worktree`：僅在工作階段處於 [worktree 工作階段](https://code.claude.com/docs/zh-TW/worktrees.md) 時出現。出現時，對於以 hook 為基礎的 worktree，`branch` 與 `original_branch` 也可能不存在

344> * `rate_limits`：僅對 Claude.ai Pro 和 Max 訂閱者，或在設定支出限制的 Claude apps gateway 後面，以及僅在工作階段中第一次 API 回應後出現。每個視窗（`five_hour`、`seven_day`、`spend_limit`）可能獨立不存在，Claude Code 會在其 `resets_at` 時間過去後捨棄視窗。使用 `jq -r '.rate_limits.five_hour.used_percentage // empty'` 以優雅地處理不存在的情況。344> * `rate_limits`：僅對 claude.ai Pro 與 Max 訂閱者，或位於為您設定支出上限的 Claude apps 閘道後方時出現，且僅在工作階段的第一個 API 回應之後出現。每個視窗（`five_hour`、`seven_day`、`spend_limit`）可能單獨不存在，且一旦其 `resets_at` 時間過後，Claude Code 就會移除該視窗。使用 `jq -r '.rate_limits.five_hour.used_percentage // empty'` 可妥善處理欄位不存在的情況。

345> * `prompt_cache`：在主對話的第一次 API 回應後出現。請參閱 [prompt cache 欄位](#prompt-cache-fields)345> * `prompt_cache`：在主要對話的第一個 API 回應之後出現。請參閱 [提示快取欄位](#prompt-cache-fields)

346>346>

347> **可能為 `null` 的欄位**：347> **可能為 `null` 的欄位**：

348>348>

349> * `context_window.current_usage`：在工作階段中第一次 API 呼叫之前為 `null`，以及在 `/compact` 之後直到下一次 API 呼叫重新填入為止349> * `context_window.current_usage`：在工作階段的第一次 API 呼叫之前為 `null`，在 `/compact` 之後也會再次為 `null`，直到下一次 API 呼叫重新填入

350> * `context_window.used_percentage`, `context_window.remaining_percentage`：在工作階段早期可能為 `null`350> * `context_window.used_percentage`、`context_window.remaining_percentage`：在工作階段初期可能為 `null`

351>351>

352> 在您的指令碼中使用條件存取處理遺漏的欄位，並使用後備預設值處理 null 值。352> 請在指令碼中使用條件式存取處理缺少的欄位，並以備援預設值處理 null 值。

353 353

354### Context window 欄位354### 上下文視窗欄位

355 355

356`context_window` 物件描述來自最近 API 回應的即時 context window。356`context_window` 物件描述最近一次 API 回應中的即時上下文視窗。

357 357

358* **合併總計**（`total_input_tokens`, `total_output_tokens`）：目前在 context window 中的令牌。`total_input_tokens` 是 `input_tokens`、`cache_creation_input_tokens` 和 `cache_read_input_tokens` 的總和；`total_output_tokens` 是最近回應中的輸出令牌。在第一次 API 回應之前兩者都是 `0`。358* **合計總數**（`total_input_tokens`、`total_output_tokens`）：目前位於上下文視窗中的 token。`total_input_tokens` 是 `input_tokens`、`cache_creation_input_tokens` 與 `cache_read_input_tokens` 的總和；`total_output_tokens` 是最近一次回應的輸出 token。兩者在第一個 API 回應之前皆為 `0`。

359* **按元件使用情況**（`current_usage`）：相同的令牌計數按類別分解。當您需要將快取命中與新輸入分開時，請使用此項。359* **各元件用量**（`current_usage`）：依類別細分的相同 token 數量。當您需要將快取命中與新輸入分開時，請使用此欄位。

360 360

361`current_usage` 物件包含：361`current_usage` 物件包含：

362 362

363* `input_tokens`：目前 context 中的輸入令牌363* `input_tokens`：目前上下文中的輸入 token

364* `output_tokens`：產生的輸出令牌364* `output_tokens`：產生的輸出 token

365* `cache_creation_input_tokens`：寫入快取的令牌365* `cache_creation_input_tokens`：寫入快取的 token

366* `cache_read_input_tokens`：從快取讀取的令牌366* `cache_read_input_tokens`：從快取讀取的 token

367 367

368如需了解快取欄位的含義及其計費方式，請參閱[檢查快取效能](https://code.claude.com/docs/zh-TW/prompt-caching.md#check-cache-performance)。368關於快取欄位的意義及其計費方式，請參閱 [檢查快取效能](https://code.claude.com/docs/zh-TW/prompt-caching.md#check-cache-performance)。

369 369

370`used_percentage` 欄位僅從輸入令牌計算：`input_tokens + cache_creation_input_tokens + cache_read_input_tokens`。它不包括 `output_tokens`。370`used_percentage` 欄位僅根據輸入 token 計算：`input_tokens + cache_creation_input_tokens + cache_read_input_tokens`。不包含 `output_tokens`。

371 371

372如果您從 `current_usage` 手動計算 context 百分比，請使用相同的僅輸入公式以符合 `used_percentage`。372若您從 `current_usage` 手動計算上下文百分比，請使用相同的僅輸入公式，以與 `used_percentage` 一致。

373 373

374`current_usage` 物件在工作階段中第一次 API 呼叫之前為 `null`，以及在 `/compact` 之後直到下一次 API 呼叫重新填入為止再次為 `null`。374`current_usage` 物件在工作階段的第一次 API 呼叫之前為 `null`，在 `/compact` 之後也會立即再次為 `null`，直到下一次 API 呼叫重新填入。

375 375

376### 支出限制欄位376### 支出上限欄位

377 377

378在[設定支出限制的 Claude apps 閘道](https://code.claude.com/docs/zh-TW/claude-apps-gateway-spend-limits.md#usage-warnings-in-claude-code)後面，`rate_limits.spend_limit` 物件描述適用於您的支出限制。它在工作階段的第一次 API 回應後出現，且需要 Claude Code v2.1.251 或更新版本。您的指令碼會依不同的排程接收其欄位：378在 [具有支出上限的 Claude apps 閘道](https://code.claude.com/docs/zh-TW/claude-apps-gateway-spend-limits.md#usage-warnings-in-claude-code) 後方時，`rate_limits.spend_limit` 物件描述適用於您的支出上限。它會在工作階段的第一個 API 回應之後出現，且需要 Claude Code v2.1.251 或更新版本。您的指令碼會依不同的時程接收其欄位：

379 379

380* `used_percentage` 和 `resets_at`：隨每個回應提供，因此只要 `spend_limit` 存在，它們就會存在。`used_percentage` 從 0 到 100，或一旦您超過限制就超過 100，而 `resets_at` 是限制期間重設時的 Unix 紀元秒數。380* `used_percentage` 與 `resets_at`：隨每個回應一起提供，因此只要 `spend_limit` 存在，它們就會存在。`used_percentage` 的範圍為 0 到 100，超過上限後會大於 100；`resets_at` 是上限週期重設時的 Unix epoch 秒數。

381* `used_usd`、`limit_usd` 和 `period`：您目前為止以美元計的預估支出和限制，以及限制涵蓋的期間，為 `daily`、`weekly` 或 `monthly` 之一。閘道[從 token 計數計算 `used_usd`](https://code.claude.com/docs/zh-TW/claude-apps-gateway-spend-limits#how-requests-are-priced)，因此它是預估值，而非計費金額。Claude Code 透過另一個請求從閘道讀取它們，在您傳送請求期間約每五分鐘一次。美元金額可能比 `used_percentage` 舊約五分鐘，因此兩者可能會短暫不一致。Claude Code 和閘道都需要 v2.1.284 或更新版本。381* `used_usd`、`limit_usd` 與 `period`：您到目前為止以美元計的預估支出與上限，以及上限涵蓋的週期，為 `daily`、`weekly` 或 `monthly` 其中之一。閘道會 [根據 token 數量計算 `used_usd`](https://code.claude.com/docs/zh-TW/claude-apps-gateway-spend-limits#how-requests-are-priced)，因此它是預估值，而非實際計費金額。Claude Code 會在您傳送請求期間，約每五分鐘以另一個請求從閘道讀取這些欄位。金額可能比 `used_percentage` 舊約五分鐘，因此兩者可能短暫不一致。Claude Code 與閘道都需要 v2.1.284 或更新版本。

382 382

383即使 `spend_limit` 存在，也請將 `used_usd`、`limit_usd` 和 `period` 視為選用。您的指令碼會先收到百分比，再收到這些欄位；如果您設定了 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`（會關閉該請求），這些欄位將保持不存在。請在指令碼中以備援值讀取每個欄位，例如 `jq -r '.rate_limits.spend_limit.used_usd // empty'`。383即使 `spend_limit` 存在，也請將 `used_usd`、`limit_usd` 與 `period` 視為選用欄位，因為您的指令碼會先收到百分比。請在指令碼中以備援值讀取每個欄位，例如 `jq -r '.rate_limits.spend_limit.used_usd // empty'`。在 Claude Code v2.1.295 之前，若您設定了 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`，這些欄位會一直不存在，因為該設定會關閉這個請求。

384 384

385### Prompt cache 欄位385### 提示快取欄位

386 386

387`prompt_cache` 物件總結工作階段的主對話如何使用 [prompt cache](https://code.claude.com/docs/zh-TW/prompt-caching.md)。Claude Code 從 API 回應中的快取令牌計數計算它，因此它適用於每個提供者。387`prompt_cache` 物件總結工作階段的主要對話如何使用 [提示快取](https://code.claude.com/docs/zh-TW/prompt-caching.md)。Claude Code 根據 API 回應中的快取 token 數量計算此物件，因此適用於所有供應商。

388 388

389該物件在主對話的第一次 API 回應後出現。Claude Code 不會在這些統計資料中計算子代理請求。需要 Claude Code v2.1.251 或更新版本。389此物件會在主要對話的第一個 API 回應之後出現。Claude Code 不會將 subagent 請求計入這些統計資料。需要 Claude Code v2.1.251 或更新版本。

390 390

391該表列出每個欄位及其含義。時間戳記是 Unix 紀元秒，與 `rate_limits.*.resets_at` 相同的單位。簡短的狀態列通常顯示其中一個或兩個；`warm` 和 `hit_ratio` 最直接地總結快取狀態。391下表列出每個欄位及其意義。時間戳記為 Unix epoch 秒數，與 `rate_limits.*.resets_at` 的單位相同。簡短的狀態列通常只會顯示其中一兩個；`warm` 與 `hit_ratio` 最能直接概括快取狀態。

392 392

393| 欄位 | 描述 |393| 欄位 | 說明 |

394| - | - |394| - | - |

397| `ttl` | 目前快取前綴的 [cache lifetime](https://code.claude.com/docs/zh-TW/prompt-caching.md#cache-lifetime)：`"5m"` 或 `"1h"` |397| `ttl` | 目前快取前綴的 [快取存留時間](https://code.claude.com/docs/zh-TW/prompt-caching.md#cache-lifetime)：`"5m"` 或 `"1h"` |

~~409~~ 409

410Claude Code 在終端機上顯示相同的統計資料，在 [`/usage` 命令的 `Prompt cache (main)` 行](https://code.claude.com/docs/zh-TW/costs#prompt-cache-statistics)上。410Claude Code 也會在終端機中的 [`/usage` 命令的 `Prompt cache (main)` 行](https://code.claude.com/docs/zh-TW/costs#prompt-cache-statistics) 顯示相同的統計資料。

~~411~~ 411

412#### Last miss cause412#### 上一次未命中原因

~~413~~ 413

414`last_miss_cause` 物件報告 Claude Code 識別為最後一次未命中可能原因的內容。其 `causes` 陣列保留一個或多個原因名稱，例如 `tools_changed`、`system_prompt_changed`、`ttl_expired_5m` 或 `likely_server_side`。該物件在工作階段的第一次未命中之前為 `null`，以及每當 Claude Code 無法識別最後一次未命中的原因時再次為 `null`。需要 Claude Code v2.1.260 或更新版本。414`last_miss_cause` 物件回報 Claude Code 判定為最近一次未命中的可能原因。其 `causes` 陣列包含一個或多個原因名稱，例如 `tools_changed`、`system_prompt_changed`、`ttl_expired_5m` 或 `likely_server_side`。此物件在工作階段第一次未命中之前為 `null`，且每當 Claude Code 無法為最近一次未命中判定原因時，也會再次為 `null`。需要 Claude Code v2.1.260 或更新版本。

~~415~~ 415

416兩個原因將計數新增到物件：416有兩個原因會在物件中加入計數：

~~417~~ 417

418* `tools_added` 和 `tools_removed`：使用 `tools_changed`，有多少工具被新增到或從請求中移除418* `tools_added` 與 `tools_removed`：搭配 `tools_changed`，表示請求中新增或移除了多少個工具

419* `system_char_delta`：使用 `system_prompt_changed`，系統提示長度的變化（以字元為單位）419* `system_char_delta`：搭配 `system_prompt_changed`，表示系統提示詞長度的變化，以字元為單位

420 420

421## 範例421## 範例

422 422

terminal-config.md +2 −0

Details

121* **背景工作階段**：[背景工作階段](https://code.claude.com/docs/zh-TW/agent-view.md)不會向您的終端機回報其狀態，即使您已附加至該工作階段也是如此。其狀態會改為顯示在 agent 檢視中。121* **背景工作階段**：[背景工作階段](https://code.claude.com/docs/zh-TW/agent-view.md)不會向您的終端機回報其狀態，即使您已附加至該工作階段也是如此。其狀態會改為顯示在 agent 檢視中。

122* **[`CLAUDE_CODE_DISABLE_TERMINAL_TITLE`](https://code.claude.com/docs/zh-TW/env-vars#variables)**：如果您將此變數設為 `1`，Claude Code 就不會檢查是否支援，也不會回報狀態。請取消設定此變數。122* **[`CLAUDE_CODE_DISABLE_TERMINAL_TITLE`](https://code.claude.com/docs/zh-TW/env-vars#variables)**：如果您將此變數設為 `1`，Claude Code 就不會檢查是否支援，也不會回報狀態。請取消設定此變數。

123 123

124在回報支援此協定的終端機中，分頁標題開頭不會出現狀態符號。由於終端機本身會顯示工作階段的狀態，Claude Code 便會省略在其他終端機中加在標題前方的符號。

125

124## 設定 tmux126## 設定 tmux

125 127

126當 Claude Code 在 tmux 內執行時，預設會發生兩個問題：Shift+Enter 會提交而不是插入新行，且桌面通知和[進度列](https://code.claude.com/docs/zh-TW/settings-reference.md#terminalprogressbarenabled)永遠無法到達外層終端。將這些行新增到 `~/.tmux.conf`，然後執行 `tmux source-file ~/.tmux.conf` 以將其套用到執行中的伺服器：128當 Claude Code 在 tmux 內執行時，預設會發生兩個問題：Shift+Enter 會提交而不是插入新行，且桌面通知和[進度列](https://code.claude.com/docs/zh-TW/settings-reference.md#terminalprogressbarenabled)永遠無法到達外層終端。將這些行新增到 `~/.tmux.conf`，然後執行 `tmux source-file ~/.tmux.conf` 以將其套用到執行中的伺服器：

tools-reference.md +5 −2

Details

258 258

259在 Claude 最後讀取檔案後，磁碟上變更的檔案仍然可以編輯，當 `old_string` 與目前內容完全且明確匹配，且 Claude Code 可以讀取檔案而無需提示時。針對檔案的目前內容進行匹配可保持安全，結果會注意到檔案包含其他變更，因此 Claude 在依賴周圍內容的編輯前重新讀取它。在任何其他情況下，例如過時的 `old_string` 或不使用 `replace_all` 而匹配多次的情況，Claude 在編輯前再次讀取檔案。259在 Claude 最後讀取檔案後，磁碟上變更的檔案仍然可以編輯，當 `old_string` 與目前內容完全且明確匹配，且 Claude Code 可以讀取檔案而無需提示時。針對檔案的目前內容進行匹配可保持安全，結果會注意到檔案包含其他變更，因此 Claude 在依賴周圍內容的編輯前重新讀取它。在任何其他情況下，例如過時的 `old_string` 或不使用 `replace_all` 而匹配多次的情況，Claude 在編輯前再次讀取檔案。

260 260

261Claude 使用 `cat` 或 `grep` 等 Bash 命令檢視檔案後，也可以在不另外執行 Read 的情況下編輯該檔案。這些命令為 `cat`、`nl`、`bat`、`batcat`、`head`、`tail`、`sed -n 'X,Yp'`、`grep`、`egrep`、`fgrep` 和 `rg`，且每個命令都須在單一檔案上執行，沒有管道或重新導向。未輸出任何匹配結果的搜尋不算作讀取，此清單以外的任何命令也不算。261Claude 使用 `cat` 或 `grep` 等 Bash 命令檢視檔案後，也可以在不另外執行 Read 的情況下編輯該檔案。這些命令為 `cat`、`nl`、`bat`、`batcat`、`head`、`tail`、`sed -n 'X,Yp'`、`grep`、`egrep`、`fgrep` 和 `rg`，且每個命令都須在單一檔案上執行，沒有管道或重新導向。如果命令未輸出檔案的任何文字，例如搜尋沒有匹配任何內容時，編輯前讀取檢查仍然適用。

262 262

263當 Claude 以這種方式檢視檔案時，Claude Code 也會載入適用於該檔案的任何[子目錄 `CLAUDE.md`](https://code.claude.com/docs/zh-TW/memory#how-claude-md-files-load) 和[路徑範圍規則](https://code.claude.com/docs/zh-TW/memory.md#path-specific-rules)。請參閱 [Read 和 Edit 權限規則](https://code.claude.com/docs/zh-TW/permissions.md#read-and-edit)，了解您的 `Read` 和 `Edit` 拒絕規則涵蓋哪些 Bash 命令。263當 Claude 以這種方式檢視檔案時，Claude Code 也會載入適用於該檔案的任何[子目錄 `CLAUDE.md`](https://code.claude.com/docs/zh-TW/memory#how-claude-md-files-load) 和[路徑範圍規則](https://code.claude.com/docs/zh-TW/memory.md#path-specific-rules)。請參閱 [Read 和 Edit 權限規則](https://code.claude.com/docs/zh-TW/permissions.md#read-and-edit)，了解您的 `Read` 和 `Edit` 拒絕規則涵蓋哪些 Bash 命令。

264 264

383 383

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

385 385

386該工具在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用。當設定 `DISABLE_TELEMETRY` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 時，它也不可用。在 Windows 上，只有在安裝 [Git Bash](https://code.claude.com/docs/zh-TW/setup.md#set-up-on-windows) 時才能使用該工具。386在下列情況中，Monitor 需要最低版本或 Git Bash：

387

388* **最低版本**：在 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) 關閉時

389* **Windows**：只有在安裝 [Git Bash](https://code.claude.com/docs/zh-TW/setup.md#set-up-on-windows) 時才能使用該工具

387 390

388外掛程式可以宣告在外掛程式處於活動狀態時自動啟動的監視，而不是要求 Claude 啟動它們。請參閱 [外掛程式監視](https://code.claude.com/docs/zh-TW/plugins/components.md#monitors)。391外掛程式可以宣告在外掛程式處於活動狀態時自動啟動的監視，而不是要求 Claude 啟動它們。請參閱 [外掛程式監視](https://code.claude.com/docs/zh-TW/plugins/components.md#monitors)。

389 392

web-quickstart.md +11 −5

Details

177 177

178**1. 打開差異檢視**178**1. 打開差異檢視**

179 179

180差異指示器顯示整個會話中新增和移除的行，例如 `+42 -18`。選擇它以打開差異檢視，左側有文件列表，右側有更改。180在 Claude 將其更改推送到分支後，聊天旁面板中的 **Changes** 卡片會顯示整個工作階段中新增和移除的行，例如 `+42 -18`。點擊這些數字以打開差異檢視。

181 181

182差異預設會與其基礎分支進行比較。若要與不同的分支進行比較，請選擇**比較對象**並選擇一個。182* 您也可以點擊工作階段標題列中的 **Changes**，或標題列 **⋮** 選單中的該項目。

183* 若要在面板隱藏時顯示它，請點擊工作階段標題列中的 **Show session rail** 圖示，或標題列 **⋮** 選單中的該項目。

184

185差異預設會將工作階段的更改與其基礎分支進行比較。若要與不同的分支進行比較，請選擇 **Compare against** 並選擇一個。

183 186

184**2. 留下內聯評論**187**2. 留下內聯評論**

185 188

186選擇差異中的任何行，輸入您的反饋，然後按 Enter。評論會排隊直到您發送下一條訊息，然後它們會與其捆綁。Claude 看到「在 `src/auth.ts:47`，不要在這裡捕捉錯誤」以及您的主要指令，因此您無需描述問題所在。189選擇差異中的任何行，輸入您的反饋，然後按 Enter。評論會排隊直到您發送下一條訊息，然後它們會與其捆綁。Claude 看到「在 `src/auth.ts:47`，不要在這裡捕捉錯誤」以及您的主要指令，因此您無需描述問題所在。

187 190

188**3. 建立拉取請求**191**3. 建立 pull request**

192

193當差異看起來正確時，如果 **Changes** 卡片不在視野中，請[再次顯示面板](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md#review-changes)，然後從卡片建立 pull request 或草稿：

189 194

190當差異看起來正確時，選擇差異檢視頂部的**建立 PR**。您可以將其作為完整 PR、草稿打開，或跳轉到 GitHub 的撰寫頁面，其中包含生成的標題和描述。195* 點擊 **Create PR**。Claude Code 會以生成的標題和描述建立 pull request。

196* 若要改為開啟草稿，請在 **Create PR** 上按右鍵，選擇 **Create draft PR** 以更改按鈕的動作，然後點擊該按鈕

191 197

192**4. 在 PR 後繼續迭代**198**4. 在 PR 後繼續迭代**

193 199

194會話在建立 PR 後保持活躍。將 CI 失敗輸出或審查者評論貼上到聊天中，並要求 Claude 解決它們。若要讓 Claude 自動監控 PR，請參閱[自動修復拉取請求](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md#auto-fix-pull-requests)。200工作階段在建立 PR 後保持活躍。將 CI 失敗輸出或審查者評論貼上到聊天中，並要求 Claude 解決它們。若要讓 Claude 自動監控 PR，請參閱[自動修復 pull request](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md#auto-fix-pull-requests)。

195 201

196## 設定故障排除202## 設定故障排除

197 203

Documentation 2026-10-24 22:59 UTC to 2026-10-25 23:58 UTC