Documentation 2026-10-27 22:59 UTC to 2026-10-28 23:57 UTC

97| [Customization lockdown](https://code.claude.com/docs/zh-TW/settings-reference.md#strictpluginonlycustomization) | 阻止 skills、agents、hooks 和 MCP 伺服器來自使用者和專案來源，使其只能來自外掛程式或受管設定。鎖定 skills 也會停止[您的開發人員在 claude.ai 上啟用的 skills](https://code.claude.com/docs/zh-TW/skills.md#where-synced-skills-load)同步 | `strictPluginOnlyCustomization` |97| [Customization lockdown](https://code.claude.com/docs/zh-TW/settings-reference.md#strictpluginonlycustomization) | 阻止 skills、agents、hooks 和 MCP 伺服器來自使用者和專案來源，使其只能來自外掛程式或受管設定。鎖定 skills 也會停止[您的開發人員在 claude.ai 上啟用的 skills](https://code.claude.com/docs/zh-TW/skills.md#where-synced-skills-load)同步 | `strictPluginOnlyCustomization` |

98| [Disable claude.ai sync](https://code.claude.com/docs/zh-TW/settings-reference.md#syncclaudeaiskills) | 停止 Claude Code 載入[skills](https://code.claude.com/docs/zh-TW/skills.md#how-synced-skills-behave)和[外掛程式](https://code.claude.com/docs/zh-TW/plugins/loading.md#synced-plugins)您的開發人員在 claude.ai 上啟用。如果您為組織關閉 claude.ai 上的 Skills，Claude Code 會停止同步兩者，在 v2.1.273 或更新版本上，它也會移除已同步的。若要在不關閉 Skills 的情況下停止其中任一個，請在受管設定中將其鍵設定為 `false` | `syncClaudeAiSkills`、`syncClaudeAiPlugins` |98| [Disable claude.ai sync](https://code.claude.com/docs/zh-TW/settings-reference.md#syncclaudeaiskills) | 停止 Claude Code 載入[skills](https://code.claude.com/docs/zh-TW/skills.md#how-synced-skills-behave)和[外掛程式](https://code.claude.com/docs/zh-TW/plugins/loading.md#synced-plugins)您的開發人員在 claude.ai 上啟用。如果您為組織關閉 claude.ai 上的 Skills，Claude Code 會停止同步兩者，在 v2.1.273 或更新版本上，它也會移除已同步的。若要在不關閉 Skills 的情況下停止其中任一個，請在受管設定中將其鍵設定為 `false` | `syncClaudeAiSkills`、`syncClaudeAiPlugins` |

99| [Hook restrictions](https://code.claude.com/docs/zh-TW/settings-reference.md#allowmanagedhooksonly) | 限制哪些 hooks 執行並限制 HTTP hook URL；請參閱[在 `allowManagedHooksOnly` 下執行的內容](https://code.claude.com/docs/zh-TW/settings-reference#what-runs-under-allowmanagedhooksonly)以了解完整的效果清單 | `allowManagedHooksOnly`、`allowedHttpHookUrls` |99| [Hook restrictions](https://code.claude.com/docs/zh-TW/settings-reference.md#allowmanagedhooksonly) | 限制哪些 hooks 執行並限制 HTTP hook URL；請參閱[在 `allowManagedHooksOnly` 下執行的內容](https://code.claude.com/docs/zh-TW/settings-reference#what-runs-under-allowmanagedhooksonly)以了解完整的效果清單 | `allowManagedHooksOnly`、`allowedHttpHookUrls` |

100| [Login enforcement](https://code.claude.com/docs/zh-TW/settings-reference.md#forceloginmethod) | 限制登入為特定方法或 Anthropic 組織。方法限制適用於 VS Code 擴充功能、Agent SDK、`claude setup-token` 和 `/install-github-app`，以及終端的互動式登入畫面（透過 `/login` 或首次執行上線到達），預先選擇方法而不強制執行；Claude Code 驗證終端、VS Code 擴充功能和 Agent SDK 中 claude.ai 帳戶登入的組織，不檢查 Claude Console 登入或[閘道](https://code.claude.com/docs/zh-TW/claude-apps-gateway)登入。在 v2.1.212 之前，只有終端登入應用任一鍵。設定時，由 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 驗證的會話在啟動時被阻止；雲端提供者會話不受影響，除非這些認證之一或由較早的 Claude Console 登入儲存的 API 金鑰也存在 | `forceLoginMethod`、`forceLoginOrgUUID` |100| [Login enforcement](https://code.claude.com/docs/zh-TW/settings-reference.md#forceloginmethod) | 限制登入為特定方法或 Anthropic 組織。方法限制適用於 VS Code 擴充功能、Agent SDK、`claude setup-token` 和 `/install-github-app`，而終端的互動式登入畫面（透過 `/login` 或首次執行上線到達）則會預先選擇該方法而不強制執行；Claude Code 驗證終端、VS Code 擴充功能和 Agent SDK 中 claude.ai 帳戶登入的組織，不檢查 Claude Console 登入或[閘道](https://code.claude.com/docs/zh-TW/claude-apps-gateway)登入。在 v2.1.212 之前，只有終端登入應用任一鍵。設定時，由 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 驗證的會話在啟動時被阻止；雲端提供者會話不受影響，除非這些認證之一或由較早的 Claude Console 登入儲存的 API 金鑰也存在 | `forceLoginMethod`、`forceLoginOrgUUID` |

101| [Provider restrictions](https://code.claude.com/docs/zh-TW/settings-reference.md#allowedproviders) | 限制機器可能使用的 API 提供者。不在列表中的提供者上的會話在啟動時、登入時以及下次聯絡 API 時被拒絕。需要 Claude Code v2.1.285 或更新版本 | `allowedProviders` |101| [Provider restrictions](https://code.claude.com/docs/zh-TW/settings-reference.md#allowedproviders) | 限制機器可能使用的 API 提供者。不在列表中的提供者上的會話在啟動時、登入時以及下次聯絡 API 時被拒絕。需要 Claude Code v2.1.285 或更新版本 | `allowedProviders` |

102| [Disable agent view](https://code.claude.com/docs/zh-TW/agent-view.md#how-background-sessions-are-hosted) | 關閉 `claude agents`、`--bg`、`/background` 和隨選監督員 | `disableAgentView` |102| [Disable agent view](https://code.claude.com/docs/zh-TW/agent-view.md#how-background-sessions-are-hosted) | 關閉 `claude agents`、`--bg`、`/background` 和隨選監督員 | `disableAgentView` |

103| [Configure the corporate launcher](https://code.claude.com/docs/zh-TW/corporate-launcher.md) | 使用必需的公司啟動器作為[背景代理監督員](https://code.claude.com/docs/zh-TW/agent-view.md#how-background-sessions-are-hosted)、其工作者和[其他涵蓋的背景程序](https://code.claude.com/docs/zh-TW/corporate-launcher.md#what-the-launcher-covers)的前綴，而不是關閉代理檢視 | `processWrapper` |103| [Configure the corporate launcher](https://code.claude.com/docs/zh-TW/corporate-launcher.md) | 使用必需的公司啟動器作為[背景代理監督員](https://code.claude.com/docs/zh-TW/agent-view.md#how-background-sessions-are-hosted)、其工作者和[其他涵蓋的背景程序](https://code.claude.com/docs/zh-TW/corporate-launcher.md#what-the-launcher-covers)的前綴，而不是關閉代理檢視 | `processWrapper` |

104| [Model restrictions](https://code.claude.com/docs/zh-TW/model-config.md#restrict-model-selection) | `availableModels` 篩選模型選擇器中出現的模型。新增 `enforceAvailableModels` 也會限制自動選擇的預設模型。請參閱[表面涵蓋範圍](https://code.claude.com/docs/zh-TW/model-config.md#surface-coverage)以了解此設定如何到達 CLI、網頁和 IDE | `availableModels`、`enforceAvailableModels` |104| [Model restrictions](https://code.claude.com/docs/zh-TW/model-config.md#restrict-model-selection) | `availableModels` 篩選模型選擇器中出現的模型。新增 `enforceAvailableModels` 也會限制自動選擇的預設模型。請參閱[表面涵蓋範圍](https://code.claude.com/docs/zh-TW/model-config.md#surface-coverage)以了解此設定如何到達 CLI、網頁和 IDE | `availableModels`、`enforceAvailableModels` |

105| [Effort cap](https://code.claude.com/docs/zh-TW/settings-reference.md#maxeffortlevel) | 為每個模型或每個提供者上的每個模型限制[工作量級別](https://code.claude.com/docs/zh-TW/model-config.md#adjust-effort-level) | `maxEffortLevel` |105| [Effort cap](https://code.claude.com/docs/zh-TW/settings-reference.md#maxeffortlevel) | 為所有模型或個別模型限制[工作量級別](https://code.claude.com/docs/zh-TW/model-config.md#adjust-effort-level)，適用於每個提供者 | `maxEffortLevel` |

106| [Version floor](https://code.claude.com/docs/zh-TW/settings-reference.md#minimumversion) | 防止自動更新安裝低於組織範圍最小值的版本 | `minimumVersion` |106| [Version floor](https://code.claude.com/docs/zh-TW/settings-reference.md#minimumversion) | 防止自動更新安裝低於組織範圍最小值的版本 | `minimumVersion` |

107| [Required version range](https://code.claude.com/docs/zh-TW/settings-reference.md#requiredminimumversion) | 當執行版本超出組織核准範圍時，完全拒絕啟動。比 `minimumVersion` 更強大，後者只會阻止降級 | `requiredMinimumVersion`、`requiredMaximumVersion` |107| [Required version range](https://code.claude.com/docs/zh-TW/settings-reference.md#requiredminimumversion) | 當執行版本超出組織核准範圍時，完全拒絕啟動。比 `minimumVersion` 更強大，後者只會阻止降級 | `requiredMinimumVersion`、`requiredMaximumVersion` |

108| [Telemetry opt-out](https://code.claude.com/docs/zh-TW/data-usage.md#telemetry-services) | 在每個裝置上關閉 Anthropic 繫結的使用量指標、錯誤報告和調查 | `env` 設定 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 為 `1`；連結的部分列出了各類別變數 |108| [Telemetry opt-out](https://code.claude.com/docs/zh-TW/data-usage.md#telemetry-services) | 在每個裝置上關閉 Anthropic 繫結的使用量指標、錯誤報告和調查 | `env` 設定 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 為 `1`；連結的部分列出了各類別變數 |

211. **接收提示。** Claude 接收您的提示，以及系統提示、工具定義和對話歷史記錄。SDK 會產生一個 [`SystemMessage`](#message-types)，其子類型為 `"init"`，包含工作階段中繼資料。211. **接收提示。** Claude 接收您的提示，以及系統提示、工具定義和對話歷史記錄。SDK 會產生一個 [`SystemMessage`](#message-types)，其子類型為 `"init"`，包含工作階段中繼資料。

222. **評估並回應。** Claude 評估目前狀態並決定如何進行。它可能會以文字回應、要求一個或多個工具呼叫，或兩者都有。SDK 會產生一個或多個 [`AssistantMessage`](#message-types) 物件，每個內容區塊（例如文字區塊或工具呼叫要求）各一個。222. **評估並回應。** Claude 評估目前狀態並決定如何進行。它可能會以文字回應、要求一個或多個工具呼叫，或兩者都有。SDK 會產生一個或多個 [`AssistantMessage`](#message-types) 物件，每個內容區塊（例如文字區塊或工具呼叫要求）各一個。

233. **執行工具。** SDK 執行每個要求的工具並收集結果。每組工具結果都會回饋給 Claude 以進行下一個決定。您可以使用 [hooks](https://code.claude.com/docs/zh-TW/agent-sdk/hooks.md) 在工具執行前攔截、修改或阻止工具呼叫。233. **執行工具。** SDK 執行每個要求的工具並收集結果。每組工具結果都會回饋給 Claude 以進行下一個決定。您可以使用 [hooks](https://code.claude.com/docs/zh-TW/agent-sdk/hooks.md) 在工具執行前攔截、修改或阻止工具呼叫。

244. **重複。** 步驟 2 和 3 重複為一個週期。每個完整週期是一個回合。Claude 繼續呼叫工具並處理結果，直到它產生沒有工具呼叫的回應。244. **重複。** 步驟 2 和 3 重複為一個週期。Claude 繼續呼叫工具並處理結果，直到它產生沒有工具呼叫的回應。

255. **返回結果。** SDK 會產生最終的 [`AssistantMessage`](#message-types)，包含文字回應（無工具呼叫），然後是 [`ResultMessage`](#message-types)，包含最終文字、代幣使用量、成本和工作階段 ID。255. **返回結果。** SDK 會產生最終的 [`AssistantMessage`](#message-types)，包含文字回應（無工具呼叫），然後是 [`ResultMessage`](#message-types)，包含最終文字、代幣使用量、成本和工作階段 ID。

26 26 

27一個快速問題（「這裡有什麼檔案？」）可能需要一到兩個回合的 `Glob` 呼叫和結果回應。一個複雜的任務（「重構驗證模組並更新測試」）可以在許多回合中鏈接數十個工具呼叫，讀取檔案、編輯程式碼和執行測試，Claude 根據每個結果調整其方法。27一個快速問題（例如「這裡有什麼檔案？」）可能需要兩到三個[回合](#turns-and-messages)：一到兩個回合呼叫 `Glob`，然後一個回合以結果回應。一個複雜的任務（例如「重構驗證模組並更新測試」）可能會在許多回合中串連數十個工具呼叫，Claude 會根據每個結果進行調整。

28 28 

29## 回合和訊息29## 回合和訊息

30 30 

31回合是迴圈內的一個往返：Claude 產生包含工具呼叫的輸出，SDK 執行這些工具，結果自動回饋給 Claude。這發生在不將控制權交回給您的程式碼的情況下。回合繼續進行，直到 Claude 產生沒有工具呼叫的輸出，此時迴圈結束並傳遞最終結果。31回合是迴圈內的一個往返：Claude 產生輸出，如果輸出包含工具呼叫，SDK 會執行這些工具，結果自動回饋給 Claude。這發生在不將控制權交回給您的程式碼的情況下。回合繼續進行，直到 Claude 產生沒有工具呼叫的輸出，此時迴圈結束並傳遞最終結果。

32 32 

33考慮提示「修復 auth.ts 中失敗的測試」的完整工作階段可能是什麼樣子。33考慮提示「修復 auth.ts 中失敗的測試」的完整工作階段可能是什麼樣子。

34 34 

1274| `updated_input` | `dict[str, Any] \| None` | `None` | 要使用的修改輸入而不是原始輸入 |1274| `updated_input` | `dict[str, Any] \| None` | `None` | 要使用的修改輸入而不是原始輸入 |

1275| `updated_permissions` | `list[PermissionUpdate] \| None` | `None` | 要套用的權限更新 |1275| `updated_permissions` | `list[PermissionUpdate] \| None` | `None` | 要套用的權限更新 |

1276 1276 

1277如果您傳回的 `PermissionResultAllow` 在 `updated_permissions` 中包含超過 4,096 個項目，Claude Code 會將結果視為無效並拒絕該工具呼叫。每個 [`PermissionUpdate`](#permissionupdate) 計為一個項目，其 `rules` 或 `directories` 清單中的每個條目也各計為一個項目。拒絕訊息的結尾為 `updatedPermissions may hold at most 4096 updates, rules and directories in all.` 若要避免遭拒，請傳回 4,096 個或更少的項目。

1278 

1277### `PermissionResultDeny`1279### `PermissionResultDeny`

1278 1280 

1279指示應拒絕工具呼叫的結果。1281指示應拒絕工具呼叫的結果。

497| 屬性 | 型別 | 預設值 | 說明 |497| 屬性 | 型別 | 預設值 | 說明 |

498| :- | :- | :- | :- |498| :- | :- | :- | :- |

499| `abortController` | `AbortController` | `new AbortController()` | 用於取消操作的控制器 |499| `abortController` | `AbortController` | `new AbortController()` | 用於取消操作的控制器 |

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

501| `agent` | `string` | `undefined` | 主執行緒的 agent 名稱。該 agent 必須在 `agents` 選項或設定中定義 |501| `agent` | `string` | `undefined` | 主執行緒的 agent 名稱。該 agent 必須在 `agents` 選項或設定中定義 |

502| `agents` | `Record<string, [`AgentDefinition`](#agentdefinition)>` | `undefined` | 以程式方式定義 subagent |502| `agents` | `Record<string, [`AgentDefinition`](#agentdefinition)>` | `undefined` | 以程式方式定義 subagent |

503| `agentProgressSummaries` | `boolean` | `false` | 為 `true` 時，為 subagent 產生單行進度摘要，並透過 `summary` 欄位在 [`task_progress`](#sdktaskprogressmessage) 事件中轉發。適用於前景和背景 subagent |503| `agentProgressSummaries` | `boolean` | `false` | 設為 `true` 時，為 subagent 產生單行進度摘要，並透過 `summary` 欄位在 [`task_progress`](#sdktaskprogressmessage) 事件中轉送。適用於前景和背景 subagent |

504| `allowDangerouslySkipPermissions` | `boolean` | `false` | 啟用略過權限。使用 `permissionMode: 'bypassPermissions'` 時必須設定，無論是在啟動時或之後透過 `setPermissionMode()` 設定。關於它如何與 `permissionMode: 'plan'` 互動，請參閱 [plan mode](https://code.claude.com/docs/zh-TW/agent-sdk/permissions.md#plan-mode-plan) |504| `allowDangerouslySkipPermissions` | `boolean` | `false` | 啟用略過權限。在啟動時或之後透過 `setPermissionMode()` 使用 `permissionMode: 'bypassPermissions'` 時為必要項目。關於它與 `permissionMode: 'plan'` 的互動方式，請參閱 [plan mode](https://code.claude.com/docs/zh-TW/agent-sdk/permissions.md#plan-mode-plan) |

505| `allowedTools` | `string[]` | `[]` | 無需提示即可自動核准的工具，但從[網路路徑](https://code.claude.com/docs/zh-TW/permissions.md#network-paths)讀取除外。這不會將 Claude 限制為只能使用這些工具。如果您在此指定其中一個[任務追蹤工具](https://code.claude.com/docs/zh-TW/agent-sdk/todo-tracking.md#model-availability)，Claude Code 也會讓該工作階段選擇加入。其他未列出的工具則交由 `permissionMode` 和 `canUseTool` 處理。使用 `disallowedTools` 來封鎖工具。請參閱[權限](https://code.claude.com/docs/zh-TW/agent-sdk/permissions.md#allow-and-deny-rules) |505| `allowedTools` | `string[]` | `[]` | 無需提示即自動核准的工具，但從[網路路徑](https://code.claude.com/docs/zh-TW/permissions.md#network-paths)讀取的操作除外。這不會將 Claude 限制為只能使用這些工具。若您在此列出其中一個[任務追蹤工具](https://code.claude.com/docs/zh-TW/agent-sdk/todo-tracking.md#model-availability)，Claude Code 也會讓該工作階段啟用此功能。其他未列出的工具會交由 `permissionMode` 和 `canUseTool` 處理。使用 `disallowedTools` 封鎖工具。請參閱[權限](https://code.claude.com/docs/zh-TW/agent-sdk/permissions.md#allow-and-deny-rules) |

506| `betas` | [`SdkBeta`](#sdkbeta)`[]` | `[]` | 啟用 beta 功能 |506| `betas` | [`SdkBeta`](#sdkbeta)`[]` | `[]` | 啟用 beta 功能 |

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

508| `continue` | `boolean` | `false` | 繼續最近的對話 |508| `continue` | `boolean` | `false` | 繼續最近一次的對話 |

509| `cwd` | `string` | `process.cwd()` | 目前的工作目錄 |509| `cwd` | `string` | `process.cwd()` | 目前的工作目錄 |

510| `debug` | `boolean` | `false` | 為 Claude Code 程序啟用偵錯模式 |510| `debug` | `boolean` | `false` | 為 Claude Code 程序啟用除錯模式 |

511| `debugFile` | `string` | `undefined` | 將偵錯日誌寫入特定檔案路徑。會隱含啟用偵錯模式 |511| `debugFile` | `string` | `undefined` | 將除錯日誌寫入特定檔案路徑。會隱含啟用除錯模式 |

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

513| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'` | `undefined` | 控制 Claude 在回應中投入多少 effort。搭配自適應思考來引導思考深度。請參閱[調整 effort 等級](https://code.claude.com/docs/zh-TW/model-config.md#adjust-effort-level) |513| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'` | `undefined` | 控制 Claude 在回應中投入多少 effort。與自適應思考搭配使用以引導思考深度。請參閱[調整 effort 等級](https://code.claude.com/docs/zh-TW/model-config.md#adjust-effort-level) |

514| `enableFileCheckpointing` | `boolean` | `false` | 啟用檔案變更追蹤以便倒轉。請參閱[檔案檢查點功能](https://code.claude.com/docs/zh-TW/agent-sdk/file-checkpointing.md) |514| `enableFileCheckpointing` | `boolean` | `false` | 啟用檔案變更追蹤以便倒回。請參閱[檔案檢查點功能](https://code.claude.com/docs/zh-TW/agent-sdk/file-checkpointing.md) |

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

516| `executable` | `'bun' \| 'deno' \| 'node'` | 自動偵測 | 要使用的 JavaScript 執行環境 |516| `executable` | `'bun' \| 'deno' \| 'node'` | 自動偵測 | 要使用的 JavaScript 執行環境 |

517| `executableArgs` | `string[]` | `[]` | 要傳遞給執行檔的引數 |517| `executableArgs` | `string[]` | `[]` | 要傳遞給執行檔的引數 |

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

519| `fallbackModel` | `string` | `undefined` | 主要模型失敗時要使用的模型。接受以逗號分隔的清單。關於順序和上限，請參閱[備援模型鏈](https://code.claude.com/docs/zh-TW/model-config.md#fallback-model-chains)。相關指引請參閱[選擇模型](https://code.claude.com/docs/zh-TW/agent-sdk/configuration.md#choose-a-model) |519| `fallbackModel` | `string` | `undefined` | 主要模型失敗時使用的模型。接受以逗號分隔的清單。關於順序與上限，請參閱[備援模型鏈](https://code.claude.com/docs/zh-TW/model-config.md#fallback-model-chains)。相關指引請參閱[選擇模型](https://code.claude.com/docs/zh-TW/agent-sdk/configuration.md#choose-a-model) |

520| `forkSession` | `boolean` | `false` | 使用 `resume` 繼續時，分支到新的工作階段 ID，而不是繼續原始工作階段 |520| `forkSession` | `boolean` | `false` | 使用 `resume` 恢復時，分支到新的工作階段 ID，而不是繼續原本的工作階段 |

521| `forwardSubagentText` | `boolean` | `false` | 將 subagent 的文字和思考區塊轉發為設定了 `parent_tool_use_id` 的 assistant 和 user 訊息，讓取用端可以呈現巢狀逐字稿。若沒有此選項，Claude Code 會省略在[前景](https://code.claude.com/docs/zh-TW/sub-agents.md#run-subagents-in-foreground-or-background)執行之 subagent 的文字和思考區塊。關於巢狀 subagent、具有 `context: fork` 的 skill，以及各自所需的 Claude Code 版本，請參閱[追蹤 subagent 訊息](https://code.claude.com/docs/zh-TW/headless.md#follow-subagent-messages) |521| `forwardSubagentText` | `boolean` | `false` | 將 subagent 的文字和思考區塊以設定了 `parent_tool_use_id` 的 assistant 和 user 訊息轉送，讓消費端能呈現巢狀逐字稿。若未使用此選項，Claude Code 會省略在[前景](https://code.claude.com/docs/zh-TW/sub-agents.md#run-subagents-in-foreground-or-background)執行之 subagent 的文字和思考區塊。關於巢狀 subagent、使用 `context: fork` 的 skill，以及各自所需的 Claude Code 版本，請參閱[追蹤 subagent 訊息](https://code.claude.com/docs/zh-TW/headless.md#follow-subagent-messages) |

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

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

524| `includePartialMessages` | `boolean` | `false` | 包含部分訊息事件 |524| `includePartialMessages` | `boolean` | `false` | 包含部分訊息事件 |

525| `loadTimeoutMs` | `number` | `60000` | *Alpha.* 在繼續工作階段的具體化過程中，每次 `sessionStore.load()` 和 `sessionStore.listSubkeys()` 呼叫的逾時時間（毫秒）。如果轉接器未在此時間範圍內完成，查詢會失敗而不是停滯。未設定 `sessionStore` 時會忽略 |525| `loadTimeoutMs` | `number` | `60000` | *Alpha。* 在恢復具體化期間，每次 `sessionStore.load()` 和 `sessionStore.listSubkeys()` 呼叫的逾時時間（毫秒）。若配接器未在此時間內完成，查詢會失敗而不是停滯。未設定 `sessionStore` 時會忽略 |

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

527| `maxBudgetUsd` | `number` | `undefined` | 當用戶端成本估算達到此美元值時停止查詢。估算值可能超過此值，因此請[保留餘裕](https://code.claude.com/docs/zh-TW/agent-sdk/agent-loop.md#budget-headroom)。僅計算該呼叫本身的花費；從繼續的工作階段還原的總計不列入計算。關於準確度注意事項和重設行為，請參閱[追蹤成本和用量](https://code.claude.com/docs/zh-TW/agent-sdk/cost-tracking.md) |527| `maxBudgetUsd` | `number` | `undefined` | 當用戶端成本估算達到此 USD 值時停止查詢。估算值可能超過此值，因此請[保留餘裕](https://code.claude.com/docs/zh-TW/agent-sdk/agent-loop.md#budget-headroom)。僅計算該呼叫本身的花費；從恢復的工作階段還原的總額不計入。關於準確性注意事項與重設行為，請參閱[追蹤成本與用量](https://code.claude.com/docs/zh-TW/agent-sdk/cost-tracking.md) |

528| `maxThinkingTokens` | `number` | `undefined` | *已棄用：* 請改用 `thinking`。思考過程的最大 token 數 |528| `maxThinkingTokens` | `number` | `undefined` | *已淘汰：* 請改用 `thinking`。思考過程的最大 token 數 |

529| `maxTurns` | `number` | `undefined` | 最大 agentic [回合](https://code.claude.com/docs/zh-TW/agent-sdk/agent-loop.md#turns-and-messages)數 |529| `maxTurns` | `number` | `undefined` | 最大 agent [回合](https://code.claude.com/docs/zh-TW/agent-sdk/agent-loop.md#turns-and-messages)數 |

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

531| `model` | `string` | 來自 CLI 的預設值 | Claude 模型別名或完整模型名稱。請參閱[接受的值和供應商特定的 ID](https://code.claude.com/docs/zh-TW/model-config.md#available-models) |531| `model` | `string` | 來自 CLI 的預設值 | Claude 模型別名或完整模型名稱。請參閱[可接受的值與供應商特定 ID](https://code.claude.com/docs/zh-TW/model-config.md#available-models) |

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

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

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

535| `pathToClaudeCodeExecutable` | `string` | 從隨附的原生二進位檔自動解析 | Claude Code 執行檔的路徑。只有在安裝期間略過了選用相依套件，或您的平台不在支援範圍內時才需要 |535| `pathToClaudeCodeExecutable` | `string` | 從隨附的原生二進位檔自動解析 | Claude Code 執行檔的路徑。僅在安裝時略過了選用相依套件，或您的平台不在支援清單中時才需要 |

536| `permissionMode` | [`PermissionMode`](#permissionmode) | `undefined` | 工作階段的權限模式。如果您省略它，且沒有其他項目設定權限模式（例如 [`permissions.defaultMode`](https://code.claude.com/docs/zh-TW/settings-reference#permissions-defaultmode) 設定），工作階段會以 `default` 啟動。請參閱[權限模式](https://code.claude.com/docs/zh-TW/agent-sdk/permissions.md#permission-modes) |536| `permissionMode` | [`PermissionMode`](#permissionmode) | `undefined` | 工作階段的權限模式。若您省略此項且沒有其他項目設定權限模式（例如 [`permissions.defaultMode`](https://code.claude.com/docs/zh-TW/settings-reference#permissions-defaultmode) 設定），工作階段會以 `default` 啟動。請參閱[權限模式](https://code.claude.com/docs/zh-TW/agent-sdk/permissions.md#permission-modes) |

537| `permissionPromptToolName` | `string` | `undefined` | 用於權限提示的 MCP 工具名稱 |537| `permissionPromptToolName` | `string` | `undefined` | 用於權限提示的 MCP 工具名稱 |

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

539| `persistSession` | `boolean` | `true` | 為 `false` 時，停用將工作階段持久化到磁碟。之後將無法繼續這些工作階段 |539| `persistSession` | `boolean` | `true` | 設為 `false` 時，停用將工作階段持久化到磁碟。之後無法恢復工作階段 |

540| `planModeInstructions` | `string` | `undefined` | plan mode 的自訂工作流程指令。當 `permissionMode` 為 `'plan'` 時，此字串會取代預設的 plan mode 工作流程主體。CLI 仍會以唯讀強制前言和 ExitPlanMode 協定結尾包裝它 |540| `planModeInstructions` | `string` | `undefined` | plan mode 的自訂工作流程指令。當 `permissionMode` 為 `'plan'` 時，此字串會取代預設的 plan mode 工作流程主體。CLI 仍會以唯讀強制前言和 ExitPlanMode 協定結尾將其包覆 |

541| `plugins` | [`SdkPluginConfig`](#sdkpluginconfig)`[]` | `[]` | 從本機路徑載入自訂外掛。詳情請參閱[外掛](https://code.claude.com/docs/zh-TW/agent-sdk/plugins.md) |541| `plugins` | [`SdkPluginConfig`](#sdkpluginconfig)`[]` | `[]` | 從本機路徑載入自訂外掛。詳情請參閱[外掛](https://code.claude.com/docs/zh-TW/agent-sdk/plugins.md) |

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

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

544| `resume` | `string` | `undefined` | 要繼續的工作階段 ID |544| `resume` | `string` | `undefined` | 要恢復的工作階段 ID |

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

546| `resumeSessionAt` | `string` | `undefined` | 在特定訊息 UUID 處繼續工作階段 |546| `resumeSessionAt` | `string` | `undefined` | 在特定訊息 UUID 處恢復工作階段 |

547| `sandbox` | [`SandboxSettings`](#sandboxsettings) | `undefined` | 以程式方式設定沙箱行為。詳情請參閱[沙箱設定](#sandboxsettings) |547| `sandbox` | [`SandboxSettings`](#sandboxsettings) | `undefined` | 以程式方式設定沙箱行為。詳情請參閱[沙箱設定](#sandboxsettings) |

548| `sessionId` | `string` | 自動產生 | 為工作階段使用特定的 UUID，而不是自動產生 |548| `sessionId` | `string` | 自動產生 | 為工作階段使用特定的 UUID，而不是自動產生 |

549| `sessionStore` | [`SessionStore`](https://code.claude.com/docs/zh-TW/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | 將工作階段逐字稿鏡像到外部後端，讓另一台主機可以繼續這些工作階段。請參閱[將工作階段持久化到外部儲存空間](https://code.claude.com/docs/zh-TW/agent-sdk/session-storage.md) |549| `sessionStore` | [`SessionStore`](https://code.claude.com/docs/zh-TW/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | 將工作階段逐字稿鏡像到外部後端，讓其他主機可以恢復它們。請參閱[將工作階段持久化到外部儲存空間](https://code.claude.com/docs/zh-TW/agent-sdk/session-storage.md) |

550| `sessionStoreFlush` | `'batched' \| 'eager'` | `'batched'` | *Alpha.* `sessionStore` 的清除模式。未設定 `sessionStore` 時會忽略 |550| `sessionStoreFlush` | `'batched' \| 'eager'` | `'batched'` | *Alpha。* `sessionStore` 的排清模式。未設定 `sessionStore` 時會忽略 |

551| `settings` | `string \| Settings` | `undefined` | 內嵌的[設定](https://code.claude.com/docs/zh-TW/settings.md)物件、設定檔路徑或內嵌 JSON 字串。填入[優先順序](https://code.claude.com/docs/zh-TW/settings.md#settings-precedence)中的旗標設定層。可在執行時使用 [`applyFlagSettings()`](#applyflagsettings) 變更 |551| `settings` | `string \| Settings` | `undefined` | 內嵌的[設定](https://code.claude.com/docs/zh-TW/settings.md)物件、設定檔路徑或內嵌 JSON 字串。填入[優先順序](https://code.claude.com/docs/zh-TW/settings.md#settings-precedence)中的旗標設定層。可在執行時期以 [`applyFlagSettings()`](#applyflagsettings) 變更 |

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

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

554| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | 用於產生 Claude Code 程序的自訂函式。用於在 VM、容器或遠端環境中執行 Claude Code |554| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | 用於產生 Claude Code 程序的自訂函式。用於在 VM、容器或遠端環境中執行 Claude Code |

555| `stderr` | `(data: string) => void` | `undefined` | stderr 輸出的回呼 |555| `stderr` | `(data: string) => void` | `undefined` | stderr 輸出的回呼 |

556| `strictMcpConfig` | `boolean` | `false` | 只使用在 `mcpServers` 中傳遞的伺服器，並忽略專案 `.mcp.json`、使用者設定、外掛提供的 MCP 伺服器，以及 [claude.ai 連接器](https://code.claude.com/docs/zh-TW/mcp.md#use-mcp-servers-from-claude-ai) |556| `strictMcpConfig` | `boolean` | `false` | 僅使用 `mcpServers` 中傳入的伺服器，並忽略專案 `.mcp.json`、使用者設定、外掛提供的 MCP 伺服器以及 [claude.ai 連接器](https://code.claude.com/docs/zh-TW/mcp.md#use-mcp-servers-from-claude-ai) |

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

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

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

560| `title` | `string` | `undefined` | 工作階段的顯示標題。透過 `resume` 或 `continue` 繼續時，被繼續工作階段已持久化的標題優先；使用 [`renameSession()`](#renamesession) 重新命名現有的工作階段 |560| `title` | `string` | `undefined` | 工作階段的顯示標題。透過 `resume` 或 `continue` 恢復時，已恢復工作階段所持久化的標題優先；請使用 [`renameSession()`](#renamesession) 重新命名現有工作階段 |

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

562| `toolConfig` | [`ToolConfig`](#toolconfig) | `undefined` | 內建工具行為的設定。詳情請參閱 [`ToolConfig`](#toolconfig) |562| `toolConfig` | [`ToolConfig`](#toolconfig) | `undefined` | 內建工具行為的設定。詳情請參閱 [`ToolConfig`](#toolconfig) |

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

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

565 565 

566#### 處理緩慢或停滯的 API 回應566#### 處理緩慢或停滯的 API 回應

567 567 

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

569 569 

570```typescript theme={null}570```typescript theme={null}

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

583});583});

584```584```

585 585 

586* [`API_TIMEOUT_MS`](https://code.claude.com/docs/zh-TW/env-vars)：每次請求嘗試可等待回應標頭的時間（毫秒）。它不會限制標頭抵達後串流回應的執行時間。預設值為 `600000`。適用於主迴圈和所有 subagent。586* [`API_TIMEOUT_MS`](https://code.claude.com/docs/zh-TW/env-vars)：每次請求嘗試可等待回應標頭的時間（毫秒）。它不會限制標頭抵達後串流回應的執行時間。預設為 `600000`。適用於主迴圈和所有 subagent。

587* `CLAUDE_CODE_MAX_RETRIES`：API 重試的最大次數。預設為 `10`，上限為 `15`。每次重試都有自己的 `API_TIMEOUT_MS` 時間範圍。587* `CLAUDE_CODE_MAX_RETRIES`：API 重試的最大次數。預設為 `10`，上限為 `15`。每次重試都有自己的 `API_TIMEOUT_MS` 時間窗。

588 588 

589 對於需要等待較長中斷期間的無人值守執行，請設定 [`CLAUDE_CODE_RETRY_WATCHDOG=1`](https://code.claude.com/docs/zh-TW/errors#tune-retry-behavior)：它會無限期重試暫時性的容量錯誤，並且在 Claude Code v2.1.199 或更新版本上，會將其他暫時性錯誤的預設值提高到 `300`，並移除此變數的上限。589 對於需要撐過較長中斷時間的無人值守執行，請設定 [`CLAUDE_CODE_RETRY_WATCHDOG=1`](https://code.claude.com/docs/zh-TW/errors#tune-retry-behavior)：它會無限次重試暫時性的容量錯誤，且在 Claude Code v2.1.199 或更新版本中，會將其他暫時性錯誤的預設值提高到 `300`，並移除此變數的上限。

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

591 591 

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

593* `CLAUDE_ENABLE_STREAM_WATCHDOG` 搭配 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`：串流監控器，會在標頭已送達但回應主體停止串流時中止請求。此監控器對所有供應商預設為開啟；設定 `CLAUDE_ENABLE_STREAM_WATCHDOG=0` 可停用。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` 預設為 `300000`，且最小值被限制為該值。中止之後，Claude Code 會依據回應已進行的程度採取的行動，請參閱[自動重試](https://code.claude.com/docs/zh-TW/errors.md#automatic-retries)。593* `CLAUDE_ENABLE_STREAM_WATCHDOG` 搭配 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`：串流監視器，當標頭已抵達但回應主體停止串流時中止請求。此監視器對所有供應商預設開啟；設定 `CLAUDE_ENABLE_STREAM_WATCHDOG=0` 可將其停用。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` 預設為 `300000`，且最小值會被限制為該值。中止後，Claude Code 會依據回應進行到的程度採取行動，詳見[自動重試](https://code.claude.com/docs/zh-TW/errors.md#automatic-retries)。

594 594 

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

596 596 

597### `Query` 物件597### `Query` 物件

598 598 

599`query()` 函式回傳的介面。599`query()` 函式傳回的介面。

600 600 

601```typescript theme={null}601```typescript theme={null}

602interface Query extends AsyncGenerator<SDKMessage, void> {602interface Query extends AsyncGenerator<SDKMessage, void> {

657 657 

658| 方法 | 說明 |658| 方法 | 說明 |

659| :- | :- |659| :- | :- |

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

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

662| `setPermissionMode()` | 變更權限模式（僅在串流輸入模式下可用） |662| `setPermissionMode()` | 變更權限模式（僅在串流輸入模式下可用） |

663| `setModel()` | 變更模型（僅在串流輸入模式下可用）。傳入 `undefined` 或字串 `"default"` 會重設為 [Claude Code 的預設模型](https://code.claude.com/docs/zh-TW/model-config.md)。若新模型不支援自動模式，處於 `auto` 模式的工作階段會[變更為 `default` 模式](https://code.claude.com/docs/zh-TW/agent-sdk/permissions#auto-mode-auto) |663| `setModel()` | 變更模型（僅在串流輸入模式下可用）。傳入 `undefined` 或字串 `"default"` 會重設為 [Claude Code 的預設模型](https://code.claude.com/docs/zh-TW/model-config.md)。若新模型不支援自動模式，處於 `auto` 模式的工作階段會[變更為 `default` 模式](https://code.claude.com/docs/zh-TW/agent-sdk/permissions#auto-mode-auto) |

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

665| `applyFlagSettings(settings)` | 在執行時將設定合併到工作階段的旗標設定層（僅在串流輸入模式下可用）。請參閱 [`applyFlagSettings()`](#applyflagsettings) |665| `applyFlagSettings(settings)` | 在執行時期將設定合併到工作階段的旗標設定層（僅在串流輸入模式下可用）。請參閱 [`applyFlagSettings()`](#applyflagsettings) |

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

667| `initializationResult()` | 回傳完整的初始化結果，包括支援的命令、模型、帳戶資訊和輸出風格設定 |667| `initializationResult()` | 傳回完整的初始化結果，包括支援的命令、模型、帳戶資訊和輸出風格設定 |

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

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

670| `supportedModels()` | 回傳可用的模型及其顯示資訊 |670| `supportedModels()` | 傳回可用的模型及顯示資訊 |

671| `supportedAgents()` | 以 [`AgentInfo`](#agentinfo)`[]` 回傳可用的 subagent |671| `supportedAgents()` | 以 [`AgentInfo`](#agentinfo)`[]` 傳回可用的 subagent |

672| `mcpServerStatus()` | 以 [`McpServerStatus`](#mcpserverstatus)`[]` 回傳已連線 MCP 伺服器的狀態 |672| `mcpServerStatus()` | 以 [`McpServerStatus`](#mcpserverstatus)`[]` 傳回已連線 MCP 伺服器的狀態 |

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

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

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

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

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

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

679| `accountInfo()` | 回傳帳戶資訊 |679| `accountInfo()` | 傳回帳戶資訊 |

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

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

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

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

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

685| `streamInput(stream)` | 將輸入訊息串流到查詢，以進行多回合對話 |685| `streamInput(stream)` | 將輸入訊息串流到查詢中以進行多回合對話 |

686| `stopTask(taskId)` | 依 ID 停止正在執行的背景任務 |686| `stopTask(taskId)` | 依 ID 停止執行中的背景任務 |

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

688| `close()` | 關閉查詢並終止底層程序。強制結束查詢並清理所有資源 |688| `close()` | 關閉查詢並終止底層程序。強制結束查詢並清理所有資源 |

689 689 

690#### `setMcpPermissionModeOverride()`690#### `setMcpPermissionModeOverride()`

691 691 

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

693 693 

694傳遞下列三個值之一作為 `mode`：694傳入以下三個值之一作為 `mode`：

695 695 

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

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

698* `null`：清除覆寫。698* `null`：清除覆寫。

699 699 

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

701 701 

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

703 703 

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

705 705 

706#### `seedReadState()`706#### `seedReadState()`

707 707 

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

709 709 

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

711 711 

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

713 713 

714#### `backgroundTasks()`714#### `backgroundTasks()`

715 715 

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

717 717 

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

719 719 

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

721 721 

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

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

724 724 

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

726 726 

727#### `applyFlagSettings()`727#### `applyFlagSettings()`

728 728 

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

730 730 

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

732 732 

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

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

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

736 736 

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

738 738 

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

740 740 

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

742 742 

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

744 744 

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

746 746 

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

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

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

750 750 

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

752 752 

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

754 754 

755```typescript theme={null}755```typescript theme={null}

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

766 766 

767> [!NOTE]767> [!NOTE]

768>768>

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

770 770 

771#### `updateSettings()`771#### `updateSettings()`

772 772 

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

774 774 

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

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

777 777 

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

779 779 

780#### `toggleMcpServer()`780#### `toggleMcpServer()`

781 781 

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

783 783 

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

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

786 786 

787### `WarmQuery`787### `WarmQuery`

788 788 

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

790 790 

791```typescript theme={null}791```typescript theme={null}

792interface WarmQuery extends AsyncDisposable {792interface WarmQuery extends AsyncDisposable {

799 799 

800| 方法 | 說明 |800| 方法 | 說明 |

801| :- | :- |801| :- | :- |

802| `query(prompt)` | 將提示詞傳送到預熱的子程序並回傳 [`Query`](#query-object)。每個 `WarmQuery` 只能呼叫一次 |802| `query(prompt)` | 將提示詞傳送到預熱的子程序並傳回 [`Query`](#query-object)。每個 `WarmQuery` 只能呼叫一次 |

803| `close()` | 在不傳送提示詞的情況下關閉子程序。用於捨棄不再需要的預熱查詢 |803| `close()` | 在不傳送提示詞的情況下關閉子程序。用於捨棄不再需要的預熱查詢 |

804 804 

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

806 806 

807### `SpareProcess`807### `SpareProcess`

808 808 

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

810 810 

811```typescript theme={null}811```typescript theme={null}

812interface SpareProcess extends AsyncDisposable {812interface SpareProcess extends AsyncDisposable {

824 824 

825| 成員 | 說明 |825| 成員 | 說明 |

826| :- | :- |826| :- | :- |

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

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

829| `exited` | 在程序結束時完成，無論是否已被認領。請替換在您認領之前就結束的備用程序 |829| `exited` | 在程序結束時完成，無論是否已被認領。若備用程序在您認領前就結束，請予以替換 |

830| `close()` | 終止程序。在認領之前呼叫會捨棄備用程序並拒絕 `claimed` |830| `close()` | 終止程序。在認領之前呼叫會捨棄備用程序並拒絕 `claimed` |

831 831 

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

833 833 

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

835 835 

836### `SDKControlInitializeResponse`836### `SDKControlInitializeResponse`

837 837 

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

839 839 

840```typescript theme={null}840```typescript theme={null}

841type SDKControlInitializeResponse = {841type SDKControlInitializeResponse = {

860};860};

861```861```

862 862 

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

864 864 

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

866 866 

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

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

869 869 

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

871 871 

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

873 873 

874`claude_code_version` 是執行工作階段回合之程序的 Claude Code 版本。它與 [`SDKSystemMessage`](#sdksystemmessage) init 訊息所攜帶的值相同，因此您可以在第一個回合之前讀取 CLI 版本。874`claude_code_version` 是執行工作階段回合之程序的 Claude Code 版本。它與 [`SDKSystemMessage`](#sdksystemmessage) init 訊息所帶的值相同，因此您可以在第一個回合之前讀取 CLI 版本。

875 875 

876* 此欄位需要 Agent SDK v0.3.296 或更新版本，其隨附 Claude Code v2.1.296。876* 此欄位需要 Agent SDK v0.3.296 或更新版本，其隨附 Claude Code v2.1.296。

877* 如果此欄位為 `undefined` 且您設定了 `pathToClaudeCodeExecutable`，請將其指向 Claude Code v2.1.296 或更新版本。877* 若此欄位為 `undefined` 且您設定了 `pathToClaudeCodeExecutable`，請將其指向 Claude Code v2.1.296 或更新版本。

878 878 

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

880 880 

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

882 882 

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

884 884 

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

886 886 

887### `SDKControlInterruptResponse`887### `SDKControlInterruptResponse`

888 888 

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

890 890 

891```typescript theme={null}891```typescript theme={null}

892type SDKControlInterruptResponse = {892type SDKControlInterruptResponse = {

895};895};

896```896```

897 897 

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

899 899 

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

901 901 

902解讀此清單時請注意以下事項：902解讀此清單時請注意以下事項：

903 903 

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

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

906* 清單可能包含您的用戶端從未傳送的 UUID，例如[工作階段範圍的排程任務](https://code.claude.com/docs/zh-TW/scheduled-tasks.md)觸發。請忽略您無法辨識的 UUID，而不要將其視為錯誤。906* 清單可能包含您的用戶端從未傳送過的 UUID，例如[工作階段範圍的排程任務](https://code.claude.com/docs/zh-TW/scheduled-tasks.md)觸發。請忽略您無法辨識的 UUID，而不要將其視為錯誤。

907 907 

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

909 909 

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

911 911 

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

913 913 

914### `SDKControlGetContextUsageResponse`914### `SDKControlGetContextUsageResponse`

915 915 

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

917 917 

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

919 919 

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

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

922 922 

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

924 924 

925在 `SDKControlGetContextUsageResponse` 中，`categories[].id`、`mcpInstructions`，以及 `agents` 與 `skills.skillFrontmatter` 項目的 `pluginId` 和 `path` 欄位需要 Agent SDK v0.3.304 或更新版本。925在 `SDKControlGetContextUsageResponse` 中，`categories[].id`、`mcpInstructions`，以及 `agents` 和 `skills.skillFrontmatter` 項目的 `pluginId` 和 `path` 欄位需要 Agent SDK v0.3.304 或更新版本。

926 926 

927```typescript theme={null}927```typescript theme={null}

928type SDKControlGetContextUsageResponse = {928type SDKControlGetContextUsageResponse = {

1042};1042};

1043```1043```

1044 1044 

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

1046 1046 

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

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

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

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

1051 1051 

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

1053 1053 

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

1055 1055 

1056#### 依 ID 尋找列、伺服器的指令 token，或項目的外掛與檔案1056#### 依 ID 尋找列、伺服器的指令 token，或項目的外掛與檔案

1057 1057 

1058MCP 伺服器指令是已連線伺服器提供、由 Claude Code 加入上下文的使用說明，而 `categories` 的 `mcp_instructions` 列會計算它們的 token。使用這些 [`getContextUsage()`](#query-object) 欄位，依 `id` 挑出一個 `categories` 列、依伺服器拆分 `mcp_instructions` 的 token，或找出 agent 或 skill 項目背後的外掛和檔案：1058MCP 伺服器指令是已連線伺服器提供、並由 Claude Code 加入上下文的使用說明，而 `categories` 的 `mcp_instructions` 列會計算它們的 token。使用以下 [`getContextUsage()`](#query-object) 欄位，可依 `id` 挑出單一 `categories` 列、依伺服器拆分 `mcp_instructions` 的 token，或找出 agent 或 skill 項目背後的外掛與檔案：

1059 1059 

1060| 欄位 | 所在位置 | 內容 |1060| 欄位 | 所在位置 | 內容 |

1061| :- | :- | :- |1061| :- | :- | :- |

1062| `id` | 每個 `categories` 列 | 該列的識別碼，為[回應類型](#sdkcontrolgetcontextusageresponse)所列值之一，例如 `mcp_instructions`。依 `id` 比對以挑出一列，或依 `kind` 將列分組。較新的 Claude Code 版本可能會傳送您已安裝之類型未列出的值，因此請將無法辨識的 `id` 視為不存在 |1062| `id` | 每個 `categories` 列 | 該列的識別碼，為[回應型別](#sdkcontrolgetcontextusageresponse)所列的值之一，例如 `mcp_instructions`。依 `id` 比對以挑出單一列，或依 `kind` 比對以將各列分組。較新的 Claude Code 版本可能會傳送您已安裝型別中未列出的值，因此請將無法辨識的 `id` 視為不存在 |

1063| `mcpInstructions` | 回應 | 每個提供指令的已連線 MCP 伺服器各有一個 `{ serverName, tokens }` 項目，若沒有任何伺服器提供則為空陣列。`tokens` 值為估算值，加總等於 `mcp_instructions` 列的 `tokens`。`serverName` 是 [`mcpServerStatus()`](#query-object) 為該伺服器回報的 `name` |1063| `mcpInstructions` | 回應 | 每個提供指令的已連線 MCP 伺服器各有一個 `{ serverName, tokens }` 項目，若沒有任何伺服器提供則為空陣列。`tokens` 值為估算值，加總起來等於 `mcp_instructions` 列的 `tokens`。`serverName` 是 [`mcpServerStatus()`](#query-object) 為該伺服器回報的 `name` |

1064| `pluginId` | `agents` 和 `skills.skillFrontmatter` 項目 | 以 `name@marketplace` 形式的 ID 指出項目來自的外掛，對於並非來自外掛的項目則不存在。當外掛並非來自市集時，`@` 之後的部分會改為指出[其來源](https://code.claude.com/docs/zh-TW/plugins/loading.md#find-where-a-plugin-came-from)，例如透過 [`plugins`](#options) 選項載入的外掛為 `inline` |1064| `pluginId` | `agents` 和 `skills.skillFrontmatter` 項目 | 以 `name@marketplace` 形式的 ID 指出該項目來自哪個外掛；對於不是來自外掛的項目則不存在。當外掛不是來自市集時，`@` 之後的部分改為指出[其來源](https://code.claude.com/docs/zh-TW/plugins/loading.md#find-where-a-plugin-came-from)，例如透過 [`plugins`](#options) 選項載入的外掛為 `inline` |

1065| `path` | `agents` 和 `skills.skillFrontmatter` 項目 | 定義該 agent 或 skill 之檔案的絕對路徑，位於 Claude Code 執行所在的機器上。當沒有檔案定義該項目時（例如來自 [`agents`](#options) 選項的 agent 或 Claude Code 內建的 skill），此欄位不存在 |1065| `path` | `agents` 和 `skills.skillFrontmatter` 項目 | 定義該 agent 或 skill 之檔案的絕對路徑，位於執行 Claude Code 的機器上。當沒有檔案定義該項目時（例如來自 [`agents`](#options) 選項的 agent 或 Claude Code 內建的 skill），此欄位不存在 |

1066 1066 

1067作為依 `id` 比對的範例，此範例會找出 `mcp_instructions` 列：1067以依 `id` 比對為例，以下範例會找出 `mcp_instructions` 列：

1068 1068 

1069```typescript theme={null}1069```typescript theme={null}

1070// q is the Query object that query() returned1070// q is the Query object that query() returned

1086};1086};

1087```1087```

1088 1088 

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

1090 1090 

1091#### `readFile()` 可以讀取的內容1091#### `readFile()` 可以讀取的內容

1092 1092 

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

1094 1094 

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

1096* Claude Code 為該工作階段所保存的少數自有檔案，例如工具結果1096* 該工作階段中 Claude Code 本身的少數檔案，例如工具結果

1097 1097 

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

1099 1099 

1100### `SDKControlReloadPluginsResponse`1100### `SDKControlReloadPluginsResponse`

1101 1101 

1122};1122};

1123```1123```

1124 1124 

1125集合欄位描述呼叫之後的工作階段：1125集合欄位描述呼叫後的工作階段狀態：

1126 1126 

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

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

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

1130 1130 

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

1132 1132 

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

1134 1134 

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

1136* `false`：檢查未發現快取影響，且重新載入已套用。1136* `false`：檢查發現沒有快取影響，並已套用重新載入。

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

1138 1138 

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

1140 1140 

1141#### 使用 `addPlugins` 載入更多外掛資料夾1141#### 使用 `addPlugins` 載入更多外掛資料夾

1142 1142 

1143若要載入啟動時不在 [`plugins`](#options) 選項中的外掛資料夾，請將它們以 `addPlugins` 傳給 `reloadPlugins()`，這是一個 [`SdkPluginConfig`](#sdkpluginconfig) 項目清單，其 `path` 必須是絕對路徑。Claude Code 會在一次處理中載入新資料夾並重新載入工作階段現有的外掛。每個新增外掛的 MCP 伺服器也會連線，除非您在該資料夾的項目上設定了 [`skipMcpDiscovery`](#sdkpluginconfig)。需要 Agent SDK v0.3.301 或更新版本，以及 Claude Code v2.1.301 或更新版本。1143若要載入啟動時不在 [`plugins`](#options) 選項中的外掛資料夾，請將它們以 `addPlugins` 傳給 `reloadPlugins()`，這是一個 [`SdkPluginConfig`](#sdkpluginconfig) 項目清單，其 `path` 為絕對路徑。Claude Code 會在單次處理中載入新資料夾並重新載入工作階段現有的外掛。每個新增外掛的 MCP 伺服器也會連線，除非您在該資料夾的項目上設定 [`skipMcpDiscovery`](#sdkpluginconfig)。需要 Agent SDK v0.3.301 或更新版本，以及 Claude Code v2.1.301 或更新版本。

1144 1144 

1145此範例將一個資料夾新增至正在執行的查詢 `q`，並在呼叫回傳時列印工作階段已載入的每個外掛的安裝路徑：1145此範例將一個資料夾新增到執行中的查詢 `q`，並在呼叫回傳時印出工作階段已載入的每個外掛的安裝路徑：

1146 1146 

1147```typescript theme={null}1147```typescript theme={null}

1148const result = await q.reloadPlugins({1148const result = await q.reloadPlugins({

1152console.log(result.plugins.map((plugin) => plugin.path));1152console.log(result.plugins.map((plugin) => plugin.path));

1153```1153```

1154 1154 

1155如果資料夾已載入，列印出的清單會包含 `/opt/my-app/plugins/reports`，且該外掛的命令和 subagent 會出現在 `result.commands` 和 `result.agents` 中。1155如果資料夾已載入，印出的清單會包含 `/opt/my-app/plugins/reports`，且該外掛的命令和 subagent 會出現在 `result.commands` 和 `result.agents` 中。

1156 1156 

1157新增的資料夾會一直是工作階段的一部分。當您再次呼叫 `reloadPlugins()` 時，Claude Code 會將它與其他外掛一起重新載入，您不需要再次在 `addPlugins` 中傳入它。1157新增的資料夾會持續成為工作階段的一部分。當您再次呼叫 `reloadPlugins()` 時，Claude Code 會將它與其他外掛一起重新載入，您不需要再次在 `addPlugins` 中傳入它。

1158 1158 

1159##### 當 `reloadPlugins()` 未載入 `addPlugins` 資料夾時1159##### 當 `reloadPlugins()` 未載入 `addPlugins` 資料夾時

1160 1160 

1161如果 `reloadPlugins()` 被拒絕，則不會新增任何 `addPlugins` 資料夾，因此重試時請再次在 `addPlugins` 中傳入它們。當拒絕是由下列原因之一造成時，工作階段會保留原本已有的外掛：1161如果 `reloadPlugins()` 被拒絕，則不會新增任何 `addPlugins` 資料夾，因此重試時請再次在 `addPlugins` 中傳入它們。當拒絕是由以下原因之一造成時，工作階段會保留它原本已有的外掛：

1162 1162 

1163* **相對 `path` 或格式錯誤的項目**：錯誤訊息為 `add_plugins must be a list of { type: "local", path } entries with absolute paths`。只要有一個錯誤項目，Claude Code 就會拒絕整個清單，因此請將每個項目都以 `{ type: "local", path }` 搭配絕對 `path` 傳入1163* **相對的 `path` 或格式錯誤的項目**：錯誤訊息為 `add_plugins must be a list of { type: "local", path } entries with absolute paths`。Claude Code 會因為一個錯誤項目而拒絕整個清單，因此請將每個項目都以 `{ type: "local", path }` 傳入，並使用絕對 `path`

1164* **管理員已在您的受管設定中開啟 [`disableSideloadFlags`](https://code.claude.com/docs/zh-TW/settings-reference#disablesideloadflags)**：訊息為 `reload_plugins add_plugins is disabled by managed settings (disableSideloadFlags)`。若要載入該資料夾，請要求該管理員移除此設定1164* **管理員已在您的受管設定中開啟 [`disableSideloadFlags`](https://code.claude.com/docs/zh-TW/settings-reference#disablesideloadflags)**：訊息為 `reload_plugins add_plugins is disabled by managed settings (disableSideloadFlags)`。若要載入該資料夾，請要求該管理員移除此設定

1165* **無法重建[沙箱](https://code.claude.com/docs/zh-TW/sandboxing.md)**：在開啟[沙箱機制](#sandboxsettings)時，Claude Code 會重建沙箱設定，使在沙箱中執行的 shell 命令無法寫入您新增的資料夾。訊息為 `the sandbox could not be rebuilt to keep shell commands out of this folder`。請檢查您的[沙箱設定](#sandboxsettings)是否仍構成有效的設定1165* **無法重建[沙箱](https://code.claude.com/docs/zh-TW/sandboxing.md)**：在[沙箱機制](#sandboxsettings)開啟時，Claude Code 會重建沙箱設定，使沙箱化的 shell 命令無法寫入您新增的資料夾。訊息為 `the sandbox could not be rebuilt to keep shell commands out of this folder`。請檢查您的[沙箱設定](#sandboxsettings)是否仍構成有效的設定

1166 1166 

1167如果您傳入 `holdOnCacheImpact` 且呼叫以 [`held: true`](#sdkcontrolreloadpluginsresponse) 解析，則不會新增 `addPlugins` 資料夾。若仍要新增，請以相同的 `addPlugins` 清單且不帶 `holdOnCacheImpact` 再次呼叫 `reloadPlugins()`。1167如果您傳入 `holdOnCacheImpact` 且呼叫以 [`held: true`](#sdkcontrolreloadpluginsresponse) 解析，則不會新增 `addPlugins` 資料夾。若仍要新增，請使用相同的 `addPlugins` 清單且不帶 `holdOnCacheImpact` 再次呼叫 `reloadPlugins()`。

1168 1168 

1169當呼叫解析結果沒有 `held: true`，而某個資料夾仍未出現在 `result.plugins` 中時，請先檢查下列原因：1169當呼叫未以 `held: true` 解析，但某個資料夾仍未出現在 `result.plugins` 中時，請先檢查以下原因：

1170 1170 

1171* **資料夾不存在或其外掛載入失敗**：`result.error_count` 為 `1` 或更高。即便如此，該資料夾仍是工作階段的一部分。修正資料夾後，再次呼叫 `reloadPlugins()` 以載入它，這次不需在 `addPlugins` 中列出它1171* **資料夾不存在或其外掛載入失敗**：`result.error_count` 為 `1` 或更高。即使如此，該資料夾仍會是工作階段的一部分。修正資料夾後，請再次呼叫 `reloadPlugins()` 以載入它，這次不需要在 `addPlugins` 中列出它

1172* **Claude Code 執行檔早於 v2.1.301**：早於 v2.1.301 的執行檔會忽略 `addPlugins`，只重新載入工作階段原本已有的外掛。請檢查 [init 訊息](#sdksystemmessage)上的 `claude_code_version`，並執行 v2.1.301 或更新版本的執行檔1172* **Claude Code 執行檔早於 v2.1.301**：早於 v2.1.301 的執行檔會忽略 `addPlugins`，只重新載入工作階段原本已有的外掛。請檢查 [init 訊息](#sdksystemmessage)上的 `claude_code_version`，並執行 v2.1.301 或更新版本的執行檔

1173 1173 

1174### `SDKControlReloadSkillsResponse`1174### `SDKControlReloadSkillsResponse`

1181};1181};

1182```1182```

1183 1183 

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

1185 1185 

1186### `SDKControlReloadOutputStylesResponse`1186### `SDKControlReloadOutputStylesResponse`

1187 1187 

1193};1193};

1194```1194```

1195 1195 

1196`available_output_styles` 列出重新載入後可用的內建和自訂輸出風格名稱。1196`available_output_styles` 列出重新載入後可用的內建與自訂輸出風格名稱。

1197 1197 

1198### `SDKControlMcpReadResourceResponse`1198### `SDKControlMcpReadResourceResponse`

1199 1199 

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

1201 1201 

1202```typescript theme={null}1202```typescript theme={null}

1203type SDKControlMcpReadResourceResponse = {1203type SDKControlMcpReadResourceResponse = {

1211};1211};

1212```1212```

1213 1213 

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

1215 1215 

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

1217 1217 

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

1219 1219 

1220### `AgentDefinition`1220### `AgentDefinition`

1221 1221 

1222以程式方式定義之 subagent 的設定。1222以程式方式定義的 subagent 設定。

1223 1223 

1224```typescript theme={null}1224```typescript theme={null}

1225type AgentDefinition = {1225type AgentDefinition = {

1242};1242};

1243```1243```

1244 1244 

1245| 欄位 | 必填 | 說明 |1245| 欄位 | 必要 | 說明 |

1246| :- | :- | :- |1246| :- | :- | :- |

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

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

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

1250| `prompt` | 是 | agent 的系統提示詞 |1250| `prompt` | 是 | agent 的系統提示詞 |

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

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

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

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

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

1256| `autoCompactWindow` | 否 | 當此 agent 以 subagent 身分執行時，將其[自動壓縮視窗](https://code.claude.com/docs/zh-TW/sub-agents.md#subagent-auto-compact-window)降低至 `100000` 到 `1000000` 之間的 token 數。需要 TypeScript Agent SDK v0.3.296 或更新版本 |1256| `autoCompactWindow` | 否 | 當此 agent 作為 subagent 執行時，將其[自動壓縮視窗](https://code.claude.com/docs/zh-TW/sub-agents.md#subagent-auto-compact-window)降低至 `100000` 到 `1000000` 的 token 數。需要 TypeScript Agent SDK v0.3.296 或更新版本 |

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

1258| `omitClaudeMd` | 否 | 將使用者、專案和本機的 CLAUDE.md 檔案排除在此 agent 的初始上下文之外；受管政策檔案仍會載入。適用於從 Agent 工具提示詞取得所需一切內容的 agent。當此 agent 作為主執行緒 agent 執行時會被忽略。需要 TypeScript Agent SDK v0.3.271 或更新版本 |1258| `omitClaudeMd` | 否 | 將使用者、專案和本機 CLAUDE.md 檔案排除在此 agent 的初始上下文之外；受管政策檔案仍會載入。適用於從 Agent 工具提示詞取得所需一切的 agent。當此 agent 作為主執行緒 agent 執行時會被忽略。需要 TypeScript Agent SDK v0.3.271 或更新版本 |

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

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

1261| `permissionMode` | 否 | 此 agent 內工具執行的權限模式。[subagent 繼承規則](https://code.claude.com/docs/zh-TW/agent-sdk/permissions.md#available-modes)決定何時套用。請參閱 [`PermissionMode`](#permissionmode) |1261| `permissionMode` | 否 | 此 agent 內工具執行的權限模式。由 [subagent 繼承規則](https://code.claude.com/docs/zh-TW/agent-sdk/permissions.md#available-modes)決定何時套用。請參閱 [`PermissionMode`](#permissionmode) |

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

1263 1263 

1264### `AgentMcpServerSpec`1264### `AgentMcpServerSpec`

1265 1265 

1266指定 subagent 可用的 MCP 伺服器。可以是伺服器名稱（參照父層 `mcpServers` 設定中某個伺服器的字串），或是將伺服器名稱對應至設定的內嵌伺服器設定記錄。1266指定 subagent 可用的 MCP 伺服器。可以是伺服器名稱（參照父層 `mcpServers` 設定中伺服器的字串），或是將伺服器名稱對應到設定的內嵌伺服器設定記錄。

1267 1267 

1268```typescript theme={null}1268```typescript theme={null}

1269type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;1269type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;

1282| 值 | 說明 | 位置 |1282| 值 | 說明 | 位置 |

1283| :- | :- | :- |1283| :- | :- | :- |

1284| `'user'` | 全域使用者設定 | `~/.claude/settings.json` |1284| `'user'` | 全域使用者設定 | `~/.claude/settings.json` |

1285| `'project'` | 共用專案設定（受版本控制） | `.claude/settings.json` |1285| `'project'` | 共享的專案設定（納入版本控制） | `.claude/settings.json` |

1286| `'local'` | 本機專案設定，Claude Code 將設定儲存至此檔案時會將其加入 gitignore | `.claude/settings.local.json` |1286| `'local'` | 本機專案設定，當 Claude Code 將設定儲存至其中時會加入 gitignore | `.claude/settings.local.json` |

1287 1287 

1288#### 預設行為1288#### 預設行為

1289 1289 

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

1291 1291 

1292#### 為何使用 settingSources1292#### 為何使用 settingSources

1293 1293 

1303});1303});

1304```1304```

1305 1305 

1306**僅載入特定設定來源：**1306**僅載入特定的設定來源：**

1307 1307 

1308```typescript theme={null}1308```typescript theme={null}

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

1317});1317});

1318```1318```

1319 1319 

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

1321 1321 

1322#### 設定優先順序1322#### 設定優先順序

1323 1323 

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

1325 1325 

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

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

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

1329 1329 

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

1331 1331 

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

1333 1333 

1345 1345 

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

1347 1347 

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

1349 1349 

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

1351 1351 

1352```typescript theme={null}1352```typescript theme={null}

1353type CanUseTool = (1353type CanUseTool = (

1370 1370 

1371| 選項 | 型別 | 說明 |1371| 選項 | 型別 | 說明 |

1372| :- | :- | :- |1372| :- | :- | :- |

1373| `signal` | `AbortSignal` | 當操作應中止時會發出訊號 |1373| `signal` | `AbortSignal` | 若操作應中止則會發出訊號 |

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

1375| `blockedPath` | `string` | 觸發權限請求的檔案路徑（如適用） |1375| `blockedPath` | `string` | 觸發權限請求的檔案路徑（如適用） |

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

1377| `decisionReason` | `string` | 說明觸發此權限請求的原因 |1377| `decisionReason` | `string` | 說明為何觸發此權限請求 |

1378| `defaultToNo` | `boolean` | 當為 `true` 時，單一誤觸按鍵不得核准此請求：開啟提示時應停留在拒絕選項上，不要預先選取核准，也不要提供單鍵核准的快捷鍵。需要 Agent SDK v0.3.268 或更新版本 |1378| `defaultToNo` | `boolean` | 當為 `true` 時，單一誤觸的按鍵不得核准此請求：請讓您的提示停在拒絕選項上、不要預先選取核准，也不要提供單鍵核准的快捷鍵。需要 Agent SDK v0.3.268 或更新版本 |

1379| `suppressAlwaysAllowRule` | `boolean` | 當為 `true` 時，不要為此請求提供持久的「一律允許」選項。需要 Agent SDK v0.3.268 或更新版本 |1379| `suppressAlwaysAllowRule` | `boolean` | 當為 `true` 時，不要為此請求提供持續性的「永遠允許」選項。需要 Agent SDK v0.3.268 或更新版本 |

1380| `toolUseID` | `string` | 此特定工具呼叫在助理訊息中的唯一識別碼 |1380| `toolUseID` | `string` | 助理訊息中此特定工具呼叫的唯一識別碼 |

1381| `agentID` | `string` | 若在 sub-agent 中執行，則為該 sub-agent 的 ID |1381| `agentID` | `string` | 若在 sub-agent 中執行，則為該 sub-agent 的 ID |

1382| `requestId` | `string` | `control_request` 封套的 `request_id`。您的應用程式在 SDK 之外傳送的 `control_response`（例如經簽署的 HTTP POST）必須回傳此值，讓 Claude Code 程序能將回覆與請求配對 |1382| `requestId` | `string` | `control_request` 封包的 `request_id`。您的應用程式在 SDK 之外傳送的 `control_response`（例如已簽署的 HTTP POST）必須回傳此值，Claude Code 程序才能將回覆與請求配對 |

1383 1383 

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

1385 1385 

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

1387 1387 

1388### `PermissionResult`1388### `PermissionResult`

1389 1389 

1405 };1405 };

1406```1406```

1407 1407 

1408如果您回傳 `allow` 且 `updatedPermissions` 中有超過 4,096 個項目，Claude Code 會將結果視為無效並拒絕該工具呼叫。每個更新算作一個項目，其 `rules` 或 `directories` 清單中的每個條目也各算一個項目。拒絕訊息的結尾為 `updatedPermissions may hold at most 4096 updates, rules and directories in all`。若要讓呼叫被允許，請回傳 4,096 個或更少的項目。1408如果您回傳 `allow` 且 `updatedPermissions` 中有超過 4,096 個項目，Claude Code 會將結果視為無效並拒絕該工具呼叫。每個更新計為一個項目，其 `rules` 或 `directories` 清單中的每個條目也各計為一個項目。拒絕訊息的結尾為 `updatedPermissions may hold at most 4096 updates, rules and directories in all.` 若要讓呼叫被允許，請回傳 4,096 個或更少的項目。

1409 1409 

1410### `ToolConfig`1410### `ToolConfig`

1411 1411 

1421 1421 

1422| 欄位 | 型別 | 說明 |1422| 欄位 | 型別 | 說明 |

1423| :- | :- | :- |1423| :- | :- | :- |

1424| `askUserQuestion.previewFormat` | `'markdown' \| 'html'` | 啟用 [`AskUserQuestion`](https://code.claude.com/docs/zh-TW/agent-sdk/user-input#question-format) 選項上的 `preview` 欄位，並設定其內容格式。未設定時，Claude 不會產生預覽 |1424| `askUserQuestion.previewFormat` | `'markdown' \| 'html'` | 啟用 [`AskUserQuestion`](https://code.claude.com/docs/zh-TW/agent-sdk/user-input#question-format) 選項上的 `preview` 欄位並設定其內容格式。未設定時，Claude 不會產生預覽 |

1425 1425 

1426### `McpServerConfig`1426### `McpServerConfig`

1427 1427 

1468 1468 

1469#### `McpSdkServerConfigWithInstance`1469#### `McpSdkServerConfigWithInstance`

1470 1470 

1471行程內 MCP 伺服器的設定。它就是 [`createSdkMcpServer()`](#createsdkmcpserver) 所回傳的內容，再加上您可自行新增、由 [`McpServerToolPolicy`](#mcpservertoolpolicy) 項目組成的選用 `tools` 清單。1471程序內 MCP 伺服器的設定。它是 [`createSdkMcpServer()`](#createsdkmcpserver) 的回傳值，再加上您新增的選用 [`McpServerToolPolicy`](#mcpservertoolpolicy) 項目 `tools` 清單。

1472 1472 

1473```typescript theme={null}1473```typescript theme={null}

1474type McpSdkServerConfigWithInstance = {1474type McpSdkServerConfigWithInstance = {

1480};1480};

1481```1481```

1482 1482 

1483若要讓伺服器某個工具的呼叫需要核准或予以拒絕，請新增一個指名該工具的政策項目。將 `createSdkMcpServer()` 回傳的內容展開到 `mcpServers` 下的物件中，並將該項目放入該物件上的 `tools` 清單，因為該函式的 `tools` 選項接受的是工具定義，而非政策項目。政策清單需要 Agent SDK v0.3.301 或更新版本，而 [`McpServerToolPolicy`](#mcpservertoolpolicy) 說明了每個 `permission_policy` 值的作用。1483若要讓伺服器某個工具的呼叫需要核准或拒絕它們，請新增一個指名該工具的政策項目。將 `createSdkMcpServer()` 的回傳值展開到 `mcpServers` 下的一個物件中，並將該項目放在該物件上的 `tools` 清單中，因為該函式的 `tools` 選項接受的是工具定義，而不是政策項目。政策清單需要 Agent SDK v0.3.301 或更新版本，[`McpServerToolPolicy`](#mcpservertoolpolicy) 說明每個 `permission_policy` 值的作用。

1484 1484 

1485在此指令碼中，`allowedTools` 萬用字元預先核准了 `records` 伺服器上的所有工具，但 `delete_record` 被標記為 `always_ask`，因此對它的呼叫仍會送到 `canUseTool`。由於帶有 `destructiveHint: true` 註解，即使工作階段在 `auto` 模式下執行，呼叫仍會到達回呼；否則自動模式的[分類器](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode)可能會核准它。1485在此指令碼中，`allowedTools` 萬用字元預先核准了 `records` 伺服器上的每個工具，但 `delete_record` 被標記為 `always_ask`，因此對它的呼叫仍會送到 `canUseTool`。有了 `destructiveHint: true` 註解，即使工作階段以 `auto` 模式執行，呼叫仍會到達回呼，否則自動模式的[分類器](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode)可能會核准它。

1486 1486 

1487```typescript theme={null}1487```typescript theme={null}

1488import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";1488import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";

1523 1523 

1524當 Claude 呼叫 `delete_record` 時，指令碼會印出 `Approval requested for mcp__records__delete_record`。1524當 Claude 呼叫 `delete_record` 時，指令碼會印出 `Approval requested for mcp__records__delete_record`。

1525 1525 

1526若要在工作階段執行期間變更或解除工具的原則，請將帶有新 `tools` 值的伺服器設定傳給 [`setMcpServers()`](#mcpsetserversresult)。您傳入的 `tools` 值會從 Claude 下一次呼叫該伺服器的工具時生效：1526若要在工作階段執行期間變更或解除工具的政策，請將帶有新 `tools` 值的伺服器設定傳給 [`setMcpServers()`](#mcpsetserversresult)。您傳入的 `tools` 值會從 Claude 下一次呼叫該伺服器的工具時開始生效：

1527 1527 

1528* **含有項目的清單**：這些項目會取代目前的原則1528* **含有項目的清單**：這些項目會取代目前的政策

1529* **空清單**：清除伺服器上的所有原則1529* **空清單**：清除伺服器上的所有政策

1530* **沒有 `tools` 鍵**：保留目前的原則1530* **沒有 `tools` 鍵**：保留目前的政策

1531 1531 

1532請在該呼叫中納入您的其他程序內伺服器，以及先前 `setMcpServers()` 呼叫所新增的任何伺服器，否則該呼叫會中斷它們的連線。1532請在該呼叫中包含您的其他程序內伺服器，以及先前 `setMcpServers()` 呼叫所新增的任何伺服器，否則該呼叫會中斷它們的連線。

1533 1533 

1534#### `McpServerToolPolicy`1534#### `McpServerToolPolicy`

1535 1535 

1536[`McpSdkServerConfigWithInstance`](#mcpsdkserverconfigwithinstance) 的 `tools` 清單中的一個項目，指名伺服器的某個工具，並為對該工具的呼叫設定權限原則。此清單需要 Agent SDK v0.3.301 或更新版本，以及 Claude Code v2.1.301 或更新版本。較舊的 Claude Code 執行檔（例如您以 `pathToClaudeCodeExecutable` 指向的執行檔）會忽略此清單。此時 `always_ask` 和 `always_deny` 不會被強制執行，每個呼叫都會經過[權限流程](https://code.claude.com/docs/zh-TW/agent-sdk/permissions.md#how-permissions-are-evaluated)。1536[`McpSdkServerConfigWithInstance`](#mcpsdkserverconfigwithinstance) 的 `tools` 清單中的一個項目，指名伺服器的某個工具，並為對該工具的呼叫設定權限政策。此清單需要 Agent SDK v0.3.301 或更新版本，以及 Claude Code v2.1.301 或更新版本。較舊的 Claude Code 執行檔（例如您以 `pathToClaudeCodeExecutable` 指定的執行檔）會忽略此清單。此時 `always_ask` 和 `always_deny` 不會被強制執行，每個呼叫都會經過[權限流程](https://code.claude.com/docs/zh-TW/agent-sdk/permissions.md#how-permissions-are-evaluated)。

1537 1537 

1538```typescript theme={null}1538```typescript theme={null}

1539type McpServerToolPolicy = {1539type McpServerToolPolicy = {

1546| 欄位 | 型別 | 說明 |1546| 欄位 | 型別 | 說明 |

1547| :- | :- | :- |1547| :- | :- | :- |

1548| `name` | `string` | 傳給 [`tool()`](#tool) 的工具原始名稱，不含 `mcp__<server>__` 前綴 |1548| `name` | `string` | 傳給 [`tool()`](#tool) 的工具原始名稱，不含 `mcp__<server>__` 前綴 |

1549| `permission_policy` | `'always_allow' \| 'always_ask' \| 'always_deny'` | 此工具呼叫的核准原則，[`always_ask` 或 `always_deny`](#permission-policy-values)。`always_allow` 在程序內伺服器上會被忽略：若要預先核准工具，請改為在 [`allowedTools`](#options) 中列出它 |1549| `permission_policy` | `'always_allow' \| 'always_ask' \| 'always_deny'` | 工具呼叫的核准政策，[`always_ask` 或 `always_deny`](#permission-policy-values)。`always_allow` 在程序內伺服器上會被忽略：若要預先核准工具，請改為在 [`allowedTools`](#options) 中列出它 |

1550| `org_max_permission` | `'allow' \| 'ask' \| 'blocked'` | 由組織管理員設定的每個工具上限。在程序內伺服器上會被忽略，因此請保持未設定 |1550| `org_max_permission` | `'allow' \| 'ask' \| 'blocked'` | 由組織管理員設定的每個工具上限。在程序內伺服器上會被忽略，因此請勿設定 |

1551 1551 

1552##### `permission_policy` 值1552##### `permission_policy` 值

1553 1553 

1554選擇 `always_ask` 以自行核准每個呼叫，或選擇 `always_deny` 以直接封鎖該工具：1554選擇 `always_ask` 以自行核准每個呼叫，或選擇 `always_deny` 以直接封鎖該工具：

1555 1555 

1556* **`always_ask`**：對該工具的每個呼叫都[需要核准](https://code.claude.com/docs/zh-TW/agent-sdk/permissions.md#how-permissions-are-evaluated)，即使有 `allowedTools` 項目或允許規則涵蓋它。除非先行處理，否則呼叫會送到您的 `canUseTool` 回呼或 [`permissionPromptToolName`](#options) 工具。您載入的外掛中的 [mod](https://code.claude.com/docs/zh-TW/plugins/mods/overview.md) [可以先核准它](https://code.claude.com/docs/zh-TW/permissions.md#precedence-among-rules-hooks-and-mods)。否則，在 `dontAsk` 模式下會被拒絕，而在 [`auto`、`plan` 和 `bypassPermissions` 模式](#permission-modes-that-can-approve-an-always_ask-call)下，它可能在抵達您的回呼之前就被核准1556* **`always_ask`**：對該工具的每個呼叫都[需要核准](https://code.claude.com/docs/zh-TW/agent-sdk/permissions.md#how-permissions-are-evaluated)，即使有 `allowedTools` 項目或允許規則涵蓋它。呼叫會送到您的 `canUseTool` 回呼或 [`permissionPromptToolName`](#options) 工具，除非它先被處理。您載入的外掛中的 [mod](https://code.claude.com/docs/zh-TW/plugins/mods/overview.md) [可以先核准它](https://code.claude.com/docs/zh-TW/permissions.md#precedence-among-rules-hooks-and-mods)。否則，在 `dontAsk` 模式下會被拒絕，而在 [`auto`、`plan` 和 `bypassPermissions` 模式](#permission-modes-that-can-approve-an-always_ask-call)下，它可能在到達您的回呼之前就被核准

1557* **`always_deny`**：對該工具的呼叫在每種權限模式下都[會被拒絕](https://code.claude.com/docs/zh-TW/agent-sdk/permissions.md#how-permissions-are-evaluated)，包括 `bypassPermissions`，但您載入的外掛中的 mod [仍可以核准它](https://code.claude.com/docs/zh-TW/permissions.md#precedence-among-rules-hooks-and-mods)1557* **`always_deny`**：對該工具的呼叫在每種權限模式下都[會被拒絕](https://code.claude.com/docs/zh-TW/agent-sdk/permissions.md#how-permissions-are-evaluated)，包括 `bypassPermissions`，但您載入的外掛中的 mod [仍然可以核准它](https://code.claude.com/docs/zh-TW/permissions.md#precedence-among-rules-hooks-and-mods)

1558 1558 

1559如果您既未傳入 `canUseTool` 也未傳入 `permissionPromptToolName`，或將 [`permissionPrompts`](#options) 設為 `'none'`，則未先行處理的 `always_ask` 呼叫會被拒絕，除非有 [`PermissionRequest` hook](https://code.claude.com/docs/zh-TW/hooks#permissionrequest) 允許它。1559如果您既未傳入 `canUseTool` 也未傳入 `permissionPromptToolName`，或將 [`permissionPrompts`](#options) 設為 `'none'`，則未先被處理的 `always_ask` 呼叫會被拒絕，除非有 [`PermissionRequest` hook](https://code.claude.com/docs/zh-TW/hooks#permissionrequest) 允許它。

1560 1560 

1561##### 可以核准 `always_ask` 呼叫的權限模式1561##### 可以核准 `always_ask` 呼叫的權限模式

1562 1562 

1563在 `auto`、`plan` 和 `bypassPermissions` 模式下，對標記為 [`always_ask`](#permission-policy-values) 之工具的呼叫，可能在到達您的 `canUseTool` 回呼之前就被核准。1563在 `auto`、`plan` 和 `bypassPermissions` 模式下，對標記為 [`always_ask`](#permission-policy-values) 的工具的呼叫，可能在到達您的 `canUseTool` 回呼之前就被核准。

1564 1564 

1565* **`auto`**：自動模式[分類器](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode)會審查呼叫並可能允許它。若要讓每個呼叫在 `auto` 模式下都抵達您的回呼，請在工具的[註解](#toolannotations)中設定 `destructiveHint: true`1565* **`auto`**：自動模式[分類器](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode)會審查該呼叫並可能允許它。若要讓 `auto` 模式下的每個呼叫都到達您的回呼，請在工具的[註解](#toolannotations)中設定 `destructiveHint: true`

1566* **`plan`**：當工作階段[可使用自動模式](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode)時，對註解為 `readOnlyHint: true` 的 `always_ask` 工具的呼叫會送到自動模式分類器，分類器可能允許它們。對其他 `always_ask` 工具的呼叫會抵達您的回呼。若要讓唯讀工具的呼叫也抵達您的回呼，請在該工具的註解中，於 `readOnlyHint: true` 旁加入 `destructiveHint: true`。或者，將 [`useAutoModeDuringPlan`](https://code.claude.com/docs/zh-TW/settings-reference#useautomodeduringplan) 設為 `false`，這會在規劃期間關閉分類器1566* **`plan`**：當[自動模式可供](https://code.claude.com/docs/zh-TW/permission-modes.md#eliminate-prompts-with-auto-mode)工作階段使用時，對註解為 `readOnlyHint: true` 的 `always_ask` 工具的呼叫會送到自動模式分類器，分類器可能允許它們。對其他 `always_ask` 工具的呼叫會到達您的回呼。若要讓唯讀工具的呼叫也到達您的回呼，請在該工具的註解中於 `readOnlyHint: true` 之外加上 `destructiveHint: true`。或者，將 [`useAutoModeDuringPlan`](https://code.claude.com/docs/zh-TW/settings-reference#useautomodeduringplan) 設為 `false`，以在規劃期間關閉分類器

1567* **`bypassPermissions`**：當 [`CLAUDE_CODE_REMOTE`](https://code.claude.com/docs/zh-TW/env-vars#variables) 環境變數為 `true` 時（在[雲端工作階段](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md)中即是如此），無論工具的註解為何，呼叫都會在不經過您回呼的情況下被核准。在其他任何地方，呼叫都會抵達您的回呼。若要讓它在雲端工作階段中也抵達您的回呼，請改以 `default` 或 `acceptEdits` 模式執行工作階段1567* **`bypassPermissions`**：當 [`CLAUDE_CODE_REMOTE`](https://code.claude.com/docs/zh-TW/env-vars#variables) 環境變數為 `true` 時（如同在[雲端工作階段](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md)中），無論工具的註解為何，呼叫都會在不經過您的回呼的情況下被核准。在其他任何地方，呼叫都會到達您的回呼。若要讓它在雲端工作階段中也到達您的回呼，請改以 `default` 或 `acceptEdits` 模式執行工作階段

1568 1568 

1569在 `auto` 和 `plan` 模式下，請明確將 `destructiveHint` 設為 `true`。對於 `always_ask` 呼叫，Claude Code 會將未設定的 `destructiveHint` 視為 `false`，儘管 [`ToolAnnotations`](#toolannotations) 下列出的預設值為 `true`。1569在 `auto` 和 `plan` 模式下，請明確將 `destructiveHint` 設為 `true`。對於 `always_ask` 呼叫，Claude Code 會將未設定的 `destructiveHint` 視為 `false`，儘管 [`ToolAnnotations`](#toolannotations) 下列出的預設值為 `true`。

1570 1570 

1594| :- | :- | :- |1594| :- | :- | :- |

1595| `type` | `'local'` | 必須為 `'local'`（目前僅支援本機外掛） |1595| `type` | `'local'` | 必須為 `'local'`（目前僅支援本機外掛） |

1596| `path` | `string` | 外掛目錄的路徑。相對路徑會在工作階段啟動時相對於 [`cwd`](#options) 選項解析。當您在工作階段中途以 [`addPlugins`](#load-more-plugin-folders-with-addplugins) 載入外掛時，路徑必須是絕對路徑 |1596| `path` | `string` | 外掛目錄的路徑。相對路徑會在工作階段啟動時相對於 [`cwd`](#options) 選項解析。當您在工作階段中途以 [`addPlugins`](#load-more-plugin-folders-with-addplugins) 載入外掛時，路徑必須是絕對路徑 |

1597| `skipMcpDiscovery` | `boolean` | 當為 `true` 時，SDK 會從此外掛載入 skill、hook、agent 與命令，但不會讀取其 `.mcp.json` 或 manifest 中的 `mcpServers`。當您的應用程式自行管理外掛的 MCP 連線時，請設定此項。 |1597| `skipMcpDiscovery` | `boolean` | 當為 `true` 時，SDK 會從此外掛載入 skill、hook、agent 和命令，但不會讀取其 `.mcp.json` 或 manifest 的 `mcpServers`。當您的應用程式自行管理外掛的 MCP 連線時，請設定此項。 |

1598 1598 

1599**範例：**1599**範例：**

1600 1600 

1605];1605];

1606```1606```

1607 1607 

1608關於建立與使用外掛的完整資訊，請參閱[外掛](https://code.claude.com/docs/zh-TW/agent-sdk/plugins.md)。1608如需建立和使用外掛的完整資訊，請參閱[外掛](https://code.claude.com/docs/zh-TW/agent-sdk/plugins.md)。

1609 1609 

1610## 訊息類型1610## 訊息類型

1611 1611 

4705 humanSchedule: string;4705 humanSchedule: string;

4706 recurring: boolean;4706 recurring: boolean;

4707 durable?: boolean; // 當持久化到 .claude/scheduled_tasks.json 時為真；當僅限工作階段時為假4707 durable?: boolean; // 當持久化到 .claude/scheduled_tasks.json 時為真；當僅限工作階段時為假

4708 nextFireAt?: number;

4708};4709};

4709```4710```

4710 4711 

4711傳回工作 ID 和排程的人類可讀描述。4712傳回工作 ID、人類可讀的排程以及下次執行時間。`nextFireAt` 以紀元毫秒表示該時間，且已套用[抖動](https://code.claude.com/docs/zh-TW/scheduled-tasks.md#jitter)，因此它就是工作設定執行的時間。此欄位需要 TypeScript Agent SDK v0.3.299 或更新版本以及 Claude Code v2.1.299 或更新版本。

4712 4713 

4713### CronDelete4714### CronDelete

4714 4715 

4735 prompt: string;4736 prompt: string;

4736 recurring?: boolean;4737 recurring?: boolean;

4737 durable?: boolean;4738 durable?: boolean;

4739 nextFireAt?: number;

4738 }[];4740 }[];

4739};4741};

4740```4742```

4741 4743 

4742傳回排程的 cron 工作：來自 `.claude/scheduled_tasks.json` 的持久化工作和來自目前工作階段的僅限工作階段工作。僅限工作階段的工作攜帶 `durable: false`；從磁碟讀取的工作省略欄位。4744傳回排程的 cron 工作：來自 `.claude/scheduled_tasks.json` 的持久化工作和來自目前工作階段的僅限工作階段工作。僅限工作階段的工作攜帶 `durable: false`；從磁碟讀取的工作省略欄位。

4743 4745 

4746`nextFireAt` 是工作的下次執行時間（以紀元毫秒表示），已包含[抖動](https://code.claude.com/docs/zh-TW/scheduled-tasks.md#jitter)。任何值都不會早於 `CronList` 呼叫的時間：時間已[過去但未執行](https://code.claude.com/docs/zh-TW/scheduled-tasks.md#how-scheduled-tasks-run)的工作會攜帶該呼叫的時間。此欄位需要 TypeScript Agent SDK v0.3.299 或更新版本以及 Claude Code v2.1.299 或更新版本。

4747 

4744### ScheduleWakeup4748### ScheduleWakeup

4745 4749 

4746**工具名稱：** `ScheduleWakeup`4750**工具名稱：** `ScheduleWakeup`

5458};5462};

5459```5463```

5460 5464 

5465`setMcpServers()` 的 promise 會在新增的 stdio、HTTP 和 SSE 伺服器連線或失敗後解決，因此來自已連線伺服器的工具在下一回合可用。

5466 

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

5462 5468 

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

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

5468* **與 MCP 安裝範圍（例如 `.mcp.json`）中的伺服器同名的 stdio、HTTP 或 SSE 伺服器**：在該名稱下，工作階段會使用您的伺服器的工具，而非[安裝範圍伺服器](https://code.claude.com/docs/zh-TW/mcp.md#mcp-installation-scopes)的工具。在 Claude Code v2.1.305 之前，當您的應用程式[重新載入外掛](#query-object)時，Claude Code 可能會中斷您的伺服器連線，改為連線至安裝範圍伺服器。5474* **與 MCP 安裝範圍（例如 `.mcp.json`）中的伺服器同名的 stdio、HTTP 或 SSE 伺服器**：在該名稱下，工作階段會使用您的伺服器的工具，而非[安裝範圍伺服器](https://code.claude.com/docs/zh-TW/mcp.md#mcp-installation-scopes)的工具。在 Claude Code v2.1.305 之前，當您的應用程式[重新載入外掛](#query-object)時，Claude Code 可能會中斷您的伺服器連線，改為連線至安裝範圍伺服器。

5469 5475 

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

5471 

5472`added` 列出 Claude Code 新增或替換的伺服器，無論它們是否連線。未能連線的伺服器同時出現在 `added` 和 `errors` 中，失敗文字在 `errors` 下，`failed` 列在 [`mcpServerStatus()`](#methods) 中。在 Claude Code v2.1.257 之前，連線嘗試拋出的伺服器僅在 `errors` 下報告。5476`added` 列出 Claude Code 新增或替換的伺服器，無論它們是否連線。未能連線的伺服器同時出現在 `added` 和 `errors` 中，失敗文字在 `errors` 下，`failed` 列在 [`mcpServerStatus()`](#methods) 中。在 Claude Code v2.1.257 之前，連線嘗試拋出的伺服器僅在 `errors` 下報告。

5473 5477 

5478以 `Blocked by enterprise` 開頭的 `errors` 值表示政策拒絕了該伺服器，而非連線失敗：

5479 

5480* `Blocked by enterprise policy (allowedMcpServers/deniedMcpServers)`：該伺服器不在 `added` 中。有 [`deniedMcpServers`](https://code.claude.com/docs/zh-TW/managed-mcp#policy-based-control-with-allowlists-and-denylists) 項目與其相符，或已設定 `allowedMcpServers` 清單但未包含它。如果該清單位於您透過 [`settingSources`](#options) 載入的設定檔中，請編輯該檔案。如果它位於受管設定中，請要求您的管理員變更它。

5481* `Blocked by enterprise managed policy`：該伺服器在 `added` 中，並在 `mcpServerStatus()` 中有一個 `failed` 列。請詢問管理員是哪項政策封鎖了它。

5482 

5474### `RewindFilesResult`5483### `RewindFilesResult`

5475 5484 

5476`rewindFiles()` 操作的結果。5485`rewindFiles()` 操作的結果。

24 24 

25## 使用 Bedrock 登入25## 使用 Bedrock 登入

26 26 

27如果您有 AWS 認證資訊，並想透過 Amazon Bedrock 開始使用 Claude Code，登入精靈會引導您完成整個過程。您只需在每個帳戶上完成一次 AWS 端的先決條件；精靈會處理 Claude Code 端的設定。27如果您擁有 AWS 憑證，並想透過 Amazon Bedrock 開始使用 Claude Code，登入精靈會引導您完成整個流程。AWS 端的先決條件每個帳戶只需完成一次；Claude Code 端則由精靈處理。

28 28 

29**1. 在您的 AWS 帳戶中啟用 Anthropic 模型**29**1. 在您的 AWS 帳戶中啟用 Anthropic 模型**

30 30 

31在 [Amazon Bedrock 主控台](https://console.aws.amazon.com/bedrock/)中，開啟模型目錄，選擇 Anthropic 模型，並提交使用案例表單。提交後會立即授予存取權限。如需 AWS Organizations 的相關資訊，請參閱[提交使用案例詳細資訊](#1-submit-use-case-details)；如需您的角色所需的權限，請參閱 [IAM 設定](#iam-configuration)。31在 [Amazon Bedrock 主控台](https://console.aws.amazon.com/bedrock/)中，開啟 Model catalog，選取一個 Anthropic 模型，然後提交使用案例表單。提交後會立即授予存取權。關於 AWS Organizations，請參閱[提交使用案例詳細資訊](#1-submit-use-case-details)；關於您的角色所需的權限，請參閱 [IAM 設定](#iam-configuration)。

32 32 

33**2. 啟動 Claude Code 並選擇 Amazon Bedrock**33**2. 啟動 Claude Code 並選擇 Amazon Bedrock**

34 34 

35執行 `claude`。在登入提示時，選擇**第三方平台**，然後選擇 **Amazon Bedrock**。如果您已經登入並看到聊天提示，請執行 `/setup-bedrock` 來開啟精靈。在設定 `CLAUDE_CODE_USE_BEDROCK=1` 之前，Claude Code [會從命令選單中隱藏該命令](https://code.claude.com/docs/zh-TW/commands.md#how-the-command-menu-matches-what-you-type)；請完整輸入該命令。35執行 `claude`。在登入提示中，選取 **3rd-party platform**，然後選取 **Amazon Bedrock**。如果您已經登入並看到的是聊天提示，請執行 `/setup-bedrock` 以開啟精靈。在設定 `CLAUDE_CODE_USE_BEDROCK=1` 之前，Claude Code 會[在命令選單中隱藏此命令](https://code.claude.com/docs/zh-TW/commands.md#how-the-command-menu-matches-what-you-type)；請完整輸入該命令。

36 36 

37**3. 按照精靈提示進行**37**3. 依照精靈提示操作**

38 38 

39選擇您向 AWS 進行身份驗證的方式：從您的 `~/.aws` 目錄偵測到的 AWS 設定檔、Amazon Bedrock API 金鑰、存取金鑰和密鑰，或已在您環境中的認證資訊。精靈會要求您提供區域，驗證您的帳戶可以叫用哪些 Claude 模型，並讓您釘選它們。它會將結果儲存到您的[使用者設定檔](https://code.claude.com/docs/zh-TW/settings.md)的 `env` 區塊中，因此您不需要自行匯出環境變數。39選擇您向 AWS 進行身分驗證的方式：從您的 `~/.aws` 目錄偵測到的 AWS 設定檔、Amazon Bedrock API 金鑰、存取金鑰與密鑰，或環境中既有的憑證。精靈會詢問您的區域，驗證您的帳戶可以呼叫哪些 Claude 模型，並讓您固定這些模型。它會將結果儲存到您的[使用者設定檔](https://code.claude.com/docs/zh-TW/settings.md)的 `env` 區塊中，因此您不需要自行匯出環境變數。

40 40 

41登入後，您可以隨時執行 `/setup-bedrock` 來重新開啟精靈並變更您的認證資訊、區域或模型釘選。模型釘選步驟會從您目前釘選的模型開始。精靈會寫入 `~/.claude/settings.json`，或在設定 [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/zh-TW/env-vars#variables) 時寫入 `$CLAUDE_CONFIG_DIR/settings.json`。41登入後，您可以隨時執行 `/setup-bedrock` 重新開啟精靈，以變更您的憑證、區域或固定的模型。模型固定步驟會從您目前固定的模型開始。精靈會寫入 `~/.claude/settings.json`，或在設定了 [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/zh-TW/env-vars#variables) 時寫入 `$CLAUDE_CONFIG_DIR/settings.json`。

42 42 

43## 手動設定43## 手動設定

44 44 

17 17 

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

19 19 

20如果您的瀏覽器在您登入後顯示登入代碼而不是重新導向回來，請將其貼到終端機的 `Paste code here if prompted` 提示符處。這在瀏覽器無法連接到 Claude Code 的本機回呼伺服器時發生，這在 WSL2、SSH 工作階段和容器中很常見。20如果您的瀏覽器在您登入後顯示登入代碼而不是重新導向回來，請將其貼到終端機的 `Paste code here if prompted` 提示處。

21 21 

22登入完成時，終端機會顯示 `Login successful`，並提示您按 `Enter` 繼續。22登入完成時，終端機會顯示 `Login successful`，並提示您按 `Enter` 繼續。

23 23 

54 54 

55在您開啟新終端機並首次執行 `claude-work` 後，Claude Code 會引導您完成新目錄的登入和設定。由於 Claude Code 將該類登入儲存在設定目錄外，單獨的目錄無法將兩個 Claude Console 登入 [不使用 API 金鑰](#sign-in-without-an-api-key) 分開。55在您開啟新終端機並首次執行 `claude-work` 後，Claude Code 會引導您完成新目錄的登入和設定。由於 Claude Code 將該類登入儲存在設定目錄外，單獨的目錄無法將兩個 Claude Console 登入 [不使用 API 金鑰](#sign-in-without-an-api-key) 分開。

56 56 

57## 設定團隊驗證57## 設定團隊身分驗證

58 58 

59對於團隊和組織，您可以透過以下方式之一配置 Claude Code 存取：59對於團隊和組織，您可以透過以下其中一種方式設定 Claude Code 存取權：

60 60 

61* [Claude for Teams 或 Enterprise](#claude-for-teams-or-enterprise)，建議用於大多數團隊61* [Claude for Teams 或 Enterprise](#claude-for-teams-or-enterprise)，建議大多數團隊使用

62* [Claude Console](#claude-console-authentication)62* [Claude Console](#claude-console-authentication)

63* [Claude apps gateway](https://code.claude.com/docs/zh-TW/claude-apps-gateway)，一個自託管閘道，使用您的 IdP 簽署開發人員，並將推論路由到您配置的雲端提供商63* [Claude apps 閘道](https://code.claude.com/docs/zh-TW/claude-apps-gateway)，一種自行託管的閘道，會透過您的 IdP 讓開發人員登入，並將推論路由至您設定的雲端供應商

64* [Amazon Bedrock](https://code.claude.com/docs/zh-TW/amazon-bedrock.md)64* [Amazon Bedrock](https://code.claude.com/docs/zh-TW/amazon-bedrock.md)

65* [Google Cloud's Agent Platform](https://code.claude.com/docs/zh-TW/google-vertex-ai.md)65* [Google Cloud's Agent Platform](https://code.claude.com/docs/zh-TW/google-vertex-ai.md)

66* [Microsoft Foundry](https://code.claude.com/docs/zh-TW/microsoft-foundry.md)66* [Microsoft Foundry](https://code.claude.com/docs/zh-TW/microsoft-foundry.md)

67 67 

68### Claude for Teams 或 Enterprise68### Claude for Teams 或 Enterprise

69 69 

70[Claude for Teams](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_teams#team-&-enterprise) 和 [Claude for Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_enterprise) 為使用 Claude Code 的組織提供最佳體驗。團隊成員可以存取 Claude Code 和網頁版 Claude，並具有集中式帳單和團隊管理。70[Claude for Teams](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_teams#team-&-enterprise) 和 [Claude for Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_enterprise) 為使用 Claude Code 的組織提供最佳體驗。團隊成員可同時存取 Claude Code 和網頁版 Claude，並享有集中計費與團隊管理。

71 71 

72* **Claude for Teams**：自助服務方案，具有協作功能、管理工具、SSO、帳單管理和 [伺服器受管設定](https://code.claude.com/docs/zh-TW/server-managed-settings.md)，用於組織範圍的 Claude Code 配置。最適合較小的團隊。72* **Claude for Teams**：自助式方案，提供協作功能、管理工具、SSO、計費管理，以及用於全組織 Claude Code 設定的[伺服器受管設定](https://code.claude.com/docs/zh-TW/server-managed-settings.md)。最適合較小的團隊。

73* **Claude for Enterprise**：新增網域擷取、角色型權限和合規性 API。最適合具有安全性和合規性要求的大型組織。73* **Claude for Enterprise**：增加網域擷取、角色型權限和合規 API。最適合有安全性與合規需求的大型組織。

74 74 

75**1. 訂閱**75**1. 訂閱**

76 76 

77訂閱 [Claude for Teams](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_teams_step#team-&-enterprise) 或聯絡銷售部門以取得 [Claude for Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_enterprise_step)。77訂閱 [Claude for Teams](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_teams_step#team-&-enterprise)，或聯絡業務團隊洽詢 [Claude for Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_enterprise_step)。

78 78 

79**2. 邀請團隊成員**79**2. 邀請團隊成員**

80 80 

82 82 

83**3. 安裝並登入**83**3. 安裝並登入**

84 84 

85團隊成員安裝 Claude Code 並使用其 claude.ai 帳戶登入。85團隊成員安裝 Claude Code，並使用其 claude.ai 帳戶登入。

86 86 

87### Claude Console 驗證87### Claude Console 身分驗證

88 88 

89對於偏好基於 API 的帳單的組織，您可以透過 Claude Console 設定存取。89對於偏好以 API 為基礎計費的組織，您可以透過 Claude Console 設定存取權。

90 90 

91**1. 建立或使用 Console 帳戶**91**1. 建立或使用 Console 帳戶**

92 92 

96 96 

97您可以透過以下任一方法新增使用者：97您可以透過以下任一方法新增使用者：

98 98 

99* 從 Console 的 Members 頁面 [platform.claude.com/settings/members](https://platform.claude.com/settings/members) 大量邀請使用者：點選 **Invite**99* 從 Console 的 Members 頁面 [platform.claude.com/settings/members](https://platform.claude.com/settings/members) 大量邀請使用者：點擊 **Invite**

100* [設定 SSO](https://support.claude.com/en/articles/13132885-setting-up-single-sign-on-sso)100* [設定 SSO](https://support.claude.com/en/articles/13132885-setting-up-single-sign-on-sso)

101 101 

102**3. 指派角色**102**3. 指派角色**

103 103 

104邀請使用者時，指派以下其中一個角色：104邀請使用者時，指派以下其中一種角色：

105 105 

106* **Claude Code** 角色：使用者只能建立 Claude Code API 金鑰106* **Claude Code** 角色：使用者只能建立 Claude Code API 金鑰

107* **Developer** 角色：使用者可以建立任何類型的 API 金鑰107* **Developer** 角色：使用者可以建立任何類型的 API 金鑰

108 108 

109**4. 使用者完成設定**109**4. 使用者完成設定**

110 110 

111每個受邀使用者需要：111每位受邀使用者需要：

112 112 

113* 接受 Console 邀請113* 接受 Console 邀請

114* [檢查系統要求](https://code.claude.com/docs/zh-TW/setup.md#system-requirements)114* [檢查系統需求](https://code.claude.com/docs/zh-TW/setup.md#system-requirements)

115* [安裝 Claude Code](https://code.claude.com/docs/zh-TW/setup.md#install-claude-code)115* [安裝 Claude Code](https://code.claude.com/docs/zh-TW/setup.md#install-claude-code)

116* 使用 Console 帳戶憑證登入116* 使用 Console 帳戶憑證登入

117 117 

118#### 不使用 API 金鑰登入118#### 不使用 API 金鑰登入

119 119 

120您可以不建立 API 金鑰而登入 Console 帳戶，即使您的組織不允許開發人員建立 API 金鑰。在 `/login` 提示時選擇 Anthropic Console 帳戶，Claude Code 會詢問您想如何登入。需要 Claude Code v2.1.242 或更新版本。兩種路由都會在瀏覽器中將您登入 Console，但在 Claude Code 之後儲存的內容不同：120您可以在不建立 API 金鑰的情況下登入 Console 帳戶，即使您的組織不允許開發人員建立 API 金鑰也可以。在 `/login` 提示中選擇 Anthropic Console 帳戶，Claude Code 便會詢問您要如何登入。需要 Claude Code v2.1.242 或更新版本。兩種方式都會在瀏覽器中讓您登入 Console，差別在於 Claude Code 之後儲存的內容：

121 121 

122* **使用您的 Console 帳戶登入**，標記為 `(recommended)`：Claude Code 保留該登入的 OAuth 權杖，並將其儲存為 [Anthropic 設定檔](#anthropic-profiles-and-federation-credentials)。它不建立 API 金鑰122* **使用您的 Console 帳戶登入**，標示為 `(recommended)`：Claude Code 會保留該次登入取得的 OAuth token，並將其儲存為 [Anthropic 設定檔](#anthropic-profiles-and-federation-credentials)。不會建立任何 API 金鑰

123* **建立 API 金鑰**，標記為 `(legacy)`：Claude Code 為您建立 Console API 金鑰，並將其與您的其他認證一起儲存123* **建立 API 金鑰**，標示為 `(legacy)`：Claude Code 會為您建立 Console API 金鑰，並將其與您的其他憑證一起儲存

124 124 

125實際上，設定檔儲存 OAuth 登入，而 API 金鑰是靜態憑證。Claude Code 會自動重新整理設定檔的登入，當重新整理失敗時，請求會失敗並顯示 [設定檔登入過期錯誤](https://code.claude.com/docs/zh-TW/errors.md#anthropic-profile-login-expired)，直到您再次登入。125實際上，設定檔儲存的是 OAuth 登入，而 API 金鑰則是靜態憑證。Claude Code 會自動重新整理設定檔的登入，當重新整理失敗時，請求會因[設定檔登入已過期錯誤](https://code.claude.com/docs/zh-TW/errors.md#anthropic-profile-login-expired)而失敗，直到您重新登入為止。

126 126 

127您不會在每台機器上都獲得選擇。Claude Code 在以下情況下會在不詢問的情況下建立 API 金鑰：127並非每台機器都會提供這個選擇。在以下情況中，Claude Code 會直接建立 API 金鑰而不詢問：

128 128 

129* 您針對雲端提供商執行，例如 [Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry](https://code.claude.com/docs/zh-TW/third-party-integrations.md) 或 [Claude Platform on AWS](https://code.claude.com/docs/zh-TW/claude-platform-on-aws.md)129* 您透過雲端供應商執行，例如 [Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry](https://code.claude.com/docs/zh-TW/third-party-integrations.md)，或 [Claude Platform on AWS](https://code.claude.com/docs/zh-TW/claude-platform-on-aws.md)

130* 任何設定檔設定 [`forceLoginOrgUUID`](#restrict-login-to-your-organization)，或將 `forceLoginMethod` 設定為 `"claudeai"` 或 `"console"`130* 任何設定檔設定了 [`forceLoginOrgUUID`](#restrict-login-to-your-organization)，或將 `forceLoginMethod` 設為 `"claudeai"`

131* 您機器上存在受管設定來源（例如受管設定檔、MDM 設定檔或快取的伺服器受管設定），但 Claude Code [無法讀取它](https://code.claude.com/docs/zh-TW/managed-settings.md#invalid-entries-in-managed-settings)，且沒有其他受管來源提供原則131* `forceLoginMethod` 為 `"console"` 且沒有任何設定檔設定 `forceLoginOrgUUID`，直到您在登入失敗後從錯誤畫面重試為止

132* 您機器上的某個受管設定來源（例如受管設定檔、MDM 設定檔或快取的伺服器受管設定）存在，但 Claude Code [無法讀取](https://code.claude.com/docs/zh-TW/managed-settings.md#invalid-entries-in-managed-settings)，且沒有其他受管來源提供政策

132 133 

133在不使用金鑰登入之前，請取消設定 `ANTHROPIC_API_KEY`。134在不使用金鑰登入之前，請先取消設定 `ANTHROPIC_API_KEY`。

134 135 

135在不使用金鑰登入後，您有一個設定檔而不是儲存的 API 金鑰：136在不使用金鑰登入後，您擁有的是設定檔，而非已儲存的 API 金鑰：

136 137 

137* **它寫入的設定檔**：Claude Code 寫入由 `ANTHROPIC_PROFILE` 命名的設定檔、您的作用中設定檔或 `default`。如果該設定檔是聯盟設定檔，Claude Code 會拒絕登入而不是覆寫它138* **寫入哪個設定檔**：Claude Code 會寫入 `ANTHROPIC_PROFILE` 所指定的設定檔，或您目前使用中的設定檔，或 `default`。如果該設定檔是聯合設定檔，Claude Code 會拒絕此次登入，而不會覆寫它

138* **它簽出的內容**：Claude Code 簽出儲存在機器上的任何 claude.ai 登入139* **會將您登出哪些登入**：Claude Code 會將您登出此機器上儲存的任何 claude.ai 登入

139* **如何復原它**：執行 `/logout`，它會移除並撤銷此登入寫入的認證140* **如何復原**：執行 `/logout`，這會移除並撤銷此次登入所寫入的憑證

140 141 

141有關設定檔的所有其他內容都適用於此登入，包括它在您其他認證中的排名、您在 `/status` 中獲得的 `Profile` 列，以及需要 claude.ai 登入的功能。請參閱 [Anthropic 設定檔和聯盟認證](#anthropic-profiles-and-federation-credentials)。142設定檔的其他所有行為都適用於此登入方式，包括它與您其他憑證之間的優先順序、您在 `/status` 中看到的 `Profile` 列，以及需要 claude.ai 登入的功能。請參閱 [Anthropic 設定檔與聯合憑證](#anthropic-profiles-and-federation-credentials)。

142 143 

143### 雲端提供商驗證144#### 在受管機器上停止提供免金鑰登入

145 

146若要讓 Claude Code 停止提供[免金鑰登入](#sign-in-without-an-api-key)，請使用您的裝置管理工具，將[受管設定](https://code.claude.com/docs/zh-TW/managed-settings.md)中的 [`forceLoginOrgUUID`](https://code.claude.com/docs/zh-TW/settings-reference#forceloginorguuid) 部署到每位開發人員的機器。將其設為您的 [Console 組織 ID](https://platform.claude.com/settings/organization)。部署之前，請確認每位開發人員都擁有[可以建立 API 金鑰的角色](#claude-console-authentication)。部署之後，沒有該角色的開發人員將無法在 `/login` 登入 Console。

147 

148若只將 `forceLoginMethod` 設為 `"console"`，開發人員可以重試失敗的登入並選擇免金鑰選項。部署 `forceLoginOrgUUID` 後，登入畫面會移除該選項，但開發人員仍可使用他們已有的或透過 [`ant auth login`](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/authentication) 建立的 [Anthropic 設定檔](#anthropic-profiles-and-federation-credentials)。部署之後，請在每台機器上處理以下憑證與登入：

149 

150* **免金鑰登入**：若要讓開發人員改用 API 金鑰，請讓他們登出後再次登入 Console，這會建立金鑰。若是免金鑰登入，他們需在 shell 中執行 `claude auth logout`。若是 `ant auth login` 設定檔，他們需執行 `ant auth logout`。如果機器上同時存在設定檔與 API 金鑰，Claude Code 會拒絕工作階段，因此他們必須先登出。

151* **環境與輔助程式憑證**：Claude Code 會拒絕使用 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 進行身分驗證的工作階段，即使這些憑證是由受管設定提供的也一樣。請移除這些憑證，然後讓開發人員執行 `/login` 以建立已儲存的 API 金鑰。

152* **claude.ai 登入**：Claude Code 會[拒絕登入](#restrict-login-to-your-organization)您未列出的組織，包括機器上已在使用中的組織。若要保留某個組織，請將其加入 `forceLoginOrgUUID` 陣列。

153 

154### 雲端供應商身分驗證

144 155 

145對於使用 Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry 的團隊：156對於使用 Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry 的團隊：

146 157 

147**1. 遵循提供商設定**158**1. 依照供應商設定**

148 159 

149遵循 [Amazon Bedrock 文件](https://code.claude.com/docs/zh-TW/amazon-bedrock.md)、[Google Cloud's Agent Platform 文件](https://code.claude.com/docs/zh-TW/google-vertex-ai.md) 或 [Microsoft Foundry 文件](https://code.claude.com/docs/zh-TW/microsoft-foundry.md)。160請依照 [Amazon Bedrock 文件](https://code.claude.com/docs/zh-TW/amazon-bedrock.md)、[Google Cloud's Agent Platform 文件](https://code.claude.com/docs/zh-TW/google-vertex-ai.md)或 [Microsoft Foundry 文件](https://code.claude.com/docs/zh-TW/microsoft-foundry.md)進行設定。

150 161 

151**2. 分發配置**162**2. 發佈設定**

152 163 

153將環境變數和產生雲端認證的說明分發給您的使用者。深入瞭解如何 [在此管理配置](https://code.claude.com/docs/zh-TW/settings.md)。164將環境變數以及產生雲端憑證的說明發佈給您的使用者。進一步了解如何[在此管理設定](https://code.claude.com/docs/zh-TW/settings.md)。

154 165 

155**3. 安裝 Claude Code**166**3. 安裝 Claude Code**

156 167 

157使用者可以 [安裝 Claude Code](https://code.claude.com/docs/zh-TW/setup.md#install-claude-code)。168使用者可以[安裝 Claude Code](https://code.claude.com/docs/zh-TW/setup.md#install-claude-code)。

158 169 

159### 限制登入到您的組織170### 將登入限制於您的組織

160 171 

161若要要求開發人員的 claude.ai 登入屬於特定的 Anthropic 組織，請在 [受管設定](https://code.claude.com/docs/zh-TW/managed-settings.md) 中設定 [`forceLoginMethod`](https://code.claude.com/docs/zh-TW/settings-reference#forceloginmethod) 和 [`forceLoginOrgUUID`](https://code.claude.com/docs/zh-TW/settings-reference#forceloginorguuid)。將 `forceLoginOrgUUID` 設定為您的組織 ID，該 ID 顯示在 [claude.ai 管理設定](https://claude.ai/admin-settings/organization) 中，適用於 Claude for Teams 或 Enterprise 組織。Claude Code 會針對任何其他組織的 claude.ai 登入報告錯誤，如果使用中的 claude.ai 認證屬於未列出的組織，則在啟動時退出。172若要要求開發人員的 claude.ai 登入屬於特定的 Anthropic 組織，請在[受管設定](https://code.claude.com/docs/zh-TW/managed-settings.md)中設定 [`forceLoginMethod`](https://code.claude.com/docs/zh-TW/settings-reference#forceloginmethod) 和 [`forceLoginOrgUUID`](https://code.claude.com/docs/zh-TW/settings-reference#forceloginorguuid)。將 `forceLoginOrgUUID` 設為您的組織 ID，對於 Claude for Teams 或 Enterprise 組織，該 ID 顯示於 [claude.ai 管理設定](https://claude.ai/admin-settings/organization)中。對於登入任何其他組織的 claude.ai 登入，Claude Code 會回報錯誤；如果使用中的 claude.ai 憑證屬於未列出的組織，Claude Code 會在啟動時結束。

162 173 

163對於 Claude Console 登入，Claude Code 使用 `forceLoginOrgUUID` 在您將其設定為單一 Console 組織 ID 時在 Console 登入頁面上預先選擇組織，該 ID 顯示在 [platform.claude.com/settings/organization](https://platform.claude.com/settings/organization)。它不檢查產生的 Console 認證屬於哪個組織，無論是在登入時還是在啟動時。使用 Console 帳戶登入的開發人員在您部署金鑰之前會保持登入狀態，該儲存的金鑰在同時需要 [閘道](https://code.claude.com/docs/zh-TW/claude-apps-gateway) 登入的機器上或在選擇雲端提供商的工作階段中會被阻止。174對於 Claude Console 登入，當您將 `forceLoginOrgUUID` 設為單一 Console 組織 ID（顯示於 [platform.claude.com/settings/organization](https://platform.claude.com/settings/organization)）時，Claude Code 會使用它在 Console 登入頁面上預先選取該組織。無論在登入時或啟動時，它都不會檢查所產生的 Console 憑證屬於哪個組織。在您部署這些設定鍵之前就已使用 Console 帳戶登入的開發人員會保持登入狀態，而該已儲存的金鑰在同時要求[閘道](https://code.claude.com/docs/zh-TW/claude-apps-gateway)登入的機器上，或在選擇雲端供應商的工作階段中，會遭到封鎖。

164 175 

165如果您在任何設定檔中設定 `forceLoginOrgUUID`，Claude Code 會停止在該檔案適用的工作階段中提供 [無金鑰 Console 登入](#sign-in-without-an-api-key)，並改為建立 API 金鑰。若要將開發人員導向 claude.ai 登入，請將 `forceLoginMethod` 設定為 `"claudeai"`。176如果您在任何設定檔中設定了 `forceLoginOrgUUID`，Claude Code 會在該檔案適用的工作階段中停止提供[免金鑰 Console 登入](#sign-in-without-an-api-key)，改為建立 API 金鑰。若要引導開發人員改用 claude.ai 登入，請將 `forceLoginMethod` 設為 `"claudeai"`。

166 177 

167在 Claude Code v2.1.212 或更新版本上，此處列出的每個登入路徑都套用 `forceLoginMethod`。在終端機的互動式登入畫面上，透過 `/login` 或首次執行上線到達，Claude Code 預先選擇 `claudeai` 或 `console` 方法而不強制執行，因此即使 `forceLoginMethod` 設定為 `"claudeai"`，開發人員仍然可以在那裡完成 Console 登入。178在 Claude Code v2.1.212 或更新版本中，此處列出的每條登入路徑都會套用 `forceLoginMethod`。在終端機的互動式登入畫面（透過 `/login` 或首次執行的引導流程進入）上，Claude Code 會預先選取 `claudeai` 或 `console` 方式但不會強制執行，因此即使將 `forceLoginMethod` 設為 `"claudeai"`，開發人員仍可在該處完成 Console 登入。

168 179 

169路徑在 `forceLoginOrgUUID` 上有所不同：180各路徑在 `forceLoginOrgUUID` 上的處理方式不同：

170 181 

171* **終端機、[VS Code 擴充功能](https://code.claude.com/docs/zh-TW/vs-code.md) 和 Agent SDK 登入**：驗證 claude.ai 帳戶登入的 `forceLoginOrgUUID`182* **終端機、[VS Code 擴充功能](https://code.claude.com/docs/zh-TW/vs-code.md)和 Agent SDK 登入**：會針對 claude.ai 帳戶登入驗證 `forceLoginOrgUUID`

172* **`claude setup-token` 和 `/install-github-app`**：僅強制執行 `forceLoginMethod`，因此它們可以在不同的組織中鑄造權杖183* **`claude setup-token` 和 `/install-github-app`**：只強制執行 `forceLoginMethod`，因此可以在不同的組織中產生 token

173* **[閘道](https://code.claude.com/docs/zh-TW/claude-apps-gateway) 登入**：由 `forceLoginMethod: "gateway"` 選擇而不是受其限制，並且不針對 Anthropic 組織進行驗證，因此 `forceLoginOrgUUID` 不適用；使用您的閘道身分提供者來限制存取184* **[閘道](https://code.claude.com/docs/zh-TW/claude-apps-gateway)登入**：由 `forceLoginMethod: "gateway"` 選取而非受其限制，且不會針對 Anthropic 組織進行身分驗證，因此 `forceLoginOrgUUID` 不適用；請使用您的閘道身分識別提供者來限制存取

174 185 

175透過您的裝置管理工具部署金鑰。[伺服器受管設定](https://code.claude.com/docs/zh-TW/server-managed-settings.md) 只能到達已驗證到您的組織的帳戶，因此它們無法重新導向開發人員的首次登入。如果您的組織也分發伺服器受管設定，請在兩個位置設定金鑰：受管設定來源 [不會合併](https://code.claude.com/docs/zh-TW/server-managed-settings.md#settings-precedence)，快取的伺服器受管設定會取代裝置受管檔案，除了幾個 [各受管來源的個別金鑰例外](https://code.claude.com/docs/zh-TW/server-managed-settings.md#per-key-exceptions-across-managed-sources)。`forceLoginOrgUUID` 和 `forceLoginMethod` 的 `"claudeai"` 和 `"console"` 值不在這些例外中，因此請將它們保留在兩個位置。186請透過您的裝置管理工具部署 `forceLoginMethod` 和 `forceLoginOrgUUID`。開發人員只有在向您的組織完成身分驗證後才會收到[伺服器受管設定](https://code.claude.com/docs/zh-TW/server-managed-settings.md)，因此您無法使用這些設定來重新導向首次登入。如果您也從 claude.ai 發佈伺服器受管設定，請在所有用戶端都執行 v2.1.299 或更新版本之前，也在該處設定這兩個設定鍵。關於之後應在何處設定這些設定鍵，以及套用哪個來源的值，請參閱[哪個受管來源提供登入設定鍵](https://code.claude.com/docs/zh-TW/managed-settings.md#which-managed-source-supplies-login-keys)。

176 187 

177在 [閘道](https://code.claude.com/docs/zh-TW/claude-apps-gateway) 部署中，也請將 `forceLoginMethod` 和 `forceLoginOrgUUID` 保留在 [閘道提供的設定](https://code.claude.com/docs/zh-TW/claude-apps-gateway-config.md#managed) 之外。188在[閘道](https://code.claude.com/docs/zh-TW/claude-apps-gateway)部署中，也請勿將 `forceLoginMethod` 和 `forceLoginOrgUUID` 放入[閘道提供的設定](https://code.claude.com/docs/zh-TW/claude-apps-gateway-config.md#managed)中。

178 189 

179金鑰也決定不使用登入認證的工作階段是否可以啟動。請參閱設定參考中的 [`forceLoginOrgUUID`](https://code.claude.com/docs/zh-TW/settings-reference#forceloginorguuid) 以了解完整行為。190這些設定鍵也會決定不使用登入憑證的工作階段能否啟動。完整行為請參閱設定參考中的 [`forceLoginOrgUUID`](https://code.claude.com/docs/zh-TW/settings-reference#forceloginorguuid)。

180 191 

181* **`ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper`**：在啟動時被阻止。在 `forceLoginOrgUUID` 下，無法驗證環境認證的組織成員資格，在 `forceLoginMethod` 下，認證會代替所需的登入。當受管設定也需要 [閘道](https://code.claude.com/docs/zh-TW/claude-apps-gateway) 登入時，Claude Code 會以相同方式阻止由較早的 Claude Console 登入儲存的 API 金鑰。請參閱 [管理員原則需要雲端閘道登入](https://code.claude.com/docs/zh-TW/errors.md#administrator-policy-requires-a-cloud-gateway-sign-in)192* **`ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper`**：在啟動時遭到封鎖。在 `forceLoginOrgUUID` 之下，無法驗證環境憑證的組織成員資格；而在 `forceLoginMethod` 之下，該憑證會取代必要的登入。當受管設定也要求[閘道](https://code.claude.com/docs/zh-TW/claude-apps-gateway)登入時，Claude Code 會以相同方式封鎖先前 Claude Console 登入所儲存的 API 金鑰。請參閱 [Administrator policy requires a Cloud gateway sign-in](https://code.claude.com/docs/zh-TW/errors.md#administrator-policy-requires-a-cloud-gateway-sign-in)

182* **雲端提供商工作階段，例如 Amazon Bedrock**：僅在 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 認證，或由較早的 Claude Console 登入儲存的 API 金鑰仍然存在於機器上時被阻止。移除它，工作階段就會啟動。這些工作階段針對您的雲端提供商進行驗證，其存取原則管理它們193* **雲端供應商工作階段，例如 Amazon Bedrock**：只有在機器上仍存在 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 憑證，或先前 Claude Console 登入所儲存的 API 金鑰時，才會遭到封鎖。移除後，工作階段即可啟動。這些工作階段會向您的雲端供應商進行身分驗證，並受其存取政策管轄

183* **[Anthropic 設定檔或聯盟認證](#anthropic-profiles-and-federation-credentials)**：除非 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 認證，或由較早的 Claude Console 登入儲存的 API 金鑰也存在於機器上，否則不會被阻止。金鑰不檢查設定檔屬於哪個組織194* **[Anthropic 設定檔或聯合憑證](#anthropic-profiles-and-federation-credentials)**：不會遭到封鎖，除非機器上同時存在 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 憑證，或先前 Claude Console 登入所儲存的 API 金鑰。這些設定鍵不會檢查設定檔屬於哪個組織

184 195 

185### 限制機器可能使用的 API 提供商196### 限制機器可使用的 API 供應商

186 197 

187[受管設定](https://code.claude.com/docs/zh-TW/managed-settings.md) 中的 [`allowedProviders`](https://code.claude.com/docs/zh-TW/settings-reference#allowedproviders) 列出受管機器可能透過哪些服務到達 Claude，例如 Anthropic API、Amazon Bedrock 或 LLM 閘道。它補充 `forceLoginMethod` 和 `forceLoginOrgUUID`，這些控制工作階段在與 Anthropic 通話時使用的帳戶。需要 Claude Code v2.1.285 或更新版本。198[受管設定](https://code.claude.com/docs/zh-TW/managed-settings.md)中的 [`allowedProviders`](https://code.claude.com/docs/zh-TW/settings-reference#allowedproviders) 會列出受管機器可透過哪些服務存取 Claude，例如 Anthropic API、Amazon Bedrock 或 LLM 閘道。它與 `forceLoginMethod` 和 `forceLoginOrgUUID` 互補，後兩者管轄工作階段與 Anthropic 通訊時使用哪個帳戶。需要 Claude Code v2.1.285 或更新版本。

188 199 

189```json managed-settings.json theme={null}200```json managed-settings.json theme={null}

190{201{

194}205}

195```206```

196 207 

197使用此檔案，簽入到您的 claude.ai 組織或為 Amazon Bedrock 配置的開發人員會正常啟動。為任何其他提供商設定的工作階段在啟動時被拒絕，執行中的工作階段切換到一個時在其下一個請求時被拒絕。[受管設定不允許此 API 提供商](https://code.claude.com/docs/zh-TW/errors.md#managed-settings-dont-allow-this-api-provider) 顯示每條訊息。208使用此檔案時，已登入您 claude.ai 組織或已設定為使用 Amazon Bedrock 的開發人員可正常啟動。設定為任何其他供應商的工作階段會在啟動時遭到拒絕，而切換至其他供應商的執行中工作階段會在下一個請求時遭到拒絕。[Managed settings don't allow this API provider](https://code.claude.com/docs/zh-TW/errors.md#managed-settings-dont-allow-this-api-provider) 列出了每則訊息。

198 209 

199* **允許 LLM 閘道或代理**：列出 `"customEndpoint"` 並在同一來源的受管 `env` 區塊中設定閘道的 URL。[設定參考](https://code.claude.com/docs/zh-TW/settings-reference.md#allowedproviders) 列出每個值並說明哪些端點變數需要受管 `env` 釘選。210* **允許 LLM 閘道或代理伺服器**：列出 `"customEndpoint"`，並在同一來源的受管 `env` 區塊中設定閘道的 URL。[設定參考](https://code.claude.com/docs/zh-TW/settings-reference.md#allowedproviders)列出了每個值，並說明哪些端點變數需要在受管 `env` 中固定。

200* **在受管機器上部署**：將清單放在承載您其餘原則的受管來源中。該項目的 [範圍注記](https://code.claude.com/docs/zh-TW/settings-reference.md#allowedproviders) 說明伺服器受管清單如何與其結合。211* **在受管機器上部署**：將清單放在承載您其餘政策的受管來源中。該項目的[範圍說明](https://code.claude.com/docs/zh-TW/settings-reference.md#allowedproviders)說明了伺服器受管清單如何與其合併。